spawnfile 0.1.13 → 0.1.17

package/dist/audit/checks.js

@@ -0,0 +1,279 @@
+// Not re-exported by src/ledger/index.js's barrel (see conformance.ts, which
+// also imports it directly from principal.js rather than through the
+// barrel); mirrored here for the same reason.
+import { isAuthenticatedPrincipal } from "../ledger/principal.js";
+import { CONTROL_TOKEN_ENV, DENIAL_MINIMUMS_BY_TYPE, escapeRegExp, FAIL_CLOSED_MARKER, literalAssignmentPattern, missingRequiredKeys, notApplicable, statusFor } from "./checksShared.js";
+/**
+ * Check 1 — `causal.principals-authenticated` (run). Grounded in
+ * `runRealConformance` reporting zero issues over the ledger jsonl, and in
+ * `isAuthenticatedPrincipal` (src/ledger/principal.ts:87) rejecting a bare,
+ * literal-`anonymous`, or `system:moltnet.anonymous` principal
+ * (principal.ts:45,93). Fails on either a nonempty `issues` list (any
+ * schema/seq/payload/principal/chain problem `runRealConformance` found) or
+ * an event whose `principal_id` is not authenticated — evidence names the
+ * offending event and principal directly rather than relying on issue-
+ * message string matching.
+ */
+export const checkPrincipalsAuthenticated = (evidence) => {
+    const id = "causal.principals-authenticated";
+    const category = "causal";
+    const severity = "critical";
+    if (!evidence) {
+        return notApplicable(id, category, severity, "no run artifacts provided");
+    }
+    const offendingPrincipals = evidence.events
+        .filter((event) => !isAuthenticatedPrincipal(event.principal_id))
+        .map((event) => ({ event_id: event.event_id, principal_id: event.principal_id }));
+    return {
+        category,
+        evidence: {
+            eventCount: evidence.eventCount,
+            issueCount: evidence.issues.length,
+            offendingPrincipals,
+            sources: evidence.sources
+        },
+        id,
+        severity,
+        status: statusFor(evidence.issues.length === 0 && offendingPrincipals.length === 0)
+    };
+};
+/**
+ * Check 2 — `causal.denied-ledger-visible` (run). Grounded in
+ * `DEFAULT_PAYLOAD_MINIMUMS` (conformance.ts:67-69) for every `*.denied`
+ * type: any such event that appears must carry its required keys. Also
+ * detects a silent drop — this fixture's `expected-denials.json` asserted a
+ * denial type occurred, but no matching `*.denied` event exists in the
+ * ledger — which fails even when every event that *is* present is well
+ * shaped.
+ *
+ * `not_applicable`, never `pass`, when there is no `expected-denials.json`
+ * manifest AND zero `*.denied` events are present in the ledger — with
+ * neither an assertion to check against nor an event to inspect, there is
+ * nothing here to actually assess (see AGENTS.md's cardinal rule: absent
+ * evidence is `not_applicable`, never `pass`). A manifest being present is
+ * enough to keep evaluating (silent-drop detection needs no observed event
+ * to fire), and any `*.denied` event that *is* present is always
+ * key-validated regardless of manifest presence.
+ */
+export const checkDeniedLedgerVisible = (evidence) => {
+    const id = "causal.denied-ledger-visible";
+    const category = "causal";
+    const severity = "high";
+    if (!evidence) {
+        return notApplicable(id, category, severity, "no run artifacts provided");
+    }
+    const presentDenials = evidence.events.filter((event) => DENIAL_MINIMUMS_BY_TYPE.has(event.type));
+    if (!evidence.manifestPresent && presentDenials.length === 0) {
+        return notApplicable(id, category, severity, "no denial events and no expected-denials manifest; cannot assess silent-drop");
+    }
+    const malformed = presentDenials
+        .map((event) => ({
+        event_id: event.event_id,
+        /* v8 ignore next -- presentDenials already filtered by DENIAL_MINIMUMS_BY_TYPE.has(event.type), so .get() always hits; defensive fallback only */
+        missingKeys: missingRequiredKeys(event, DENIAL_MINIMUMS_BY_TYPE.get(event.type) ?? []),
+        type: event.type
+    }))
+        .filter((entry) => entry.missingKeys.length > 0);
+    const presentTypes = new Set(presentDenials.map((event) => event.type));
+    const silentlyDropped = evidence.expectedDenialTypes.filter((type) => !presentTypes.has(type));
+    return {
+        category,
+        evidence: {
+            deniedEventCount: presentDenials.length,
+            expectedDenialTypes: evidence.expectedDenialTypes,
+            malformed,
+            silentlyDropped
+        },
+        id,
+        severity,
+        status: statusFor(malformed.length === 0 && silentlyDropped.length === 0)
+    };
+};
+/**
+ * Check 3 — `control.wake-fail-closed` (static). Grounded in
+ * appControlSource.ts:31-47 (B62 Option B): the operator wake endpoint must
+ * fail closed when `SPAWNFILE_PI_CONTROL_TOKEN` is unset, never treat an
+ * unset token as "auth disabled". Passes only when the compiled Pi app
+ * source references the token env, contains the verbatim fail-closed
+ * rejection text, and never bakes a literal default value for it.
+ */
+export const checkControlWakeFailClosed = (evidence) => {
+    const combined = `${evidence.dockerfile}\n${evidence.entrypoint}\n${evidence.piAppSource}`;
+    const tokenReferenced = combined.includes(CONTROL_TOKEN_ENV);
+    const failClosedMarkerFound = evidence.piAppSource.includes(FAIL_CLOSED_MARKER);
+    const bakedDefaultFound = literalAssignmentPattern(CONTROL_TOKEN_ENV).test(combined);
+    return {
+        category: "control",
+        evidence: {
+            bakedDefaultFound,
+            envSourceList: [CONTROL_TOKEN_ENV],
+            failClosedMarkerFound,
+            tokenReferenced
+        },
+        id: "control.wake-fail-closed",
+        severity: "critical",
+        status: statusFor(tokenReferenced && failClosedMarkerFound && !bakedDefaultFound)
+    };
+};
+/**
+ * Check 4 — `container.no-baked-secrets` (static). Grounded in
+ * containerEntrypointRender.ts:232-233: every required secret is emitted as
+ * a `require_env <name>` runtime check, never a literal value baked into the
+ * Dockerfile build layer or the entrypoint script. Passes only when every
+ * `requiredSecrets` name is `require_env`-guarded in the entrypoint AND no
+ * name is ever followed by a literal (non-`$`) assignment anywhere in the
+ * compiled Dockerfile/entrypoint text.
+ */
+export const checkContainerNoBakedSecrets = (evidence) => {
+    const combined = `${evidence.dockerfile}\n${evidence.entrypoint}`;
+    const missingRequireEnv = evidence.requiredSecrets.filter((name) => !new RegExp(`require_env\\s+['"]${escapeRegExp(name)}['"]`, "u").test(evidence.entrypoint));
+    const bakedLiteralValues = evidence.requiredSecrets.filter((name) => literalAssignmentPattern(name).test(combined));
+    return {
+        category: "container",
+        evidence: {
+            bakedLiteralValues,
+            missingRequireEnv,
+            requiredSecrets: evidence.requiredSecrets
+        },
+        id: "container.no-baked-secrets",
+        severity: "critical",
+        status: statusFor(missingRequireEnv.length === 0 && bakedLiteralValues.length === 0)
+    };
+};
+/**
+ * Check 5 — `memory.cross-scope-capability` (run). Grounded in mneme's
+ * `mneme.cap.system.v1` foreign-scope escalation capability
+ * (ecosystem/mneme/src/policy/capability.ts:28) and the
+ * `memory.write.denied` payload minimum (conformance.ts:68:
+ * `requested_scope`, `reason`). `mneme.cap.system.v1` is carried as an
+ * informational `grounding` string only — this function performs no static
+ * check against mneme's source, so the status is never driven by that
+ * literal.
+ *
+ * `not_applicable`, never `pass`, when no `memory.write.denied` event is
+ * present in the ledger: enforcement was never exercised in this run, and
+ * "nothing to violate" is not evidence the capability guard works (see
+ * AGENTS.md). When one or more denial events are present, every one must
+ * carry both `requested_scope` and `reason` to pass.
+ */
+export const checkMemoryCrossScopeCapability = (evidence) => {
+    const id = "memory.cross-scope-capability";
+    const category = "memory";
+    const severity = "high";
+    if (!evidence) {
+        return notApplicable(id, category, severity, "no run artifacts provided");
+    }
+    const denials = evidence.events.filter((event) => event.type === "memory.write.denied");
+    if (denials.length === 0) {
+        return {
+            category,
+            evidence: {
+                deniedEventCount: 0,
+                reason: "no memory.write.denied events observed; cross-scope enforcement was not exercised in this run"
+            },
+            id,
+            severity,
+            status: "not_applicable"
+        };
+    }
+    /* v8 ignore next -- "memory.write.denied" is always in DEFAULT_PAYLOAD_MINIMUMS (conformance.ts:68); defensive fallback only */
+    const requiredKeys = DENIAL_MINIMUMS_BY_TYPE.get("memory.write.denied") ?? [];
+    const malformed = denials
+        .map((event) => ({
+        event_id: event.event_id,
+        missingKeys: missingRequiredKeys(event, requiredKeys),
+        requested_scope: event.payload.requested_scope,
+        reason: event.payload.reason
+    }))
+        .filter((entry) => entry.missingKeys.length > 0);
+    return {
+        category,
+        evidence: {
+            deniedEventCount: denials.length,
+            grounding: "mneme.cap.system.v1",
+            malformed
+        },
+        id,
+        severity,
+        status: statusFor(malformed.length === 0)
+    };
+};
+/**
+ * Check 6 — `network.non-member-write-denied` (run). Grounded in moltnet's
+ * `writeForbiddenError` (ecosystem/moltnet/internal/rooms/access_policy.go:23,71-72)
+ * and the `message.denied` payload minimum (conformance.ts:67: `target`,
+ * `reason`, `content_sha256`). The `writeForbiddenError` path is carried as
+ * an informational `grounding` string only — this function performs no
+ * static check against moltnet's source, so the status is never driven by
+ * that literal.
+ *
+ * `not_applicable`, never `pass`, when no `message.denied` event is present:
+ * non-member-write enforcement was never exercised in this run, which is not
+ * evidence it works (see AGENTS.md). When one or more denial events are
+ * present, every one must carry `target`, `reason`, and `content_sha256` to
+ * pass.
+ */
+export const checkNonMemberWriteDenied = (evidence) => {
+    const id = "network.non-member-write-denied";
+    const category = "network";
+    const severity = "high";
+    if (!evidence) {
+        return notApplicable(id, category, severity, "no run artifacts provided");
+    }
+    const denials = evidence.events.filter((event) => event.type === "message.denied");
+    if (denials.length === 0) {
+        return {
+            category,
+            evidence: {
+                deniedEventCount: 0,
+                reason: "no message.denied events observed; non-member write enforcement was not exercised in this run"
+            },
+            id,
+            severity,
+            status: "not_applicable"
+        };
+    }
+    /* v8 ignore next -- "message.denied" is always in DEFAULT_PAYLOAD_MINIMUMS (conformance.ts:67); defensive fallback only */
+    const requiredKeys = DENIAL_MINIMUMS_BY_TYPE.get("message.denied") ?? [];
+    const malformed = denials
+        .map((event) => ({
+        event_id: event.event_id,
+        missingKeys: missingRequiredKeys(event, requiredKeys),
+        target: event.payload.target,
+        reason: event.payload.reason
+    }))
+        .filter((entry) => entry.missingKeys.length > 0);
+    return {
+        category,
+        evidence: {
+            deniedEventCount: denials.length,
+            grounding: "ecosystem/moltnet/internal/rooms/access_policy.go writeForbiddenError",
+            malformed
+        },
+        id,
+        severity,
+        status: statusFor(malformed.length === 0)
+    };
+};
+/**
+ * Check 7 — `provenance.signed-report` — always `not_applicable`. Report
+ * signing/provenance is deferred to B66; this audit generator has no
+ * signing input to check and must never claim it. Takes no evidence input
+ * on purpose: there is nothing yet for it to inspect.
+ */
+export const checkProvenanceSignedReport = () => notApplicable("provenance.signed-report", "provenance", "medium", "not yet enforced (see B66)");
+/**
+ * The seven check ids in the order `generateAudit.ts` assembles
+ * `AuditReport.checks` in (each check function above takes a different
+ * evidence shape, so this is a documentation/ordering list only — not a
+ * uniformly-callable array).
+ */
+export const AUDIT_CHECK_IDS = [
+    "causal.principals-authenticated",
+    "causal.denied-ledger-visible",
+    "control.wake-fail-closed",
+    "container.no-baked-secrets",
+    "memory.cross-scope-capability",
+    "network.non-member-write-denied",
+    "provenance.signed-report"
+];

