@qitqode/qitqore 0.1.0 → 0.3.0

package/dist/recovery-capabilities.js

@@ -0,0 +1,113 @@
+const MODES = new Set(["buffered", "streaming", "async_job", "utility"]);
+const RETRIES = new Set(["pre_execution_only", "safe_observation", "unsupported"]);
+const REPLAYS = new Set(["retained_result", "unsupported"]);
+const RESUMES = new Set(["supported", "unsupported"]);
+const RECONCILIATIONS = new Set([
+    "recovery_status",
+    "billing_status_only",
+    "job_status",
+    "unsupported",
+]);
+const MANIFEST_FIELDS = new Set(["success", "contractVersion", "capabilities"]);
+const CAPABILITY_FIELDS = new Set([
+    "contractVersion",
+    "routeID",
+    "mode",
+    "retry",
+    "replay",
+    "resume",
+    "reconciliation",
+    "requiresIdempotencyKey",
+    "retentionMs",
+    "maxBackendAdditionalWork",
+]);
+const MAX_CAPABILITIES = 512;
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function boundedString(value, field, maxLength) {
+    if (typeof value !== "string" || value.length === 0 || value.length > maxLength) {
+        throw new TypeError(`Qortex recovery capabilities have an invalid ${field}`);
+    }
+    return value;
+}
+/** Parse one route capability. Unrecognized fields are rejected rather than forwarded. */
+export function parseRecoveryCapability(value) {
+    if (!isRecord(value))
+        throw new TypeError("Qortex recovery capability must be an object");
+    for (const key of Object.keys(value)) {
+        if (!CAPABILITY_FIELDS.has(key)) {
+            throw new TypeError("Qortex recovery capability contains an unsupported field");
+        }
+    }
+    if (value.contractVersion !== 1) {
+        throw new TypeError("Qortex recovery capability uses an unsupported contract version");
+    }
+    if (typeof value.mode !== "string" || !MODES.has(value.mode)) {
+        throw new TypeError("Qortex recovery capability has an invalid mode");
+    }
+    if (typeof value.retry !== "string" || !RETRIES.has(value.retry)) {
+        throw new TypeError("Qortex recovery capability has an invalid retry policy");
+    }
+    if (typeof value.replay !== "string" || !REPLAYS.has(value.replay)) {
+        throw new TypeError("Qortex recovery capability has an invalid replay policy");
+    }
+    if (typeof value.resume !== "string" || !RESUMES.has(value.resume)) {
+        throw new TypeError("Qortex recovery capability has an invalid resume policy");
+    }
+    if (typeof value.reconciliation !== "string" || !RECONCILIATIONS.has(value.reconciliation)) {
+        throw new TypeError("Qortex recovery capability has an invalid reconciliation policy");
+    }
+    if (typeof value.requiresIdempotencyKey !== "boolean") {
+        throw new TypeError("Qortex recovery capability has an invalid idempotency requirement");
+    }
+    if (!Number.isSafeInteger(value.maxBackendAdditionalWork) ||
+        value.maxBackendAdditionalWork < 0) {
+        throw new TypeError("Qortex recovery capability has an invalid additional-work limit");
+    }
+    if (value.retentionMs !== undefined &&
+        (!Number.isSafeInteger(value.retentionMs) || value.retentionMs <= 0)) {
+        throw new TypeError("Qortex recovery capability has an invalid retention period");
+    }
+    return {
+        contractVersion: 1,
+        routeID: boundedString(value.routeID, "routeID", 256),
+        mode: value.mode,
+        retry: value.retry,
+        replay: value.replay,
+        resume: value.resume,
+        reconciliation: value.reconciliation,
+        requiresIdempotencyKey: value.requiresIdempotencyKey,
+        ...(value.retentionMs === undefined ? {} : { retentionMs: value.retentionMs }),
+        maxBackendAdditionalWork: value.maxBackendAdditionalWork,
+    };
+}
+/** Parse only bounded route facts; never pass through unrecognized server metadata. */
+export function parseRecoveryCapabilities(value) {
+    if (!isRecord(value))
+        throw new TypeError("Qortex recovery capabilities must be an object");
+    let candidate = value;
+    if (value.success === true && Object.hasOwn(value, "data"))
+        candidate = value.data;
+    if (!isRecord(candidate))
+        throw new TypeError("Qortex recovery capabilities data must be an object");
+    for (const key of Object.keys(candidate)) {
+        if (!MANIFEST_FIELDS.has(key)) {
+            throw new TypeError("Qortex recovery capabilities contain an unsupported field");
+        }
+    }
+    if (candidate.success !== undefined && candidate.success !== true) {
+        throw new TypeError("Qortex recovery capabilities have an invalid success marker");
+    }
+    if (candidate.contractVersion !== 1) {
+        throw new TypeError("Qortex recovery capabilities use an unsupported contract version");
+    }
+    if (!Array.isArray(candidate.capabilities) || candidate.capabilities.length > MAX_CAPABILITIES) {
+        throw new TypeError("Qortex recovery capabilities have an invalid capability list");
+    }
+    return {
+        contractVersion: 1,
+        capabilities: candidate.capabilities.map(parseRecoveryCapability),
+    };
+}
+//# sourceMappingURL=recovery-capabilities.js.map

