@warmdrift/kgauto-compiler 2.0.0-alpha.78 → 2.0.0-alpha.79

package/dist/{chunk-QVD2QWST.mjs → chunk-DRYCOR6G.mjs}

@@ -1,5 +1,5 @@
 // src/version.ts
-var LIBRARY_VERSION = "2.0.0-alpha.78";
+var LIBRARY_VERSION = "2.0.0-alpha.79";
 
 // src/key-health.ts
 var JSON_HEADERS = { "Content-Type": "application/json" };

package/dist/index.d.mts

@@ -1146,7 +1146,7 @@ declare function runStrategyEvalWithAttribution(opts: Omit<GoldenEvalOptions, 'a
  * guard in `tests/version.test.ts` fails the suite (and therefore
  * `prepublishOnly`) when they diverge — a stale constant cannot reach npm.
  */
-declare const LIBRARY_VERSION = "2.0.0-alpha.78";
+declare const LIBRARY_VERSION = "2.0.0-alpha.79";
 
 /**
  * Oracle contract — how an app tells the brain whether a response was good.
@@ -1250,6 +1250,155 @@ declare function resetTokenizer(): void;
  */
 declare function countTokens(text: string): number;
 
+/**
+ * delegate — Release D, the R2 primitive (delegation-fanout accelerator §5.2,
+ * design contract advisory/kgauto/2026-07-24_delegation-fanout-accelerator-design.md).
+ *
+ * A consumer-mountable TOOL the orchestrating model calls mid-loop:
+ * `{ sub_archetype, input, quality_floor? }`. kgauto selects the executor
+ * from evidence, runs the sub-call through the compiler + call(), returns
+ * the result into the loop, links parent↔child rows (R0), and enforces
+ * `policy.maxCostPerTraceUsd` against the running trace spend — the field
+ * that shipped INERT in Release A precisely so this release could turn it on.
+ *
+ * THE AUTHORITY SPLIT IS THE CONTAINMENT (§3):
+ *   - the MODEL decides whether and what to delegate (kgauto never
+ *     decomposes uninvited — §10);
+ *   - KGAUTO decides only who runs it — and never selects a model absent
+ *     from the consumer's declared `ir.models`;
+ *   - the CONSUMER consents: default OFF, `KGAUTO_AUTO_PROMOTE` posture
+ *     (explicit option beats `KGAUTO_DELEGATE` env; neither ⇒ the handler
+ *     refuses observably, never silently).
+ *
+ * Budget refusals and floor refusals are RETURNED to the model as
+ * structured tool results, never thrown — the orchestrator must be able to
+ * compose with what it has (a refusal mid-loop that crashes the loop would
+ * convert a budget into an outage).
+ *
+ * Composition-verification (§7a): every sub-result is 'trusted' until the
+ * orchestrator/consumer reports otherwise via `reportComposition` —
+ * absence-of-report IS the recorded state (migration 052). Rung 3 reads
+ * this to attribute composition failures to stitching, not executor choice.
+ *
+ * Trace-budget honesty (v1 limits, stated where consumers read):
+ *   - the in-process ledger sums DELEGATED spend for this trace (parent's
+ *     own root-call spend is not visible to a library ledger until a
+ *     brain-informed ledger lands; documented on `maxCostPerTraceUsd`);
+ *   - enforcement is estimate-ahead: a sub-call whose compile-time estimate
+ *     would cross the ceiling is refused BEFORE any spend;
+ *   - realized spend is computed from actual tokens × the executor
+ *     profile's prices after each sub-call.
+ */
+
+declare function isDelegateEnabledFromEnv(envSource?: Record<string, string | undefined>): boolean;
+/** Arguments the ORCHESTRATING MODEL supplies when it calls the tool. */
+interface DelegateToolArgs {
+    /** The sub-task's archetype — its own learning_key downstream. */
+    sub_archetype: IntentArchetypeName | string;
+    /** Complete, self-contained sub-task input. The model owns fidelity here
+     *  (authority split): kgauto runs exactly what it is handed. */
+    input: string;
+    /**
+     * Minimum archetype-perf score (0..10) the executor must carry for this
+     * sub-archetype. Candidates below the floor are excluded BEFORE ranking;
+     * if nothing in the parent's declared pool clears it, the tool refuses
+     * with the scores so the model can lower the floor or do the work itself.
+     */
+    quality_floor?: number;
+}
+type DelegateRefusalReason = 'delegate_not_enabled' | 'invalid_sub_archetype' | 'no_qualified_executor' | 'trace_budget_exhausted' | 'call_failed';
+type DelegateResult = {
+    ok: true;
+    /** The sub-result text (or serialized structured output). */
+    output: string;
+    /** Branch handle — pass to reportComposition; joins the brain row. */
+    subHandle: string;
+    executorModel: string;
+    costUsd: number;
+    latencyMs: number;
+    /** Always 'trusted' at return time — flips only via reportComposition. */
+    verification: 'trusted';
+} | {
+    ok: false;
+    reason: DelegateRefusalReason;
+    /** Human/model-readable detail — written to be COMPOSABLE (“continue
+     *  without this sub-result”), never a stack trace. */
+    detail: string;
+};
+/**
+ * Provider-agnostic tool definition. Consumers adapt `inputSchema` to their
+ * SDK's tool shape (AI-SDK `parameters`, Anthropic `input_schema`, …). The
+ * description IS prompt surface — it teaches the model the authority split
+ * and the compose-on-refusal discipline (gates 4/5 of discipline-gates-v1
+ * in tool-description form).
+ */
+declare const DELEGATE_TOOL_DEFINITION: {
+    readonly name: "delegate";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly sub_archetype: {
+                readonly type: "string";
+                readonly enum: ("ask" | "hunt" | "classify" | "summarize" | "generate" | "extract" | "plan" | "critique" | "transform" | "judge")[];
+                readonly description: "What kind of work the sub-task is (its routing archetype).";
+            };
+            readonly input: {
+                readonly type: "string";
+                readonly description: "Complete, self-contained sub-task input. Include everything the executor needs — it sees nothing else.";
+            };
+            readonly quality_floor: {
+                readonly type: "number";
+                readonly minimum: 0;
+                readonly maximum: 10;
+                readonly description: "Optional minimum executor quality score (0-10) for this archetype. Omit to accept the evidence-ranked default.";
+            };
+        };
+        readonly required: readonly ["sub_archetype", "input"];
+        readonly additionalProperties: false;
+    };
+};
+interface CreateDelegateOpts {
+    /** The PARENT call's IR — supplies the declared model pool (the containment
+     *  boundary), appId, and dialect context. */
+    parentIr: PromptIR;
+    /** The parent's compile/call handle — R0 linkage root. Branch rows record
+     *  `parent_handle=<this>` and inherit `trace_id`. */
+    parentHandle: string;
+    /**
+     * Options forwarded to the sub-`call()` (apiKeys, fetchImpl,
+     * attemptTimeoutMs, policy…). `policy.maxCostPerTraceUsd` here is what the
+     * ledger enforces. `parentHandle` is set by the factory — a value passed
+     * in callOpts is overridden.
+     */
+    callOpts?: CallOptions & {
+        policy?: CompilePolicy;
+    };
+    /** Explicit consent — beats KGAUTO_DELEGATE env (AUTO_PROMOTE posture). */
+    enabled?: boolean;
+}
+interface DelegateHandle {
+    toolDefinition: typeof DELEGATE_TOOL_DEFINITION;
+    handler: (args: DelegateToolArgs) => Promise<DelegateResult>;
+    /**
+     * §7a — report what the orchestrator did with a sub-result. Writes a
+     * migration-052 row via the brain-read env trio (RLS-scoped to appId).
+     * Unreported sub-results are 'trusted' by definition — report only
+     * 'verified' and 'discarded'.
+     */
+    reportComposition: (report: {
+        subHandle: string;
+        disposition: 'verified' | 'discarded';
+        note?: string;
+    }) => Promise<{
+        ok: boolean;
+        reason?: string;
+    }>;
+    /** Ledger introspection: delegated spend recorded for this trace so far. */
+    traceSpendUsd: () => number;
+}
+declare function createDelegate(opts: CreateDelegateOpts): DelegateHandle;
+
 /**
  * archetype-fits — alpha.43.
  *
@@ -3531,4 +3680,4 @@ declare function planDecomposition(args: PlanDecompositionArgs): DecompositionPl
  */
 declare function compile(ir: PromptIR, opts?: CompileOptions): CompileResult;
 
