@fuaran-ui/ops 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,552 @@
+import { Result, NodeId, NodeKind, JsonValue, Binding, SemanticStyle, StateBehaviour, Node, Cell, ColExpr, DataSource, Transform, EvalError, Table, TextSource, CellFormat, ColumnWidth, Orientation, ToneVariant, StyleWeight, Emphasis, HeadingVariant, BadgeVariant, IconSource } from '@fuaran-ui/schema';
+
+/** Local JSON AST. Shape-for-shape port of the F# decoder's private `Json` DU. */
+type JsonAst = {
+    readonly kind: 'JNull';
+} | {
+    readonly kind: 'JBool';
+    readonly value: boolean;
+} | {
+    readonly kind: 'JNumber';
+    readonly value: number;
+} | {
+    readonly kind: 'JString';
+    readonly value: string;
+} | {
+    readonly kind: 'JArray';
+    readonly items: readonly JsonAst[];
+} | {
+    readonly kind: 'JObject';
+    readonly fields: ReadonlyMap<string, JsonAst>;
+};
+/** Structural parse failure carrying the byte offset where it was detected. */
+interface ParseError {
+    readonly message: string;
+    readonly offset: number;
+}
+/**
+ * Parse a JSON document into the local AST. Mirrors the F# `tryParse`: empty /
+ * whitespace-only input is a structural error; otherwise a single top-level
+ * value is parsed (trailing content after the first value is not inspected,
+ * matching the F# parser).
+ */
+declare const parse: (input: string) => Result<JsonAst, ParseError>;
+/** Look up an object field by key (key-order tolerant per WIRE_FORMAT.md §2). */
+declare const field: (fields: ReadonlyMap<string, JsonAst>, key: string) => JsonAst | undefined;
+
+type TreeOp<TMsg> = {
+    readonly kind: 'EditNode';
+    readonly target: NodeId;
+    readonly newKind: NodeKind<TMsg>;
+} | {
+    readonly kind: 'UpdateProp';
+    readonly target: NodeId;
+    readonly path: string;
+    readonly value: JsonValue;
+} | {
+    readonly kind: 'ReplaceBinding';
+    readonly target: NodeId;
+    readonly slot: string;
+    readonly binding: Binding<unknown>;
+} | {
+    readonly kind: 'UpdateStyle';
+    readonly target: NodeId;
+    readonly style: SemanticStyle;
+} | {
+    readonly kind: 'UpdateState';
+    readonly target: NodeId;
+    readonly state: StateBehaviour<TMsg>;
+} | {
+    readonly kind: 'InsertChild';
+    readonly parentId: NodeId;
+    readonly position: number;
+    readonly child: Node<TMsg>;
+} | {
+    readonly kind: 'RemoveNode';
+    readonly target: NodeId;
+} | {
+    readonly kind: 'MoveNode';
+    readonly target: NodeId;
+    readonly newParentId: NodeId;
+    readonly newPosition: number;
+} | {
+    readonly kind: 'ReorderChildren';
+    readonly parentId: NodeId;
+    readonly newOrder: readonly NodeId[];
+} | {
+    readonly kind: 'ReplaceRoot';
+    readonly node: Node<TMsg>;
+} | {
+    readonly kind: 'Batch';
+    readonly ops: readonly TreeOp<TMsg>[];
+};
+
+/**
+ * Re-render a parsed JSON AST (parse.ts) to canonical wire bytes — Ordinal-
+ * sorted object keys (§2 rule 2), the §2 rule-5 number layout, the §2 rule-6
+ * string escapes — using the very primitives the encoder uses. For input that
+ * was already canonical, `renderAstCanonical(parse(x)) === x`. This is the
+ * §15 wire-versioning building block: it re-emits a preserved `Unknown`
+ * payload byte-for-byte (must-ignore-but-preserve, WIRE_FORMAT.md §15.3) and
+ * renders the `$profile` / `$payload` envelope. Mirrors F#
+ * `Fuaran.Core.Wire.Canon.render` composed over the same JVal shape.
+ */
+declare const renderAstCanonical: (ast: JsonAst) => string;
+/** Encode a `DataSource` to its canonical-JSON string (Compute layer). */
+declare const encodeDataSource: (src: DataSource) => string;
+/** Encode a literal `Cell` to its `$type`-tagged canonical-JSON string. */
+declare const encodeCell: (c: Cell) => string;
+/** Encode a `ColExpr` to its canonical-JSON string. */
+declare const encodeColExpr: (e: ColExpr) => string;
+/** Encode a transform `pipeline` (ordered steps) to its canonical-JSON array string. */
+declare const encodePipeline: (pipeline: readonly Transform[]) => string;
+/** Encode a `Node<TMsg>` to its canonical-JSON string (WIRE_FORMAT.md). */
+declare const encodeNode: <TMsg>(n: Node<TMsg>) => string;
+/** Encode a `TreeOp<TMsg>` to its canonical-JSON string (WIRE_FORMAT.md). */
+declare const encodeOp: <TMsg>(op: TreeOp<TMsg>) => string;
+
+type DR<T> = Result<T, EvalError>;
+/** The canonical string of a cell (float via the shared `Canon` layout). */
+declare const cellString: (c: Cell) => string;
+/** Evaluate a `ColExpr` against one row. */
+/** The evaluation environment (fuaran-core#77) — binds each `ColExpr.param` name to a `Cell`. */
+type EvalEnv = Readonly<Record<string, Cell>>;
+/** Resolve a `Ref` source to a concrete `Table` (default: reject every ref). */
+type SourceResolver = (ref: string) => DR<Table>;
+/** A `Ref`-rejecting resolver — the default for embedded-only pipelines. */
+declare const noResolve: SourceResolver;
+/** Evaluate a `DataSource` to a concrete `Table`, resolving a `Ref` through `resolve`. */
+declare const evalSource: (resolve: SourceResolver, src: DataSource) => DR<Table>;
+/**
+ * The reference evaluator: fold the pipeline over the input table, threading a
+ * `Frame`. `resolve` provides any `Ref` source a `Join` / `Union` names.
+ */
+declare const evalPipelineWithInEnv: (resolve: SourceResolver, env: EvalEnv, pipeline: readonly Transform[], input: Table) => DR<Table>;
+declare const evalPipelineWith: (resolve: SourceResolver, pipeline: readonly Transform[], input: Table) => DR<Table>;
+/** The reference evaluator over embedded sources only (`Ref` ⇒ `UnresolvedSource`). */
+declare const evalPipeline: (pipeline: readonly Transform[], input: Table) => DR<Table>;
+/** The env-aware evaluator over embedded sources only (fuaran-core#77 / Phase 424). */
+declare const evalPipelineInEnv: (env: EvalEnv, pipeline: readonly Transform[], input: Table) => DR<Table>;
+/** Render an `EvalError` as a stable human string (mirrors F# `DataFrame.errorString`). */
+declare const evalErrorString: (e: EvalError) => string;
+/** Every `ColExpr.param` name a single step references (only `filter` / `derive` carry a ColExpr). */
+declare const stepParams: (t: Transform) => readonly string[];
+/** Every distinct param name a pipeline references — the TS mirror of Core `Transform.paramsOf`. */
+declare const pipelineParams: (pipeline: readonly Transform[]) => readonly string[];
+
+/** Stable AI-friendly discriminator for decode-time failures (WIRE_FORMAT.md §6). */
+type DecodeErrorCode = 'INVALID_JSON' | 'MISSING_FIELD' | 'WRONG_TYPE' | 'UNKNOWN_DU_CASE' | 'WRONG_NODE_KIND' | 'EMPTY_NODE_ID';
+/** AI-recoverable decode-time failure. Mirrors the F# `DecodeError` record. */
+interface DecodeError {
+    readonly code: DecodeErrorCode;
+    readonly path: string;
+    readonly message: string;
+    readonly expectedShape?: string;
+}
+type R<T> = Result<T, DecodeError>;
+/** Typed-value coercers for `TreeOp.UpdateProp` (used by the apply engine). */
+declare const coerce: {
+    int: (v: JsonValue) => Result<number, string>;
+    float: (v: JsonValue) => Result<number, string>;
+    bool: (v: JsonValue) => Result<boolean, string>;
+    string: (v: JsonValue) => Result<string, string>;
+    textSource: (v: JsonValue) => Result<TextSource, string>;
+    bindingNumber: (v: JsonValue) => Result<Binding<number>, string>;
+    bindingInt: (v: JsonValue) => Result<Binding<number>, string>;
+    bindingBool: (v: JsonValue) => Result<Binding<boolean>, string>;
+    bindingString: (v: JsonValue) => Result<Binding<string>, string>;
+    cellFormat: (v: JsonValue) => Result<CellFormat, string>;
+    columnWidth: (v: JsonValue) => Result<ColumnWidth, string>;
+    orientation: (v: JsonValue) => Result<Orientation, string>;
+    tone: (v: JsonValue) => Result<ToneVariant, string>;
+    weight: (v: JsonValue) => Result<StyleWeight, string>;
+    emphasis: (v: JsonValue) => Result<Emphasis, string>;
+    /**
+     * The behavioural `emphasis` BOOL on Fact / LabelValueRow — the UpdateProp
+     * twin of `decodeEmphasisFlag`, so a TreeOp edit gets the same
+     * cross-vocabulary admission as a fresh decode (0.2.8, 2026-07-19 sweep).
+     */
+    emphasisFlag: (v: JsonValue) => Result<boolean, string>;
+    headingVariant: (v: JsonValue) => Result<HeadingVariant, string>;
+    badgeVariant: (v: JsonValue) => Result<BadgeVariant, string>;
+    iconSource: (v: JsonValue) => Result<IconSource, string>;
+};
+/** Decode a canonical-JSON `Node` payload into the storage-shape `Node<unknown>`. */
+declare const decodeNode: (json: string) => R<Node<unknown>>;
+/** Decode a canonical-JSON `TreeOp` payload into the storage-shape `TreeOp<unknown>`. */
+declare const decodeOp: (json: string) => R<TreeOp<unknown>>;
+
+type ApplyErrorCode = 'NodeNotFound' | 'ParentNotFound' | 'ChildlessKind' | 'PositionOutOfRange' | 'DuplicateNodeId' | 'FieldNotFound' | 'SlotNotFound' | 'KindMismatch' | 'PathInvalid' | 'PathNotSupportedYet' | 'OrderingMismatch' | 'BatchAborted';
+interface ApplyError {
+    readonly code: ApplyErrorCode;
+    readonly message: string;
+    /** Inner-op index when `code === 'BatchAborted'`. */
+    readonly batchIndex?: number;
+}
+/** One record per applied leaf op (Phase 76 telemetry contract). */
+interface OpApplyTelemetryRecord {
+    readonly op: TreeOp<unknown>['kind'];
+    readonly targetId: string;
+}
+type ApplyResult<TMsg> = Result<{
+    readonly newTree: Node<TMsg>;
+    readonly emittedTelemetry: readonly OpApplyTelemetryRecord[];
+}, ApplyError>;
+/**
+ * Apply a single tree-op against `tree`, returning either the updated tree plus
+ * emitted telemetry, or a structured `ApplyError`. Fold this across an op list
+ * to apply many; wrap in `TreeOp.Batch` for atomic all-or-nothing application.
+ */
+declare const apply: <TMsg>(tree: Node<TMsg>, op: TreeOp<TMsg>) => ApplyResult<TMsg>;
+
+/** The result envelope captured on a DAG record (closed shape). */
+type DagResultEnvelope = {
+    readonly $type: 'Success';
+} | {
+    readonly $type: 'Failure';
+    readonly code: string;
+    readonly message: string;
+};
+/**
+ * Content-addressed, multi-parent op-record — the branching-DAG generalisation
+ * of the linear `OpRecord`. `parents` is in author order (head = primary
+ * parent); `outcomeHash` is present only on a merge node (committed to the
+ * canonical encoding of the resulting tree). A linear chain is the degenerate
+ * single-parent case.
+ */
+interface DagOpRecord<TMsg = unknown> {
+    readonly streamId: string;
+    readonly hash: string;
+    readonly parents: readonly string[];
+    readonly op: TreeOp<TMsg>;
+    readonly outcomeHash?: string;
+    readonly promptId?: string;
+    readonly userId: string;
+    /** Unix seconds. */
+    readonly timestamp: number;
+    readonly resultEnvelope: DagResultEnvelope;
+    readonly tombstoned: boolean;
+}
+/**
+ * Encode a `DagOpRecord` to its canonical JSON wire form. Keys in Ordinal order
+ * (hash < op < outcomeHash < parents < promptId < resultEnvelope < streamId <
+ * timestamp < tombstoned < userId); `outcomeHash` / `promptId` omitted when
+ * absent; `op` nests `encodeOp` verbatim. Byte-identical to the F#
+ * `DagWire.encodeRecord`.
+ */
+declare const encodeDagRecord: <TMsg>(record: DagOpRecord<TMsg>) => string;
+type DecodeResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/**
+ * Decode a canonical DAG-record envelope. The nested `op` AST is routed through
+ * the canonical `decodeOp` (the same structural decoder the linear wire path
+ * uses). Returns a structured error string on any wire-shape violation.
+ */
+declare const decodeDagRecord: (json: string) => DecodeResult<DagOpRecord<unknown>>;
+
+type N = Node<unknown>;
+/** A `(nodeId, facet)` cell that could not be auto-merged. */
+interface MergeConflict {
+    readonly nodeId: string;
+    readonly facet: string;
+}
+/** Outcome of a 3-way merge: the merged tree, or the conflicting cells. */
+type MergeResult = {
+    readonly ok: true;
+    readonly tree: N;
+} | {
+    readonly ok: false;
+    readonly conflicts: readonly MergeConflict[];
+};
+/**
+ * Author-agnostic facet 3-way merge of `a` and `b` over their common `base`
+ * (all three share the root id). Returns the merged tree on full auto-merge, or
+ * the conflicting cells. Deterministic + host-reproducible (NodeId-byte
+ * tie-break, no wall-clock) — byte-identical to the F# `TreeMerge.merge3Way`.
+ */
+declare const merge3Way: (base: N, a: N, b: N) => MergeResult;
+
+/**
+ * A wire profile id — `<name>@<major>.<minor>` (e.g. `core@1.0`). `name` is the
+ * capability namespace; `major` is the `/vN/` incompatibility boundary (a
+ * removal/rename mints a new major — old consumers cannot interpret it); `minor`
+ * is the additive capability counter (a new kind/case/field bumps the minor — an
+ * older consumer tolerates it via must-ignore-but-preserve).
+ */
+interface Profile {
+    readonly name: string;
+    readonly major: number;
+    readonly minor: number;
+}
+/** The canonical string form: `<name>@<major>.<minor>`. */
+declare const renderProfile: (p: Profile) => string;
+/** The base `core` profile — `core@1.0` (the current wire). */
+declare const coreV1: Profile;
+/**
+ * Parse `<name>@<major>.<minor>`. Names a typed error on any malformed shape —
+ * the same envelope discipline as the decoder (no exceptions escape). Mirrors
+ * F# `Profile.tryParse`: split on the LAST `@`, require a `<major>.<minor>` of
+ * two non-negative integers.
+ */
+declare const tryParseProfile: (s: string) => Result<Profile, string>;
+/** The capability-negotiation outcome of a consumer reading an artifact's profile. */
+type Compatibility = 
+/** Authored at-or-below the consumer's profile (same name + major) — decode fully. */
+{
+    readonly kind: 'Current';
+}
+/**
+ * Authored *ahead* of the consumer (same name + major, higher minor) — the
+ * consumer may meet kinds it does not understand; it must tolerate (preserve +
+ * degrade), never crash.
+ */
+ | {
+    readonly kind: 'Behind';
+    readonly authored: Profile;
+}
+/**
+ * A different namespace or a different major — an incompatible `/vN/` boundary
+ * the consumer cannot interpret at all (hard-refuse, never silently mis-decode).
+ */
+ | {
+    readonly kind: 'Foreign';
+    readonly authored: Profile;
+};
+/**
+ * Negotiate a consumer's supported profile against an artifact's authored
+ * profile. Minor-ahead is `Behind` (tolerable); a different name or major is
+ * `Foreign` (refuse). Mirrors F# `Versioning.negotiate`.
+ */
+declare const negotiate: (consumer: Profile, authored: Profile) => Compatibility;
+/** The versioned-envelope payload key. `$`-prefixed so it sorts before data keys. */
+declare const PAYLOAD_KEY = "$payload";
+/** The versioned-envelope profile key. */
+declare const PROFILE_KEY = "$profile";
+/** The optional artifact-declares-its-required-profile key. */
+declare const REQUIRED_PROFILE_KEY = "requiredProfile";
+/**
+ * A versioning-layer failure. Extends the six canonical `DecodeErrorCode`s with
+ * two envelope-specific codes, kept OUT of the core `DecodeErrorCode` set (the
+ * six-code AI-recovery surface stays unpolluted — WIRE_FORMAT.md §6):
+ *   - `FOREIGN_PROFILE` — negotiate returned `Foreign`; the artifact is refused.
+ *   - `MALFORMED_PROFILE` — the `$profile` value is not a `<name>@<major>.<minor>`.
+ */
+type EnvelopeErrorCode = DecodeErrorCode | 'FOREIGN_PROFILE' | 'MALFORMED_PROFILE';
+interface EnvelopeError {
+    readonly code: EnvelopeErrorCode;
+    readonly path: string;
+    readonly message: string;
+}
+/**
+ * A versioned wire envelope: the producer's authored `profile` + the artifact
+ * `payload` (a `Node` / `TreeOp` as the verbatim parsed AST). `$profile` /
+ * `$payload` sort before any lower-case data key under the canonical key order,
+ * so an enveloped fixture is byte-stable. Mirrors F# `Versioning.Envelope`.
+ */
+interface Envelope {
+    readonly profile: Profile;
+    readonly payload: JsonAst;
+}
+/** Render an envelope to canonical wire bytes. */
+declare const encodeEnvelope: (env: Envelope) => string;
+/**
+ * Decode an envelope from an already-parsed AST — reads `$profile` (parsed) +
+ * the verbatim `$payload`. A missing / non-string / malformed `$profile`, or a
+ * missing `$payload`, is a structured `EnvelopeError`.
+ */
+declare const decodeEnvelopeAst: (ast: JsonAst) => Result<Envelope, EnvelopeError>;
+/** Parse + decode an envelope from wire bytes. */
+declare const decodeEnvelope: (json: string) => Result<Envelope, EnvelopeError>;
+/**
+ * A kind the consumer does not understand, captured on the decode boundary.
+ * **Transport-only**: reachable here and nowhere on the authoring/encode path —
+ * no host can construct one to emit. `payload` is the *verbatim parsed AST*, so
+ * re-rendering it reproduces the producer's bytes (must-ignore-but-preserve);
+ * `requiredProfile` is the profile the artifact declared it needs (when a
+ * well-formed one was present), so the consumer can name what it is missing in a
+ * degraded placeholder. Mirrors F# `Versioning.UnknownKind`.
+ */
+interface UnknownKind {
+    readonly kind: string;
+    readonly payload: JsonAst;
+    readonly requiredProfile?: Profile;
+}
+/** The result of a tolerant decode: a fully-understood `T`, or a preserved `Unknown`. */
+type Decoded<T> = {
+    readonly known: true;
+    readonly value: T;
+} | {
+    readonly known: false;
+    readonly unknown: UnknownKind;
+};
+/**
+ * Tolerantly decode one artifact AST. `tagOf` reads its discriminator; `isKnown`
+ * reports whether this consumer understands that tag; `decodeKnown` decodes a
+ * known one. An *unrecognised* tag is NOT an error — it becomes a transport-only
+ * `Unknown` carrying the verbatim parsed `payload` and any declared
+ * `requiredProfile`. A genuinely malformed object (no discriminator at all)
+ * still fails via `tagOf`. Mirrors F# `Versioning.decodeTolerant`.
+ */
+declare const decodeTolerant: <T>(tagOf: (ast: JsonAst) => Result<string, EnvelopeError>, isKnown: (tag: string) => boolean, decodeKnown: (ast: JsonAst) => Result<T, EnvelopeError>, ast: JsonAst) => Result<Decoded<T>, EnvelopeError>;
+/**
+ * Re-encode a tolerant decode back to canonical wire bytes. The `Unknown` branch
+ * re-renders its preserved `payload` **verbatim** (must-ignore-but-preserve);
+ * the `Known` branch re-encodes through the real node encoder. Composed with the
+ * canonical renderer's deterministic key order, an unknown artifact round-trips
+ * byte-for-byte. Mirrors F# `Versioning.reencode` (specialised to `Node`).
+ */
+declare const reencodeNode: (d: Decoded<Node<unknown>>) => string;
+/**
+ * Tolerantly decode a bare (un-enveloped) `Node` wire form. A known kind decodes
+ * normally; an unknown top-level kind becomes a transport-only `Unknown` whose
+ * bytes round-trip verbatim through `reencodeNode` — a minor-ahead artifact no
+ * longer throws `WRONG_NODE_KIND` / `UNKNOWN_DU_CASE`. A genuinely malformed
+ * object (no `kind.$type`) still fails.
+ */
+declare const decodeNodeTolerant: (json: string) => Result<Decoded<Node<unknown>>, EnvelopeError>;
+/**
+ * The consumer entry point for reading a possibly-versioned `Node` artifact
+ * safely. Decodes the `$profile` / `$payload` envelope, negotiates the authored
+ * profile against `consumer`, and:
+ *   - **Foreign** → refuses with `FOREIGN_PROFILE` (never silently mis-decodes);
+ *   - **Current / Behind** → tolerantly decodes the payload (unknown kinds
+ *     preserved) and returns the whole envelope re-encoded to canonical bytes.
+ *
+ * The re-encode is byte-identical to a canonical input (must-ignore-but-preserve
+ * keeps an unknown-kind payload verbatim), which is exactly what the
+ * `envelope-round-trip` corpus family asserts and the `envelope-reject` family
+ * asserts the `FOREIGN_PROFILE` refusal for.
+ */
+declare const negotiateEnvelope: (json: string, consumer?: Profile) => Result<string, EnvelopeError>;
+
+/** The envelope format-version tag key (`$`-prefixed, reserved per §2.1). */
+declare const ELICITATION_KEY = "$elicitation";
+/** The envelope format version this codec produces and accepts. */
+declare const ELICITATION_VERSION = "1";
+/**
+ * The elicitation error surface: the six §6 codes plus the §18.5 codes, kept
+ * OUT of the core `DecodeErrorCode` set (same posture as §15's
+ * `FOREIGN_PROFILE`).
+ */
+type ElicitationErrorCode = DecodeErrorCode | 'UNSUPPORTED_VERSION' | 'UNDECLARED_FIELD' | 'CONTRACT_EMPTY' | 'CONTRACT_DUPLICATE_FIELD' | 'CONTRACT_UNKNOWN_NODE' | 'ANSWER_MISSING_FIELD' | 'ANSWER_UNDECLARED_FIELD' | 'ANSWER_TYPE_MISMATCH' | 'ANSWER_OUT_OF_SPACE' | 'DEFAULT_NONCONFORMANT';
+interface ElicitationError {
+    readonly code: ElicitationErrorCode;
+    readonly path: string;
+    readonly message: string;
+}
+/**
+ * A value space — the platform's established `$type`-tagged space vocabulary
+ * (the same wire shape the capability codec uses). `min`/`max` inclusive;
+ * `anyString` is the only unbounded space.
+ */
+type AnswerSpace = {
+    readonly kind: 'intRange';
+    readonly min: number;
+    readonly max: number;
+} | {
+    readonly kind: 'floatRange';
+    readonly min: number;
+    readonly max: number;
+} | {
+    readonly kind: 'stringLen';
+    readonly min: number;
+    readonly max: number;
+} | {
+    readonly kind: 'enum';
+    readonly values: readonly string[];
+} | {
+    readonly kind: 'anyString';
+};
+/** One declared answer field (§18.1). */
+interface AnswerField {
+    /** The key this field's value takes in the answer object. */
+    readonly name: string;
+    /** The id of the NODE whose committed state carries the value. */
+    readonly nodeId: string;
+    /** The state key the node's binding writes the value under. */
+    readonly stateKey: string;
+    readonly space: AnswerSpace;
+    readonly required: boolean;
+}
+/** The declared answer contract — non-empty on the wire (`CONTRACT_EMPTY`). */
+interface AnswerContract {
+    readonly fields: readonly AnswerField[];
+}
+/** A typed answer value — the JSON scalar shapes a space ranges over. */
+type AnswerValue = string | number;
+/** An answer object: declared field names → scalar values. */
+type Answer = ReadonlyMap<string, AnswerValue>;
+/** The elicitation envelope (§18.1). */
+interface ElicitationEnvelope {
+    readonly id: string;
+    readonly tree: Node<unknown>;
+    readonly contract: AnswerContract;
+    /** Milliseconds, ≥ 1. DATA only — the presenting host's clock acts on it. */
+    readonly timeoutMs?: number;
+    /** A proposed answer; must itself conform to the contract. */
+    readonly defaultAnswer?: Answer;
+}
+/** The closed outcome set (§18.3). */
+type ElicitationOutcome = {
+    readonly kind: 'Answered';
+    readonly answer: Answer;
+} | {
+    readonly kind: 'Declined';
+} | {
+    readonly kind: 'TimedOut';
+} | {
+    readonly kind: 'Superseded';
+    readonly by?: string;
+};
+/** An outcome on the wire, correlated to its elicitation by id. */
+interface ElicitationOutcomeEnvelope {
+    readonly elicitationId: string;
+    readonly outcome: ElicitationOutcome;
+}
+/**
+ * Validate a typed answer against `contract`, reporting at `basePath`.
+ * Deterministic fail-fast order: (1) undeclared keys, in Ordinal key order;
+ * (2) per contract field, in declaration order — missing-required, then
+ * JSON-type-vs-space, then in-space.
+ */
+declare const validateAnswerAt: (basePath: string, contract: AnswerContract, answer: Answer) => Result<undefined, ElicitationError>;
+/**
+ * Validate an answer at the standard `$.answer` root — the gate a resolution
+ * host runs before an `Answered` outcome reaches the asking agent.
+ */
+declare const validateAnswer: (contract: AnswerContract, answer: Answer) => Result<undefined, ElicitationError>;
+/**
+ * Encode an elicitation envelope to canonical wire bytes. Fails only when the
+ * tree is not wire-representable.
+ */
+declare const encodeElicitation: (env: ElicitationEnvelope) => Result<string, ElicitationError>;
+/**
+ * Decode + validate an elicitation envelope (fail-fast, §18.4 order): stray
+ * keys → version tag → id → tree (standard node decode, errors re-rooted
+ * under `$.tree`) → contract (structure, duplicates, node membership) →
+ * timeoutMs → default conformance.
+ */
+declare const decodeElicitation: (json: string) => Result<ElicitationEnvelope, ElicitationError>;
+/** Encode an outcome to canonical wire bytes. Total — no embedded tree. */
+declare const encodeElicitationOutcome: (env: ElicitationOutcomeEnvelope) => string;
+/**
+ * Decode an outcome envelope. Contract conformance of an `Answered` answer is
+ * NOT checked here (the outcome does not carry the contract) — a resolution
+ * host pairs the outcome with its pending elicitation and runs
+ * `validateAnswer` before the answer reaches the asking agent (§18.4).
+ */
+declare const decodeElicitationOutcome: (json: string) => Result<ElicitationOutcomeEnvelope, ElicitationError>;
+/**
+ * Validate a `{"answer": {…}, "contract": {…}}` conformance document — the
+ * operation the `elicitation-answer-accept` / `elicitation-answer-reject`
+ * corpus families drive. The document carries no tree, so the
+ * `CONTRACT_UNKNOWN_NODE` probe does not apply here.
+ */
+declare const validateAnswerDocument: (json: string) => Result<undefined, ElicitationError>;
+
+export { type Answer, type AnswerContract, type AnswerField, type AnswerSpace, type AnswerValue, type ApplyError, type ApplyErrorCode, type ApplyResult, type Compatibility, type DagOpRecord, type DagResultEnvelope, type DecodeError, type DecodeErrorCode, type Decoded, ELICITATION_KEY, ELICITATION_VERSION, type ElicitationEnvelope, type ElicitationError, type ElicitationErrorCode, type ElicitationOutcome, type ElicitationOutcomeEnvelope, type Envelope, type EnvelopeError, type EnvelopeErrorCode, type EvalEnv, type JsonAst, type MergeConflict, type MergeResult, type OpApplyTelemetryRecord, PAYLOAD_KEY, PROFILE_KEY, type ParseError, type Profile, REQUIRED_PROFILE_KEY, type SourceResolver, type TreeOp, type UnknownKind, apply, cellString, coerce, coreV1, decodeDagRecord, decodeElicitation, decodeElicitationOutcome, decodeEnvelope, decodeEnvelopeAst, decodeNode, decodeNodeTolerant, decodeOp, decodeTolerant, encodeCell, encodeColExpr, encodeDagRecord, encodeDataSource, encodeElicitation, encodeElicitationOutcome, encodeEnvelope, encodeNode, encodeOp, encodePipeline, evalErrorString, evalPipeline, evalPipelineInEnv, evalPipelineWith, evalPipelineWithInEnv, evalSource, field as jsonField, merge3Way, negotiate, negotiateEnvelope, noResolve, parse, pipelineParams, reencodeNode, renderAstCanonical, renderProfile, stepParams, tryParseProfile, validateAnswer, validateAnswerAt, validateAnswerDocument };