@awebai/oats 0.25.8 → 0.26.0

package/lib/readiness.mjs

@@ -1,225 +0,0 @@
-/** K5 — readiness quartet, signature status and enforced policy, as DATA.
- *
- * `installed | trusted | configured | enrolled`, each `pass | fail | unknown |
- * not-applicable` with items a human can act on: subject, whether it is
- * required, the reason, the producer of the fact, evidence, remedy. Every fact
- * is derived from what inspect already reports (capability inventory, health,
- * executable approval, activation, runtime-package requirements, soul
- * declarations) — never a second opinion. Unknown is unknown; "Ready" is the
- * consumer's word and only when every required check passes. */
-import { spawnSync } from "node:child_process";
-import { killGroup } from "./process-group.mjs";
-import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { parseYamlNested } from "./core.mjs";
-
-export const READINESS_API = 1;
-
-function roll(items, { required = (i) => i.required !== false } = {}) {
-  const req = items.filter(required);
-  if (!items.length) return "not-applicable";
-  if (req.some((i) => i.status === "fail")) return "fail";
-  if (req.some((i) => i.status === "unknown")) return "unknown";
-  if (req.every((i) => i.status === "pass" || i.status === "not-applicable")) return req.length ? "pass" : "not-applicable";
-  return "unknown";
-}
-const item = (subject, status, { required = true, reason = null, producer = "kernel", evidence = null, remedy = null, ...rest } = {}) =>
-  ({ subject, status, required, reason, producer, evidence, remedy, ...rest });
-
-/** Verified Git signature of a source commit, named signer or nothing.
- *  Requires network (fetch) — only when the caller asks (`verify: true`);
- *  otherwise `unknown` with the reason. Never a URL, owner or hash as signer. */
-export const SIGNATURE_FAILURES = Object.freeze(["transport-not-allowed", "fetch-failed", "fetch-timeout", "budget-exhausted", "verifier-failed", "verifier-timeout", "cannot-check", "no-source"]);
-const ALLOWED_TRANSPORTS = /^(https:\/\/|ssh:\/\/|git@[^/:]+:)/;
-/** Verified Git signature of a source commit, named signer or nothing.
- *  Requires network (fetch) — only when the caller asks (`verify: true`);
- *  otherwise `unknown` with the reason. Never a URL, owner or hash as signer.
- *  Bounded custody: one total budget per call (`budgetMs`, default 60s) shared
- *  by fetch and verify; each Git child runs in its own process group and is
- *  killed with the group on timeout; the scratch repository is removed on every
- *  exit including signals; Git reads NO global/system config and cannot prompt;
- *  only https/ssh transports are fetched. Failures carry a closed `failure`
- *  code — never stderr. */
-/** One verification budget for a whole readiness read: every signatureOf call
- *  in that read draws from it, so a target with N capabilities is bounded by the
- *  TOTAL (default 120 s), not N × per-call. */
-export function verificationBudget(totalMs = 120000) {
-  const started = Date.now();
-  return { totalMs, remaining: () => totalMs - (Date.now() - started) };
-}
-const scratchDirs = new Set();
-let signalCleanupInstalled = false;
-function installSignalCleanup() {
-  if (signalCleanupInstalled) return; signalCleanupInstalled = true;
-  const sweep = () => { for (const d of scratchDirs) { try { rmSync(d, { recursive: true, force: true }); } catch { /* best effort */ } } scratchDirs.clear(); };
-  process.once("exit", sweep);
-  for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) process.once(sig, () => { sweep(); process.exit(128 + (sig === "SIGINT" ? 2 : sig === "SIGTERM" ? 15 : 1)); });
-}
-export function signatureOf({ url, commit }, { verify = false, budgetMs = 60000, budget = null } = {}) {
-  if (!url || !commit || commit === "local") return { status: "not-applicable", signer: null, reason: commit === "local" ? "path-installed capability has no source commit" : "no source recorded", failure: null };
-  if (!verify) return { status: "unknown", signer: null, reason: "signature verification needs a network fetch; pass --verify-signatures", failure: null };
-  if (!ALLOWED_TRANSPORTS.test(url)) return { status: "unknown", signer: null, reason: "source transport is not https or ssh; not fetched", failure: { code: "transport-not-allowed" } };
-  const shared = budget ?? verificationBudget(budgetMs);
-  if (shared.remaining() <= 0) return { status: "unknown", signer: null, reason: "the verification budget was exhausted", failure: { code: "budget-exhausted" } };
-  installSignalCleanup();
-  const dir = mkdtempSync(join(tmpdir(), "oats-sig-")); scratchDirs.add(dir);
-  const cleanup = () => { scratchDirs.delete(dir); try { rmSync(dir, { recursive: true, force: true }); } catch { /* best effort */ } };
-  const env = { PATH: process.env.PATH ?? "", HOME: dir, GIT_TERMINAL_PROMPT: "0", GIT_CONFIG_NOSYSTEM: "1", GIT_CONFIG_GLOBAL: "/dev/null", GIT_ASKPASS: "/bin/false", SSH_ASKPASS: "/bin/false", GIT_SSH_COMMAND: "ssh -o BatchMode=yes", LC_ALL: "C" };
-  const git = (args, stage) => {
-    const left = shared.remaining();
-    if (left <= 0) throw Object.assign(new Error("budget"), { failure: "budget-exhausted" });
-    const child = spawnSync("git", ["-C", dir, "-c", "core.fsmonitor=false", "-c", "core.hooksPath=/dev/null", "-c", "protocol.allow=never", "-c", "protocol.https.allow=always", "-c", "protocol.ssh.allow=always", ...args],
-      { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: left, killSignal: "SIGKILL", detached: true, env, shell: false });
-    if (child.error?.code === "ETIMEDOUT" || child.signal === "SIGKILL") { killGroup(child); throw Object.assign(new Error(stage), { failure: `${stage}-timeout` }); }
-    if (child.error || child.status !== 0) { killGroup(child); throw Object.assign(new Error(stage), { failure: `${stage}-failed` }); }
-    return child.stdout;
-  };
-  try {
-    git(["init", "-q"], "verifier");
-    git(["fetch", "-q", "--depth", "1", url, commit], "fetch");
-    // %G? : G good, B bad, U good-untrusted, X expired, Y expired key, R revoked, E cannot check, N none
-    const out = git(["log", "-1", "--format=%G?%x00%GS%x00%GK%x00%GF", commit], "verifier").trim();
-    const [code, signerName, keyId, fingerprint] = out.split("\0");
-    if (code === "N") return { status: "unsigned", signer: null, reason: "commit carries no signature", failure: null };
-    if (code === "G") return { status: "verified", signer: { id: fingerprint || keyId || null, label: signerName || null }, reason: null, failure: null };
-    if (code === "U") return { status: "verified", signer: { id: fingerprint || keyId || null, label: signerName || null }, reason: "good signature from a key not marked trusted in the local keyring", trust: "untrusted-key", failure: null };
-    if (code === "E") return { status: "unknown", signer: null, reason: "signature present but cannot be checked (missing public key)", failure: { code: "cannot-check" } };
-    return { status: "invalid", signer: null, reason: { B: "bad signature", X: "good signature that has expired", Y: "good signature made by an expired key", R: "good signature made by a revoked key" }[code] || "verifier reported an unrecognised state", failure: null };
-  } catch (e) {
-    const code = SIGNATURE_FAILURES.includes(e.failure) ? e.failure : "verifier-failed";
-    const reasons = { "fetch-failed": "the source could not be fetched", "fetch-timeout": "the fetch exceeded the verification budget", "budget-exhausted": "the verification budget was exhausted", "verifier-failed": "the local verifier failed", "verifier-timeout": "the local verifier exceeded the verification budget" };
-    return { status: "unknown", signer: null, reason: reasons[code], failure: { code } };
-  } finally { cleanup(); }
-}
-
-function sourceOfCapability(cap, catalog) {
-  // cap.source is e.g. "catalog:oats.framework" or "git:https://…@ref#path"; the
-  // installed record's package commit is what we would verify.
-  const src = String(cap.source || "");
-  if (src.startsWith("git:")) { const m = /^git:([^@#]+)(?:@([^#]+))?/.exec(src); return { url: m?.[1] ?? null, commit: cap.commit ?? m?.[2] ?? null }; }
-  if (src.startsWith("catalog:") && catalog) { const entry = catalog.packages?.[src.slice(8)]; return { url: entry?.url ?? null, commit: cap.commit ?? null }; }
-  return { url: null, commit: cap.commit ?? null };
-}
-
-/** The quartet for a scope or one soul, from an inspect result. */
-export function readinessOf(inspect, { soul = null, verifySignatures = false, catalog = null, deploymentDir = null, memberDocument = null, selector = null, verificationBudgetMs = 120000 } = {}) {
-  const caps = inspect.capabilities || [];
-  const budget = verifySignatures ? verificationBudget(verificationBudgetMs) : null;
-  const soulEntry = soul ? (inspect.souls || []).find((s) => s.name === soul) : null;
-  const declaredRequires = soulEntry?.declarations?.requires?.capabilities ? Object.keys(soulEntry.declarations.requires.capabilities) : null;
-  const required = new Set(declaredRequires ?? caps.filter((c) => c.activation?.enabled).map((c) => c.id));
-  const declaredForSoul = (c) => !!c.activation?.declaredAt?.some((d) => (d.targets || []).includes(`soul:${soul}`));
-  const relevant = soul ? caps.filter((c) => required.has(c.id) || declaredForSoul(c)) : caps;
-  // Typed linkage for consumers (frame-level per-capability rows): WHICH
-  // capability, at which config level/scope, and WHY it is in this quartet.
-  const capabilityOf = (c) => ({ id: c.id, level: c.activation?.level ?? null, scope: c.activation?.target ?? null });
-  const originOf = (c) => declaredRequires?.includes(c.id) ? { kind: "requires", target: `soul:${soul}` }
-    : soul && declaredForSoul(c) ? { kind: "declares", target: `soul:${soul}` }
-    : c.activation?.enabled ? { kind: "default", target: c.activation?.target ?? "global" } : { kind: "inventory", target: null };
-  const typed = (c) => ({ capability: capabilityOf(c), origin: originOf(c) });
-
-  // installed — the artifact's bytes are present and locked with matching integrity
-  const installed = relevant.map((c) => {
-    const ok = c.health?.installed === true && (c.health.integrity == null || c.health.installedIntegrity == null || c.health.integrity === c.health.installedIntegrity);
-    return item(c.id, ok ? "pass" : c.health?.installed === false ? "fail" : "unknown", { required: required.has(c.id), producer: "oats list",
-      reason: ok ? null : c.health?.installed === false ? "not acquired" : c.health?.code || "integrity drift", evidence: { version: c.version ?? null, integrity: c.health?.integrity ?? null, origin: c.origin ?? null },
-      remedy: ok ? null : `oats install ${c.package || c.id}`, ...typed(c) });
-  });
-  for (const id of required) if (!caps.some((c) => c.id === id)) installed.push(item(id, "fail", { producer: "soul declaration", reason: "declared by the soul but not in the inventory", remedy: `oats install <package providing ${id}>`,
-    capability: { id, level: null, scope: null }, origin: { kind: "requires", target: `soul:${soul}` } }));
-
-  // trusted — executable approval of the exact artifact; signature separately
-  const trusted = relevant.map((c) => {
-    // The inspect row states whether the manifest has anything trust approves
-    // (commands/hooks/launch env). No surface → trust is not-applicable, however
-    // the lock records it. Older rows without the flag fall back to the old heuristic.
-    const executable = typeof c.health?.executableSurface === "boolean" ? c.health.executableSurface
-      : !!(c.operations?.length || c.health?.code === "untrusted-surface");
-    const approved = c.health?.trusted === true;
-    const sig = signatureOf(sourceOfCapability(c, catalog), { verify: verifySignatures, budget });
-    return item(c.id, !executable ? "not-applicable" : approved ? "pass" : c.health?.trusted === false ? "fail" : "unknown", { required: required.has(c.id), producer: "artifact approval",
-      reason: !executable ? "no executable surface" : approved ? null : "executable surface not approved", evidence: { integrity: c.health?.integrity ?? null }, remedy: approved || !executable ? null : `oats trust ${c.id}`,
-      signature: sig, ...typed(c) });
-  });
-
-  // configured — EFFECTIVE activation for the subject (a declaration at the
-  // soul is not activation: `enabled` is the resolved verdict for this subject,
-  // and a declared-but-disabled binding is a fail that says so) + runtime
-  // package requirements + layer readiness problems
-  const configured = [];
-  for (const c of relevant) {
-    const active = c.activation?.enabled === true;
-    const declaredOnly = !active && soul && declaredForSoul(c);
-    if (required.has(c.id)) configured.push(item(`${c.id} activation`, active ? "pass" : "fail", { producer: "oats-config.yaml",
-      reason: active ? null : declaredOnly ? `declared for soul ${soul} but disabled${c.activation?.reason ? ` (${c.activation.reason})` : ""}` : `not active for ${soul ? `soul ${soul}` : "this scope"}`,
-      evidence: { target: c.activation?.target ?? null, level: c.activation?.level ?? null, source: c.activation?.source ?? null }, remedy: active ? null : `oats use ${c.id}${soul ? ` --soul ${soul}` : ""}`, ...typed(c) }));
-    for (const miss of c.missingRequires || []) configured.push(item(`${c.id} requires ${miss.command}`, "fail", { producer: "capability manifest", reason: miss.why || "required command not on PATH", remedy: miss.install || null, ...typed(c) }));
-  }
-  for (const p of inspect.problems || []) if (/runtime package|DISABLED|extension/i.test(p.message || "")) configured.push(item(p.capability || p.code, "fail", { producer: "runtime settings", reason: p.message, remedy: null }));
-  if (soulEntry && soulEntry.readiness?.status === "undeclared") configured.push(item(`${soul} declarations`, "not-applicable", { required: false, producer: "soul.yaml", reason: "no requirements declared" }));
-
-  // enrolled — workspace member admission (decision §3): not-applicable for
-  // standalone; pass/fail when this repository declares a workspace.
-  const enrolled = [];
-  const member = memberDocument ?? readMemberDocument(deploymentDir);
-  if (!member) enrolled.push(item("workspace membership", "not-applicable", { required: false, producer: "oats.yaml", reason: "standalone deployment: no workspace declared in oats.yaml" }));
-  else if (member.unreadable) enrolled.push(item("workspace membership", "unknown", { producer: "oats.yaml", reason: "workspace member document is unreadable; membership cannot be stated", evidence: { file: member.file ?? null }, remedy: "repair oats.yaml (valid YAML) and re-run" }));
-  else if (!member.workspace?.source) enrolled.push(item("workspace membership", "not-applicable", { required: false, producer: "oats.yaml", reason: "oats.yaml declares exports but no workspace backlink" }));
-  else enrolled.push(item(`member of ${member.workspace.source}`, member.admitted === true ? "pass" : member.admitted === false ? "fail" : "unknown", { producer: "workspace discovery",
-    reason: member.admitted === true ? null : member.admitted === false ? "this repository is not admitted in the workspace's members" : "reciprocal admission not observed: this CLI reads the backlink but does not yet fetch the workspace's members (declared, not verified)",
-    evidence: { workspace: member.workspace.source, revision: member.workspace.revision ?? null }, remedy: member.admitted === true ? null : "ask the workspace maintainer to admit this repository (oats-workspace.yaml members) — enrolment is admission, not login" }));
-
-  const checks = { installed: { status: roll(installed), items: installed }, trusted: { status: roll(trusted), items: trusted }, configured: { status: roll(configured), items: configured }, enrolled: { status: roll(enrolled), items: enrolled } };
-  const requiredStatuses = Object.values(checks).flatMap((c) => c.items.filter((i) => i.required).map((i) => i.status));
-  // Per-capability grouping of the same items (no second observation): each
-  // capability's four verdicts, ready only if all its REQUIRED items pass.
-  const byCapability = [...new Set(Object.values(checks).flatMap((c) => c.items.map((i) => i.capability?.id).filter(Boolean)))].sort().map((id) => {
-    const of = (name) => checks[name].items.filter((i) => i.capability?.id === id);
-    const statuses = Object.keys(checks).flatMap((name) => of(name).filter((i) => i.required).map((i) => i.status));
-    const any = Object.keys(checks).flatMap((name) => of(name)).find(Boolean);
-    return { capability: any?.capability ?? { id, level: null, scope: null }, origin: any?.origin ?? null, required: statuses.length > 0,
-      checks: Object.fromEntries(Object.keys(checks).map((name) => [name, of(name).length ? roll(of(name)) : "not-applicable"])),
-      ownReady: statuses.length > 0 && statuses.every((s) => s === "pass" || s === "not-applicable") };
-  });
-  // Items that belong to no capability (workspace membership, soul declarations)
-  // are SUBJECT-level: a capability's own verdict never overrides them, and a
-  // row must not read "ready" while the subject is blocked by one of them.
-  const subjectBlockers = Object.entries(checks).flatMap(([name, c]) => c.items.filter((i) => i.required && !i.capability && i.status !== "pass" && i.status !== "not-applicable").map((i) => ({ check: name, subject: i.subject, status: i.status })));
-  for (const g of byCapability) g.ready = g.ownReady && subjectBlockers.length === 0;
-  return { readinessApi: READINESS_API, subject: { ...(soul ? { kind: "soul", name: soul } : { kind: "scope", context: inspect.scope?.context ?? null }), ...(selector ? { selector } : {}) }, at: new Date().toISOString(),
-    checks, summary: { ready: requiredStatuses.length > 0 && requiredStatuses.every((s) => s === "pass" || s === "not-applicable"), required: requiredStatuses.length,
-      pass: requiredStatuses.filter((s) => s === "pass").length, fail: requiredStatuses.filter((s) => s === "fail").length, unknown: requiredStatuses.filter((s) => s === "unknown").length, byCapability, subjectBlockers },
-    notes: [
-      ...(verifySignatures ? [] : ["signatures are unknown until --verify-signatures (network fetch)"]),
-      "ready means every REQUIRED check passes; it is never inferred from an empty set",
-      "enrolment is workspace member admission, not native login or team registration",
-    ] };
-}
-
-function readMemberDocument(deploymentDir) {
-  if (!deploymentDir) return null;
-  const file = join(deploymentDir, "oats.yaml");
-  if (!existsSync(file)) return null;
-  try {
-    const doc = parseYamlNested(readFileSync(file, "utf8"));
-    // The lenient parser never throws: a `workspace:` that is present but not a
-    // mapping is a document we cannot read a membership from — unreadable, not absent.
-    if (doc.workspace !== undefined && (doc.workspace === null || typeof doc.workspace !== "object")) return { workspace: null, admitted: null, unreadable: true, file };
-    return { workspace: doc.workspace && typeof doc.workspace === "object" ? doc.workspace : null, admitted: null, exports: doc.exports ?? null };
-  } catch { return { workspace: null, admitted: null, unreadable: true, file }; }
-}
-
-/** Enforced policy for an instance (from its recorded metadata) or a soul
- *  (its declaration + default), with origins. Advisory/unknown stays unknown. */
-export function policyOf({ instanceMeta = null, soul = null } = {}) {
-  const child = instanceMeta?.policy?.childSpawns
-    ? { allowed: instanceMeta.policy.childSpawns.allowed === true, enforced: true, origin: instanceMeta.policy.childSpawns.origin ?? { kind: "recorded" } }
-    : instanceMeta ? { allowed: true, enforced: true, origin: { kind: "default", detail: "no recorded policy: children allowed (pre-0.24.8 instance)" } }
-    : soul?.declarations?.children && typeof soul.declarations.children.spawn === "boolean"
-      ? { allowed: soul.declarations.children.spawn, enforced: false, origin: { kind: "soul", detail: "children.spawn in soul.yaml; enforced once an instance records it" } }
-      : { allowed: true, enforced: false, origin: { kind: "default", detail: "no declaration: children allowed" } };
-  const worktree = instanceMeta ? { allowed: instanceMeta.work === "worktree" || instanceMeta.work === "checkout", mode: instanceMeta.work ?? null, enforced: true, origin: { kind: "work-mode", detail: `work: ${instanceMeta.work}` } }
-    : soul ? { allowed: ["worktree", "checkout"].includes(soul.work), mode: soul.work ?? null, enforced: false, origin: { kind: "soul", detail: `work: ${soul.work}` } } : { allowed: null, mode: null, enforced: false, origin: { kind: "unknown" } };
-  return { readinessApi: READINESS_API, policy: { childSpawns: child, worktrees: worktree }, notes: ["a lifecycle-authority claim enforced by the spawn route, not an OS sandbox"] };
-}

package/lib/repository-observation.mjs

@@ -1,226 +0,0 @@
-/** Exact, transaction-scoped repository observations. Bare Git reads never check
- * out or execute source content. Cache lifetime/auth context is one transaction. */
-import { execFileSync } from "node:child_process";
-import { lstatSync, mkdirSync, mkdtempSync, realpathSync, rmSync } from "node:fs";
-import { isAbsolute, join } from "node:path";
-import { canonicalJson, decodeUtf8, freezeJson, parseStrictJson } from "./portable-values.mjs";
-import { bytesIntegrity } from "./portable-digest.mjs";
-import { parseRepositorySource, portablePath, revisionSelector } from "./source-spec.mjs";
-import { sameIdentity, validateRepositoryIdentity } from "./portable-identity.mjs";
-import { validateOrigin } from "./resolution-shape.mjs";
-import { createSourceProjection, validateProjectionPath } from "./source-projection.mjs";
-export { validateProjectionPath } from "./source-projection.mjs";
-import { oatsError } from "./errors.mjs";
-
-function githubCoordinates(url) {
-  let host, path;
-  if (url.includes("://")) { const parsed = new URL(url); host = parsed.hostname; path = parsed.pathname.slice(1); }
-  else { const match = /^[^@]+@([^:]+):(.+)$/.exec(url); if (!match) return null; [, host, path] = match; }
-  if (host.toLowerCase() !== "github.com") return null;
-  const parts = path.replace(/\.git$/, "").split("/");
-  if (parts.length !== 2 || parts.some((part) => !/^[A-Za-z0-9_.-]+$/.test(part))) throw oatsError("source-identity-unresolved", "GitHub repository locator cannot be qualified");
-  return { host: "github.com", owner: parts[0], name: parts[1] };
-}
-
-/** Native host credentials only; no token extraction, copying or fallback after
- * a GitHub identity lookup fails. Unsupported hosts use explicit remote identity. */
-export function readHostingIdentity(repository, { environment = process.env, expectedIdentity } = {}) {
-  if (expectedIdentity?.kind === "canonical-remote") return { identity: { kind: "canonical-remote", remote: repository.normalized } };
-  const coordinates = githubCoordinates(repository.url);
-  if (!coordinates) return { identity: { kind: "canonical-remote", remote: repository.normalized } };
-  let metadata;
-  try {
-    const output = execFileSync("gh", ["api", "--hostname", coordinates.host, `repos/${coordinates.owner}/${coordinates.name}`,
-      "--jq", "{id, full_name, default_branch}"], { env: environment, timeout: 30_000, maxBuffer: 64 * 1024, stdio: ["ignore", "pipe", "pipe"] });
-    metadata = parseStrictJson(output);
-  } catch { throw oatsError("source-identity-unresolved", "repository hosting identity is unavailable in the selected access context"); }
-  if (!Number.isSafeInteger(metadata.id) || metadata.id < 1 || typeof metadata.full_name !== "string") throw oatsError("source-identity-unresolved", "hosting response lacks a stable repository identity");
-  if (metadata.full_name.toLowerCase() !== `${coordinates.owner}/${coordinates.name}`.toLowerCase()) throw oatsError("source-identity-change", "repository redirect or rename requires an explicit identity mapping");
-  revisionSelector(metadata.default_branch);
-  return { identity: { kind: "provider-repository", provider: "github", host: coordinates.host, id: String(metadata.id) }, defaultBranch: metadata.default_branch };
-}
-
-function gitEnvironment(environment) {
-  const out = { ...environment };
-  // Keep native credential/SSH facilities, but never an invoking repository's
-  // object/index/config injection. Host HOME/config credentials remain host-owned.
-  const retained = new Set(["GIT_ASKPASS", "GIT_SSH", "GIT_SSH_COMMAND", "GIT_SSH_VARIANT", "GIT_CONFIG_GLOBAL", "GIT_CONFIG_SYSTEM", "GIT_CONFIG_NOSYSTEM"]);
-  for (const key of Object.keys(out)) if (key.startsWith("GIT_") && !retained.has(key)) delete out[key];
-  out.GIT_TERMINAL_PROMPT = "0"; out.GIT_LITERAL_PATHSPECS = "1"; out.GIT_NO_REPLACE_OBJECTS = "1";
-  return out;
-}
-
-export function createRepositoryTransaction({ directory, accessContextKey, environment = process.env, identityReader = readHostingIdentity, allowLocalGit = false,
-  maxRepositories = 32, maxEntries = 10_000, maxBytes = 256 * 1024 * 1024 } = {}) {
-  if (typeof directory !== "string" || !isAbsolute(directory) || typeof accessContextKey !== "string" || !accessContextKey) throw oatsError("invalid-source", "repository observation requires an explicit scratch directory and access context");
-  canonicalJson(accessContextKey, { maxBytes: 8192 });
-  for (const value of [maxRepositories, maxEntries, maxBytes]) if (!Number.isSafeInteger(value) || value < 1) throw oatsError("resource-limit", "invalid repository observation budget");
-  const parent = realpathSync(directory);
-  if (!lstatSync(parent).isDirectory()) throw oatsError("invalid-source", "repository observation scratch root is not a directory");
-  const root = mkdtempSync(join(parent, ".repository-transaction-")), owned = lstatSync(root), hooks = join(root, "empty-hooks");
-  mkdirSync(hooks, { mode: 0o700 });
-  const env = gitEnvironment(environment), memo = new Map(), snapshots = new Map(), hosts = new Map(), defaults = new Map(), handles = new WeakMap(), blobs = new Map();
-  let closed = false, readBytes = 0, entriesRead = 0;
-  const active = () => { if (closed) throw oatsError("source-unavailable", "repository transaction is closed"); };
-  const git = (args, limit = 1024 * 1024) => {
-    active();
-    try { return execFileSync("git", ["-c", `core.hooksPath=${hooks}`, "-c", "protocol.ext.allow=never", "-c", `protocol.file.allow=${allowLocalGit ? "always" : "never"}`,
-      "-c", "http.followRedirects=false", ...args], { cwd: root, env, timeout: 60_000, maxBuffer: limit, stdio: ["ignore", "pipe", "pipe"] }); }
-    catch (error) { throw oatsError(error.code === "ENOBUFS" ? "resource-limit" : "source-unavailable", "repository read failed in the selected access context"); }
-  };
-  const hostFor = (repository, expectedIdentity) => {
-    if (!hosts.has(repository.normalized)) {
-      if (hosts.size >= maxRepositories * 4) throw oatsError("resource-limit", "repository identity count exceeded");
-      try {
-        const response = identityReader(repository, { environment: env, expectedIdentity });
-        validateRepositoryIdentity(response.identity);
-        if (response.defaultBranch !== undefined) revisionSelector(response.defaultBranch);
-        hosts.set(repository.normalized, { value: freezeJson({ identity: structuredClone(response.identity),
-          ...(response.defaultBranch === undefined ? {} : { defaultBranch: response.defaultBranch }) }) });
-      } catch (error) { hosts.set(repository.normalized, { error }); }
-    }
-    const hosted = hosts.get(repository.normalized);
-    if (hosted.error) throw hosted.error;
-    const host = hosted.value;
-    if (host.identity.kind === "canonical-remote" && host.identity.remote !== repository.normalized) throw oatsError("source-identity-change", "canonical repository identity differs from its source");
-    if (expectedIdentity && !sameIdentity(host.identity, expectedIdentity)) throw oatsError("source-identity-change", "repository hosting identity changed");
-    const identityKey = canonicalJson(host.identity);
-    if (host.defaultBranch !== undefined && !defaults.has(identityKey)) defaults.set(identityKey, { selector: host.defaultBranch });
-    return host;
-  };
-  const dataFor = (observation) => {
-    active(); const data = handles.get(observation);
-    if (!data) throw oatsError("invalid-source", "repository observation was not issued by this transaction");
-    return data;
-  };
-  const list = (data, paths, recursive) => {
-    const args = ["-C", data.directory, "ls-tree", "-z", "--full-tree", ...(recursive ? ["-r"] : []), data.commit];
-    if (!paths.includes(".")) args.push("--", ...paths);
-    const rows = decodeUtf8(git(args, 16 * 1024 * 1024)).split("\0").filter(Boolean);
-    if ((entriesRead += rows.length) > maxEntries) throw oatsError("resource-limit", "repository entry budget exceeded");
-    return rows.map((row) => {
-      const at = row.indexOf("\t"), header = /^([0-7]{6}) (blob|tree|commit) ([a-f0-9]{40})$/.exec(row.slice(0, at)), path = row.slice(at + 1);
-      if (!header || at < 0) throw oatsError("invalid-source", "repository returned a malformed tree entry");
-      portablePath(path);
-      if (path.split("/").some((part) => part.toLowerCase() === ".git")) throw oatsError("resource-not-contained", "source projection cannot include Git administrative files");
-      if (!paths.some((root) => root === "." || path === root || path.startsWith(`${root}/`))) throw oatsError("resource-not-contained", "repository returned an unselected source path");
-      return { mode: header[1], type: header[2], object: header[3], path };
-    });
-  };
-  const blob = (data, entry, limit) => {
-    if (entry.type !== "blob") throw oatsError("source-incomplete", "selected source contains an unsupported submodule or object kind");
-    const key = `${data.directory}:${entry.object}`;
-    if (!blobs.has(key)) {
-      const sizeText = decodeUtf8(git(["-C", data.directory, "cat-file", "-s", entry.object], 1024)).trim();
-      const size = Number(sizeText);
-      if (!/^[0-9]+$/.test(sizeText) || !Number.isSafeInteger(size) || size > limit || readBytes + size > maxBytes) throw oatsError("resource-limit", "repository content byte budget exceeded");
-      const bytes = git(["-C", data.directory, "cat-file", "blob", entry.object], size + 1024);
-      if (bytes.length !== size) throw oatsError("integrity-drift", "repository blob changed during reading");
-      readBytes += size; blobs.set(key, bytes);
-    }
-    const bytes = blobs.get(key);
-    if (bytes.length > limit) throw oatsError("resource-limit", "repository descriptor byte limit exceeded");
-    return Buffer.from(bytes);
-  };
-
-  return {
-    identify(source, { expectedIdentity } = {}) {
-      active();
-      if (expectedIdentity !== undefined) validateRepositoryIdentity(expectedIdentity);
-      const repository = parseRepositorySource(source), host = hostFor(repository, expectedIdentity);
-      return Object.freeze({ identity: host.identity, source: repository.normalized, accessContextKey });
-    },
-    observe(source, { revision, origin, expectedIdentity } = {}) {
-      active(); validateOrigin(origin);
-      if (expectedIdentity !== undefined) validateRepositoryIdentity(expectedIdentity);
-      // Local working snapshots use path: custody, not portable file: identities.
-      // allowLocalGit only enables an explicit host/test transport mapping.
-      const repository = parseRepositorySource(source);
-      if (revision !== undefined) revisionSelector(revision);
-      const key = canonicalJson({ source: repository.normalized, selector: revision ?? null });
-      if (!memo.has(key)) {
-        if (memo.size >= maxRepositories * 4) throw oatsError("resource-limit", "repository request count exceeded");
-        // Cache failures too: a single transaction never re-observes a moving
-        // request because its first attempt was inconvenient or inaccessible.
-        const slot = {}; memo.set(key, slot);
-        try {
-          const host = hostFor(repository, expectedIdentity), identityKey = canonicalJson(host.identity);
-          let selector = revision ?? defaults.get(identityKey)?.selector, exactHead = revision === undefined ? defaults.get(identityKey)?.exactHead : undefined;
-          if (selector === undefined) {
-            const head = decodeUtf8(git(["ls-remote", "--symref", "--", repository.url, "HEAD"], 64 * 1024));
-            const symbolic = /^ref: refs\/heads\/(.+)\tHEAD$/m.exec(head), resolved = /^([a-f0-9]{40})\tHEAD$/m.exec(head);
-            if (!symbolic || !resolved) throw oatsError("source-identity-unresolved", "repository default branch is unavailable");
-            selector = symbolic[1]; exactHead = resolved[1];
-            defaults.set(identityKey, { selector, exactHead });
-          }
-          revisionSelector(selector);
-          const snapshotKey = canonicalJson({ identity: host.identity, selector });
-          if (snapshots.has(snapshotKey)) {
-            const existing = snapshots.get(snapshotKey);
-            if (existing.error) throw existing.error;
-            slot.data = existing.data;
-          } else {
-            if (snapshots.size >= maxRepositories) throw oatsError("resource-limit", "repository snapshot count exceeded");
-            const directory = join(root, `repository-${snapshots.size}.git`);
-            snapshots.set(snapshotKey, slot);
-            // One selected shallow snapshot, not all repository branches/history.
-            // Servers may decline filtering; budgets below bound selected reads,
-            // not the transport's pack size. Git/host resource limits still apply.
-            git(["init", "--quiet", "--bare", directory]);
-            git(["-C", directory, "remote", "add", "origin", repository.url]);
-            git(["-C", directory, "fetch", "--quiet", "--depth=1", "--filter=blob:none", "--no-tags", "--", "origin", exactHead ?? selector], 4 * 1024 * 1024);
-            const commit = decodeUtf8(git(["-C", directory, "rev-parse", "--verify", "--quiet", "--end-of-options", "FETCH_HEAD^{commit}"], 1024)).trim();
-            if (exactHead && commit !== exactHead) throw oatsError("integrity-drift", "fetched default branch differs from its exact observation");
-            if (!/^[a-f0-9]{40}$/.test(commit)) throw oatsError("source-identity-unresolved", "repository selector did not resolve to an exact commit");
-            slot.data = { directory, identity: Object.freeze({ ...host.identity }), selector, commit };
-          }
-        } catch (error) { slot.error = error; throw error; }
-      }
-      const slot = memo.get(key);
-      if (slot.error) throw slot.error;
-      const data = { ...slot.data, remote: repository.normalized };
-      if (expectedIdentity && !sameIdentity(data.identity, expectedIdentity)) throw oatsError("source-identity-change", "cached repository identity differs from the request");
-      const observation = Object.freeze({ schemaVersion: 1, source: Object.freeze({ identity: data.identity, remote: data.remote,
-        selector: data.selector, commit: data.commit, provenance: freezeJson([structuredClone(origin)]) }), accessContextKey });
-      handles.set(observation, data);
-      return observation;
-    },
-    readFile(observation, path, { optional = false } = {}) {
-      portablePath(path); const data = dataFor(observation), rows = list(data, [path], false);
-      if (!rows.length && optional) return null;
-      if (rows.length !== 1 || rows[0].path !== path || !["100644", "100755"].includes(rows[0].mode)) throw oatsError("export-not-found", "repository descriptor is absent or is not a regular file");
-      const bytes = blob(data, rows[0], 1024 * 1024);
-      return { bytes, origin: { kind: "source", source: data.remote, revision: data.commit, path, integrity: bytesIntegrity(bytes) } };
-    },
-    materialize(observation, roots, destination) {
-      const data = dataFor(observation);
-      canonicalJson(roots);
-      if (!Array.isArray(roots) || !roots.length || roots.length > 1024 || new Set(roots).size !== roots.length) throw oatsError("invalid-source", "source projection needs a bounded unique root set");
-      roots.forEach((path) => portablePath(path, { allowRoot: true }));
-      if (typeof destination !== "string" || !isAbsolute(destination)) throw oatsError("invalid-source", "source projection destination must be explicit");
-      const rows = list(data, roots, true);
-      for (const path of roots) if (!rows.some((row) => path === "." || row.path === path || row.path.startsWith(`${path}/`))) throw oatsError("export-not-found", "required source projection root is absent");
-      for (const entry of rows) validateProjectionPath(entry.path);
-      const expected = new Map(rows.map((entry) => [entry.path, entry]));
-      if (expected.size !== rows.length) throw oatsError("invalid-source", "source tree has duplicate paths");
-      const projection = createSourceProjection(destination);
-      try {
-        for (const entry of rows) {
-          const bytes = blob(data, entry, maxBytes);
-          if (entry.mode === "120000") projection.link(entry.path, decodeUtf8(bytes, "source link target"));
-          else if (["100644", "100755"].includes(entry.mode)) projection.file(entry.path, bytes, entry.mode === "100755" ? 0o755 : 0o644);
-          else throw oatsError("source-incomplete", "source object mode cannot be retained");
-        }
-        projection.finish();
-        return { directory: destination, roots: [...roots], observation };
-      } catch (error) { error.stagingPath = destination; throw error; }
-    },
-    close() {
-      if (closed) return;
-      const current = lstatSync(root);
-      if (!current.isDirectory() || current.dev !== owned.dev || current.ino !== owned.ino) throw oatsError("source-unavailable", "repository transaction cleanup lost ownership");
-      closed = true;
-      rmSync(root, { recursive: true });
-    },
-  };
-}