@sema-agent/core 7.51.2 → 7.52.0

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

@@ -0,0 +1,127 @@
+import { type BandId, type CatalogSection, type OverlayOp, type OverlaySource, type VariantWhen } from "./catalog/schema.js";
+/** One overlay: an operation on a target, carrying text (or a catalog message reference). */
+export interface PromptOverlay {
+    /** `<namespace>/<name>`; the `core/` namespace is the task sugar's alone. Names an added entry. */
+    readonly id: string;
+    readonly op: OverlayOp;
+    /** A message id (`replace` / `append`), a band id (`add`), or a section / added-entry id (`drop`). */
+    readonly target: string;
+    /** The overlay's text (`replace` / `append` / `add`); exclusive with `message`. */
+    readonly text?: string;
+    /** A catalog message whose selected variant is the overlay's text; exclusive with `text`. */
+    readonly message?: string;
+    /** Selects a center artifact's overlay by binding; carried by center artifacts only. */
+    readonly scope?: {
+        readonly binding?: string;
+    };
+    /** The overlay applies to this run only when this holds (the variant selector's own closed vocabulary). */
+    readonly when?: VariantWhen;
+}
+/** The source classes in application order (later wins). `bundled` is the catalog itself and writes no overlay. */
+export declare const OVERLAY_SOURCE_ORDER: readonly ["bundled", "task", "center", "deploy"];
+/** Who contributed an overlay: its source class and, within it, the contributor (`sugar`, a mods registration, the center). */
+export interface OverlayOrigin {
+    readonly source: OverlaySource;
+    readonly by: string;
+}
+export interface SourcedOverlay {
+    readonly overlay: PromptOverlay;
+    readonly origin: OverlayOrigin;
+}
+/** An overlay a later one on the same target overrode (or a drop removed), or one that changed nothing this run. */
+export interface SupersededOverlay {
+    readonly id: string;
+    readonly source: OverlaySource;
+    readonly by: string;
+    readonly target: string;
+    /** The overlay id that won, or {@link ABSENT_THIS_RUN}. */
+    readonly supersededBy: string;
+}
+/** `supersededBy` of an overlay that changed nothing this run: the selector chose no variant of its target, or of
+ *  the catalog message it takes its text from. */
+export declare const ABSENT_THIS_RUN = "(absent this run)";
+/** The section a message id is placed by, when the catalog places it. */
+export declare function sectionOfMessage(id: string): CatalogSection | undefined;
+export interface LockedEntry {
+    readonly message: string;
+    readonly variant: string;
+    readonly text: string;
+}
+/** Every constitution entry the guard compares: each message a constitution section places, every variant, whole. */
+export declare function lockedEntries(): readonly LockedEntry[];
+/** The constitution entries (`message#variant`) whose canonical text `text` contains verbatim. */
+export declare function lockedTextIn(text: string): string[];
+/** The task sugar's one violation: a role-layer text that carries locked text (an already-assembled prompt). */
+export declare function assembledRoleRefused(field: string, hits: readonly string[]): Error;
+/** Receive a source's prompt data ({@link PROMPT_DATA}): its frozen copy, or the clause naming what in it is not data. */
+export declare function receivePromptData(raw: unknown): {
+    readonly value: unknown;
+} | {
+    readonly notData: string;
+};
+/**
+ * The run's center binding (`TaskSpec.promptBinding`): the key a center artifact's scoped overlays are selected by.
+ * Its one writer is the task (a deployment names its scenario); absent ⇒ undefined. A value outside the grammar is
+ * refused by name (`config.prompt_selector_invalid`), never read as absent.
+ */
+export declare function resolvePromptBinding(task: {
+    readonly promptBinding?: unknown;
+}): string | undefined;
+/** What a validation needs besides the overlay: its source class, which mods event (if any) carries it, and the
+ *  entries lower classes added (the only entries a `drop` may name besides a built-in section). */
+export interface OverlayValidationContext {
+    readonly source: OverlaySource;
+    /** The mods event the overlay arrived on; absent for the sugar and the center. */
+    readonly event?: "prompt.compose";
+    /** The request-body sugar may use the `core/` namespace; nothing else may. */
+    readonly sugar?: boolean;
+    /** Ids of entries lower source classes added (`add`) and the band each landed in. */
+    readonly lowerAdds?: ReadonlyMap<string, BandId>;
+}
+/**
+ * Validate one overlay for one source class. Returns the overlay (a frozen copy of its known members) or why it is
+ * a violation: shape, namespace, op, text/message, `when`, `scope`, target existence, band authorization (and the
+ * band's mods write port), and the locked-text guard.
+ */
+export declare function validateOverlay(raw: unknown, ctx: OverlayValidationContext): {
+    readonly overlay: PromptOverlay;
+} | {
+    readonly violation: string;
+};
+/** One added entry as the fold leaves it. */
+export interface AddedEntry {
+    readonly id: string;
+    readonly band: BandId;
+    readonly rank: number;
+    readonly text: string;
+    readonly origin: OverlayOrigin;
+}
+/** One overlay in a section's history, in application order; `superseded` once a later one overrode it. The
+ *  composition puts the catalog's own text (`bundled`) first for a catalog section. */
+export interface ChainLink {
+    readonly source: "bundled" | OverlaySource;
+    readonly overlay?: string;
+    readonly op?: OverlayOp;
+    readonly superseded?: true;
+}
+/** The fold's result: per-message text the overlays set, dropped sections, added entries, superseded overlays. */
+export interface OverlayFold {
+    /** Message id → its text after the overlays (absent ⇒ the selected variant's text stands). */
+    readonly messageText: ReadonlyMap<string, {
+        readonly text: string;
+        readonly origin: OverlayOrigin;
+        readonly replaced: boolean;
+    }>;
+    /** Built-in section ids a drop removed. */
+    readonly dropped: ReadonlySet<string>;
+    readonly added: readonly AddedEntry[];
+    readonly superseded: readonly SupersededOverlay[];
+    /** Section id (or added-entry id) → the overlays applied to it, in order, superseded ones marked. */
+    readonly chains: ReadonlyMap<string, readonly ChainLink[]>;
+}
+/**
+ * Apply sourced overlays, already validated and already in application order, over the selected texts.
+ * `selectedText(messageId)` answers the text the selector chose (undefined ⇒ the message is absent this run);
+ * `applies(overlay)` answers its `when`.
+ */
+export declare function foldOverlays(ordered: readonly SourcedOverlay[], selectedText: (messageId: string) => string | undefined, applies: (o: PromptOverlay) => boolean, overlayText: (o: PromptOverlay) => string | undefined): OverlayFold;

