@godspeedai/cognate-realitytrace 0.9.2 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -103,3 +103,7 @@ observation → receipt mapping stays in your store, keyed by event id.
103
103
  ## License
104
104
 
105
105
  Apache-2.0
106
+
107
+ ## Interaction events (`godspeed.interaction_event` v1)
108
+
109
+ A run started with a `caseContext` (see `@godspeedai/cognate-runtime-api`) emits one `godspeed.interaction_event` per consequential event (`run.started`, `run.invocation`, `run.completed`, `run.failed`, `run.cancelled`; the service commits the first and last through the same `outboxFor` hook). Wire it with `outboxFor: (event) => interactionOutboxFor(event)`: the observation carries the extension in `interactionEvent` (and inside the governed `execution_trace` when an authority decision exists). Runs without a case context emit nothing extra. `source.record_id` is the run event id, so redelivery repeats the same record. The extension is unsigned in S1 (`emitter` absent). The CEP schema is vendored at `schemas/godspeed.interaction_event.v1.json` with a pinned sha256 in the tests.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@godspeedai/cognate-realitytrace",
3
- "version": "0.9.2",
3
+ "version": "0.10.0",
4
4
  "description": "Observation port, committed-outbox delivery, receipts, strict gating, and the SXR CLI adapter (spec §20). RealityTrace stays unchanged.",
5
5
  "type": "module",
6
6
  "license": "Apache-2.0",
@@ -16,17 +16,22 @@
16
16
  "access": "public"
17
17
  },
18
18
  "files": [
19
- "src"
19
+ "src",
20
+ "schemas"
20
21
  ],
21
22
  "exports": {
22
23
  ".": "./src/index.ts"
23
24
  },
24
25
  "dependencies": {
25
- "@godspeedai/cognate-events": "^0.9.2",
26
- "@godspeedai/cognate-kernel-api": "^0.9.2"
26
+ "@godspeedai/cognate-events": "^0.10.0",
27
+ "@godspeedai/cognate-kernel-api": "^0.10.0"
27
28
  },
28
29
  "devDependencies": {
30
+ "@godspeedai/cognate-execution": "workspace:*",
31
+ "@godspeedai/cognate-runtime-api": "workspace:*",
32
+ "@godspeedai/cognate-runtime-bun": "workspace:*",
29
33
  "@godspeedai/cognate-store-memory": "workspace:*",
30
- "@godspeedai/cognate-store-sqlite": "workspace:*"
34
+ "@godspeedai/cognate-store-sqlite": "workspace:*",
35
+ "ajv": "^8.17.1"
31
36
  }
32
37
  }
