@cairnkeep/cli 2.22.4 → 2.23.0

package/scripts/lib/release-verification.mjs

@@ -0,0 +1,131 @@
+import { createHash } from "node:crypto";
+
+function requireThat(condition, label) { if (!condition) throw new Error(`Release verification failed: ${label}.`); }
+const hash = bytes => createHash("sha256").update(bytes).digest("hex");
+const digestPattern = /^sha256:[a-f0-9]{64}$/;
+
+export function validateReleaseOptions(options) {
+  requireThat(/^[A-Za-z0-9][A-Za-z0-9_.-]*\/[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(options.repo ?? ""), "repository");
+  requireThat(/^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/.test(options.version ?? ""), "stable version");
+  for (const field of ["commit", "tree"]) requireThat(/^[a-f0-9]{40}$/.test(options[field] ?? ""), `exact ${field}`);
+  for (const field of ["ciRun", "securityRun", "publishRun"]) requireThat(/^[1-9][0-9]*$/.test(options[field] ?? ""), field);
+}
+
+export function releaseAttestationArguments(image, digest, options) {
+  validateReleaseOptions(options);
+  requireThat(digestPattern.test(digest), "attestation subject digest");
+  requireThat(image === options.repo || image === `${options.repo}-workspace`, "attestation image repository");
+  // Exact certificate identity binds repository, workflow and tag. The CLI
+  // makes this mutually exclusive with its broader signer-workflow selector.
+  return ["attestation", "verify", `oci://ghcr.io/${image}@${digest}`, "--repo", options.repo,
+    "--source-ref", `refs/tags/v${options.version}`, "--source-digest", options.commit,
+    "--cert-identity", `https://github.com/${options.repo}/.github/workflows/publish.yml@refs/tags/v${options.version}`,
+    "--cert-oidc-issuer", "https://token.actions.githubusercontent.com",
+    "--predicate-type", "https://slsa.dev/provenance/v1", "--deny-self-hosted-runners", "--format", "json"];
+}
+
+function json(bytes, label) {
+  try { return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)); }
+  catch { throw new Error(`Release verification failed: ${label} encoding or JSON.`); }
+}
+
+function verifyAssets(options, candidate, released) {
+  const names = [`cairnkeep-cli-${options.version}.tgz`, `cairnkeep-cli-${options.version}.cdx.json`];
+  const exactKeys = (map, expected) => map instanceof Map && JSON.stringify([...map.keys()].sort()) === JSON.stringify(expected.sort());
+  requireThat(exactKeys(candidate, [...names, "SHA256SUMS", "RELEASE-CANDIDATE.json"]), "candidate file set");
+  requireThat(exactKeys(released, [...names, "SHA256SUMS"]), "release asset set");
+  const manifest = json(candidate.get("RELEASE-CANDIDATE.json"), "candidate manifest");
+  requireThat(Object.keys(manifest).sort().join(",") === "schema_version,tree,version"
+    && manifest.schema_version === 1 && manifest.tree === options.tree && manifest.version === options.version, "candidate manifest binding");
+  const sums = new TextDecoder("utf-8", { fatal: true }).decode(candidate.get("SHA256SUMS")).trim().split("\n");
+  requireThat(sums.length === names.length, "checksum file count");
+  const seen = new Set();
+  for (const line of sums) {
+    const match = /^([a-f0-9]{64})\s+\*?(?:\.\/)?([A-Za-z0-9._-]+)$/.exec(line);
+    requireThat(match && names.includes(match[2]) && !seen.has(match[2]), "checksum paths and uniqueness");
+    seen.add(match[2]);
+    requireThat(hash(candidate.get(match[2])) === match[1], "candidate checksum");
+    requireThat(candidate.get(match[2]).equals(released.get(match[2])), "release/candidate exact bytes");
+  }
+  requireThat(candidate.get("SHA256SUMS").equals(released.get("SHA256SUMS")), "checksum asset exact bytes");
+  const sbom = json(candidate.get(names[1]), "SBOM");
+  requireThat(sbom.bomFormat === "CycloneDX" && sbom.specVersion === "1.6"
+    && sbom.metadata?.component?.version === options.version, "CycloneDX release binding");
+  return candidate.get(names[0]);
+}
+
+export async function verifyPublishedRelease(options, io) {
+  validateReleaseOptions(options);
+  const api = path => io.api(path);
+  const ci = await api(`actions/runs/${options.ciRun}`);
+  requireThat(ci.conclusion === "success" && ci.path === ".github/workflows/ci.yml", "successful maintained CI");
+  requireThat((await api(`git/commits/${ci.head_sha}`)).tree?.sha === options.tree, "tested tree");
+  requireThat((await api(`git/commits/${options.commit}`)).tree?.sha === options.tree, "release tree");
+  const security = await api(`actions/runs/${options.securityRun}`);
+  requireThat(security.conclusion === "success" && security.path === ".github/workflows/security.yml", "successful maintained security workflow");
+  requireThat((await api(`git/commits/${security.head_sha}`)).tree?.sha === options.tree, "security-tested tree");
+  let tag = (await api(`git/ref/tags/v${options.version}`)).object;
+  for (let depth = 0; tag?.type === "tag" && depth < 4; depth++) tag = (await api(`git/tags/${tag.sha}`)).object;
+  requireThat(tag?.type === "commit" && tag.sha === options.commit, "immutable tag source");
+  const publication = await api(`actions/runs/${options.publishRun}`);
+  requireThat(publication.conclusion === "success" && publication.path === ".github/workflows/publish.yml"
+    && publication.event === "release" && publication.head_sha === options.commit, "successful exact-source publication");
+  const release = await api(`releases/tags/v${options.version}`);
+  requireThat(release.tag_name === `v${options.version}` && release.draft === false && release.prerelease === false, "published stable release");
+  const artifacts = (await api(`actions/runs/${options.ciRun}/artifacts?per_page=100`)).artifacts;
+  const matches = artifacts?.filter(a => a.name === `release-candidate-${options.tree}` && a.expired === false);
+  requireThat(matches?.length === 1, "one retained exact-tree candidate");
+  const tarball = verifyAssets(options, await io.candidate(matches[0]), await io.release());
+  const registry = await io.registry();
+  let url;
+  try { url = new URL(registry.dist?.tarball); } catch { /* fail below */ }
+  requireThat(registry.version === options.version && url?.protocol === "https:" && url.hostname === "registry.npmjs.org"
+    && !url.username && !url.password && !url.port && !url.hash, "registry tarball authority");
+  const publishedTarball = await io.tarball(url.href);
+  requireThat(tarball.equals(publishedTarball), "registry/candidate exact bytes");
+  requireThat(registry.dist.integrity === `sha512-${createHash("sha512").update(tarball).digest("base64")}`, "registry integrity");
+  requireThat(await io.verifyNpm(tarball), "npm signatures and attestations");
+
+  const images = [];
+  const [owner, project] = options.repo.split("/");
+  for (const name of [project, `${project}-workspace`]) {
+    const image = `${owner}/${name}`;
+    const get = async (kind, ref) => {
+      requireThat([options.version, "latest"].includes(ref) || digestPattern.test(ref), "OCI reference");
+      const result = await io.oci(image, kind, ref);
+      requireThat(digestPattern.test(result.digest) && (!ref.startsWith("sha256:") || result.digest === ref), "OCI content digest");
+      return result;
+    };
+    const index = await get("manifests", options.version);
+    requireThat((await get("manifests", "latest")).digest === index.digest, "stable image channel");
+    const manifests = index.value.manifests;
+    requireThat(Array.isArray(manifests) && manifests.length <= 32, "bounded OCI index");
+    for (const arch of ["amd64", "arm64"]) {
+      const entries = manifests.filter(m => m.platform?.os === "linux" && m.platform?.architecture === arch);
+      requireThat(entries.length === 1, "one image per supported architecture");
+      const entry = entries[0];
+      const manifest = (await get("manifests", entry.digest)).value;
+      const config = (await get("blobs", manifest.config?.digest)).value;
+      requireThat(config.os === "linux" && config.architecture === arch
+        && config.config?.Labels?.["org.opencontainers.image.revision"] === options.commit, "image platform/source binding");
+      const attestations = manifests.filter(m => m.annotations?.["vnd.docker.reference.digest"] === entry.digest
+        && m.annotations?.["vnd.docker.reference.type"] === "attestation-manifest");
+      requireThat(attestations.length === 1, "bound build attestation");
+      const layers = (await get("manifests", attestations[0].digest)).value.layers;
+      requireThat(Array.isArray(layers) && layers.length <= 32, "bounded attestation layers");
+      let sbom = false;
+      for (const layer of layers) {
+        const statement = (await get("blobs", layer.digest)).value;
+        if (statement.predicateType === "https://spdx.dev/Document" && statement.predicate?.spdxVersion?.startsWith("SPDX-")
+          && statement.subject?.some(s => s.digest?.sha256 === entry.digest.slice(7))) sbom = true;
+      }
+      requireThat(sbom, "per-architecture bound SPDX SBOM");
+    }
+    requireThat(await io.verifyAttestation(image, index.digest, options), "verified exact-source release-workflow provenance");
+    images.push({ image: `ghcr.io/${image}`, digest: index.digest, platforms: ["linux/amd64", "linux/arm64"] });
+  }
+  return { schema_version: 1, status: "verified", ...options, candidate_artifact: matches[0].id,
+    exact_bytes: true, cyclonedx: "1.6", npm_signatures_and_attestations: true, images,
+    scope: "release-artifacts-only", anonymous_oci_metadata_verified: true,
+    full_image_layer_pull_verified: false, deployment_verified: false };
+}