package/dist/prompt-assembly/overlay.js

@@ -0,0 +1,301 @@
+import { types } from "node:util";
+import { describeFault, isPlainRecord, receive } from "../core/mods/kernel/receive.js";
+import { egressText } from "../core/untrusted-egress.js";
+import { bandOf, isBandId } from "./bands.js";
+import { SEMA_DEFAULT_CATALOG, catalogMessage } from "./catalog/index.js";
+import { HOST_FORMS, HOST_ROLES, OVERLAY_OPS, PROMPT_FACT_NAMES, PROMPT_TRAITS, isWordOf, } from "./catalog/schema.js";
+import { RENDERERS } from "./renderers.js";
+export const OVERLAY_SOURCE_ORDER = Object.freeze(["bundled", "task", "center", "deploy"]);
+export const ABSENT_THIS_RUN = "(absent this run)";
+const SECTION_BY_ID = new Map(SEMA_DEFAULT_CATALOG.sections.map((s) => [s.id, s]));
+const MESSAGE_TARGETS = (() => {
+    const m = new Map();
+    for (const s of SEMA_DEFAULT_CATALOG.sections) {
+        const ids = "message" in s.body ? [s.body.message] : "lines" in s.body ? s.body.lines.map((l) => l.message) : (RENDERERS[s.body.renderer].messages ?? []);
+        for (const id of ids)
+            m.set(id, { section: s });
+    }
+    return m;
+})();
+const MESSAGE_IDS = new Set(SEMA_DEFAULT_CATALOG.messages.map((m) => m.id));
+export function sectionOfMessage(id) {
+    return MESSAGE_TARGETS.get(id)?.section;
+}
+const LOCKED = Object.freeze(SEMA_DEFAULT_CATALOG.sections
+    .filter((s) => s.band === "constitution" && !("renderer" in s.body))
+    .flatMap((s) => ("message" in s.body ? [s.body.message] : "lines" in s.body ? s.body.lines.map((l) => l.message) : []))
+    .flatMap((id) => catalogMessage(id).variants.map((v) => Object.freeze({ message: id, variant: v.id, text: v.text }))));
+export function lockedEntries() {
+    return LOCKED;
+}
+export function lockedTextIn(text) {
+    const hits = [];
+    for (const e of LOCKED)
+        if (text.includes(e.text))
+            hits.push(`${e.message}#${e.variant}`);
+    return hits;
+}
+export function assembledRoleRefused(field, hits) {
+    const named = [...new Set(hits.map((h) => h.split("#")[0]))];
+    return Object.assign(new Error(`prompt.assembled_role_refused: ${field} contains, verbatim, the locked text of ${named.slice(0, 4).join(", ")}${named.length > 4 ? ` and ${named.length - 4} more` : ""} — the engine composes the locked sections itself; supply only the role layer (an already-assembled prompt is refused, never passed through)`), { code: "prompt.assembled_role_refused" });
+}
+const ID_GRAMMAR = /^[a-z0-9][a-z0-9/._-]*$/;
+const OVERLAY_KEYS = new Set(["id", "op", "target", "text", "message", "scope", "when"]);
+const OPS = new Set(OVERLAY_OPS);
+const PROMPT_DATA = Object.freeze({ accessors: "refuse", depth: 4, others: "refuse", freeze: true, isProxy: (v) => types.isProxy(v) });
+export function receivePromptData(raw) {
+    const r = receive(raw, PROMPT_DATA);
+    return r.ok ? { value: r.value } : { notData: describeFault(r.fault) };
+}
+const BINDING_MAX = 128;
+function bindingProblem(v) {
+    return typeof v !== "string" || v.trim() === "" || v.length > BINDING_MAX ? `${str(v)} is not a non-blank string of at most ${BINDING_MAX} characters` : undefined;
+}
+export function resolvePromptBinding(task) {
+    if (task.promptBinding === undefined)
+        return undefined;
+    const why = bindingProblem(task.promptBinding);
+    if (why !== undefined)
+        throw Object.assign(new Error(`TaskSpec.promptBinding ${why} (or absent)`), { code: "config.prompt_selector_invalid" });
+    return task.promptBinding;
+}
+function str(v, max = 160) {
+    if (typeof v !== "string")
+        return typeof v;
+    const e = egressText("same-principal", v);
+    return JSON.stringify(e.length > max ? `${e.slice(0, max)}…` : e);
+}
+function whenViolation(when) {
+    if (typeof when !== "object" || when === null || Array.isArray(when))
+        return `"when" is ${str(when)}, not an object`;
+    for (const k of Object.keys(when))
+        if (k !== "traits" && k !== "host" && k !== "facts")
+            return `"when" carries ${str(k)} (traits, host, facts only)`;
+    const w = when;
+    if (w["traits"] !== undefined) {
+        const t = w["traits"];
+        if (typeof t !== "object" || t === null || Array.isArray(t))
+            return `"when.traits" is not an object`;
+        for (const [k, list] of Object.entries(t)) {
+            if (k !== "allOf" && k !== "noneOf")
+                return `"when.traits" carries ${str(k)} (allOf, noneOf only)`;
+            if (!Array.isArray(list))
+                return `"when.traits.${k}" is not an array`;
+            for (const name of list)
+                if (!isWordOf(PROMPT_TRAITS, name))
+                    return `"when.traits.${k}" names ${str(name)}, not a trait (${PROMPT_TRAITS.join(", ")})`;
+        }
+    }
+    if (w["host"] !== undefined) {
+        const h = w["host"];
+        if (typeof h !== "object" || h === null || Array.isArray(h))
+            return `"when.host" is not an object`;
+        for (const [k, v] of Object.entries(h)) {
+            if (k === "role" ? !isWordOf(HOST_ROLES, v) : k === "form" ? !isWordOf(HOST_FORMS, v) : true) {
+                return `"when.host" carries ${str(k)} = ${str(v)} (role: ${HOST_ROLES.join(" | ")}; form: ${HOST_FORMS.join(" | ")})`;
+            }
+        }
+    }
+    if (w["facts"] !== undefined) {
+        const f = w["facts"];
+        if (typeof f !== "object" || f === null || Array.isArray(f))
+            return `"when.facts" is not an object`;
+        for (const [k, v] of Object.entries(f)) {
+            if (!isWordOf(PROMPT_FACT_NAMES, k))
+                return `"when.facts" names ${str(k)}, not a fact`;
+            if (typeof v !== "boolean")
+                return `"when.facts.${k}" is ${str(v)}, not a boolean`;
+        }
+    }
+    return undefined;
+}
+function textsOf(o) {
+    if (o.text !== undefined)
+        return [o.text];
+    if (o.message !== undefined && MESSAGE_IDS.has(o.message))
+        return catalogMessage(o.message).variants.map((v) => v.text);
+    return [];
+}
+export function validateOverlay(raw, ctx) {
+    const fail = (why) => ({ violation: why });
+    const received = receivePromptData(raw);
+    if ("notData" in received)
+        return fail(`an overlay is data (plain objects, arrays, strings, booleans); it holds ${received.notData}`);
+    const r = received.value;
+    if (!isPlainRecord(r))
+        return fail(`an overlay is an object, got ${Array.isArray(r) ? "an array" : str(r)}`);
+    for (const k of Object.keys(r))
+        if (!OVERLAY_KEYS.has(k))
+            return fail(`an overlay carries ${str(k)} (id, op, target, text, message, scope, when only)`);
+    const { id, op, target, text, message, scope, when } = r;
+    if (typeof id !== "string" || id.length === 0 || id.length > 128 || !ID_GRAMMAR.test(id))
+        return fail(`overlay id ${str(id)} is not ^[a-z0-9][a-z0-9/._-]*$ of at most 128 characters`);
+    if (id.startsWith("core/") && ctx.sugar !== true)
+        return fail(`overlay id ${str(id)}: the core/ namespace is the engine's own`);
+    if (typeof op !== "string" || !OPS.has(op))
+        return fail(`overlay "${id}": op ${str(op)} is not one of ${OVERLAY_OPS.join(", ")}`);
+    if (typeof target !== "string" || target.length === 0)
+        return fail(`overlay "${id}": target ${str(target)} is not an id`);
+    const carries = op !== "drop";
+    if (!carries && (text !== undefined || message !== undefined))
+        return fail(`overlay "${id}": a drop carries no text or message`);
+    if (carries && (text === undefined) === (message === undefined))
+        return fail(`overlay "${id}": a ${op} carries exactly one of text, message`);
+    if (text !== undefined && (typeof text !== "string" || text.trim() === ""))
+        return fail(`overlay "${id}": text is ${typeof text === "string" ? "blank" : str(text)}`);
+    if (message !== undefined && (typeof message !== "string" || !MESSAGE_IDS.has(message)))
+        return fail(`overlay "${id}": message ${str(message)} is not a catalog message`);
+    if (when !== undefined) {
+        const why = whenViolation(when);
+        if (why !== undefined)
+            return fail(`overlay "${id}": ${why}`);
+    }
+    if (scope !== undefined && ctx.source !== "center")
+        return fail(`overlay "${id}": "scope" selects among a center artifact's overlays; a ${ctx.source} overlay answers for this run`);
+    if (scope !== undefined && (!isPlainRecord(scope) || Object.entries(scope).some(([k, v]) => k !== "binding" || bindingProblem(v) !== undefined))) {
+        return fail(`overlay "${id}": "scope" is { binding?: a non-blank string of at most ${BINDING_MAX} characters }`);
+    }
+    let band;
+    let where;
+    if (op === "add") {
+        if (!isBandId(target))
+            return fail(`overlay "${id}": an add targets a band; ${str(target)} is not one`);
+        if (bandOf(target).addRank === undefined)
+            return fail(`overlay "${id}": band "${target}" takes no additions`);
+        if (SECTION_BY_ID.has(id) || MESSAGE_IDS.has(id))
+            return fail(`overlay "${id}": an added entry cannot take a catalog id`);
+        band = target;
+        where = `band "${target}"`;
+    }
+    else if (op === "drop") {
+        const section = SECTION_BY_ID.get(target);
+        const added = ctx.lowerAdds?.get(target);
+        if (section !== undefined)
+            band = section.band;
+        else if (added !== undefined)
+            band = added;
+        else
+            return fail(`overlay "${id}": drop target ${str(target)} is neither a catalog section nor an entry a lower source added`);
+        where = `"${target}" (band "${band}")`;
+    }
+    else {
+        const placed = MESSAGE_TARGETS.get(target);
+        if (placed === undefined)
+            return fail(`overlay "${id}": ${op} target ${str(target)} is not a message the catalog places`);
+        band = placed.section.band;
+        where = `"${target}" (band "${band}")`;
+    }
+    const row = bandOf(band);
+    if (!row.ops[ctx.source].includes(op)) {
+        return fail(`overlay "${id}": a ${ctx.source} overlay may not ${op} ${where} (the band grants ${ctx.source} ${row.ops[ctx.source].length > 0 ? row.ops[ctx.source].join(", ") : "nothing"})`);
+    }
+    if (ctx.event !== undefined && row.modsEvent !== ctx.event)
+        return fail(`overlay "${id}": ${where} is written through ${row.modsEvent ?? "no mods event"}, not ${ctx.event}`);
+    const overlay = Object.freeze({
+        id,
+        op: op,
+        target,
+        ...(text !== undefined ? { text: text } : {}),
+        ...(message !== undefined ? { message: message } : {}),
+        ...(scope !== undefined ? { scope: scope } : {}),
+        ...(when !== undefined ? { when: when } : {}),
+    });
+    for (const t of textsOf(overlay)) {
+        const hits = lockedTextIn(t);
+        if (hits.length > 0)
+            return fail(`overlay "${id}": its text contains, verbatim, the locked text of ${[...new Set(hits.map((h) => h.split("#")[0]))].join(", ")}`);
+    }
+    return { overlay };
+}
+export function foldOverlays(ordered, selectedText, applies, overlayText) {
+    const messageText = new Map();
+    const writers = new Map();
+    const dropped = new Map();
+    const added = new Map();
+    const addedBy = new Map();
+    const addCount = new Map();
+    const superseded = [];
+    const chains = new Map();
+    const supersede = (w, target, by) => {
+        superseded.push(Object.freeze({ id: w.id, source: w.origin.source, by: w.origin.by, target, supersededBy: by }));
+        if (w.link !== undefined)
+            w.link.superseded = true;
+    };
+    const applied = (key, o, origin) => {
+        const link = { source: origin.source, overlay: o.id, op: o.op };
+        chains.set(key, [...(chains.get(key) ?? []), link]);
+        return { id: o.id, origin, link };
+    };
+    const sectionMessages = (sectionId) => [...MESSAGE_TARGETS.entries()].filter(([, t]) => t.section.id === sectionId).map(([m]) => m);
+    for (const { overlay: o, origin } of ordered) {
+        if (!applies(o))
+            continue;
+        const me = { id: o.id, origin };
+        const text = o.op === "drop" ? "" : overlayText(o);
+        if (text === undefined) {
+            supersede(me, o.target, ABSENT_THIS_RUN);
+            continue;
+        }
+        if (o.op === "add") {
+            const prior = addedBy.get(o.id);
+            if (prior !== undefined)
+                supersede(prior, o.target, o.id);
+            const band = o.target;
+            const k = addCount.get(band) ?? 0;
+            addCount.set(band, k + 1);
+            added.set(o.id, Object.freeze({ id: o.id, band, rank: bandOf(band).addRank + k * 0.001, text, origin }));
+            addedBy.set(o.id, applied(o.id, o, origin));
+            continue;
+        }
+        if (o.op === "drop") {
+            const entry = addedBy.get(o.target);
+            if (entry !== undefined) {
+                supersede(entry, o.target, o.id);
+                added.delete(o.target);
+                addedBy.delete(o.target);
+                continue;
+            }
+            for (const m of sectionMessages(o.target)) {
+                for (const w of writers.get(m) ?? [])
+                    supersede(w, m, o.id);
+                writers.delete(m);
+                messageText.delete(m);
+            }
+            dropped.set(o.target, applied(o.target, o, origin));
+            continue;
+        }
+        const section = MESSAGE_TARGETS.get(o.target).section;
+        const drop = dropped.get(section.id);
+        if (o.op === "append" && drop !== undefined) {
+            supersede(me, o.target, drop.id);
+            continue;
+        }
+        if (selectedText(o.target) === undefined && !messageText.has(o.target)) {
+            supersede(me, o.target, ABSENT_THIS_RUN);
+            continue;
+        }
+        if (drop !== undefined) {
+            supersede(drop, section.id, o.id);
+            dropped.delete(section.id);
+        }
+        const writer = applied(section.id, o, origin);
+        if (o.op === "replace") {
+            for (const w of writers.get(o.target) ?? [])
+                supersede(w, o.target, o.id);
+            writers.set(o.target, [writer]);
+            messageText.set(o.target, { text, origin, replaced: true });
+        }
+        else {
+            const base = messageText.get(o.target)?.text ?? selectedText(o.target);
+            writers.set(o.target, [...(writers.get(o.target) ?? []), writer]);
+            messageText.set(o.target, { text: `${base}\n\n${text}`, origin, replaced: messageText.get(o.target)?.replaced ?? false });
+        }
+    }
+    return {
+        messageText,
+        dropped: new Set(dropped.keys()),
+        added: [...added.values()],
+        superseded,
+        chains: new Map([...chains].map(([k, links]) => [k, Object.freeze(links.map((l) => Object.freeze({ ...l })))])),
+    };
+}

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