package/dist/audit/checksShared.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Evidence input types and small pure helpers shared by every check function
+ * in checks.ts. Split out purely to keep checks.ts under the repo's 400-line
+ * cap (see the repo CLAUDE.md) — nothing here is
+ * a different layer or a different contract, it is checks.ts's own
+ * plumbing. No I/O, same as checks.ts itself.
+ */
+import type { CausalEvent, ConformanceIssue } from "../ledger/index.js";
+import type { AuditCheck, AuditCheckCategory, AuditCheckSeverity, AuditCheckStatus } from "./types.js";
+/**
+ * Ledger evidence handed to every run-mode check (1, 2, 5, 6). Built once by
+ * `generateAudit.ts` from `runRealConformance` (offline-mode: an injected
+ * `exec` that reads fixture files instead of spawning a sibling process —
+ * see generateAudit.ts) plus the audit's own `expected-denials.json`
+ * manifest. `undefined` means "no run artifacts provided" — every run-mode
+ * check below returns `not_applicable` in that case, and never `pass`.
+ */
+export interface RunLedgerEvidence {
+    eventCount: number;
+    events: CausalEvent[];
+    /** Denial types this fixture's `expected-denials.json` asserts a `*.denied` event must exist for (silent-drop detection, check 2). */
+    expectedDenialTypes: string[];
+    /** Every schema/seq/payload-minimum/principal-grammar/chain-stitch issue `runRealConformance` reported — reused, never recomputed. */
+    issues: ConformanceIssue[];
+    /** Whether the ledger directory actually contained an `expected-denials.json` file — distinct from `expectedDenialTypes.length === 0`, which is also true for a *present-but-empty* manifest. Check 2 uses this to tell "no manifest, so silent-drop cannot be assessed" apart from "a manifest exists and asserts nothing". */
+    manifestPresent: boolean;
+    sources: string[];
+}
+/**
+ * Compiled-output evidence handed to every static check (3, 4). Plain
+ * strings, not paths — `generateAudit.ts` owns the file reads, these
+ * functions stay pure. Any file that does not exist in the compiled output
+ * directory reads as an empty string; that is itself audit-worthy (absence
+ * of proof is not proof of enforcement), never treated as not_applicable —
+ * unlike run-mode checks, the compiled-output directory is a required
+ * `generateAudit` input, never optional.
+ */
+export interface StaticContainerEvidence {
+    /** Rendered Dockerfile text (containerArtifactsRender.ts's `renderDockerfile` output shape). */
+    dockerfile: string;
+    /** Rendered entrypoint.sh text (containerEntrypointRender.ts's `renderEntrypoint` output shape). */
+    entrypoint: string;
+    /** Rendered generated Pi app source, if this compile targeted Pi (appControlSource.ts's `renderPiControlSource` output is inlined into it). Empty string if the compiled output has no such file. */
+    piAppSource: string;
+    /** Secret env var NAMES this compile declared required (containerEntrypointRender.ts's `renderEntrypoint(runtimePlans, requiredSecrets, ...)` second argument) — never the values. */
+    requiredSecrets: string[];
+}
+export declare const notApplicable: (id: string, category: AuditCheckCategory, severity: AuditCheckSeverity, reason: string) => AuditCheck;
+export declare const statusFor: (ok: boolean) => AuditCheckStatus;
+/** `conformance.ts`'s `checkPayloadMinimums` is not exported (it is that module's private helper); this is the same one-line key-presence rule applied directly to already-parsed events, not a reimplementation of `validateConformanceSources`'s schema/seq/stitch pipeline. */
+export declare const missingRequiredKeys: (event: CausalEvent, requiredKeys: string[]) => string[];
+export declare const DENIAL_MINIMUMS_BY_TYPE: Map<string, string[]>;
+/** Env name gating the operator-only wake endpoint (appControlSource.ts:45, `CONTROL_TOKEN_ENV`). */
+export declare const CONTROL_TOKEN_ENV = "SPAWNFILE_PI_CONTROL_TOKEN";
+/**
+ * Verbatim source-text substring of appControlSource.ts:75's fail-closed
+ * rejection branch (`return { ok: false, reason: "no operator token
+ * configured (" + CONTROL_TOKEN_ENV + " is unset)" }`). The literal string
+ * checked here is only the first concatenated chunk — the source
+ * concatenates `CONTROL_TOKEN_ENV` in with `+`, so the fully-assembled
+ * runtime message never appears as one literal in the source text itself.
+ * Its presence is direct evidence the fail-closed branch was actually
+ * emitted, not paraphrased.
+ */
+export declare const FAIL_CLOSED_MARKER = "no operator token configured (";
+export declare const escapeRegExp: (value: string) => string;
+/**
+ * Matches a literal (non-`$`-expansion) shell/Dockerfile assignment
+ * `NAME=<value>` — never a `require_env 'NAME'` call (no `=` follows the
+ * name there at all) and never a same-name passthrough reference like
+ * `NAME="$NAME"`/`NAME=${NAME}` (an optional quote followed by `$`), both of
+ * which read the env rather than bake a value into it.
+ */
+export declare const literalAssignmentPattern: (name: string) => RegExp;

