spawnfile 0.1.12 → 0.1.14

package/dist/ledger/conformance.js

@@ -0,0 +1,259 @@
+import { checkSeqContiguity, parseCausalJsonl, reconcileEvents, traceCausesBackward } from "@noopolis/stele";
+import { checkCauseNamespaces } from "./causeNamespace.js";
+import { collectEmitterFixtures, EMITTER_RUN_ID, EMITTER_SPECS, realExec } from "./emitters.js";
+import { PRINCIPAL_DISCIPLINE_CHECKS } from "./principal.js";
+/**
+ * Shared payload minimum for every world.act variant (specs/CAUSAL.md, the
+ * simfile runtime AGENTS.md). The wire never carries the literal type
+ * `world.act` — simfile emits the family members `world.message`,
+ * `world.dm`, and `wake.recommended` — but `world.act` is kept as its own
+ * declared type key so a hypothetical direct `world.act` record is still
+ * enforced, and so tests can assert the minimum by its family name.
+ */
+const WORLD_ACT_REQUIRED_KEYS = ["sim_time", "provenance", "actor", "target", "scope", "act_id", "action", "value"];
+/**
+ * Payload minimums for the event types named in specs/CAUSAL.md and the B57/
+ * B92 family packets. `runSyntheticConformance` validates seeded fixture
+ * text against these; `runRealConformance` (B92) validates the four real
+ * sibling emitters' output against the same minimums.
+ */
+export const DEFAULT_PAYLOAD_MINIMUMS = [
+    { requiredKeys: ["message_id", "content_sha256"], type: "message.accepted" },
+    {
+        requiredKeys: ["turn_id", "input_message_ids", "input_content_sha256", "prompt_sha256"],
+        type: "turn.input.submitted"
+    },
+    { requiredKeys: ["turn_id", "output_sha256"], type: "turn.output.completed" },
+    { requiredKeys: ["memory_id", "content_sha256"], type: "memory.recalled" },
+    { requiredKeys: WORLD_ACT_REQUIRED_KEYS, type: "world.act" },
+    { requiredKeys: WORLD_ACT_REQUIRED_KEYS, type: "world.message" },
+    { requiredKeys: WORLD_ACT_REQUIRED_KEYS, type: "world.dm" },
+    { requiredKeys: WORLD_ACT_REQUIRED_KEYS, type: "wake.recommended" },
+    // B62 enforcement-point denial payloads (specs/CAUSAL.md §"Enforcement
+    // points"). Field names mirror each authority's real emitted shape:
+    // moltnet's protocol.MessageDeniedPayload (target/reason/content_sha256),
+    // mneme's kernel/support.ts denyWriteScope (requested_scope/reason), and
+    // daimon's controlCausal.ts emitControlWakeDenied (reason/target_agent_id).
+    { requiredKeys: ["target", "reason", "content_sha256"], type: "message.denied" },
+    { requiredKeys: ["requested_scope", "reason"], type: "memory.write.denied" },
+    { requiredKeys: ["reason", "target_agent_id"], type: "control.wake.denied" }
+];
+const checkPayloadMinimums = (event, sourceName, requiredKeysByType) => {
+    const requiredKeys = requiredKeysByType.get(event.type);
+    if (!requiredKeys) {
+        return [];
+    }
+    // `key in payload` (not truthiness) is what lets an explicit `null` value
+    // (e.g. wake.recommended's `value: null`) pass: absent is a violation,
+    // present-but-null is not.
+    const missing = requiredKeys.filter((key) => !(key in event.payload) || event.payload[key] === undefined);
+    if (missing.length === 0) {
+        return [];
+    }
+    return [
+        {
+            message: `event ${event.event_id} of type ${event.type} is missing required payload keys: ${missing.join(", ")}`,
+            source: sourceName
+        }
+    ];
+};
+/**
+ * Shared validation core for both synthetic and real conformance: schema
+ * parsing (via parseCausalJsonl), payload minimums, and combined per-
+ * (run_id, system:stream) seq contiguity across every source (disjoint
+ * streams are safe to combine — checkSeqContiguity groups by stream key).
+ * An empty source list is always reported as a failure, never a silent
+ * no-op.
+ */
+const validateConformanceSources = (sources, payloadMinimums, extraChecks = []) => {
+    const issues = [];
+    if (sources.length === 0) {
+        issues.push({ message: "no conformance fixture sources were provided", source: "<none>" });
+    }
+    const requiredKeysByType = new Map(payloadMinimums.map((minimum) => [minimum.type, minimum.requiredKeys]));
+    const allEvents = [];
+    for (const source of sources) {
+        const { errors, events } = parseCausalJsonl(source.jsonl);
+        for (const error of errors) {
+            issues.push({ line: error.line, message: error.message, source: source.name });
+        }
+        for (const event of events) {
+            issues.push(...checkPayloadMinimums(event, source.name, requiredKeysByType));
+            for (const check of extraChecks) {
+                issues.push(...check(event, source.name));
+            }
+        }
+        allEvents.push(...events);
+    }
+    const contiguity = checkSeqContiguity(allEvents);
+    for (const gap of contiguity.gaps) {
+        issues.push({
+            message: `stream ${gap.runId}/${gap.system}:${gap.streamId} has a seq gap at ${gap.missing.map(({ from, to }) => from === to ? `${from}` : `${from}-${to}`).join(", ")} (max seq ${gap.maxSeq})`,
+            source: "<seq>"
+        });
+    }
+    return { events: allEvents, issues };
+};
+/**
+ * Validates seeded/synthetic CausalEvent JSONL fixtures against the schema
+ * (via parseCausalJsonl), per-stream seq contiguity, payload minimums, and
+ * (B62) the principal grammar/consistency discipline in
+ * `PRINCIPAL_DISCIPLINE_CHECKS`. An empty source list is always reported as
+ * a failure — this harness never silently skips a missing source, even in
+ * synthetic mode.
+ */
+export const runSyntheticConformance = (sources, payloadMinimums = DEFAULT_PAYLOAD_MINIMUMS) => {
+    const { events, issues } = validateConformanceSources(sources, payloadMinimums, PRINCIPAL_DISCIPLINE_CHECKS);
+    issues.push(...checkCauseNamespaces(events));
+    return { eventCount: events.length, issues, ok: issues.length === 0 };
+};
+/**
+ * Locates the B92 interaction-chain roles among a flat CausalEvent[] set,
+ * scoped to EMITTER_RUN_ID (every real emitter is invoked with that shared
+ * run_id — see emitters.ts): M1/M2 are moltnet message.accepted seq 1/2 on
+ * the same stream, R[] is every mneme memory.recalled event in seq order,
+ * T1/T1out are daimon's turn.input.submitted/turn.output.completed. A
+ * missing role is reported as an issue rather than throwing.
+ */
+const identifyChainRoles = (events) => {
+    const issues = [];
+    const inRun = events.filter((event) => event.run_id === EMITTER_RUN_ID);
+    const moltnetAccepted = inRun.filter((event) => event.emitter.system === "moltnet" && event.type === "message.accepted");
+    const m1 = moltnetAccepted.find((event) => event.emitter.seq === 1);
+    const m2 = moltnetAccepted.find((event) => event.emitter.seq === 2 && (m1 === undefined || event.emitter.stream_id === m1.emitter.stream_id));
+    const recalls = inRun
+        .filter((event) => event.emitter.system === "mneme" && event.type === "memory.recalled")
+        .sort((left, right) => left.emitter.seq - right.emitter.seq);
+    const daimonEvents = inRun.filter((event) => event.emitter.system === "daimon");
+    const t1 = daimonEvents.find((event) => event.type === "turn.input.submitted");
+    const t1out = daimonEvents.find((event) => event.type === "turn.output.completed");
+    if (!m1) {
+        issues.push({ message: "chain stitch: missing moltnet message.accepted seq 1 (M1)", source: "<chain>" });
+    }
+    if (!m2) {
+        issues.push({ message: "chain stitch: missing moltnet message.accepted seq 2 (M2)", source: "<chain>" });
+    }
+    if (recalls.length === 0) {
+        issues.push({ message: "chain stitch: missing mneme memory.recalled events (R)", source: "<chain>" });
+    }
+    if (!t1) {
+        issues.push({ message: "chain stitch: missing daimon turn.input.submitted (T1)", source: "<chain>" });
+    }
+    if (!t1out) {
+        issues.push({ message: "chain stitch: missing daimon turn.output.completed (T1out)", source: "<chain>" });
+    }
+    return { issues, m1, m2, recalls, t1, t1out };
+};
+const cloneEvent = (event) => ({
+    ...event,
+    cause_event_ids: [...event.cause_event_ids],
+    payload: { ...event.payload }
+});
+/**
+ * Stitches the four independent, non-cross-referencing real fixtures into
+ * one interaction chain (B92 §4). Pure: never mutates its input, never does
+ * I/O. Rewrites ONLY linkage fields — R[i].cause_event_ids, T1.cause_event_ids,
+ * T1.payload.input_message_ids, T1.payload.input_content_sha256, and
+ * M2.cause_event_ids — every other field of every event is carried through
+ * byte-identical. T1out.cause_event_ids is asserted to already equal [T1.id]
+ * (daimon stamps that for real) rather than rewritten.
+ *
+ * Missing roles or a violated T1out->T1 assertion are reported as issues and
+ * the input is returned unstitched rather than guessed at.
+ */
+export const stitchInteractionChain = (events) => {
+    const roles = identifyChainRoles(events);
+    if (roles.issues.length > 0) {
+        return { issues: roles.issues, stitched: [...events] };
+    }
+    const m1 = roles.m1;
+    const m2 = roles.m2;
+    const t1 = roles.t1;
+    const t1out = roles.t1out;
+    const recalls = roles.recalls;
+    if (t1out.cause_event_ids.length !== 1 || t1out.cause_event_ids[0] !== t1.event_id) {
+        return {
+            issues: [
+                {
+                    message: `chain stitch: expected daimon turn.output.completed to cause from turn.input.submitted ` +
+                        `${t1.event_id}, got [${t1out.cause_event_ids.join(", ")}]`,
+                    source: "<chain>"
+                }
+            ],
+            stitched: [...events]
+        };
+    }
+    const m1MessageId = m1.payload.message_id;
+    const m1ContentSha256 = m1.payload.content_sha256;
+    if (typeof m1MessageId !== "string" || typeof m1ContentSha256 !== "string") {
+        return {
+            issues: [
+                { message: "chain stitch: moltnet M1 payload is missing string message_id/content_sha256", source: "<chain>" }
+            ],
+            stitched: [...events]
+        };
+    }
+    const recallIds = new Set(recalls.map((recall) => recall.event_id));
+    const stitchedRecallsById = new Map(recalls.map((recall) => {
+        const clone = cloneEvent(recall);
+        clone.cause_event_ids = [m1.event_id];
+        return [recall.event_id, clone];
+    }));
+    const stitchedT1 = cloneEvent(t1);
+    stitchedT1.cause_event_ids = [m1.event_id, ...recalls.map((recall) => recall.event_id)];
+    stitchedT1.payload.input_message_ids = [m1MessageId];
+    stitchedT1.payload.input_content_sha256 = m1ContentSha256;
+    const stitchedM2 = cloneEvent(m2);
+    stitchedM2.cause_event_ids = [t1out.event_id];
+    const stitched = events.map((event) => {
+        if (event.event_id === t1.event_id) {
+            return stitchedT1;
+        }
+        if (event.event_id === m2.event_id) {
+            return stitchedM2;
+        }
+        if (recallIds.has(event.event_id)) {
+            return stitchedRecallsById.get(event.event_id);
+        }
+        return event;
+    });
+    return { issues: [], stitched };
+};
+/**
+ * Collects the four real sibling emitters (emitters.ts), validates them
+ * (schema + payload minimums + combined seq contiguity + (B62) the
+ * principal grammar/consistency discipline in `PRINCIPAL_DISCIPLINE_CHECKS`
+ * — the real path now enforces exactly what `runSyntheticConformance` does,
+ * so a real emitter stamping a non-grammar principal is a reported issue,
+ * not a silent pass), stitches them into one interaction chain, and
+ * reconciles the result. This is B92's real-mode counterpart to
+ * runSyntheticConformance: same validation core, live process spawning
+ * instead of seeded fixture text.
+ */
+export const runRealConformance = async (options = {}) => {
+    const { issues: collectIssues, sources } = await collectEmitterFixtures(options.specs ?? EMITTER_SPECS, options.exec ?? realExec);
+    const sourceCounts = sources.map((source) => ({
+        count: parseCausalJsonl(source.jsonl).events.length,
+        source: source.name
+    }));
+    const { events, issues: validateIssues } = validateConformanceSources(sources, DEFAULT_PAYLOAD_MINIMUMS, PRINCIPAL_DISCIPLINE_CHECKS);
+    const { issues: stitchIssues, stitched } = stitchInteractionChain(events);
+    const causeNamespaceIssues = checkCauseNamespaces(stitched);
+    let edges = [];
+    if (stitchIssues.length === 0) {
+        const roles = identifyChainRoles(stitched);
+        if (roles.m2) {
+            const reconciled = reconcileEvents(stitched);
+            edges = traceCausesBackward(reconciled, roles.m2.event_id);
+        }
+    }
+    const issues = [...collectIssues, ...validateIssues, ...stitchIssues, ...causeNamespaceIssues];
+    return {
+        chain: { edges, issues: stitchIssues, stitchedEventCount: stitched.length },
+        eventCount: events.length,
+        events,
+        issues,
+        ok: issues.length === 0,
+        sourceCounts
+    };
+};

