@noopolis/daimon 0.1.1 → 0.1.2

package/dist/observability/causalEvents.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Daimon's own copy of the `noopolis.causal-event.v1` wire envelope. Field-
+ * for-field the canonical shape in `specs/causal-event.v1.schema.json` and
+ * `specs/CAUSAL.md` (root repo) — daimon is an independent repo and does not
+ * import that schema, it only conforms to it. The wire JSON emitted by
+ * `appendCausalEvent` is the actual contract; this type is local sugar over
+ * it.
+ */
+export declare const CAUSAL_EVENT_VERSION: "noopolis.causal-event.v1";
+export type CausalEventSystem = "simfile" | "moltnet" | "mneme" | "daimon";
+export interface CausalEventEmitter {
+    system: CausalEventSystem;
+    stream_id: string;
+    seq: number;
+}
+export interface CausalEvent<TPayload = Record<string, unknown>> {
+    cause_event_ids: string[];
+    emitter: CausalEventEmitter;
+    event_id: string;
+    payload: TPayload;
+    principal_id: string;
+    recorded_at: string;
+    run_id: string;
+    type: string;
+    version: typeof CAUSAL_EVENT_VERSION;
+}
+/** Payload for `turn.input.submitted`, stamped just before a Pi session prompt call. */
+export interface TurnInputSubmittedPayload extends Record<string, unknown> {
+    input_content_sha256: string;
+    input_message_ids: string[];
+    prompt_sha256: string;
+    turn_id: string;
+}
+/** Payload for `turn.output.completed`, stamped once a Pi turn finishes successfully. */
+export interface TurnOutputCompletedPayload extends Record<string, unknown> {
+    output_sha256: string;
+    turn_id: string;
+}
+export declare const TURN_INPUT_SUBMITTED_TYPE: "turn.input.submitted";
+export declare const TURN_OUTPUT_COMPLETED_TYPE: "turn.output.completed";
+/** Name of the environment variable every Noopolis authority reads `run_id` from. Never model output. */
+export declare const NOOPOLIS_RUN_ID_ENV = "NOOPOLIS_RUN_ID";
+/**
+ * Resolves `run_id` from the `NOOPOLIS_RUN_ID` environment variable, per
+ * `specs/CAUSAL.md`. Never derived from a WakeEvent, model output, or any
+ * other in-turn data. A causal event cannot be emitted without a real run id.
+ */
+export declare const resolveRunId: (env?: NodeJS.ProcessEnv) => string;
+export declare const sha256Hex: (value: string) => string;
+/** Deterministic, non-model-derived event id for a turn's `turn.input.submitted` record. */
+export declare const turnInputSubmittedEventId: (turnId: string) => string;
+/** Deterministic, non-model-derived event id for a turn's `turn.output.completed` record. */
+export declare const turnOutputCompletedEventId: (turnId: string) => string;
+/**
+ * The `cause_event_ids` an outbound Moltnet reply for `turnId` should carry.
+ * Pure and deterministic from `turn_id` alone — the harness owns this value,
+ * never the model. Daimon does not construct Moltnet `SendMessageRequest`
+ * values itself (see repo AGENTS.md: Moltnet wiring belongs to the caller,
+ * not this package), so this helper is what a caller sending the reply on
+ * Daimon's behalf attaches to that request's `cause_event_ids`.
+ */
+export declare const replyCauseEventIds: (turnId: string) => string[];
+/**
+ * Allocates the next contiguous seq number for `(run_id, stream_id)`,
+ * persisted under `runtimeHome/telemetry/causal.seq.json`. Daimon runs at
+ * most one wake at a time per agent (`PiAgentHandle.wakeQueue` serializes
+ * them), so read-modify-write here does not need extra locking.
+ */
+export declare const nextCausalSeq: (input: {
+    runId: string;
+    runtimeHomePath: string;
+    streamId: string;
+}) => Promise<number>;
+/** Appends one CausalEvent record as a line of `runtimeHome/telemetry/causal.jsonl`. */
+export declare const appendCausalEvent: (runtimeHomePath: string, event: CausalEvent) => Promise<void>;
+export interface EmitCausalEventInput<TPayload extends Record<string, unknown>> {
+    agentId: string;
+    causeEventIds: string[];
+    eventId: string;
+    payload: TPayload;
+    principalId: string;
+    runId: string;
+    runtimeHomePath: string;
+    type: string;
+}
+/**
+ * Stamps and appends one causal event for this agent's stream
+ * (`agent:<agentId>`). `run_id` and `principal_id` are always caller-
+ * supplied values (never read from `payload` or model output) — see
+ * `piHarness.ts`, which is the only caller and always passes the resolved
+ * `NOOPOLIS_RUN_ID` and the authenticated agent identity.
+ */
+export declare const emitCausalEvent: <TPayload extends Record<string, unknown>>(input: EmitCausalEventInput<TPayload>) => Promise<CausalEvent<TPayload>>;
+export interface EmitTurnInputSubmittedInput {
+    agentId: string;
+    causeEventIds: string[];
+    inputContentSha256: string;
+    inputMessageIds: string[];
+    principalId: string;
+    promptSha256: string;
+    runId: string;
+    runtimeHomePath: string;
+    turnId: string;
+}
+/** Stamps `turn.input.submitted` for one Pi turn, right before the engine prompt call. */
+export declare const emitTurnInputSubmitted: (input: EmitTurnInputSubmittedInput) => Promise<CausalEvent<TurnInputSubmittedPayload>>;
+export interface EmitTurnOutputCompletedInput {
+    agentId: string;
+    causeEventIds: string[];
+    outputSha256: string;
+    principalId: string;
+    runId: string;
+    runtimeHomePath: string;
+    turnId: string;
+}
+/** Stamps `turn.output.completed` once a Pi turn finishes successfully. */
+export declare const emitTurnOutputCompleted: (input: EmitTurnOutputCompletedInput) => Promise<CausalEvent<TurnOutputCompletedPayload>>;
+//# sourceMappingURL=causalEvents.d.ts.map

