@kontourai/flow-agents 3.12.1 → 4.0.0

package/build/src/index.d.ts

@@ -1,13 +1,44 @@
+export { NARRATIVE_SOURCE_ID_VERSION, SourceIdParseError, compareSourceIds, formatSourceId, parseSourceId, } from "./narrative/source-ids.js";
+export type { AgentEventSourceId, ChainedCommandLogSourceId, CommandLogSourceId, FileSourceId, FlowReportSourceId, FlowStateSourceId, FlowTransitionSourceId, LegacyCommandLogSourceId, NarrativeSourceId, NarrativeSourceStream, SourceIdErrorCode, SurfaceExplanationSourceId, TelemetrySourceId, TranscriptSourceId, TrustSourceId, } from "./narrative/source-ids.js";
+export { DEFAULT_INTEGRITY_CLASS, KNOWN_CAPTURE_GAPS, buildCaptureCompleteness, integrityClassForSource, } from "./narrative/integrity.js";
+export type { CaptureChannelStatus, CaptureCompleteness, IntegrityClass, KnownGapClass, UnavailableReason, } from "./narrative/integrity.js";
+export { TELEMETRY_CHANNEL_ANALYTICS_REDACT_DEFAULT, TELEMETRY_CHANNEL_FULL_REDACT_DEFAULT, effectiveNarrativeRedactionFields, filterNarrativeRecord, } from "./narrative/policy-filter.js";
+export type { NarrativePolicyFilterResult } from "./narrative/policy-filter.js";
+export { snapshotNarrative, validateNarrativeSourceManifest } from "./narrative/snapshot.js";
+export type { NarrativeLineageEvent, NarrativeSourceManifest, NarrativeSourceManifestEntry, NarrativeSourceOrigin, NarrativeSourceRequest, NarrativeSourceRoots, SnapshotNarrativeDependencies, SnapshotNarrativeInput, } from "./narrative/snapshot.js";
+export { resolveManifestEntry, resolveSource, verifyManifest } from "./narrative/resolver.js";
+export type { FrozenManifestEntry, ResolveSourceOptions, ResolveSourceResult, VerifyManifestReport } from "./narrative/resolver.js";
+export { NARRATIVE_RUNTIME_PROJECTION_SCHEMA_VERSION, NARRATIVE_RUNTIME_PROJECTOR, NarrativeProjectionError, projectRuntimeNarrative, stableStringify, validateNarrativeRuntimeProjection, } from "./narrative/projection.js";
+export { GROUNDED_EXECUTION_NARRATIVE_COMPILER_NAME, GROUNDED_EXECUTION_NARRATIVE_SCHEMA_VERSION, GroundedNarrativeError, composeGroundedNarrative, validateGroundedNarrative, writeEnvelope, } from "./narrative/envelope.js";
+export { renderGroundedNarrative } from "./narrative/render.js";
+export type { GroundedExecutionNarrative, GroundedNarrativeConclusion, GroundedNarrativeConfig, GroundedNarrativeCorrelation, GroundedNarrativeErrorCode, GroundedNarrativeFlowTransition, GroundedNarrativeForeignSection, GroundedNarrativeRule, GroundedNarrativeRuntimeSection, GroundedNarrativeSection, SchemaIssue as GroundedNarrativeSchemaIssue, WriteEnvelopeOptions, WrittenGroundedNarrative, } from "./narrative/envelope.js";
+export type { NarrativeRuntimeProjection, NarrativeProjectionErrorCode, ProjectRuntimeNarrativeOptions, RuntimePurpose, RuntimeProjectionTurn, } from "./narrative/projection.js";
+export { QUARANTINE_SESSION_ID, TURN_SPINE_RULE_ID, buildTurnSpine } from "./narrative/turn-spine.js";
+export type { ResolvedTelemetryRecord, Turn, TurnBoundary } from "./narrative/turn-spine.js";
+export { AGENT_STATED_ACTOR_MAX_LENGTH, AGENT_STATED_PURPOSE_MAX_LENGTH, NarrativeStatementError, agentStatedIntent, derivedNoOpTurn, derivedRetry, derivedTimeout, derivedUnavailableSource, observedCommand, observedDelegation, observedFileCreation, observedToolAction, summarizerInferredConnective, workflowDerivedPurpose, } from "./narrative/statements.js";
+export type { NarrativeStatementErrorCode, ObservedResult, Statement, StatementClass, StatementRule, } from "./narrative/statements.js";
+export { INTENT_ANNOTATION_FILE, INTENT_ANNOTATION_SCHEMA_VERSION, bindIntentAnnotation, captureIntent, } from "./narrative/intent.js";
+export type { CaptureIntentDependencies, CaptureIntentInput, CapturedIntent, IntentAnnotation, IntentCapabilityStatus, IntentCaptureMode, } from "./narrative/intent.js";
+export { INTENT_ECONOMICS_FILE, appendIntentEconomics, readIntentEconomics, reduceIntentEconomics, } from "./narrative/intent-economics.js";
+export type { IntentAnnotationMode, IntentEconomicsDelta, IntentEconomicsRecord, IntentEconomicsSummary, } from "./narrative/intent-economics.js";
+export { entailmentIndependenceHolds, isAssertionProhibited, materialEventCoverage, NarrativeGroundingError, validateNarrativeGrounding, } from "./narrative/grounding-validator.js";
+export type { AssertionKind, EntailmentIdentity, EntailmentProvenance, EntailmentVerdict, GroundingKnownGap, GroundingViolation, GroundingViolationCode, GroundingVerdict, MaterialEventClassCoverage, MaterialEventCoverage, MaterialEventKind, ValidateNarrativeGroundingOptions, } from "./narrative/grounding-validator.js";
+export { NARRATIVE_EVAL_RESULT_SCHEMA_VERSION, validateNarrativeEvalResult, } from "./narrative/eval-result.js";
+export type { NarrativeEvalCapabilityParity, NarrativeEvalFixtureResult, NarrativeEvalKnownGap, NarrativeEvalMetricUncertainty, NarrativeEvalMetrics, NarrativeEvalRawSourceLink, NarrativeEvalResult, NarrativeEvalVerdict, SchemaIssue as NarrativeEvalResultSchemaIssue, } from "./narrative/eval-result.js";
+export { GeneratorTimeoutError, PROSE_ECONOMICS_FILE, PROSE_PROMPT_VERSION, ProviderNotAllowedError, hostedModelGenerator, localModelGenerator, providerAllowed, renderProse, stubGenerator, } from "./cli/narrative-render.js";
+export type { GeneratedProse, ModelGeneratorConfig, ProseEconomicsRecord, ProseGenerator, ProseGeneratorInput, ProseGeneratorSentence, ProseGeneratorUsage, ProseRenderOutcome, ProseSourceView, ProviderConfig, ProviderOptIn, RenderProseOptions, RenderProseResult, } from "./cli/narrative-render.js";
 export { BUILDER_BUILD_FLOW_ID, BUILDER_BUILD_FLOW_RELATIVE_PATH, BuilderBuildRunInputError, BuilderBuildRunIdentityError, evaluateBuilderBuildRun, loadBuilderBuildRun, resolveBuilderBuildFlowDefinitionPath, startBuilderBuildRun, } from "./builder-flow-run-adapter.js";
 export type { BuilderBuildRunResult, BuilderBuildRunIdentityMismatch, BuilderBuildTrustBundleEvidenceInput, EvaluateBuilderBuildRunInput, LoadBuilderBuildRunInput, StartBuilderBuildRunInput, } from "./builder-flow-run-adapter.js";
 export { archiveBuilderFlowSession, cancelBuilderFlowSession, pauseBuilderFlowSession, recoverBuilderFlowSession, releaseBuilderFlowAssignment, resumeBuilderFlowSession, startBuilderFlowSession, syncBuilderFlowSession, } from "./builder-flow-runtime.js";
 export type { BuilderFlowAgentLifecycleInput, BuilderFlowAuthorizedLifecycleInput, BuilderFlowSessionInput, BuilderFlowSessionResult } from "./builder-flow-runtime.js";
 export { deriveBuilderGateActionEnvelope, gateActionProgressSnapshot, withGateActionPriorProgress, } from "./builder-gate-action-envelope.js";
