@sema-agent/core 7.51.1 → 7.52.0

package/dist/prompt-assembly/artifact-store.js

@@ -1,29 +1,25 @@
 import { mkdirSync, promises as fs } from "node:fs";
 import path from "node:path";
-import { verifyPromptArtifact, } from "./artifact.js";
-function normalizedEnvelope(parsed, artifact) {
-    return { ...parsed, artifact };
+import { verifyPromptArtifact } from "./artifact.js";
+function verifiedRead(bytes, artifactDigest) {
+    let parsed;
+    try {
+        parsed = JSON.parse(bytes);
+    }
+    catch {
+        return undefined;
+    }
+    const v = verifyPromptArtifact(parsed);
+    return v.ok && v.artifact.artifactDigest === artifactDigest ? v.artifact : undefined;
 }
 export class MemoryPromptArtifactStore {
     byDigest = new Map();
-    async get(artifactDigest, opts) {
+    async get(artifactDigest) {
         const bytes = this.byDigest.get(artifactDigest);
-        if (bytes === undefined)
-            return undefined;
-        let parsed;
-        try {
-            parsed = JSON.parse(bytes);
-        }
-        catch {
-            return undefined;
-        }
-        const v = verifyPromptArtifact(parsed, opts);
-        if (!v.ok || v.artifact.artifactDigest !== artifactDigest)
-            return undefined;
-        return normalizedEnvelope(parsed, v.artifact);
+        return bytes === undefined ? undefined : verifiedRead(bytes, artifactDigest);
     }
-    async put(envelope) {
-        this.byDigest.set(envelope.artifact.artifactDigest, JSON.stringify(envelope));
+    async put(artifact) {
+        this.byDigest.set(artifact.artifactDigest, JSON.stringify(artifact));
     }
 }
 export class FilePromptArtifactStore {
@@ -36,7 +32,7 @@ export class FilePromptArtifactStore {
         const m = /^sha256:([0-9a-f]{64})$/.exec(artifactDigest);
         return m ? path.join(this.dir, "artifacts", `${m[1]}.json`) : undefined;
     }
-    async get(artifactDigest, opts) {
+    async get(artifactDigest) {
         const file = this.fileFor(artifactDigest);
         if (file === undefined)
             return undefined;
@@ -47,24 +43,14 @@ export class FilePromptArtifactStore {
         catch {
             return undefined;
         }
-        let parsed;
-        try {
-            parsed = JSON.parse(bytes);
-        }
-        catch {
-            return undefined;
-        }
-        const v = verifyPromptArtifact(parsed, opts);
-        if (!v.ok || v.artifact.artifactDigest !== artifactDigest)
-            return undefined;
-        return normalizedEnvelope(parsed, v.artifact);
+        return verifiedRead(bytes, artifactDigest);
     }
-    async put(envelope) {
-        const file = this.fileFor(envelope.artifact.artifactDigest);
+    async put(artifact) {
+        const file = this.fileFor(artifact.artifactDigest);
         if (file === undefined)
-            throw new Error(`prompt-artifact store: malformed digest ${JSON.stringify(envelope.artifact.artifactDigest).slice(0, 120)}`);
+            throw new Error(`prompt-artifact store: malformed digest ${JSON.stringify(artifact.artifactDigest).slice(0, 120)}`);
         const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
-        await fs.writeFile(tmp, JSON.stringify(envelope), "utf8");
+        await fs.writeFile(tmp, JSON.stringify(artifact), "utf8");
         await fs.rename(tmp, file);
     }
 }
@@ -113,7 +99,6 @@ export class FilePromptSourceStateStore {
 export class CenterPromptSource {
     store;
     stateStore;
-    engineVersion;
     candidate;
     state = "unavailable";
     tail = Promise.resolve();
@@ -125,16 +110,14 @@ export class CenterPromptSource {
     constructor(opts) {
         this.store = opts.store;
         this.stateStore = opts.stateStore ?? new MemoryPromptSourceStateStore();
-        this.engineVersion = opts.engineVersion;
     }
     current() {
         return this.candidate;
     }
     async get(artifactDigest) {
-        if (this.candidate?.artifact.artifactDigest === artifactDigest)
-            return this.candidate.artifact;
-        const env = await this.store.get(artifactDigest, { engineVersion: this.engineVersion });
-        return env?.artifact;
+        if (this.candidate?.artifactDigest === artifactDigest)
+            return this.candidate;
+        return this.store.get(artifactDigest);
     }
     async restore() {
         return this.exclusive(async () => {
@@ -149,23 +132,22 @@ export class CenterPromptSource {
                 this.state = "unavailable";
                 return;
             }
-            const env = await this.store.get(state.artifactDigest, { engineVersion: this.engineVersion });
-            this.candidate = env !== undefined ? { artifact: env.artifact, sourceRevision: state.sourceRevision } : undefined;
-            this.state = env !== undefined ? "active" : "unavailable";
+            const stored = await this.store.get(state.artifactDigest);
+            this.candidate = stored !== undefined ? { ...stored, sourceRevision: state.sourceRevision } : undefined;
+            this.state = stored !== undefined ? "active" : "unavailable";
         });
     }
     sourceState() {
         return this.state;
     }
     async applySnapshot(raw) {
-        const v = verifyPromptArtifact(raw, { engineVersion: this.engineVersion });
+        const v = verifyPromptArtifact(raw);
         if (!v.ok)
             return v;
-        const envelope = raw;
         return this.exclusive(async () => {
-            await this.store.put(envelope);
-            await this.stateStore.save({ state: "active", artifactDigest: v.artifact.artifactDigest, sourceRevision: envelope.sourceRevision });
-            this.candidate = { artifact: v.artifact, sourceRevision: envelope.sourceRevision };
+            await this.store.put(v.artifact);
+            await this.stateStore.save({ state: "active", artifactDigest: v.artifact.artifactDigest, sourceRevision: v.artifact.sourceRevision });
+            this.candidate = v.artifact;
             this.state = "active";
             return { ok: true, artifactDigest: v.artifact.artifactDigest };
         });

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

@@ -1,92 +1,105 @@
-import type { PromptTextDeclaration } from "../prompts/default.js";
-/** v1 overlay slots — the same reserved rank bands the stableBlocks lane mounts into. */
-export type CenterOverlaySlot = "identity" | "scenario" | "behavior";
-export interface CenterOverlaySection {
-    /** Same grammar as stableBlocks ids (manifest/trace/explain-safe, never `core/`). */
-    id: string;
-    slot: CenterOverlaySlot;
-    /** Immutable rendered text (v1: fixed text, no renderer — center compiles before publishing). */
-    text: string;
-    /** REQUIRED on the center lane (unlike caller stableBlocks): sha256 of `text`. The center
-     *  publish path always mints it — it is the reconciliation anchor (digest tiering). */
-    contentHash: string;
+import { type OverlayOp, type PromptTrait } from "./catalog/schema.js";
+import { type PromptOverlay, type SourcedOverlay } from "./overlay.js";
+/** What an artifact needs from the engine that composes it: the targets it names (each with what kind of target it
+ *  is), the operations it uses, the traits its `when` conditions read, and the bindings its overlays are scoped to. */
+export interface PromptArtifactRequires {
+    readonly targets: readonly {
+        readonly id: string;
+        readonly kind: "message" | "section" | "band";
+    }[];
+    readonly ops: readonly OverlayOp[];
+    readonly traits: readonly PromptTrait[];
+    readonly bindings: readonly string[];
 }
-export interface PromptCatalogSnapshot {
-    /** Center pack identity, e.g. "center:acme@3". Logical name only — history identity is digests. */
-    packId: string;
-    sections: ReadonlyArray<CenterOverlaySection>;
+/** Why the artifact exists: an intent sentence (required) and references to the evaluations or goldens behind it. */
+export interface PromptArtifactEvidence {
+    readonly intent: string;
+    readonly refs: readonly string[];
 }
-export interface PromptDependencyClosure {
-    /** v1: only the bundled base is a legal foundation (exact-archive multi-base = later slice). */
-    basePackId: string;
-    promptCatalog: PromptCatalogSnapshot;
+/** The digested part of an artifact. */
+export interface PromptArtifactPayload {
+    readonly schemaVersion: 2;
+    readonly requires: PromptArtifactRequires;
+    /** Every overlay is of the `center` class; `scope.binding` absent ⇒ applies under every binding. */
+    readonly overlays: readonly PromptOverlay[];
+    readonly evidence: PromptArtifactEvidence;
 }
-/** Dependency-free core-compat range: dotted-triple compares, absent bound = unbounded. */
-export interface CoreCompatRange {
-    minCore?: string;
-    maxCoreExclusive?: string;
+/** An artifact's identity: the payload and its digest (what a session pins and a store holds by digest). */
+export interface PromptArtifact {
+    readonly payload: PromptArtifactPayload;
+    readonly artifactDigest: string;
 }
-export interface PromptEpochArtifactPayload {
-    schemaVersion: 1;
-    assemblyApi: 1;
-    catalogDigest: string;
-    compatibleCore?: CoreCompatRange;
-    closure: PromptDependencyClosure;
+/** The published form: the artifact plus its opaque source revision (never ordered, never compared for recency). */
+export interface PublishedPromptArtifact extends PromptArtifact {
+    readonly sourceRevision: string;
 }
-export interface PromptEpochArtifact {
-    payload: PromptEpochArtifactPayload;
-    artifactDigest: string;
-}
-/** The publish envelope (§9.2): artifact + opaque source provenance. Attestation = later slice
- *  (protocol: first phase does not require full PKI for internal artifacts). */
-export interface PublishedPromptArtifactEnvelope {
-    artifact: PromptEpochArtifact;
-    /** Opaque ETag-like revision. State transitions key off "last successfully verified response";
-     *  NEVER ordered or compared for recency. */
-    sourceRevision: string;
-}
-/** Validator hard limits (§9.2: sections/bytes caps so a untrusted or runaway publish cannot wedge
- *  the composer). Deliberately generous — these bound abuse, not legitimate catalogs. */
-export declare const ARTIFACT_LIMITS: {
-    readonly maxSections: 64;
-    readonly maxSectionBytes: 32000;
-    readonly maxTotalBytes: 131072;
-    readonly maxIdLength: 128;
-    readonly maxPackIdLength: 200;
-};
-export declare function sha256Hex(text: string): string;
-export declare function computeCatalogDigest(catalog: PromptCatalogSnapshot): string;
-export declare function computeArtifactDigest(payload: PromptEpochArtifactPayload): string;
+/** Validator bounds: they bound abuse and runaway publishes, not legitimate artifacts. */
+export declare const ARTIFACT_LIMITS: Readonly<{
+    maxOverlays: 64;
+    maxOverlayTextBytes: 32000;
+    maxTotalTextBytes: 131072;
+    maxIntentChars: 2000;
+    maxRefs: 32;
+    maxRefChars: 500;
+    maxSourceRevisionChars: 500;
+}>;
+export declare function computeArtifactDigest(payload: PromptArtifactPayload): string;
+/** The requirement set an overlay list implies — the one derivation the builder stores and the verifier recomputes. */
+export declare function requiresOf(overlays: readonly PromptOverlay[]): PromptArtifactRequires;
+/** The requirements this engine does not meet (empty ⇒ all met): a target its catalog lacks, an op or a trait outside
+ *  its vocabulary. Bindings are the deployment's open vocabulary and are always met. */
+export declare function unmetRequirements(requires: PromptArtifactRequires): string[];
 export type ArtifactVerifyResult = {
     ok: true;
-    artifact: PromptEpochArtifact;
+    artifact: PublishedPromptArtifact;
+} | {
+    ok: false;
+    code: ArtifactVerifyCode;
+    reason: string;
+};
+type BodyVerifyResult = {
+    ok: true;
+    artifact: PromptArtifact;
 } | {
     ok: false;
-    code: string;
+    code: ArtifactVerifyCode;
     reason: string;
 };
+/** Why an artifact is invalid (docs/CLOSED-SETS.md). */
+export type ArtifactVerifyCode = "shape" | "schema" | "limits" | "requires" | "overlay" | "evidence" | "digest";
 /**
- * Full §9.2 verify pipeline over an UNTRUSTED envelope (network body or disk bytes — the store
- * re-verifies on read; nothing on disk is trusted by location). Every arm is a distinct coded
- * rejection so the source-state machine can log honestly. Verification is pure — no IO.
+ * Verify an UNTRUSTED published artifact (a network body or stored bytes — a store re-verifies on read). Pure. Any
+ * failure invalidates the whole artifact: shape, schema version, bounds, each overlay under the center class's band
+ * columns and the locked-text guard, the stored requirement list (recomputed, then checked against this engine),
+ * same-target replace conflicts, the evidence rule, and the digest.
  */
-export declare function verifyPromptArtifact(raw: unknown, opts: {
-    engineVersion: string;
-}): ArtifactVerifyResult;
+export declare function verifyPromptArtifact(raw: unknown): ArtifactVerifyResult;
+/**
+ * The same verifier over an artifact without its provenance — what a run re-checks when it adopts an artifact from
+ * its source (a candidate, a pinned digest, a parent's layer): requirements are met by THIS engine, every overlay is
+ * legal here, the digest holds. A source is a deployment seat; what it hands the run is checked, not trusted.
+ */
+export declare function verifyPromptArtifactBody(raw: unknown): BodyVerifyResult;
+/** The center layer a run composes under: the adopted artifact and, when the source stamped one, its revision. */
+export type CenterAdoption = {
+    artifact: PromptArtifact;
+    sourceRevision?: string;
+};
+/**
+ * The center class's overlays for an adopted artifact under a binding: every overlay with no `scope.binding`, and
+ * every one whose `scope.binding` equals the run's binding, in the artifact's order.
+ */
+export declare function centerOverlaysOf(adoption: CenterAdoption | undefined, binding: string | undefined): readonly SourcedOverlay[];
+/** An artifact a source handed a run, re-checked by this engine before the run adopts it; undefined when it fails. */
+export declare function adoptCenter(artifact: PromptArtifact, sourceRevision: string | undefined): CenterAdoption | undefined;
 /**
- * Compile a VERIFIED artifact into the declaration lane (v1 adoption channel — see file header).
- * Deterministic order: catalog order preserved (it entered the digest, so it is stable).
+ * Build a published artifact from overlays and evidence — the one builder (a center's publish pipeline calls it):
+ * `requires` is derived, the digest computed over the payload's JSON form (what travels), and the result goes
+ * through the verifier, so the caller holds either a valid artifact or the reason it is not one.
  */
-export declare function artifactDeclarations(artifact: PromptEpochArtifact): PromptTextDeclaration[];
-/** Test/fixture helper: build a correctly-digested envelope from plain sections (the shape a
- *  center's publish pipeline produces). Exported for tests and the fixture-center harness. */
-export declare function buildPromptArtifactEnvelope(opts: {
-    packId: string;
-    sections: ReadonlyArray<{
-        id: string;
-        slot: CenterOverlaySlot;
-        text: string;
-    }>;
+export declare function buildPromptArtifact(opts: {
+    overlays: readonly PromptOverlay[];
+    evidence: PromptArtifactEvidence;
     sourceRevision: string;
-    compatibleCore?: CoreCompatRange;
-}): PublishedPromptArtifactEnvelope;
+}): ArtifactVerifyResult;
+export {};