package/dist/observability/causalEvents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"causalEvents.d.ts","sourceRoot":"","sources":["../../src/observability/causalEvents.ts"],"names":[],"mappings":"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"}

package/dist/observability/causalEvents.js

@@ -0,0 +1,135 @@
+import { createHash } from "node:crypto";
+import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+/**
+ * Daimon's own copy of the `noopolis.causal-event.v1` wire envelope. Field-
+ * for-field the canonical shape in `specs/causal-event.v1.schema.json` and
+ * `specs/CAUSAL.md` (root repo) — daimon is an independent repo and does not
+ * import that schema, it only conforms to it. The wire JSON emitted by
+ * `appendCausalEvent` is the actual contract; this type is local sugar over
+ * it.
+ */
+export const CAUSAL_EVENT_VERSION = "noopolis.causal-event.v1";
+export const TURN_INPUT_SUBMITTED_TYPE = "turn.input.submitted";
+export const TURN_OUTPUT_COMPLETED_TYPE = "turn.output.completed";
+/** Name of the environment variable every Noopolis authority reads `run_id` from. Never model output. */
+export const NOOPOLIS_RUN_ID_ENV = "NOOPOLIS_RUN_ID";
+/**
+ * Resolves `run_id` from the `NOOPOLIS_RUN_ID` environment variable, per
+ * `specs/CAUSAL.md`. Never derived from a WakeEvent, model output, or any
+ * other in-turn data. A causal event cannot be emitted without a real run id.
+ */
+export const resolveRunId = (env = process.env) => {
+    const value = env[NOOPOLIS_RUN_ID_ENV];
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`${NOOPOLIS_RUN_ID_ENV} must be set to a non-blank value`);
+    }
+    return value.trim();
+};
+export const sha256Hex = (value) => createHash("sha256").update(value, "utf8").digest("hex");
+/** Deterministic, non-model-derived event id for a turn's `turn.input.submitted` record. */
+export const turnInputSubmittedEventId = (turnId) => `daimon:${turnId}:turn.input.submitted`;
+/** Deterministic, non-model-derived event id for a turn's `turn.output.completed` record. */
+export const turnOutputCompletedEventId = (turnId) => `daimon:${turnId}:turn.output.completed`;
+/**
+ * The `cause_event_ids` an outbound Moltnet reply for `turnId` should carry.
+ * Pure and deterministic from `turn_id` alone — the harness owns this value,
+ * never the model. Daimon does not construct Moltnet `SendMessageRequest`
+ * values itself (see repo AGENTS.md: Moltnet wiring belongs to the caller,
+ * not this package), so this helper is what a caller sending the reply on
+ * Daimon's behalf attaches to that request's `cause_event_ids`.
+ */
+export const replyCauseEventIds = (turnId) => [turnOutputCompletedEventId(turnId)];
+const telemetryDir = (runtimeHomePath) => path.join(runtimeHomePath, "telemetry");
+const seqFilePath = (runtimeHomePath) => path.join(telemetryDir(runtimeHomePath), "causal.seq.json");
+const jsonlFilePath = (runtimeHomePath) => path.join(telemetryDir(runtimeHomePath), "causal.jsonl");
+const readSeqStore = async (runtimeHomePath) => {
+    try {
+        const raw = await readFile(seqFilePath(runtimeHomePath), "utf8");
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+            return {};
+        }
+        throw error;
+    }
+};
+const writeSeqStore = async (runtimeHomePath, store) => {
+    await mkdir(telemetryDir(runtimeHomePath), { recursive: true });
+    await writeFile(seqFilePath(runtimeHomePath), `${JSON.stringify(store, null, 2)}\n`, "utf8");
+};
+/**
+ * Allocates the next contiguous seq number for `(run_id, stream_id)`,
+ * persisted under `runtimeHome/telemetry/causal.seq.json`. Daimon runs at
+ * most one wake at a time per agent (`PiAgentHandle.wakeQueue` serializes
+ * them), so read-modify-write here does not need extra locking.
+ */
+export const nextCausalSeq = async (input) => {
+    const store = await readSeqStore(input.runtimeHomePath);
+    const forRun = store[input.runId] ?? {};
+    const next = (forRun[input.streamId] ?? 0) + 1;
+    forRun[input.streamId] = next;
+    store[input.runId] = forRun;
+    await writeSeqStore(input.runtimeHomePath, store);
+    return next;
+};
+/** Appends one CausalEvent record as a line of `runtimeHome/telemetry/causal.jsonl`. */
+export const appendCausalEvent = async (runtimeHomePath, event) => {
+    await mkdir(telemetryDir(runtimeHomePath), { recursive: true });
+    await appendFile(jsonlFilePath(runtimeHomePath), `${JSON.stringify(event)}\n`, "utf8");
+};
+/**
+ * Stamps and appends one causal event for this agent's stream
+ * (`agent:<agentId>`). `run_id` and `principal_id` are always caller-
+ * supplied values (never read from `payload` or model output) — see
+ * `piHarness.ts`, which is the only caller and always passes the resolved
+ * `NOOPOLIS_RUN_ID` and the authenticated agent identity.
+ */
+export const emitCausalEvent = async (input) => {
+    const streamId = `agent:${input.agentId}`;
+    const seq = await nextCausalSeq({ runId: input.runId, runtimeHomePath: input.runtimeHomePath, streamId });
+    const event = {
+        cause_event_ids: [...input.causeEventIds],
+        emitter: { system: "daimon", stream_id: streamId, seq },
+        event_id: input.eventId,
+        payload: input.payload,
+        principal_id: input.principalId,
+        recorded_at: new Date().toISOString(),
+        run_id: input.runId,
+        type: input.type,
+        version: CAUSAL_EVENT_VERSION
+    };
+    await appendCausalEvent(input.runtimeHomePath, event);
+    return event;
+};
+/** Stamps `turn.input.submitted` for one Pi turn, right before the engine prompt call. */
+export const emitTurnInputSubmitted = (input) => emitCausalEvent({
+    agentId: input.agentId,
+    causeEventIds: input.causeEventIds,
+    eventId: turnInputSubmittedEventId(input.turnId),
+    payload: {
+        input_content_sha256: input.inputContentSha256,
+        input_message_ids: [...input.inputMessageIds],
+        prompt_sha256: input.promptSha256,
+        turn_id: input.turnId
+    },
+    principalId: input.principalId,
+    runId: input.runId,
+    runtimeHomePath: input.runtimeHomePath,
+    type: TURN_INPUT_SUBMITTED_TYPE
+});
+/** Stamps `turn.output.completed` once a Pi turn finishes successfully. */
+export const emitTurnOutputCompleted = (input) => emitCausalEvent({
+    agentId: input.agentId,
+    causeEventIds: input.causeEventIds,
+    eventId: turnOutputCompletedEventId(input.turnId),
+    payload: {
+        output_sha256: input.outputSha256,
+        turn_id: input.turnId
+    },
+    principalId: input.principalId,
+    runId: input.runId,
+    runtimeHomePath: input.runtimeHomePath,
+    type: TURN_OUTPUT_COMPLETED_TYPE
+});

