@ultimat3/entity 1.1.0 → 2.0.0

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. */

package/src/type-pins.ts

@@ -0,0 +1,311 @@
+// Compile-time pins for the two type positions this package has already regressed in. Source, not
+// a `.test.ts`, on purpose: `tsconfig.json` excludes `src/**/*.test.ts`, so `tsc -b` never reads a
+// test file and a type-level assertion written there can never fail. Everything below is erased —
+// the module emits nothing — and a regression is a build error, which is the only kind of
+// enforcement this repo counts (axiom 3).
+
+import type { Id } from '@ultimat3/core';
+import type { MoneyValue as SchemaMoneyValue } from '@ultimat3/schema';
+import type { uuid } from './columns';
+import type { EntitySet } from './database';
+import type { Entity, EntityCore, EntityInit } from './entity';
+import type { ColumnExpr, InvariantColumns } from './expr';
+import type { Invariant, InvariantDef } from './invariants';
+import type { Table } from './query';
+import type { Repo } from './repo';
+import type { AnyColumn, IdOf, Insertable, MoneyInput, MoneyValue, RowOf } from './types';
+
+/** Fails to compile when `T` is anything but `true`. The whole mechanism. */
+type Assert<T extends true> = T;
+
+/**
+ * Shaped like a declared column set; only its keys and its derived row take part. A type alias,
+ * not an interface: only an alias gets the implicit index signature `ColumnMap` asks for.
+ */
+type PinColumns = {
+  readonly title: AnyColumn;
+  readonly price: AnyColumn;
+};
+
+type PinRow = RowOf<PinColumns>;
+
+/** Ambient: a type query needs a value to name, and an ambient declaration emits nothing. */
+declare const pinned: InvariantColumns<PinColumns>;
+
+/**
+ * The defect: `InvariantColumns` was `{ readonly [column: string]: ColumnExpr }`, so under
+ * `noUncheckedIndexedAccess` every `c.title` was `ColumnExpr | undefined` and every generated
+ * entity needed a `!`. Written as a property access rather than an indexed-access type, because
+ * that is the position the flag widens.
+ */
+export type PinColumnIsNotOptional = Assert<undefined extends typeof pinned.title ? false : true>;
+
+export type PinColumnIsAColumnExpr = Assert<
+  [typeof pinned.title] extends [ColumnExpr] ? true : false
+>;
+
+/** An index signature would make every string a key, so a typo would type-check. */
+export type PinUnknownColumnIsNotAKey = Assert<
+  'titel' extends keyof InvariantColumns<PinColumns> ? false : true
+>;
+
+/** `unique()` and `satisfies()` name columns as strings, so they need the same protection. */
+export type PinHelpersTakeDeclaredColumns = Assert<
+  readonly 'titel'[] extends Parameters<InvariantColumns<PinColumns>['unique']>[0] ? false : true
+>;
+
+/**
+ * `invariants` is one callback over the whole list, never an array of `(c) => …` builders: a
+ * per-element builder is a call TypeScript checks before `C` is fixed, so `C` fell back to its
+ * constraint and the mapped type above never reached the author.
+ */
+export type PinInvariantsIsOneCallback = Assert<
+  EntityInit<PinColumns>['invariants'] extends
+    | ((columns: InvariantColumns<PinColumns>) => readonly InvariantDef[])
+    | undefined
+    ? true
+    : false
+>;
+
+/**
+ * `Invariant<T>.holds` is a method, not a `readonly holds: (row: T) => boolean` property. A
+ * function-typed property is checked contravariantly, which made `Invariant<PinRow>` unassignable
+ * to `Invariant<unknown>`, `Entity<PinRow, C>` unassignable to `EntityCore`, and so every
+ * `database({ … })` call degrade to `Table<unknown>` — one position, 36 cascading errors.
+ */
+export type PinInvariantIsBivariant = Assert<
+  [Invariant<PinRow>] extends [Invariant<unknown>] ? true : false
+>;
+
+export type PinEntityIsAnEntityCore = Assert<
+  [Entity<PinRow, PinColumns>] extends [EntityCore] ? true : false
+>;
+
+export type PinEntityMapIsAnEntitySet = Assert<
+  [{ readonly post: Entity<PinRow, PinColumns> }] extends [EntitySet] ? true : false
+>;
+
+// --- Insertable: a nullable column is omissible ------------------------------
+// `nullable()` widens the type to `T | null` without setting `$optional`, so before this pin every
+// insert had to spell out `avatarKey: null, deletedAt: null` — restating an absence the column
+// declaration already carries, for values SQL was going to write as NULL either way. The demo's
+// seed could not compile without that padding, which is precisely the boilerplate this framework
+// exists to delete.
+
+declare const nullableColumn: import('./types').Column<string | null, false>;
+declare const requiredColumn: import('./types').Column<string, false>;
+
+type InsertPinColumns = {
+  readonly required: typeof requiredColumn;
+  readonly optionalByNull: typeof nullableColumn;
+};
+
+type InsertPin = import('./types').Insertable<InsertPinColumns>;
+
+/** The nullable column may be omitted entirely… */
+type _NullableIsOmissible = Assert<{ required: 'x' } extends InsertPin ? true : false>;
+
+/** …and passing `null` explicitly stays legal, so a programmatic caller need not strip keys. */
+type _NullableStillAccepted = Assert<
+  { required: 'x'; optionalByNull: null } extends InsertPin ? true : false
+>;
+
+/** A non-nullable column with no default is still required — the pin must not over-relax. */
+type _RequiredStaysRequired = Assert<{ optionalByNull: null } extends InsertPin ? false : true>;
+
+// --- The bulk write path keeps every narrowing the single-row one has ---------
+// `insertAll`/`upsertAll` are `insert` in bulk, and a bulk signature is exactly where one quietly
+// widens: `readonly Row[]` instead of `readonly Insertable<C>[]` would make every batch spell out
+// the defaults `insert` fills for one row, and a `readonly string[]` conflict target would push a
+// typo the single-row path never had to the runtime guard.
+
+type InsertPinTable = Table<RowOf<InsertPinColumns>, InsertPinColumns>;
+type ConflictTarget = Parameters<InsertPinTable['upsertAll']>[1]['onConflict'];
+
+/** A batch is `Insertable`, so a nullable column stays omissible a hundred rows at a time. */
+type _InsertAllTakesInsertables = Assert<
+  readonly { required: 'x' }[] extends Parameters<InsertPinTable['insertAll']>[0] ? true : false
+>;
+
+/** What comes back is the stored row, never the insertable the caller handed in. */
+type _InsertAllResolvesWithRows = Assert<
+  [Awaited<ReturnType<InsertPinTable['insertAll']>>] extends [readonly RowOf<InsertPinColumns>[]]
+    ? true
+    : false
+>;
+
+type _ConflictTargetTakesADeclaredColumn = Assert<
+  readonly 'required'[] extends ConflictTarget ? true : false
+>;
+
+/** The narrowing that matters: a misspelled conflict target is a compile error, not a rejection. */
+type _ConflictTargetRejectsATypo = Assert<
+  readonly 'requiredd'[] extends ConflictTarget ? false : true
+>;
+
+// --- A branded id survives the whole type chain ------------------------------
+// `uuid<PostId>()` is where the brand is declared, and every hop after it has to carry it. The
+// derivation (`TypeOf`, `RowOf`, `Insertable`) always did; the BUILDER hard-coded `Column<string>`
+// so there was nothing to carry, and `Repo`/`Table` then took `id: string`, which is where the
+// last of it went. Both halves are pinned, because fixing either one alone still lets
+// `posts.update(someUserId, …)` compile.
+
+type PostId = Id<'post'>;
+type UserId = Id<'user'>;
+
+/** The builder's own output, not a hand-written `Column<PostId, true>`. */
+type BrandedKey = ReturnType<ReturnType<typeof uuid<PostId>>['primaryKey']>;
+
+type BrandColumns = {
+  readonly id: BrandedKey;
+  readonly authorId: ReturnType<typeof uuid<UserId>>;
+  readonly title: typeof requiredColumn;
+};
+
+type BrandRow = RowOf<BrandColumns>;
+
+type _BrandSurvivesTheRow = Assert<[BrandRow['id']] extends [PostId] ? true : false>;
+
+/** The half that matters: a plain string is no longer good enough to be a post id. */
+type _RowIdIsNotAPlainString = Assert<[string] extends [BrandRow['id']] ? false : true>;
+
+/** Two entities' ids do not mix, which is the whole reason to declare one. */
+type _BrandsDoNotMix = Assert<[BrandRow['authorId']] extends [PostId] ? false : true>;
+
+/** The write path too — an insert that names the wrong entity's id is a compile error. */
+type _BrandSurvivesTheInsert = Assert<
+  [Insertable<BrandColumns>['authorId']] extends [UserId] ? true : false
+>;
+
+type _InsertRejectsAnotherBrand = Assert<
+  [PostId] extends [Insertable<BrandColumns>['authorId']] ? false : true
+>;
+
+/** `Repo` was the last hop that erased it: `findById(id: string)` accepted any entity's id. */
+type _FindByIdTakesTheBrand = Assert<
+  [Parameters<Repo<BrandRow>['findById']>[0]] extends [PostId] ? true : false
+>;
+
+type _FindByIdRejectsAnotherBrand = Assert<
+  [UserId] extends [Parameters<Repo<BrandRow>['findById']>[0]] ? false : true
+>;
+
+/**
+ * `UpsertArgs<T>.onConflict` is `readonly (keyof T & string)[]`, which is `readonly never[]` at
+ * `T = unknown` — so a typed repository must still satisfy the row-agnostic one `RelatedTable.repo`
+ * and the generated admin are written against, or narrowing the target breaks the preload seam.
+ */
+type _TypedRepoIsARowAgnosticRepo = Assert<[Repo<BrandRow>] extends [Repo<unknown>] ? true : false>;
+
+type _TableUpdateTakesTheBrand = Assert<
+  [Parameters<Table<BrandRow>['update']>[0]] extends [PostId] ? true : false
+>;
+
+type _TableDeleteRejectsAnotherBrand = Assert<
+  [UserId] extends [Parameters<Table<BrandRow>['delete']>[0]] ? false : true
+>;
+
+/**
+ * …and an unbranded entity is addressed exactly as it was. `IdOf` collapsing to `string` for
+ * every row that declared no brand is what makes this additive rather than a major version.
+ */
+type _UnbrandedIdStaysAString = Assert<
+  [string] extends [IdOf<{ readonly id: string }>] ? true : false
+>;
+
+// --- The batch iteration stays consumable both ways --------------------------
+// `inBatches()` is the one read that hands back a resource instead of a value, and both ways of
+// consuming it are language features rather than methods a call site would obviously miss:
+// `for await` needs `[Symbol.asyncIterator]`, `await using` needs `[Symbol.asyncDispose]`. Losing
+// either is a silent regression — every existing call keeps compiling, and only the loop that was
+// supposed to stop reading stops stopping.
+
+type BatchPin = ReturnType<Table<BrandRow>['inBatches']>;
+
+type _BatchIterates = Assert<
+  [BatchPin] extends [AsyncIterable<readonly BrandRow[]>] ? true : false
+>;
+
+type _BatchDisposes = Assert<[BatchPin] extends [AsyncDisposable] ? true : false>;
+
+/** Batches, never rows: yielding one row at a time is the loop this call exists to replace. */
+type _BatchYieldsBatches = Assert<[BatchPin] extends [AsyncIterable<BrandRow>] ? false : true>;
+
+type _RowAgnosticIdStaysAString = Assert<[string] extends [IdOf<unknown>] ? true : false>;
+
+// --- Money is one declaration, and the wide half is the write half -----------
+// `MoneyValue` was a third structural restatement of `Money` whose `minor` was a `bigint`, so a
+// row this package decoded satisfied neither `t.money` nor `JSON.stringify` — the shape the whole
+// framework passes around was not the shape its own driver produced. It is now an alias of
+// `@ultimat3/schema`'s declaration, which is also what `@ultimat3/money`'s `Money` is; these pins
+// are what stops the next edit from re-declaring it here and re-opening the same gap.
+
+/**
+ * Identity, not mutual assignability: `extends` ignores `readonly`, so the weaker test would pass
+ * against a mutable restatement — which is exactly the drift being pinned against.
+ */
+type Identical<X, Y> =
+  (<T>() => T extends X ? 1 : 2) extends <T>() => T extends Y ? 1 : 2 ? true : false;
+
+type _MoneyValueIsSchemasDeclaration = Assert<Identical<MoneyValue, SchemaMoneyValue>>;
+
+/** The value type is a `number`. A `bigint` here is the regression, not a widening. */
+type _MoneyMinorIsANumber = Assert<[MoneyValue['minor']] extends [number] ? true : false>;
+
+// The shape is pinned as independent properties rather than as one literal snapshot of the whole
+// interface. The snapshot said the same thing, but every additive change had to be hand-edited
+// past it — and a pin the next reader learns to hand-edit reflexively has stopped being a check.
+// Only the key set moves when a field is added, which is the one place that decision belongs.
+
+/** No field but these three, ever: a fourth is a shape nobody declared. */
+type _MoneyHasNoOtherField = Assert<
+  [keyof MoneyValue] extends ['minor' | 'currency' | 'scale'] ? true : false
+>;
+
+/** …and none of the three may go — the pin must not pass by the type shrinking instead. */
+type _MoneyHasEveryField = Assert<
+  ['minor' | 'currency' | 'scale'] extends [keyof MoneyValue] ? true : false
+>;
+
+// Immutable, enforced, field by field: a mutable `minor` is a rounding bug with a place to hide.
+// `Pick` carries `readonly` and optionality through, so each of these is exact about one field
+// and says nothing about the others.
+
+type _MoneyMinorIsAReadonlyNumber = Assert<
+  Identical<Pick<MoneyValue, 'minor'>, { readonly minor: number }>
+>;
+
+type _MoneyCurrencyIsAReadonlyString = Assert<
+  Identical<Pick<MoneyValue, 'currency'>, { readonly currency: string }>
+>;
+
+/**
+ * `scale` is the decimal exponent `minor` counts in — `{ minor: 2, currency: 'USD', scale: 6 }` is
+ * $0.000002. Optional, and pinned optional, because a cents-only `Money` could not name a
+ * sub-cent amount at all: the AI cost path rounded a $0.00016 call up to a whole cent, 62x, and
+ * the alternative to this field was a second money type.
+ */
+type _MoneyScaleIsAReadonlyOptionalNumber = Assert<
+  Identical<Pick<MoneyValue, 'scale'>, { readonly scale?: number }>
+>;
+
+/**
+ * The additive half, and the pin that decides the semver: a value carrying no scale is still a
+ * `MoneyValue`, meaning the currency's own minor unit. Every amount already stored, serialized
+ * and asserted against in every app is that shape — so the day this fails, the change that made
+ * it fail is a breaking one and needs a major, not a fix here.
+ */
+type _MoneyWithoutAScaleIsStillMoney = Assert<
+  { readonly minor: number; readonly currency: string } extends MoneyValue ? true : false
+>;
+
+/**
+ * A writer may still hand a `bigint` — that is the additive half, and it is what lets a minor unit
+ * read straight off a `bigint` column reach an insert without a conversion at the call site.
+ */
+type _MoneyInputTakesABigInt = Assert<
+  [{ readonly minor: bigint; readonly currency: string }] extends [MoneyInput] ? true : false
+>;
+
+/** And a row value is always a legal input: read a row, write it back. */
+type _MoneyValueIsMoneyInput = Assert<[MoneyValue] extends [MoneyInput] ? true : false>;

