open-multi-agent-kit 0.99.0 → 1.2.0

package/dist/observation/identity.d.ts

@@ -0,0 +1,14 @@
+export declare function sha256Hex(data: Uint8Array | string): string;
+export declare function observationId(input: {
+    readonly runId: string;
+    readonly operationId: string;
+    readonly sequence: number;
+    readonly rawDigest: string;
+}): string;
+/** Deterministic digest of a derived view's transform + source + params. */
+export declare function viewDigestOf(input: {
+    readonly observationId: string;
+    readonly viewKind: string;
+    readonly params: string;
+}): string;
+//# sourceMappingURL=identity.d.ts.map

package/dist/observation/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../src/observation/identity.ts"],"names":[],"mappings":"AAWA,wBAAgB,SAAS,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,MAAM,CAI3D;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC3B,GAAG,MAAM,CAMT;AAED,4EAA4E;AAC5E,wBAAgB,YAAY,CAAC,KAAK,EAAE;IACnC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACxB,GAAG,MAAM,CAIT","sourcesContent":["/**\n * Observation identity and digests — U1.\n *\n * `observationId` binds an execution event (run, operation, sequence) to its\n * content digest. It is intentionally not a bare content hash: identical bytes\n * from two different executions are different events and must not collapse into\n * one record. Digests here are integrity checks, not provenance authentication.\n */\nimport { createHash } from \"node:crypto\";\nimport { integer, text } from \"../metacognition/validation.ts\";\n\nexport function sha256Hex(data: Uint8Array | string): string {\n\treturn createHash(\"sha256\")\n\t\t.update(data as Uint8Array)\n\t\t.digest(\"hex\");\n}\n\nexport function observationId(input: {\n\treadonly runId: string;\n\treadonly operationId: string;\n\treadonly sequence: number;\n\treadonly rawDigest: string;\n}): string {\n\ttext(input.runId, \"runId\", 256);\n\ttext(input.operationId, \"operationId\", 256);\n\tinteger(input.sequence, \"sequence\");\n\ttext(input.rawDigest, \"rawDigest\", 128);\n\treturn sha256Hex(`${input.runId}${input.operationId}${input.sequence}${input.rawDigest}`);\n}\n\n/** Deterministic digest of a derived view's transform + source + params. */\nexport function viewDigestOf(input: {\n\treadonly observationId: string;\n\treadonly viewKind: string;\n\treadonly params: string;\n}): string {\n\ttext(input.observationId, \"observationId\", 128);\n\ttext(input.viewKind, \"viewKind\", 32);\n\treturn sha256Hex(`${input.observationId}${input.viewKind}${input.params}`);\n}\n"]}

package/dist/observation/identity.js

@@ -0,0 +1,29 @@
+/**
+ * Observation identity and digests — U1.
+ *
+ * `observationId` binds an execution event (run, operation, sequence) to its
+ * content digest. It is intentionally not a bare content hash: identical bytes
+ * from two different executions are different events and must not collapse into
+ * one record. Digests here are integrity checks, not provenance authentication.
+ */
+import { createHash } from "node:crypto";
+import { integer, text } from "../metacognition/validation.js";
+export function sha256Hex(data) {
+    return createHash("sha256")
+        .update(data)
+        .digest("hex");
+}
+export function observationId(input) {
+    text(input.runId, "runId", 256);
+    text(input.operationId, "operationId", 256);
+    integer(input.sequence, "sequence");
+    text(input.rawDigest, "rawDigest", 128);
+    return sha256Hex(`${input.runId}${input.operationId}${input.sequence}${input.rawDigest}`);
+}
+/** Deterministic digest of a derived view's transform + source + params. */
+export function viewDigestOf(input) {
+    text(input.observationId, "observationId", 128);
+    text(input.viewKind, "viewKind", 32);
+    return sha256Hex(`${input.observationId}${input.viewKind}${input.params}`);
+}
+//# sourceMappingURL=identity.js.map

package/dist/observation/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../../src/observation/identity.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,gCAAgC,CAAC;AAE/D,MAAM,UAAU,SAAS,CAAC,IAAyB,EAAU;IAC5D,OAAO,UAAU,CAAC,QAAQ,CAAC;SACzB,MAAM,CAAC,IAAkB,CAAC;SAC1B,MAAM,CAAC,KAAK,CAAC,CAAC;AAAA,CAChB;AAED,MAAM,UAAU,aAAa,CAAC,KAK7B,EAAU;IACV,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;IAChC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,aAAa,EAAE,GAAG,CAAC,CAAC;IAC5C,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IACpC,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,WAAW,EAAE,GAAG,CAAC,CAAC;IACxC,OAAO,SAAS,CAAC,GAAG,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,WAAW,GAAG,KAAK,CAAC,QAAQ,GAAG,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC;AAAA,CAC1F;AAED,4EAA4E;AAC5E,MAAM,UAAU,YAAY,CAAC,KAI5B,EAAU;IACV,IAAI,CAAC,KAAK,CAAC,aAAa,EAAE,eAAe,EAAE,GAAG,CAAC,CAAC;IAChD,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,UAAU,EAAE,EAAE,CAAC,CAAC;IACrC,OAAO,SAAS,CAAC,GAAG,KAAK,CAAC,aAAa,GAAG,KAAK,CAAC,QAAQ,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;AAAA,CAC3E","sourcesContent":["/**\n * Observation identity and digests — U1.\n *\n * `observationId` binds an execution event (run, operation, sequence) to its\n * content digest. It is intentionally not a bare content hash: identical bytes\n * from two different executions are different events and must not collapse into\n * one record. Digests here are integrity checks, not provenance authentication.\n */\nimport { createHash } from \"node:crypto\";\nimport { integer, text } from \"../metacognition/validation.ts\";\n\nexport function sha256Hex(data: Uint8Array | string): string {\n\treturn createHash(\"sha256\")\n\t\t.update(data as Uint8Array)\n\t\t.digest(\"hex\");\n}\n\nexport function observationId(input: {\n\treadonly runId: string;\n\treadonly operationId: string;\n\treadonly sequence: number;\n\treadonly rawDigest: string;\n}): string {\n\ttext(input.runId, \"runId\", 256);\n\ttext(input.operationId, \"operationId\", 256);\n\tinteger(input.sequence, \"sequence\");\n\ttext(input.rawDigest, \"rawDigest\", 128);\n\treturn sha256Hex(`${input.runId}${input.operationId}${input.sequence}${input.rawDigest}`);\n}\n\n/** Deterministic digest of a derived view's transform + source + params. */\nexport function viewDigestOf(input: {\n\treadonly observationId: string;\n\treadonly viewKind: string;\n\treadonly params: string;\n}): string {\n\ttext(input.observationId, \"observationId\", 128);\n\ttext(input.viewKind, \"viewKind\", 32);\n\treturn sha256Hex(`${input.observationId}${input.viewKind}${input.params}`);\n}\n"]}

package/dist/observation/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Observation kernel — U1/U2/U3 substrate of the upgraded SoL-Pi design.
+ *
+ * Pure, deterministic, bounded modules: raw-observation storage with byte-
+ * scoped reads, deterministic views with a coverage gate, and a shadow
+ * observation-mode recorder. No model calls, no I/O, no completion authority.
+ */
+export * from "./identity.ts";
+export * from "./observe-mode.ts";
+export * from "./store.ts";
+export * from "./types.ts";
+export * from "./view.ts";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/observation/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC","sourcesContent":["/**\n * Observation kernel — U1/U2/U3 substrate of the upgraded SoL-Pi design.\n *\n * Pure, deterministic, bounded modules: raw-observation storage with byte-\n * scoped reads, deterministic views with a coverage gate, and a shadow\n * observation-mode recorder. No model calls, no I/O, no completion authority.\n */\nexport * from \"./identity.ts\";\nexport * from \"./observe-mode.ts\";\nexport * from \"./store.ts\";\nexport * from \"./types.ts\";\nexport * from \"./view.ts\";\n"]}

package/dist/observation/index.js

@@ -0,0 +1,13 @@
+/**
+ * Observation kernel — U1/U2/U3 substrate of the upgraded SoL-Pi design.
+ *
+ * Pure, deterministic, bounded modules: raw-observation storage with byte-
+ * scoped reads, deterministic views with a coverage gate, and a shadow
+ * observation-mode recorder. No model calls, no I/O, no completion authority.
+ */
+export * from "./identity.js";
+export * from "./observe-mode.js";
+export * from "./store.js";
+export * from "./types.js";
+export * from "./view.js";
+//# sourceMappingURL=index.js.map