package/dist/observability/controlCausal.d.ts

@@ -0,0 +1,117 @@
+import { type CausalEvent } from "./causalEvents.js";
+/**
+ * Control-wake causal emitters for root's two wake-acceptance surfaces
+ * (`src/runtime/pi/appControlSource.ts`, root repo, out of scope here):
+ * the operator-only control endpoint and the Moltnet loopback delivery
+ * endpoint (`/agents/:slug/wake`). Both stamp `control.wake.accepted` —
+ * enforcement point #3 in `specs/CAUSAL.md` §"Enforcement points" — but with
+ * different `principal_id` authorities, per the B62 fix (Option B): the
+ * operator endpoint stamps `operator:<name>` (`emitControlWakeAccepted`),
+ * the delivery endpoint stamps the fixed `system:moltnet` authority
+ * (`emitDeliveryWakeAccepted`), never a caller-supplied `from`/agent field.
+ * `control.wake.denied` (`emitControlWakeDenied`) stays operator-only: the
+ * delivery endpoint has no bearer-token deny path to stamp. Root's generated
+ * app calls these directly; this file has no knowledge of HTTP, tokens, or
+ * the request shape, only the causal envelope contract.
+ */
+export declare const CONTROL_WAKE_ACCEPTED_TYPE: "control.wake.accepted";
+export declare const CONTROL_WAKE_DENIED_TYPE: "control.wake.denied";
+/** Payload for `control.wake.accepted`. */
+export interface ControlWakeAcceptedPayload extends Record<string, unknown> {
+    target_agent_id: string;
+    wake_kind: string;
+}
+/** Payload for `control.wake.denied`. */
+export interface ControlWakeDeniedPayload extends Record<string, unknown> {
+    reason: string;
+    target_agent_id: string;
+}
+/**
+ * Payload for a Moltnet-delivered `control.wake.accepted` (same event type
+ * as the operator path — it is still an accepted wake; `principal_id` is
+ * what distinguishes authority). Adds `delivered_by` so downstream readers
+ * can tell a delivery-stamped event from an operator-stamped one without
+ * inspecting `principal_id`.
+ */
+export interface DeliveryWakeAcceptedPayload extends ControlWakeAcceptedPayload {
+    delivered_by: "moltnet";
+}
+/**
+ * Principal grammar per `specs/CAUSAL.md` §3 (`^(agent|operator|system):.+`):
+ * an authenticated operator identity, e.g. `operator:control`. Callers must
+ * pass the identity behind the verified bearer token, never a value read
+ * from the request body or model output.
+ */
+export declare const operatorPrincipalId: (operatorName: string) => string;
+/**
+ * Fixed principal for wakes accepted through the Moltnet loopback delivery
+ * endpoint (`/agents/:slug/wake`): the delivering authority itself, never an
+ * identity derived from a caller-supplied `from`/agent field on the request.
+ */
+export declare const DELIVERY_PRINCIPAL_ID: "system:moltnet";
+/** Deterministic, non-model-derived event id for a control wake acceptance. */
+export declare const controlWakeAcceptedEventId: (requestId: string) => string;
+/** Deterministic, non-model-derived event id for a control wake denial. */
+export declare const controlWakeDeniedEventId: (requestId: string) => string;
+/**
+ * Deterministic, non-model-derived event id for a Moltnet-delivered wake
+ * acceptance. Distinct from `controlWakeAcceptedEventId` (own `.delivery.`
+ * segment) so the two paths never collide even if a future caller reused a
+ * `requestId` across both endpoints for the same target.
+ */
+export declare const deliveryWakeAcceptedEventId: (requestId: string) => string;
+export interface EmitControlWakeAcceptedInput {
+    causeEventIds?: string[];
+    operatorName: string;
+    requestId: string;
+    runId?: string;
+    runtimeHomePath: string;
+    targetAgentId: string;
+    wakeKind: string;
+}
+/**
+ * Stamps `control.wake.accepted` once root's operator-control endpoint has
+ * verified the bearer token and is about to wake `targetAgentId`.
+ * `principal_id` is always `operator:<operatorName>` (the authenticated
+ * operator behind the verified token), never derived from the request body.
+ * `run_id` defaults to `resolveRunId()` like every other daimon emitter.
+ */
+export declare const emitControlWakeAccepted: (input: EmitControlWakeAcceptedInput) => Promise<CausalEvent<ControlWakeAcceptedPayload>>;
+export interface EmitDeliveryWakeAcceptedInput {
+    causeEventIds?: string[];
+    requestId: string;
+    runId?: string;
+    runtimeHomePath: string;
+    targetAgentId: string;
+    wakeKind: string;
+}
+/**
+ * Stamps `control.wake.accepted` once root's Moltnet loopback delivery
+ * endpoint (`/agents/:slug/wake`) is about to wake `targetAgentId` on behalf
+ * of an inter-agent message. `principal_id` is always the fixed
+ * `DELIVERY_PRINCIPAL_ID` (`system:moltnet`) — the delivering authority —
+ * never derived from a caller-supplied `from`/agent field, and never
+ * `operator:<name>` (that principal is reserved for the operator-only
+ * control endpoint; see `emitControlWakeAccepted`). `run_id` defaults to
+ * `resolveRunId()` like every other daimon emitter.
+ */
+export declare const emitDeliveryWakeAccepted: (input: EmitDeliveryWakeAcceptedInput) => Promise<CausalEvent<DeliveryWakeAcceptedPayload>>;
+export interface EmitControlWakeDeniedInput {
+    causeEventIds?: string[];
+    operatorName: string;
+    reason: string;
+    requestId: string;
+    runId?: string;
+    runtimeHomePath: string;
+    targetAgentId: string;
+}
+/**
+ * Stamps `control.wake.denied` when root's operator-control endpoint rejects
+ * a wake request over a missing or invalid bearer token. Deny paths must
+ * never drop silently (see `specs/CAUSAL.md` enforcement point #3 / T5):
+ * every 401 the endpoint returns should carry exactly one of these. As with
+ * `emitControlWakeAccepted`, `principal_id` is always the authenticated
+ * operator identity, never a value read from the request.
+ */
+export declare const emitControlWakeDenied: (input: EmitControlWakeDeniedInput) => Promise<CausalEvent<ControlWakeDeniedPayload>>;
+//# sourceMappingURL=controlCausal.d.ts.map