-export { ABSOLUTE_FLOOR, type AISDKConvertedMessage, ARCHETYPE_FAMILY_FITS, ARCHETYPE_FLOOR_DEFAULT, type ActionableAdvisory, Adapter, type AdvisoryResolutionSource, type AdvisorySeverity, type AdvisoryStatus, type AdvisorySuggestedFix, ApiKeys, type AppOracle, type ApplySectionRewritesArgs, type ApplySectionRewritesResult, ArchetypeConvention, type ArchetypeFamilyFit, type ArchetypePerfMap, type ArchetypePerfNMap, type ArchetypePerfScoreResult, type AttachCacheControlResult, BRAIN_READ_ENV_NAMES, BestPracticeAdvisory, type BrainConfig, type BrainDeadLetterEntry, type BrainHealthSnapshot, type BrainQueryConfig, type BrainReadEnv, COACH_CFG, CallOptions, CallResult, ChainEntry, type CompatibilityIntent, type CompileForAISDKv6Result, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, DECOMPOSITION_TEMPLATES, DECOMPOSITION_TEMPLATES_VERSION, DEFAULT_FINDINGS_ENDPOINT, DEFAULT_MEASURED_FAILURE_ENDPOINT, DEFAULT_PROMOTIONS_ENDPOINT, DISCIPLINE_GATES_V1_ALT_HEADER, type DecompositionPlan, type DecompositionStep, type DecompositionTemplate, type ExclusionFindingRow, type ExclusionResolutionSource, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type ExecutorCandidate, type FallbackPosture, FallbackReason, FamilyResolutionError, type GetActionableAdvisoriesOptions, type GetApplicablePromotionOpts, type GetDefaultFallbackChainOpts, type GetMeasuredFailureOpts, type GetPerAxisMetricsOpts, type GetRecommendedPrimaryOptions, type GoldenEvalAxis, type GoldenEvalCase, type GoldenEvalOptions, type GoldenEvalRunResult, type GoldenEvalStrategyId, type GoldenIrRecordInput, Grounding, IntentArchetypeName, JUDGE_RUBRICS, LIBRARY_VERSION, type LLMJudgeOptions, MEASURED_FAILURE_CFG, MEASURED_GROUNDING_MIN_N, type MarkAdvisoryResolvedOptions, type MarkExclusionFindingHandledOptions, type MarkPromoteReadyHandledOptions, type MeasuredFailureRuntime, type MeasuredFailureVerdict, type ModelBrainRow, type ModelCompatibility, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, OutputMode, PRODUCER_OWNED_RULE_CODES, PROVIDER_ENV_KEYS, PerAxisMetrics, type PlannedStep, type PricingRow, type ProbeShadowOptions, type ProbeShadowServed, type ProfileToRowOptions, type PromoteReadyFindingRow, type PromoteReadyResolution, type PromotionRow, type PromotionsRuntime, PromptIR, Provider, ProviderOverrides, type ProviderReachability, ROLLBACK_SUPPRESSION_WINDOW_DAYS, RULE_DISCIPLINE_GATES_V1, RULE_DISCIPLINE_GATES_V1_STRUCTURED, RULE_SEQUENTIAL_TOOL_CLIFF, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, STRATEGY_AUTHORSHIP_LIMITATION, SectionRewrite, type ShadowProbeRecordInput, type StrategyAttribution, type StrategyAttributionResult, type StrategyOutcome, type SupportedProvider, type SurfaceFailureRow, type SurfaceStats, SystemModelMessage, TRANSLATOR_FLOOR, _testResetMeasuredFailure, _testResetPromotions, _testWaitForMeasuredFailureRefresh, _testWaitForPromotionsRefresh, altGatesBlockFor, applyArchetypeConvention, applySectionRewrites, attachCacheControlToStreamTextInput, awaitMeasuredFailureReady, brainHealth, buildGoldenIrRow, buildLLMJudge, buildPairwiseJudgePrompt, buildShadowProbeRow, call, classifyStrategyOutcome, clearBrain, combineOrderSwappedVerdicts, compile, compileForAISDKv6, configureBrain, configureMeasuredFailureBrain, configurePromotionsBrain, countTokens, deriveFamilyFromModelId, deriveOwnership, execute, findBetterFit, flushBrainDeadLetter, getActionableAdvisories, getAllStarterChains, getAllStarterChainsWithGrounding, getApplicablePromotion, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getMeasuredFailureVerdict, getModelCompatibility, getPerAxisMetrics, getReachabilityDiagnostic, getRecentRollback, getRecommendedPrimary, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStaleExclusionFindings, getStarterChain, getStarterChainWithGrounding, isAutoPromoteEnabledFromEnv, isBrainQueryActiveFor, isBrainSync, isExclusionFindingsBrainActive, isMeasuredFailureBrainActive, isMeasuredFailureGateEnabledFromEnv, isModelReachable, isPromotionsBrainActive, isProviderReachable, judgeMeasuredFailure, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, mapMeasuredFailureRows, markAdvisoryResolved, markExclusionFindingHandled, markPromoteReadyHandled, parseJudgeVerdict, peekBrainDeadLetter, planDecomposition, prefetchMeasuredFailure, probeShadow, profileToRow, readBrainReadEnv, record, recordGoldenIr, recordOutcome, recordShadowProbe, renderIrForJudge, resetTokenizer, resolveConventionsForProfile, resolvePricingAt, resolveProviderKey, rubricFor, runAdvisor, runGoldenEval, runStrategyEvalWithAttribution, setTokenizer, wilsonLowerBound, withAltDisciplineContract, withDisciplineContract };
+export { ABSOLUTE_FLOOR, type AISDKConvertedMessage, ARCHETYPE_FAMILY_FITS, ARCHETYPE_FLOOR_DEFAULT, type ActionableAdvisory, Adapter, type AdvisoryResolutionSource, type AdvisorySeverity, type AdvisoryStatus, type AdvisorySuggestedFix, ApiKeys, type AppOracle, type ApplySectionRewritesArgs, type ApplySectionRewritesResult, ArchetypeConvention, type ArchetypeFamilyFit, type ArchetypePerfMap, type ArchetypePerfNMap, type ArchetypePerfScoreResult, type AttachCacheControlResult, BRAIN_READ_ENV_NAMES, BestPracticeAdvisory, type BrainConfig, type BrainDeadLetterEntry, type BrainHealthSnapshot, type BrainQueryConfig, type BrainReadEnv, COACH_CFG, CallOptions, CallResult, ChainEntry, type CompatibilityIntent, type CompileForAISDKv6Result, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, type CreateDelegateOpts, DECOMPOSITION_TEMPLATES, DECOMPOSITION_TEMPLATES_VERSION, DEFAULT_FINDINGS_ENDPOINT, DEFAULT_MEASURED_FAILURE_ENDPOINT, DEFAULT_PROMOTIONS_ENDPOINT, DELEGATE_TOOL_DEFINITION, DISCIPLINE_GATES_V1_ALT_HEADER, type DecompositionPlan, type DecompositionStep, type DecompositionTemplate, type DelegateHandle, type DelegateRefusalReason, type DelegateResult, type DelegateToolArgs, type ExclusionFindingRow, type ExclusionResolutionSource, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type ExecutorCandidate, type FallbackPosture, FallbackReason, FamilyResolutionError, type GetActionableAdvisoriesOptions, type GetApplicablePromotionOpts, type GetDefaultFallbackChainOpts, type GetMeasuredFailureOpts, type GetPerAxisMetricsOpts, type GetRecommendedPrimaryOptions, type GoldenEvalAxis, type GoldenEvalCase, type GoldenEvalOptions, type GoldenEvalRunResult, type GoldenEvalStrategyId, type GoldenIrRecordInput, Grounding, IntentArchetypeName, JUDGE_RUBRICS, LIBRARY_VERSION, type LLMJudgeOptions, MEASURED_FAILURE_CFG, MEASURED_GROUNDING_MIN_N, type MarkAdvisoryResolvedOptions, type MarkExclusionFindingHandledOptions, type MarkPromoteReadyHandledOptions, type MeasuredFailureRuntime, type MeasuredFailureVerdict, type ModelBrainRow, type ModelCompatibility, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, OutputMode, PRODUCER_OWNED_RULE_CODES, PROVIDER_ENV_KEYS, PerAxisMetrics, type PlannedStep, type PricingRow, type ProbeShadowOptions, type ProbeShadowServed, type ProfileToRowOptions, type PromoteReadyFindingRow, type PromoteReadyResolution, type PromotionRow, type PromotionsRuntime, PromptIR, Provider, ProviderOverrides, type ProviderReachability, ROLLBACK_SUPPRESSION_WINDOW_DAYS, RULE_DISCIPLINE_GATES_V1, RULE_DISCIPLINE_GATES_V1_STRUCTURED, RULE_SEQUENTIAL_TOOL_CLIFF, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, STRATEGY_AUTHORSHIP_LIMITATION, SectionRewrite, type ShadowProbeRecordInput, type StrategyAttribution, type StrategyAttributionResult, type StrategyOutcome, type SupportedProvider, type SurfaceFailureRow, type SurfaceStats, SystemModelMessage, TRANSLATOR_FLOOR, _testResetMeasuredFailure, _testResetPromotions, _testWaitForMeasuredFailureRefresh, _testWaitForPromotionsRefresh, altGatesBlockFor, applyArchetypeConvention, applySectionRewrites, attachCacheControlToStreamTextInput, awaitMeasuredFailureReady, brainHealth, buildGoldenIrRow, buildLLMJudge, buildPairwiseJudgePrompt, buildShadowProbeRow, call, classifyStrategyOutcome, clearBrain, combineOrderSwappedVerdicts, compile, compileForAISDKv6, configureBrain, configureMeasuredFailureBrain, configurePromotionsBrain, countTokens, createDelegate, deriveFamilyFromModelId, deriveOwnership, execute, findBetterFit, flushBrainDeadLetter, getActionableAdvisories, getAllStarterChains, getAllStarterChainsWithGrounding, getApplicablePromotion, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getMeasuredFailureVerdict, getModelCompatibility, getPerAxisMetrics, getReachabilityDiagnostic, getRecentRollback, getRecommendedPrimary, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStaleExclusionFindings, getStarterChain, getStarterChainWithGrounding, isAutoPromoteEnabledFromEnv, isBrainQueryActiveFor, isBrainSync, isDelegateEnabledFromEnv, isExclusionFindingsBrainActive, isMeasuredFailureBrainActive, isMeasuredFailureGateEnabledFromEnv, isModelReachable, isPromotionsBrainActive, isProviderReachable, judgeMeasuredFailure, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, mapMeasuredFailureRows, markAdvisoryResolved, markExclusionFindingHandled, markPromoteReadyHandled, parseJudgeVerdict, peekBrainDeadLetter, planDecomposition, prefetchMeasuredFailure, probeShadow, profileToRow, readBrainReadEnv, record, recordGoldenIr, recordOutcome, recordShadowProbe, renderIrForJudge, resetTokenizer, resolveConventionsForProfile, resolvePricingAt, resolveProviderKey, rubricFor, runAdvisor, runGoldenEval, runStrategyEvalWithAttribution, setTokenizer, wilsonLowerBound, withAltDisciplineContract, withDisciplineContract };