package/dist/observation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/observation/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC","sourcesContent":["/**\n * Observation kernel — U1/U2/U3 substrate of the upgraded SoL-Pi design.\n *\n * Pure, deterministic, bounded modules: raw-observation storage with byte-\n * scoped reads, deterministic views with a coverage gate, and a shadow\n * observation-mode recorder. No model calls, no I/O, no completion authority.\n */\nexport * from \"./identity.ts\";\nexport * from \"./observe-mode.ts\";\nexport * from \"./store.ts\";\nexport * from \"./types.ts\";\nexport * from \"./view.ts\";\n"]}

package/dist/observation/observe-mode.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Observation-mode recorder — U1 shadow evaluation.
+ *
+ * Records what the coverage-gated deterministic view would have chosen and the
+ * upper-bound token saving, without changing what the model actually receives.
+ * A projected saving is an estimate, never an achieved saving — promotion out
+ * of observation mode requires a real comparison on the same budget.
+ */
+import type { ObservationView } from "./types.ts";
+export interface ObservationChoiceRecord {
+    readonly observationId: string;
+    readonly observedTokens: number;
+    readonly chosenTokens: number;
+    readonly chosenViewKind: string;
+    readonly savedTokensUpperBound: number;
+    readonly coverageStatus: string;
+    readonly infeasible: boolean;
+}
+export interface ObservationModeSummary {
+    readonly observations: number;
+    readonly observedTokens: number;
+    readonly chosenTokens: number;
+    readonly savedTokensUpperBound: number;
+    readonly infeasible: number;
+    readonly coverageComplete: number;
+    readonly coveragePartial: number;
+    readonly coverageUnknown: number;
+}
+export interface ObservationModeRecorder {
+    record(choice: {
+        readonly observationId: string;
+        readonly observedTokens: number;
+        readonly chosenView: ObservationView | null;
+        readonly requiredFactIds?: readonly string[];
+    }): ObservationChoiceRecord;
+    readonly records: readonly ObservationChoiceRecord[];
+    summary(): ObservationModeSummary;
+}
+/**
+ * Pure recorder: given what the model actually saw (`observedTokens`) and what
+ * the gated selector would have chosen, emit one decision record. A null
+ * `chosenView` means the candidate set was infeasible under the required
+ * coverage — recorded as such, never converted into an implicit success.
+ */
+export declare function createObservationModeRecorder(): ObservationModeRecorder;
+//# sourceMappingURL=observe-mode.d.ts.map

package/dist/observation/observe-mode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observe-mode.d.ts","sourceRoot":"","sources":["../../src/observation/observe-mode.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,MAAM,WAAW,uBAAuB;IACvC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,sBAAsB;IACtC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,uBAAuB;IACvC,MAAM,CAAC,MAAM,EAAE;QACd,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;QAC/B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;QAChC,QAAQ,CAAC,UAAU,EAAE,eAAe,GAAG,IAAI,CAAC;QAC5C,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;KAC7C,GAAG,uBAAuB,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,SAAS,uBAAuB,EAAE,CAAC;IACrD,OAAO,IAAI,sBAAsB,CAAC;CAClC;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,IAAI,uBAAuB,CA+DvE","sourcesContent":["/**\n * Observation-mode recorder — U1 shadow evaluation.\n *\n * Records what the coverage-gated deterministic view would have chosen and the\n * upper-bound token saving, without changing what the model actually receives.\n * A projected saving is an estimate, never an achieved saving — promotion out\n * of observation mode requires a real comparison on the same budget.\n */\n\nimport { ensure, integer, text } from \"../metacognition/validation.ts\";\nimport type { ObservationView } from \"./types.ts\";\n\nexport interface ObservationChoiceRecord {\n\treadonly observationId: string;\n\treadonly observedTokens: number;\n\treadonly chosenTokens: number;\n\treadonly chosenViewKind: string;\n\treadonly savedTokensUpperBound: number;\n\treadonly coverageStatus: string;\n\treadonly infeasible: boolean;\n}\n\nexport interface ObservationModeSummary {\n\treadonly observations: number;\n\treadonly observedTokens: number;\n\treadonly chosenTokens: number;\n\treadonly savedTokensUpperBound: number;\n\treadonly infeasible: number;\n\treadonly coverageComplete: number;\n\treadonly coveragePartial: number;\n\treadonly coverageUnknown: number;\n}\n\nexport interface ObservationModeRecorder {\n\trecord(choice: {\n\t\treadonly observationId: string;\n\t\treadonly observedTokens: number;\n\t\treadonly chosenView: ObservationView | null;\n\t\treadonly requiredFactIds?: readonly string[];\n\t}): ObservationChoiceRecord;\n\treadonly records: readonly ObservationChoiceRecord[];\n\tsummary(): ObservationModeSummary;\n}\n\n/**\n * Pure recorder: given what the model actually saw (`observedTokens`) and what\n * the gated selector would have chosen, emit one decision record. A null\n * `chosenView` means the candidate set was infeasible under the required\n * coverage — recorded as such, never converted into an implicit success.\n */\nexport function createObservationModeRecorder(): ObservationModeRecorder {\n\tconst records: ObservationChoiceRecord[] = [];\n\treturn {\n\t\trecord(choice) {\n\t\t\ttext(choice.observationId, \"observationId\", 128);\n\t\t\tinteger(choice.observedTokens, \"observedTokens\");\n\t\t\tconst chosen = choice.chosenView;\n\t\t\tconst record: ObservationChoiceRecord =\n\t\t\t\tchosen === null\n\t\t\t\t\t? Object.freeze({\n\t\t\t\t\t\t\tobservationId: choice.observationId,\n\t\t\t\t\t\t\tobservedTokens: choice.observedTokens,\n\t\t\t\t\t\t\tchosenTokens: choice.observedTokens,\n\t\t\t\t\t\t\tchosenViewKind: \"infeasible\",\n\t\t\t\t\t\t\tsavedTokensUpperBound: 0,\n\t\t\t\t\t\t\tcoverageStatus: \"unknown\",\n\t\t\t\t\t\t\tinfeasible: true,\n\t\t\t\t\t\t})\n\t\t\t\t\t: Object.freeze({\n\t\t\t\t\t\t\tobservationId: choice.observationId,\n\t\t\t\t\t\t\tobservedTokens: choice.observedTokens,\n\t\t\t\t\t\t\tchosenTokens: chosen.estimatedTokens,\n\t\t\t\t\t\t\tchosenViewKind: chosen.viewKind,\n\t\t\t\t\t\t\tsavedTokensUpperBound: Math.max(0, choice.observedTokens - chosen.estimatedTokens),\n\t\t\t\t\t\t\tcoverageStatus: chosen.coverageStatus,\n\t\t\t\t\t\t\tinfeasible: false,\n\t\t\t\t\t\t});\n\t\t\tensure(Number.isFinite(record.savedTokensUpperBound), \"savedTokensUpperBound must be finite\");\n\t\t\trecords.push(record);\n\t\t\treturn record;\n\t\t},\n\t\tget records() {\n\t\t\treturn records;\n\t\t},\n\t\tsummary() {\n\t\t\tlet observedTokens = 0;\n\t\t\tlet chosenTokens = 0;\n\t\t\tlet savedTokensUpperBound = 0;\n\t\t\tlet infeasible = 0;\n\t\t\tlet coverageComplete = 0;\n\t\t\tlet coveragePartial = 0;\n\t\t\tlet coverageUnknown = 0;\n\t\t\tfor (const r of records) {\n\t\t\t\tobservedTokens += r.observedTokens;\n\t\t\t\tchosenTokens += r.chosenTokens;\n\t\t\t\tsavedTokensUpperBound += r.savedTokensUpperBound;\n\t\t\t\tif (r.infeasible) infeasible += 1;\n\t\t\t\tif (r.coverageStatus === \"complete\") coverageComplete += 1;\n\t\t\t\telse if (r.coverageStatus === \"partial\") coveragePartial += 1;\n\t\t\t\telse coverageUnknown += 1;\n\t\t\t}\n\t\t\treturn {\n\t\t\t\tobservations: records.length,\n\t\t\t\tobservedTokens,\n\t\t\t\tchosenTokens,\n\t\t\t\tsavedTokensUpperBound,\n\t\t\t\tinfeasible,\n\t\t\t\tcoverageComplete,\n\t\t\t\tcoveragePartial,\n\t\t\t\tcoverageUnknown,\n\t\t\t};\n\t\t},\n\t};\n}\n"]}

