@aiwg/cli 2026.9.24 → 2026.10.1

package/dist/src/decision/ask.js

@@ -0,0 +1,352 @@
+import { readFile } from 'node:fs/promises';
+import { JEV_ENDPOINT, JevDecisionAdapter } from './adapters/jev.js';
+import { evaluateDecisionRuleset } from './evaluate.js';
+import { artifactPin } from './validate.js';
+import { JEV_CREDENTIAL_REF, JEV_DEFAULT_REGION, lookupJevCredential, removeJevCredentialFile, resolveJevCredentialBytes, writeJevCredentialFile, } from './jev-credentials.js';
+const CONTEXT_LIMIT_BYTES = 32 * 1024;
+const MODEL = 'jev-latest';
+const PURPOSE = 'agent-bounded-decision';
+const INPUT_SCHEMA = {
+    type: 'object',
+    properties: { message: { type: 'string', minLength: 1 } },
+    required: ['message'],
+    additionalProperties: false,
+};
+export class DecisionAskUsageError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+        this.name = 'DecisionAskUsageError';
+    }
+}
+function usageError(reason, message) {
+    throw new DecisionAskUsageError(reason, message);
+}
+function byteLength(value) {
+    return Buffer.byteLength(value, 'utf8');
+}
+function validateQuestion(question) {
+    if (!question.trim())
+        usageError('question-required', 'decision ask requires --question <q>');
+}
+export function validateDecisionAskInput(input) {
+    validateQuestion(input.question);
+    if (input.context !== undefined && byteLength(input.context) > CONTEXT_LIMIT_BYTES) {
+        usageError('context-too-large', 'decision ask context exceeds 32 KiB');
+    }
+    const threshold = input.threshold ?? 0.8;
+    if (!Number.isFinite(threshold) || threshold < 0 || threshold > 1) {
+        usageError('invalid-threshold', '--threshold must be a probability from 0 to 1');
+    }
+    const timeoutMs = input.timeoutMs ?? 15_000;
+    if (!Number.isInteger(timeoutMs) || timeoutMs <= 0)
+        usageError('invalid-timeout', '--timeout-ms must be a positive integer');
+    if (input.mode.kind === 'choices') {
+        if (input.mode.choices.length < 2 || input.mode.choices.length > 255)
+            usageError('invalid-choices', '--choices requires 2..255 ids');
+        const seen = new Set();
+        for (const { id, description } of input.mode.choices.map(parseChoice)) {
+            if (!/^[A-Za-z0-9_.-]{1,64}$/.test(id))
+                usageError('invalid-choices', 'choice ids must match [A-Za-z0-9_.-]{1,64}');
+            if (description !== undefined && (!description || description.length > 200)) {
+                usageError('invalid-choices', 'choice descriptions after = must be 1..200 characters');
+            }
+            if (seen.has(id))
+                usageError('invalid-choices', 'choice ids must not contain duplicates');
+            seen.add(id);
+        }
+    }
+    if (input.mode.kind === 'scale') {
+        const count = input.mode.high - input.mode.low + 1;
+        if (!Number.isInteger(input.mode.low) || !Number.isInteger(input.mode.high) || input.mode.low > input.mode.high || count < 2 || count > 10) {
+            usageError('invalid-scale', '--scale must be an integer range like 1-5 with at most 10 levels');
+        }
+    }
+}
+function usage(usageValue) {
+    if (!usageValue)
+        return null;
+    return { inputTokens: usageValue.inputTokens, outputTokens: usageValue.outputTokens };
+}
+function fallback(reason, latencyMs, attempt) {
+    return {
+        schema: 'aiwg-decision-ask/v1',
+        status: 'fallback',
+        answer: null,
+        confidence: null,
+        fallback: 'llm',
+        reason,
+        model: attempt?.actualModel ?? null,
+        usage: usage(attempt?.usage),
+        latencyMs,
+    };
+}
+/** A choice is `id` or `id=description`; the description tells Jev what the option means. */
+function parseChoice(entry) {
+    const separator = entry.indexOf('=');
+    if (separator < 0)
+        return { id: entry.trim() };
+    return { id: entry.slice(0, separator).trim(), description: entry.slice(separator + 1).trim() };
+}
+function scaleLevel(value, low, high) {
+    const edge = value === low ? ' (lowest)' : value === high ? ' (highest)' : '';
+    return `Level ${value} on a ${low} to ${high} scale${edge}.`;
+}
+function answerKind(mode) {
+    if (mode.kind === 'yes-no')
+        return {
+            kind: 'truth-probability',
+            trueDescription: 'Yes.',
+            falseDescription: 'No.',
+        };
+    if (mode.kind === 'choices')
+        return {
+            kind: 'choice',
+            options: mode.choices.map(parseChoice).map(({ id, description }) => ({ id, description: description ?? id })),
+        };
+    return {
+        kind: 'ordinal-score',
+        levels: Array.from({ length: mode.high - mode.low + 1 }, (_, index) => scaleLevel(mode.low + index, mode.low, mode.high)),
+    };
+}
+function definition(input) {
+    return {
+        apiVersion: 'decision.aiwg.io/v1alpha2',
+        kind: 'DecisionDefinition',
+        metadata: { id: 'aiwg.ask.answer', version: '1.0.0', description: 'Bounded advisory ask decision' },
+        spec: {
+            purpose: PURPOSE,
+            inputSchema: INPUT_SCHEMA,
+            question: input.question,
+            answer: answerKind(input.mode),
+            requiredCapabilities: [input.mode.kind === 'yes-no' ? 'truth-probability' : input.mode.kind === 'choices' ? 'choice' : 'ordinal-score'],
+        },
+    };
+}
+function ruleset(definitionValue) {
+    return {
+        apiVersion: 'decision.aiwg.io/v1alpha2',
+        kind: 'DecisionRuleset',
+        metadata: { id: 'aiwg.ask.ruleset', version: '1.0.0', description: 'Bounded advisory ask ruleset' },
+        spec: {
+            purpose: PURPOSE,
+            inputSchema: INPUT_SCHEMA,
+            evaluations: [{ alias: 'answer', decision: artifactPin(definitionValue), inputPointer: '' }],
+            rules: [{
+                    id: 'answered',
+                    priority: 1,
+                    when: { op: 'exists', left: { source: 'decision', alias: 'answer', pointer: '/value' } },
+                    outcome: 'answered',
+                }],
+            composition: 'first-match',
+            conflict: 'review',
+            defaultOutcome: 'fallback',
+            failureOutcome: 'fallback',
+            outputSchema: { enum: ['answered', 'fallback'] },
+        },
+    };
+}
+function binding(rulesetValue, primitive, timeoutMs) {
+    const target = {
+        adapter: 'jev',
+        adapterVersion: '1.0.0',
+        model: MODEL,
+        requiredCapabilities: [primitive],
+        acceptance: { mode: 'typed-value' },
+        timeoutMs,
+        retry: { maxRetries: 0, initialDelayMs: 250, maxDelayMs: 2_000 },
+        credentialRef: JEV_CREDENTIAL_REF,
+    };
+    return {
+        apiVersion: 'decision.aiwg.io/v1alpha2',
+        kind: 'DecisionBinding',
+        metadata: { id: 'aiwg.ask.binding', version: '1.0.0', description: 'Bounded advisory ask Jev binding' },
+        spec: {
+            ruleset: artifactPin(rulesetValue),
+            totalTimeoutMs: timeoutMs,
+            maxAttempts: 1,
+            concurrency: 1,
+            evaluations: { answer: { targets: [target], fallbackOn: [] } },
+        },
+    };
+}
+function projectionPolicy(region, endpoint) {
+    const origin = new URL(endpoint ?? JEV_ENDPOINT).origin;
+    return {
+        version: '1.0.0',
+        provider: 'jev',
+        model: MODEL,
+        origin,
+        region,
+        purpose: PURPOSE,
+        allowIncompleteContext: false,
+        fields: [{
+                pointer: '/message',
+                output: 'message',
+                source: 'operator',
+                subject: 'aiwg-decision-ask',
+                trust: 'untrusted',
+                sensitivity: 'internal',
+                purpose: PURPOSE,
+                retentionClass: 'ephemeral',
+                accessScopes: ['decision-runtime'],
+                exportPolicy: 'sanitized',
+                deletionPolicy: 'erase',
+                backupPolicy: 'not-persisted',
+                allowedProviders: ['jev'],
+                allowedModels: [MODEL],
+                allowedOrigins: [origin],
+                allowedRegions: [region],
+            }],
+    };
+}
+function contextMessage(input) {
+    return input.context === undefined || input.context === ''
+        ? input.question
+        : `${input.question}\n\nContext:\n${input.context}`;
+}
+function confidenceFor(mode, evaluation) {
+    const uncertainty = evaluation.spec.uncertainty;
+    const value = evaluation.spec.value;
+    if (mode.kind === 'yes-no' && typeof value === 'number')
+        return Math.max(value, 1 - value);
+    if (uncertainty?.distribution && mode.kind === 'choices' && typeof value === 'string')
+        return uncertainty.distribution[value] ?? uncertainty.confidence;
+    if (uncertainty?.distribution && mode.kind === 'scale')
+        return Math.max(...Object.values(uncertainty.distribution));
+    return uncertainty?.confidence ?? null;
+}
+function mostLikelyIndex(distribution) {
+    if (!distribution)
+        return null;
+    let best = null;
+    for (const [index, probability] of Object.entries(distribution)) {
+        if (best === null || probability > (distribution[String(best)] ?? -1))
+            best = Number(index);
+    }
+    return best;
+}
+function publicAnswer(mode, value, distribution) {
+    if (mode.kind === 'yes-no') {
+        const probability = typeof value === 'number' ? value : null;
+        return probability === null ? { answer: null } : { answer: probability >= 0.5, probability };
+    }
+    if (mode.kind === 'scale') {
+        // Jev returns the distribution-weighted mean index; report the most likely level instead.
+        const index = mostLikelyIndex(distribution) ?? (typeof value === 'number' ? Math.round(value) : null);
+        return index === null ? { answer: null } : { answer: mode.low + index };
+    }
+    return typeof value === 'string' ? { answer: value } : { answer: null };
+}
+export async function askDecision(input, options = {}) {
+    validateDecisionAskInput(input);
+    const started = options.now?.() ?? Date.now();
+    let credential;
+    try {
+        credential = await lookupJevCredential(options);
+    }
+    catch {
+        return fallback('not-configured', 0);
+    }
+    if (!credential?.enabled || !credential.token)
+        return fallback('not-configured', 0);
+    const timeoutMs = input.timeoutMs ?? 15_000;
+    const def = definition(input);
+    const rules = ruleset(def);
+    const bind = binding(rules, def.spec.answer.kind, timeoutMs);
+    const adapter = options.adapter ?? options.createAdapter?.({ region: credential.region, endpoint: credential.endpoint })
+        ?? new JevDecisionAdapter({ region: credential.region, ...(credential.endpoint ? {
+                endpoint: credential.endpoint,
+                allowedOrigins: [new URL(credential.endpoint).origin],
+            } : {}) });
+    let result;
+    try {
+        result = await (options.evaluate ?? evaluateDecisionRuleset)({
+            ruleset: rules,
+            binding: bind,
+            definitions: { [def.metadata.id]: def },
+            input: { message: contextMessage(input) },
+            runId: options.runId ?? 'aiwg-decision-ask',
+            invocationId: options.invocationId ?? `ask-${Date.now()}`,
+            adapters: { jev: adapter },
+            resolveCredential: options.resolveCredential ?? (logicalRef => resolveJevCredentialBytes(logicalRef, options)),
+            projection: { resolve: () => projectionPolicy(credential.region, credential.endpoint) },
+        });
+    }
+    catch {
+        return fallback('jev-error', Math.max(0, (options.now?.() ?? Date.now()) - started));
+    }
+    const latencyMs = Math.max(0, (options.now?.() ?? Date.now()) - started);
+    const evaluation = result.spec.evaluations.answer;
+    const attempt = evaluation?.spec.attempts.at(-1);
+    if (!evaluation || evaluation.spec.status !== 'success')
+        return fallback(evaluation?.spec.reason ?? result.spec.reason, latencyMs, attempt);
+    const confidence = confidenceFor(input.mode, evaluation);
+    const threshold = input.threshold ?? 0.8;
+    if (confidence === null || confidence < threshold)
+        return fallback('low-confidence', latencyMs, attempt);
+    const answer = publicAnswer(input.mode, evaluation.spec.value, evaluation.spec.uncertainty?.distribution);
+    return {
+        schema: 'aiwg-decision-ask/v1',
+        status: 'answered',
+        answer: answer.answer,
+        confidence,
+        ...(answer.probability === undefined ? {} : { probability: answer.probability }),
+        fallback: null,
+        reason: 'none',
+        model: attempt?.actualModel ?? null,
+        usage: usage(attempt?.usage),
+        latencyMs,
+    };
+}
+export async function readDecisionContextFile(filePath) {
+    const content = await readFile(filePath, 'utf8');
+    if (byteLength(content) > CONTEXT_LIMIT_BYTES)
+        usageError('context-too-large', 'decision ask context exceeds 32 KiB');
+    return content;
+}
+export async function setupJev(input = {}, options = {}) {
+    const region = input.region?.trim() || JEV_DEFAULT_REGION;
+    if (input.remove) {
+        await removeJevCredentialFile(options);
+        return {
+            schema: 'aiwg-decision-jev-setup/v1',
+            configured: false,
+            credentialSource: 'file',
+            region,
+            next: ['Run aiwg decision setup jev --token-stdin to configure Jev again.'],
+        };
+    }
+    const environment = options.env ?? process.env;
+    const envToken = environment.JEV_API_KEY?.trim() || environment.AIWG_DECISION_JEV_API_KEY?.trim();
+    const token = input.token?.trim() || envToken;
+    if (!token)
+        usageError('token-required', 'Provide --token-stdin or set JEV_API_KEY or AIWG_DECISION_JEV_API_KEY.');
+    await writeJevCredentialFile({
+        token,
+        region,
+        ...(input.endpoint?.trim() ? { endpoint: input.endpoint.trim() } : {}),
+        enabled: true,
+    }, options);
+    const result = {
+        schema: 'aiwg-decision-jev-setup/v1',
+        configured: true,
+        credentialSource: input.token?.trim() ? 'file' : 'env',
+        region,
+        next: ['Run aiwg decision ask --question "<q>" --yes-no --json.'],
+    };
+    if (input.verify) {
+        const verified = await askDecision({
+            question: 'Is this Jev decision setup verification request well formed?',
+            mode: { kind: 'yes-no' },
+            threshold: 0,
+            timeoutMs: 15_000,
+        }, options);
+        result.verified = verified.status === 'answered';
+        result.model = verified.model;
+        result.usage = verified.usage;
+    }
+    return result;
+}
+//# sourceMappingURL=ask.js.map

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