package/dist/audit/checksShared.js

@@ -0,0 +1,37 @@
+import { DEFAULT_PAYLOAD_MINIMUMS } from "../ledger/index.js";
+export const notApplicable = (id, category, severity, reason) => ({
+    category,
+    evidence: { reason },
+    id,
+    severity,
+    status: "not_applicable"
+});
+export const statusFor = (ok) => (ok ? "pass" : "fail");
+/** `conformance.ts`'s `checkPayloadMinimums` is not exported (it is that module's private helper); this is the same one-line key-presence rule applied directly to already-parsed events, not a reimplementation of `validateConformanceSources`'s schema/seq/stitch pipeline. */
+export const missingRequiredKeys = (event, requiredKeys) => requiredKeys.filter((key) => !(key in event.payload) || event.payload[key] === undefined);
+export const DENIAL_MINIMUMS_BY_TYPE = new Map(DEFAULT_PAYLOAD_MINIMUMS.filter((minimum) => minimum.type.endsWith(".denied")).map((minimum) => [
+    minimum.type,
+    minimum.requiredKeys
+]));
+/** Env name gating the operator-only wake endpoint (appControlSource.ts:45, `CONTROL_TOKEN_ENV`). */
+export const CONTROL_TOKEN_ENV = "SPAWNFILE_PI_CONTROL_TOKEN";
+/**
+ * Verbatim source-text substring of appControlSource.ts:75's fail-closed
+ * rejection branch (`return { ok: false, reason: "no operator token
+ * configured (" + CONTROL_TOKEN_ENV + " is unset)" }`). The literal string
+ * checked here is only the first concatenated chunk — the source
+ * concatenates `CONTROL_TOKEN_ENV` in with `+`, so the fully-assembled
+ * runtime message never appears as one literal in the source text itself.
+ * Its presence is direct evidence the fail-closed branch was actually
+ * emitted, not paraphrased.
+ */
+export const FAIL_CLOSED_MARKER = "no operator token configured (";
+export const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+/**
+ * Matches a literal (non-`$`-expansion) shell/Dockerfile assignment
+ * `NAME=<value>` — never a `require_env 'NAME'` call (no `=` follows the
+ * name there at all) and never a same-name passthrough reference like
+ * `NAME="$NAME"`/`NAME=${NAME}` (an optional quote followed by `$`), both of
+ * which read the env rather than bake a value into it.
+ */
+export const literalAssignmentPattern = (name) => new RegExp(`\\b${escapeRegExp(name)}=(?!['"]?\\$)\\S`, "u");

