@cueai/omni-reader-mcp 1.6.0 → 1.7.0

package/dist/operation-journal.js

@@ -47,6 +47,11 @@ const PERSISTED_V4_KEYS = [
     ...PERSISTED_V3_KEYS,
     "result_delivery_effective",
 ];
+const PERSISTED_V5_KEYS = [
+    ...PERSISTED_V4_KEYS,
+    "direct_profile",
+    "billing",
+];
 const JOURNAL_STATES = new Set([
     "CREATED",
     "GRANT_PENDING",
@@ -280,6 +285,53 @@ function parseVersionFourRecord(value) {
         result_delivery_effective: result_delivery_effective,
     };
 }
+function isBillingDirectProfile(value) {
+    return value === "omni.direct_text_billing.v1"
+        || value === "omni.direct_grounding_billing.v1";
+}
+function isPersistedBilling(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const billing = value;
+    return Object.keys(billing).length === 2
+        && "credits_charged" in billing
+        && "credits_remaining" in billing
+        && typeof billing.credits_charged === "number"
+        && Number.isFinite(billing.credits_charged)
+        && billing.credits_charged >= 0
+        && typeof billing.credits_remaining === "number"
+        && Number.isFinite(billing.credits_remaining)
+        && billing.credits_remaining >= 0;
+}
+function parseVersionFiveRecord(value) {
+    const keys = Object.keys(value);
+    if (keys.length !== PERSISTED_V5_KEYS.length
+        || PERSISTED_V5_KEYS.some((key) => !(key in value))
+        || value.version !== 5
+        || !(value.direct_profile === null
+            || isBillingDirectProfile(value.direct_profile))
+        || !(value.billing === null || isPersistedBilling(value.billing))) {
+        throw new Error("version-5 record fields are invalid");
+    }
+    const { direct_profile, billing, ...versionFourFields } = value;
+    const validated = parseVersionFourRecord({
+        ...versionFourFields,
+        version: 4,
+    });
+    if ((validated.sourceKind === "url" && direct_profile !== null)
+        || (validated.sourceKind === "local"
+            && billing !== null
+            && direct_profile === null)) {
+        throw new Error("version-5 settlement facts are invalid");
+    }
+    return {
+        ...validated,
+        version: 5,
+        direct_profile: direct_profile,
+        billing: billing,
+    };
+}
 function parsePersistedRecord(value) {
     if (value === null || typeof value !== "object" || Array.isArray(value)) {
         throw new Error("record is not an object");
@@ -293,12 +345,14 @@ function parsePersistedRecord(value) {
         return parseVersionThreeRecord(record);
     if (record.version === 4)
         return parseVersionFourRecord(record);
+    if (record.version === 5)
+        return parseVersionFiveRecord(record);
     throw new Error("record version is invalid");
 }
 function migrateInMemory(stored) {
-    if (stored.version === 3 || stored.version === 4) {
+    if (stored.version === 3 || stored.version === 4 || stored.version === 5) {
         return {
-            version: 4,
+            version: 5,
             clientRequestId: stored.clientRequestId,
             requestIdentityHmac: stored.requestIdentityHmac,
             sourceLocatorHmac: stored.sourceLocatorHmac,
@@ -309,9 +363,16 @@ function migrateInMemory(stored) {
             detail: stored.detail,
             groundingSchemaVersion: stored.groundingSchemaVersion,
             bundleProtocolVersion: stored.bundleProtocolVersion,
-            resultDeliveryEffective: stored.version === 4
+            resultDeliveryEffective: stored.version === 4 || stored.version === 5
                 ? stored.result_delivery_effective
                 : "auto",
+            directProfile: stored.version === 5 ? stored.direct_profile : null,
+            billing: stored.version === 5 && stored.billing !== null
+                ? {
+                    creditsCharged: stored.billing.credits_charged,
+                    creditsRemaining: stored.billing.credits_remaining,
+                }
+                : null,
             operationId: stored.operationId,
             operationToken: stored.operationToken,
             state: stored.state,
@@ -338,7 +399,7 @@ function migrateInMemory(stored) {
         // are recomputed only when safe canonical source facts reconstruct the
         // stored unkeyed requestHash (see #reconstructLegacy).
         return {
-            version: 4,
+            version: 5,
             clientRequestId: stored.clientRequestId,
             requestIdentityHmac: null,
             sourceLocatorHmac: null,
@@ -350,6 +411,8 @@ function migrateInMemory(stored) {
             groundingSchemaVersion: "none",
             bundleProtocolVersion: "none",
             resultDeliveryEffective: "auto",
+            directProfile: null,
+            billing: null,
             operationId: stored.operationId,
             operationToken: stored.operationToken,
             state: stored.state,
@@ -372,7 +435,7 @@ function migrateInMemory(stored) {
         };
     }
     return {
-        version: 4,
+        version: 5,
         clientRequestId: stored.clientRequestId,
         requestIdentityHmac: null,
         sourceLocatorHmac: null,
@@ -384,6 +447,8 @@ function migrateInMemory(stored) {
         groundingSchemaVersion: "none",
         bundleProtocolVersion: "none",
         resultDeliveryEffective: "auto",
+        directProfile: null,
+        billing: null,
         operationId: stored.operationId,
         operationToken: stored.operationToken,
         state: stored.state,
@@ -439,6 +504,10 @@ function assertStableTransition(current, updated) {
             throw bridgeError("JOURNAL_IDENTITY_CONFLICT", "A stable local operation identifier cannot be replaced.", false);
         }
     }
+    if (current.directProfile !== null
+        && current.directProfile !== updated.directProfile) {
+        throw bridgeError("JOURNAL_DIRECT_PROFILE_MISMATCH", "The direct billing profile cannot be replaced.", false);
+    }
     if (current.operationToken !== null &&
         current.operationToken !== updated.operationToken &&
         !(updated.operationToken === null && TERMINAL_STATES.has(updated.state))) {
@@ -470,6 +539,18 @@ function hmacEqual(left, right) {
         return false;
     return timingSafeEqual(Buffer.from(left, "hex"), Buffer.from(right, "hex"));
 }
+function assertJournalBilling(billing) {
+    if (!Number.isFinite(billing.creditsCharged)
+        || billing.creditsCharged < 0
+        || !Number.isFinite(billing.creditsRemaining)
+        || billing.creditsRemaining < 0) {
+        throw bridgeError("JOURNAL_BILLING_INVALID", "The authoritative billing facts are invalid.", false);
+    }
+}
+function billingEqual(left, right) {
+    return left.creditsCharged === right.creditsCharged
+        && left.creditsRemaining === right.creditsRemaining;
+}
 export class OperationJournal {
     #rootDirectory;
     #now;
@@ -487,7 +568,7 @@ export class OperationJournal {
     async sourceLocatorHmac(sourceLocator) {
         return this.#hmac(SOURCE_LOCATOR_DOMAIN, sourceLocator);
     }
-    // v4 intent creation. canonicalIdentityJson is the exact canonical
+    // v5 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.
@@ -502,7 +583,7 @@ export class OperationJournal {
         }
         const createdAt = this.#now().toISOString();
         const created = {
-            version: 4,
+            version: 5,
             clientRequestId,
             requestIdentityHmac: await this.#hmac(REQUEST_IDENTITY_DOMAIN, canonicalIdentityJson),
             sourceLocatorHmac: sourceLocator === null
@@ -516,6 +597,8 @@ export class OperationJournal {
             groundingSchemaVersion: representation.groundingSchemaVersion,
             bundleProtocolVersion: representation.bundleProtocolVersion,
             resultDeliveryEffective: resultDelivery,
+            directProfile: null,
+            billing: null,
             operationId: null,
             operationToken: null,
             state: "CREATED",
@@ -555,7 +638,7 @@ export class OperationJournal {
         const stored = await this.#readRecord(clientRequestId);
         if (stored === null)
             return null;
-        if (stored.version === 3 || stored.version === 4) {
+        if (stored.version === 3 || stored.version === 4 || stored.version === 5) {
             return this.#recordToPublic(clientRequestId, stored);
         }
         const expected = `sha256:${createHash("sha256").update(canonicalIdentityJson, "utf8").digest("hex")}`;
@@ -625,6 +708,80 @@ export class OperationJournal {
             return updated;
         });
     }
+    async bindDirectProfile(clientRequestId, directProfile) {
+        validateClientRequestId(clientRequestId);
+        if (!isBillingDirectProfile(directProfile)) {
+            throw bridgeError("JOURNAL_DIRECT_PROFILE_MISMATCH", "The direct billing profile does not match the operation source.", 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 (current.sourceKind !== "local") {
+                throw bridgeError("JOURNAL_DIRECT_PROFILE_MISMATCH", "The direct billing profile does not match the operation source.", false);
+            }
+            if (current.directProfile !== null) {
+                if (current.directProfile !== directProfile) {
+                    throw bridgeError("JOURNAL_DIRECT_PROFILE_MISMATCH", "The direct billing profile cannot be replaced.", false);
+                }
+                return current;
+            }
+            const updated = {
+                ...current,
+                directProfile,
+                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 bindSettlementFacts(clientRequestId, facts) {
+        validateClientRequestId(clientRequestId);
+        assertJournalBilling(facts.billing);
+        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);
+            const profileMatchesSource = current.sourceKind === "url"
+                ? facts.directProfile === null
+                : isBillingDirectProfile(facts.directProfile);
+            if (!profileMatchesSource) {
+                throw bridgeError("JOURNAL_DIRECT_PROFILE_MISMATCH", "The direct billing profile does not match the operation source.", false);
+            }
+            if (current.billing !== null) {
+                if (current.directProfile !== facts.directProfile) {
+                    throw bridgeError("JOURNAL_DIRECT_PROFILE_MISMATCH", "The direct billing profile cannot be replaced.", false);
+                }
+                if (!billingEqual(current.billing, facts.billing)) {
+                    throw bridgeError("JOURNAL_BILLING_MISMATCH", "The authoritative billing facts cannot be replaced.", false);
+                }
+                return current;
+            }
+            if (current.directProfile !== null
+                && current.directProfile !== facts.directProfile) {
+                throw bridgeError("JOURNAL_DIRECT_PROFILE_MISMATCH", "The direct billing profile cannot be replaced.", false);
+            }
+            const updated = {
+                ...current,
+                directProfile: facts.directProfile,
+                billing: {
+                    creditsCharged: facts.billing.creditsCharged,
+                    creditsRemaining: facts.billing.creditsRemaining,
+                },
+                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);
@@ -658,7 +815,7 @@ export class OperationJournal {
         // the journal receives, so the keyed handle is derived over that value.
         const createdAt = this.#now().toISOString();
         const created = {
-            version: 4,
+            version: 5,
             clientRequestId,
             requestIdentityHmac: await this.#hmac(REQUEST_IDENTITY_DOMAIN, requestHash),
             sourceLocatorHmac: null,
@@ -670,6 +827,8 @@ export class OperationJournal {
             groundingSchemaVersion: "none",
             bundleProtocolVersion: "none",
             resultDeliveryEffective: "auto",
+            directProfile: null,
+            billing: null,
             operationId: null,
             operationToken: null,
             state: "CREATED",
@@ -765,7 +924,7 @@ export class OperationJournal {
     }
     async #persistedRecord(record) {
         return {
-            version: 4,
+            version: 5,
             clientRequestId: record.clientRequestId,
             // A legacy record persisted before reconstruction (for example a
             // source-free recovery failure) gets the deterministic keyed handle of
@@ -779,6 +938,13 @@ export class OperationJournal {
             groundingSchemaVersion: record.groundingSchemaVersion,
             bundleProtocolVersion: record.bundleProtocolVersion,
             result_delivery_effective: record.resultDeliveryEffective,
+            direct_profile: record.directProfile,
+            billing: record.billing === null
+                ? null
+                : {
+                    credits_charged: record.billing.creditsCharged,
+                    credits_remaining: record.billing.creditsRemaining,
+                },
             operationId: record.operationId,
             operationToken: record.operationToken === null
                 ? null
@@ -804,7 +970,7 @@ export class OperationJournal {
     }
     async #persistedFromInMemory(record) {
         return {
-            version: 4,
+            version: 5,
             clientRequestId: record.clientRequestId,
             requestIdentityHmac: record.requestIdentityHmac === null
                 ? await this.#hmac(REQUEST_IDENTITY_DOMAIN, "")
@@ -815,6 +981,13 @@ export class OperationJournal {
             groundingSchemaVersion: record.groundingSchemaVersion,
             bundleProtocolVersion: record.bundleProtocolVersion,
             result_delivery_effective: record.resultDeliveryEffective,
+            direct_profile: record.directProfile,
+            billing: record.billing === null
+                ? null
+                : {
+                    credits_charged: record.billing.creditsCharged,
+                    credits_remaining: record.billing.creditsRemaining,
+                },
             operationId: record.operationId,
             operationToken: record.operationToken,
             state: record.state,
@@ -854,6 +1027,8 @@ export class OperationJournal {
             groundingSchemaVersion: migrated.groundingSchemaVersion,
             bundleProtocolVersion: migrated.bundleProtocolVersion,
             resultDeliveryEffective: migrated.resultDeliveryEffective,
+            directProfile: migrated.directProfile,
+            billing: migrated.billing,
             operationId: migrated.operationId,
             operationToken,
             uploadUrl: migrated.uploadUrl,
@@ -889,7 +1064,7 @@ export class OperationJournal {
         return migrated;
     }
     async #requireMatchingRequest(clientRequestId, canonicalIdentityJson, sourceLocator, persisted) {
-        if (persisted.version === 3 || persisted.version === 4) {
+        if (persisted.version === 3 || persisted.version === 4 || persisted.version === 5) {
             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);
@@ -903,7 +1078,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 || persisted.version === 4) {
+        if (persisted.version === 3 || persisted.version === 4 || persisted.version === 5) {
             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

@@ -39,7 +39,7 @@ 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" | "strengthenResultDelivery">;
+    readonly journal: Pick<OperationJournal, "beginIntent" | "bindSettlementFacts" | "migrateLegacyRecord" | "requestIdentityHmac" | "sourceLocatorHmac" | "transition" | "loadByRequestId" | "loadByOperationId" | "loadLatestByRequestIdentityHmac" | "loadLatestBySourceLocatorHmac" | "listRecoverable" | "strengthenResultDelivery">;
     readonly driver: OperationManagerDriver;
     readonly presentResult?: (record: JournalRecord, canonicalResult: ParseResult) => Promise<ParseResult>;
     readonly now?: () => number;