simfile 0.0.1

package/dist/observe/artifacts.js

@@ -0,0 +1,31 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+const sha256Hex = (buffer) => createHash("sha256").update(buffer).digest("hex");
+/**
+ * Verifies every manifest-declared artifact's sha256 against the file on
+ * disk. A mismatch (or a missing file) is reported as a failed check, never
+ * silently repaired or stitched over — the caller decides what to do with a
+ * failed integrity check (contracts.md: "missing links are reported, not
+ * synthesized" applies just as much to artifact bytes as to causal edges).
+ */
+export const verifyManifestArtifacts = async (runDir, artifacts) => {
+    const checks = [];
+    for (const artifact of artifacts) {
+        const absolutePath = path.resolve(runDir, artifact.path);
+        try {
+            const buffer = await readFile(absolutePath);
+            const actualSha256 = sha256Hex(buffer);
+            checks.push({
+                actualSha256,
+                expectedSha256: artifact.sha256,
+                ok: actualSha256 === artifact.sha256,
+                path: artifact.path
+            });
+        }
+        catch {
+            checks.push({ actualSha256: null, expectedSha256: artifact.sha256, ok: false, path: artifact.path });
+        }
+    }
+    return checks;
+};

package/dist/observe/causalStreams.d.ts

@@ -0,0 +1,19 @@
+import { type CausalEvent, type CausalJsonlParseError } from "@noopolis/stele";
+export interface CausalStreamSource {
+    /** The authority directory name directly under `raw/` (e.g. "moltnet", "daimon", "mneme"). */
+    authority: string;
+    errors: CausalJsonlParseError[];
+    events: CausalEvent[];
+    /** Path relative to the run directory. */
+    relativePath: string;
+}
+/**
+ * Reads and parses every `causal.jsonl` file under `<runDir>/raw/**`,
+ * tagging each stream by the authority directory it lives under
+ * (`raw/<authority>/...causal.jsonl`). Never reads any other file kind here
+ * — that keeps this module a single-purpose causal-stream collector; other
+ * per-authority artifacts (transcripts, bank event logs) are read by their
+ * own modules.
+ */
+export declare const collectCausalStreams: (runDir: string) => Promise<CausalStreamSource[]>;
+//# sourceMappingURL=causalStreams.d.ts.map

package/dist/observe/causalStreams.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"causalStreams.d.ts","sourceRoot":"","sources":["../../src/observe/causalStreams.ts"],"names":[],"mappings":"AAGA,OAAO,EAAoB,KAAK,WAAW,EAAE,KAAK,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAEjG,MAAM,WAAW,kBAAkB;IACjC,8FAA8F;IAC9F,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,qBAAqB,EAAE,CAAC;IAChC,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,0CAA0C;IAC1C,YAAY,EAAE,MAAM,CAAC;CACtB;AAgBD;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,GAAU,QAAQ,MAAM,KAAG,OAAO,CAAC,kBAAkB,EAAE,CAavF,CAAC"}

package/dist/observe/causalStreams.js

@@ -0,0 +1,38 @@
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { parseCausalJsonl } from "@noopolis/stele";
+const walkFiles = async (root) => {
+    const entries = await readdir(root, { withFileTypes: true }).catch(() => []);
+    const files = [];
+    for (const entry of entries) {
+        const entryPath = path.join(root, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...(await walkFiles(entryPath)));
+        }
+        else if (entry.isFile()) {
+            files.push(entryPath);
+        }
+    }
+    return files;
+};
+/**
+ * Reads and parses every `causal.jsonl` file under `<runDir>/raw/**`,
+ * tagging each stream by the authority directory it lives under
+ * (`raw/<authority>/...causal.jsonl`). Never reads any other file kind here
+ * — that keeps this module a single-purpose causal-stream collector; other
+ * per-authority artifacts (transcripts, bank event logs) are read by their
+ * own modules.
+ */
+export const collectCausalStreams = async (runDir) => {
+    const rawDir = path.join(runDir, "raw");
+    const files = (await walkFiles(rawDir)).filter((file) => file.endsWith("causal.jsonl")).sort();
+    const sources = [];
+    for (const file of files) {
+        const relativePath = path.relative(runDir, file);
+        const authority = relativePath.split(path.sep)[1] ?? "unknown";
+        const text = await readFile(file, "utf8");
+        const { errors, events } = parseCausalJsonl(text);
+        sources.push({ authority, errors, events, relativePath });
+    }
+    return sources;
+};

