aptly 0.1.0

package/dist/src/catalog.js

@@ -0,0 +1,135 @@
+import { createHash } from 'node:crypto';
+const codexSource = 'https://learn.chatgpt.com/docs/models';
+const claudeSource = 'https://code.claude.com/docs/en/model-config.md';
+const entries = [
+    { profile: { id: 'codex-simple', client: 'codex', model: 'gpt-6-luna', reasoning_effort: 'max' }, tier: 'simple',
+        task: 'Bounded extraction, format conversion, wording cleanup, or small mechanical edits.',
+        fact: 'Efficient for focused, repeatable and high-volume tasks.', source: codexSource, default: true },
+    { profile: { id: 'codex-routine', client: 'codex', model: 'gpt-6.1-terra', reasoning_effort: 'high' }, tier: 'standard',
+        task: 'Context-aware writing or translation, everyday analysis, or clearly scoped implementation.',
+        fact: 'Fast and efficient for writing, visual understanding, and computer use.', source: codexSource, default: true },
+    { profile: { id: 'codex-deep', client: 'codex', model: 'gpt-6.1-sol', reasoning_effort: 'medium' }, tier: 'deep',
+        task: 'Cross-component debugging, architectural tradeoffs, or demanding accuracy-sensitive review.',
+        fact: 'Near-Astra capability for complex, repeated and long-running work at lower cost than Astra.', source: codexSource, default: true },
+    { profile: { id: 'claude-simple', client: 'claude', model: 'haiku' }, tier: 'simple',
+        task: 'Bounded extraction, format conversion, wording cleanup, or small mechanical edits.',
+        fact: 'Fast and efficient for simple tasks.', source: claudeSource, default: true },
+    { profile: { id: 'claude-routine', client: 'claude', model: 'sonnet' }, tier: 'standard',
+        task: 'Context-aware writing or translation, everyday analysis, or clearly scoped implementation.',
+        fact: 'General-purpose model family for daily coding tasks.', source: claudeSource, default: true },
+    { profile: { id: 'claude-deep', client: 'claude', model: 'opus' }, tier: 'deep',
+        task: 'Cross-component debugging, architectural tradeoffs, or demanding accuracy-sensitive review.',
+        fact: 'Model family for complex reasoning tasks.', source: claudeSource, default: true },
+    { profile: { id: 'codex-frontier', client: 'codex', model: 'gpt-6-astra', reasoning_effort: 'high' }, tier: 'deep',
+        task: 'The most demanding sustained end-to-end workflows and judgment across several sources.',
+        fact: 'Most capable family for complex work across code, apps and research.', source: codexSource, default: false },
+    { profile: { id: 'claude-frontier', client: 'claude', model: 'fable' }, tier: 'deep',
+        task: 'The hardest and longest-running workflows requiring sustained investigation and judgment.',
+        fact: 'Model family for the hardest and longest-running tasks.', source: claudeSource, default: false },
+];
+for (const entry of entries) {
+    Object.freeze(entry.profile);
+    Object.freeze(entry);
+}
+Object.freeze(entries);
+const clientOrder = ['codex', 'claude'];
+const own = (value, key) => Object.hasOwn(value, key);
+const plain = (value) => value !== null && typeof value === 'object' &&
+    !Array.isArray(value) && [Object.prototype, null].includes(Object.getPrototypeOf(value));
+const error = (code) => Object.assign(new Error(code), { code });
+/** Fresh copies prevent caller mutation from changing the trusted registry. */
+export function builtInProfiles() { return entries.filter(entry => entry.default).map(entry => ({ ...entry.profile })); }
+/** Exact finite profile tuples, including key coverage, not arbitrary model strings. */
+export function isSupportedProfile(value) {
+    try {
+        if (!plain(value) || Object.getOwnPropertySymbols(value).length)
+            return false;
+        const descriptors = Object.getOwnPropertyDescriptors(value);
+        if (Object.values(descriptors).some(d => !own(d, 'value') || !d.enumerable))
+            return false;
+        return entries.some(({ profile }) => {
+            const expected = Object.entries(profile);
+            return Object.keys(descriptors).length === expected.length && expected.every(([key, field]) => own(descriptors, key) && descriptors[key].value === field);
+        });
+    }
+    catch {
+        return false;
+    }
+}
+function envValue(env, key) {
+    const descriptor = Object.getOwnPropertyDescriptor(env, key);
+    if (!descriptor)
+        return undefined;
+    if (!own(descriptor, 'value') || typeof descriptor.value !== 'string')
+        throw error('catalog_configuration_invalid');
+    return descriptor.value;
+}
+function selectedModels(env, client) {
+    const suffix = client === 'claude' ? 'CLAUDE_MODELS' : 'CODEX_MODELS';
+    if (own(env, 'APTLY_' + suffix) && own(env, suffix))
+        throw error('catalog_configuration_conflict');
+    const raw = envValue(env, 'APTLY_' + suffix) ?? envValue(env, suffix);
+    if (raw === undefined)
+        return entries.filter(entry => entry.default && entry.profile.client === client).map(entry => entry.profile.model);
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw error('catalog_configuration_invalid');
+    }
+    if (!Array.isArray(parsed) || parsed.length > 20 || parsed.some(model => typeof model !== 'string') ||
+        new Set(parsed).size !== parsed.length || parsed.some(model => !entries.some(entry => entry.profile.client === client && entry.profile.model === model))) {
+        throw error('catalog_configuration_invalid');
+    }
+    return parsed;
+}
+function normalizedFacts(facts) {
+    const result = new Map();
+    if (!Array.isArray(facts) || facts.length > 40)
+        throw error('catalog_facts_invalid');
+    for (const fact of facts) {
+        if (!plain(fact) || Object.getOwnPropertySymbols(fact).length)
+            throw error('catalog_facts_invalid');
+        const descriptors = Object.getOwnPropertyDescriptors(fact);
+        if (Object.keys(descriptors).length !== 3 || ['client', 'model', 'description'].some(key => !own(descriptors, key) ||
+            !own(descriptors[key], 'value') || !descriptors[key].enumerable))
+            throw error('catalog_facts_invalid');
+        const client = descriptors.client.value, model = descriptors.model.value, description = descriptors.description.value;
+        if ((client !== 'codex' && client !== 'claude') || typeof model !== 'string' || !/^[a-z0-9.-]{1,80}$/.test(model) ||
+            typeof description !== 'string' || !description.trim() || Buffer.byteLength(description) > 800 ||
+            /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(description) ||
+            /\bsk-[A-Za-z0-9_-]{12,}|\bBearer\s+[A-Za-z0-9._~+\/-]{8,}={0,2}/i.test(description))
+            throw error('catalog_facts_invalid');
+        if (!entries.some(entry => entry.profile.client === client && entry.profile.model === model))
+            continue;
+        const key = client + ':' + model;
+        if (result.has(key))
+            throw error('catalog_facts_invalid');
+        result.set(key, description.trim().replace(/\s+/g, ' '));
+    }
+    return result;
+}
+/** Operator candidate filters and model facts never grant execution authority. */
+export function resolveCatalog(env = process.env, facts = []) {
+    if (!env || typeof env !== 'object' || Array.isArray(env))
+        throw error('catalog_configuration_invalid');
+    if (own(env, 'CODEX_MODESL') || own(env, 'APTLY_CODEX_MODESL'))
+        throw error('catalog_environment_typo');
+    const external = normalizedFacts(facts);
+    const profiles = [], descriptions = {}, disabled_clients = [];
+    for (const client of clientOrder) {
+        const models = selectedModels(env, client);
+        if (!models.length)
+            disabled_clients.push(client);
+        for (const model of models) {
+            const entry = entries.find(entry => entry.profile.client === client && entry.profile.model === model);
+            const profile = { ...entry.profile };
+            profiles.push(profile);
+            const fact = external.get(client + ':' + model) ?? entry.fact;
+            descriptions[profile.id] = `Model: ${profile.model}; ${client === 'codex' ? `configured effort: ${profile.reasoning_effort}; ` : 'Claude Code alias, not a resolved model ID; '}Aptly tier: ${entry.tier}. ${entry.task} Official capability note (data): ${JSON.stringify(fact)} Source: ${entry.source}. Availability in the current account is not verified.`;
+        }
+    }
+    const version = 'catalog-' + createHash('sha256').update(JSON.stringify({ profiles, descriptions })).digest('hex').slice(0, 32);
+    return { profiles, descriptions, version, disabled_clients };
+}