package/dist/recovery-capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery-capabilities.js","sourceRoot":"","sources":["../src/recovery-capabilities.ts"],"names":[],"mappings":"AA4BA,MAAM,KAAK,GAAG,IAAI,GAAG,CAAqB,CAAC,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,SAAS,CAAC,CAAC,CAAC;AAC7F,MAAM,OAAO,GAAG,IAAI,GAAG,CAAsB,CAAC,oBAAoB,EAAE,kBAAkB,EAAE,aAAa,CAAC,CAAC,CAAC;AACxG,MAAM,OAAO,GAAG,IAAI,GAAG,CAAuB,CAAC,iBAAiB,EAAE,aAAa,CAAC,CAAC,CAAC;AAClF,MAAM,OAAO,GAAG,IAAI,GAAG,CAAuB,CAAC,WAAW,EAAE,aAAa,CAAC,CAAC,CAAC;AAC5E,MAAM,eAAe,GAAG,IAAI,GAAG,CAA+B;IAC5D,iBAAiB;IACjB,qBAAqB;IACrB,YAAY;IACZ,aAAa;CACd,CAAC,CAAC;AACH,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC,CAAC,SAAS,EAAE,iBAAiB,EAAE,cAAc,CAAC,CAAC,CAAC;AAChF,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAC;IAChC,iBAAiB;IACjB,SAAS;IACT,MAAM;IACN,OAAO;IACP,QAAQ;IACR,QAAQ;IACR,gBAAgB;IAChB,wBAAwB;IACxB,aAAa;IACb,0BAA0B;CAC3B,CAAC,CAAC;AACH,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAE7B,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,SAAS,aAAa,CAAC,KAAc,EAAE,KAAa,EAAE,SAAiB;IACrE,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,SAAS,EAAE,CAAC;QAChF,MAAM,IAAI,SAAS,CAAC,gDAAgD,KAAK,EAAE,CAAC,CAAC;IAC/E,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,uBAAuB,CAAC,KAAc;IACpD,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,SAAS,CAAC,8CAA8C,CAAC,CAAC;IAC1F,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACrC,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAChC,MAAM,IAAI,SAAS,CAAC,0DAA0D,CAAC,CAAC;QAClF,CAAC;IACH,CAAC;IACD,IAAI,KAAK,CAAC,eAAe,KAAK,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,SAAS,CAAC,iEAAiE,CAAC,CAAC;IACzF,CAAC;IACD,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,IAA0B,CAAC,EAAE,CAAC;QACnF,MAAM,IAAI,SAAS,CAAC,gDAAgD,CAAC,CAAC;IACxE,CAAC;IACD,IAAI,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,KAA4B,CAAC,EAAE,CAAC;QACxF,MAAM,IAAI,SAAS,CAAC,wDAAwD,CAAC,CAAC;IAChF,CAAC;IACD,IAAI,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,MAA8B,CAAC,EAAE,CAAC;QAC3F,MAAM,IAAI,SAAS,CAAC,yDAAyD,CAAC,CAAC;IACjF,CAAC;IACD,IAAI,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,MAA8B,CAAC,EAAE,CAAC;QAC3F,MAAM,IAAI,SAAS,CAAC,yDAAyD,CAAC,CAAC;IACjF,CAAC;IACD,IAAI,OAAO,KAAK,CAAC,cAAc,KAAK,QAAQ,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,KAAK,CAAC,cAA8C,CAAC,EAAE,CAAC;QAC3H,MAAM,IAAI,SAAS,CAAC,iEAAiE,CAAC,CAAC;IACzF,CAAC;IACD,IAAI,OAAO,KAAK,CAAC,sBAAsB,KAAK,SAAS,EAAE,CAAC;QACtD,MAAM,IAAI,SAAS,CAAC,mEAAmE,CAAC,CAAC;IAC3F,CAAC;IACD,IACE,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,wBAAwB,CAAC;QACpD,KAAK,CAAC,wBAAmC,GAAG,CAAC,EAC9C,CAAC;QACD,MAAM,IAAI,SAAS,CAAC,iEAAiE,CAAC,CAAC;IACzF,CAAC;IACD,IACE,KAAK,CAAC,WAAW,KAAK,SAAS;QAC/B,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,WAAW,CAAC,IAAK,KAAK,CAAC,WAAsB,IAAI,CAAC,CAAC,EAChF,CAAC;QACD,MAAM,IAAI,SAAS,CAAC,4DAA4D,CAAC,CAAC;IACpF,CAAC;IAED,OAAO;QACL,eAAe,EAAE,CAAC;QAClB,OAAO,EAAE,aAAa,CAAC,KAAK,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,CAAC;QACrD,IAAI,EAAE,KAAK,CAAC,IAA0B;QACtC,KAAK,EAAE,KAAK,CAAC,KAA4B;QACzC,MAAM,EAAE,KAAK,CAAC,MAA8B;QAC5C,MAAM,EAAE,KAAK,CAAC,MAA8B;QAC5C,cAAc,EAAE,KAAK,CAAC,cAA8C;QACpE,sBAAsB,EAAE,KAAK,CAAC,sBAAsB;QACpD,GAAG,CAAC,KAAK,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,WAAqB,EAAE,CAAC;QACxF,wBAAwB,EAAE,KAAK,CAAC,wBAAkC;KACnE,CAAC;AACJ,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,yBAAyB,CAAC,KAAc;IACtD,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,SAAS,CAAC,gDAAgD,CAAC,CAAC;IAC5F,IAAI,SAAS,GAAY,KAAK,CAAC;IAC/B,IAAI,KAAK,CAAC,OAAO,KAAK,IAAI,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC;QAAE,SAAS,GAAG,KAAK,CAAC,IAAI,CAAC;IACnF,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC;QAAE,MAAM,IAAI,SAAS,CAAC,qDAAqD,CAAC,CAAC;IAErG,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;QACzC,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAC9B,MAAM,IAAI,SAAS,CAAC,2DAA2D,CAAC,CAAC;QACnF,CAAC;IACH,CAAC;IACD,IAAI,SAAS,CAAC,OAAO,KAAK,SAAS,IAAI,SAAS,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;QAClE,MAAM,IAAI,SAAS,CAAC,6DAA6D,CAAC,CAAC;IACrF,CAAC;IACD,IAAI,SAAS,CAAC,eAAe,KAAK,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,SAAS,CAAC,kEAAkE,CAAC,CAAC;IAC1F,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,YAAY,CAAC,IAAI,SAAS,CAAC,YAAY,CAAC,MAAM,GAAG,gBAAgB,EAAE,CAAC;QAC/F,MAAM,IAAI,SAAS,CAAC,8DAA8D,CAAC,CAAC;IACtF,CAAC;IAED,OAAO;QACL,eAAe,EAAE,CAAC;QAClB,YAAY,EAAE,SAAS,CAAC,YAAY,CAAC,GAAG,CAAC,uBAAuB,CAAC;KAClE,CAAC;AACJ,CAAC"}