-export type { BuilderGateActionEnvelopeInput, GateActionEnvelope, GateActionInterfaceParameter, GateActionPriorProgress, GateActionProgressSnapshot, GateActionPublicMutation, } from "./builder-gate-action-envelope.js";
+export type { BuilderGateActionEnvelopeInput, GateActionArtifactBinding, GateActionArtifactTarget, GateActionEnvelope, GateActionInterfaceParameter, GateActionPriorProgress, GateActionProgressSnapshot, GateActionPublicMutation, } from "./builder-gate-action-envelope.js";
 export { ContinuationAdapterTimeoutError, MAX_CONTINUATION_ADAPTER_EVIDENCE_BYTES, MAX_CONTINUATION_TURN_RESULT_BYTES, createFileContinuationStore, driveBuilderFlowSession, runContinuationDriver, withContinuationDriverLock, } from "./continuation-driver.js";
-export type { ContinuationBarrier, ContinuationAcceptedTurn, ContinuationDriverEvent, ContinuationDriverLockLease, ContinuationDriverOutcome, ContinuationDriverState, ContinuationRuntimePort, ContinuationSnapshot, ContinuationStateStore, ContinuationTurnAuthority, ContinuationTurnContext, ContinuationTurnRequest, ContinuationTurnResult, DriveBuilderFlowSessionInput, RunContinuationDriverInput, } from "./continuation-driver.js";
+export type { ContinuationBarrier, ContinuationContextPolicy, ContinuationContextStrategy, ContinuationAcceptedTurn, ContinuationDriverEvent, ContinuationDriverLockLease, ContinuationDriverOutcome, ContinuationDriverState, ContinuationRuntimePort, ContinuationSnapshot, ContinuationStateStore, ContinuationTurnAuthority, ContinuationTurnContext, ContinuationTurnRequest, ContinuationTurnResult, DriveBuilderFlowSessionInput, RunContinuationDriverInput, } from "./continuation-driver.js";
 export { builderLifecycleAuthorizationPayload, loadBuilderLifecycleAuthorization } from "./builder-lifecycle-authority.js";
 export type { BuilderLifecycleAuthorization } from "./builder-lifecycle-authority.js";