@@ -88,6 +88,11 @@ export class CalibrationRegistry {
         const rollback = history.find(event => event.revision === eligibility.rollbackTarget.aliasRevision);
         if (!rollback || rollback.actualIdentityDigest !== eligibility.rollbackTarget.identityDigest)
             throw new CalibrationRegistryError('rollback target no longer matches immutable alias history');
+        const current = history.at(-1);
+        if (current !== rollback || current.kind === 'retired')
+            throw new CalibrationRegistryError('alias no longer holds the champion this promotion was approved to replace');
+        if (history.some(event => event.promotionEligibilityId === eligibility.id))
+            throw new CalibrationRegistryError(`promotion eligibility '${eligibility.id}' was already used`);
         const event = immutable({ revision: history.length + 1, alias: eligibility.alias,
             actualIdentityDigest: eligibility.candidateIdentityDigest, actualModel: eligibility.candidateActualModel, recordedAt: new Date(validDate(at)).toISOString(),
             kind: 'promoted', promotionEligibilityId: eligibility.id });
@@ -172,6 +177,7 @@ export class CalibrationRegistry {
     aliasHistory(alias) { return structuredClone(this.aliases.get(alias) ?? []); }
     driftEvents(alias) { return structuredClone(alias ? this.drift.filter(event => event.alias === alias) : this.drift); }
     promotionHistory() { return structuredClone([...this.eligibility.values()]); }
+    promotionEligibility(id) { const record = this.eligibility.get(id); return record ? structuredClone(record) : null; }
     artifactHistory() { return structuredClone([...this.artifacts.values()]); }
     compatibilityHistory() { return structuredClone(this.relations); }
 }
@@ -190,6 +196,9 @@ function calibrationUsability(artifact, at) {
         reasons.push('calibration-bound-exceeded');
     if (artifact.metrics.selectiveRisk > artifact.profile.maximumSelectiveRisk)
         reasons.push('selective-risk-bound-exceeded');
+    // An artifact is unusable before it takes effect: a back-dated request cannot borrow a later calibration.
+    if (validDate(at) < validDate(artifact.effectiveAt))
+        reasons.push('calibration-not-yet-effective');
     if (validDate(at) >= validDate(artifact.effectiveAt) + artifact.profile.expiresAfterDays * 86_400_000)
         reasons.push('calibration-expired');
     return reasons;

package/dist/src/decision/compose.js

@@ -1,7 +1,16 @@
 import { evaluatePredicate } from './predicates.js';
 import { validateAgainstSchema } from './validate.js';
 export function composeRuleset(ruleset, input, evaluations) {
-    const failed = Object.values(evaluations).some(result => result.spec.status !== 'success');
+    const referencedAliases = referencedDecisionAliases(ruleset);
+    const requiredEvaluations = new Map(ruleset.spec.evaluations
+        .filter(evaluation => referencedAliases.includes(evaluation.alias))
+        .map(evaluation => [evaluation.alias, evaluation]));
+    const suppliedFailed = Object.values(evaluations).some(result => !acceptedEvaluation(result));
+    const requiredFailed = [...requiredEvaluations].some(([alias, evaluation]) => {
+        const result = evaluations[alias];
+        return !result || result.spec.alias !== alias || !acceptedEvaluation(result) || !samePin(result.spec.decision, evaluation.decision);
+    });
+    const failed = suppliedFailed || requiredFailed;
     if (failed) {
         validateAgainstSchema(ruleset.spec.outputSchema, ruleset.spec.failureOutcome, 'failureOutcome');
         return {
@@ -18,31 +27,81 @@ export function composeRuleset(ruleset, input, evaluations) {
         validateAgainstSchema(ruleset.spec.outputSchema, ruleset.spec.defaultOutcome, 'defaultOutcome');
         return { status: 'defaulted', reason: 'no-match', outcome: structuredClone(ruleset.spec.defaultOutcome), matchedRules: [] };
     }
-    if (ruleset.spec.composition === 'collect') {
-        const outcome = matches.map(rule => structuredClone(rule.outcome));
+    if (ruleset.spec.composition === 'collect' || ruleset.spec.composition.startsWith('collect-')) {
+        const collected = matches.map(rule => structuredClone(rule.outcome));
+        const outcome = ruleset.spec.composition === 'collect' ? collected : aggregateCollect(collected, ruleset.spec.composition);
         validateAgainstSchema(ruleset.spec.outputSchema, outcome, 'collected outcome');
         return { status: 'completed', reason: 'none', outcome, matchedRules: matches.map(rule => rule.id) };
     }
+    if (ruleset.spec.composition === 'unique' && matches.length > 1)
+        return conflictResult(ruleset, matches);
+    if (ruleset.spec.composition === 'any') {
+        const first = sortJson(matches[0].outcome);
+        if (matches.some(rule => JSON.stringify(sortJson(rule.outcome)) !== JSON.stringify(first)))
+            return conflictResult(ruleset, matches);
+        const outcome = structuredClone(matches[0].outcome);
+        validateAgainstSchema(ruleset.spec.outputSchema, outcome, 'matched outcome');
+        return { status: 'completed', reason: 'none', outcome, matchedRules: matches.map(rule => rule.id) };
+    }
     const top = matches.filter(rule => rule.priority === matches[0].priority);
     const unique = new Map();
     for (const rule of top)
         unique.set(JSON.stringify(sortJson(rule.outcome)), rule.outcome);
-    if (unique.size > 1) {
-        if (ruleset.spec.conflict === 'review') {
-            validateAgainstSchema(ruleset.spec.outputSchema, ruleset.spec.failureOutcome, 'failureOutcome');
-            return {
-                status: 'review',
-                reason: 'conflicting-outcomes',
-                outcome: structuredClone(ruleset.spec.failureOutcome),
-                matchedRules: top.map(rule => rule.id),
-            };
-        }
-        return { status: 'error', reason: 'conflicting-outcomes', matchedRules: top.map(rule => rule.id) };
-    }
+    if (unique.size > 1)
+        return conflictResult(ruleset, top);
     const outcome = structuredClone(top[0].outcome);
     validateAgainstSchema(ruleset.spec.outputSchema, outcome, 'matched outcome');
     return { status: 'completed', reason: 'none', outcome, matchedRules: top.map(rule => rule.id) };
 }
+function acceptedEvaluation(result) {
+    return result.spec.status === 'success'
+        && (result.spec.acceptance === undefined || result.spec.acceptance.disposition === 'act');
+}
+function samePin(left, right) {
+    return left.id === right.id && left.version === right.version && left.digest === right.digest;
+}
+function referencedDecisionAliases(ruleset) {
+    const aliases = new Set();
+    const visit = (predicate) => {
+        if ('all' in predicate)
+            predicate.all.forEach(visit);
+        else if ('any' in predicate)
+            predicate.any.forEach(visit);
+        else if ('not' in predicate)
+            visit(predicate.not);
+        else if (predicate.left.source === 'decision' && predicate.left.alias)
+            aliases.add(predicate.left.alias);
+    };
+    ruleset.spec.rules.forEach(rule => visit(rule.when));
+    return [...aliases].sort();
+}
+function conflictResult(ruleset, matches) {
+    if (ruleset.spec.conflict === 'review') {
+        validateAgainstSchema(ruleset.spec.outputSchema, ruleset.spec.failureOutcome, 'failureOutcome');
+        return {
+            status: 'review',
+            reason: 'conflicting-outcomes',
+            outcome: structuredClone(ruleset.spec.failureOutcome),
+            matchedRules: matches.map(rule => rule.id),
+        };
+    }
+    return { status: 'error', reason: 'conflicting-outcomes', matchedRules: matches.map(rule => rule.id) };
+}
+function aggregateCollect(values, composition) {
+    if (composition === 'collect-count')
+        return values.length;
+    if (!values.every(value => typeof value === 'number' && Number.isFinite(value))) {
+        throw new Error(`${composition} requires finite numeric outcomes`);
+    }
+    const numbers = values;
+    if (composition === 'collect-sum')
+        return numbers.reduce((sum, value) => sum + value, 0);
+    if (composition === 'collect-min')
+        return Math.min(...numbers);
+    if (composition === 'collect-max')
+        return Math.max(...numbers);
+    return values;
+}
 function sortJson(value) {
     if (Array.isArray(value))
         return value.map(sortJson);