@voltro/database 0.25.0 → 0.27.0

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
@@ -3477,6 +3490,55 @@ export declare const planVersionedUpdate: (input: {
     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 {
@@ -4567,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'`);
@@ -4748,6 +4820,20 @@ export declare interface SchemaTable extends TableLike {
     readonly tableName: string;
     readonly fields: Record<string, ColumnDefinition<unknown>>;
     readonly appliedIndexes: ReadonlyArray<TableIndex>;
+    /**
+     * The plugin references DECLARED on this table, surviving `table()`.
+     *
+     * `pluginRefSpecOf` reads a column BUILDER, and materialisation replaces it
+     * with a plain field descriptor — so without this the declaration is
+     * unreadable the moment the table exists, and any tool deriving structure
+     * from the schema sees an ordinary `text()` column.
+     */
+    readonly appliedPluginRefs?: ReadonlyArray<{
+        readonly column: string;
+        readonly target: () => unknown;
+        readonly orphanPolicy: PluginRefOrphanPolicy;
+        readonly onSoftDelete: boolean;
+    }>;
     /**
      * Declared full-text indexes. Carried so a `SchemaTable`-annotated table
      * is still a valid `queryFor(...)` input (the builder reads this to let
@@ -5175,6 +5261,20 @@ export declare interface Table<Name extends string, Fields extends Record<string
     readonly isReactive: Reactive;
     readonly appliedMixins: ReadonlyArray<AnyMixin>;
     readonly appliedIndexes: ReadonlyArray<TableIndex>;
+    /**
+     * The plugin references DECLARED on this table, surviving `table()`.
+     *
+     * `pluginRefSpecOf` reads a column BUILDER, and materialisation replaces it
+     * with a plain field descriptor — so without this the declaration is
+     * unreadable the moment the table exists, and any tool deriving structure
+     * from the schema sees an ordinary `text()` column.
+     */
+    readonly appliedPluginRefs?: ReadonlyArray<{
+        readonly column: string;
+        readonly target: () => unknown;
+        readonly orphanPolicy: PluginRefOrphanPolicy;
+        readonly onSoftDelete: boolean;
+    }>;
     readonly appliedUniques: ReadonlyArray<TableUnique>;
     readonly appliedFullText: ReadonlyArray<TableFullTextIndex>;
     readonly appliedChecks: ReadonlyArray<TableCheck>;