@@ -0,0 +1,21 @@
+import type { RendererId } from "./catalog/schema.js";
+import { type PromptSelectors } from "./select.js";
+import type { SectionRenderInputs } from "./types.js";
+export interface RendererSpec {
+    readonly id: RendererId;
+    readonly version: number;
+    readonly stability: "static" | "session" | "leg";
+    readonly reads: "inputs" | "facts" | "env" | "memory" | "mcp" | "mark" | "selectors";
+    readonly external: boolean;
+    /** The catalog messages this renderer's output is (an overlay targets them). */
+    readonly messages?: readonly string[];
+}
+export declare const RENDERERS: Readonly<Record<RendererId, RendererSpec>>;
+/** The renderer version vector — the identity's renderer element (a changed output bumps a version). */
+export declare function rendererVector(): Readonly<Record<RendererId, number>>;
+/** One renderer's output for these inputs (and the variant it rendered, when it rendered a catalog message);
+ *  undefined ⇒ the section is absent this run. */
+export declare function runRenderer(id: RendererId, inputs: SectionRenderInputs, selectors: PromptSelectors): {
+    readonly text: string;
+    readonly variant?: string;
+} | undefined;

package/dist/prompt-assembly/renderers.js

@@ -0,0 +1,39 @@
+import { reminderMarkDeclaration } from "../core/reminder-mint.js";
+import { renderCoworkBase } from "../prompts/cowork.js";
+import { catalogMessage } from "./catalog/index.js";
+import { selectVariant } from "./select.js";
+export const RENDERERS = {
+    "role-base": { id: "role-base", version: 2, stability: "session", reads: "selectors", external: false, messages: ["core/role.base"] },
+    "model-guidance": { id: "model-guidance", version: 1, stability: "session", reads: "inputs", external: false },
+    "mcp-instructions": { id: "mcp-instructions", version: 1, stability: "session", reads: "mcp", external: true },
+    "reminder-mark": { id: "reminder-mark", version: 1, stability: "session", reads: "mark", external: false },
+    environment: { id: "environment", version: 2, stability: "leg", reads: "env", external: false },
+    memory: { id: "memory", version: 1, stability: "leg", reads: "memory", external: false },
+};
+export function rendererVector() {
+    return Object.fromEntries(Object.values(RENDERERS).map((r) => [r.id, r.version]));
+}
+export function runRenderer(id, inputs, selectors) {
+    const plain = (text) => (text === undefined ? undefined : { text });
+    switch (id) {
+        case "role-base": {
+            const v = selectVariant(catalogMessage("core/role.base"), selectors);
+            if (v === undefined)
+                return undefined;
+            if (v.id !== "cowork")
+                return { text: v.text, variant: v.id };
+            const sections = renderCoworkBase({ tools: inputs.toolNames ?? [], workspaceFolder: inputs.workspaceFolder });
+            return sections.length === 0 ? undefined : { text: sections.map((s) => s.text).join("\n\n"), variant: v.id };
+        }
+        case "model-guidance":
+            return plain(inputs.modelGuidance);
+        case "mcp-instructions":
+            return plain(inputs.mcpInstructionsBlock);
+        case "reminder-mark":
+            return plain(inputs.facts.reminderMark !== undefined ? reminderMarkDeclaration(inputs.facts.reminderMark) : undefined);
+        case "environment":
+            return plain(inputs.environmentBlock);
+        case "memory":
+            return plain(inputs.memoryBlock);
+    }
+}