package/dist/index.d.ts

@@ -1146,7 +1146,7 @@ declare function runStrategyEvalWithAttribution(opts: Omit<GoldenEvalOptions, 'a
  * guard in `tests/version.test.ts` fails the suite (and therefore
  * `prepublishOnly`) when they diverge — a stale constant cannot reach npm.
  */
-declare const LIBRARY_VERSION = "2.0.0-alpha.78";
+declare const LIBRARY_VERSION = "2.0.0-alpha.79";
 
 /**
  * Oracle contract — how an app tells the brain whether a response was good.
@@ -1250,6 +1250,155 @@ declare function resetTokenizer(): void;
  */
 declare function countTokens(text: string): number;
 
+/**
+ * delegate — Release D, the R2 primitive (delegation-fanout accelerator §5.2,
+ * design contract advisory/kgauto/2026-07-24_delegation-fanout-accelerator-design.md).
+ *
+ * A consumer-mountable TOOL the orchestrating model calls mid-loop:
+ * `{ sub_archetype, input, quality_floor? }`. kgauto selects the executor
+ * from evidence, runs the sub-call through the compiler + call(), returns
+ * the result into the loop, links parent↔child rows (R0), and enforces
+ * `policy.maxCostPerTraceUsd` against the running trace spend — the field
+ * that shipped INERT in Release A precisely so this release could turn it on.
+ *
+ * THE AUTHORITY SPLIT IS THE CONTAINMENT (§3):
+ *   - the MODEL decides whether and what to delegate (kgauto never
+ *     decomposes uninvited — §10);
+ *   - KGAUTO decides only who runs it — and never selects a model absent
+ *     from the consumer's declared `ir.models`;
+ *   - the CONSUMER consents: default OFF, `KGAUTO_AUTO_PROMOTE` posture
+ *     (explicit option beats `KGAUTO_DELEGATE` env; neither ⇒ the handler
+ *     refuses observably, never silently).
+ *
+ * Budget refusals and floor refusals are RETURNED to the model as
+ * structured tool results, never thrown — the orchestrator must be able to
+ * compose with what it has (a refusal mid-loop that crashes the loop would
+ * convert a budget into an outage).
+ *
+ * Composition-verification (§7a): every sub-result is 'trusted' until the
+ * orchestrator/consumer reports otherwise via `reportComposition` —
+ * absence-of-report IS the recorded state (migration 052). Rung 3 reads
+ * this to attribute composition failures to stitching, not executor choice.
+ *
+ * Trace-budget honesty (v1 limits, stated where consumers read):
+ *   - the in-process ledger sums DELEGATED spend for this trace (parent's
+ *     own root-call spend is not visible to a library ledger until a
+ *     brain-informed ledger lands; documented on `maxCostPerTraceUsd`);
+ *   - enforcement is estimate-ahead: a sub-call whose compile-time estimate
+ *     would cross the ceiling is refused BEFORE any spend;
+ *   - realized spend is computed from actual tokens × the executor
+ *     profile's prices after each sub-call.
+ */
+
+declare function isDelegateEnabledFromEnv(envSource?: Record<string, string | undefined>): boolean;
+/** Arguments the ORCHESTRATING MODEL supplies when it calls the tool. */
+interface DelegateToolArgs {
+    /** The sub-task's archetype — its own learning_key downstream. */
+    sub_archetype: IntentArchetypeName | string;
+    /** Complete, self-contained sub-task input. The model owns fidelity here
+     *  (authority split): kgauto runs exactly what it is handed. */
+    input: string;
+    /**
+     * Minimum archetype-perf score (0..10) the executor must carry for this
+     * sub-archetype. Candidates below the floor are excluded BEFORE ranking;
+     * if nothing in the parent's declared pool clears it, the tool refuses
+     * with the scores so the model can lower the floor or do the work itself.
+     */
+    quality_floor?: number;
+}
+type DelegateRefusalReason = 'delegate_not_enabled' | 'invalid_sub_archetype' | 'no_qualified_executor' | 'trace_budget_exhausted' | 'call_failed';
+type DelegateResult = {
+    ok: true;
+    /** The sub-result text (or serialized structured output). */
+    output: string;
+    /** Branch handle — pass to reportComposition; joins the brain row. */
+    subHandle: string;
+    executorModel: string;
+    costUsd: number;
+    latencyMs: number;
+    /** Always 'trusted' at return time — flips only via reportComposition. */
+    verification: 'trusted';
+} | {
+    ok: false;
+    reason: DelegateRefusalReason;
+    /** Human/model-readable detail — written to be COMPOSABLE (“continue
+     *  without this sub-result”), never a stack trace. */
+    detail: string;
+};
+/**
+ * Provider-agnostic tool definition. Consumers adapt `inputSchema` to their
+ * SDK's tool shape (AI-SDK `parameters`, Anthropic `input_schema`, …). The
+ * description IS prompt surface — it teaches the model the authority split
+ * and the compose-on-refusal discipline (gates 4/5 of discipline-gates-v1
+ * in tool-description form).
+ */
+declare const DELEGATE_TOOL_DEFINITION: {
+    readonly name: "delegate";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly sub_archetype: {
+                readonly type: "string";
+                readonly enum: ("ask" | "hunt" | "classify" | "summarize" | "generate" | "extract" | "plan" | "critique" | "transform" | "judge")[];
+                readonly description: "What kind of work the sub-task is (its routing archetype).";
+            };
+            readonly input: {
+                readonly type: "string";
+                readonly description: "Complete, self-contained sub-task input. Include everything the executor needs — it sees nothing else.";
+            };
+            readonly quality_floor: {
+                readonly type: "number";
+                readonly minimum: 0;
+                readonly maximum: 10;
+                readonly description: "Optional minimum executor quality score (0-10) for this archetype. Omit to accept the evidence-ranked default.";
+            };
+        };
+        readonly required: readonly ["sub_archetype", "input"];
+        readonly additionalProperties: false;
+    };
+};
+interface CreateDelegateOpts {
+    /** The PARENT call's IR — supplies the declared model pool (the containment
+     *  boundary), appId, and dialect context. */
+    parentIr: PromptIR;
+    /** The parent's compile/call handle — R0 linkage root. Branch rows record
+     *  `parent_handle=<this>` and inherit `trace_id`. */
+    parentHandle: string;
+    /**
+     * Options forwarded to the sub-`call()` (apiKeys, fetchImpl,
+     * attemptTimeoutMs, policy…). `policy.maxCostPerTraceUsd` here is what the
+     * ledger enforces. `parentHandle` is set by the factory — a value passed
+     * in callOpts is overridden.
+     */
+    callOpts?: CallOptions & {
+        policy?: CompilePolicy;
+    };
+    /** Explicit consent — beats KGAUTO_DELEGATE env (AUTO_PROMOTE posture). */
+    enabled?: boolean;
+}
+interface DelegateHandle {
+    toolDefinition: typeof DELEGATE_TOOL_DEFINITION;
+    handler: (args: DelegateToolArgs) => Promise<DelegateResult>;
+    /**
+     * §7a — report what the orchestrator did with a sub-result. Writes a
+     * migration-052 row via the brain-read env trio (RLS-scoped to appId).
+     * Unreported sub-results are 'trusted' by definition — report only
+     * 'verified' and 'discarded'.
+     */
+    reportComposition: (report: {
+        subHandle: string;
+        disposition: 'verified' | 'discarded';
+        note?: string;
+    }) => Promise<{
+        ok: boolean;
+        reason?: string;
+    }>;
+    /** Ledger introspection: delegated spend recorded for this trace so far. */
+    traceSpendUsd: () => number;
+}
+declare function createDelegate(opts: CreateDelegateOpts): DelegateHandle;
+
 /**
  * archetype-fits — alpha.43.
  *
@@ -3531,4 +3680,4 @@ declare function planDecomposition(args: PlanDecompositionArgs): DecompositionPl
  */
 declare function compile(ir: PromptIR, opts?: CompileOptions): CompileResult;
 