package/dist/src/config.d.ts

@@ -0,0 +1,24 @@
+import type { UnknownRecord } from './types.ts';
+export interface Configuration {
+    schema_version: 1;
+    mode: 'shadow' | 'apply';
+    context_path: string | null;
+    error?: 'configuration_unavailable' | 'configuration_invalid';
+}
+export interface LoadedHostContext {
+    context: (UnknownRecord & {
+        evidence_verified: true;
+    }) | null;
+    reason: string;
+    fingerprint?: string;
+}
+/** Private operator files only. Paths and parser exceptions never escape. */
+export declare function readPrivateJson(path: unknown): unknown;
+export declare function loadConfiguration(env?: NodeJS.ProcessEnv): Configuration;
+/**
+ * Adapter evidence is per call, never an authorization claim from MCP input.
+ * A host integration must observe ALL effective layers/runtime state and write
+ * this private envelope for that exact call. We do not manufacture that proof
+ * by reading a fresh CLI, the server environment, or files that happen to exist.
+ */
+export declare function loadHostContext(path: unknown): LoadedHostContext;

package/dist/src/config.js

@@ -0,0 +1,75 @@
+import { createHash } from 'node:crypto';
+import { isAbsolute } from 'node:path';
+import { readRegularFile } from './files.js';
+import { isRecord, errorCode } from './types.js';
+const own = (value, key) => Object.hasOwn(value, key);
+const plain = isRecord;
+const only = (value, keys) => plain(value) && Object.keys(value).every(key => keys.includes(key));
+/** Private operator files only. Paths and parser exceptions never escape. */
+export function readPrivateJson(path) {
+    if (typeof path !== 'string' || !isAbsolute(path))
+        throw new Error('private_file_invalid');
+    try {
+        return JSON.parse(readRegularFile(path, { privateFile: true }).toString('utf8'));
+    }
+    catch {
+        throw new Error('private_file_unavailable');
+    }
+}
+export function loadConfiguration(env = process.env) {
+    const defaults = { schema_version: 1, mode: 'shadow', context_path: null };
+    if (!env.ROUTER_CONFIG_PATH)
+        return defaults;
+    let config;
+    try {
+        config = readPrivateJson(env.ROUTER_CONFIG_PATH);
+    }
+    catch {
+        return { ...defaults, error: 'configuration_unavailable' };
+    }
+    if (!only(config, ['schema_version', 'mode', 'context_path']) || config.schema_version !== 1 ||
+        (config.mode !== 'shadow' && config.mode !== 'apply') ||
+        (own(config, 'context_path') && config.context_path !== null && (typeof config.context_path !== 'string' || !isAbsolute(config.context_path)))) {
+        return { ...defaults, error: 'configuration_invalid' };
+    }
+    return { schema_version: 1, mode: config.mode, context_path: typeof config.context_path === 'string' ? config.context_path : null };
+}
+function unchangedSource(source) {
+    if (!only(source, ['path', 'sha256']) || typeof source.path !== 'string' || !isAbsolute(source.path) ||
+        !(/\.(json|toml|md)$/.test(source.path)) || /(?:^|[/\\])(?:auth|credentials)(?:[.\/\\]|$)/i.test(source.path))
+        return false;
+    try {
+        const bytes = readRegularFile(source.path);
+        if (typeof source.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(source.sha256))
+            return false;
+        return createHash('sha256').update(bytes).digest('hex') === source.sha256;
+    }
+    catch (error) {
+        return source.sha256 === null && errorCode(error) === 'ENOENT';
+    }
+}
+/**
+ * Adapter evidence is per call, never an authorization claim from MCP input.
+ * A host integration must observe ALL effective layers/runtime state and write
+ * this private envelope for that exact call. We do not manufacture that proof
+ * by reading a fresh CLI, the server environment, or files that happen to exist.
+ */
+export function loadHostContext(path) {
+    if (!path)
+        return { context: null, reason: 'context_missing' };
+    let envelope;
+    try {
+        envelope = readPrivateJson(path);
+    }
+    catch {
+        return { context: null, reason: 'context_file_unavailable' };
+    }
+    if (!only(envelope, ['schema_version', 'authority', 'context', 'sources']) || envelope.schema_version !== 1 ||
+        envelope.authority !== 'effective-host-settings-v1' || !plain(envelope.context) ||
+        own(envelope.context, 'evidence_verified') || !Array.isArray(envelope.sources) || envelope.sources.length > 64) {
+        return { context: null, reason: 'context_envelope_invalid' };
+    }
+    if (!envelope.sources.every(unchangedSource))
+        return { context: null, reason: 'context_sources_changed' };
+    return { context: { ...envelope.context, evidence_verified: true }, reason: 'host_evidence_loaded', fingerprint: createHash('sha256').update(JSON.stringify(envelope)).digest('hex') };
+}