+export { CAPABILITIES, RUNTIME_ADAPTER_IDS, RUNTIME_CAPABILITY_DECLARATIONS, RUNTIME_ID_ALIASES, getDeclaration, normalizeRuntimeId, queryCapability, } from "./lib/capability-declarations.js";
+export type { Capability, CapabilityStatus, RuntimeAdapterId, RuntimeCapabilityDeclaration, } from "./lib/capability-declarations.js";
 export { defaultArtifactRootForRead, defaultCodexHome, defaultTelemetryDirForRead, defaultTelemetryDirsForRead, durableFlowAgentsRoot, durableInstallRecordPath, DURABLE_FLOW_AGENTS_DIR, FLOW_AGENTS_RUNTIME_DIR, FLOW_AGENTS_RUNTIME_SUBDIR, firstExistingPath, flowAgentsArtifactRoot, KONTOURAI_DIR, legacyTelemetryDataDir, LEGACY_TELEMETRY_DIR, telemetryDataDir, } from "./lib/local-artifact-root.js";
 export { validateTrustBundle, normalizeCheck, normalizeFinding, normalizeLearning, normalizeEvidenceRefs, validateEvidenceRef, validateLearningCorrection, loadJson, writeJson, appendJsonl, sidecarBase, writeState, statuses, phases, checkKinds, checkStatuses, verdicts, } from "./cli/workflow-sidecar.js";
 /** Read a sidecar JSON file from a workflow artifact directory; returns `{}` if absent. */

package/build/src/index.js

@@ -13,6 +13,29 @@
  */
 import * as path from "node:path";
 import { loadJson as _loadJson, writeJson as _writeJson } from "./cli/workflow-sidecar.js";
