Exact local GraphOS releases

GraphOS has one current local release path. The promoter installs an immutable, package-name-selected wheel closure and changes the active release only after every static artifact check passes. It does not support editable installs, source trees, direct wheel URLs, legacy layouts, best-effort fallbacks, or in-place upgrades.

The promoter is current-only for native Linux and WSL2 running a Linux userspace. It requires POSIX ownership and mode enforcement, directory file descriptors, advisory flock, sealed anonymous memfd executables, /proc descriptor paths, relative symlinks, process groups, and /proc process inspection. Native Windows and macOS promotion are unsupported. The Agent Utilities wheel may be installed on those platforms for other capabilities, but this promoter must fail closed there rather than selecting a compatibility path.

Input contract

The caller supplies five external inputs:

1. An opaque release ID matching release-[a-z0-9][a-z0-9.-]{2,63}.
2. A flat wheelhouse containing one requirements lock and exactly one wheel for every locked distribution. No directories, source archives, links, or unrelated files are accepted. The packaged assembler creates this from a wheel-only source.
3. An ExactLocalRelease JSON document conforming to deploy/release/exact-local-release-spec.schema.json. The packaged assembler creates this document; it is not hand-authored or generated by an external script.
4. An existing, caller-owned releases root. The candidate directory and current link are created inside that root, so staging and activation share a filesystem. Under WSL, run the promoter inside WSL2 and use a Linux-native filesystem for the runtime root rather than a Windows-mounted source workspace.
5. Exact identities for the separately installed Python and uv executables. The assembler binds its Python 3.12 interpreter and the current uv 0.11.7 executable into the specification. The promoter re-hashes both tools before use and rejects any version or digest drift.

The requirements lock is intentionally stricter than a general pip lock. Each logical line is one exact package-name requirement and one SHA-256 hash:

agent-utilities[serving]==<exact-version> --hash=sha256:<artifact-digest>
epistemic-graph[full]==<exact-version> --hash=sha256:<artifact-digest>
langfuse-agent[mcp]==<exact-version> --hash=sha256:<artifact-digest>

The complete transitive closure follows the same format. Markers, constraints, recursive includes, multiple hashes, indexes, source distributions, URLs, local paths, and direct references are rejected. One lock entry maps to one wheel. This makes the wheelhouse a neutral, closed, platform-specific release input rather than a resolver hint. The assembler accepts one explicit verified uv executable. The only installer used by the promoter is the byte-identical executable resolved from PATH; the promoter exposes no installer override.

The JSON specification binds the lock, all three release roots, and both native Epistemic Graph artifacts:

{
  "apiVersion": "graphos.io/v2",
  "kind": "ExactLocalRelease",
  "releaseId": "release-r19",
  "requirements": {
    "file": "release-requirements.txt",
    "sha256": "sha256:<requirements-digest>"
  },
  "packages": {
    "agent-utilities": {
      "version": "<exact-version>",
      "wheel": "agent_utilities-<exact-version>-py3-none-any.whl",
      "sha256": "sha256:<artifact-digest>"
    },
    "epistemic-graph": {
      "version": "<exact-version>",
      "wheel": "epistemic_graph-<exact-version>-<platform-tag>.whl",
      "sha256": "sha256:<artifact-digest>"
    },
    "langfuse-agent": {
      "version": "<exact-version>",
      "wheel": "langfuse_agent-<exact-version>-py3-none-any.whl",
      "sha256": "sha256:<artifact-digest>"
    }
  },
  "nativeArtifacts": {
    "epistemic-graph-server": "sha256:<installed-binary-digest>",
    "epistemic-graph-numeric": "sha256:<installed-extension-digest>"
  },
  "toolchain": {
    "python": {
      "version": "<exact-python-version>",
      "sha256": "sha256:<python-executable-digest>"
    },
    "uv": {
      "version": "<exact-uv-version>",
      "sha256": "sha256:<uv-executable-digest>"
    }
  },
  "commands": {
    "canary": {
      "entryPoint": "graph-os-release-canary",
      "arguments": ["--json"],
      "timeoutSeconds": 30
    },
    "doctor": {
      "entryPoint": "agent-utilities-doctor",
      "arguments": [
        "--json",
        "--live",
        "--only",
        "engine_request_context",
        "engine",
        "langfuse",
        "native_optimizer",
        "skills"
      ],
      "timeoutSeconds": 120
    }
  }
}

The live doctor proof is mandatory. Trust bundles, endpoints, AgentConfig, and credentials remain external runtime configuration. The promoter inherits that environment but never copies or reports it. The installer and proof processes also strip Python, pip, uv, and dynamic-loader injection variables before execution.

Assembly and promotion

Run the packaged assembler under the same verified Python environment that will run the promoter. Its source directory contains wheels only. It rejects an incomplete or non-minimal union of epistemic-graph[full], agent-utilities[serving], and langfuse-agent[mcp], verifies the folded engine binary and numeric extension, and atomically publishes a new private directory without overwriting an earlier assembly:

"$RELEASE_PYTHON" -m scripts.release.assemble_exact_local_release \
  --release-id "$RELEASE_ID" \
  --source-wheelhouse "$BUILT_WHEELS" \
  --uv "$UV_EXECUTABLE" \
  --output "$RELEASE_INPUTS"