package/src/types.ts

@@ -28,16 +28,35 @@ export interface ReferenceOptions {
   readonly onDelete?: OnDelete;
 }
 
-/** The single value a money column puts on the row. Two physical columns back it. */
-export interface MoneyValue {
-  readonly minor: bigint;
-  readonly currency: string;
-}
+/**
+ * The single value a money column puts on the row. Two physical columns back it.
+ *
+ * An **alias** of `@ultimat3/schema`'s declaration, which is also what `@ultimat3/money`'s `Money`
+ * is — so a row this package decodes IS a `Money`, assignable to `add()`, `formatMoney()` and
+ * `<Money>` without a cast. It used to be a third, structurally different interface whose `minor`
+ * was a `bigint`, and that was a live defect rather than a stylistic one: `JSON.stringify` throws
+ * on a bigint, so returning a row with a money column from an action crashed the response, and
+ * `t.money` — the schema node that becomes the OpenAPI contract — rejected the framework's own row.
+ */
+import type { MoneyValue } from '@ultimat3/schema';
 
-/** What a writer may hand a money column. An integer `number` widens; a float throws. */
+export type { MoneyValue };
+
+/**
+ * What a writer may hand a money column. An integer `number` is the value type; a `bigint` is
+ * accepted so a minor unit read straight off a `bigint` column (hand-written SQL, a backfill)
+ * needs no conversion at the call site. A float throws, and so does a `bigint` past
+ * `Number.MAX_SAFE_INTEGER` — see `parseMinor` in `columns.ts`.
+ */
 export interface MoneyInput {
   readonly minor: bigint | number;
   readonly currency: string;
+  /**
+   * Carried through the write, never invented: `undefined` means the currency's own minor unit and
+   * `0` means whole units, and the two must not collapse. `null` is accepted because that is what
+   * the `<name>_scale` column holds for an amount that declared none.
+   */
+  readonly scale?: number | null;
 }
 
 /**
@@ -82,9 +101,16 @@ export interface Column<T, Optional extends boolean = false> {
   default(value: T): Column<T, true>;
 }
 
-/** A uuid primary key is generated (v7) when omitted, which is why it narrows to `true`. */
-export interface UuidColumn<Optional extends boolean = false> extends Column<string, Optional> {
-  primaryKey(): Column<string, true>;
+/**
+ * A uuid primary key is generated (v7) when omitted, which is why it narrows to `true`.
+ *
+ * `T` is the declared id type: `uuid<PostId>()` carries the brand from here to the row, the
+ * insert and every repository signature, so a `PostId` cannot be passed where a `UserId` is
+ * wanted. It defaults to `string`, so an unbranded declaration reads exactly as it did.
+ */
+export interface UuidColumn<T extends string = string, Optional extends boolean = false>
+  extends Column<T, Optional> {
+  primaryKey(): Column<T, true>;
 }
 
 export interface TimestampColumn<Optional extends boolean = false> extends Column<Date, Optional> {
@@ -98,6 +124,18 @@ export type ColumnMap = Readonly<Record<string, AnyColumn>>;
 
 export type TypeOf<C> = C extends Column<infer T, boolean> ? T : never;
 
+/**
+ * How a row is addressed: the type its own `id` column declared, or `string` when the entity is
+ * keyed by something else (a composite key, or an unbranded uuid).
+ *
+ * This is where a brand used to die. `RowOf` and `Insertable` carry it through the derivation
+ * without help, but `Repo.findById(id: string)` and `Table.update(id: string, …)` erased it at
+ * the last hop — so `posts.update(someUserId, …)` type-checked and Postgres returned nothing.
+ * `IdOf<Row>` collapses to `string` for every unbranded entity, so nothing that compiled before
+ * stops compiling.
+ */
+export type IdOf<Row> = Row extends { readonly id: infer I extends string } ? I : string;
+
 /** The row type a column set describes. This derivation is why the package exists. */
 export type RowOf<C extends ColumnMap> = {
   readonly [K in keyof C]: TypeOf<C[K]>;
@@ -107,14 +145,28 @@ type DefaultedKeys<C extends ColumnMap> = {
   [K in keyof C]-?: C[K]['$optional'] extends true ? K : never;
 }[keyof C];
 
+/**
+ * A `.nullable()` column is omissible too, and that is not a convenience — it is the difference
+ * between declaring a fact and restating an absence. `nullable()` widens the type to `T | null`
+ * without setting `$optional`, so every insert had to spell out `avatarKey: null, deletedAt: null`
+ * for columns whose whole meaning is "there may be nothing here", and SQL was going to write NULL
+ * either way. That is boilerplate the declaration already contains.
+ *
+ * Omitting it and passing `null` stay equivalent, deliberately: a caller building a row
+ * programmatically should not have to strip keys to avoid a type error.
+ */
+type NullableKeys<C extends ColumnMap> = {
+  [K in keyof C]-?: null extends TypeOf<C[K]> ? K : never;
+}[keyof C];
+
 /** Money is the one column whose write shape is wider than its row shape. */
 type InputOf<T> = T extends MoneyValue ? MoneyInput : T;
 
-/** What an insert must supply: every column except the ones carrying a default. */
+/** What an insert must supply: every column that is neither defaulted nor nullable. */
 export type Insertable<C extends ColumnMap> = {
-  readonly [K in Exclude<keyof C, DefaultedKeys<C>>]: InputOf<TypeOf<C[K]>>;
+  readonly [K in Exclude<keyof C, DefaultedKeys<C> | NullableKeys<C>>]: InputOf<TypeOf<C[K]>>;
 } & {
-  readonly [K in DefaultedKeys<C>]?: InputOf<TypeOf<C[K]>>;
+  readonly [K in DefaultedKeys<C> | NullableKeys<C>]?: InputOf<TypeOf<C[K]>>;
 };
 
 export interface IndexDef {