@thomasfosterau/pulpit 0.0.0 → 0.1.0

package/dist/version-chain.d.ts

@@ -0,0 +1,702 @@
+/**
+ * **The node / version chain discipline** — create, append, tombstone,
+ * restore, history and field-level compare over an append-only chain,
+ * generic in the leaf.
+ *
+ * Every node carries an append-only chain of `(version, action, timestamp,
+ * actor)` rows (`READ-009` / `PUB-003`): each edit appends a row rather than
+ * rewriting in place, and "repointing the current version" is nothing but
+ * that append — the current version is the chain's maximum, resolved by the
+ * current-version view. The behavioural spec is gardeneria's
+ * `packages/database/src/nodes.ts` (`createNodeE` / `updateNodeE` /
+ * `deleteNodeE`), the leaf-chain half of `apps/api/src/operations/subtype.ts`
+ * (`defineVersionOpsE`, the merge / carry-forward writers) and
+ * `version-history.ts`; a `#NNN` here names a gardeneria issue.
+ *
+ * ## The invariants
+ *
+ * - **Append-only** (`VERSION-CHAIN-001/002`). Every write lands at
+ *   `N_max + 1`; no existing version row is ever updated, deleted or
+ *   reordered. A restore is a new version whose content came from history.
+ *   The one exception is erasure (`./purge`), which deletes a node's whole
+ *   chain, never part of one.
+ * - **Create is never an upsert.** A caller-supplied id that already belongs
+ *   to a node fails {@link NodeAlreadyExists} (F-OP-02) rather than minting a
+ *   version onto it.
+ * - **Update carries forward.** A patch is tri-state per column: a value
+ *   sets, `null` clears, an absent (or `undefined`) key carries the previous
+ *   version's value forward. Never `input.x ?? null`.
+ * - **Delete is a tombstone that carries the state forward**, so a `delete`
+ *   version is itself a complete snapshot — which is what makes restoring
+ *   *from* a tombstone possible. It is idempotent: on an already tombstoned
+ *   node it returns the existing tombstone and writes nothing.
+ * - **A plain update never resurrects** (`VERSION-CHAIN-006`). Over a
+ *   tombstone it fails {@link NodeNotFound}; only the explicit `restore` and
+ *   `restoreVersion` write over one.
+ * - **No partial restore.** `restoreVersion` reads the whole snapshot first
+ *   and fails {@link VersionNotFound} when any level of the chain has no row
+ *   at that version — before anything is written.
+ * - **Every chain read is bounded** (`PERF-DB-001`): `history` takes a
+ *   `limit`, capped at {@link MAX_HISTORY_LIMIT}.
+ * - **An expected version is a precondition on the append.** A write to an
+ *   existing node (`update`, `restore`, `delete`, `restoreVersion`) may
+ *   carry the head version its caller last read ({@link Precondition}); a
+ *   head that has moved fails {@link StaleVersion} and nothing is written.
+ *   It is checked against the very head the append extends, and the append
+ *   lands at that head + 1, so a writer that slips in between the read and
+ *   the append takes the `(id, version)` key first and this one fails
+ *   {@link VersionConflict}: the store's primary key is what makes the check
+ *   atomic. Without one, a write extends whatever the head is (last writer
+ *   wins on a column two patches both set).
+ *
+ * ## The seam
+ *
+ * The chain is read and written through a {@link VersionChainStore} the
+ * application supplies — in production, a Drizzle store over
+ * effect-drizzle-ext's `./versioned-chain` tables and views, which is not yet
+ * published (see the package README → Seams for the expected table shape).
+ * The operations here own the discipline; the store owns persistence
+ * and nothing else. Authorisation is not this module's concern either: the
+ * subtype factory (`./subtype`) gates before it calls in.
+ *
+ * @copyright Thomas Foster
+ * @module pulpit/version-chain
+ * @since 0.1.0
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+/**
+ * What one version row recorded: the create, an edit (restores included), or a tombstone.
+ *
+ * @since 0.1.0
+ */
+export declare const VersionAction: Schema.Literals<readonly ["create", "update", "delete"]>;
+/**
+ * The {@link VersionAction} literal union: `"create" | "update" | "delete"`.
+ *
+ * @since 0.1.0
+ */
+export type VersionAction = typeof VersionAction.Type;
+/**
+ * One column's value in a leaf's state: a JSON value, or one of the two
+ * non-JSON scalars a Drizzle row carries (`Date` for timestamps, `bigint` for
+ * `bigint` columns). A content-addressed document is carried as its
+ * `DocumentHash` (`./documents`' `documentRef`), never as a copy; a document
+ * a leaf keeps inline is its parsed JSON.
+ *
+ * @since 0.1.0
+ */
+export type ColumnValue = Schema.Json | Date | bigint;
+/**
+ * A leaf's domain state at one version: every column of every level of its
+ * chain, keyed by column name (the leaf-most level wins on a shared name).
+ * Generated columns (a `search_vector`) are not part of it — they regenerate.
+ *
+ * @since 0.1.0
+ */
+export type ChainState = {
+    readonly [column: string]: ColumnValue;
+};
+/**
+ * A tri-state patch over a {@link ChainState}: a value sets, `null` clears,
+ * an absent or `undefined` key carries the previous version's value forward.
+ *
+ * @since 0.1.0
+ */
+export type ChainPatch = {
+    readonly [column: string]: ColumnValue | undefined;
+};
+/**
+ * A localised leaf's locale level at one version (pulpit#56, model (b)): each
+ * locale the version carries, keyed by its tag (`"en"`, `"fr-CA"`), and that
+ * locale's translated columns. The node's shared (untranslated) columns stay
+ * in its {@link ChainState}; a translated column lives here only. A store
+ * keeps it as the locale level's fact rows, keyed `(id, version, locale)`.
+ * A version that carries no locale has none; an absent `locales` and `{}`
+ * mean the same.
+ *
+ * @since 0.1.0
+ */
+export type LocaleStates = {
+    readonly [locale: string]: ChainState;
+};
+/**
+ * A tri-state patch over a {@link LocaleStates}, per locale: a
+ * {@link ChainPatch} updates that locale's columns (starting from none for a
+ * locale the version did not carry), `null` drops the locale, and an absent
+ * or `undefined` key carries it forward unchanged.
+ *
+ * @since 0.1.0
+ */
+export type LocalePatch = {
+    readonly [locale: string]: ChainPatch | null | undefined;
+};
+/**
+ * One entry in a node's append-only version chain.
+ *
+ * @since 0.1.0
+ */
+export interface VersionChainEntry {
+    /** The version number (0 is the create). */
+    readonly version: bigint;
+    /** The edit action this version recorded. */
+    readonly action: VersionAction;
+    /** When the version was written. */
+    readonly timestamp: Date;
+}
+/**
+ * One version's reconstructed state, for the edits (browse / compare) surface.
+ *
+ * @since 0.1.0
+ */
+export interface VersionSnapshot extends VersionChainEntry {
+    /** The shared (untranslated) columns, or every column of a leaf with no locale level. */
+    readonly state: ChainState;
+    /**
+     * A localised leaf's locale level at this version (pulpit#56); absent, the
+     * version carries no locale. A store reconstructs it with the rest of the
+     * snapshot, or reports the version absent.
+     */
+    readonly locales?: LocaleStates | undefined;
+}
+/**
+ * The row a write appends: the entry, the node's leaf type, the acting account, the full state.
+ *
+ * @since 0.1.0
+ */
+export interface VersionRow extends VersionSnapshot {
+    readonly id: string;
+    /** The concrete leaf's wire type, threaded onto the node row at version 0 (#864 S3). */
+    readonly type: string;
+    /** The acting account (#1581) — recorded on the version row, never inferred. */
+    readonly actorId: Option.Option<string>;
+    /**
+     * The contributor whose accepted proposal this version applies
+     * (`./proposals`), recorded beside the actor, who is the account that
+     * accepted it; none for every other write. A store persists it with the
+     * version row (README → Seams → `VersionChainStore`).
+     */
+    readonly proposedBy: Option.Option<string>;
+}
+/**
+ * What a chain write returns: the node and the version it landed at.
+ *
+ * @since 0.1.0
+ */
+export interface ChainWrite {
+    readonly id: string;
+    readonly version: bigint;
+}
+declare const NodeNotFound_base: Schema.Class<NodeNotFound, Schema.TaggedStruct<"NodeNotFound", {
+    readonly type: Schema.String;
+    readonly id: Schema.String;
+}>, import("effect/Cause").YieldableError & {
+    readonly brand: unique symbol;
+}>;
+/**
+ * No such node, or (for a plain update) a tombstoned one: the wire's 404.
+ *
+ * @since 0.1.0
+ */
+export declare class NodeNotFound extends NodeNotFound_base {
+}
+declare const VersionNotFound_base: Schema.Class<VersionNotFound, Schema.TaggedStruct<"VersionNotFound", {
+    readonly type: Schema.String;
+    readonly id: Schema.String;
+    readonly version: Schema.BigInt;
+}>, import("effect/Cause").YieldableError & {
+    readonly brand: unique symbol;
+}>;
+/**
+ * No reconstructable version at `(id, version)`: an unknown version, or a partial chain.
+ *
+ * @since 0.1.0
+ */
+export declare class VersionNotFound extends VersionNotFound_base {
+}
+declare const NodeAlreadyExists_base: Schema.Class<NodeAlreadyExists, Schema.TaggedStruct<"NodeAlreadyExists", {
+    readonly type: Schema.String;
+    readonly id: Schema.String;
+}>, import("effect/Cause").YieldableError & {
+    readonly brand: unique symbol;
+}>;
+/**
+ * A create whose caller-supplied id already belongs to a node — never an upsert: the wire's 409.
+ *
+ * @since 0.1.0
+ */
+export declare class NodeAlreadyExists extends NodeAlreadyExists_base {
+}
+declare const VersionConflict_base: Schema.Class<VersionConflict, Schema.TaggedStruct<"VersionConflict", {
+    readonly id: Schema.String;
+    readonly version: Schema.BigInt;
+}>, import("effect/Cause").YieldableError & {
+    readonly brand: unique symbol;
+}>;
+/**
+ * The store refused an append because `(id, version)` is already taken — a
+ * concurrent writer got there first. Raised by the store (the `(id, version)`
+ * primary key is what enforces append-only under concurrency); never retried
+ * here, because a retry would silently base the write on a version the
+ * caller never read.
+ *
+ * @since 0.1.0
+ */
+export declare class VersionConflict extends VersionConflict_base {
+}
+declare const StaleVersion_base: Schema.Class<StaleVersion, Schema.TaggedStruct<"StaleVersion", {
+    readonly type: Schema.String;
+    readonly id: Schema.String;
+    /** The version the caller expected the head to be. */
+    readonly expected: Schema.BigInt;
+    /** The head version the write found. */
+    readonly current: Schema.BigInt;
+}>, import("effect/Cause").YieldableError & {
+    readonly brand: unique symbol;
+}>;
+/**
+ * An expected-version precondition that no longer holds: the head moved past
+ * the version the caller last read, so the write would have overwritten an
+ * edit the caller never saw. Nothing was written. Carries the head the write
+ * would have extended (`current`), so the caller can re-read and re-apply;
+ * the wire's 412 (a failed `If-Match`) or 409.
+ *
+ * A writer that passes the check but loses the race to the append fails
+ * {@link VersionConflict} instead: the same stale read, caught one step later
+ * by the store's key.
+ *
+ * @since 0.1.0
+ */
+export declare class StaleVersion extends StaleVersion_base {
+}
+declare const BrokenChain_base: Schema.Class<BrokenChain, Schema.TaggedStruct<"BrokenChain", {
+    readonly type: Schema.String;
+    readonly id: Schema.String;
+    readonly version: Schema.BigInt;
+}>, import("effect/Cause").YieldableError & {
+    readonly brand: unique symbol;
+}>;
+/**
+ * The chain's head version has no reconstructable state — the store broke its
+ * own contract (a head it reports must be readable). A defect, never a typed
+ * failure: there is nothing a caller could do about it.
+ *
+ * @since 0.1.0
+ */
+export declare class BrokenChain extends BrokenChain_base {
+}
+/**
+ * The persistence seam the chain operations run over. `E` is the store's own
+ * failure (a Drizzle store's `EffectDrizzleQueryError`); `R` its requirements
+ * (a Drizzle store's `CurrentTransaction` — the operations never open a
+ * transaction themselves: `transact` is always-open and the boundary belongs
+ * to the caller, website #1883).
+ *
+ * Every method reads or writes exactly what it says and applies no policy.
+ *
+ * @since 0.1.0
+ */
+export interface VersionChainStore<E, R> {
+    /** The node's latest version entry, or none for an id with no versions. */
+    readonly head: (id: string) => Effect.Effect<Option.Option<VersionChainEntry>, E, R>;
+    /**
+     * The full state at `(id, version)`, or none when the version does not
+     * exist OR any level of the chain has no row there — a version that cannot
+     * be fully reconstructed is reported as absent, never as a partial state.
+     * On a localised leaf the snapshot carries its locale level too: every
+     * `(id, version, locale)` fact row, as `locales` (pulpit#56).
+     */
+    readonly snapshot: (id: string, version: bigint) => Effect.Effect<Option.Option<VersionSnapshot>, E, R>;
+    /**
+     * Append one version row — at version 0 together with the node's identity
+     * row, and one locale-level row per locale `row.locales` carries. Fails {@link VersionConflict} when `(id, version)` already exists
+     * (at version 0: the id already belongs to a node).
+     */
+    readonly append: (row: VersionRow) => Effect.Effect<void, E | VersionConflict, R>;
+    /** The chain's entries, oldest first, at most `limit` of them. */
+    readonly entries: (id: string, limit: number) => Effect.Effect<ReadonlyArray<VersionChainEntry>, E, R>;
+    /** Mint a fresh node id (a UUID) when the caller supplies none. */
+    readonly mintId: Effect.Effect<string, E, R>;
+}
+/**
+ * The hard cap on a history read (`PERF-DB-001`): a chain is tiny in practice; this bounds a pathological one.
+ *
+ * @since 0.1.0
+ */
+export declare const MAX_HISTORY_LIMIT = 1000;
+/**
+ * Apply a tri-state patch to a state: a value sets, `null` clears, `undefined` carries forward.
+ *
+ * @since 0.1.0
+ */
+export declare const applyPatch: (state: ChainState, patch: ChainPatch) => {
+    [x: string]: ColumnValue;
+};
+/**
+ * Apply a {@link LocalePatch} to a locale level: a patch updates its locale
+ * (from nothing for a locale `locales` lacks) with {@link applyPatch}, `null`
+ * drops the locale, `undefined` carries it forward. Pure and total.
+ *
+ * @example
+ * ```ts
+ * import { deepStrictEqual } from "node:assert";
+ * import { applyLocalePatch } from "@thomasfosterau/pulpit/version-chain";
+ *
+ * const before = { en: { title: "Hello" }, fr: { title: "Bonjour" } };
+ * deepStrictEqual(applyLocalePatch(before, { en: { title: "Hi" }, fr: null, de: { title: "Hallo" } }), {
+ *   en: { title: "Hi" },
+ *   de: { title: "Hallo" },
+ * });
+ * ```
+ *
+ * @since 0.1.0
+ */
+export declare const applyLocalePatch: (locales: LocaleStates, patch: LocalePatch) => LocaleStates;
+/**
+ * The locale level a snapshot carries, `{}` for none.
+ *
+ * @since 0.1.0
+ */
+export declare const localesOf: (snapshot: Pick<VersionSnapshot, "locales">) => LocaleStates;
+/**
+ * How one column differs between two states, read from the first state to
+ * the second: `added` (absent before, present after), `removed` (present
+ * before, absent after) or `changed` (present on both sides, structurally
+ * unequal). A `null` is a present value: a column cleared to `null` is
+ * `changed`, never `removed`, and a column absent from a state is a column
+ * that state does not have, not one it cleared.
+ *
+ * @since 0.1.0
+ */
+export type AttributeChange = {
+    readonly _tag: "added";
+    readonly after: ColumnValue;
+} | {
+    readonly _tag: "removed";
+    readonly before: ColumnValue;
+} | {
+    readonly _tag: "changed";
+    readonly before: ColumnValue;
+    readonly after: ColumnValue;
+};
+/**
+ * The field-level change set between two states, keyed by column: one
+ * {@link AttributeChange} per column that differs. An unchanged column has
+ * no key, so two equal states diff to `{}`.
+ *
+ * @since 0.1.0
+ */
+export type StateDiff = {
+    readonly [column: string]: AttributeChange;
+};
+/**
+ * The field-level change set from state `from` to state `to`: every column
+ * that is added, removed or changed, with its before and after values;
+ * unchanged columns are omitted. Pure and total, with no error channel.
+ *
+ * Presence is read per key, so the tri-state distinction survives: a column
+ * holding `null` is present (a clear), and only a column with no key is
+ * absent. Values compare structurally with `Equal.equals`: JSON objects and
+ * arrays by content (key order ignored), a `Date` by its instant, a `bigint`
+ * by value, and a `Date` never equals the string of its instant. A
+ * content-addressed document is held as its `DocumentHash`, so it compares by
+ * hash: changed or unchanged, never a textual diff, which is the UI's job.
+ *
+ * The diff is directed: swapping the arguments swaps `added` and `removed`
+ * and each change's `before` and `after`. A state's values are compared as
+ * immutable (Effect caches structural hashes), as a {@link ChainState} is.
+ *
+ * @since 0.1.0
+ */
+export declare const diffStates: (from: ChainState, to: ChainState) => StateDiff;
+/**
+ * How one locale differs between two versions' locale levels, read from the
+ * first to the second: `added` (the second carries it, the first did not,
+ * with its columns), `removed` (the reverse) or `changed` (both carry it, and
+ * its columns differ: their {@link StateDiff}).
+ *
+ * @since 0.1.0
+ */
+export type LocaleChange = {
+    readonly _tag: "added";
+    readonly after: ChainState;
+} | {
+    readonly _tag: "removed";
+    readonly before: ChainState;
+} | {
+    readonly _tag: "changed";
+    readonly changes: StateDiff;
+};
+/**
+ * The per-locale change set between two locale levels, keyed by locale: one
+ * {@link LocaleChange} per locale that differs. An unchanged locale has no
+ * key.
+ *
+ * @since 0.1.0
+ */
+export type LocaleDiff = {
+    readonly [locale: string]: LocaleChange;
+};
+/**
+ * The per-locale change set from locale level `from` to locale level `to`
+ * (pulpit#56): every locale added, removed, or whose columns changed by
+ * {@link diffStates}; an unchanged locale is omitted. Pure and total.
+ *
+ * @example
+ * ```ts
+ * import { deepStrictEqual } from "node:assert";
+ * import { diffLocales } from "@thomasfosterau/pulpit/version-chain";
+ *
+ * deepStrictEqual(
+ *   diffLocales({ en: { title: "Hello" }, fr: { title: "Bonjour" } }, { en: { title: "Hi" }, de: { title: "Hallo" } }),
+ *   {
+ *     en: { _tag: "changed", changes: { title: { _tag: "changed", before: "Hello", after: "Hi" } } },
+ *     fr: { _tag: "removed", before: { title: "Bonjour" } },
+ *     de: { _tag: "added", after: { title: "Hallo" } },
+ *   },
+ * );
+ * ```
+ *
+ * @since 0.1.0
+ */
+export declare const diffLocales: (from: LocaleStates, to: LocaleStates) => LocaleDiff;
+/**
+ * What {@link VersionChainOps.compare} returns: both versions as read
+ * (entry and full state) and the {@link StateDiff} from the first to the
+ * second.
+ *
+ * A tombstone is not an attribute: it is the version's `action`, so it shows
+ * as `from.action` / `to.action` being `"delete"` and never as a key in
+ * `changes`. A tombstone carries its state forward, so a version compared
+ * with the tombstone that followed it has no changes; a history view labels
+ * the version deleted from its action and lists only what the content did.
+ *
+ * @since 0.1.0
+ */
+export interface VersionComparison {
+    /** The version compared from, with its state. */
+    readonly from: VersionSnapshot;
+    /** The version compared to, with its state. */
+    readonly to: VersionSnapshot;
+    /** `diffStates(from.state, to.state)`: the shared columns. */
+    readonly changes: StateDiff;
+    /**
+     * `diffLocales` over the two versions' locale levels (pulpit#56): the
+     * per-locale changes, `{}` for a leaf with no locale level. Kept beside
+     * `changes` rather than inside it, since a column may itself be named
+     * `locales`.
+     */
+    readonly locales: LocaleDiff;
+}
+/**
+ * The input to {@link VersionChainOps.create}: the node id, the leaf's
+ * initial state, the acting account.
+ *
+ * @since 0.1.0
+ */
+export interface CreateInput {
+    /** A caller-supplied node id (client-generated ids); minted by the store when absent. */
+    readonly id: Option.Option<string>;
+    /** The leaf's full state at version 0: its shared columns, on a localised leaf. */
+    readonly state: ChainState;
+    /** A localised leaf's locale level at version 0 (pulpit#56); absent, none. */
+    readonly locales?: LocaleStates | undefined;
+    /** The acting account, recorded on the version row; none for a write with no session behind it. */
+    readonly actorId: Option.Option<string>;
+}
+/**
+ * An optimistic-concurrency precondition on a write to an existing node: the
+ * head version the caller last read. Every write that extends a chain
+ * ({@link VersionChainOps.update}, {@link VersionChainOps.restore},
+ * {@link VersionChainOps.delete}, {@link VersionChainOps.restoreVersion})
+ * accepts one.
+ *
+ * @since 0.1.0
+ */
+export interface Precondition {
+    /**
+     * The head version the caller last read. When present, the write fails
+     * {@link StaleVersion}, writing nothing, unless the head it extends is
+     * exactly this version; absent (or `undefined`), the write extends whatever
+     * the head is.
+     */
+    readonly expectedVersion?: bigint | undefined;
+}
+/**
+ * The input to {@link VersionChainOps.update} and
+ * {@link VersionChainOps.restore}: the node, a tri-state patch, the acting
+ * account, and an optional expected version.
+ *
+ * @since 0.1.0
+ */
+export interface UpdateInput extends Precondition {
+    /** The node to append to. */
+    readonly id: string;
+    /**
+     * The tri-state patch over the current state: a value sets, `null` clears,
+     * an absent key carries forward.
+     */
+    readonly patch: ChainPatch;
+    /**
+     * A localised leaf's per-locale patch ({@link LocalePatch}, pulpit#56):
+     * absent, every locale carries forward. Even a write that touches one
+     * locale appends one version of the whole node.
+     */
+    readonly locales?: LocalePatch | undefined;
+    /** The acting account, recorded on the version row; none for a write with no session behind it. */
+    readonly actorId: Option.Option<string>;
+    /**
+     * The contributor whose proposal this edit applies, recorded on the
+     * version row as `proposedBy`; absent (or `undefined`) for an ordinary
+     * edit. `./proposals`' `accept` sets it.
+     */
+    readonly proposedBy?: Option.Option<string> | undefined;
+}
+/**
+ * The chain operations for one leaf type, bound to a store.
+ *
+ * @since 0.1.0
+ */
+export interface VersionChainOps<E, R> {
+    /** Insert the node and its version 0 (`create`). Fails {@link NodeAlreadyExists} on a taken id. */
+    readonly create: (input: CreateInput) => Effect.Effect<ChainWrite, E | NodeAlreadyExists | VersionConflict, R>;
+    /**
+     * Append an `update` version carrying the patch over the current state.
+     * Fails {@link NodeNotFound} for an unknown id and for a tombstoned node,
+     * and {@link StaleVersion} when `input.expectedVersion` is not the head.
+     */
+    readonly update: (input: UpdateInput) => Effect.Effect<ChainWrite, E | NodeNotFound | StaleVersion | VersionConflict, R>;
+    /**
+     * {@link update}, except a tombstone does not fail: the explicit restore
+     * surface (`VERSION-CHAIN-006`) — the node comes back live. Fails
+     * {@link NodeNotFound} for an unknown id and {@link StaleVersion} when
+     * `input.expectedVersion` is not the head.
+     */
+    readonly restore: (input: UpdateInput) => Effect.Effect<ChainWrite, E | NodeNotFound | StaleVersion | VersionConflict, R>;
+    /**
+     * Append a `delete` version carrying the state forward. Idempotent: on a
+     * tombstoned node it returns the existing tombstone with
+     * `alreadyDeleted: true` and writes nothing, whatever the precondition
+     * says (the delete it asked for has happened). Fails {@link NodeNotFound}
+     * for an unknown id and {@link StaleVersion} when a live node's head is
+     * not `precondition.expectedVersion`.
+     */
+    readonly delete: (id: string, actorId: Option.Option<string>, precondition?: Precondition) => Effect.Effect<ChainWrite & {
+        readonly alreadyDeleted: boolean;
+    }, E | NodeNotFound | StaleVersion | VersionConflict, R>;
+    /** The reconstructed state at `(id, version)`. Read-only. */
+    readonly getVersion: (id: string, version: bigint) => Effect.Effect<VersionSnapshot, E | VersionNotFound, R>;
+    /**
+     * The field-level change set from version `from` to version `to` of one
+     * node: two {@link VersionChainOps.getVersion} reads and {@link diffStates}.
+     * Read-only. Fails {@link VersionNotFound} for whichever version (`from`
+     * first) cannot be fully reconstructed. A tombstone on either side is that
+     * side's `action`, never an entry in `changes` (see
+     * {@link VersionComparison}). Ungated, like `getVersion`: `./subtype` gates
+     * history reads (`READ-009`), and its `SubtypeOps.compare` is this behind
+     * `getVersion`'s gate.
+     */
+    readonly compare: (id: string, from: bigint, to: bigint) => Effect.Effect<VersionComparison, E | VersionNotFound, R>;
+    /**
+     * Re-apply the full snapshot at `(id, version)` as a NEW `update` version —
+     * over a tombstone too. Fails {@link VersionNotFound}, before writing
+     * anything, when the version cannot be fully reconstructed, and
+     * {@link StaleVersion} when the head is not
+     * `precondition.expectedVersion` (the precondition is on the head the
+     * restore extends, not on the version it restores).
+     */
+    readonly restoreVersion: (id: string, version: bigint, actorId: Option.Option<string>, precondition?: Precondition) => Effect.Effect<ChainWrite, E | VersionNotFound | StaleVersion | VersionConflict, R>;
+    /**
+     * The chain, oldest first, at most `limit` entries (default and cap
+     * {@link MAX_HISTORY_LIMIT}). Fails {@link NodeNotFound} when the id has no
+     * versions, so a caller surfaces the 404 a missing resource would.
+     */
+    readonly history: (id: string, limit?: number) => Effect.Effect<ReadonlyArray<VersionChainEntry>, E | NodeNotFound, R>;
+}
+/**
+ * The write that is about to append: the chain's `action` vocabulary, with
+ * the two explicit restore surfaces named apart (`VERSION-CHAIN-006`), so a
+ * hook can tell a resurrection from an edit. `restore` and `restoreVersion`
+ * still append an `update` row. `publish` and `unpublish` are `./subtype`'s
+ * publication operations, which record a publication fact and append no
+ * version; the chain itself never emits them.
+ *
+ * @since 0.1.0
+ */
+export declare const WriteAction: Schema.Literals<readonly ["create", "update", "delete", "restore", "restoreVersion", "publish", "unpublish"]>;
+/**
+ * The {@link WriteAction} literal union.
+ *
+ * @since 0.1.0
+ */
+export type WriteAction = typeof WriteAction.Type;
+/**
+ * What a {@link ChainHooks.beforeAppend} hook is shown: the write, the node,
+ * the head it extends, and the patch it is about to apply.
+ *
+ * - `create` — `prior` is none, and `patch` is the whole initial state;
+ * - `update` / `restore` — `prior` is the head, `patch` the caller's tri-state patch;
+ * - `delete` — `prior` is the live head, `patch` is `{}` (the tombstone
+ *   carries the head's state forward); an already tombstoned node writes
+ *   nothing and runs no hook;
+ * - `restoreVersion` — `prior` is the head, `patch` the whole state of the
+ *   version being restored.
+ *
+ * The version written is the hook's patch applied to `prior`'s state (to
+ * nothing for `create` and `restoreVersion`, whose patch is the whole state).
+ *
+ * On a localised leaf (pulpit#56) `locales` is the write's locale patch, in
+ * the same reading: the whole locale level for `create` and
+ * `restoreVersion`, the caller's {@link LocalePatch} for `update` /
+ * `restore`, `{}` for `delete`. `beforeAppend`'s patch is the shared
+ * columns' alone; `beforeAppendLocales` returns the locale patch the write
+ * applies (see {@link ChainHooks}).
+ *
+ * @since 0.1.0
+ */
+export interface ChainAppendEvent {
+    readonly action: WriteAction;
+    readonly id: string;
+    /** The head the append extends (its full state), or none for a create. */
+    readonly prior: Option.Option<VersionSnapshot>;
+    readonly patch: ChainPatch;
+    /** The write's locale patch (see above); absent or `{}`, every locale carries forward. */
+    readonly locales?: LocalePatch | undefined;
+    /** The acting account the row will record. */
+    readonly actorId: Option.Option<string>;
+}
+/**
+ * The chain's hook point, bound once by {@link defineVersionChain}.
+ *
+ * @since 0.1.0
+ */
+export interface ChainHooks<E, R> {
+    /**
+     * Runs after the head is read and before the row is appended, in the
+     * caller's transaction: its patch replaces the event's, and a failure
+     * (its `E`) fails the write with nothing appended. It sees the very head
+     * the append extends, so the expected-version check (`appendNext`) still
+     * runs against that head after it. Absent, nothing extra is read.
+     */
+    readonly beforeAppend?: ((event: ChainAppendEvent) => Effect.Effect<ChainPatch, E, R>) | undefined;
+    /**
+     * The locale level's counterpart of `beforeAppend` (pulpit#56): runs at the
+     * same point, shown the same event, and its {@link LocalePatch} replaces
+     * the event's `locales`, so a hook that validates or transforms a column
+     * does so in every locale too. Absent, the event's locale patch is applied
+     * as given.
+     */
+    readonly beforeAppendLocales?: ((event: ChainAppendEvent) => Effect.Effect<LocalePatch, E, R>) | undefined;
+}
+/**
+ * Bind the chain operations for one leaf `type` to a store. Every produced
+ * operation is traced as `${type}.<operation>`. `hooks.beforeAppend`, when
+ * given, runs before every append (see {@link ChainHooks}); its failure is
+ * each write's `E`.
+ *
+ * @since 0.1.0
+ */
+export declare const defineVersionChain: <E, R>(type: string, store: VersionChainStore<E, R>, hooks?: ChainHooks<E, R>) => VersionChainOps<E, R>;
+export {};
+//# sourceMappingURL=version-chain.d.ts.map