package/dist/recovery-directive.d.ts

@@ -0,0 +1,20 @@
+import type { QortexExecutionState } from "./recovery-status.js";
+export type QortexRecoveryFailureLayer = "client" | "qortex_transport" | "qortex_auth" | "qortex_harness" | "omniquery_inference" | "tool" | "verification" | "capability";
+export type QortexRecoveryFailureCategory = "backend_unavailable" | "authentication_rejected" | "backend_harness_failed" | "inference_failed" | "tool_failed" | "tool_running" | "verification_failed" | "unsupported_capability" | "rate_limited" | "operation_budget_exhausted" | "operation_deadline_expired" | "effect_outcome_unknown" | "cancelled" | "invalid_request" | "internal_failure";
+export type QortexRecommendedRecoveryAction = "retry_same_work" | "replay_retained_result" | "continue_partial" | "change_approach" | "reconcile" | "wait" | "reauthenticate" | "stop";
+export interface QortexRecoveryDirective {
+    contractVersion: 1;
+    policyVersion: string;
+    category: QortexRecoveryFailureCategory;
+    layer: QortexRecoveryFailureLayer;
+    stage: string;
+    executionState: QortexExecutionState | "accepted" | "cancelled";
+    recommendedAction: QortexRecommendedRecoveryAction;
+    retryable: boolean;
+    reasonCode: string;
+    requestID?: string;
+    retryAfterMs?: number;
+}
+/** Parse the public directive without retaining unrecognized provider or server fields. */
+export declare function parseRecoveryDirective(value: unknown): QortexRecoveryDirective;
+//# sourceMappingURL=recovery-directive.d.ts.map