package/dist/observability/controlCausal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controlCausal.d.ts","sourceRoot":"","sources":["../../src/observability/controlCausal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiC,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEpF;;;;;;;;;;;;;;GAcG;AAEH,eAAO,MAAM,0BAA0B,EAAG,uBAAgC,CAAC;AAC3E,eAAO,MAAM,wBAAwB,EAAG,qBAA8B,CAAC;AAEvE,2CAA2C;AAC3C,MAAM,WAAW,0BAA2B,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACzE,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,yCAAyC;AACzC,MAAM,WAAW,wBAAyB,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACvE,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,2BAA4B,SAAQ,0BAA0B;IAC7E,YAAY,EAAE,SAAS,CAAC;CACzB;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAAI,cAAc,MAAM,KAAG,MAAoC,CAAC;AAEhG;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAG,gBAAyB,CAAC;AAE/D,+EAA+E;AAC/E,eAAO,MAAM,0BAA0B,GAAI,WAAW,MAAM,KAAG,MAClB,CAAC;AAE9C,2EAA2E;AAC3E,eAAO,MAAM,wBAAwB,GAAI,WAAW,MAAM,KAAG,MAAmD,CAAC;AAEjH;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,GAAI,WAAW,MAAM,KAAG,MAClB,CAAC;AAE/C,MAAM,WAAW,4BAA4B;IAC3C,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,GAClC,OAAO,4BAA4B,KAClC,OAAO,CAAC,WAAW,CAAC,0BAA0B,CAAC,CAa9C,CAAC;AAEL,MAAM,WAAW,6BAA6B;IAC5C,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,wBAAwB,GACnC,OAAO,6BAA6B,KACnC,OAAO,CAAC,WAAW,CAAC,2BAA2B,CAAC,CAc/C,CAAC;AAEL,MAAM,WAAW,0BAA0B;IACzC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,GAChC,OAAO,0BAA0B,KAChC,OAAO,CAAC,WAAW,CAAC,wBAAwB,CAAC,CAa5C,CAAC"}