-export { ABSOLUTE_FLOOR, type AISDKConvertedMessage, ARCHETYPE_FAMILY_FITS, ARCHETYPE_FLOOR_DEFAULT, type ActionableAdvisory, Adapter, type AdvisoryResolutionSource, type AdvisorySeverity, type AdvisoryStatus, type AdvisorySuggestedFix, ApiKeys, type AppOracle, type ApplySectionRewritesArgs, type ApplySectionRewritesResult, ArchetypeConvention, type ArchetypeFamilyFit, type ArchetypePerfMap, type ArchetypePerfNMap, type ArchetypePerfScoreResult, type AttachCacheControlResult, BRAIN_READ_ENV_NAMES, BestPracticeAdvisory, type BrainConfig, type BrainDeadLetterEntry, type BrainHealthSnapshot, type BrainQueryConfig, type BrainReadEnv, COACH_CFG, CallOptions, CallResult, ChainEntry, type CompatibilityIntent, type CompileForAISDKv6Result, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, DECOMPOSITION_TEMPLATES, DECOMPOSITION_TEMPLATES_VERSION, DEFAULT_FINDINGS_ENDPOINT, DEFAULT_MEASURED_FAILURE_ENDPOINT, DEFAULT_PROMOTIONS_ENDPOINT, DISCIPLINE_GATES_V1_ALT_HEADER, type DecompositionPlan, type DecompositionStep, type DecompositionTemplate, type ExclusionFindingRow, type ExclusionResolutionSource, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type ExecutorCandidate, type FallbackPosture, FallbackReason, FamilyResolutionError, type GetActionableAdvisoriesOptions, type GetApplicablePromotionOpts, type GetDefaultFallbackChainOpts, type GetMeasuredFailureOpts, type GetPerAxisMetricsOpts, type GetRecommendedPrimaryOptions, type GoldenEvalAxis, type GoldenEvalCase, type GoldenEvalOptions, type GoldenEvalRunResult, type GoldenEvalStrategyId, type GoldenIrRecordInput, Grounding, IntentArchetypeName, JUDGE_RUBRICS, LIBRARY_VERSION, type LLMJudgeOptions, MEASURED_FAILURE_CFG, MEASURED_GROUNDING_MIN_N, type MarkAdvisoryResolvedOptions, type MarkExclusionFindingHandledOptions, type MarkPromoteReadyHandledOptions, type MeasuredFailureRuntime, type MeasuredFailureVerdict, type ModelBrainRow, type ModelCompatibility, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, OutputMode, PRODUCER_OWNED_RULE_CODES, PROVIDER_ENV_KEYS, PerAxisMetrics, type PlannedStep, type PricingRow, type ProbeShadowOptions, type ProbeShadowServed, type ProfileToRowOptions, type PromoteReadyFindingRow, type PromoteReadyResolution, type PromotionRow, type PromotionsRuntime, PromptIR, Provider, ProviderOverrides, type ProviderReachability, ROLLBACK_SUPPRESSION_WINDOW_DAYS, RULE_DISCIPLINE_GATES_V1, RULE_DISCIPLINE_GATES_V1_STRUCTURED, RULE_SEQUENTIAL_TOOL_CLIFF, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, STRATEGY_AUTHORSHIP_LIMITATION, SectionRewrite, type ShadowProbeRecordInput, type StrategyAttribution, type StrategyAttributionResult, type StrategyOutcome, type SupportedProvider, type SurfaceFailureRow, type SurfaceStats, SystemModelMessage, TRANSLATOR_FLOOR, _testResetMeasuredFailure, _testResetPromotions, _testWaitForMeasuredFailureRefresh, _testWaitForPromotionsRefresh, altGatesBlockFor, applyArchetypeConvention, applySectionRewrites, attachCacheControlToStreamTextInput, awaitMeasuredFailureReady, brainHealth, buildGoldenIrRow, buildLLMJudge, buildPairwiseJudgePrompt, buildShadowProbeRow, call, classifyStrategyOutcome, clearBrain, combineOrderSwappedVerdicts, compile, compileForAISDKv6, configureBrain, configureMeasuredFailureBrain, configurePromotionsBrain, countTokens, deriveFamilyFromModelId, deriveOwnership, execute, findBetterFit, flushBrainDeadLetter, getActionableAdvisories, getAllStarterChains, getAllStarterChainsWithGrounding, getApplicablePromotion, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getMeasuredFailureVerdict, getModelCompatibility, getPerAxisMetrics, getReachabilityDiagnostic, getRecentRollback, getRecommendedPrimary, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStaleExclusionFindings, getStarterChain, getStarterChainWithGrounding, isAutoPromoteEnabledFromEnv, isBrainQueryActiveFor, isBrainSync, isExclusionFindingsBrainActive, isMeasuredFailureBrainActive, isMeasuredFailureGateEnabledFromEnv, isModelReachable, isPromotionsBrainActive, isProviderReachable, judgeMeasuredFailure, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, mapMeasuredFailureRows, markAdvisoryResolved, markExclusionFindingHandled, markPromoteReadyHandled, parseJudgeVerdict, peekBrainDeadLetter, planDecomposition, prefetchMeasuredFailure, probeShadow, profileToRow, readBrainReadEnv, record, recordGoldenIr, recordOutcome, recordShadowProbe, renderIrForJudge, resetTokenizer, resolveConventionsForProfile, resolvePricingAt, resolveProviderKey, rubricFor, runAdvisor, runGoldenEval, runStrategyEvalWithAttribution, setTokenizer, wilsonLowerBound, withAltDisciplineContract, withDisciplineContract };
+export { ABSOLUTE_FLOOR, type AISDKConvertedMessage, ARCHETYPE_FAMILY_FITS, ARCHETYPE_FLOOR_DEFAULT, type ActionableAdvisory, Adapter, type AdvisoryResolutionSource, type AdvisorySeverity, type AdvisoryStatus, type AdvisorySuggestedFix, ApiKeys, type AppOracle, type ApplySectionRewritesArgs, type ApplySectionRewritesResult, ArchetypeConvention, type ArchetypeFamilyFit, type ArchetypePerfMap, type ArchetypePerfNMap, type ArchetypePerfScoreResult, type AttachCacheControlResult, BRAIN_READ_ENV_NAMES, BestPracticeAdvisory, type BrainConfig, type BrainDeadLetterEntry, type BrainHealthSnapshot, type BrainQueryConfig, type BrainReadEnv, COACH_CFG, CallOptions, CallResult, ChainEntry, type CompatibilityIntent, type CompileForAISDKv6Result, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, type CreateDelegateOpts, DECOMPOSITION_TEMPLATES, DECOMPOSITION_TEMPLATES_VERSION, DEFAULT_FINDINGS_ENDPOINT, DEFAULT_MEASURED_FAILURE_ENDPOINT, DEFAULT_PROMOTIONS_ENDPOINT, DELEGATE_TOOL_DEFINITION, DISCIPLINE_GATES_V1_ALT_HEADER, type DecompositionPlan, type DecompositionStep, type DecompositionTemplate, type DelegateHandle, type DelegateRefusalReason, type DelegateResult, type DelegateToolArgs, type ExclusionFindingRow, type ExclusionResolutionSource, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type ExecutorCandidate, type FallbackPosture, FallbackReason, FamilyResolutionError, type GetActionableAdvisoriesOptions, type GetApplicablePromotionOpts, type GetDefaultFallbackChainOpts, type GetMeasuredFailureOpts, type GetPerAxisMetricsOpts, type GetRecommendedPrimaryOptions, type GoldenEvalAxis, type GoldenEvalCase, type GoldenEvalOptions, type GoldenEvalRunResult, type GoldenEvalStrategyId, type GoldenIrRecordInput, Grounding, IntentArchetypeName, JUDGE_RUBRICS, LIBRARY_VERSION, type LLMJudgeOptions, MEASURED_FAILURE_CFG, MEASURED_GROUNDING_MIN_N, type MarkAdvisoryResolvedOptions, type MarkExclusionFindingHandledOptions, type MarkPromoteReadyHandledOptions, type MeasuredFailureRuntime, type MeasuredFailureVerdict, type ModelBrainRow, type ModelCompatibility, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, OutputMode, PRODUCER_OWNED_RULE_CODES, PROVIDER_ENV_KEYS, PerAxisMetrics, type PlannedStep, type PricingRow, type ProbeShadowOptions, type ProbeShadowServed, type ProfileToRowOptions, type PromoteReadyFindingRow, type PromoteReadyResolution, type PromotionRow, type PromotionsRuntime, PromptIR, Provider, ProviderOverrides, type ProviderReachability, ROLLBACK_SUPPRESSION_WINDOW_DAYS, RULE_DISCIPLINE_GATES_V1, RULE_DISCIPLINE_GATES_V1_STRUCTURED, RULE_SEQUENTIAL_TOOL_CLIFF, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, STRATEGY_AUTHORSHIP_LIMITATION, SectionRewrite, type ShadowProbeRecordInput, type StrategyAttribution, type StrategyAttributionResult, type StrategyOutcome, type SupportedProvider, type SurfaceFailureRow, type SurfaceStats, SystemModelMessage, TRANSLATOR_FLOOR, _testResetMeasuredFailure, _testResetPromotions, _testWaitForMeasuredFailureRefresh, _testWaitForPromotionsRefresh, altGatesBlockFor, applyArchetypeConvention, applySectionRewrites, attachCacheControlToStreamTextInput, awaitMeasuredFailureReady, brainHealth, buildGoldenIrRow, buildLLMJudge, buildPairwiseJudgePrompt, buildShadowProbeRow, call, classifyStrategyOutcome, clearBrain, combineOrderSwappedVerdicts, compile, compileForAISDKv6, configureBrain, configureMeasuredFailureBrain, configurePromotionsBrain, countTokens, createDelegate, deriveFamilyFromModelId, deriveOwnership, execute, findBetterFit, flushBrainDeadLetter, getActionableAdvisories, getAllStarterChains, getAllStarterChainsWithGrounding, getApplicablePromotion, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getMeasuredFailureVerdict, getModelCompatibility, getPerAxisMetrics, getReachabilityDiagnostic, getRecentRollback, getRecommendedPrimary, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStaleExclusionFindings, getStarterChain, getStarterChainWithGrounding, isAutoPromoteEnabledFromEnv, isBrainQueryActiveFor, isBrainSync, isDelegateEnabledFromEnv, isExclusionFindingsBrainActive, isMeasuredFailureBrainActive, isMeasuredFailureGateEnabledFromEnv, isModelReachable, isPromotionsBrainActive, isProviderReachable, judgeMeasuredFailure, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, mapMeasuredFailureRows, markAdvisoryResolved, markExclusionFindingHandled, markPromoteReadyHandled, parseJudgeVerdict, peekBrainDeadLetter, planDecomposition, prefetchMeasuredFailure, probeShadow, profileToRow, readBrainReadEnv, record, recordGoldenIr, recordOutcome, recordShadowProbe, renderIrForJudge, resetTokenizer, resolveConventionsForProfile, resolvePricingAt, resolveProviderKey, rubricFor, runAdvisor, runGoldenEval, runStrategyEvalWithAttribution, setTokenizer, wilsonLowerBound, withAltDisciplineContract, withDisciplineContract };

