@kontourai/flow-agents 3.12.1 → 4.1.0

package/src/flow-kit/validate.ts

@@ -7,27 +7,40 @@ export { isObservableBuilderArtifactRef, isSafeBuilderArtifactRef, parseKitFlowS
 export type { KitFlowStepActionEntry, KitFlowStepArtifactBinding, KitFlowStepExpectationBinding } from "./action-metadata.js";
 
 // Extension-only asset classes: validated by Flow Agents. Flows are validated by @kontourai/flow.
-const EXTENSION_ASSET_CLASSES = ["skills", "docs", "adapters", "evals", "assets"] as const;
+const EXTENSION_ASSET_CLASSES = ["skills", "docs", "adapters", "evals", "assets", "provisions"] as const;
 
 // Core container fields owned by kontourai/flow (flow-kit-container.schema.json).
 // agent-extension fields are skills, docs, adapters, evals, assets.
 const CORE_CONTAINER_FIELDS = new Set(["schema_version", "id", "name", "description", "product_name", "flows"]);
-const AGENT_EXTENSION_CLASSES = new Set(["skills", "docs", "adapters", "evals", "assets"]);
+const AGENT_EXTENSION_CLASSES = new Set(["skills", "docs", "adapters", "evals", "assets", "provisions"]);
 
 // Flow Agents-recognized metadata fields that are neither core container fields nor
 // agent-extension asset classes. Recognized here so they are never misreported as
 // unknown third-party extension namespaces. `dependencies` declares cross-kit skill
 // dependencies (extension-layer ownership; see docs/adr/0019-kit-dependency-ownership.md),
 // workflow_triggers / hook_influence_expectations declare kit-owned runtime influence,
-// and first_party is legacy catalog/marketplace metadata. It does not grant runtime
-// capability or steering privilege.
-const KNOWN_METADATA_FIELDS = new Set(["dependencies", "workflow_triggers", "hook_influence_expectations", "flow_step_actions", "skill_roles", "first_party"]);
+// agent_spawn_triggers declares perimeter trigger surfaces that spawn agent runs plus
+// their guard config (context/contracts/trigger-guards.md), and first_party is legacy
+// catalog/marketplace metadata. It does not grant runtime capability or steering privilege.
+const KNOWN_METADATA_FIELDS = new Set(["dependencies", "workflow_triggers", "hook_influence_expectations", "flow_step_actions", "skill_roles", "first_party", "agent_spawn_triggers"]);
 
 export interface KitDependencyEntry {
   kit_id: string;
   reason?: string;
 }
 
+export interface KitProvisionEntry {
+  id: string;
+  path: string;
+  target: string;
+  description?: string;
+}
+
+// Consumer-repo-relative directory (posix, lowercase) where the engine writes its own
+// per-kit provision manifest. Reserved: a provision may not target inside it. Shared with
+// provision.ts so the reservation and the actual manifest write stay in agreement.
+export const PROVISION_MANIFEST_DIR = ".kontourai/flow-agents/provisions";
+
 export interface KitWorkflowTriggerEntry {
   id: string;
   when: string;
@@ -48,6 +61,20 @@ export interface KitHookInfluenceExpectationEntry {
   must_include_actions: string[];
 }
 
+export interface KitAgentSpawnTriggerGuards {
+  dedup_key: string;
+  cooldown_seconds: number;
+  daily_cap: number;
+  max_concurrent: number;
+}
+
+export interface KitAgentSpawnTriggerEntry {
+  id: string;
+  description: string;
+  spawns_agent_runs: boolean;
+  guards?: KitAgentSpawnTriggerGuards;
+}
+
 export type KitSkillRole = "entrypoint" | "profile" | "step" | "shared-primitive" | "extension";
 
 export interface KitSkillRoleEntry {
@@ -266,6 +293,120 @@ export function parseKitHookInfluenceExpectations(manifest: Record<string, unkno
   return { entries, errors };
 }
 
+const AGENT_SPAWN_TRIGGER_GUARD_FIELDS = ["dedup_key", "cooldown_seconds", "daily_cap", "max_concurrent"] as const;
+
+/**
+ * Parse and shape-validate a kit manifest's optional `agent_spawn_triggers` field:
+ * perimeter trigger surfaces (check failures, schedules, watchers) that spawn agent
+ * runs, plus their guard config. Contract: context/contracts/trigger-guards.md.
+ *
+ * Shape rules (ERRORS):
+ *  - `agent_spawn_triggers` (if present) must be an array of objects.
+ *  - `id` must match the workflow-trigger identifier pattern and be unique.
+ *  - `description` must be a non-empty string.
+ *  - `spawns_agent_runs` must be a boolean.
+ *  - `guards` (if present) must be an object with exactly the four guard fields when
+ *    complete: `dedup_key` non-empty string; `cooldown_seconds`, `daily_cap`,
+ *    `max_concurrent` integers >= 1. Unknown guard fields are errors.
+ *
+ * Guard-completeness (WARNINGS, never errors — declaration-first rollout, #664):
+ *  - an entry with `spawns_agent_runs: true` and missing or incomplete `guards`
+ *    produces a warning naming the missing guard fields and the contract doc.
+ */
+export function parseKitAgentSpawnTriggers(manifest: Record<string, unknown>, manifestPath: string): { entries: KitAgentSpawnTriggerEntry[]; errors: string[]; warnings: string[] } {
+  const entries: KitAgentSpawnTriggerEntry[] = [];
+  const errors: string[] = [];
+  const warnings: string[] = [];
+  const raw = manifest.agent_spawn_triggers;
+  if (raw === undefined) return { entries, errors, warnings };
+  if (!Array.isArray(raw)) {
+    errors.push(`${manifestPath}: .agent_spawn_triggers must be a list`);
+    return { entries, errors, warnings };
+  }
+  const fields = new Set(["id", "description", "spawns_agent_runs", "guards"]);
+  const seen = new Set<string>();
+  raw.forEach((entry, index) => {
+    if (typeof entry !== "object" || entry === null) {
+      errors.push(`${manifestPath}: agent_spawn_triggers[${index}] must be an object`);
+      return;
+    }
+    const record = entry as Record<string, unknown>;
+    const unknown = Object.keys(record).filter((field) => !fields.has(field));
+    if (unknown.length > 0) {
+      errors.push(`${manifestPath}: agent_spawn_triggers[${index}] contains unsupported field(s): ${unknown.join(", ")}`);
+      return;
+    }
+    const id = record.id;
+    if (!workflowTriggerIdentifier(id)) {
+      errors.push(`${manifestPath}: agent_spawn_triggers[${index}].id must match ^[a-z0-9]+(?:[.-][a-z0-9]+)*$`);
+      return;
+    }
+    if (seen.has(id)) {
+      errors.push(`${manifestPath}: agent_spawn_triggers[${index}].id duplicates '${id}'`);
+      return;
+    }
+    seen.add(id);
+    if (typeof record.description !== "string" || !record.description.trim()) {
+      errors.push(`${manifestPath}: agent_spawn_triggers[${index}].description must be a non-empty string`);
+      return;
+    }
+    if (typeof record.spawns_agent_runs !== "boolean") {
+      errors.push(`${manifestPath}: agent_spawn_triggers[${index}].spawns_agent_runs must be a boolean`);
+      return;
+    }
+    let guards: KitAgentSpawnTriggerGuards | undefined;
+    let guardsShapeValid = true;
+    const missingGuardFields: string[] = [];
+    if (record.guards !== undefined) {
+      if (typeof record.guards !== "object" || record.guards === null || Array.isArray(record.guards)) {
+        errors.push(`${manifestPath}: agent_spawn_triggers[${index}].guards must be an object when present`);
+        return;
+      }
+      const guardRecord = record.guards as Record<string, unknown>;
+      const guardFieldSet = new Set<string>(AGENT_SPAWN_TRIGGER_GUARD_FIELDS);
+      const unknownGuards = Object.keys(guardRecord).filter((field) => !guardFieldSet.has(field));
+      if (unknownGuards.length > 0) {
+        errors.push(`${manifestPath}: agent_spawn_triggers[${index}].guards contains unsupported field(s): ${unknownGuards.join(", ")}`);
+        return;
+      }
+      if (guardRecord.dedup_key !== undefined && (typeof guardRecord.dedup_key !== "string" || !guardRecord.dedup_key.trim())) {
+        errors.push(`${manifestPath}: agent_spawn_triggers[${index}].guards.dedup_key must be a non-empty string`);
+        guardsShapeValid = false;
+      }
+      for (const field of ["cooldown_seconds", "daily_cap", "max_concurrent"] as const) {
+        const value = guardRecord[field];
+        if (value !== undefined && (typeof value !== "number" || !Number.isInteger(value) || value < 1)) {
+          errors.push(`${manifestPath}: agent_spawn_triggers[${index}].guards.${field} must be an integer >= 1`);
+          guardsShapeValid = false;
+        }
+      }
+      if (!guardsShapeValid) return;
+      for (const field of AGENT_SPAWN_TRIGGER_GUARD_FIELDS) {
+        if (guardRecord[field] === undefined) missingGuardFields.push(field);
+      }
+      if (missingGuardFields.length === 0) {
+        guards = {
+          dedup_key: guardRecord.dedup_key as string,
+          cooldown_seconds: guardRecord.cooldown_seconds as number,
+          daily_cap: guardRecord.daily_cap as number,
+          max_concurrent: guardRecord.max_concurrent as number,
+        };
+      }
+    } else {
+      missingGuardFields.push(...AGENT_SPAWN_TRIGGER_GUARD_FIELDS);
+    }
+    if (record.spawns_agent_runs === true && missingGuardFields.length > 0) {
+      warnings.push(
+        `${manifestPath}: agent_spawn_triggers[${index}] ('${id}') spawns agent runs without complete guard config` +
+        ` (missing: ${missingGuardFields.join(", ")}); declare dedup_key, cooldown_seconds, daily_cap, and max_concurrent` +
+        ` per context/contracts/trigger-guards.md`,
+      );
+    }
+    entries.push({ id, description: record.description, spawns_agent_runs: record.spawns_agent_runs, ...(guards ? { guards } : {}) });
+  });
+  return { entries, errors, warnings };
+}
+
 export function parseKitSkillRoles(manifest: Record<string, unknown>, manifestPath: string): { entries: KitSkillRoleEntry[]; errors: string[] } {
   const entries: KitSkillRoleEntry[] = [];
   const errors: string[] = [];
@@ -493,21 +634,34 @@ export async function deriveKitTargets(manifest: Record<string, unknown>, kitDir
 }
 
 export async function validateKitRepository(kitDir: string): Promise<string[]> {
+  return (await validateKitRepositoryDiagnostics(kitDir)).errors;
+}
+
+/**
+ * Repository validation with a non-blocking warnings channel alongside the blocking
+ * errors `validateKitRepository` has always returned. Warnings are advisory quality
+ * findings (today: an agent-spawning trigger surface declared without complete guard
+ * config — context/contracts/trigger-guards.md); they never fail validation.
+ */
+export async function validateKitRepositoryDiagnostics(kitDir: string): Promise<{ errors: string[]; warnings: string[] }> {
   const errors: string[] = [];
+  const warnings: string[] = [];
   const manifestPath = path.join(kitDir, "kit.json");
   let manifest: Record<string, unknown>;
   try {
     manifest = readJson(manifestPath) as Record<string, unknown>;
   } catch (error) {
     errors.push(`${manifestPath}: invalid JSON: ${(error as Error).message}`);
-    return errors;
+    return { errors, warnings };
   }
 
   errors.push(...await delegateCoreContainerValidation(kitDir, manifest));
   errors.push(...validateExtensionAssets(kitDir, manifestPath, manifest));
-  errors.push(...validateAgentMetadata(kitDir, manifestPath, manifest));
+  const metadata = validateAgentMetadata(kitDir, manifestPath, manifest);
+  errors.push(...metadata.errors);
+  warnings.push(...metadata.warnings);
   if (manifest.first_party !== undefined && typeof manifest.first_party !== "boolean") errors.push(`${manifestPath}: .first_party must be a boolean when present`);
-  return errors;
+  return { errors, warnings };
 }
 
 function validateExtensionAssets(kitDir: string, manifestPath: string, manifest: Record<string, unknown>): string[] {
@@ -528,10 +682,14 @@ function validateExtensionAssets(kitDir: string, manifestPath: string, manifest:
       const record = entry as Record<string, unknown>;
       const id = record.id;
       const rel = record.path;
+      const kitId = typeof manifest.id === "string" ? manifest.id : "";
       if (typeof id === "string") {
         if (seen.has(id)) errors.push(`${manifestPath}: ${section}[${index}].id duplicates`);
         seen.add(id);
       }
+      if (section === "provisions" && (typeof id !== "string" || !kitId || !id.startsWith(`${kitId}.`))) {
+        errors.push(`${manifestPath}: provisions[${index}].id must be prefixed with '${kitId}.'`);
+      }
       if (typeof rel !== "string" || !rel) {
         errors.push(`${manifestPath}: ${section}[${index}].path must be a string`);
         return;
@@ -540,6 +698,10 @@ function validateExtensionAssets(kitDir: string, manifestPath: string, manifest:
         errors.push(`${manifestPath}: ${section}[${index}].path must be relative`);
         return;
       }
+      if (rel.replace(/\\/g, "/").split("/").includes("..")) {
+        errors.push(`${manifestPath}: ${section}[${index}].path must not contain traversal segments`);
+        return;
+      }
       const resolved = path.resolve(kitDir, rel);
       const root = path.resolve(kitDir);
       if (resolved !== root && !resolved.startsWith(`${root}${path.sep}`)) {
@@ -548,21 +710,82 @@ function validateExtensionAssets(kitDir: string, manifestPath: string, manifest:
       }
       if (!fs.existsSync(resolved)) {
         errors.push(`${manifestPath}: ${section}[${index}].path points at missing asset: ${rel}`);
+      } else if (section === "provisions") {
+        if (!fs.statSync(resolved).isFile()) {
+          errors.push(`${manifestPath}: provisions[${index}].path must point at a file: ${rel}`);
+        } else {
+          // A provisioned source is copied byte-for-byte into a consumer repo, so a symlink that
+          // resolves outside the kit would exfiltrate arbitrary readable host files. Require the
+          // link-resolved real path to stay inside the kit.
+          const realResolved = fs.realpathSync(resolved);
+          const realRoot = fs.realpathSync(root);
+          if (realResolved !== realRoot && !realResolved.startsWith(`${realRoot}${path.sep}`)) {
+            errors.push(`${manifestPath}: provisions[${index}].path must not resolve outside the kit directory`);
+          }
+        }
       }
     });
   }
 
+  const rawProvisions = manifest.provisions;
+  if (Array.isArray(rawProvisions)) {
+    const targets = new Set<string>();
+    rawProvisions.forEach((entry, index) => {
+      if (typeof entry !== "object" || entry === null) return;
+      const record = entry as Record<string, unknown>;
+      if (record.description !== undefined && typeof record.description !== "string") {
+        errors.push(`${manifestPath}: provisions[${index}].description must be a string when present`);
+      }
+      const target = record.target;
+      if (typeof target !== "string" || target.trim().length === 0) {
+        errors.push(`${manifestPath}: provisions[${index}].target must be a non-empty string`);
+        return;
+      }
+      if (path.isAbsolute(target) || path.win32.isAbsolute(target)) {
+        errors.push(`${manifestPath}: provisions[${index}].target must be relative`);
+        return;
+      }
+      const segments = target.replace(/\\/g, "/").split("/");
+      if (segments.includes("..")) {
+        errors.push(`${manifestPath}: provisions[${index}].target must not contain traversal segments`);
+        return;
+      }
+      const normalized = path.posix.normalize(segments.join("/"));
+      if (normalized === "." || normalized.startsWith("..")) {
+        errors.push(`${manifestPath}: provisions[${index}].target must stay inside the consumer repository`);
+        return;
+      }
+      // Case-fold reserved-directory and collision checks: on a case-insensitive filesystem
+      // `.GIT/` still lands in the real `.git`, and README.md/readme.md still collide.
+      const lowered = normalized.toLowerCase();
+      if (lowered === ".git" || lowered.startsWith(".git/")) {
+        errors.push(`${manifestPath}: provisions[${index}].target must not be inside .git`);
+        return;
+      }
+      if (lowered === PROVISION_MANIFEST_DIR || lowered.startsWith(`${PROVISION_MANIFEST_DIR}/`)) {
+        errors.push(`${manifestPath}: provisions[${index}].target must not be inside the provision manifest namespace (${PROVISION_MANIFEST_DIR}/)`);
+        return;
+      }
+      if (targets.has(lowered)) errors.push(`${manifestPath}: provisions[${index}].target duplicates '${normalized}'`);
+      targets.add(lowered);
+    });
+  }
+
   return errors;
 }
 
-function validateAgentMetadata(kitDir: string, manifestPath: string, manifest: Record<string, unknown>): string[] {
+function validateAgentMetadata(kitDir: string, manifestPath: string, manifest: Record<string, unknown>): { errors: string[]; warnings: string[] } {
   const errors: string[] = [];
+  const warnings: string[] = [];
   const depResult = parseKitDependencies(manifest, manifestPath);
   for (const err of depResult.errors) errors.push(err);
   const workflowTriggerResult = parseKitWorkflowTriggers(manifest, manifestPath);
   for (const err of workflowTriggerResult.errors) errors.push(err);
   const hookExpectationResult = parseKitHookInfluenceExpectations(manifest, manifestPath);
   for (const err of hookExpectationResult.errors) errors.push(err);
+  const agentSpawnTriggerResult = parseKitAgentSpawnTriggers(manifest, manifestPath);
+  for (const err of agentSpawnTriggerResult.errors) errors.push(err);
+  for (const warning of agentSpawnTriggerResult.warnings) warnings.push(warning);
   const flowStepActionResult = parseKitFlowStepActions(manifest, manifestPath);
   for (const err of flowStepActionResult.errors) errors.push(err);
   const skillRoleResult = parseKitSkillRoles(manifest, manifestPath);
@@ -570,7 +793,7 @@ function validateAgentMetadata(kitDir: string, manifestPath: string, manifest: R
   if ((manifest.skill_roles !== undefined || manifest.flow_step_actions !== undefined) && skillRoleResult.errors.length === 0) {
     errors.push(...validateActionRepositoryMetadata({ kitDir, manifestPath, manifest, actions: flowStepActionResult.entries, skillRoles: skillRoleResult.entries }));
   }
-  return errors;
+  return { errors, warnings };
 }
 
 export async function assertKitRepository(kitDir: string): Promise<Record<string, unknown>> {

package/src/index.ts

@@ -14,6 +14,227 @@
 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 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";
+
+// #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 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";
+
+// #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";
+export type {
+  NarrativeEvalCapabilityParity,
+  NarrativeEvalFixtureResult,
+  NarrativeEvalKnownGap,
+  NarrativeEvalMetricUncertainty,
+  NarrativeEvalMetrics,
+  NarrativeEvalRawSourceLink,
+  NarrativeEvalResult,
+  NarrativeEvalVerdict,
+  SchemaIssue as NarrativeEvalResultSchemaIssue,
+} 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 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,
@@ -52,6 +273,8 @@ export {
 } from "./builder-gate-action-envelope.js";
 export type {
   BuilderGateActionEnvelopeInput,
+  GateActionArtifactBinding,
+  GateActionArtifactTarget,
   GateActionEnvelope,
   GateActionInterfaceParameter,
   GateActionPriorProgress,
@@ -70,6 +293,8 @@ export {
 } from "./continuation-driver.js";
 export type {
   ContinuationBarrier,
+  ContinuationContextPolicy,
+  ContinuationContextStrategy,
   ContinuationAcceptedTurn,
   ContinuationDriverEvent,
   ContinuationDriverLockLease,
@@ -91,6 +316,22 @@ export type {
 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,