@ultimat3/entity 1.2.0 → 3.0.0

package/src/seed.ts

@@ -1,17 +1,27 @@
-// A seed is the fixture graph, written once and replayed anywhere. `id('post:tenancy')` is a
-// UUID v5 of the label, so the same row gets the same id on every machine and a bug reproduced
-// locally reproduces in CI. Rows go through `entity.$parse` and the invariants, which makes a
-// seed a test of the schema as well as data for one.
+// A seed is the fixture graph, written once and REPLAYED anywhere: a second run writes nothing new
+// and raises nothing. Two write verbs, because only the author knows which key identifies a row —
+// `insert` where the seed owns the id (`id('post:tenancy')` is a v5 uuid of the label, the same on
+// every machine), `upsert` where the table owns it and a natural key is all there is.
 
 import { createHash } from 'node:crypto';
+import { type Environment, resolveEnvironment, systemClock } from '@ultimat3/core';
 import type { Driver } from './database';
 import { memoryDriver } from './database';
-import type { EntityCore } from './entity';
+import { type EntityCore, SOFT_DELETE_COLUMN } from './entity';
+import { EntityError } from './errors';
+import type { Predicate } from './tenancy';
 import type { ColumnMap, Insertable } from './types';
 
 /** Framework namespace for seed labels. Fixed forever: changing it moves every seeded id. */
 const NAMESPACE = 'a3c1f0d6-5c2b-4a3e-9f1b-6d4e7c8a9b02';
 
+/**
+ * What a replay never overwrites, unless `preserve` says otherwise. Spelled here as a constant for
+ * the reason `SOFT_DELETE_COLUMN` is: the timestamp convention is the framework's, so the column a
+ * seed must not reset is decided once.
+ */
+const CREATED_AT_COLUMN = 'createdAt';
+
 const bytesOf = (uuid: string): Uint8Array =>
   Uint8Array.from((uuid.replaceAll('-', '').match(/../g) ?? []).map((pair) => parseInt(pair, 16)));
 
@@ -35,35 +45,294 @@ export const seedId = (label: string): string => {
   ].join('-');
 };
 