package/dist/recovery-directive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery-directive.d.ts","sourceRoot":"","sources":["../src/recovery-directive.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAEjE,MAAM,MAAM,0BAA0B,GAClC,QAAQ,GACR,kBAAkB,GAClB,aAAa,GACb,gBAAgB,GAChB,qBAAqB,GACrB,MAAM,GACN,cAAc,GACd,YAAY,CAAC;AAEjB,MAAM,MAAM,6BAA6B,GACrC,qBAAqB,GACrB,yBAAyB,GACzB,wBAAwB,GACxB,kBAAkB,GAClB,aAAa,GACb,cAAc,GACd,qBAAqB,GACrB,wBAAwB,GACxB,cAAc,GACd,4BAA4B,GAC5B,4BAA4B,GAC5B,wBAAwB,GACxB,WAAW,GACX,iBAAiB,GACjB,kBAAkB,CAAC;AAEvB,MAAM,MAAM,+BAA+B,GACvC,iBAAiB,GACjB,wBAAwB,GACxB,kBAAkB,GAClB,iBAAiB,GACjB,WAAW,GACX,MAAM,GACN,gBAAgB,GAChB,MAAM,CAAC;AAEX,MAAM,WAAW,uBAAuB;IACtC,eAAe,EAAE,CAAC,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,6BAA6B,CAAC;IACxC,KAAK,EAAE,0BAA0B,CAAC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,oBAAoB,GAAG,UAAU,GAAG,WAAW,CAAC;IAChE,iBAAiB,EAAE,+BAA+B,CAAC;IACnD,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AA8DD,2FAA2F;AAC3F,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,uBAAuB,CAyD9E"}

package/dist/recovery-directive.js

@@ -0,0 +1,116 @@
+const CATEGORIES = new Set([
+    "backend_unavailable",
+    "authentication_rejected",
+    "backend_harness_failed",
+    "inference_failed",
+    "tool_failed",
+    "tool_running",
+    "verification_failed",
+    "unsupported_capability",
+    "rate_limited",
+    "operation_budget_exhausted",
+    "operation_deadline_expired",
+    "effect_outcome_unknown",
+    "cancelled",
+    "invalid_request",
+    "internal_failure",
+]);
+const LAYERS = new Set([
+    "client",
+    "qortex_transport",
+    "qortex_auth",
+    "qortex_harness",
+    "omniquery_inference",
+    "tool",
+    "verification",
+    "capability",
+]);
+const ACTIONS = new Set([
+    "retry_same_work",
+    "replay_retained_result",
+    "continue_partial",
+    "change_approach",
+    "reconcile",
+    "wait",
+    "reauthenticate",
+    "stop",
+]);
+const EXECUTION_STATES = new Set(["not_started", "accepted", "running", "succeeded", "failed", "unknown", "cancelled"]);
+const FIELDS = new Set([
+    "contractVersion",
+    "policyVersion",
+    "category",
+    "layer",
+    "stage",
+    "executionState",
+    "recommendedAction",
+    "retryable",
+    "reasonCode",
+    "requestID",
+    "retryAfterMs",
+]);
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function matches(value, pattern) {
+    return typeof value === "string" && pattern.test(value);
+}
+/** Parse the public directive without retaining unrecognized provider or server fields. */
+export function parseRecoveryDirective(value) {
+    if (!isRecord(value))
+        throw new TypeError("Qortex recovery directive must be an object");
+    for (const key of Object.keys(value)) {
+        if (!FIELDS.has(key))
+            throw new TypeError("Qortex recovery directive contains an unsupported field");
+    }
+    if (value.contractVersion !== 1) {
+        throw new TypeError("Qortex recovery directive uses an unsupported contract version");
+    }
+    if (!matches(value.policyVersion, /^[A-Za-z0-9_.:-]{1,256}$/)) {
+        throw new TypeError("Qortex recovery directive has an invalid policyVersion");
+    }
+    if (typeof value.category !== "string" || !CATEGORIES.has(value.category)) {
+        throw new TypeError("Qortex recovery directive has an invalid category");
+    }
+    if (typeof value.layer !== "string" || !LAYERS.has(value.layer)) {
+        throw new TypeError("Qortex recovery directive has an invalid layer");
+    }
+    if (!matches(value.stage, /^[A-Za-z0-9_.:-]{1,128}$/)) {
+        throw new TypeError("Qortex recovery directive has an invalid stage");
+    }
+    if (typeof value.executionState !== "string" || !EXECUTION_STATES.has(value.executionState)) {
+        throw new TypeError("Qortex recovery directive has an invalid executionState");
+    }
+    if (typeof value.recommendedAction !== "string" || !ACTIONS.has(value.recommendedAction)) {
+        throw new TypeError("Qortex recovery directive has an invalid recommendedAction");
+    }
+    if (typeof value.retryable !== "boolean") {
+        throw new TypeError("Qortex recovery directive has an invalid retryable flag");
+    }
+    if (!matches(value.reasonCode, /^[a-z0-9_:-]{1,256}$/)) {
+        throw new TypeError("Qortex recovery directive has an invalid reasonCode");
+    }
+    if (value.requestID !== undefined && !matches(value.requestID, /^[A-Za-z0-9_.:/-]{1,256}$/)) {
+        throw new TypeError("Qortex recovery directive has an invalid requestID");
+    }
+    if (value.retryAfterMs !== undefined &&
+        (!Number.isSafeInteger(value.retryAfterMs) ||
+            value.retryAfterMs < 0 ||
+            value.retryAfterMs > 86_400_000)) {
+        throw new TypeError("Qortex recovery directive has an invalid retryAfterMs");
+    }
+    return {
+        contractVersion: 1,
+        policyVersion: value.policyVersion,
+        category: value.category,
+        layer: value.layer,
+        stage: value.stage,
+        executionState: value.executionState,
+        recommendedAction: value.recommendedAction,
+        retryable: value.retryable,
+        reasonCode: value.reasonCode,
+        ...(value.requestID === undefined ? {} : { requestID: value.requestID }),
+        ...(value.retryAfterMs === undefined ? {} : { retryAfterMs: value.retryAfterMs }),
+    };
+}
+//# sourceMappingURL=recovery-directive.js.map

