@sema-agent/core/dist/core/memory-engine/delegation-provenance.d.ts

Stateless, task-oriented AI agent core

/**
 * design/180 half A — delegation RUNTIME provenance: the three-value attestation and its monotonic
 * aggregate. The static tool-face judgment ({@link import("./content-origin.js").delegationCallIsExternal})
 * stays the FLOOR of the attestation reduction: runtime evidence may only retire the static verdict
 * when a COMPLETE clean proof is in hand; any evidence gap falls back to the floor. "We could not
 * prove it clean" and "it is clean" are different answers — replacing the floor outright would fail
 * OPEN on every evidence gap (old child vintages, crashes, un-armed sessions). Whether the floor's
 * verdict MARKS the judging session's memory is a separate, deployment-governed question
 * (design/324, `RunnerDeps.memoryDelegationEvidence`): the reduction semantics here never change
 * with that key — only the mark action at the judging run's wrap does.
 *
 * The aggregate is two MONOTONIC bits plus versioning:
 *  - `sawExternal` — an actually-observed polluting-class invocation (own recorder, or a delivered
 *    child attestation of `external`). Once set, never cleared.
 *  - `incomplete` — some stretch of the session's conduct is unprovable (a delegation delivered no /
 *    an unknown attestation, a resume lost the aggregate, the recorder was not armed from turn 0).
 *    Once set, never cleared.
 * Reduction order is FIXED (design/180 r3): `sawExternal ⇒ external` > `incomplete ⇒ unknown` >
 * `clean` — an observed external event always outranks an evidence gap (missing evidence can make
 * "clean" unprovable; it can never make an observed event disappear).
 */
/** The three-value delegation attestation. Only `clean` changes behavior (the parent skips the
 *  static mark); `unknown` is byte-equivalent to absence (the static floor governs — its mark
 *  action subject to the judging run's deployment evidence standard, design/324); `external` marks
 *  unconditionally on every evidence standard, with the observed-event reason. */
export type DelegationAttestation = "clean" | "external" | "unknown";
/** The monotonic per-run provenance aggregate (in-process this slice; the durable-checkpoint
 *  persistence leg rides the background-face slice — absence after a resume reads `incomplete`,
 *  which is the fail-closed default this shape is built around). */
export interface DelegationProvenanceAggregate {
    version: 1;
    /** Turn index the recorder was armed from. 0 ⇔ armed at prepare (full coverage). */
    coverageStartTurn: number;
    sawExternal: boolean;
    incomplete: boolean;
}
/** The frozen content-safety snapshot a parent hands its delegated children (design/180 A-2): the
 *  classification config the child's recorder must judge under. Inherit-narrow-only — see
 *  {@link narrowContentSafety}. */
export interface DelegationContentSafety {
    trustedTools: readonly string[];
    execIsExternalContent: boolean;
}
export declare function newDelegationProvenanceAggregate(): DelegationProvenanceAggregate;
/**
 * Effective content-safety for a run: the parent chain's frozen snapshot ∩ the run's own config.
 * A child may NARROW what the chain trusts (fewer trusted tools, stricter exec), never widen it —
 * a wider child-side allowlist must not launder a chain-external tool into `local` on the way up.
 * At least one input must be present (the caller only computes this when armed).
 */
export declare function narrowContentSafety(parent: DelegationContentSafety | undefined, own: {
    trustedTools: ReadonlySet<string>;
    execIsExternalContent: boolean;
} | undefined): {
    trustedTools: Set<string>;
    execIsExternalContent: boolean;
};
/** Reduce an aggregate to the delivered attestation. `completed` = the child reached its terminal
 *  normally with its full result delivered — a salvage/partial/errored child can never prove clean
 *  (its conduct after the cut is unobserved), though an OBSERVED external event still reports. */
export declare function reduceDelegationAttestation(agg: DelegationProvenanceAggregate | undefined, opts: {
    completed: boolean;
}): DelegationAttestation;
/** Read a delivered card's attestation field (the explicit-whitelist handback seat). Anything but
 *  the three spellings — including absence — reads as undefined, i.e. the static floor governs
 *  (whether that floor MARKS is the judging run's deployment evidence standard, design/324). */
export declare function readCardAttestation(details: unknown): DelegationAttestation | undefined;