@@ -0,0 +1,292 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://cep.dev/schemas/extensions/godspeed.interaction_event.v1.json",
4
+ "title": "GodSpeed interaction event extension v1",
5
+ "description": "The object carried at extensions[\"godspeed.interaction_event\"] on an execution_trace envelope. One consequential interaction observed by an emitter. It is observation, not settlement (CEP-0008 \u00a79.5).",
6
+ "type": "object",
7
+ "additionalProperties": false,
8
+ "required": [
9
+ "world_ref",
10
+ "semantic_ref",
11
+ "declaration_key",
12
+ "actor",
13
+ "operation",
14
+ "resource",
15
+ "context",
16
+ "correlation",
17
+ "authority",
18
+ "outcome",
19
+ "source",
20
+ "executor_provenance",
21
+ "kind"
22
+ ],
23
+ "properties": {
24
+ "world_ref": {
25
+ "type": "string",
26
+ "description": "Semantic-world revision of the addressed element (world:<name>@sha256:<64 hex>).",
27
+ "pattern": "^world:[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*@sha256:[0-9a-f]{64}$"
28
+ },
29
+ "semantic_ref": {
30
+ "type": "string",
31
+ "description": "Declared element addressed, namespace::name.",
32
+ "pattern": "^[A-Za-z0-9_.-]+::[A-Za-z0-9_.-]+$"
33
+ },
34
+ "declaration_key": {
35
+ "type": "string",
36
+ "description": "concept:<uuidv5 of namespace::name>. Emitted for convenience; the receiver recomputes and never trusts it.",
37
+ "pattern": "^concept:[0-9a-f]{8}-[0-9a-f]{4}-5[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
38
+ },
39
+ "actor": {
40
+ "type": "object",
41
+ "additionalProperties": false,
42
+ "required": [
43
+ "principal",
44
+ "role"
45
+ ],
46
+ "properties": {
47
+ "principal": {
48
+ "type": "string",
49
+ "minLength": 1,
50
+ "description": "Authenticated principal."
51
+ },
52
+ "role": {
53
+ "type": "string",
54
+ "minLength": 1,
55
+ "description": "SOP role."
56
+ }
57
+ }
58
+ },
59
+ "operation": {
60
+ "type": "string",
61
+ "minLength": 1,
62
+ "description": "Declared or observed operation."
63
+ },
64
+ "resource": {
65
+ "type": "string",
66
+ "minLength": 1,
67
+ "description": "Resource acted on."
68
+ },
69
+ "context": {
70
+ "type": "object",
71
+ "additionalProperties": false,
72
+ "required": [
73
+ "case_id",
74
+ "plan_item_id"
75
+ ],
76
+ "properties": {
77
+ "case_id": {
78
+ "type": "string",
79
+ "minLength": 1
80
+ },
81
+ "plan_item_id": {
82
+ "type": "string",
83
+ "minLength": 1
84
+ },
85
+ "episode_ref": {
86
+ "type": "string",
87
+ "description": "episode:<case_id>:<plan_item_id>:<n>@sha256:<64 hex>. Required when kind is evaluated.",
88
+ "pattern": "^episode:[^:@\\s]+:[^:@\\s]+:[0-9]+@sha256:[0-9a-f]{64}$"
89
+ },
90
+ "assignment_id": {
91
+ "type": "string",
92
+ "description": "assign:<caseId>:<stepId>:<n>:<k>. Present when the work was delegated.",
93
+ "pattern": "^assign:[^:\\s]+:[^:\\s]+:[0-9]+:[0-9]+$"
94
+ }
95
+ }
96
+ },
97
+ "correlation": {
98
+ "type": "object",
99
+ "description": "Structured; never parsed from a string.",
100
+ "additionalProperties": false,
101
+ "required": [
102
+ "case_id"
103
+ ],
104
+ "properties": {
105
+ "case_id": {
106
+ "type": "string",
107
+ "minLength": 1
108
+ },
109
+ "assignment_id": {
110
+ "type": "string",
111
+ "pattern": "^assign:[^:\\s]+:[^:\\s]+:[0-9]+:[0-9]+$"
112
+ },
113
+ "episode_ref": {
114
+ "type": "string",
115
+ "pattern": "^episode:[^:@\\s]+:[^:@\\s]+:[0-9]+@sha256:[0-9a-f]{64}$"
116
+ },
117
+ "run_id": {
118
+ "type": "string",
119
+ "minLength": 1
120
+ }
121
+ }
122
+ },
123
+ "causation_id": {
124
+ "type": "string",
125
+ "minLength": 1,
126
+ "description": "Record id of the cause in the owning system. Present when caused."
127
+ },
128
+ "authority": {
129
+ "type": "object",
130
+ "additionalProperties": false,
131
+ "required": [
132
+ "decision_id"
133
+ ],
134
+ "properties": {
135
+ "decision_id": {
136
+ "type": "string",
137
+ "minLength": 1,
138
+ "description": "A SEA-Forge decision id, or the literal not_required, or the literal unknown. Verified against SEA-Forge at ingest."
139
+ }
140
+ }
141
+ },
142
+ "outcome": {
143
+ "type": "object",
144
+ "additionalProperties": false,
145
+ "required": [
146
+ "status"
147
+ ],
148
+ "properties": {
149
+ "status": {
150
+ "enum": [
151
+ "succeeded",
152
+ "failed",
153
+ "denied",
154
+ "interrupted",
155
+ "unknown"
156
+ ],
157
+ "description": "Observed, never inferred."
158
+ },
159
+ "effect_refs": {
160
+ "type": "array",
161
+ "items": {
162
+ "type": "string",
163
+ "minLength": 1
164
+ }
165
+ }
166
+ }
167
+ },
168
+ "evidence_refs": {
169
+ "type": "array",
170
+ "items": {
171
+ "type": "string",
172
+ "minLength": 1
173
+ }
174
+ },
175
+ "settlement_ref": {
176
+ "type": "string",
177
+ "minLength": 1,
178
+ "description": "Settlement events only."
179
+ },
180
+ "source": {
181
+ "type": "object",
182
+ "additionalProperties": false,
183
+ "required": [
184
+ "system",
185
+ "record_id",
186
+ "sequence",
187
+ "recorded_at"
188
+ ],
189
+ "properties": {
190
+ "system": {
191
+ "type": "string",
192
+ "minLength": 1
193
+ },
194
+ "record_id": {
195
+ "type": "string",
196
+ "minLength": 1,
197
+ "description": "Pointer to the untouched source record."
198
+ },
199
+ "sequence": {
200
+ "type": "integer",
201
+ "minimum": 0,
202
+ "description": "Owning system's sequence; the ordering field."
203
+ },
204
+ "recorded_at": {
205
+ "type": "string",
206
+ "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\\.[0-9]+)?(?:Z|[+-][0-9]{2}:[0-9]{2})$",
207
+ "description": "Emitter clock; informational only, never orders."
208
+ }
209
+ }
210
+ },
211
+ "executor_provenance": {
212
+ "enum": [
213
+ "program",
214
+ "live",
215
+ "injected_fault"
216
+ ]
217
+ },
218
+ "kind": {
219
+ "enum": [
220
+ "evaluated",
221
+ "exploratory"
222
+ ]
223
+ },
224
+ "emitter": {
225
+ "type": "object",
226
+ "additionalProperties": false,
227
+ "required": [
228
+ "signature"
229
+ ],
230
+ "properties": {
231
+ "signature": {
232
+ "type": "object",
233
+ "description": "Workload-identity signature over the canonical extension (RFC 8785, CEP-0008 \u00a716.5) with emitter.signature removed. Required from WP-33; absent before.",
234
+ "additionalProperties": false,
235
+ "required": [
236
+ "key_id",
237
+ "alg",
238
+ "sig"
239
+ ],
240
+ "properties": {
241
+ "key_id": {
242
+ "type": "string",
243
+ "minLength": 1
244
+ },
245
+ "alg": {
246
+ "type": "string",
247
+ "minLength": 1
248
+ },
249
+ "sig": {
250
+ "type": "string",
251
+ "minLength": 1
252
+ }
253
+ }
254
+ }
255
+ }
256
+ },
257
+ "expectation_refs": {
258
+ "type": "array",
259
+ "items": {
260
+ "type": "string",
261
+ "pattern": "^(question|threshold):.+$"
262
+ },
263
+ "description": "RealityTrace question and threshold ids the event bears on (E section 5). Required when kind is evaluated; may be empty. Entries must be unique: JSON Schema uniqueItems is not supported by CEP's own validator (DEBT-IE-01), so uniqueness is checked by consumers and by the contract test (IE_EXPECTATION_REFS_DUPLICATE)."
264
+ }
265
+ },
266
+ "anyOf": [
267
+ {
268
+ "description": "exploratory events need no frozen reference",
269
+ "properties": {
270
+ "kind": {
271
+ "const": "exploratory"
272
+ }
273
+ }
274
+ },
275
+ {
276
+ "description": "evaluated events carry the frozen reference and the expectation",
277
+ "properties": {
278
+ "kind": {
279
+ "const": "evaluated"
280
+ },
281
+ "context": {
282
+ "required": [
283
+ "episode_ref"
284
+ ]
285
+ }
286
+ },
287
+ "required": [
288
+ "expectation_refs"
289
+ ]
290
+ }
291
+ ]
292
+ }
package/src/index.ts CHANGED
@@ -1,5 +1,6 @@
1
1
  export type * from "./types.ts";
