@sequenceholdings/orm 0.1.2 → 0.1.3

package/dist/authoring.d.cts

@@ -1,4 +1,7 @@
-import { ColumnType, CanonicalColumn, CanonicalDefinition } from './canonical.cjs';
+import { ColumnType, CanonicalColumn, CanonicalDefinition, CanonicalTable } from './canonical.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';
 import 'zod';
 
 /**
@@ -80,10 +83,184 @@ declare const t: {
     readonly enum: (ref: EnumRef, columnName?: string) => ColumnBuilder;
 };
 
+/**
+ * Overlay identity for CoW helpers. Prefer a plain `{ tableName, columns }`
+ * descriptor when declaring `cowMutations` inside the same `defineTable` call
+ * (the `SeqTable` handle does not exist yet). A finished `SeqTable` also works.
+ */
+type OverlayTableRef<TColumns extends Record<string, ColumnBuilder> = Record<string, ColumnBuilder>> = {
+    readonly tableName: string;
+    readonly columns: Readonly<TColumns>;
+    /** Optional — used only when a finished `SeqTable` is passed. */
+    readonly config?: TableConfig;
+};
+/** Structured CoW mutation declaration — serialized into canonical `cowMutations`. */
+interface CowMutationInput {
+    kind: 'override' | 'revert';
+    /** Mutation name (snake identifier); the GraphQL field is its camelCase form. */
+    name: string;
+    /** Synced table (same namespace) the overlay copies from / falls back to. */
+    synced: string;
+    /** Single-column primary key property shared by overlay and synced. */
+    pk: string;
+    /** Override: contract properties copied INSERT…SELECT from synced (pk included). */
+    copy: readonly string[];
+    /** Override: overlay properties written by the UPDATE (never the pk). */
+    set: readonly string[];
+}
+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. */
+    synced: TSynced;
+    /**
+     * Property name of the single-column primary key shared by both tables.
+     * Must be the declared PK on overlay and synced.
+     */
+    pk: string & keyof TOverlay['columns'] & keyof TSynced['columns'];
+    /**
+     * Overlay property names that become required mutation arguments and are
+     * written by the UPDATE. Defaults to every non-PK column shared with the
+     * synced table. PK changes are always rejected.
+     */
+    set?: ReadonlyArray<string & keyof TOverlay['columns']>;
+    /** Mutation name. Defaults to `override_<overlay.tableName>`. */
+    name?: string;
+}
+interface RevertOverlayMutationInput<TOverlay extends OverlayTableRef = OverlayTableRef, TSynced extends SeqTable = SeqTable> {
+    /** Writable ORM overlay table (or `{ tableName, columns }` descriptor). */
+    overlay: TOverlay;
+    /**
+     * Read-only synced table — required so revert only deletes overrides that
+     * have a synced row to fall back to (never overlay-only creates).
+     */
+    synced: TSynced;
+    /**
+     * Property name of the single-column primary key shared by both tables.
+     * Must be the declared PK on overlay and synced.
+     */
+    pk: string & keyof TOverlay['columns'] & keyof TSynced['columns'];
+    /** Mutation name. Defaults to `revert_<overlay.tableName>`. */
+    name?: string;
+}
+/**
+ * Declares an explicit copy-on-write override mutation for an overlay table.
+ *
+ * Executes atomically in the data plane (both statements engine-generated):
+ * 1. `INSERT … SELECT` contract columns from synced, `ON CONFLICT (pk) DO NOTHING`
+ * 2. `UPDATE` overlay with the declared `set` arguments (PK pinned; gated on a
+ *    matching synced row; overlay write policy injected)
+ *
+ * Serializes into the overlay table's canonical `cowMutations`. Revert with
+ * {@link revertOverlayMutation}.
+ *
+ * ```ts
+ * const columns = { uid: t.uuid().primaryKey(), name: t.text().notNull(), balance: t.numeric() }
+ * defineTable('loan_overlay', columns, {
+ *   policies: { read: 'true', write: 'true' },
+ *   cowMutations: [
+ *     overrideRowMutation({
+ *       overlay: { tableName: 'loan_overlay', columns },
+ *       synced: syncedLoans,
+ *       pk: 'uid',
+ *       set: ['name', 'balance'],
+ *     }),
+ *     revertOverlayMutation({
+ *       overlay: { tableName: 'loan_overlay', columns },
+ *       synced: syncedLoans,
+ *       pk: 'uid',
+ *     }),
+ *   ],
+ * })
+ * ```
+ */
+declare function overrideRowMutation<TOverlay extends OverlayTableRef, TSynced extends SeqTable>(input: OverrideRowMutationInput<TOverlay, TSynced>): CowMutationInput;
+/**
+ * Declares a revert mutation that deletes an overlay override by PK so the
+ * coalesce view falls back to synced.
+ *
+ * The DELETE is gated on a matching synced row — overlay-only creates (or rows
+ * whose synced source disappeared) are not deleted by revert.
+ */
+declare function revertOverlayMutation<TOverlay extends OverlayTableRef, TSynced extends SeqTable>(input: RevertOverlayMutationInput<TOverlay, TSynced>): CowMutationInput;
+
+/**
+ * Managed regular-view authoring. A view keeps its GraphQL contract in the
+ * Sequence column/policy DSL, while its SELECT is authored with Drizzle and
+ * compiled to inert canonical SQL before crossing the CLI → Atlas boundary.
+ */
+
+declare const VIEW_BRAND: "seq-view";
+type ViewSelectQuery = TypedQueryBuilder<ColumnsSelection>;
+interface ViewQueryContext {
+    readonly qb: QueryBuilder;
+    relation<TRelation extends SeqTable | SeqView>(relation: TRelation | (() => TRelation)): DrizzleRelation<TRelation>;
+}
+interface ViewPoliciesInput {
+    read: PolicyInput;
+}
+interface ViewConfig {
+    description?: string;
+    /** Logical GraphQL identity only; PostgreSQL does not create a PK for a view. */
+    primaryKey?: readonly string[];
+    links?: Record<string, SeqLink>;
+    policies: ViewPoliciesInput;
+    query: (context: ViewQueryContext) => ViewSelectQuery;
+}
+interface SeqView<TColumns extends Record<string, ColumnBuilder> = Record<string, ColumnBuilder>> {
+    readonly kind: typeof VIEW_BRAND;
+    readonly viewName: string;
+    readonly columns: Readonly<TColumns>;
+    readonly config: ViewConfig;
+    readonly file: string | undefined;
+}
+type RelationColumnKeys<TRelation extends SeqTable | SeqView> = keyof TRelation['columns'] & string;
+/** Property-keyed Drizzle handle supplied by `relation(...)` inside a view query. */
+type DrizzleRelation<TRelation extends SeqTable | SeqView> = (TRelation extends SeqView ? PgView : PgTable) & Record<RelationColumnKeys<TRelation>, AnyPgColumn>;
+declare function isSeqView(value: unknown): value is SeqView;
+declare function defineView<const TColumns extends Record<string, ColumnBuilder>>(name: string, columns: TColumns, config: ViewConfig): SeqView<TColumns>;
+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. */
+    synced: TSynced;
+    /**
+     * Property name of the single-column primary key shared by both tables.
+     * Must be the declared PK on overlay and synced (`.primaryKey()` or
+     * `config.primaryKey`), not merely a unique/not-null column.
+     */
+    pk: string;
+    /**
+     * Property name of a non-null boolean tombstone column on the overlay table.
+     * When set, tombstoned overlay rows are excluded (and therefore suppress the
+     * matching synced row). Omit if the overlay table has no tombstone column.
+     */
+    tombstone?: string;
+}
+/**
+ * Builds the overlay-wins coalesce `query` callback for `defineView`.
+ *
+ * Row-level overlay wins: every overlay row (minus tombstones) appears with
+ * `provenance = 'overlay'`; every synced row whose PK is NOT present in the
+ * overlay appears with `provenance = 'synced'`.
+ *
+ * The returned callback is passed directly as `ViewConfig.query`.
+ *
+ * ```ts
+ * const view = defineView('unified_loans', columns, {
+ *   query: overlayWinsUnion({ overlay: loanOverlay, synced: syncedLoans, pk: 'uid' }),
+ *   policies: { read: 'true' },
+ * })
+ * ```
+ */
+declare function overlayWinsUnion<TOverlay extends SeqTable, TSynced extends SeqTable>(input: OverlayWinsUnionInput<TOverlay, TSynced>): ViewConfig['query'];
+
 declare const TABLE_BRAND: "seq-table";
 declare const LINK_BRAND: "seq-link";
