@prisma-next/sql-contract 0.14.0 → 0.15.0-dev.1

package/src/entity-handle-lowering-hook.ts

@@ -0,0 +1,104 @@
+/**
+ * SQL-family extension to the pack authoring contributions: a pack whose
+ * `entityTypes` registers entity kinds may implement a batch lowering hook
+ * that turns author-declared pack-entity handles (the generic `entities`
+ * list on the TS contract input) into `entries` rows.
+ *
+ * The generic contract build (`contract-ts`) owns the kind-agnostic walk: it
+ * groups handles by the pack that registered each `entityKind`, resolves
+ * each handle's declared model refs to storage table coordinates using the
+ * same model→table maps the relation lowering uses, and calls the owning
+ * pack's hook once with all of its claimed handles — batch, so the hook's
+ * diagnostics can see sibling handles. Neither the walk nor these types name
+ * any specific entity kind.
+ *
+ * SQL-family concept — the resolved-ref shape is a table coordinate, so the
+ * hook lives here beside {@link ../value-set-derivation-hook} instead of on
+ * the framework contributions type.
+ */
+
+/**
+ * An authored pack-entity handle: branded by the `entityKind` its owning
+ * pack registered, optionally declaring model refs under `refs` (actual
+ * model-handle objects, resolved by the generic walk before lowering).
+ */
+export interface PackEntityHandle {
+  readonly entityKind: string;
+  readonly refs?: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * A declared model ref after the generic walk resolved it: a storage table
+ * coordinate for a model of this contract, the coordinate plus `spaceId` for
+ * a cross-space (extensionModel) handle, or `unresolved` when the handle
+ * does not correspond to any model in the contract. `modelName` is carried
+ * for diagnostics where the handle declares one.
+ */
+export type ResolvedEntityHandleRef =
+  | {
+      readonly kind: 'resolved';
+      readonly namespaceId: string;
+      readonly tableName: string;
+      readonly modelName?: string;
+    }
+  | {
+      readonly kind: 'cross-space';
+      readonly spaceId: string;
+      readonly namespaceId: string;
+      readonly tableName: string;
+      readonly modelName?: string;
+    }
+  | {
+      readonly kind: 'unresolved';
+      readonly modelName?: string;
+    };
+
+/** One claimed handle paired with its resolved declared refs. */
+export interface ResolvedPackEntityHandle {
+  readonly handle: PackEntityHandle;
+  readonly refs: Readonly<Record<string, ResolvedEntityHandleRef>>;
+}
+
+export interface EntityHandleLoweringInput {
+  /** Every handle in the `entities` list whose `entityKind` this pack registered, in authored order. */
+  readonly handles: readonly ResolvedPackEntityHandle[];
+  readonly defaultNamespaceId: string;
+}
+
+/** One lowered entity row: filed into `storage.namespaces[namespaceId].entries[entityKind][key]`. */
+export interface LoweredPackEntity {
+  readonly namespaceId: string;
+  readonly entityKind: string;
+  readonly key: string;
+  readonly entity: unknown;
+}
+
+export interface SqlEntityHandleLoweringContribution {
+  /**
+   * Method syntax keeps the declaration bivariant, so a pack's concretely
+   * typed implementation stays structurally compatible (the same convention
+   * as `SqlValueSetDerivingEntityTypeOutput.deriveValueSet`).
+   */
+  lowerEntityHandles(input: EntityHandleLoweringInput): readonly LoweredPackEntity[];
+}
+
+/** Structural check for {@link SqlEntityHandleLoweringContribution}: no casts. */
+export function providesEntityHandleLowering(
+  authoring: unknown,
+): authoring is SqlEntityHandleLoweringContribution {
+  if (typeof authoring !== 'object' || authoring === null || !('lowerEntityHandles' in authoring)) {
+    return false;
+  }
+  const { lowerEntityHandles } = authoring;
+  return typeof lowerEntityHandles === 'function';
+}
+
+/**
+ * PSL-side twin of {@link ResolvedEntityHandleRef}: the family interpreter
+ * resolves an extension block's descriptor-declared model ref parameters
+ * (`{ kind: 'ref', refKind: 'model' }`) to storage table names and annotates
+ * the block with this map (keyed by parameter name) before invoking the
+ * entity factory. An unresolved required ref is the interpreter's
+ * diagnostic; a factory never sees one.
+ */
+export type ResolvedPslModelRefs = Readonly<Record<string, { readonly tableName: string }>>;

package/src/exports/contract-view.ts

@@ -0,0 +1,11 @@
+export type {
+  SqlBuiltinKind,
+  SqlSchemaQualifiedView,
+  SqlSingleNamespaceAccessors,
+  SqlSingleNamespaceView,
+} from '../contract-view';
+export {
+  buildSqlSchemaQualifiedView,
+  buildSqlSingleNamespaceView,
+  SQL_BUILTIN_KINDS,
+} from '../contract-view';

package/src/exports/entity-handle-lowering-hook.ts

@@ -0,0 +1,10 @@
+export {
+  type EntityHandleLoweringInput,
+  type LoweredPackEntity,
+  type PackEntityHandle,
+  providesEntityHandleLowering,
+  type ResolvedEntityHandleRef,
+  type ResolvedPackEntityHandle,
+  type ResolvedPslModelRefs,
+  type SqlEntityHandleLoweringContribution,
+} from '../entity-handle-lowering-hook';

package/src/exports/foreign-key-materialization.ts

@@ -0,0 +1,8 @@
+export {
+  type BackingIndexCandidates,
+  backingIndexColumnKeys,
+  type ForeignKeyAuthoringInput,
+  isBackedByColumnKeys,
+  type MaterializedTableConstraints,
+  materializeForeignKeysAndIndexes,
+} from '../foreign-key-materialization';

package/src/exports/types.ts

@@ -1,3 +1,7 @@
+export type {
+  StorageColumnMapAt,
+  StorageColumnTypeAcrossNamespaces,
+} from '../column-type-resolution';
 export type {
   CheckConstraintInput,
   CodecTypesOf,
@@ -6,6 +10,8 @@ export type {
   ExtractFieldInputTypes,
   ExtractFieldOutputTypes,
   ExtractQueryOperationTypes,
+  ExtractStorageColumnInputTypes,
+  ExtractStorageColumnTypes,
   ExtractTypeMapsFromContract,
   FieldInputTypesOf,
   FieldOutputTypesOf,
@@ -13,6 +19,8 @@ export type {
   ForeignKeyOptions,
   ForeignKeyReferenceInput,
   IndexInput,
+  NamespacedFieldTypeMap,
+  NamespacedStorageColumnTypeMap,
   PrimaryKeyInput,
   QueryOperationReturn,
   QueryOperationSelfSpec,
@@ -21,16 +29,20 @@ export type {
   QueryOperationTypesOf,
   ReferentialAction,
   ResolveCodecTypes,
+  SqlAuthoringContributions,
   SqlControlDriverInstance,
   SqlModelFieldStorage,
   SqlModelStorage,
   SqlNamespace,
   SqlNamespaceEntries,
-  SqlNamespaceTablesInput,
+  SqlNamespaceFactory,
+  SqlNamespaceInput,
   SqlQueryOperationTypes,
   SqlStorageInput,
   SqlStorageTypeEntry,
   StorageColumnInput,
+  StorageColumnInputTypesOf,
+  StorageColumnTypesOf,
   StorageTableInput,
   StorageTypeInstance,
   StorageTypeInstanceInput,
@@ -41,8 +53,6 @@ export type {
 } from '../types';
 export {
   applyFkDefaults,
-  buildSqlNamespace,
-  buildSqlNamespaceMap,
   CheckConstraint,
   CODEC_INSTANCE_KIND,
   DEFAULT_FK_CONSTRAINT,
@@ -50,11 +60,14 @@ export {
   ForeignKey,
   ForeignKeyReference,
   Index,
+  isMaterializedSqlNamespace,
+  isSqlAuthoringContributions,
   isStorageTypeInstance,
+  isStorageValueSet,
   PrimaryKey,
+  SqlNamespaceBase,
   SqlNode,
   SqlStorage,
-  SqlUnboundNamespace,
   StorageColumn,
   StorageTable,
   StorageValueSet,

package/src/exports/value-set-derivation-hook.ts

@@ -0,0 +1,2 @@
+export type { SqlValueSetDerivingEntityTypeOutput } from '../value-set-derivation-hook';
+export { deriveValueSetFromEntity, providesValueSetDerivation } from '../value-set-derivation-hook';

package/src/factories.ts

@@ -1,7 +1,6 @@
 import { asNamespaceId, type ScalarFieldType } from '@prisma-next/contract/types';
 import { UNBOUND_NAMESPACE_ID } from '@prisma-next/framework-components/ir';
 import {
-  applyFkDefaults,
   ForeignKey,
   type ForeignKeyOptions,
   Index,
@@ -14,8 +13,18 @@ import {
   UniqueConstraint,
 } from './types';
 
-export function col(nativeType: string, codecId: string, nullable = false): StorageColumn {
-  return new StorageColumn({ nativeType, codecId, nullable });
+export function col(
+  nativeType: string,
+  codecId: string,
+  nullable = false,
+  opts?: { readonly many?: boolean },
+): StorageColumn {
+  return new StorageColumn({
+    nativeType,
+    codecId,
+    nullable,
+    ...(opts?.many !== undefined && { many: opts.many }),
+  });
 }
 
 export function pk(...columns: readonly string[]): PrimaryKey {
@@ -35,9 +44,8 @@ export function fk(
   srcColumns: readonly string[],
   targetTableName: string,
   targetColumns: readonly string[],
-  opts?: ForeignKeyOptions & { constraint?: boolean; index?: boolean; namespaceId?: string },
+  opts?: ForeignKeyOptions & { namespaceId?: string },
 ): ForeignKey {
-  const defaults = applyFkDefaults({ constraint: opts?.constraint, index: opts?.index });
   const namespaceId = asNamespaceId(opts?.namespaceId ?? UNBOUND_NAMESPACE_ID);
   return new ForeignKey({
     source: { namespaceId, tableName: srcTableName, columns: srcColumns },
@@ -45,8 +53,6 @@ export function fk(
     ...(opts?.name !== undefined && { name: opts.name }),
     ...(opts?.onDelete !== undefined && { onDelete: opts.onDelete }),
     ...(opts?.onUpdate !== undefined && { onUpdate: opts.onUpdate }),
-    constraint: defaults.constraint,
-    index: defaults.index,
   });
 }
 

package/src/foreign-key-materialization.ts

@@ -0,0 +1,107 @@
+import { defaultIndexName } from '@prisma-next/sql-schema-ir/naming';
+import type { ForeignKeyInput, ReferentialAction } from './ir/foreign-key';
+import type { ForeignKeyReferenceInput } from './ir/foreign-key-reference';
+import type { PrimaryKeyInput } from './ir/primary-key';
+import type { IndexInput } from './ir/sql-index';
+import type { UniqueConstraintInput } from './ir/unique-constraint';
+
+export type BackingIndexCandidates = {
+  readonly indexes: readonly { readonly columns: readonly string[] }[];
+  readonly uniques: readonly { readonly columns: readonly string[] }[];
+  readonly primaryKey?: { readonly columns: readonly string[] } | undefined;
+};
+
+/**
+ * The column-list keys (`"colA,colB"`, order preserved) a table's own
+ * indexes, unique constraints, and primary key already back. A foreign key
+ * whose source columns join to one of these keys needs no separately
+ * derived backing index.
+ *
+ * Shared by {@link isBackedByColumnKeys}'s callers: `materializeForeignKeysAndIndexes`
+ * (deriving the discrete backing-index entities persisted at `contract emit`)
+ * and the postgres PSL inferrer (deciding whether an introspected relation
+ * needs an explicit `index: false`).
+ */
+export function backingIndexColumnKeys(table: BackingIndexCandidates): readonly string[] {
+  return [
+    ...table.indexes.map((index) => index.columns.join(',')),
+    ...table.uniques.map((unique) => unique.columns.join(',')),
+    ...(table.primaryKey ? [table.primaryKey.columns.join(',')] : []),
+  ];
+}
+
+/**
+ * Whether `columns`, in order, matches one of `backingKeys` (see
+ * {@link backingIndexColumnKeys}). Order-sensitive: `(a, b)` does not
+ * satisfy a backing index declared as `(b, a)`.
+ */
+export function isBackedByColumnKeys(
+  columns: readonly string[],
+  backingKeys: readonly string[],
+): boolean {
+  return backingKeys.includes(columns.join(','));
+}
+
+/**
+ * A foreign key as authored, before FK1 materialization: the referential
+ * coordinates plus the `constraint`/`index` intent booleans that drive
+ * whether — and how — it survives into the persisted contract.
+ */
+export interface ForeignKeyAuthoringInput {
+  readonly source: ForeignKeyReferenceInput;
+  readonly target: ForeignKeyReferenceInput;
+  readonly name?: string;
+  readonly onDelete?: ReferentialAction;
+  readonly onUpdate?: ReferentialAction;
+  readonly constraint: boolean;
+  readonly index: boolean;
+}
+
+export interface MaterializedTableConstraints {
+  readonly foreignKeys: readonly ForeignKeyInput[];
+  readonly indexes: readonly IndexInput[];
+}
+
+/**
+ * Lowers a table's authored foreign keys into the discrete entities
+ * `contract.json` persists: a `constraint: false` FK contributes no
+ * `foreignKeys[]` entry, and an `index: true` FK whose columns aren't already
+ * backed by a declared index/unique/primary-key contributes a named
+ * `indexes[]` entry (`defaultIndexName`). Declared indexes always survive
+ * unchanged; a second FK sharing already-synthesized backing columns does not
+ * mint a duplicate index.
+ */
+export function materializeForeignKeysAndIndexes(
+  tableName: string,
+  foreignKeys: readonly ForeignKeyAuthoringInput[],
+  declaredIndexes: readonly IndexInput[],
+  uniques: readonly UniqueConstraintInput[],
+  primaryKey: PrimaryKeyInput | undefined,
+): MaterializedTableConstraints {
+  const satisfiedIndexColumns = new Set(
+    backingIndexColumnKeys({ indexes: declaredIndexes, uniques, primaryKey }),
+  );
+  const synthesizedIndexes: IndexInput[] = [];
+  const materializedForeignKeys: ForeignKeyInput[] = [];
+
+  for (const { constraint, index, ...reference } of foreignKeys) {
+    if (constraint !== false) {
+      materializedForeignKeys.push(reference);
+    }
+    if (index !== false) {
+      const key = reference.source.columns.join(',');
+      if (!satisfiedIndexColumns.has(key)) {
+        synthesizedIndexes.push({
+          columns: reference.source.columns,
+          name: defaultIndexName(tableName, reference.source.columns),
+        });
+        satisfiedIndexColumns.add(key);
+      }
+    }
+  }
+
+  return {
+    foreignKeys: materializedForeignKeys,
+    indexes: [...declaredIndexes, ...synthesizedIndexes],
+  };
+}

package/src/ir/foreign-key.ts

@@ -10,14 +10,18 @@ export interface ForeignKeyInput {
   readonly name?: string;
   readonly onDelete?: ReferentialAction;
   readonly onUpdate?: ReferentialAction;
-  /** Whether to emit FK constraint DDL (ALTER TABLE … ADD CONSTRAINT … FOREIGN KEY). */
-  readonly constraint: boolean;
-  /** Whether to emit a backing index for the FK columns. */
-  readonly index: boolean;
 }
 
 /**
- * SQL Contract IR node for a table-level foreign-key declaration.
+ * SQL Contract IR node for a table-level foreign-key declaration — the
+ * referential constraint only (source, target, `onDelete`/`onUpdate`).
+ *
+ * A persisted `foreignKeys[]` entry always denotes a real constraint: whether
+ * to emit the constraint at all, and whether to back it with an index, are
+ * authoring-time decisions (PSL `@relation(index:)`, TS `fk({ constraint,
+ * index })`) resolved once at `contract emit` — a `constraint: false` FK
+ * simply has no entry here, and a backing index (if any) is its own discrete,
+ * named entry in the table's `indexes[]`.
  *
  * Each FK carries explicit `source` and `target` {@link ForeignKeyReference}
  * coordinates (namespace, table, columns). For single-namespace contracts the
@@ -31,8 +35,6 @@ export interface ForeignKeyInput {
 export class ForeignKey extends SqlNode {
   readonly source: ForeignKeyReference;
   readonly target: ForeignKeyReference;
-  readonly constraint: boolean;
-  readonly index: boolean;
   declare readonly name?: string;
   declare readonly onDelete?: ReferentialAction;
   declare readonly onUpdate?: ReferentialAction;
@@ -47,8 +49,6 @@ export class ForeignKey extends SqlNode {
       input.target instanceof ForeignKeyReference
         ? input.target
         : new ForeignKeyReference(input.target);
-    this.constraint = input.constraint;
-    this.index = input.index;
     if (input.name !== undefined) this.name = input.name;
     if (input.onDelete !== undefined) this.onDelete = input.onDelete;
     if (input.onUpdate !== undefined) this.onUpdate = input.onUpdate;

package/src/ir/sql-storage.ts

@@ -1,5 +1,12 @@
 import type { StorageHashBase } from '@prisma-next/contract/types';
-import { freezeNode, type Namespace, type Storage } from '@prisma-next/framework-components/ir';
+import type { AuthoringContributions } from '@prisma-next/framework-components/authoring';
+import {
+  freezeNode,
+  isPlainRecord,
+  type Namespace,
+  NamespaceBase,
+  type Storage,
+} from '@prisma-next/framework-components/ir';
 import { SqlNode } from './sql-node';
 import type { StorageTable } from './storage-table';
 import {
@@ -19,15 +26,45 @@ import type { StorageValueSet } from './storage-value-set';
  */
 export type SqlStorageTypeEntry = StorageTypeInstance | StorageTypeInstanceInput;
 
-export interface SqlNamespaceTablesInput {
+export interface SqlNamespaceInput {
   readonly id: string;
   readonly entries: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
 }
 
+/**
+ * Target-supplied factory that materializes a `Namespace` from a SQL
+ * `SqlNamespaceInput` (used to populate `SqlStorage.namespaces`).
+ */
+export type SqlNamespaceFactory = (input: SqlNamespaceInput) => Namespace;
+
+/**
+ * SQL-family extension of the framework `AuthoringContributions`. SQL target
+ * packs add a `createNamespace` factory so the PSL/TS authoring paths can
+ * materialize namespaces (and merge lowered extension-block entities) without
+ * each consumer re-specifying it. The factory is SQL-specific, so it lives here
+ * rather than on the framework `AuthoringContributions` base.
+ */
+export interface SqlAuthoringContributions extends AuthoringContributions {
+  readonly createNamespace?: SqlNamespaceFactory;
+}
+
+/**
+ * Narrows framework `AuthoringContributions` to the SQL-family shape by testing
+ * for the SQL-specific `createNamespace` capability.
+ */
+export function isSqlAuthoringContributions(
+  authoring: AuthoringContributions | undefined,
+): authoring is SqlAuthoringContributions {
+  if (authoring === undefined || !Object.hasOwn(authoring, 'createNamespace')) {
+    return false;
+  }
+  return typeof Reflect.get(authoring, 'createNamespace') === 'function';
+}
+
 export interface SqlStorageInput<THash extends string = string> {
   readonly storageHash: StorageHashBase<THash>;
   readonly types?: Record<string, SqlStorageTypeEntry>;
-  readonly namespaces: Readonly<Record<string, SqlNamespace>>;
+  readonly namespaces: Readonly<Record<string, SqlNamespaceBase>>;
 }
 
 /**
@@ -63,22 +100,49 @@ export type SqlNamespaceEntries = Readonly<Record<string, Readonly<Record<string
 };
 
 /**
- * SQL family namespace. `entries` is the open ADR 224 dictionary —
- * `entries[entityKind][entityName]` addresses any entity. Emitted
- * contract literals satisfy this structurally (no prototype getters
- * needed). For typed access to specific kinds, use the class getters
- * on the concretion or `ns.entries.table` / `ns.entries.valueSet` directly.
+ * Structural interface for SQL family namespaces. Generated `.d.ts` contract
+ * types satisfy this structurally (no prototype methods). The runtime
+ * abstract class `SqlNamespaceBase` extends this.
+ *
+ * `qualifyTable` and `isUnbound` are optional so JSON-shaped contract types
+ * (which carry no methods) are accepted where `SqlNamespace` is required.
+ * Hydrated `SqlNamespaceBase` instances always have both.
  */
-export type SqlNamespace = Namespace & {
+export interface SqlNamespace {
+  readonly kind: string;
+  readonly id: string;
   readonly entries: SqlNamespaceEntries;
-  /**
-   * Render a dialect-qualified table reference for runtime SQL emission.
-   * Present on materialised target concretions (`PostgresSchema`,
-   * `SqliteDatabase`, …) and family placeholders; omitted on emitted
-   * contract structural namespace literals (methods are not serialised).
-   */
+  readonly isUnbound?: boolean;
   qualifyTable?(tableName: string): string;
-};
+}
+
+/**
+ * Abstract SQL family namespace base class. Target concretions (`PostgresSchema`,
+ * `SqliteDatabase`, …) extend this — it is never instantiated directly.
+ * `entries` is the open ADR 224 dictionary: `entries[entityKind][entityName]`
+ * addresses any entity.
+ */
+export abstract class SqlNamespaceBase extends NamespaceBase implements SqlNamespace {
+  abstract override readonly id: string;
+  abstract override readonly entries: SqlNamespaceEntries;
+
+  abstract qualifyTable(tableName: string): string;
+}
+
+/**
+ * Realm-safe guard for hydrated `SqlNamespaceBase` concretions. Checks
+ * `qualifyTable` structurally instead of `instanceof NamespaceBase`, so it
+ * survives duplicate-module boundaries (e.g. dist e2e where the target and
+ * the family carry separate copies of `@prisma-next/framework-components`).
+ *
+ * Every concrete `SqlNamespaceBase` subclass (`PostgresSchema`, `SqliteDatabase`,
+ * `TestSqlNamespace`, …) implements `qualifyTable`. Raw `SqlNamespaceInput`
+ * objects (`{ id, entries }`) do not.
+ */
+export function isMaterializedSqlNamespace(x: unknown): x is SqlNamespaceBase {
+  if (typeof x !== 'object' || x === null || !('qualifyTable' in x)) return false;
+  return typeof x.qualifyTable === 'function';
+}
 
 export class SqlStorage<THash extends string = string> extends SqlNode implements Storage {
   readonly storageHash: StorageHashBase<THash>;
@@ -128,7 +192,7 @@ function normaliseTypeEntry(name: string, entry: SqlStorageTypeEntry): StorageTy
     }
     return toStorageTypeInstance(entry);
   }
-  const rawKind = (entry as { kind?: unknown }).kind;
+  const rawKind = isPlainRecord(entry) ? entry['kind'] : undefined;
   const kindDescription =
     rawKind === undefined
       ? 'missing `kind` discriminator'

package/src/ir/storage-column.ts

@@ -16,6 +16,7 @@ export interface StorageColumnInput {
   readonly nativeType: string;
   readonly codecId: string;
   readonly nullable: boolean;
+  readonly many?: boolean;
   readonly typeParams?: Record<string, unknown>;
   readonly typeRef?: string;
   readonly default?: ColumnDefault;
@@ -40,6 +41,7 @@ export class StorageColumn extends SqlNode {
   readonly nativeType: string;
   readonly codecId: string;
   readonly nullable: boolean;
+  declare readonly many?: boolean;
   declare readonly typeParams?: Record<string, unknown>;
   declare readonly typeRef?: string;
   declare readonly default?: ColumnDefault;
@@ -51,6 +53,7 @@ export class StorageColumn extends SqlNode {
     this.nativeType = input.nativeType;
     this.codecId = input.codecId;
     this.nullable = input.nullable;
+    if (input.many !== undefined) this.many = input.many;
     if (input.typeParams !== undefined) this.typeParams = input.typeParams;
     if (input.typeRef !== undefined) this.typeRef = input.typeRef;
     if (input.default !== undefined) this.default = input.default;

package/src/ir/storage-entry-schemas.ts

@@ -39,6 +39,7 @@ const StorageColumnSchema = type({
   nativeType: 'string',
   codecId: 'string',
   nullable: 'boolean',
+  'many?': 'boolean',
   'typeParams?': 'Record<string, unknown>',
   'typeRef?': 'string',
   'default?': ColumnDefaultSchema,
@@ -105,8 +106,6 @@ export const ForeignKeySchema = type.declare<ForeignKeyInput>().type({
   'name?': 'string',
   'onDelete?': ReferentialActionSchema,
   'onUpdate?': ReferentialActionSchema,
-  constraint: 'boolean',
-  index: 'boolean',
 });
 
 export const CheckConstraintSchema = type({

package/src/ir/storage-table.ts

@@ -68,4 +68,25 @@ export class StorageTable extends SqlNode {
     }
     freezeNode(this);
   }
+
+  /**
+   * Runtime guard that a namespace `table` entry is really a `StorageTable`.
+   * The compiler already types the entry as `StorageTable`, but a
+   * freshly-deserialized contract may carry plain JSON at that slot until
+   * hydration; this duck-types the structural shape. Accepts `undefined` so
+   * optional-chained entry lookups pass straight through.
+   */
+  static is(value: StorageTable | undefined): value is StorageTable {
+    if (typeof value !== 'object' || value === null) return false;
+    return 'columns' in value && 'uniques' in value && 'indexes' in value && 'foreignKeys' in value;
+  }
+
+  static assert(
+    value: StorageTable | undefined,
+    coordinate: string,
+  ): asserts value is StorageTable {
+    if (!StorageTable.is(value)) {
+      throw new Error(`Expected a StorageTable at ${coordinate}`);
+    }
+  }
 }

package/src/ir/storage-value-set.ts

@@ -41,3 +41,8 @@ export class StorageValueSet extends SqlNode {
     freezeNode(this);
   }
 }
+
+export function isStorageValueSet(value: unknown): value is StorageValueSet {
+  if (typeof value !== 'object' || value === null) return false;
+  return 'kind' in value && value.kind === 'valueSet' && 'values' in value;
+}