@sema-agent/core 7.51.1 → 7.52.0

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;

package/dist/prompt-assembly/epoch.js

@@ -7,140 +7,55 @@ export function canonical(node) {
     const keys = Object.keys(node).sort();
     return `{${keys.map((k) => `${JSON.stringify(k)}:${canonical(node[k])}`).join(",")}}`;
 }
-const PROBE_FACTS_OFF = {
-    policyEnabled: false,
-    hooksEnabled: false,
-    isolationEnabled: false,
-    withinTaskCompactionEnabled: false,
-    supervisorEnabled: false,
-    orchestrationEnabled: false,
-    awarenessEnabled: false,
-    goalEnabled: false,
-    worktreeIsolated: false,
-    teammateEnabled: false,
-    orchestrationDeferred: false,
-    isSubagent: false,
-    promptProfile: "simple",
-    fableMitigations: false,
-    readFaceOpen: false,
-    writeFaceOpen: false,
-    reminderMark: undefined,
-};
-const PROBE_FACTS_ON = {
-    policyEnabled: true,
-    hooksEnabled: true,
-    isolationEnabled: true,
-    withinTaskCompactionEnabled: true,
-    supervisorEnabled: true,
-    orchestrationEnabled: true,
-    awarenessEnabled: true,
-    goalEnabled: true,
-    worktreeIsolated: true,
-    teammateEnabled: true,
-    orchestrationDeferred: true,
-    isSubagent: true,
-    promptProfile: "classic",
-    fableMitigations: true,
-    readFaceOpen: true,
-    writeFaceOpen: true,
-    reminderMark: "PROBE-FIXED-MARK-AXIS0",
-};
-const PROBE_VECTORS = [
-    PROBE_FACTS_OFF,
-    PROBE_FACTS_ON,
-    ...Object.keys(PROBE_FACTS_OFF).map((k) => ({ ...PROBE_FACTS_OFF, [k]: PROBE_FACTS_ON[k] })),
-];
-const PROBE_INPUTS_BASE = {
-    roleBase: "\u0000probe-role\u0000",
-    roleAppend: "\u0000probe-append\u0000",
-    mcpInstructionsBlock: "\u0000probe-mcp\u0000",
-    environmentBlock: "\u0000probe-env@2\u0000",
-    memoryBlock: "\u0000probe-memory\u0000",
-    modelGuidance: "\u0000probe-guidance\u0000",
-};
-export function computeBundledArtifactDigest(pack, declared) {
-    const probeSection = (s) => PROBE_VECTORS.map((facts) => {
-        const inputs = { ...PROBE_INPUTS_BASE, facts };
-        try {
-            if (s.admit && !s.admit(inputs))
-                return null;
-            return s.content(inputs) ?? null;
-        }
-        catch {
-            return " probe-threw ";
-        }
-    });
-    const payload = {
-        packId: pack.packId,
-        assemblyApi: pack.assemblyApi,
-        ...(declared !== undefined && declared.length > 0
-            ? { declaredSections: declared.map((d) => ({ id: d.id, slot: d.slot, chars: d.chars, ...(d.contentHash !== undefined ? { contentHash: d.contentHash } : {}) })) }
-            : {}),
-        sections: [...pack.sections].sort((a, b) => a.rank - b.rank).map((s) => ({
-            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,
-            legacyBlockId: s.blockId,
-            probes: probeSection(s),
-        })),
-    };
-    return `sha256:${createHash("sha256").update(canonical(payload)).digest("hex")}`;
+export function digestOf(node) {
+    return `sha256:${createHash("sha256").update(canonical(node)).digest("hex")}`;
 }
-export function mintSessionStartEpoch(pack, declared) {
-    return {
-        epoch: 1,
-        artifactDigest: computeBundledArtifactDigest(pack, declared),
-        packId: pack.packId,
-        assemblyApi: pack.assemblyApi,
-        activatedBy: "session_start",
-    };
+export function catalogDigestOf(catalog) {
+    return digestOf({
+        ...catalog,
+        bands: [...catalog.bands].sort((a, b) => a.id.localeCompare(b.id)),
+        messages: [...catalog.messages].sort((a, b) => a.id.localeCompare(b.id)),
+        sections: [...catalog.sections].sort((a, b) => a.rank - b.rank),
+    });
 }
-export function selectCompactionEpoch(current, pack, declared, centerAdoption) {
-    const digest = computeBundledArtifactDigest(pack, declared);
-    if (centerAdoption === undefined && current && current.artifactDigest === digest) {
-        return { ...current, activatedBy: "compaction" };
-    }
-    return {
-        epoch: (current?.epoch ?? 0) + 1,
-        artifactDigest: digest,
-        packId: pack.packId,
-        assemblyApi: pack.assemblyApi,
-        activatedBy: "compaction",
-        ...(centerAdoption !== undefined
-            ? "clear" in centerAdoption
-                ? {}
-                : {
-                    centerArtifactDigest: centerAdoption.centerArtifactDigest,
-                    ...(centerAdoption.sourceRevision !== undefined ? { sourceRevision: centerAdoption.sourceRevision } : {}),
-                }
-            : current?.centerArtifactDigest !== undefined
-                ? {
-                    centerArtifactDigest: current.centerArtifactDigest,
-                    ...(current.sourceRevision !== undefined ? { sourceRevision: current.sourceRevision } : {}),
-                }
-                : {}),
-    };
+export function promptIdentityOf(layers) {
+    return digestOf({
+        catalog: layers.catalog,
+        renderers: layers.renderers,
+        overlays: digestOf({ center: layers.center ?? null, deploy: layers.deploy ?? null, task: layers.task ?? null }),
+        binding: layers.binding,
+    });
 }
-export function resolveEpochAgainstBundled(pinned, pack, declared) {
-    const digest = computeBundledArtifactDigest(pack, declared);
-    if (pinned && pinned.artifactDigest === digest && pinned.packId === pack.packId && pinned.assemblyApi === pack.assemblyApi) {
-        return { descriptor: pinned, migrated: false };
-    }
+export const PROMPT_EPOCH_ACTIVATIONS = Object.freeze(["session_start", "compaction", "code_change", "selection_change"]);
+export const PROMPT_EPOCH_CHANGES = Object.freeze(["catalog", "renderers", "deploy", "task", "published_schema"]);
+const DIGEST = /^sha256:[0-9a-f]{64}$/;
+const isDigest = (v) => typeof v === "string" && DIGEST.test(v);
+const RETIRED_DESCRIPTOR_FIELDS = Object.freeze(["artifactDigest", "packId", "assemblyApi", "centerArtifactDigest"]);
+function normalizeLayers(raw) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const r = raw;
+    for (const k of Object.keys(r))
+        if (!["catalog", "renderers", "center", "deploy", "task", "binding"].includes(k))
+            return undefined;
+    if (!isDigest(r.catalog) || !isDigest(r.binding))
+        return undefined;
+    for (const k of ["center", "deploy", "task"])
+        if (r[k] !== undefined && !isDigest(r[k]))
+            return undefined;
+    const rv = r.renderers;
+    if (rv === null || typeof rv !== "object" || Array.isArray(rv))
+        return undefined;
+    const entries = Object.entries(rv);
+    if (entries.length > 64 || entries.some(([k, v]) => k.length === 0 || k.length > 64 || typeof v !== "number" || !Number.isInteger(v) || v < 1 || v > 1_000_000))
+        return undefined;
     return {
-        descriptor: {
-            epoch: (pinned?.epoch ?? 0) + 1,
-            artifactDigest: digest,
-            packId: pack.packId,
-            assemblyApi: pack.assemblyApi,
-            activatedBy: "legacy_migration",
-        },
-        migrated: true,
+        catalog: r.catalog,
+        renderers: Object.fromEntries(entries),
+        ...(r.center !== undefined ? { center: r.center } : {}),
+        ...(r.deploy !== undefined ? { deploy: r.deploy } : {}),
+        ...(r.task !== undefined ? { task: r.task } : {}),
+        binding: r.binding,
     };
 }
 export function normalizePromptEpoch(raw) {
@@ -149,23 +64,81 @@ export function normalizePromptEpoch(raw) {
     const r = raw;
     if (typeof r.epoch !== "number" || !Number.isInteger(r.epoch) || r.epoch < 1 || r.epoch > 1_000_000_000)
         return undefined;
-    if (typeof r.artifactDigest !== "string" || !/^sha256:[0-9a-f]{64}$/.test(r.artifactDigest))
+    if (!isDigest(r.identity))
         return undefined;
-    if (typeof r.packId !== "string" || !r.packId.trim() || r.packId.length > 200)
+    const layers = normalizeLayers(r.layers);
+    if (layers === undefined || promptIdentityOf(layers) !== r.identity)
         return undefined;
-    if (r.assemblyApi !== 1)
+    if (!PROMPT_EPOCH_ACTIVATIONS.some((a) => a === r.activatedBy))
         return undefined;
-    if (r.activatedBy !== "session_start" && r.activatedBy !== "compaction" && r.activatedBy !== "legacy_migration")
+    const activatedBy = r.activatedBy;
+    let changed;
+    if (r.changed !== undefined) {
+        if (activatedBy !== "code_change" || !Array.isArray(r.changed) || r.changed.length === 0)
+            return undefined;
+        if (r.changed.some((c) => !PROMPT_EPOCH_CHANGES.some((w) => w === c)) || new Set(r.changed).size !== r.changed.length)
+            return undefined;
+        changed = [...r.changed];
+    }
+    if (r.sourceRevision !== undefined && (layers.center === undefined || typeof r.sourceRevision !== "string" || r.sourceRevision.length === 0 || r.sourceRevision.length > 500))
         return undefined;
-    const centerArtifactDigest = typeof r.centerArtifactDigest === "string" && /^sha256:[0-9a-f]{64}$/.test(r.centerArtifactDigest) ? r.centerArtifactDigest : undefined;
-    const sourceRevision = typeof r.sourceRevision === "string" && r.sourceRevision.length > 0 && r.sourceRevision.length <= 500 ? r.sourceRevision : undefined;
     return {
         epoch: r.epoch,
-        artifactDigest: r.artifactDigest,
-        packId: r.packId,
-        assemblyApi: 1,
-        activatedBy: r.activatedBy,
-        ...(centerArtifactDigest !== undefined ? { centerArtifactDigest } : {}),
-        ...(centerArtifactDigest !== undefined && sourceRevision !== undefined ? { sourceRevision } : {}),
+        identity: r.identity,
+        layers,
+        activatedBy,
+        ...(changed !== undefined ? { changed } : {}),
+        ...(r.sourceRevision !== undefined ? { sourceRevision: r.sourceRevision } : {}),
+    };
+}
+export function readStoredPromptEpoch(raw) {
+    const descriptor = normalizePromptEpoch(raw);
+    if (descriptor !== undefined)
+        return { kind: "pin", descriptor };
+    if (raw === null || typeof raw !== "object")
+        return undefined;
+    const r = raw;
+    if (!RETIRED_DESCRIPTOR_FIELDS.some((f) => f in r))
+        return undefined;
+    return { kind: "legacy", centerPinned: isDigest(r.centerArtifactDigest) };
+}
+function changedLayers(a, b) {
+    const out = [];
+    if (a.catalog !== b.catalog)
+        out.push("catalog");
+    if (canonical(a.renderers) !== canonical(b.renderers))
+        out.push("renderers");
+    if (a.deploy !== b.deploy)
+        out.push("deploy");
+    if (a.task !== b.task)
+        out.push("task");
+    return out;
+}
+function descriptorOf(epoch, layers, activatedBy, extra) {
+    return {
+        epoch,
+        identity: promptIdentityOf(layers),
+        layers,
+        activatedBy,
+        ...(extra.changed !== undefined && extra.changed.length > 0 ? { changed: [...extra.changed] } : {}),
+        ...(layers.center !== undefined && extra.sourceRevision !== undefined ? { sourceRevision: extra.sourceRevision } : {}),
     };
 }
+export function prepareEpochRecord(stored, layers, ctx) {
+    if (stored === undefined)
+        return descriptorOf(1, layers, ctx.priorConversation ? "code_change" : "session_start", ctx);
+    if (stored.kind === "legacy")
+        return descriptorOf(1, layers, "code_change", { ...ctx, ...(stored.centerPinned ? { changed: ["published_schema"] } : {}) });
+    const pinned = stored.descriptor;
+    if (pinned.identity === promptIdentityOf(layers))
+        return undefined;
+    const changed = changedLayers(pinned.layers, layers);
+    return descriptorOf(pinned.epoch + 1, layers, changed.length > 0 ? "code_change" : "selection_change", { ...ctx, changed });
+}
+export function selectCompactionEpoch(current, layers, sourceRevision) {
+    if (current !== undefined && current.identity === promptIdentityOf(layers)) {
+        const { changed: _recordOnly, ...restated } = current;
+        return { ...restated, activatedBy: "compaction" };
+    }
+    return descriptorOf((current?.epoch ?? 0) + 1, layers, "compaction", sourceRevision !== undefined ? { sourceRevision } : {});
+}

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

@@ -1,57 +1,81 @@
+import type { BandId, OverlayOp } from "./catalog/schema.js";
+/** A `prompt.assembled` manifest (v3) as explain reads it: the frame's own members. */
 export interface ExplainInput {
-    constitution: "core" | "replaced" | "provider-assembled";
-    blocks: Array<{
+    identity: {
+        artifact: string;
+        layers: {
+            center?: string;
+            deploy?: string;
+            task?: string;
+        };
+        epoch: number;
+        activatedBy: string;
+    };
+    selectors: {
+        binding?: string;
+        traits: readonly string[];
+        host: {
+            role: string;
+            form: string;
+        };
+    };
+    blocks: ReadonlyArray<{
         id: string;
         chars: number;
         hash: string;
     }>;
-    sections?: Array<{
+    sections: ReadonlyArray<{
         id: string;
-        slot: string;
-        carrier: string;
-        cadence: string;
-        cacheClass: string;
+        band: string;
+        variant?: string;
         chars: number;
-        hash: string;
-        contentHash?: string;
+        locale: string;
+        contentHash: string;
+        chain: ReadonlyArray<{
+            source: string;
+            overlay?: string;
+            op?: string;
+            superseded?: true;
+        }>;
     }>;
-    tools?: Array<{
+    superseded?: ReadonlyArray<{
+        id: string;
+        source: string;
+        by: string;
+        target: string;
+        supersededBy: string;
+    }>;
+    tools?: ReadonlyArray<{
         wireName: string;
         contractId: string;
         cardId: string;
         shapeDigest: string;
     }>;
-    epoch?: {
-        epoch: number;
-        artifactDigest: string;
-        packId: string;
-        activatedBy: string;
-    };
 }
-/** Render a `prompt.assembled` manifest (+ optional epoch pin) as a readable report. */
+/** Render a `prompt.assembled` manifest as a readable report: which prompt (identity, its layers, the selector values),
+ *  what composed it, and where each section's text came from. */
 export declare function explainPromptAssembly(input: ExplainInput): string;
 /**
- * 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 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 (no static copies).
+ * The CENTER-facing read-only description of the bundled catalog: each section's id, band, rank and what each overlay
+ * source class may do to it (the band's three op columns — a center editor reads `ops.center`; an empty column for
+ * every class is a platform-managed section), plus the default role-base TEXT (the append-mode compile skeleton the web
+ * UI prepends to a user's "Role details"). No other section texts. Programmatic — a static copy in the web tier would
+ * drift the moment the catalog changes.
  */
-export interface DefaultPackDescription {
-    packId: string;
-    /** The pack-default role base (append-mode skeleton). */
+export interface CatalogDescription {
+    catalogId: string;
+    /** The catalog-default role base (append-mode skeleton). */
     roleBaseText: string;
     sections: Array<{
         id: string;
-        slot: string;
+        band: BandId;
         rank: number;
-        owner: string;
-        trust: string;
-        mutability: string;
-        /** True ⇒ not deployment-writable (the UI shows the platform-managed indicator, never an editor). */
-        locked: boolean;
+        /** The band's op columns: what a center artifact, a deployment's mods and a task may do to this section. */
+        ops: {
+            center: readonly OverlayOp[];
+            deploy: readonly OverlayOp[];
+            task: readonly OverlayOp[];
+        };
     }>;
 }
-export declare function describeDefaultPack(): DefaultPackDescription;
+export declare function describeCatalog(): CatalogDescription;

package/dist/prompt-assembly/explain.js

@@ -1,23 +1,28 @@
 import { EVENT_PROMPT_REGISTRY } from "./event-registry.js";
-import { SEMA_DEFAULT_PACK } from "./packs/sema-default.js";
-import { DEFAULT_SYSTEM_PROMPT } from "../prompts/default.js";
+import { bandOf } from "./bands.js";
+import { SEMA_DEFAULT_CATALOG, catalogText } from "./catalog/index.js";
 function safeId(raw) {
-    const cleaned = raw.replace(/[\u0000-\u001f\u007f]/g, "\u2400");
+    const cleaned = raw.replace(/[\u0000-\u001f\u007f]/g, "␀");
     return cleaned.length > 120 ? `${cleaned.slice(0, 117)}...` : cleaned;
 }
 export function explainPromptAssembly(input) {
     const lines = [];
-    lines.push(`constitution: ${safeId(input.constitution)}${input.constitution === "core" ? "" : " (non-default — see PromptProvider tier docs)"}`);
-    if (input.epoch) {
-        lines.push(`epoch: #${input.epoch.epoch} on ${safeId(input.epoch.packId)} (${safeId(input.epoch.artifactDigest).slice(0, 23)}…) via ${safeId(input.epoch.activatedBy)}`);
-    }
-    lines.push(`system blocks (v1 view): ${input.blocks.map((b) => `${safeId(b.id)}[${b.chars}ch]`).join(" → ")}`);
-    if (input.sections?.length) {
-        lines.push("sections (compiled IR):");
-        for (const s of input.sections) {
-            lines.push(`  ${safeId(s.id)}  slot=${safeId(s.slot)} carrier=${safeId(s.carrier)} cadence=${safeId(s.cadence)} cache=${safeId(s.cacheClass)} ${s.chars}ch #${safeId(s.hash)}${s.contentHash !== undefined ? ` content=${safeId(s.contentHash)}` : ""}`);
+    const short = (d) => (d === undefined ? "none" : `${safeId(d).slice(0, 23)}…`);
+    lines.push(`identity: ${short(input.identity.artifact)} (record #${input.identity.epoch} via ${safeId(input.identity.activatedBy)})`);
+    lines.push(`  layers: center=${short(input.identity.layers.center)} deploy=${short(input.identity.layers.deploy)} task=${short(input.identity.layers.task)}`);
+    const s = input.selectors;
+    lines.push(`  selectors: role=${safeId(s.host.role)} form=${safeId(s.host.form)} traits=[${s.traits.map(safeId).join(", ")}]${s.binding !== undefined ? ` binding=${safeId(s.binding)}` : ""}`);
+    lines.push(`system blocks: ${input.blocks.map((b) => `${safeId(b.id)}[${b.chars}ch]`).join(" → ")}`);
+    if (input.sections.length > 0) {
+        lines.push("sections:");
+        for (const sec of input.sections) {
+            const chain = sec.chain.map((l) => (l.source === "bundled" ? "bundled" : `${safeId(l.source)}:${l.op ?? "?"} ${safeId(l.overlay ?? "?")}${l.superseded === true ? " (superseded)" : ""}`)).join(" > ");
+            lines.push(`  ${safeId(sec.id)}  band=${safeId(sec.band)}${sec.variant !== undefined ? ` variant=${safeId(sec.variant)}` : ""} ${sec.chars}ch ${safeId(sec.locale)} ${safeId(sec.contentHash).slice(0, 19)}…  ${chain}`);
         }
     }
+    if (input.superseded?.length) {
+        lines.push(`superseded: ${input.superseded.map((o) => `${safeId(o.id)} (${safeId(o.source)}) on ${safeId(o.target)} by ${safeId(o.supersededBy)}`).join("; ")}`);
+    }
     if (input.tools?.length) {
         const legacy = input.tools.filter((t) => t.contractId.startsWith("legacy:"));
         lines.push(`tools: ${input.tools.length} mounted (${input.tools.length - legacy.length} contract-declared, ${legacy.length} legacy/external)`);
@@ -26,18 +31,10 @@ export function explainPromptAssembly(input) {
     lines.push(`event kinds registered: ${kinds.length} (default-on: ${kinds.filter((k) => k.defaultPolicy === "on").map((k) => k.kind).join(", ")})`);
     return lines.join("\n");
 }
-export function describeDefaultPack() {
+export function describeCatalog() {
     return {
-        packId: SEMA_DEFAULT_PACK.packId,
-        roleBaseText: DEFAULT_SYSTEM_PROMPT,
-        sections: [...SEMA_DEFAULT_PACK.sections].sort((a, b) => a.rank - b.rank).map((s) => ({
-            id: s.id,
-            slot: s.slot,
-            rank: s.rank,
-            owner: s.owner,
-            trust: s.trust,
-            mutability: s.mutability,
-            locked: s.mutability === "locked",
-        })),
+        catalogId: SEMA_DEFAULT_CATALOG.id,
+        roleBaseText: catalogText("core/role.base", "default"),
+        sections: [...SEMA_DEFAULT_CATALOG.sections].sort((a, b) => a.rank - b.rank).map((s) => ({ id: s.id, band: s.band, rank: s.rank, ops: bandOf(s.band).ops })),
     };
 }