@qitqode/qitqore 0.1.0 → 0.3.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,27 @@ 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.
+
+The published `@qitqode/qitqore@0.3.0` release is immutable and licensed under
+the [MIT License](./LICENSE), the same license as QitQode. Its package includes
+the `LICENSE` file. The copyright holder is QitQode contributors, Spannings LLC.
+
+The `0.1.0` and `0.2.0` artifacts remain immutable; current consumer pins target
+`0.2.0` until each consumer adopts `0.3.0`.
+
 ## Development
 
 - Requires Node.js 24 or newer.
@@ -21,6 +42,60 @@ 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 latest public package is **`@qitqode/qitqore@0.3.0`**. Install it with
+`npm install --save-exact @qitqode/qitqore@0.3.0`. The independently managed
+QitQode CLI, its backend SDK, and Wud currently pin the exact `0.2.0` release in
+their own manifests and native Bun/npm lockfiles; they do not import sibling
+source. Adopting `0.3.0` in a consumer is a separate change to its exact pin and
+regenerated lockfile.
+
+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
+published `0.2.0` release 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 +115,96 @@ 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.
+
+## Release 0.3.0
+
+Version 0.3.0 adds features without removing or renaming any 0.2.0 export:
+
+- **Decision-policy client.** New `createDecisionPolicyClient`,
+  `assertDecisionPolicyRequest`, `parseDecisionPolicyResult` and
+  `DECISION_POLICY_CONTRACT_VERSION`, described below.
+- **Free-tier fallback stage.** `SseDecoder` events may carry
+  `routingStatus: "free-fallback"` and `routingStage: "auto-free" | "free-pool"`
+  from Qortex's routing headers. `classifyQortexStreamPayload` reports the same
+  stage as an optional `fallbackStage` on a `routing-status` control frame.
+- **Untrusted stage values.** A routing-status frame whose `fallbackStage` is
+  present but is neither `auto-free` nor `free-pool` is now classified as plain
+  `json` instead of a routing-status control. A frame without `fallbackStage`
+  is classified exactly as in 0.2.0.
+
+## Decision-policy client
+
+`createDecisionPolicyClient` is a typed, zero-dependency client for OmniQuery's
+named decision policies, reached through a Qortex module route. It validates the
+request and response contract, and it makes exactly one POST per call with no
+retries. The host supplies the base URL, the module path, the function name and
+the caller's credential headers. QitQore never chooses a policy, tier, model or
+rubric, never loads or stores credentials, and never invents request or
+idempotency identities. A result is returned as data for the host to decide on.
+
+The response parser cross-checks the status against the findings and the
+aggregate usage against the per-invocation segments. A tampered or inconsistent
+result is a `QortexProtocolError`, not a decision. The client was first
+published in `0.3.0`.
+
+## Shared wire contracts (0.2.0)
+
+The 0.2.0 release 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`. The routing control keeps its generic status and
+  accepts only an optional `fallbackStage` of `auto-free` or `free-pool`; legacy
+  stage-less frames remain valid, while unknown stage values stay ordinary JSON.
+  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/decision-policy.d.ts

@@ -0,0 +1,132 @@
+import { QortexClient } from "./transport.js";
+export declare const DECISION_POLICY_CONTRACT_VERSION = 1;
+export type DecisionPolicyStatus = "decided" | "partial" | "abstained";
+export type DecisionNativeTier = "decisions" | "quick-decisions";
+export interface DecisionPolicySubject {
+    kind: "request" | "candidate" | "requirement_check";
+    id: string;
+    requirementID?: string;
+    checkID?: string;
+    evidenceIDs?: string[];
+}
+export interface DecisionPolicyFinding {
+    findingID: string;
+    subject: DecisionPolicySubject;
+    status: "decided" | "abstained";
+    source: "model" | "deterministic";
+    nativeType: "noul" | "choice" | "score" | null;
+    verdict: string | null;
+    selectedCandidateID?: string;
+    noul?: number;
+    probabilities?: Record<string, number>;
+    confidence?: number;
+    ordinalScore?: number;
+    legend?: Record<string, unknown>;
+    nativeTier?: DecisionNativeTier;
+    reasonCodes: string[];
+}
+export interface DecisionPolicyInvocation {
+    invocationID: string;
+    tier: DecisionNativeTier;
+    nativeUsage: {
+        input_tokens: number;
+        output_tokens: number;
+    };
+    usage: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+        context_window: number;
+    };
+}
+export interface DecisionPolicyResult {
+    contractVersion: 1;
+    policy: string;
+    policyVersion: string;
+    status: DecisionPolicyStatus;
+    verdict: string | null;
+    findings: DecisionPolicyFinding[];
+    observationOnly: boolean;
+    reasonCodes: string[];
+    durationMs: number;
+    requestID?: string;
+    usage: {
+        invocations: DecisionPolicyInvocation[];
+        aggregate: {
+            promptTokens: number;
+            completionTokens: number;
+            totalTokens: number;
+        };
+    };
+}
+export interface DecisionPolicyRequest {
+    contractVersion: 1;
+    policy: string;
+    expectedPolicyVersion?: string;
+    state: Record<string, unknown>;
+    evidence?: Record<string, unknown>;
+    images?: Array<string | {
+        content_type: string;
+        base64: string;
+    }>;
+    timeoutMs?: number;
+    requestID?: string;
+    escalation?: "none" | "full-on-abstain";
+}
+export interface DecisionPolicyCallOptions {
+    /** Caller-supplied credential headers, for example the Forgewise or Qortex key. QitQode never creates them. */
+    headers: HeadersInit;
+    /** Host-supplied request identity. Never invented here. */
+    requestId?: string;
+    /** Host-supplied stable idempotency key. Never invented here. */
+    idempotencyKey?: string;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+export interface DecisionPolicyResponse {
+    data: DecisionPolicyResult;
+    status: number;
+    requestId?: string;
+}
+export interface DecisionPolicyClientOptions {
+    /** Explicit Qortex base URL. Required so the route origin is always an explicit host decision. */
+    baseUrl: string | URL;
+    /** Optional preconstructed transport. Its base URL must match `baseUrl`. */
+    client?: QortexClient;
+    fetch?: typeof globalThis.fetch;
+    timeoutMs?: number;
+    /** Host-selected approved module path, for example the one the host has tested against. No default. */
+    module: string;
+    /** Host-selected public function name, for example `evaluateDecisionPolicy`. No default. */
+    functionName: string;
+}
+export interface DecisionPolicyClient {
+    evaluate(request: DecisionPolicyRequest, options: DecisionPolicyCallOptions): Promise<DecisionPolicyResponse>;
+}
+/**
+ * Validate a caller's request locally before any network call.
+ * @param value - Untrusted request body.
+ * @returns The same request, typed.
+ * @throws TypeError naming the first violated rule. Values are never echoed.
+ */
+export declare function assertDecisionPolicyRequest(value: unknown): DecisionPolicyRequest;
+/**
+ * Parse and cross-check a policy result. The status must agree with the findings, and the aggregate must equal
+ * the sum of the per-invocation segments, so a malformed or tampered response cannot pass as a decided result.
+ * @param value - Unwrapped policy result from the Qortex envelope.
+ * @param context - Status and request ID for sanitized error evidence.
+ * @returns A typed result.
+ * @throws QortexProtocolError for any contract violation.
+ */
+export declare function parseDecisionPolicyResult(value: unknown, context?: {
+    status?: number;
+    requestId?: string;
+}): DecisionPolicyResult;
+/**
+ * Create a typed decision-policy client for one explicitly selected Qortex module function.
+ * @param options - Base URL, optional transport, and the host-chosen module and function names.
+ * @returns A client whose `evaluate` sends one POST per call and never retries.
+ * @throws TypeError for an invalid module, function name or base URL.
+ */
+export declare function createDecisionPolicyClient(options: DecisionPolicyClientOptions): DecisionPolicyClient;
+//# sourceMappingURL=decision-policy.d.ts.map

package/dist/decision-policy.d.ts.map

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

package/dist/decision-policy.js

@@ -0,0 +1,308 @@
+/**
+ * Typed client for OmniQuery's named decision policies, reached through a Qortex module route.
+ *
+ * QitQore validates the contract and carries the call. It never chooses a policy, tier, model, rubric or
+ * temperature; never loads or stores credentials; never invents operation or idempotency IDs; and never retries.
+ * The host supplies the module path, function name, base URL and caller credential headers explicitly, so no
+ * historical alias is picked silently. Semantic outcomes are returned as data; this client decides nothing with them.
+ */
+import { QortexProtocolError } from "./errors.js";
+import { qortexModuleEndpoint, qortexRequestHeaders } from "./route-contract.js";
+import { createQortexClient, unwrapSuccessEnvelope } from "./transport.js";
+export const DECISION_POLICY_CONTRACT_VERSION = 1;
+/** Largest request body the native decision layer accepts (13 MiB serialized). */
+const MAX_REQUEST_BYTES = 13 * 1024 * 1024;
+const MAX_TIMEOUT_MS = 60_000;
+const MAX_IMAGES = 4;
+const POLICY_NAME = /^[a-z][a-z0-9]*(?:\.[a-z0-9]+)*\.v[0-9]+$/;
+const POLICY_VERSION = /^[a-z][a-z0-9]*(?:\.[a-z0-9]+)*\.v[0-9]+@[0-9]+\.[0-9]+\.[0-9]+$/;
+const TIERS = new Set(["decisions", "quick-decisions"]);
+const REQUEST_KEYS = new Set([
+    "contractVersion", "policy", "expectedPolicyVersion", "state", "evidence",
+    "images", "timeoutMs", "requestID", "escalation",
+]);
+/** Options a caller may never send: tier, model and sampling are chosen server-side by the registry. */
+const FORBIDDEN_REQUEST_KEYS = ["tier", "model", "temperature"];
+function contractError(message) {
+    return new TypeError(message);
+}
+function isPlainObject(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+/**
+ * Validate a caller's request locally before any network call.
+ * @param value - Untrusted request body.
+ * @returns The same request, typed.
+ * @throws TypeError naming the first violated rule. Values are never echoed.
+ */
+export function assertDecisionPolicyRequest(value) {
+    if (!isPlainObject(value))
+        throw contractError("Decision policy request must be a plain object");
+    for (const key of FORBIDDEN_REQUEST_KEYS) {
+        if (Object.hasOwn(value, key))
+            throw contractError("Decision policy requests cannot choose a tier, model or sampling option");
+    }
+    for (const key of Object.keys(value)) {
+        if (!REQUEST_KEYS.has(key))
+            throw contractError("Decision policy request contains an undocumented field");
+    }
+    if (value.contractVersion !== DECISION_POLICY_CONTRACT_VERSION)
+        throw contractError("Decision policy contractVersion must be 1");
+    if (typeof value.policy !== "string" || value.policy.length > 80 || !POLICY_NAME.test(value.policy)) {
+        throw contractError("Decision policy name is invalid");
+    }
+    if (value.expectedPolicyVersion !== undefined && (typeof value.expectedPolicyVersion !== "string"
+        || value.expectedPolicyVersion.length > 120 || !POLICY_VERSION.test(value.expectedPolicyVersion))) {
+        throw contractError("expectedPolicyVersion must name an immutable policy version");
+    }
+    if (!isPlainObject(value.state))
+        throw contractError("Decision policy state must be a plain object");
+    if (value.evidence !== undefined && !isPlainObject(value.evidence))
+        throw contractError("Decision policy evidence must be a plain object");
+    if (value.images !== undefined) {
+        if (!Array.isArray(value.images) || value.images.length > MAX_IMAGES)
+            throw contractError("Decision policy images must be an array of at most four items");
+        for (const image of value.images) {
+            const valid = typeof image === "string"
+                ? /^data:/i.test(image)
+                : isPlainObject(image) && typeof image.content_type === "string" && typeof image.base64 === "string" && image.base64.length > 0;
+            if (!valid)
+                throw contractError("Decision policy image must be a data URL or a content_type and base64 pair");
+        }
+    }
+    if (value.timeoutMs !== undefined && (typeof value.timeoutMs !== "number" || !Number.isFinite(value.timeoutMs)
+        || value.timeoutMs <= 0 || value.timeoutMs > MAX_TIMEOUT_MS)) {
+        throw contractError("Decision policy timeoutMs must be between 1 and 60000");
+    }
+    if (value.requestID !== undefined && (typeof value.requestID !== "string" || value.requestID.length === 0 || value.requestID.length > 128)) {
+        throw contractError("Decision policy requestID must contain between 1 and 128 characters");
+    }
+    if (value.escalation !== undefined && value.escalation !== "none" && value.escalation !== "full-on-abstain") {
+        throw contractError("Decision policy escalation must be none or full-on-abstain");
+    }
+    return value;
+}
+function protocolError(message, status, requestId) {
+    return new QortexProtocolError(message, status, requestId);
+}
+function isFiniteNumber(value, min = -Infinity, max = Infinity) {
+    return typeof value === "number" && Number.isFinite(value) && value >= min && value <= max;
+}
+function isCount(value) {
+    return Number.isInteger(value) && value >= 0;
+}
+function isStringArray(value, max) {
+    return Array.isArray(value) && value.length <= max && value.every(item => typeof item === "string");
+}
+function isProbabilityMap(value) {
+    return isPlainObject(value) && Object.values(value).every(probability => isFiniteNumber(probability, 0, 1));
+}
+function parseSubject(value) {
+    if (!isPlainObject(value) || typeof value.id !== "string")
+        throw protocolError("Decision policy subject is malformed");
+    if (value.kind === "request")
+        return { kind: "request", id: value.id };
+    if (value.kind === "candidate")
+        return { kind: "candidate", id: value.id };
+    if (value.kind === "requirement_check" && typeof value.requirementID === "string"
+        && typeof value.checkID === "string" && isStringArray(value.evidenceIDs, 5)) {
+        return { kind: "requirement_check", id: value.id, requirementID: value.requirementID, checkID: value.checkID, evidenceIDs: [...value.evidenceIDs] };
+    }
+    throw protocolError("Decision policy subject kind is not recognized");
+}
+function parseFinding(value) {
+    if (!isPlainObject(value) || typeof value.findingID !== "string")
+        throw protocolError("Decision policy finding is malformed");
+    const status = value.status;
+    const source = value.source;
+    const nativeType = value.nativeType;
+    if ((status !== "decided" && status !== "abstained") || (source !== "model" && source !== "deterministic")) {
+        throw protocolError("Decision policy finding status is not recognized");
+    }
+    if (nativeType !== null && nativeType !== "noul" && nativeType !== "choice" && nativeType !== "score") {
+        throw protocolError("Decision policy native type is not recognized");
+    }
+    if (value.verdict !== null && typeof value.verdict !== "string")
+        throw protocolError("Decision policy verdict must be a string or null");
+    if (!isStringArray(value.reasonCodes, 16))
+        throw protocolError("Decision policy reason codes are malformed");
+    if (value.noul !== undefined && !isFiniteNumber(value.noul, 0, 1))
+        throw protocolError("Decision policy noul must be a probability");
+    if (value.probabilities !== undefined && !isProbabilityMap(value.probabilities))
+        throw protocolError("Decision policy probabilities must be probabilities");
+    if (value.confidence !== undefined && !isFiniteNumber(value.confidence, 0, 1))
+        throw protocolError("Decision policy confidence must be a probability");
+    if (value.ordinalScore !== undefined && !isFiniteNumber(value.ordinalScore))
+        throw protocolError("Decision policy ordinal score must be finite");
+    if (value.nativeTier !== undefined && !TIERS.has(value.nativeTier))
+        throw protocolError("Decision policy native tier is not recognized");
+    if (value.selectedCandidateID !== undefined && typeof value.selectedCandidateID !== "string")
+        throw protocolError("Decision policy selected candidate is malformed");
+    return {
+        findingID: value.findingID,
+        subject: parseSubject(value.subject),
+        status,
+        source,
+        nativeType,
+        verdict: value.verdict,
+        reasonCodes: [...value.reasonCodes],
+        ...(value.noul !== undefined && { noul: value.noul }),
+        ...(value.probabilities !== undefined && { probabilities: { ...value.probabilities } }),
+        ...(value.confidence !== undefined && { confidence: value.confidence }),
+        ...(value.ordinalScore !== undefined && { ordinalScore: value.ordinalScore }),
+        ...(value.legend !== undefined && isPlainObject(value.legend) && { legend: { ...value.legend } }),
+        ...(value.nativeTier !== undefined && { nativeTier: value.nativeTier }),
+        ...(value.selectedCandidateID !== undefined && { selectedCandidateID: value.selectedCandidateID }),
+    };
+}
+function parseInvocation(value) {
+    if (!isPlainObject(value) || typeof value.invocationID !== "string" || !TIERS.has(value.tier)) {
+        throw protocolError("Decision policy usage segment is malformed");
+    }
+    const native = value.nativeUsage;
+    const usage = value.usage;
+    if (!isPlainObject(native) || !isCount(native.input_tokens) || !isCount(native.output_tokens)) {
+        throw protocolError("Decision policy native usage is malformed");
+    }
+    if (!isPlainObject(usage) || !isCount(usage.prompt_tokens) || !isCount(usage.completion_tokens)
+        || !isCount(usage.total_tokens) || !isCount(usage.context_window)) {
+        throw protocolError("Decision policy usage is malformed");
+    }
+    return {
+        invocationID: value.invocationID,
+        tier: value.tier,
+        nativeUsage: { input_tokens: native.input_tokens, output_tokens: native.output_tokens },
+        usage: {
+            prompt_tokens: usage.prompt_tokens, completion_tokens: usage.completion_tokens,
+            total_tokens: usage.total_tokens, context_window: usage.context_window,
+        },
+    };
+}
+/**
+ * Parse and cross-check a policy result. The status must agree with the findings, and the aggregate must equal
+ * the sum of the per-invocation segments, so a malformed or tampered response cannot pass as a decided result.
+ * @param value - Unwrapped policy result from the Qortex envelope.
+ * @param context - Status and request ID for sanitized error evidence.
+ * @returns A typed result.
+ * @throws QortexProtocolError for any contract violation.
+ */
+export function parseDecisionPolicyResult(value, context = {}) {
+    const fail = (message) => protocolError(message, context.status, context.requestId);
+    if (!isPlainObject(value))
+        throw fail("Decision policy result is malformed");
+    if (value.contractVersion !== DECISION_POLICY_CONTRACT_VERSION)
+        throw fail("Decision policy result uses an unsupported contract version");
+    if (typeof value.policy !== "string" || !POLICY_NAME.test(value.policy))
+        throw fail("Decision policy result names an invalid policy");
+    if (typeof value.policyVersion !== "string" || !POLICY_VERSION.test(value.policyVersion))
+        throw fail("Decision policy result has an invalid policy version");
+    if (value.status !== "decided" && value.status !== "partial" && value.status !== "abstained")
+        throw fail("Decision policy status is not recognized");
+    if (value.verdict !== null && typeof value.verdict !== "string")
+        throw fail("Decision policy verdict must be a string or null");
+    if (!Array.isArray(value.findings) || value.findings.length === 0 || value.findings.length > 128)
+        throw fail("Decision policy findings are malformed");
+    if (typeof value.observationOnly !== "boolean")
+        throw fail("Decision policy observationOnly must be a boolean");
+    if (!isStringArray(value.reasonCodes, 16) || !isFiniteNumber(value.durationMs, 0))
+        throw fail("Decision policy result metadata is malformed");
+    if (value.requestID !== undefined && typeof value.requestID !== "string")
+        throw fail("Decision policy requestID must be a string");
+    if (!isPlainObject(value.usage) || !Array.isArray(value.usage.invocations) || value.usage.invocations.length > 128)
+        throw fail("Decision policy usage is malformed");
+    const findings = value.findings.map(parseFinding);
+    const invocations = value.usage.invocations.map(parseInvocation);
+    const decidedCount = findings.filter(finding => finding.status === "decided").length;
+    const expectedStatus = decidedCount === findings.length ? "decided" : decidedCount === 0 ? "abstained" : "partial";
+    if (value.status !== expectedStatus)
+        throw fail("Decision policy status does not match its findings");
+    const aggregate = value.usage.aggregate;
+    const sum = (pick) => invocations.reduce((total, segment) => total + pick(segment), 0);
+    const expectedAggregate = {
+        promptTokens: sum(segment => segment.usage.prompt_tokens),
+        completionTokens: sum(segment => segment.usage.completion_tokens),
+        totalTokens: sum(segment => segment.usage.total_tokens),
+    };
+    if (!isPlainObject(aggregate) || aggregate.promptTokens !== expectedAggregate.promptTokens
+        || aggregate.completionTokens !== expectedAggregate.completionTokens || aggregate.totalTokens !== expectedAggregate.totalTokens) {
+        throw fail("Decision policy aggregate usage does not equal its invocations");
+    }
+    return {
+        contractVersion: 1,
+        policy: value.policy,
+        policyVersion: value.policyVersion,
+        status: value.status,
+        verdict: value.verdict,
+        findings,
+        observationOnly: value.observationOnly,
+        reasonCodes: [...value.reasonCodes],
+        durationMs: value.durationMs,
+        ...(value.requestID !== undefined && { requestID: value.requestID }),
+        usage: { invocations, aggregate: expectedAggregate },
+    };
+}
+function resolveTransport(options) {
+    if (options.client)
+        return options.client;
+    return createQortexClient({
+        baseUrl: options.baseUrl,
+        ...(options.fetch && { fetch: options.fetch }),
+        ...(options.timeoutMs !== undefined && { timeoutMs: options.timeoutMs }),
+    });
+}
+/**
+ * Create a typed decision-policy client for one explicitly selected Qortex module function.
+ * @param options - Base URL, optional transport, and the host-chosen module and function names.
+ * @returns A client whose `evaluate` sends one POST per call and never retries.
+ * @throws TypeError for an invalid module, function name or base URL.
+ */
+export function createDecisionPolicyClient(options) {
+    // Resolving the endpoint once validates the base URL and the host-chosen module and function names up front.
+    const endpoint = qortexModuleEndpoint({ baseUrl: options.baseUrl, module: options.module, functionName: options.functionName });
+    const transport = resolveTransport(options);
+    return {
+        async evaluate(request, callOptions) {
+            const body = assertDecisionPolicyRequest(request);
+            if (callOptions === null || typeof callOptions !== "object" || callOptions.headers === undefined) {
+                throw contractError("Decision policy calls require caller-supplied headers");
+            }
+            const serialized = JSON.stringify(body);
+            if (new TextEncoder().encode(serialized).byteLength > MAX_REQUEST_BYTES) {
+                throw contractError("Decision policy request exceeds the 13 MiB limit");
+            }
+            const headers = new Headers(callOptions.headers);
+            headers.set("content-type", "application/json");
+            for (const [name, value] of Object.entries(qortexRequestHeaders({
+                ...(callOptions.requestId !== undefined && { requestId: callOptions.requestId }),
+                ...(callOptions.idempotencyKey !== undefined && { idempotencyKey: callOptions.idempotencyKey }),
+            }))) {
+                headers.set(name, value);
+            }
+            const policy = {
+                ...(callOptions.signal && { signal: callOptions.signal }),
+                ...(callOptions.timeoutMs !== undefined && { timeoutMs: callOptions.timeoutMs }),
+            };
+            // Exactly one attempt. Decision inference may already be metered or accepted, so a retry is a host decision.
+            const response = await transport.requestJson(endpoint, { method: "POST", headers, body: serialized }, policy);
+            const data = parseDecisionPolicyResult(unwrapSuccessEnvelope(response.data), {
+                status: response.status,
+                ...(response.requestId !== undefined && { requestId: response.requestId }),
+            });
+            if (data.policy !== body.policy) {
+                throw protocolError("Decision policy result names a different policy than requested", response.status, response.requestId);
+            }
+            if (body.expectedPolicyVersion !== undefined && data.policyVersion !== body.expectedPolicyVersion) {
+                throw protocolError("Decision policy result does not match the expected policy version", response.status, response.requestId);
+            }
+            return {
+                data,
+                status: response.status,
+                ...(response.requestId !== undefined && { requestId: response.requestId }),
+            };
+        },
+    };
+}
+//# sourceMappingURL=decision-policy.js.map