package/dist/observation/observe-mode.js

@@ -0,0 +1,83 @@
+/**
+ * Observation-mode recorder — U1 shadow evaluation.
+ *
+ * Records what the coverage-gated deterministic view would have chosen and the
+ * upper-bound token saving, without changing what the model actually receives.
+ * A projected saving is an estimate, never an achieved saving — promotion out
+ * of observation mode requires a real comparison on the same budget.
+ */
+import { ensure, integer, text } from "../metacognition/validation.js";
+/**
+ * Pure recorder: given what the model actually saw (`observedTokens`) and what
+ * the gated selector would have chosen, emit one decision record. A null
+ * `chosenView` means the candidate set was infeasible under the required
+ * coverage — recorded as such, never converted into an implicit success.
+ */
+export function createObservationModeRecorder() {
+    const records = [];
+    return {
+        record(choice) {
+            text(choice.observationId, "observationId", 128);
+            integer(choice.observedTokens, "observedTokens");
+            const chosen = choice.chosenView;
+            const record = chosen === null
+                ? Object.freeze({
+                    observationId: choice.observationId,
+                    observedTokens: choice.observedTokens,
+                    chosenTokens: choice.observedTokens,
+                    chosenViewKind: "infeasible",
+                    savedTokensUpperBound: 0,
+                    coverageStatus: "unknown",
+                    infeasible: true,
+                })
+                : Object.freeze({
+                    observationId: choice.observationId,
+                    observedTokens: choice.observedTokens,
+                    chosenTokens: chosen.estimatedTokens,
+                    chosenViewKind: chosen.viewKind,
+                    savedTokensUpperBound: Math.max(0, choice.observedTokens - chosen.estimatedTokens),
+                    coverageStatus: chosen.coverageStatus,
+                    infeasible: false,
+                });
+            ensure(Number.isFinite(record.savedTokensUpperBound), "savedTokensUpperBound must be finite");
+            records.push(record);
+            return record;
+        },
+        get records() {
+            return records;
+        },
+        summary() {
+            let observedTokens = 0;
+            let chosenTokens = 0;
+            let savedTokensUpperBound = 0;
+            let infeasible = 0;
+            let coverageComplete = 0;
+            let coveragePartial = 0;
+            let coverageUnknown = 0;
+            for (const r of records) {
+                observedTokens += r.observedTokens;
+                chosenTokens += r.chosenTokens;
+                savedTokensUpperBound += r.savedTokensUpperBound;
+                if (r.infeasible)
+                    infeasible += 1;
+                if (r.coverageStatus === "complete")
+                    coverageComplete += 1;
+                else if (r.coverageStatus === "partial")
+                    coveragePartial += 1;
+                else
+                    coverageUnknown += 1;
+            }
+            return {
+                observations: records.length,
+                observedTokens,
+                chosenTokens,
+                savedTokensUpperBound,
+                infeasible,
+                coverageComplete,
+                coveragePartial,
+                coverageUnknown,
+            };
+        },
+    };
+}
+//# sourceMappingURL=observe-mode.js.map

package/dist/observation/observe-mode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observe-mode.js","sourceRoot":"","sources":["../../src/observation/observe-mode.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,gCAAgC,CAAC;AAmCvE;;;;;GAKG;AACH,MAAM,UAAU,6BAA6B,GAA4B;IACxE,MAAM,OAAO,GAA8B,EAAE,CAAC;IAC9C,OAAO;QACN,MAAM,CAAC,MAAM,EAAE;YACd,IAAI,CAAC,MAAM,CAAC,aAAa,EAAE,eAAe,EAAE,GAAG,CAAC,CAAC;YACjD,OAAO,CAAC,MAAM,CAAC,cAAc,EAAE,gBAAgB,CAAC,CAAC;YACjD,MAAM,MAAM,GAAG,MAAM,CAAC,UAAU,CAAC;YACjC,MAAM,MAAM,GACX,MAAM,KAAK,IAAI;gBACd,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC;oBACd,aAAa,EAAE,MAAM,CAAC,aAAa;oBACnC,cAAc,EAAE,MAAM,CAAC,cAAc;oBACrC,YAAY,EAAE,MAAM,CAAC,cAAc;oBACnC,cAAc,EAAE,YAAY;oBAC5B,qBAAqB,EAAE,CAAC;oBACxB,cAAc,EAAE,SAAS;oBACzB,UAAU,EAAE,IAAI;iBAChB,CAAC;gBACH,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC;oBACd,aAAa,EAAE,MAAM,CAAC,aAAa;oBACnC,cAAc,EAAE,MAAM,CAAC,cAAc;oBACrC,YAAY,EAAE,MAAM,CAAC,eAAe;oBACpC,cAAc,EAAE,MAAM,CAAC,QAAQ;oBAC/B,qBAAqB,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,cAAc,GAAG,MAAM,CAAC,eAAe,CAAC;oBAClF,cAAc,EAAE,MAAM,CAAC,cAAc;oBACrC,UAAU,EAAE,KAAK;iBACjB,CAAC,CAAC;YACN,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,qBAAqB,CAAC,EAAE,sCAAsC,CAAC,CAAC;YAC9F,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACrB,OAAO,MAAM,CAAC;QAAA,CACd;QACD,IAAI,OAAO,GAAG;YACb,OAAO,OAAO,CAAC;QAAA,CACf;QACD,OAAO,GAAG;YACT,IAAI,cAAc,GAAG,CAAC,CAAC;YACvB,IAAI,YAAY,GAAG,CAAC,CAAC;YACrB,IAAI,qBAAqB,GAAG,CAAC,CAAC;YAC9B,IAAI,UAAU,GAAG,CAAC,CAAC;YACnB,IAAI,gBAAgB,GAAG,CAAC,CAAC;YACzB,IAAI,eAAe,GAAG,CAAC,CAAC;YACxB,IAAI,eAAe,GAAG,CAAC,CAAC;YACxB,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;gBACzB,cAAc,IAAI,CAAC,CAAC,cAAc,CAAC;gBACnC,YAAY,IAAI,CAAC,CAAC,YAAY,CAAC;gBAC/B,qBAAqB,IAAI,CAAC,CAAC,qBAAqB,CAAC;gBACjD,IAAI,CAAC,CAAC,UAAU;oBAAE,UAAU,IAAI,CAAC,CAAC;gBAClC,IAAI,CAAC,CAAC,cAAc,KAAK,UAAU;oBAAE,gBAAgB,IAAI,CAAC,CAAC;qBACtD,IAAI,CAAC,CAAC,cAAc,KAAK,SAAS;oBAAE,eAAe,IAAI,CAAC,CAAC;;oBACzD,eAAe,IAAI,CAAC,CAAC;YAC3B,CAAC;YACD,OAAO;gBACN,YAAY,EAAE,OAAO,CAAC,MAAM;gBAC5B,cAAc;gBACd,YAAY;gBACZ,qBAAqB;gBACrB,UAAU;gBACV,gBAAgB;gBAChB,eAAe;gBACf,eAAe;aACf,CAAC;QAAA,CACF;KACD,CAAC;AAAA,CACF","sourcesContent":["/**\n * Observation-mode recorder — U1 shadow evaluation.\n *\n * Records what the coverage-gated deterministic view would have chosen and the\n * upper-bound token saving, without changing what the model actually receives.\n * A projected saving is an estimate, never an achieved saving — promotion out\n * of observation mode requires a real comparison on the same budget.\n */\n\nimport { ensure, integer, text } from \"../metacognition/validation.ts\";\nimport type { ObservationView } from \"./types.ts\";\n\nexport interface ObservationChoiceRecord {\n\treadonly observationId: string;\n\treadonly observedTokens: number;\n\treadonly chosenTokens: number;\n\treadonly chosenViewKind: string;\n\treadonly savedTokensUpperBound: number;\n\treadonly coverageStatus: string;\n\treadonly infeasible: boolean;\n}\n\nexport interface ObservationModeSummary {\n\treadonly observations: number;\n\treadonly observedTokens: number;\n\treadonly chosenTokens: number;\n\treadonly savedTokensUpperBound: number;\n\treadonly infeasible: number;\n\treadonly coverageComplete: number;\n\treadonly coveragePartial: number;\n\treadonly coverageUnknown: number;\n}\n\nexport interface ObservationModeRecorder {\n\trecord(choice: {\n\t\treadonly observationId: string;\n\t\treadonly observedTokens: number;\n\t\treadonly chosenView: ObservationView | null;\n\t\treadonly requiredFactIds?: readonly string[];\n\t}): ObservationChoiceRecord;\n\treadonly records: readonly ObservationChoiceRecord[];\n\tsummary(): ObservationModeSummary;\n}\n\n/**\n * Pure recorder: given what the model actually saw (`observedTokens`) and what\n * the gated selector would have chosen, emit one decision record. A null\n * `chosenView` means the candidate set was infeasible under the required\n * coverage — recorded as such, never converted into an implicit success.\n */\nexport function createObservationModeRecorder(): ObservationModeRecorder {\n\tconst records: ObservationChoiceRecord[] = [];\n\treturn {\n\t\trecord(choice) {\n\t\t\ttext(choice.observationId, \"observationId\", 128);\n\t\t\tinteger(choice.observedTokens, \"observedTokens\");\n\t\t\tconst chosen = choice.chosenView;\n\t\t\tconst record: ObservationChoiceRecord =\n\t\t\t\tchosen === null\n\t\t\t\t\t? Object.freeze({\n\t\t\t\t\t\t\tobservationId: choice.observationId,\n\t\t\t\t\t\t\tobservedTokens: choice.observedTokens,\n\t\t\t\t\t\t\tchosenTokens: choice.observedTokens,\n\t\t\t\t\t\t\tchosenViewKind: \"infeasible\",\n\t\t\t\t\t\t\tsavedTokensUpperBound: 0,\n\t\t\t\t\t\t\tcoverageStatus: \"unknown\",\n\t\t\t\t\t\t\tinfeasible: true,\n\t\t\t\t\t\t})\n\t\t\t\t\t: Object.freeze({\n\t\t\t\t\t\t\tobservationId: choice.observationId,\n\t\t\t\t\t\t\tobservedTokens: choice.observedTokens,\n\t\t\t\t\t\t\tchosenTokens: chosen.estimatedTokens,\n\t\t\t\t\t\t\tchosenViewKind: chosen.viewKind,\n\t\t\t\t\t\t\tsavedTokensUpperBound: Math.max(0, choice.observedTokens - chosen.estimatedTokens),\n\t\t\t\t\t\t\tcoverageStatus: chosen.coverageStatus,\n\t\t\t\t\t\t\tinfeasible: false,\n\t\t\t\t\t\t});\n\t\t\tensure(Number.isFinite(record.savedTokensUpperBound), \"savedTokensUpperBound must be finite\");\n\t\t\trecords.push(record);\n\t\t\treturn record;\n\t\t},\n\t\tget records() {\n\t\t\treturn records;\n\t\t},\n\t\tsummary() {\n\t\t\tlet observedTokens = 0;\n\t\t\tlet chosenTokens = 0;\n\t\t\tlet savedTokensUpperBound = 0;\n\t\t\tlet infeasible = 0;\n\t\t\tlet coverageComplete = 0;\n\t\t\tlet coveragePartial = 0;\n\t\t\tlet coverageUnknown = 0;\n\t\t\tfor (const r of records) {\n\t\t\t\tobservedTokens += r.observedTokens;\n\t\t\t\tchosenTokens += r.chosenTokens;\n\t\t\t\tsavedTokensUpperBound += r.savedTokensUpperBound;\n\t\t\t\tif (r.infeasible) infeasible += 1;\n\t\t\t\tif (r.coverageStatus === \"complete\") coverageComplete += 1;\n\t\t\t\telse if (r.coverageStatus === \"partial\") coveragePartial += 1;\n\t\t\t\telse coverageUnknown += 1;\n\t\t\t}\n\t\t\treturn {\n\t\t\t\tobservations: records.length,\n\t\t\t\tobservedTokens,\n\t\t\t\tchosenTokens,\n\t\t\t\tsavedTokensUpperBound,\n\t\t\t\tinfeasible,\n\t\t\t\tcoverageComplete,\n\t\t\t\tcoveragePartial,\n\t\t\t\tcoverageUnknown,\n\t\t\t};\n\t\t},\n\t};\n}\n"]}

