simfile 0.0.1

package/dist/observe/report.d.ts

@@ -0,0 +1,165 @@
+import { z } from "zod";
+/**
+ * `simfile.observe.v1` — the report `simfile observe <run-dir>` emits
+ * (Decision 21 / contracts.md's `simfile.observe.v1` row, the one contract
+ * id: `spawnfile.spread-report.v1` is a removed alias, never revived here).
+ * `seed_spread`, `spread_summary`, and `wake_diff` are DEFINED-BUT-OPTIONAL
+ * and omitted for the office-sim golden fixture (no seeded secret, no
+ * compiled wake schedule); memetics increment (b) populates `seed_spread`/
+ * `spread_summary` for a seed-declared run without a v2 bump.
+ */
+export declare const OBSERVE_REPORT_VERSION: "simfile.observe.v1";
+/** Precedence order matches `@noopolis/stele`'s `reconcileEvents` states,
+ * minus "complete" (that count lives in `chains.complete`, not the flagged list). */
+export declare const INCOMPLETE_CHAIN_FLAGS: readonly ["divergent", "unknown", "partial", "stale"];
+export type IncompleteChainFlag = (typeof INCOMPLETE_CHAIN_FLAGS)[number];
+/**
+ * Where `memory.events` (the write-count proxy) for a bank came from —
+ * Slice B Piece 4b. `"ledger"` means at least one `memory.written` causal
+ * event was reconciled for the bank (mneme's write-side envelope);
+ * `"events-fallback"` means the count instead came from the interim signal
+ * (mneme's own `events.jsonl` bank log, or that bank's `memory.recalled`
+ * causal events if even that is absent). Optional so a pre-4b serialized
+ * report (no source marker at all) still validates.
+ */
+export declare const MEMORY_WRITE_SOURCES: readonly ["ledger", "events-fallback"];
+export type MemoryWriteSource = (typeof MEMORY_WRITE_SOURCES)[number];
+/** `doc-seeded` is added (contracts.md) so a seed's entry channel is
+ * representable and never misclassified as spontaneous invention. */
+export declare const SEED_SPREAD_CHANNELS: readonly ["doc-seeded", "uttered", "registered", "recalled"];
+export type SeedSpreadChannel = (typeof SEED_SPREAD_CHANNELS)[number];
+/**
+ * Memetics increment (b): `agent`/`tick`/`memory_write_source` are a
+ * compatible v1 amendment (`seed_spread` was frozen DEFINED-BUT-OPTIONAL
+ * precisely so a later phase could grow the entry shape without a v2 bump).
+ * `agent` is the principal simfile observe attributes the hit to (never the
+ * seed agent for a `doc-seeded` entry's own later channels — reach/latency
+ * math excludes the seed agent, this field alone doesn't). `tick` is the
+ * world's own tick counter, joined from `world/ingested-messages.jsonl`
+ * (an `uttered` hit) or traced back to the moltnet message that caused it
+ * (a `registered`/`recalled` hit whose ledger event chains back that far) —
+ * never fabricated; omitted when no such join exists. `memory_write_source`
+ * mirrors `MemoryWriteSource` (Slice B Piece 4b) but scoped to this single
+ * `registered` hit, not a whole bank.
+ */
+declare const seedSpreadSchema: z.ZodObject<{
+    channel: z.ZodEnum<{
+        "doc-seeded": "doc-seeded";
+        uttered: "uttered";
+        registered: "registered";
+        recalled: "recalled";
+    }>;
+    event_id: z.ZodString;
+    fidelity: z.ZodOptional<z.ZodNumber>;
+    agent: z.ZodOptional<z.ZodString>;
+    tick: z.ZodOptional<z.ZodNumber>;
+    memory_write_source: z.ZodOptional<z.ZodEnum<{
+        ledger: "ledger";
+        "events-fallback": "events-fallback";
+    }>>;
+}, z.core.$strict>;
+export type SeedSpreadEntry = z.infer<typeof seedSpreadSchema>;
+/**
+ * The smallest honest summary of `seed_spread` (memetics increment (b)):
+ * `reach` counts non-seed agents with any post-seed appearance; `latency`
+ * is the lowest known `tick` among those appearances (omitted when no
+ * appearance carries a `tick`) — ticks/causal steps from the seed epoch to
+ * first spread, never wall-clock. Derivable from `seed_spread` alone, but
+ * kept as its own field so a consumer (the viewer) doesn't have to
+ * re-implement the derivation.
+ */
+declare const spreadSummarySchema: z.ZodObject<{
+    reach: z.ZodNumber;
+    latency: z.ZodOptional<z.ZodNumber>;
+    first_appearance: z.ZodArray<z.ZodObject<{
+        agent: z.ZodString;
+        channel: z.ZodEnum<{
+            "doc-seeded": "doc-seeded";
+            uttered: "uttered";
+            registered: "registered";
+            recalled: "recalled";
+        }>;
+        event_id: z.ZodString;
+        tick: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type SpreadSummary = z.infer<typeof spreadSummarySchema>;
+export declare const observeReportSchema: z.ZodObject<{
+    version: z.ZodLiteral<"simfile.observe.v1">;
+    run_id: z.ZodString;
+    contract_versions: z.ZodRecord<z.ZodString, z.ZodString>;
+    participants: z.ZodArray<z.ZodString>;
+    agent_turns: z.ZodObject<{
+        count: z.ZodNumber;
+        sequence: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>;
+    chains: z.ZodObject<{
+        complete: z.ZodNumber;
+        incomplete: z.ZodArray<z.ZodObject<{
+            event_id: z.ZodString;
+            flag: z.ZodEnum<{
+                unknown: "unknown";
+                divergent: "divergent";
+                partial: "partial";
+                stale: "stale";
+            }>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    memory: z.ZodArray<z.ZodObject<{
+        bank: z.ZodString;
+        events: z.ZodNumber;
+        recalls: z.ZodNumber;
+        memory_write_source: z.ZodOptional<z.ZodEnum<{
+            ledger: "ledger";
+            "events-fallback": "events-fallback";
+        }>>;
+        writes_by_agent: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    }, z.core.$strict>>;
+    failures: z.ZodArray<z.ZodObject<{
+        reason: z.ZodString;
+        event_id: z.ZodString;
+    }, z.core.$strict>>;
+    seed_spread: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        channel: z.ZodEnum<{
+            "doc-seeded": "doc-seeded";
+            uttered: "uttered";
+            registered: "registered";
+            recalled: "recalled";
+        }>;
+        event_id: z.ZodString;
+        fidelity: z.ZodOptional<z.ZodNumber>;
+        agent: z.ZodOptional<z.ZodString>;
+        tick: z.ZodOptional<z.ZodNumber>;
+        memory_write_source: z.ZodOptional<z.ZodEnum<{
+            ledger: "ledger";
+            "events-fallback": "events-fallback";
+        }>>;
+    }, z.core.$strict>>>;
+    spread_summary: z.ZodOptional<z.ZodObject<{
+        reach: z.ZodNumber;
+        latency: z.ZodOptional<z.ZodNumber>;
+        first_appearance: z.ZodArray<z.ZodObject<{
+            agent: z.ZodString;
+            channel: z.ZodEnum<{
+                "doc-seeded": "doc-seeded";
+                uttered: "uttered";
+                registered: "registered";
+                recalled: "recalled";
+            }>;
+            event_id: z.ZodString;
+            tick: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    wake_diff: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        agent_id: z.ZodString;
+        wake_id: z.ZodString;
+        status: z.ZodEnum<{
+            delivered: "delivered";
+            "wake-not-delivered": "wake-not-delivered";
+        }>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type SimfileObserveReport = z.infer<typeof observeReportSchema>;
+export declare const parseObserveReport: (raw: unknown) => SimfileObserveReport;
+export {};
+//# sourceMappingURL=report.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../src/observe/report.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,EAAG,oBAA6B,CAAC;AAEpE;qFACqF;AACrF,eAAO,MAAM,sBAAsB,uDAAwD,CAAC;AAC5F,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAS1E;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,wCAAyC,CAAC;AAC3E,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAmBtE;qEACqE;AACrE,eAAO,MAAM,oBAAoB,8DAA+D,CAAC;AACjG,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtE;;;;;;;;;;;;;GAaG;AACH,QAAA,MAAM,gBAAgB;;;;;;;;;;;;;;;kBASX,CAAC;AAEZ,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAY/D;;;;;;;;GAQG;AACH,QAAA,MAAM,mBAAmB;;;;;;;;;;;;;;kBAMd,CAAC;AAEZ,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAUhE,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAwBrB,CAAC;AAEZ,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEvE,eAAO,MAAM,kBAAkB,GAAI,KAAK,OAAO,KAAG,oBAUjD,CAAC"}

package/dist/observe/report.js

@@ -0,0 +1,138 @@
+import { z } from "zod";
+/**
+ * `simfile.observe.v1` — the report `simfile observe <run-dir>` emits
+ * (Decision 21 / contracts.md's `simfile.observe.v1` row, the one contract
+ * id: `spawnfile.spread-report.v1` is a removed alias, never revived here).
+ * `seed_spread`, `spread_summary`, and `wake_diff` are DEFINED-BUT-OPTIONAL
+ * and omitted for the office-sim golden fixture (no seeded secret, no
+ * compiled wake schedule); memetics increment (b) populates `seed_spread`/
+ * `spread_summary` for a seed-declared run without a v2 bump.
+ */
+export const OBSERVE_REPORT_VERSION = "simfile.observe.v1";
+/** Precedence order matches `@noopolis/stele`'s `reconcileEvents` states,
+ * minus "complete" (that count lives in `chains.complete`, not the flagged list). */
+export const INCOMPLETE_CHAIN_FLAGS = ["divergent", "unknown", "partial", "stale"];
+const incompleteChainEntrySchema = z
+    .object({
+    event_id: z.string().min(1),
+    flag: z.enum(INCOMPLETE_CHAIN_FLAGS)
+})
+    .strict();
+/**
+ * Where `memory.events` (the write-count proxy) for a bank came from —
+ * Slice B Piece 4b. `"ledger"` means at least one `memory.written` causal
+ * event was reconciled for the bank (mneme's write-side envelope);
+ * `"events-fallback"` means the count instead came from the interim signal
+ * (mneme's own `events.jsonl` bank log, or that bank's `memory.recalled`
+ * causal events if even that is absent). Optional so a pre-4b serialized
+ * report (no source marker at all) still validates.
+ */
+export const MEMORY_WRITE_SOURCES = ["ledger", "events-fallback"];
+const memoryBankEntrySchema = z
+    .object({
+    bank: z.string().min(1),
+    events: z.number().int().min(0),
+    recalls: z.number().int().min(0),
+    memory_write_source: z.enum(MEMORY_WRITE_SOURCES).optional(),
+    writes_by_agent: z.record(z.string(), z.number().int().min(0)).optional()
+})
+    .strict();
+const failureEntrySchema = z
+    .object({
+    reason: z.string().min(1),
+    event_id: z.string().min(1)
+})
+    .strict();
+/** `doc-seeded` is added (contracts.md) so a seed's entry channel is
+ * representable and never misclassified as spontaneous invention. */
+export const SEED_SPREAD_CHANNELS = ["doc-seeded", "uttered", "registered", "recalled"];
+/**
+ * Memetics increment (b): `agent`/`tick`/`memory_write_source` are a
+ * compatible v1 amendment (`seed_spread` was frozen DEFINED-BUT-OPTIONAL
+ * precisely so a later phase could grow the entry shape without a v2 bump).
+ * `agent` is the principal simfile observe attributes the hit to (never the
+ * seed agent for a `doc-seeded` entry's own later channels — reach/latency
+ * math excludes the seed agent, this field alone doesn't). `tick` is the
+ * world's own tick counter, joined from `world/ingested-messages.jsonl`
+ * (an `uttered` hit) or traced back to the moltnet message that caused it
+ * (a `registered`/`recalled` hit whose ledger event chains back that far) —
+ * never fabricated; omitted when no such join exists. `memory_write_source`
+ * mirrors `MemoryWriteSource` (Slice B Piece 4b) but scoped to this single
+ * `registered` hit, not a whole bank.
+ */
+const seedSpreadSchema = z
+    .object({
+    channel: z.enum(SEED_SPREAD_CHANNELS),
+    event_id: z.string().min(1),
+    fidelity: z.number().min(0).max(1).optional(),
+    agent: z.string().min(1).optional(),
+    tick: z.number().int().min(0).optional(),
+    memory_write_source: z.enum(MEMORY_WRITE_SOURCES).optional()
+})
+    .strict();
+/** One non-seed agent's earliest re-derived appearance, across every channel. */
+const spreadFirstAppearanceSchema = z
+    .object({
+    agent: z.string().min(1),
+    channel: z.enum(SEED_SPREAD_CHANNELS),
+    event_id: z.string().min(1),
+    tick: z.number().int().min(0).optional()
+})
+    .strict();
+/**
+ * The smallest honest summary of `seed_spread` (memetics increment (b)):
+ * `reach` counts non-seed agents with any post-seed appearance; `latency`
+ * is the lowest known `tick` among those appearances (omitted when no
+ * appearance carries a `tick`) — ticks/causal steps from the seed epoch to
+ * first spread, never wall-clock. Derivable from `seed_spread` alone, but
+ * kept as its own field so a consumer (the viewer) doesn't have to
+ * re-implement the derivation.
+ */
+const spreadSummarySchema = z
+    .object({
+    reach: z.number().int().min(0),
+    latency: z.number().int().min(0).optional(),
+    first_appearance: z.array(spreadFirstAppearanceSchema)
+})
+    .strict();
+const wakeDiffEntrySchema = z
+    .object({
+    agent_id: z.string().min(1),
+    wake_id: z.string().min(1),
+    status: z.enum(["delivered", "wake-not-delivered"])
+})
+    .strict();
+export const observeReportSchema = z
+    .object({
+    version: z.literal(OBSERVE_REPORT_VERSION),
+    run_id: z.string().min(1),
+    contract_versions: z.record(z.string(), z.string()),
+    participants: z.array(z.string().min(1)),
+    agent_turns: z
+        .object({
+        count: z.number().int().min(0),
+        sequence: z.array(z.string().min(1))
+    })
+        .strict(),
+    chains: z
+        .object({
+        complete: z.number().int().min(0),
+        incomplete: z.array(incompleteChainEntrySchema)
+    })
+        .strict(),
+    memory: z.array(memoryBankEntrySchema),
+    failures: z.array(failureEntrySchema),
+    seed_spread: z.array(seedSpreadSchema).optional(),
+    spread_summary: spreadSummarySchema.optional(),
+    wake_diff: z.array(wakeDiffEntrySchema).optional()
+})
+    .strict();
+export const parseObserveReport = (raw) => {
+    const result = observeReportSchema.safeParse(raw);
+    if (!result.success) {
+        throw new Error(`invalid ${OBSERVE_REPORT_VERSION} report: ${result.error.issues
+            .map((issue) => `${issue.path.join(".") || "<root>"}: ${issue.message}`)
+            .join("; ")}`);
+    }
+    return result.data;
+};

package/dist/observe/seedSpread.d.ts

@@ -0,0 +1,49 @@
+import type { CausalEvent } from "@noopolis/stele";
+import type { SeedDeclaration } from "./manifest.js";
+import type { SeedSpreadEntry, SpreadSummary } from "./report.js";
+import type { SpreadMnemeEvent, SpreadTranscriptMessage } from "./seedSpreadArtifacts.js";
+export interface SeedSpreadExcluded {
+    event_id: string;
+    reason: string;
+}
+export interface SeedSpreadComputeInput {
+    seedDeclaration: SeedDeclaration;
+    /** Every collected causal event across every authority, keyed by `event_id` — the
+     * cross-stream join surface `deriveTick`'s backward trace walks. */
+    causalEventsById: ReadonlyMap<string, CausalEvent>;
+    transcriptMessages: readonly SpreadTranscriptMessage[];
+    /** Per-bank `raw/mneme/<bank>/causal.jsonl` events, as `observe.ts` already groups them. */
+    causalEventsByBank: ReadonlyMap<string, readonly CausalEvent[]>;
+    /** Per-bank `raw/mneme/<bank>/events.jsonl` rows (the write-side/interim signal). */
+    mnemeEventsByBank: ReadonlyMap<string, readonly SpreadMnemeEvent[]>;
+    /** `world/ingested-messages.jsonl`'s `message_id -> tick` join; empty for a non-world-driven run. */
+    tickByMoltnetMessageId: ReadonlyMap<string, number>;
+}
+export interface SeedSpreadComputeResult {
+    entries: SeedSpreadEntry[];
+    excluded: SeedSpreadExcluded[];
+    summary: SpreadSummary;
+}
+export declare const computeSeedSpread: (input: SeedSpreadComputeInput) => SeedSpreadComputeResult;
+export interface SeedSpreadSelfCheck {
+    /** Moltnet message ids the live world loop's own `marker.seen` flagged. */
+    liveHitMessageIds: string[];
+    /** Moltnet message ids this module's re-derivation flagged as `uttered` (including excluded ones). */
+    derivedHitMessageIds: string[];
+    /** Present in the live loop's `marker.seen` set but not re-derived here. */
+    onlyLive: string[];
+    /** Re-derived here but never flagged by the live loop's `marker.seen`. */
+    onlyDerived: string[];
+    matches: boolean;
+}
+/**
+ * Diagnostic only, never authoritative (`worldTickLoop.ts`'s own doc
+ * comment: the live loop's `marker.seen` is polling-order, not causal
+ * order). Compares the set of Moltnet message ids the live loop flagged
+ * against this module's independently re-derived `uttered` hits (both
+ * excluded and counted ones — exclusion is instrument hygiene, not evidence
+ * the live loop wouldn't have also flagged the same message) and reports
+ * any mismatch rather than silently trusting either side.
+ */
+export declare const diffSeedSpreadAgainstLiveMarkerSeen: (worldEvents: readonly CausalEvent[], transcriptMessages: readonly SpreadTranscriptMessage[], tokenSet: readonly string[], matcherPolicy?: string) => SeedSpreadSelfCheck;
+//# sourceMappingURL=seedSpread.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"seedSpread.d.ts","sourceRoot":"","sources":["../../src/observe/seedSpread.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EAAqB,eAAe,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACrF,OAAO,KAAK,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AA4B1F,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,sBAAsB;IACrC,eAAe,EAAE,eAAe,CAAC;IACjC;wEACoE;IACpE,gBAAgB,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACnD,kBAAkB,EAAE,SAAS,uBAAuB,EAAE,CAAC;IACvD,4FAA4F;IAC5F,kBAAkB,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,CAAC,CAAC;IAChE,qFAAqF;IACrF,iBAAiB,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,gBAAgB,EAAE,CAAC,CAAC;IACpE,qGAAqG;IACrG,sBAAsB,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrD;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,QAAQ,EAAE,kBAAkB,EAAE,CAAC;IAC/B,OAAO,EAAE,aAAa,CAAC;CACxB;AA4PD,eAAO,MAAM,iBAAiB,GAAI,OAAO,sBAAsB,KAAG,uBAYjE,CAAC;AAEF,MAAM,WAAW,mBAAmB;IAClC,2EAA2E;IAC3E,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,sGAAsG;IACtG,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAC/B,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,0EAA0E;IAC1E,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,mCAAmC,GAC9C,aAAa,SAAS,WAAW,EAAE,EACnC,oBAAoB,SAAS,uBAAuB,EAAE,EACtD,UAAU,SAAS,MAAM,EAAE,EAC3B,sBAAuB,KACtB,mBAyBF,CAAC"}

package/dist/observe/seedSpread.js

@@ -0,0 +1,262 @@
+import { matchSeedSpread, parseSpreadMatcherPolicy } from "./spreadMatcher.js";
+/**
+ * Memetics increment (b): re-derives `seed_spread` from sealed artifacts +
+ * `manifest.seed_declaration`, never from the live world loop's own
+ * `marker.seen` events (`worldTickLoop.ts`'s own doc comment: polling order
+ * ≠ causal order — see `diffSeedSpreadAgainstLiveMarkerSeen` below for the
+ * self-check that DOES read `marker.seen`, but only to report a mismatch,
+ * never to feed `seed_spread` itself).
+ *
+ * Honesty rules enforced here (never hand-waved):
+ * - `turn.input.submitted` payloads are never scanned — a token appearing in
+ *   an agent's prompt is exposure, not expression.
+ * - Any hit whose actor is `world` or `operator:<agent>` is excluded from
+ *   `seed_spread` and reported instead as a `failures[]` entry (instrument
+ *   error or containment violation, never agent spread).
+ * - The one `doc-seeded` entry is taken verbatim from the manifest, never
+ *   scanned for.
+ */
+const AGENT_PRINCIPAL_PATTERN = /^agent:(.+)$/u;
+const isInstrumentOrOperatorActor = (actor) => actor === "world" || (actor?.startsWith("operator:") ?? false);
+const matchTokenSet = (text, tokenSet, matcherPolicy) => matchSeedSpread(text, tokenSet, matcherPolicy);
+const agentIdFromPrincipal = (principalId) => AGENT_PRINCIPAL_PATTERN.exec(principalId)?.[1];
+const stringPayloadField = (event, field) => {
+    const value = event.payload?.[field];
+    return typeof value === "string" ? value : undefined;
+};
+/**
+ * Walks `event_id`'s `cause_event_ids` backward (bounded depth) looking for
+ * a `moltnet` `message.accepted` event on each branch — stopping the moment
+ * one is found (never recursing past it). Real cause chains only, never a
+ * synthesized or wall-clock-ordered link: this is how a `registered`
+ * (ledger-path) or `recalled` hit gets an honest `tick` without a direct
+ * one-hop join.
+ */
+const traceBackToMoltnetMessageIds = (eventId, byId, maxDepth = 6) => {
+    const start = byId.get(eventId);
+    if (!start)
+        return [];
+    const found = new Set();
+    const seen = new Set([eventId]);
+    const stack = start.cause_event_ids.map((id) => ({ id, depth: 1 }));
+    while (stack.length > 0) {
+        const next = stack.pop();
+        if (!next || seen.has(next.id) || next.depth > maxDepth)
+            continue;
+        seen.add(next.id);
+        const event = byId.get(next.id);
+        if (!event)
+            continue;
+        if (event.emitter.system === "moltnet" && event.type === "message.accepted") {
+            found.add(stringPayloadField(event, "message_id") ?? event.event_id);
+            continue;
+        }
+        for (const cause of event.cause_event_ids)
+            stack.push({ id: cause, depth: next.depth + 1 });
+    }
+    return [...found];
+};
+const deriveTick = (event, byId, tickByMessageId) => {
+    if (!event)
+        return undefined;
+    if (event.emitter.system === "moltnet" && event.type === "message.accepted") {
+        const messageId = stringPayloadField(event, "message_id");
+        return messageId ? tickByMessageId.get(messageId) : undefined;
+    }
+    const ticks = traceBackToMoltnetMessageIds(event.event_id, byId)
+        .map((messageId) => tickByMessageId.get(messageId))
+        .filter((tick) => tick !== undefined);
+    return ticks.length > 0 ? Math.min(...ticks) : undefined;
+};
+const docSeededEntry = (seed) => ({
+    channel: "doc-seeded",
+    event_id: `doc-seed:${seed.seed_agent}:${seed.seed_epoch}`,
+    fidelity: 1,
+    agent: seed.seed_agent
+});
+const computeUtteredEntries = (input, matcherPolicy) => {
+    const entries = [];
+    const excluded = [];
+    const messageAcceptedByMessageId = new Map();
+    for (const event of input.causalEventsById.values()) {
+        if (event.emitter.system !== "moltnet" || event.type !== "message.accepted")
+            continue;
+        const messageId = stringPayloadField(event, "message_id");
+        if (messageId)
+            messageAcceptedByMessageId.set(messageId, event);
+    }
+    for (const message of input.transcriptMessages) {
+        const match = matchTokenSet(message.text, input.seedDeclaration.token_set, matcherPolicy);
+        if (!match.matched)
+            continue;
+        const causal = messageAcceptedByMessageId.get(message.id);
+        const eventId = causal?.event_id ?? message.id;
+        if (isInstrumentOrOperatorActor(message.fromId)) {
+            excluded.push({
+                event_id: eventId,
+                reason: `seed-spread: excluded uttered hit from instrument/operator actor "${message.fromId}" — never counted as agent spread`
+            });
+            continue;
+        }
+        entries.push({
+            channel: "uttered",
+            event_id: eventId,
+            fidelity: match.fidelity,
+            ...(message.fromId ? { agent: message.fromId } : {}),
+            ...(() => {
+                const tick = deriveTick(causal, input.causalEventsById, input.tickByMoltnetMessageId);
+                return tick === undefined ? {} : { tick };
+            })()
+        });
+    }
+    return { entries, excluded };
+};
+const computeRegisteredEntries = (input, matcherPolicy) => {
+    const entries = [];
+    const excluded = [];
+    for (const [bank, bankEvents] of input.mnemeEventsByBank) {
+        const bankCausal = input.causalEventsByBank.get(bank) ?? [];
+        const writtenByMemoryId = new Map();
+        for (const event of bankCausal) {
+            if (event.type !== "memory.written")
+                continue;
+            const memoryId = stringPayloadField(event, "memory_id");
+            if (memoryId)
+                writtenByMemoryId.set(memoryId, event);
+        }
+        for (const bankEvent of bankEvents) {
+            // Recalls get their own channel below, from the causal `memory.recalled`
+            // stream — never double-counted here as a registration.
+            if (bankEvent.type === "memory.recalled")
+                continue;
+            const match = matchTokenSet(bankEvent.text, input.seedDeclaration.token_set, matcherPolicy);
+            if (!match.matched)
+                continue;
+            const ledgerEvent = writtenByMemoryId.get(bankEvent.id);
+            const eventId = ledgerEvent?.event_id ?? bankEvent.id;
+            if (isInstrumentOrOperatorActor(bankEvent.agentId)) {
+                excluded.push({
+                    event_id: eventId,
+                    reason: `seed-spread: excluded registered hit from instrument/operator actor "${bankEvent.agentId}" — never counted as agent spread`
+                });
+                continue;
+            }
+            const tick = ledgerEvent ? deriveTick(ledgerEvent, input.causalEventsById, input.tickByMoltnetMessageId) : undefined;
+            entries.push({
+                channel: "registered",
+                event_id: eventId,
+                fidelity: match.fidelity,
+                ...(bankEvent.agentId ? { agent: bankEvent.agentId } : {}),
+                ...(tick === undefined ? {} : { tick }),
+                memory_write_source: ledgerEvent ? "ledger" : "events-fallback"
+            });
+        }
+    }
+    return { entries, excluded };
+};
+const computeRecalledEntries = (input, matcherPolicy) => {
+    const entries = [];
+    const excluded = [];
+    for (const [bank, bankEvents] of input.mnemeEventsByBank) {
+        const bankCausal = input.causalEventsByBank.get(bank) ?? [];
+        const contentById = new Map(bankEvents.map((event) => [event.id, event.text]));
+        for (const event of bankCausal) {
+            if (event.type !== "memory.recalled")
+                continue;
+            const memoryId = stringPayloadField(event, "memory_id");
+            const text = memoryId ? contentById.get(memoryId) : undefined;
+            if (text === undefined)
+                continue;
+            const match = matchTokenSet(text, input.seedDeclaration.token_set, matcherPolicy);
+            if (!match.matched)
+                continue;
+            const agent = agentIdFromPrincipal(event.principal_id);
+            if (isInstrumentOrOperatorActor(agent ?? event.principal_id)) {
+                excluded.push({
+                    event_id: event.event_id,
+                    reason: `seed-spread: excluded recalled hit from instrument/operator principal "${event.principal_id}" — never counted as agent spread`
+                });
+                continue;
+            }
+            const tick = deriveTick(event, input.causalEventsById, input.tickByMoltnetMessageId);
+            entries.push({
+                channel: "recalled",
+                event_id: event.event_id,
+                fidelity: match.fidelity,
+                ...(agent ? { agent } : {}),
+                ...(tick === undefined ? {} : { tick })
+            });
+        }
+    }
+    return { entries, excluded };
+};
+const computeSummary = (entries, seedAgent) => {
+    const firstAppearanceByAgent = new Map();
+    for (const entry of entries) {
+        if (entry.channel === "doc-seeded" || !entry.agent || entry.agent === seedAgent)
+            continue;
+        const existing = firstAppearanceByAgent.get(entry.agent);
+        if (!existing) {
+            firstAppearanceByAgent.set(entry.agent, { channel: entry.channel, event_id: entry.event_id, tick: entry.tick });
+            continue;
+        }
+        // Prefer whichever appearance carries the lower known tick; keep the
+        // first-seen entry when neither (or both equally) carries one.
+        if (entry.tick !== undefined && (existing.tick === undefined || entry.tick < existing.tick)) {
+            firstAppearanceByAgent.set(entry.agent, { channel: entry.channel, event_id: entry.event_id, tick: entry.tick });
+        }
+    }
+    const firstAppearance = [...firstAppearanceByAgent.entries()]
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([agent, appearance]) => ({
+        agent,
+        channel: appearance.channel,
+        event_id: appearance.event_id,
+        ...(appearance.tick === undefined ? {} : { tick: appearance.tick })
+    }));
+    const knownTicks = firstAppearance.map((entry) => entry.tick).filter((tick) => tick !== undefined);
+    return {
+        reach: firstAppearance.length,
+        ...(knownTicks.length > 0 ? { latency: Math.min(...knownTicks) } : {}),
+        first_appearance: firstAppearance
+    };
+};
+export const computeSeedSpread = (input) => {
+    // Resolve once before scanning so an unsupported pinned policy fails even
+    // when the run has no transcript messages or memory content.
+    const matcherPolicy = parseSpreadMatcherPolicy(input.seedDeclaration.matcher_policy);
+    const uttered = computeUtteredEntries(input, matcherPolicy);
+    const registered = computeRegisteredEntries(input, matcherPolicy);
+    const recalled = computeRecalledEntries(input, matcherPolicy);
+    const entries = [docSeededEntry(input.seedDeclaration), ...uttered.entries, ...registered.entries, ...recalled.entries];
+    const excluded = [...uttered.excluded, ...registered.excluded, ...recalled.excluded];
+    return { entries, excluded, summary: computeSummary(entries, input.seedDeclaration.seed_agent) };
+};
+/**
+ * Diagnostic only, never authoritative (`worldTickLoop.ts`'s own doc
+ * comment: the live loop's `marker.seen` is polling-order, not causal
+ * order). Compares the set of Moltnet message ids the live loop flagged
+ * against this module's independently re-derived `uttered` hits (both
+ * excluded and counted ones — exclusion is instrument hygiene, not evidence
+ * the live loop wouldn't have also flagged the same message) and reports
+ * any mismatch rather than silently trusting either side.
+ */
+export const diffSeedSpreadAgainstLiveMarkerSeen = (worldEvents, transcriptMessages, tokenSet, matcherPolicy = "exact") => {
+    const parsedMatcherPolicy = parseSpreadMatcherPolicy(matcherPolicy);
+    const liveHitMessageIds = [
+        ...new Set(worldEvents
+            .filter((event) => event.type === "marker.seen")
+            .map((event) => stringPayloadField(event, "source_event_id"))
+            .filter((id) => id !== undefined))
+    ].sort();
+    const derivedHitMessageIds = [
+        ...new Set(transcriptMessages
+            .filter((message) => matchTokenSet(message.text, tokenSet, parsedMatcherPolicy).matched)
+            .map((message) => message.id))
+    ].sort();
+    const liveSet = new Set(liveHitMessageIds);
+    const derivedSet = new Set(derivedHitMessageIds);
+    const onlyLive = liveHitMessageIds.filter((id) => !derivedSet.has(id));
+    const onlyDerived = derivedHitMessageIds.filter((id) => !liveSet.has(id));
+    return { liveHitMessageIds, derivedHitMessageIds, onlyLive, onlyDerived, matches: onlyLive.length === 0 && onlyDerived.length === 0 };
+};

package/dist/observe/seedSpreadArtifacts.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Memetics increment (b): the extra sealed-artifact reads `seedSpread.ts`'s
+ * re-derivation needs, on top of what `causalStreams.ts`/`memoryBanks.ts`
+ * already collect. Kept as its own I/O-only module (this folder's own rule:
+ * `compute.ts`-style pure functions never touch the filesystem) so
+ * `seedSpread.ts` stays a pure function of already-loaded data, matching
+ * `memoryBanks.ts`/`causalStreams.ts`'s split.
+ */
+export interface SpreadTranscriptMessage {
+    id: string;
+    fromId?: string;
+    text: string;
+}
+export interface SpreadMnemeEvent {
+    id: string;
+    type: string;
+    agentId?: string;
+    text: string;
+}
+/**
+ * Reads every `transcript.json` under `<runDir>/raw/moltnet/**` (today a
+ * single file; globbed so a future multi-network export nesting transcripts
+ * per network/room still gets picked up) and flattens every conversation's
+ * messages to `{id, fromId, text}`. Only the `moltnet.transcript-export.v1`
+ * export shape (`{conversations:[{messages}]}`) is read here — the seed-spread
+ * path only ever runs against a real composed/world-driven run, never the
+ * hand-authored golden-fixture shape (which never carries `seed_declaration`).
+ */
+export declare const readSpreadTranscriptMessages: (runDir: string) => Promise<SpreadTranscriptMessage[]>;
+/**
+ * Reads every mneme bank's `events.jsonl` (the write-side/interim signal —
+ * same file `memoryBanks.ts` falls back to) into `{id, type, agentId, text}`,
+ * keyed by bank directory name. Every field is read verbatim from the
+ * sealed file; a malformed line is skipped rather than crashing the whole
+ * read (mirrors this folder's "report, don't stitch" posture for a
+ * diagnostic-only artifact).
+ */
+export declare const readSpreadMnemeEventsByBank: (runDir: string) => Promise<Map<string, SpreadMnemeEvent[]>>;
+/**
+ * Reads `<runDir>/world/ingested-messages.jsonl` (note: NOT under `raw/` —
+ * `worldLedgerWriter.ts`'s own diagnostic, one line per tick,
+ * `{tick, message_ids}`) into a `message_id -> tick` map: the one exact,
+ * non-wall-clock fact the live world loop recorded about when it folded a
+ * given Moltnet message into the run. Absent entirely for a run that wasn't
+ * world-driven (batch `composedOfficeSimDriver`-style runs never write this
+ * file) — returns an empty map rather than failing.
+ */
+export declare const readTickByIngestedMessageId: (runDir: string) => Promise<Map<string, number>>;
+//# sourceMappingURL=seedSpreadArtifacts.d.ts.map