This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

OpenSpec

1 - Specifications

1.1 - Project al

1.1.1 - Al Specification

Describe AL, the repository command runner that prepares plugin resources and environment variables, executes a command, and releases those resources.

Sources: project README, lifecycle contract, command implementation, lifecycle manager, Bazel package, and toolchain registration. Baseline source revision: 550d7e79b1f5fdbc2b6017b75178471d6914082f, observed 2026-09-08.

al run SHALL load its supplied configurations, start the plugins selected by --plugin_label, and append their environment values to the child command’s environment before starting that command. It SHALL reject invocation without a command argument.

  • WHEN configuration loading and selected-plugin startup succeed
  • THEN the requested command receives its arguments, inherited environment, Bazel runfiles environment, and prepared plugin environment.

The lifecycle manager SHALL cancel sibling starts after a startup failure and attempt cleanup for every attempted resource, including the resource that failed to start. It SHALL return startup and cleanup failures to its caller.

  • WHEN one selected plugin cannot start
  • THEN AL does not execute the requested command and releases resources allocated during the unsuccessful startup.

AL SHALL wait for its command to exit before stopping plugin resources. On cancellation it SHALL request direct-child termination, allow up to ten seconds for shutdown, and kill and reap the child if the grace period expires.

  • WHEN the invocation context is cancelled while the command is running
  • THEN the command can use its prepared plugin resources during graceful shutdown, and plugin cleanup follows command termination.

Dependency-ordered lifecycle resources SHALL stop in reverse registration order. AL SHALL include cleanup errors in its invocation result even when the requested command itself succeeded.

  • WHEN the command exits successfully but a plugin shutdown returns an error
  • THEN al run reports failure rather than treating cleanup as successful.

1.2 - Project bazel agent

1.2.1 - Bazel Agent Specification

Describe the validated AL Bazel entry point and installation diagnostics used by repository agents.

Sources: project README, Bazel targets, command and diagnostic implementation, and runner tests. Baseline source revision: 550d7e79b1f5fdbc2b6017b75178471d6914082f, observed 2026-09-08.

al bazel SHALL require a recognized Bazel command and insert --config=agent immediately after that command. Subsequent options, targets, and arguments after a run separator SHALL pass through unchanged.

  • WHEN the caller invokes al bazel run //path:target -- argument
  • THEN the runner constructs bazel run --config=agent //path:target -- argument.

The Bazel entry point SHALL resolve bazel from PATH and replace the runner process with it, preserving the supplied environment without creating or injecting a host temporary directory.

  • WHEN a validated invocation starts Bazel
  • THEN Bazel owns the runner process and its resulting exit status directly.

doctor SHALL emit a read-only JSON report containing runner and available built-source identities, Bazelisk pins, platform, configured profile and rc paths, and task-scratch classification without dumping environment values. Unavailable built-source identity SHALL remain explicit.

  • WHEN doctor cannot find the expected Bazel output for the runner
  • THEN the source report records that it is unavailable rather than claiming that the installed runner matches current source.

1.3 - Project dns

1.3.1 - project-dns Specification

Record the retirement of this project’s landing DNS infrastructure while preserving its repository documentation and builds.

The project SHALL have no dedicated landing DNS declaration, Terraform root, or operational source export. Its documentation SHALL be published by the main site under /docs/projects/al/ without a separate project landing page.

  • WHEN the project tree is consumed
  • THEN it contains no landing DNS declaration, Terraform DNS stage, or landing build target, and the main site owns its documentation.

1.4 - Review delivery

1.4.1 - review-delivery Specification

Make validated pull-request review delivery reliable and concise while preserving exact-candidate and mutation consistency checks.

The CLI SHALL offer a single review-address operation using a published validation receipt, a thread ID, and a reasoned reply file. It SHALL derive current expectations, post at most one reply per durable reply receipt, and resolve only the verified resulting thread. A retry SHALL resume an existing valid reply receipt rather than posting another reply.

  • WHEN the published validated head and unresolved thread match the supplied candidate receipt
  • THEN the operation posts the reasoned reply, verifies it, resolves the unchanged thread, and returns the resulting inventory
  • WHEN the published head differs or the target thread changes during processing
  • THEN the operation refuses mutation or stops further mutation with diagnostic state

The CLI SHALL preserve the original unexpired reply receipt when a transient provider read or advancing review epoch prevents observing a coherent inventory before any resolution mutation. It SHALL retain single-use consumption on attempted mutations, semantic mismatches, and expiry, without extending authority.

  • WHEN read-only inventory collection observes an advancing GitHub epoch before resolution
  • THEN the operation reports that resolution was not attempted and leaves the original unexpired receipt available for a guarded retry
  • WHEN a resolution mutation was attempted but its result cannot be verified
  • THEN the receipt remains consumed and the tool requires fresh inspection

