@godspeedai/cognate-realitytrace 0.8.0 → 0.9.1
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/package.json +3 -3
- package/src/EGM.md +45 -0
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@godspeedai/cognate-realitytrace",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.9.1",
|
|
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",
|
|
@@ -22,8 +22,8 @@
|
|
|
22
22
|
".": "./src/index.ts"
|
|
23
23
|
},
|
|
24
24
|
"dependencies": {
|
|
25
|
-
"@godspeedai/cognate-events": "^0.
|
|
26
|
-
"@godspeedai/cognate-kernel-api": "^0.
|
|
25
|
+
"@godspeedai/cognate-events": "^0.9.1",
|
|
26
|
+
"@godspeedai/cognate-kernel-api": "^0.9.1"
|
|
27
27
|
},
|
|
28
28
|
"devDependencies": {
|
|
29
29
|
"@godspeedai/cognate-store-memory": "workspace:*",
|
package/src/EGM.md
ADDED
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
# realitytrace / src — observation delivery, SXR CLI port, CEP envelopes
|
|
2
|
+
|
|
3
|
+
## Overview
|
|
4
|
+
|
|
5
|
+
Four modules. `types.ts` holds the `Observation`, `DeliveryReceipt`, `ObservationPort`, and `ObservationStatus` contracts; `index.ts` builds an observation from a committed event, delivers it at least once from the committed outbox with persisted status, and applies the strict-mode gate; `sxr-cli.ts` implements `ObservationPort` over the external `sxr` command through `Bun.spawn`; `godspeed.ts` builds GodSpeed CEP `execution_trace` and `evidence_packet` envelopes with content-addressed ids. `index.ts` re-exports `./types.ts` and `./godspeed.ts` and additionally exports `createSxrCliPort` `[packages/realitytrace/src/index.ts:export]`.
|
|
6
|
+
|
|
7
|
+
## Interface
|
|
8
|
+
|
|
9
|
+
- `Observation` — correlation fields plus `classification` (`reversible_effect` | `durable_fact` | `external_commitment`), optional refs, and an optional CEP `trace` `[packages/realitytrace/src/types.ts:Observation]`
|
|
10
|
+
- `DeliveryReceipt` — only `accepted` or `duplicate`, each with `observationId`, `targetRef`, `detail` `[packages/realitytrace/src/types.ts:DeliveryReceipt]`
|
|
11
|
+
- `ObservationStatus` — persists `queued` | `accepted` | `duplicate` | `retrying` | `failed` with `attempts` and `lastError` `[packages/realitytrace/src/types.ts:ObservationStatus]`
|
|
12
|
+
- `OBSERVATION_TOPIC` — the outbox topic string `observation.deliver` `[packages/realitytrace/src/index.ts:OBSERVATION_TOPIC]`
|
|
13
|
+
- `observationIntent(event, extra)` — the observation plus outbox intent for the same decision `[packages/realitytrace/src/index.ts:observationIntent]`
|
|
14
|
+
- `ObservationDelivery` — `drain()`, `status(eventId)`, `unreconciled()`, `isRecorded(eventId)` `[packages/realitytrace/src/index.ts:ObservationDelivery]`
|
|
15
|
+
- `createSxrCliPort(options)` — `ObservationPort` plus `prepare`, `readCorrelation`, `deriveEvidence`, `readEvidence` `[packages/realitytrace/src/sxr-cli.ts:createSxrCliPort]`
|
|
16
|
+
- `executionTraceEnvelope`, `evidencePacketEnvelope`, `governedTraceFor`, `executionTraceId`, `transformationId` `[packages/realitytrace/src/godspeed.ts:executionTraceEnvelope]`
|
|
17
|
+
|
|
18
|
+
## Invariants
|
|
19
|
+
|
|
20
|
+
- The observation id is `obs-<eventId>` and the outbox id is `observation:<eventId>`; queue ids are stripped back to the event id for status keys `[packages/realitytrace/src/index.ts:eventIdFromOutboxId]`
|
|
21
|
+
- Optional correlation fields are omitted rather than written as `undefined`, and the status write reads the existing record's version first, so each write is a versioned commit into collection `observations` `[packages/realitytrace/src/index.ts:writeStatus]`
|
|
22
|
+
- A failed port call records `retrying` until `item.attempts` reaches `backoff.maxAttempts`, then `failed`, and rethrows so the outbox owns the retry `[packages/realitytrace/src/index.ts:ObservationDelivery]`
|
|
23
|
+
- `isRecorded` is true only for `accepted` or `duplicate`; queued and retrying are explicitly not enough, and `unreconciled()` lists only `failed` records `[packages/realitytrace/src/index.ts:unreconciled]`
|
|
24
|
+
- Every SXR method except `prepare` throws if called before `prepare()` resolves `[packages/realitytrace/src/sxr-cli.ts:record]`
|
|
25
|
+
- The SXR target is the fixed constant `concept:runtime_execution`, used for question declaration and every plan `[packages/realitytrace/src/sxr-cli.ts:TARGET]`
|
|
26
|
+
- The verifier per observation is `cognate.<observationId>`; a `plan create` failure is tolerated only when stderr matches `already exists` `[packages/realitytrace/src/sxr-cli.ts:record]`
|
|
27
|
+
- Ingest sends the CEP `trace` as the content when present, otherwise the observation with `trace` stripped, so a trace is never sent alongside itself `[packages/realitytrace/src/sxr-cli.ts:stripTrace]`
|
|
28
|
+
- Cognate correlation travels as `extensions.cognate` and is read back from the committed ledger row matching `ledger_id` and `append_ordinal` `[packages/realitytrace/src/sxr-cli.ts:readCorrelation]`
|
|
29
|
+
- `evidencePacketEnvelope` throws on zero evidence rows, defaults a missing direction to `unknown`, and never upgrades direction or reliability `[packages/realitytrace/src/godspeed.ts:evidencePacketEnvelope]`
|
|
30
|
+
- `governedTraceFor` returns `undefined` unless metadata carries `authority.operationId`, `decisionEnvelopeId`, and `worldRef`, and stamps `createdAt` from the event time so re-derivation yields identical bytes `[packages/realitytrace/src/godspeed.ts:governedTraceFor]`
|
|
31
|
+
|
|
32
|
+
## Side Effects
|
|
33
|
+
|
|
34
|
+
- `prepare()` creates `repoDir` with `mkdirSync`, runs `git init -q` and an empty commit with `-c user.email=realitytrace@cognate.local -c user.name=realitytrace` via `Bun.spawnSync`, then runs `sxr repo enroll <repoDir> --json` `[packages/realitytrace/src/sxr-cli.ts:prepare]`
|
|
35
|
+
- Creates a scratch directory with `mkdtempSync(join(tmpdir(), "cognate-sxr-prereq-"))`, writes `question.json` as `{question_form:"is_true", question_type:"declared_semantics", target_entities: TARGET, title}` and `threshold.json` as `{threshold_id:"cognate-threshold", kind:"AllEvidenceSupports", minimum_reliability:"medium"}`, and removes the directory in a `finally` `[packages/realitytrace/src/sxr-cli.ts:prepare]`
|
|
36
|
+
- The run is begun with snapshot `snapshot:genesis` over the declared question and threshold `[packages/realitytrace/src/sxr-cli.ts:prepare]`
|
|
37
|
+
- `runSxr` spawns `[bin, ...args]` with `cwd`, `env`, piped stdout/stderr, and optionally piped stdin, then JSON-parses stdout and leaves non-JSON stdout as `undefined` `[packages/realitytrace/src/sxr-cli.ts:runSxr]`
|
|
38
|
+
- The child environment is `process.env` overlaid with `options.env` `[packages/realitytrace/src/sxr-cli.ts:createSxrCliPort]`
|
|
39
|
+
- `readEvidence` and `readCorrelation` run `sxr ledger export --repo <repoId>` and scan the returned rows in memory; non-zero exits are raised as `realitytrace: sxr <description> failed (exit N): <stderr or stdout>` `[packages/realitytrace/src/sxr-cli.ts:requireOk]`
|
|
40
|
+
- `godspeed.ts` reads a clock: `createdAt` defaults to `new Date()` and timestamps are truncated to whole seconds; `evidencePacketEnvelope` derives its id suffix from a `sha256` hash of the sorted evidence ids `[packages/realitytrace/src/godspeed.ts:isoSeconds]`
|
|
41
|
+
- Delivery status is durably committed into the `observations` collection of the caller's `DurableStore` `[packages/realitytrace/src/index.ts:OBSERVATIONS_COLLECTION]`
|
|
42
|
+
|
|
43
|
+
## Verification
|
|
44
|
+
|
|
45
|
+
- Run: `cd packages/realitytrace && bun test`
|