+/**
+ * Which deploys a seed belongs to, declared as DATA on the seed and never inferred from its name.
+ *
+ * `reference` is data the app is wrong without — currencies, plans, service tiers, locations — and
+ * it ships to production through this same mechanism. `dev` is fixture data, and production is the
+ * one environment it must not reach by accident. The word is the seed's; the refusal is the
+ * caller's (`x db seed`), because an app that seeds its own database from its boot code has
+ * DECIDED to (axiom 8) and a library that overruled that would break it.
+ */
+export const SEED_TIERS = ['reference', 'dev'] as const;
+
+export type SeedTier = (typeof SEED_TIERS)[number];
+
+/**
+ * The tiers a run takes when nothing asked for one: everything, except that production leaves
+ * `dev` out. `requested` is both the selection AND the consent, one word doing one job — a cluster
+ * that sets `ULTIMATE_ENV=production` on every box (staging included) still loads its dev seeds by
+ * naming the tier, instead of by lying about the environment.
+ */
+export const seedTiersFor = (
+  environment: Environment,
+  requested?: SeedTier | undefined,
+): readonly SeedTier[] => {
+  if (requested !== undefined) return [requested];
+  return environment === 'production' ? ['reference'] : [...SEED_TIERS];
+};
+
+/** What one `upsert` did. `skipped` is a row already stored with these values — no statement. */
+export type SeedWrite = 'inserted' | 'updated' | 'skipped';
+
+/** One run's tally, in the three words every seed report is built from. */
+export interface SeedMetrics {
+  inserted: number;
+  updated: number;
+  skipped: number;
+}
+
+export interface SeedKey<Row> {
+  /**
+   * The columns of the unique constraint this row is identified by — its NATURAL key, which is the
+   * only key a seed writing into an existing table can know. A target no declared constraint
+   * matches is refused by `upsertPlan` before a statement is sent (`42P10` otherwise).
+   */
+  readonly by: readonly (keyof Row & string)[];
+  /**
+   * Columns a collision leaves alone. `createdAt` by default, and that default is the point: a
+   * replay must not reset when a row first arrived. The conflict target, the primary key and the
+   * soft-delete stamp are spared by `upsertPlan` already.
+   */
+  readonly preserve?: readonly (keyof Row & string)[];
+}
+
 export interface SeedContext {
+  /**
+   * Rows whose ids the SEED chose, written in one statement and replayable by primary key: a row
+   * already stored is left exactly as it is (`on conflict … do nothing`). The bulk verb — one
+   * statement per call, not one per row.
+   */
   insert<Row, C extends ColumnMap>(
     entity: EntityCore<Row, C>,
     rows: readonly Insertable<C>[],
   ): Promise<void>;
+  /**
+   * One row whose id the TABLE owns, matched on the natural key `by` names. Reads first so the
+   * answer can be `'skipped'`, then writes with a single `on conflict … do update`, which is what
+   * settles the race between two containers booting at once — the read is for the report, never
+   * for the decision.
+   */
+  upsert<Row, C extends ColumnMap>(
+    entity: EntityCore<Row, C>,
+    key: SeedKey<Row>,
+    values: Insertable<C>,
+  ): Promise<SeedWrite>;
+  /**
+   * The other unit of idempotency: the FILE. Bulk volume data has no natural key worth upserting
+   * ten thousand rows against, so the guard is a sentinel — `if (await exists(reports)) return;`
+   * at the top of the seed.
+   */
+  exists<Row, C extends ColumnMap>(
+    entity: EntityCore<Row, C>,
+    where?: Partial<Row>,
+  ): Promise<boolean>;
+  count<Row, C extends ColumnMap>(
+    entity: EntityCore<Row, C>,
+    where?: Partial<Row>,
+  ): Promise<number>;
+  /** Scoped wipe before a regenerate. Refused on a soft-deleting entity — see `softDeleteWipe`. */
+  deleteWhere<Row, C extends ColumnMap>(
+    entity: EntityCore<Row, C>,
+    where: Partial<Row>,
+  ): Promise<number>;
   /** Deterministic id for a label. Same label, same uuid, every run. */
   id(label: string): string;
+  /** One instant for the whole run, so every row a bulk pass stamps carries the same timestamp. */
+  readonly now: Date;
+  readonly environment: Environment;
+  readonly tier: SeedTier;
+  /** Reads still run; every write short-circuits and is counted as what it WOULD have written. */
+  readonly dryRun: boolean;
+  readonly metrics: SeedMetrics;
 }
 
 export interface SeedOptions {
   /** Defaults to a fresh in-memory driver, so a seed runs with no database at all. */
   readonly driver?: Driver;
+  readonly dryRun?: boolean;
+  /** Injected for a test; `process.env` otherwise. Read once, by `resolveEnvironment`. */
+  readonly env?: Readonly<Record<string, string | undefined>> | undefined;
+}
+
+export interface SeedRun {
+  readonly name: string;
+  readonly tier: SeedTier;
+  readonly metrics: SeedMetrics;
 }
 
 export interface Seed {
   readonly name: string;
-  run(options?: SeedOptions): Promise<void>;
+  readonly tier: SeedTier;
+  run(options?: SeedOptions): Promise<SeedRun>;
 }
 