RELEASE_SPEC="$RELEASE_INPUTS/exact-local-release.json"
RELEASE_WHEELHOUSE="$RELEASE_INPUTS/wheelhouse"

The assembler's retained JSON status contains only the release ID, filenames, versions, counts, and content digests. It never retains source/output paths, tool paths, command output, host or user identity, endpoints, or credentials.

Stop GraphOS and every Epistemic Graph server before promotion, then run:

"$RELEASE_PYTHON" -m scripts.release.promote_local_release \
  --release-id "$RELEASE_ID" \
  --spec "$RELEASE_SPEC" \
  --wheelhouse "$RELEASE_WHEELHOUSE" \
  --releases-root "$RELEASES_ROOT" \
  --evidence "$RELEASE_EVIDENCE"

The promoter performs these gates serially to bound memory and native-process use:

1. Validate the exact JSON keys, lock digest, root versions, extras, toolchain versions and digests, and artifact digests. The releases root and evidence parent must be caller-owned private directories. The absolute evidence path must be new and disjoint from the specification, wheelhouse, and releases root.
2. Reject wheelhouse links, special files, nested content, path traversal, unsafe archive members, direct_url.json, missing metadata, and any lock/wheel drift.
3. Copy the validated closure into the new release directory to close the input race, copy the verified Python and uv executables into sealed anonymous Linux files, create a copy-based Python environment, and invoke uv pip install with --offline, --no-index, --require-hashes, --no-deps, and copy link mode. Root selection comes only from the package-name requirements lock.
4. Verify the complete installed distribution set, every reachable metadata dependency and selected extra, minimal closure, every version and RECORD digest/size against the locked wheel, full site-package ownership, entry points, the unchanged copied-interpreter baseline, the Agent Utilities [serving]/Langfuse metadata bindings, and exact server/numeric native digests.
5. Reject every installed link, special file, path escape, unrecorded command, and PEP 610 record. Remove only the candidate's temporary wheelhouse copy.
6. Require zero running graph-os, graph-os-daemon, or epistemic-graph-server processes.
7. Seal the candidate read-only and durably record a prepared activation journal. Replace current atomically with a relative symlink to the candidate, execute the release-owned canary and doctor under bounded time/output limits, and prove that no engine process leaked. Bytecode writes are disabled and a complete release-tree snapshot must remain unchanged across both proofs.
8. Sign and independently verify evidence that cross-binds the specification, wheels, toolchain, the exact-local campaign's Agent Utilities and distribution closure identities, interpreter, GraphOS launcher, and native engine. Durably write the signed evidence into the committed activation journal first, publish the same bytes with no-replace semantics, and clear the journal only after that publication is durable. A same-release invocation with the exact specification and evidence destination recovers an interrupted prepared, activated, or committed transaction before doing new work.

If either command fails, times out, emits a nonconforming report, or leaves a graph process, the promoter atomically restores the previous current target. When no previous release existed, it atomically removes current. It never deletes the previous release or the rejected candidate; operators retain both for review and must remove an obsolete release explicitly after evidence review.

Evidence and review

The caller-selected evidence file conforms to deploy/release/exact-local-release-evidence.schema.json. It contains release and artifact digests, toolchain identities, aggregate closure counts, zero-process counts, atomic activation state, exit codes, deterministic outcome digests, and an external signature. It contains no command arguments, filesystem paths, hostnames, usernames, endpoints, URLs, credentials, raw doctor output, or raw canary output. The evidence destination is never overwritten.

A promoted status with errorCode: null, a non-zero distributionCount, both process counts equal to zero, recordVerified: true, immutableAfterProof: true, rollback not-required, four passed exit-zero command records, exact campaign handoff identities, and a valid signature is the local activation gate. rolled-back, rollback-failed, and rejected are terminal failures for that candidate. Repair the named stable error code and assemble a new release ID; do not mutate an existing release directory.

The signer and verifier are external JSON-command adapters configured through EXACT_LOCAL_EVIDENCE_SIGNER_COMMAND and EXACT_LOCAL_EVIDENCE_VERIFIER_COMMAND. They receive bounded canonical JSON on standard input and return bounded JSON; key material never enters the release specification or evidence. Verify a published record independently with:

verify-local-graphos-release-evidence \
  --release-id "$RELEASE_ID" \
  --spec "$RELEASE_SPEC" \
  --evidence "$RELEASE_EVIDENCE"

The signed certificationArtifacts object is the campaign handoff. Its Agent Utilities, distribution-closure, release-Python, GraphOS, and engine digests use the campaign's exact identity algorithms. Create the closed handoff with generate-exact-local-gates-manifest; it re-verifies this signed evidence, cross-checks the engine/native-artifact identity, and combines those values with the current harness and fixed test-catalog digests without retaining the supplied source root. Pin that manifest by its own SHA-256. The promoter and generator do not infer or embed source-checkout locations.

This activation evidence does not replace the exact installed local certification. After promotion, run that serial campaign against the release-owned interpreter, GraphOS launcher, and engine binary to close the intent, optimizer, provider-materialization, and A2A runtime gates. The promoter proves artifact integrity and safe activation; the campaign proves the served feature behavior.