@sequenceholdings/orm 0.1.2 → 0.1.3

package/dist/authoring.cjs

@@ -1,5 +1,7 @@
 'use strict';
 
+var drizzleOrm = require('drizzle-orm');
+var pgCore = require('drizzle-orm/pg-core');
 var crypto = require('crypto');
 var zod = require('zod');
 var jiti = require('jiti');
@@ -66,8 +68,8 @@ var ColumnBuilder = class {
     this.state.defaultFn = void 0;
     return this;
   }
-  description(text) {
-    this.state.description = text;
+  description(text2) {
+    this.state.description = text2;
     return this;
   }
   /** Migration rename hint: the previous Postgres column name. */
@@ -162,7 +164,7 @@ function contextStack() {
   return created;
 }
 function beginAuthoringContext() {
-  const context = { currentFile: void 0, tables: [], enums: [], configs: [] };
+  const context = { currentFile: void 0, tables: [], views: [], enums: [], configs: [] };
   contextStack().push(context);
   return context;
 }
@@ -186,6 +188,9 @@ function register(bucket, value) {
 function registerTable(value) {
   register("tables", value);
 }
+function registerView(value) {
+  register("views", value);
+}
 function registerEnum(value) {
   register("enums", value);
 }
@@ -273,20 +278,69 @@ function defineTable(name, columns, config = {}) {
   registerTable(table);
   return table;
 }
-function defineSyncedTable(name, config) {
+function defineSyncedTable(name, columnsOrConfig, maybeConfig) {
   const file = activeAuthoringContext()?.currentFile;
   assertIdentifier({ value: name, what: "table name", file });
+  const isTyped = maybeConfig !== void 0;
+  const columns = isTyped ? columnsOrConfig : {};
+  const config = isTyped ? maybeConfig : columnsOrConfig;
   if (!SYNCED_SOURCE_PATTERN.test(config.source)) {
     throw new OrmDefinitionError(
       `synced table "${name}": source "${config.source}" must match ${SYNCED_SOURCE_PATTERN} (gold layer only)`,
       file
     );
   }
+  const entries = Object.entries(columns);
+  const seenColumnNames = /* @__PURE__ */ new Map();
+  const columnLevelPk = [];
+  for (const [propertyName, builder] of entries) {
+    if (!isColumnBuilder(builder)) {
+      throw new OrmDefinitionError(
+        `synced table "${name}": column "${propertyName}" is not a column builder \u2014 use the t.* factories (t.uuid(), t.text(), \u2026)`,
+        file
+      );
+    }
+    const columnName = builder.columnNameFor(propertyName);
+    assertIdentifier({
+      value: columnName,
+      what: `synced table "${name}": column "${propertyName}" column name`,
+      file
+    });
+    const existing = seenColumnNames.get(columnName);
+    if (existing !== void 0) {
+      throw new OrmDefinitionError(
+        `synced table "${name}": columns "${existing}" and "${propertyName}" both map to Postgres column "${columnName}"`,
+        file
+      );
+    }
+    seenColumnNames.set(columnName, propertyName);
+    if (builder.isPrimaryKey) columnLevelPk.push(propertyName);
+  }
+  if (entries.length > 0) {
+    const hasConfigPk = config.primaryKey !== void 0 && config.primaryKey.length > 0;
+    if (columnLevelPk.length === 0 && !hasConfigPk) {
+      throw new OrmDefinitionError(
+        `synced table "${name}" declares columns but no primary key \u2014 use .primaryKey() or config.primaryKey`,
+        file
+      );
+    }
+    if (columnLevelPk.length > 0 && hasConfigPk) {
+      throw new OrmDefinitionError(
+        `synced table "${name}": declare the primary key either with .primaryKey() on columns or with config.primaryKey \u2014 not both`,
+        file
+      );
+    }
+  }
+  const tableConfig = {};
+  if (config.description !== void 0) tableConfig.description = config.description;
+  if (config.primaryKey !== void 0) tableConfig.primaryKey = config.primaryKey;
+  if (config.links !== void 0) tableConfig.links = config.links;
+  if (config.policies !== void 0) tableConfig.policies = { read: config.policies.read };
   const table = {
     kind: TABLE_BRAND,
     tableName: name,
-    columns: {},
-    config: config.description !== void 0 ? { description: config.description } : {},
+    columns,
+    config: tableConfig,
     source: config.source,
     file
   };
@@ -316,6 +370,475 @@ function defineEnum(name, values) {
   registerEnum(ref);
   return ref;
 }
+var VIEW_BRAND = "seq-view";
+function isSeqView(value) {
+  return typeof value === "object" && value !== null && value.kind === VIEW_BRAND;
+}
+function defineView(name, columns, config) {
+  const file = activeAuthoringContext()?.currentFile;
+  if (!IDENTIFIER_PATTERN.test(name) || name.length > MAX_IDENTIFIER_LENGTH) {
+    throw new OrmDefinitionError(
+      `view name "${name}" must match ${IDENTIFIER_PATTERN} and be at most ${MAX_IDENTIFIER_LENGTH} characters`,
+      file
+    );
+  }
+  const entries = Object.entries(columns);
+  if (entries.length === 0) throw new OrmDefinitionError(`view "${name}" declares no columns`, file);
+  const seenColumnNames = /* @__PURE__ */ new Map();
+  for (const [propertyName, builder] of entries) {
+    if (!isColumnBuilder(builder)) {
+      throw new OrmDefinitionError(
+        `view "${name}": column "${propertyName}" is not a column builder \u2014 use the t.* factories`,
+        file
+      );
+    }
+    const columnName = builder.columnNameFor(propertyName);
+    if (!IDENTIFIER_PATTERN.test(columnName) || columnName.length > MAX_IDENTIFIER_LENGTH) {
+      throw new OrmDefinitionError(`view "${name}": column "${propertyName}" has invalid column name "${columnName}"`, file);
+    }
+    const existing = seenColumnNames.get(columnName);
+    if (existing !== void 0) {
+      throw new OrmDefinitionError(
+        `view "${name}": columns "${existing}" and "${propertyName}" both map to Postgres column "${columnName}"`,
+        file
+      );
+    }
+    seenColumnNames.set(columnName, propertyName);
+  }
+  const view = { kind: VIEW_BRAND, viewName: name, columns, config, file };
+  registerView(view);
+  return view;
+}
+var QUERY_COLUMN_FACTORIES = {
+  uuid: (name) => pgCore.uuid(name),
+  text: (name) => pgCore.text(name),
+  integer: (name) => pgCore.integer(name),
+  bigint: (name) => pgCore.bigint(name, { mode: "bigint" }),
+  numeric: (name) => pgCore.numeric(name),
+  double: (name) => pgCore.doublePrecision(name),
+  boolean: (name) => pgCore.boolean(name),
+  timestamptz: (name) => pgCore.timestamp(name, { withTimezone: true }),
+  date: (name) => pgCore.date(name),
+  jsonb: (name) => pgCore.jsonb(name)
+};
+function compileViewQueries(input) {
+  const schemaName = `orm_${input.namespace}`;
+  const schema = pgCore.pgSchema(schemaName);
+  const enumFactories = /* @__PURE__ */ new Map();
+  for (const entry of input.enums) {
+    const values = entry.values;
+    enumFactories.set(entry.name, schema.enum(entry.name, values));
+  }
+  const handles = /* @__PURE__ */ new Map();
+  const physicalToLogical = /* @__PURE__ */ new Map();
+  const tableByName = new Map(input.tables.map((table) => [table.table, table]));
+  for (const authored of input.authoredTables) {
+    const canonical = tableByName.get(authored.tableName);
+    if (!canonical) continue;
+    const physicalSchema = schemaName;
+    const physicalName = canonical.table;
+    const relationSchema = pgCore.pgSchema(physicalSchema);
+    const columns = buildQueryColumns(canonical.columns, enumFactories);
+    const handle = relationSchema.table(physicalName, columns);
+    handles.set(authored, handle);
+    physicalToLogical.set(`${physicalSchema}.${physicalName}`, canonical.table);
+  }
+  const viewByName = new Map(input.views.map((view) => [view.view, view]));
+  for (const authored of input.authoredViews) {
+    const canonical = viewByName.get(authored.viewName);
+    if (!canonical) continue;
+    const columns = buildQueryColumns(canonical.columns, enumFactories);
+    const handle = schema.view(canonical.view, columns).existing();
+    handles.set(authored, handle);
+    physicalToLogical.set(`${schemaName}.${canonical.view}`, canonical.view);
+  }
+  const dialect = new pgCore.PgDialect();
+  const compiled = /* @__PURE__ */ new Map();
+  for (const authored of input.authoredViews) {
+    const expectedFields = Object.keys(authored.columns);
+    const declaredDependencies = /* @__PURE__ */ new Set();
+    const relation = (ref) => {
+      let resolved;
+      try {
+        resolved = typeof ref === "function" ? ref() : ref;
+      } catch (error) {
+        throw new OrmDefinitionError(
+          `view "${authored.viewName}" relation thunk threw: ${error instanceof Error ? error.message : String(error)}`,
+          authored.file
+        );
+      }
+      if (!isSeqTable(resolved) && !isSeqView(resolved)) {
+        throw new OrmDefinitionError(
+          `view "${authored.viewName}" relation() expects a table or view defined by this ORM`,
+          authored.file
+        );
+      }
+      const handle = handles.get(resolved);
+      if (!handle) {
+        const name = isSeqTable(resolved) ? resolved.tableName : resolved.viewName;
+        throw new OrmDefinitionError(
+          `view "${authored.viewName}" references relation "${name}" which is not part of this namespace`,
+          authored.file
+        );
+      }
+      declaredDependencies.add(isSeqTable(resolved) ? resolved.tableName : resolved.viewName);
+      return handle;
+    };
+    let queryBuilder;
+    try {
+      queryBuilder = authored.config.query({ qb: new pgCore.QueryBuilder(), relation });
+    } catch (error) {
+      if (error instanceof OrmDefinitionError) throw error;
+      throw new OrmDefinitionError(
+        `view "${authored.viewName}" query callback failed: ${error instanceof Error ? error.message : String(error)}`,
+        authored.file
+      );
+    }
+    let config;
+    try {
+      config = pgCore.getViewConfig(schema.view(authored.viewName).as(queryBuilder));
+    } catch (error) {
+      throw new OrmDefinitionError(
+        `view "${authored.viewName}" query must return a Drizzle select builder: ${error instanceof Error ? error.message : String(error)}`,
+        authored.file
+      );
+    }
+    const selectedFields = Object.keys(config.selectedFields);
+    if (selectedFields.length !== expectedFields.length || selectedFields.some((field, index) => field !== expectedFields[index])) {
+      throw new OrmDefinitionError(
+        `view "${authored.viewName}" query selects [${selectedFields.join(", ")}], but declared columns are [${expectedFields.join(", ")}]`,
+        authored.file
+      );
+    }
+    if (!config.query) throw new OrmDefinitionError(`view "${authored.viewName}" produced no query`, authored.file);
+    const tableDependencies = pgCore.extractUsedTable(config.query).map((physical) => {
+      const logical = physicalToLogical.get(physical);
+      if (!logical) {
+        throw new OrmDefinitionError(
+          `view "${authored.viewName}" query references unmanaged relation "${physical}" \u2014 use relation(...) with a namespace table or view`,
+          authored.file
+        );
+      }
+      return logical;
+    });
+    const renderedQuery = dialect.sqlToQuery(config.query.inlineParams());
+    if (renderedQuery.params.length > 0) {
+      throw new OrmDefinitionError(
+        `view "${authored.viewName}" query produced bind parameters which cannot be persisted in view DDL`,
+        authored.file
+      );
+    }
+    compiled.set(authored.viewName, {
+      query: renderedQuery.sql,
+      dependencies: [.../* @__PURE__ */ new Set([...declaredDependencies, ...tableDependencies])].sort()
+    });
+  }
+  return compiled;
+}
+function buildQueryColumns(columns, enumFactories) {
+  return Object.fromEntries(columns.map((column) => [column.name, buildQueryColumn(column, enumFactories)]));
+}
+function buildQueryColumn(column, enumFactories) {
+  const factory = typeof column.type === "string" ? QUERY_COLUMN_FACTORIES[column.type] : enumFactories.get(column.type.enum);
+  if (!factory) {
+    const type = typeof column.type === "string" ? column.type : column.type.enum;
+    throw new OrmDefinitionError(`view query column '${column.columnName}' references unknown type '${type}'`);
+  }
+  let builder = factory(column.columnName);
+  if (!column.nullable) builder = builder.notNull();
+  return builder;
+}
+function relationName(relation) {
+  return isSeqTable(relation) ? relation.tableName : relation.viewName;
+}
+function relationKind(relation) {
+  return isSeqTable(relation) ? "table" : "view";
+}
+function declaredPrimaryKeyProperties(table) {
+  const fromColumns = Object.entries(table.columns).filter(([, builder]) => builder.isPrimaryKey).map(([propertyName]) => propertyName);
+  if (fromColumns.length > 0) return fromColumns;
+  const configPk = table.config.primaryKey ?? [];
+  const resolved = [];
+  for (const ref of configPk) {
+    if (ref in table.columns) {
+      resolved.push(ref);
+      continue;
+    }
+    const byColumnName = Object.entries(table.columns).find(
+      ([propertyName, builder]) => builder.columnNameFor(propertyName) === ref
+    );
+    if (byColumnName) resolved.push(byColumnName[0]);
+  }
+  return resolved;
+}
+function assertOverlayWinsPrimaryKey({
+  table,
+  pk,
+  role
+}) {
+  if (!(pk in table.columns)) {
+    throw new OrmDefinitionError(
+      `overlayWinsUnion: pk "${pk}" must exist as a property on both overlay and synced tables`
+    );
+  }
+  const declared = declaredPrimaryKeyProperties(table);
+  if (declared.length !== 1 || declared[0] !== pk) {
+    throw new OrmDefinitionError(
+      `overlayWinsUnion: ${role} primary key must be exactly "${pk}" (declared: ${declared.length > 0 ? declared.join(", ") : "none"})`
+    );
+  }
+}
+function formatCanonicalColumnType(type) {
+  return typeof type === "string" ? type : `enum(${type.enum})`;
+}
+function assertOverlayWinsMatchingColumnTypes({
+  overlay,
+  synced,
+  columns
+}) {
+  for (const column of columns) {
+    const overlayType = overlay.columns[column].toCanonicalColumn(column).type;
+    const syncedType = synced.columns[column].toCanonicalColumn(column).type;
+    if (JSON.stringify(overlayType) !== JSON.stringify(syncedType)) {
+      throw new OrmDefinitionError(
+        `overlayWinsUnion: column "${column}" must have the same type on overlay and synced (overlay: ${formatCanonicalColumnType(overlayType)}, synced: ${formatCanonicalColumnType(syncedType)})`
+      );
+    }
+  }
+}
+function overlayWinsUnion(input) {
+  const { overlay, synced, pk, tombstone } = input;
+  return ({ qb, relation }) => {
+    assertOverlayWinsPrimaryKey({ table: overlay, pk, role: "overlay" });
+    assertOverlayWinsPrimaryKey({ table: synced, pk, role: "synced" });
+    const overlayHandle = relation(overlay);
+    const syncedHandle = relation(synced);
+    const overlayCols = overlayHandle;
+    const syncedCols = syncedHandle;
+    const overlayPk = overlayCols[pk];
+    const syncedPk = syncedCols[pk];
+    if (tombstone !== void 0) {
+      const tombstoneBuilder = overlay.columns[tombstone];
+      if (!tombstoneBuilder) {
+        throw new OrmDefinitionError(
+          `overlayWinsUnion: tombstone "${tombstone}" must exist as a property on the overlay table`
+        );
+      }
+      const tombstoneCanonical = tombstoneBuilder.toCanonicalColumn(tombstone);
+      if (tombstoneCanonical.type !== "boolean") {
+        throw new OrmDefinitionError(
+          `overlayWinsUnion: tombstone "${tombstone}" must be a boolean column`
+        );
+      }
+      if (tombstoneCanonical.nullable) {
+        throw new OrmDefinitionError(
+          `overlayWinsUnion: tombstone "${tombstone}" must be notNull \u2014 nullable tombstones silently drop rows`
+        );
+      }
+    }
+    const overlayColumns = Object.keys(overlay.columns);
+    const syncedColumns = Object.keys(synced.columns);
+    const sharedColumns = overlayColumns.filter((col) => syncedColumns.includes(col) && col !== pk);
+    assertOverlayWinsMatchingColumnTypes({
+      overlay,
+      synced,
+      columns: [pk, ...sharedColumns]
+    });
+    const overlaySelect = {
+      [pk]: overlayPk,
+      ...Object.fromEntries(sharedColumns.map((col) => [col, overlayCols[col]])),
+      provenance: drizzleOrm.sql`'overlay'`.as("provenance")
+    };
+    const syncedSelect = {
+      [pk]: syncedPk,
+      ...Object.fromEntries(sharedColumns.map((col) => [col, syncedCols[col]])),
+      provenance: drizzleOrm.sql`'synced'`.as("provenance")
+    };
+    const overlayFrom = qb.select(overlaySelect).from(overlayHandle);
+    const overlayQuery = tombstone !== void 0 ? overlayFrom.where(drizzleOrm.eq(overlayCols[tombstone], false)) : overlayFrom;
+    const syncedQuery = qb.select(syncedSelect).from(syncedHandle).where(
+      drizzleOrm.notExists(
+        qb.select({ one: drizzleOrm.sql`1` }).from(overlayHandle).where(drizzleOrm.eq(overlayPk, syncedPk))
+      )
+    );
+    return overlayQuery.unionAll(syncedQuery);
+  };
+}
+
+// src/authoring/cow-mutations.ts
+function overrideRowMutation(input) {
+  const { overlay, synced, pk } = input;
+  const name = input.name ?? `override_${overlay.tableName}`;
+  assertMutationName(name, "overrideRowMutation");
+  assertOverlayPairPrimaryKey({ overlay, synced, pk, helper: "overrideRowMutation" });
+  const sharedProperties = sharedNonPkProperties({ overlay, synced, pk });
+  const setProperties = resolveSetProperties({
+    overlay,
+    synced,
+    pk,
+    set: input.set,
+    sharedProperties,
+    helper: "overrideRowMutation"
+  });
+  assertMatchingColumns({
+    overlay,
+    synced,
+    properties: [pk, ...sharedProperties],
+    helper: "overrideRowMutation"
+  });
+  return {
+    kind: "override",
+    name,
+    synced: synced.tableName,
+    pk,
+    copy: [pk, ...sharedProperties],
+    set: setProperties
+  };
+}
+function revertOverlayMutation(input) {
+  const { overlay, synced, pk } = input;
+  const name = input.name ?? `revert_${overlay.tableName}`;
+  assertMutationName(name, "revertOverlayMutation");
+  assertOverlayPairPrimaryKey({ overlay, synced, pk, helper: "revertOverlayMutation" });
+  assertMatchingColumns({ overlay, synced, properties: [pk], helper: "revertOverlayMutation" });
+  return {
+    kind: "revert",
+    name,
+    synced: synced.tableName,
+    pk,
+    copy: [],
+    set: []
+  };
+}
+function assertMutationName(name, helper) {
+  if (!IDENTIFIER_PATTERN.test(name) || name.length > MAX_IDENTIFIER_LENGTH) {
+    throw new OrmDefinitionError(
+      `${helper}: mutation name "${name}" must match ${IDENTIFIER_PATTERN} and be at most ${MAX_IDENTIFIER_LENGTH} characters`
+    );
+  }
+}
+function assertOverlayPairPrimaryKey({
+  overlay,
+  synced,
+  pk,
+  helper
+}) {
+  assertSinglePrimaryKey({ table: overlay, pk, role: "overlay", helper });
+  assertSinglePrimaryKey({ table: synced, pk, role: "synced", helper });
+}
+function assertSinglePrimaryKey({
+  table,
+  pk,
+  role,
+  helper
+}) {
+  if (!(pk in table.columns)) {
+    throw new OrmDefinitionError(`${helper}: pk "${pk}" must exist as a property on the ${role} table`);
+  }
+  const declared = declaredPrimaryKeyProperties2(table);
+  if (declared.length !== 1 || declared[0] !== pk) {
+    throw new OrmDefinitionError(
+      `${helper}: ${role} primary key must be exactly "${pk}" (declared: ${declared.length > 0 ? declared.join(", ") : "none"})`
+    );
+  }
+}
+function declaredPrimaryKeyProperties2(table) {
+  const fromColumns = Object.entries(table.columns).filter(([, builder]) => builder.isPrimaryKey).map(([propertyName]) => propertyName);
+  if (fromColumns.length > 0) return fromColumns;
+  const configPk = table.config?.primaryKey ?? [];
+  const resolved = [];
+  for (const ref of configPk) {
+    if (ref in table.columns) {
+      resolved.push(ref);
+      continue;
+    }
+    const byColumnName = Object.entries(table.columns).find(
+      ([propertyName, builder]) => builder.columnNameFor(propertyName) === ref
+    );
+    if (byColumnName) resolved.push(byColumnName[0]);
+  }
+  return resolved;
+}
+function sharedNonPkProperties({
+  overlay,
+  synced,
+  pk
+}) {
+  return Object.keys(overlay.columns).filter((property) => property !== pk && property in synced.columns);
+}
+function resolveSetProperties({
+  overlay,
+  synced,
+  pk,
+  set,
+  sharedProperties,
+  helper
+}) {
+  const properties = set !== void 0 ? [...set] : [...sharedProperties];
+  if (properties.length === 0) {
+    throw new OrmDefinitionError(
+      `${helper}: set must declare at least one non-PK column to update after the copy`
+    );
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (const property of properties) {
+    if (property === pk) {
+      throw new OrmDefinitionError(`${helper}: set must not include pk "${pk}" \u2014 identity columns are pinned`);
+    }
+    if (!(property in overlay.columns)) {
+      throw new OrmDefinitionError(`${helper}: set column "${property}" must exist on the overlay table`);
+    }
+    if (!(property in synced.columns)) {
+      throw new OrmDefinitionError(
+        `${helper}: set column "${property}" must exist on the synced table (contract columns only)`
+      );
+    }
+    if (seen.has(property)) {
+      throw new OrmDefinitionError(`${helper}: set column "${property}" is duplicated`);
+    }
+    seen.add(property);
+  }
+  return properties;
+}
+function assertMatchingColumns({
+  overlay,
+  synced,
+  properties,
+  helper
+}) {
+  for (const property of properties) {
+    const overlayCanonical = overlay.columns[property].toCanonicalColumn(property);
+    const syncedCanonical = synced.columns[property].toCanonicalColumn(property);
+    const overlayType = scalarColumnType(overlay, property, helper);
+    const syncedType = scalarColumnType(synced, property, helper);
+    if (overlayType !== syncedType) {
+      throw new OrmDefinitionError(
+        `${helper}: column "${property}" must have the same scalar type on overlay and synced (overlay: ${overlayType}, synced: ${syncedType})`
+      );
+    }
+    const overlayColumn = overlay.columns[property].columnNameFor(property);
+    const syncedColumn = synced.columns[property].columnNameFor(property);
+    if (overlayColumn !== syncedColumn) {
+      throw new OrmDefinitionError(
+        `${helper}: column "${property}" maps to different Postgres names on overlay (${overlayColumn}) and synced (${syncedColumn})`
+      );
+    }
+    if (syncedCanonical.nullable && !overlayCanonical.nullable) {
+      throw new OrmDefinitionError(
+        `${helper}: column "${property}" is nullable on synced but NOT NULL on overlay \u2014 a NULL synced value would fail the copy-from-synced insert; make overlay nullable or synced notNull`
+      );
+    }
+  }
+}
+function scalarColumnType(table, property, helper) {
+  const type = table.columns[property].toCanonicalColumn(property).type;
+  if (typeof type !== "string") {
+    throw new OrmDefinitionError(
+      `${helper}: column "${property}" on "${table.tableName}" must be a scalar type (enums are not supported in cow mutation arguments)`
+    );
+  }
+  return type;
+}
 var CANONICAL_FORMAT = 2;
 var IDENTIFIER_RE = /^[a-z][a-z0-9_]*$/;
 var identifier = zod.z.string().min(1).max(63).regex(IDENTIFIER_RE);
@@ -388,8 +911,33 @@ var policyExpressionSchema = zod.z.union([
 ]);
 var canonicalPoliciesSchema = zod.z.object({
   read: policyExpressionSchema.optional(),
-  write: policyExpressionSchema.optional()
+  write: policyExpressionSchema.optional(),
+  insert: policyExpressionSchema.optional(),
+  update: policyExpressionSchema.optional()
 });
+function isSingleViewQuerySql(value) {
+  const query = value.trim();
+  if (!/^\(*(?:select|with)\b/i.test(query) || query.includes("\0")) return false;
+  let state = "normal";
+  for (let index = 0; index < query.length; index += 1) {
+    const char = query[index];
+    const next = query[index + 1];
+    if (state === "single") {
+      if (char === "'" && next === "'") index += 1;
+      else if (char === "'") state = "normal";
+      continue;
+    }
+    if (state === "double") {
+      if (char === '"' && next === '"') index += 1;
+      else if (char === '"') state = "normal";
+      continue;
+    }
+    if (char === "'") state = "single";
+    else if (char === '"') state = "double";
+    else if (char === ";" || char === "-" && next === "-" || char === "/" && next === "*") return false;
+  }
+  return state === "normal" && !/\$[a-z_0-9]*\$/i.test(query);
+}
 var canonicalActionSchema = zod.z.object({
   name: identifier,
   requires: zod.z.string().max(1e3).optional(),
@@ -401,6 +949,37 @@ var canonicalActionSchema = zod.z.object({
   returns: zod.z.enum(["rows", "rowsAffected", "scalar"]).default("rowsAffected"),
   audit: zod.z.object({ action: zod.z.string(), resource: zod.z.string() }).optional()
 });
+var canonicalCowMutationSchema = zod.z.object({
+  kind: zod.z.enum(["override", "revert"]),
+  name: identifier,
+  /** Synced table (same namespace) the overlay copies from / falls back to. */
+  synced: identifier,
+  /** Single-column primary key PROPERTY (TS camelCase, like column `name`) shared by overlay and synced. */
+  pk: zod.z.string().min(1).max(63),
+  /** Override: contract properties copied INSERT…SELECT from synced (pk included). Empty for revert. */
+  copy: zod.z.array(zod.z.string().min(1).max(63)).default([]),
+  /** Override: overlay properties written by the UPDATE (never the pk). Empty for revert. */
+  set: zod.z.array(zod.z.string().min(1).max(63)).default([])
+}).superRefine((mutation, ctx) => {
+  if (mutation.kind === "override") {
+    if (mutation.set.length === 0) {
+      ctx.addIssue({ code: "custom", path: ["set"], message: "override mutations must set at least one column" });
+    }
+    if (!mutation.copy.includes(mutation.pk)) {
+      ctx.addIssue({ code: "custom", path: ["copy"], message: "override copy list must include the pk" });
+    }
+  } else if (mutation.set.length > 0 || mutation.copy.length > 0) {
+    ctx.addIssue({ code: "custom", path: ["set"], message: "revert mutations take no copy/set columns" });
+  }
+  if (mutation.set.includes(mutation.pk)) {
+    ctx.addIssue({ code: "custom", path: ["set"], message: "set must not include the pk \u2014 identity columns are pinned" });
+  }
+  for (const [field, values] of [["copy", mutation.copy], ["set", mutation.set]]) {
+    if (new Set(values).size !== values.length) {
+      ctx.addIssue({ code: "custom", path: [field], message: `${field} must not contain duplicate columns` });
+    }
+  }
+});
 var canonicalTableSchema = zod.z.object({
   table: identifier,
   description: zod.z.string().max(2e3).optional(),
@@ -413,7 +992,45 @@ var canonicalTableSchema = zod.z.object({
   links: zod.z.array(canonicalLinkSchema).default([]),
   indexes: zod.z.array(canonicalIndexSchema).default([]),
   policies: canonicalPoliciesSchema.default({}),
-  actions: zod.z.array(canonicalActionSchema).default([])
+  /**
+   * v1-conversion carry-over only. v2 has no action surface — the runtime
+   * neither compiles nor executes these; writes are mutations. Kept parseable
+   * so stored definitions and their content hashes stay stable.
+   */
+  actions: zod.z.array(canonicalActionSchema).default([]),
+  /** Optional (not defaulted) so pre-CoW canonical documents keep byte-identical hashes. */
+  cowMutations: zod.z.array(canonicalCowMutationSchema).optional()
+});
+var canonicalViewSchema = zod.z.object({
+  view: identifier,
+  description: zod.z.string().max(2e3).optional(),
+  columns: zod.z.array(canonicalColumnSchema).min(1),
+  /** Logical identity for GraphQL only; PostgreSQL views have no PK constraint. */
+  primaryKey: zod.z.array(identifier).min(1).max(8).optional(),
+  links: zod.z.array(canonicalLinkSchema).default([]),
+  policies: zod.z.object({ read: policyExpressionSchema }).strict(),
+  query: zod.z.string().min(1).max(1e5).refine(isSingleViewQuerySql, {
+    message: "view query must be one SELECT/WITH statement without comments or dollar-quoted bodies"
+  }),
+  /** Namespace-local logical relation names, sorted for deterministic hashing. */
+  dependencies: zod.z.array(identifier).max(500)
+}).superRefine((view, ctx) => {
+  for (const [index, column] of view.columns.entries()) {
+    if (column.default !== void 0 || column.defaultFn !== void 0) {
+      ctx.addIssue({ code: "custom", path: ["columns", index], message: `view column '${column.name}' cannot declare a default` });
+    }
+    if (column.unique) {
+      ctx.addIssue({ code: "custom", path: ["columns", index], message: `view column '${column.name}' cannot declare unique` });
+    }
+    if (column.renamedFrom !== void 0 || column.cast !== void 0) {
+      ctx.addIssue({ code: "custom", path: ["columns", index], message: `view column '${column.name}' cannot declare migration hints` });
+    }
+  }
+  for (const [index, link] of view.links.entries()) {
+    if (link.enforce) {
+      ctx.addIssue({ code: "custom", path: ["links", index, "enforce"], message: `view link '${link.name}' cannot enforce a foreign key` });
+    }
+  }
 });
 var canonicalDefinitionSchema = zod.z.object({
   definition_format: zod.z.literal(CANONICAL_FORMAT),
@@ -421,24 +1038,161 @@ var canonicalDefinitionSchema = zod.z.object({
   description: zod.z.string().max(2e3).optional(),
   enums: zod.z.array(canonicalEnumSchema).default([]),
   tables: zod.z.array(canonicalTableSchema).min(0).max(500),
+  /** Optional to preserve byte-identical hashes for pre-view canonical v2 documents. */
+  views: zod.z.array(canonicalViewSchema).max(500).optional(),
   /** Verbatim custom-roles grammar (@sequenceholdings/custom-roles-manifest). */
   capabilities: zod.z.object({
     roles: zod.z.unknown().optional(),
     uses: zod.z.array(zod.z.string()).default([])
   }).default({ uses: [] })
+}).superRefine((definition, ctx) => {
+  const seen = /* @__PURE__ */ new Set();
+  for (const [index, table] of definition.tables.entries()) {
+    if (seen.has(table.table)) {
+      ctx.addIssue({ code: "custom", path: ["tables", index, "table"], message: `duplicate relation '${table.table}'` });
+    }
+    seen.add(table.table);
+  }
+  const tableByName = new Map(definition.tables.map((table) => [table.table, table]));
+  for (const [tableIndex, table] of definition.tables.entries()) {
+    const cowMutations = table.cowMutations ?? [];
+    if (cowMutations.length === 0) continue;
+    const path = (index, ...rest) => ["tables", tableIndex, "cowMutations", index, ...rest];
+    if (table.source !== void 0) {
+      ctx.addIssue({ code: "custom", path: path(0), message: `synced table '${table.table}' cannot declare cow mutations \u2014 it is read-only` });
+      continue;
+    }
+    for (const [index, mutation] of cowMutations.entries()) {
+      const synced = tableByName.get(mutation.synced);
+      if (!synced || synced.source === void 0) {
+        ctx.addIssue({
+          code: "custom",
+          path: path(index, "synced"),
+          message: `cow mutation '${mutation.name}' references '${mutation.synced}', which is not a synced table in this namespace`
+        });
+        continue;
+      }
+      const overlayColumnsByName = new Map(table.columns.map((column) => [column.name, column]));
+      const syncedColumnsByName = new Map(synced.columns.map((column) => [column.name, column]));
+      let columnsExist = true;
+      for (const property of [mutation.pk, ...mutation.copy, ...mutation.set]) {
+        if (!overlayColumnsByName.has(property)) {
+          columnsExist = false;
+          ctx.addIssue({ code: "custom", path: path(index), message: `cow mutation '${mutation.name}': column '${property}' does not exist on overlay '${table.table}'` });
+        }
+      }
+      for (const property of [mutation.pk, ...mutation.copy]) {
+        if (!syncedColumnsByName.has(property)) {
+          columnsExist = false;
+          ctx.addIssue({ code: "custom", path: path(index), message: `cow mutation '${mutation.name}': column '${property}' does not exist on synced '${mutation.synced}'` });
+        }
+      }
+      if (!columnsExist) continue;
+      const overlayPk = table.primaryKey ?? [];
+      const syncedPk = synced.primaryKey ?? [];
+      if (overlayPk.length !== 1 || overlayPk[0] !== mutation.pk || syncedPk.length !== 1 || syncedPk[0] !== mutation.pk) {
+        ctx.addIssue({
+          code: "custom",
+          path: path(index, "pk"),
+          message: `cow mutation '${mutation.name}': pk '${mutation.pk}' must be the single-column primary key on both '${table.table}' and '${mutation.synced}'`
+        });
+      }
+      for (const property of [mutation.pk, ...mutation.copy]) {
+        const overlayColumn = overlayColumnsByName.get(property);
+        const syncedColumn = syncedColumnsByName.get(property);
+        if (!overlayColumn || !syncedColumn) continue;
+        if (JSON.stringify(overlayColumn.type) !== JSON.stringify(syncedColumn.type)) {
+          ctx.addIssue({
+            code: "custom",
+            path: path(index),
+            message: `cow mutation '${mutation.name}': column '${property}' must have the same type on overlay and synced`
+          });
+        }
+        if (overlayColumn.columnName !== syncedColumn.columnName) {
+          ctx.addIssue({
+            code: "custom",
+            path: path(index),
+            message: `cow mutation '${mutation.name}': column '${property}' maps to different Postgres names on overlay ('${overlayColumn.columnName}') and synced ('${syncedColumn.columnName}')`
+          });
+        }
+        if (syncedColumn.nullable !== false && overlayColumn.nullable === false) {
+          ctx.addIssue({
+            code: "custom",
+            path: path(index),
+            message: `cow mutation '${mutation.name}': column '${property}' is nullable on synced but NOT NULL on overlay \u2014 a NULL synced value would fail the copy`
+          });
+        }
+      }
+    }
+  }
+  for (const [index, view] of (definition.views ?? []).entries()) {
+    if (seen.has(view.view)) {
+      ctx.addIssue({ code: "custom", path: ["views", index, "view"], message: `duplicate relation '${view.view}'` });
+    }
+    seen.add(view.view);
+  }
+  const views = definition.views ?? [];
+  const viewByName = new Map(views.map((view) => [view.view, view]));
+  for (const [viewIndex, view] of views.entries()) {
+    for (const [dependencyIndex, dependency] of view.dependencies.entries()) {
+      if (!seen.has(dependency)) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["views", viewIndex, "dependencies", dependencyIndex],
+          message: `view '${view.view}' depends on unknown relation '${dependency}'`
+        });
+      }
+    }
+  }
+  const visiting = /* @__PURE__ */ new Set();
+  const visited = /* @__PURE__ */ new Set();
+  let cycleReported = false;
+  const visit = (name, path) => {
+    if (visited.has(name) || cycleReported) return;
+    if (visiting.has(name)) {
+      cycleReported = true;
+      ctx.addIssue({
+        code: "custom",
+        path: ["views"],
+        message: `view dependencies form a cycle: ${[...path, name].join(" -> ")}`
+      });
+      return;
+    }
+    visiting.add(name);
+    const view = viewByName.get(name);
+    for (const dependency of view?.dependencies ?? []) {
+      if (viewByName.has(dependency)) visit(dependency, [...path, name]);
+    }
+    visiting.delete(name);
+    visited.add(name);
+  };
+  for (const view of views) visit(view.view, []);
 });
 function normalizeCanonical(definition) {
   const sortByName = (items) => [...items].sort((a, b) => a.name.localeCompare(b.name));
-  return {
+  const normalized = {
     ...definition,
     enums: sortByName(definition.enums),
-    tables: [...definition.tables].sort((a, b) => a.table.localeCompare(b.table)).map((t2) => ({
-      ...t2,
-      links: sortByName(t2.links),
-      indexes: [...t2.indexes].sort((a, b) => (a.name ?? a.columns.join("_")).localeCompare(b.name ?? b.columns.join("_"))),
-      actions: sortByName(t2.actions)
-    }))
+    tables: [...definition.tables].sort((a, b) => a.table.localeCompare(b.table)).map((t2) => {
+      const { cowMutations, ...rest } = t2;
+      return {
+        ...rest,
+        links: sortByName(t2.links),
+        indexes: [...t2.indexes].sort((a, b) => (a.name ?? a.columns.join("_")).localeCompare(b.name ?? b.columns.join("_"))),
+        actions: sortByName(t2.actions),
+        // Omitted entirely when absent/empty so pre-CoW documents hash unchanged.
+        ...cowMutations !== void 0 && cowMutations.length > 0 ? { cowMutations: sortByName(cowMutations) } : {}
+      };
+    })
   };
+  if (definition.views !== void 0) {
+    normalized.views = [...definition.views].sort((a, b) => a.view.localeCompare(b.view)).map((view) => ({
+      ...view,
+      links: sortByName(view.links),
+      dependencies: [...view.dependencies].sort()
+    }));
+  }
+  return normalized;
 }
 function stableJson(value) {
   if (value === null || typeof value !== "object") return JSON.stringify(value);
@@ -469,6 +1223,7 @@ function defineNamespace(input) {
 }
 function serializeNamespace(input) {
   const { config, tables } = input;
+  const views = input.views ?? [];
   const enums = input.enums ?? [];
   const tablesByName = /* @__PURE__ */ new Map();
   for (const table of tables) {
@@ -481,6 +1236,29 @@ function serializeNamespace(input) {
     }
     tablesByName.set(table.tableName, table);
   }
+  const viewsByName = /* @__PURE__ */ new Map();
+  for (const view of views) {
+    const existing = viewsByName.get(view.viewName);
+    if (existing) {
+      throw new OrmDefinitionError(
+        `duplicate view "${view.viewName}" (defined in ${describeFile(existing)} and ${describeFile(view)})`,
+        view.file
+      );
+    }
+    viewsByName.set(view.viewName, view);
+  }
+  const relationsByName = /* @__PURE__ */ new Map();
+  for (const relation of [...tables, ...views]) {
+    const name = relationName(relation);
+    const existing = relationsByName.get(name);
+    if (existing) {
+      throw new OrmDefinitionError(
+        `duplicate relation "${name}" (defined as ${relationKind(existing)} in ${describeFile(existing)} and ${relationKind(relation)} in ${describeFile(relation)})`,
+        relation.file
+      );
+    }
+    relationsByName.set(name, relation);
+  }
   const enumsByName = /* @__PURE__ */ new Map();
   for (const ref of enums) {
     if (enumsByName.has(ref.name)) {
@@ -488,11 +1266,26 @@ function serializeNamespace(input) {
     }
     enumsByName.set(ref.name, ref);
   }
-  const canonicalTables = tables.map((table) => buildCanonicalTable({ table, tablesByName, enumsByName }));
+  const canonicalTables = tables.map((table) => buildCanonicalTable({ table, relationsByName, enumsByName }));
   const canonicalEnums = [...enumsByName.values()].map((ref) => ({
     name: ref.name,
     values: [...ref.values]
   }));
+  const viewDrafts = views.map((view) => buildCanonicalView({ view, relationsByName, enumsByName }));
+  const compiledViews = compileViewQueries({
+    namespace: config.namespace,
+    tables: canonicalTables,
+    views: viewDrafts,
+    enums: canonicalEnums,
+    authoredTables: tables,
+    authoredViews: views
+  });
+  const canonicalViews = viewDrafts.map((draft) => {
+    const compiled = compiledViews.get(draft.view);
+    if (!compiled) throw new OrmDefinitionError(`view "${draft.view}" did not compile`, viewsByName.get(draft.view)?.file);
+    return canonicalViewSchema.parse({ ...draft, ...compiled });
+  });
+  assertAcyclicViewDependencies(canonicalViews);
   const candidate = {
     definition_format: CANONICAL_FORMAT,
     namespace: config.namespace,
@@ -504,6 +1297,7 @@ function serializeNamespace(input) {
     }
   };
   if (config.description !== void 0) candidate.description = config.description;
+  if (canonicalViews.length > 0) candidate.views = canonicalViews;
   let parsed;
   try {
     parsed = canonicalDefinitionSchema.parse(candidate);
@@ -518,7 +1312,7 @@ function serializeNamespace(input) {
 function computeCanonicalHash(definition) {
   return crypto.createHash("sha256").update(HASH_DOMAIN).update(stableJson(definition)).digest("hex");
 }
-function buildCanonicalTable({ table, tablesByName, enumsByName }) {
+function buildCanonicalTable({ table, relationsByName, enumsByName }) {
   const candidate = {
     table: table.tableName,
     columns: [],
@@ -530,6 +1324,31 @@ function buildCanonicalTable({ table, tablesByName, enumsByName }) {
   if (table.config.description !== void 0) candidate.description = table.config.description;
   if (table.config.renamedFrom !== void 0) candidate.renamedFrom = table.config.renamedFrom;
   if (table.source !== void 0) candidate.source = table.source;
+  if (table.source !== void 0) {
+    if (table.config.indexes !== void 0 && table.config.indexes.length > 0) {
+      throw new OrmDefinitionError(
+        `synced table "${table.tableName}" is system-owned; indexes are not allowed`,
+        table.file
+      );
+    }
+    if (table.config.cowMutations !== void 0 && table.config.cowMutations.length > 0) {
+      throw new OrmDefinitionError(
+        `synced table "${table.tableName}" is read-only; cow mutations belong on the overlay table`,
+        table.file
+      );
+    }
+    if (table.config.policies?.write !== void 0 || table.config.policies?.insert !== void 0 || table.config.policies?.update !== void 0) {
+      throw new OrmDefinitionError(`synced table "${table.tableName}" is read-only`, table.file);
+    }
+    for (const [linkName, link] of Object.entries(table.config.links ?? {})) {
+      if (link.enforce) {
+        throw new OrmDefinitionError(
+          `synced table "${table.tableName}": link "${linkName}" cannot enforce foreign keys \u2014 its DDL is owned by the sync`,
+          table.file
+        );
+      }
+    }
+  }
   const columnLevelPk = [];
   for (const [propertyName, builder] of Object.entries(table.columns)) {
     const column = builder.toCanonicalColumn(propertyName);
@@ -551,40 +1370,38 @@ function buildCanonicalTable({ table, tablesByName, enumsByName }) {
       );
     }
     candidate.primaryKey = table.config.primaryKey.map(
-      (ref) => resolveColumnRef({ table, ref, role: "primaryKey" })
+      (ref) => resolveColumnRef({ relation: table, ref, role: "primaryKey" })
     );
   } else if (columnLevelPk.length > 0) {
     candidate.primaryKey = columnLevelPk;
   }
   for (const index of table.config.indexes ?? []) {
     const entry = {
-      columns: index.columns.map((ref) => resolveColumnRef({ table, ref, role: "index" }))
+      columns: index.columns.map((ref) => resolveColumnRef({ relation: table, ref, role: "index" }))
     };
     if (index.unique !== void 0) entry.unique = index.unique;
     if (index.name !== void 0) entry.name = index.name;
     candidate.indexes?.push(entry);
   }
   for (const [linkName, link] of Object.entries(table.config.links ?? {})) {
-    candidate.links?.push(buildCanonicalLink({ table, linkName, link, tablesByName }));
+    candidate.links?.push(buildCanonicalLink({ relation: table, linkName, link, relationsByName }));
   }
   const policies = {};
   if (table.config.policies?.read !== void 0) policies.read = toCanonicalPolicy(table.config.policies.read);
   if (table.config.policies?.write !== void 0) policies.write = toCanonicalPolicy(table.config.policies.write);
+  if (table.config.policies?.insert !== void 0) policies.insert = toCanonicalPolicy(table.config.policies.insert);
+  if (table.config.policies?.update !== void 0) policies.update = toCanonicalPolicy(table.config.policies.update);
   candidate.policies = policies;
-  for (const action of table.config.actions ?? []) {
-    candidate.actions?.push({
-      name: action.name,
-      ...action.requires !== void 0 ? { requires: action.requires } : {},
-      params: Object.fromEntries(
-        Object.entries(action.params ?? {}).map(([name, param]) => [
-          name,
-          { type: param.type, nullable: param.nullable ?? false }
-        ])
-      ),
-      executes: action.executes,
-      returns: action.returns ?? "rowsAffected",
-      ...action.audit !== void 0 ? { audit: action.audit } : {}
-    });
+  const cowMutations = table.config.cowMutations ?? [];
+  if (cowMutations.length > 0) {
+    candidate.cowMutations = cowMutations.map((mutation) => ({
+      kind: mutation.kind,
+      name: mutation.name,
+      synced: mutation.synced,
+      pk: mutation.pk,
+      copy: [...mutation.copy],
+      set: [...mutation.set]
+    }));
   }
   try {
     return canonicalTableSchema.parse(candidate);
@@ -595,14 +1412,71 @@ function buildCanonicalTable({ table, tablesByName, enumsByName }) {
     throw error;
   }
 }
+function buildCanonicalView({
+  view,
+  relationsByName,
+  enumsByName
+}) {
+  if (view.config.policies?.read === void 0) {
+    throw new OrmDefinitionError(`view "${view.viewName}" must declare policies.read`, view.file);
+  }
+  const columns = [];
+  const columnLevelPk = [];
+  for (const [propertyName, builder] of Object.entries(view.columns)) {
+    const column = builder.toCanonicalColumn(propertyName);
+    if (column.default !== void 0 || column.defaultFn !== void 0) {
+      throw new OrmDefinitionError(`view "${view.viewName}": column "${propertyName}" cannot declare a default`, view.file);
+    }
+    if (column.unique) {
+      throw new OrmDefinitionError(`view "${view.viewName}": column "${propertyName}" cannot declare unique`, view.file);
+    }
+    if (column.renamedFrom !== void 0 || column.cast !== void 0) {
+      throw new OrmDefinitionError(`view "${view.viewName}": column "${propertyName}" cannot declare migration hints`, view.file);
+    }
+    const enumName = builder.enumName;
+    if (enumName !== void 0 && !enumsByName.has(enumName)) {
+      throw new OrmDefinitionError(
+        `view "${view.viewName}": column "${propertyName}" references enum "${enumName}" which is not part of this namespace`,
+        view.file
+      );
+    }
+    if (builder.isPrimaryKey) columnLevelPk.push(column.columnName);
+    columns.push(column);
+  }
+  let primaryKey;
+  if (view.config.primaryKey !== void 0) {
+    if (columnLevelPk.length > 0) {
+      throw new OrmDefinitionError(
+        `view "${view.viewName}": declare the logical primary key either on columns or with config.primaryKey \u2014 not both`,
+        view.file
+      );
+    }
+    primaryKey = view.config.primaryKey.map((ref) => resolveColumnRef({ relation: view, ref, role: "primaryKey" }));
+  } else if (columnLevelPk.length > 0) {
+    primaryKey = columnLevelPk;
+  }
+  const links = Object.entries(view.config.links ?? {}).map(
+    ([linkName, link]) => buildCanonicalLink({ relation: view, linkName, link, relationsByName })
+  );
+  return {
+    view: view.viewName,
+    ...view.config.description !== void 0 ? { description: view.config.description } : {},
+    columns,
+    ...primaryKey !== void 0 ? { primaryKey } : {},
+    links,
+    policies: { read: toCanonicalPolicy(view.config.policies.read) }
+  };
+}
 function buildCanonicalLink({
-  table,
+  relation,
   linkName,
   link,
-  tablesByName
+  relationsByName
 }) {
+  const ownerKind = relationKind(relation);
+  const ownerName = relationName(relation);
   const fail = (message) => {
-    throw new OrmDefinitionError(`table "${table.tableName}": link "${linkName}" ${message}`, table.file);
+    throw new OrmDefinitionError(`${ownerKind} "${ownerName}": link "${linkName}" ${message}`, relation.file);
   };
   if (link.enforce && link.linkKind !== "toOne") {
     return fail("sets enforce: true, which is only supported on toOne links");
@@ -612,29 +1486,34 @@ function buildCanonicalLink({
     return {
       name: linkName,
       kind: "toPlatformUser",
-      on: resolveColumnRef({ table, ref: link.on, role: `link "${linkName}" on` }),
+      on: resolveColumnRef({ relation, ref: link.on, role: `link "${linkName}" on` }),
       ...link.references !== void 0 ? { references: deriveColumnName(link.references) } : {},
       enforce: false,
       ...link.description !== void 0 ? { description: link.description } : {}
     };
   }
-  const target = resolveTableRef({ ref: link.target, fail });
-  if (!tablesByName.has(target.tableName)) {
-    return fail(`targets table "${target.tableName}" which is not part of this namespace`);
+  const target = resolveRelationRef({ ref: link.target, fail });
+  const targetName = relationName(target);
+  if (!relationsByName.has(targetName)) {
+    return fail(`targets ${relationKind(target)} "${targetName}" which is not part of this namespace`);
+  }
+  if (link.enforce && (!isSeqTable(relation) || !isSeqTable(target))) {
+    return fail("cannot enforce a PostgreSQL foreign key involving a view");
   }
-  const owningSide = link.linkKind === "toOne" ? table : target;
+  const owningSide = link.linkKind === "toOne" ? relation : target;
+  const referencedSide = link.linkKind === "toOne" ? target : relation;
   return {
     name: linkName,
     kind: link.linkKind,
-    target: target.tableName,
-    on: resolveColumnRef({ table: owningSide, ref: link.on, role: `link "${linkName}" on` }),
-    ...link.references !== void 0 ? { references: resolveColumnRef({ table: target, ref: link.references, role: `link "${linkName}" references` }) } : {},
+    target: targetName,
+    on: resolveColumnRef({ relation: owningSide, ref: link.on, role: `link "${linkName}" on` }),
+    ...link.references !== void 0 ? { references: resolveColumnRef({ relation: referencedSide, ref: link.references, role: `link "${linkName}" references` }) } : {},
     enforce: link.enforce,
     ...link.description !== void 0 ? { description: link.description } : {}
   };
 }
-function resolveTableRef({ ref, fail }) {
-  if (ref === void 0) return fail("declares no target table");
+function resolveRelationRef({ ref, fail }) {
+  if (ref === void 0) return fail("declares no target relation");
   if (typeof ref !== "function") return ref;
   let resolved;
   try {
@@ -644,20 +1523,35 @@ function resolveTableRef({ ref, fail }) {
       `target thunk threw (${error instanceof Error ? error.message : String(error)}) \u2014 lazy refs resolve at serialize time; make sure the target module ran`
     );
   }
-  if (!isSeqTable(resolved)) return fail("target thunk did not return a table defined with defineTable");
+  if (!isSeqTable(resolved) && !isSeqView(resolved)) {
+    return fail("target thunk did not return a relation defined with defineTable/defineView");
+  }
   return resolved;
 }
-function resolveColumnRef({ table, ref, role }) {
-  const direct = table.columns[ref];
+function resolveColumnRef({ relation, ref, role }) {
+  const direct = relation.columns[ref];
   if (direct) return direct.columnNameFor(ref);
-  for (const [propertyName, builder] of Object.entries(table.columns)) {
+  for (const [propertyName, builder] of Object.entries(relation.columns)) {
     if (builder.columnNameFor(propertyName) === ref) return ref;
   }
-  const known = Object.keys(table.columns).join(", ");
+  const known = Object.keys(relation.columns).join(", ");
   throw new OrmDefinitionError(
-    `table "${table.tableName}": ${role} references unknown column "${ref}" (known columns: ${known || "none"})`,
-    table.file
+    `${relationKind(relation)} "${relationName(relation)}": ${role} references unknown column "${ref}" (known columns: ${known || "none"})`,
+    relation.file
+  );
+}
+function assertAcyclicViewDependencies(views) {
+  const viewNames = new Set(views.map((view) => view.view));
+  const remaining = new Map(
+    views.map((view) => [view.view, new Set(view.dependencies.filter((dependency) => viewNames.has(dependency)))])
   );
+  while (remaining.size > 0) {
+    const ready = [...remaining.entries()].filter(([, dependencies]) => [...dependencies].every((dependency) => !remaining.has(dependency))).map(([name]) => name);
+    if (ready.length === 0) {
+      throw new OrmDefinitionError(`view dependencies form a cycle among: ${[...remaining.keys()].sort().join(", ")}`);
+    }
+    for (const name of ready) remaining.delete(name);
+  }
 }
 function toCanonicalPolicy(policy) {
   if (typeof policy === "string") return policy;
@@ -670,12 +1564,110 @@ function toCanonicalPolicy(policy) {
     }))
   };
 }
-function describeFile(table) {
-  return table.file ?? "<unknown file>";
+function describeFile(relation) {
+  return relation.file ?? "<unknown file>";
 }
 function formatZodIssues(error) {
   return error.issues.map((issue) => issue.path.length > 0 ? `${issue.path.join(".")}: ${issue.message}` : issue.message).join("; ");
 }
+var SYNCED_CONTRACT_HASH_DOMAIN = "sequence-orm-synced-contract\0";
+var ORM_TO_PIPELINE_TYPE = {
+  uuid: "uuid",
+  text: "string",
+  integer: "int",
+  bigint: "long",
+  numeric: "numeric",
+  double: "double",
+  boolean: "boolean",
+  timestamptz: "timestamp",
+  date: "date",
+  jsonb: "json"
+};
+function isColumnType(value) {
+  return typeof value === "string" && value in ORM_TO_PIPELINE_TYPE;
+}
+function syncedContractSurface({
+  namespace,
+  table,
+  columns,
+  primary_key
+}) {
+  return {
+    namespace,
+    table,
+    columns: Object.fromEntries(
+      Object.entries(columns).map(([name, column]) => [
+        name,
+        { type: column.type, nullable: column.nullable, key: column.key }
+      ])
+    ),
+    primary_key: [...primary_key]
+  };
+}
+function computeSyncedContractHash(surface) {
+  return crypto.createHash("sha256").update(SYNCED_CONTRACT_HASH_DOMAIN).update(stableJson(surface)).digest("hex");
+}
+function extractOrmSyncedTableContract({
+  namespace,
+  table
+}) {
+  if (!NAMESPACE_PATTERN.test(namespace)) {
+    throw new OrmDefinitionError(
+      `namespace "${namespace}" must match ${NAMESPACE_PATTERN}`
+    );
+  }
+  if (table.source === void 0) {
+    throw new OrmDefinitionError(
+      `table "${table.table}" is not a synced table \u2014 extractOrmSyncedTableContract requires source: gold.*`
+    );
+  }
+  if (table.columns.length === 0) {
+    throw new OrmDefinitionError(
+      `synced table "${table.table}" has no typed columns \u2014 declare a typed defineSyncedTable contract before exporting`
+    );
+  }
+  const primaryKey = table.primaryKey;
+  if (primaryKey === void 0 || primaryKey.length === 0) {
+    throw new OrmDefinitionError(
+      `synced table "${table.table}" has no primary key \u2014 typed synced contracts require a primary key`
+    );
+  }
+  const pkSet = new Set(primaryKey);
+  const columns = {};
+  for (const column of table.columns) {
+    if (!isColumnType(column.type)) {
+      const enumName = typeof column.type === "object" && column.type !== null && "enum" in column.type ? column.type.enum : String(column.type);
+      throw new OrmDefinitionError(
+        `synced table "${table.table}": column "${column.columnName}" has enum/type '${enumName}', which has no pipeline-type mapping \u2014 use an ORM-mappable scalar`
+      );
+    }
+    columns[column.columnName] = {
+      type: ORM_TO_PIPELINE_TYPE[column.type],
+      nullable: column.nullable,
+      key: pkSet.has(column.columnName)
+    };
+  }
+  for (const key of primaryKey) {
+    if (!(key in columns)) {
+      throw new OrmDefinitionError(
+        `synced table "${table.table}": primary key column "${key}" is not declared in columns`
+      );
+    }
+  }
+  const surface = syncedContractSurface({
+    namespace,
+    table: table.table,
+    columns,
+    primary_key: primaryKey
+  });
+  return {
+    namespace,
+    table: table.table,
+    columns,
+    primary_key: [...primaryKey],
+    content_hash: computeSyncedContractHash(surface)
+  };
+}
 var NAMESPACE_CONFIG_FILE = "sequence.config.ts";
 var SCHEMA_DIR = "schema";
 async function loadNamespaceFromDir(dir, options = {}) {
@@ -734,16 +1726,20 @@ async function loadNamespaceFromDir(dir, options = {}) {
   for (const entry of context.tables) {
     if (isSeqTable(entry.value)) tables.push(entry.value);
   }
-  if (tables.length === 0) {
+  const views = [];
+  for (const entry of context.views) {
+    if (isSeqView(entry.value)) views.push(entry.value);
+  }
+  if (tables.length === 0 && views.length === 0) {
     throw new OrmDefinitionError(
-      `no tables registered \u2014 ${SCHEMA_DIR}/*.ts modules must call defineTable(...) at import time`
+      `no relations registered \u2014 ${SCHEMA_DIR}/*.ts modules must call defineTable(...) or defineView(...) at import time`
     );
   }
   const enums = [];
   for (const entry of context.enums) {
     if (isEnumRef(entry.value)) enums.push(entry.value);
   }
-  const canonical = serializeNamespace({ config: configEntry.value, tables, enums });
+  const canonical = serializeNamespace({ config: configEntry.value, tables, views, enums });
   return { canonical, hash: computeCanonicalHash(canonical), files };
 }
 async function listSchemaFiles(root) {
@@ -768,24 +1764,35 @@ exports.ENUM_BRAND = ENUM_BRAND;
 exports.LINK_BRAND = LINK_BRAND;
 exports.NAMESPACE_CONFIG_BRAND = NAMESPACE_CONFIG_BRAND;
 exports.NAMESPACE_CONFIG_FILE = NAMESPACE_CONFIG_FILE;
+exports.ORM_TO_PIPELINE_TYPE = ORM_TO_PIPELINE_TYPE;
 exports.SCHEMA_DIR = SCHEMA_DIR;
+exports.SYNCED_CONTRACT_HASH_DOMAIN = SYNCED_CONTRACT_HASH_DOMAIN;
 exports.TABLE_BRAND = TABLE_BRAND;
+exports.VIEW_BRAND = VIEW_BRAND;
 exports.activeAuthoringContext = activeAuthoringContext;
 exports.beginAuthoringContext = beginAuthoringContext;
 exports.computeCanonicalHash = computeCanonicalHash;
+exports.computeSyncedContractHash = computeSyncedContractHash;
 exports.defineEnum = defineEnum;
 exports.defineNamespace = defineNamespace;
 exports.defineSyncedTable = defineSyncedTable;
 exports.defineTable = defineTable;
+exports.defineView = defineView;
 exports.deriveColumnName = deriveColumnName;
 exports.endAuthoringContext = endAuthoringContext;
+exports.extractOrmSyncedTableContract = extractOrmSyncedTableContract;
 exports.isColumnBuilder = isColumnBuilder;
 exports.isEnumRef = isEnumRef;
 exports.isSeqLink = isSeqLink;
 exports.isSeqNamespaceConfig = isSeqNamespaceConfig;
 exports.isSeqTable = isSeqTable;
+exports.isSeqView = isSeqView;
 exports.loadNamespaceFromDir = loadNamespaceFromDir;
+exports.overlayWinsUnion = overlayWinsUnion;
+exports.overrideRowMutation = overrideRowMutation;
+exports.revertOverlayMutation = revertOverlayMutation;
 exports.serializeNamespace = serializeNamespace;
+exports.syncedContractSurface = syncedContractSurface;
 exports.t = t;
 exports.toMany = toMany;
 exports.toOne = toOne;