open-multi-agent-kit 1.0.0 → 1.2.2

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"view.d.ts","sourceRoot":"","sources":["../../src/observation/view.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAA6B,eAAe,EAAuB,cAAc,EAAE,MAAM,YAAY,CAAC;AAOlH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,6EAA6E;AAC7E,MAAM,WAAW,QAAQ;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,qFAAqF;IACrF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC5B;AASD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,UAAU,EAAE,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,QAAQ,EAAE,CAyB7F;AAwDD;;;;GAIG;AACH,wBAAgB,SAAS,CACxB,WAAW,EAAE,cAAc,EAC3B,eAAe,GAAE,SAAS,MAAM,EAAO,GACrC,SAAS,eAAe,EAAE,CAkC5B;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CACzB,KAAK,EAAE,SAAS,eAAe,EAAE,EACjC,YAAY,EAAE,MAAM,EACpB,eAAe,GAAE,SAAS,MAAM,EAAO,GACrC,eAAe,GAAG,IAAI,CAqBxB","sourcesContent":["/**\n * Deterministic observation views with a coverage gate — U1/U3.\n *\n * A view is a projection of a stored raw observation, never a rewrite of it.\n * `chooseView` refuses any candidate that drops a required fact atom: a cheap\n * representation is admissible only if it preserves the decision-relevant\n * facts the current obligations need. `coverageStatus` is `unknown` when the\n * input carries no required fact set — never silently \"covered\".\n */\n\nimport { ensure, integer, text } from \"../metacognition/validation.ts\";\nimport { viewDigestOf } from \"./identity.ts\";\nimport type { ObservationCoverageStatus, ObservationView, ObservationViewKind, RawObservation } from \"./types.ts\";\n\nconst CHARS_PER_TOKEN = 4;\n/** Per-atom-class occurrence cap. Four classes stay well under any global bound. */\nconst MAX_FACTS_PER_ID = 32;\nconst MAX_VIEW_TEXT = 32_768;\n\nexport function estimateViewTokens(text: string): number {\n\treturn Math.max(1, Math.ceil(text.length / CHARS_PER_TOKEN));\n}\n\n/** A host-verifiable fact atom extracted from raw bytes, e.g. exitCode=1. */\nexport interface FactAtom {\n\treadonly id: string;\n\t/** The verbatim text that must appear in a view for the atom to count as covered. */\n\treadonly evidence: string;\n\treadonly byteOffset: number;\n\treadonly byteLength: number;\n}\n\nconst FACT_PATTERNS: readonly { readonly id: string; readonly re: RegExp }[] = [\n\t{ id: \"exit-code\", re: /exit code[:\\s]+(-?\\d+)|exitCode\\s*[=:]\\s*(-?\\d+)/i },\n\t{ id: \"test-failure\", re: /FAIL[:\\s]+([A-Za-z0-9_.\\-/]+)|✗\\s*([A-Za-z0-9_.\\-/]+)/ },\n\t{ id: \"permission-denied\", re: /permission[ _-]?denied|EACCES/i },\n\t{ id: \"error-marker\", re: /(?:error|errno|exception|traceback)[:\\s]/i },\n];\n\n/**\n * Extract host-verifiable fact atoms from raw bytes. `requiredFactIds` limits\n * extraction to the caller's obligation set; when omitted, all recognized\n * atoms are returned so a view can advertise what it preserves.\n */\nexport function extractFacts(raw: Uint8Array, requiredFactIds?: readonly string[]): FactAtom[] {\n\tconst decoded = new TextDecoder(\"utf-8\", { fatal: false }).decode(raw);\n\tconst encoder = new TextEncoder();\n\tconst wanted = requiredFactIds === undefined ? undefined : new Set(requiredFactIds);\n\tconst facts: FactAtom[] = [];\n\tfor (const { id, re } of FACT_PATTERNS) {\n\t\tif (wanted !== undefined && !wanted.has(id)) continue;\n\t\t// Per-id cap, not a shared running total: a log that repeats one atom\n\t\t// thousands of times must not starve a later pattern out of extraction\n\t\t// entirely, or a required atom silently disappears from every view.\n\t\tlet perId = 0;\n\t\tfor (const match of decoded.matchAll(new RegExp(re.source, re.flags.includes(\"g\") ? re.flags : `${re.flags}g`))) {\n\t\t\tif (perId >= MAX_FACTS_PER_ID) break;\n\t\t\tconst evidence = match[0];\n\t\t\tconst byteOffset = encoder.encode(decoded.slice(0, match.index ?? 0)).length;\n\t\t\tfacts.push({\n\t\t\t\tid,\n\t\t\t\tevidence,\n\t\t\t\tbyteOffset,\n\t\t\t\tbyteLength: encoder.encode(evidence).length,\n\t\t\t});\n\t\t\tperId += 1;\n\t\t}\n\t}\n\treturn facts;\n}\n\n/**\n * Collapse repeated identical atoms into one line that keeps the occurrence\n * count. Without this the evidence view of a log that repeats one failure is\n * larger than the raw text it was supposed to shrink, and the selector\n * correctly but uselessly falls back to full text.\n */\nfunction dedupeFacts(facts: readonly FactAtom[]): readonly { readonly fact: FactAtom; readonly count: number }[] {\n\tconst byKey = new Map<string, { fact: FactAtom; count: number }>();\n\tfor (const fact of facts) {\n\t\tconst key = `${fact.id}\\u0000${fact.evidence}`;\n\t\tconst existing = byKey.get(key);\n\t\tif (existing === undefined) byKey.set(key, { fact, count: 1 });\n\t\telse existing.count += 1;\n\t}\n\treturn [...byKey.values()];\n}\n\nfunction viewText(raw: Uint8Array, facts: readonly FactAtom[], kind: ObservationViewKind): string {\n\tconst decoded = new TextDecoder(\"utf-8\", { fatal: false }).decode(raw);\n\tswitch (kind) {\n\t\tcase \"full\":\n\t\t\treturn decoded;\n\t\tcase \"excerpt\": {\n\t\t\tif (decoded.length <= MAX_VIEW_TEXT) return decoded;\n\t\t\tconst head = decoded.slice(0, Math.floor(MAX_VIEW_TEXT / 2));\n\t\t\tconst tail = decoded.slice(-Math.floor(MAX_VIEW_TEXT / 2));\n\t\t\treturn `${head}\\n…[omitted ${decoded.length - MAX_VIEW_TEXT} chars]…\\n${tail}`;\n\t\t}\n\t\tcase \"evidence\":\n\t\t\treturn facts.length === 0\n\t\t\t\t? \"\"\n\t\t\t\t: dedupeFacts(facts)\n\t\t\t\t\t\t.map(({ fact, count }) =>\n\t\t\t\t\t\t\tcount === 1\n\t\t\t\t\t\t\t\t? `${fact.id} @${fact.byteOffset}: ${fact.evidence}`\n\t\t\t\t\t\t\t\t: `${fact.id} @${fact.byteOffset} \\u00d7${count}: ${fact.evidence}`,\n\t\t\t\t\t\t)\n\t\t\t\t\t\t.join(\"\\n\")\n\t\t\t\t\t\t.slice(0, MAX_VIEW_TEXT);\n\t\tcase \"pointer\":\n\t\t\treturn `[observation ${raw.length} bytes; digest-bound; read via handle]`;\n\t}\n}\n\nfunction coverageFor(\n\tcovered: readonly string[],\n\trequired: readonly string[],\n): { status: ObservationCoverageStatus; missing: readonly string[] } {\n\tif (required.length === 0) return { status: \"unknown\", missing: [] };\n\tconst coveredSet = new Set(covered);\n\tconst missing = required.filter((id) => !coveredSet.has(id));\n\treturn { status: missing.length === 0 ? \"complete\" : \"partial\", missing };\n}\n\n/**\n * Build the candidate views for one observation. Every view records which\n * fact atoms it preserves and which required atoms it would drop, so the\n * selector can gate on coverage rather than token density alone.\n */\nexport function makeViews(\n\tobservation: RawObservation,\n\trequiredFactIds: readonly string[] = [],\n): readonly ObservationView[] {\n\ttext(observation.observationId, \"observationId\", 128);\n\tfor (const id of requiredFactIds) text(id, \"requiredFactId\", 256);\n\tconst facts = extractFacts(observation.bytes);\n\tconst coveredByKind: Record<ObservationViewKind, readonly string[]> = {\n\t\tfull: facts.map((f) => f.id),\n\t\texcerpt: facts.map((f) => f.id), // excerpt keeps head+tail; see note\n\t\tevidence: facts.map((f) => f.id),\n\t\tpointer: [],\n\t};\n\tconst kinds: readonly ObservationViewKind[] = [\"full\", \"excerpt\", \"evidence\", \"pointer\"];\n\treturn kinds.map((kind) => {\n\t\tconst body = viewText(observation.bytes, facts, kind);\n\t\tconst covered = coveredByKind[kind].filter(\n\t\t\t(id) => body.includes(id) || kind !== \"evidence\" || facts.some((f) => f.id === id),\n\t\t);\n\t\tconst { status, missing } = coverageFor(covered, requiredFactIds);\n\t\treturn Object.freeze({\n\t\t\tviewKind: kind,\n\t\t\tobservationId: observation.observationId,\n\t\t\tparentDigest: observation.rawDigest,\n\t\t\ttransformationDigest: viewDigestOf({\n\t\t\t\tobservationId: observation.observationId,\n\t\t\t\tviewKind: kind,\n\t\t\t\tparams: `req:${[...requiredFactIds].sort().join(\",\")}`,\n\t\t\t}),\n\t\t\ttext: body,\n\t\t\testimatedTokens: estimateViewTokens(body),\n\t\t\tcoveredFactIds: covered,\n\t\t\tmissingRequiredFactIds: missing,\n\t\t\tcoverageStatus: status,\n\t\t\ttaskVerdict: \"not-assessed\" as const,\n\t\t});\n\t});\n}\n\n/**\n * Coverage-gated deterministic selection: the smallest view that preserves\n * every required fact within budget. Returns null (infeasible) rather than\n * silently dropping a required atom — the caller must widen the budget or keep\n * the raw observation.\n */\nexport function chooseView(\n\tviews: readonly ObservationView[],\n\tbudgetTokens: number,\n\trequiredFactIds: readonly string[] = [],\n): ObservationView | null {\n\tinteger(budgetTokens, \"budgetTokens\");\n\tensure(views.length > 0, \"views must be nonempty\");\n\tfor (const id of requiredFactIds) text(id, \"requiredFactId\", 256);\n\tconst admissible = views.filter(\n\t\t(v) => v.estimatedTokens <= budgetTokens && requiredFactIds.every((id) => v.coveredFactIds.includes(id)),\n\t);\n\tif (admissible.length === 0) return null;\n\t// Smallest tokens wins; break ties toward the higher-fidelity kind.\n\tconst rank: Record<ObservationViewKind, number> = { full: 0, excerpt: 1, evidence: 2, pointer: 3 };\n\tlet best: ObservationView | undefined;\n\tfor (const view of admissible) {\n\t\tif (\n\t\t\tbest === undefined ||\n\t\t\tview.estimatedTokens < best.estimatedTokens ||\n\t\t\t(view.estimatedTokens === best.estimatedTokens && rank[view.viewKind] < rank[best.viewKind])\n\t\t) {\n\t\t\tbest = view;\n\t\t}\n\t}\n\treturn best ?? null;\n}\n"]}

