@voltro/database 0.24.0 → 0.26.0

package/dist/{frameworkLiveTables-BvPIm2cD.js → frameworkLiveTables-BQwB8K6R.js}

@@ -32,6 +32,15 @@ var r = (e) => {
 			serverOnly: !0
 		});
 	}
+	version() {
+		if (this.rejectIfRaw("version"), this.definition.type !== "integer") throw Error(`.version() requires an integer() column (got ${this.definition.type}). The store increments it, so it has to be a number — and a timestamp version reintroduces exactly the clock problem optimistic locking exists to avoid: two writes in the same millisecond are indistinguishable, and replica clocks disagree.`);
+		return new e({
+			...this.definition,
+			versionColumn: !0,
+			hasDefault: !0,
+			defaultValue: 1
+		});
+	}
 	sensitive(t) {
 		return new e({
 			...this.definition,

package/dist/index.d.ts

@@ -11,6 +11,11 @@ import { Stream } from 'effect';
 import { VoidIfEmpty } from 'effect/Types';
 import { YieldableError } from 'effect/Cause';
 
+/** The store shape this needs — a read, nothing more. */
+export declare interface ActorLookupStore {
+    query: (descriptor: unknown) => Promise<ReadonlyArray<Record<string, unknown>>>;
+}
+
 /** The framework's built-in `actors` core table. */
 export declare const actorsTable: Table<'actors', Record<string, ColumnDefinition<unknown>>, true, never>;
 
@@ -185,6 +190,14 @@ export declare const attributionFields: (explicit?: WriteAttribution | undefined
  *  never match. `(table, op, pk)` is stable through any re-encoding. */
 export declare const attributionKey: (table: string, op: string, primaryKey: unknown) => string;
 
+/** A snapshot of who acted, as of the call. */
+export declare interface AuditActor {
+    readonly id: string;
+    readonly type: string;
+    readonly displayName: string | null;
+    readonly email: string | null;
+}
+
 /**
  * Audit a list of tables in one call. Convenience for the CLI's boot
  * path; same shape as calling `auditTableIndexes` per table and
@@ -670,6 +683,34 @@ export declare class ColumnBuilder<TsType, Type extends ColumnType, HasDefault e
      * neither.)
      */
     serverOnly(): this;
+    /**
+     * Mark this column as the row's OPTIMISTIC-CONCURRENCY version.
+     *
+     * ```ts
+     * table('documents', { id: id(), title: text(), version: integer().version() })
+     * ```
+     *
+     * From then on the store increments it on every update, and an update that
+     * carries `expectedVersion` fails with a typed `VersionConflict` when the row
+     * has moved on. That is the whole feature, and the reason it is a COLUMN
+     * marker rather than a table mixin is that only the author knows which column
+     * (if any) their schema already uses for this — several apps arrive with one.
+     *
+     * WHAT IT REPLACES. Nothing, which is the point: today the second of two
+     * concurrent writers wins silently. `updatedAt` is the obvious substitute and
+     * it does not work — same-millisecond writes are indistinguishable and replica
+     * clocks disagree, so a comparison that looks correct in a test loses rows
+     * under load. An integer the DATABASE owns has neither problem.
+     *
+     * WHAT IT DOES NOT DO. It is not a history: it records that a row changed, not
+     * what it changed to. For that use `plugin-versioning`. It is also not a
+     * distributed lock — a conflicting write is REPORTED, never queued or merged,
+     * because merging two intents is a decision only the application can make.
+     *
+     * Must be an `integer()`. A `text()` version cannot be incremented and a
+     * `timestamp()` one reintroduces the clock, so both fail at declaration.
+     */
+    version(): this;
     /**
      * Classify this column as SENSITIVE — it holds personal / sensitive data of
      * `class` (`'email'`, `'fullName'`, `'phone'`, `'address'`, `'secret'`, …).
@@ -1112,6 +1153,23 @@ export declare interface ColumnDefinition<TsType, Type extends ColumnType = Colu
      * COSTS is per command — see `serverOnly()` below for the matrix.
      */
     readonly serverOnly?: boolean;
+    /**
+     * Optimistic-concurrency marker, set by `.version()`.
+     *
+     * The column the store INCREMENTS on every update, and the one an update may
+     * carry an expectation of. Two clients that read the same row and both write
+     * it are the normal case, not an exotic one — and without this the second
+     * write silently wins, which is the shape of every "my change disappeared"
+     * report ever filed.
+     *
+     * A TIMESTAMP cannot do this job. Two writes in the same millisecond are
+     * indistinguishable, and across replicas the clocks disagree; this repo has
+     * already lost rows to exactly that (an analytics sink dropped 7 of 40 events
+     * written in the same millisecond as the query bounding them). A monotonic
+     * integer has neither problem, and it also answers the other half of the
+     * question — which of two copies is NEWER — without consulting a clock.
+     */
+    readonly versionColumn?: boolean;
     /**
      * Data-sensitivity classification, set by `.sensitive(class)`. Declares that
      * this column holds personal / sensitive data of a given CLASS (`'email'`,
@@ -2215,6 +2273,35 @@ export declare interface ExistsPredicate {
     readonly subquery: QueryDescriptor;
 }
 
+/**
+ * Add `expiresAt` — after that instant the row is invisible to reads.
+ *
+ * ```ts
+ * table('inviteLinks', { id: id(), email: text() }).with(expires())
+ *
+ * await ctx.store.insert('inviteLinks', {
+ *   email, expiresAt: new Date(Date.now() + 24 * 3_600_000),
+ * })
+ * ```
+ *
+ * `expiresAt` is NULLABLE and null means never — so adding the mixin to an
+ * existing table does not make its rows vanish, and a row that should outlive
+ * the others simply leaves it unset. A non-null default would have been the
+ * tidier API and the wrong one: it would turn "I added a mixin" into "I set an
+ * expiry on every existing row".
+ *
+ * Reads filter it out on EVERY dialect from the moment it passes; the physical
+ * delete is a postgres-only sweep. Read the header before relying on the second
+ * half — an expired row is INVISIBLE everywhere and still PRESENT on four of
+ * five dialects, which is the right trade and a surprising one.
+ *
+ * Opt out for a deliberate read of expired rows the same way soft-delete does:
+ * `ctx.store.select('inviteLinks').includeExpired()`.
+ */
+export declare const expires: () => MixinDefinition<{
+    readonly expiresAt: ColumnDefinition<Date | null, "timestamp", boolean>;
+}>;
+
 /** The cipher the store middleware injects. Operates on opaque strings. */
 export declare interface FieldCipher {
     readonly encrypt: (plaintext: string) => string;
@@ -2664,6 +2751,16 @@ export declare type InferRowFromFields<F extends Record<string, ColumnDefinition
 /** Row type for a view — mirrors `InferRow` for tables. */
 export declare type InferViewRow<V> = V extends View<string, infer F> ? InferRowFromFields<F> : never;
 
+/**
+ * The version a freshly-inserted row starts at.
+ *
+ * 1 rather than 0 so that "has this row ever been written?" and "what version is
+ * it?" are never the same question — a 0 reads as absent in too many places
+ * (`if (row.version)`), and a version that is falsy on a real row is a trap
+ * waiting for the first person who writes that check.
+ */
+export declare const INITIAL_VERSION = 1;
+
 /**
  * Insert a row, typed against the table: the payload must carry every required
  * column (NOT NULL, no default, not auto-filled) or it is a compile error.
@@ -3373,6 +3470,75 @@ export declare const planNeonBranchProvision: (branchId: string, options?: NeonB
  *  never delete a non-branch; idempotent on the executor side. */
 export declare const planNeonBranchTeardown: (branchId: string) => ReadonlyArray<BranchStep>;
 
+/**
+ * The version an UPDATE must write, and the guard it must carry.
+ *
+ * Returns `undefined` when the table has no version column, so a store's fast
+ * path is a single check and an app that does not use the feature pays nothing.
+ *
+ * `expected` is read from the PATCH rather than passed separately, because the
+ * alternative — a second argument on every store method — is a change every
+ * caller has to make and most would skip. Putting it in the patch means the
+ * caller who cares opts in at the one call site that cares.
+ */
+export declare const planVersionedUpdate: (input: {
+    readonly versionColumn: string | undefined;
+    readonly patch: Readonly<Record<string, unknown>>;
+}) => {
+    readonly nextVersion: number | undefined;
+    readonly expected: number | undefined;
+    readonly patch: Record<string, unknown>;
+};
+
+/**
+ * A typed id column pointing at a plugin-owned row, with an orphan rule.
+ *
+ * No foreign key is emitted — see the header. The rule is enforced by the
+ * runtime on the target's delete.
+ */
+export declare const pluginRef: (target: () => TableLike, options?: PluginRefOptions) => ColumnBuilder<string, ColumnType>;
+
+export declare interface PluginRefOptions {
+    /** What to do with this row when the target row is deleted. Default `'keep'`,
+     *  which is today's behaviour — declaring the rule is opt-in, and a default
+     *  that deleted rows would be a footgun in a patch release. */
+    readonly orphanPolicy?: PluginRefOrphanPolicy;
+    /**
+     * Also fire on a SOFT delete of the target.
+     *
+     * Default `false`, and the asymmetry is real rather than an oversight: some
+     * plugin tables carry `deletedAt` and some do not (`_voltro_ai_flows` does,
+     * `_voltro_ai_flow_runs` does not). A soft delete is a state change the
+     * target can undo, so cascading on it destroys rows that a restore cannot
+     * bring back. Opt in when your rule is about visibility rather than
+     * existence.
+     */
+    readonly onSoftDelete?: boolean;
+}
+
+/** What happens to the referencing row when the target row goes away. */
+export declare type PluginRefOrphanPolicy = 
+/** Delete the referencing row. For a row that only exists to point at it —
+*  a favourite, a pin, a share. */
+'delete'
+/** Null the column, keeping the row. Requires `.nullable()`; declaring it on
+*  a non-nullable column is refused at declaration rather than failing at the
+*  first delete, months later. */
+| 'null'
+/** Do nothing. The explicit "I know, and I handle it myself" — different from
+*  omitting the option, which is the same behaviour arrived at by accident. */
+| 'keep';
+
+/** Declared metadata for one plugin reference — read by the boot wiring. */
+export declare interface PluginRefSpec {
+    readonly target: () => TableLike;
+    readonly orphanPolicy: PluginRefOrphanPolicy;
+    readonly onSoftDelete: boolean;
+}
+
+/** The declared spec for a column builder, when it is a `pluginRef`. */
+export declare const pluginRefSpecOf: (column: unknown) => PluginRefSpec | undefined;
+
 export declare type Predicate = PredicateLeaf | AndPredicate | OrPredicate | NotPredicate | SubqueryInPredicate | ExistsPredicate;
 
 export declare interface PredicateLeaf {
@@ -3849,6 +4015,10 @@ export declare interface QueryDescriptor<R = Row> {
      * (storeMiddleware read path + reactive-query finalize) honors.
      */
     readonly includeDeleted?: boolean;
+    /** Opt OUT of the `expires()` read filter — a deliberate read of expired
+     *  rows (an admin view, a grace-period check). Same shape and same posture as
+     *  `includeDeleted`. */
+    readonly includeExpired?: boolean;
     /**
      * Opt OUT of the runtime's automatic tenant scope on `tenant()` tables.
      * Set by `.unscoped()`. Honored by the runtime, same as `includeDeleted`.
@@ -4459,6 +4629,16 @@ declare type Resolve<T> = {
     readonly [K in keyof T]: T[K];
 } & {};
 
+/**
+ * Snapshot the `actors` row for `subjectId`.
+ *
+ * `email` is read opportunistically: the framework's own `actors` carries
+ * `id` / `kind` / `displayName`, and apps commonly extend it. Reading whatever
+ * identifies the actor is the point — insisting on a fixed shape would make the
+ * field useless for the deployments that need it most.
+ */
+export declare const resolveActorSnapshot: (store: ActorLookupStore, subjectId: string | null | undefined, subjectType: string) => Promise<AuditActor | undefined>;
+
 /**
  * Pick the branch mechanism. Prioritises the Neon copy-on-write fast-path when
  * the owned DB is Neon AND the branch snapshots parent data (`seed: 'copy'`);
@@ -4810,6 +4990,20 @@ export declare const setResidencyConfig: (config: ResidencyConfig) => ResidencyC
  */
 export declare const settleTransactionExit: <A>(exit: Exit.Exit<A, unknown>) => A;
 
+/**
+ * Decide the outcome of a versioned update from what the row actually held.
+ *
+ * Separated from the SQL so every store shares the DECISION and only the
+ * statement differs. `current` is the row's version before the write, or `null`
+ * when the row is gone.
+ */
+export declare const settleVersionedUpdate: (input: {
+    readonly table: string;
+    readonly id: string;
+    readonly expected: number | undefined;
+    readonly current: number | null;
+}) => VersionConflict | undefined;
+
 /**
  * PostGIS spatial-distance clause carried on a {@link QueryDescriptor}.
  * Drives a `ST_Distance` projected column (distance-as-a-value) and/or a
@@ -5923,6 +6117,34 @@ export declare interface VectorOptions {
     readonly precision?: 'float32' | 'half';
 }
 
+/** The column marked `.version()`, or `undefined` when a table has none. */
+export declare const versionColumnOf: (columns: Readonly<Record<string, {
+    readonly definition?: {
+        readonly versionColumn?: boolean;
+    };
+}>>) => string | undefined;
+
+/**
+ * A write lost the race.
+ *
+ * Carries both numbers because "someone else changed it" is not actionable and
+ * "you had 3, it is now 7" is: four intervening writes is a different situation
+ * from one, and a UI can say so.
+ */
+export declare class VersionConflict extends VersionConflict_base {
+}
+
+declare const VersionConflict_base: Schema.TaggedErrorClass<VersionConflict, "VersionConflict", {
+    readonly _tag: Schema.tag<"VersionConflict">;
+} & {
+    table: typeof Schema.String;
+    id: typeof Schema.String;
+    /** What the caller believed the row was at. */
+    expected: typeof Schema.Number;
+    /** What it is actually at. `null` when the row is gone entirely. */
+    actual: Schema.NullOr<typeof Schema.Number>;
+}>;
+
 /**
  * A read-only SQL view descriptor. Structurally a `TableLike` (carries
  * `tableName` + `fields`) so the query builder + row decoder + by-name
@@ -5970,6 +6192,9 @@ export declare const view: <const Name extends string, const Input extends Field
  */
 export declare const viewSql: (v: View<string, Record<string, ColumnDefinition<unknown>>>, dialect: DialectId, schema?: string | null) => string;
 
+/** Stable mixin id — the runtime keys read-filtering off it. */
+export declare const VOLTRO_EXPIRES_MIXIN_ID = "voltro/expires";
+
 /**
  * `_voltro_api_keys` — first-class API key management. Only the SHA-256 HASH
  * of a key is stored (`hashedKey`, unique); the raw token is shown once at