package/dist/observability/controlCausal.js

@@ -0,0 +1,107 @@
+import { emitCausalEvent, resolveRunId } from "./causalEvents.js";
+/**
+ * Control-wake causal emitters for root's two wake-acceptance surfaces
+ * (`src/runtime/pi/appControlSource.ts`, root repo, out of scope here):
+ * the operator-only control endpoint and the Moltnet loopback delivery
+ * endpoint (`/agents/:slug/wake`). Both stamp `control.wake.accepted` —
+ * enforcement point #3 in `specs/CAUSAL.md` §"Enforcement points" — but with
+ * different `principal_id` authorities, per the B62 fix (Option B): the
+ * operator endpoint stamps `operator:<name>` (`emitControlWakeAccepted`),
+ * the delivery endpoint stamps the fixed `system:moltnet` authority
+ * (`emitDeliveryWakeAccepted`), never a caller-supplied `from`/agent field.
+ * `control.wake.denied` (`emitControlWakeDenied`) stays operator-only: the
+ * delivery endpoint has no bearer-token deny path to stamp. Root's generated
+ * app calls these directly; this file has no knowledge of HTTP, tokens, or
+ * the request shape, only the causal envelope contract.
+ */
+export const CONTROL_WAKE_ACCEPTED_TYPE = "control.wake.accepted";
+export const CONTROL_WAKE_DENIED_TYPE = "control.wake.denied";
+/**
+ * Principal grammar per `specs/CAUSAL.md` §3 (`^(agent|operator|system):.+`):
+ * an authenticated operator identity, e.g. `operator:control`. Callers must
+ * pass the identity behind the verified bearer token, never a value read
+ * from the request body or model output.
+ */
+export const operatorPrincipalId = (operatorName) => `operator:${operatorName}`;
+/**
+ * Fixed principal for wakes accepted through the Moltnet loopback delivery
+ * endpoint (`/agents/:slug/wake`): the delivering authority itself, never an
+ * identity derived from a caller-supplied `from`/agent field on the request.
+ */
+export const DELIVERY_PRINCIPAL_ID = "system:moltnet";
+/** Deterministic, non-model-derived event id for a control wake acceptance. */
+export const controlWakeAcceptedEventId = (requestId) => `daimon:${requestId}:control.wake.accepted`;
+/** Deterministic, non-model-derived event id for a control wake denial. */
+export const controlWakeDeniedEventId = (requestId) => `daimon:${requestId}:control.wake.denied`;
+/**
+ * Deterministic, non-model-derived event id for a Moltnet-delivered wake
+ * acceptance. Distinct from `controlWakeAcceptedEventId` (own `.delivery.`
+ * segment) so the two paths never collide even if a future caller reused a
+ * `requestId` across both endpoints for the same target.
+ */
+export const deliveryWakeAcceptedEventId = (requestId) => `daimon:${requestId}:delivery.wake.accepted`;
+/**
+ * Stamps `control.wake.accepted` once root's operator-control endpoint has
+ * verified the bearer token and is about to wake `targetAgentId`.
+ * `principal_id` is always `operator:<operatorName>` (the authenticated
+ * operator behind the verified token), never derived from the request body.
+ * `run_id` defaults to `resolveRunId()` like every other daimon emitter.
+ */
+export const emitControlWakeAccepted = (input) => emitCausalEvent({
+    agentId: input.targetAgentId,
+    causeEventIds: input.causeEventIds ?? [],
+    eventId: controlWakeAcceptedEventId(input.requestId),
+    payload: {
+        target_agent_id: input.targetAgentId,
+        wake_kind: input.wakeKind
+    },
+    principalId: operatorPrincipalId(input.operatorName),
+    runId: input.runId ?? resolveRunId(),
+    runtimeHomePath: input.runtimeHomePath,
+    type: CONTROL_WAKE_ACCEPTED_TYPE
+});
+/**
+ * Stamps `control.wake.accepted` once root's Moltnet loopback delivery
+ * endpoint (`/agents/:slug/wake`) is about to wake `targetAgentId` on behalf
+ * of an inter-agent message. `principal_id` is always the fixed
+ * `DELIVERY_PRINCIPAL_ID` (`system:moltnet`) — the delivering authority —
+ * never derived from a caller-supplied `from`/agent field, and never
+ * `operator:<name>` (that principal is reserved for the operator-only
+ * control endpoint; see `emitControlWakeAccepted`). `run_id` defaults to
+ * `resolveRunId()` like every other daimon emitter.
+ */
+export const emitDeliveryWakeAccepted = (input) => emitCausalEvent({
+    agentId: input.targetAgentId,
+    causeEventIds: input.causeEventIds ?? [],
+    eventId: deliveryWakeAcceptedEventId(input.requestId),
+    payload: {
+        delivered_by: "moltnet",
+        target_agent_id: input.targetAgentId,
+        wake_kind: input.wakeKind
+    },
+    principalId: DELIVERY_PRINCIPAL_ID,
+    runId: input.runId ?? resolveRunId(),
+    runtimeHomePath: input.runtimeHomePath,
+    type: CONTROL_WAKE_ACCEPTED_TYPE
+});
+/**
+ * Stamps `control.wake.denied` when root's operator-control endpoint rejects
+ * a wake request over a missing or invalid bearer token. Deny paths must
+ * never drop silently (see `specs/CAUSAL.md` enforcement point #3 / T5):
+ * every 401 the endpoint returns should carry exactly one of these. As with
+ * `emitControlWakeAccepted`, `principal_id` is always the authenticated
+ * operator identity, never a value read from the request.
+ */
+export const emitControlWakeDenied = (input) => emitCausalEvent({
+    agentId: input.targetAgentId,
+    causeEventIds: input.causeEventIds ?? [],
+    eventId: controlWakeDeniedEventId(input.requestId),
+    payload: {
+        reason: input.reason,
+        target_agent_id: input.targetAgentId
+    },
+    principalId: operatorPrincipalId(input.operatorName),
+    runId: input.runId ?? resolveRunId(),
+    runtimeHomePath: input.runtimeHomePath,
+    type: CONTROL_WAKE_DENIED_TYPE
+});