package/dist/recovery-directive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery-directive.js","sourceRoot":"","sources":["../src/recovery-directive.ts"],"names":[],"mappings":"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"}

package/dist/recovery-lease.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Qortex's recovery lease wire contract: the control envelope a host sends to
+ * bound additional work, and the usage projection Qortex returns for it.
+ * QitQore parses and encodes these values only. Hosts allocate token budgets,
+ * persist leases, authorize replay, and settle outcomes.
+ */
+/** Request header that carries a base64url-encoded control envelope to Qortex. */
+export declare const QORTEX_RECOVERY_CONTROL_HEADER = "x-qitqode-recovery-control";
+/** Maximum additional-work tokens in one lease, matching Qortex's public limit. */
+export declare const MAX_RECOVERY_ADDITIONAL_WORK = 12;
+/** Longest root-operation window Qortex will honor for one dispatch. */
+export declare const MAX_RECOVERY_ROOT_REMAINING_MS: number;
+export type QortexRecoveryAdditionalWorkAction = "retry_same_work" | "changed_approach" | "continuation" | "compaction" | "worker" | "reconciliation";
+export type QortexRecoveryAction = QortexRecoveryAdditionalWorkAction | "initial_dispatch";
+export interface QortexRecoveryConsumedWork {
+    tokenID: string;
+    action: QortexRecoveryAdditionalWorkAction;
+    stage: string;
+}
+/** Qortex's report of which reserved tokens a request consumed and which it left unused. */
+export interface QortexRecoveryLeaseUsage {
+    contractVersion: 1;
+    leaseID: string;
+    publicOperationID: string;
+    operationGeneration: number;
+    workID: string;
+    attemptID: string;
+    requestID: string;
+    routeID: string;
+    consumed: QortexRecoveryConsumedWork[];
+    unusedTokenIDs: string[];
+}
+export interface QortexRecoveryControlOperation {
+    contractVersion: 1;
+    publicOperationID: string;
+    operationGeneration: number;
+    workID: string;
+    attemptID: string;
+    parentWorkID?: string;
+    action: QortexRecoveryAction;
+    rootDeadlineAt: number;
+    rootRemainingMsAtDispatch: number;
+    claimID?: string;
+    leaseID: string;
+    policyVersion?: string;
+}
+/** The decoded value of the recovery-control header. */
+export interface QortexRecoveryControlEnvelope {
+    contractVersion: 1;
+    operation: QortexRecoveryControlOperation;
+    lease: {
+        leaseID: string;
+        tokenIDs: string[];
+    };
+}
+/**
+ * Parse Qortex's lease usage projection. Every identity and token is bounded,
+ * token IDs must be unique across consumed and unused work, and unknown fields
+ * are rejected rather than forwarded.
+ */
+export declare function parseRecoveryLeaseUsage(value: unknown): QortexRecoveryLeaseUsage;
+/**
+ * Validate a control envelope before it is sent. The operation's lease ID must
+ * name the same lease as the token list, and the list stays within Qortex's
+ * additional-work limit.
+ */
+export declare function parseRecoveryControlEnvelope(value: unknown): QortexRecoveryControlEnvelope;
+/**
+ * Encode a validated control envelope as the base64url header value Qortex
+ * expects. Parser bounds keep every valid envelope under the header size limit.
+ */
+export declare function encodeRecoveryControlEnvelope(value: unknown): string;
+/**
+ * Decode a recovery-control header value. The encoding must be canonical base64url
+ * so that a value cannot be accepted by one parser and rewritten by another.
+ */
+export declare function decodeRecoveryControlHeader(value: string): QortexRecoveryControlEnvelope;
+/** Return a copy of request headers that carries a validated recovery-control envelope. */
+export declare function withRecoveryControlHeader(headers: Record<string, string>, control: unknown): Record<string, string>;
+//# sourceMappingURL=recovery-lease.d.ts.map