package/dist/ledger/emitters.d.ts

@@ -0,0 +1,76 @@
+import type { ConformanceFixtureSource, ConformanceIssue } from "./conformance.js";
+/**
+ * Normalized invocation contract for the four real Noopolis causal fixture
+ * emitters (B92, §2). `command` is a direct argv (never a shell string, never
+ * `npm run` — the npm banner would pollute stdout-jsonl output), resolved
+ * relative to `cwd`. `output` distinguishes emitters that print JSONL
+ * directly to stdout from daimon, which prints the absolute path of a JSONL
+ * file it wrote as the last stdout line.
+ */
+export interface EmitterSpec {
+    command: string[];
+    cwd: string;
+    name: string;
+    output: "path-line" | "stdout-jsonl";
+}
+/** run_id every emitter is invoked with. Sourced from NOOPOLIS_RUN_ID, never model output. */
+export declare const EMITTER_RUN_ID = "b92-conformance";
+/**
+ * The four real sibling fixture emitters, invoked by path (never `npm run`).
+ * See B92 packet §1-§2 and each sibling's own runtime/observability AGENTS.md
+ * for what each emitter does.
+ */
+export declare const EMITTER_SPECS: EmitterSpec[];
+/**
+ * Builds the adversarial "spoof mode" variant of an `EmitterSpec` (B62
+ * enforcement point #4): the sibling fixture emitter is asked to embed a
+ * forged/claimed identity in its fixture's input or output content, while
+ * still stamping `principal_id` as its own authenticated identity — never
+ * the claimed one. `--spoof` is the flag convention daimon's own fixture
+ * emitter already understands (`npm run emit-causal-fixture:spoof`, see
+ * `ecosystem/daimon/src/observability/emitCausalFixture.ts`); this helper
+ * applies the same convention uniformly across all four `EmitterSpec`s so a
+ * future caller does not need one-off spoof plumbing per sibling.
+ *
+ * `EMITTER_SPOOF_SPECS` is deliberately NOT part of the default real-mode
+ * `EMITTER_SPECS` list `causalConformanceCli.ts` invokes: today only
+ * daimon's real fixture script understands `--spoof` (simfile/mneme/moltnet
+ * have not yet added a spoof-capable fixture variant), so spawning the
+ * other three with an unrecognized flag would break the hermetic real-mode
+ * run. `EMITTER_SPOOF_SPECS` exists for callers — and this file's own
+ * injected-exec tests — that want to exercise spoof-mode collection
+ * explicitly, and is the shape every sibling's real spoof script should
+ * match once added.
+ */
+export declare const toSpoofEmitterSpec: (spec: EmitterSpec) => EmitterSpec;
+/** The adversarial "spoof mode" counterpart to `EMITTER_SPECS` — see `toSpoofEmitterSpec`. */
+export declare const EMITTER_SPOOF_SPECS: EmitterSpec[];
+export interface ExecResult {
+    exitCode: number | null;
+    spawnError?: Error;
+    stderr: string;
+    stdout: string;
+    timedOut: boolean;
+}
+/** Injectable process runner. `realExec` is the only implementation that actually spawns a process. */
+export type Exec = (spec: EmitterSpec) => Promise<ExecResult>;
+/**
+ * Spawns `spec.command` directly (no shell) in `spec.cwd`, with stdout and
+ * stderr captured separately so stderr noise (npm banners, SQLite
+ * ExperimentalWarning, etc.) never corrupts stdout-jsonl parsing. Kills the
+ * child on `EMITTER_TIMEOUT_MS` expiry.
+ */
+export declare const realExec: Exec;
+export interface EmitterFixtureResult {
+    issues: ConformanceIssue[];
+    sources: ConformanceFixtureSource[];
+}
+/**
+ * Runs every emitter spec sequentially (daimon reuses a fixed on-disk
+ * directory across runs, so concurrent invocation is unsafe) and turns each
+ * result into either a conformance fixture source or a reported issue.
+ * Never silently skips an emitter: spawn error, timeout, nonzero exit, zero
+ * parsed records, and an unreadable daimon path-line are all reported as a
+ * `ConformanceIssue{source}` rather than dropped.
+ */
+export declare const collectEmitterFixtures: (specs?: EmitterSpec[], exec?: Exec) => Promise<EmitterFixtureResult>;