+export { NARRATIVE_SOURCE_ID_VERSION, SourceIdParseError, compareSourceIds, formatSourceId, parseSourceId, } from "./narrative/source-ids.js";
+export { DEFAULT_INTEGRITY_CLASS, KNOWN_CAPTURE_GAPS, buildCaptureCompleteness, integrityClassForSource, } from "./narrative/integrity.js";
+export { TELEMETRY_CHANNEL_ANALYTICS_REDACT_DEFAULT, TELEMETRY_CHANNEL_FULL_REDACT_DEFAULT, effectiveNarrativeRedactionFields, filterNarrativeRecord, } from "./narrative/policy-filter.js";
+export { snapshotNarrative, validateNarrativeSourceManifest } from "./narrative/snapshot.js";
+export { resolveManifestEntry, resolveSource, verifyManifest } from "./narrative/resolver.js";
+export { NARRATIVE_RUNTIME_PROJECTION_SCHEMA_VERSION, NARRATIVE_RUNTIME_PROJECTOR, NarrativeProjectionError, projectRuntimeNarrative, stableStringify, validateNarrativeRuntimeProjection, } from "./narrative/projection.js";
+export { GROUNDED_EXECUTION_NARRATIVE_COMPILER_NAME, GROUNDED_EXECUTION_NARRATIVE_SCHEMA_VERSION, GroundedNarrativeError, composeGroundedNarrative, validateGroundedNarrative, writeEnvelope, } from "./narrative/envelope.js";
+export { renderGroundedNarrative } from "./narrative/render.js";
+export { QUARANTINE_SESSION_ID, TURN_SPINE_RULE_ID, buildTurnSpine } from "./narrative/turn-spine.js";
+export { AGENT_STATED_ACTOR_MAX_LENGTH, AGENT_STATED_PURPOSE_MAX_LENGTH, NarrativeStatementError, agentStatedIntent, derivedNoOpTurn, derivedRetry, derivedTimeout, derivedUnavailableSource, observedCommand, observedDelegation, observedFileCreation, observedToolAction, summarizerInferredConnective, workflowDerivedPurpose, } from "./narrative/statements.js";
+// #622: bounded, capability-declared at-action stated-intent capture + the
+// annotation-on/off A/B measurement with uncertainty.
+export { INTENT_ANNOTATION_FILE, INTENT_ANNOTATION_SCHEMA_VERSION, bindIntentAnnotation, captureIntent, } from "./narrative/intent.js";
+export { INTENT_ECONOMICS_FILE, appendIntentEconomics, readIntentEconomics, reduceIntentEconomics, } from "./narrative/intent-economics.js";
+export { entailmentIndependenceHolds, isAssertionProhibited, materialEventCoverage, NarrativeGroundingError, validateNarrativeGrounding, } from "./narrative/grounding-validator.js";
+// #612: consolidated grounded-narrative eval-result schema + ajv-free validator.
+// The shared, versioned package (corpus.json + this result schema) consumed by
+// kontourai/evals#95 unmodified (R6/AC6).
+export { NARRATIVE_EVAL_RESULT_SCHEMA_VERSION, validateNarrativeEvalResult, } from "./narrative/eval-result.js";
+// #614: model-assisted prose renderer (display-only, fail-closed). Lives outside
+// src/narrative/ (I/O, provider gating, timeout orchestration; see narrative-render.ts's
+// header comment) but is exported here alongside the pure narrative primitives it composes.
+export { GeneratorTimeoutError, PROSE_ECONOMICS_FILE, PROSE_PROMPT_VERSION, ProviderNotAllowedError, hostedModelGenerator, localModelGenerator, providerAllowed, renderProse, stubGenerator, } from "./cli/narrative-render.js";
 export { BUILDER_BUILD_FLOW_ID, BUILDER_BUILD_FLOW_RELATIVE_PATH, BuilderBuildRunInputError, BuilderBuildRunIdentityError, evaluateBuilderBuildRun, loadBuilderBuildRun, resolveBuilderBuildFlowDefinitionPath, startBuilderBuildRun, } from "./builder-flow-run-adapter.js";
 export { archiveBuilderFlowSession, cancelBuilderFlowSession, pauseBuilderFlowSession, recoverBuilderFlowSession, releaseBuilderFlowAssignment, resumeBuilderFlowSession, startBuilderFlowSession, syncBuilderFlowSession, } from "./builder-flow-runtime.js";
 export { deriveBuilderGateActionEnvelope, gateActionProgressSnapshot, withGateActionPriorProgress, } from "./builder-gate-action-envelope.js";