package/dist/src/core.d.ts

@@ -0,0 +1,50 @@
+import type { Profile, RoutingPolicy, RoutingProvider, RoutingResult, RoutingStatus } from './types.ts';
+export declare const defaultPolicy: Readonly<RoutingPolicy>;
+interface LedgerRecord {
+    digest: string;
+    state: 'complete' | 'unknown';
+    result?: RoutingResult;
+}
+interface LedgerState {
+    version: 1;
+    calls: number;
+    estimated_usd: number;
+    days: Record<string, number>;
+    requests: Record<string, LedgerRecord>;
+}
+interface RouterOptions {
+    policy?: RoutingPolicy;
+    provider?: RoutingProvider;
+    ledgerPath?: string;
+}
+export declare class Router {
+    policy: RoutingPolicy;
+    provider: RoutingProvider;
+    ledgerPath: string | undefined;
+    state: LedgerState;
+    active: number;
+    constructor({ policy, provider, ledgerPath }?: RouterOptions);
+    capabilities(): {
+        policy_version: string;
+        catalog_version: string;
+        profiles: readonly Profile[];
+        profile_descriptions: Record<string, string>;
+        application: 'advisory_only';
+        storage: string;
+        cost_guard: string;
+        limits: {
+            [k: string]: any;
+        };
+    };
+    result(status: RoutingStatus, reason: string, extra?: Partial<RoutingResult>): RoutingResult;
+    validateOutcome(result: unknown): asserts result is RoutingResult;
+    load(): void;
+    save(): void;
+    /** Strict native-routing path: preserves existing host-evidence and digest semantics. */
+    recommend(input: unknown): Promise<RoutingResult>;
+    /** Independent task advice. Omitted constraints mean no caller-declared pins,
+     * not verified host settings. A legacy provenance flag grants no authority. */
+    advise(input: unknown): Promise<RoutingResult>;
+    private route;
+}
+export {};