package/dist/observability/emitCausalFixture.d.ts

@@ -0,0 +1,25 @@
+import { type CausalEvent } from "./causalEvents.js";
+export interface CausalFixtureResult {
+    events: [CausalEvent, CausalEvent];
+    jsonlPath: string;
+}
+export interface RunCausalFixtureOptions {
+    /** Overrides the scratch runtime home; defaults to a fixed `.runtime/` path keyed on `spoof`. */
+    runtimeHomePath?: string;
+    /**
+     * Adversarial mode: the fixture's "wake text" (standing in for untrusted
+     * model/request input) embeds a forged identity claim, but the emitted
+     * `principal_id` on both events must remain the authenticated
+     * `agent:<agentId>` regardless — never the claimed identity. Mirrors the
+     * spoof invariant already covered live in `piHarnessCausal.test.ts`
+     * ("model output cannot set principal_id...").
+     */
+    spoof?: boolean;
+}
+/**
+ * Runs the fixture and returns the two stamped events plus the jsonl path,
+ * without touching `process.stdout`/`process.exitCode` — the CLI entry
+ * point below wraps this for `npm run emit-causal-fixture`.
+ */
+export declare const runCausalFixture: (options?: RunCausalFixtureOptions) => Promise<CausalFixtureResult>;
+//# sourceMappingURL=emitCausalFixture.d.ts.map