package/dist/observe/compute.d.ts

@@ -0,0 +1,17 @@
+import type { CausalEvent, ReconcileResult } from "@noopolis/stele";
+import type { MemoryBankCounts } from "./memoryBanks.js";
+import type { SimfileRunManifest } from "./manifest.js";
+import { type SimfileObserveReport } from "./report.js";
+import type { SeedSpreadComputeResult } from "./seedSpread.js";
+export interface BuildObserveReportInput {
+    allEvents: readonly CausalEvent[];
+    manifest: SimfileRunManifest;
+    memoryBanks: readonly MemoryBankCounts[];
+    reconciled: ReconcileResult;
+    /** Memetics increment (b): present only when `manifest.seed_declaration`
+     * exists. `excluded` hits (instrument/operator actors) fold into
+     * `failures`, never into `seed_spread`. */
+    seedSpread?: SeedSpreadComputeResult;
+}
+export declare const buildObserveReport: (input: BuildObserveReportInput) => SimfileObserveReport;
+//# sourceMappingURL=compute.d.ts.map

package/dist/observe/compute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compute.d.ts","sourceRoot":"","sources":["../../src/observe/compute.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAuB,MAAM,iBAAiB,CAAC;AAEzF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,EAAkD,KAAK,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACxG,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAiG/D,MAAM,WAAW,uBAAuB;IACtC,SAAS,EAAE,SAAS,WAAW,EAAE,CAAC;IAClC,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,WAAW,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACzC,UAAU,EAAE,eAAe,CAAC;IAC5B;;+CAE2C;IAC3C,UAAU,CAAC,EAAE,uBAAuB,CAAC;CACtC;AAED,eAAO,MAAM,kBAAkB,GAAI,OAAO,uBAAuB,KAAG,oBAmBlE,CAAC"}

package/dist/observe/compute.js