package/dist/observation/store.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Bounded raw-observation store — U1.
+ *
+ * Session-scoped, in-memory, deterministic. Stores exact bytes with their
+ * execution identity, and serves byte-range reads that snap to UTF-8 code-point
+ * boundaries rather than emitting silently-corrupted text. Over-capacity puts
+ * fail closed with `archive-unavailable` instead of silently evicting evidence.
+ */
+import type { ObservationKind, ObservationPrivacy, ObservationReadResult, ObservationStatus, RawObservation } from "./types.ts";
+export interface ObservationStoreOptions {
+    readonly maxObservations?: number;
+    readonly maxTotalBytes?: number;
+    readonly maxObservationBytes?: number;
+}
+export declare class ObservationStore {
+    private readonly maxObservations;
+    private readonly maxTotalBytes;
+    private readonly maxObservationBytes;
+    private readonly byId;
+    private totalBytes;
+    constructor(options?: ObservationStoreOptions);
+    /** Store one raw observation. Throws (fails closed) on malformed input or capacity. */
+    put(input: {
+        readonly sessionId: string;
+        readonly runId: string;
+        readonly operationId: string;
+        readonly sequence: number;
+        readonly bytes: Uint8Array;
+        readonly status: ObservationStatus;
+        readonly kind?: ObservationKind;
+        readonly privacy?: ObservationPrivacy;
+        readonly sourceComplete?: boolean;
+        readonly toolCallId?: string;
+    }): RawObservation;
+    get(observationId: string): RawObservation | undefined;
+    has(observationId: string): boolean;
+    /**
+     * Scoped byte-range read. `scopeSessionId` must equal the observation's own
+     * session — a handle never crosses a session boundary. Byte offsets snap to
+     * UTF-8 boundaries; a `strict` range that lands mid-codepoint returns
+     * `utf8-boundary` instead of emitting corrupted text.
+     */
+    read(input: {
+        readonly observationId: string;
+        readonly scopeSessionId: string;
+        readonly byteOffset: number;
+        readonly maxBytes: number;
+        readonly strict?: boolean;
+    }): ObservationReadResult;
+    get size(): number;
+    get bytes(): number;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/observation/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/observation/store.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EACX,eAAe,EACf,kBAAkB,EAElB,qBAAqB,EACrB,iBAAiB,EACjB,cAAc,EACd,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,uBAAuB;IACvC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CACtC;AAkBD,qBAAa,gBAAgB;IAC5B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAC7C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAqC;IAC1D,OAAO,CAAC,UAAU,CAAK;IAEvB,YAAY,OAAO,GAAE,uBAA4B,EAIhD;IAED,uFAAuF;IACvF,GAAG,CAAC,KAAK,EAAE;QACV,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;QAC3B,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;QACnC,QAAQ,CAAC,IAAI,CAAC,EAAE,eAAe,CAAC;QAChC,QAAQ,CAAC,OAAO,CAAC,EAAE,kBAAkB,CAAC;QACtC,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;QAClC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;KAC7B,GAAG,cAAc,CAmCjB;IAED,GAAG,CAAC,aAAa,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAErD;IAED,GAAG,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAElC;IAED;;;;;OAKG;IACH,IAAI,CAAC,KAAK,EAAE;QACX,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;QAC/B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;QAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;KAC1B,GAAG,qBAAqB,CA+BxB;IAED,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,KAAK,IAAI,MAAM,CAElB;CACD","sourcesContent":["/**\n * Bounded raw-observation store — U1.\n *\n * Session-scoped, in-memory, deterministic. Stores exact bytes with their\n * execution identity, and serves byte-range reads that snap to UTF-8 code-point\n * boundaries rather than emitting silently-corrupted text. Over-capacity puts\n * fail closed with `archive-unavailable` instead of silently evicting evidence.\n */\n\nimport { ensure, integer, text } from \"../metacognition/validation.ts\";\nimport { observationId as makeObservationId, sha256Hex } from \"./identity.ts\";\nimport type {\n\tObservationKind,\n\tObservationPrivacy,\n\tObservationRead,\n\tObservationReadResult,\n\tObservationStatus,\n\tRawObservation,\n} from \"./types.ts\";\n\nexport interface ObservationStoreOptions {\n\treadonly maxObservations?: number;\n\treadonly maxTotalBytes?: number;\n\treadonly maxObservationBytes?: number;\n}\n\nconst DEFAULT_MAX_OBSERVATIONS = 512;\nconst DEFAULT_MAX_TOTAL_BYTES = 64 * 1024 * 1024;\nconst DEFAULT_MAX_OBSERVATION_BYTES = 8 * 1024 * 1024;\n\nconst UTF8_DECODER = new TextDecoder(\"utf-8\", { fatal: false });\n\n/** Snap a byte offset down to the nearest UTF-8 code-point boundary. */\nfunction snapUtf8Boundary(bytes: Uint8Array, offset: number): { offset: number; normalized: boolean } {\n\tif (offset <= 0 || offset >= bytes.length)\n\t\treturn { offset: Math.max(0, Math.min(offset, bytes.length)), normalized: false };\n\t// A continuation byte is 0b10xxxxxx; walk back to a lead byte or ASCII.\n\tlet i = offset;\n\twhile (i > 0 && (bytes[i]! & 0xc0) === 0x80) i -= 1;\n\treturn { offset: i, normalized: i !== offset };\n}\n\nexport class ObservationStore {\n\tprivate readonly maxObservations: number;\n\tprivate readonly maxTotalBytes: number;\n\tprivate readonly maxObservationBytes: number;\n\tprivate readonly byId = new Map<string, RawObservation>();\n\tprivate totalBytes = 0;\n\n\tconstructor(options: ObservationStoreOptions = {}) {\n\t\tthis.maxObservations = options.maxObservations ?? DEFAULT_MAX_OBSERVATIONS;\n\t\tthis.maxTotalBytes = options.maxTotalBytes ?? DEFAULT_MAX_TOTAL_BYTES;\n\t\tthis.maxObservationBytes = options.maxObservationBytes ?? DEFAULT_MAX_OBSERVATION_BYTES;\n\t}\n\n\t/** Store one raw observation. Throws (fails closed) on malformed input or capacity. */\n\tput(input: {\n\t\treadonly sessionId: string;\n\t\treadonly runId: string;\n\t\treadonly operationId: string;\n\t\treadonly sequence: number;\n\t\treadonly bytes: Uint8Array;\n\t\treadonly status: ObservationStatus;\n\t\treadonly kind?: ObservationKind;\n\t\treadonly privacy?: ObservationPrivacy;\n\t\treadonly sourceComplete?: boolean;\n\t\treadonly toolCallId?: string;\n\t}): RawObservation {\n\t\ttext(input.sessionId, \"sessionId\", 256);\n\t\ttext(input.runId, \"runId\", 256);\n\t\ttext(input.operationId, \"operationId\", 256);\n\t\tinteger(input.sequence, \"sequence\");\n\t\tensure(input.bytes instanceof Uint8Array, \"bytes must be a Uint8Array\");\n\t\tensure(input.bytes.length <= this.maxObservationBytes, \"observation exceeds per-item cap\");\n\t\tif (this.byId.size >= this.maxObservations || this.totalBytes + input.bytes.length > this.maxTotalBytes) {\n\t\t\tthrow new Error(\"archive-unavailable: observation store capacity exceeded\");\n\t\t}\n\t\tconst rawDigest = sha256Hex(input.bytes);\n\t\tconst id = makeObservationId({\n\t\t\trunId: input.runId,\n\t\t\toperationId: input.operationId,\n\t\t\tsequence: input.sequence,\n\t\t\trawDigest,\n\t\t});\n\t\tconst observation: RawObservation = Object.freeze({\n\t\t\tobservationId: id,\n\t\t\tsessionId: input.sessionId,\n\t\t\trunId: input.runId,\n\t\t\toperationId: input.operationId,\n\t\t\tsequence: input.sequence,\n\t\t\trawDigest,\n\t\t\tbyteLength: input.bytes.length,\n\t\t\tbytes: input.bytes,\n\t\t\tstatus: input.status,\n\t\t\tkind: input.kind ?? \"generic\",\n\t\t\tprivacy: input.privacy ?? \"raw-private\",\n\t\t\tsourceComplete: input.sourceComplete ?? true,\n\t\t\t...(input.toolCallId === undefined ? {} : { toolCallId: input.toolCallId }),\n\t\t});\n\t\tthis.byId.set(id, observation);\n\t\tthis.totalBytes += input.bytes.length;\n\t\treturn observation;\n\t}\n\n\tget(observationId: string): RawObservation | undefined {\n\t\treturn this.byId.get(observationId);\n\t}\n\n\thas(observationId: string): boolean {\n\t\treturn this.byId.has(observationId);\n\t}\n\n\t/**\n\t * Scoped byte-range read. `scopeSessionId` must equal the observation's own\n\t * session — a handle never crosses a session boundary. Byte offsets snap to\n\t * UTF-8 boundaries; a `strict` range that lands mid-codepoint returns\n\t * `utf8-boundary` instead of emitting corrupted text.\n\t */\n\tread(input: {\n\t\treadonly observationId: string;\n\t\treadonly scopeSessionId: string;\n\t\treadonly byteOffset: number;\n\t\treadonly maxBytes: number;\n\t\treadonly strict?: boolean;\n\t}): ObservationReadResult {\n\t\ttext(input.observationId, \"observationId\", 128);\n\t\ttext(input.scopeSessionId, \"scopeSessionId\", 256);\n\t\tinteger(input.byteOffset, \"byteOffset\");\n\t\tinteger(input.maxBytes, \"maxBytes\");\n\t\tensure(input.maxBytes > 0, \"maxBytes must be positive\");\n\t\tconst observation = this.byId.get(input.observationId);\n\t\tif (!observation) return { ok: false, error: \"observation-not-found\" };\n\t\tif (observation.sessionId !== input.scopeSessionId) {\n\t\t\treturn { ok: false, error: \"scope-mismatch\" };\n\t\t}\n\t\tif (input.byteOffset > observation.byteLength) {\n\t\t\treturn { ok: false, error: \"invalid-range\" };\n\t\t}\n\t\tconst snapped = snapUtf8Boundary(observation.bytes, input.byteOffset);\n\t\tif (input.strict && snapped.normalized) return { ok: false, error: \"utf8-boundary\" };\n\t\tconst start = snapped.offset;\n\t\tconst end = Math.min(observation.byteLength, start + input.maxBytes);\n\t\tconst chunk = observation.bytes.slice(start, end);\n\t\tconst read: ObservationRead = {\n\t\t\tobservationId: observation.observationId,\n\t\t\ttext: UTF8_DECODER.decode(chunk),\n\t\t\tbyteOffset: start,\n\t\t\tbyteLength: chunk.length,\n\t\t\tnextOffset: end,\n\t\t\teof: end >= observation.byteLength,\n\t\t\ttruncated: end < observation.byteLength,\n\t\t\tsourceComplete: observation.sourceComplete,\n\t\t\tnormalized: snapped.normalized,\n\t\t};\n\t\treturn { ok: true, read };\n\t}\n\n\tget size(): number {\n\t\treturn this.byId.size;\n\t}\n\n\tget bytes(): number {\n\t\treturn this.totalBytes;\n\t}\n}\n"]}