package/dist/recovery-lease.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery-lease.d.ts","sourceRoot":"","sources":["../src/recovery-lease.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,kFAAkF;AAClF,eAAO,MAAM,8BAA8B,+BAA+B,CAAC;AAE3E,mFAAmF;AACnF,eAAO,MAAM,4BAA4B,KAAK,CAAC;AAE/C,wEAAwE;AACxE,eAAO,MAAM,8BAA8B,QAAkB,CAAC;AAO9D,MAAM,MAAM,kCAAkC,GAC1C,iBAAiB,GACjB,kBAAkB,GAClB,cAAc,GACd,YAAY,GACZ,QAAQ,GACR,gBAAgB,CAAC;AAErB,MAAM,MAAM,oBAAoB,GAAG,kCAAkC,GAAG,kBAAkB,CAAC;AAE3F,MAAM,WAAW,0BAA0B;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,kCAAkC,CAAC;IAC3C,KAAK,EAAE,MAAM,CAAC;CACf;AAED,4FAA4F;AAC5F,MAAM,WAAW,wBAAwB;IACvC,eAAe,EAAE,CAAC,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,0BAA0B,EAAE,CAAC;IACvC,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,8BAA8B;IAC7C,eAAe,EAAE,CAAC,CAAC;IACnB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,oBAAoB,CAAC;IAC7B,cAAc,EAAE,MAAM,CAAC;IACvB,yBAAyB,EAAE,MAAM,CAAC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,wDAAwD;AACxD,MAAM,WAAW,6BAA6B;IAC5C,eAAe,EAAE,CAAC,CAAC;IACnB,SAAS,EAAE,8BAA8B,CAAC;IAC1C,KAAK,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;CAChD;AA0FD;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,wBAAwB,CAuChF;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,6BAA6B,CAgE1F;AAgBD;;;GAGG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEpE;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,MAAM,GAAG,6BAA6B,CAoBxF;AAED,2FAA2F;AAC3F,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,OAAO,EAAE,OAAO,GACf,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAExB"}

package/dist/recovery-lease.js

