@voltro/plugin-row-history 0.52.0

package/dist/index.d.ts

@@ -0,0 +1,323 @@
+import { ColumnBuilder } from '@voltro/database';
+import { DataStore } from '@voltro/database';
+import { Effect } from 'effect';
+import { FieldDefinitions } from '@voltro/database';
+import { Table } from '@voltro/database';
+import { VoltroPlugin } from '@voltro/protocol';
+
+/** Adapt the framework DataStore to the pure HistoryStore. */
+export declare const dataStoreHistoryStore: (store: DataStore) => HistoryStore;
+
+/** Field-level delta between two row snapshots (key-order-insensitive). */
+export declare const diffSnapshots: (from: Record<string, unknown> | null, to: Record<string, unknown> | null) => Record<string, FieldChange>;
+
+/** Diff two version numbers out of a row's (already tenant-scoped) timeline.
+ *  `null` when either version is absent from `rows` — not recorded, pruned,
+ *  or hidden from the caller's tenant. */
+export declare const diffVersionRows: (rows: ReadonlyArray<VersionRow>, fromVersion: number, toVersion: number) => VersionDiff | null;
+
+/** Field-level delta between two versions of a row, tenant-scoped like
+ *  `rowHistory`. `null` when either version is absent from the caller's
+ *  visible timeline (never recorded, pruned, or another tenant's row). */
+export declare const diffVersions: (store: DataStore, tableName: string, rowId: string, tenantId: string | null, fromVersion: number, toVersion: number) => Promise<VersionDiff | null>;
+
+/** Effect-native `diffVersions` (see {@link rowHistoryEffect}). */
+export declare const diffVersionsEffect: (store: DataStore, tableName: string, rowId: string, tenantId: string | null, fromVersion: number, toVersion: number) => Effect.Effect<VersionDiff | null>;
+
+/** One field's before/after in a version diff. */
+export declare interface FieldChange {
+    readonly from: unknown;
+    readonly to: unknown;
+}
+
+/**
+ * Every row change made by ONE actor, newest first — the `bySubject` index's
+ * caller. `subjectId` is the CALLER (see the correlation bridge), not the row's
+ * `audit()` stamp, so this covers writes through the boot store that the stamp
+ * never named.
+ *
+ * `limit` is required and defaults to 100 on purpose: an actor's history is
+ * unbounded, and an entry point that returns all of it by default is one that
+ * gets called once in production and never again.
+ */
+export declare const historyBySubject: (store: DataStore, subjectId: string, tenantId: string | null | undefined, limit?: number) => Promise<ReadonlyArray<VersionRow>>;
+
+/** Effect-native `historyBySubject` (see {@link rowHistoryEffect}). */
+export declare const historyBySubjectEffect: (store: DataStore, subjectId: string, tenantId: string | null | undefined, limit?: number) => Effect.Effect<ReadonlyArray<VersionRow>>;
+
+/**
+ * Every row change made by ONE call — the audit join, entered from the trace.
+ *
+ * This is what the `byTrace` index is for, and without it the index had no
+ * caller: `rowHistory` requires you to already know which row you are asking
+ * about, which is exactly the wrong way round during an incident. Pair it with
+ * the `_voltro_audit_log` row carrying the same `traceId` to get "who called,
+ * what they were refused, and what they changed" in two reads.
+ *
+ * Tenant-scoped like `rowHistory`. Pass the caller's `tenantId`; `undefined`
+ * skips the filter and is for system/admin paths only.
+ */
+export declare const historyByTrace: (store: DataStore, traceId: string, tenantId: string | null | undefined) => Promise<ReadonlyArray<VersionRow>>;
+
+/** Effect-native `historyByTrace` (see {@link rowHistoryEffect}). */
+export declare const historyByTraceEffect: (store: DataStore, traceId: string, tenantId: string | null | undefined) => Effect.Effect<ReadonlyArray<VersionRow>>;
+
+/** The store surface versioning needs (adapts the framework DataStore).
+ *  `versionsOf`'s `tenantId` filter: pass the caller's tenant on the READ path
+ *  so a row's timeline is visible only to its own tenant (a `null`-tenant /
+ *  untenanted-source row stays visible to all). `maxVersion` is the write-path
+ *  read — it returns ONLY the highest version number recorded for a (table,
+ *  rowId), so a new version costs a `MAX(version)` aggregate instead of
+ *  materialising the whole timeline on every write (it sees every version,
+ *  unfiltered — a rowId is globally unique so all its versions share a tenant).
+ *  `prune` drops every version of a (table, rowId) BELOW `keepFrom` — the
+ *  per-row max-versions cap's delete path. */
+export declare interface HistoryStore {
+    readonly versionsOf: (tableName: string, rowId: string, tenantId?: string | null) => Promise<ReadonlyArray<VersionRow>>;
+    readonly maxVersion: (tableName: string, rowId: string) => Promise<number>;
+    readonly append: (row: VersionRow) => Promise<void>;
+    readonly prune: (tableName: string, rowId: string, keepFrom: number) => Promise<void>;
+}
+
+export declare const historyTable: Table<"_voltro_row_history", FieldDefinitions<{
+    readonly id: ColumnBuilder<string, "id", boolean>;
+    readonly tableName: ColumnBuilder<string, "text", boolean>;
+    readonly rowId: ColumnBuilder<string, "text", boolean>;
+    readonly version: ColumnBuilder<number, "integer", boolean>;
+    readonly op: ColumnBuilder<string, "text", boolean>;
+    readonly data: ColumnBuilder<unknown, "json", boolean>;
+    readonly changedBy: ColumnBuilder<string | null, "text", boolean>;
+    /**
+     * WHO changed it, SNAPSHOTTED — the counterpart to `data` above.
+     *
+     * The inconsistency this closes lives inside ONE row: `data` is a full-row
+     * snapshot, deliberately, so it survives what happens to the source; while
+     * `changedBy` is a reference that does not. One record, two philosophies —
+     * the row's state preserved forever, its author only until someone exercises
+     * a right to be forgotten, which `@voltro/plugin-governance`'s own
+     * `governance.erase` exists to grant.
+     *
+     * `{ id, type, displayName, email }` as of the change. Written by the audit
+     * plugin's resolver when both are installed; `null` otherwise, which is
+     * honest — a fabricated name would be the thing this column prevents.
+     */
+    readonly actor: ColumnBuilder<unknown, "json", boolean>;
+    /** The app's own scoping dimension — mirrors `_voltro_audit_log.scope`. A
+     *  per-team trail needs it on BOTH tables, or half the view filters. */
+    readonly scope: ColumnBuilder<unknown, "json", boolean>;
+    readonly changedAt: ColumnBuilder<Date, "timestamp", true>;
+    readonly tenantId: ColumnBuilder<string | null, "text", boolean>;
+    readonly traceId: ColumnBuilder<string | null, "text", boolean>;
+    readonly subjectId: ColumnBuilder<string | null, "text", boolean>;
+    readonly procedure: ColumnBuilder<string | null, "text", boolean>;
+}>, true, "byRow" | "byRowHistoryTrace" | "byRowHistorySubject">;
+
+/** In-memory history store (tests + dev). */
+export declare const memoryHistoryStore: () => HistoryStore & {
+    all: () => ReadonlyArray<VersionRow>;
+};
+
+/** Next version number given the rows already recorded for a (table, rowId). */
+export declare const nextVersionNumber: (existing: ReadonlyArray<VersionRow>) => number;
+
+/** Record one change event as a new version. Pure orchestration over the store. */
+export declare const recordChange: (store: HistoryStore, event: {
+    tableName: string;
+    rowId: string;
+    op: RowOp;
+    data: Record<string, unknown> | null;
+    changedBy: string | null;
+    now: number;
+    tenantId: string | null;
+    traceId?: string;
+    subjectId?: string | null;
+    procedure?: string;
+}, options?: RecordChangeOptions) => Promise<VersionRow>;
+
+export declare interface RecordChangeOptions {
+    /** Bounded retry budget for the read-MAX-then-insert version race (default 3).
+     *  Concurrent same-row writes on two replicas can compute the same version;
+     *  the derived unique PK makes the loser's INSERT fail — a retry re-reads
+     *  MAX(version) and re-appends instead of dropping the history record. */
+    readonly attempts?: number;
+    /** Keep at most this many versions per row: after a successful append,
+     *  versions older than `newest - maxVersions` are pruned. Unset → no cap. */
+    readonly maxVersions?: number;
+}
+
+/** Write the row's as-of snapshot back to the LIVE row (`store.update` by pk),
+ *  tenant-scoped like `rowAsOf` — a caller only restores what its tenant can
+ *  see. Returns the post-image, or `null` (and writes NOTHING) when the row
+ *  had no visible state at `at` (absent, deleted then, or cross-tenant). The
+ *  restore itself flows through the store, so the tap records it as a NEW
+ *  version — history stays append-only, a restore never rewrites the past. */
+export declare const restoreAsOf: (store: DataStore, tableName: string, rowId: string, tenantId: string | null, at: Date | number) => Promise<Record<string, unknown> | null>;
+
+/** Effect-native `restoreAsOf` (see {@link rowHistoryEffect}). */
+export declare const restoreAsOfEffect: (store: DataStore, tableName: string, rowId: string, tenantId: string | null, at: Date | number) => Effect.Effect<Record<string, unknown> | null>;
+
+/** The row's value as of a past instant (`null` if absent/deleted then),
+ *  tenant-scoped like `rowHistory`. */
+export declare const rowAsOf: (store: DataStore, tableName: string, rowId: string, tenantId: string | null, at: Date | number) => Promise<Record<string, unknown> | null>;
+
+/** Effect-native `rowAsOf` (see {@link rowHistoryEffect}). */
+export declare const rowAsOfEffect: (store: DataStore, tableName: string, rowId: string, tenantId: string | null, at: Date | number) => Effect.Effect<Record<string, unknown> | null>;
+
+/** Full version history for one row, oldest → newest, SCOPED to the caller's
+ *  tenant (pass `ctx.request.subject.tenantId`). A row's timeline is visible
+ *  only to its own tenant; `null`-tenant (untenanted-source) rows are visible
+ *  to all. Anonymous caller (`null`) sees only untenanted history. */
+export declare const rowHistory: (store: DataStore, tableName: string, rowId: string, tenantId: string | null) => Promise<ReadonlyArray<VersionRow>>;
+
+/** Effect-native `rowHistory` for handlers written in `Effect.gen` — same
+ *  tenant scoping, no `Effect.tryPromise` hand-wrap at the call site. */
+export declare const rowHistoryEffect: (store: DataStore, tableName: string, rowId: string, tenantId: string | null) => Effect.Effect<ReadonlyArray<VersionRow>>;
+
+export declare const rowHistoryPlugin: (options: RowHistoryPluginOptions) => VoltroPlugin;
+
+export declare interface RowHistoryPluginOptions {
+    /**
+     * Tables to version IN ADDITION to the default set — normally a PLUGIN's
+     * table, since those are excluded by default.
+     *
+     * Passed as table VALUES, not names. That is the whole point: the previous
+     * shape took `tables: string[]`, nothing cross-checked the strings, and a
+     * misspelled table silently recorded nothing forever. A value cannot be
+     * misspelled — `tsc` catches it at the call site.
+     */
+    readonly include?: ReadonlyArray<{
+        readonly tableName: string;
+    }>;
+    /**
+     * Tables to leave OUT of the default set. Same reasoning: values, not names.
+     *
+     * Reach for it on append-only or high-write tables of your own, where a full
+     * row snapshot per write buys nothing — the table already IS the history.
+     */
+    readonly exclude?: ReadonlyArray<{
+        readonly tableName: string;
+    }>;
+    /**
+     * Namespace for this plugin's surface. Default `row-history`.
+     *
+     * Set it when your app already publishes under that name — an exact tag
+     * collision is fatal at codegen, and this is the way out. Orthogonal to
+     * `name` below: `alias` REPLACES the namespace, `name` distinguishes two
+     * installations within it.
+     */
+    readonly alias?: string;
+    /**
+     * Discriminator for a SECOND installation of this plugin, when one app runs
+     * two (`@voltro/plugin-row-history#analytics`). Not a rename — for that use
+     * `alias`.
+     */
+    readonly name?: string;
+    /** Keep at most this many versions per row (>= 1): after each recorded
+     *  change, versions older than the newest N are pruned. Complements the
+     *  time-based retention sweep (`VOLTRO_ROW_HISTORY_TTL_HOURS`) — the sweep
+     *  bounds AGE, this bounds per-row COUNT. Unset → time-TTL only. */
+    readonly maxVersionsPerRow?: number;
+    /**
+     * WHEN the history row is written.
+     *
+     *   - `'post-commit'` (default) — off the change tap, after the domain write
+     *     has committed. Two separate writes.
+     *   - `'in-transaction'` — inside the SAME transaction as the domain write.
+     *
+     * **Why the default is not `'in-transaction'`.** Post-commit can lose an
+     * entry: between COMMIT and the forked write there is a window, and a process
+     * that dies inside it leaves the change permanent and the trail silent.
+     * In-transaction closes that — at the price of making this table a hard
+     * dependency of every write path it covers. A failed history insert then
+     * fails the user's mutation, and every covered write holds its locks longer.
+     * Post-commit loses at worst ONE ENTRY; in-transaction can, at worst, stop
+     * writes to the covered tables altogether. For a compliance trail the second
+     * trade is right; for the undo / time-travel use this plugin also serves, it
+     * is not. Two populations, opposite correct defaults — so the default is the
+     * one whose failure stays local.
+     *
+     * **What `'in-transaction'` actually promises**: if the change committed, the
+     * entry is there. That is only obtainable by being willing to REFUSE: when
+     * the history insert fails, either the mutation fails with it, or the error
+     * is swallowed and the change commits without its entry — which is
+     * post-commit's hole with the cost already paid. There is no third option,
+     * so a rare, explained rejection is the shape of the guarantee, not a bug.
+     *
+     * **Two honest limits**, in both timings:
+     *   - `store.raw()` produces no change event (the framework does not parse
+     *     hand-written SQL), so raw writes are absent from the trail. Enabling
+     *     `'in-transaction'` does not make coverage total.
+     *   - A write made OUTSIDE a transaction (a bare `store.updateMany`, not a
+     *     handler's) is recorded immediately after on the same connection, not
+     *     atomically. Framework mutations are auto-transactional, so handler
+     *     writes do get the guarantee.
+     */
+    /**
+     * Derive the app's own scoping dimension from the changed ROW.
+     *
+     * From the row rather than from a request context, because that is what this
+     * plugin has — and because a per-team dimension on a versioned table lives on
+     * the row itself. `(row) => ({ teamId: row.teamId })`.
+     *
+     * Mirrors `auditPlugin`'s option so a per-team trail can filter BOTH tables;
+     * without it on this one, half of every audit view is unfiltered.
+     */
+    readonly resolveScope?: (row: Record<string, unknown>) => unknown;
+    readonly timing?: 'post-commit' | 'in-transaction';
+}
+
+export declare type RowOp = 'insert' | 'update' | 'delete';
+
+/** The row's value AS OF a timestamp — the latest version at/ before `at`,
+ *  or `null` if the row didn't exist yet (or was deleted at that point). */
+export declare const selectAsOf: (rows: ReadonlyArray<VersionRow>, at: number) => VersionRow | null;
+
+/** History for one row, oldest → newest. */
+export declare const sortHistory: (rows: ReadonlyArray<VersionRow>) => ReadonlyArray<VersionRow>;
+
+/** Delta between two versions of a row. `changed` maps each field whose value
+ *  differs to its before/after pair (fields absent on one side read as `null`). */
+export declare interface VersionDiff {
+    readonly fromVersion: number;
+    readonly toVersion: number;
+    readonly changed: Record<string, FieldChange>;
+}
+
+export declare interface VersionRow {
+    readonly tableName: string;
+    readonly rowId: string;
+    readonly version: number;
+    readonly op: RowOp;
+    /** Full row snapshot AFTER the change (the pre-delete state for a delete). */
+    readonly data: Record<string, unknown> | null;
+    readonly changedBy: string | null;
+    /** Snapshot of who changed it — see `actor` on the history table. */
+    readonly actor?: unknown;
+    /** The app's own scoping dimension — see `scope` on the history table. */
+    readonly scope?: unknown;
+    /** epoch ms */
+    readonly changedAt: number;
+    /** The source row's tenant (from the change event), or `null` for an
+     *  untenanted source table. Reads are scoped to it so one tenant can't read
+     *  another's value timeline. */
+    readonly tenantId: string | null;
+    /** The rpc tag of the call that caused this version
+     *  (`teams.removeSubTeamMember`), or `null` for a write with no procedure
+     *  behind it (seed, startup, migration, schedule).
+     *
+     *  `traceId` says which CALL; this says which call it WAS. A row diff carries
+     *  no intent — the same delete on a join table is a member removal, a cascade
+     *  or an expiry — so without the tag a history UI can show what changed and
+     *  never what happened. */
+    readonly procedure?: string | null;
+    /** The trace the write happened under (`ChangeEvent.traceId`) — the join key
+     *  to the audit sink's row for the SAME call. Absent for a write with no
+     *  request behind it (a seed, a schedule) or one injected from a replica. */
+    readonly traceId?: string | null;
+    /** The CALLER (`ChangeEvent.subjectId`), which is not the same claim as
+     *  `changedBy`: that falls back to the row's own `audit()` stamp, which is
+     *  null for every write through the boot store. */
+    readonly subjectId?: string | null;
+}
+
+export { }