package/dist/observation/view.js

@@ -0,0 +1,173 @@
+/**
+ * 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 { ensure, integer, text } from "../metacognition/validation.js";
+import { viewDigestOf } from "./identity.js";
+const CHARS_PER_TOKEN = 4;
+/** Per-atom-class occurrence cap. Four classes stay well under any global bound. */
+const MAX_FACTS_PER_ID = 32;
+const MAX_VIEW_TEXT = 32_768;
+export function estimateViewTokens(text) {
+    return Math.max(1, Math.ceil(text.length / CHARS_PER_TOKEN));
+}
+const FACT_PATTERNS = [
+    { id: "exit-code", re: /exit code[:\s]+(-?\d+)|exitCode\s*[=:]\s*(-?\d+)/i },
+    { id: "test-failure", re: /FAIL[:\s]+([A-Za-z0-9_.\-/]+)|✗\s*([A-Za-z0-9_.\-/]+)/ },
+    { id: "permission-denied", re: /permission[ _-]?denied|EACCES/i },
+    { id: "error-marker", re: /(?:error|errno|exception|traceback)[:\s]/i },
+];
+/**
+ * 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 function extractFacts(raw, requiredFactIds) {
+    const decoded = new TextDecoder("utf-8", { fatal: false }).decode(raw);
+    const encoder = new TextEncoder();
+    const wanted = requiredFactIds === undefined ? undefined : new Set(requiredFactIds);
+    const facts = [];
+    for (const { id, re } of FACT_PATTERNS) {
+        if (wanted !== undefined && !wanted.has(id))
+            continue;
+        // Per-id cap, not a shared running total: a log that repeats one atom
+        // thousands of times must not starve a later pattern out of extraction
+        // entirely, or a required atom silently disappears from every view.
+        let perId = 0;
+        for (const match of decoded.matchAll(new RegExp(re.source, re.flags.includes("g") ? re.flags : `${re.flags}g`))) {
+            if (perId >= MAX_FACTS_PER_ID)
+                break;
+            const evidence = match[0];
+            const byteOffset = encoder.encode(decoded.slice(0, match.index ?? 0)).length;
+            facts.push({
+                id,
+                evidence,
+                byteOffset,
+                byteLength: encoder.encode(evidence).length,
+            });
+            perId += 1;
+        }
+    }
+    return facts;
+}
+/**
+ * Collapse repeated identical atoms into one line that keeps the occurrence
+ * count. Without this the evidence view of a log that repeats one failure is
+ * larger than the raw text it was supposed to shrink, and the selector
+ * correctly but uselessly falls back to full text.
+ */
+function dedupeFacts(facts) {
+    const byKey = new Map();
+    for (const fact of facts) {
+        const key = `${fact.id}\u0000${fact.evidence}`;
+        const existing = byKey.get(key);
+        if (existing === undefined)
+            byKey.set(key, { fact, count: 1 });
+        else
+            existing.count += 1;
+    }
+    return [...byKey.values()];
+}
+function viewText(raw, facts, kind) {
+    const decoded = new TextDecoder("utf-8", { fatal: false }).decode(raw);
+    switch (kind) {
+        case "full":
+            return decoded;
+        case "excerpt": {
+            if (decoded.length <= MAX_VIEW_TEXT)
+                return decoded;
+            const head = decoded.slice(0, Math.floor(MAX_VIEW_TEXT / 2));
+            const tail = decoded.slice(-Math.floor(MAX_VIEW_TEXT / 2));
+            return `${head}\n…[omitted ${decoded.length - MAX_VIEW_TEXT} chars]…\n${tail}`;
+        }
+        case "evidence":
+            return facts.length === 0
+                ? ""
+                : dedupeFacts(facts)
+                    .map(({ fact, count }) => count === 1
+                    ? `${fact.id} @${fact.byteOffset}: ${fact.evidence}`
+                    : `${fact.id} @${fact.byteOffset} \u00d7${count}: ${fact.evidence}`)
+                    .join("\n")
+                    .slice(0, MAX_VIEW_TEXT);
+        case "pointer":
+            return `[observation ${raw.length} bytes; digest-bound; read via handle]`;
+    }
+}
+function coverageFor(covered, required) {
+    if (required.length === 0)
+        return { status: "unknown", missing: [] };
+    const coveredSet = new Set(covered);
+    const missing = required.filter((id) => !coveredSet.has(id));
+    return { status: missing.length === 0 ? "complete" : "partial", missing };
+}
+/**
+ * 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 function makeViews(observation, requiredFactIds = []) {
+    text(observation.observationId, "observationId", 128);
+    for (const id of requiredFactIds)
+        text(id, "requiredFactId", 256);
+    const facts = extractFacts(observation.bytes);
+    const coveredByKind = {
+        full: facts.map((f) => f.id),
+        excerpt: facts.map((f) => f.id), // excerpt keeps head+tail; see note
+        evidence: facts.map((f) => f.id),
+        pointer: [],
+    };
+    const kinds = ["full", "excerpt", "evidence", "pointer"];
+    return kinds.map((kind) => {
+        const body = viewText(observation.bytes, facts, kind);
+        const covered = coveredByKind[kind].filter((id) => body.includes(id) || kind !== "evidence" || facts.some((f) => f.id === id));
+        const { status, missing } = coverageFor(covered, requiredFactIds);
+        return Object.freeze({
+            viewKind: kind,
+            observationId: observation.observationId,
+            parentDigest: observation.rawDigest,
+            transformationDigest: viewDigestOf({
+                observationId: observation.observationId,
+                viewKind: kind,
+                params: `req:${[...requiredFactIds].sort().join(",")}`,
+            }),
+            text: body,
+            estimatedTokens: estimateViewTokens(body),
+            coveredFactIds: covered,
+            missingRequiredFactIds: missing,
+            coverageStatus: status,
+            taskVerdict: "not-assessed",
+        });
+    });
+}
+/**
+ * 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 function chooseView(views, budgetTokens, requiredFactIds = []) {
+    integer(budgetTokens, "budgetTokens");
+    ensure(views.length > 0, "views must be nonempty");
+    for (const id of requiredFactIds)
+        text(id, "requiredFactId", 256);
+    const admissible = views.filter((v) => v.estimatedTokens <= budgetTokens && requiredFactIds.every((id) => v.coveredFactIds.includes(id)));
+    if (admissible.length === 0)
+        return null;
+    // Smallest tokens wins; break ties toward the higher-fidelity kind.
+    const rank = { full: 0, excerpt: 1, evidence: 2, pointer: 3 };
+    let best;
+    for (const view of admissible) {
+        if (best === undefined ||
+            view.estimatedTokens < best.estimatedTokens ||
+            (view.estimatedTokens === best.estimatedTokens && rank[view.viewKind] < rank[best.viewKind])) {
+            best = view;
+        }
+    }
+    return best ?? null;
+}
+//# sourceMappingURL=view.js.map

package/dist/observation/view.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"view.js","sourceRoot":"","sources":["../../src/observation/view.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Deterministic observation views with a coverage gate — U1/U3.\n *\n * A view is a projection of a stored raw observation, never a rewrite of it.\n * `chooseView` refuses any candidate that drops a required fact atom: a cheap\n * representation is admissible only if it preserves the decision-relevant\n * facts the current obligations need. `coverageStatus` is `unknown` when the\n * input carries no required fact set — never silently \"covered\".\n */\n\nimport { ensure, integer, text } from \"../metacognition/validation.ts\";\nimport { viewDigestOf } from \"./identity.ts\";\nimport type { ObservationCoverageStatus, ObservationView, ObservationViewKind, RawObservation } from \"./types.ts\";\n\nconst CHARS_PER_TOKEN = 4;\n/** Per-atom-class occurrence cap. Four classes stay well under any global bound. */\nconst MAX_FACTS_PER_ID = 32;\nconst MAX_VIEW_TEXT = 32_768;\n\nexport function estimateViewTokens(text: string): number {\n\treturn Math.max(1, Math.ceil(text.length / CHARS_PER_TOKEN));\n}\n\n/** A host-verifiable fact atom extracted from raw bytes, e.g. exitCode=1. */\nexport interface FactAtom {\n\treadonly id: string;\n\t/** The verbatim text that must appear in a view for the atom to count as covered. */\n\treadonly evidence: string;\n\treadonly byteOffset: number;\n\treadonly byteLength: number;\n}\n\nconst FACT_PATTERNS: readonly { readonly id: string; readonly re: RegExp }[] = [\n\t{ id: \"exit-code\", re: /exit code[:\\s]+(-?\\d+)|exitCode\\s*[=:]\\s*(-?\\d+)/i },\n\t{ id: \"test-failure\", re: /FAIL[:\\s]+([A-Za-z0-9_.\\-/]+)|✗\\s*([A-Za-z0-9_.\\-/]+)/ },\n\t{ id: \"permission-denied\", re: /permission[ _-]?denied|EACCES/i },\n\t{ id: \"error-marker\", re: /(?:error|errno|exception|traceback)[:\\s]/i },\n];\n\n/**\n * Extract host-verifiable fact atoms from raw bytes. `requiredFactIds` limits\n * extraction to the caller's obligation set; when omitted, all recognized\n * atoms are returned so a view can advertise what it preserves.\n */\nexport function extractFacts(raw: Uint8Array, requiredFactIds?: readonly string[]): FactAtom[] {\n\tconst decoded = new TextDecoder(\"utf-8\", { fatal: false }).decode(raw);\n\tconst encoder = new TextEncoder();\n\tconst wanted = requiredFactIds === undefined ? undefined : new Set(requiredFactIds);\n\tconst facts: FactAtom[] = [];\n\tfor (const { id, re } of FACT_PATTERNS) {\n\t\tif (wanted !== undefined && !wanted.has(id)) continue;\n\t\t// Per-id cap, not a shared running total: a log that repeats one atom\n\t\t// thousands of times must not starve a later pattern out of extraction\n\t\t// entirely, or a required atom silently disappears from every view.\n\t\tlet perId = 0;\n\t\tfor (const match of decoded.matchAll(new RegExp(re.source, re.flags.includes(\"g\") ? re.flags : `${re.flags}g`))) {\n\t\t\tif (perId >= MAX_FACTS_PER_ID) break;\n\t\t\tconst evidence = match[0];\n\t\t\tconst byteOffset = encoder.encode(decoded.slice(0, match.index ?? 0)).length;\n\t\t\tfacts.push({\n\t\t\t\tid,\n\t\t\t\tevidence,\n\t\t\t\tbyteOffset,\n\t\t\t\tbyteLength: encoder.encode(evidence).length,\n\t\t\t});\n\t\t\tperId += 1;\n\t\t}\n\t}\n\treturn facts;\n}\n\n/**\n * Collapse repeated identical atoms into one line that keeps the occurrence\n * count. Without this the evidence view of a log that repeats one failure is\n * larger than the raw text it was supposed to shrink, and the selector\n * correctly but uselessly falls back to full text.\n */\nfunction dedupeFacts(facts: readonly FactAtom[]): readonly { readonly fact: FactAtom; readonly count: number }[] {\n\tconst byKey = new Map<string, { fact: FactAtom; count: number }>();\n\tfor (const fact of facts) {\n\t\tconst key = `${fact.id}\\u0000${fact.evidence}`;\n\t\tconst existing = byKey.get(key);\n\t\tif (existing === undefined) byKey.set(key, { fact, count: 1 });\n\t\telse existing.count += 1;\n\t}\n\treturn [...byKey.values()];\n}\n\nfunction viewText(raw: Uint8Array, facts: readonly FactAtom[], kind: ObservationViewKind): string {\n\tconst decoded = new TextDecoder(\"utf-8\", { fatal: false }).decode(raw);\n\tswitch (kind) {\n\t\tcase \"full\":\n\t\t\treturn decoded;\n\t\tcase \"excerpt\": {\n\t\t\tif (decoded.length <= MAX_VIEW_TEXT) return decoded;\n\t\t\tconst head = decoded.slice(0, Math.floor(MAX_VIEW_TEXT / 2));\n\t\t\tconst tail = decoded.slice(-Math.floor(MAX_VIEW_TEXT / 2));\n\t\t\treturn `${head}\\n…[omitted ${decoded.length - MAX_VIEW_TEXT} chars]…\\n${tail}`;\n\t\t}\n\t\tcase \"evidence\":\n\t\t\treturn facts.length === 0\n\t\t\t\t? \"\"\n\t\t\t\t: dedupeFacts(facts)\n\t\t\t\t\t\t.map(({ fact, count }) =>\n\t\t\t\t\t\t\tcount === 1\n\t\t\t\t\t\t\t\t? `${fact.id} @${fact.byteOffset}: ${fact.evidence}`\n\t\t\t\t\t\t\t\t: `${fact.id} @${fact.byteOffset} \\u00d7${count}: ${fact.evidence}`,\n\t\t\t\t\t\t)\n\t\t\t\t\t\t.join(\"\\n\")\n\t\t\t\t\t\t.slice(0, MAX_VIEW_TEXT);\n\t\tcase \"pointer\":\n\t\t\treturn `[observation ${raw.length} bytes; digest-bound; read via handle]`;\n\t}\n}\n\nfunction coverageFor(\n\tcovered: readonly string[],\n\trequired: readonly string[],\n): { status: ObservationCoverageStatus; missing: readonly string[] } {\n\tif (required.length === 0) return { status: \"unknown\", missing: [] };\n\tconst coveredSet = new Set(covered);\n\tconst missing = required.filter((id) => !coveredSet.has(id));\n\treturn { status: missing.length === 0 ? \"complete\" : \"partial\", missing };\n}\n\n/**\n * Build the candidate views for one observation. Every view records which\n * fact atoms it preserves and which required atoms it would drop, so the\n * selector can gate on coverage rather than token density alone.\n */\nexport function makeViews(\n\tobservation: RawObservation,\n\trequiredFactIds: readonly string[] = [],\n): readonly ObservationView[] {\n\ttext(observation.observationId, \"observationId\", 128);\n\tfor (const id of requiredFactIds) text(id, \"requiredFactId\", 256);\n\tconst facts = extractFacts(observation.bytes);\n\tconst coveredByKind: Record<ObservationViewKind, readonly string[]> = {\n\t\tfull: facts.map((f) => f.id),\n\t\texcerpt: facts.map((f) => f.id), // excerpt keeps head+tail; see note\n\t\tevidence: facts.map((f) => f.id),\n\t\tpointer: [],\n\t};\n\tconst kinds: readonly ObservationViewKind[] = [\"full\", \"excerpt\", \"evidence\", \"pointer\"];\n\treturn kinds.map((kind) => {\n\t\tconst body = viewText(observation.bytes, facts, kind);\n\t\tconst covered = coveredByKind[kind].filter(\n\t\t\t(id) => body.includes(id) || kind !== \"evidence\" || facts.some((f) => f.id === id),\n\t\t);\n\t\tconst { status, missing } = coverageFor(covered, requiredFactIds);\n\t\treturn Object.freeze({\n\t\t\tviewKind: kind,\n\t\t\tobservationId: observation.observationId,\n\t\t\tparentDigest: observation.rawDigest,\n\t\t\ttransformationDigest: viewDigestOf({\n\t\t\t\tobservationId: observation.observationId,\n\t\t\t\tviewKind: kind,\n\t\t\t\tparams: `req:${[...requiredFactIds].sort().join(\",\")}`,\n\t\t\t}),\n\t\t\ttext: body,\n\t\t\testimatedTokens: estimateViewTokens(body),\n\t\t\tcoveredFactIds: covered,\n\t\t\tmissingRequiredFactIds: missing,\n\t\t\tcoverageStatus: status,\n\t\t\ttaskVerdict: \"not-assessed\" as const,\n\t\t});\n\t});\n}\n\n/**\n * Coverage-gated deterministic selection: the smallest view that preserves\n * every required fact within budget. Returns null (infeasible) rather than\n * silently dropping a required atom — the caller must widen the budget or keep\n * the raw observation.\n */\nexport function chooseView(\n\tviews: readonly ObservationView[],\n\tbudgetTokens: number,\n\trequiredFactIds: readonly string[] = [],\n): ObservationView | null {\n\tinteger(budgetTokens, \"budgetTokens\");\n\tensure(views.length > 0, \"views must be nonempty\");\n\tfor (const id of requiredFactIds) text(id, \"requiredFactId\", 256);\n\tconst admissible = views.filter(\n\t\t(v) => v.estimatedTokens <= budgetTokens && requiredFactIds.every((id) => v.coveredFactIds.includes(id)),\n\t);\n\tif (admissible.length === 0) return null;\n\t// Smallest tokens wins; break ties toward the higher-fidelity kind.\n\tconst rank: Record<ObservationViewKind, number> = { full: 0, excerpt: 1, evidence: 2, pointer: 3 };\n\tlet best: ObservationView | undefined;\n\tfor (const view of admissible) {\n\t\tif (\n\t\t\tbest === undefined ||\n\t\t\tview.estimatedTokens < best.estimatedTokens ||\n\t\t\t(view.estimatedTokens === best.estimatedTokens && rank[view.viewKind] < rank[best.viewKind])\n\t\t) {\n\t\t\tbest = view;\n\t\t}\n\t}\n\treturn best ?? null;\n}\n"]}