package/dist/ledger/emitters.js

@@ -0,0 +1,188 @@
+import { spawn } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseCausalJsonl } from "@noopolis/stele";
+/** run_id every emitter is invoked with. Sourced from NOOPOLIS_RUN_ID, never model output. */
+export const EMITTER_RUN_ID = "b92-conformance";
+/** Per-emitter kill timeout. `go run` pays a compile cost on a cold module cache. */
+const EMITTER_TIMEOUT_MS = 120_000;
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// src/ledger -> src -> <repo root>
+const ROOT_DIR = path.resolve(__dirname, "..", "..");
+const ecosystemPath = (name) => path.resolve(ROOT_DIR, "ecosystem", name);
+/**
+ * The four real sibling fixture emitters, invoked by path (never `npm run`).
+ * See B92 packet §1-§2 and each sibling's own runtime/observability AGENTS.md
+ * for what each emitter does.
+ */
+export const EMITTER_SPECS = [
+    {
+        command: ["node_modules/.bin/tsx", "src/runtime/emit-causal-fixture.ts"],
+        cwd: ecosystemPath("simfile"),
+        name: "simfile",
+        output: "stdout-jsonl"
+    },
+    {
+        command: ["node_modules/.bin/tsx", "scripts/emit-causal-fixture.ts"],
+        cwd: ecosystemPath("mneme"),
+        name: "mneme",
+        output: "stdout-jsonl"
+    },
+    {
+        command: ["node_modules/.bin/tsx", "src/observability/emitCausalFixture.ts"],
+        cwd: ecosystemPath("daimon"),
+        name: "daimon",
+        output: "path-line"
+    },
+    {
+        command: ["go", "run", "./cmd/emit-causal-fixture"],
+        cwd: ecosystemPath("moltnet"),
+        name: "moltnet",
+        output: "stdout-jsonl"
+    }
+];
+/**
+ * Builds the adversarial "spoof mode" variant of an `EmitterSpec` (B62
+ * enforcement point #4): the sibling fixture emitter is asked to embed a
+ * forged/claimed identity in its fixture's input or output content, while
+ * still stamping `principal_id` as its own authenticated identity — never
+ * the claimed one. `--spoof` is the flag convention daimon's own fixture
+ * emitter already understands (`npm run emit-causal-fixture:spoof`, see
+ * `ecosystem/daimon/src/observability/emitCausalFixture.ts`); this helper
+ * applies the same convention uniformly across all four `EmitterSpec`s so a
+ * future caller does not need one-off spoof plumbing per sibling.
+ *
+ * `EMITTER_SPOOF_SPECS` is deliberately NOT part of the default real-mode
+ * `EMITTER_SPECS` list `causalConformanceCli.ts` invokes: today only
+ * daimon's real fixture script understands `--spoof` (simfile/mneme/moltnet
+ * have not yet added a spoof-capable fixture variant), so spawning the
+ * other three with an unrecognized flag would break the hermetic real-mode
+ * run. `EMITTER_SPOOF_SPECS` exists for callers — and this file's own
+ * injected-exec tests — that want to exercise spoof-mode collection
+ * explicitly, and is the shape every sibling's real spoof script should
+ * match once added.
+ */
+export const toSpoofEmitterSpec = (spec) => ({
+    ...spec,
+    command: [...spec.command, "--spoof"],
+    name: `${spec.name}-spoof`
+});
+/** The adversarial "spoof mode" counterpart to `EMITTER_SPECS` — see `toSpoofEmitterSpec`. */
+export const EMITTER_SPOOF_SPECS = EMITTER_SPECS.map(toSpoofEmitterSpec);
+/**
+ * Spawns `spec.command` directly (no shell) in `spec.cwd`, with stdout and
+ * stderr captured separately so stderr noise (npm banners, SQLite
+ * ExperimentalWarning, etc.) never corrupts stdout-jsonl parsing. Kills the
+ * child on `EMITTER_TIMEOUT_MS` expiry.
+ */
+export const realExec = (spec) => new Promise((resolve) => {
+    const [command, ...args] = spec.command;
+    if (!command) {
+        resolve({ exitCode: null, spawnError: new Error("empty command"), stderr: "", stdout: "", timedOut: false });
+        return;
+    }
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    let settled = false;
+    const child = spawn(command, args, {
+        cwd: spec.cwd,
+        env: { ...process.env, NOOPOLIS_RUN_ID: EMITTER_RUN_ID }
+    });
+    const timer = setTimeout(() => {
+        timedOut = true;
+        child.kill("SIGKILL");
+    }, EMITTER_TIMEOUT_MS);
+    child.stdout?.on("data", (chunk) => {
+        stdout += chunk.toString("utf8");
+    });
+    child.stderr?.on("data", (chunk) => {
+        stderr += chunk.toString("utf8");
+    });
+    child.on("error", (error) => {
+        if (settled) {
+            return;
+        }
+        settled = true;
+        clearTimeout(timer);
+        resolve({ exitCode: null, spawnError: error, stderr, stdout, timedOut });
+    });
+    child.on("close", (code) => {
+        if (settled) {
+            return;
+        }
+        settled = true;
+        clearTimeout(timer);
+        resolve({ exitCode: code, stderr, stdout, timedOut });
+    });
+});
+const lastNonEmptyLine = (text) => {
+    const lines = text.split("\n").map((line) => line.trim()).filter((line) => line.length > 0);
+    return lines[lines.length - 1];
+};
+/**
+ * Runs every emitter spec sequentially (daimon reuses a fixed on-disk
+ * directory across runs, so concurrent invocation is unsafe) and turns each
+ * result into either a conformance fixture source or a reported issue.
+ * Never silently skips an emitter: spawn error, timeout, nonzero exit, zero
+ * parsed records, and an unreadable daimon path-line are all reported as a
+ * `ConformanceIssue{source}` rather than dropped.
+ */
+export const collectEmitterFixtures = async (specs = EMITTER_SPECS, exec = realExec) => {
+    const sources = [];
+    const issues = [];
+    for (const spec of specs) {
+        const result = await exec(spec);
+        if (result.spawnError) {
+            issues.push({ message: `spawn error: ${result.spawnError.message}`, source: spec.name });
+            continue;
+        }
+        if (result.timedOut) {
+            issues.push({ message: `timed out after ${EMITTER_TIMEOUT_MS}ms`, source: spec.name });
+            continue;
+        }
+        if (result.exitCode !== 0) {
+            const stderrDetail = result.stderr.trim();
+            issues.push({
+                message: `exited with code ${String(result.exitCode)}${stderrDetail ? `: ${stderrDetail}` : ""}`,
+                source: spec.name
+            });
+            continue;
+        }
+        let jsonl;
+        if (spec.output === "path-line") {
+            const pathLine = lastNonEmptyLine(result.stdout);
+            if (!pathLine) {
+                issues.push({ message: "path-line emitter produced no output path on stdout", source: spec.name });
+                continue;
+            }
+            try {
+                jsonl = await readFile(pathLine, "utf8");
+            }
+            catch (error) {
+                issues.push({
+                    message: `unreadable path ${pathLine}: ${error instanceof Error ? error.message : String(error)}`,
+                    source: spec.name
+                });
+                continue;
+            }
+        }
+        else {
+            jsonl = result.stdout;
+        }
+        const { errors, events } = parseCausalJsonl(jsonl);
+        if (errors.length > 0) {
+            for (const error of errors) {
+                issues.push({ line: error.line, message: error.message, source: spec.name });
+            }
+            continue;
+        }
+        if (events.length === 0) {
+            issues.push({ message: "emitter produced zero parsed records", source: spec.name });
+            continue;
+        }
+        sources.push({ jsonl, name: spec.name });
+    }
+    return { issues, sources };
+};