Review inspection SHALL include every returned thread and comment while fetching the first comment page with the thread page. It SHALL fetch additional comment pages when necessary and retain request, byte, and node limits, identity checks, and duplicate detection.

  • WHEN every returned thread has one page of comments
  • THEN inspection obtains their comments without one separate details request per thread
  • WHEN a thread has more comments than its embedded page
  • THEN inspection follows its cursor and returns all comments or refuses incomplete state

1.5 - Ssh release deployment

1.5.1 - ssh-release-deployment Specification

Publish release files and activate archived static websites through the existing release tool using authenticated SSH and explicit target selection.

The existing release deploy command SHALL use rsync over OpenSSH and accept SSH deployment metadata alongside existing OCI deployments. An SSH-only deployment SHALL require neither Ansible nor an OCI executable. It SHALL verify the selected host using the configured SSH trust mechanism and reuse existing release metadata for version and file identity.

  • WHEN a valid SSH release is selected without Soras or Ansible
  • THEN the tool deploys over SSH to the explicitly configured environment
  • AND an unknown or mismatched host key causes failure before upload
  • WHEN an existing OCI release is deployed
  • THEN its existing deployment behavior remains available

The tool SHALL publish each file directly beneath projects/<project>/releases/<version>/ on the selected host. Regular archives SHALL remain files. The tool SHALL use rsync over SSH for transfer verification and temporary-file publication, update existing filenames using rsync semantics, and preserve unrelated retained files.

  • WHEN a release contains a binary and a compressed archive
  • THEN both are downloadable under their original filenames in the release directory
  • AND the archive is not extracted and no public files/ layer is added
  • WHEN upload is interrupted
  • THEN rsync reports failure and leaves previously completed files available
  • AND a later successful run updates the selected filenames without deleting unrelated files

Only the extract step with an explicitly designated website archive SHALL trigger extraction. The tool SHALL accept .tar.gz and .zip archives containing a static site at archive root, preserve the public archive, and publish extracted content under sites/<project>/releases/<version>/. The link step SHALL select the completed release by atomically changing sites/<project>/current after validation.

  • WHEN upload, extract, and link are selected for a valid archive with index.html
  • THEN the original archive remains downloadable
  • AND the site’s unchanged main URL serves the completed extracted release

Unsafe paths, unsupported archive entries, malformed archives, insufficient space, or missing required site content SHALL cause activation to fail. Concurrent deployments SHALL NOT corrupt release contents or the selected link. Failed activation SHALL leave the previous selection intact.

  • WHEN a site archive contains traversal, an absolute path, or a link entry
  • THEN extraction is rejected without writing outside its staging directory
  • AND the selected site remains unchanged
  • WHEN upload or extraction cannot complete because storage is full
  • THEN the tool reports failure and preserves previously published content

Running the link step for an existing validated extracted release SHALL select it through the same deploy command without uploading or extracting it again. The version SHALL identify the retained extracted release; changed site content requires a new version. The tool SHALL NOT introduce a separate rollback command or delete other releases.

  • WHEN an operator runs link for a retained extracted version
  • THEN only the site’s selected-release link changes
  • AND newer retained releases and their archives remain available

SSH deployment SHALL accept an ordered subset of upload, extract, and link, with upload as the default. Extraction SHALL use a published archive, and linking SHALL select an existing extracted release without local payload files.

  • WHEN an administrator uploads release files and later runs extract alone
  • THEN the archive becomes an extracted versioned site
  • AND the current website selection remains unchanged until link is selected
  • WHEN an administrator runs link alone with a release manifest
  • THEN the current symlink selects that existing site version
  • AND no archive access or rsync transfer is required
  • WHEN step selection is empty, unknown, duplicated, or out of order
  • THEN deployment fails before any remote change

1.6 - Tool cache

1.6.1 - Explicit tool installation

Record AL’s explicit source-built installation boundary after removal of the private executable cache.

AL SHALL be built by Bazel and installed only through an explicitly requested installation target. It SHALL NOT expose al tool or maintain a private executable cache. Updating source SHALL NOT change an installed executable automatically.

  • WHEN an operator requests the repository’s AL install target
  • THEN the installer atomically copies the current source-built executable.
  • WHEN a caller invokes al tool
  • THEN AL reports usage failure without inspecting a tool cache.