@sema-agent/core 7.51.2 → 7.53.0

package/dist/prompt-assembly/overlay.js

@@ -0,0 +1,339 @@
+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";
+import { canonicalWhen } from "./select.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", "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) };
+}
+export const PROMPT_BINDING_MAX_CHARS = 128;
+export const PROMPT_BINDING_LIST_MAX = 64;
+export function codePointsOver(s, max) {
+    if (s.length <= max)
+        return false;
+    if (s.length > 2 * max)
+        return true;
+    let n = 0;
+    for (const _ of s)
+        if (++n > max)
+            return true;
+    return false;
+}
+function bindingProblem(v) {
+    return typeof v !== "string" || v.trim() === "" || codePointsOver(v, PROMPT_BINDING_MAX_CHARS) ? `${str(v)} is not a non-blank string of at most ${PROMPT_BINDING_MAX_CHARS} characters (code points)` : undefined;
+}
+function bindingConditionProblem(b) {
+    if (!isPlainRecord(b))
+        return `"when.binding" is ${Array.isArray(b) ? "an array" : str(b)}, not { anyOf: [...] } or { noneOf: [...] }`;
+    const keys = Object.keys(b);
+    const k = keys[0];
+    if (keys.length !== 1 || (k !== "anyOf" && k !== "noneOf"))
+        return `"when.binding" carries ${keys.length === 0 ? "no list" : keys.map((x) => str(x)).join(", ")} (exactly one of anyOf, noneOf)`;
+    const list = b[k];
+    if (!Array.isArray(list) || list.length === 0)
+        return `"when.binding.${k}" is ${Array.isArray(list) ? "empty" : str(list)}, not a list naming at least one binding`;
+    if (list.length > PROMPT_BINDING_LIST_MAX)
+        return `"when.binding.${k}" names ${list.length} bindings (at most ${PROMPT_BINDING_LIST_MAX})`;
+    for (const name of list) {
+        const why = bindingProblem(name);
+        if (why !== undefined)
+            return `"when.binding.${k}": ${why}`;
+    }
+    if (new Set(list).size !== list.length)
+        return `"when.binding.${k}" names a binding twice`;
+    return 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" && k !== "binding")
+            return `"when" carries ${str(k)} (traits, host, facts, binding 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`;
+        }
+    }
+    if (w["binding"] !== undefined)
+        return bindingConditionProblem(w["binding"]);
+    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))
+            continue;
+        const rewrite = k === "scope" ? `; an overlay names its binding as "when": { "binding": { "anyOf": [<binding>] } }` : "";
+        return fail(`an overlay carries ${str(k)} (id, op, target, text, message, when only)${rewrite}`);
+    }
+    const { id, op, target, text, message, when } = r;
+    if (typeof id !== "string" || id.length === 0 || codePointsOver(id, 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}`);
+    }
+    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 normalWhen = canonicalWhen(when);
+    const overlay = Object.freeze({
+        id,
+        op: op,
+        target,
+        ...(text !== undefined ? { text: text } : {}),
+        ...(message !== undefined ? { message: message } : {}),
+        ...(normalWhen !== undefined ? { when: normalWhen } : {}),
+    });
+    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;
+            }
+            if (!SECTION_BY_ID.has(o.target)) {
+                supersede(me, o.target, ABSENT_THIS_RUN);
+                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,71 @@
+/**
+ * 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 (every source class alike). Four 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`).
+ * - `binding` — the deployment's scenario name (`TaskSpec.promptBinding`, an open vocabulary; absent ⇒ none).
+ *
+ * A `when` is a conjunction: every listed trait present, every `noneOf` trait absent, every host key equal, every
+ * fact equal, the binding inside its `anyOf` (or outside its `noneOf`). No disjunction across dimensions.
+ */
+import type { PromptManifestSelectors } from "../core/trace.js";
+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>>;
+    readonly binding?: string;
+}
+/**
+ * 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 — their one mint: traits and facts from the runtime facts, the host from its two writers' values,
+ *  the binding as the task's door validated it. */
+export declare function selectorsOf(facts: PromptRuntimeFacts, host?: {
+    readonly role?: HostRole;
+    readonly form?: HostForm;
+}, binding?: string): PromptSelectors;
+/** The selectors' plain form (traits sorted): what the manifest shows, the identity's `binding` element digests and the
+ *  `prompt.compose` event carries — one record. */
+export declare function selectorRecordOf(s: PromptSelectors): PromptManifestSelectors;
+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;
+/**
+ * A `when` in its normal form — the one spelling of what it asks: every list sorted and without repeats, a conjunct that
+ * asks nothing (an empty `traits`, `host` or `facts`, an empty list) left out, and a condition left with no conjunct
+ * (`{}`) is no condition at all (`undefined`). Two conditions that hold in the same runs by construction are equal as
+ * values here, so the overlay door (`validateOverlay`) hands every reader — the artifact digest, the publish-side
+ * conflict check — the same condition. Idempotent; it never changes which runs a condition holds for.
+ */
+export declare function canonicalWhen(when: VariantWhen | undefined): VariantWhen | undefined;
+/** 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,106 @@
+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 = {}, binding) {
+    return Object.freeze({
+        traits: promptTraitsOf(facts),
+        host: Object.freeze({ role: host.role ?? "general", form: host.form ?? "standard" }),
+        facts: Object.freeze(catalogFactsOf(facts)),
+        ...(binding !== undefined ? { binding } : {}),
+    });
+}
+export function selectorRecordOf(s) {
+    return {
+        ...(s.binding !== undefined ? { binding: s.binding } : {}),
+        traits: [...s.traits].sort(),
+        host: { role: s.host.role, form: s.host.form },
+        facts: { ...s.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);
+}
+function bindingHolds(cond, binding) {
+    if (cond === undefined)
+        return true;
+    if (cond.anyOf !== undefined)
+        return binding !== undefined && cond.anyOf.includes(binding);
+    return binding === undefined || !cond.noneOf.includes(binding);
+}
+export function whenHolds(when, s) {
+    return when === undefined || (traitsHold(when.traits, s.traits) && hostHolds(when.host, s.host) && factsHold(when.facts, s.facts) && bindingHolds(when.binding, s.binding));
+}
+const byText = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+const sortedSet = (xs) => Object.freeze([...new Set(xs ?? [])].sort(byText));
+export function canonicalWhen(when) {
+    if (when === undefined)
+        return undefined;
+    const allOf = sortedSet(when.traits?.allOf);
+    const noneOf = sortedSet(when.traits?.noneOf);
+    const hostKeys = Object.keys(when.host ?? {});
+    const factNames = Object.keys(when.facts ?? {}).sort(byText);
+    const binding = when.binding;
+    const out = {};
+    if (allOf.length > 0 || noneOf.length > 0)
+        out.traits = Object.freeze({ ...(allOf.length > 0 ? { allOf } : {}), ...(noneOf.length > 0 ? { noneOf } : {}) });
+    if (hostKeys.length > 0)
+        out.host = Object.freeze({ ...when.host });
+    if (factNames.length > 0)
+        out.facts = Object.freeze(Object.fromEntries(factNames.map((n) => [n, when.facts[n]])));
+    if (binding !== undefined)
+        out.binding = Object.freeze(binding.anyOf !== undefined ? { anyOf: sortedSet(binding.anyOf) } : { noneOf: sortedSet(binding.noneOf) });
+    return Object.keys(out).length === 0 ? undefined : Object.freeze(out);
+}
+export function selectVariant(message, s) {
+    return message.variants.find((v) => whenHolds(v.when, s));
+}

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

@@ -0,0 +1,31 @@
+/**
+ * The request-body sugar: the one place the task's role-layer prompt inputs are read and turned into overlays of
+ * the `task` source class. Three inputs, one expression each:
+ *
+ * - the role base — `TaskSpec.systemPrompt ?? resolvedRole.systemPrompt ?? internals.defaultSystemPrompt` (the
+ *   task's own text, else the role preset the task named, else the persona a core spawner hands its child) — a
+ *   `replace` of `core/role.base`, applied after the selector chose the role base's variant;
+ * - the appended block — `TaskSpec.appendSystemPrompt` — an `add` to the `task-append` band (entry
+ *   `core/role.append`);
+ *
+ * and nothing else reads them for assembly (`gate:sugar-single-site`). The sugar is applied first within its class,
+ * the task-seat mods after it. Its one possible violation is locked text: a role-layer input carrying, verbatim,
+ * the canonical text of a `constitution` entry is an already-assembled prompt, and the task is refused by name
+ * (`prompt.assembled_role_refused`) — never passed through, never silently dropped.
+ */
+import { type SourcedOverlay } from "./overlay.js";
+/** The task's role-layer prompt inputs, as prepare holds them. */
+export interface SugarInputs {
+    readonly spec: {
+        readonly systemPrompt?: string;
+        readonly appendSystemPrompt?: string;
+    };
+    readonly resolvedRole: {
+        readonly systemPrompt?: string;
+    };
+    readonly internals?: {
+        readonly defaultSystemPrompt?: string;
+    };
+}
+/** The task-class overlays the request body carries, in application order (role base, then the appended block). */
+export declare function sugarOverlays(inputs: SugarInputs): readonly SourcedOverlay[];

package/dist/prompt-assembly/sugar.js

@@ -0,0 +1,20 @@
+import { assembledRoleRefused, lockedTextIn } from "./overlay.js";
+const SUGAR = { source: "task", by: "sugar" };
+export function sugarOverlays(inputs) {
+    const roleBase = inputs.spec.systemPrompt ?? inputs.resolvedRole.systemPrompt ?? inputs.internals?.defaultSystemPrompt;
+    const append = inputs.spec.appendSystemPrompt;
+    const out = [];
+    if (roleBase !== undefined) {
+        const hits = lockedTextIn(roleBase);
+        if (hits.length > 0)
+            throw assembledRoleRefused("the task's role text (systemPrompt)", hits);
+        out.push({ overlay: Object.freeze({ id: "core/role.base", op: "replace", target: "core/role.base", text: roleBase }), origin: SUGAR });
+    }
+    if (append !== undefined) {
+        const hits = lockedTextIn(append);
+        if (hits.length > 0)
+            throw assembledRoleRefused("the task's appendSystemPrompt", hits);
+        out.push({ overlay: Object.freeze({ id: "core/role.append", op: "add", target: "task-append", text: append }), origin: SUGAR });
+    }
+    return Object.freeze(out);
+}