package/scripts/test-memory-retrieval-docs.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+set -euo pipefail
+ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+cd "$ROOT"
+for path in docs/memory-retrieval.md docs/benchmarks/memory-retrieval-v1.json docs/learning/video-scripts/V04-memory-retrieval-supplement.md; do
+  [[ -f "$path" ]]
+done
+for path in docs/README.md docs/operating.md docs/storage.md docs/agents.md docs/learning/lessons/L04-memory-fundamentals.md; do
+  grep -qF 'memory-retrieval.md' "$path"
+done
+for path in claude/commands/recall.md opencode/command/recall.md; do
+  grep -qF 'do not automatically widen' "$path"
+  grep -qF 'strategy: "hybrid"' "$path"
+done
+grep -qF 'same admission' docs/memory-retrieval.md
+grep -qF 'HTTP 502' docs/memory-retrieval.md
+grep -qF 'ranking-not-confidence' docs/memory-retrieval.md
+grep -qF 'Status: available since Cairnkeep 2.23.0' docs/memory-retrieval.md
+echo 'PASS: hybrid retrieval, Markdown parity, provider limitations and learning/recording references'

package/scripts/test-release-sbom.sh

@@ -14,6 +14,8 @@ fail() {
 
 node - "$ROOT/package.json" "$ROOT/package-lock.json" "$CANDIDATE_WORKFLOW" "$PUBLISH_WORKFLOW" <<'NODE'
 const fs = require("node:fs");
+const assert = require("node:assert/strict");
+const { parse } = require("yaml");
 
 const manifest = JSON.parse(fs.readFileSync(process.argv[2], "utf8"));
 const lock = JSON.parse(fs.readFileSync(process.argv[3], "utf8"));
@@ -36,6 +38,36 @@ if (!candidateWorkflow.includes("release-candidate:")
   || !candidateWorkflow.includes("name: release-candidate-${{ steps.candidate.outputs.tree }}")) {
   throw new Error("CI must build and upload a tree-addressed release candidate after its required jobs");
 }
+function validateCandidateRetry(workflow) {
+  const job = workflow.jobs["release-candidate"];
+  assert.deepEqual(new Set(job.needs), new Set([
+    "memory-server", "native-windows", "repository", "shell-portability",
+    "server-boot", "container", "fresh-install-macos",
+  ]), "candidate retry must retain every platform/runtime gate");
+  assert.equal(job.if, undefined, "candidate retry must not bypass failed or pending gates");
+  const uploads = job.steps.filter(step => step.uses?.startsWith("actions/upload-artifact@"));
+  assert.equal(uploads.length, 1, "candidate retry must have one artifact publication");
+  assert.equal(uploads[0].with.name, "release-candidate-${{ steps.candidate.outputs.tree }}");
+  assert.equal(uploads[0].with.overwrite, true, "candidate upload must support same-run retries");
+  assert.equal(uploads[0].with["if-no-files-found"], "error");
+}
+const candidate = parse(candidateWorkflow);
+const positive = structuredClone(candidate);
+positive.jobs["release-candidate"].steps.find(step => step.uses?.startsWith("actions/upload-artifact@")).with.overwrite = true;
+validateCandidateRetry(positive);
+for (const overwrite of [undefined, false]) {
+  const invalid = structuredClone(positive);
+  invalid.jobs["release-candidate"].steps.find(step => step.uses?.startsWith("actions/upload-artifact@")).with.overwrite = overwrite;
+  assert.throws(() => validateCandidateRetry(invalid), /same-run retries/);
+}
+const missingGate = structuredClone(positive);
+missingGate.jobs["release-candidate"].needs = missingGate.jobs["release-candidate"].needs.filter(name => name !== "native-windows");
+assert.throws(() => validateCandidateRetry(missingGate), /every platform\/runtime gate/);
+const bypass = structuredClone(positive);
+bypass.jobs["release-candidate"].if = "always()";
+assert.throws(() => validateCandidateRetry(bypass), /must not bypass/);
+validateCandidateRetry(candidate);
+console.log("PASS: retry-safe candidate upload and four gate/replacement mutation controls");
 if (!publishWorkflow.includes("- name: Download the CI-verified release candidate")
   || !publishWorkflow.includes("jq -r '.conclusion'")
   || !publishWorkflow.includes("== success")

package/scripts/test-release-verification.mjs

@@ -0,0 +1,109 @@
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { releaseAttestationArguments, validateReleaseOptions, verifyPublishedRelease } from "./lib/release-verification.mjs";
+
+const options = { repo: "example/project", version: "1.2.3", commit: "a".repeat(40), tree: "b".repeat(40), ciRun: "12", publishRun: "13", securityRun: "14" };
+const hash = bytes => createHash("sha256").update(bytes).digest("hex");
+function fixture() {
+  const tar = Buffer.from("synthetic-package");
+  const sbom = Buffer.from(JSON.stringify({ bomFormat: "CycloneDX", specVersion: "1.6", metadata: { component: { version: options.version } } }));
+  const sums = Buffer.from(`${hash(tar)}  ./cairnkeep-cli-1.2.3.tgz\n${hash(sbom)}  ./cairnkeep-cli-1.2.3.cdx.json\n`);
+  const candidate = new Map([["cairnkeep-cli-1.2.3.tgz", tar], ["cairnkeep-cli-1.2.3.cdx.json", sbom], ["SHA256SUMS", sums],
+    ["RELEASE-CANDIDATE.json", Buffer.from(JSON.stringify({ schema_version: 1, tree: options.tree, version: options.version }))]]);
+  const released = new Map([...candidate].filter(([name]) => name !== "RELEASE-CANDIDATE.json"));
+  const api = new Map([
+    ["actions/runs/12", { conclusion: "success", path: ".github/workflows/ci.yml", head_sha: options.commit }],
+    ["actions/runs/13", { conclusion: "success", path: ".github/workflows/publish.yml", head_sha: options.commit, event: "release" }],
+    ["actions/runs/14", { conclusion: "success", path: ".github/workflows/security.yml", head_sha: options.commit }],
+    [`git/commits/${options.commit}`, { tree: { sha: options.tree } }],
+    ["git/ref/tags/v1.2.3", { object: { type: "commit", sha: options.commit } }],
+    ["actions/runs/12/artifacts?per_page=100", { artifacts: [{ id: 5, name: `release-candidate-${options.tree}`, expired: false }] }],
+    ["releases/tags/v1.2.3", { draft: false, prerelease: false, tag_name: "v1.2.3" }],
+  ]);
+  const objects = new Map();
+  const add = value => { const digest = `sha256:${hash(Buffer.from(JSON.stringify(value)))}`; objects.set(digest, value); return digest; };
+  const manifests = [];
+  for (const architecture of ["amd64", "arm64"]) {
+    const config = add({ os: "linux", architecture, config: { Labels: { "org.opencontainers.image.revision": options.commit } } });
+    const image = add({ config: { digest: config } });
+    manifests.push({ digest: image, platform: { os: "linux", architecture } });
+    const statement = add({ predicateType: "https://spdx.dev/Document", subject: [{ digest: { sha256: image.slice(7) } }], predicate: { spdxVersion: "SPDX-2.3" } });
+    const attestation = add({ layers: [{ digest: statement }] });
+    manifests.push({ digest: attestation, annotations: { "vnd.docker.reference.digest": image, "vnd.docker.reference.type": "attestation-manifest" } });
+  }
+  const index = add({ manifests });
+  let signed = 0, signatures = 0;
+  const io = {
+    api: async path => { assert(api.has(path), `unexpected API request ${path}`); return api.get(path); },
+    candidate: async () => candidate, release: async () => released,
+    registry: async () => ({ version: options.version, dist: { tarball: "https://registry.npmjs.org/package.tgz", integrity: `sha512-${createHash("sha512").update(tar).digest("base64")}` } }),
+    tarball: async () => tar,
+    oci: async (_image, _kind, ref) => { const digest = ref.startsWith("sha256:") ? ref : index; return { digest, value: objects.get(digest) }; },
+    verifyAttestation: async (_image, digest, expected) => { assert.equal(digest, index); assert.deepEqual(expected, options); signed++; return true; },
+    verifyNpm: async bytes => { assert(bytes.equals(tar)); signatures++; return true; },
+  };
+  return { io, api, candidate, released, objects, manifests, index, counts: () => ({ signed, signatures }) };
+}
+const originalFetch = globalThis.fetch;
+globalThis.fetch = () => { throw new Error("offline release controls must not use the network"); };
+try {
+  for (const invalid of [{ repo: "../.." }, { repo: "owner/../secret" }, { version: "01.2.3" }, { version: "1.2.3-beta" },
+    { commit: "main" }, { ciRun: "0" }, { publishRun: "not-a-run" }]) {
+    assert.throws(() => validateReleaseOptions({ ...options, ...invalid }));
+  }
+  const attestationArgs = releaseAttestationArguments("example/project", `sha256:${"d".repeat(64)}`, options);
+  for (const [flag, value] of [["--source-digest", options.commit], ["--source-ref", "refs/tags/v1.2.3"],
+    ["--cert-identity", "https://github.com/example/project/.github/workflows/publish.yml@refs/tags/v1.2.3"],
+    ["--cert-oidc-issuer", "https://token.actions.githubusercontent.com"], ["--predicate-type", "https://slsa.dev/provenance/v1"]]) {
+    assert.equal(attestationArgs[attestationArgs.indexOf(flag) + 1], value);
+  }
+  assert(attestationArgs.includes("--deny-self-hosted-runners"));
+  assert(!attestationArgs.includes("--signer-workflow"), "mutually exclusive identity flags cannot be combined");
+  assert.throws(() => releaseAttestationArguments("other/project", `sha256:${"d".repeat(64)}`, options));
+  const valid = fixture();
+  const report = await verifyPublishedRelease(options, valid.io);
+  assert.equal(report.status, "verified"); assert.equal(report.images.length, 2);
+  assert.equal(report.deployment_verified, false); assert.equal(report.full_image_layer_pull_verified, false);
+  assert.deepEqual(valid.counts(), { signed: 2, signatures: 1 });
+  for (const [name, mutate] of [
+    ["failed CI", f => { f.api.get("actions/runs/12").conclusion = "failure"; }],
+    ["wrong CI workflow", f => { f.api.get("actions/runs/12").path = ".github/workflows/other.yml"; }],
+    ["failed security", f => { f.api.get("actions/runs/14").conclusion = "failure"; }],
+    ["wrong security workflow", f => { f.api.get("actions/runs/14").path = ".github/workflows/other.yml"; }],
+    ["different security tree", f => { const sha = "c".repeat(40); f.api.get("actions/runs/14").head_sha = sha; f.api.set(`git/commits/${sha}`, { tree: { sha: "d".repeat(40) } }); }],
+    ["different tree", f => { f.api.get(`git/commits/${options.commit}`).tree.sha = "c".repeat(40); }],
+    ["different tag", f => { f.api.get("git/ref/tags/v1.2.3").object.sha = "c".repeat(40); }],
+    ["expired candidate", f => { f.api.get("actions/runs/12/artifacts?per_page=100").artifacts[0].expired = true; }],
+    ["failed publication", f => { f.api.get("actions/runs/13").conclusion = "failure"; }],
+    ["wrong publish source", f => { f.api.get("actions/runs/13").head_sha = "c".repeat(40); }],
+    ["draft release", f => { f.api.get("releases/tags/v1.2.3").draft = true; }],
+    ["candidate tampering", f => { f.candidate.set("cairnkeep-cli-1.2.3.tgz", Buffer.from("tampered")); }],
+    ["asset tampering", f => { f.released.set("cairnkeep-cli-1.2.3.cdx.json", Buffer.from("tampered")); }],
+    ["undeclared candidate", f => { f.candidate.set("extra", Buffer.from("extra")); }],
+    ["checksum traversal", f => { f.candidate.set("SHA256SUMS", Buffer.from(`${"a".repeat(64)}  ../escape\n`)); }],
+    ["registry mismatch", f => { f.io.tarball = async () => Buffer.from("different"); }],
+    ["registry credentials", f => { f.io.registry = async () => ({ version: "1.2.3", dist: { tarball: "https://secret@registry.npmjs.org/package.tgz" } }); }],
+    ["signature failure", f => { f.io.verifyNpm = async () => false; }],
+    ["missing architecture", f => { f.objects.get(f.index).manifests = f.manifests.filter(m => m.platform?.architecture !== "arm64"); }],
+    ["wrong image revision", f => { for (const value of f.objects.values()) if (value.config?.Labels) value.config.Labels["org.opencontainers.image.revision"] = "c".repeat(40); }],
+    ["unbound SBOM", f => { for (const value of f.objects.values()) if (value.subject) value.subject[0].digest.sha256 = "c".repeat(64); }],
+    ["provenance failure", f => { f.io.verifyAttestation = async () => false; }],
+  ]) { const f = fixture(); mutate(f); await assert.rejects(() => verifyPublishedRelease(options, f.io), undefined, name); }
+  const scratch = mkdtempSync(join(tmpdir(), "cairn-release-report-test-"));
+  try {
+    const output = join(scratch, "existing.json"); writeFileSync(output, "retained-report\n");
+    const command = fileURLToPath(new URL("verify-published-release.mjs", import.meta.url));
+    const result = spawnSync(process.execPath, [command, "--version", options.version, "--commit", options.commit,
+      "--tree", options.tree, "--ci-run", options.ciRun, "--security-run", options.securityRun, "--publish-run", options.publishRun,
+      "--out", output, "--gh", join(scratch, "missing-command")], { encoding: "utf8", timeout: 3000 });
+    assert.notEqual(result.status, 0); assert.match(result.stderr, /output already exists/);
+    assert.equal(readFileSync(output, "utf8"), "retained-report\n");
+    assert.equal(result.stdout, "");
+  } finally { rmSync(scratch, { recursive: true, force: true }); }
+  console.log("PASS: offline exact-tree release, assets, registry, signatures, architectures, SBOM and provenance controls");
+} finally { globalThis.fetch = originalFetch; }

package/scripts/test-release-verification.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+set -euo pipefail
+ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+node "$ROOT/scripts/test-release-verification.mjs"

package/scripts/test-setup-reconcile.mjs

@@ -18,6 +18,7 @@ import {
 import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { readStableFile } from "./lib/stable-file.mjs";
 
 const EXPECTED_RED_EXIT = 86;
 const RED_MARKER = "PHASE26_RED:SETUP_RECONCILE_MISSING";
@@ -172,8 +173,9 @@ async function testOwnershipBranches(reconciler, fixture, baseline) {
 
   writeFileSync(ownedPath, "operator-owned\n");
   chmodSync(ownedPath, 0o700);
-  const userBytes = readFileSync(ownedPath);
-  const userMtime = statSync(ownedPath).mtimeMs;
+  const userSnapshot = readStableFile(ownedPath, { label: "Operator-owned setup fixture", maxBytes: 1024 * 1024 });
+  const userBytes = userSnapshot.bytes;
+  const userMtime = userSnapshot.stat.mtimeMs;
   const diverged = await reconciler.reconcileSetupPlan(plan(fixture.target, [fixture.first]), { previousState: updated.state });
   assertCounts(diverged, { created: 0, updated: 0, unchanged: 0, skipped: 1 });
   assert.deepEqual(readFileSync(ownedPath), userBytes);

package/scripts/test-windows-native.mjs

@@ -24,6 +24,7 @@ await import("./test-setup-diagnosis.mjs");
 await import("./test-runtime-file-security.mjs");
 await import("./test-container-health.mjs");
 await import("./test-omp-staged-security.mjs");
+await import("./test-release-verification.mjs");
 const sandbox = mkdtempSync(join(tmpdir(), "cairn-windows-native-"));
 const originalBase = process.env.CAIRN_AGENTFS_BASE_DIR;
 const originalPackBase = process.env.CAIRN_PACK_BASE_DIR;

package/scripts/verify-phase19-runtime-evidence.mjs

@@ -2,6 +2,8 @@
 import assert from "node:assert/strict";
 import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
+import fs from "node:fs";
+import { syncBuiltinESMExports } from "node:module";
 import {
   existsSync,
   lstatSync,
@@ -15,6 +17,7 @@ import {
 import { tmpdir } from "node:os";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { readStableFile } from "./lib/stable-file.mjs";
 
 const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const EVIDENCE_RELATIVE = join(
@@ -250,9 +253,7 @@ function assertNoSentinels(bytes, label) {
 function readOwnedFile(root, relative) {
   const label = safeRelative(relative, "evidence file");
   const path = join(root, label);
-  const info = lstatSync(path);
-  if (!info.isFile() || info.isSymbolicLink() || info.size > 16 * 1024 * 1024) throw new Error(`${label}: unsafe evidence file`);
-  const bytes = readFileSync(path);
+  const { bytes } = readStableFile(path, { label: "Runtime evidence file", maxBytes: 16 * 1024 * 1024 });
   assertNoSentinels(bytes, label);
   return bytes;
 }
@@ -762,6 +763,44 @@ function expectFailure(label, operation) {
   assert.throws(operation, undefined, label);
 }
 
+function testEvidenceReadRaces(root) {
+  const path = join(root, "read-race.log");
+  const original = { readFileSync: fs.readFileSync, readSync: fs.readSync, lstatSync: fs.lstatSync };
+  let injected = false;
+  const grow = () => {
+    if (!injected) { injected = true; fs.appendFileSync(path, "changed-after-inspection\n"); }
+  };
+  writeFileSync(path, "original\n");
+  fs.readFileSync = (candidate, ...args) => { if (candidate === path) grow(); return original.readFileSync(candidate, ...args); };
+  fs.readSync = (...args) => { grow(); return original.readSync(...args); };
+  syncBuiltinESMExports();
+  try {
+    assert.throws(() => readOwnedFile(root, "read-race.log"), /unsafe|changed/,
+      "evidence reader accepted bytes changed after inspection");
+    assert.equal(injected, true, "evidence growth race was not exercised");
+  } finally { Object.assign(fs, original); syncBuiltinESMExports(); }
+
+  writeFileSync(path, "original\n");
+  const replacement = join(root, "replacement.log");
+  writeFileSync(replacement, "replacement\n");
+  injected = false;
+  fs.lstatSync = (candidate, ...args) => {
+    const result = original.lstatSync(candidate, ...args);
+    if (candidate === path && !injected) {
+      injected = true;
+      renameSync(path, join(root, "old.log"));
+      renameSync(replacement, path);
+    }
+    return result;
+  };
+  syncBuiltinESMExports();
+  try {
+    assert.throws(() => readOwnedFile(root, "read-race.log"), /unsafe|changed/,
+      "evidence reader accepted a pathname replacement");
+    assert.equal(injected, true, "evidence replacement race was not exercised");
+  } finally { Object.assign(fs, original); syncBuiltinESMExports(); }
+}
+
 function selfTest() {
   const sourceCommit = requireSuccess(git(ROOT, ["rev-parse", "HEAD"]), "read self-test source commit");
   requireCommit(sourceCommit);
@@ -787,6 +826,7 @@ function selfTest() {
     "published contract mutation did not change its digest");
   const root = mkdtempSync(join(tmpdir(), "cairn-phase19-evidence-"));
   try {
+    testEvidenceReadRaces(root);
     const valid = join(root, "valid");
     writeFixture(valid, sourceCommit);
     verifyEvidence(valid, sourceCommit);

package/scripts/verify-published-release.mjs

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readStableFile } from "./lib/stable-file.mjs";
+import { releaseAttestationArguments, validateReleaseOptions, verifyPublishedRelease } from "./lib/release-verification.mjs";
+
+const usage = "Usage: node scripts/verify-published-release.mjs --version X.Y.Z --commit SHA --tree SHA --ci-run ID --security-run ID --publish-run ID --out FILE [--repo OWNER/REPO] [--gh PATH] [--npm PATH]";
+function optionsFrom(args) {
+  const options = { repo: "cairnkeep/cairnkeep", gh: "gh", npm: "npm" };
+  const keys = new Map([["--version", "version"], ["--commit", "commit"], ["--tree", "tree"], ["--ci-run", "ciRun"],
+    ["--security-run", "securityRun"], ["--publish-run", "publishRun"], ["--repo", "repo"], ["--gh", "gh"], ["--npm", "npm"], ["--out", "out"]]);
+  const seen = new Set();
+  for (let i = 0; i < args.length; i += 2) {
+    const key = keys.get(args[i]);
+    if (!key || seen.has(key) || !args[i + 1] || args[i + 1].startsWith("--")) throw new Error(usage);
+    seen.add(key); options[key] = args[i + 1];
+  }
+  if (!options.out) throw new Error(usage);
+  validateReleaseOptions(options);
+  return options;
+}
+
+function run(command, args, options = {}) {
+  const result = spawnSync(command, args, { encoding: "utf8", timeout: 60000, maxBuffer: 16 * 1024 * 1024, ...options });
+  if (result.error || result.status !== 0) {
+    const operation = ["api", "run", "release", "install", "audit", "attestation"].includes(args[0]) ? args[0] : "required";
+    throw new Error(`Release verification failed: ${operation} command unavailable, timed out or failed.`);
+  }
+  return result.stdout;
+}
+
+async function bytesFrom(url, maxBytes, headers = {}, blobRedirects = false) {
+  const signal = AbortSignal.timeout(30000);
+  let response;
+  for (let redirects = 0; redirects <= 3; redirects++) {
+    response = await fetch(url, { headers, redirect: "manual", signal });
+    if (![301, 302, 303, 307, 308].includes(response.status)) break;
+    const next = new URL(response.headers.get("location"), url);
+    await response.body?.cancel();
+    if (!blobRedirects || redirects === 3 || next.protocol !== "https:"
+      || next.hostname !== "pkg-containers.githubusercontent.com" || next.username || next.password || next.port) {
+      throw new Error("Release verification failed: unexpected registry redirect.");
+    }
+    url = next.href; headers = {}; // Never forward registry authorization.
+  }
+  if (!response.ok || !response.body) throw new Error("Release verification failed: remote response unavailable.");
+  const declared = Number(response.headers.get("content-length"));
+  if (Number.isFinite(declared) && declared > maxBytes) { await response.body.cancel(); throw new Error("Release verification failed: remote byte limit."); }
+  const reader = response.body.getReader();
+  const chunks = []; let total = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read(); if (done) break;
+      total += value.byteLength;
+      if (total > maxBytes) throw new Error("Release verification failed: remote byte limit.");
+      chunks.push(Buffer.from(value));
+    }
+    return Buffer.concat(chunks, total);
+  } finally { await reader.cancel().catch(() => {}); reader.releaseLock(); }
+}
+const parse = bytes => JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+const digest = bytes => `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+
+async function main(args) {
+  if (args.length === 1 && ["--help", "-h"].includes(args[0])) { console.log(usage); return; }
+  const options = optionsFrom(args);
+  const { gh, npm, out, ...expected } = options;
+  const output = resolve(out);
+  try { fs.lstatSync(output); throw new Error("Release verification failed: output already exists."); }
+  catch (error) { if (error.code !== "ENOENT") throw error; }
+  const scratch = fs.mkdtempSync(join(tmpdir(), "cairn-release-verification-"));
+  fs.chmodSync(scratch, 0o700);
+  const ghRun = args => run(gh, args);
+  const readDirectory = directory => new Map(fs.readdirSync(directory).map(name => [name,
+    readStableFile(join(directory, name), { label: "Release verification input", maxBytes: 64 * 1024 * 1024 }).bytes]));
+  const tokens = new Map();
+  try {
+    const io = {
+      api: async suffix => JSON.parse(ghRun(["api", `repos/${expected.repo}/${suffix}`])),
+      candidate: async artifact => {
+        const directory = join(scratch, "candidate");
+        ghRun(["run", "download", expected.ciRun, "--repo", expected.repo, "--name", artifact.name, "--dir", directory]);
+        return readDirectory(directory);
+      },
+      release: async () => {
+        const directory = join(scratch, "release");
+        ghRun(["release", "download", `v${expected.version}`, "--repo", expected.repo, "--dir", directory]);
+        return readDirectory(directory);
+      },
+      registry: async () => parse(await bytesFrom(`https://registry.npmjs.org/@cairnkeep%2fcli/${expected.version}`, 8 * 1024 * 1024)),
+      tarball: async url => bytesFrom(url, 64 * 1024 * 1024),
+      verifyNpm: async tarball => {
+        const prefix = join(scratch, "npm");
+        run(npm, ["install", "--prefix", prefix, `@cairnkeep/cli@${expected.version}`, "--ignore-scripts", "--no-audit", "--no-fund", "--registry", "https://registry.npmjs.org"]);
+        const lock = parse(readStableFile(join(prefix, "package-lock.json"), { label: "Verification install lock", maxBytes: 8 * 1024 * 1024 }).bytes);
+        if (lock.packages?.["node_modules/@cairnkeep/cli"]?.integrity !== `sha512-${createHash("sha512").update(tarball).digest("base64")}`) {
+          throw new Error("Release verification failed: audited package/candidate binding.");
+        }
+        const audited = run(npm, ["audit", "signatures", "--prefix", prefix, "--registry", "https://registry.npmjs.org"]);
+        return /[1-9][0-9]* packages have verified registry signatures/.test(audited)
+          && /[1-9][0-9]* packages have verified attestations/.test(audited);
+      },
+      oci: async (image, kind, ref) => {
+        if (!tokens.has(image)) {
+          const result = parse(await bytesFrom(`https://ghcr.io/token?service=ghcr.io&scope=repository:${image}:pull`, 64 * 1024));
+          if (typeof result.token !== "string" || !result.token) throw new Error("Release verification failed: anonymous OCI access.");
+          tokens.set(image, result.token);
+        }
+        const bytes = await bytesFrom(`https://ghcr.io/v2/${image}/${kind}/${ref}`, 16 * 1024 * 1024, {
+          Authorization: `Bearer ${tokens.get(image)}`,
+          Accept: "application/vnd.oci.image.index.v1+json, application/vnd.docker.distribution.manifest.list.v2+json, application/vnd.oci.image.manifest.v1+json",
+        }, kind === "blobs");
+        return { digest: digest(bytes), value: parse(bytes) };
+      },
+      verifyAttestation: async (image, imageDigest) => {
+        const verified = JSON.parse(ghRun(releaseAttestationArguments(image, imageDigest, expected)));
+        return Array.isArray(verified) && verified.length > 0;
+      },
+    };
+    const report = await verifyPublishedRelease(expected, io);
+    fs.writeFileSync(output, `${JSON.stringify(report, null, 2)}\n`, { flag: "wx", mode: 0o600 });
+    console.log(JSON.stringify(report));
+  } finally { fs.rmSync(scratch, { recursive: true, force: true }); }
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const previousMask = process.umask(0o077);
+  try { await main(process.argv.slice(2)); }
+  catch (error) {
+    console.error(error.message === usage || error.message?.startsWith("Release verification failed:")
+      ? error.message : "Release verification failed; no verified report was written.");
+    process.exitCode = 1;
+  } finally { process.umask(previousMask); }
+}

package/templates/playbook-agent-instructions.md.template

@@ -10,6 +10,11 @@ inventory, or search commands such as `pwd`, `ls`, `rg --files`, `find`,
 - If `memory_search` is available, derive one short query from the task and
   search `scope: project` once. Derive it from the user's task; do not inspect
   the repository first merely to formulate the query.
+- When the discovered schema supports hybrid search, use it for explicit
+  identifiers or mixed wording; request explanations when needed. Supply only
+  aliases already known from the task. Hybrid semantic-only matches require an
+  explicit model-specific positive similarity threshold; otherwise keep the
+  existing semantic strategy for paraphrases. Empty results are acceptable.
 - Treat returned memory as a locator, not authority. Read and verify the
   maintained repository sources it references before implementing a result.
 - If the tool is unavailable or no relevant result exists, continue with