@ultimat3/entity 5.0.1 → 7.0.0

package/CLAUDE.md

@@ -4,7 +4,7 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
 
 ## Boundary
 
-- May import `@ultimat3/core`, `@ultimat3/schema` and `@ultimat3/db`. Nothing else — `http`,
+- May import `@ultimat3/core`, `@ultimat3/schema`, `@ultimat3/db` and `@ultimat3/time` (tier 1 — `columns.ts` and `columns-data.ts` read its `isValidTimeZone`, so a zone this package accepts is one `@ultimat3/time` can do arithmetic in). Nothing else — `http`,
   `policy` and `auth` are the same tier.
 - `db` is tier 1 (it imports only `core`), which is what lets the Postgres driver live **here**
   rather than in a tier-3 package: `Driver` and its production implementation stay in one place.
@@ -564,13 +564,28 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   hole open on exactly the unauthenticated path. **Outside every request context there is no actor
   to derive from** — a script, a seed, a test harness — so the caller names the tenant itself and
   `X_TENANCY_UNSCOPED` still refuses a plan that names none. There is no build-time tenancy step in
-  `x verify` (its 17 steps check none) and the old comment in `tenancy.ts` claiming one was wrong:
+  `x verify` (its 19 steps check none) and the old comment in `tenancy.ts` claiming one was wrong:
   the tenant is a request-time value, so the seam is the enforcement.
 - **`crossTenant(reason, fn)` (`cross-tenant.ts`) is the ONE way to read across tenants**, for the
   three cases that have no single one: an admin surface over every org, background reconciliation,
-  support tooling. An `AsyncLocalStorage` scope with a written reason, the same shape
+  support tooling. An async-context scope with a written reason, the same shape
   `@ultimat3/db`'s `expectedQueryLoop` has, never a boolean argument on a repository call — which
   reads exactly like forgetting the tenant — and never a config list of exempt entities (axiom 1).
+  The scope opens through `asyncContext<string>('the cross-tenant reason')` from `@ultimat3/core`,
+  **never a `new AsyncLocalStorage` here, and that is a build error rather than a convention `As of
+  2026-08`** — `scripts/async-context-guard.ts` refuses the construction *and* the import that
+  binds the class, anywhere but `packages/core/src/async-context.ts`, and
+  `scripts/async-context-guard.test.ts` runs it over the tree in the gate's `unit` step. The
+  module-scope `new` this replaced threw `TypeError: undefined is not a constructor` at module
+  **evaluation** in a browser bundle, where the bundler stubs `node:async_hooks` to `{}`, taking
+  every importer of `cross-tenant.ts` with it. Now the module evaluates and `crossTenantReason()`
+  answers `undefined` there — in a browser nothing IS in flight, so that is the true answer. A
+  write is the case that names itself: `storage.run` throws `X_ASYNC_CONTEXT_UNAVAILABLE` instead
+  of a bare `TypeError`, though `crossTenant()` reaches it only past `assertCrossTenant`, which
+  wants a request context a browser does not have. A server saves no allocation — the store is
+  built on the first `get()` **or** `run()`, so a read constructs it too; what the laziness costs
+  is nothing observable, since `getStore()` outside a scope answers `undefined` whether the storage
+  existed or not.
   **The capability is proven twice**: `CROSS_TENANT_SCOPE` (`tenancy:cross`) on the actor, at the
   call and again at every plan built inside it, because `withChildContext({ actor })` swaps the
   actor without closing the scope and an impersonated caller must not inherit it —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/entity",
-  "version": "5.0.1",
+  "version": "7.0.0",
   "description": "A table + its domain type + invariants the database also enforces",
   "license": "MIT",
   "type": "module",
@@ -31,9 +31,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "5.0.1",
-    "@ultimat3/db": "5.0.1",
-    "@ultimat3/schema": "5.0.1",
-    "@ultimat3/time": "5.0.1"
+    "@ultimat3/core": "7.0.0",
+    "@ultimat3/db": "7.0.0",
+    "@ultimat3/schema": "7.0.0",
+    "@ultimat3/time": "7.0.0"
   }
 }

package/src/columns.ts