@@ -0,0 +1,97 @@
+import { OBSERVE_REPORT_VERSION } from "./report.js";
+const FAILURE_TYPES = new Set(["turn.failed", "wake.failed"]);
+const AGENT_PRINCIPAL_PATTERN = /^agent:(.+)$/u;
+const agentIdFromStreamId = (streamId) => streamId.replace(/^agent:/u, "");
+/**
+ * Orders an agent's `turn.output.completed` events by the moltnet message
+ * seq that triggered the underlying turn (never `recorded_at`): each
+ * `turn.input.submitted` carries `payload.input_message_ids`, the message
+ * event ids that caused it; resolving those back to moltnet's own
+ * per-stream `emitter.seq` gives a causal, non-wall-clock ordering.
+ */
+const triggeringMoltnetSeq = (inputEvent, byEventId) => {
+    const messageIds = inputEvent?.payload.input_message_ids;
+    if (!Array.isArray(messageIds))
+        return undefined;
+    let minSeq;
+    for (const messageId of messageIds) {
+        if (typeof messageId !== "string")
+            continue;
+        const message = byEventId.get(messageId);
+        if (!message || message.emitter.system !== "moltnet")
+            continue;
+        minSeq = minSeq === undefined ? message.emitter.seq : Math.min(minSeq, message.emitter.seq);
+    }
+    return minSeq;
+};
+const computeParticipants = (events) => {
+    const participants = new Set();
+    for (const event of events) {
+        const match = AGENT_PRINCIPAL_PATTERN.exec(event.principal_id);
+        if (match?.[1])
+            participants.add(match[1]);
+    }
+    return [...participants].sort();
+};
+const computeAgentTurns = (events) => {
+    const byEventId = new Map(events.map((event) => [event.event_id, event]));
+    const turnOutputs = events.filter((event) => event.emitter.system === "daimon" && event.type === "turn.output.completed");
+    const ordered = turnOutputs
+        .map((turnOutput) => {
+        const inputEventId = turnOutput.cause_event_ids.find((causeId) => {
+            const cause = byEventId.get(causeId);
+            return cause?.emitter.system === "daimon" && cause.type === "turn.input.submitted";
+        });
+        const inputEvent = inputEventId ? byEventId.get(inputEventId) : undefined;
+        return {
+            agentId: agentIdFromStreamId(turnOutput.emitter.stream_id),
+            eventId: turnOutput.event_id,
+            seq: triggeringMoltnetSeq(inputEvent, byEventId)
+        };
+    })
+        .sort((left, right) => {
+        const leftSeq = left.seq ?? Number.POSITIVE_INFINITY;
+        const rightSeq = right.seq ?? Number.POSITIVE_INFINITY;
+        return leftSeq - rightSeq || left.eventId.localeCompare(right.eventId);
+    });
+    return { count: ordered.length, sequence: ordered.map((entry) => entry.agentId) };
+};
+const computeChains = (reconciled) => {
+    let complete = 0;
+    const incomplete = [];
+    for (const [eventId, record] of reconciled.byEventId) {
+        if (record.state === "complete") {
+            complete += 1;
+            continue;
+        }
+        incomplete.push({ event_id: eventId, flag: record.state });
+    }
+    incomplete.sort((left, right) => left.event_id.localeCompare(right.event_id));
+    return { complete, incomplete };
+};
+const computeFailures = (events) => events
+    .filter((event) => FAILURE_TYPES.has(event.type))
+    .map((event) => ({
+    event_id: event.event_id,
+    reason: typeof event.payload.reason === "string" ? event.payload.reason : event.type
+}));
+export const buildObserveReport = (input) => ({
+    version: OBSERVE_REPORT_VERSION,
+    run_id: input.manifest.run_id,
+    contract_versions: input.manifest.contract_versions,
+    participants: computeParticipants(input.allEvents),
+    agent_turns: computeAgentTurns(input.allEvents),
+    chains: computeChains(input.reconciled),
+    memory: input.memoryBanks.map((bank) => ({
+        bank: bank.bank,
+        events: bank.events,
+        recalls: bank.recalls,
+        memory_write_source: bank.memory_write_source,
+        ...(bank.writes_by_agent ? { writes_by_agent: bank.writes_by_agent } : {})
+    })),
+    failures: [
+        ...computeFailures(input.allEvents),
+        ...(input.seedSpread?.excluded.map((excluded) => ({ event_id: excluded.event_id, reason: excluded.reason })) ?? [])
+    ],
+    ...(input.seedSpread ? { seed_spread: input.seedSpread.entries, spread_summary: input.seedSpread.summary } : {})
+});

package/dist/observe/index.d.ts

@@ -0,0 +1,11 @@
+export * from "./artifacts.js";
+export * from "./causalStreams.js";
+export * from "./compute.js";
+export * from "./manifest.js";
+export * from "./memoryBanks.js";
+export * from "./observe.js";
+export * from "./report.js";
+export * from "./seedSpread.js";
+export * from "./seedSpreadArtifacts.js";
+export * from "./spreadMatcher.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/observe/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/observe/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC"}

package/dist/observe/index.js

@@ -0,0 +1,10 @@
+export * from "./artifacts.js";
+export * from "./causalStreams.js";
+export * from "./compute.js";
+export * from "./manifest.js";
+export * from "./memoryBanks.js";
+export * from "./observe.js";
+export * from "./report.js";
+export * from "./seedSpread.js";
+export * from "./seedSpreadArtifacts.js";
+export * from "./spreadMatcher.js";

package/dist/observe/manifest.d.ts