package/dist/observation/store.js

@@ -0,0 +1,126 @@
+/**
+ * Bounded raw-observation store — U1.
+ *
+ * Session-scoped, in-memory, deterministic. Stores exact bytes with their
+ * execution identity, and serves byte-range reads that snap to UTF-8 code-point
+ * boundaries rather than emitting silently-corrupted text. Over-capacity puts
+ * fail closed with `archive-unavailable` instead of silently evicting evidence.
+ */
+import { ensure, integer, text } from "../metacognition/validation.js";
+import { observationId as makeObservationId, sha256Hex } from "./identity.js";
+const DEFAULT_MAX_OBSERVATIONS = 512;
+const DEFAULT_MAX_TOTAL_BYTES = 64 * 1024 * 1024;
+const DEFAULT_MAX_OBSERVATION_BYTES = 8 * 1024 * 1024;
+const UTF8_DECODER = new TextDecoder("utf-8", { fatal: false });
+/** Snap a byte offset down to the nearest UTF-8 code-point boundary. */
+function snapUtf8Boundary(bytes, offset) {
+    if (offset <= 0 || offset >= bytes.length)
+        return { offset: Math.max(0, Math.min(offset, bytes.length)), normalized: false };
+    // A continuation byte is 0b10xxxxxx; walk back to a lead byte or ASCII.
+    let i = offset;
+    while (i > 0 && (bytes[i] & 0xc0) === 0x80)
+        i -= 1;
+    return { offset: i, normalized: i !== offset };
+}
+export class ObservationStore {
+    maxObservations;
+    maxTotalBytes;
+    maxObservationBytes;
+    byId = new Map();
+    totalBytes = 0;
+    constructor(options = {}) {
+        this.maxObservations = options.maxObservations ?? DEFAULT_MAX_OBSERVATIONS;
+        this.maxTotalBytes = options.maxTotalBytes ?? DEFAULT_MAX_TOTAL_BYTES;
+        this.maxObservationBytes = options.maxObservationBytes ?? DEFAULT_MAX_OBSERVATION_BYTES;
+    }
+    /** Store one raw observation. Throws (fails closed) on malformed input or capacity. */
+    put(input) {
+        text(input.sessionId, "sessionId", 256);
+        text(input.runId, "runId", 256);
+        text(input.operationId, "operationId", 256);
+        integer(input.sequence, "sequence");
+        ensure(input.bytes instanceof Uint8Array, "bytes must be a Uint8Array");
+        ensure(input.bytes.length <= this.maxObservationBytes, "observation exceeds per-item cap");
+        if (this.byId.size >= this.maxObservations || this.totalBytes + input.bytes.length > this.maxTotalBytes) {
+            throw new Error("archive-unavailable: observation store capacity exceeded");
+        }
+        const rawDigest = sha256Hex(input.bytes);
+        const id = makeObservationId({
+            runId: input.runId,
+            operationId: input.operationId,
+            sequence: input.sequence,
+            rawDigest,
+        });
+        const observation = Object.freeze({
+            observationId: id,
+            sessionId: input.sessionId,
+            runId: input.runId,
+            operationId: input.operationId,
+            sequence: input.sequence,
+            rawDigest,
+            byteLength: input.bytes.length,
+            bytes: input.bytes,
+            status: input.status,
+            kind: input.kind ?? "generic",
+            privacy: input.privacy ?? "raw-private",
+            sourceComplete: input.sourceComplete ?? true,
+            ...(input.toolCallId === undefined ? {} : { toolCallId: input.toolCallId }),
+        });
+        this.byId.set(id, observation);
+        this.totalBytes += input.bytes.length;
+        return observation;
+    }
+    get(observationId) {
+        return this.byId.get(observationId);
+    }
+    has(observationId) {
+        return this.byId.has(observationId);
+    }
+    /**
+     * Scoped byte-range read. `scopeSessionId` must equal the observation's own
+     * session — a handle never crosses a session boundary. Byte offsets snap to
+     * UTF-8 boundaries; a `strict` range that lands mid-codepoint returns
+     * `utf8-boundary` instead of emitting corrupted text.
+     */
+    read(input) {
+        text(input.observationId, "observationId", 128);
+        text(input.scopeSessionId, "scopeSessionId", 256);
+        integer(input.byteOffset, "byteOffset");
+        integer(input.maxBytes, "maxBytes");
+        ensure(input.maxBytes > 0, "maxBytes must be positive");
+        const observation = this.byId.get(input.observationId);
+        if (!observation)
+            return { ok: false, error: "observation-not-found" };
+        if (observation.sessionId !== input.scopeSessionId) {
+            return { ok: false, error: "scope-mismatch" };
+        }
+        if (input.byteOffset > observation.byteLength) {
+            return { ok: false, error: "invalid-range" };
+        }
+        const snapped = snapUtf8Boundary(observation.bytes, input.byteOffset);
+        if (input.strict && snapped.normalized)
+            return { ok: false, error: "utf8-boundary" };
+        const start = snapped.offset;
+        const end = Math.min(observation.byteLength, start + input.maxBytes);
+        const chunk = observation.bytes.slice(start, end);
+        const read = {
+            observationId: observation.observationId,
+            text: UTF8_DECODER.decode(chunk),
+            byteOffset: start,
+            byteLength: chunk.length,
+            nextOffset: end,
+            eof: end >= observation.byteLength,
+            truncated: end < observation.byteLength,
+            sourceComplete: observation.sourceComplete,
+            normalized: snapped.normalized,
+        };
+        return { ok: true, read };
+    }
+    get size() {
+        return this.byId.size;
+    }
+    get bytes() {
+        return this.totalBytes;
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/observation/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/observation/store.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Bounded raw-observation store — U1.\n *\n * Session-scoped, in-memory, deterministic. Stores exact bytes with their\n * execution identity, and serves byte-range reads that snap to UTF-8 code-point\n * boundaries rather than emitting silently-corrupted text. Over-capacity puts\n * fail closed with `archive-unavailable` instead of silently evicting evidence.\n */\n\nimport { ensure, integer, text } from \"../metacognition/validation.ts\";\nimport { observationId as makeObservationId, sha256Hex } from \"./identity.ts\";\nimport type {\n\tObservationKind,\n\tObservationPrivacy,\n\tObservationRead,\n\tObservationReadResult,\n\tObservationStatus,\n\tRawObservation,\n} from \"./types.ts\";\n\nexport interface ObservationStoreOptions {\n\treadonly maxObservations?: number;\n\treadonly maxTotalBytes?: number;\n\treadonly maxObservationBytes?: number;\n}\n\nconst DEFAULT_MAX_OBSERVATIONS = 512;\nconst DEFAULT_MAX_TOTAL_BYTES = 64 * 1024 * 1024;\nconst DEFAULT_MAX_OBSERVATION_BYTES = 8 * 1024 * 1024;\n\nconst UTF8_DECODER = new TextDecoder(\"utf-8\", { fatal: false });\n\n/** Snap a byte offset down to the nearest UTF-8 code-point boundary. */\nfunction snapUtf8Boundary(bytes: Uint8Array, offset: number): { offset: number; normalized: boolean } {\n\tif (offset <= 0 || offset >= bytes.length)\n\t\treturn { offset: Math.max(0, Math.min(offset, bytes.length)), normalized: false };\n\t// A continuation byte is 0b10xxxxxx; walk back to a lead byte or ASCII.\n\tlet i = offset;\n\twhile (i > 0 && (bytes[i]! & 0xc0) === 0x80) i -= 1;\n\treturn { offset: i, normalized: i !== offset };\n}\n\nexport class ObservationStore {\n\tprivate readonly maxObservations: number;\n\tprivate readonly maxTotalBytes: number;\n\tprivate readonly maxObservationBytes: number;\n\tprivate readonly byId = new Map<string, RawObservation>();\n\tprivate totalBytes = 0;\n\n\tconstructor(options: ObservationStoreOptions = {}) {\n\t\tthis.maxObservations = options.maxObservations ?? DEFAULT_MAX_OBSERVATIONS;\n\t\tthis.maxTotalBytes = options.maxTotalBytes ?? DEFAULT_MAX_TOTAL_BYTES;\n\t\tthis.maxObservationBytes = options.maxObservationBytes ?? DEFAULT_MAX_OBSERVATION_BYTES;\n\t}\n\n\t/** Store one raw observation. Throws (fails closed) on malformed input or capacity. */\n\tput(input: {\n\t\treadonly sessionId: string;\n\t\treadonly runId: string;\n\t\treadonly operationId: string;\n\t\treadonly sequence: number;\n\t\treadonly bytes: Uint8Array;\n\t\treadonly status: ObservationStatus;\n\t\treadonly kind?: ObservationKind;\n\t\treadonly privacy?: ObservationPrivacy;\n\t\treadonly sourceComplete?: boolean;\n\t\treadonly toolCallId?: string;\n\t}): RawObservation {\n\t\ttext(input.sessionId, \"sessionId\", 256);\n\t\ttext(input.runId, \"runId\", 256);\n\t\ttext(input.operationId, \"operationId\", 256);\n\t\tinteger(input.sequence, \"sequence\");\n\t\tensure(input.bytes instanceof Uint8Array, \"bytes must be a Uint8Array\");\n\t\tensure(input.bytes.length <= this.maxObservationBytes, \"observation exceeds per-item cap\");\n\t\tif (this.byId.size >= this.maxObservations || this.totalBytes + input.bytes.length > this.maxTotalBytes) {\n\t\t\tthrow new Error(\"archive-unavailable: observation store capacity exceeded\");\n\t\t}\n\t\tconst rawDigest = sha256Hex(input.bytes);\n\t\tconst id = makeObservationId({\n\t\t\trunId: input.runId,\n\t\t\toperationId: input.operationId,\n\t\t\tsequence: input.sequence,\n\t\t\trawDigest,\n\t\t});\n\t\tconst observation: RawObservation = Object.freeze({\n\t\t\tobservationId: id,\n\t\t\tsessionId: input.sessionId,\n\t\t\trunId: input.runId,\n\t\t\toperationId: input.operationId,\n\t\t\tsequence: input.sequence,\n\t\t\trawDigest,\n\t\t\tbyteLength: input.bytes.length,\n\t\t\tbytes: input.bytes,\n\t\t\tstatus: input.status,\n\t\t\tkind: input.kind ?? \"generic\",\n\t\t\tprivacy: input.privacy ?? \"raw-private\",\n\t\t\tsourceComplete: input.sourceComplete ?? true,\n\t\t\t...(input.toolCallId === undefined ? {} : { toolCallId: input.toolCallId }),\n\t\t});\n\t\tthis.byId.set(id, observation);\n\t\tthis.totalBytes += input.bytes.length;\n\t\treturn observation;\n\t}\n\n\tget(observationId: string): RawObservation | undefined {\n\t\treturn this.byId.get(observationId);\n\t}\n\n\thas(observationId: string): boolean {\n\t\treturn this.byId.has(observationId);\n\t}\n\n\t/**\n\t * Scoped byte-range read. `scopeSessionId` must equal the observation's own\n\t * session — a handle never crosses a session boundary. Byte offsets snap to\n\t * UTF-8 boundaries; a `strict` range that lands mid-codepoint returns\n\t * `utf8-boundary` instead of emitting corrupted text.\n\t */\n\tread(input: {\n\t\treadonly observationId: string;\n\t\treadonly scopeSessionId: string;\n\t\treadonly byteOffset: number;\n\t\treadonly maxBytes: number;\n\t\treadonly strict?: boolean;\n\t}): ObservationReadResult {\n\t\ttext(input.observationId, \"observationId\", 128);\n\t\ttext(input.scopeSessionId, \"scopeSessionId\", 256);\n\t\tinteger(input.byteOffset, \"byteOffset\");\n\t\tinteger(input.maxBytes, \"maxBytes\");\n\t\tensure(input.maxBytes > 0, \"maxBytes must be positive\");\n\t\tconst observation = this.byId.get(input.observationId);\n\t\tif (!observation) return { ok: false, error: \"observation-not-found\" };\n\t\tif (observation.sessionId !== input.scopeSessionId) {\n\t\t\treturn { ok: false, error: \"scope-mismatch\" };\n\t\t}\n\t\tif (input.byteOffset > observation.byteLength) {\n\t\t\treturn { ok: false, error: \"invalid-range\" };\n\t\t}\n\t\tconst snapped = snapUtf8Boundary(observation.bytes, input.byteOffset);\n\t\tif (input.strict && snapped.normalized) return { ok: false, error: \"utf8-boundary\" };\n\t\tconst start = snapped.offset;\n\t\tconst end = Math.min(observation.byteLength, start + input.maxBytes);\n\t\tconst chunk = observation.bytes.slice(start, end);\n\t\tconst read: ObservationRead = {\n\t\t\tobservationId: observation.observationId,\n\t\t\ttext: UTF8_DECODER.decode(chunk),\n\t\t\tbyteOffset: start,\n\t\t\tbyteLength: chunk.length,\n\t\t\tnextOffset: end,\n\t\t\teof: end >= observation.byteLength,\n\t\t\ttruncated: end < observation.byteLength,\n\t\t\tsourceComplete: observation.sourceComplete,\n\t\t\tnormalized: snapped.normalized,\n\t\t};\n\t\treturn { ok: true, read };\n\t}\n\n\tget size(): number {\n\t\treturn this.byId.size;\n\t}\n\n\tget bytes(): number {\n\t\treturn this.totalBytes;\n\t}\n}\n"]}

