@sequenceholdings/orm 2.1.0 → 2.2.0

package/dist/authoring.d.cts

@@ -1,8 +1,11 @@
-import { ColumnType, CanonicalColumn, CanonicalDefinition, CanonicalTable } from './canonical.cjs';
+import { ColumnType, CanonicalColumn, ComparatorKind, CanonicalFunctionRef, CanonicalFetchShape, CanonicalDefinition, CanonicalTable } from './canonical.cjs';
+import { b as CellPart } from './constants-C6EG6Wq7.cjs';
 import { ColumnsSelection } from 'drizzle-orm';
 import { TypedQueryBuilder } from 'drizzle-orm/query-builders/query-builder';
 import { QueryBuilder, PgView, PgTable, AnyPgColumn } from 'drizzle-orm/pg-core';
+export { S as SqlOperationDefinition, d as defineOperation } from './definition-DjfC7Lll.cjs';
 import 'zod';
+import './policy-1iZbGnZZ.cjs';
 
 /**
  * Fluent column builders for the v2 authoring surface — `t.uuid()`,
@@ -61,6 +64,8 @@ declare class ColumnBuilder {
     cast(usingSql: string): this;
     /** Emits `@deprecated` in the generated SDL; the column stays queryable. */
     deprecated(): this;
+    /** @internal System cell-metadata part of logical column `of` (generated resolved views only). */
+    cellPart(of: string, part: CellPart): this;
     /** Whether `.primaryKey()` was called — collected into the table-level PK. */
     get isPrimaryKey(): boolean;
     /** The enum name when this is an enum column, else undefined. */
