@sema-agent/core 7.51.1 → 7.52.0

package/dist/prompt-assembly/artifact.js

@@ -1,169 +1,190 @@
 import { createHash } from "node:crypto";
+import { isBandId } from "./bands.js";
+import { SEMA_DEFAULT_CATALOG } from "./catalog/index.js";
+import { OVERLAY_OPS, PROMPT_TRAITS, isWordOf } from "./catalog/schema.js";
 import { canonical } from "./epoch.js";
-export const ARTIFACT_LIMITS = {
-    maxSections: 64,
-    maxSectionBytes: 32_000,
-    maxTotalBytes: 131_072,
-    maxIdLength: 128,
-    maxPackIdLength: 200,
-};
-const ID_RE = /^[a-z0-9][a-z0-9/._-]*$/;
+import { sectionOfMessage, validateOverlay } from "./overlay.js";
+export const ARTIFACT_LIMITS = Object.freeze({
+    maxOverlays: 64,
+    maxOverlayTextBytes: 32_000,
+    maxTotalTextBytes: 131_072,
+    maxIntentChars: 2_000,
+    maxRefs: 32,
+    maxRefChars: 500,
+    maxSourceRevisionChars: 500,
+});
 const DIGEST_RE = /^sha256:[0-9a-f]{64}$/;
