open-multi-agent-kit 1.0.0 → 1.2.0

package/dist/metacognition/verifier.js

@@ -0,0 +1,88 @@
+/**
+ * Algorithm D — meta-verification: checking that a check detects the defect
+ * it claims to cover. Spec §7.
+ *
+ * Obligation-scoped negative controls are evaluated over VALID, non-equivalent
+ * mutants only. Environment failures, compile-broken mutants, and timeouts are
+ * never counted as semantic detections. An empty denominator is `unknown`,
+ * never a score. This is an empirical detection rate for this mutant set,
+ * not the probability the code is correct.
+ */
+import { ensure, finite, integer, lexical, member, text, unique } from "./validation.js";
+const MUTANT_BOUND = 1024;
+export function evaluateVerifier(obligationId, mutants, checksValidOnHealthy) {
+    text(obligationId, "obligationId", 256);
+    ensure(mutants.length <= MUTANT_BOUND, "too many mutants");
+    unique(mutants.map((m) => m.mutantId), "mutant ids");
+    const scoped = mutants.filter((m) => m.obligationId === obligationId);
+    const excluded = {
+        equivalent: 0,
+        "invalid-compile": 0,
+        "environment-failure": 0,
+        timeout: 0,
+        "killed-unintended": 0,
+    };
+    let detected = 0;
+    const survivors = [];
+    const blindSpots = [];
+    for (const m of scoped) {
+        member(m.classification, [
+            "killed-intended",
+            "survived",
+            "equivalent",
+            "invalid-compile",
+            "environment-failure",
+            "timeout",
+            "killed-unintended",
+        ], "mutant classification");
+        if (m.classification === "killed-intended" && m.intendedViolation) {
+            detected += 1;
+        }
+        else if (m.classification === "survived") {
+            survivors.push(m.mutantId);
+            blindSpots.push(`undetected-violation:${m.mutantId}`);
+        }
+        else {
+            excluded[m.classification] += 1;
+            if (m.classification === "invalid-compile" || m.classification === "environment-failure") {
+                blindSpots.push(`uninformative-mutant:${m.mutantId}`);
+            }
+        }
+    }
+    if (!checksValidOnHealthy)
+        blindSpots.push("check-invalid-on-healthy-candidate");
+    const denominator = detected + survivors.length;
+    return {
+        obligationId,
+        detectionRate: denominator === 0 ? "unknown" : detected / denominator,
+        evaluated: denominator,
+        excluded,
+        survivingMutantIds: survivors.sort(lexical),
+        blindSpots: blindSpots.sort(lexical),
+    };
+}
+export function relationApplicable(rel) {
+    return rel.requiredProperty;
+}
+export function progressKey(k) {
+    return [k.goalScope, k.candidateFamily, k.errorClass, k.approach, k.checkMethod, k.sourceFamily].join("\u001f");
+}
+export function isStagnant(current, history, maxRepetitions) {
+    integer(maxRepetitions, "maxRepetitions", 64);
+    const key = progressKey(current);
+    let repeats = 0;
+    for (const entry of history) {
+        if (entry.key === key && !entry.newEvidence && entry.resolvedObligations === 0 && entry.newValidChecks === 0) {
+            repeats += 1;
+        }
+    }
+    return repeats >= maxRepetitions;
+}
+/** §10.2 net strategy-switch score with hysteresis margin. */
+export function netSwitchValue(estimatedLossDelta, cost, switchCost) {
+    finite(estimatedLossDelta, "estimatedLossDelta");
+    finite(cost, "cost");
+    finite(switchCost, "switchCost");
+    return estimatedLossDelta - cost - switchCost;
+}
+//# sourceMappingURL=verifier.js.map