package/dist/src/core.js

@@ -0,0 +1,324 @@
+import { createHash } from 'node:crypto';
+import { openSync, closeSync, readFileSync, writeFileSync, renameSync, unlinkSync, lstatSync, chmodSync } from 'node:fs';
+import { isRecord, errorCode } from './types.js';
+import { builtInProfiles, resolveCatalog, isSupportedProfile } from './catalog.js';
+const defaultCatalog = resolveCatalog({});
+export const defaultPolicy = Object.freeze({
+    version: 'aptly-v010', catalog_version: defaultCatalog.version, max_summary_bytes: 4000,
+    max_concurrency: 1, max_daily_calls: 20, max_total_calls: 50,
+    estimated_call_usd: 0.01, max_estimated_usd: 0.5, timeout_ms: 10000,
+    profiles: Object.freeze(builtInProfiles().map(profile => Object.freeze(profile))),
+    profile_descriptions: Object.freeze(defaultCatalog.descriptions),
+});
+const clone = (value) => structuredClone(value);
+const canonical = (value) => Array.isArray(value) ? value.map(canonical) : isRecord(value) ? Object.fromEntries(Object.keys(value).sort().map(k => [k, canonical(value[k])])) : value;
+const digest = (value) => {
+    const serialized = JSON.stringify(canonical(value));
+    if (serialized === undefined)
+        throw new Error('invalid_digest');
+    return createHash('sha256').update(serialized).digest('hex');
+};
+const empty = () => ({ version: 1, calls: 0, estimated_usd: 0, days: {}, requests: {} });
+const own = (obj, key) => Object.hasOwn(obj, key);
+const keysOnly = (obj, allowed) => isRecord(obj) && Object.keys(obj).every(k => allowed.includes(k));
+const safeInt = (n, max = 1e9) => typeof n === 'number' && Number.isSafeInteger(n) && n >= 0 && n <= max;
+const safeVersion = (value) => typeof value === 'string' && /^[A-Za-z0-9_.-]{1,64}$/.test(value);
+const usageOf = (usage) => {
+    if (!keysOnly(usage, ['input_tokens', 'output_tokens', 'total_tokens']))
+        throw new Error('invalid_usage');
+    const { input_tokens, output_tokens, total_tokens } = usage;
+    if (!safeInt(input_tokens) || !safeInt(output_tokens) || !safeInt(total_tokens) || total_tokens !== input_tokens + output_tokens)
+        throw new Error('invalid_usage');
+    return { input_tokens, output_tokens, total_tokens };
+};
+// Runtime eligibility stays within the current finite catalog; archival compatibility below does not expand it.
+const supportedProfile = (p) => isSupportedProfile(p);
+// Storage compatibility only. These retired tuples may be read from an old
+// ledger, but do not enter the runtime catalog or grant Hook execution rights.
+const legacyStoredProfiles = [
+    { id: 'codex-routine', client: 'codex', model: 'gpt-6.1-sol', reasoning_effort: 'low' },
+    { id: 'codex-deep', client: 'codex', model: 'gpt-6-astra', reasoning_effort: 'high' },
+    { id: 'claude-routine', client: 'claude', model: 'haiku' },
+    { id: 'claude-deep', client: 'claude', model: 'sonnet' },
+];
+function isStoredProfile(value) {
+    if (isSupportedProfile(value))
+        return true;
+    if (!isRecord(value) || Object.getOwnPropertySymbols(value).length)
+        return false;
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    return legacyStoredProfiles.some(profile => {
+        const expected = Object.entries(profile);
+        return Object.keys(descriptors).length === expected.length && expected.every(([key, field]) => own(descriptors, key) && own(descriptors[key], 'value') && descriptors[key].enumerable && descriptors[key].value === field);
+    });
+}
+const outcomeReasons = {
+    recommended: ['allowed_profile'],
+    keep_current: ['preserved_constraints', 'unsupported_profile', 'invalid_response', 'invalid_choice', 'provider_abstained', 'no_candidates'],
+    needs_context: ['insufficient_context', 'provider_needs_context'],
+    unavailable: ['budget_exhausted'],
+};
+const isClient = (value) => value === 'codex' || value === 'claude';
+const preservedFields = ['model_pinned', 'effort_pinned', 'role_pinned', 'fork_inherits'];
+export class Router {
+    policy;
+    provider;
+    ledgerPath;
+    state;
+    active;
+    constructor({ policy = defaultPolicy, provider, ledgerPath } = {}) {
+        this.policy = clone(policy);
+        const integerCaps = { max_summary_bytes: 64000, max_concurrency: 16, max_daily_calls: 100000, max_total_calls: 1000000, timeout_ms: 60000 };
+        if (!safeVersion(policy.version) || !safeVersion(policy.catalog_version))
+            throw new Error('invalid_policy');
+        for (const k of Object.keys(integerCaps)) {
+            if (!safeInt(this.policy[k], integerCaps[k]) || this.policy[k] === 0)
+                throw new Error('invalid_policy');
+        }
+        for (const k of ['estimated_call_usd', 'max_estimated_usd'])
+            if (!Number.isFinite(policy[k]) || policy[k] <= 0 || policy[k] > 100)
+                throw new Error('invalid_policy');
+        if (typeof provider !== 'function')
+            throw new Error('invalid_provider');
+        if (!Array.isArray(policy.profiles) || policy.profiles.length > 20 || policy.profiles.some(p => !p || typeof p !== 'object') || new Set(policy.profiles.map(p => p.id)).size !== policy.profiles.length)
+            throw new Error('invalid_policy');
+        for (const p of policy.profiles) {
+            if (!keysOnly(p, ['id', 'client', 'model', 'reasoning_effort']) || typeof p.id !== 'string' || !/^[a-z0-9-]{1,64}$/.test(p.id) || !supportedProfile(p) || (p.client === 'claude' && own(p, 'reasoning_effort')))
+                throw new Error('invalid_policy');
+        }
+        if (policy.profile_descriptions !== undefined && (!isRecord(policy.profile_descriptions) || Object.entries(policy.profile_descriptions).some(([id, value]) => !/^[a-z0-9-]{1,64}$/.test(id) || typeof value !== 'string' || !value.trim() || Buffer.byteLength(value) > 2400)))
+            throw new Error('invalid_policy');
+        this.provider = provider;
+        this.ledgerPath = ledgerPath;
+        this.state = empty();
+        this.active = 0;
+    }
+    capabilities() {
+        return { policy_version: this.policy.version, catalog_version: this.policy.catalog_version,
+            profiles: clone(this.policy.profiles), profile_descriptions: clone(this.policy.profile_descriptions ?? {}), application: 'advisory_only',
+            storage: this.ledgerPath ? 'persistent_metadata' : 'in_memory_fixture_only',
+            cost_guard: 'local_estimate_not_billing_cap', limits: Object.fromEntries(Object.entries(this.policy).filter(([k]) => k.startsWith('max_') || ['estimated_call_usd', 'timeout_ms'].includes(k))) };
+    }
+    result(status, reason, extra = {}) {
+        return { status, reason, application: 'advisory_only', policy_version: this.policy.version, catalog_version: this.policy.catalog_version, ...extra };
+    }
+    validateOutcome(result) {
+        if (!keysOnly(result, ['status', 'reason', 'application', 'policy_version', 'catalog_version', 'profile_id', 'profile', 'usage', 'latency_ms', 'confidence']) ||
+            typeof result.status !== 'string' || !own(outcomeReasons, result.status) || typeof result.reason !== 'string' || !outcomeReasons[result.status].includes(result.reason) || result.application !== 'advisory_only' ||
+            !safeVersion(result.policy_version) || !safeVersion(result.catalog_version) ||
+            (own(result, 'latency_ms') && (typeof result.latency_ms !== 'number' || !Number.isFinite(result.latency_ms) || result.latency_ms < 0 || result.latency_ms > 3600000)) ||
+            (own(result, 'confidence') && (typeof result.confidence !== 'number' || !Number.isFinite(result.confidence) || result.confidence < 0 || result.confidence > 1)))
+            throw new Error('invalid_outcome');
+        if (own(result, 'usage'))
+            usageOf(result.usage);
+        if (result.status === 'recommended') {
+            // Validate archival shape/known provenance without requiring membership
+            // in today's selected subset. Eligibility is checked again before reuse.
+            if (!isStoredProfile(result.profile) || result.profile_id !== result.profile.id)
+                throw new Error('invalid_outcome');
+        }
+        else if (own(result, 'profile') || own(result, 'profile_id'))
+            throw new Error('invalid_outcome');
+    }
+    load() {
+        if (!this.ledgerPath)
+            return;
+        try {
+            const stat = lstatSync(this.ledgerPath);
+            if (!stat.isFile() || stat.isSymbolicLink())
+                throw new Error('unsafe_ledger');
+            chmodSync(this.ledgerPath, 0o600);
+            const state = JSON.parse(readFileSync(this.ledgerPath, 'utf8'));
+            if (!keysOnly(state, ['version', 'calls', 'estimated_usd', 'days', 'requests']) || state.version !== 1 || !safeInt(state.calls) || typeof state.estimated_usd !== 'number' || !Number.isFinite(state.estimated_usd) || state.estimated_usd < 0 ||
+                !isRecord(state.days) || !isRecord(state.requests))
+                throw new Error('invalid_ledger');
+            const days = state.days;
+            if (Object.entries(days).some(([day, calls]) => !/^\d{4}-\d{2}-\d{2}$/.test(day) || !safeInt(calls)))
+                throw new Error('invalid_ledger');
+            const validatedDays = days;
+            if (Object.values(validatedDays).reduce((a, b) => a + b, 0) !== state.calls)
+                throw new Error('invalid_ledger');
+            for (const [id, record] of Object.entries(state.requests)) {
+                if (!/^[A-Za-z0-9_-]{1,96}$/.test(id) || ['__proto__', 'constructor', 'prototype'].includes(id) || !keysOnly(record, ['digest', 'state', 'result']) || typeof record.digest !== 'string' || !/^[a-f0-9]{64}$/.test(record.digest) || (record.state !== 'complete' && record.state !== 'unknown'))
+                    throw new Error('invalid_ledger');
+                if (record.state === 'complete')
+                    this.validateOutcome(record.result);
+                else if (own(record, 'result'))
+                    throw new Error('invalid_ledger');
+            }
+            // All records, counters and outcomes were validated above; no parsed
+            // JSON shape is trusted at the file boundary before those checks.
+            this.state = state;
+        }
+        catch (e) {
+            if (errorCode(e) !== 'ENOENT')
+                throw e;
+        }
+    }
+    save() {
+        if (!this.ledgerPath)
+            return;
+        const tmp = `${this.ledgerPath}.write-${process.pid}`;
+        let fd;
+        try {
+            fd = openSync(tmp, 'wx', 0o600);
+            writeFileSync(fd, JSON.stringify(this.state));
+            closeSync(fd);
+            fd = undefined;
+            renameSync(tmp, this.ledgerPath);
+        }
+        finally {
+            if (fd !== undefined)
+                closeSync(fd);
+            try {
+                unlinkSync(tmp);
+            }
+            catch (e) {
+                if (errorCode(e) !== 'ENOENT')
+                    throw e;
+            }
+        }
+    }
+    /** Strict native-routing path: preserves existing host-evidence and digest semantics. */
+    async recommend(input) {
+        return this.route(input, 'hook');
+    }
+    /** Independent task advice. Omitted constraints mean no caller-declared pins,
+     * not verified host settings. A legacy provenance flag grants no authority. */
+    async advise(input) {
+        const invalid = () => this.result('unavailable', 'invalid_input');
+        if (!keysOnly(input, ['request_id', 'client', 'task', 'eligible_profile_ids', 'constraints']) || !isClient(input.client))
+            return invalid();
+        const constraints = own(input, 'constraints') ? input.constraints : {};
+        if (!keysOnly(constraints, [...preservedFields, 'provenance_verified']) || Object.values(constraints).some(value => typeof value !== 'boolean'))
+            return invalid();
+        const declared = Object.fromEntries(preservedFields.map(key => [key, constraints[key] ?? false]));
+        return this.route({ ...input,
+            eligible_profile_ids: own(input, 'eligible_profile_ids') ? input.eligible_profile_ids : this.policy.profiles.filter(profile => profile.client === input.client).map(profile => profile.id),
+            constraints: declared,
+        }, 'advisory');
+    }
+    async route(input, kind) {
+        const invalid = () => this.result('unavailable', 'invalid_input');
+        if (!keysOnly(input, ['request_id', 'client', 'task', 'eligible_profile_ids', 'constraints']) ||
+            typeof input.request_id !== 'string' || !/^[A-Za-z0-9_-]{1,96}$/.test(input.request_id) || !isClient(input.client) ||
+            ['__proto__', 'constructor', 'prototype'].includes(input.request_id) ||
+            !keysOnly(input.task, ['summary', 'operation', 'context_sufficient']) || typeof input.task.summary !== 'string' ||
+            !input.task.summary.trim() || Buffer.byteLength(input.task.summary) > this.policy.max_summary_bytes ||
+            typeof input.task.operation !== 'string' || !['read_only', 'write', 'review', 'analysis'].includes(input.task.operation) || typeof input.task.context_sufficient !== 'boolean' ||
+            !Array.isArray(input.eligible_profile_ids) || (!input.eligible_profile_ids.length && this.policy.profiles.some(p => p.client === input.client)) || input.eligible_profile_ids.length > 20 ||
+            input.eligible_profile_ids.some((id) => typeof id !== 'string') || new Set(input.eligible_profile_ids).size !== input.eligible_profile_ids.length ||
+            !keysOnly(input.constraints, ['model_pinned', 'effort_pinned', 'role_pinned', 'fork_inherits', 'provenance_verified']) ||
+            Object.values(input.constraints).some(v => typeof v !== 'boolean'))
+            return invalid();
+        if (/\bsk-[A-Za-z0-9_-]{12,}|\bBearer\s+[A-Za-z0-9._~+\/-]{8,}={0,2}/i.test(input.task.summary))
+            return this.result('keep_current', 'sensitive_input');
+        const req = clone(input);
+        const profiles = this.policy.profiles.filter(p => p.client === req.client && req.eligible_profile_ids.includes(p.id));
+        if (!profiles.length && !req.eligible_profile_ids.length)
+            return this.result('keep_current', 'no_candidates');
+        if (profiles.length !== req.eligible_profile_ids.length)
+            return this.result('keep_current', 'unsupported_profile');
+        // Keep historical strict-path hashes unchanged. Advice has a separate digest
+        // namespace within the SAME request ledger, so cross-purpose ID reuse cannot
+        // reuse results or automatically retry a previously uncertain paid request.
+        const hash = kind === 'hook' ? digest({ input: req, policy: this.policy }) : digest({ kind: 'advisory-v1', input: req, policy: this.policy });
+        if (this.active >= this.policy.max_concurrency)
+            return this.result('unavailable', 'concurrency_limit');
+        let lock;
+        if (this.ledgerPath) {
+            try {
+                lock = openSync(`${this.ledgerPath}.lock`, 'wx', 0o600);
+            }
+            catch {
+                return this.result('unavailable', 'ledger_locked');
+            }
+        }
+        this.active++;
+        try {
+            this.load();
+            const previous = own(this.state.requests, req.request_id) ? this.state.requests[req.request_id] : undefined;
+            if (previous) {
+                if (previous.digest !== hash)
+                    return this.result('unavailable', 'request_conflict');
+                if (previous.state !== 'complete')
+                    return this.result('unavailable', 'outcome_unknown');
+                this.validateOutcome(previous.result);
+                if (previous.result.policy_version !== this.policy.version || previous.result.catalog_version !== this.policy.catalog_version ||
+                    (previous.result.status === 'recommended' && !profiles.some(p => p.id === previous.result?.profile_id && digest(p) === digest(previous.result?.profile))))
+                    return this.result('unavailable', 'ledger_error');
+                return { ...clone(previous.result), cached: true };
+            }
+            const complete = (result) => {
+                this.state.requests[req.request_id] = { digest: hash, state: 'complete', result };
+                this.save();
+                return clone(result);
+            };
+            if ((kind === 'hook' && req.constraints.provenance_verified !== true) || preservedFields.some(k => req.constraints[k] !== false))
+                return complete(this.result('keep_current', 'preserved_constraints'));
+            if (!req.task.context_sufficient)
+                return complete(this.result('needs_context', 'insufficient_context'));
+            const day = new Date().toISOString().slice(0, 10);
+            if (this.state.calls >= this.policy.max_total_calls || (this.state.days[day] ?? 0) >= this.policy.max_daily_calls || this.state.estimated_usd + this.policy.estimated_call_usd > this.policy.max_estimated_usd + 1e-12)
+                return complete(this.result('unavailable', 'budget_exhausted'));
+            this.state.calls++;
+            this.state.days[day] = (this.state.days[day] ?? 0) + 1;
+            this.state.estimated_usd += this.policy.estimated_call_usd;
+            this.state.requests[req.request_id] = { digest: hash, state: 'unknown' };
+            this.save();
+            const controller = new AbortController();
+            let timer;
+            const started = performance.now();
+            const latency = () => Math.round((performance.now() - started) * 1000) / 1000;
+            try {
+                const response = await Promise.race([
+                    Promise.resolve().then(() => this.provider({ input: clone(req), profiles: clone(profiles), signal: controller.signal })),
+                    new Promise((_, reject) => { timer = setTimeout(() => { controller.abort(); reject(Object.assign(new Error('timeout'), { code: 'timeout' })); }, this.policy.timeout_ms); }),
+                ]);
+                if (!isRecord(response) || typeof response.choice !== 'string' || (own(response, 'confidence') && (typeof response.confidence !== 'number' || !Number.isFinite(response.confidence) || response.confidence < 0 || response.confidence > 1)))
+                    return complete(this.result('keep_current', 'invalid_response', { latency_ms: latency() }));
+                const metadata = { latency_ms: latency() };
+                if (typeof response.confidence === 'number')
+                    metadata.confidence = response.confidence;
+                if (own(response, 'usage')) {
+                    try {
+                        metadata.usage = usageOf(response.usage);
+                    }
+                    catch {
+                        return complete(this.result('keep_current', 'invalid_response', { latency_ms: latency() }));
+                    }
+                }
+                if (response.choice === 'keep_current')
+                    return complete(this.result('keep_current', 'provider_abstained', metadata));
+                if (response.choice === 'needs_context')
+                    return complete(this.result('needs_context', 'provider_needs_context', metadata));
+                const profile = profiles.find(p => p.id === response.choice);
+                if (!profile)
+                    return complete(this.result('keep_current', 'invalid_choice', metadata));
+                return complete(this.result('recommended', 'allowed_profile', { profile_id: profile.id, profile: clone(profile), ...metadata }));
+            }
+            catch (e) {
+                // A failed transport can have consumed a paid call. Preserve its unknown marker.
+                const allowed = ['timeout', 'refused', 'truncated', 'invalid_json', 'unauthorized', 'rate_limited', 'network'];
+                const code = errorCode(e);
+                return this.result('unavailable', code !== undefined && allowed.includes(code) ? code : 'provider_error', { latency_ms: latency() });
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        }
+        catch {
+            return this.result('unavailable', 'ledger_error');
+        }
+        finally {
+            this.active--;
+            if (lock !== undefined) {
+                closeSync(lock);
+                try {
+                    unlinkSync(`${this.ledgerPath}.lock`);
+                }
+                catch { }
+            }
+        }
+    }
+}

package/dist/src/diagnostics.d.ts

@@ -0,0 +1,11 @@
+import type { Diagnostic } from './report.ts';
+export interface DiagnosticOptions {
+    env?: unknown;
+    node?: unknown;
+    platform?: unknown;
+    arch?: unknown;
+    now?: Date;
+    reportId?: string;
+}
+/** Read-only local checks. No hosts are started and no API authentication probe is made. */
+export declare function collectDiagnostics({ env, node, platform, arch, now, reportId }?: DiagnosticOptions): Diagnostic;