@sema-agent/core 5.20.0 → 5.21.1

package/dist/prompt-assembly/artifact.d.ts

@@ -1,19 +1,27 @@
 import type { PromptTextDeclaration } from "../prompts/default.js";
+/** v1 overlay slots — the same reserved rank bands the stableBlocks lane mounts into. */
 export type CenterOverlaySlot = "identity" | "scenario" | "behavior";
 export interface CenterOverlaySection {
+    /** Same grammar as stableBlocks ids (manifest/trace/explain-safe, never `core/`). */
     id: string;
     slot: CenterOverlaySlot;
+    /** Immutable rendered text (v1: fixed text, no renderer — center compiles before publishing). */
     text: string;
+    /** REQUIRED on the center lane (unlike caller stableBlocks): sha256 of `text`. The center
+     *  publish path always mints it — it is the reconciliation anchor ([1050]② tiering). */
     contentHash: string;
 }
 export interface PromptCatalogSnapshot {
+    /** Center pack identity, e.g. "center:acme@3". Logical name only — history identity is digests. */
     packId: string;
     sections: ReadonlyArray<CenterOverlaySection>;
 }
 export interface PromptDependencyClosure {
+    /** v1: only the bundled base is a legal foundation (exact-archive multi-base = later slice). */
     basePackId: string;
     promptCatalog: PromptCatalogSnapshot;
 }