-export const defineSeed = (name: string, build: (context: SeedContext) => Promise<void>): Seed => ({
-  name,
-  run: async (options = {}) => {
-    const driver = options.driver ?? memoryDriver();
-    await build({
-      insert: async (entity, rows) => {
-        const repo = driver.repo(entity);
-        for (const row of rows) await repo.insert(entity.$parse(row));
-      },
-      id: seedId,
-    });
-  },
-});
+export interface SeedInit {
+  /** Defaults to `dev`: fixture data is what a seed is until its author says otherwise. */
+  readonly tier?: SeedTier;
+}
+
+/** What `x db seed` picks out of a module. Same shape rule as `isRouteConfig`. */
+export const isSeed = (value: unknown): value is Seed =>
+  typeof value === 'object' &&
+  value !== null &&
+  typeof (value as { name?: unknown }).name === 'string' &&
+  typeof (value as { run?: unknown }).run === 'function' &&
+  (SEED_TIERS as readonly unknown[]).includes((value as { tier?: unknown }).tier);
+
+/** Property access on a parsed row without `any`: `$parse` fills every declared column. */
+const cellOf = (row: unknown, property: string): unknown =>
+  (row as Readonly<Record<string, unknown>>)[property];
+
+/**
+ * Two cells, as a replay has to compare them: a `Date` is not `===` a `Date` and money is an
+ * object, so both are compared by value and everything else by identity.
+ */
+const sameCell = (left: unknown, right: unknown): boolean => {
+  if (left instanceof Date || right instanceof Date) {
+    return left instanceof Date && right instanceof Date && left.getTime() === right.getTime();
+  }
+  if (typeof left === 'object' && left !== null && typeof right === 'object' && right !== null) {
+    return JSON.stringify(left) === JSON.stringify(right);
+  }
+  return left === right;
+};
+
+const equalityPredicates = <Row>(where: Partial<Row>): readonly Predicate[] =>
+  Object.entries(where).map(([column, value]): Predicate => ({ column, op: 'eq', value }));
+
+/**
+ * The entity's own key as a conflict target. `$primaryKey` is `readonly string[]` because an
+ * entity does not know its row type at that field, and `onConflict` is typed by the row.
+ */
+const primaryKeyTarget = <Row>(entity: EntityCore<Row>): readonly (keyof Row & string)[] =>
+  entity.$primaryKey as readonly (keyof Row & string)[];
+
+/**
+ * A primary key the row leaves to a GENERATED default is a different id on every run, so the
+ * conflict target finds nothing and each replay inserts one more copy. `$parse` refuses a key with
+ * no value at all; this is the half it cannot see, because filling that column is what it does.
+ */
+const generatedKey = (entity: EntityCore, missing: string, position: number): EntityError =>
+  new EntityError({
+    code: 'X_INVARIANT_VIOLATED',
+    cause: `${entity.$name} seed row ${position + 1} leaves "${missing}" to a generated default, and a primary key generated fresh on every run is a row every replay inserts a second copy of`,
+    fix: `insert(${entity.$name}, rows.map((row, index) => ({ ...row, ${missing}: id(\`${entity.$name}:\${index}\`) })))   # id() is a uuid v5 of the label: same row, same id, every run`,
+  });
+
+/**
+ * Deleting from a soft-deleting entity inside a seed, refused rather than documented. The stamp is
+ * what makes it unrecoverable: `upsertPlan` spares the soft-delete column on purpose and the stored
+ * row still occupies its unique key, so the replay that was supposed to bring the rows back writes
+ * nothing at all and the fixture is gone until the database is.
+ */
+const softDeleteWipe = (entity: EntityCore): EntityError =>
+  new EntityError({
+    code: 'X_INVARIANT_VIOLATED',
+    cause: `${entity.$name} declares ${SOFT_DELETE_COLUMN}, so deleteWhere() would stamp its seeded rows rather than remove them — the stamped row keeps its unique key, and no replay of this seed can clear it`,
+    fix: 'x db reset --json   # the only wipe a soft-deleting entity has; drop the deleteWhere() call from the seed',
+  });
+
+/** The row an update may write: everything the caller named, less what a match must not move. */
+const withoutPreserved = <Row>(row: Row, preserve: readonly string[]): Row => {
+  const copy: Record<string, unknown> = { ...(row as Record<string, unknown>) };
+  for (const property of preserve) delete copy[property];
+  // `Repo` is typed for whole rows, and a partial one is exactly what keeps a column OUT of the
+  // update set — `namedProperties` reads what the row owns. Same assertion the bulk live test takes.
+  return copy as Row;
+};
+
+export const defineSeed = (
+  name: string,
+  build: (context: SeedContext) => Promise<void>,
+  init: SeedInit = {},
+): Seed => {
+  const tier = init.tier ?? 'dev';
+  return {
+    name,
+    tier,
+    run: async (options = {}) => {
+      const driver = options.driver ?? memoryDriver();
+      const dryRun = options.dryRun ?? false;
+      const metrics: SeedMetrics = { inserted: 0, updated: 0, skipped: 0 };
+      const context: SeedContext = {
+        insert: async (entity, rows) => {
+          // Judged on the row as WRITTEN, before `$parse` fills the column that would hide it.
+          for (const [position, row] of rows.entries()) {
+            const missing = entity.$primaryKey.find(
+              (property) =>
+                entity.$columns[property]?.$meta.default?.kind === 'generated' &&
+                !Object.hasOwn(row, property),
+            );
+            if (missing !== undefined) throw generatedKey(entity, missing, position);
+          }
+          const parsed = rows.map((row) => entity.$parse(row));
+          if (dryRun) {
+            metrics.inserted += parsed.length;
+            return;
+          }
+          const written = await driver.repo(entity).upsertAll(parsed, {
+            onConflict: primaryKeyTarget(entity),
+            // Never `'update'`: a do-nothing conflict needs no tenant column in the target, so this
+            // is the one form that replays on a tenant-scoped entity whose unique keys are global.
+            onMatch: 'nothing',
+          });
+          metrics.inserted += written.length;
+          metrics.skipped += parsed.length - written.length;
+        },
+
+        upsert: async (entity, key, values) => {
+          const row = entity.$parse(values);
+          const repo = driver.repo(entity);
+          const where = Object.fromEntries(
+            key.by.map((property) => [property, cellOf(row, property)]),
+          );
+          const found = await repo.findMany({ where: equalityPredicates(where), limit: 1 });
+          const stored = found.rows[0];
+          const preserve: readonly string[] = key.preserve ?? [CREATED_AT_COLUMN];
+          const compared = Object.keys(row as Record<string, unknown>).filter(
+            (property) => !preserve.includes(property),
+          );
+          if (
+            stored !== undefined &&
+            compared.every((property) => sameCell(cellOf(stored, property), cellOf(row, property)))
+          ) {
+            metrics.skipped += 1;
+            return 'skipped';
+          }
+          const write: SeedWrite = stored === undefined ? 'inserted' : 'updated';
+          if (!dryRun) {
+            await repo.upsertAll([stored === undefined ? row : withoutPreserved(row, preserve)], {
+              onConflict: key.by,
+              onMatch: 'update',
+            });
+          }
+          metrics[write === 'inserted' ? 'inserted' : 'updated'] += 1;
+          return write;
+        },
+
+        count: async (entity, where) =>
+          driver
+            .repo(entity)
+            .count(where === undefined ? {} : { where: equalityPredicates(where) }),
+
+        exists: async (entity, where) => (await context.count(entity, where)) > 0,
+
+        deleteWhere: async (entity, where) => {
+          if (entity.$softDelete) throw softDeleteWipe(entity);
+          if (dryRun) return context.count(entity, where);
+          return driver.repo(entity).deleteWhere(where);
+        },
+
+        id: seedId,
+        now: systemClock.now(),
+        environment: resolveEnvironment({ env: options.env }),
+        tier,
+        dryRun,
+        metrics,
+      };
+      await build(context);
+      return { name, tier, metrics };
+    },
+  };
+};