@@ -117,7 +122,7 @@ interface CowMutationInput {
 interface OverrideRowMutationInput<TOverlay extends OverlayTableRef = OverlayTableRef, TSynced extends SeqTable = SeqTable> {
     /** Writable ORM overlay table (or `{ tableName, columns }` descriptor). */
     overlay: TOverlay;
-    /** Read-only synced table reflecting the gold-layer source. */
+    /** Read-only synced table reflecting its qualified source relation. */
     synced: TSynced;
     /**
      * Property name of the single-column primary key shared by both tables.
@@ -179,6 +184,8 @@ interface RevertOverlayMutationInput<TOverlay extends OverlayTableRef = OverlayT
  *   ],
  * })
  * ```
+ *
+ * @deprecated Resolved tables write sparse cells directly (`defineResolvedTable`). Kept so existing definitions still compile.
  */
 declare function overrideRowMutation<TOverlay extends OverlayTableRef, TSynced extends SeqTable>(input: OverrideRowMutationInput<TOverlay, TSynced>): CowMutationInput;
 /**
@@ -187,9 +194,182 @@ declare function overrideRowMutation<TOverlay extends OverlayTableRef, TSynced e
  *
  * The DELETE is gated on a matching synced row — overlay-only creates (or rows
  * whose synced source disappeared) are not deleted by revert.
+ *
+ * @deprecated Resolved tables write sparse cells directly (`defineResolvedTable`). Kept so existing definitions still compile.
  */
 declare function revertOverlayMutation<TOverlay extends OverlayTableRef, TSynced extends SeqTable>(input: RevertOverlayMutationInput<TOverlay, TSynced>): CowMutationInput;
 
+/**
+ * `defineResolvedTable` — one logical table backed by manual, etl and
+ * prefetch sources, with a SQL comparator per column.
+ *
+ * It expands into existing primitives so DDL, apply, SDL and policy
+ * compilation stay shared:
+ *
+ *  - one internal table per manual/prefetch source (`<name>__<source>`,
+ *    `cellMetadata: true`, sparse nullable columns),
+ *  - the author's own synced tables for etl sources,
+ *  - a managed view named `<name>` whose generated query unions every
+ *    source's primary keys (so `pk = $1` pushes down into each source),
+ *    left-joins each source back, and picks every column's winner with a
+ *    CASE over typed per-cell timestamps (built-in comparators) or a small
+ *    ORDER BY … LIMIT 1 lateral (custom).
+ *
+ * All comparators run in SQL — never app code — so reads stay one statement
+ * and filters/policies see resolved values.
+ */
+
+/** A duration: milliseconds, or a string like `'1500ms'`, `'30s'`, `'5m'`. */
+type DurationInput = number | `${number}ms` | `${number}s` | `${number}m`;
+type FunctionRef = CanonicalFunctionRef;
+/** A Managed Function (id or slug) that implements a prefetch source's fetch and writeback. */
+declare function managedFn(id: string): FunctionRef;
+interface ManualSourceInput {
+    readonly kind: 'manual';
+}
+interface EtlSourceInput {
+    readonly kind: 'etl';
+    /** A `defineSyncedTable` relation fed by a pipeline. */
+    readonly table: RelationRef;
+    /** Property on the synced table whose value timestamps every cell (e.g. an ingested_at column). */
+    readonly updatedAt?: string;
+    /** Resolved columns this source supplies; defaults to every column the synced table shares by name. */
+    readonly columns?: readonly string[];
+}
+interface PrefetchSourceInput {
+    readonly kind: 'prefetch';
+    readonly function: FunctionRef;
+    /** Resolved column holding the source system's key (may be the primary key). */
+    readonly key: string;
+    /** Resolved columns the function returns. */
+    readonly columns: readonly string[];
+    /** What the source API supports: one key per call, or batches. */
+    readonly fetch: 'single' | {
+        readonly batch: {
+            readonly maxKeys: number;
+        };
+    };
+    readonly prefetchDefaults?: {
+        readonly maxStaleness?: DurationInput;
+        readonly timeout?: DurationInput;
+        readonly onError?: 'fallback' | 'fail';
+    };
+    readonly writeback?: {
+        readonly columns: readonly string[];
+        readonly defaultMode?: 'sync' | 'async';
+        readonly timeout?: DurationInput;
+        readonly clearManualOnConfirm?: boolean;
+    };
+}
+type ResolvedSourceInput = ManualSourceInput | EtlSourceInput | PrefetchSourceInput;
+declare function manualSource(): ManualSourceInput;
+declare function etlSource(input: Omit<EtlSourceInput, 'kind'>): EtlSourceInput;
+declare function prefetchSource(input: Omit<PrefetchSourceInput, 'kind'>): PrefetchSourceInput;
+interface Comparator {
+    readonly kind: ComparatorKind;
+    readonly candidates: readonly string[];
+    readonly orderBy?: string;
+}
+/** Newest `updated_at` wins; source order breaks ties. */
+declare const latest: (candidates: readonly string[]) => Comparator;
+/** Largest value wins. */
+declare const highest: (candidates: readonly string[]) => Comparator;
+/** Smallest value wins. */
+declare const lowest: (candidates: readonly string[]) => Comparator;
+/** First candidate with an opinion (a cleared cell counts) wins. */
+declare const priority: (candidates: readonly string[]) => Comparator;
+/** First candidate with a non-null value wins. */
+declare const nonNullFirst: (candidates: readonly string[]) => Comparator;
+/**
+ * Author-defined SQL ORDER BY key over each candidate's `value`, `updated_at`,
+ * `source`, `actor` and `ord` (its position in `candidates`). The first row
+ * wins; `ord` is always appended as the final tie-break.
+ *
+ * ```ts
+ * custom(['edits', 'abrigo'], "CASE WHEN source = 'abrigo' AND value IS NOT NULL THEN 0 ELSE 1 END")
+ * ```
+ */
+declare const custom: (candidates: readonly string[], orderBy: string) => Comparator;
+interface ResolvedTablePoliciesInput {
+    read: PolicyInput;
+    write?: PolicyInput;
+    insert?: PolicyInput;
+    update?: PolicyInput;
+}
+interface ResolvedTableConfig {
+    description?: string;
+    sources: Record<string, ResolvedSourceInput>;
+    /** Per-column comparator; unlisted columns use `default`. */
+    resolve?: Record<string, Comparator>;
+    /** Fallback comparator; each column keeps only the candidates that supply it. Defaults to priority(manual, prefetch…, etl…). */
+    default?: Comparator;
+    rows?: {
+        deletedBy?: readonly string[];
+    };
+    links?: Record<string, SeqLink>;
+    /** Reads use `read`; writes are evaluated against the resolved row. */
+    policies: ResolvedTablePoliciesInput;
+    /**
+     * Store the resolved rows in an indexed internal table instead of
+     * computing them on every read, so filters and sorts on resolved values can
+     * use `indexes`. The data plane refreshes a row in the same transaction as
+     * any ORM write to its sources (edits, prefetch, writeback); ETL changes are
+     * picked up by a periodic reconcile. Every ETL source must have read policy
+     * `'true'` — the copy is shared by all callers.
+     */
+    materialize?: true | {
+        indexes?: readonly IndexInput[];
+    };
+}
+/** Authoring-side resolved metadata carried on the generated view (serialized by namespace.ts). */
+interface ResolvedViewConfig {
+    readonly internalTables: readonly SeqTable[];
+    /** A materialized table's compute view. */
+    readonly internalViews?: readonly SeqView[];
+    readonly materialized?: {
+        readonly table: string;
+        readonly compute: string;
+    };
+    readonly sources: ReadonlyArray<ResolvedSourcePlan>;
+    readonly rules: ReadonlyArray<{
+        column: string;
+        comparator: ComparatorKind;
+        candidates: string[];
+        orderBy?: string;
+    }>;
+    readonly deletedBy: readonly string[];
+    readonly policies: Omit<ResolvedTablePoliciesInput, 'read'>;
+}
+interface ResolvedSourcePlan {
+    readonly name: string;
+    readonly kind: ResolvedSourceInput['kind'];
+    readonly table: SeqTable;
+    readonly columns: readonly string[];
+    readonly updatedAt?: string;
+    readonly key?: string;
+    readonly fetch?: CanonicalFetchShape;
+    readonly function?: FunctionRef;
+    readonly prefetchDefaults?: {
+        maxStalenessMs: number;
+        timeoutMs: number;
+        onError: 'fallback' | 'fail';
+    };
+    readonly writeback?: {
+        columns: string[];
+        defaultMode: 'sync' | 'async';
+        timeoutMs: number;
+        clearManualOnConfirm: boolean;
+    };
+}
+declare const SYSTEM_VIEW_COLUMNS: {
+    readonly writebackStatus: () => ColumnBuilder;
+    readonly writebackError: () => ColumnBuilder;
+};
+type SystemViewColumns = {
+    [K in keyof typeof SYSTEM_VIEW_COLUMNS]: ColumnBuilder;
+};
+declare function defineResolvedTable<const TColumns extends Record<string, ColumnBuilder>>(name: string, columns: TColumns, config: ResolvedTableConfig): SeqView<TColumns & SystemViewColumns>;
+
 /**
  * Managed regular-view authoring. A view keeps its GraphQL contract in the
  * Sequence column/policy DSL, while its SELECT is authored with Drizzle and
@@ -212,6 +392,10 @@ interface ViewConfig {
     links?: Record<string, SeqLink>;
     policies: ViewPoliciesInput;
     query: (context: ViewQueryContext) => ViewSelectQuery;
+    /** Set by defineResolvedTable — multi-source metadata serialized onto the canonical view. */
+    resolved?: ResolvedViewConfig;
+    /** System-owned view (a materialized resolved table's compute view): no GraphQL surface. Set by defineResolvedTable. */
+    internal?: boolean;
 }
 interface SeqView<TColumns extends Record<string, ColumnBuilder> = Record<string, ColumnBuilder>> {
     readonly kind: typeof VIEW_BRAND;
@@ -228,7 +412,7 @@ declare function defineView<const TColumns extends Record<string, ColumnBuilder>
 interface OverlayWinsUnionInput<TOverlay extends SeqTable = SeqTable, TSynced extends SeqTable = SeqTable> {
     /** The ORM overlay table (writable, has `tombstone` if soft-delete is used). */
     overlay: TOverlay;
-    /** The synced (read-only) table reflecting the gold-layer source. */
+    /** The synced (read-only) table reflecting its qualified source relation. */
     synced: TSynced;
     /**
      * Property name of the single-column primary key shared by both tables.
@@ -258,6 +442,8 @@ interface OverlayWinsUnionInput<TOverlay extends SeqTable = SeqTable, TSynced ex
  *   policies: { read: 'true' },
  * })
  * ```
+ *
+ * @deprecated Use `defineResolvedTable` — per-cell comparators over manual/etl/prefetch sources. Kept so existing definitions still compile.
  */
 declare function overlayWinsUnion<TOverlay extends SeqTable, TSynced extends SeqTable>(input: OverlayWinsUnionInput<TOverlay, TSynced>): ViewConfig['query'];
 
@@ -266,8 +452,16 @@ declare const LINK_BRAND: "seq-link";
 /** A link target: a managed table/view, or a lazy thunk for forward/cyclic references. */
 type RelationRef = SeqTable | SeqView | (() => SeqTable | SeqView);
 /** Backward-compatible alias retained for existing consumers. */
-type TableRef = RelationRef;
+type TableRef = RelationRef | ExternalObjectRef;
+interface ExternalObjectRef {
+    readonly kind: 'seq-external-object';
+    readonly namespace: string;
+    readonly table: string;
+}
+/** Qualified identity resolved against a pinned namespace contract at compile time. */
+declare function objectRef(namespace: string, table: string): ExternalObjectRef;
 type LinkKind = 'toOne' | 'toMany' | 'toPlatformUser';
+type ReferentialAction = 'cascade' | 'restrict' | 'no action' | 'set null' | 'set default';
 interface SeqLink {
     readonly kind: typeof LINK_BRAND;
     readonly linkKind: LinkKind;
@@ -277,6 +471,8 @@ interface SeqLink {
     readonly on: string;
     readonly references: string | undefined;
     readonly enforce: boolean;
+    readonly onDelete: ReferentialAction | undefined;
+    readonly onUpdate: ReferentialAction | undefined;
     readonly description: string | undefined;
 }
 interface ToOneOptions {
@@ -284,6 +480,8 @@ interface ToOneOptions {
     references?: string;
     /** Emit a real FK constraint (same-namespace toOne only). */
     enforce?: boolean;
+    onDelete?: ReferentialAction;
+    onUpdate?: ReferentialAction;
     description?: string;
 }
 interface ToManyOptions {
@@ -330,6 +528,11 @@ interface IndexInput {
     unique?: boolean;
     name?: string;
 }
+/** Named PostgreSQL CHECK using the supported, validated predicate subset. */
+interface CheckInput {
+    name: string;
+    expression: string;
+}
 /** Database integrity constraint; independent of GraphQL relationship traversal. */
 interface ForeignKeyInput {
     name: string;
@@ -338,14 +541,18 @@ interface ForeignKeyInput {
     references: readonly string[];
     /** Omit for immediate, non-deferrable PostgreSQL enforcement. */
     deferrable?: 'initially-immediate' | 'initially-deferred';
+    onDelete?: ReferentialAction;
+    onUpdate?: ReferentialAction;
 }
 interface TableConfig {
+    displayName?: string;
     description?: string;
     /** Table-level migration rename hint (new in v2). */
     renamedFrom?: string;
     /** Composite primary key: property names (or column names). Mutually exclusive with column-level `.primaryKey()`. */
     primaryKey?: readonly string[];
     indexes?: readonly IndexInput[];
+    checks?: readonly CheckInput[];
     foreignKeys?: readonly ForeignKeyInput[];
     links?: Record<string, SeqLink>;
     policies?: TablePoliciesInput;
@@ -356,13 +563,36 @@ interface TableConfig {
      * mutation roots whose SQL the engine generates.
      */
     cowMutations?: readonly CowMutationInput[];
+    /**
+     * Track per-cell edit metadata: every data column `c` gets typed system
+     * columns `c__at` (timestamptz) and `c__by` (text), stamped by each
+     * insert/update for exactly the columns it writes. Read through the typed
+     * GraphQL field `cells { c { at by } }`; never client-writable.
+     */
+    cellMetadata?: boolean;
+    /**
+     * Internal (resolved-table manual source): also keep a `c__rev` uuid per
+     * cell identifying each edit. Set by defineResolvedTable.
+     */
+    cellRevisions?: boolean;
+    /**
+     * Internal: this table is the materialized copy of resolved table
+     * `materializes` (its columns mirror the view, cell parts included). Set by
+     * defineResolvedTable.
+     */
+    materializes?: string;
+    /**
+     * System-owned backing table of a resolved table (set by
+     * defineResolvedTable). Gets DDL but no GraphQL surface.
+     */
+    internal?: boolean;
 }
 interface SeqTable<TColumns extends Record<string, ColumnBuilder> = Record<string, ColumnBuilder>> {
     readonly kind: typeof TABLE_BRAND;
     readonly tableName: string;
     readonly columns: Readonly<TColumns>;
     readonly config: TableConfig;
-    /** Synced reflected source (`gold.*`) — set only by defineSyncedTable. */
+    /** Synced reflected source (`schema.table`) — set only by defineSyncedTable. */
     readonly source: string | undefined;
     /** Consumer file that defined the table (set when loaded via loadNamespaceFromDir). */
     readonly file: string | undefined;
@@ -374,11 +604,11 @@ interface SyncedTablePoliciesInput {
     read?: PolicyInput;
 }
 /**
- * Config for a read-only gold reflection. Columns (typed overload) are a contract
+ * Config for a read-only qualified-source reflection. Columns (typed overload) are a contract
  * for views/clients — ORM does not own synced DDL.
  */
 interface SyncedTableConfig {
-    /** Reflected read-only source, restricted to the gold layer: `gold.<table>`. */
+    /** Reflected read-only source as a safe qualified identifier: `<schema>.<table>`. */
     source: string;
     description?: string;
     /** Composite primary key: property names (or column names). Mutually exclusive with column-level `.primaryKey()`. */
@@ -411,12 +641,16 @@ interface NamespaceConfigInput {
     namespace: string;
     description?: string;
     capabilities?: NamespaceCapabilitiesInput;
+    imports?: readonly unknown[];
+    exports?: CanonicalDefinition['exports'];
 }
 interface SeqNamespaceConfig {
     readonly kind: typeof NAMESPACE_CONFIG_BRAND;
     readonly namespace: string;
     readonly description: string | undefined;
     readonly capabilities: NamespaceCapabilitiesInput;
+    readonly imports?: readonly unknown[];
+    readonly exports?: CanonicalDefinition['exports'];
     readonly file: string | undefined;
 }
 declare function isSeqNamespaceConfig(value: unknown): value is SeqNamespaceConfig;
@@ -553,4 +787,14 @@ declare function beginAuthoringContext(): AuthoringContext;
 declare function endAuthoringContext(context: AuthoringContext): void;
 declare function activeAuthoringContext(): AuthoringContext | undefined;
 
-export { type AuthoringContext, type AuthoringRegistration, COLUMN_BRAND, COLUMN_DEFAULT_FNS, ColumnBuilder, type ColumnDefaultFn, type ColumnDefaultLiteral, type ColumnTypeSpec, type CowMutationInput, type DrizzleRelation, ENUM_BRAND, type EnumRef, type ForeignKeyInput, type IndexInput, LINK_BRAND, type LinkKind, type LoadNamespaceOptions, type LoadedNamespaceV2, NAMESPACE_CONFIG_BRAND, NAMESPACE_CONFIG_FILE, type NamespaceCapabilitiesInput, type NamespaceConfigInput, ORM_TO_PIPELINE_TYPE, type OrmContractColumnMap, type OrmContractPipelineColumn, type OrmSyncedTableContract, type OrmToPipelineType, type OverlayTableRef, type OverlayWinsUnionInput, type OverrideRowMutationInput, type PolicyInput, type PolicyVariantInput, type PolicyWithVariantsInput, type RelationRef, type RevertOverlayMutationInput, SCHEMA_DIR, SYNCED_CONTRACT_HASH_DOMAIN, type SeqLink, type SeqNamespaceConfig, type SeqTable, type SeqView, type SerializeNamespaceInput, type SyncedTableConfig, type SyncedTablePoliciesInput, TABLE_BRAND, type TableConfig, type TablePoliciesInput, type TableRef, type ToManyOptions, type ToOneOptions, type ToPlatformUserOptions, type TypedSyncedTableConfig, VIEW_BRAND, type ViewConfig, type ViewPoliciesInput, type ViewQueryContext, type ViewSelectQuery, activeAuthoringContext, beginAuthoringContext, computeCanonicalHash, computeSyncedContractHash, defineEnum, defineNamespace, defineSyncedTable, defineTable, defineView, deriveColumnName, endAuthoringContext, extractOrmSyncedTableContract, isColumnBuilder, isEnumRef, isSeqLink, isSeqNamespaceConfig, isSeqTable, isSeqView, loadNamespaceFromDir, overlayWinsUnion, overrideRowMutation, revertOverlayMutation, serializeNamespace, syncedContractSurface, t, toMany, toOne, toPlatformUser };
+interface CatalogFolders {
+    [name: string]: CatalogFolders | null;
+}
+/** Presentation-only organization; never included in the canonical schema hash. */
+interface NamespaceCatalog {
+    folders: CatalogFolders;
+    objects: Record<string, string>;
+}
+declare function validateNamespaceCatalog(catalog: NamespaceCatalog, file?: string): void;
+
+export { type AuthoringContext, type AuthoringRegistration, COLUMN_BRAND, COLUMN_DEFAULT_FNS, type CatalogFolders, type CheckInput, ColumnBuilder, type ColumnDefaultFn, type ColumnDefaultLiteral, type ColumnTypeSpec, type Comparator, type CowMutationInput, type DrizzleRelation, type DurationInput, ENUM_BRAND, type EnumRef, type EtlSourceInput, type ExternalObjectRef, type ForeignKeyInput, type FunctionRef, type IndexInput, LINK_BRAND, type LinkKind, type LoadNamespaceOptions, type LoadedNamespaceV2, type ManualSourceInput, NAMESPACE_CONFIG_BRAND, NAMESPACE_CONFIG_FILE, type NamespaceCapabilitiesInput, type NamespaceCatalog, type NamespaceConfigInput, ORM_TO_PIPELINE_TYPE, type OrmContractColumnMap, type OrmContractPipelineColumn, type OrmSyncedTableContract, type OrmToPipelineType, type OverlayTableRef, type OverlayWinsUnionInput, type OverrideRowMutationInput, type PolicyInput, type PolicyVariantInput, type PolicyWithVariantsInput, type PrefetchSourceInput, type ReferentialAction, type RelationRef, type ResolvedSourceInput, type ResolvedTableConfig, type ResolvedTablePoliciesInput, type RevertOverlayMutationInput, SCHEMA_DIR, SYNCED_CONTRACT_HASH_DOMAIN, type SeqLink, type SeqNamespaceConfig, type SeqTable, type SeqView, type SerializeNamespaceInput, type SyncedTableConfig, type SyncedTablePoliciesInput, TABLE_BRAND, type TableConfig, type TablePoliciesInput, type TableRef, type ToManyOptions, type ToOneOptions, type ToPlatformUserOptions, type TypedSyncedTableConfig, VIEW_BRAND, type ViewConfig, type ViewPoliciesInput, type ViewQueryContext, type ViewSelectQuery, activeAuthoringContext, beginAuthoringContext, computeCanonicalHash, computeSyncedContractHash, custom, defineEnum, defineNamespace, defineResolvedTable, defineSyncedTable, defineTable, defineView, deriveColumnName, endAuthoringContext, etlSource, extractOrmSyncedTableContract, highest, isColumnBuilder, isEnumRef, isSeqLink, isSeqNamespaceConfig, isSeqTable, isSeqView, latest, loadNamespaceFromDir, lowest, managedFn, manualSource, nonNullFirst, objectRef, overlayWinsUnion, overrideRowMutation, prefetchSource, priority, revertOverlayMutation, serializeNamespace, syncedContractSurface, t, toMany, toOne, toPlatformUser, validateNamespaceCatalog };