package/dist/metacognition/verifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verifier.js","sourceRoot":"","sources":["../../src/metacognition/verifier.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Algorithm D — meta-verification: checking that a check detects the defect\n * it claims to cover. Spec §7.\n *\n * Obligation-scoped negative controls are evaluated over VALID, non-equivalent\n * mutants only. Environment failures, compile-broken mutants, and timeouts are\n * never counted as semantic detections. An empty denominator is `unknown`,\n * never a score. This is an empirical detection rate for this mutant set,\n * not the probability the code is correct.\n */\nimport { ensure, finite, integer, lexical, member, text, unique } from \"./validation.ts\";\n\nexport type MutantClass =\n\t| \"killed-intended\"\n\t| \"survived\"\n\t| \"equivalent\"\n\t| \"invalid-compile\"\n\t| \"environment-failure\"\n\t| \"timeout\"\n\t| \"killed-unintended\";\nexport interface MutantRecord {\n\treadonly mutantId: string;\n\treadonly obligationId: string;\n\t/** The host classifies the outcome; this module never guesses. */\n\treadonly classification: MutantClass;\n\t/** Whether the intended obligation violation was what the check caught. */\n\treadonly intendedViolation: boolean;\n}\nexport interface VerifierEvaluation {\n\treadonly obligationId: string;\n\t/** D_v over valid non-equivalent mutants; \"unknown\" when empty. */\n\treadonly detectionRate: number | \"unknown\";\n\treadonly evaluated: number;\n\treadonly excluded: Readonly<Record<Exclude<MutantClass, \"killed-intended\" | \"survived\">, number>>;\n\treadonly survivingMutantIds: readonly string[];\n\treadonly blindSpots: readonly string[];\n}\n\nconst MUTANT_BOUND = 1024;\n\nexport function evaluateVerifier(\n\tobligationId: string,\n\tmutants: readonly MutantRecord[],\n\tchecksValidOnHealthy: boolean,\n): VerifierEvaluation {\n\ttext(obligationId, \"obligationId\", 256);\n\tensure(mutants.length <= MUTANT_BOUND, \"too many mutants\");\n\tunique(\n\t\tmutants.map((m) => m.mutantId),\n\t\t\"mutant ids\",\n\t);\n\tconst scoped = mutants.filter((m) => m.obligationId === obligationId);\n\tconst excluded: Record<Exclude<MutantClass, \"killed-intended\" | \"survived\">, number> = {\n\t\tequivalent: 0,\n\t\t\"invalid-compile\": 0,\n\t\t\"environment-failure\": 0,\n\t\ttimeout: 0,\n\t\t\"killed-unintended\": 0,\n\t};\n\tlet detected = 0;\n\tconst survivors: string[] = [];\n\tconst blindSpots: string[] = [];\n\tfor (const m of scoped) {\n\t\tmember(\n\t\t\tm.classification,\n\t\t\t[\n\t\t\t\t\"killed-intended\",\n\t\t\t\t\"survived\",\n\t\t\t\t\"equivalent\",\n\t\t\t\t\"invalid-compile\",\n\t\t\t\t\"environment-failure\",\n\t\t\t\t\"timeout\",\n\t\t\t\t\"killed-unintended\",\n\t\t\t],\n\t\t\t\"mutant classification\",\n\t\t);\n\t\tif (m.classification === \"killed-intended\" && m.intendedViolation) {\n\t\t\tdetected += 1;\n\t\t} else if (m.classification === \"survived\") {\n\t\t\tsurvivors.push(m.mutantId);\n\t\t\tblindSpots.push(`undetected-violation:${m.mutantId}`);\n\t\t} else {\n\t\t\texcluded[m.classification as keyof typeof excluded] += 1;\n\t\t\tif (m.classification === \"invalid-compile\" || m.classification === \"environment-failure\") {\n\t\t\t\tblindSpots.push(`uninformative-mutant:${m.mutantId}`);\n\t\t\t}\n\t\t}\n\t}\n\tif (!checksValidOnHealthy) blindSpots.push(\"check-invalid-on-healthy-candidate\");\n\tconst denominator = detected + survivors.length;\n\treturn {\n\t\tobligationId,\n\t\tdetectionRate: denominator === 0 ? \"unknown\" : detected / denominator,\n\t\tevaluated: denominator,\n\t\texcluded,\n\t\tsurvivingMutantIds: survivors.sort(lexical),\n\t\tblindSpots: blindSpots.sort(lexical),\n\t};\n}\n\n/**\n * §7.4 metamorphic relation: Pre(x,T) ⟹ R(f(x), f(T(x))). The relation must\n * be a declared required property of this program — never a universal rule.\n */\nexport interface MetamorphicRelation {\n\treadonly relationId: string;\n\treadonly description: string;\n\treadonly precondition: string;\n\treadonly requiredProperty: boolean;\n}\nexport function relationApplicable(rel: MetamorphicRelation): boolean {\n\treturn rel.requiredProperty;\n}\n\n/** §10.1 progress key: same key + no new adopted evidence = repetition. */\nexport interface ProgressKey {\n\treadonly goalScope: string;\n\treadonly candidateFamily: string;\n\treadonly errorClass: string;\n\treadonly approach: string;\n\treadonly checkMethod: string;\n\treadonly sourceFamily: string;\n}\nexport function progressKey(k: ProgressKey): string {\n\treturn [k.goalScope, k.candidateFamily, k.errorClass, k.approach, k.checkMethod, k.sourceFamily].join(\"\\u001f\");\n}\nexport function isStagnant(\n\tcurrent: ProgressKey,\n\thistory: readonly { key: string; newEvidence: boolean; resolvedObligations: number; newValidChecks: number }[],\n\tmaxRepetitions: number,\n): boolean {\n\tinteger(maxRepetitions, \"maxRepetitions\", 64);\n\tconst key = progressKey(current);\n\tlet repeats = 0;\n\tfor (const entry of history) {\n\t\tif (entry.key === key && !entry.newEvidence && entry.resolvedObligations === 0 && entry.newValidChecks === 0) {\n\t\t\trepeats += 1;\n\t\t}\n\t}\n\treturn repeats >= maxRepetitions;\n}\n\n/** §10.2 net strategy-switch score with hysteresis margin. */\nexport function netSwitchValue(estimatedLossDelta: number, cost: number, switchCost: number): number {\n\tfinite(estimatedLossDelta, \"estimatedLossDelta\");\n\tfinite(cost, \"cost\");\n\tfinite(switchCost, \"switchCost\");\n\treturn estimatedLossDelta - cost - switchCost;\n}\n"]}

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"]}