package/dist/observation/types.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Observation kernel types — U1/U2 of the upgraded SoL-Pi design.
+ *
+ * Raw observations are host-owned execution artifacts. Model-facing views are
+ * derived projections and never replace the raw authority: `taskVerdict` is
+ * always `not-assessed` here because a view cannot prove completion.
+ */
+export type ObservationStatus = "exit" | "signal" | "partial" | "unavailable";
+export type ObservationPrivacy = "raw-private" | "approved-sanitized";
+export type ObservationKind = "log" | "test" | "command" | "file" | "dom" | "network" | "generic";
+/**
+ * A stored execution artifact. `observationId` binds the run, operation and
+ * sequence to the content digest, so two identical byte outputs from different
+ * executions remain distinct events (never content-hash deduped into one).
+ */
+export interface RawObservation {
+    readonly observationId: string;
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly operationId: string;
+    readonly sequence: number;
+    readonly rawDigest: string;
+    readonly byteLength: number;
+    readonly bytes: Uint8Array;
+    readonly status: ObservationStatus;
+    readonly kind: ObservationKind;
+    readonly privacy: ObservationPrivacy;
+    /** False when the capture itself was truncated upstream — never claim "full raw". */
+    readonly sourceComplete: boolean;
+    readonly toolCallId?: string;
+}
+export type ObservationViewKind = "full" | "excerpt" | "evidence" | "pointer";
+export type ObservationCoverageStatus = "complete" | "partial" | "unknown";
+/**
+ * A model-facing projection of a stored observation. `transformationDigest`
+ * binds the view to the deterministic transform that produced it, and
+ * `coverageStatus` records whether the view preserves the required fact atoms.
+ */
+export interface ObservationView {
+    readonly viewKind: ObservationViewKind;
+    readonly observationId: string;
+    readonly parentDigest: string;
+    readonly transformationDigest: string;
+    readonly text: string;
+    readonly estimatedTokens: number;
+    readonly coveredFactIds: readonly string[];
+    readonly missingRequiredFactIds: readonly string[];
+    readonly coverageStatus: ObservationCoverageStatus;
+    readonly taskVerdict: "not-assessed";
+}
+/** Result of a scoped, byte-bounded read against a stored observation. */
+export interface ObservationRead {
+    readonly observationId: string;
+    readonly text: string;
+    readonly byteOffset: number;
+    readonly byteLength: number;
+    readonly nextOffset: number;
+    readonly eof: boolean;
+    readonly truncated: boolean;
+    readonly sourceComplete: boolean;
+    /** True when the requested byte range was snapped to UTF-8 boundaries. */
+    readonly normalized: boolean;
+}
+export type ObservationReadError = "observation-not-found" | "scope-mismatch" | "invalid-range" | "utf8-boundary" | "archive-unavailable";
+export type ObservationReadResult = {
+    readonly ok: true;
+    readonly read: ObservationRead;
+} | {
+    readonly ok: false;
+    readonly error: ObservationReadError;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/observation/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/observation/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,aAAa,CAAC;AAC9E,MAAM,MAAM,kBAAkB,GAAG,aAAa,GAAG,oBAAoB,CAAC;AACtE,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,KAAK,GAAG,SAAS,GAAG,SAAS,CAAC;AAElG;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IACrC,uFAAqF;IACrF,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;AAC9E,MAAM,MAAM,yBAAyB,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,CAAC;AAE3E;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;IACvC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,QAAQ,CAAC,sBAAsB,EAAE,SAAS,MAAM,EAAE,CAAC;IACnD,QAAQ,CAAC,cAAc,EAAE,yBAAyB,CAAC;IACnD,QAAQ,CAAC,WAAW,EAAE,cAAc,CAAC;CACrC;AAED,0EAA0E;AAC1E,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,MAAM,oBAAoB,GAC7B,uBAAuB,GACvB,gBAAgB,GAChB,eAAe,GACf,eAAe,GACf,qBAAqB,CAAC;AAEzB,MAAM,MAAM,qBAAqB,GAC9B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;CAAE,GACrD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAA;CAAE,CAAC","sourcesContent":["/**\n * Observation kernel types — U1/U2 of the upgraded SoL-Pi design.\n *\n * Raw observations are host-owned execution artifacts. Model-facing views are\n * derived projections and never replace the raw authority: `taskVerdict` is\n * always `not-assessed` here because a view cannot prove completion.\n */\n\nexport type ObservationStatus = \"exit\" | \"signal\" | \"partial\" | \"unavailable\";\nexport type ObservationPrivacy = \"raw-private\" | \"approved-sanitized\";\nexport type ObservationKind = \"log\" | \"test\" | \"command\" | \"file\" | \"dom\" | \"network\" | \"generic\";\n\n/**\n * A stored execution artifact. `observationId` binds the run, operation and\n * sequence to the content digest, so two identical byte outputs from different\n * executions remain distinct events (never content-hash deduped into one).\n */\nexport interface RawObservation {\n\treadonly observationId: string;\n\treadonly sessionId: string;\n\treadonly runId: string;\n\treadonly operationId: string;\n\treadonly sequence: number;\n\treadonly rawDigest: string;\n\treadonly byteLength: number;\n\treadonly bytes: Uint8Array;\n\treadonly status: ObservationStatus;\n\treadonly kind: ObservationKind;\n\treadonly privacy: ObservationPrivacy;\n\t/** False when the capture itself was truncated upstream — never claim \"full raw\". */\n\treadonly sourceComplete: boolean;\n\treadonly toolCallId?: string;\n}\n\nexport type ObservationViewKind = \"full\" | \"excerpt\" | \"evidence\" | \"pointer\";\nexport type ObservationCoverageStatus = \"complete\" | \"partial\" | \"unknown\";\n\n/**\n * A model-facing projection of a stored observation. `transformationDigest`\n * binds the view to the deterministic transform that produced it, and\n * `coverageStatus` records whether the view preserves the required fact atoms.\n */\nexport interface ObservationView {\n\treadonly viewKind: ObservationViewKind;\n\treadonly observationId: string;\n\treadonly parentDigest: string;\n\treadonly transformationDigest: string;\n\treadonly text: string;\n\treadonly estimatedTokens: number;\n\treadonly coveredFactIds: readonly string[];\n\treadonly missingRequiredFactIds: readonly string[];\n\treadonly coverageStatus: ObservationCoverageStatus;\n\treadonly taskVerdict: \"not-assessed\";\n}\n\n/** Result of a scoped, byte-bounded read against a stored observation. */\nexport interface ObservationRead {\n\treadonly observationId: string;\n\treadonly text: string;\n\treadonly byteOffset: number;\n\treadonly byteLength: number;\n\treadonly nextOffset: number;\n\treadonly eof: boolean;\n\treadonly truncated: boolean;\n\treadonly sourceComplete: boolean;\n\t/** True when the requested byte range was snapped to UTF-8 boundaries. */\n\treadonly normalized: boolean;\n}\n\nexport type ObservationReadError =\n\t| \"observation-not-found\"\n\t| \"scope-mismatch\"\n\t| \"invalid-range\"\n\t| \"utf8-boundary\"\n\t| \"archive-unavailable\";\n\nexport type ObservationReadResult =\n\t| { readonly ok: true; readonly read: ObservationRead }\n\t| { readonly ok: false; readonly error: ObservationReadError };\n"]}

