@aiwg/cli 2026.9.19 → 2026.9.21

package/dist/src/decision/batch-receipts/store.js

@@ -0,0 +1,362 @@
+import { createHash } from 'node:crypto';
+import { lstat, readFile, readdir, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { canonicalJson } from '../../security/artifact-trust.js';
+import { mayRestoreDecisionReference } from '../lifecycle.js';
+import { BatchRecordUnavailableError, BatchStoreIntegrityError, BatchStoreMigrationRequiredError, ensurePrivateDirectory, exists, expired, keyedName, macFor, macMatches, parseCanonical, publishExclusive, receiptLifecycleRule, requireIntegrityKey, serialized, syncDirectory, writeTombstone } from './protection.js';
+import { BatchReceiptValidationError, validateBatchReceipt, validateBatchReceiptTransition } from './validate.js';
+export class BatchReceiptConflictError extends Error {
+}
+export class MemoryBatchReceiptStore {
+    records = new Map();
+    async acquire(initial) {
+        validateBatchReceipt(initial);
+        if (initial.revision !== 1 || initial.status !== 'acquired')
+            throw new BatchReceiptValidationError('Initial receipt must be acquired revision 1');
+        const key = scopeKey(initial.batchId, initial.tenantId, initial.projectId);
+        const existing = this.records.get(key);
+        if (existing) {
+            assertSameIdentity(initial, existing);
+            return { owner: false, receipt: structuredClone(existing) };
+        }
+        this.records.set(key, structuredClone(initial));
+        return { owner: true, receipt: structuredClone(initial) };
+    }
+    async read(batchId, tenantId, projectId) {
+        return structuredClone(this.records.get(scopeKey(batchId, tenantId, projectId)) ?? null);
+    }
+    async compareAndSwap(previous, next) {
+        validateBatchReceiptTransition(previous, next);
+        const key = scopeKey(previous.batchId, previous.tenantId, previous.projectId);
+        const current = this.records.get(key);
+        if (!current || canonicalJson(current) !== canonicalJson(previous))
+            return false;
+        this.records.set(key, structuredClone(next));
+        return true;
+    }
+}
+const ENVELOPE = 'decision-batch-receipt-envelope/v1';
+const MAC_DOMAIN = 'decision-batch-receipt/v1';
+const REFERENCE = /^batch-receipt-([a-f0-9]{64})$/;
+const SEALED = /^([a-f0-9]{64})\.r([0-9]+)\.sealed\.json$/;
+const LEGACY = /^([a-f0-9]{64})\.r([0-9]+)\.json$/;
+/**
+ * Every revision is immutable and sealed with a keyed MAC; hard-link publication supplies
+ * filesystem CAS. File names are keyed, so a directory listing does not reveal scope.
+ */
+export class FileBatchReceiptStore {
+    directory;
+    options;
+    key;
+    rule;
+    clock;
+    constructor(directory, options) {
+        this.directory = directory;
+        this.options = options;
+        this.key = requireIntegrityKey(options?.integrityKey, 'Batch receipt');
+        this.rule = receiptLifecycleRule(options);
+        this.clock = options.clock ?? Date.now;
+    }
+    /** Opaque D10 reference for host link registration. It never contains scope identifiers. */
+    lifecycleReference(batchId, tenantId, projectId) {
+        return { surface: 'receipt', opaqueId: `batch-receipt-${this.prefix(batchId, tenantId, projectId)}` };
+    }
+    async acquire(initial) {
+        validateBatchReceipt(initial);
+        if (initial.revision !== 1 || initial.status !== 'acquired')
+            throw new BatchReceiptValidationError('Initial receipt must be acquired revision 1');
+        await this.ensurePrivateDirectory();
+        const prefix = this.prefix(initial.batchId, initial.tenantId, initial.projectId);
+        // An erased batch must never be re-owned: that would re-dispatch a deleted request.
+        if (await this.tombstoned(prefix))
+            throw new BatchRecordUnavailableError();
+        await this.assertNoLegacy(initial.batchId, initial.tenantId, initial.projectId);
+        if (await this.publish(initial)) {
+            if (await this.tombstoned(prefix)) {
+                await this.removeRevisions(prefix);
+                throw new BatchRecordUnavailableError();
+            }
+            return { owner: true, receipt: structuredClone(initial) };
+        }
+        const existing = await this.read(initial.batchId, initial.tenantId, initial.projectId);
+        if (!existing)
+            throw new BatchRecordUnavailableError();
+        assertSameIdentity(initial, existing);
+        return { owner: false, receipt: existing };
+    }
+    /** Erased, expired and missing receipts all return null. */
+    async read(batchId, tenantId, projectId) {
+        await this.ensurePrivateDirectory();
+        const prefix = this.prefix(batchId, tenantId, projectId);
+        if (await this.tombstoned(prefix))
+            return null;
+        const revisions = revisionsIn(await readdir(this.directory), prefix, SEALED);
+        if (!revisions.length) {
+            await this.assertNoLegacy(batchId, tenantId, projectId);
+            return null;
+        }
+        const chain = await this.chain(this.directory, prefix, revisions);
+        if (expired(chain[0].createdAtEpochMs, this.clock(), this.rule))
+            return null;
+        return structuredClone(chain.at(-1));
+    }
+    async compareAndSwap(previous, next) {
+        validateBatchReceiptTransition(previous, next);
+        const current = await this.read(previous.batchId, previous.tenantId, previous.projectId);
+        if (!current || canonicalJson(current) !== canonicalJson(previous))
+            return false;
+        const prefix = this.prefix(next.batchId, next.tenantId, next.projectId);
+        const published = await this.publish(next);
+        if (published && await this.tombstoned(prefix)) {
+            await this.removeRevisions(prefix);
+            return false;
+        }
+        return published;
+    }
+    /**
+     * D10 content eraser for the `receipt` surface. Call it through `eraseDecisionSubject`, which
+     * enforces legal holds and records the journal tombstone first. Publishes a body-free local
+     * tombstone, cascades to the bound result store, then removes every revision body.
+     */
+    async erase(opaqueId) {
+        const match = REFERENCE.exec(opaqueId);
+        if (!match)
+            throw new Error('Batch receipt lifecycle reference invalid');
+        if (!this.options.results)
+            throw new Error('Batch receipt erase requires a bound result store');
+        await this.ensurePrivateDirectory();
+        const prefix = match[1];
+        await writeTombstone(this.directory, this.tombstonePath(prefix), { surface: 'receipt', opaqueId }, this.clock());
+        const revisions = revisionsIn(await readdir(this.directory), prefix, SEALED);
+        let identity = null;
+        for (const revision of revisions) {
+            try {
+                identity = await this.revision(this.directory, prefix, revision);
+                break;
+            }
+            catch { /* try the next sealed revision */ }
+        }
+        if (identity)
+            await this.options.results.eraseBatch(identity.batchId, identity.tenantId, identity.projectId);
+        await this.removeRevisions(prefix);
+        // The bodies are gone, but an unverifiable receipt left its result cascade unresolved.
+        if (revisions.length && !identity)
+            throw new BatchStoreIntegrityError();
+    }
+    /** Erase receipts whose retention elapsed, skipping any the host reports as held. Returns the count erased. */
+    async sweepExpired(isHeld) {
+        if (typeof isHeld !== 'function')
+            throw new Error('Batch receipt sweep requires a hold authority');
+        await this.ensurePrivateDirectory();
+        let erased = 0;
+        for (const prefix of prefixesIn(await readdir(this.directory))) {
+            if (await this.tombstoned(prefix))
+                continue;
+            let first;
+            try {
+                first = await this.revision(this.directory, prefix, 1);
+            }
+            catch {
+                continue;
+            }
+            if (!expired(first.createdAtEpochMs, this.clock(), this.rule))
+                continue;
+            const reference = { surface: 'receipt', opaqueId: `batch-receipt-${prefix}` };
+            let held = true;
+            try {
+                held = await isHeld(reference) !== false;
+            }
+            catch { /* an unavailable hold authority keeps the record */ }
+            if (held)
+                continue;
+            await this.erase(reference.opaqueId);
+            erased++;
+        }
+        return erased;
+    }
+    /**
+     * Restore sealed revisions from a backup copy of this store. A batch is refused when it is
+     * tombstoned locally or by the host, is past retention, or fails verification.
+     */
+    async restoreFrom(backupDirectory, tombstones = []) {
+        if (this.rule.backup === 'not-persisted')
+            throw new Error('Batch receipt backup restore denied by lifecycle policy');
+        await this.ensurePrivateDirectory();
+        const names = await readdir(backupDirectory);
+        const report = { restored: 0, refused: 0 };
+        for (const prefix of prefixesIn(names)) {
+            const reference = { surface: 'receipt', opaqueId: `batch-receipt-${prefix}` };
+            try {
+                const revisions = revisionsIn(names, prefix, SEALED);
+                const chain = await this.chain(backupDirectory, prefix, revisions);
+                if (await this.tombstoned(prefix)
+                    || !mayRestoreDecisionReference(reference, chain[0].createdAtEpochMs, this.clock(), this.options.lifecycle, tombstones)) {
+                    report.refused++;
+                    continue;
+                }
+                for (const revision of revisions) {
+                    const name = sealedName(prefix, revision);
+                    const contents = await readFile(join(backupDirectory, name), 'utf8');
+                    if (!await publishExclusive(this.directory, join(this.directory, name), contents, 'batch-receipt')
+                        && await readFile(join(this.directory, name), 'utf8') !== contents)
+                        throw new BatchStoreIntegrityError();
+                }
+                report.restored++;
+            }
+            catch {
+                report.refused++;
+            }
+        }
+        return report;
+    }
+    /**
+     * Explicit, authorized upgrade of unkeyed revisions written before integrity protection.
+     * Every legacy chain is validated before authorization; nothing is written unless it is granted.
+     */
+    async migrateLegacy(authorize) {
+        await this.ensurePrivateDirectory();
+        const names = await readdir(this.directory);
+        const chains = [];
+        for (const legacyPrefix of new Set(names.flatMap(name => LEGACY.exec(name)?.[1] ?? []))) {
+            const chain = [];
+            for (const [index, revision] of revisionsIn(names, legacyPrefix, LEGACY).entries()) {
+                const path = join(this.directory, `${legacyPrefix}.r${revision}.json`);
+                await assertPrivateFile(path, 'Insecure batch receipt file');
+                let receipt;
+                try {
+                    receipt = JSON.parse(await readFile(path, 'utf8'));
+                    validateBatchReceipt(receipt);
+                }
+                catch {
+                    throw new BatchStoreIntegrityError();
+                }
+                if (revision !== index + 1 || receipt.revision !== revision
+                    || filePrefix(receipt.batchId, receipt.tenantId, receipt.projectId) !== legacyPrefix)
+                    throw new BatchStoreIntegrityError();
+                if (chain.length)
+                    validateBatchReceiptTransition(chain.at(-1), receipt);
+                chain.push(receipt);
+            }
+            chains.push(chain);
+        }
+        if (!chains.length)
+            return { migrated: 0 };
+        let approved = false;
+        try {
+            approved = await authorize({ receipts: chains.length, revisions: chains.reduce((sum, chain) => sum + chain.length, 0) }) === true;
+        }
+        catch { /* authorization fails closed */ }
+        if (!approved)
+            throw new Error('Batch store migration denied');
+        for (const chain of chains) {
+            const first = chain[0];
+            const prefix = this.prefix(first.batchId, first.tenantId, first.projectId);
+            if (await this.tombstoned(prefix))
+                throw new BatchRecordUnavailableError();
+            for (const receipt of chain) {
+                if (!await this.publish(receipt)
+                    && canonicalJson(await this.revision(this.directory, prefix, receipt.revision)) !== canonicalJson(receipt)) {
+                    throw new BatchReceiptConflictError('Legacy batch receipt conflicts with a sealed revision');
+                }
+            }
+            const legacyPrefix = filePrefix(first.batchId, first.tenantId, first.projectId);
+            for (const receipt of chain)
+                await rm(join(this.directory, `${legacyPrefix}.r${receipt.revision}.json`));
+        }
+        await syncDirectory(this.directory);
+        return { migrated: chains.length };
+    }
+    prefix(batchId, tenantId, projectId) {
+        return keyedName(this.key, 'decision-batch-receipt-name/v1', [tenantId, projectId, batchId]);
+    }
+    tombstonePath(prefix) { return join(this.directory, `${prefix}.tombstone`); }
+    async tombstoned(prefix) {
+        if (await exists(this.tombstonePath(prefix)))
+            return true;
+        if (!this.options.isTombstoned)
+            return false;
+        try {
+            return await this.options.isTombstoned({ surface: 'receipt', opaqueId: `batch-receipt-${prefix}` }) !== false;
+        }
+        catch {
+            return true;
+        }
+    }
+    async assertNoLegacy(batchId, tenantId, projectId) {
+        if (revisionsIn(await readdir(this.directory), filePrefix(batchId, tenantId, projectId), LEGACY).length) {
+            throw new BatchStoreMigrationRequiredError();
+        }
+    }
+    async chain(directory, prefix, revisions) {
+        revisions.forEach((revision, index) => { if (revision !== index + 1)
+            throw new BatchReceiptValidationError('Batch receipt revision gap'); });
+        const chain = [];
+        for (const revision of revisions) {
+            const receipt = await this.revision(directory, prefix, revision);
+            if (chain.length)
+                validateBatchReceiptTransition(chain.at(-1), receipt);
+            chain.push(receipt);
+        }
+        return chain;
+    }
+    async revision(directory, prefix, revision) {
+        const path = join(directory, sealedName(prefix, revision));
+        if (directory === this.directory)
+            await assertPrivateFile(path, 'Insecure batch receipt file');
+        try {
+            const envelope = parseCanonical(await readFile(path, 'utf8'));
+            if (!envelope || envelope.version !== ENVELOPE || Object.keys(envelope).length !== 3
+                || !macMatches(this.key, MAC_DOMAIN, envelope.receipt, envelope.mac))
+                throw new BatchStoreIntegrityError();
+            validateBatchReceipt(envelope.receipt);
+            if (envelope.receipt.revision !== revision
+                || this.prefix(envelope.receipt.batchId, envelope.receipt.tenantId, envelope.receipt.projectId) !== prefix) {
+                throw new BatchStoreIntegrityError();
+            }
+            return envelope.receipt;
+        }
+        catch {
+            throw new BatchStoreIntegrityError();
+        }
+    }
+    async removeRevisions(prefix) {
+        for (const revision of revisionsIn(await readdir(this.directory), prefix, SEALED)) {
+            await rm(join(this.directory, sealedName(prefix, revision)), { force: true });
+        }
+        await syncDirectory(this.directory);
+    }
+    async ensurePrivateDirectory() {
+        await ensurePrivateDirectory(this.directory, 'Insecure batch receipt directory');
+    }
+    async publish(receipt) {
+        const prefix = this.prefix(receipt.batchId, receipt.tenantId, receipt.projectId);
+        const envelope = { version: ENVELOPE, receipt, mac: macFor(this.key, MAC_DOMAIN, receipt) };
+        return publishExclusive(this.directory, join(this.directory, sealedName(prefix, receipt.revision)), serialized(envelope), 'batch-receipt');
+    }
+}
+function sealedName(prefix, revision) { return `${prefix}.r${revision}.sealed.json`; }
+function prefixesIn(names) { return new Set(names.flatMap(name => SEALED.exec(name)?.[1] ?? [])); }
+function revisionsIn(names, prefix, pattern) {
+    return names.flatMap(name => { const match = pattern.exec(name); return match && match[1] === prefix ? [Number(match[2])] : []; })
+        .sort((a, b) => a - b);
+}
+async function assertPrivateFile(path, message) {
+    const stat = await lstat(path);
+    if (!stat.isFile() || (stat.mode & 0o077) !== 0)
+        throw new BatchReceiptValidationError(message);
+}
+function scopeKey(batchId, tenantId, projectId) { return `${tenantId}\u0000${projectId}\u0000${batchId}`; }
+/** Unkeyed name used by stores written before integrity protection; only migration reads it. */
+function filePrefix(batchId, tenantId, projectId) {
+    return createHash('sha256').update(scopeKey(batchId, tenantId, projectId)).digest('hex');
+}
+function assertSameIdentity(requested, existing) {
+    const identity = (receipt) => ({ tenantId: receipt.tenantId, projectId: receipt.projectId,
+        batchId: receipt.batchId, invocationId: receipt.invocationId, runId: receipt.runId, plan: receipt.plan,
+        subjectHash: receipt.subjectHash, stateHash: receipt.stateHash, executionEnvelope: receipt.executionEnvelope,
+        questionIds: receipt.questionIds });
+    if (canonicalJson(identity(requested)) !== canonicalJson(identity(existing))) {
+        throw new BatchReceiptConflictError('Batch ID already belongs to another immutable receipt identity');
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/src/decision/batch-receipts/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/decision/batch-receipts/validate.js

@@ -0,0 +1,127 @@
+import { canonicalJson } from '../../security/artifact-trust.js';
+import { isTraceparent } from '../telemetry/context.js';
+const HASH = /^sha256:[0-9a-f]{64}$/;
+const TERMINAL = new Set(['completed', 'failed', 'execution-uncertain']);
+const TRANSITIONS = {
+    acquired: ['running', 'failed'],
+    running: ['running', 'completed', 'failed', 'execution-uncertain'],
+    completed: [], failed: [], 'execution-uncertain': [],
+};
+export class BatchReceiptValidationError extends Error {
+    constructor(message) { super(message); this.name = 'BatchReceiptValidationError'; }
+}
+export function validateBatchReceipt(receipt) {
+    const ids = new Set(receipt.questionIds);
+    if (receipt.schemaVersion !== 'decision-batch-receipt/v1'
+        || !positive(receipt.revision) || !text(receipt.tenantId) || !text(receipt.projectId)
+        || !text(receipt.batchId) || !text(receipt.invocationId) || !text(receipt.runId)
+        || !HASH.test(receipt.plan.planDigest) || !text(receipt.plan.partitionId)
+        || !HASH.test(receipt.subjectHash) || !HASH.test(receipt.stateHash)
+        || !text(receipt.executionEnvelope) || !receipt.questionIds.length || ids.size !== receipt.questionIds.length
+        || receipt.questionIds.some(id => !text(id))
+        || !Number.isSafeInteger(receipt.createdAtEpochMs) || receipt.createdAtEpochMs < 0
+        || !Number.isSafeInteger(receipt.updatedAtEpochMs) || receipt.updatedAtEpochMs < receipt.createdAtEpochMs
+        || (TERMINAL.has(receipt.status) !== (receipt.terminalAtEpochMs !== null))
+        || (receipt.terminalAtEpochMs !== null && (!Number.isSafeInteger(receipt.terminalAtEpochMs)
+            || receipt.terminalAtEpochMs < receipt.createdAtEpochMs))
+        || (receipt.traceParent !== undefined && !isTraceparent(receipt.traceParent)))
+        fail();
+    receipt.attempts.forEach((attempt, index) => validateAttempt(attempt, index + 1));
+    const answers = new Set();
+    const referencedQuestions = new Set();
+    const results = new Set();
+    for (const ref of receipt.answerReferences) {
+        if (!ids.has(ref.questionId) || !text(ref.answerId) || !text(ref.resultId) || answers.has(ref.answerId)
+            || referencedQuestions.has(ref.questionId) || results.has(ref.resultId))
+            fail();
+        answers.add(ref.answerId);
+        referencedQuestions.add(ref.questionId);
+        results.add(ref.resultId);
+    }
+    if (receipt.allocations.length && receipt.allocations.length !== receipt.questionIds.length)
+        fail();
+    const allocationIds = new Set();
+    for (const allocation of receipt.allocations) {
+        if (!ids.has(allocation.questionId) || allocationIds.has(allocation.questionId)
+            || allocation.kind !== 'estimated' || allocation.algorithm !== 'largest-remainder-weighted'
+            || allocation.algorithmVersion !== '1' || !nullableCount(allocation.inputTokens)
+            || !nullableCount(allocation.outputTokens))
+            fail();
+        allocationIds.add(allocation.questionId);
+    }
+    if (receipt.status === 'completed' && (receipt.questionIds.some(questionId => !receipt.answerReferences.some(reference => reference.questionId === questionId))
+        || !receipt.attempts.some(attempt => attempt.status === 'succeeded')))
+        fail();
+    if (receipt.allocations.length) {
+        const inputTotal = knownAttemptTotal(receipt, 'inputTokens');
+        const outputTotal = knownAttemptTotal(receipt, 'outputTokens');
+        if (inputTotal === null ? receipt.allocations.some(item => item.inputTokens !== null)
+            : receipt.allocations.some(item => item.inputTokens === null)
+                || receipt.allocations.reduce((sum, item) => sum + item.inputTokens, 0) !== inputTotal)
+            fail();
+        if (outputTotal === null ? receipt.allocations.some(item => item.outputTokens !== null)
+            : receipt.allocations.some(item => item.outputTokens === null)
+                || receipt.allocations.reduce((sum, item) => sum + item.outputTokens, 0) !== outputTotal)
+            fail();
+    }
+}
+export function validateBatchReceiptTransition(previous, next) {
+    validateBatchReceipt(previous);
+    validateBatchReceipt(next);
+    if (next.revision !== previous.revision + 1 || next.updatedAtEpochMs < previous.updatedAtEpochMs
+        || !TRANSITIONS[previous.status].includes(next.status))
+        throw new BatchReceiptValidationError('Illegal batch receipt transition');
+    const immutable = ['schemaVersion', 'tenantId', 'projectId', 'batchId', 'invocationId', 'runId', 'plan',
+        'subjectHash', 'stateHash', 'executionEnvelope', 'questionIds', 'createdAtEpochMs'];
+    for (const key of immutable)
+        if (canonicalJson(previous[key]) !== canonicalJson(next[key])) {
+            throw new BatchReceiptValidationError(`Immutable batch receipt field changed: ${key}`);
+        }
+    if (previous.traceParent !== next.traceParent)
+        throw new BatchReceiptValidationError('Immutable batch receipt field changed: traceParent');
+    if (next.attempts.length < previous.attempts.length
+        || previous.attempts.some((attempt, index) => canonicalJson(attempt) !== canonicalJson(next.attempts[index]))) {
+        throw new BatchReceiptValidationError('Batch attempt chronology is append-only');
+    }
+    if (previous.answerReferences.some(ref => !next.answerReferences.some(candidate => canonicalJson(candidate) === canonicalJson(ref)))) {
+        throw new BatchReceiptValidationError('Batch answer references are append-only');
+    }
+}
+function validateAttempt(attempt, ordinal) {
+    if (attempt.ordinal !== ordinal || !text(attempt.adapterId) || !text(attempt.adapterVersion)
+        || !text(attempt.requestedModel) || (attempt.actualModel !== null && !text(attempt.actualModel))
+        || (attempt.providerRequestId !== null && !validOpaqueRequestId(attempt.providerRequestId))
+        || !nullableTime(attempt.dispatchedAtEpochMs) || !nullableTime(attempt.completedAtEpochMs)
+        || (attempt.dispatchedAtEpochMs !== null && attempt.completedAtEpochMs !== null
+            && attempt.completedAtEpochMs < attempt.dispatchedAtEpochMs)
+        || !nullableCount(attempt.usage.inputTokens) || !nullableCount(attempt.usage.outputTokens)
+        || (attempt.status === 'not-sent' && (attempt.providerRequestId !== null || attempt.dispatchedAtEpochMs !== null))
+        || (attempt.fallbackFromAttemptOrdinal !== null && (!positive(attempt.fallbackFromAttemptOrdinal)
+            || attempt.fallbackFromAttemptOrdinal >= ordinal)))
+        fail();
+    const cost = attempt.cost;
+    if (cost.kind === 'provider-authoritative' && !count(cost.amountMicros))
+        fail();
+    if (cost.kind === 'client-derived' && (!count(cost.amountMicros) || !text(cost.priceCatalogId)
+        || !text(cost.priceCatalogVersion) || !validIso(cost.effectiveAt)))
+        fail();
+    if (cost.kind === 'bounded-unknown' && (!count(cost.upperBoundMicros) || !text(cost.boundPolicyId)
+        || !text(cost.boundPolicyVersion)))
+        fail();
+}
+/** Provider IDs are opaque internal data: bounded printable ASCII, never an authorization key. */
+export function validOpaqueRequestId(value) {
+    return value.length >= 1 && value.length <= 256 && /^[\x21-\x7e]+$/.test(value);
+}
+function validIso(value) { return !Number.isNaN(Date.parse(value)); }
+function text(value) { return typeof value === 'string' && value.length > 0; }
+function count(value) { return Number.isSafeInteger(value) && value >= 0; }
+function positive(value) { return Number.isSafeInteger(value) && value > 0; }
+function nullableCount(value) { return value === null || count(value); }
+function nullableTime(value) { return value === null || count(value); }
+function knownAttemptTotal(receipt, key) {
+    const values = receipt.attempts.map(attempt => attempt.usage[key]);
+    return values.some(value => value === null) ? null : values.reduce((sum, value) => sum + value, 0);
+}
+function fail() { throw new BatchReceiptValidationError('Invalid batch receipt'); }
+//# sourceMappingURL=validate.js.map

package/dist/src/decision/batch.js

@@ -0,0 +1,68 @@
+import { createHash } from 'node:crypto';
+import { canonicalJson } from '../security/artifact-trust.js';
+/** Stable, opaque, declaration-order-independent provider question identity. */
+export function decisionBatchQuestionId(alias) {
+    return `q_${createHash('sha256').update(alias, 'utf8').digest('hex').slice(0, 24)}`;
+}
+export function planNativeDecisionBatches(candidates, policy) {
+    if (!policy?.enabled)
+        return [];
+    const groups = new Map();
+    for (const candidate of candidates) {
+        const rule = policy.evaluations[candidate.alias];
+        const batch = candidate.capabilities.batch;
+        if (!rule?.independent || !rule.decisionSubject || !rule.egressPolicy || !rule.hostPolicy || !batch?.native
+            || !candidate.adapter.evaluateMany)
+            continue;
+        const stage = rule.stage ?? 0;
+        const key = canonicalJson({
+            decisionSubject: rule.decisionSubject,
+            state: candidate.input,
+            stage,
+            egressPolicy: rule.egressPolicy,
+            hostPolicy: rule.hostPolicy,
+            adapter: candidate.adapter.id,
+            adapterVersion: candidate.adapter.version,
+            executionEnvelope: batch.executionEnvelope,
+            target: {
+                adapter: candidate.target.adapter,
+                adapterVersion: candidate.target.adapterVersion,
+                model: candidate.target.model,
+                credentialRef: candidate.target.credentialRef ?? null,
+                subagent: candidate.target.subagent ?? null,
+                timeoutMs: candidate.target.timeoutMs,
+                retry: candidate.target.retry,
+            },
+        });
+        const values = groups.get(key) ?? [];
+        values.push(candidate);
+        groups.set(key, values);
+    }
+    return [...groups.entries()]
+        .filter(([, values]) => values.length > 1)
+        .map(([key, values]) => ({
+        groupId: `batch_${createHash('sha256').update(key, 'utf8').digest('hex').slice(0, 24)}`,
+        decisionSubject: policy.evaluations[values[0].alias].decisionSubject,
+        stage: policy.evaluations[values[0].alias].stage ?? 0,
+        // Candidate iteration follows ruleset declaration order; response order never does.
+        candidates: [...values],
+    }))
+        .sort((left, right) => left.stage - right.stage || left.groupId.localeCompare(right.groupId));
+}
+export function correlateAtomicBatch(requestedIds, returned) {
+    const requested = new Set(requestedIds);
+    if (requested.size !== requestedIds.length || returned.length !== requestedIds.length) {
+        throw new Error('batch response cardinality mismatch');
+    }
+    const correlated = new Map();
+    for (const answer of returned) {
+        if (!requested.has(answer.questionId) || correlated.has(answer.questionId)) {
+            throw new Error('batch response identity mismatch');
+        }
+        correlated.set(answer.questionId, answer.value);
+    }
+    if (correlated.size !== requested.size)
+        throw new Error('batch response identity mismatch');
+    return correlated;
+}
+//# sourceMappingURL=batch.js.map

package/dist/src/decision/calibration/index.js

@@ -0,0 +1,4 @@
+export * from './types.js';
+export * from './registry.js';
+export * from './receipts.js';
+//# sourceMappingURL=index.js.map