@@ -0,0 +1,257 @@
+/**
+ * Qortex's recovery lease wire contract: the control envelope a host sends to
+ * bound additional work, and the usage projection Qortex returns for it.
+ * QitQore parses and encodes these values only. Hosts allocate token budgets,
+ * persist leases, authorize replay, and settle outcomes.
+ */
+/** Request header that carries a base64url-encoded control envelope to Qortex. */
+export const QORTEX_RECOVERY_CONTROL_HEADER = "x-qitqode-recovery-control";
+/** Maximum additional-work tokens in one lease, matching Qortex's public limit. */
+export const MAX_RECOVERY_ADDITIONAL_WORK = 12;
+/** Longest root-operation window Qortex will honor for one dispatch. */
+export const MAX_RECOVERY_ROOT_REMAINING_MS = 15 * 60 * 1_000;
+const MAX_RECOVERY_CONTROL_HEADER_LENGTH = 16_384;
+const MAX_IDENTIFIER_LENGTH = 256;
+const MAX_STAGE_LENGTH = 128;
+const HEADER_VALUE = /^[A-Za-z0-9_-]+$/;
+const RECOVERY_ACTIONS = new Set([
+    "initial_dispatch",
+    "retry_same_work",
+    "changed_approach",
+    "continuation",
+    "compaction",
+    "worker",
+    "reconciliation",
+]);
+const CONSUMED_WORK_ACTIONS = new Set([
+    "retry_same_work",
+    "changed_approach",
+    "continuation",
+    "compaction",
+    "worker",
+    "reconciliation",
+]);
+const USAGE_FIELDS = new Set([
+    "contractVersion",
+    "leaseID",
+    "publicOperationID",
+    "operationGeneration",
+    "workID",
+    "attemptID",
+    "requestID",
+    "routeID",
+    "consumed",
+    "unusedTokenIDs",
+]);
+const CONSUMED_FIELDS = new Set(["tokenID", "action", "stage"]);
+const ENVELOPE_FIELDS = new Set(["contractVersion", "operation", "lease"]);
+const OPERATION_FIELDS = new Set([
+    "contractVersion",
+    "publicOperationID",
+    "operationGeneration",
+    "workID",
+    "attemptID",
+    "parentWorkID",
+    "action",
+    "rootDeadlineAt",
+    "rootRemainingMsAtDispatch",
+    "claimID",
+    "leaseID",
+    "policyVersion",
+]);
+const LEASE_FIELDS = new Set(["leaseID", "tokenIDs"]);
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function assertKnownFields(value, allowed, label) {
+    for (const key of Object.keys(value)) {
+        if (!allowed.has(key))
+            throw new TypeError(`Qortex ${label} contains an unsupported field`);
+    }
+}
+function boundedString(value, label, maxLength) {
+    if (typeof value !== "string" || value.length === 0 || value.length > maxLength) {
+        throw new TypeError(`Qortex ${label} has an invalid identifier`);
+    }
+    return value;
+}
+function nonnegativeInteger(value, label) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new TypeError(`Qortex ${label} must be a non-negative integer`);
+    }
+    return value;
+}
+function uniqueTokenIDs(tokenIDs, label) {
+    if (tokenIDs.length > MAX_RECOVERY_ADDITIONAL_WORK) {
+        throw new TypeError(`Qortex ${label} exceeds the additional-work limit`);
+    }
+    if (new Set(tokenIDs).size !== tokenIDs.length) {
+        throw new TypeError(`Qortex ${label} token IDs must be unique`);
+    }
+    return tokenIDs;
+}
+function tokenIDList(value, label) {
+    if (!Array.isArray(value) || value.length > MAX_RECOVERY_ADDITIONAL_WORK) {
+        throw new TypeError(`Qortex ${label} has an invalid token list`);
+    }
+    return value.map((item) => boundedString(item, label, MAX_IDENTIFIER_LENGTH));
+}
+/**
+ * Parse Qortex's lease usage projection. Every identity and token is bounded,
+ * token IDs must be unique across consumed and unused work, and unknown fields
+ * are rejected rather than forwarded.
+ */
+export function parseRecoveryLeaseUsage(value) {
+    if (!isRecord(value))
+        throw new TypeError("Qortex recovery lease usage must be an object");
+    assertKnownFields(value, USAGE_FIELDS, "recovery lease usage");
+    if (value.contractVersion !== 1) {
+        throw new TypeError("Qortex recovery lease usage uses an unsupported contract version");
+    }
+    if (!Array.isArray(value.consumed) || value.consumed.length > MAX_RECOVERY_ADDITIONAL_WORK) {
+        throw new TypeError("Qortex recovery lease usage has an invalid consumed list");
+    }
+    const consumed = value.consumed.map((item) => {
+        if (!isRecord(item))
+            throw new TypeError("Qortex recovery lease usage has an invalid consumed entry");
+        assertKnownFields(item, CONSUMED_FIELDS, "recovery lease usage consumed entry");
+        if (typeof item.action !== "string" || !CONSUMED_WORK_ACTIONS.has(item.action)) {
+            throw new TypeError("Qortex recovery lease usage has an invalid consumed action");
+        }
+        return {
+            tokenID: boundedString(item.tokenID, "recovery lease usage tokenID", MAX_IDENTIFIER_LENGTH),
+            action: item.action,
+            stage: boundedString(item.stage, "recovery lease usage stage", MAX_STAGE_LENGTH),
+        };
+    });
+    const unusedTokenIDs = tokenIDList(value.unusedTokenIDs, "recovery lease usage unusedTokenIDs");
+    uniqueTokenIDs([...consumed.map((item) => item.tokenID), ...unusedTokenIDs], "recovery lease usage");
+    return {
+        contractVersion: 1,
+        leaseID: boundedString(value.leaseID, "recovery lease usage leaseID", MAX_IDENTIFIER_LENGTH),
+        publicOperationID: boundedString(value.publicOperationID, "recovery lease usage publicOperationID", MAX_IDENTIFIER_LENGTH),
+        operationGeneration: nonnegativeInteger(value.operationGeneration, "recovery lease usage operationGeneration"),
+        workID: boundedString(value.workID, "recovery lease usage workID", MAX_IDENTIFIER_LENGTH),
+        attemptID: boundedString(value.attemptID, "recovery lease usage attemptID", MAX_IDENTIFIER_LENGTH),
+        requestID: boundedString(value.requestID, "recovery lease usage requestID", MAX_IDENTIFIER_LENGTH),
+        routeID: boundedString(value.routeID, "recovery lease usage routeID", MAX_IDENTIFIER_LENGTH),
+        consumed,
+        unusedTokenIDs,
+    };
+}
+/**
+ * Validate a control envelope before it is sent. The operation's lease ID must
+ * name the same lease as the token list, and the list stays within Qortex's
+ * additional-work limit.
+ */
+export function parseRecoveryControlEnvelope(value) {
+    if (!isRecord(value))
+        throw new TypeError("Qortex recovery control must be an object");
+    assertKnownFields(value, ENVELOPE_FIELDS, "recovery control");
+    if (value.contractVersion !== 1) {
+        throw new TypeError("Qortex recovery control uses an unsupported contract version");
+    }
+    if (!isRecord(value.operation))
+        throw new TypeError("Qortex recovery control operation must be an object");
+    const operation = value.operation;
+    assertKnownFields(operation, OPERATION_FIELDS, "recovery control operation");
+    if (operation.contractVersion !== 1) {
+        throw new TypeError("Qortex recovery control operation uses an unsupported contract version");
+    }
+    if (typeof operation.action !== "string" || !RECOVERY_ACTIONS.has(operation.action)) {
+        throw new TypeError("Qortex recovery control operation has an invalid action");
+    }
+    if (typeof operation.rootDeadlineAt !== "number" ||
+        !Number.isFinite(operation.rootDeadlineAt) ||
+        operation.rootDeadlineAt <= 0) {
+        throw new TypeError("Qortex recovery control operation has an invalid rootDeadlineAt");
+    }
+    if (typeof operation.rootRemainingMsAtDispatch !== "number" ||
+        !Number.isFinite(operation.rootRemainingMsAtDispatch) ||
+        operation.rootRemainingMsAtDispatch < 0 ||
+        operation.rootRemainingMsAtDispatch > MAX_RECOVERY_ROOT_REMAINING_MS) {
+        throw new TypeError("Qortex recovery control operation has an invalid rootRemainingMsAtDispatch");
+    }
+    if (!isRecord(value.lease))
+        throw new TypeError("Qortex recovery control lease must be an object");
+    assertKnownFields(value.lease, LEASE_FIELDS, "recovery control lease");
+    const leaseID = boundedString(value.lease.leaseID, "recovery control leaseID", MAX_IDENTIFIER_LENGTH);
+    const operationLeaseID = boundedString(operation.leaseID, "recovery control operation leaseID", MAX_IDENTIFIER_LENGTH);
+    if (operationLeaseID !== leaseID) {
+        throw new TypeError("Qortex recovery control lease ID must match the operation");
+    }
+    const tokenIDs = uniqueTokenIDs(tokenIDList(value.lease.tokenIDs, "recovery control tokenIDs"), "recovery control");
+    return {
+        contractVersion: 1,
+        operation: {
+            contractVersion: 1,
+            publicOperationID: boundedString(operation.publicOperationID, "recovery control publicOperationID", MAX_IDENTIFIER_LENGTH),
+            operationGeneration: nonnegativeInteger(operation.operationGeneration, "recovery control operationGeneration"),
+            workID: boundedString(operation.workID, "recovery control workID", MAX_IDENTIFIER_LENGTH),
+            attemptID: boundedString(operation.attemptID, "recovery control attemptID", MAX_IDENTIFIER_LENGTH),
+            ...(operation.parentWorkID === undefined
+                ? {}
+                : { parentWorkID: boundedString(operation.parentWorkID, "recovery control parentWorkID", MAX_IDENTIFIER_LENGTH) }),
+            action: operation.action,
+            rootDeadlineAt: operation.rootDeadlineAt,
+            rootRemainingMsAtDispatch: operation.rootRemainingMsAtDispatch,
+            ...(operation.claimID === undefined
+                ? {}
+                : { claimID: boundedString(operation.claimID, "recovery control claimID", MAX_IDENTIFIER_LENGTH) }),
+            leaseID,
+            ...(operation.policyVersion === undefined
+                ? {}
+                : { policyVersion: boundedString(operation.policyVersion, "recovery control policyVersion", MAX_IDENTIFIER_LENGTH) }),
+        },
+        lease: { leaseID, tokenIDs },
+    };
+}
+function base64UrlEncode(text) {
+    const bytes = new TextEncoder().encode(text);
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function base64UrlDecode(value) {
+    const padded = value.replace(/-/g, "+").replace(/_/g, "/").padEnd(Math.ceil(value.length / 4) * 4, "=");
+    const binary = atob(padded);
+    const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
+    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+}
+/**
+ * Encode a validated control envelope as the base64url header value Qortex
+ * expects. Parser bounds keep every valid envelope under the header size limit.
+ */
+export function encodeRecoveryControlEnvelope(value) {
+    return base64UrlEncode(JSON.stringify(parseRecoveryControlEnvelope(value)));
+}
+/**
+ * Decode a recovery-control header value. The encoding must be canonical base64url
+ * so that a value cannot be accepted by one parser and rewritten by another.
+ */
+export function decodeRecoveryControlHeader(value) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.length > MAX_RECOVERY_CONTROL_HEADER_LENGTH ||
+        !HEADER_VALUE.test(value)) {
+        throw new TypeError("Qortex recovery control header is invalid");
+    }
+    let decoded;
+    try {
+        decoded = JSON.parse(base64UrlDecode(value));
+    }
+    catch {
+        throw new TypeError("Qortex recovery control header is invalid");
+    }
+    const envelope = parseRecoveryControlEnvelope(decoded);
+    if (base64UrlEncode(JSON.stringify(envelope)) !== value) {
+        throw new TypeError("Qortex recovery control header is not canonically encoded");
+    }
+    return envelope;
+}
+/** Return a copy of request headers that carries a validated recovery-control envelope. */
+export function withRecoveryControlHeader(headers, control) {
+    return { ...headers, [QORTEX_RECOVERY_CONTROL_HEADER]: encodeRecoveryControlEnvelope(control) };
+}
+//# sourceMappingURL=recovery-lease.js.map

package/dist/recovery-lease.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery-lease.js","sourceRoot":"","sources":["../src/recovery-lease.ts"],"names":[],"mappings":"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"}