-const SLOTS = new Set(["identity", "scenario", "behavior"]);
-export function sha256Hex(text) {
+const MESSAGE_IDS = new Set(SEMA_DEFAULT_CATALOG.messages.map((m) => m.id));
+const SECTION_IDS = new Set(SEMA_DEFAULT_CATALOG.sections.map((s) => s.id));
+function sha256Hex(text) {
     return `sha256:${createHash("sha256").update(text, "utf8").digest("hex")}`;
 }
-export function computeCatalogDigest(catalog) {
-    return sha256Hex(canonical(catalog));
-}
 export function computeArtifactDigest(payload) {
     return sha256Hex(canonical(payload));
 }
-function triple(v) {
-    const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(v.trim());
-    if (!m)
-        return undefined;
-    return [Number(m[1]), Number(m[2]), Number(m[3])];
+export function requiresOf(overlays) {
+    const targets = new Map();
+    const need = (id, kind) => {
+        targets.set(`${kind}:${id}`, { id, kind });
+    };
+    const ops = new Set();
+    const traits = new Set();
+    const bindings = new Set();
+    for (const o of overlays) {
+        ops.add(o.op);
+        need(o.target, o.op === "add" ? "band" : o.op === "drop" ? "section" : "message");
+        if (o.message !== undefined)
+            need(o.message, "message");
+        for (const t of [...(o.when?.traits?.allOf ?? []), ...(o.when?.traits?.noneOf ?? [])])
+            traits.add(t);
+        if (o.scope?.binding !== undefined)
+            bindings.add(o.scope.binding);
+    }
+    const byText = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+    return {
+        targets: [...targets.values()].sort((a, b) => byText(`${a.kind}:${a.id}`, `${b.kind}:${b.id}`)),
+        ops: OVERLAY_OPS.filter((op) => ops.has(op)),
+        traits: PROMPT_TRAITS.filter((t) => traits.has(t)),
+        bindings: [...bindings].sort(byText),
+    };
 }
-function tripleCmp(a, b) {
-    for (let i = 0; i < 3; i++) {
-        if (a[i] !== b[i])
-            return a[i] < b[i] ? -1 : 1;
+export function unmetRequirements(requires) {
+    const unmet = [];
+    for (const t of requires.targets) {
+        const has = t.kind === "message" ? MESSAGE_IDS.has(t.id) : t.kind === "section" ? SECTION_IDS.has(t.id) : isBandId(t.id);
+        if (!has)
+            unmet.push(`${t.kind} "${t.id}"`);
     }
-    return 0;
+    for (const op of requires.ops)
+        if (!isWordOf(OVERLAY_OPS, op))
+            unmet.push(`op "${String(op)}"`);
+    for (const tr of requires.traits)
+        if (!isWordOf(PROMPT_TRAITS, tr))
+            unmet.push(`trait "${String(tr)}"`);
+    return unmet;
 }
-export function verifyPromptArtifact(raw, opts) {
-    const fail = (code, reason) => ({ ok: false, code, reason });
-    if (raw === null || typeof raw !== "object")
-        return fail("shape", "envelope is not an object");
-    const env = raw;
-    if (typeof env.sourceRevision !== "string" || !env.sourceRevision || env.sourceRevision.length > 500) {
-        return fail("shape", "sourceRevision missing/oversized");
+function isRecord(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+function requiresShaped(v) {
+    if (!isRecord(v))
+        return false;
+    const strings = (a) => Array.isArray(a) && a.every((s) => typeof s === "string");
+    return (Object.keys(v).every((k) => k === "targets" || k === "ops" || k === "traits" || k === "bindings") &&
+        Array.isArray(v.targets) &&
+        v.targets.every((t) => isRecord(t) && typeof t.id === "string" && (t.kind === "message" || t.kind === "section" || t.kind === "band") && Object.keys(t).every((k) => k === "id" || k === "kind")) &&
+        strings(v.ops) &&
+        strings(v.traits) &&
+        strings(v.bindings));
+}
+function replaceConflict(overlays) {
+    const seen = new Map();
+    for (const o of overlays) {
+        if (o.op !== "replace")
+            continue;
+        const key = canonical({ target: o.target, binding: o.scope?.binding ?? null, when: o.when ?? null });
+        const prior = seen.get(key);
+        if (prior !== undefined)
+            return `overlays "${prior}" and "${o.id}" both replace "${o.target}" under the same binding and condition`;
+        seen.set(key, o.id);
+    }
+    return undefined;
+}
+export function verifyPromptArtifact(raw) {
+    if (!isRecord(raw))
+        return { ok: false, code: "shape", reason: "the published artifact is not an object" };
+    if (typeof raw.sourceRevision !== "string" || raw.sourceRevision.length === 0 || raw.sourceRevision.length > ARTIFACT_LIMITS.maxSourceRevisionChars) {
+        return { ok: false, code: "shape", reason: "sourceRevision missing or oversized" };
     }
-    const art = env.artifact;
-    if (art === null || typeof art !== "object")
-        return fail("shape", "artifact is not an object");
-    const payload = art.payload;
-    if (payload === null || typeof payload !== "object")
+    const v = verifyPromptArtifactBody(raw);
+    return v.ok ? { ok: true, artifact: { ...v.artifact, sourceRevision: raw.sourceRevision } } : v;
+}
+export function verifyPromptArtifactBody(raw) {
+    const fail = (code, reason) => ({ ok: false, code, reason });
+    if (!isRecord(raw))
+        return fail("shape", "the artifact is not an object");
+    for (const k of Object.keys(raw))
+        if (k !== "payload" && k !== "artifactDigest" && k !== "sourceRevision")
+            return fail("shape", `the artifact carries ${JSON.stringify(k).slice(0, 60)}`);
+    if (typeof raw.artifactDigest !== "string" || !DIGEST_RE.test(raw.artifactDigest))
+        return fail("shape", "artifactDigest malformed");
+    const payload = raw.payload;
+    if (!isRecord(payload))
         return fail("shape", "payload is not an object");
-    if (payload.schemaVersion !== 1)
-        return fail("schema", `unsupported schemaVersion ${String(payload.schemaVersion)}`);
-    if (payload.assemblyApi !== 1)
-        return fail("schema", `unsupported assemblyApi ${String(payload.assemblyApi)}`);
-    if (typeof payload.catalogDigest !== "string" || !DIGEST_RE.test(payload.catalogDigest))
-        return fail("shape", "catalogDigest malformed");
-    let compatibleCore;
-    if (payload.compatibleCore !== undefined) {
-        const cc = payload.compatibleCore;
-        if (cc === null || typeof cc !== "object")
-            return fail("shape", "compatibleCore malformed");
-        compatibleCore = {};
-        for (const key of ["minCore", "maxCoreExclusive"]) {
-            const v = cc[key];
-            if (v === undefined)
-                continue;
-            if (typeof v !== "string" || triple(v) === undefined)
-                return fail("shape", `compatibleCore.${key} is not a dotted triple`);
-            compatibleCore[key] = v;
-        }
-        const engine = triple(opts.engineVersion);
-        if (engine === undefined)
-            return fail("core-range", `engine version "${opts.engineVersion}" is not a dotted triple`);
-        if (compatibleCore.minCore !== undefined && tripleCmp(engine, triple(compatibleCore.minCore)) < 0) {
-            return fail("core-range", `engine ${opts.engineVersion} < minCore ${compatibleCore.minCore}`);
-        }
-        if (compatibleCore.maxCoreExclusive !== undefined && tripleCmp(engine, triple(compatibleCore.maxCoreExclusive)) >= 0) {
-            return fail("core-range", `engine ${opts.engineVersion} >= maxCoreExclusive ${compatibleCore.maxCoreExclusive}`);
+    if (payload.schemaVersion !== 2)
+        return fail("schema", `unsupported schemaVersion ${JSON.stringify(payload.schemaVersion)?.slice(0, 40)} (this engine reads schemaVersion 2 only)`);
+    for (const k of Object.keys(payload))
+        if (k !== "schemaVersion" && k !== "requires" && k !== "overlays" && k !== "evidence")
+            return fail("shape", `payload carries ${JSON.stringify(k).slice(0, 60)}`);
+    if (!Array.isArray(payload.overlays))
+        return fail("shape", "overlays is not an array");
+    if (payload.overlays.length === 0)
+        return fail("shape", "overlays is empty — publish at least one overlay, or disable the source instead");
+    if (payload.overlays.length > ARTIFACT_LIMITS.maxOverlays)
+        return fail("limits", `${payload.overlays.length} overlays > max ${ARTIFACT_LIMITS.maxOverlays}`);
+    const requires = payload.requires;
+    if (!requiresShaped(requires))
+        return fail("shape", "requires is not { targets: { id, kind }[], ops: string[], traits: string[], bindings: string[] }");
+    const unmet = unmetRequirements(requires);
+    if (unmet.length > 0)
+        return fail("requires", `this engine does not meet the artifact's requirements: ${unmet.slice(0, 6).join(", ")}${unmet.length > 6 ? ` and ${unmet.length - 6} more` : ""}`);
+    const overlays = [];
+    let totalBytes = 0;
+    for (const rawOverlay of payload.overlays) {
+        const v = validateOverlay(rawOverlay, { source: "center" });
+        if ("violation" in v)
+            return fail("overlay", v.violation);
+        const text = v.overlay.text;
+        if (text !== undefined) {
+            const bytes = Buffer.byteLength(text, "utf8");
+            if (bytes > ARTIFACT_LIMITS.maxOverlayTextBytes)
+                return fail("limits", `overlay "${v.overlay.id}" text ${bytes} bytes > max ${ARTIFACT_LIMITS.maxOverlayTextBytes}`);
+            totalBytes += bytes;
         }
+        overlays.push(v.overlay);
     }
-    const closure = payload.closure;
-    if (closure === null || typeof closure !== "object")
-        return fail("shape", "closure is not an object");
-    if (closure.basePackId !== "sema-default@1") {
-        return fail("base-pack", `unsupported basePackId ${JSON.stringify(closure.basePackId).slice(0, 120)} (v1: bundled base only)`);
+    if (totalBytes > ARTIFACT_LIMITS.maxTotalTextBytes)
+        return fail("limits", `overlay text ${totalBytes} bytes > max ${ARTIFACT_LIMITS.maxTotalTextBytes}`);
+    if (canonical(requiresOf(overlays)) !== canonical(requires))
+        return fail("requires", "requires differs from what the overlays require (build the artifact with buildPromptArtifact)");
+    const conflict = replaceConflict(overlays);
+    if (conflict !== undefined)
+        return fail("overlay", conflict);
+    const evidence = payload.evidence;
+    if (!isRecord(evidence) || typeof evidence.intent !== "string" || evidence.intent.trim() === "" || evidence.intent.length > ARTIFACT_LIMITS.maxIntentChars) {
+        return fail("evidence", `evidence.intent is a non-blank string of at most ${ARTIFACT_LIMITS.maxIntentChars} characters`);
     }
-    const catalog = closure.promptCatalog;
-    if (catalog === null || typeof catalog !== "object")
-        return fail("shape", "promptCatalog is not an object");
-    if (typeof catalog.packId !== "string" || !catalog.packId.trim() || catalog.packId.length > ARTIFACT_LIMITS.maxPackIdLength) {
-        return fail("shape", "promptCatalog.packId missing/oversized");
+    if (!Array.isArray(evidence.refs) || evidence.refs.length > ARTIFACT_LIMITS.maxRefs || evidence.refs.some((r) => typeof r !== "string" || r.trim() === "" || r.length > ARTIFACT_LIMITS.maxRefChars)) {
+        return fail("evidence", `evidence.refs is a list of at most ${ARTIFACT_LIMITS.maxRefs} non-blank references`);
     }
-    if (!Array.isArray(catalog.sections))
-        return fail("shape", "promptCatalog.sections is not an array");
-    if (catalog.sections.length === 0)
-        return fail("shape", "promptCatalog.sections is empty — publish at least one section, or disable the source instead");
-    if (catalog.sections.length > ARTIFACT_LIMITS.maxSections) {
-        return fail("limits", `${catalog.sections.length} sections > max ${ARTIFACT_LIMITS.maxSections}`);
+    for (const k of Object.keys(evidence))
+        if (k !== "intent" && k !== "refs")
+            return fail("shape", `evidence carries ${JSON.stringify(k).slice(0, 60)}`);
+    const behaviorReplace = overlays.find((o) => o.op === "replace" && sectionOfMessage(o.target)?.band === "core-behavior");
+    if (behaviorReplace !== undefined && evidence.refs.length === 0) {
+        return fail("evidence", `overlay "${behaviorReplace.id}" replaces core-behavior text; evidence.refs names at least one evaluation or golden`);
     }
-    const ids = new Set();
-    let totalBytes = 0;
-    const sections = [];
-    for (const rawSection of catalog.sections) {
-        if (rawSection === null || typeof rawSection !== "object")
-            return fail("shape", "section is not an object");
-        const s = rawSection;
-        if (typeof s.id !== "string" || s.id.startsWith("core/") || s.id.length > ARTIFACT_LIMITS.maxIdLength || !ID_RE.test(s.id)) {
-            return fail("shape", `invalid section id ${JSON.stringify(s.id).slice(0, 120)}`);
-        }
-        if (ids.has(s.id))
-            return fail("shape", `duplicate section id "${s.id}"`);
-        ids.add(s.id);
-        if (typeof s.slot !== "string" || !SLOTS.has(s.slot))
-            return fail("shape", `unknown slot ${JSON.stringify(s.slot).slice(0, 60)} ("${s.id}")`);
-        if (typeof s.text !== "string" || s.text.length === 0)
-            return fail("shape", `empty/missing text ("${s.id}")`);
-        const bytes = Buffer.byteLength(s.text, "utf8");
-        if (bytes > ARTIFACT_LIMITS.maxSectionBytes)
-            return fail("limits", `section "${s.id}" ${bytes} bytes > max ${ARTIFACT_LIMITS.maxSectionBytes}`);
-        totalBytes += bytes;
-        if (typeof s.contentHash !== "string" || !DIGEST_RE.test(s.contentHash))
-            return fail("shape", `contentHash missing/malformed ("${s.id}")`);
-        if (s.contentHash !== sha256Hex(s.text))
-            return fail("content-hash", `contentHash does not match text ("${s.id}")`);
-        sections.push({ id: s.id, slot: s.slot, text: s.text, contentHash: s.contentHash });
-    }
-    if (totalBytes > ARTIFACT_LIMITS.maxTotalBytes)
-        return fail("limits", `catalog ${totalBytes} bytes > max ${ARTIFACT_LIMITS.maxTotalBytes}`);
-    const normalizedCatalog = { packId: catalog.packId, sections };
-    const normalizedPayload = {
-        schemaVersion: 1,
-        assemblyApi: 1,
-        catalogDigest: payload.catalogDigest,
-        ...(compatibleCore !== undefined ? { compatibleCore } : {}),
-        closure: { basePackId: "sema-default@1", promptCatalog: normalizedCatalog },
+    const normalized = {
+        schemaVersion: 2,
+        requires: requiresOf(overlays),
+        overlays,
+        evidence: { intent: evidence.intent, refs: [...evidence.refs] },
     };
-    if (computeCatalogDigest(normalizedCatalog) !== payload.catalogDigest) {
-        return fail("digest", "catalogDigest does not match canonical(promptCatalog)");
-    }
-    if (typeof art.artifactDigest !== "string" || !DIGEST_RE.test(art.artifactDigest))
-        return fail("shape", "artifactDigest malformed");
-    if (computeArtifactDigest(normalizedPayload) !== art.artifactDigest) {
+    if (computeArtifactDigest(normalized) !== raw.artifactDigest)
         return fail("digest", "artifactDigest does not match canonical(payload)");
-    }
-    return { ok: true, artifact: { payload: normalizedPayload, artifactDigest: art.artifactDigest } };
+    return { ok: true, artifact: { payload: normalized, artifactDigest: raw.artifactDigest } };
 }
-export function artifactDeclarations(artifact) {
-    return artifact.payload.closure.promptCatalog.sections.map((s) => ({
-        id: s.id,
-        slot: s.slot,
-        text: s.text,
-        contentHash: s.contentHash,
-    }));
+const CENTER_ORIGIN = Object.freeze({ source: "center", by: "center" });
+export function centerOverlaysOf(adoption, binding) {
+    if (adoption === undefined)
+        return [];
+    return adoption.artifact.payload.overlays.filter((o) => o.scope?.binding === undefined || o.scope.binding === binding).map((overlay) => ({ overlay, origin: CENTER_ORIGIN }));
 }
-export function buildPromptArtifactEnvelope(opts) {
-    const catalog = {
-        packId: opts.packId,
-        sections: opts.sections.map((s) => ({ ...s, contentHash: sha256Hex(s.text) })),
-    };
-    const payload = {
-        schemaVersion: 1,
-        assemblyApi: 1,
-        catalogDigest: computeCatalogDigest(catalog),
-        ...(opts.compatibleCore !== undefined ? { compatibleCore: opts.compatibleCore } : {}),
-        closure: { basePackId: "sema-default@1", promptCatalog: catalog },
-    };
-    return {
-        artifact: { payload, artifactDigest: computeArtifactDigest(payload) },
-        sourceRevision: opts.sourceRevision,
-    };
+export function adoptCenter(artifact, sourceRevision) {
+    const v = verifyPromptArtifactBody(artifact);
+    return v.ok ? { artifact: v.artifact, ...(sourceRevision !== undefined ? { sourceRevision } : {}) } : undefined;
+}
+export function buildPromptArtifact(opts) {
+    const payload = JSON.parse(JSON.stringify({ schemaVersion: 2, requires: requiresOf(opts.overlays), overlays: opts.overlays, evidence: opts.evidence }));
+    return verifyPromptArtifact({ payload, artifactDigest: sha256Hex(canonical(payload)), sourceRevision: opts.sourceRevision });
 }

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

@@ -1,42 +1,46 @@
+/**
+ * Prepare-side assembly adapter — the SINGLE entry that drives the Composer over the bundled catalog. Prepare
+ * hands it the run's facts and tails and the overlays of each source class (the task class: the request-body
+ * sugar's, then the task seat's mods; the center class; the deploy class: the deployment seat's mods); it
+ * orders the classes `task < center < deploy`, composes, and reports every overlay a later one superseded.
+ *
+ * There is no "provider" here: no source owns the whole prompt, the locked bands have no writer, and a role
+ * text that carries locked text never reaches this point (the sugar refuses it, a mods handler's answer is
+ * skipped).
+ */
 import type { AgentTool } from "../internal/harness-types.js";
-import { type EnvironmentFacts, type PromptProvider, type PromptTextDeclaration } from "../prompts/default.js";
+import type { HostForm, HostRole } from "./catalog/schema.js";
+import { type SourcedOverlay, type SupersededOverlay } from "./overlay.js";
 import type { CompiledSection, CompiledSystemBlock, PromptRuntimeFacts } from "./types.js";
 export interface AssembleInputs {
-    provider: PromptProvider;
-    /** True when the provider is the built-in defaultPromptProvider (checked FIRST — its stableSystem
-     *  output contains the constitution anchors and would misroute through the M9 guard). */
-    isDefaultProvider: boolean;
-    userSystemPrompt?: string;
-    userAppendSystemPrompt?: string;
-    tools: AgentTool[];
+    /** The task class, in application order: the request-body sugar's overlays, then the task seat's mods. */
+    taskOverlays: readonly SourcedOverlay[];
+    /** The center class (the adopted center layer's overlays). */
+    centerOverlays: readonly SourcedOverlay[];
+    /** The deploy class: the deployment seat's mods, in chain order. */
+    deployOverlays: readonly SourcedOverlay[];
+    /** The host selector values (`TaskSpec.promptRole` / `TaskSpec.promptForm`). */
+    host?: {
+        role?: HostRole;
+        form?: HostForm;
+    };
+    tools: readonly AgentTool[];
     facts: PromptRuntimeFacts;
+    /** The task's working directory (the Cowork role base's `{{workspaceFolder}}`). */
+    workspaceFolder?: string;
     mcpInstructionsBlock?: string;
     memoryBlock?: string;
     /** Renders the environment tail for a given date (leg-frozen; date_change re-render seam). */
     buildEnvBlock: (date: string) => string | undefined;
-    /** The leg's frozen date — the initial render input (design/66 date_change). */
+    /** The leg's frozen date — the initial render input. */
     date: string;
-    /** The environment facts the tail renders from; a provider sees them without the date (`StablePromptContext.envFacts`). */
-    envFacts?: EnvironmentFacts;
     modelGuidance?: string;
-    /** design/148 S1 — declarations compiled from a VERIFIED center prompt artifact (the adoption
-     *  channel: core verifies the artifact, synthesizes these, and they ride the same mount loop as
-     *  provider stableBlocks — same manifest/epoch/contentHash faces, zero new assembly machinery).
-     *  Mounted ahead of provider declarations on every COMPOSED path; the provider-assembled
-     *  pass-through path cannot mount them (operator-visible warn, never silent). */
-    centerDeclarations?: PromptTextDeclaration[];
     /** Structured warning channel (maps to deps.onError with a phase). */
     onWarn?: (message: string, phase: "prompt-constitution") => void;
 }
 export interface AssembledPrompt {
-    constitution: "core" | "replaced" | "provider-assembled";
-    /** design/148 S1: true ⇔ the supplied centerDeclarations were actually COMPILED into
-     *  this prompt. The caller must never persist a center pin when this is false — a pin that claims
-     *  an artifact the model never received is a durable lie (the assembled-identity pass-through path
-     *  warns + false). */
-    centerMounted?: boolean;
     /** Re-render the full prompt for a date. */
-    renderWithDate?: (date: string) => string;
+    renderWithDate: (date: string) => string;
     /** The initially-rendered system prompt. */
     systemPrompt: string;
     /** The `prompt.assembled` block view (the id wordlist is a downstream contract). */
@@ -44,10 +48,11 @@ export interface AssembledPrompt {
         id: string;
         text: string;
     }>;
-    /** Compiled IR of the last render — manifest v2 source. */
-    sections?: CompiledSection[];
-    /** S4: physical system blocks of the last render (sema-default: ONE block, text === systemPrompt —
-     *  byte-identity). */
-    systemBlocks?: CompiledSystemBlock[];
+    /** Compiled IR of the last render — the manifest's section source. */
+    sections: CompiledSection[];
+    /** Physical system blocks of the last render (one block, text === systemPrompt). */
+    systemBlocks: CompiledSystemBlock[];
+    /** The composition's {@link ComposedWithOverlays.superseded}, from the first render. */
+    superseded: readonly SupersededOverlay[];
 }
 export declare function assemblePrompt(inputs: AssembleInputs): AssembledPrompt;