package/dist/observability/emitCausalFixture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emitCausalFixture.d.ts","sourceRoot":"","sources":["../../src/observability/emitCausalFixture.ts"],"names":[],"mappings":"AAIA,OAAO,EAA4E,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AA0B/H,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;IACnC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,uBAAuB;IACtC,iGAAiG;IACjG,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAID;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,GAAU,UAAS,uBAA4B,KAAG,OAAO,CAAC,mBAAmB,CA0DzG,CAAC"}

package/dist/observability/emitCausalFixture.js

@@ -0,0 +1,98 @@
+import { mkdir, rm } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { emitTurnInputSubmitted, emitTurnOutputCompleted, resolveRunId, sha256Hex } from "./causalEvents.js";
+/**
+ * Standalone fixture emitter, run via `npm run emit-causal-fixture`
+ * (or `npm run emit-causal-fixture:spoof` for the adversarial mode below).
+ *
+ * Stamps one synthetic `turn.input.submitted` -> `turn.output.completed`
+ * chain into a scratch runtime home under `.runtime/causal-fixture[-spoof]/`,
+ * using the same `causalEvents.ts` functions `turnCausal.ts` uses for real
+ * turns. This is a fixture, not a live engine run: no Pi session, no mneme
+ * recall.
+ *
+ * `principal_id` here is stamped as `agent:<agentId>` directly (rather than
+ * importing `turnCausal.ts`'s `agentPrincipalId` helper) because this file
+ * lives under `src/observability/`, which stays engine-neutral and must not
+ * import `src/pi/` implementation details (see this folder's `AGENTS.md`).
+ * The value is the same grammar (`specs/CAUSAL.md` §3) either way.
+ *
+ * Exact invocation contract for a future cross-repo conformance harness
+ * (B92/B62, out of scope here) is not defined yet, so this script picks the
+ * simplest reasonable convention: write the fixture under a fixed relative
+ * path and print its absolute location as the last line of stdout.
+ */
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const daimonRoot = path.resolve(__dirname, "../..");
+const SPOOFED_AGENT_ID = "attacker-agent";
+/**
+ * Runs the fixture and returns the two stamped events plus the jsonl path,
+ * without touching `process.stdout`/`process.exitCode` — the CLI entry
+ * point below wraps this for `npm run emit-causal-fixture`.
+ */
+export const runCausalFixture = async (options = {}) => {
+    const spoof = options.spoof ?? false;
+    const runtimeHomePath = options.runtimeHomePath ?? path.join(daimonRoot, ".runtime", spoof ? "causal-fixture-spoof" : "causal-fixture");
+    await rm(runtimeHomePath, { recursive: true, force: true });
+    await mkdir(runtimeHomePath, { recursive: true });
+    const agentId = "fixture-agent";
+    const principalId = `agent:${agentId}`;
+    const turnId = "fixture-turn-1";
+    const runId = resolveRunId();
+    const inputText = spoof
+        ? `Fixture wake text for the causal conformance harness. ` +
+            `SPOOF CLAIM (must be ignored): ${JSON.stringify({ from: SPOOFED_AGENT_ID, principal_id: `agent:${SPOOFED_AGENT_ID}` })}`
+        : "Fixture wake text for the causal conformance harness.";
+    const promptText = "Fixture prompt text.";
+    const outputText = spoof
+        ? `Fixture reply text. SPOOF CLAIM (must be ignored): ${JSON.stringify({ principal_id: `agent:${SPOOFED_AGENT_ID}` })}`
+        : "Fixture reply text.";
+    const inputSubmitted = await emitTurnInputSubmitted({
+        agentId,
+        causeEventIds: [turnId],
+        inputContentSha256: sha256Hex(inputText),
+        inputMessageIds: [turnId],
+        principalId,
+        promptSha256: sha256Hex(promptText),
+        runId,
+        runtimeHomePath,
+        turnId
+    });
+    const outputCompleted = await emitTurnOutputCompleted({
+        agentId,
+        causeEventIds: [inputSubmitted.event_id],
+        outputSha256: sha256Hex(outputText),
+        principalId,
+        runId,
+        runtimeHomePath,
+        turnId
+    });
+    // The whole point of spoof mode: the forged claim above must never reach
+    // the stamped envelope. Fail loudly here rather than let a future refactor
+    // silently regress this invariant.
+    for (const event of [inputSubmitted, outputCompleted]) {
+        if (event.principal_id !== principalId) {
+            throw new Error(`causal fixture invariant violated: principal_id was "${event.principal_id}", expected "${principalId}"`);
+        }
+    }
+    return {
+        events: [inputSubmitted, outputCompleted],
+        jsonlPath: path.join(runtimeHomePath, "telemetry", "causal.jsonl")
+    };
+};
+const isMainModule = () => {
+    const invoked = process.argv[1] ? path.resolve(process.argv[1]) : undefined;
+    return invoked !== undefined && invoked === path.resolve(fileURLToPath(import.meta.url));
+};
+if (isMainModule()) {
+    const spoof = process.argv.includes("--spoof");
+    runCausalFixture({ spoof })
+        .then((result) => {
+        console.log(result.jsonlPath);
+    })
+        .catch((error) => {
+        console.error(error instanceof Error ? error.stack ?? error.message : String(error));
+        process.exitCode = 1;
+    });
+}

package/dist/observability/index.d.ts

@@ -1,2 +1,4 @@
+export * from "./causalEvents.js";
+export * from "./controlCausal.js";
 export * from "./orgObserver.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/observability/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/observability/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC"}

package/dist/observability/index.js

@@ -1 +1,3 @@
+export * from "./causalEvents.js";
+export * from "./controlCausal.js";
 export * from "./orgObserver.js";