-/** A link target: the table itself, or a lazy thunk for forward/cyclic references. */
-type TableRef = SeqTable | (() => SeqTable);
+/** 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 LinkKind = 'toOne' | 'toMany' | 'toPlatformUser';
 interface SeqLink {
     readonly kind: typeof LINK_BRAND;
@@ -134,7 +311,12 @@ interface PolicyWithVariantsInput {
 type PolicyInput = string | PolicyWithVariantsInput;
 interface TablePoliciesInput {
     read?: PolicyInput;
+    /** Legacy single policy for every write command; use insert/update when they differ. */
     write?: PolicyInput;
+    /** Insert WITH CHECK; falls back to write when omitted. */
+    insert?: PolicyInput;
+    /** Update USING + WITH CHECK; falls back to write when omitted. */
+    update?: PolicyInput;
 }
 interface IndexInput {
     /** Property names (camelCase) or Postgres column names. */
@@ -142,21 +324,6 @@ interface IndexInput {
     unique?: boolean;
     name?: string;
 }
-interface ActionParamInput {
-    type: ColumnType;
-    nullable?: boolean;
-}
-interface ActionInput {
-    name: string;
-    requires?: string;
-    params?: Record<string, ActionParamInput>;
-    executes: string;
-    returns?: 'rows' | 'rowsAffected' | 'scalar';
-    audit?: {
-        action: string;
-        resource: string;
-    };
-}
 interface TableConfig {
     description?: string;
     /** Table-level migration rename hint (new in v2). */
@@ -166,12 +333,18 @@ interface TableConfig {
     indexes?: readonly IndexInput[];
     links?: Record<string, SeqLink>;
     policies?: TablePoliciesInput;
-    actions?: readonly ActionInput[];
+    /**
+     * Copy-on-write mutations for overlay tables backed by a synced twin —
+     * declare with `overrideRowMutation` / `revertOverlayMutation`. v2 has no
+     * action surface: writes are mutations, and these compile to structured
+     * mutation roots whose SQL the engine generates.
+     */
+    cowMutations?: readonly CowMutationInput[];
 }
-interface SeqTable {
+interface SeqTable<TColumns extends Record<string, ColumnBuilder> = Record<string, ColumnBuilder>> {
     readonly kind: typeof TABLE_BRAND;
     readonly tableName: string;
-    readonly columns: Readonly<Record<string, ColumnBuilder>>;
+    readonly columns: Readonly<TColumns>;
     readonly config: TableConfig;
     /** Synced reflected source (`gold.*`) — set only by defineSyncedTable. */
     readonly source: string | undefined;
@@ -179,13 +352,36 @@ interface SeqTable {
     readonly file: string | undefined;
 }
 declare function isSeqTable(value: unknown): value is SeqTable;
-declare function defineTable(name: string, columns: Record<string, ColumnBuilder>, config?: TableConfig): SeqTable;
+declare function defineTable<const TColumns extends Record<string, ColumnBuilder>>(name: string, columns: TColumns, config?: TableConfig): SeqTable<TColumns>;
+interface SyncedTablePoliciesInput {
+    /** Claims-filtered read policy compiled onto the ORM materialization view. */
+    read?: PolicyInput;
+}
+/**
+ * Config for a read-only gold 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>`. */
     source: string;
     description?: string;
+    /** Composite primary key: property names (or column names). Mutually exclusive with column-level `.primaryKey()`. */
+    primaryKey?: readonly string[];
+    links?: Record<string, SeqLink>;
+    policies?: SyncedTablePoliciesInput;
 }
+/** @deprecated Alias — typed and untyped share SyncedTableConfig. */
+type TypedSyncedTableConfig = SyncedTableConfig;
+/**
+ * Untyped: schema-less synced table (columns discovered at apply time).
+ */
 declare function defineSyncedTable(name: string, config: SyncedTableConfig): SeqTable;
+/**
+ * Typed: synced table with explicit column declarations for use in view
+ * queries (e.g. overlay-wins coalesce). Columns are authored with `t.*`
+ * builders like regular tables; the table remains read-only.
+ */
+declare function defineSyncedTable<const TColumns extends Record<string, ColumnBuilder>>(name: string, columns: TColumns, config: SyncedTableConfig): SeqTable<TColumns>;
 declare function defineEnum(name: string, values: readonly string[]): EnumRef;
 
 declare const NAMESPACE_CONFIG_BRAND: "seq-namespace-config";
@@ -212,6 +408,7 @@ declare function defineNamespace(input: NamespaceConfigInput): SeqNamespaceConfi
 interface SerializeNamespaceInput {
     config: SeqNamespaceConfig;
     tables: readonly SeqTable[];
+    views?: readonly SeqView[];
     enums?: readonly EnumRef[];
 }
 /**
@@ -223,6 +420,73 @@ declare function serializeNamespace(input: SerializeNamespaceInput): CanonicalDe
 /** sha256 over the v1 hash domain + key-sorted JSON of the normalized canonical definition. */
 declare function computeCanonicalHash(definition: CanonicalDefinition): string;
 
+/** Domain separation so synced-contract hashes never collide with definition hashes. */
+declare const SYNCED_CONTRACT_HASH_DOMAIN = "sequence-orm-synced-contract\0";
+/**
+ * Pipeline-side ORM-mappable scalars. Inverse of pipeline-spec's
+ * `PIPELINE_TO_ORM_TYPE` — every ORM scalar has exactly one preimage.
+ */
+declare const ORM_TO_PIPELINE_TYPE: {
+    readonly uuid: "uuid";
+    readonly text: "string";
+    readonly integer: "int";
+    readonly bigint: "long";
+    readonly numeric: "numeric";
+    readonly double: "double";
+    readonly boolean: "boolean";
+    readonly timestamptz: "timestamp";
+    readonly date: "date";
+    readonly jsonb: "json";
+};
+type OrmToPipelineType = (typeof ORM_TO_PIPELINE_TYPE)[ColumnType];
+/**
+ * Column shape a serving projection / `checkCompatibility` consumer expects.
+ * Structurally aligned with pipeline-spec `Column` (type + nullable + key);
+ * intentionally local so `@sequenceholdings/orm` does not depend on
+ * `@sequenceholdings/pipeline-spec`.
+ */
+interface OrmContractPipelineColumn {
+    readonly type: OrmToPipelineType;
+    readonly nullable: boolean;
+    /** True when the column participates in the synced table primary key. */
+    readonly key: boolean;
+}
+type OrmContractColumnMap = Readonly<Record<string, OrmContractPipelineColumn>>;
+/** Published contract artifact for one typed synced table. */
+interface OrmSyncedTableContract {
+    readonly namespace: string;
+    readonly table: string;
+    /** Columns keyed by Postgres column name (pipeline identifier plane). */
+    readonly columns: OrmContractColumnMap;
+    /** Postgres column names, exact order from the canonical primary key. */
+    readonly primary_key: readonly string[];
+    /** sha256 hex of the contract-bearing surface (stable across cosmetic fields). */
+    readonly content_hash: string;
+}
+/**
+ * Contract-bearing surface hashed into `content_hash`. Descriptions, links,
+ * policies, and source string are intentionally excluded — they are not part
+ * of the projection↔ORM column contract.
+ */
+declare function syncedContractSurface({ namespace, table, columns, primary_key, }: {
+    namespace: string;
+    table: string;
+    columns: OrmContractColumnMap;
+    primary_key: readonly string[];
+}): Record<string, unknown>;
+declare function computeSyncedContractHash(surface: Record<string, unknown>): string;
+/**
+ * Extract the Managed Pipelines contract from a typed canonical synced table.
+ *
+ * Requires non-empty columns and a primary key (the typed `defineSyncedTable`
+ * authoring rules). Enum columns are rejected — they have no pipeline-type
+ * preimage in the ORM↔pipeline bijection.
+ */
+declare function extractOrmSyncedTableContract({ namespace, table, }: {
+    namespace: string;
+    table: CanonicalTable;
+}): OrmSyncedTableContract;
+
 declare const NAMESPACE_CONFIG_FILE = "sequence.config.ts";
 declare const SCHEMA_DIR = "schema";
 interface LoadNamespaceOptions {
@@ -243,7 +507,7 @@ declare function loadNamespaceFromDir(dir: string, options?: LoadNamespaceOption
 
 /**
  * Module-registry pattern for the authoring surface: `defineTable` /
- * `defineEnum` / `defineNamespace` register into the ACTIVE collection
+ * `defineView` / `defineEnum` / `defineNamespace` register into the ACTIVE collection
  * context while `loadNamespaceFromDir` imports a consumer's files, so the
  * loader collects definitions without inspecting module exports.
  *
@@ -262,6 +526,7 @@ interface AuthoringContext {
     /** Set by the loader before importing each consumer file — error attribution. */
     currentFile: string | undefined;
     readonly tables: AuthoringRegistration[];
+    readonly views: AuthoringRegistration[];
     readonly enums: AuthoringRegistration[];
     readonly configs: AuthoringRegistration[];
 }
@@ -271,4 +536,4 @@ declare function beginAuthoringContext(): AuthoringContext;
 declare function endAuthoringContext(context: AuthoringContext): void;
 declare function activeAuthoringContext(): AuthoringContext | undefined;
 
-export { type ActionInput, type ActionParamInput, type AuthoringContext, type AuthoringRegistration, COLUMN_BRAND, COLUMN_DEFAULT_FNS, ColumnBuilder, type ColumnDefaultFn, type ColumnDefaultLiteral, type ColumnTypeSpec, ENUM_BRAND, type EnumRef, type IndexInput, LINK_BRAND, type LinkKind, type LoadNamespaceOptions, type LoadedNamespaceV2, NAMESPACE_CONFIG_BRAND, NAMESPACE_CONFIG_FILE, type NamespaceCapabilitiesInput, type NamespaceConfigInput, type PolicyInput, type PolicyVariantInput, type PolicyWithVariantsInput, SCHEMA_DIR, type SeqLink, type SeqNamespaceConfig, type SeqTable, type SerializeNamespaceInput, type SyncedTableConfig, TABLE_BRAND, type TableConfig, type TablePoliciesInput, type TableRef, type ToManyOptions, type ToOneOptions, type ToPlatformUserOptions, activeAuthoringContext, beginAuthoringContext, computeCanonicalHash, defineEnum, defineNamespace, defineSyncedTable, defineTable, deriveColumnName, endAuthoringContext, isColumnBuilder, isEnumRef, isSeqLink, isSeqNamespaceConfig, isSeqTable, loadNamespaceFromDir, serializeNamespace, t, toMany, toOne, toPlatformUser };
+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 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 };