@sema-agent/core 7.51.2 → 7.53.0

package/dist/prompt-assembly/composer.js

@@ -1,67 +1,145 @@
+import { catalogMessage } from "./catalog/index.js";
+import { foldOverlays } from "./overlay.js";
+import { RENDERERS, runRenderer } from "./renderers.js";
+import { factsHold, selectVariant, selectorsOf, whenHolds } from "./select.js";
 function joinParts(parts) {
     return parts.filter((p) => Boolean(p && p.trim())).join("\n\n");
 }
-export function validatePack(pack) {
-    const ids = new Set();
-    const ranks = new Set();
-    for (const s of pack.sections) {
-        if (!s.id || !s.id.trim())
-            throw new Error(`prompt-pack ${pack.packId}: section with empty id`);
-        if (ids.has(s.id))
-            throw new Error(`prompt-pack ${pack.packId}: duplicate section id "${s.id}"`);
-        ids.add(s.id);
-        if (ranks.has(s.rank))
-            throw new Error(`prompt-pack ${pack.packId}: duplicate rank ${s.rank} ("${s.id}")`);
-        ranks.add(s.rank);
-        if (s.blockJoiner !== undefined && s.blockJoiner !== "\n" && s.blockJoiner !== "\n\n") {
-            throw new Error(`prompt-pack ${pack.packId}: section "${s.id}" has invalid blockJoiner`);
+function basesOf(catalog, inputs, s) {
+    const bases = new Map();
+    for (const section of catalog.sections) {
+        if (!factsHold(section.admit, s.facts))
+            continue;
+        if ("renderer" in section.body) {
+            const out = runRenderer(section.body.renderer, inputs, s);
+            if (out !== undefined && out.text.trim())
+                bases.set(section.id, { kind: "renderer", text: out.text, ...(out.variant !== undefined ? { variant: out.variant } : {}) });
+            continue;
+        }
+        const lines = "message" in section.body ? [{ message: section.body.message }] : section.body.lines;
+        const picked = [];
+        for (const line of lines) {
+            if ("admit" in line && !factsHold(line.admit, s.facts))
+                continue;
+            const v = selectVariant(catalogMessage(line.message, catalog), s);
+            if (v !== undefined)
+                picked.push({ message: line.message, text: v.text, variant: v.id });
         }
+        bases.set(section.id, { kind: "lines", lines: picked });
     }
+    return bases;
 }
-function renderSection(s, inputs) {
-    if (s.admit && !s.admit(inputs))
-        return undefined;
-    const text = s.content(inputs);
-    if (!text || !text.trim())
+function selectedTextOf(catalog, bases) {
+    const sectionOf = new Map();
+    for (const sec of catalog.sections) {
+        const ids = "message" in sec.body ? [sec.body.message] : "lines" in sec.body ? sec.body.lines.map((l) => l.message) : (RENDERERS[sec.body.renderer].messages ?? []);
+        for (const id of ids)
+            sectionOf.set(id, sec);
+    }
+    return (messageId) => {
+        const sec = sectionOf.get(messageId);
+        const base = sec === undefined ? undefined : bases.get(sec.id);
+        if (base === undefined)
+            return undefined;
+        if (base.kind === "renderer")
+            return base.text;
+        return base.lines.find((l) => l.message === messageId)?.text;
+    };
+}
+function renderSection(section, base, fold) {
+    let text;
+    let variant;
+    if (base.kind === "renderer") {
+        const m = "renderer" in section.body ? RENDERERS[section.body.renderer].messages?.[0] : undefined;
+        const over = m !== undefined ? fold.messageText.get(m) : undefined;
+        text = over?.text ?? base.text;
+        variant = base.variant;
+    }
+    else {
+        const parts = base.lines.map((l) => fold.messageText.get(l.message)?.text ?? l.text);
+        if (parts.length === 0)
+            return undefined;
+        const joiner = "message" in section.body ? "" : "lines" in section.body ? section.body.joiner : "";
+        text = parts.join(joiner);
+        variant = base.lines.map((l) => l.variant).join("+");
+    }
+    if (!text.trim())
         return undefined;
     return {
-        id: s.id,
-        slot: s.slot,
-        rank: s.rank,
-        owner: s.owner,
-        trust: s.trust,
-        mutability: s.mutability,
-        cadence: s.cadence,
-        cacheClass: s.cacheClass,
-        carrier: s.carrier,
+        id: section.id,
+        band: section.band,
+        rank: section.rank,
+        ...(variant !== undefined ? { variant } : {}),
         text,
-        blockId: s.blockId,
-        blockJoiner: s.blockJoiner ?? "\n\n",
-        ...(s.declaredContentHash ? { declaredContentHash: s.declaredContentHash } : {}),
-        ...(s.origin ? { origin: s.origin } : {}),
+        blockId: section.block.id,
+        blockJoiner: section.block.joiner ?? "\n\n",
+        chain: [{ source: "bundled" }, ...(fold.chains.get(section.id) ?? [])],
+        ...("renderer" in section.body ? { renderer: { id: section.body.renderer, version: RENDERERS[section.body.renderer].version } } : {}),
+    };
+}
+function renderAdded(e, fold) {
+    if (!e.text.trim())
+        return undefined;
+    return {
+        id: e.id,
+        band: e.band,
+        rank: e.rank,
+        text: e.text,
+        blockId: e.id.startsWith("core/") ? e.id.slice("core/".length) : e.id,
+        blockJoiner: "\n\n",
+        chain: fold.chains.get(e.id) ?? [],
     };
 }
-export function compose(pack, inputs) {
-    validatePack(pack);
-    const ordered = [...pack.sections].sort((a, b) => a.rank - b.rank);
+export function composeCatalog(plan, inputs) {
+    const s = selectorsOf(inputs.facts, plan.host, plan.binding);
+    const bases = basesOf(plan.catalog, inputs, s);
+    const selectedText = selectedTextOf(plan.catalog, bases);
+    const overlayText = (o) => {
+        if (o.text !== undefined)
+            return o.text;
+        if (o.message === undefined)
+            return undefined;
+        return selectVariant(catalogMessage(o.message, plan.catalog), s)?.text;
+    };
+    const fold = foldOverlays(plan.overlays ?? [], selectedText, (o) => whenHolds(o.when, s), overlayText);
+    const rows = [];
+    for (const section of plan.catalog.sections) {
+        if (fold.dropped.has(section.id))
+            continue;
+        const base = bases.get(section.id);
+        if (base === undefined)
+            continue;
+        rows.push({ rank: section.rank, id: section.id, render: () => renderSection(section, base, fold) });
+    }
+    for (const e of fold.added)
+        rows.push({ rank: e.rank, id: e.id, render: () => renderAdded(e, fold) });
+    rows.sort((a, b) => a.rank - b.rank);
+    const ranks = new Set();
+    const ids = new Set();
+    for (const r of rows) {
+        if (ids.has(r.id))
+            throw new Error(`prompt composition: duplicate section id "${r.id}"`);
+        if (ranks.has(r.rank))
+            throw new Error(`prompt composition: duplicate rank ${r.rank} ("${r.id}")`);
+        ids.add(r.id);
+        ranks.add(r.rank);
+    }
     const sections = [];
-    for (const s of ordered) {
-        const compiled = renderSection(s, inputs);
+    for (const r of rows) {
+        const compiled = r.render();
         if (compiled)
             sections.push(compiled);
     }
-    const text = joinParts(sections.map((s) => s.text));
+    const text = joinParts(sections.map((x) => x.text));
     const blocks = [];
-    for (const s of sections) {
+    for (const x of sections) {
         const last = blocks[blocks.length - 1];
-        if (last && last.id === s.blockId) {
-            last.text = `${last.text}${s.blockJoiner}${s.text}`;
-        }
-        else {
-            blocks.push({ id: s.blockId, text: s.text });
-        }
+        if (last && last.id === x.blockId)
+            last.text = `${last.text}${x.blockJoiner}${x.text}`;
+        else
+            blocks.push({ id: x.blockId, text: x.text });
     }
-    return { text, sections, blocks };
+    return { text, sections, blocks, superseded: fold.superseded };
 }
 export const SINGLE_BLOCK_LAYOUT = { groups: [{ groupId: "body", untilRank: Number.POSITIVE_INFINITY, cacheControlBoundary: true }] };
 export function layoutSystemBlocks(composed, layout = SINGLE_BLOCK_LAYOUT) {

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

@@ -1,85 +1,95 @@
-import type { PromptPack } from "./types.js";
-/** 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.
- *
- *  (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). */
+import type { PromptCatalog } from "./catalog/schema.js";
+/** Deterministic canonical JSON (sorted keys) — the one identity encoding (the catalog digest, the identity, the
+ *  center artifact digest). */
+export declare function canonical(node: unknown): string;
+/** `sha256:<hex>` over a canonical encoding. */
+export declare function digestOf(node: unknown): string;
+/** The bundled catalog's digest. Array positions that carry no meaning are normalized (sections by rank, messages and
+ *  bands by id), so the digest does not depend on how a module lays out its arrays; variant order is meaning (first
+ *  match wins) and stays. */
+export declare function catalogDigestOf(catalog: PromptCatalog): string;
+/** The inputs of a run's prompt identity. Only `center` is pinned (resolved by digest on resume); the rest are what
+ *  the run computed, kept so a later run can say what changed. Absent `center` / `deploy` / `task` = that layer
+ *  contributed nothing. */
+export interface PromptIdentityLayers {
+    readonly catalog: string;
+    readonly renderers: Readonly<Record<string, number>>;
+    /** The adopted center artifact's digest. */
+    readonly center?: string;
+    readonly deploy?: string;
+    readonly task?: string;
+    /** H(the run's selector values). */
+    readonly binding: string;
+}
+/** A run's prompt identity inputs plus its pinned center layer's provenance — what the epoch record carries. */
+export interface RunPromptIdentity {
+    readonly layers: PromptIdentityLayers;
+    readonly sourceRevision?: string;
+}
+/** The one identity digest over the four inputs. */
+export declare function promptIdentityOf(layers: PromptIdentityLayers): string;
+/** How a recorded epoch came to be: a legal boundary (`session_start`, `compaction`), or a record that code or
+ *  inputs moved (`code_change`, naming the changed layers when they are known) or that only the selector values
+ *  did (`selection_change`). */
+export declare const PROMPT_EPOCH_ACTIVATIONS: readonly ["session_start", "compaction", "code_change", "selection_change"];
+export type PromptEpochActivation = (typeof PROMPT_EPOCH_ACTIVATIONS)[number];
+/** What a `code_change` record names as changed. `published_schema` is the one replacement of a retired-shape center
+ *  pin by the current center layer. */
+export declare const PROMPT_EPOCH_CHANGES: readonly ["catalog", "renderers", "deploy", "task", "published_schema"];
+export type PromptEpochChange = (typeof PROMPT_EPOCH_CHANGES)[number];
+/** The durable record, persisted as a first-class session entry and restated in every compaction entry's
+ *  `details.promptEpoch`. */
 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;
+    /** Monotonic per-session record counter. */
+    readonly epoch: number;
+    /** The run's prompt identity ({@link promptIdentityOf}). */
+    readonly identity: string;
+    readonly layers: PromptIdentityLayers;
+    readonly activatedBy: PromptEpochActivation;
+    /** Present only on `code_change` records whose changed layers are known. */
+    readonly changed?: readonly PromptEpochChange[];
+    /** Opaque publish provenance of the pinned center layer (present only with `layers.center`; never digested). */
+    readonly 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;
-/** 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;
+/** What a stored epoch record reads as on the resume path: a v3 pin, or a retired shape recognized by name. */
+export type StoredPromptEpoch = {
+    readonly kind: "pin";
+    readonly descriptor: PromptEpochDescriptor;
 } | {
-    clear: true;
-}): PromptEpochDescriptor;
+    readonly kind: "legacy";
+    readonly centerPinned: boolean;
+};
 /**
- * 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.
+ * Shape-normalize an untrusted v3 descriptor — the current shape's one judge (the first reading of
+ * {@link readStoredPromptEpoch}; a session backend judges a record with it). Strict: a bounded positive epoch, a full
+ * digest identity that MATCHES its layers, the closed activation and change vocabularies, provenance only beside a
+ * center layer. Members it does not read (a session entry's own `type` / `id` / `parentId` / `timestamp`) are ignored.
+ * Undefined for anything else — including every retired shape.
  */
-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;
+/**
+ * The resume path's reading of one stored record: a valid v3 pin, `legacy` (a retired shape, recognized by its field
+ * names — nothing in it is parsed but whether `centerArtifactDigest` is a digest, the only value the retired reader
+ * took for a pin), or undefined (malformed: the walk skips it).
+ */
+export declare function readStoredPromptEpoch(raw: unknown): StoredPromptEpoch | undefined;
+/**
+ * The record a run leaves at prepare, or undefined when the stored pin already names this run's identity.
+ * - no record: `session_start` for a session with no prior conversation; otherwise `code_change` (a session that
+ *   predates epochs — what changed is unknown);
+ * - a v3 pin: the same identity ⇒ nothing; else `code_change` naming the changed code / input layers, or
+ *   `selection_change` when only the selector values moved;
+ * - `legacy`: `code_change` — naming `published_schema` when the retired record pinned a center artifact (the caller
+ *   applied the center source's tri-state to it), otherwise unknown. The retired record's counter is not read; the
+ *   v3 line starts at 1.
+ */
+export declare function prepareEpochRecord(stored: StoredPromptEpoch | undefined, layers: PromptIdentityLayers, ctx: {
+    readonly priorConversation: boolean;
+    readonly sourceRevision?: string;
+}): PromptEpochDescriptor | undefined;
+/**
+ * The record a compaction restates or advances: the current pin restated when the run's identity is unchanged (the
+ * boundary is stamped), otherwise a new record with the run's layers after the boundary — an adopted center
+ * candidate, or an emptied center layer after an explicit revocation.
+ */
+export declare function selectCompactionEpoch(current: PromptEpochDescriptor | undefined, layers: PromptIdentityLayers, sourceRevision?: string): PromptEpochDescriptor;