@@ -0,0 +1,79 @@
+import { z } from "zod";
+/**
+ * `simfile.run-manifest.v1` — the composite run manifest simfile writes for
+ * a run's directory (Decision 21 / contracts.md's `simfile.run-manifest.v1`
+ * row). `seed_declaration` and `expected_wakes` are DEFINED-BUT-OPTIONAL:
+ * office-sim runs omit both (no seeded secret, no compiled wake schedule to
+ * diff against yet), so a manifest without them is still fully conformant.
+ * A future memetics phase (Phase G) populates both without a v2 bump.
+ */
+export declare const RUN_MANIFEST_VERSION: "simfile.run-manifest.v1";
+declare const artifactEntrySchema: z.ZodObject<{
+    path: z.ZodString;
+    sha256: z.ZodString;
+}, z.core.$strict>;
+export type RunManifestArtifactEntry = z.infer<typeof artifactEntrySchema>;
+/**
+ * The observer's ground truth for a seeded memetics secret (contracts.md
+ * "measurement-critical contracts" section). `matcher_policy` is kept as a
+ * documented free-form string rather than a tight enum: the named policies
+ * (`exact` / `edit-distance:<k>` / `embedding` / `judge`) may carry pinned
+ * experiment parameters. `spreadMatcher.ts` validates and dispatches this
+ * field; model-backed policies fail loudly in builds without those models.
+ */
+declare const seedDeclarationSchema: z.ZodObject<{
+    content_hash: z.ZodString;
+    token_set: z.ZodArray<z.ZodString>;
+    matcher_policy: z.ZodString;
+    seed_agent: z.ZodString;
+    seed_epoch: z.ZodString;
+    entry_channel: z.ZodLiteral<"doc-seeded">;
+}, z.core.$strict>;
+export type SeedDeclaration = z.infer<typeof seedDeclarationSchema>;
+/**
+ * One compiled schedule fire simfile expects to observe within the run's
+ * sim-time window (the denominator oracle for the 100%-reply-or-recover
+ * bar, contracts.md). Kept minimal and generic: the compiled-schedule ->
+ * wake-diff lowering is Phase 7 scope (Decision 21's phasing), so this only
+ * carries what `simfile observe`'s wake-diff will need to match against —
+ * which agent, which wake, and when.
+ */
+declare const expectedWakeSchema: z.ZodObject<{
+    agent_id: z.ZodString;
+    wake_id: z.ZodString;
+    sim_time: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type ExpectedWake = z.infer<typeof expectedWakeSchema>;
+export declare const runManifestSchema: z.ZodObject<{
+    version: z.ZodLiteral<"simfile.run-manifest.v1">;
+    run_id: z.ZodString;
+    created_at: z.ZodString;
+    contract_versions: z.ZodRecord<z.ZodString, z.ZodString>;
+    spawnfile: z.ZodOptional<z.ZodObject<{
+        up_receipt_ref: z.ZodOptional<z.ZodString>;
+        fingerprint: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    artifacts: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        sha256: z.ZodString;
+    }, z.core.$strict>>;
+    engine: z.ZodOptional<z.ZodString>;
+    world: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    seed_declaration: z.ZodOptional<z.ZodObject<{
+        content_hash: z.ZodString;
+        token_set: z.ZodArray<z.ZodString>;
+        matcher_policy: z.ZodString;
+        seed_agent: z.ZodString;
+        seed_epoch: z.ZodString;
+        entry_channel: z.ZodLiteral<"doc-seeded">;
+    }, z.core.$strict>>;
+    expected_wakes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        agent_id: z.ZodString;
+        wake_id: z.ZodString;
+        sim_time: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type SimfileRunManifest = z.infer<typeof runManifestSchema>;
+export declare const parseRunManifest: (raw: unknown) => SimfileRunManifest;
+export {};
+//# sourceMappingURL=manifest.d.ts.map

package/dist/observe/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/observe/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,EAAG,yBAAkC,CAAC;AAEvE,QAAA,MAAM,mBAAmB;;;kBAKd,CAAC;AAEZ,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAS3E;;;;;;;GAOG;AACH,QAAA,MAAM,qBAAqB;;;;;;;kBAShB,CAAC;AAEZ,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE;;;;;;;GAOG;AACH,QAAA,MAAM,kBAAkB;;;;kBAMb,CAAC;AAEZ,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAsB1B,CAAC;AAEL,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAEnE,eAAO,MAAM,gBAAgB,GAAI,KAAK,OAAO,KAAG,kBAU/C,CAAC"}

package/dist/observe/manifest.js

@@ -0,0 +1,87 @@
+import { z } from "zod";
+/**
+ * `simfile.run-manifest.v1` — the composite run manifest simfile writes for
+ * a run's directory (Decision 21 / contracts.md's `simfile.run-manifest.v1`
+ * row). `seed_declaration` and `expected_wakes` are DEFINED-BUT-OPTIONAL:
+ * office-sim runs omit both (no seeded secret, no compiled wake schedule to
+ * diff against yet), so a manifest without them is still fully conformant.
+ * A future memetics phase (Phase G) populates both without a v2 bump.
+ */
+export const RUN_MANIFEST_VERSION = "simfile.run-manifest.v1";
+const artifactEntrySchema = z
+    .object({
+    path: z.string().min(1),
+    sha256: z.string().regex(/^[0-9a-f]{64}$/u, "sha256 must be a 64-character lowercase hex digest")
+})
+    .strict();
+const spawnfileRefSchema = z
+    .object({
+    up_receipt_ref: z.string().min(1).optional(),
+    fingerprint: z.string().min(1).optional()
+})
+    .strict();
+/**
+ * The observer's ground truth for a seeded memetics secret (contracts.md
+ * "measurement-critical contracts" section). `matcher_policy` is kept as a
+ * documented free-form string rather than a tight enum: the named policies
+ * (`exact` / `edit-distance:<k>` / `embedding` / `judge`) may carry pinned
+ * experiment parameters. `spreadMatcher.ts` validates and dispatches this
+ * field; model-backed policies fail loudly in builds without those models.
+ */
+const seedDeclarationSchema = z
+    .object({
+    content_hash: z.string().min(1),
+    token_set: z.array(z.string().min(1)),
+    matcher_policy: z.string().min(1),
+    seed_agent: z.string().min(1),
+    seed_epoch: z.string().min(1),
+    entry_channel: z.literal("doc-seeded")
+})
+    .strict();
+/**
+ * One compiled schedule fire simfile expects to observe within the run's
+ * sim-time window (the denominator oracle for the 100%-reply-or-recover
+ * bar, contracts.md). Kept minimal and generic: the compiled-schedule ->
+ * wake-diff lowering is Phase 7 scope (Decision 21's phasing), so this only
+ * carries what `simfile observe`'s wake-diff will need to match against —
+ * which agent, which wake, and when.
+ */
+const expectedWakeSchema = z
+    .object({
+    agent_id: z.string().min(1),
+    wake_id: z.string().min(1),
+    sim_time: z.number().optional()
+})
+    .strict();
+export const runManifestSchema = z
+    .object({
+    version: z.literal(RUN_MANIFEST_VERSION),
+    run_id: z.string().min(1),
+    created_at: z.string().min(1),
+    contract_versions: z.record(z.string(), z.string()),
+    spawnfile: spawnfileRefSchema.optional(),
+    artifacts: z.array(artifactEntrySchema),
+    engine: z.string().min(1).optional(),
+    world: z.record(z.string(), z.unknown()).optional(),
+    seed_declaration: seedDeclarationSchema.optional(),
+    expected_wakes: z.array(expectedWakeSchema).optional()
+})
+    .strict()
+    .superRefine((value, context) => {
+    if (Number.isNaN(Date.parse(value.created_at))) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "created_at must be a valid ISO 8601 timestamp",
+            path: ["created_at"]
+        });
+    }
+});
+export const parseRunManifest = (raw) => {
+    const result = runManifestSchema.safeParse(raw);
+    if (!result.success) {
+        throw new Error(`invalid ${RUN_MANIFEST_VERSION} manifest: ${result.error.issues
+            .map((issue) => `${issue.path.join(".") || "<root>"}: ${issue.message}`)
+            .join("; ")}`);
+    }
+    return result.data;
+};