package/dist/prompt-assembly/section-usage.d.ts

@@ -4,8 +4,8 @@ export interface ContextUsageSection {
     id: string;
     /** The section's ESTIMATED token weight (see {@link contextUsageSections} for what that promises). */
     tokens: number;
-    /** The section's semantic slot (`identity`, `security`, …), so a view can group without knowing every
-     *  id. Absent only if the manifest entry carried no slot. */
+    /** The section's band (`role`, `constitution`, `core-behavior`, …), so a view can group without knowing
+     *  every id. Absent only if the manifest entry carried no band. */
     kind?: string;
 }
 /**
@@ -21,6 +21,6 @@ export interface ContextUsageSection {
  */
 export declare function contextUsageSections(sections: ReadonlyArray<{
     id: string;
-    slot?: string;
+    band?: string;
     chars: number;
 }> | undefined): ContextUsageSection[] | undefined;

package/dist/prompt-assembly/section-usage.js

@@ -5,6 +5,6 @@ export function contextUsageSections(sections) {
     return sections.map((s) => ({
         id: s.id,
         tokens: Math.ceil(s.chars / DEFAULT_CHARS_PER_TOKEN),
-        ...(s.slot !== undefined ? { kind: s.slot } : {}),
+        ...(s.band !== undefined ? { kind: s.band } : {}),
     }));
 }

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