package/dist/index.js

@@ -33,6 +33,7 @@ __export(index_exports, {
   DEFAULT_FINDINGS_ENDPOINT: () => DEFAULT_FINDINGS_ENDPOINT,
   DEFAULT_MEASURED_FAILURE_ENDPOINT: () => DEFAULT_MEASURED_FAILURE_ENDPOINT,
   DEFAULT_PROMOTIONS_ENDPOINT: () => DEFAULT_PROMOTIONS_ENDPOINT,
+  DELEGATE_TOOL_DEFINITION: () => DELEGATE_TOOL_DEFINITION,
   DIALECT_VERSION: () => DIALECT_VERSION,
   DISCIPLINE_GATES_V1_ALT_HEADER: () => DISCIPLINE_GATES_V1_ALT_HEADER,
   FamilyResolutionError: () => FamilyResolutionError,
@@ -80,6 +81,7 @@ __export(index_exports, {
   configurePromotionsBrain: () => configurePromotionsBrain,
   countTokens: () => countTokens,
   createBrainForwardRoutes: () => createBrainForwardRoutes,
+  createDelegate: () => createDelegate,
   createKeyHealthRoute: () => createKeyHealthRoute,
   deriveFamilyFromModelId: () => deriveFamilyFromModelId,
   deriveOwnership: () => deriveOwnership,
@@ -111,6 +113,7 @@ __export(index_exports, {
   isAutoPromoteEnabledFromEnv: () => isAutoPromoteEnabledFromEnv,
   isBrainQueryActiveFor: () => isBrainQueryActiveFor,
   isBrainSync: () => isBrainSync,
+  isDelegateEnabledFromEnv: () => isDelegateEnabledFromEnv,
   isExclusionFindingsBrainActive: () => isExclusionFindingsBrainActive,
   isMeasuredFailureBrainActive: () => isMeasuredFailureBrainActive,
   isMeasuredFailureGateEnabledFromEnv: () => isMeasuredFailureGateEnabledFromEnv,
@@ -9312,7 +9315,7 @@ function createBrainForwardRoutes(config) {
 }
 
 // src/version.ts
-var LIBRARY_VERSION = "2.0.0-alpha.78";
+var LIBRARY_VERSION = "2.0.0-alpha.79";
 
 // src/key-health.ts
 var JSON_HEADERS2 = { "Content-Type": "application/json" };
@@ -9598,6 +9601,171 @@ function clamp(n) {
   return Math.max(0, Math.min(1, n));
 }
 
+// src/delegate.ts
+function isDelegateEnabledFromEnv(envSource) {
+  const env = envSource ?? (typeof process !== "undefined" && process.env ? process.env : {});
+  const raw = (env.KGAUTO_DELEGATE ?? "").trim().toLowerCase();
+  return raw === "1" || raw === "true";
+}
+var DELEGATE_TOOL_DEFINITION = {
+  name: "delegate",
+  description: "Delegate a self-contained sub-task to a cheaper executor model chosen by kgauto from measured evidence. YOU decide what to delegate and supply a complete input; kgauto decides which model runs it (never outside the declared pool). The call may be refused (budget exhausted, no qualified executor) \u2014 on refusal, continue and compose with what you have. Verify sub-results before composing them into your answer; do not present unverified delegated content as checked.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      sub_archetype: {
+        type: "string",
+        enum: ALL_ARCHETYPES,
+        description: "What kind of work the sub-task is (its routing archetype)."
+      },
+      input: {
+        type: "string",
+        description: "Complete, self-contained sub-task input. Include everything the executor needs \u2014 it sees nothing else."
+      },
+      quality_floor: {
+        type: "number",
+        minimum: 0,
+        maximum: 10,
+        description: "Optional minimum executor quality score (0-10) for this archetype. Omit to accept the evidence-ranked default."
+      }
+    },
+    required: ["sub_archetype", "input"],
+    additionalProperties: false
+  }
+};
+function createDelegate(opts) {
+  const { parentIr, parentHandle } = opts;
+  const enabled = opts.enabled ?? isDelegateEnabledFromEnv();
+  const budget = opts.callOpts?.policy?.maxCostPerTraceUsd;
+  let spentUsd = 0;
+  async function handler(args) {
+    if (!enabled) {
+      return {
+        ok: false,
+        reason: "delegate_not_enabled",
+        detail: "Delegation is not enabled for this consumer (KGAUTO_DELEGATE / CreateDelegateOpts.enabled). Do the sub-task yourself."
+      };
+    }
+    const archetype = args.sub_archetype;
+    if (!ALL_ARCHETYPES.includes(archetype)) {
+      return {
+        ok: false,
+        reason: "invalid_sub_archetype",
+        detail: `Unknown sub_archetype '${String(args.sub_archetype)}'. Valid: ${ALL_ARCHETYPES.join(", ")}. Re-classify or do the sub-task yourself.`
+      };
+    }
+    const pool = parentIr.models;
+    const concreteIds = pool.filter((m) => typeof m === "string");
+    let blockedByFloor = [];
+    if (typeof args.quality_floor === "number") {
+      blockedByFloor = concreteIds.filter(
+        (m) => getArchetypePerfScore(m, archetype).score < args.quality_floor
+      );
+      if (blockedByFloor.length === pool.length) {
+        const scores = concreteIds.map((m) => `${m}=${getArchetypePerfScore(m, archetype).score}`).join(", ");
+        return {
+          ok: false,
+          reason: "no_qualified_executor",
+          detail: `No model in the declared pool clears quality_floor=${args.quality_floor} for '${archetype}' (${scores}). Lower the floor or do the sub-task yourself.`
+        };
+      }
+    }
+    const subIr = {
+      appId: parentIr.appId,
+      intent: { name: `delegate:${archetype}`, archetype },
+      sections: [{ id: "delegated-task", text: args.input }],
+      currentTurn: { role: "user", content: args.input },
+      models: pool
+    };
+    const mergedPolicy = {
+      ...opts.callOpts?.policy ?? {},
+      blockedModels: [
+        ...opts.callOpts?.policy?.blockedModels ?? [],
+        ...blockedByFloor
+      ]
+    };
+    if (typeof budget === "number" && budget > 0) {
+      let estimate = 0;
+      try {
+        estimate = compile(subIr, { policy: mergedPolicy }).estimatedCostUsd;
+      } catch {
+        estimate = 0;
+      }
+      if (spentUsd + estimate > budget) {
+        return {
+          ok: false,
+          reason: "trace_budget_exhausted",
+          detail: `Trace budget $${budget.toFixed(4)} would be exceeded (spent $${spentUsd.toFixed(4)} + estimated $${estimate.toFixed(4)}). Compose your answer from the sub-results you already have.`
+        };
+      }
+    }
+    let result;
+    try {
+      result = await call(subIr, {
+        ...opts.callOpts ?? {},
+        policy: mergedPolicy,
+        parentHandle
+        // R0 linkage — branch row, trace_id = parent
+      });
+    } catch (err) {
+      const detail = err instanceof CallError ? `Sub-call failed after ${err.attempts.length} attempt(s): ${err.attempts.map((a) => a.errorCode).join(" \u2192 ")}.` : String(err);
+      return {
+        ok: false,
+        reason: "call_failed",
+        detail: `${detail} Compose without this sub-result or retry with different input.`
+      };
+    }
+    const profile = tryGetProfile(result.actualModel);
+    const costUsd2 = profile ? result.response.tokens.input / 1e6 * profile.costInputPer1m + result.response.tokens.output / 1e6 * profile.costOutputPer1m : 0;
+    spentUsd += costUsd2;
+    return {
+      ok: true,
+      output: result.response.structuredOutput !== null ? JSON.stringify(result.response.structuredOutput) : result.response.text,
+      subHandle: result.handle,
+      executorModel: result.actualModel,
+      costUsd: costUsd2,
+      latencyMs: result.latencyMs,
+      verification: "trusted"
+    };
+  }
+  async function reportComposition(report) {
+    const env = readBrainReadEnv();
+    if (!env.endpoint || !env.jwt || !env.anonKey) {
+      return { ok: false, reason: `brain_read_not_configured:${env.missingEnv.join(",")}` };
+    }
+    try {
+      const res = await fetch(
+        `${env.endpoint.replace(/\/$/, "")}/rest/v1/kgauto_composition_reports`,
+        {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${env.jwt}`,
+            apikey: env.anonKey,
+            "Content-Type": "application/json",
+            Prefer: "return=minimal"
+          },
+          body: JSON.stringify({
+            app_id: parentIr.appId,
+            sub_handle: report.subHandle,
+            disposition: report.disposition,
+            ...report.note ? { note: report.note } : {}
+          })
+        }
+      );
+      if (!res.ok) return { ok: false, reason: `write_failed:${res.status}` };
+      return { ok: true };
+    } catch (err) {
+      return { ok: false, reason: `network_error:${err instanceof Error ? err.message : String(err)}` };
+    }
+  }
+  return {
+    toolDefinition: DELEGATE_TOOL_DEFINITION,
+    handler,
+    reportComposition,
+    traceSpendUsd: () => spentUsd
+  };
+}
+
 // src/advisories-api.ts
 var SEVERITY_SET = /* @__PURE__ */ new Set(["info", "warn", "critical"]);
 var STATUS_SET = /* @__PURE__ */ new Set(["open", "snoozed", "resolved"]);
@@ -10197,6 +10365,7 @@ function compile2(ir, opts) {
   DEFAULT_FINDINGS_ENDPOINT,
   DEFAULT_MEASURED_FAILURE_ENDPOINT,
   DEFAULT_PROMOTIONS_ENDPOINT,
+  DELEGATE_TOOL_DEFINITION,
   DIALECT_VERSION,
   DISCIPLINE_GATES_V1_ALT_HEADER,
   FamilyResolutionError,
@@ -10244,6 +10413,7 @@ function compile2(ir, opts) {
   configurePromotionsBrain,
   countTokens,
   createBrainForwardRoutes,
+  createDelegate,
   createKeyHealthRoute,
   deriveFamilyFromModelId,
   deriveOwnership,
@@ -10275,6 +10445,7 @@ function compile2(ir, opts) {
   isAutoPromoteEnabledFromEnv,
   isBrainQueryActiveFor,
   isBrainSync,
+  isDelegateEnabledFromEnv,
   isExclusionFindingsBrainActive,
   isMeasuredFailureBrainActive,
   isMeasuredFailureGateEnabledFromEnv,

package/dist/index.mjs

@@ -16,7 +16,7 @@ import {
 import {
   LIBRARY_VERSION,
   createKeyHealthRoute
-} from "./chunk-QVD2QWST.mjs";
+} from "./chunk-DRYCOR6G.mjs";
 import {
   ABSOLUTE_FLOOR,
   ARCHETYPE_FLOOR_DEFAULT,
@@ -6343,6 +6343,171 @@ function clamp(n) {
   return Math.max(0, Math.min(1, n));
 }
 
+// src/delegate.ts
+function isDelegateEnabledFromEnv(envSource) {
+  const env = envSource ?? (typeof process !== "undefined" && process.env ? process.env : {});
+  const raw = (env.KGAUTO_DELEGATE ?? "").trim().toLowerCase();
+  return raw === "1" || raw === "true";
+}
+var DELEGATE_TOOL_DEFINITION = {
+  name: "delegate",
+  description: "Delegate a self-contained sub-task to a cheaper executor model chosen by kgauto from measured evidence. YOU decide what to delegate and supply a complete input; kgauto decides which model runs it (never outside the declared pool). The call may be refused (budget exhausted, no qualified executor) \u2014 on refusal, continue and compose with what you have. Verify sub-results before composing them into your answer; do not present unverified delegated content as checked.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      sub_archetype: {
+        type: "string",
+        enum: ALL_ARCHETYPES,
+        description: "What kind of work the sub-task is (its routing archetype)."
+      },
+      input: {
+        type: "string",
+        description: "Complete, self-contained sub-task input. Include everything the executor needs \u2014 it sees nothing else."
+      },
+      quality_floor: {
+        type: "number",
+        minimum: 0,
+        maximum: 10,
+        description: "Optional minimum executor quality score (0-10) for this archetype. Omit to accept the evidence-ranked default."
+      }
+    },
+    required: ["sub_archetype", "input"],
+    additionalProperties: false
+  }
+};
+function createDelegate(opts) {
+  const { parentIr, parentHandle } = opts;
+  const enabled = opts.enabled ?? isDelegateEnabledFromEnv();
+  const budget = opts.callOpts?.policy?.maxCostPerTraceUsd;
+  let spentUsd = 0;
+  async function handler(args) {
+    if (!enabled) {
+      return {
+        ok: false,
+        reason: "delegate_not_enabled",
+        detail: "Delegation is not enabled for this consumer (KGAUTO_DELEGATE / CreateDelegateOpts.enabled). Do the sub-task yourself."
+      };
+    }
+    const archetype = args.sub_archetype;
+    if (!ALL_ARCHETYPES.includes(archetype)) {
+      return {
+        ok: false,
+        reason: "invalid_sub_archetype",
+        detail: `Unknown sub_archetype '${String(args.sub_archetype)}'. Valid: ${ALL_ARCHETYPES.join(", ")}. Re-classify or do the sub-task yourself.`
+      };
+    }
+    const pool = parentIr.models;
+    const concreteIds = pool.filter((m) => typeof m === "string");
+    let blockedByFloor = [];
+    if (typeof args.quality_floor === "number") {
+      blockedByFloor = concreteIds.filter(
+        (m) => getArchetypePerfScore(m, archetype).score < args.quality_floor
+      );
+      if (blockedByFloor.length === pool.length) {
+        const scores = concreteIds.map((m) => `${m}=${getArchetypePerfScore(m, archetype).score}`).join(", ");
+        return {
+          ok: false,
+          reason: "no_qualified_executor",
+          detail: `No model in the declared pool clears quality_floor=${args.quality_floor} for '${archetype}' (${scores}). Lower the floor or do the sub-task yourself.`
+        };
+      }
+    }
+    const subIr = {
+      appId: parentIr.appId,
+      intent: { name: `delegate:${archetype}`, archetype },
+      sections: [{ id: "delegated-task", text: args.input }],
+      currentTurn: { role: "user", content: args.input },
+      models: pool
+    };
+    const mergedPolicy = {
+      ...opts.callOpts?.policy ?? {},
+      blockedModels: [
+        ...opts.callOpts?.policy?.blockedModels ?? [],
+        ...blockedByFloor
+      ]
+    };
+    if (typeof budget === "number" && budget > 0) {
+      let estimate = 0;
+      try {
+        estimate = compile(subIr, { policy: mergedPolicy }).estimatedCostUsd;
+      } catch {
+        estimate = 0;
+      }
+      if (spentUsd + estimate > budget) {
+        return {
+          ok: false,
+          reason: "trace_budget_exhausted",
+          detail: `Trace budget $${budget.toFixed(4)} would be exceeded (spent $${spentUsd.toFixed(4)} + estimated $${estimate.toFixed(4)}). Compose your answer from the sub-results you already have.`
+        };
+      }
+    }
+    let result;
+    try {
+      result = await call(subIr, {
+        ...opts.callOpts ?? {},
+        policy: mergedPolicy,
+        parentHandle
+        // R0 linkage — branch row, trace_id = parent
+      });
+    } catch (err) {
+      const detail = err instanceof CallError ? `Sub-call failed after ${err.attempts.length} attempt(s): ${err.attempts.map((a) => a.errorCode).join(" \u2192 ")}.` : String(err);
+      return {
+        ok: false,
+        reason: "call_failed",
+        detail: `${detail} Compose without this sub-result or retry with different input.`
+      };
+    }
+    const profile = tryGetProfile(result.actualModel);
+    const costUsd2 = profile ? result.response.tokens.input / 1e6 * profile.costInputPer1m + result.response.tokens.output / 1e6 * profile.costOutputPer1m : 0;
+    spentUsd += costUsd2;
+    return {
+      ok: true,
+      output: result.response.structuredOutput !== null ? JSON.stringify(result.response.structuredOutput) : result.response.text,
+      subHandle: result.handle,
+      executorModel: result.actualModel,
+      costUsd: costUsd2,
+      latencyMs: result.latencyMs,
+      verification: "trusted"
+    };
+  }
+  async function reportComposition(report) {
+    const env = readBrainReadEnv();
+    if (!env.endpoint || !env.jwt || !env.anonKey) {
+      return { ok: false, reason: `brain_read_not_configured:${env.missingEnv.join(",")}` };
+    }
+    try {
+      const res = await fetch(
+        `${env.endpoint.replace(/\/$/, "")}/rest/v1/kgauto_composition_reports`,
+        {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${env.jwt}`,
+            apikey: env.anonKey,
+            "Content-Type": "application/json",
+            Prefer: "return=minimal"
+          },
+          body: JSON.stringify({
+            app_id: parentIr.appId,
+            sub_handle: report.subHandle,
+            disposition: report.disposition,
+            ...report.note ? { note: report.note } : {}
+          })
+        }
+      );
+      if (!res.ok) return { ok: false, reason: `write_failed:${res.status}` };
+      return { ok: true };
+    } catch (err) {
+      return { ok: false, reason: `network_error:${err instanceof Error ? err.message : String(err)}` };
+    }
+  }
+  return {
+    toolDefinition: DELEGATE_TOOL_DEFINITION,
+    handler,
+    reportComposition,
+    traceSpendUsd: () => spentUsd
+  };
+}
+
 // src/advisories-api.ts
 var SEVERITY_SET = /* @__PURE__ */ new Set(["info", "warn", "critical"]);
 var STATUS_SET = /* @__PURE__ */ new Set(["open", "snoozed", "resolved"]);
@@ -6941,6 +7106,7 @@ export {
   DEFAULT_FINDINGS_ENDPOINT,
   DEFAULT_MEASURED_FAILURE_ENDPOINT,
   DEFAULT_PROMOTIONS_ENDPOINT,
+  DELEGATE_TOOL_DEFINITION,
   DIALECT_VERSION,
   DISCIPLINE_GATES_V1_ALT_HEADER,
   FamilyResolutionError,
@@ -6988,6 +7154,7 @@ export {
   configurePromotionsBrain,
   countTokens,
   createBrainForwardRoutes,
+  createDelegate,
   createKeyHealthRoute,
   deriveFamilyFromModelId,
   deriveOwnership,
@@ -7019,6 +7186,7 @@ export {
   isAutoPromoteEnabledFromEnv,
   isBrainQueryActiveFor,
   isBrainSync,
+  isDelegateEnabledFromEnv,
   isExclusionFindingsBrainActive,
   isMeasuredFailureBrainActive,
   isMeasuredFailureGateEnabledFromEnv,

package/dist/key-health.js

@@ -25,7 +25,7 @@ __export(key_health_exports, {
 module.exports = __toCommonJS(key_health_exports);
 
 // src/version.ts
-var LIBRARY_VERSION = "2.0.0-alpha.78";
+var LIBRARY_VERSION = "2.0.0-alpha.79";
 
 // src/key-health.ts
 var JSON_HEADERS = { "Content-Type": "application/json" };

package/dist/key-health.mjs

@@ -1,6 +1,6 @@
 import {
   createKeyHealthRoute
-} from "./chunk-QVD2QWST.mjs";
+} from "./chunk-DRYCOR6G.mjs";
 export {
   createKeyHealthRoute
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warmdrift/kgauto-compiler",
-  "version": "2.0.0-alpha.78",
+  "version": "2.0.0-alpha.79",
   "description": "Prompt compiler with executable provider knowledge for multi-model AI apps: normalized multi-provider transport with fallback chains, compile-time cliff guards, a curated model registry, and a telemetry flight recorder. Swap models without rewriting prompts.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",