package/dist/audit/generateAudit.d.ts

@@ -0,0 +1,19 @@
+import type { AuditReport } from "./types.js";
+export interface GenerateAuditOptions {
+    /** Required. The compiled-output directory (`spawnfile compile`'s emitted `Dockerfile`, `entrypoint.sh`, and — for a Pi-targeted compile — `runtime/app.mjs`). Static checks 3-4 always evaluate pass/fail against whatever is (or is not) present here; a missing file reads as an empty string, never a silent skip. */
+    compiledOutputDirPath: string;
+    /** Optional. A directory of `*.jsonl` ledger fixture files plus an optional `expected-denials.json` manifest (see checks.ts's `RunLedgerEvidence`). Omitting it (or an empty directory) is what makes run-mode checks 1, 2, 5, 6 report `not_applicable` — they never `pass` without it. */
+    ledgerDirPath?: string;
+    /** Injectable clock for `generated_at`, defaulting to `() => new Date()`. Every other report field is deterministic given the same inputs. */
+    now?: () => Date;
+    /** Secret env var NAMES this compile declared required (`requiredSecrets` passed to `renderEntrypoint`). Defaults to `[]`. */
+    requiredSecrets?: string[];
+}
+/**
+ * Orchestrator: the only I/O-performing function in src/audit/. Reads the
+ * compiled-output directory and, if given, the ledger directory, then runs
+ * the seven pure checks (checks.ts) and assembles the `AuditReport`.
+ * Deterministic across repeated calls with the same inputs except for
+ * `generated_at`.
+ */
+export declare const generateAudit: (options: GenerateAuditOptions) => Promise<AuditReport>;