@@ -0,0 +1,56 @@
+/**
+ * The selector: the one reading that picks, for a catalog message, the variant a run receives — and decides
+ * whether an overlay's `when` applies to this run. Three dimensions, each with exactly one writer, so no value
+ * ever needs a precedence order:
+ *
+ * - `traits` — derived from the run's two prompt-shape axes by {@link promptTraitsOf} (the prompt profile and the
+ *   fable-family model); catalog data reads traits, never the axes.
+ * - `host` — `role` (which role base the run is assembled for; `TaskSpec.promptRole`, absent ⇒ `general`) and
+ *   `form` (`TaskSpec.promptForm`, which every engine-built child receives through the parent spec seat; absent ⇒
+ *   `standard`).
+ * - `facts` — the runtime facts prepare produces (one derived: `executionEnvironmentDeclared`).
+ *
+ * A variant's `when` is a conjunction: every listed trait present, every `noneOf` trait absent, every host key
+ * equal, every fact equal. No disjunction, no expressions.
+ */
+import { type CatalogMessage, type FactConjunction, type HostForm, type HostRole, type PromptFactName, type PromptTrait, type Variant, type VariantWhen } from "./catalog/schema.js";
+import type { PromptRuntimeFacts } from "./types.js";
+/** The run's selector values, resolved once per assembly. */
+export interface PromptSelectors {
+    readonly traits: ReadonlySet<PromptTrait>;
+    readonly host: {
+        readonly role: HostRole;
+        readonly form: HostForm;
+    };
+    readonly facts: Readonly<Record<PromptFactName, boolean>>;
+}
+/**
+ * The run's prompt traits, derived from the two prompt-shape axes the engine resolves today: the simple
+ * profile is `lean_prompt`, a fable-family model is `fable_5_mitigations`. This is the only place those
+ * axes become traits.
+ */
+export declare function promptTraitsOf(facts: Pick<PromptRuntimeFacts, "promptProfile" | "fableMitigations">): ReadonlySet<PromptTrait>;
+/** The predicate facts a condition may test; optional runtime facts read as false when absent. */
+export declare function catalogFactsOf(facts: PromptRuntimeFacts): Readonly<Record<PromptFactName, boolean>>;
+/**
+ * The host selector's two values as their one writer gave them: the task (`TaskSpec.promptRole` /
+ * `TaskSpec.promptForm`; an engine-built child's spec carries its parent's form through the parent spec seat).
+ * A value outside the closed set is refused by name (`config.prompt_selector_invalid`), never read as the default.
+ */
+export declare function resolveHost(task: {
+    readonly promptRole?: unknown;
+    readonly promptForm?: unknown;
+}): {
+    readonly role?: HostRole;
+    readonly form?: HostForm;
+};
+/** The run's selectors: traits and facts from the runtime facts, the host from its two writers' values. */
+export declare function selectorsOf(facts: PromptRuntimeFacts, host?: {
+    readonly role?: HostRole;
+    readonly form?: HostForm;
+}): PromptSelectors;
+export declare function factsHold(conj: FactConjunction | undefined, facts: Readonly<Record<PromptFactName, boolean>>): boolean;
+/** Whether a `when` holds under the run's selectors. */
+export declare function whenHolds(when: VariantWhen | undefined, s: PromptSelectors): boolean;
+/** The variant this run receives, or undefined when no variant's `when` holds (the message is absent). */
+export declare function selectVariant(message: CatalogMessage, s: PromptSelectors): Variant | undefined;