package/dist/observation/types.js

@@ -0,0 +1,9 @@
+/**
+ * Observation kernel types — U1/U2 of the upgraded SoL-Pi design.
+ *
+ * Raw observations are host-owned execution artifacts. Model-facing views are
+ * derived projections and never replace the raw authority: `taskVerdict` is
+ * always `not-assessed` here because a view cannot prove completion.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/observation/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/observation/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG","sourcesContent":["/**\n * Observation kernel types — U1/U2 of the upgraded SoL-Pi design.\n *\n * Raw observations are host-owned execution artifacts. Model-facing views are\n * derived projections and never replace the raw authority: `taskVerdict` is\n * always `not-assessed` here because a view cannot prove completion.\n */\n\nexport type ObservationStatus = \"exit\" | \"signal\" | \"partial\" | \"unavailable\";\nexport type ObservationPrivacy = \"raw-private\" | \"approved-sanitized\";\nexport type ObservationKind = \"log\" | \"test\" | \"command\" | \"file\" | \"dom\" | \"network\" | \"generic\";\n\n/**\n * A stored execution artifact. `observationId` binds the run, operation and\n * sequence to the content digest, so two identical byte outputs from different\n * executions remain distinct events (never content-hash deduped into one).\n */\nexport interface RawObservation {\n\treadonly observationId: string;\n\treadonly sessionId: string;\n\treadonly runId: string;\n\treadonly operationId: string;\n\treadonly sequence: number;\n\treadonly rawDigest: string;\n\treadonly byteLength: number;\n\treadonly bytes: Uint8Array;\n\treadonly status: ObservationStatus;\n\treadonly kind: ObservationKind;\n\treadonly privacy: ObservationPrivacy;\n\t/** False when the capture itself was truncated upstream — never claim \"full raw\". */\n\treadonly sourceComplete: boolean;\n\treadonly toolCallId?: string;\n}\n\nexport type ObservationViewKind = \"full\" | \"excerpt\" | \"evidence\" | \"pointer\";\nexport type ObservationCoverageStatus = \"complete\" | \"partial\" | \"unknown\";\n\n/**\n * A model-facing projection of a stored observation. `transformationDigest`\n * binds the view to the deterministic transform that produced it, and\n * `coverageStatus` records whether the view preserves the required fact atoms.\n */\nexport interface ObservationView {\n\treadonly viewKind: ObservationViewKind;\n\treadonly observationId: string;\n\treadonly parentDigest: string;\n\treadonly transformationDigest: string;\n\treadonly text: string;\n\treadonly estimatedTokens: number;\n\treadonly coveredFactIds: readonly string[];\n\treadonly missingRequiredFactIds: readonly string[];\n\treadonly coverageStatus: ObservationCoverageStatus;\n\treadonly taskVerdict: \"not-assessed\";\n}\n\n/** Result of a scoped, byte-bounded read against a stored observation. */\nexport interface ObservationRead {\n\treadonly observationId: string;\n\treadonly text: string;\n\treadonly byteOffset: number;\n\treadonly byteLength: number;\n\treadonly nextOffset: number;\n\treadonly eof: boolean;\n\treadonly truncated: boolean;\n\treadonly sourceComplete: boolean;\n\t/** True when the requested byte range was snapped to UTF-8 boundaries. */\n\treadonly normalized: boolean;\n}\n\nexport type ObservationReadError =\n\t| \"observation-not-found\"\n\t| \"scope-mismatch\"\n\t| \"invalid-range\"\n\t| \"utf8-boundary\"\n\t| \"archive-unavailable\";\n\nexport type ObservationReadResult =\n\t| { readonly ok: true; readonly read: ObservationRead }\n\t| { readonly ok: false; readonly error: ObservationReadError };\n"]}

