@aiwg/cli 2026.10.1 → 2026.10.3

package/dist/src/models/provider-policy.js

@@ -3,14 +3,24 @@
  * @implements #1802
  * @implements #1805
  */
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { z } from 'zod';
 import { createRequire } from 'node:module';
+import { compileWorkerVersionPattern, workerVersionRangeMismatch } from './worker-installation.mjs';
+import { normalizeProviderDefinitionId } from '../providers/provider-definitions.js';
+import { qualificationDigest } from './qualification-digest.mjs';
 const require = createRequire(import.meta.url);
 function requireModelResource(filename) {
     const candidates = [
         `./${filename}`,
         `../../agentic/code/providers/${filename}`,
         `../../../agentic/code/providers/${filename}`,
+        `../../schemas/models/${filename}`,
+        `../../../schemas/models/${filename}`,
     ];
     for (const candidate of candidates) {
         try {
@@ -32,6 +42,27 @@ const ProviderSchema = z.enum([
 const OutcomeSchema = z.enum([
     'native', 'compiled', 'inherited', 'global-only', 'informational', 'unsupported',
 ]);
+// Use the bundled owner for nested controls, including forward-compatible optional
+// health records. Zod must validate and preserve them, never silently strip them.
+const capabilitySchema = requireModelResource('provider-model-capabilities.v1.schema.json');
+const capabilityAjv = addFormats(new Ajv2020({ strict: false, allErrors: true }));
+capabilityAjv.addSchema(capabilitySchema);
+const validateAdapter = capabilityAjv.compile({ $ref: `${capabilitySchema.$id}#/$defs/workerAdapter` });
+export const WorkerAdapterSchema = z.custom().superRefine((value, context) => {
+    if (!validateAdapter(value)) {
+        context.addIssue({ code: 'custom', message: `Invalid worker adapter: ${capabilityAjv.errorsText(validateAdapter.errors)}` });
+        return;
+    }
+    try {
+        const invocation = value.invocation;
+        if (invocation.kind === 'process' && invocation.versionPattern !== undefined)
+            compileWorkerVersionPattern(invocation.versionPattern);
+    }
+    catch (error) {
+        context.addIssue({ code: 'custom', path: ['invocation', 'versionPattern'],
+            message: `Invalid worker adapter: ${error instanceof Error ? error.message : String(error)}` });
+    }
+});
 const CapabilityEntrySchema = z.object({
     agent: OutcomeSchema,
     skill: OutcomeSchema,
@@ -45,12 +76,29 @@ const CapabilityEntrySchema = z.object({
     verification: z.string().min(1),
     sourceUrl: z.string().url(),
     verifiedAt: z.string().date(),
-});
+    workerAdapter: WorkerAdapterSchema.optional(),
+    // Descriptive health coverage is not an installed executable registration.
+    workerHealthAdapter: WorkerAdapterSchema.optional(),
+    workerHealthCoverage: z.object({
+        scope: z.literal('out'), coverage: z.literal('unobserved'), handshake: z.literal('unobserved'),
+        evidenceGrades: z.array(z.enum(['H', 'R', 'D'])).max(3),
+        qualificationOwner: z.string().regex(/^B-OG-[0-9]{2}$/),
+        provenance: z.array(z.string().min(1).max(4096)).min(1).max(16), reason: z.string().min(1).max(4096),
+    }).strict().optional(),
+}).strict();
 const CapabilityRegistrySchema = z.object({
+    $schema: z.enum([
+        '../../../schemas/models/provider-model-capabilities.v1.schema.json',
+        'https://aiwg.io/schemas/models/provider-model-capabilities.v1.schema.json',
+    ]).optional(),
     version: z.literal('1.0.0'),
     verifiedAt: z.string().date(),
     providers: z.record(ProviderSchema, CapabilityEntrySchema),
-});
+    workerAdapters: z.record(z.string().regex(/^[a-z][a-z0-9-]{0,62}$/), WorkerAdapterSchema)
+        .refine(value => Object.keys(value).length <= 128, 'At most 128 worker adapters').optional(),
+    workerHealthAdapters: z.record(z.string().regex(/^[a-z][a-z0-9-]{0,62}$/), WorkerAdapterSchema)
+        .refine(value => Object.keys(value).length <= 128, 'At most 128 worker health descriptors').optional(),
+}).strict();
 const CatalogModelSchema = z.object({
     id: z.string().min(1),
     status: z.enum(['active', 'deprecated', 'unverified']),
@@ -66,22 +114,228 @@ const CatalogProviderSchema = z.object({
     sourceUrl: z.string().url(),
     verifiedAt: z.string().date(),
 });
+let catalogValidators;
+function getCatalogValidators() {
+    if (!catalogValidators) {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const file = [resolve(here, '../../schemas/models/model-catalog.v1.schema.json'), resolve(here, '../../../schemas/models/model-catalog.v1.schema.json')].find(existsSync);
+        if (!file)
+            throw new Error('Model catalog schema is unavailable');
+        const schema = JSON.parse(readFileSync(file, 'utf8'));
+        const ajv = addFormats(new Ajv2020({ strict: false, allErrors: true }));
+        ajv.addSchema(schema);
+        catalogValidators = { catalog: ajv.getSchema(schema.$id), observation: ajv.compile({ $ref: `${schema.$id}#/$defs/workerObservation` }), discovery: ajv.compile({ $ref: `${schema.$id}#/properties/discovery` }) };
+    }
+    return catalogValidators;
+}
+export function validateWorkerModelObservation(input) {
+    const validate = getCatalogValidators().observation;
+    return validate(input) ? [] : (validate.errors ?? []).map(error => `${error.instancePath}: ${error.message}`);
+}
+const WorkerObservationSchema = z.custom(input => validateWorkerModelObservation(input).length === 0);
+const DiscoveredWorkerModelSchema = z.object({
+    id: z.string().min(1), apiModelId: z.string().optional(), llmProvider: z.string().optional(),
+    hidden: z.boolean().optional(), reasoningEfforts: z.array(z.string()).optional(), worker: WorkerObservationSchema.optional(),
+}).passthrough().superRefine((model, context) => {
+    if (!model.worker)
+        return;
+    if (model.hidden !== undefined && model.worker.visibility !== (model.hidden ? 'hidden' : 'listed'))
+        context.addIssue({ code: 'custom', path: ['worker', 'visibility'], message: 'Conflicting visibility evidence' });
+    const efforts = model.reasoningEfforts ?? [];
+    const observed = model.worker.efforts.map(e => e.id);
+    if (efforts.length !== observed.length || new Set(observed).size !== observed.length || efforts.some(e => !observed.includes(e)))
+        context.addIssue({ code: 'custom', path: ['worker', 'efforts'], message: 'Conflicting effort evidence' });
+});
+const ProviderDiscoverySchema = z.object({
+    provider: z.string(), source: z.enum(['native', 'cache', 'remote', 'static']), observedAt: z.string().datetime({ offset: true }),
+    runtimeVersion: z.string().optional(), accountScope: z.enum(['local-account', 'local-runtime', 'public-feed', 'static']),
+    accountBinding: z.string().min(1).optional(), models: z.array(DiscoveredWorkerModelSchema),
+}).passthrough();
+const DiscoverySchema = z.object({
+    source: z.enum(['native', 'cache', 'remote', 'static']), upstreamSource: z.enum(['native', 'remote', 'static']).optional(),
+    fetchedAt: z.string().datetime({ offset: true }), remoteUrl: z.string().url().optional(), remoteError: z.string().optional(),
+    inventorySignature: z.string().optional(), providers: z.record(z.string(), ProviderDiscoverySchema),
+    instances: z.record(z.string(), ProviderDiscoverySchema).optional(),
+}).strict();
+/** Optional enrichment is checked without tightening legacy catalog rows. */
+export function validateWorkerCatalogDiscovery(input) {
+    if (input === undefined)
+        return [];
+    const validate = getCatalogValidators().discovery;
+    if (!validate(input))
+        return (validate.errors ?? []).map(error => `${error.instancePath}: ${error.message}`);
+    const parsed = DiscoverySchema.safeParse(input);
+    return parsed.success ? [] : parsed.error.issues.map(issue => `${issue.path.join('/')}: ${issue.message}`);
+}
 const CatalogSchema = z.object({
     version: z.literal('1.0.0'),
+    $schema: z.literal('../../../schemas/models/model-catalog.v1.schema.json').optional(),
+    discovery: DiscoverySchema.optional(),
     refreshedAt: z.string().date(),
     staleAfterDays: z.number().int().positive(),
     providers: z.record(ProviderSchema, CatalogProviderSchema),
-});
+}).strict();
 const PolicySchema = z.object({
     role: z.enum(['reasoning', 'coding', 'efficiency']),
     tier: z.enum(['economy', 'standard', 'premium']),
     effort: z.enum(['minimal', 'low', 'medium', 'high', 'xhigh']).optional(),
     override: z.string().min(1).optional(),
 }).strict();
+const uniqueStrings = z.array(z.string().min(1)).refine(values => new Set(values).size === values.length, 'Duplicate entries');
+const WorkerDataPolicySchema = z.object({
+    allowedProcessing: z.array(z.enum(['local', 'remote'])).refine(values => new Set(values).size === values.length).optional(),
+    allowProductImprovement: z.boolean().optional(),
+    allowUnknown: z.boolean().optional(),
+    maxRetentionDays: z.number().int().nonnegative().optional(),
+}).strict();
+const WorkerRoleSchema = z.object({
+    groups: uniqueStrings.refine(values => values.length > 0),
+    tier: z.enum(['economy', 'standard', 'premium', 'max-quality']),
+    initialEffort: z.string().min(1).nullable(),
+    effortLadder: uniqueStrings,
+    escalateAfter: z.number().int().positive().optional(),
+    maxEscalations: z.number().int().nonnegative().optional(),
+    deescalateAfter: z.number().int().positive().optional(),
+    allowNotApplicableEffort: z.boolean().optional(),
+}).strict();
+export const WorkerSelectionPolicySchema = z.object({
+    roleGuidance: z.record(z.string().regex(/^[a-z][a-z0-9-]{0,62}$/), WorkerRoleSchema).optional(),
+    guards: z.object({
+        deniedEfforts: uniqueStrings.optional(),
+        deniedModels: uniqueStrings.optional(),
+        denySelfDelegation: z.boolean().optional(),
+        requireExactModel: z.boolean().optional(),
+        allowedVisibility: z.array(z.enum(['listed', 'hidden'])).refine(v => new Set(v).size === v.length).optional(),
+        allowedLifecycle: z.array(z.enum(['active', 'deprecated'])).refine(v => new Set(v).size === v.length).optional(),
+        minimumIdentityEvidence: z.enum(['runtime-configured', 'backend-attested']).optional(),
+    }).strict().optional(),
+    dataPolicy: WorkerDataPolicySchema.optional(),
+    dataClasses: z.record(z.string().regex(/^[a-z][a-z0-9-]{0,62}$/), WorkerDataPolicySchema).optional(),
+    freshness: z.object({
+        warnHours: z.number().int().positive().optional(),
+        blockHours: z.number().int().positive().optional(),
+        policyDays: z.number().int().positive().optional(),
+    }).strict().optional(),
+    taskClasses: z.record(z.string().regex(/^[a-z][a-z0-9-]{0,62}$/), z.string().min(1)).optional(),
+}).strict().superRefine((policy, context) => {
+    for (const [role, guidance] of Object.entries(policy.roleGuidance ?? {})) {
+        if (!['efficiency', 'coding', 'reasoning'].includes(role))
+            context.addIssue({ code: 'custom', path: ['roleGuidance', role], message: 'Unknown worker role' });
+        if (guidance.effortLadder.includes('none') || (guidance.initialEffort === 'none' ? guidance.effortLadder.length !== 0 : guidance.initialEffort !== null && !guidance.effortLadder.includes(guidance.initialEffort))) {
+            context.addIssue({ code: 'custom', path: ['roleGuidance', role], message: 'Initial effort must belong to the ladder; real none requires an empty ladder' });
+        }
+        if (guidance.initialEffort === null && (guidance.allowNotApplicableEffort !== true || guidance.effortLadder.length !== 0)) {
+            context.addIssue({ code: 'custom', path: ['roleGuidance', role], message: 'Null effort requires an empty ladder and allowNotApplicableEffort=true' });
+        }
+    }
+    for (const key of policy.guards?.deniedModels ?? []) {
+        if (!isCanonicalWorkerModelKey(key))
+            context.addIssue({ code: 'custom', path: ['guards', 'deniedModels'], message: 'Noncanonical inference model key' });
+    }
+    if (policy.freshness?.warnHours !== undefined && policy.freshness.blockHours !== undefined && policy.freshness.warnHours > policy.freshness.blockHours) {
+        context.addIssue({ code: 'custom', path: ['freshness'], message: 'warnHours must not exceed blockHours' });
+    }
+    for (const role of Object.values(policy.taskClasses ?? {})) {
+        if (!['coding', 'reasoning', 'efficiency'].includes(role))
+            context.addIssue({ code: 'custom', path: ['taskClasses'], message: 'Unknown worker role' });
+    }
+});
+/** Canonical RFC3986 identity; installation and account never enter the key. */
+export function workerModelKey(inferenceProvider, apiModelId) {
+    if (!/^[a-z][a-z0-9-]{0,62}$/.test(inferenceProvider) || !apiModelId)
+        throw new Error('OG_CONFIG_REFERENCE: invalid inference model identity');
+    return `${inferenceProvider}/${encodeURIComponent(apiModelId).replace(/[!'()*]/g, c => `%${c.charCodeAt(0).toString(16).toUpperCase()}`)}`;
+}
+export function isCanonicalWorkerModelKey(key) {
+    const slash = key.indexOf('/');
+    try {
+        return slash > 0 && workerModelKey(key.slice(0, slash), decodeURIComponent(key.slice(slash + 1))) === key;
+    }
+    catch {
+        return false;
+    }
+}
+export const DEFAULT_WORKER_SELECTION = {
+    guards: { deniedEfforts: ['ultra'], deniedModels: [], denySelfDelegation: true, requireExactModel: true, allowedVisibility: ['listed'], allowedLifecycle: ['active'], minimumIdentityEvidence: 'runtime-configured' },
+    dataPolicy: { allowedProcessing: ['local', 'remote'], allowProductImprovement: false, allowUnknown: false },
+    freshness: { warnHours: 24, blockHours: 168, policyDays: 30 },
+    taskClasses: { inventory: 'efficiency', implementation: 'coding', architecture: 'reasoning', review: 'reasoning' },
+};
+/** Merge leaves, preserving pre-merge explicit origins and attempted relaxations. */
+export function mergeWorkerSelection(layers) {
+    const policy = {};
+    const origins = {};
+    const diagnostics = [];
+    const visit = (target, input, parts, layer) => {
+        for (const [key, value] of Object.entries(input)) {
+            const path = [...parts, key];
+            const pointer = `/defaults/workerSelection/${path.map(p => p.replace(/~/g, '~0').replace(/\//g, '~1')).join('/')}`;
+            if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+                target[key] ??= {};
+                visit(target[key], value, path, layer);
+                continue;
+            }
+            const origin = { source: layer.source, authority: layer.authority, digest: layer.digest, pointer, contribution: structuredClone(value) };
+            const prior = origins[pointer] ?? [];
+            const explicit = prior.filter(o => o.authority !== 'builtin');
+            let effective = structuredClone(value);
+            let relaxation = false;
+            if (layer.authority !== 'builtin' && explicit.length > 0) {
+                const previous = target[key];
+                if (['deniedEfforts', 'deniedModels'].includes(key))
+                    effective = [...new Set([...previous, ...value])];
+                else if (['allowedVisibility', 'allowedLifecycle', 'allowedProcessing'].includes(key)) {
+                    relaxation = value.some((v) => !previous.includes(v));
+                    effective = previous.filter((v) => value.includes(v));
+                }
+                else if (['denySelfDelegation', 'requireExactModel'].includes(key)) {
+                    relaxation = previous === true && value === false;
+                    effective = previous || value;
+                }
+                else if (['allowUnknown', 'allowProductImprovement'].includes(key)) {
+                    relaxation = previous === false && value === true;
+                    effective = previous && value;
+                }
+                else if (['maxRetentionDays', 'warnHours', 'blockHours', 'policyDays'].includes(key)) {
+                    relaxation = value > previous;
+                    effective = Math.min(previous, value);
+                }
+                else if (key === 'minimumIdentityEvidence') {
+                    relaxation = previous === 'backend-attested' && value !== previous;
+                    effective = previous === 'backend-attested' ? previous : value;
+                }
+            }
+            if (relaxation)
+                diagnostics.push({ code: 'OG_POLICY_RELAXATION', pointer, message: 'Explicit restriction cannot relax an inherited restriction', origins: [...explicit, origin] });
+            target[key] = effective;
+            origins[pointer] = [...prior, origin];
+        }
+    };
+    for (const layer of layers)
+        if (layer.policy)
+            visit(policy, layer.policy, [], layer);
+    const validation = WorkerSelectionPolicySchema.safeParse(policy);
+    if (!validation.success)
+        for (const issue of validation.error.issues)
+            diagnostics.push({ code: 'OG_CONFIG_REFERENCE', pointer: `/defaults/workerSelection/${issue.path.join('/')}`, message: issue.message });
+    // Data classes are applied as further restrictions to the base path.
+    for (const dataClass of Object.values(policy.dataClasses ?? {})) {
+        const base = policy.dataPolicy ?? {};
+        if (dataClass.allowedProcessing)
+            dataClass.allowedProcessing = dataClass.allowedProcessing.filter(p => !base.allowedProcessing || base.allowedProcessing.includes(p));
+        for (const key of ['allowUnknown', 'allowProductImprovement'])
+            if (base[key] === false)
+                dataClass[key] = false;
+        if (base.maxRetentionDays !== undefined)
+            dataClass.maxRetentionDays = Math.min(dataClass.maxRetentionDays ?? base.maxRetentionDays, base.maxRetentionDays);
+    }
+    return { policy, origins, diagnostics };
+}
 const UserProjectModelConfigSchema = z.object({
     defaults: z.object({
         tier: z.enum(['economy', 'standard', 'premium', 'max-quality']).optional(),
         provider: ProviderSchema.optional(),
+        workerSelection: WorkerSelectionPolicySchema.optional(),
     }).strict().optional(),
     agentOverrides: z.record(z.string(), z.object({
         'model-tier': z.enum(['economy', 'standard', 'premium', 'max-quality']).optional(),
@@ -103,18 +357,239 @@ let registryCache = null;
 let catalogCache = null;
 export function loadProviderModelCapabilities() {
     if (!registryCache) {
-        registryCache = CapabilityRegistrySchema.parse(capabilityData);
-        const expected = new Set(ProviderSchema.options);
-        const actual = new Set(Object.keys(registryCache.providers));
-        if (actual.size !== expected.size || [...expected].some(id => !actual.has(id))) {
-            throw new Error('Provider model capability registry must cover all registered providers');
-        }
+        registryCache = parseProviderModelCapabilities(capabilityData);
     }
     return registryCache;
 }
+export function parseProviderModelCapabilities(input) {
+    const registry = CapabilityRegistrySchema.parse(input);
+    const expected = new Set(ProviderSchema.options);
+    const actual = new Set(Object.keys(registry.providers));
+    if (actual.size !== expected.size || [...expected].some(id => !actual.has(id))) {
+        throw new Error('Provider model capability registry must cover all registered providers');
+    }
+    const ids = new Set();
+    for (const adapter of [...Object.values(registry.providers).flatMap(p => p.workerAdapter ? [p.workerAdapter] : []),
+        ...Object.values(registry.workerAdapters ?? {})]) {
+        if (!/^[a-z][a-z0-9-]{0,62}$/.test(adapter.id) || ids.has(adapter.id))
+            throw new Error(`Duplicate or invalid worker adapter ID: ${adapter.id}`);
+        ids.add(adapter.id);
+    }
+    return registry;
+}
+/** Exact, case-sensitive references; deployment and inference provider identities differ. */
+export function resolveWorkerAdapter(registry, reference) {
+    const match = /^(providers|workerAdapters):([a-z][a-z0-9-]{0,62})$/.exec(reference);
+    if (!match)
+        throw new Error(`Invalid worker adapter reference: ${reference}`);
+    const [, namespace, id] = match;
+    const adapter = namespace === 'providers'
+        ? registry.providers[id]?.workerAdapter
+        : registry.workerAdapters?.[id];
+    if (!adapter)
+        throw new Error(`Unknown worker adapter reference: ${reference}`);
+    return WorkerAdapterSchema.parse(adapter);
+}
+/** Pure direct/shared mapping: no admission store, Mission or activation marker. */
+export function resolveWorkerInstallation(registry, installation) {
+    const adapter = resolveWorkerAdapter(registry, installation.adapter);
+    if (adapter.invocation.kind === 'process') {
+        if (installation.endpoint !== undefined)
+            throw new Error('Process adapter forbids endpoint');
+        const executable = installation.executable ?? adapter.invocation.executable;
+        if (!executable.trim() || executable.includes('\0'))
+            throw new Error('Process adapter requires executable');
+        return { adapter, executable };
+    }
+    if (installation.executable !== undefined)
+        throw new Error('HTTP adapter forbids executable');
+    if (!installation.endpoint)
+        throw new Error('HTTP adapter requires endpoint');
+    const endpoint = new URL(installation.endpoint);
+    if (!['http:', 'https:'].includes(endpoint.protocol) || endpoint.username || endpoint.password || endpoint.hash) {
+        throw new Error('Invalid HTTP adapter endpoint');
+    }
+    return { adapter, endpoint: installation.endpoint };
+}
+/** Typed policy failures let public surfaces retain the cause without exposing internal details. */
+export class WorkerPolicyError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'WorkerPolicyError';
+    }
+}
+/**
+ * Dispatch-time safety checks belong here, alongside transport qualification.
+ * Like route validation, rendering requires observation evidence; a default
+ * observation may supply it when no model observation is available.
+ */
+export function assertWorkerSelectionAllowed(selected, context) {
+    const policy = context.policy ?? DEFAULT_WORKER_SELECTION;
+    if (isWorkerEffortDenied(selected.effort.value, policy)) {
+        throw new WorkerPolicyError('OG_EFFORT_DENIED', `Worker invocation denied effort: ${selected.effort.value}`);
+    }
+    if (isContributorWorkerModel(selected.model)
+        || isWorkerModelDenied(workerModelKey(selected.inferenceProvider, selected.model), policy)) {
+        throw new WorkerPolicyError('OG_MODEL_UNAPPROVED', `Worker invocation denied model: ${selected.model}`);
+    }
+    const { data, unknownDataClass } = workerRouteDataPolicy(policy, context.dataClass);
+    if (unknownDataClass)
+        throw new WorkerPolicyError('OG_DATA_POLICY', 'Worker invocation has denied data-use: unknown data class');
+    const observation = context.modelObservation ?? context.defaultObservation;
+    if (!observation)
+        throw new WorkerPolicyError('OG_MODEL_UNAPPROVED', 'Worker invocation requires model or default observation evidence');
+    const guidance = context.role ? policy.roleGuidance?.[context.role] : undefined;
+    if (isWorkerNullEffortDenied(selected.effort.value, observation, guidance)) {
+        throw new WorkerPolicyError('OG_EFFORT_DENIED', 'Worker invocation denied effort: null effort requires qualified absence of an effort control');
+    }
+    for (const [kind, observation] of [
+        ['model', context.modelObservation], ['default', context.defaultObservation],
+    ]) {
+        if (!observation)
+            continue;
+        if (observation.lifecycle === 'retired'
+            || (observation.retiredAt != null && Date.parse(observation.retiredAt) <= context.now)
+            || (observation.sunsetAt != null && Date.parse(observation.sunsetAt) <= context.now)) {
+            throw new WorkerPolicyError('OG_MODEL_UNAPPROVED', `Worker invocation ${kind} observation is retired`);
+        }
+        const blockMs = (policy.freshness?.blockHours ?? DEFAULT_WORKER_SELECTION.freshness.blockHours) * 3_600_000;
+        const observedAt = Date.parse(observation.observedAt);
+        if (!Number.isFinite(context.now) || !Number.isFinite(observedAt)
+            || !Number.isFinite(blockMs) || blockMs <= 0
+            || (observation.verifiedAt !== undefined && !Number.isFinite(Date.parse(observation.verifiedAt)))
+            || isWorkerEvidenceStale(observation, policy, context.now)) {
+            throw new WorkerPolicyError('OG_MODEL_UNAPPROVED', `Worker invocation ${kind} observation is stale or invalid`);
+        }
+        if (hasSelectionRelevantConflicts(observation)) {
+            throw new WorkerPolicyError('OG_MODEL_UNAPPROVED', `Worker invocation ${kind} observation has conflicting selection-relevant evidence`);
+        }
+        if (observation.dataUse && isWorkerDataUseDenied({
+            processing: observation.dataUse.processing ?? 'unknown',
+            productImprovement: observation.dataUse.productImprovement ?? null,
+            retentionDays: observation.dataUse.retentionDays ?? null,
+        }, data)) {
+            throw new WorkerPolicyError('OG_DATA_POLICY', `Worker invocation ${kind} observation has denied data-use`);
+        }
+    }
+}
+const WORKER_CONTROLS = ['model', 'effort', 'sandbox', 'approval', 'workdir',
+    'finalOutput', 'stdin', 'structuredOutput', 'stepCap', 'trust', 'children', 'fallback'];
+/** Caller controls only add restrictions. Absent resolved authority, require all controls. */
+export function requiredWorkerControls(context) {
+    if (context.requiredControls !== undefined && (!Array.isArray(context.requiredControls)
+        || context.requiredControls.some(name => typeof name !== 'string' || !name))) {
+        throw new Error('Worker required controls must be an array of control names');
+    }
+    const controls = new Set(WORKER_CONTROLS);
+    if (context.policy && context.permissions) {
+        if (context.effort === null)
+            controls.delete('effort');
+        // Step limits are observed unless explicitly required by the trusted route.
+        controls.delete('stepCap');
+        if (context.policy.guards?.denySelfDelegation === false)
+            controls.delete('children');
+    }
+    for (const name of context.requiredControls ?? [])
+        controls.add(name);
+    return [...controls];
+}
+/** The same sandbox requirement governs inspection, resolution and rendering. */
+export function requiresWorkerExternalBoundary(adapter, selection) {
+    const providers = [adapter.id, adapter.provider].map(normalizeProviderDefinitionId);
+    return requiredWorkerControls(selection).includes('sandbox')
+        && (providers.some(provider => provider && ['claude', 'muse', 'hermes'].includes(provider))
+            || adapter.invocationProfiles?.[selection.profile]?.controls.sandbox?.support === 'external'
+            || selection.permissions?.sandbox === 'external');
+}
+/** Inspect declared controls before installation evidence can be produced. This
+ * does not authorize invocation; consumers must use qualifyWorkerInvocationProfile. */
+export function inspectWorkerInvocationProfile(adapter, selection) {
+    WorkerAdapterSchema.parse(adapter);
+    const profile = adapter.invocationProfiles?.[selection.profile];
+    if (adapter.qualification.status !== 'qualified' || !profile || profile.transport !== selection.transport) {
+        throw new Error('Worker transport/profile is unqualified');
+    }
+    // Shared range predicate (worker-installation.mjs): read-only surfaces
+    // (worker-direct-readiness.ts) reuse the same helper instead of
+    // re-deriving this inspector's range logic.
+    if (workerVersionRangeMismatch(selection.cliVersion, [adapter.supportedVersions, profile.supportedVersions]) !== null) {
+        throw new Error('Worker CLI version is outside qualified profile');
+    }
+    const requiredControls = requiredWorkerControls(selection);
+    if (requiresWorkerExternalBoundary(adapter, selection)
+        && (!selection.boundary || !['os', 'executor'].includes(selection.boundary.kind)
+            || !selection.boundary.identity || !/^sha256:[a-f0-9]{64}$/.test(selection.boundary.digest)
+            || !selection.boundary.controls?.includes('sandbox'))) {
+        throw new Error('Required worker control sandbox needs a qualified external enforcing boundary');
+    }
+    for (const name of requiredControls) {
+        if ((name === 'children' && !adapter.capabilities.nestedAgentsControllable)
+            || (name === 'fallback' && !adapter.capabilities.nativeFallbackControllable)) {
+            throw new Error(`Required worker control is unqualified: ${name}`);
+        }
+        const control = profile.controls[name];
+        if (!control || !['native', 'external'].includes(control.support) || !control.mapping || !control.evidence) {
+            throw new Error(`Required worker control is unqualified: ${name}`);
+        }
+    }
+    if (selection.transport === 'mcp' && (!selection.mcp || !profile.mcp
+        || Object.keys(profile.mcp).some(key => profile.mcp[key]
+            !== selection.mcp[key]))) {
+        throw new Error('MCP server/tool/schema/session qualification changed');
+    }
+    return profile;
+}
+/** Qualification is transport/version scoped; declaration or boundary claims
+ * alone cannot qualify an external sandbox. The invocation owner rechecks the
+ * installation scope, including this boundary, against the recorded digest. */
+export function qualifyWorkerInvocationProfile(adapter, selection) {
+    const profile = inspectWorkerInvocationProfile(adapter, selection);
+    if (requiresWorkerExternalBoundary(adapter, selection) && !profile.installationQualification) {
+        throw new Error('Required worker control sandbox needs matching installation qualification for its external boundary');
+    }
+    return profile;
+}
+/** Health timing evidence belongs to the exact execution profile and tuple.
+ * Fixture qualification does not become authenticated/live qualification. */
+export function workerHealthScopeDigest(profile, scope) {
+    const { installationQualification: _installation, health, ...executionProfile } = profile;
+    const { qualification: _qualification, ...signals } = health ?? {};
+    return qualificationDigest({ profile: executionProfile, health: signals,
+        profileRef: scope.profileRef, cliVersion: scope.cliVersion, accountScope: scope.accountScope,
+        modelKey: workerModelKey(scope.inferenceProvider, scope.model), effort: scope.effort });
+}
+/** Reused by observation and invocation owners before using qualified health.
+ * Older profiles have no qualification record and retain degraded observation. */
+export function assertWorkerHealthQualification(profile, scope) {
+    const evidence = profile.health?.qualification;
+    if (!evidence)
+        return;
+    if (evidence.status === 'unqualified') {
+        if (profile.health?.coverage === 'full' || profile.health?.handshake === 'semantic') {
+            throw new Error('Unqualified worker health cannot assert full or semantic coverage');
+        }
+        return;
+    }
+    const modelKey = workerModelKey(scope.inferenceProvider, scope.model);
+    if (evidence.cliVersion !== scope.cliVersion || evidence.accountScope !== scope.accountScope
+        || evidence.profileRef !== scope.profileRef || evidence.modelKey !== modelKey || evidence.effort !== scope.effort
+        || !profile.health?.qualifiedAt || !Number.isFinite(Date.parse(profile.health.qualifiedAt))
+        || evidence.scopeDigest !== workerHealthScopeDigest(profile, scope)
+        || (evidence.status === 'live-qualified' && evidence.authorizedLive !== true)) {
+        throw new Error('Worker health qualification scope changed or lacks live authorization');
+    }
+}
+export function parseProviderModelCatalog(input) {
+    const validate = getCatalogValidators().catalog;
+    if (!validate(input))
+        throw new Error(`MODEL_POLICY_INVALID: ${validate.errors?.map(e => `${e.instancePath} ${e.message}`).join('; ')}`);
+    return CatalogSchema.parse(input);
+}
 export function loadProviderModelCatalog() {
     if (!catalogCache)
-        catalogCache = CatalogSchema.parse(catalogData);
+        catalogCache = parseProviderModelCatalog(catalogData);
     return catalogCache;
 }
 export function validateCanonicalModelPolicy(input) {
@@ -138,7 +613,8 @@ export function validateUserProjectModelConfig(input) {
     return {
         valid: false,
         diagnostics: parsed.error.issues.map(issue => ({
-            code: 'MODEL_POLICY_INVALID',
+            code: issue.path.includes('workerSelection') ? 'OG_CONFIG_REFERENCE' : 'MODEL_POLICY_INVALID',
+            pointer: `/${issue.path.map(p => String(p).replace(/~/g, '~0').replace(/\//g, '~1')).join('/')}`,
             severity: 'error',
             message: `${issue.path.join('.') || 'config'}: ${issue.message}`,
         })),
@@ -274,4 +750,142 @@ export function resetModelPolicyCachesForTests() {
     registryCache = null;
     catalogCache = null;
 }
+// Dispatch rechecks consume the effective policy from resolution. Keep these
+// predicates shared with route validation so defaults and restrictions agree.
+function isContributorWorkerModel(model) {
+    return /(?:^|[-_:/.])contributor(?:$|[-_:/.])/i.test(model);
+}
+function isWorkerModelDenied(modelKey, policy) {
+    return (policy.guards?.deniedModels ?? DEFAULT_WORKER_SELECTION.guards.deniedModels).includes(modelKey);
+}
+function isWorkerEffortDenied(effort, policy) {
+    return effort !== null && (policy.guards?.deniedEfforts ?? DEFAULT_WORKER_SELECTION.guards.deniedEfforts).includes(effort);
+}
+function isWorkerNullEffortDenied(effort, observation, guidance) {
+    return effort === null && (observation.effortSupport !== 'not-applicable' || guidance?.allowNotApplicableEffort !== true);
+}
+function workerRouteDataPolicy(policy, dataClass) {
+    const data = { ...DEFAULT_WORKER_SELECTION.dataPolicy, ...policy.dataPolicy };
+    const narrowed = dataClass ? policy.dataClasses?.[dataClass] : undefined;
+    if (narrowed) {
+        if (narrowed.allowedProcessing)
+            data.allowedProcessing = data.allowedProcessing?.filter(p => narrowed.allowedProcessing.includes(p));
+        if (narrowed.allowUnknown === false)
+            data.allowUnknown = false;
+        if (narrowed.allowProductImprovement === false)
+            data.allowProductImprovement = false;
+        if (narrowed.maxRetentionDays !== undefined)
+            data.maxRetentionDays = Math.min(data.maxRetentionDays ?? Infinity, narrowed.maxRetentionDays);
+    }
+    return { data, unknownDataClass: Boolean(dataClass && !narrowed) };
+}
+function isWorkerDataUseDenied(facts, data) {
+    return (facts.processing === 'unknown' && data.allowUnknown !== true)
+        || (facts.processing !== 'unknown' && !data.allowedProcessing?.includes(facts.processing))
+        || (facts.productImprovement === null && data.allowUnknown !== true)
+        || (facts.productImprovement === true && data.allowProductImprovement !== true)
+        || (data.maxRetentionDays !== undefined && (facts.retentionDays === null ? data.allowUnknown !== true : facts.retentionDays > data.maxRetentionDays));
+}
+function isWorkerEvidenceStale(observation, policy, now) {
+    const observed = Date.parse(observation.observedAt);
+    const verified = observation.verifiedAt === undefined ? undefined : Date.parse(observation.verifiedAt);
+    const blockHours = policy.freshness?.blockHours ?? DEFAULT_WORKER_SELECTION.freshness.blockHours;
+    const policyDays = policy.freshness?.policyDays ?? DEFAULT_WORKER_SELECTION.freshness.policyDays;
+    return observed > now || now - observed > blockHours * 3600000
+        || (verified !== undefined && (verified > now || now - verified > policyDays * 86400000));
+}
+/** Optional catalog facts do not veto otherwise qualified selection. */
+export function hasSelectionRelevantConflicts(observation) {
+    const relevant = /^\/(?:lifecycle|availability|visibility|hidden|efforts|effortSupport|reasoningEfforts|sunsetAt|retiredAt|replacementModelId|supersededBy|dataUse|id|apiModelId|llmProvider|cliId|family|runtimeVersion|accountScope|endpointFingerprint|identityEvidence|contextTokens|maxOutputTokens|qualification)(?:\/|$)/;
+    return observation.conflicts?.some(conflict => relevant.test(conflict.field)) ?? false;
+}
+/** Validate a resolved route without launching or creating managed state. */
+export function validateWorkerPolicyRoute(input) {
+    const diagnostics = [];
+    const deny = (code, pointer, message) => { diagnostics.push({ code, pointer, message }); };
+    const shapeErrors = validateWorkerModelObservation(input.observation);
+    if (shapeErrors.length)
+        return [{ code: 'OG_ADAPTER_UNQUALIFIED', pointer: '/worker', message: shapeErrors.join('; ') }];
+    const observation = input.observation;
+    if (hasSelectionRelevantConflicts(observation))
+        deny('OG_MODEL_UNAPPROVED', '/worker/conflicts', 'Conflicting selection-relevant model evidence blocks the route');
+    else if (observation.conflicts?.length)
+        diagnostics.push({
+            code: 'OG_MODEL_UNAPPROVED', pointer: '/worker/conflicts', blocking: false,
+            message: `Conflicting optional model evidence remains unknown: ${observation.conflicts.map(conflict => conflict.field).join(', ')}`,
+        });
+    const guards = input.policy.guards ?? DEFAULT_WORKER_SELECTION.guards;
+    const guidance = input.policy.roleGuidance?.[input.role];
+    if (observation.qualification.status !== 'qualified' || !observation.qualification.roles.includes(input.role))
+        deny('OG_ADAPTER_UNQUALIFIED', '/worker/qualification', 'Role lacks qualified evidence');
+    if (!guidance)
+        deny('OG_CONFIG_REFERENCE', `/defaults/workerSelection/roleGuidance/${input.role}`, 'Role guidance is unavailable');
+    const substitution = input.substitution?.model === input.selectedModel
+        && input.substitution.effort === input.effort && input.substitution.rationale.trim();
+    if (input.wrapperPin && input.wrapperPin !== input.selectedModel && !substitution)
+        deny('OG_PIN_MISMATCH', '/agentOverrides', 'Wrapper exact pin differs from selected model');
+    if (guards.requireExactModel !== false && input.selectedModel !== input.apiModelId)
+        deny('OG_PIN_MISMATCH', '/worker/id', 'Selected model is not the exact observed API model');
+    let modelKey;
+    try {
+        modelKey = workerModelKey(input.inferenceProvider, input.apiModelId);
+    }
+    catch {
+        deny('OG_CONFIG_REFERENCE', '/worker/id', 'Invalid inference model identity');
+    }
+    // The dispatch guard checks the selected model; when requireExactModel is
+    // false that can differ from apiModelId, so deny on either identity.
+    let selectedKey;
+    try {
+        selectedKey = workerModelKey(input.inferenceProvider, input.selectedModel);
+    }
+    catch { /* reported via apiModelId */ }
+    if (isContributorWorkerModel(input.apiModelId) || isContributorWorkerModel(input.selectedModel)
+        || (modelKey && isWorkerModelDenied(modelKey, input.policy))
+        || (selectedKey && isWorkerModelDenied(selectedKey, input.policy)))
+        deny('OG_MODEL_UNAPPROVED', '/defaults/workerSelection/guards/deniedModels', 'Inference model is denied');
+    if (input.identityEvidence === 'unknown' || input.identityEvidence === 'mismatched' || (guards.minimumIdentityEvidence === 'backend-attested' && input.identityEvidence !== 'backend-attested'))
+        deny('OG_ADAPTER_UNQUALIFIED', '/defaults/workerSelection/guards/minimumIdentityEvidence', 'Identity evidence does not meet the required order');
+    if (!(guards.allowedVisibility ?? ['listed']).includes(observation.visibility) || !(guards.allowedLifecycle ?? ['active']).includes(observation.lifecycle) || observation.availability !== 'accessible')
+        deny('OG_MODEL_UNAPPROVED', '/worker', 'Visibility, lifecycle or availability is ineligible');
+    if (input.effort === null) {
+        if (isWorkerNullEffortDenied(input.effort, observation, guidance))
+            deny('OG_EFFORT_DENIED', '/worker/effortSupport', 'Null effort requires qualified absence of an effort control');
+    }
+    else {
+        const effort = observation.efforts.find(e => e.id === input.effort);
+        if (observation.effortSupport !== 'explicit' || !effort || !(input.effort === 'none' ? guidance?.initialEffort === 'none' && guidance.effortLadder.length === 0 : guidance?.effortLadder.includes(input.effort)) || isWorkerEffortDenied(input.effort, input.policy) || (guards.denySelfDelegation !== false && effort.selfDelegates !== false))
+            deny('OG_EFFORT_DENIED', '/worker/efforts', 'Unsupported, denied or self-delegating effort');
+    }
+    const { data, unknownDataClass } = workerRouteDataPolicy(input.policy, input.dataClass);
+    if (unknownDataClass)
+        deny('OG_DATA_POLICY', '/defaults/workerSelection/dataClasses', 'Unknown data class');
+    if (isWorkerDataUseDenied(observation.dataUse, data))
+        deny('OG_DATA_POLICY', '/worker/dataUse', 'Execution path data facts do not satisfy policy');
+    const now = (input.now ?? new Date()).getTime();
+    if (observation.retiredAt != null && Date.parse(observation.retiredAt) <= now
+        || observation.sunsetAt && Date.parse(observation.sunsetAt) <= now) {
+        deny('OG_MODEL_UNAPPROVED', '/worker/lifecycle', 'Model retirement or sunset is effective');
+    }
+    if (isWorkerEvidenceStale(observation, input.policy, now))
+        deny('OG_ADAPTER_UNQUALIFIED', '/worker/observedAt', 'Model evidence is stale or from the future');
+    else if (now - Date.parse(observation.observedAt) > (input.policy.freshness?.warnHours ?? DEFAULT_WORKER_SELECTION.freshness.warnHours) * 3600000) {
+        diagnostics.push({ code: 'OG_ADAPTER_UNQUALIFIED', pointer: '/worker/observedAt', blocking: false, message: 'Model observation exceeds the freshness warning threshold' });
+    }
+    if (input.context && !workerContextHeadroom(input.context, observation).fits) {
+        deny('OG_MODEL_UNAPPROVED', '/worker/contextTokens', 'Bounded context and output do not fit qualified limits');
+    }
+    return diagnostics;
+}
+export function workerContextHeadroom(estimate, observation) {
+    const safetyMargin = Math.max(estimate.safetyMargin ?? 0, Math.ceil((observation.contextTokens ?? 0) * 0.1));
+    const terms = [estimate.briefTokens, estimate.inputTokens, estimate.toolOutputAllowance, estimate.reservedOutput, safetyMargin];
+    const total = terms.reduce((sum, value) => sum + value, 0);
+    const fits = Boolean(estimate.estimator.trim()) && terms.every(value => Number.isSafeInteger(value) && value >= 0)
+        && (estimate.safetyMargin === undefined || Number.isSafeInteger(estimate.safetyMargin) && estimate.safetyMargin >= 0)
+        && Number.isSafeInteger(total) && observation.contextTokens !== null && observation.maxOutputTokens !== null
+        && total <= observation.contextTokens && estimate.reservedOutput <= observation.maxOutputTokens;
+    return { ...estimate, safetyMargin, total, qualifiedContextTokens: observation.contextTokens,
+        qualifiedMaxOutputTokens: observation.maxOutputTokens, fits };
+}
 //# sourceMappingURL=provider-policy.js.map