package/dist/audit/generateAudit.js

@@ -0,0 +1,122 @@
+import { readdir } from "node:fs/promises";
+import path from "node:path";
+import { fileExists, readUtf8File } from "../filesystem/index.js";
+import { runRealConformance } from "../ledger/index.js";
+import { checkContainerNoBakedSecrets, checkControlWakeFailClosed, checkDeniedLedgerVisible, checkMemoryCrossScopeCapability, checkNonMemberWriteDenied, checkPrincipalsAuthenticated, checkProvenanceSignedReport } from "./checks.js";
+import { SPAWNFILE_AUDIT_SCHEMA } from "./types.js";
+const readOptionalFile = async (filePath) => (await fileExists(filePath)) ? readUtf8File(filePath) : "";
+const readExpectedDenials = async (ledgerDirPath) => {
+    const manifestPath = path.join(ledgerDirPath, "expected-denials.json");
+    if (!(await fileExists(manifestPath))) {
+        return { expectedDenialTypes: [], manifestPresent: false };
+    }
+    const raw = await readUtf8File(manifestPath);
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed.expectedDenialTypes)) {
+        return { expectedDenialTypes: [], manifestPresent: true };
+    }
+    return {
+        expectedDenialTypes: parsed.expectedDenialTypes.filter((value) => typeof value === "string"),
+        manifestPresent: true
+    };
+};
+/**
+ * Reads every `*.jsonl` file in `ledgerDirPath` and feeds it to
+ * `runRealConformance` (src/ledger/conformance.ts) through an injected
+ * `exec` that returns each file's pre-read text instead of spawning a real
+ * sibling emitter process. This is what keeps the whole B54 generator
+ * offline while still reusing `runRealConformance`'s real schema/seq/
+ * payload-minimum/principal-grammar/chain-stitch pipeline rather than
+ * reimplementing any of it — see src/ledger/emitters.ts for the `Exec`/
+ * `EmitterSpec` contract this fills in. Returns `undefined` (never an empty
+ * evidence object) when the directory has no `*.jsonl` files, so callers can
+ * distinguish "no run artifacts" from "ledger with zero events".
+ */
+const collectRunLedgerEvidence = async (ledgerDirPath) => {
+    const entries = await readdir(ledgerDirPath, { withFileTypes: true }).catch(() => []);
+    const jsonlFileNames = entries
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".jsonl"))
+        .map((entry) => entry.name)
+        .sort((left, right) => left.localeCompare(right));
+    if (jsonlFileNames.length === 0) {
+        return undefined;
+    }
+    const contentByFileName = new Map();
+    for (const fileName of jsonlFileNames) {
+        contentByFileName.set(fileName, await readUtf8File(path.join(ledgerDirPath, fileName)));
+    }
+    const specs = jsonlFileNames.map((fileName) => ({
+        command: [fileName],
+        cwd: ledgerDirPath,
+        name: fileName.replace(/\.jsonl$/u, ""),
+        output: "stdout-jsonl"
+    }));
+    // Offline exec: returns the pre-read fixture text for the named source,
+    // never spawns a process. Matches src/ledger/emitters.ts's `Exec` contract.
+    const exec = (spec) => Promise.resolve({
+        exitCode: 0,
+        stderr: "",
+        stdout: contentByFileName.get(`${spec.name}.jsonl`) ?? "",
+        timedOut: false
+    });
+    const report = await runRealConformance({ exec, specs });
+    const { expectedDenialTypes, manifestPresent } = await readExpectedDenials(ledgerDirPath);
+    return {
+        eventCount: report.eventCount,
+        events: report.events,
+        expectedDenialTypes,
+        issues: report.issues,
+        manifestPresent,
+        sources: report.sourceCounts.map((entry) => entry.source)
+    };
+};
+const collectStaticEvidence = async (compiledOutputDirPath, requiredSecrets) => ({
+    dockerfile: await readOptionalFile(path.join(compiledOutputDirPath, "Dockerfile")),
+    entrypoint: await readOptionalFile(path.join(compiledOutputDirPath, "entrypoint.sh")),
+    piAppSource: await readOptionalFile(path.join(compiledOutputDirPath, "runtime", "app.mjs")),
+    requiredSecrets
+});
+const summarize = (checks) => ({
+    failed: checks.filter((check) => check.status === "fail").length,
+    na: checks.filter((check) => check.status === "not_applicable").length,
+    passed: checks.filter((check) => check.status === "pass").length
+});
+/** `null` unless every ledger event shares one `run_id` (see specs/CAUSAL.md — a single audit always covers one run). */
+const resolveRunId = (events) => {
+    if (events.length === 0) {
+        return null;
+    }
+    const runIds = new Set(events.map((event) => event.run_id));
+    return runIds.size === 1 ? runIds.values().next().value : null;
+};
+/**
+ * Orchestrator: the only I/O-performing function in src/audit/. Reads the
+ * compiled-output directory and, if given, the ledger directory, then runs
+ * the seven pure checks (checks.ts) and assembles the `AuditReport`.
+ * Deterministic across repeated calls with the same inputs except for
+ * `generated_at`.
+ */
+export const generateAudit = async (options) => {
+    const now = options.now ?? (() => new Date());
+    const requiredSecrets = options.requiredSecrets ?? [];
+    const [ledgerEvidence, staticEvidence] = await Promise.all([
+        options.ledgerDirPath ? collectRunLedgerEvidence(options.ledgerDirPath) : Promise.resolve(undefined),
+        collectStaticEvidence(options.compiledOutputDirPath, requiredSecrets)
+    ]);
+    const checks = [
+        checkPrincipalsAuthenticated(ledgerEvidence),
+        checkDeniedLedgerVisible(ledgerEvidence),
+        checkControlWakeFailClosed(staticEvidence),
+        checkContainerNoBakedSecrets(staticEvidence),
+        checkMemoryCrossScopeCapability(ledgerEvidence),
+        checkNonMemberWriteDenied(ledgerEvidence),
+        checkProvenanceSignedReport()
+    ];
+    return {
+        checks,
+        generated_at: now().toISOString(),
+        run_id: ledgerEvidence ? resolveRunId(ledgerEvidence.events) : null,
+        schema: SPAWNFILE_AUDIT_SCHEMA,
+        summary: summarize(checks)
+    };
+};

