@qitqode/qitqore 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 QitQode contributors, Spannings LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -8,6 +8,28 @@ It is not a CLI, agent runtime, authentication store, policy engine, scheduler,
 or billing/settlement system. Importing the package creates no directories,
 reads credentials, changes process settings, or makes network requests.
 
+## Repository and workspace
+
+The dedicated repository is
+[`forgewisetech/qitqore`](https://github.com/forgewisetech/qitqore).
+It is a private, independently buildable mirror of the canonical
+`products/qitqore` directory in the Forgewise monorepo. Make source changes in
+that canonical directory, then use the workspace's per-product export to update
+the repository; do not maintain a second implementation in either consumer.
+The repository does not contain QitQode, Wud, their credentials, or their state.
+
+The library is tracked as its own product in Umbrella. Its own `products/qitqore`
+folder, dedicated repository, and Umbrella tracking are the intended setup;
+a separate Replit preview artifact is not required.
+
+Repository metadata here applies to future package releases. The already
+published `@qitqode/qitqore@0.1.0` remains immutable and has not been republished.
+Future releases are licensed under the [MIT License](./LICENSE), the same license
+as QitQode. The copyright holder is QitQode contributors, Spannings LLC.
+
+The local source candidate is now `0.2.0`; it is not published. The immutable
+`0.1.0` artifact and all consumer pins remain unchanged.
+
 ## Development
 
 - Requires Node.js 24 or newer.
@@ -21,6 +43,57 @@ reads credentials, changes process settings, or makes network requests.
 The package has no runtime dependencies. Its sole public entry point is the
 compiled ESM export at `.`.
 
+## Released consumer adoption
+
+The public package is **`@qitqode/qitqore@0.1.0`**. Install it with
+`npm install --save-exact @qitqode/qitqore@0.1.0`. The independently managed
+QitQode CLI, its backend SDK, and Wud pin that exact release in their own
+manifests and native Bun/npm lockfiles; they do not import sibling source.
+
+QitQode retains AI SDK/native-tool adaptation, credential recovery, advisory
+budgets and session policy. Session retries carry an explicit operation ID;
+prompt equality does not identify an operation. Qortex session retries require
+an explicit non-acceptance verdict and no observed output or started tool.
+Unknown or interrupted execution stops without replay, preserving partial text,
+reasoning and interrupted tool records. Wud retains credentials,
+durable operations, authorization, reservations, leases and settlement.
+Both use the shared request lifecycle, SSE decoder and bounded recovery.
+Compatibility fallback requires explicit pre-execution validation evidence.
+An unterminated stream preserves available text/accounting evidence but is not
+reported as successful completion.
+
+Hosts may pass `deadlineAt` to `runWithRecovery` to apply one absolute deadline
+to every attempt, retry delay and backoff; a request timeout alone is not an
+operation-wide limit. `getRecoveryStatus` and `getRecoveryCapabilities`
+validate separate Qortex execution and route-capability contracts; neither is
+billing evidence. `parseRecoveryDirective` accepts only bounded decision fields.
+QitQore does not provide exactly-once effects: callers still need stable
+operation IDs, receipts and reconciliation for ambiguous external operations.
+Recovery status reports only a retained Qortex route result. It never proves that
+a caller applied a local change, an external effect happened exactly once, or
+acceptance verification succeeded.
+
+From the monorepo, run
+`node products/qitqore/scripts/verify-consumers.mjs --production-install --bun /path/to/bun`
+under Node 24, with Bun 1.3.11. This checks exact manifest/lock integrity,
+compiled public imports in all consumers, and a clean Wud production dependency
+installation without either application's source. Temporary fixtures are removed.
+Package-local tests remain deterministic and independent of this network install.
+Wud's injected-transport and accounting regressions run without Mongo initialization:
+`cd products/wud && npx vitest run --config vitest.qitqore.config.ts`.
+
+Publication, packed-candidate verification, released-consumer adoption and
+deployment are separate claims. The package was published and its public tarball
+verified; adopting it locally does **not** push either consumer or deploy it.
+Future core changes require a new immutable package version, package tests and
+packing checks, separate publication approval, then exact consumer pins and
+regenerated native lockfiles.
+
+Release 0.1.0's registry manifest does not declare a license. QitQode's generated
+notice inventory identifies that exact release as first-party code without
+inventing a third-party license grant. That release is not rewritten. The 0.2.0
+candidate declares `"license": "MIT"` and ships its `LICENSE` file in the package.
+
 ## Host responsibilities
 
 Create a client with an explicit base URL and optional `fetch` implementation.
@@ -40,6 +113,62 @@ produced partial output, or started a side effect. Acceptance, partial output,
 and side effects block replay. Unknown outcomes require affirmative host
 evidence and authorization; an idempotency header alone is not evidence.
 
+Hosts that maintain a durable attempt ledger can use `onAttemptStart` and
+`onAttemptOutcome` to record dispatch and settlement evidence. The outcome hook
+is informational and does not authorize replay; hosts must still use
+`authorizeReplay` for every additional attempt. Hook payloads contain operation
+and attempt identities plus bounded execution facts, never request bodies,
+credentials, or response content.
+
 Errors expose bounded, redacted diagnostic fields and request IDs, not raw
 response bodies or request credentials. Hosts may retain their existing
 product-specific error mappings around these shared primitives.
+
+## Shared wire contracts (0.2 candidate)
+
+The 0.2 candidate adds one implementation of the public Qortex contracts that
+QitQode and Wud previously duplicated. Each area states what QitQore does and
+what stays with the host.
+
+- **Recovery lease and control.** `parseRecoveryStatus` accepts Qortex's
+  optional `recoveryLeaseUsage` only when it names the status's request, and the
+  status's route whenever the status includes one.
+  `parseRecoveryControlEnvelope`, `encodeRecoveryControlEnvelope`, and
+  `decodeRecoveryControlHeader` validate the header value Qortex reads. The
+  decoder accepts only canonical base64url. The host allocates token budgets,
+  persists leases, decides which work may run, and settles outcomes.
+- **Routes and headers.** `recoveryRouteID`, `qortexModuleEndpoint`,
+  `qortexRequestHeaders`, and `withRecoveryControlHeader` take every module name,
+  identity, and key from the caller. Scoped historical paths such as
+  `@bijikyu/omniquery` are preserved exactly. QitQore never chooses between the
+  canonical and historical module, never generates a request or idempotency
+  identity, and never adds credentials.
+- **SSE payloads.** `SseDecoder` and `iterateSse` frame the stream.
+  `classifyQortexStreamPayload` then returns a tagged result: `text`, `json`,
+  `usage`, `cost`, `control` (the documented free-fallback routing signal),
+  `done`, `error`, or `empty`. Plain tokens stay `text`, malformed or non-object
+  JSON stays `text`, and unknown objects stay `json`. The host converts OpenAI
+  chunks, tool calls, finish reasons, accounting, and terminal success. A stream
+  that ends without a terminator remains incomplete.
+- **Error evidence.** `qortexErrorEvidence` reads the top-level, `error`, and
+  `details` envelopes once and keeps only allowlisted fields: acceptance,
+  partial output, side-effect markers, a validated recovery directive, and
+  whether replay evidence was available. Any non-`false` acceptance signal
+  blocks replay, including values QitQore does not recognize. A terminal
+  `retryable: false` wins over `true`. Use `hasReplayBlockingEvidence` before
+  replaying; absence of evidence is never permission to replay.
+- **Secret redaction.** `createSecretRedactor` is pure and opt-in. The host
+  passes exact values and key names. It returns redaction, chunk-safe stream
+  redaction, and bounded structural redaction. It does not read the environment,
+  keep a global registry, or discover credentials. Pass `patterns: false` for
+  model output, where credential-shape heuristics could alter ordinary prose.
+- **Forgewise device authorization.** `parseDeviceAuthorizationStart` validates
+  the start response and resolves expiry from an explicit `now`.
+  `classifyDeviceTokenPoll` classifies one poll as success, pending, slow-down
+  (through `pending`), denied, expired, failed, or invalid. It does not poll,
+  sleep, open a browser, persist a code, install a credential, refresh a session,
+  or read a clock. The host owns all of those.
+
+Acceptance, partial-output, side-effect, and directive fields are evidence for
+the host's replay decision. They are not authorization, billing settlement, or
+proof of an exactly-once effect.

package/dist/device-authorization.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Stateless Forgewise device-authorization protocol (RFC 8628 response shapes).
+ * These functions validate protocol data and classify poll outcomes. They never
+ * poll, sleep, open a browser, persist a code, install or refresh a credential,
+ * or read a clock: the caller passes the current time explicitly.
+ */
+export declare const DEVICE_AUTHORIZATION_DEFAULT_EXPIRES_IN_SECONDS = 900;
+export declare const DEVICE_AUTHORIZATION_DEFAULT_INTERVAL_SECONDS = 5;
+export declare const DEVICE_AUTHORIZATION_SLOW_DOWN_STEP_SECONDS = 5;
+/** Upper bound for any server-supplied polling interval, so a hostile value cannot stall a host. */
+export declare const DEVICE_AUTHORIZATION_MAX_INTERVAL_SECONDS = 3600;
+/** Upper bound for any server-supplied code lifetime. */
+export declare const DEVICE_AUTHORIZATION_MAX_EXPIRES_IN_SECONDS = 86400;
+/** Validated device authorization start, with the expiry resolved to epoch milliseconds. */
+export interface DeviceAuthorizationStart {
+    deviceCode: string;
+    userCode: string;
+    verificationUri: string;
+    verificationUriComplete?: string;
+    expiresAt: number;
+    intervalSeconds: number;
+}
+/** Outcome of one token poll. Only bounded, safe fields are carried. */
+export type DeviceTokenPollOutcome = {
+    kind: "success";
+    accessToken: string;
+    refreshToken?: string;
+    expiresInSeconds?: number;
+} | {
+    kind: "pending";
+    intervalSeconds: number;
+} | {
+    kind: "denied";
+} | {
+    kind: "expired";
+} | {
+    kind: "failed";
+    code: string;
+} | {
+    kind: "invalid";
+};
+/** Thrown when the authorization-start response is missing a required protocol field. */
+export declare class DeviceAuthorizationProtocolError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Validate the device authorization response. Required fields must be present
+ * and well-formed. Optional timing is clamped, not trusted. `now` is the caller's
+ * current epoch time in milliseconds.
+ */
+export declare function parseDeviceAuthorizationStart(value: unknown, now: number): DeviceAuthorizationStart;
+/** True once the code's lifetime has elapsed. The boundary instant itself counts as expired. */
+export declare function deviceAuthorizationExpired(input: {
+    expiresAt: number;
+    now: number;
+}): boolean;
+/**
+ * Classify one device-token poll. `intervalSeconds` is the host's current
+ * interval, which `slow_down` increases by a bounded step. Errors other than the
+ * RFC 8628 set are reported only by their safe code, never by description text.
+ */
+export declare function classifyDeviceTokenPoll(input: {
+    status: number;
+    body: unknown;
+    intervalSeconds: number;
+}): DeviceTokenPollOutcome;
+//# sourceMappingURL=device-authorization.d.ts.map

package/dist/device-authorization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-authorization.d.ts","sourceRoot":"","sources":["../src/device-authorization.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAO,MAAM,+CAA+C,MAAM,CAAC;AACnE,eAAO,MAAM,6CAA6C,IAAI,CAAC;AAC/D,eAAO,MAAM,2CAA2C,IAAI,CAAC;AAC7D,oGAAoG;AACpG,eAAO,MAAM,yCAAyC,OAAQ,CAAC;AAC/D,yDAAyD;AACzD,eAAO,MAAM,2CAA2C,QAAS,CAAC;AAQlE,4FAA4F;AAC5F,MAAM,WAAW,wBAAwB;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,wEAAwE;AACxE,MAAM,MAAM,sBAAsB,GAC9B;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAE,GAC1F;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,eAAe,EAAE,MAAM,CAAA;CAAE,GAC5C;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAExB,yFAAyF;AACzF,qBAAa,gCAAiC,SAAQ,KAAK;gBAC7C,OAAO,SAAiE;CAIrF;AA6BD;;;;GAIG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,wBAAwB,CA8BnG;AAED,gGAAgG;AAChG,wBAAgB,0BAA0B,CAAC,KAAK,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAE7F;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,eAAe,EAAE,MAAM,CAAC;CACzB,GAAG,sBAAsB,CAiCzB"}

package/dist/device-authorization.js

@@ -0,0 +1,122 @@
+/**
+ * Stateless Forgewise device-authorization protocol (RFC 8628 response shapes).
+ * These functions validate protocol data and classify poll outcomes. They never
+ * poll, sleep, open a browser, persist a code, install or refresh a credential,
+ * or read a clock: the caller passes the current time explicitly.
+ */
+export const DEVICE_AUTHORIZATION_DEFAULT_EXPIRES_IN_SECONDS = 900;
+export const DEVICE_AUTHORIZATION_DEFAULT_INTERVAL_SECONDS = 5;
+export const DEVICE_AUTHORIZATION_SLOW_DOWN_STEP_SECONDS = 5;
+/** Upper bound for any server-supplied polling interval, so a hostile value cannot stall a host. */
+export const DEVICE_AUTHORIZATION_MAX_INTERVAL_SECONDS = 3_600;
+/** Upper bound for any server-supplied code lifetime. */
+export const DEVICE_AUTHORIZATION_MAX_EXPIRES_IN_SECONDS = 86_400;
+const MAX_CODE_LENGTH = 2_048;
+const MAX_USER_CODE_LENGTH = 64;
+const MAX_URI_LENGTH = 2_048;
+const MAX_TOKEN_LENGTH = 16_384;
+const SAFE_ERROR_CODE = /^[a-z_]{1,64}$/;
+/** Thrown when the authorization-start response is missing a required protocol field. */
+export class DeviceAuthorizationProtocolError extends Error {
+    constructor(message = "Forgewise returned an invalid device authorization response.") {
+        super(message);
+        this.name = "DeviceAuthorizationProtocolError";
+    }
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function boundedString(value, maxLength) {
+    return typeof value === "string" && value.length > 0 && value.length <= maxLength ? value : undefined;
+}
+/** A verification URI must be absolute HTTPS, or plain HTTP only for a loopback host. */
+function verificationUri(value) {
+    const text = boundedString(value, MAX_URI_LENGTH);
+    if (text === undefined)
+        return undefined;
+    try {
+        const url = new URL(text);
+        const loopback = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+        return url.protocol === "https:" || (url.protocol === "http:" && loopback) ? text : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Clamp a server-supplied number to [1, max] and fall back to the default when it is absent or invalid. */
+function boundedSeconds(value, fallback, max) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return fallback;
+    return Math.min(max, Math.max(1, Math.floor(value)));
+}
+/**
+ * Validate the device authorization response. Required fields must be present
+ * and well-formed. Optional timing is clamped, not trusted. `now` is the caller's
+ * current epoch time in milliseconds.
+ */
+export function parseDeviceAuthorizationStart(value, now) {
+    if (!isRecord(value))
+        throw new DeviceAuthorizationProtocolError();
+    const deviceCode = boundedString(value.device_code, MAX_CODE_LENGTH);
+    const userCode = boundedString(value.user_code, MAX_USER_CODE_LENGTH);
+    const verification = verificationUri(value.verification_uri);
+    if (deviceCode === undefined || userCode === undefined || verification === undefined) {
+        throw new DeviceAuthorizationProtocolError();
+    }
+    const complete = value.verification_uri_complete === undefined ? undefined : verificationUri(value.verification_uri_complete);
+    if (value.verification_uri_complete !== undefined && complete === undefined) {
+        throw new DeviceAuthorizationProtocolError();
+    }
+    const expiresIn = boundedSeconds(value.expires_in, DEVICE_AUTHORIZATION_DEFAULT_EXPIRES_IN_SECONDS, DEVICE_AUTHORIZATION_MAX_EXPIRES_IN_SECONDS);
+    return {
+        deviceCode,
+        userCode,
+        verificationUri: verification,
+        ...(complete === undefined ? {} : { verificationUriComplete: complete }),
+        expiresAt: now + expiresIn * 1_000,
+        intervalSeconds: boundedSeconds(value.interval, DEVICE_AUTHORIZATION_DEFAULT_INTERVAL_SECONDS, DEVICE_AUTHORIZATION_MAX_INTERVAL_SECONDS),
+    };
+}
+/** True once the code's lifetime has elapsed. The boundary instant itself counts as expired. */
+export function deviceAuthorizationExpired(input) {
+    return input.now >= input.expiresAt;
+}
+/**
+ * Classify one device-token poll. `intervalSeconds` is the host's current
+ * interval, which `slow_down` increases by a bounded step. Errors other than the
+ * RFC 8628 set are reported only by their safe code, never by description text.
+ */
+export function classifyDeviceTokenPoll(input) {
+    const body = isRecord(input.body) ? input.body : undefined;
+    if (input.status >= 200 && input.status < 300) {
+        const accessToken = boundedString(body?.access_token, MAX_TOKEN_LENGTH);
+        if (accessToken === undefined)
+            return { kind: "invalid" };
+        const refreshToken = boundedString(body?.refresh_token, MAX_TOKEN_LENGTH);
+        const expiresIn = typeof body?.expires_in === "number" && Number.isFinite(body.expires_in) && body.expires_in > 0
+            ? body.expires_in
+            : undefined;
+        return {
+            kind: "success",
+            accessToken,
+            ...(refreshToken === undefined ? {} : { refreshToken }),
+            ...(expiresIn === undefined ? {} : { expiresInSeconds: expiresIn }),
+        };
+    }
+    const error = typeof body?.error === "string" && SAFE_ERROR_CODE.test(body.error) ? body.error : undefined;
+    if (error === "authorization_pending") {
+        return { kind: "pending", intervalSeconds: input.intervalSeconds };
+    }
+    if (error === "slow_down") {
+        return {
+            kind: "pending",
+            intervalSeconds: Math.min(DEVICE_AUTHORIZATION_MAX_INTERVAL_SECONDS, input.intervalSeconds + DEVICE_AUTHORIZATION_SLOW_DOWN_STEP_SECONDS),
+        };
+    }
+    if (error === "access_denied")
+        return { kind: "denied" };
+    if (error === "expired_token")
+        return { kind: "expired" };
+    return { kind: "failed", code: error ?? `http_${input.status}` };
+}
+//# sourceMappingURL=device-authorization.js.map

package/dist/device-authorization.js.map

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

package/dist/errors.d.ts

@@ -1,4 +1,29 @@
+import { type QortexRecoveryDirective } from "./recovery-directive.js";
 export type QortexErrorCategory = "credentials" | "authorization" | "validation" | "rate-limit" | "gateway" | "server" | "http" | "protocol" | "transport" | "timeout";
+/** Server-reported acceptance, restricted to the public states. */
+export type QortexAcceptanceState = "unknown" | "not-accepted" | "accepted";
+/**
+ * Bounded replay evidence from an error envelope. Only the fields below survive.
+ * `accepted` is set whenever the server reported any acceptance other than
+ * `not-accepted`, including an unrecognized value, so ambiguity fails closed.
+ * Use `hasReplayBlockingEvidence` rather than reading one field by itself.
+ */
+export interface QortexErrorEvidence {
+    contractVersion: 1;
+    /** True when the error body was a JSON object whose fields could be examined. */
+    replayEvidenceAvailable: boolean;
+    accepted?: true;
+    partialOutput?: true;
+    sideEffectStarted?: true;
+    acceptance?: QortexAcceptanceState;
+    recoveryDirective?: QortexRecoveryDirective;
+    /**
+     * The server's explicit retryability verdict, from its directive or envelope.
+     * Absent when the server stated none, in which case `QortexError.retryable`
+     * falls back to the HTTP status.
+     */
+    retryable?: boolean;
+}
 export interface QortexErrorDetails {
     category: QortexErrorCategory;
     message: string;
@@ -6,13 +31,24 @@ export interface QortexErrorDetails {
     status?: number;
     requestId?: string;
     retryable: boolean;
+    evidence?: QortexErrorEvidence;
 }
+/** The first safe request ID named in an error body, read from the documented envelope locations. */
+export declare function qortexErrorRequestId(payload: unknown): string | undefined;
+/**
+ * Read only the bounded evidence from an error payload. Raw strings, unknown
+ * fields, and credentials are never copied into the result.
+ */
+export declare function qortexErrorEvidence(payload: unknown): QortexErrorEvidence;
+/** True when any server evidence forbids replaying the failed attempt. */
+export declare function hasReplayBlockingEvidence(evidence: QortexErrorEvidence | undefined): boolean;
 export declare class QortexError extends Error {
     readonly category: QortexErrorCategory;
     readonly code?: string;
     readonly status?: number;
     readonly requestId?: string;
     readonly retryable: boolean;
+    readonly evidence?: QortexErrorEvidence;
     constructor(details: QortexErrorDetails, options?: {
         cause?: unknown;
     });

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,mBAAmB,GAC3B,aAAa,GACb,eAAe,GACf,YAAY,GACZ,YAAY,GACZ,SAAS,GACT,QAAQ,GACR,MAAM,GACN,UAAU,GACV,WAAW,GACX,SAAS,CAAC;AAEd,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;CACpB;AAmDD,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;IACvC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;gBAG1B,OAAO,EAAE,kBAAkB,EAC3B,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;IAWnC,MAAM,IAAI,kBAAkB;CAU7B;AAED,qBAAa,eAAgB,SAAQ,WAAW;gBAClC,OAAO,EAAE,kBAAkB,EAAE,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAI3E;AAED,qBAAa,kBAAmB,SAAQ,WAAW;gBACrC,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAYjE;AAED,qBAAa,oBAAqB,SAAQ,WAAW;gBACvC,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAY9C;AAED,qBAAa,mBAAoB,SAAQ,WAAW;gBACtC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM;CAWjE;AAED,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE,WAAW,GACpB,eAAe,CA4CjB;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAKpD"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,KAAK,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAG/F,MAAM,MAAM,mBAAmB,GAC3B,aAAa,GACb,eAAe,GACf,YAAY,GACZ,YAAY,GACZ,SAAS,GACT,QAAQ,GACR,MAAM,GACN,UAAU,GACV,WAAW,GACX,SAAS,CAAC;AAEd,mEAAmE;AACnE,MAAM,MAAM,qBAAqB,GAAG,SAAS,GAAG,cAAc,GAAG,UAAU,CAAC;AAE5E;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,eAAe,EAAE,CAAC,CAAC;IACnB,iFAAiF;IACjF,uBAAuB,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,EAAE,IAAI,CAAC;IAChB,aAAa,CAAC,EAAE,IAAI,CAAC;IACrB,iBAAiB,CAAC,EAAE,IAAI,CAAC;IACzB,UAAU,CAAC,EAAE,qBAAqB,CAAC;IACnC,iBAAiB,CAAC,EAAE,uBAAuB,CAAC;IAC5C;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,mBAAmB,CAAC;CAChC;AAsCD,qGAAqG;AACrG,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAIzE;AA8BD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,mBAAmB,CAczE;AA4BD,0EAA0E;AAC1E,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,mBAAmB,GAAG,SAAS,GAAG,OAAO,CAQ5F;AAQD,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;IACvC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,mBAAmB,CAAC;gBAGtC,OAAO,EAAE,kBAAkB,EAC3B,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;IAYnC,MAAM,IAAI,kBAAkB;CAW7B;AAED,qBAAa,eAAgB,SAAQ,WAAW;gBAClC,OAAO,EAAE,kBAAkB,EAAE,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAI3E;AAED,qBAAa,kBAAmB,SAAQ,WAAW;gBACrC,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAYjE;AAED,qBAAa,oBAAqB,SAAQ,WAAW;gBACvC,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAY9C;AAED,qBAAa,mBAAoB,SAAQ,WAAW;gBACtC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM;CAWjE;AAED,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE,WAAW,GACpB,eAAe,CA+CjB;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAKpD"}

package/dist/errors.js

@@ -1,10 +1,9 @@
+import { parseRecoveryDirective } from "./recovery-directive.js";
+import { redactSensitiveText } from "./redaction.js";
 const SAFE_CODE = /^[A-Za-z0-9_.:-]{1,128}$/;
 const SAFE_REQUEST_ID = /^[A-Za-z0-9_.:-]{1,160}$/;
-const AUTH_HEADER = /\b(authorization)\s*[:=]\s*(?:bearer|basic)\s+\S+/gi;
-const SECRET_VALUE = /\b(api[-_ ]?key|access[-_ ]?token|refresh[-_ ]?token|token|password|secret)\s*[:=]\s*["']?[^\s,;"'&]+/gi;
-const BEARER_TOKEN = /\b(bearer|basic)\s+[A-Za-z0-9._~+/-]+=*/gi;
-const URL_SECRET = /([?&](?:api[-_]?key|access[-_]?token|refresh[-_]?token|token|secret)=)[^&\s]+/gi;
-const JWT = /\beyJ[A-Za-z0-9_-]*\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g;
+const ACCEPTANCE_STATES = new Set(["unknown", "not-accepted", "accepted"]);
+const REPLAY_FLAGS = ["accepted", "partialOutput", "sideEffectStarted"];
 function record(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value)
         ? value
@@ -13,16 +12,7 @@ function record(value) {
 function boundedText(value, maxLength) {
     if (typeof value !== "string")
         return undefined;
-    const safe = value
-        .replace(AUTH_HEADER, "$1: [redacted]")
-        .replace(SECRET_VALUE, "$1=[redacted]")
-        .replace(BEARER_TOKEN, "$1 [redacted]")
-        .replace(URL_SECRET, "$1[redacted]")
-        .replace(JWT, "[redacted-token]")
-        .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, " ")
-        .trim()
-        .slice(0, maxLength);
-    return safe || undefined;
+    return redactSensitiveText(value, maxLength) || undefined;
 }
 function safeCode(value) {
     if (typeof value !== "string")
@@ -42,12 +32,108 @@ function safeRequestId(value) {
     const candidate = value?.trim();
     return candidate && SAFE_REQUEST_ID.test(candidate) ? candidate : undefined;
 }
+/** The first safe request ID named in an error body, read from the documented envelope locations. */
+export function qortexErrorRequestId(payload) {
+    return envelopeRecords(payload)
+        .map((item) => safeRequestId(typeof item.requestId === "string" ? item.requestId : undefined))
+        .find((value) => value !== undefined);
+}
+/**
+ * The error envelope may appear at the top level, under `error`, or under
+ * `details`. Those are the documented locations, and each is read once here,
+ * before the raw payload is discarded.
+ */
+function envelopeRecords(payload) {
+    const outer = record(payload);
+    if (!outer)
+        return [];
+    return [outer, record(outer.error), record(outer.details)].filter((item) => item !== undefined);
+}
+function replayEvidence(records) {
+    const evidence = {};
+    for (const flag of REPLAY_FLAGS) {
+        // Any value other than an explicit `false` is ambiguous, and ambiguity blocks replay.
+        if (records.some((item) => item[flag] != null && item[flag] !== false))
+            evidence[flag] = true;
+    }
+    const reported = records.map((item) => item.acceptance).filter((value) => value != null);
+    if (reported.some((value) => value !== "not-accepted"))
+        evidence.accepted = true;
+    if (reported.length === 0)
+        return evidence;
+    if (reported.includes("accepted"))
+        evidence.acceptance = "accepted";
+    else if (reported.includes("unknown"))
+        evidence.acceptance = "unknown";
+    else if (reported.every((value) => value === "not-accepted"))
+        evidence.acceptance = "not-accepted";
+    return evidence;
+}
+/**
+ * Read only the bounded evidence from an error payload. Raw strings, unknown
+ * fields, and credentials are never copied into the result.
+ */
+export function qortexErrorEvidence(payload) {
+    const records = envelopeRecords(payload);
+    if (records.length === 0)
+        return { contractVersion: 1, replayEvidenceAvailable: false };
+    const directiveSource = records.map((item) => item.recoveryDirective).find((value) => value !== undefined);
+    const directive = directiveSource === undefined ? undefined : parseDirectiveSafely(directiveSource);
+    const retryable = explicitRetryable(records, directive);
+    return {
+        contractVersion: 1,
+        replayEvidenceAvailable: true,
+        ...replayEvidence(records),
+        ...(directive === undefined ? {} : { recoveryDirective: directive }),
+        ...(retryable === undefined ? {} : { retryable }),
+    };
+}
+/**
+ * The server's own verdict. An explicit `false` is terminal. Otherwise a valid
+ * directive decides, and then an explicit `true` from the envelope.
+ */
+function explicitRetryable(records, directive) {
+    const verdicts = records
+        .map((item) => item.retryable)
+        .filter((value) => typeof value === "boolean");
+    if (verdicts.includes(false))
+        return false;
+    if (directive !== undefined)
+        return directive.retryable;
+    if (verdicts.includes(true))
+        return true;
+    return undefined;
+}
+function parseDirectiveSafely(value) {
+    // A malformed or future directive is omitted rather than reflected to the caller.
+    try {
+        return parseRecoveryDirective(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** True when any server evidence forbids replaying the failed attempt. */
+export function hasReplayBlockingEvidence(evidence) {
+    return (evidence !== undefined &&
+        (evidence.accepted === true ||
+            evidence.partialOutput === true ||
+            evidence.sideEffectStarted === true ||
+            (evidence.acceptance !== undefined && evidence.acceptance !== "not-accepted")));
+}
+/** The server's explicit verdict wins. Otherwise the HTTP status decides. */
+function resolveRetryable(status, evidence) {
+    if (evidence.retryable !== undefined)
+        return evidence.retryable;
+    return status === 408 || status === 425 || status === 429 || status >= 500;
+}
 export class QortexError extends Error {
     category;
     code;
     status;
     requestId;
     retryable;
+    evidence;
     constructor(details, options = {}) {
         super(details.message, options.cause === undefined ? undefined : { cause: options.cause });
         this.name = "QortexError";
@@ -56,6 +142,7 @@ export class QortexError extends Error {
         this.status = details.status;
         this.requestId = details.requestId;
         this.retryable = details.retryable;
+        this.evidence = details.evidence;
     }
     toJSON() {
         return {
@@ -65,6 +152,7 @@ export class QortexError extends Error {
             ...(this.status === undefined ? {} : { status: this.status }),
             ...(this.requestId ? { requestId: this.requestId } : {}),
             retryable: this.retryable,
+            ...(this.evidence ? { evidence: this.evidence } : {}),
         };
     }
 }
@@ -112,6 +200,7 @@ export class QortexProtocolError extends QortexError {
 export function qortexHttpError(status, payload, headers) {
     const outer = record(payload);
     const nested = record(outer?.error);
+    const evidence = qortexErrorEvidence(payload);
     const code = safeCode(outer?.code) ??
         safeCode(nested?.code) ??
         (typeof outer?.error === "string" ? safeCode(outer.error) : undefined) ??
@@ -124,7 +213,8 @@ export function qortexHttpError(status, payload, headers) {
     const requestHeaders = new Headers(headers);
     const requestId = safeRequestId(requestHeaders.get("x-request-id")) ??
         safeRequestId(requestHeaders.get("request-id")) ??
-        safeRequestId(requestHeaders.get("x-qlex-request-id"));
+        safeRequestId(requestHeaders.get("x-qlex-request-id")) ??
+        qortexErrorRequestId(payload);
     const envelopeFailure = outer?.success === false;
     let category;
     if (envelopeFailure && status < 400)
@@ -153,7 +243,8 @@ export function qortexHttpError(status, payload, headers) {
         code,
         status,
         ...(requestId ? { requestId } : {}),
-        retryable: status === 408 || status === 425 || status === 429 || status >= 500,
+        retryable: resolveRetryable(status, evidence),
+        evidence,
     });
 }
 export function isAbortError(error) {