package/dist/prompt-assembly/select.js

@@ -0,0 +1,69 @@
+import { HOST_ROLES, isWordOf } from "./catalog/schema.js";
+export function promptTraitsOf(facts) {
+    const traits = new Set();
+    if (facts.promptProfile !== "classic")
+        traits.add("lean_prompt");
+    if (facts.fableMitigations === true)
+        traits.add("fable_5_mitigations");
+    return traits;
+}
+export function catalogFactsOf(facts) {
+    return {
+        policyEnabled: facts.policyEnabled,
+        hooksEnabled: facts.hooksEnabled,
+        isolationEnabled: facts.isolationEnabled,
+        readFaceOpen: facts.readFaceOpen === true,
+        writeFaceOpen: facts.writeFaceOpen === true,
+        withinTaskCompactionEnabled: facts.withinTaskCompactionEnabled,
+        supervisorEnabled: facts.supervisorEnabled,
+        orchestrationEnabled: facts.orchestrationEnabled,
+        orchestrationDeferred: facts.orchestrationDeferred === true,
+        awarenessEnabled: facts.awarenessEnabled,
+        goalEnabled: facts.goalEnabled,
+        worktreeIsolated: facts.worktreeIsolated,
+        teammateEnabled: facts.teammateEnabled,
+        isSubagent: facts.isSubagent === true,
+        executionEnvironmentDeclared: facts.policyEnabled || facts.isolationEnabled,
+    };
+}
+export function resolveHost(task) {
+    const refuse = (key, value, allowed) => {
+        throw Object.assign(new Error(`TaskSpec.${key} is ${typeof value === "string" ? JSON.stringify(value.slice(0, 64)) : typeof value}; it is one of ${allowed.map((a) => `"${a}"`).join(", ")} (or absent)`), {
+            code: "config.prompt_selector_invalid",
+        });
+    };
+    const role = task.promptRole === undefined ? undefined : isWordOf(HOST_ROLES, task.promptRole) ? task.promptRole : refuse("promptRole", task.promptRole, HOST_ROLES);
+    const form = task.promptForm === undefined ? undefined : task.promptForm === "minimal" ? "minimal" : refuse("promptForm", task.promptForm, ["minimal"]);
+    return Object.freeze({ ...(role !== undefined ? { role } : {}), ...(form !== undefined ? { form } : {}) });
+}
+export function selectorsOf(facts, host = {}) {
+    return Object.freeze({
+        traits: promptTraitsOf(facts),
+        host: Object.freeze({ role: host.role ?? "general", form: host.form ?? "standard" }),
+        facts: Object.freeze(catalogFactsOf(facts)),
+    });
+}
+export function factsHold(conj, facts) {
+    if (conj === undefined)
+        return true;
+    for (const [name, want] of Object.entries(conj))
+        if (facts[name] !== want)
+            return false;
+    return true;
+}
+function traitsHold(cond, traits) {
+    if (cond === undefined)
+        return true;
+    return (cond.allOf ?? []).every((t) => traits.has(t)) && !(cond.noneOf ?? []).some((t) => traits.has(t));
+}
+function hostHolds(cond, host) {
+    if (cond === undefined)
+        return true;
+    return (cond.role === undefined || cond.role === host.role) && (cond.form === undefined || cond.form === host.form);
+}
+export function whenHolds(when, s) {
+    return when === undefined || (traitsHold(when.traits, s.traits) && hostHolds(when.host, s.host) && factsHold(when.facts, s.facts));
+}
+export function selectVariant(message, s) {
+    return message.variants.find((v) => whenHolds(v.when, s));
+}