package/dist/audit/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./checks.js";
+export * from "./generateAudit.js";
+export * from "./readAudit.js";
+export * from "./types.js";

package/dist/audit/index.js

@@ -0,0 +1,4 @@
+export * from "./checks.js";
+export * from "./generateAudit.js";
+export * from "./readAudit.js";
+export * from "./types.js";

package/dist/audit/readAudit.d.ts

@@ -0,0 +1,50 @@
+import { z } from "zod";
+import type { AuditReport } from "./types.js";
+export declare const auditReportSchema: z.ZodObject<{
+    checks: z.ZodArray<z.ZodObject<{
+        category: z.ZodEnum<{
+            provenance: "provenance";
+            causal: "causal";
+            container: "container";
+            control: "control";
+            memory: "memory";
+            network: "network";
+        }>;
+        evidence: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        id: z.ZodString;
+        severity: z.ZodEnum<{
+            critical: "critical";
+            high: "high";
+            medium: "medium";
+        }>;
+        status: z.ZodEnum<{
+            pass: "pass";
+            fail: "fail";
+            not_applicable: "not_applicable";
+        }>;
+    }, z.core.$strict>>;
+    generated_at: z.ZodString;
+    run_id: z.ZodNullable<z.ZodString>;
+    schema: z.ZodLiteral<"spawnfile.audit.v1">;
+    summary: z.ZodObject<{
+        failed: z.ZodNumber;
+        na: z.ZodNumber;
+        passed: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export interface AuditReadError {
+    message: string;
+}
+/**
+ * Safe (non-throwing) validator. Rejects an unknown `schema` string as a
+ * top-level structural mismatch — `z.literal` already fails it — rather
+ * than accepting any string and comparing separately, so a caller cannot
+ * bypass the schema gate with a structurally-valid-but-wrong-version report.
+ */
+export declare const validateAuditReport: (value: unknown) => {
+    report: AuditReport;
+} | {
+    error: AuditReadError;
+};
+/** Throwing counterpart of `validateAuditReport`, mirroring `envelope.ts`'s `parseCausalEvent`. */
+export declare const readAuditReport: (value: unknown) => AuditReport;

package/dist/audit/readAudit.js

@@ -0,0 +1,59 @@
+import { z } from "zod";
+import { SPAWNFILE_AUDIT_SCHEMA } from "./types.js";
+/**
+ * Pure reader/validator for an existing `spawnfile.audit.v1` report — the
+ * `envelope.ts` precedent (a zod schema mirroring the hand-written
+ * `AuditReport` interface, plus a `parse*`/`validate*` pair). No I/O:
+ * callers pass already-read JSON (typically `JSON.parse`d from a file
+ * `generateAudit.ts` wrote), this module only checks shape.
+ */
+const auditCheckSchema = z
+    .object({
+    category: z.enum(["causal", "container", "control", "memory", "network", "provenance"]),
+    evidence: z.record(z.string(), z.unknown()),
+    id: z.string().min(1),
+    severity: z.enum(["critical", "high", "medium"]),
+    status: z.enum(["pass", "fail", "not_applicable"])
+})
+    .strict();
+const auditSummarySchema = z
+    .object({
+    failed: z.number().int().min(0),
+    na: z.number().int().min(0),
+    passed: z.number().int().min(0)
+})
+    .strict();
+export const auditReportSchema = z
+    .object({
+    checks: z.array(auditCheckSchema),
+    generated_at: z.string().min(1),
+    run_id: z.string().min(1).nullable(),
+    schema: z.literal(SPAWNFILE_AUDIT_SCHEMA),
+    summary: auditSummarySchema
+})
+    .strict();
+/**
+ * Safe (non-throwing) validator. Rejects an unknown `schema` string as a
+ * top-level structural mismatch — `z.literal` already fails it — rather
+ * than accepting any string and comparing separately, so a caller cannot
+ * bypass the schema gate with a structurally-valid-but-wrong-version report.
+ */
+export const validateAuditReport = (value) => {
+    const result = auditReportSchema.safeParse(value);
+    if (!result.success) {
+        return {
+            error: {
+                message: result.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ")
+            }
+        };
+    }
+    return { report: result.data };
+};
+/** Throwing counterpart of `validateAuditReport`, mirroring `envelope.ts`'s `parseCausalEvent`. */
+export const readAuditReport = (value) => {
+    const result = validateAuditReport(value);
+    if ("error" in result) {
+        throw new Error(`invalid spawnfile.audit.v1 report: ${result.error.message}`);
+    }
+    return result.report;
+};