@sema-agent/core/dist/engine/session/import-validate.d.ts

Stateless, task-oriented AI agent core

import { type SessionTreeEntry } from "../harness/types.js";
/** Options for {@link StreamingImportValidator} / {@link validateEntriesForImport}. */
export interface ImportValidatorOptions {
    /**
     * design/171 §6.4 — the import door's SECOND WRITE GATE for `UserMessage.actor`. Default `false`
     * (fail-closed): imported history has its `actor` assertions STRIPPED — an importer must never
     * re-assert who spoke in a history it did not witness (`hostAsserted:true` is an ingress-derived
     * claim, and import is not an ingress). `true` = the operator DECLARES the source trusted
     * (e.g. a same-deployment backend migration) and well-formed assertions are preserved verbatim;
     * shape-contaminated ones are still stripped like the sibling metadata fields.
     */
    preserveActorAssertions?: boolean;
}
export declare class StreamingImportValidator {
    private readonly seen;
    /** RB-129: entry id → parentId, so the compaction floor check can walk ANCESTRY rather than stream order. */
    private readonly parentOf;
    private rootCount;
    private runningLeaf;
    private done;
    /** design/171 — see {@link ImportValidatorOptions.preserveActorAssertions}. */
    private readonly preserveActorAssertions;
    constructor(options?: ImportValidatorOptions);
    /** Validate ONE entry, in oldest-first order. Throws `SessionError("invalid_session")` on the first violation
     *  (duplicate id, or a parent/structural reference not stepped before this entry). */
    step(entry: SessionTreeEntry): void;
    /** Finalize the stream: exactly one root (for a non-empty log) + the derived leaf resolves to a stepped entry.
     *  Returns the resolved leaf id (null for an empty session). Throws on violation; single-use. */
    finish(): {
        leafId: string | null;
    };
}
/**
 * Validate a verbatim session-entry log for cross-backend IMPORT (2c session-sync). The ARRAY
 * form of {@link StreamingImportValidator} (ONE source of truth — this just drives step()/finish() over the
 * array, kept for `fork`/tests that already hold the whole log). Fail-CLOSED: any violation throws
 * `SessionError("invalid_session")` and nothing is written.
 *
 * Returns the validated log with ids/parents/timestamps preserved (the imported session is
 * byte-identical to the source; only the owner is re-stamped by the caller, not here), modulo the
 * single engine-provenance normalization carve-out ([c209-C] R4 double-stamp + R5 shape + design/171
 * actor gate) documented on {@link StreamingImportValidator} — applied to a PROTECTED COPY of each
 * message entry, never to the caller's shared objects (see the clone note in the body).
 */
export declare function validateEntriesForImport(entries: SessionTreeEntry[], options?: ImportValidatorOptions): SessionTreeEntry[];