+/** Dependency-free core-compat range: dotted-triple compares, absent bound = unbounded. */
 export interface CoreCompatRange {
     minCore?: string;
     maxCoreExclusive?: string;
@@ -29,10 +37,16 @@ export interface PromptEpochArtifact {
     payload: PromptEpochArtifactPayload;
     artifactDigest: string;
 }
+/** The publish envelope (§9.2): artifact + opaque source provenance. Attestation = later slice
+ *  (protocol: first phase does not require full PKI for internal artifacts). */
 export interface PublishedPromptArtifactEnvelope {
     artifact: PromptEpochArtifact;
+    /** Opaque ETag-like revision. State transitions key off "last successfully verified response";
+     *  NEVER ordered or compared for recency. */
     sourceRevision: string;
 }
+/** Validator hard limits (§9.2: sections/bytes caps so a hostile or runaway publish cannot wedge
+ *  the composer). Deliberately generous — these bound abuse, not legitimate catalogs. */
 export declare const ARTIFACT_LIMITS: {
     readonly maxSections: 64;
     readonly maxSectionBytes: 32000;
@@ -51,10 +65,21 @@ export type ArtifactVerifyResult = {
     code: string;
     reason: string;
 };
+/**
+ * Full §9.2 verify pipeline over an UNTRUSTED envelope (network body or disk bytes — the store
+ * re-verifies on read; nothing on disk is trusted by location). Every arm is a distinct coded
+ * rejection so the source-state machine can log honestly. Verification is pure — no IO.
+ */
 export declare function verifyPromptArtifact(raw: unknown, opts: {
     engineVersion: string;
 }): ArtifactVerifyResult;
+/**
+ * Compile a VERIFIED artifact into the declaration lane (v1 adoption channel — see file header).
+ * Deterministic order: catalog order preserved (it entered the digest, so it is stable).
+ */
 export declare function artifactDeclarations(artifact: PromptEpochArtifact): PromptTextDeclaration[];
+/** Test/fixture helper: build a correctly-digested envelope from plain sections (the shape a
+ *  center's publish pipeline produces). Exported for tests and the fixture-center harness. */
 export declare function buildPromptArtifactEnvelope(opts: {
     packId: string;
     sections: ReadonlyArray<{

package/dist/prompt-assembly/assemble.d.ts

@@ -3,6 +3,8 @@ import { type PromptProvider, type PromptTextDeclaration } from "../prompts/defa
 import type { CompiledSection, CompiledSystemBlock, PromptRuntimeFacts } from "./types.js";
 export interface AssembleInputs {
     provider: PromptProvider;
+    /** True when the provider is the built-in defaultPromptProvider (checked FIRST — its stableSystem
+     *  output contains the constitution anchors and would misroute through the M9 guard). */
     isDefaultProvider: boolean;
     userSystemPrompt?: string;
     userAppendSystemPrompt?: string;
@@ -10,22 +12,40 @@ export interface AssembleInputs {
     facts: PromptRuntimeFacts;
     mcpInstructionsBlock?: string;
     memoryBlock?: string;
+    /** Renders the environment tail for a given date (leg-frozen; date_change re-render seam). */
     buildEnvBlock: (date: string) => string | undefined;
+    /** The leg's frozen date — the initial render input (design/66 date_change). */
     date: string;
     modelGuidance?: string;
+    /** design/148 S1 — declarations compiled from a VERIFIED center prompt artifact (the adoption
+     *  channel: core verifies the artifact, synthesizes these, and they ride the same mount loop as
+     *  provider stableBlocks — same manifest/epoch/contentHash faces, zero new assembly machinery).
+     *  Mounted ahead of provider declarations on every COMPOSED path; the provider-assembled
+     *  pass-through path cannot mount them (operator-visible warn, never silent). */
     centerDeclarations?: PromptTextDeclaration[];
+    /** Structured warning channel (maps to deps.onError with a phase). */
     onWarn?: (message: string, phase: "prompt-constitution") => void;
 }
 export interface AssembledPrompt {
     constitution: "core" | "replaced" | "provider-assembled";
+    /** design/148 S1 (codex F3): true ⇔ the supplied centerDeclarations were actually COMPILED into
+     *  this prompt. The caller must never persist a center pin when this is false — a pin that claims
+     *  an artifact the model never received is a durable lie (the assembled-identity pass-through path
+     *  warns + false). */
     centerMounted?: boolean;
+    /** Re-render the full prompt for a date. */
     renderWithDate?: (date: string) => string;
+    /** The initially-rendered system prompt. */
     systemPrompt: string;
+    /** v1 `prompt.assembled` block view (id wordlist contract preserved). */
     legacyBlocks: Array<{
         id: string;
         text: string;
     }>;
+    /** Compiled IR of the last render — manifest v2 source. */
     sections?: CompiledSection[];
+    /** S4: physical system blocks of the last render (sema-default: ONE block, text === systemPrompt —
+     *  byte-identity). */
     systemBlocks?: CompiledSystemBlock[];
 }
 export declare function assemblePrompt(inputs: AssembleInputs): AssembledPrompt;

package/dist/prompt-assembly/composer.d.ts

@@ -1,5 +1,34 @@
+/**
+ * The prompt Composer — the single deterministic assembly path (campaign S1; protocol §6).
+ *
+ * compose() is a pure function of (pack, inputs): validate → admit → render → join. The legacy
+ * date re-render seam (design/66 date_change) is expressed by re-running compose with a different
+ * `environmentBlock` — everything else stays byte-identical, so the prefix-cache property is
+ * preserved exactly as before (only the env tail differs between legs).
+ *
+ * Manifest duality: the compiled IR (sections, manifest-v2 source) coexists with the v1
+ * `prompt.assembled` block view — adjacent sections sharing a `legacyBlockId` merge into one
+ * legacy block (the harness.context composite), keeping the downstream id-wordlist contract
+ * intact (sentence-index #28).
+ */
 import type { CompiledSystemBlock, ComposedPrompt, PromptPack, SectionRenderInputs, SystemLayout } from "./types.js";
+/**
+ * Structural pack validation (protocol §14.1 negative cases — fail-loud, never a silent skip):
+ * duplicate section id, duplicate rank, empty id, or an unknown legacy joiner all reject the pack.
+ * Called once per pack instance (composePack callers may cache); cheap enough to run per compose.
+ */
 export declare function validatePack(pack: PromptPack): void;
+/**
+ * Assemble the pack's system-prompt plane from prepare-frozen inputs. Sections emit in ascending
+ * rank (the pack-declared global order — slot NEVER drives physical order, see types.ts header).
+ */
 export declare function compose(pack: PromptPack, inputs: SectionRenderInputs): ComposedPrompt;
+/** The implicit single-group layout — the legacy wire face (one system block, one cache span). */
 export declare const SINGLE_BLOCK_LAYOUT: SystemLayout;
+/**
+ * Route a composed prompt's sections into PHYSICAL system blocks per the layout (campaign S4).
+ * Sections keep their emission order; groups partition by rank range (routing never reorders —
+ * see types.ts header on slot interleaving). Empty groups are dropped. With SINGLE_BLOCK_LAYOUT
+ * the result is one block whose text === composed.text (byte-identity, golden-pinned).
+ */
 export declare function layoutSystemBlocks(composed: ComposedPrompt, layout?: SystemLayout): CompiledSystemBlock[];

package/dist/prompt-assembly/epoch.d.ts

@@ -1,31 +1,85 @@
 import type { PromptPack } from "./types.js";
+/** [1068] — the provider-declared sections of THIS run's resolved prompt (the `origin:"provider"`
+ *  subset of the compiled IR), the declaration axis of the artifact identity.
+ *
+ *  codex F6 (S1 round 2): declaration TEXT deliberately does NOT enter this shape — the epoch
+ *  digest is a deterministic, unsalted value persisted in exportable session entries, and session
+ *  readers do not see system prompts; hashing private text into it would be a dictionary-preimage
+ *  surface (the exact class the salted prompt-manifest hashes exist to prevent). Identity instead
+ *  rides `(id, slot, chars)` plus the declarer's OPT-IN `contentHash` (the digest-tiering value,
+ *  already public by declaration): with contentHash — byte-precise re-pin detection (the center
+ *  publish path always mints it); without — length-level detection only, documented degradation
+ *  for private/forwarded text. */
 export type EpochDeclaredSections = ReadonlyArray<{
     id: string;
     slot: string;
     chars: number;
     contentHash?: string;
 }>;
+/** How an epoch became active (protocol §9.2 descriptor field; `clear` arrives with a future
+ *  first-class context_reset — v1 clear = new session = `session_start`). */
 export type PromptEpochActivation = "session_start" | "compaction" | "legacy_migration";
+/** The durable pin, persisted as a first-class session entry (root) and restated in every
+ *  compaction entry's `details.promptEpoch` (same-CAS atomicity; bounded-tail recoverable). */
 export interface PromptEpochDescriptor {
+    /** Monotonic per-session epoch counter (session_start = 1). */
     epoch: number;
     artifactDigest: string;
     packId: string;
     assemblyApi: number;
     activatedBy: PromptEpochActivation;
+    /** design/148 S1 (additive provenance, present only on center-adopted pins): the VERIFIED center
+     *  artifact this session composes from. `artifactDigest` above stays the computed
+     *  bundled+declarations identity (the existing re-pin machinery); this field is what the resume
+     *  path resolves through the artifact store — a miss is fail-loud (`prompt.snapshot_unavailable`),
+     *  never a silent hybrid recompose (protocol §9.2). */
     centerArtifactDigest?: string;
+    /** Opaque publish provenance of the adopted envelope (audit only — never enters any digest). */
     sourceRevision?: string;
 }
+/** Deterministic canonical JSON (sorted keys) — shared identity encoding for the bundled-pack
+ *  digest AND the center artifact digests (design/148 S1: one canonicalization, never two). */
 export declare function canonical(node: unknown): string;
+/**
+ * Bundled-pack artifact digest: canonical hash over the pack's structural declaration PLUS each
+ * section's probe-rendered content under the probe-fact vectors — all-off, all-on, and one
+ * single-axis-flipped vector per axis (content- and admission-binding, incl. single-gate mixed
+ * states). TOTALITY over the axes the pack forks on is the load-bearing property (see
+ * PROBE_FACTS_OFF/PROBE_FACTS_ON); it is pinned behaviourally by
+ * test/hardening-prompt-assembly.test.ts. Deterministic across processes and object insertion order;
+ * changes to any section's prose, admission behavior, or structure change the digest. Build version
+ * deliberately EXCLUDED (F3): a release that doesn't touch the pack keeps the same identity.
+ */
 export declare function computeBundledArtifactDigest(pack: PromptPack, declared?: EpochDeclaredSections): string;
+/** Mint the descriptor for a NEW session on the current bundled artifact.
+ *  Subagent/fork note (RB-16 ruling, 2026-07-17): children mint their OWN session_start pin rather
+ *  than inheriting the parent's descriptor — under v1 bundled-only resolution both produce the
+ *  identical pin (same process, same pack, same digest), so the protocol's "explicit inheritance
+ *  via RunInternals" is deferred to the multi-artifact era, where a parent pinned to a non-latest
+ *  artifact genuinely diverges from a fresh mint (lands with the center candidate machinery). */
 export declare function mintSessionStartEpoch(pack: PromptPack, declared?: EpochDeclaredSections): PromptEpochDescriptor;
-export declare function selectCompactionEpoch(current: PromptEpochDescriptor | undefined, pack: PromptPack, declared?: EpochDeclaredSections, centerAdoption?: {
+/** Epoch selection at a compaction boundary (protocol §9.3 order steps 1-4, v1 bundled form):
+ *  the "latest validated candidate" IS the current bundled artifact. Same digest ⇒ restate the
+ *  current epoch (no advance); different digest (engine upgraded mid-session) ⇒ advance. */
+export declare function selectCompactionEpoch(current: PromptEpochDescriptor | undefined, pack: PromptPack, declared?: EpochDeclaredSections, 
+/** RB-31 (design/148 S2) — a compaction-boundary CENTER ADOPTION: the new candidate's provenance
+ *  rides the advanced descriptor (the caller pre-assembled with the candidate's declarations, so
+ *  `declared` already reflects the new closure — the digest moves, the epoch advances). */
+centerAdoption?: {
     centerArtifactDigest: string;
     sourceRevision?: string;
 } | {
     clear: true;
 }): PromptEpochDescriptor;
+/**
+ * Resolve the session's pinned epoch against the CURRENT bundled artifact (v1 resolution).
+ * Returns the effective descriptor plus whether a legacy migration happened (pin from another
+ * build, or a pre-epoch session with no pin at all) — the caller records the migration entry.
+ */
 export declare function resolveEpochAgainstBundled(pinned: PromptEpochDescriptor | undefined, pack: PromptPack, declared?: EpochDeclaredSections): {
     descriptor: PromptEpochDescriptor;
     migrated: boolean;
 };
+/** Shape-normalize an untrusted candidate (session import face — RB-7: import-validate is a
+ *  consumer). Returns undefined for anything that isn't a plausible descriptor. */
 export declare function normalizePromptEpoch(raw: unknown): PromptEpochDescriptor | undefined;

package/dist/prompt-assembly/event-registry.d.ts

@@ -1,20 +1,55 @@
+/**
+ * Event prompt registry (campaign S5; protocol §5.3) — the typed catalog of every runtime
+ * message-injection kind: its carrier, trust, dedupe semantics, byte budget and DEFAULT policy.
+ * Mechanism/copy separation: the registry owns the MECHANISM row (who fires, how it dedupes,
+ * where it rides); the render functions stay where they live (turn-attachments.ts / runtask.ts,
+ * next to their attribution comments — the S1 indexing posture). Behavior-zero slice: the rows
+ * below DESCRIBE the shipped behavior byte-for-byte; the default-policy matrix is consumed live
+ * by the run loop (single source for the M12 attachment-default carve-out).
+ */
 import type { PromptCarrier, PromptTrust } from "./types.js";
+/** Dedupe/replay semantics of one event kind (protocol §5.3). */
 export type EventDedupe = "once-per-epoch" | "once-per-run" | "replace-by-key" | "repeat";
+/** Default mount policy (plan M12): `on` = fires unless explicitly disabled (the [c209-C] Q2
+ *  carve-out pair — the listing frames are the ONLY roster/skills carrier); `off` = fires only
+ *  when the task opts in (the 133 attachment-family constitution: new injection surfaces never
+ *  disturb existing deployments by default); `always` = not policy-gated (mechanism lanes). */
 export type EventDefaultPolicy = "on" | "off" | "always";
 export interface CompiledEventPrompt {
+    /** Event kind — attachment kinds reuse the AttachmentSource wordlist verbatim. */
     kind: string;
     carrier: PromptCarrier;
     trust: PromptTrust;
     dedupe: EventDedupe;
+    /** Byte budget note: attachment kinds share the 8KB boundary cap (evidence-strength ordered);
+     *  a per-kind number here is the kind's OWN clamp where one exists. */
     maxBytes?: number;
     defaultPolicy: EventDefaultPolicy;
+    /** Where the renderer lives (index, not a copy — attribution comments stay at the source). */
     rendererRef: string;
 }
+/** The shipped registry. Rows mirror the live behavior exactly (S5 is formalization, not change):
+ *  - carrier: every boundary attachment + first-frame listing rides the user turn wrapped in a
+ *    single-point `<system-reminder>` shell (`message.user-prefix` on the first frame, user-turn
+ *    steer afterwards — both are the user-prefix carrier class);
+ *  - trust: bodies are engine-rendered (operator) except where the content embeds external text
+ *    (mcp instructions — fenced/sanitized by the renderer, marked external);
+ *  - defaultPolicy: the M12 matrix (runtask.ts attachment-config derivation, single-sourced here).
+ */
 export declare const EVENT_PROMPT_REGISTRY: ReadonlyMap<string, CompiledEventPrompt>;
+/** The M12 default matrix, single-sourced: is this attachment kind on when the task supplies no
+ *  `attachments` config? (Live consumer: the run loop's attachment-config derivation.) */
 export declare function eventDefaultOn(kind: string): boolean;
+/**
+ * One compiled message injection (protocol §5.4; plan M7) — the provider-neutral unit the S4 turn
+ * snapshot will carry. Provenance fields are FIRST-CLASS (mirroring the shipped 1.301 metadata
+ * system verbatim — the consumers' stripping semantics are behavior-frozen): see
+ * `engine/llm/types.ts` UserMessage for the field-by-field contract.
+ */
 export interface CompiledMessageInjection {
     kind: string;
     carrier: PromptCarrier;
+    /** Inner body text — the `<system-reminder>` shell is added at the single delivery point (F3). */
     body: string;
     provenance?: {
         enginePrefixChars?: number;

package/dist/prompt-assembly/explain.d.ts

@@ -28,9 +28,20 @@ export interface ExplainInput {
         activatedBy: string;
     };
 }
+/** Render a `prompt.assembled` manifest (+ optional epoch pin) as a readable report. */
 export declare function explainPromptAssembly(input: ExplainInput): string;
+/**
+ * [1050]①d / [1051]③b — the CENTER-facing read-only description of the default pack: section
+ * metadata (id/slot/rank/ownership/locked) plus the default role-base TEXT (the append-mode
+ * compile skeleton the web UI prepends to a user's "Role details"). Deliberately NO other section
+ * texts (the [989] no-prompt-bodies observability line — structure yes, prose no; the role base is
+ * the one deliberate exception: it is the public compile input of the append mode, and its text is
+ * this open repo's DEFAULT_SYSTEM_PROMPT). Programmatic — a static copy in the web tier would
+ * silently drift the moment core's default prompt changes ([1049]①d 禁静态拷贝).
+ */
 export interface DefaultPackDescription {
     packId: string;
+    /** The pack-default role base (append-mode skeleton). */
     roleBaseText: string;
     sections: Array<{
         id: string;
@@ -39,6 +50,7 @@ export interface DefaultPackDescription {
         owner: string;
         trust: string;
         mutability: string;
+        /** True ⇒ not deployment-writable (the UI shows the platform-managed indicator, never an editor). */
         locked: boolean;
     }>;
 }

package/dist/prompt-assembly/tool-catalog.d.ts

@@ -1,17 +1,38 @@
 import type { TSchema } from "typebox";
 import type { AgentTool } from "../internal/harness-types.js";
 import type { ProtocolId } from "../core/protocol-table.js";
+/** The protocol slice comes from the protocol table — adding a protocol extends ProtocolId and this
+ *  union follows automatically (the origin projection is table-driven, prepare-task). */
 export type ToolOrigin = "core" | "caller" | "synthetic" | ProtocolId;
 export interface ToolContractDescriptor {
+    /** Stable contract identity, e.g. `core.read@2`. Versioned independently of the wire name. */
     contractId: string;
+    /** Declared behavior revision (protocol §7.1: declarative — hashing a JS closure proves nothing). */
     implementationRevision: string;
     wireName: string;
+    /** Live deployment aliases (ToolSpec.aliases) — dispatchable alternate wire names. Retired-name
+     *  replay aliases are gone (RB-476-A, 5.0.0): a persisted old name misses loudly instead. */
     aliases?: string[];
     origin: ToolOrigin;
+    /** Structure-only schema digest (descriptions/titles/examples stripped) — presentation-invariant. */
     shapeDigest: string;
+    /** Full materialized schema digest (incl. descriptions) — the model-visible wire face. */
     wireSchemaDigest: string;
+    /** The presentation card in effect. v1: `builtin:<wireName>` (the factory's inline text). */
     cardId: string;
 }
+/**
+ * Manifest v2 row (protocol §5.4) — {@link projectToolManifest}'s per-tool projection of
+ * {@link ToolContractDescriptor} onto the wire-visible manifest plane. REF-D25 (2026-08):
+ * this is an intentional projection, not a subset alias — it drops `origin` and normalizes
+ * `aliases` from optional to required (empty array when there are none), so it cannot be
+ * expressed as `Pick<ToolContractDescriptor, ...>`. `core/trace.ts` (TraceEvent's
+ * `prompt.assembled` manifest) and `core/runner/prepare-task.ts` (`Prepared.promptManifest.tools`)
+ * both reference this same type — the value flows prepare-task.ts → runtask.ts → trace.ts
+ * untouched, so a shape drift between those two sites would make a real call-shape change
+ * invisible to replay/audit (the same shapeDigest-collision class documented above on
+ * `stripPresentation`).
+ */
 export interface ToolManifestRow {
     wireName: string;
     aliases: string[];
@@ -29,10 +50,27 @@ export interface AttachContractInput {
     origin: ToolOrigin;
     aliases?: string[];
 }
+/** Attach a contract descriptor to a materialized tool (factory exit point). Digests are computed
+ *  from the tool's REAL mounted schema/description, so they always reflect the wire face. */
 export declare function attachToolContract(tool: AgentTool, input: AttachContractInput): void;
+/**
+ * Resolve a tool's descriptor. Undeclared tools get a deterministic legacy descriptor derived from
+ * their shape (`legacy:<shapeDigest>`), origin per the mount channel — an external tool NEVER
+ * inherits a core contract by name (§7.2: don't guess contracts from names).
+ */
 export declare function getToolContract(tool: AgentTool, fallbackOrigin?: ToolOrigin): ToolContractDescriptor;
 export declare function hasToolContract(tool: AgentTool): boolean;
+/** Manifest projection for the final mounted tool set (manifest v2 `tools`, protocol §5.4). */
 export declare function projectToolManifest(tools: AgentTool[], originOf?: (tool: AgentTool) => ToolOrigin): ToolManifestRow[];
+/**
+ * RB-15 (campaign review): wire-identity collision audit over the FINAL mounted tool set.
+ * Rules (plan §6.2 tool row):
+ *   - an ALIAS colliding with another tool's canonical name or alias = FATAL (silent misdispatch
+ *     of durable replays would follow — never ship such a mount);
+ *   - two tools sharing a CANONICAL name = the historic deliberate yield (a caller tool may shadow
+ *     a built-in; the harness Map keeps the later mount) — NOT fatal, but returned as an explicit
+ *     exemption record so the mount site can surface it (observable, never silent).
+ */
 export declare function auditToolCollisions(tools: AgentTool[]): {
     yields: Array<{
         name: string;

package/dist/prompt-assembly/turn-snapshot.d.ts

@@ -1,25 +1,45 @@
 import type { ToolFingerprintInput } from "../core/cache-break-detector.js";
+/** Every prefix-shaping input a request carries — the CLASSIFICATION DOMAIN. Adding a field here
+ *  without classifying it in {@link PREFIX_INPUT_CLASSIFICATION} is a compile error. */
 export interface RawPrefixInputs {
+    /** Provider namespace (cache namespaces never span providers). */
     provider: string;
+    /** Model id (a switch is a new cache namespace). */
     modelId: string;
+    /** The session's pinned prompt-epoch artifact digest (bundled+declarations identity). */
     artifactDigest: string;
+    /** Presentation/policy axis: promptProfile + fable mitigations (prose forks on these). */
     promptProfile: string;
     fableMitigations: boolean;
+    /** Physical block layout as SERVED (derived from the composed system blocks; single-block default). */
     layoutGroups: ReadonlyArray<{
         groupId: string;
         cacheControlBoundary: boolean;
     }>;
+    /** The composed stable system text (digested — text never enters the snapshot object).
+     *  UNSALTED by design, same rule as the tool wireSchemaDigest ("schemas are code"): a full-text
+     *  sha of a LONG composed prompt is an equality oracle only for someone who already possesses the
+     *  exact bytes — unlike the SHORT guessable manifest blocks (env facts, one-line memory) whose
+     *  dictionary-preimage risk is why block hashes are salted. Cross-run comparability is the whole
+     *  point of this identity; salting would destroy it. */
     stableSystemText: string;
+    /** Wire-face tool projections (name/description/schema — the mounted set, post-defer). */
     toolWire: ReadonlyArray<ToolFingerprintInput>;
+    /** Request-shaping controls that alter the wire body. */
     thinkingLevel: string;
     maxTokens: number | undefined;
     hasOutputSchema: boolean;
+    /** Routing/audit fields — provably NOT part of the cacheable prefix. */
     sessionId: string;
     taskId: string | undefined;
+    /** Per-call variables — never reusable, never identity. */
     turn: number;
     cacheRead: number;
 }
 export type PrefixInputClass = "cache-identity" | "volatile-no-reuse" | "proven-irrelevant";
+/** The EXHAUSTIVE classification (§10.2). The `satisfies` bound is the CI gate: a new
+ *  {@link RawPrefixInputs} field fails typecheck until classified here; the runtime pin
+ *  (`test/turn-snapshot.test.ts`) asserts totality survives refactors. Reasons ride inline. */
 export declare const PREFIX_INPUT_CLASSIFICATION: {
     readonly provider: "cache-identity";
     readonly modelId: "cache-identity";
@@ -37,6 +57,7 @@ export declare const PREFIX_INPUT_CLASSIFICATION: {
     readonly turn: "volatile-no-reuse";
     readonly cacheRead: "volatile-no-reuse";
 };
+/** The lowering face (§10.1): version + wire form + that form's KNOWN intentional divergences. */
 export interface LoweringRecord {
     version: string;
     form: "openai-merged" | "anthropic-blocks" | "other";
@@ -44,6 +65,7 @@ export interface LoweringRecord {
 }
 export declare const LOWERING_VERSION = "sema-lowering@1";
 export declare function loweringRecordFor(api: string): LoweringRecord;
+/** The nine identity elements, individually digested (observable without shipping prompt text). */
 export interface CacheIdentityElements {
     provider: string;
     modelId: string;
@@ -57,11 +79,19 @@ export interface CacheIdentityElements {
 }
 export interface TurnPromptSnapshot {
     elements: CacheIdentityElements;
+    /** sha256(canonical(elements)) — the ONE nine-element identity value. */
     cacheIdentity: string;
     lowering: LoweringRecord;
+    /** codex S3 F3 — invoked after EVERY refresh so the run loop can emit the changed identity
+     *  (`prompt.snapshot_changed` trace); traces must never keep claiming a superseded prefix. */
     onChange?: (snapshot: TurnPromptSnapshot) => void;
+    /** Refresh the tool half (design/36 rematerialize follows the declared mid-run change). */
     refreshTools(toolWire: RawPrefixInputs["toolWire"]): void;
+    /** Refresh the stable-system half (RB-31 adoption swap — pass the COMMITTED epoch digest so the
+     *  identity never mixes old-artifact/new-prompt, codex S3 F2). */
     refreshStableSystem(stableSystemText: string, artifactDigest?: string): void;
+    /** codex S3 F1 — request-policy element follows mid-run wire changes (finalize lanes flip the
+     *  thinking level; a served-model swap re-namespaces the cache). */
     refreshRequestPolicy(p: {
         thinkingLevel?: string;
         maxTokens?: number | null;
@@ -71,4 +101,14 @@ export interface TurnPromptSnapshot {
         modelId: string;
     }): void;
 }
+/** Build the run's snapshot from classified raw inputs. Volatile/irrelevant fields are accepted so
+ *  the CLASSIFICATION stays total over everything callers hold, but only identity-class fields can
+ *  reach the digest — enforced structurally (this function reads exactly the identity fields).
+ *
+ *  `promptHasher` (codex S3 F4): the digest applied to COMPOSED PROMPT TEXT — callers inject a
+ *  KEYED/salted hasher (the run loop uses the per-process manifest salt): a fixed public prefix +
+ *  short unknown suffix (an env fact, a memory note, a tenant string) makes an unsalted full-text
+ *  sha ENUMERABLE, recreating exactly the disclosure the salted block hashes prevent. Consequence,
+ *  documented: `stableSystemDigest` (and thus `cacheIdentity`) compares within one process only;
+ *  cross-process reconciliation rides the CODE-class digests (artifact/toolWire — unsalted). */
 export declare function buildTurnPromptSnapshot(raw: Omit<RawPrefixInputs, "turn" | "cacheRead">, api: string, promptHasher?: (text: string) => string): TurnPromptSnapshot;