@@ -20,6 +43,7 @@ export { ContinuationAdapterTimeoutError, MAX_CONTINUATION_ADAPTER_EVIDENCE_BYTE
 // Pure serialization contract used by external lifecycle authorities when
 // signing requests. This does not load, create, or mutate a Flow run.
 export { builderLifecycleAuthorizationPayload, loadBuilderLifecycleAuthorization } from "./builder-lifecycle-authority.js";
+export { CAPABILITIES, RUNTIME_ADAPTER_IDS, RUNTIME_CAPABILITY_DECLARATIONS, RUNTIME_ID_ALIASES, getDeclaration, normalizeRuntimeId, queryCapability, } from "./lib/capability-declarations.js";
 export { defaultArtifactRootForRead, defaultCodexHome, defaultTelemetryDirForRead, defaultTelemetryDirsForRead, durableFlowAgentsRoot, durableInstallRecordPath, DURABLE_FLOW_AGENTS_DIR, FLOW_AGENTS_RUNTIME_DIR, FLOW_AGENTS_RUNTIME_SUBDIR, firstExistingPath, flowAgentsArtifactRoot, KONTOURAI_DIR, legacyTelemetryDataDir, LEGACY_TELEMETRY_DIR, telemetryDataDir, } from "./lib/local-artifact-root.js";
 export { 
 // Trust-bundle (Hachure) validation — the same validator the writer uses.

package/build/src/lib/capability-declarations.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Programmatic runtime capability declarations (#620).
+ *
+ * The single source of truth for "which agent-runtime telemetry capability does
+ * each shipped adapter expose". This replaces the hand-maintained coverage table
+ * in docs/specs/harness-capability-matrix.md and the hardcoded emitter `signals`
+ * literals: the matrix doc is GENERATED from this module (src/tools/
+ * generate-capability-matrix.ts) and the economics-record emitter derives its
+ * per_delegation_tokens signal from a build-only JSON projection of it.
+ *
+ * This module is the declaration/query MECHANISM only (issue #620). It does NOT
+ * measure declaration-vs-runtime reality (a NON-GOAL), and it does NOT implement
+ * the capabilities themselves (intent capture #622, trace propagation #425) — it
+ * declares whether each runtime exposes them so consumers can distinguish a real
+ * zero from a harness-blind gap, and returns a TYPED `unsupported` for an
+ * undeclared runtime or capability rather than a fabricated default.
+ *
+ * PURE: no fs / net / process imports. Safe to import from hooks, compilers,
+ * evals, and generators alike.
+ *
+ * @module
+ */
+/** The six declared per-runtime capabilities (R1/#620). */
+export declare const CAPABILITIES: readonly ["turn_id", "transcript_path", "intent_annotation", "per_delegation_trace_context", "per_delegation_tokens", "terminal_verdict"];
+export type Capability = (typeof CAPABILITIES)[number];
+/**
+ * The seven shipped adapters (R1). The first five are agent runtimes; the last
+ * two (codex-local, strands-local) are kit-ACTIVATION adapters on a different
+ * axis from agent-runtime telemetry — they declare their agent-runtime telemetry
+ * capabilities honestly (mostly `unsupported`), satisfying R1 literally without
+ * fabricating support they do not have.
+ */
+export declare const RUNTIME_ADAPTER_IDS: readonly ["claude-code", "codex", "kiro", "opencode", "pi", "codex-local", "strands-local"];
+export type RuntimeAdapterId = (typeof RUNTIME_ADAPTER_IDS)[number];
+/**
+ * Per-capability status as a discriminated union (D3). Richer than a bare
+ * boolean: `partial` carries a `note`, `unsupported` carries a `reason`, so R4's
+ * explicit `unsupported` sentinel always travels with a justification and a
+ * consumer never has to invent one.
+ */
+export type CapabilityStatus = {
+    readonly status: "supported";
+} | {
+    readonly status: "partial";
+    readonly note: string;
+} | {
+    readonly status: "unsupported";
+    readonly reason: string;
+};
+/** A runtime's full declaration: the canonical id + all six capability statuses. */
+export interface RuntimeCapabilityDeclaration {
+    readonly runtime: RuntimeAdapterId;
+    readonly capabilities: Readonly<Record<Capability, CapabilityStatus>>;
+}
+/**
+ * The canonical declaration data — the single source of truth. Every adapter
+ * declares ALL six capabilities explicitly (conformance-enforced; no defaulting).
+ */
+export declare const RUNTIME_CAPABILITY_DECLARATIONS: Readonly<Record<RuntimeAdapterId, RuntimeCapabilityDeclaration>>;
+/**
+ * Alias → canonical-runtime-id map (D1). The load-bearing entry is
+ * `kiro-cli → kiro`: the value `.agent.runtime` carries for Kiro is `kiro-cli`,
+ * but declarations are keyed on the canonical `kiro`. Keys are the already
+ * lowercased + whitespace-collapsed form.
+ */
+export declare const RUNTIME_ID_ALIASES: Readonly<Record<string, string>>;
+/**
+ * Normalize any raw runtime spelling to its canonical key (D1). Total + pure:
+ * trims, lowercases, collapses internal whitespace to hyphens, then folds known
+ * aliases (notably `kiro-cli → kiro`). Returns `""` for a null/blank input.
+ * The canonical id may still be undeclared (e.g. `base`) — that is intentional
+ * and resolves to a typed `unsupported` at query time, never a fabricated value.
+ */
+export declare function normalizeRuntimeId(raw: string | null | undefined): string;
+/** Return the full declaration for a runtime (after alias normalization), or `undefined`. */
+export declare function getDeclaration(runtimeId: string | null | undefined): RuntimeCapabilityDeclaration | undefined;
+/**
+ * Query a single capability for a runtime (D5). ALWAYS returns a typed
+ * `CapabilityStatus` — never `undefined`/`false`. An undeclared runtime OR an
+ * undeclared capability returns `{status:"unsupported", reason}` (R4): the
+ * JS-natural undefined/false fallback is exactly the fabrication R4 forbids.
+ */
+export declare function queryCapability(runtimeId: string | null | undefined, capability: string): CapabilityStatus;

package/build/src/lib/capability-declarations.js

@@ -0,0 +1,209 @@
+/**
+ * Programmatic runtime capability declarations (#620).
+ *
+ * The single source of truth for "which agent-runtime telemetry capability does
+ * each shipped adapter expose". This replaces the hand-maintained coverage table
+ * in docs/specs/harness-capability-matrix.md and the hardcoded emitter `signals`
+ * literals: the matrix doc is GENERATED from this module (src/tools/
+ * generate-capability-matrix.ts) and the economics-record emitter derives its
+ * per_delegation_tokens signal from a build-only JSON projection of it.
+ *
+ * This module is the declaration/query MECHANISM only (issue #620). It does NOT
+ * measure declaration-vs-runtime reality (a NON-GOAL), and it does NOT implement
+ * the capabilities themselves (intent capture #622, trace propagation #425) — it
+ * declares whether each runtime exposes them so consumers can distinguish a real
+ * zero from a harness-blind gap, and returns a TYPED `unsupported` for an
+ * undeclared runtime or capability rather than a fabricated default.
+ *
+ * PURE: no fs / net / process imports. Safe to import from hooks, compilers,
+ * evals, and generators alike.
+ *
+ * @module
+ */
+/** The six declared per-runtime capabilities (R1/#620). */
+export const CAPABILITIES = [
+    "turn_id",
+    "transcript_path",
+    "intent_annotation",
+    "per_delegation_trace_context",
+    "per_delegation_tokens",
+    "terminal_verdict",
+];
+/**
+ * The seven shipped adapters (R1). The first five are agent runtimes; the last
+ * two (codex-local, strands-local) are kit-ACTIVATION adapters on a different
+ * axis from agent-runtime telemetry — they declare their agent-runtime telemetry
+ * capabilities honestly (mostly `unsupported`), satisfying R1 literally without
+ * fabricating support they do not have.
+ */
+export const RUNTIME_ADAPTER_IDS = [
+    "claude-code",
+    "codex",
+    "kiro",
+    "opencode",
+    "pi",
+    "codex-local",
+    "strands-local",
+];
+// --- status constructors (local, keep the declaration table terse + honest) ---
+const supported = () => ({ status: "supported" });
+const partial = (note) => ({ status: "partial", note });
+const unsupported = (reason) => ({ status: "unsupported", reason });
+// Reasons shared across every adapter for the three capabilities that no runtime
+// exposes today (kept single-sourced so the declarations stay consistent).
+const NOT_IMPLEMENTED_INTENT = unsupported("Intent-annotation capture is not implemented on any runtime yet (#622).");
+const NOT_IMPLEMENTED_TRACE = unsupported("Per-delegation trace-context propagation is not implemented on any runtime yet (#425).");
+const NO_PER_DELEGATION_TOKENS = unsupported("No runtime isolates per-sub-agent token usage; per-delegation cost is attributed at (role, model) granularity instead.");
+const VERDICT_WORKFLOW_PARTIAL = partial("Captured only when the workflow records an evidence/verdict event for the sub-agent — not guaranteed every run.");
+const KIT_ADAPTER_TURN = (adapter) => unsupported(`${adapter} is a kit-activation adapter, not an agent-runtime telemetry source; it emits no per-turn agent-runtime telemetry.`);
+const KIT_ADAPTER_TRANSCRIPT = (adapter) => unsupported(`${adapter} is a kit-activation adapter and does not expose a per-session transcript path.`);
+const KIT_ADAPTER_VERDICT = (adapter) => unsupported(`${adapter} is a kit-activation adapter and does not surface per-sub-agent terminal verdicts.`);
+/**
+ * The canonical declaration data — the single source of truth. Every adapter
+ * declares ALL six capabilities explicitly (conformance-enforced; no defaulting).
+ */
+export const RUNTIME_CAPABILITY_DECLARATIONS = {
+    "claude-code": {
+        runtime: "claude-code",
+        capabilities: {
+            turn_id: supported(),
+            transcript_path: supported(),
+            intent_annotation: NOT_IMPLEMENTED_INTENT,
+            per_delegation_trace_context: NOT_IMPLEMENTED_TRACE,
+            per_delegation_tokens: NO_PER_DELEGATION_TOKENS,
+            terminal_verdict: VERDICT_WORKFLOW_PARTIAL,
+        },
+    },
+    codex: {
+        runtime: "codex",
+        capabilities: {
+            turn_id: supported(),
+            transcript_path: supported(),
+            intent_annotation: NOT_IMPLEMENTED_INTENT,
+            per_delegation_trace_context: NOT_IMPLEMENTED_TRACE,
+            per_delegation_tokens: NO_PER_DELEGATION_TOKENS,
+            terminal_verdict: unsupported("Codex does not surface a per-sub-agent terminal verdict to the orchestrator."),
+        },
+    },
+    kiro: {
+        runtime: "kiro",
+        capabilities: {
+            turn_id: supported(),
+            transcript_path: supported(),
+            intent_annotation: NOT_IMPLEMENTED_INTENT,
+            per_delegation_trace_context: NOT_IMPLEMENTED_TRACE,
+            per_delegation_tokens: NO_PER_DELEGATION_TOKENS,
+            terminal_verdict: VERDICT_WORKFLOW_PARTIAL,
+        },
+    },
+    opencode: {
+        runtime: "opencode",
+        capabilities: {
+            turn_id: partial("session.start telemetry is unavailable in opencode run (non-interactive) mode; tool events still carry a turn context."),
+            transcript_path: unsupported("opencode does not expose a per-session transcript path to hooks."),
+            intent_annotation: NOT_IMPLEMENTED_INTENT,
+            per_delegation_trace_context: NOT_IMPLEMENTED_TRACE,
+            per_delegation_tokens: NO_PER_DELEGATION_TOKENS,
+            terminal_verdict: unsupported("opencode does not surface per-sub-agent terminal verdicts."),
+        },
+    },
+    pi: {
+        runtime: "pi",
+        capabilities: {
+            turn_id: supported(),
+            transcript_path: unsupported("pi does not expose a per-session transcript path to hooks."),
+            intent_annotation: NOT_IMPLEMENTED_INTENT,
+            per_delegation_trace_context: NOT_IMPLEMENTED_TRACE,
+            per_delegation_tokens: NO_PER_DELEGATION_TOKENS,
+            terminal_verdict: unsupported("pi has no named-subagent registry, so per-sub-agent verdicts are not observable."),
+        },
+    },
+    "codex-local": {
+        runtime: "codex-local",
+        capabilities: {
+            turn_id: KIT_ADAPTER_TURN("codex-local"),
+            transcript_path: KIT_ADAPTER_TRANSCRIPT("codex-local"),
+            intent_annotation: NOT_IMPLEMENTED_INTENT,
+            per_delegation_trace_context: NOT_IMPLEMENTED_TRACE,
+            per_delegation_tokens: NO_PER_DELEGATION_TOKENS,
+            terminal_verdict: KIT_ADAPTER_VERDICT("codex-local"),
+        },
+    },
+    "strands-local": {
+        runtime: "strands-local",
+        capabilities: {
+            turn_id: KIT_ADAPTER_TURN("strands-local"),
+            transcript_path: KIT_ADAPTER_TRANSCRIPT("strands-local"),
+            intent_annotation: NOT_IMPLEMENTED_INTENT,
+            per_delegation_trace_context: NOT_IMPLEMENTED_TRACE,
+            per_delegation_tokens: NO_PER_DELEGATION_TOKENS,
+            terminal_verdict: KIT_ADAPTER_VERDICT("strands-local"),
+        },
+    },
+};
+/**
+ * Alias → canonical-runtime-id map (D1). The load-bearing entry is
+ * `kiro-cli → kiro`: the value `.agent.runtime` carries for Kiro is `kiro-cli`,
+ * but declarations are keyed on the canonical `kiro`. Keys are the already
+ * lowercased + whitespace-collapsed form.
+ */
+export const RUNTIME_ID_ALIASES = {
+    "kiro-cli": "kiro",
+    "raw-model": "base",
+    "raw-model-runner": "base",
+};
+/**
+ * Normalize any raw runtime spelling to its canonical key (D1). Total + pure:
+ * trims, lowercases, collapses internal whitespace to hyphens, then folds known
+ * aliases (notably `kiro-cli → kiro`). Returns `""` for a null/blank input.
+ * The canonical id may still be undeclared (e.g. `base`) — that is intentional
+ * and resolves to a typed `unsupported` at query time, never a fabricated value.
+ */
+export function normalizeRuntimeId(raw) {
+    const lowered = String(raw ?? "").trim().toLowerCase();
+    if (!lowered)
+        return "";
+    const collapsed = lowered.replace(/\s+/g, "-");
+    // Object.hasOwn guards against prototype-member keys (`__proto__`,
+    // `constructor`, `toString`, …): a bare bracket lookup would resolve those to
+    // inherited Object.prototype members instead of `undefined`, breaking the
+    // total-string contract. Own-property only; unknown keys fall through.
+    return Object.hasOwn(RUNTIME_ID_ALIASES, collapsed) ? RUNTIME_ID_ALIASES[collapsed] : collapsed;
+}
+/** Return the full declaration for a runtime (after alias normalization), or `undefined`. */
+export function getDeclaration(runtimeId) {
+    const canonical = normalizeRuntimeId(runtimeId);
+    return Object.hasOwn(RUNTIME_CAPABILITY_DECLARATIONS, canonical)
+        ? RUNTIME_CAPABILITY_DECLARATIONS[canonical]
+        : undefined;
+}
+/**
+ * Query a single capability for a runtime (D5). ALWAYS returns a typed
+ * `CapabilityStatus` — never `undefined`/`false`. An undeclared runtime OR an
+ * undeclared capability returns `{status:"unsupported", reason}` (R4): the
+ * JS-natural undefined/false fallback is exactly the fabrication R4 forbids.
+ */
+export function queryCapability(runtimeId, capability) {
+    const canonical = normalizeRuntimeId(runtimeId);
+    const declaration = getDeclaration(canonical);
+    if (!declaration) {
+        return {
+            status: "unsupported",
+            reason: `No capability declaration for runtime '${canonical || String(runtimeId ?? "")}'.`,
+        };
+    }
+    // Own-property guard: a prototype-member capability name (`constructor`,
+    // `__proto__`, …) must resolve to a typed `unsupported`, not an inherited
+    // Object.prototype value (a function / the prototype object) that is not a
+    // CapabilityStatus at all.
+    const status = Object.hasOwn(declaration.capabilities, capability)
+        ? declaration.capabilities[capability]
+        : undefined;
+    if (!status) {
+        return {
+            status: "unsupported",
+            reason: `Capability '${capability}' is not declared for runtime '${canonical}'.`,
+        };
+    }
+    return status;
+}

package/build/src/narrative/envelope.d.ts

@@ -0,0 +1,111 @@
+import type { CaptureCompleteness, UnavailableReason } from "./integrity.js";
+import { type NarrativeRuntimeProjection } from "./projection.js";
+export declare const GROUNDED_EXECUTION_NARRATIVE_SCHEMA_VERSION: "grounded-execution-narrative/v1";
+export declare const GROUNDED_EXECUTION_NARRATIVE_COMPILER_NAME: "flow-agents-narrative-composer";
+export type GroundedNarrativeErrorCode = "manifest_invalid" | "source_integrity_failed" | "malformed_embedded_json" | "embedded_integrity_failed" | "schema_unavailable" | "compiler_unavailable";
+export declare class GroundedNarrativeError extends Error {
+    readonly code: GroundedNarrativeErrorCode;
+    readonly sourceId?: string | undefined;
+    readonly name = "GroundedNarrativeError";
+    constructor(code: GroundedNarrativeErrorCode, message: string, sourceId?: string | undefined);
+}
+export interface GroundedNarrativeConfig {
+    compiledAt: string;
+    renderTitle?: string;
+}
+export interface GroundedNarrativeRule {
+    id: "flow-turn-correlation/v1";
+    version: "v1";
+    inputs: string[];
+}
+export interface GroundedNarrativeFlowTransition {
+    kind: "flow-transition";
+    from: string;
+    to: string;
+    at?: string;
+    source_refs: [string];
+    rule: GroundedNarrativeRule;
+}
+export interface GroundedNarrativeCorrelation {
+    turns: Array<{
+        turn_ordinal: number;
+        placed: GroundedNarrativeFlowTransition[];
+    }>;
+    unplaced: Array<GroundedNarrativeFlowTransition & {
+        reason: "ambiguous_window" | "no_timestamp" | "no_timezone" | "no_turns";
+    }>;
+}
+export type GroundedNarrativeConclusion = {
+    proposition: string;
+    grounding: {
+        kind: "flow_gate_derivation";
+        source_ref: string;
+        pointer: string;
+    };
+} | {
+    proposition: string;
+    grounding: {
+        kind: "surface_explanation";
+        source_ref: string;
+    };
+};
+export interface GroundedNarrativeForeignSection {
+    authority: "flow" | "surface";
+    kind: "flow-process-projection" | "claim-explanation";
+    source_refs: [string];
+    sha256: string;
+    embedded_bytes: string;
+}
+export interface GroundedNarrativeRuntimeSection {
+    authority: "flow-agents";
+    kind: "runtime-projection";
+    sha256: string;
+    embedded: NarrativeRuntimeProjection;
+}
+export type GroundedNarrativeSection = GroundedNarrativeForeignSection | GroundedNarrativeRuntimeSection;
+export interface GroundedExecutionNarrative {
+    schema_version: typeof GROUNDED_EXECUTION_NARRATIVE_SCHEMA_VERSION;
+    narrative_id: string;
+    provenance: {
+        compiler: {
+            name: typeof GROUNDED_EXECUTION_NARRATIVE_COMPILER_NAME;
+            version: string;
+        };
+        compiled_at: string;
+        manifest_sha256: string;
+        schema_sha256: string;
+        config_sha256: string;
+        compiler_sha256: string;
+    };
+    capture_completeness: CaptureCompleteness;
+    sections: GroundedNarrativeSection[];
+    correlation: GroundedNarrativeCorrelation;
+    conclusions: GroundedNarrativeConclusion[];
+    coverage: {
+        sources: number;
+        embedded: number;
+        unavailable: number;
+    };
+    unavailable_sources: Array<{
+        source_ref: string;
+        reason: UnavailableReason;
+    }>;
+}
+export interface WrittenGroundedNarrative {
+    envelopePath: string;
+    lineagePath: string;
+    envelopeSha256: string;
+    renderPath?: string;
+}
+export interface WriteEnvelopeOptions {
+    render?: boolean;
+    outDir?: string;
+}
+export type SchemaIssue = {
+    path: string;
+    message: string;
+};
+export declare function validateGroundedNarrative(value: unknown): SchemaIssue[];
+/** Compile exclusively from the frozen manifest and its content-addressed blobs. */
+export declare function composeGroundedNarrative(narrativeDir: string, config: GroundedNarrativeConfig): GroundedExecutionNarrative;
+export declare function writeEnvelope(narrativeDir: string, envelope: GroundedExecutionNarrative, options?: WriteEnvelopeOptions): WrittenGroundedNarrative;