@cueai/omni-reader-mcp 1.5.4 → 1.6.0

package/dist/operation-journal.js

@@ -4,7 +4,7 @@ import { homedir } from "node:os";
 import path from "node:path";
 import { OmniBridgeError } from "./errors.js";
 import { GROUNDING_SCHEMA_VERSION, RESULT_BUNDLE_PROTOCOL_VERSION, normalizeRepresentation, } from "./protocol.js";
-// D2-D item 4-6: v3 records persist keyed identities instead of unkeyed
+// D2-D item 4-6: v3/v4 records persist keyed identities instead of unkeyed
 // request/source hashes. requestIdentityHmac and sourceLocatorHmac are
 // lowercase full hex of HMAC-SHA-256 over the journal secret with the exact
 // domain prefixes below; they are never returned in tool output and never
@@ -43,6 +43,10 @@ const PERSISTED_V3_KEYS = [
     "resultExpiresAt",
     "errorCode",
 ];
+const PERSISTED_V4_KEYS = [
+    ...PERSISTED_V3_KEYS,
+    "result_delivery_effective",
+];
 const JOURNAL_STATES = new Set([
     "CREATED",
     "GRANT_PENDING",
@@ -81,6 +85,7 @@ const DELIVERY_STATES = new Set([
     "pending",
     "deleted_after_ack",
 ]);
+const RESULT_DELIVERIES = new Set(["auto", "artifact"]);
 const RECORD_FILE_PATTERN = /^[0-9a-f]{64}(?:\.issued)?\.json$/u;
 const LOCK_STALE_MS = 30_000;
 const HEX_64_PATTERN = /^[0-9a-f]{64}$/u;
@@ -255,6 +260,26 @@ function parseVersionThreeRecord(value) {
     }
     return value;
 }
+function parseVersionFourRecord(value) {
+    const keys = Object.keys(value);
+    if (keys.length !== PERSISTED_V4_KEYS.length ||
+        PERSISTED_V4_KEYS.some((key) => !(key in value)) ||
+        value.version !== 4 ||
+        typeof value.result_delivery_effective !== "string" ||
+        !RESULT_DELIVERIES.has(value.result_delivery_effective)) {
+        throw new Error("version-4 record fields are invalid");
+    }
+    const { result_delivery_effective, ...versionThreeFields } = value;
+    const validated = parseVersionThreeRecord({
+        ...versionThreeFields,
+        version: 3,
+    });
+    return {
+        ...validated,
+        version: 4,
+        result_delivery_effective: result_delivery_effective,
+    };
+}
 function parsePersistedRecord(value) {
     if (value === null || typeof value !== "object" || Array.isArray(value)) {
         throw new Error("record is not an object");
@@ -266,12 +291,14 @@ function parsePersistedRecord(value) {
         return parseVersionTwoRecord(record);
     if (record.version === 3)
         return parseVersionThreeRecord(record);
+    if (record.version === 4)
+        return parseVersionFourRecord(record);
     throw new Error("record version is invalid");
 }
 function migrateInMemory(stored) {
-    if (stored.version === 3) {
+    if (stored.version === 3 || stored.version === 4) {
         return {
-            version: 3,
+            version: 4,
             clientRequestId: stored.clientRequestId,
             requestIdentityHmac: stored.requestIdentityHmac,
             sourceLocatorHmac: stored.sourceLocatorHmac,
@@ -282,6 +309,9 @@ function migrateInMemory(stored) {
             detail: stored.detail,
             groundingSchemaVersion: stored.groundingSchemaVersion,
             bundleProtocolVersion: stored.bundleProtocolVersion,
+            resultDeliveryEffective: stored.version === 4
+                ? stored.result_delivery_effective
+                : "auto",
             operationId: stored.operationId,
             operationToken: stored.operationToken,
             state: stored.state,
@@ -308,7 +338,7 @@ function migrateInMemory(stored) {
         // are recomputed only when safe canonical source facts reconstruct the
         // stored unkeyed requestHash (see #reconstructLegacy).
         return {
-            version: 3,
+            version: 4,
             clientRequestId: stored.clientRequestId,
             requestIdentityHmac: null,
             sourceLocatorHmac: null,
@@ -319,6 +349,7 @@ function migrateInMemory(stored) {
             detail: "text",
             groundingSchemaVersion: "none",
             bundleProtocolVersion: "none",
+            resultDeliveryEffective: "auto",
             operationId: stored.operationId,
             operationToken: stored.operationToken,
             state: stored.state,
@@ -341,7 +372,7 @@ function migrateInMemory(stored) {
         };
     }
     return {
-        version: 3,
+        version: 4,
         clientRequestId: stored.clientRequestId,
         requestIdentityHmac: null,
         sourceLocatorHmac: null,
@@ -352,6 +383,7 @@ function migrateInMemory(stored) {
         detail: "text",
         groundingSchemaVersion: "none",
         bundleProtocolVersion: "none",
+        resultDeliveryEffective: "auto",
         operationId: stored.operationId,
         operationToken: stored.operationToken,
         state: stored.state,
@@ -428,6 +460,10 @@ function assertStableTransition(current, updated) {
             throw bridgeError("JOURNAL_FACT_REGRESSION", "A confirmed local operation fact cannot be reverted.", false);
         }
     }
+    if (current.resultDeliveryEffective === "artifact" &&
+        updated.resultDeliveryEffective !== "artifact") {
+        throw bridgeError("JOURNAL_RESULT_DELIVERY_REGRESSION", "Artifact result delivery cannot be weakened to automatic delivery.", false);
+    }
 }
 function hmacEqual(left, right) {
     if (left.length !== right.length)
@@ -451,19 +487,22 @@ export class OperationJournal {
     async sourceLocatorHmac(sourceLocator) {
         return this.#hmac(SOURCE_LOCATOR_DOMAIN, sourceLocator);
     }
-    // v3 intent creation. canonicalIdentityJson is the exact canonical
+    // v4 intent creation. canonicalIdentityJson is the exact canonical
     // serialization of {source_kind, source_facts} (which includes the
     // normalized representation tuple); the journal derives the keyed identity
     // from it and persists only the HMAC, never the payload or any unkeyed hash.
-    async beginIntent(clientRequestId, canonicalIdentityJson, sourceKind = "local", sourceLocator = null, representation = TEXT_REPRESENTATION) {
+    async beginIntent(clientRequestId, canonicalIdentityJson, sourceKind = "local", sourceLocator = null, representation = TEXT_REPRESENTATION, resultDelivery = "auto") {
         validateClientRequestId(clientRequestId);
+        if (!RESULT_DELIVERIES.has(resultDelivery)) {
+            throw bridgeError("INVALID_RESULT_DELIVERY", "The result delivery mode is invalid.", false);
+        }
         const existing = await this.#readRecord(clientRequestId);
         if (existing !== null) {
             return this.#requireMatchingRequest(clientRequestId, canonicalIdentityJson, sourceLocator, existing);
         }
         const createdAt = this.#now().toISOString();
         const created = {
-            version: 3,
+            version: 4,
             clientRequestId,
             requestIdentityHmac: await this.#hmac(REQUEST_IDENTITY_DOMAIN, canonicalIdentityJson),
             sourceLocatorHmac: sourceLocator === null
@@ -476,6 +515,7 @@ export class OperationJournal {
             detail: representation.detail,
             groundingSchemaVersion: representation.groundingSchemaVersion,
             bundleProtocolVersion: representation.bundleProtocolVersion,
+            resultDeliveryEffective: resultDelivery,
             operationId: null,
             operationToken: null,
             state: "CREATED",
@@ -507,7 +547,7 @@ export class OperationJournal {
     }
     // Migrate a legacy v1/v2 record using the caller's safe canonical source
     // facts. When the facts reconstruct the stored unkeyed requestHash, the
-    // record migrates to v3 (durably) with domain-separated HMACs and keeps its
+    // record migrates to v4 (durably) with domain-separated HMACs and keeps its
     // state; otherwise it becomes a terminal source-free recovery failure and
     // never copies the unkeyed hashes. Returns null when no record exists.
     async migrateLegacyRecord(clientRequestId, canonicalIdentityJson, sourceLocator = null) {
@@ -515,8 +555,9 @@ export class OperationJournal {
         const stored = await this.#readRecord(clientRequestId);
         if (stored === null)
             return null;
-        if (stored.version === 3)
+        if (stored.version === 3 || stored.version === 4) {
             return this.#recordToPublic(clientRequestId, stored);
+        }
         const expected = `sha256:${createHash("sha256").update(canonicalIdentityJson, "utf8").digest("hex")}`;
         if (stored.requestHash === expected) {
             const migrated = await this.#reconstructLegacy(stored, canonicalIdentityJson, sourceLocator);
@@ -559,6 +600,31 @@ export class OperationJournal {
             return updated;
         });
     }
+    async strengthenResultDelivery(clientRequestId, requested) {
+        validateClientRequestId(clientRequestId);
+        if (!RESULT_DELIVERIES.has(requested)) {
+            throw bridgeError("INVALID_RESULT_DELIVERY", "The result delivery mode is invalid.", false);
+        }
+        return this.#withRecordLock(clientRequestId, async () => {
+            const stored = await this.#readRecord(clientRequestId);
+            if (stored === null) {
+                throw bridgeError("JOURNAL_RECORD_NOT_FOUND", "The local operation journal record is missing.", true);
+            }
+            const current = await this.#recordToPublic(clientRequestId, stored);
+            if (requested === "auto" || current.resultDeliveryEffective === "artifact") {
+                return current;
+            }
+            const updated = {
+                ...current,
+                resultDeliveryEffective: "artifact",
+                updatedAt: this.#now().toISOString(),
+            };
+            assertStableTransition(current, updated);
+            await this.#replaceRecord(await this.#persistedRecord(updated), this.#recordPath(clientRequestId));
+            await unlink(this.#legacyIssuedRecordPath(clientRequestId)).catch(() => undefined);
+            return updated;
+        });
+    }
     async loadByRequestId(clientRequestId) {
         validateClientRequestId(clientRequestId);
         const persisted = await this.#readRecord(clientRequestId);
@@ -592,7 +658,7 @@ export class OperationJournal {
         // the journal receives, so the keyed handle is derived over that value.
         const createdAt = this.#now().toISOString();
         const created = {
-            version: 3,
+            version: 4,
             clientRequestId,
             requestIdentityHmac: await this.#hmac(REQUEST_IDENTITY_DOMAIN, requestHash),
             sourceLocatorHmac: null,
@@ -603,6 +669,7 @@ export class OperationJournal {
             detail: "text",
             groundingSchemaVersion: "none",
             bundleProtocolVersion: "none",
+            resultDeliveryEffective: "auto",
             operationId: null,
             operationToken: null,
             state: "CREATED",
@@ -698,7 +765,7 @@ export class OperationJournal {
     }
     async #persistedRecord(record) {
         return {
-            version: 3,
+            version: 4,
             clientRequestId: record.clientRequestId,
             // A legacy record persisted before reconstruction (for example a
             // source-free recovery failure) gets the deterministic keyed handle of
@@ -711,6 +778,7 @@ export class OperationJournal {
             detail: record.detail,
             groundingSchemaVersion: record.groundingSchemaVersion,
             bundleProtocolVersion: record.bundleProtocolVersion,
+            result_delivery_effective: record.resultDeliveryEffective,
             operationId: record.operationId,
             operationToken: record.operationToken === null
                 ? null
@@ -736,7 +804,7 @@ export class OperationJournal {
     }
     async #persistedFromInMemory(record) {
         return {
-            version: 3,
+            version: 4,
             clientRequestId: record.clientRequestId,
             requestIdentityHmac: record.requestIdentityHmac === null
                 ? await this.#hmac(REQUEST_IDENTITY_DOMAIN, "")
@@ -746,6 +814,7 @@ export class OperationJournal {
             detail: record.detail,
             groundingSchemaVersion: record.groundingSchemaVersion,
             bundleProtocolVersion: record.bundleProtocolVersion,
+            result_delivery_effective: record.resultDeliveryEffective,
             operationId: record.operationId,
             operationToken: record.operationToken,
             state: record.state,
@@ -784,6 +853,7 @@ export class OperationJournal {
             detail: migrated.detail,
             groundingSchemaVersion: migrated.groundingSchemaVersion,
             bundleProtocolVersion: migrated.bundleProtocolVersion,
+            resultDeliveryEffective: migrated.resultDeliveryEffective,
             operationId: migrated.operationId,
             operationToken,
             uploadUrl: migrated.uploadUrl,
@@ -819,7 +889,7 @@ export class OperationJournal {
         return migrated;
     }
     async #requireMatchingRequest(clientRequestId, canonicalIdentityJson, sourceLocator, persisted) {
-        if (persisted.version === 3) {
+        if (persisted.version === 3 || persisted.version === 4) {
             const expected = await this.#hmacExisting(REQUEST_IDENTITY_DOMAIN, canonicalIdentityJson);
             if (!hmacEqual(persisted.requestIdentityHmac, expected)) {
                 throw bridgeError("IDEMPOTENCY_COLLISION", "This local operation request identifier is already bound to different metadata.", false);
@@ -833,7 +903,7 @@ export class OperationJournal {
         throw bridgeError("IDEMPOTENCY_COLLISION", "This local operation request identifier is already bound to different metadata.", false);
     }
     async #requireMatchingCubeRequest(clientRequestId, requestHash, persisted) {
-        if (persisted.version === 3) {
+        if (persisted.version === 3 || persisted.version === 4) {
             const expected = await this.#hmacExisting(REQUEST_IDENTITY_DOMAIN, requestHash);
             if (!hmacEqual(persisted.requestIdentityHmac, expected)) {
                 throw bridgeError("IDEMPOTENCY_COLLISION", "This local operation request identifier is already bound to different metadata.", false);

package/dist/operation-manager.d.ts

@@ -3,7 +3,7 @@ import type { CubeGrantClient } from "./cube-client.js";
 import type { IiisClient, ResultRetentionSink } from "./iiis-client.js";
 import type { JournalPatch, JournalRecord, JournalState, OperationJournal } from "./operation-journal.js";
 import { type OpenAllowedFileOptions, type OpenedAllowedFile } from "./path-security.js";
-import { type RepresentationIntent } from "./protocol.js";
+import { type RepresentationIntent, type ResultDelivery } from "./protocol.js";
 import type { RemoteOmniClient } from "./remote-client.js";
 import { type ParseResult } from "./result-contract.js";
 export interface SubmitOperationInput {
@@ -12,6 +12,7 @@ export interface SubmitOperationInput {
     readonly clientRequestId: string;
     readonly signal?: AbortSignal;
     readonly context?: unknown;
+    readonly resultDelivery?: ResultDelivery;
     readonly representation?: RepresentationIntent;
 }
 export interface OperationDriverUpdate {
@@ -38,8 +39,9 @@ export interface OperationManagerDriver {
     result?(record: JournalRecord, signal: AbortSignal): Promise<ParseResult | void>;
 }
 export interface OperationManagerOptions {
-    readonly journal: Pick<OperationJournal, "beginIntent" | "migrateLegacyRecord" | "requestIdentityHmac" | "sourceLocatorHmac" | "transition" | "loadByRequestId" | "loadByOperationId" | "loadLatestByRequestIdentityHmac" | "loadLatestBySourceLocatorHmac" | "listRecoverable">;
+    readonly journal: Pick<OperationJournal, "beginIntent" | "migrateLegacyRecord" | "requestIdentityHmac" | "sourceLocatorHmac" | "transition" | "loadByRequestId" | "loadByOperationId" | "loadLatestByRequestIdentityHmac" | "loadLatestBySourceLocatorHmac" | "listRecoverable" | "strengthenResultDelivery">;
     readonly driver: OperationManagerDriver;
+    readonly presentResult?: (record: JournalRecord, canonicalResult: ParseResult) => Promise<ParseResult>;
     readonly now?: () => number;
     readonly sleep?: (milliseconds: number) => Promise<void>;
 }
@@ -61,6 +63,8 @@ export interface LocalRetention extends ResultRetentionSink {
 }
 export interface LocalArtifactStore {
     createRetention(): LocalRetention;
+    preflightWrite?(): Promise<void>;
+    mintReadCursor?(resultId: string, byteOffset: number): Promise<string>;
     read(resultId: string, cursor?: string, maxBytes?: number): Promise<ArtifactReadResult>;
     readBundleDescriptor?(resultId: string): Promise<BundleLocalResult | null>;
 }