package/dist/utils/exif-orientation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"exif-orientation.d.ts","sourceRoot":"","sources":["../../src/utils/exif-orientation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,KAAK,MAAM,GAAG,cAAc,4BAA4B,CAAC,CAAC;AAgJ1D,wBAAgB,oBAAoB,CACnC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,eAAe,EACtB,aAAa,EAAE,UAAU,GACvB,eAAe,CAgCjB","sourcesContent":["import type { PhotonImageType } from \"./photon.ts\";\n\ntype Photon = typeof import(\"@silvia-odwyer/photon-node\");\n\nfunction readOrientationFromTiff(bytes: Uint8Array, tiffStart: number): number {\n\tif (tiffStart + 8 > bytes.length) return 1;\n\n\tconst byteOrder = (bytes[tiffStart] << 8) | bytes[tiffStart + 1];\n\tconst le = byteOrder === 0x4949;\n\n\tconst read16 = (pos: number): number => {\n\t\tif (le) return bytes[pos] | (bytes[pos + 1] << 8);\n\t\treturn (bytes[pos] << 8) | bytes[pos + 1];\n\t};\n\n\tconst read32 = (pos: number): number => {\n\t\tif (le) return bytes[pos] | (bytes[pos + 1] << 8) | (bytes[pos + 2] << 16) | (bytes[pos + 3] << 24);\n\t\treturn ((bytes[pos] << 24) | (bytes[pos + 1] << 16) | (bytes[pos + 2] << 8) | bytes[pos + 3]) >>> 0;\n\t};\n\n\tconst ifdOffset = read32(tiffStart + 4);\n\tconst ifdStart = tiffStart + ifdOffset;\n\tif (ifdStart + 2 > bytes.length) return 1;\n\n\tconst entryCount = read16(ifdStart);\n\tfor (let i = 0; i < entryCount; i++) {\n\t\tconst entryPos = ifdStart + 2 + i * 12;\n\t\tif (entryPos + 12 > bytes.length) return 1;\n\n\t\tif (read16(entryPos) === 0x0112) {\n\t\t\tconst value = read16(entryPos + 8);\n\t\t\treturn value >= 1 && value <= 8 ? value : 1;\n\t\t}\n\t}\n\n\treturn 1;\n}\n\nfunction findJpegTiffOffset(bytes: Uint8Array): number {\n\tlet offset = 2;\n\twhile (offset < bytes.length - 1) {\n\t\tif (bytes[offset] !== 0xff) return -1;\n\t\tconst marker = bytes[offset + 1];\n\t\tif (marker === 0xff) {\n\t\t\toffset++;\n\t\t\tcontinue;\n\t\t}\n\n\t\tif (marker === 0xe1) {\n\t\t\tif (offset + 4 >= bytes.length) return -1;\n\t\t\tconst segmentStart = offset + 4;\n\t\t\tif (segmentStart + 6 > bytes.length) return -1;\n\t\t\tif (!hasExifHeader(bytes, segmentStart)) return -1;\n\t\t\treturn segmentStart + 6;\n\t\t}\n\n\t\tif (offset + 4 > bytes.length) return -1;\n\t\tconst length = (bytes[offset + 2] << 8) | bytes[offset + 3];\n\t\toffset += 2 + length;\n\t}\n\n\treturn -1;\n}\n\nfunction findWebpTiffOffset(bytes: Uint8Array): number {\n\tlet offset = 12;\n\twhile (offset + 8 <= bytes.length) {\n\t\tconst chunkId = String.fromCharCode(bytes[offset], bytes[offset + 1], bytes[offset + 2], bytes[offset + 3]);\n\t\tconst chunkSize =\n\t\t\tbytes[offset + 4] | (bytes[offset + 5] << 8) | (bytes[offset + 6] << 16) | (bytes[offset + 7] << 24);\n\t\tconst dataStart = offset + 8;\n\n\t\tif (chunkId === \"EXIF\") {\n\t\t\tif (dataStart + chunkSize > bytes.length) return -1;\n\t\t\t// Some WebP files have \"Exif\\0\\0\" prefix before the TIFF header\n\t\t\tconst tiffStart = chunkSize >= 6 && hasExifHeader(bytes, dataStart) ? dataStart + 6 : dataStart;\n\t\t\treturn tiffStart;\n\t\t}\n\n\t\t// RIFF chunks are padded to even size\n\t\toffset = dataStart + chunkSize + (chunkSize % 2);\n\t}\n\n\treturn -1;\n}\n\nfunction hasExifHeader(bytes: Uint8Array, offset: number): boolean {\n\treturn (\n\t\tbytes[offset] === 0x45 &&\n\t\tbytes[offset + 1] === 0x78 &&\n\t\tbytes[offset + 2] === 0x69 &&\n\t\tbytes[offset + 3] === 0x66 &&\n\t\tbytes[offset + 4] === 0x00 &&\n\t\tbytes[offset + 5] === 0x00\n\t);\n}\n\nfunction getExifOrientation(bytes: Uint8Array): number {\n\tlet tiffOffset = -1;\n\n\t// JPEG: starts with FF D8\n\tif (bytes.length >= 2 && bytes[0] === 0xff && bytes[1] === 0xd8) {\n\t\ttiffOffset = findJpegTiffOffset(bytes);\n\t}\n\t// WebP: starts with RIFF....WEBP\n\telse if (\n\t\tbytes.length >= 12 &&\n\t\tbytes[0] === 0x52 &&\n\t\tbytes[1] === 0x49 &&\n\t\tbytes[2] === 0x46 &&\n\t\tbytes[3] === 0x46 &&\n\t\tbytes[8] === 0x57 &&\n\t\tbytes[9] === 0x45 &&\n\t\tbytes[10] === 0x42 &&\n\t\tbytes[11] === 0x50\n\t) {\n\t\ttiffOffset = findWebpTiffOffset(bytes);\n\t}\n\n\tif (tiffOffset === -1) return 1;\n\treturn readOrientationFromTiff(bytes, tiffOffset);\n}\n\ntype DstIndexFn = (x: number, y: number, w: number, h: number) => number;\n\nfunction rotate90(photon: Photon, image: PhotonImageType, dstIndex: DstIndexFn): PhotonImageType {\n\tconst w = image.get_width();\n\tconst h = image.get_height();\n\tconst src = image.get_raw_pixels();\n\tconst dst = new Uint8Array(src.length);\n\n\tfor (let y = 0; y < h; y++) {\n\t\tfor (let x = 0; x < w; x++) {\n\t\t\tconst srcIdx = (y * w + x) * 4;\n\t\t\tconst dstIdx = dstIndex(x, y, w, h) * 4;\n\t\t\tdst[dstIdx] = src[srcIdx];\n\t\t\tdst[dstIdx + 1] = src[srcIdx + 1];\n\t\t\tdst[dstIdx + 2] = src[srcIdx + 2];\n\t\t\tdst[dstIdx + 3] = src[srcIdx + 3];\n\t\t}\n\t}\n\n\treturn new photon.PhotonImage(dst, h, w);\n}\n\n// Flip orientations mutate in-place. Rotations return a new image (caller must free the old one if different).\nexport function applyExifOrientation(\n\tphoton: Photon,\n\timage: PhotonImageType,\n\toriginalBytes: Uint8Array,\n): PhotonImageType {\n\tconst orientation = getExifOrientation(originalBytes);\n\tif (orientation === 1) return image;\n\n\tswitch (orientation) {\n\t\tcase 2:\n\t\t\tphoton.fliph(image);\n\t\t\treturn image;\n\t\tcase 3:\n\t\t\tphoton.fliph(image);\n\t\t\tphoton.flipv(image);\n\t\t\treturn image;\n\t\tcase 4:\n\t\t\tphoton.flipv(image);\n\t\t\treturn image;\n\t\tcase 5: {\n\t\t\tconst rotated = rotate90(photon, image, (x, y, _w, h) => x * h + (h - 1 - y));\n\t\t\tphoton.fliph(rotated);\n\t\t\treturn rotated;\n\t\t}\n\t\tcase 6:\n\t\t\treturn rotate90(photon, image, (x, y, _w, h) => x * h + (h - 1 - y));\n\t\tcase 7: {\n\t\t\tconst rotated = rotate90(photon, image, (x, y, w, h) => (w - 1 - x) * h + y);\n\t\t\tphoton.fliph(rotated);\n\t\t\treturn rotated;\n\t\t}\n\t\tcase 8:\n\t\t\treturn rotate90(photon, image, (x, y, w, h) => (w - 1 - x) * h + y);\n\t\tdefault:\n\t\t\treturn image;\n\t}\n}\n"]}
+{"version":3,"file":"exif-orientation.d.ts","sourceRoot":"","sources":["../../src/utils/exif-orientation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,KAAK,MAAM,GAAG,cAAc,4BAA4B,CAAC,CAAC;AA+I1D,wBAAgB,oBAAoB,CACnC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,eAAe,EACtB,aAAa,EAAE,UAAU,GACvB,eAAe,CAgCjB","sourcesContent":["import type { PhotonImageType } from \"./photon.ts\";\n\ntype Photon = typeof import(\"@silvia-odwyer/photon-node\");\n\nfunction readOrientationFromTiff(bytes: Uint8Array, tiffStart: number): number {\n\tif (tiffStart + 8 > bytes.length) return 1;\n\n\tconst byteOrder = (bytes[tiffStart] << 8) | bytes[tiffStart + 1];\n\tconst le = byteOrder === 0x4949;\n\n\tconst read16 = (pos: number): number => {\n\t\tif (le) return bytes[pos] | (bytes[pos + 1] << 8);\n\t\treturn (bytes[pos] << 8) | bytes[pos + 1];\n\t};\n\n\tconst read32 = (pos: number): number => {\n\t\tif (le) return bytes[pos] | (bytes[pos + 1] << 8) | (bytes[pos + 2] << 16) | (bytes[pos + 3] << 24);\n\t\treturn ((bytes[pos] << 24) | (bytes[pos + 1] << 16) | (bytes[pos + 2] << 8) | bytes[pos + 3]) >>> 0;\n\t};\n\n\tconst ifdOffset = read32(tiffStart + 4);\n\tconst ifdStart = tiffStart + ifdOffset;\n\tif (ifdStart + 2 > bytes.length) return 1;\n\n\tconst entryCount = read16(ifdStart);\n\tfor (let i = 0; i < entryCount; i++) {\n\t\tconst entryPos = ifdStart + 2 + i * 12;\n\t\tif (entryPos + 12 > bytes.length) return 1;\n\n\t\tif (read16(entryPos) === 0x0112) {\n\t\t\tconst value = read16(entryPos + 8);\n\t\t\treturn value >= 1 && value <= 8 ? value : 1;\n\t\t}\n\t}\n\n\treturn 1;\n}\n\nfunction findJpegTiffOffset(bytes: Uint8Array): number {\n\tlet offset = 2;\n\twhile (offset < bytes.length - 1) {\n\t\tif (bytes[offset] !== 0xff) return -1;\n\t\tconst marker = bytes[offset + 1];\n\t\tif (marker === 0xff) {\n\t\t\toffset++;\n\t\t\tcontinue;\n\t\t}\n\n\t\tif (marker === 0xe1) {\n\t\t\tif (offset + 4 >= bytes.length) return -1;\n\t\t\tconst segmentStart = offset + 4;\n\t\t\tif (segmentStart + 6 > bytes.length) return -1;\n\t\t\tif (hasExifHeader(bytes, segmentStart)) return segmentStart + 6;\n\t\t}\n\n\t\tif (offset + 4 > bytes.length) return -1;\n\t\tconst length = (bytes[offset + 2] << 8) | bytes[offset + 3];\n\t\toffset += 2 + length;\n\t}\n\n\treturn -1;\n}\n\nfunction findWebpTiffOffset(bytes: Uint8Array): number {\n\tlet offset = 12;\n\twhile (offset + 8 <= bytes.length) {\n\t\tconst chunkId = String.fromCharCode(bytes[offset], bytes[offset + 1], bytes[offset + 2], bytes[offset + 3]);\n\t\tconst chunkSize =\n\t\t\tbytes[offset + 4] | (bytes[offset + 5] << 8) | (bytes[offset + 6] << 16) | (bytes[offset + 7] << 24);\n\t\tconst dataStart = offset + 8;\n\n\t\tif (chunkId === \"EXIF\") {\n\t\t\tif (dataStart + chunkSize > bytes.length) return -1;\n\t\t\t// Some WebP files have \"Exif\\0\\0\" prefix before the TIFF header\n\t\t\tconst tiffStart = chunkSize >= 6 && hasExifHeader(bytes, dataStart) ? dataStart + 6 : dataStart;\n\t\t\treturn tiffStart;\n\t\t}\n\n\t\t// RIFF chunks are padded to even size\n\t\toffset = dataStart + chunkSize + (chunkSize % 2);\n\t}\n\n\treturn -1;\n}\n\nfunction hasExifHeader(bytes: Uint8Array, offset: number): boolean {\n\treturn (\n\t\tbytes[offset] === 0x45 &&\n\t\tbytes[offset + 1] === 0x78 &&\n\t\tbytes[offset + 2] === 0x69 &&\n\t\tbytes[offset + 3] === 0x66 &&\n\t\tbytes[offset + 4] === 0x00 &&\n\t\tbytes[offset + 5] === 0x00\n\t);\n}\n\nfunction getExifOrientation(bytes: Uint8Array): number {\n\tlet tiffOffset = -1;\n\n\t// JPEG: starts with FF D8\n\tif (bytes.length >= 2 && bytes[0] === 0xff && bytes[1] === 0xd8) {\n\t\ttiffOffset = findJpegTiffOffset(bytes);\n\t}\n\t// WebP: starts with RIFF....WEBP\n\telse if (\n\t\tbytes.length >= 12 &&\n\t\tbytes[0] === 0x52 &&\n\t\tbytes[1] === 0x49 &&\n\t\tbytes[2] === 0x46 &&\n\t\tbytes[3] === 0x46 &&\n\t\tbytes[8] === 0x57 &&\n\t\tbytes[9] === 0x45 &&\n\t\tbytes[10] === 0x42 &&\n\t\tbytes[11] === 0x50\n\t) {\n\t\ttiffOffset = findWebpTiffOffset(bytes);\n\t}\n\n\tif (tiffOffset === -1) return 1;\n\treturn readOrientationFromTiff(bytes, tiffOffset);\n}\n\ntype DstIndexFn = (x: number, y: number, w: number, h: number) => number;\n\nfunction rotate90(photon: Photon, image: PhotonImageType, dstIndex: DstIndexFn): PhotonImageType {\n\tconst w = image.get_width();\n\tconst h = image.get_height();\n\tconst src = image.get_raw_pixels();\n\tconst dst = new Uint8Array(src.length);\n\n\tfor (let y = 0; y < h; y++) {\n\t\tfor (let x = 0; x < w; x++) {\n\t\t\tconst srcIdx = (y * w + x) * 4;\n\t\t\tconst dstIdx = dstIndex(x, y, w, h) * 4;\n\t\t\tdst[dstIdx] = src[srcIdx];\n\t\t\tdst[dstIdx + 1] = src[srcIdx + 1];\n\t\t\tdst[dstIdx + 2] = src[srcIdx + 2];\n\t\t\tdst[dstIdx + 3] = src[srcIdx + 3];\n\t\t}\n\t}\n\n\treturn new photon.PhotonImage(dst, h, w);\n}\n\n// Flip orientations mutate in-place. Rotations return a new image (caller must free the old one if different).\nexport function applyExifOrientation(\n\tphoton: Photon,\n\timage: PhotonImageType,\n\toriginalBytes: Uint8Array,\n): PhotonImageType {\n\tconst orientation = getExifOrientation(originalBytes);\n\tif (orientation === 1) return image;\n\n\tswitch (orientation) {\n\t\tcase 2:\n\t\t\tphoton.fliph(image);\n\t\t\treturn image;\n\t\tcase 3:\n\t\t\tphoton.fliph(image);\n\t\t\tphoton.flipv(image);\n\t\t\treturn image;\n\t\tcase 4:\n\t\t\tphoton.flipv(image);\n\t\t\treturn image;\n\t\tcase 5: {\n\t\t\tconst rotated = rotate90(photon, image, (x, y, _w, h) => x * h + (h - 1 - y));\n\t\t\tphoton.fliph(rotated);\n\t\t\treturn rotated;\n\t\t}\n\t\tcase 6:\n\t\t\treturn rotate90(photon, image, (x, y, _w, h) => x * h + (h - 1 - y));\n\t\tcase 7: {\n\t\t\tconst rotated = rotate90(photon, image, (x, y, w, h) => (w - 1 - x) * h + y);\n\t\t\tphoton.fliph(rotated);\n\t\t\treturn rotated;\n\t\t}\n\t\tcase 8:\n\t\t\treturn rotate90(photon, image, (x, y, w, h) => (w - 1 - x) * h + y);\n\t\tdefault:\n\t\t\treturn image;\n\t}\n}\n"]}

package/dist/utils/exif-orientation.js

@@ -45,9 +45,8 @@ function findJpegTiffOffset(bytes) {
             const segmentStart = offset + 4;
             if (segmentStart + 6 > bytes.length)
                 return -1;
-            if (!hasExifHeader(bytes, segmentStart))
-                return -1;
-            return segmentStart + 6;
+            if (hasExifHeader(bytes, segmentStart))
+                return segmentStart + 6;
         }
         if (offset + 4 > bytes.length)
             return -1;