package/src/tenancy.ts

@@ -1,8 +1,16 @@
-// Multi-tenancy is a guard, not a convention. An entity with a tenant column can only be read
-// through a plan that carries an org predicate; building one without it throws
-// `X_TENANCY_UNSCOPED` at the seam instead of leaking another tenant's rows.
+// Multi-tenancy is a guard, not a convention. An entity with a tenant column is read AND written
+// under the acting actor's tenant — derived from the ambient context, never taken from an argument
+// — and a plan or a row that names a different one is refused rather than carried out.
 
-import { EntityError, tenancyUnscoped } from './errors';
+import { tryUseContext } from '@ultimat3/core';
+import { assertCrossTenant, crossTenantReason } from './cross-tenant';
+import {
+  EntityError,
+  tenancyActorMismatch,
+  tenancyActorOrgRequired,
+  tenancyRowMismatch,
+  tenancyUnscoped,
+} from './errors';
 import type { ColumnMap } from './types';
 
 export type Operator =
@@ -67,8 +75,7 @@ export const resolveTenantColumn = (
   columns: ColumnMap,
   declared: string | undefined,
 ): string | null => {
-  if (declared === undefined) return tenantColumnOf(columns);
-  if (!Object.hasOwn(columns, declared)) {
+  if (declared !== undefined && !Object.hasOwn(columns, declared)) {
     const available = Object.keys(columns).join(', ');
     // Not `invariantViolated`: its fix points at `x entity explain`, which describes invariants
     // the author never wrote. What repairs this is one edit to the declaration, so the error
@@ -79,7 +86,24 @@ export const resolveTenantColumn = (
       fix: `set tenant to one of ${available} in entity('${entityName}'), or remove the tenant key — inference then takes the .tenant() column, else one named ${ORG_COLUMN}`,
     });
   }
-  return declared;
+  const property = declared ?? tenantColumnOf(columns);
+  if (property === null) return null;
+  // A NULLABLE tenant column is refused here, at the declaration, and this is the same guard as
+  // the one above rather than an extra rule: `assertRowTenant` returns early on a row that names
+  // no tenant — "left alone, and the column's NOT NULL answers it" — so on a nullable column the
+  // delegation has nothing to delegate to. The row lands with a null tenant, and a null is
+  // matched by no `org_id = $1`: it is invisible to every tenant-scoped read, so it never appears
+  // in an export, never goes in an offboarding sweep, and sits in the table owned by nobody.
+  // A tenant that may be absent is a table that is only sometimes multi-tenant, which is not a
+  // shape this layer can enforce — so it is refused where the author can see it.
+  if (columns[property]?.$meta.notNull === false) {
+    throw new EntityError({
+      code: 'X_INVARIANT_VIOLATED',
+      cause: `${entityName}.${property} is the tenant column and is nullable — a row written with no ${property} is matched by no tenant-scoped query, so it belongs to nobody and no sweep can ever find it`,
+      fix: `drop .nullable() from ${property} in entity('${entityName}'), then x db gen "backfill ${entityName} ${property}" — a row with no tenant needs one before the column can refuse it`,
+    });
+  }
+  return property;
 };
 
 export const emptyPlan = (entity: string, limit = 50): QueryPlan => ({
@@ -89,10 +113,19 @@ export const emptyPlan = (entity: string, limit = 50): QueryPlan => ({
   limit,
 });
 
+/**
+ * Whether the plan mentions the tenant column at all — never whether it mentions the right VALUE,
+ * which is why this is not the guard. `scopedPlan` compares against the actor; this answers the
+ * narrower question the derivation asks before it appends a predicate that already exists.
+ */
 export const hasOrgPredicate = (plan: QueryPlan, column: string = ORG_COLUMN): boolean =>
   plan.where.some((predicate) => predicate.column === column);
 
-/** Adds the org predicate exactly once; calling it twice is not an error. */
+/**
+ * Adds the org predicate exactly once; calling it twice is not an error. The explicit form of what
+ * `scopedPlan` does from the actor — and inside a request it must name that same tenant, or the
+ * plan is refused as `X_TENANCY_ACTOR_MISMATCH`. It adds a predicate; it never authorises one.
+ */
 export const orgScoped = (
   plan: QueryPlan,
   orgId: string,
@@ -103,8 +136,101 @@ export const orgScoped = (
     : { ...plan, where: [...plan.where, { column, op: 'eq', value: orgId }] };
 
 /**
- * Called by every repository operation. Runtime here, and a build-time check in `x verify`
- * that no query for a tenant-scoped entity is constructed without it.
+ * The tenant every plan for a scoped entity runs under: the acting actor's own, or `undefined`
+ * when there is no request context to take one from.
+ *
+ * An actor that carries no tenant is refused rather than allowed to name one — anonymous is the
+ * case that must not read a tenant table by asking nicely, and a service actor minted without an
+ * org is a boundary that forgot to resolve it. `crossTenant()` is the way to mean it on purpose.
+ *
+ * No context at all is a different situation and not a caller-reachable one: every entry point in
+ * the framework runs its handler inside `runWithContext`, so this is a script, a boot path or a
+ * test harness, with no identity to check a value against. Those callers still have to name the
+ * tenant themselves — `verifyScope` refuses an unscoped plan exactly as it always did.
+ */
+const actorTenant = (entityName: string, operation: string): string | undefined => {
+  const ctx = tryUseContext();
+  if (ctx === undefined) return undefined;
+  const { actor } = ctx;
+  if (actor.orgId === undefined) {
+    throw tenancyActorOrgRequired({
+      entityName,
+      operation,
+      actorId: actor.id,
+      actorKind: actor.kind,
+    });
+  }
+  return actor.orgId;
+};
+
+/**
+ * Every predicate on the tenant column has to be `eq` the actor's own tenant. Every one, and `eq`
+ * only: `where('orgId', 'in', [mine, theirs])` names a tenant that is not the actor's just as
+ * plainly as `where('orgId', 'eq', theirs)` does, and a plan carrying both predicates is answered
+ * by the narrower of the two — so checking "one of them matches" would pass a plan whose rows come
+ * from a set the actor never proved they own.
+ */
+const verifyScope = (
+  entityName: string,
+  tenantColumn: string,
+  operation: string,
+  plan: QueryPlan,
+  actorOrg: string | undefined,
+): void => {
+  const named = plan.where.filter((predicate) => predicate.column === tenantColumn);
+  // `actorOrg` goes in so the refusal states which of the two situations this is: `scopedPlan`
+  // never reaches here with an actor (it derives first), but `assertScoped` verifies plans it did
+  // not build, and telling that caller "no actor carried a tenant" would be false.
+  if (named.length === 0) throw tenancyUnscoped(entityName, operation, actorOrg);
+  if (actorOrg === undefined) return;
+  for (const predicate of named) {
+    if (predicate.op !== 'eq' || predicate.value !== actorOrg) {
+      throw tenancyActorMismatch({ entityName, operation, named: predicate.value, actorOrg });
+    }
+  }
+};
+
+/**
+ * The plan a tenant-scoped operation actually runs, with the actor's tenant applied. Called by
+ * every repository operation through `readPlan`, so both drivers and every read, write and count
+ * pass through this one derivation.
+ *
+ * Runtime only. There is no build-time tenancy step in `x verify` — its 17 steps check none — and
+ * there cannot usefully be one: the tenant is a request-time value, so a compiler could only prove
+ * that some argument was passed, which is exactly the thing that was never a guarantee. That is
+ * why this is the seam every plan is built through rather than a lint.
+ */
+export const scopedPlan = (
+  entityName: string,
+  tenantColumn: string | null,
+  operation: string,
+  plan: QueryPlan,
+): QueryPlan => {
+  if (tenantColumn === null) return plan;
+  const crossing = crossTenantReason();
+  // Re-proved per plan, not trusted from the scope's own entry: `withChildContext({ actor })`
+  // swaps the actor without closing the scope.
+  if (crossing !== undefined) {
+    assertCrossTenant(crossing);
+    return plan;
+  }
+  const actorOrg = actorTenant(entityName, operation);
+  // Derived only when the caller named nothing: a predicate that is already there is checked
+  // rather than joined by a second one, so a disagreement is refused instead of being answered by
+  // whichever of the two the driver applies first.
+  const scoped =
+    actorOrg !== undefined && !hasOrgPredicate(plan, tenantColumn)
+      ? orgScoped(plan, actorOrg, tenantColumn)
+      : plan;
+  verifyScope(entityName, tenantColumn, operation, scoped, actorOrg);
+  return scoped;
+};
+
+/**
+ * The same guard, verifying a plan that is already built — for a caller holding one this layer did
+ * not construct. It cannot derive (there is nowhere to put the predicate), so a plan that names no
+ * tenant is `X_TENANCY_UNSCOPED` even where the actor carries one; `scopedPlan` is the path that
+ * fills it in.
  */
 export const assertScoped = (
   entityName: string,
@@ -113,8 +239,64 @@ export const assertScoped = (
   plan: QueryPlan,
 ): void => {
   if (tenantColumn === null) return;
-  if (hasOrgPredicate(plan, tenantColumn)) return;
-  throw tenancyUnscoped(entityName, operation);
+  const crossing = crossTenantReason();
+  if (crossing !== undefined) {
+    assertCrossTenant(crossing);
+    return;
+  }
+  verifyScope(entityName, tenantColumn, operation, plan, actorTenant(entityName, operation));
+};
+
+/**
+ * The tenant a row or a patch names, or `undefined` for one that names none. `undefined` is read
+ * as "not named" rather than as a value: it is what `namedColumns` already drops from a filter,
+ * and a row whose tenant column is genuinely missing is refused one step later by the column's own
+ * `NOT NULL` — by the declaration, which is where that rule belongs.
+ */
+const tenantValueOf = (values: unknown, column: string): unknown => {
+  if (typeof values !== 'object' || values === null || !Object.hasOwn(values, column)) {
+    return undefined;
+  }
+  return (values as Record<string, unknown>)[column];
+};
+
+/**
+ * The write half of the guard: a row or a patch may name the acting actor's tenant, or none, and
+ * nothing else. Called wherever a driver is about to write values — `insert`, `insertAll`,
+ * `upsertAll`, `update`, `updateWhere` — because those build no read plan, so `scopedPlan` never
+ * sees them and an `orgId` in a row literal would otherwise be a tenant the caller chose.
+ *
+ * **Refuse, never stamp.** A row that names no tenant is left alone rather than filled in from the
+ * actor. Stamping is the ergonomic half and it is deliberately not here: `namedProperties` decides
+ * an `upsertAll`'s column list by `Object.hasOwn`, so a stamped column would change which columns
+ * the statement writes, silence the uneven-batch refusal that exists because `excluded.<col>` is a
+ * default and not "leave it alone", and — where the conflict target includes the tenant column —
+ * let ambient state decide which stored row a collision lands on. A write that creates data from
+ * the ambient context is a bigger decision than this guard, and it is not needed for the security
+ * property: a wrong tenant is refused either way.
+ */
+export const assertRowTenant = (
+  entityName: string,
+  tenantColumn: string | null,
+  operation: string,
+  values: unknown,
+): void => {
+  if (tenantColumn === null) return;
+  // Before the "names no tenant" shortcut, exactly as `scopedPlan` proves it before deriving: an
+  // insert builds no plan, so this is the only place a write inside somebody else's sweep re-proves
+  // the capability, and a row that names nothing is still a row written under that scope.
+  const crossing = crossTenantReason();
+  if (crossing !== undefined) {
+    assertCrossTenant(crossing);
+    return;
+  }
+  const named = tenantValueOf(values, tenantColumn);
+  if (named === undefined) return;
+  const actorOrg = actorTenant(entityName, operation);
+  // No request context: no actor to check the value against, and the same fallback the read path
+  // takes — a script, a seed or a migration writes the tenant it names.
+  if (actorOrg === undefined || named === actorOrg) return;
+  throw tenancyRowMismatch({ entityName, operation, column: tenantColumn, named, actorOrg });
 };
 
 /** Debug and `x db explain` rendering. Values stay out: a plan is safe to log. */