package/dist/ledger/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./causeNamespace.js";
+export * from "./conformance.js";
+export * from "./emitters.js";
+export * from "@noopolis/stele";

package/dist/ledger/index.js

@@ -0,0 +1,4 @@
+export * from "./causeNamespace.js";
+export * from "./conformance.js";
+export * from "./emitters.js";
+export * from "@noopolis/stele";

package/dist/ledger/principal.d.ts

@@ -0,0 +1,96 @@
+import type { CausalEvent } from "@noopolis/stele";
+import { PRINCIPAL_GRAMMAR_SOURCE } from "@noopolis/stele";
+/**
+ * Principal grammar (specs/CAUSAL.md §3, `specs/causal-event.v1.schema.json`
+ * `principal_id.pattern`): `agent:<agentId>` | `operator:<credentialKey|name>`
+ * | `system:<system>[.<component>]`. A principal is minted only by a
+ * trusted layer (root's container env, a per-agent harness config, an
+ * authn claim) — never derived from `request.From`, tool arguments, or
+ * model output. This module owns parsing/validating that grammar on the
+ * root side, plus the per-event conformance checks conformance.ts layers
+ * on top of it; it has no I/O and no knowledge of any specific authority's
+ * transport.
+ *
+ * The grammar itself (`PRINCIPAL_GRAMMAR_SOURCE`) is defined once in
+ * `envelope.ts` — the same regex `causalEventSchema` enforces on the wire —
+ * and re-exported from here so existing callers of this module keep working;
+ * this file never hardcodes a second copy of the pattern.
+ */
+export type PrincipalKind = "agent" | "operator" | "system";
+export interface Principal {
+    id: string;
+    kind: PrincipalKind;
+}
+export interface PrincipalParseError {
+    message: string;
+}
+export { PRINCIPAL_GRAMMAR_SOURCE };
+/**
+ * `system:moltnet.anonymous` is moltnet's stamped principal for the
+ * unauthenticated dev-mode case (no authn claims on the request context at
+ * all) — see `ecosystem/moltnet/internal/rooms/causal.go`. It is grammar-
+ * valid (a real `system:` principal) but conformance treats it as
+ * unauthenticated on purpose: it is a placeholder for "no principal",
+ * never a credential to attribute causal events to.
+ */
+export declare const ANONYMOUS_SYSTEM_PRINCIPAL = "system:moltnet.anonymous";
+/**
+ * Parses a `principal_id` string against the grammar. Returns a
+ * `PrincipalParseError` (never throws) for anything that does not match
+ * `^(agent|operator|system):.+` — a bare id with no prefix, an unknown
+ * prefix, or an empty string all land here.
+ */
+export declare const parsePrincipal: (value: string) => Principal | PrincipalParseError;
+export declare const isPrincipalParseError: (value: Principal | PrincipalParseError) => value is PrincipalParseError;
+/**
+ * True only for a principal that is both grammar-valid and represents a
+ * real authenticated identity: grammar mismatches, a bare id, an empty
+ * trailing id, the literal `anonymous`, and `system:moltnet.anonymous`
+ * (moltnet's unauthenticated dev-mode placeholder) are all rejected.
+ * Conformance (`conformance.ts`) uses this as its per-event grammar check.
+ */
+export declare const isAuthenticatedPrincipal: (value: string) => boolean;
+/**
+ * Lightweight structural sibling of `conformance.ts`'s `ConformanceIssue`
+ * (message + source; no line number — these are per-event, not per-line
+ * fixture checks). Kept local to this module to avoid a circular import
+ * with `conformance.ts`, which imports `PRINCIPAL_DISCIPLINE_CHECKS` from
+ * here; every field here is a subset of `ConformanceIssue`'s, so these
+ * values are usable anywhere a `ConformanceIssue` is expected.
+ */
+export interface PrincipalConformanceIssue {
+    message: string;
+    source: string;
+}
+export type PrincipalEventCheck = (event: CausalEvent, sourceName: string) => PrincipalConformanceIssue[];
+/**
+ * Principal-grammar check (specs/CAUSAL.md §3, B62 enforcement point #4a):
+ * every event's `principal_id` must be an authenticated `agent:`/`operator:`/
+ * `system:` principal — never a bare id, the literal `anonymous`, or
+ * moltnet's `system:moltnet.anonymous` unauthenticated placeholder.
+ */
+export declare const checkPrincipalGrammar: PrincipalEventCheck;
+/**
+ * Stream/principal consistency check (B62 enforcement point #4b): for
+ * daimon's turn events, `principal_id` must exactly equal `emitter.stream_id`
+ * — the agent whose stream this is must be the agent this event is
+ * attributed to. This deliberately does NOT apply to daimon's control-wake
+ * events (`control.wake.accepted`/`control.wake.denied`), whose stream is
+ * the *target* agent being woken but whose principal is the *operator* who
+ * requested the wake — an intentional mismatch, not a violation.
+ */
+export declare const checkStreamPrincipalConsistency: PrincipalEventCheck;
+/**
+ * Per-event checks `conformance.ts`'s `runSyntheticConformance` AND (as of
+ * the B62 fix) `runRealConformance` both layer on top of schema parsing +
+ * payload minimums, via `validateConformanceSources`'s `extraChecks`
+ * parameter. Wiring this into `runRealConformance` is what gives the real
+ * `npm run test:causal-conformance` path teeth: without it, a real sibling
+ * emitter stamping a non-grammar `principal_id` would pass conformance
+ * silently (the schema-level `PRINCIPAL_GRAMMAR_SOURCE` regex in
+ * `envelope.ts` already rejects most malformed principals at parse time, but
+ * `checkStreamPrincipalConsistency` in particular is conformance-only — it
+ * has no envelope-schema equivalent). `realConformance.test.ts`'s hand-
+ * authored fixtures are kept grammar-compliant for exactly this reason.
+ */
+export declare const PRINCIPAL_DISCIPLINE_CHECKS: PrincipalEventCheck[];