package/dist/observe/memoryBanks.d.ts

@@ -0,0 +1,38 @@
+import type { CausalEvent } from "@noopolis/stele";
+import type { MemoryWriteSource } from "./report.js";
+export interface MemoryBankCounts {
+    bank: string;
+    events: number;
+    recalls: number;
+    memory_write_source: MemoryWriteSource;
+    /** Per-agent write counts, derived from `memory.written`'s `principal_id`. Only set on the ledger path. */
+    writes_by_agent?: Record<string, number>;
+}
+/**
+ * Derives each mneme bank's memory-write count, per-agent write signal, and
+ * recall count.
+ *
+ * Ledger-first (Slice B Piece 4b): mneme stamps a `memory.written` causal
+ * event (`noopolis.causal-event.v1`, same `memory/causal.jsonl` stream as
+ * `memory.recalled`) on every durable memory register, with
+ * `cause_event_ids` chaining it to the wake/turn that produced it. When a
+ * bank's reconciled causal stream (`causalEventsByBank`) contains at least
+ * one `memory.written` event, that count is authoritative
+ * (`memory_write_source: "ledger"`), and `writes_by_agent` is derived from
+ * each event's `principal_id`.
+ *
+ * Fallback (pre-4b runs, e.g. the office-sim golden fixture captured before
+ * mneme shipped the write-side event): if a bank's causal stream has ZERO
+ * `memory.written` events, this falls back to the interim signal — mneme's
+ * own `raw/mneme/<bank>/events.jsonl` bank event log (line count as the
+ * write proxy) — marking `memory_write_source: "events-fallback"` so a
+ * stale run is visibly on the fallback, never silently. If neither
+ * `events.jsonl` nor any `memory.written` event exists, `events` is 0.
+ *
+ * `recalls` is unaffected by which write source wins: it always prefers
+ * `events.jsonl`'s own `memory.recalled` lines when the file exists, falling
+ * back to the bank's `memory.recalled` causal events otherwise — the same
+ * behavior this function had before Piece 4b.
+ */
+export declare const collectMemoryBankCounts: (runDir: string, causalEventsByBank: ReadonlyMap<string, CausalEvent[]>) => Promise<MemoryBankCounts[]>;
+//# sourceMappingURL=memoryBanks.d.ts.map

