@sema-agent/core/dist/prompt-assembly/artifact.d.ts

Stateless, task-oriented AI agent core

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 they name. */
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[];
}
/** 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[];
}
/** The digested part of an artifact. */
export interface PromptArtifactPayload {
    readonly schemaVersion: 3;
    readonly requires: PromptArtifactRequires;
    /** Every overlay is of the `center` class; one with no `when.binding` applies under every binding. */
    readonly overlays: readonly PromptOverlay[];
    readonly evidence: PromptArtifactEvidence;
}
/** 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;
}
/** The published form: the artifact plus its opaque source revision (never ordered, never compared for recency). */
export interface PublishedPromptArtifact extends PromptArtifact {
    readonly sourceRevision: string;
}
/** Validator bounds: they bound abuse and runaway publishes, not legitimate artifacts. A `…Chars` bound counts Unicode
 *  code points (`codePointsOver`, the verifier's one character unit); a `…Bytes` bound counts UTF-8 bytes. */
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: PublishedPromptArtifact;
} | {
    ok: false;
    code: ArtifactVerifyCode;
    reason: string;
};
type BodyVerifyResult = {
    ok: true;
    artifact: PromptArtifact;
} | {
    ok: false;
    code: ArtifactVerifyCode;
    reason: string;
};
/** Why an artifact is invalid (docs/CLOSED-SETS.md). */
export type ArtifactVerifyCode = "shape" | "schema" | "limits" | "requires" | "overlay" | "evidence" | "digest";
/**
 * 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): 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, in the artifact's order. Which of them apply to a run is their
 *  `when` (the binding included), read where every class's is — at the composition. */
export declare function centerOverlaysOf(adoption: CenterAdoption | 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;
/**
 * 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) with each overlay as the
 * overlay door leaves it (its `when` in normal form, so one meaning is one digest), and the result goes through the
 * verifier, so the caller holds either a valid artifact or the reason it is not one. An overlay the door refuses goes on
 * as it was given: the verifier names it, in its own order of checks.
 */
export declare function buildPromptArtifact(opts: {
    overlays: readonly PromptOverlay[];
    evidence: PromptArtifactEvidence;
    sourceRevision: string;
}): ArtifactVerifyResult;
export {};