@@ -10,6 +10,7 @@ import {
   isMoneyScale,
   MAX_MONEY_SCALE,
 } from '@ultimat3/schema';
+import { isValidTimeZone } from '@ultimat3/time';
 import {
   assertColumnName,
   BARE,
@@ -176,22 +177,22 @@ export const url = (): Column<string> =>
     { check: (name) => `${name} ~ '^https?://'` },
   );
 
-const isIanaZone = (value: string): boolean => {
-  try {
-    new Intl.DateTimeFormat('en', { timeZone: value }).format(0);
-    return true;
-  } catch {
-    return false;
-  }
-};
-
 /**
- * IANA identifiers, checked against `Intl` when the column is declared — a typo or a UTC offset
- * is a startup error rather than a row nobody can format. An offset is wrong twice a year.
+ * IANA identifiers, checked when the column is declared — a typo, an abbreviation or a UTC offset
+ * is a startup error rather than a row nobody can format.
+ *
+ * The check is `@ultimat3/time`'s own `isValidTimeZone`, imported and never restated: `time` is
+ * tier 1 and this package is tier 2, so the one rule is a downward import away. A local
+ * `new Intl.DateTimeFormat(…)` probe was the second answer to that question, and the two stopped
+ * agreeing — `Intl` answers "can I format this", never "is this IANA", and ICU 78 (Bun 1.4)
+ * resolves `CET`, `EST`, `GMT`, `Zulu` and `Japan`, so `tz(['CET'])` declared a column every
+ * `format` call above it then refused with `X_TIMEZONE_INVALID`. A leading-sign offset (`+01:00`)
+ * resolved under every runtime this framework has shipped on, and carries no DST rule at all, so
+ * it is wrong twice a year on top of being unformattable.
  */
 export const tz = <const Z extends readonly string[]>(zones: Z): Column<Z[number]> => {
   for (const zone of zones) {
-    if (!isIanaZone(zone)) reject('iana-tz', `${zone} is not an IANA time zone`);
+    if (!isValidTimeZone(zone)) reject('iana-tz', `${zone} is not an IANA time zone`);
   }
   const allowed = new Set<string>(zones);
   return column<Z[number]>(

package/src/cross-tenant.ts

@@ -3,11 +3,11 @@
 // reads exactly like forgetting the tenant, and never a config list of exempt entities (axiom 1):
 // both put the argument somewhere other than the read it defends.
 
-// `node:` because Bun exposes no native async-context primitive: the scope has to outlive every
-// `await` inside it, and `AsyncLocalStorage` is the only thing that carries a value across them.
-// A module-scope flag would be shared by two concurrent requests — one of them ordinary.
-import { AsyncLocalStorage } from 'node:async_hooks';
-import { actorLabel, assert, hasScope, tryUseContext } from '@ultimat3/core';
+// The scope has to outlive every `await` inside it and a module-scope flag would be shared by two
+// concurrent requests — one of them ordinary — so it needs an async context. Opened through core's
+// one lazy seam rather than a `node:async_hooks` construction here, which threw at module
+// EVALUATION in a browser bundle (the bundler stubs the module to `{}`).
+import { actorLabel, assert, asyncContext, hasScope, tryUseContext } from '@ultimat3/core';
 import { crossTenantDenied } from './errors';
 
 /**
@@ -18,7 +18,7 @@ import { crossTenantDenied } from './errors';
  */
 export const CROSS_TENANT_SCOPE = 'tenancy:cross';
 
-const storage = new AsyncLocalStorage<string>();
+const storage = asyncContext<string>('the cross-tenant reason');
 
 /**
  * Run `fn` with the tenant guard lifted — every read and write it issues, at any depth and across
@@ -54,7 +54,7 @@ export function crossTenant<T>(reason: string, fn: () => T): T {
  * The innermost enclosing reason, or `undefined` outside every scope — which is every query in an
  * app that never calls `crossTenant`. Read by the tenant guard, and by nothing else.
  */
-export const crossTenantReason = (): string | undefined => storage.getStore();
+export const crossTenantReason = (): string | undefined => storage.get();
 
 /**
  * The capability check itself, run at `crossTenant()` and again for every plan built inside it.