package/dist/observe/memoryBanks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memoryBanks.d.ts","sourceRoot":"","sources":["../../src/observe/memoryBanks.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAErD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,mBAAmB,EAAE,iBAAiB,CAAC;IACvC,2GAA2G;IAC3G,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC1C;AA6BD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,uBAAuB,GAClC,QAAQ,MAAM,EACd,oBAAoB,WAAW,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC,KACrD,OAAO,CAAC,gBAAgB,EAAE,CAwC5B,CAAC"}

package/dist/observe/memoryBanks.js

@@ -0,0 +1,86 @@
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+const AGENT_PRINCIPAL_PATTERN = /^agent:(.+)$/u;
+const countJsonlLines = (content) => content
+    .split(/\r?\n/u)
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+const countRecallsFromEventsJsonl = (lines) => lines.filter((line) => {
+    try {
+        return JSON.parse(line).type === "memory.recalled";
+    }
+    catch {
+        return false;
+    }
+}).length;
+const countByAgent = (events) => {
+    const counts = {};
+    for (const event of events) {
+        const agentId = AGENT_PRINCIPAL_PATTERN.exec(event.principal_id)?.[1];
+        if (!agentId)
+            continue;
+        counts[agentId] = (counts[agentId] ?? 0) + 1;
+    }
+    return counts;
+};
+/**
+ * Derives each mneme bank's memory-write count, per-agent write signal, and
+ * recall count.
+ *
+ * Ledger-first (Slice B Piece 4b): mneme stamps a `memory.written` causal
+ * event (`noopolis.causal-event.v1`, same `memory/causal.jsonl` stream as
+ * `memory.recalled`) on every durable memory register, with
+ * `cause_event_ids` chaining it to the wake/turn that produced it. When a
+ * bank's reconciled causal stream (`causalEventsByBank`) contains at least
+ * one `memory.written` event, that count is authoritative
+ * (`memory_write_source: "ledger"`), and `writes_by_agent` is derived from
+ * each event's `principal_id`.
+ *
+ * Fallback (pre-4b runs, e.g. the office-sim golden fixture captured before
+ * mneme shipped the write-side event): if a bank's causal stream has ZERO
+ * `memory.written` events, this falls back to the interim signal — mneme's
+ * own `raw/mneme/<bank>/events.jsonl` bank event log (line count as the
+ * write proxy) — marking `memory_write_source: "events-fallback"` so a
+ * stale run is visibly on the fallback, never silently. If neither
+ * `events.jsonl` nor any `memory.written` event exists, `events` is 0.
+ *
+ * `recalls` is unaffected by which write source wins: it always prefers
+ * `events.jsonl`'s own `memory.recalled` lines when the file exists, falling
+ * back to the bank's `memory.recalled` causal events otherwise — the same
+ * behavior this function had before Piece 4b.
+ */
+export const collectMemoryBankCounts = async (runDir, causalEventsByBank) => {
+    const mnemeDir = path.join(runDir, "raw", "mneme");
+    const bankDirs = await readdir(mnemeDir, { withFileTypes: true }).catch(() => []);
+    const results = [];
+    for (const entry of bankDirs) {
+        if (!entry.isDirectory())
+            continue;
+        const bank = entry.name;
+        const bankCausalEvents = causalEventsByBank.get(bank) ?? [];
+        const eventsPath = path.join(mnemeDir, bank, "events.jsonl");
+        const eventsText = await readFile(eventsPath, "utf8").catch(() => null);
+        const eventsJsonlLines = eventsText !== null ? countJsonlLines(eventsText) : null;
+        const recalls = eventsJsonlLines !== null
+            ? countRecallsFromEventsJsonl(eventsJsonlLines)
+            : bankCausalEvents.filter((event) => event.type === "memory.recalled").length;
+        const ledgerWrites = bankCausalEvents.filter((event) => event.type === "memory.written");
+        if (ledgerWrites.length > 0) {
+            results.push({
+                bank,
+                events: ledgerWrites.length,
+                recalls,
+                memory_write_source: "ledger",
+                writes_by_agent: countByAgent(ledgerWrites)
+            });
+            continue;
+        }
+        results.push({
+            bank,
+            events: eventsJsonlLines !== null ? eventsJsonlLines.length : 0,
+            recalls,
+            memory_write_source: "events-fallback"
+        });
+    }
+    return results.sort((left, right) => left.bank.localeCompare(right.bank));
+};