package/dist/observation/view.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Deterministic observation views with a coverage gate — U1/U3.
+ *
+ * A view is a projection of a stored raw observation, never a rewrite of it.
+ * `chooseView` refuses any candidate that drops a required fact atom: a cheap
+ * representation is admissible only if it preserves the decision-relevant
+ * facts the current obligations need. `coverageStatus` is `unknown` when the
+ * input carries no required fact set — never silently "covered".
+ */
+import type { ObservationView, RawObservation } from "./types.ts";
+export declare function estimateViewTokens(text: string): number;
+/** A host-verifiable fact atom extracted from raw bytes, e.g. exitCode=1. */
+export interface FactAtom {
+    readonly id: string;
+    /** The verbatim text that must appear in a view for the atom to count as covered. */
+    readonly evidence: string;
+    readonly byteOffset: number;
+    readonly byteLength: number;
+}
+/**
+ * Extract host-verifiable fact atoms from raw bytes. `requiredFactIds` limits
+ * extraction to the caller's obligation set; when omitted, all recognized
+ * atoms are returned so a view can advertise what it preserves.
+ */
+export declare function extractFacts(raw: Uint8Array, requiredFactIds?: readonly string[]): FactAtom[];
+/**
+ * Build the candidate views for one observation. Every view records which
+ * fact atoms it preserves and which required atoms it would drop, so the
+ * selector can gate on coverage rather than token density alone.
+ */
+export declare function makeViews(observation: RawObservation, requiredFactIds?: readonly string[]): readonly ObservationView[];
+/**
+ * Coverage-gated deterministic selection: the smallest view that preserves
+ * every required fact within budget. Returns null (infeasible) rather than
+ * silently dropping a required atom — the caller must widen the budget or keep
+ * the raw observation.
+ */
+export declare function chooseView(views: readonly ObservationView[], budgetTokens: number, requiredFactIds?: readonly string[]): ObservationView | null;
+//# sourceMappingURL=view.d.ts.map