2
2
  export * from "./godspeed.ts";
3
+ export * from "./interaction-event.ts";
3
4
  import type { DurableStore, Json, OutboxIntent, StoredEvent } from "@godspeedai/cognate-events";
4
5
  import { OutboxDispatcher } from "@godspeedai/cognate-events";
5
6
  import type { Observation, ObservationPort, ObservationStatus } from "./types.ts";
@@ -11,7 +12,7 @@ const OBSERVATIONS_COLLECTION = "observations";
11
12
  /** Build the observation for a committed event and the outbox intent to include in the SAME decision (spec §13.1). */
12
13
  export function observationIntent(
13
14
  event: Pick<StoredEvent, "eventId" | "tenant" | "correlationId" | "causationId" | "runId" | "scopeId" | "componentId" | "fiberId" | "semanticRef" | "recordedAt">,
14
- extra: Pick<Observation, "classification"> & Partial<Pick<Observation, "capabilityId" | "continuationId" | "inputRef" | "outputRef" | "trace">>,
15
+ extra: Pick<Observation, "classification"> & Partial<Pick<Observation, "capabilityId" | "continuationId" | "inputRef" | "outputRef" | "trace" | "interactionEvent">>,
15
16
  ): OutboxIntent {
16
17
  const observation: Observation = {
17
18
  observationId: `obs-${event.eventId}`,
@@ -30,6 +31,7 @@ export function observationIntent(
30
31
  ...(extra.inputRef !== undefined ? { inputRef: extra.inputRef } : {}),
31
32
  ...(extra.outputRef !== undefined ? { outputRef: extra.outputRef } : {}),
32
33
  ...(extra.trace !== undefined ? { trace: extra.trace } : {}),
34
+ ...(extra.interactionEvent !== undefined ? { interactionEvent: extra.interactionEvent } : {}),
33
35
  timestamp: event.recordedAt,
34
36
  };
35
37
  return {
@@ -0,0 +1,114 @@
1
+ // `godspeed.interaction_event` v1: the semantic-exhaust extension (E section 5, WP-15). One consequential run or
2
+ // invocation event becomes one extension object, built only from the committed event and the case context frozen
3
+ // on `run.started`. The event is observation, not settlement. It is UNSIGNED in S1: `emitter` is absent by design
4
+ // (the schema makes the signature required only from WP-33); nothing here fabricates one.
5
+ import { createHash } from "node:crypto";
6
+ import type { Json, OutboxIntent } from "@godspeedai/cognate-events";
7
+ import { governedTraceFor } from "./godspeed.ts";
8
+ import { observationIntent } from "./index.ts";
9
+
10
+ type Obj = { [key: string]: Json };
11
+
12
+ /** ConceptId namespace (domainforge-core `concept_id.rs`): the RFC 4122 DNS namespace. */
13
+ const CONCEPT_NAMESPACE = "6ba7b810-9dad-11d1-80b4-00c04fd430c8";
14
+
15
+ /** UUIDv5 (RFC 4122 section 4.3) of `name` under `namespace`. */
16
+ export function uuidV5(name: string, namespace = CONCEPT_NAMESPACE): string {
17
+ const ns = Buffer.from(namespace.replace(/-/g, ""), "hex");
18
+ const h = createHash("sha1").update(ns).update(Buffer.from(name, "utf8")).digest();
19
+ h[6] = (h[6]! & 0x0f) | 0x50;
20
+ h[8] = (h[8]! & 0x3f) | 0x80;
21
+ const hex = h.subarray(0, 16).toString("hex");
22
+ return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
23
+ }
24
+
25
+ /** `concept:<uuidv5 of namespace::name>`; the receiver recomputes it and never trusts this. */
26
+ export const declarationKey = (semanticRef: string): string => `concept:${uuidV5(semanticRef)}`;
27
+
28
+ /** Event types that are consequential interactions (the executor and the service commit these through the outbox hook). */
29
+ export const INTERACTION_EVENT_TYPES: ReadonlySet<string> = new Set(["run.started", "run.invocation", "run.completed", "run.failed", "run.cancelled", "assignment.interrupted", "assignment.resumed", "assignment.spend"]);
30
+
31
+ /** The committed (or about-to-commit) event fields this module reads. */
32
+ export interface InteractionSource {
33
+ readonly eventId: string;
34
+ readonly eventType: string;
35
+ readonly runId: string | null;
36
+ readonly causationId: string | null;
37
+ readonly occurredAt: string;
38
+ readonly recordedAt: string;
39
+ readonly streamSequence: number;
40
+ readonly semanticRef?: { readonly namespace: string; readonly id: string };
41
+ readonly metadata?: { readonly [key: string]: unknown };
42
+ }
43
+
44
+ const isObj = (v: unknown): v is { [key: string]: unknown } => typeof v === "object" && v !== null && !Array.isArray(v);
45
+ const SEMANTIC = /^[A-Za-z0-9_.-]+::[A-Za-z0-9_.-]+$/;
46
+ const isoSeconds = (iso: string): string => new Date(iso).toISOString().replace(/\.\d{3}Z$/, "Z");
47
+
48
+ /**
49
+ * The interaction event for one run event, or `undefined` when the run has no case context or the event is not a
50
+ * consequential interaction. A run without case context therefore yields nothing: its behavior is unchanged.
51
+ */
52
+ export function interactionEventFor(event: InteractionSource): Obj | undefined {
53
+ const meta = event.metadata ?? {};
54
+ const ctx = meta.caseContext;
55
+ if (!isObj(ctx) || !INTERACTION_EVENT_TYPES.has(event.eventType) || event.runId === null) return undefined;
56
+ const str = (key: string): string | undefined => (typeof ctx[key] === "string" ? (ctx[key] as string) : undefined);
57
+ const invocation = event.eventType === "run.invocation";
58
+ const capability = typeof meta.capability === "string" ? meta.capability : "unknown";
59
+
60
+ const own = event.semanticRef ? `${event.semanticRef.namespace}::${event.semanticRef.id}` : undefined;
61
+ const semanticRef = own !== undefined && SEMANTIC.test(own) ? own : str("semanticRef")!;
62
+
63
+ const decision = isObj(meta.decision) ? meta.decision : undefined;
64
+ const authority = isObj(decision?.authority) ? decision.authority : undefined;
65
+ // The SEA-Forge decision when one was recorded; `not_required` when no governed decision applies (local policy,
66
+ // or a run-level event); `unknown` when an invocation recorded no decision at all.
67
+ const decisionId = typeof authority?.decisionEnvelopeId === "string" ? authority.decisionEnvelopeId : invocation && decision === undefined ? "unknown" : "not_required";
68
+
69
+ let status: string;
70
+ if (invocation) status = meta.ok === true ? "succeeded" : meta.failureKind === "denied" ? "denied" : "failed";
71
+ // Assignment events: an interruption is `interrupted`; a spend that exceeded a limit is `failed`; a resume or an in-budget spend succeeded.
72
+ else if (event.eventType.startsWith("assignment.")) status = event.eventType === "assignment.interrupted" ? "interrupted" : meta.exceeded === true ? "failed" : "succeeded";
73
+ else status = event.eventType === "run.completed" || event.eventType === "run.started" ? "succeeded" : event.eventType === "run.cancelled" ? "interrupted" : "failed";
74
+
75
+ const kind = str("kind")!;
76
+ const episodeRef = str("episodeRef");
77
+ const assignmentId = str("assignmentId");
78
+ const provenance = capability === "program.run" && invocation ? "program" : (str("executorProvenance") ?? "live");
79
+
80
+ const out: Obj = {
81
+ world_ref: str("worldRef")!,
82
+ semantic_ref: semanticRef,
83
+ declaration_key: declarationKey(semanticRef),
84
+ // An operator action (cancel, interrupt, resume) is attributed to the operator who performed it; agent execution
85
+ // keeps the principal frozen at start.
86
+ actor: { principal: (typeof meta.cancelledBy === "string" ? meta.cancelledBy : typeof meta.by === "string" ? meta.by : undefined) ?? str("principal") ?? "unknown", role: str("role")! },
87
+ operation: invocation ? capability : event.eventType,
88
+ resource: invocation ? `capability:${capability}` : `run:${event.runId}`,
89
+ context: { case_id: str("caseId")!, plan_item_id: str("planItemId")!, ...(episodeRef ? { episode_ref: episodeRef } : {}), ...(assignmentId ? { assignment_id: assignmentId } : {}) },
90
+ correlation: { case_id: str("caseId")!, ...(assignmentId ? { assignment_id: assignmentId } : {}), ...(episodeRef ? { episode_ref: episodeRef } : {}), run_id: event.runId },
91
+ ...(event.causationId ? { causation_id: event.causationId } : {}),
92
+ authority: { decision_id: decisionId },
93
+ outcome: { status },
94
+ source: { system: "cognate", record_id: event.eventId, sequence: event.streamSequence, recorded_at: isoSeconds(event.recordedAt) },
95
+ executor_provenance: provenance,
96
+ kind,
97
+ };
98
+ if (kind === "evaluated") out.expectation_refs = Array.isArray(ctx.expectationRefs) ? (ctx.expectationRefs as string[]) : [];
99
+ return out;
100
+ }
101
+
102
+ /**
103
+ * Outbox intents for one run event, for `RuntimeOptions.outboxFor`. Empty for a run without case context and for
104
+ * non-consequential events, so a non-case run commits exactly the intents it did before. The observation carries the
105
+ * interaction event, and the governed execution_trace (with the extension attached) when an authority decision exists.
106
+ * `source.record_id` is the event id, so the intent id and the record id are stable across redelivery.
107
+ */
108
+ export function interactionOutboxFor(event: InteractionSource & Parameters<typeof observationIntent>[0]): OutboxIntent[] {
109
+ const interaction = interactionEventFor(event);
110
+ if (!interaction) return [];
111
+ const trace = governedTraceFor({ eventId: event.eventId, correlationId: event.correlationId, occurredAt: event.occurredAt, ...(event.metadata ? { metadata: event.metadata } : {}) });
112
+ if (trace) (trace.extensions as Obj)["godspeed.interaction_event"] = interaction;
113
+ return [observationIntent(event, { classification: "durable_fact", ...(typeof event.metadata?.capability === "string" ? { capabilityId: event.metadata.capability } : {}), interactionEvent: interaction, ...(trace ? { trace: trace as Json } : {}) })];
114
+ }
package/src/sxr-cli.ts CHANGED
@@ -12,6 +12,8 @@ export interface SxrCliOptions {
12
12
  readonly repoDir: string;
13
13
  /** Extra environment (e.g. SXR home) for isolation. */
14
14
  readonly env?: Record<string, string>;
15
+ /** Semantic entry file (relative to the repo) configured as the rulebook before the snapshot is created. */
16
+ readonly semanticEntry?: string;
15
17
  }
16
18
 
17
19
  /** Identifiers produced by the SXR prerequisite workflow (enroll → question → threshold → run). */
@@ -21,6 +23,8 @@ export interface SxrWorkflow {
21
23
  readonly thresholdId: string;
22
24
  readonly runId: string;
23
25
  readonly target: string;
26
+ /** The snapshot the run began on: `rulebook` when created from a configured semantic entry, `none` for the genesis fallback. */
27
+ readonly snapshot: { readonly id: string; readonly source: "rulebook" | "none" };
24
28
  }
25
29
 
26
30
  /** The `--target` used for the declared question, threshold's plans, and every per-observation `plan create`. */
@@ -96,6 +100,21 @@ export function createSxrCliPort(
96
100
  const enroll = requireOk(await sxr(["repo", "enroll", options.repoDir, "--json"]), "repo enroll");
97
101
  const repoId: string = enroll.repo_id;
98
102
 
103
+ let snapshot: SxrWorkflow["snapshot"];
104
+ if (options.semanticEntry !== undefined) {
105
+ requireOk(await sxr(["semantic", "configure", "--repo", repoId, "--entry", options.semanticEntry, "--json"]), "semantic configure");
106
+ const created = requireOk(await sxr(["snapshot", "create", "--repo", repoId, "--json"]), "snapshot create");
107
+ snapshot = { id: created.snapshot_id, source: "rulebook" };
108
+ } else {
109
+ // No rulebook configured: RealityTrace refuses snapshot create (exit 3). Begin on the documented genesis snapshot instead.
110
+ const created = await sxr(["snapshot", "create", "--repo", repoId, "--json"]);
111
+ if (created.exitCode === 3 && /no semantic configuration/i.test(created.stderr)) {
112
+ snapshot = { id: "snapshot:genesis", source: "none" };
113
+ } else {
114
+ snapshot = { id: requireOk(created, "snapshot create").snapshot_id, source: "rulebook" };
115
+ }
116
+ }
117
+
99
118
  const scratch = mkdtempSync(join(tmpdir(), "cognate-sxr-prereq-"));
100
119
  try {
101
120
  const questionFile = join(scratch, "question.json");
@@ -108,10 +127,10 @@ export function createSxrCliPort(
108
127
  const declaredThreshold = requireOk(await sxr(["threshold", "declare", "--repo", repoId, "--question", questionId, "--file", thresholdFile, "--json"]), "threshold declare");
109
128
  const thresholdId: string = declaredThreshold.threshold_id;
110
129
 
111
- const run = requireOk(await sxr(["run", "begin", "--repo", repoId, "--snapshot", "snapshot:genesis", "--question", questionId, "--threshold", thresholdId, "--json"]), "run begin");
130
+ const run = requireOk(await sxr(["run", "begin", "--repo", repoId, "--snapshot", snapshot.id, "--question", questionId, "--threshold", thresholdId, "--json"]), "run begin");
112
131
  const runId: string = run.run_id;
113
132
 
114
- workflow = { repoId, questionId, thresholdId, runId, target: TARGET };
133
+ workflow = { repoId, questionId, thresholdId, runId, target: TARGET, snapshot };
115
134
  return workflow;
116
135
  } finally {
117
136
  rmSync(scratch, { recursive: true, force: true });
@@ -127,7 +146,7 @@ export function createSxrCliPort(
127
146
  throw new Error(`realitytrace: sxr plan create failed (exit ${plan.exitCode}): ${plan.stderr || plan.stdout}`);
128
147
  }
129
148
 
130
- const extensions = JSON.stringify({ cognate: correlationOf(observation) });
149
+ const extensions = JSON.stringify({ cognate: correlationOf(observation), ...(observation.interactionEvent !== undefined ? { "godspeed.interaction_event": observation.interactionEvent } : {}) });
131
150
  // A governed operation hands RealityTrace its CEP execution_trace to record; otherwise the bare observation.
132
151
  const content = observation.trace ?? stripTrace(observation);
133
152
  const ingest = await sxr(["ingest", "--run", workflow.runId, "--verifier", verifier, "--stdin-format", "json", "--extensions", extensions, "--json"], JSON.stringify(content));
@@ -175,7 +194,7 @@ export function createSxrCliPort(
175
194
 
176
195
  /** The observation without its trace (the trace is delivered as the content instead, never alongside it). */
177
196
  function stripTrace(observation: Observation): Observation {
178
- const { trace: _trace, ...rest } = observation;
197
+ const { trace: _trace, interactionEvent: _interaction, ...rest } = observation;
179
198
  return rest;
180
199
  }
181
200
 
package/src/types.ts CHANGED
@@ -25,6 +25,11 @@ export interface Observation {
25
25
  * what RealityTrace is handed to record (content-addressed), instead of the bare observation.
26
26
  */
27
27
  readonly trace?: Json;
28
+ /**
29
+ * The `godspeed.interaction_event` v1 extension object for this observation, present only for a run with case
30
+ * context. Unsigned in S1. When a `trace` exists the same object is also at `trace.extensions`.
31
+ */
32
+ readonly interactionEvent?: Json;
28
33
  }
29
34
 
30
35
  /**