package/dist/observe/observe.d.ts

@@ -0,0 +1,32 @@
+import type { ArtifactIntegrityCheck } from "./artifacts.js";
+import type { CausalStreamSource } from "./causalStreams.js";
+import type { SimfileRunManifest } from "./manifest.js";
+import type { SimfileObserveReport } from "./report.js";
+import { type SeedSpreadSelfCheck } from "./seedSpread.js";
+export interface ObserveResult {
+    artifactIntegrity: ArtifactIntegrityCheck[];
+    causalParseErrors: {
+        relativePath: string;
+        line: number;
+        message: string;
+    }[];
+    manifest: SimfileRunManifest;
+    report: SimfileObserveReport;
+    streams: CausalStreamSource[];
+    /** Memetics increment (b): present only when `manifest.seed_declaration`
+     * exists — the live-`marker.seen` self-check, diagnostic only (never fed
+     * into `report.seed_spread`, see `seedSpread.ts`'s own doc comment). */
+    spreadSelfCheck?: SeedSpreadSelfCheck;
+}
+/**
+ * Reads a sealed run directory (`manifest.json` + `raw/**\/causal.jsonl` +
+ * per-bank `raw/mneme/<bank>/events.jsonl`), reconciles the causal streams
+ * with `@noopolis/stele` (no stitching, ever — an incomplete chain is
+ * flagged, not synthesized), and emits the `simfile.observe.v1` report.
+ * Pure file-reading + reconciliation: no Docker, no compile, no runtime
+ * auth (this package's charter, `ecosystem/simfile/AGENTS.md`).
+ */
+export declare const runObserve: (runDir: string) => Promise<ObserveResult>;
+/** Writes `observe/report.json` under the run directory; returns its path. */
+export declare const writeObserveReport: (runDir: string, report: SimfileObserveReport) => Promise<string>;
+//# sourceMappingURL=observe.d.ts.map

package/dist/observe/observe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../../src/observe/observe.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAE7D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAI7D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAExD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAA0D,KAAK,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAOnH,MAAM,WAAW,aAAa;IAC5B,iBAAiB,EAAE,sBAAsB,EAAE,CAAC;IAC5C,iBAAiB,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC7E,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,MAAM,EAAE,oBAAoB,CAAC;IAC7B,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B;;4EAEwE;IACxE,eAAe,CAAC,EAAE,mBAAmB,CAAC;CACvC;AAaD;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,GAAU,QAAQ,MAAM,KAAG,OAAO,CAAC,aAAa,CAmDtE,CAAC;AAEF,8EAA8E;AAC9E,eAAO,MAAM,kBAAkB,GAAU,QAAQ,MAAM,EAAE,QAAQ,oBAAoB,KAAG,OAAO,CAAC,MAAM,CAMrG,CAAC"}

package/dist/observe/observe.js