package/dist/index.js

@@ -0,0 +1,255 @@
+import { Effect as e } from "effect";
+import { allRegisteredTables as t, and as n, derivedRowId as r, eq as i, getTable as a, id as o, integer as s, isFrameworkOwnedLiveTable as c, isNull as l, json as u, lt as d, max as f, or as p, queryFor as m, registerRetention as h, registerWriteRecorder as g, resolveActorSnapshot as _, retentionTtlMsFromEnv as v, serverOnlyColumns as y, table as b, text as x, timestamp as S } from "@voltro/database";
+import { definePlugin as C, pluginInstanceName as w, tsMs as T } from "@voltro/protocol";
+//#region src/history.ts
+var E = (e) => e.reduce((e, t) => Math.max(e, t.version), 0) + 1, D = (e, t) => {
+	let n = null;
+	for (let r of e) r.changedAt <= t && (n === null || r.version > n.version) && (n = r);
+	return n === null || n.op === "delete" ? null : n;
+}, O = (e) => [...e].sort((e, t) => e.version - t.version), k = (e, t) => t === void 0 || e === null || e === t, A = () => {
+	let e = [];
+	return {
+		versionsOf: async (t, n, r) => e.filter((e) => e.tableName === t && e.rowId === n && k(e.tenantId, r)),
+		maxVersion: async (t, n) => e.reduce((e, r) => r.tableName === t && r.rowId === n ? Math.max(e, r.version) : e, 0),
+		append: async (t) => {
+			e.push(t);
+		},
+		prune: async (t, n, r) => {
+			for (let i = e.length - 1; i >= 0; i--) {
+				let a = e[i];
+				a.tableName === t && a.rowId === n && a.version < r && e.splice(i, 1);
+			}
+		},
+		all: () => [...e]
+	};
+}, j = async (e, t, n) => {
+	let r = Math.max(1, n?.attempts ?? 3), i;
+	for (let a = 0; a < r; a++) {
+		let r = {
+			tableName: t.tableName,
+			rowId: t.rowId,
+			version: await e.maxVersion(t.tableName, t.rowId) + 1,
+			op: t.op,
+			data: t.data,
+			changedBy: t.changedBy,
+			actor: t.actor ?? null,
+			scope: t.scope ?? null,
+			changedAt: t.now,
+			tenantId: t.tenantId,
+			...t.traceId === void 0 ? {} : { traceId: t.traceId },
+			...t.subjectId === void 0 ? {} : { subjectId: t.subjectId },
+			...t.procedure === void 0 ? {} : { procedure: t.procedure }
+		};
+		try {
+			await e.append(r);
+		} catch (e) {
+			i = e;
+			continue;
+		}
+		return n?.maxVersions !== void 0 && r.version > n.maxVersions && await e.prune(r.tableName, r.rowId, r.version - n.maxVersions + 1), r;
+	}
+	throw i;
+}, M = (e, t) => {
+	if (Object.is(e, t)) return !0;
+	if (typeof e != "object" || typeof t != "object" || e === null || t === null || Array.isArray(e) !== Array.isArray(t)) return !1;
+	let n = Object.keys(e), r = Object.keys(t);
+	return n.length === r.length && n.every((n) => Object.hasOwn(t, n) && M(e[n], t[n]));
+}, N = (e, t) => {
+	let n = {};
+	for (let r of /* @__PURE__ */ new Set([...Object.keys(e ?? {}), ...Object.keys(t ?? {})])) {
+		let i = e?.[r] ?? null, a = t?.[r] ?? null;
+		M(i, a) || (n[r] = {
+			from: i,
+			to: a
+		});
+	}
+	return n;
+}, P = (e, t, n) => {
+	let r = e.find((e) => e.version === t), i = e.find((e) => e.version === n);
+	return r === void 0 || i === void 0 ? null : {
+		fromVersion: t,
+		toVersion: n,
+		changed: N(r.data, i.data)
+	};
+}, F = "_voltro_row_history", I = b(F, {
+	id: o({ prefix: "rowver" }),
+	tableName: x(),
+	rowId: x(),
+	version: s(),
+	op: x(),
+	data: u().nullable(),
+	changedBy: x().nullable(),
+	actor: u().nullable(),
+	scope: u().nullable(),
+	changedAt: S().default("now"),
+	tenantId: x().nullable(),
+	traceId: x().nullable(),
+	subjectId: x().nullable(),
+	procedure: x().nullable()
+}).index("byRow", [
+	"tableName",
+	"rowId",
+	"version"
+]).index("byRowHistoryTrace", ["traceId"]).index("byRowHistorySubject", ["subjectId", "changedAt"]), L = (e) => e?.tenantId ?? null, R = (e, t, r) => {
+	let a = n(i("tableName", e), i("rowId", t));
+	return r === void 0 ? a : r === null ? n(a, l("tenantId")) : n(a, p(l("tenantId"), i("tenantId", r)));
+}, z = (e) => {
+	if (e !== void 0) return e === null ? l("tenantId") : p(l("tenantId"), i("tenantId", e));
+}, B = (e) => ({
+	tableName: String(e.tableName),
+	rowId: String(e.rowId),
+	version: Number(e.version),
+	op: String(e.op),
+	data: e.data ?? null,
+	changedBy: e.changedBy ?? null,
+	changedAt: T(e.changedAt),
+	tenantId: e.tenantId ?? null,
+	traceId: e.traceId ?? null,
+	subjectId: e.subjectId ?? null,
+	procedure: e.procedure ?? null
+}), V = (e) => ({
+	versionsOf: async (t, n, r) => (await e.query(m(I).where(R(t, n, r)).descriptor)).map(B),
+	maxVersion: async (t, r) => {
+		let a = await e.query(m(I).where(n(i("tableName", t), i("rowId", r))).aggregate({ max: f("version") }).descriptor);
+		return Number(a[0]?.max ?? 0);
+	},
+	append: async (t) => {
+		let { changedAt: n, ...i } = t;
+		await e.insert(F, {
+			...i,
+			id: r("rowver", t.tableName, t.rowId, t.version),
+			changedAt: new Date(n),
+			traceId: t.traceId ?? null,
+			subjectId: t.subjectId ?? null
+		});
+	},
+	prune: async (t, r, a) => {
+		await e.deleteMany(F, { where: n(i("tableName", t), i("rowId", r), d("version", a)) });
+	}
+}), H = (e) => e?.updatedBy ?? e?.createdBy ?? e?.deletedBy ?? null, U = (e, t) => {
+	if (t === null) return null;
+	let n = a(e);
+	if (n === void 0) return t;
+	let r = y(n);
+	if (r.length === 0) return t;
+	let i = {}, o = [];
+	for (let [e, n] of Object.entries(t)) {
+		if (r.includes(e)) {
+			o.push(e);
+			continue;
+		}
+		i[e] = n;
+	}
+	return o.length > 0 && (i._omitted = o), i;
+}, W = (e) => {
+	let t = e.new ?? e.old;
+	return t && t.id != null ? String(t.id) : null;
+}, G = "@voltro/plugin-row-history", K = (n) => {
+	if (n.maxVersionsPerRow !== void 0 && (!Number.isInteger(n.maxVersionsPerRow) || n.maxVersionsPerRow < 1)) throw Error(`rowHistoryPlugin: maxVersionsPerRow must be an integer >= 1, got ${String(n.maxVersionsPerRow)}`);
+	let i = new Set((n.include ?? []).map((e) => e.tableName)), a = new Set((n.exclude ?? []).map((e) => e.tableName)), o = [...i].filter((e) => a.has(e));
+	if (o.length > 0) throw Error(`rowHistoryPlugin: ${o.join(", ")} appears in BOTH include and exclude. One of the two is a mistake and only you know which — resolving it here would pick silently.`);
+	let s, l = () => {
+		if (s !== void 0) return s;
+		let e = /* @__PURE__ */ new Set();
+		for (let n of t()) {
+			let t = n.tableName;
+			t !== F && (c(t) && !i.has(t) || a.has(t) || e.add(t));
+		}
+		for (let t of i) e.add(t);
+		return s = e, e;
+	}, u = { has: (e) => l().has(e) }, d = w({
+		base: G,
+		alias: n.alias,
+		instance: n.name
+	}), f, p, m = v(process.env.VOLTRO_ROW_HISTORY_TTL_HOURS, 8760), y = Math.round(m / 864e5);
+	return h({
+		source: "plugin",
+		table: F,
+		timeColumn: "changedAt",
+		ttlMs: m
+	}), C({
+		name: d,
+		baseName: G,
+		description: "Row history + time-travel — value snapshots of every change, with as-of queries.",
+		permissions: ["store:write", "store:changes:read"],
+		extendSchema: { tables: [I] },
+		bindDataStore: (e) => {
+			if (f = V(e), p = e, n.timing === "in-transaction") {
+				if (e.raw === void 0) throw Error("rowHistoryPlugin({ timing: 'in-transaction' }) needs a SQL store — the in-memory store has no transaction to enlist in, and no durability for the guarantee to mean anything. Use timing: 'post-commit' for memory-backed dev, or set DB_DIALECT to a SQL dialect.");
+				g(F, {
+					tables: l(),
+					ownTables: [F],
+					recorder: async (e, t) => {
+						let n = t.next ?? t.prev, i = n && n.id != null ? String(n.id) : null;
+						if (i === null) return;
+						let a = await e.maxOf(F, "version", {
+							tableName: t.table,
+							rowId: i
+						}), o = a === null ? 1 : a + 1;
+						await e.append(F, {
+							id: r("rowver", t.table, i, o),
+							tableName: t.table,
+							rowId: i,
+							version: o,
+							op: t.op,
+							data: U(t.table, n),
+							changedBy: t.subjectId ?? H(n ?? null),
+							changedAt: /* @__PURE__ */ new Date(),
+							tenantId: L(n ?? null),
+							traceId: t.traceId ?? null,
+							subjectId: t.subjectId ?? null,
+							procedure: t.procedure ?? null
+						});
+					}
+				});
+			}
+		},
+		onChangeEvent: (t) => e.gen(function* () {
+			if (n.timing === "in-transaction" || !f || !u.has(t.table)) return;
+			let r = W(t);
+			if (r === null) return;
+			let i = p === void 0 ? void 0 : yield* e.tryPromise(() => _(p, t.subjectId ?? H(t.new ?? t.old), "user")).pipe(e.orElseSucceed(() => void 0));
+			yield* e.tryPromise(() => j(f, {
+				tableName: t.table,
+				rowId: r,
+				op: t.op,
+				data: t.oversized === "tombstone" ? null : U(t.table, t.new ?? t.old),
+				changedBy: t.subjectId === void 0 ? H(t.new ?? t.old) : t.subjectId,
+				...t.traceId === void 0 ? {} : { traceId: t.traceId },
+				...t.subjectId === void 0 ? {} : { subjectId: t.subjectId },
+				...t.procedure === void 0 ? {} : { procedure: t.procedure },
+				...i === void 0 ? {} : { actor: i },
+				...n.resolveScope === void 0 ? {} : { scope: (() => {
+					try {
+						return n.resolveScope(t.new ?? t.old ?? {});
+					} catch {
+						return null;
+					}
+				})() },
+				now: Date.now(),
+				tenantId: L(t.new ?? t.old)
+			}, n.maxVersionsPerRow === void 0 ? void 0 : { maxVersions: n.maxVersionsPerRow }));
+		}),
+		onActivate: (t) => e.sync(() => {
+			t.logger.info("row-history active", {
+				tables: l().size,
+				historyTable: F,
+				retentionDays: y,
+				...n.maxVersionsPerRow === void 0 ? {} : { maxVersionsPerRow: n.maxVersionsPerRow }
+			});
+		})
+	});
+}, q = async (e, t, n, r) => O(await V(e).versionsOf(t, n, r)), J = async (e, t, n, r, i) => D(await V(e).versionsOf(t, n, r), i instanceof Date ? i.getTime() : i)?.data ?? null, Y = async (e, t, n, r, i, a) => P(await V(e).versionsOf(t, n, r), i, a), X = async (e, t, n, r, i) => {
+	let a = await J(e, t, n, r, i);
+	if (a === null) return null;
+	let { id: o, ...s } = a;
+	return await e.update(t, n, s);
+}, Z = async (e, t, r) => {
+	let a = z(r), o = a === void 0 ? i("traceId", t) : n(i("traceId", t), a);
+	return O((await e.query(m(I).where(o).descriptor)).map(B));
+}, Q = async (e, t, r, a = 100) => {
+	let o = z(r), s = o === void 0 ? i("subjectId", t) : n(i("subjectId", t), o);
+	return (await e.query(m(I).where(s).orderBy("changedAt", "desc").limit(a).descriptor)).map(B);
+}, $ = (t, n, r) => e.promise(() => Z(t, n, r)), ee = (t, n, r, i = 100) => e.promise(() => Q(t, n, r, i)), te = (t, n, r, i) => e.promise(() => q(t, n, r, i)), ne = (t, n, r, i, a) => e.promise(() => J(t, n, r, i, a)), re = (t, n, r, i, a, o) => e.promise(() => Y(t, n, r, i, a, o)), ie = (t, n, r, i, a) => e.promise(() => X(t, n, r, i, a));
+//#endregion
+export { V as dataStoreHistoryStore, N as diffSnapshots, P as diffVersionRows, Y as diffVersions, re as diffVersionsEffect, Q as historyBySubject, ee as historyBySubjectEffect, Z as historyByTrace, $ as historyByTraceEffect, I as historyTable, A as memoryHistoryStore, E as nextVersionNumber, j as recordChange, X as restoreAsOf, ie as restoreAsOfEffect, J as rowAsOf, ne as rowAsOfEffect, q as rowHistory, te as rowHistoryEffect, K as rowHistoryPlugin, D as selectAsOf, O as sortHistory };

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@voltro/plugin-row-history",
+  "version": "0.52.0",
+  "description": "Row history + time-travel. audit() records who/when; row history records what-changed-to-what — a full value snapshot of every row on every insert/update/delete, with as-of queries.",
+  "keywords": [
+    "voltro",
+    "typescript",
+    "framework"
+  ],
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://voltro.dev",
+  "bugs": {
+    "email": "support@voltro.dev"
+  },
+  "author": {
+    "name": "Voltro UG",
+    "url": "https://voltro.dev"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "dependencies": {
+    "@voltro/database": "0.52.0",
+    "@voltro/protocol": "0.52.0"
+  },
+  "peerDependencies": {
+    "effect": "^3.22.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}