@@ -0,0 +1,73 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { reconcileEvents } from "@noopolis/stele";
+import { verifyManifestArtifacts } from "./artifacts.js";
+import { collectCausalStreams } from "./causalStreams.js";
+import { buildObserveReport } from "./compute.js";
+import { collectMemoryBankCounts } from "./memoryBanks.js";
+import { parseRunManifest } from "./manifest.js";
+import { computeSeedSpread, diffSeedSpreadAgainstLiveMarkerSeen } from "./seedSpread.js";
+import { readSpreadTranscriptMessages, readTickByIngestedMessageId, readSpreadMnemeEventsByBank } from "./seedSpreadArtifacts.js";
+const loadRunManifest = async (runDir) => {
+    const raw = JSON.parse(await readFile(path.join(runDir, "manifest.json"), "utf8"));
+    return parseRunManifest(raw);
+};
+const bankFromRelativePath = (relativePath) => {
+    // raw/mneme/<bank>/causal.jsonl
+    const segments = relativePath.split(path.sep);
+    return segments[0] === "raw" && segments[1] === "mneme" ? segments[2] : undefined;
+};
+/**
+ * Reads a sealed run directory (`manifest.json` + `raw/**\/causal.jsonl` +
+ * per-bank `raw/mneme/<bank>/events.jsonl`), reconciles the causal streams
+ * with `@noopolis/stele` (no stitching, ever — an incomplete chain is
+ * flagged, not synthesized), and emits the `simfile.observe.v1` report.
+ * Pure file-reading + reconciliation: no Docker, no compile, no runtime
+ * auth (this package's charter, `ecosystem/simfile/AGENTS.md`).
+ */
+export const runObserve = async (runDir) => {
+    const manifest = await loadRunManifest(runDir);
+    const artifactIntegrity = await verifyManifestArtifacts(runDir, manifest.artifacts);
+    const streams = await collectCausalStreams(runDir);
+    const causalParseErrors = streams.flatMap((stream) => stream.errors.map((error) => ({ relativePath: stream.relativePath, ...error })));
+    const allEvents = streams.flatMap((stream) => stream.events);
+    const reconciled = reconcileEvents(allEvents);
+    const eventsByBank = new Map();
+    for (const stream of streams) {
+        const bank = bankFromRelativePath(stream.relativePath);
+        if (!bank)
+            continue;
+        eventsByBank.set(bank, [...(eventsByBank.get(bank) ?? []), ...stream.events]);
+    }
+    const memoryBanks = await collectMemoryBankCounts(runDir, eventsByBank);
+    let seedSpread;
+    let spreadSelfCheck;
+    if (manifest.seed_declaration) {
+        const [transcriptMessages, mnemeEventsByBank, tickByMoltnetMessageId] = await Promise.all([
+            readSpreadTranscriptMessages(runDir),
+            readSpreadMnemeEventsByBank(runDir),
+            readTickByIngestedMessageId(runDir)
+        ]);
+        const causalEventsById = new Map(allEvents.map((event) => [event.event_id, event]));
+        seedSpread = computeSeedSpread({
+            seedDeclaration: manifest.seed_declaration,
+            causalEventsById,
+            transcriptMessages,
+            causalEventsByBank: eventsByBank,
+            mnemeEventsByBank,
+            tickByMoltnetMessageId
+        });
+        const worldEvents = streams.filter((stream) => stream.authority === "world").flatMap((stream) => stream.events);
+        spreadSelfCheck = diffSeedSpreadAgainstLiveMarkerSeen(worldEvents, transcriptMessages, manifest.seed_declaration.token_set, manifest.seed_declaration.matcher_policy);
+    }
+    const report = buildObserveReport({ allEvents, manifest, memoryBanks, reconciled, seedSpread });
+    return { artifactIntegrity, causalParseErrors, manifest, report, streams, spreadSelfCheck };
+};
+/** Writes `observe/report.json` under the run directory; returns its path. */
+export const writeObserveReport = async (runDir, report) => {
+    const observeDir = path.join(runDir, "observe");
+    await mkdir(observeDir, { recursive: true });
+    const reportPath = path.join(observeDir, "report.json");
+    await writeFile(reportPath, `${JSON.stringify(report, null, 2)}\n`, "utf8");
+    return reportPath;
+};