@ultimat3/flags 2.0.0

package/CLAUDE.md

@@ -0,0 +1,98 @@
+# @ultimat3/flags — boundary
+
+Tier 1. May import `@ultimat3/core` and nothing else. Never sideways, never upward.
+
+Tier 1 is the lowest its real imports allow — the same rule that placed `db`. Evaluation needs an
+`Actor`, a `Clock` and `UltimateError`, all tier 0. It deliberately does **not** import `entity`,
+`query` or `policy`: a store read on the hot path would make `isEnabled()` async, and tier 1 is
+what lets `policy` (tier 2) call it from inside a predicate.
+
+| Rule | Detail |
+|---|---|
+| Exports | `src/index.ts`, explicit, no `export *` |
+| Errors | `src/errors.ts`, subclass `UltimateError`, never a bare `Error` |
+| Files | one responsibility each, < 200 lines, tests beside the source |
+| Subjects | `src/subject.ts` — one resolver; never a second allow list per record kind |
+
+## Invariants
+
+- **`defineFlag()` is a `define*` helper, not a ninth primitive.** A flag has no handler, no input
+  schema and no surface of its own, so there is nothing for `primitiveRegistrar` to project. The
+  eight kinds in `PRIMITIVE_KINDS` stay eight. A capability that *does* need a handler arrives as a
+  factory over an existing primitive — `llm()` returns an `action`.
+- **Evaluation is synchronous, and allocates nothing per declared subject kind.** It runs inside
+  policy predicates and render passes. No `await`, no I/O, no date parsing (`expiresAtMs` is
+  precomputed), and the expired-flag error is built lazily so a rate-limited call costs a map
+  lookup. It is **not literally allocation-free** — `roles` allocates a closure for `some()`, and
+  `subjectIdOf` takes an options object — so do not restate that stronger claim. What is
+  guaranteed: no `Object.entries`/`Object.keys` pass, no normalisation pass, and nothing at all
+  allocated for a flag declaring no subject axis.
+- **A temporary flag without an expiry must not be declarable.** `FlagExpiryIsMandatory` in
+  `flag.ts` is a compile-time assertion: loosen the union and `tsc -b packages/flags` fails on that
+  line. `toFlag()` re-checks at runtime for snapshots and JS callers. Do not replace either with a
+  lint rule.
+- **`X_FLAG_EXPIRED` is reported, never thrown.** A framework that took production down on a date
+  nobody remembered setting would teach everyone to declare every flag `permanent`, which is the
+  failure this design exists to prevent.
+- **The reporter is core's, not this package's.** `reportError({ source: 'process', severity:
+  'warning' })` is the one error-monitoring seam; a second one here would be a second place an app
+  wires its monitor and a second place to look when a report does not arrive. `runtime.ts` holds
+  the framework's ONE `reportError` call site in this package, same rule as the metric recorders.
+  Never name a vendor here (axiom 7).
+- **The rate limit is keyed on `clock.monotonic()`**, not wall time: an NTP correction or a
+  container resuming must not reopen the window and flood the monitor.
+- **Buckets are `fnv1a(key + ':' + subjectId) % 100`.** Never `Math.random()`, and never the
+  subject id alone — hashing the subject by itself puts the same cohort in the first slice of every
+  rollout the app ever runs. **The assignments are pinned in `bucket.test.ts`**: a rollout already
+  live is a promise to the subjects inside it, so changing the hash must break that test, never
+  move the boundary silently.
+- **A flag decides about a SUBJECT, and the actor is one kind of subject.** `subject.ts` owns the
+  resolution. `actor` and `org` come off the `Actor`; every other kind comes from the `subjects`
+  argument at the call site. `actors` and `orgs` in targeting are shorthands for the first two
+  kinds, not separate mechanisms — do not add a fourth parallel allow list for a new record kind,
+  it already works through `subjects`. `roles` is NOT a subject: a role is a predicate over the
+  actor, has no id, and cannot bucket.
+- **One source per kind.** A built-in kind is never read from the call-site map, so there is no
+  precedence rule and no second place a tenant comes from. Passing `org` at a call site is dead
+  data; with no `actor.orgId` the evaluation raises and the fix line says to mint the actor.
+  `assertTargeting` refuses `subjects.actor` / `subjects.org` for the same reason.
+- **The kind space is open, like the flag key space.** No registry of kinds: a typo raises
+  `X_FLAG_SUBJECT_REQUIRED` at the first evaluation, the same loud failure `X_FLAG_UNKNOWN` already
+  gives an undeclared key. Do not add a `defineSubjectKinds()` — it is a second declaration surface
+  buying a check evaluation already makes.
+- **Allow lists beat the rollout.** An operator who named a subject is not overruled by a hash.
+  `actors`, `roles`, `orgs` and `subjects` are one rank — any hit is `true`, so their order is
+  unobservable. That is the same OR Flipper applies across the actors passed to one `enabled?`.
+- **The subject axis throws rather than degrades.** A kind the evaluation context does not carry
+  raises `X_FLAG_SUBJECT_REQUIRED`. Never fall back to the actor axis or to `default`: an answer
+  about a record computed from whoever was calling looks like it worked, which is the whole bug
+  class. **Every declared kind is resolved before any branch answers** — allow lists included — so
+  the raise depends only on the flag and the context, never on declaration order and never on which
+  list happened to match. An early `return true` on an allow-list hit is the regression to watch
+  for: it hides a missing record from exactly the callers who are on the list. A `null` actor is
+  the one exception and still gets `default` — no evaluation context at all, every such call
+  answers alike, so no single subject is split.
+- **`bucketBy` defaults to `actor`.** The subject axes are opt-in; a flag declared before they
+  existed must answer identically, which is why the default is not `org`.
+- **Subject lookups are own-property only.** `subjects[kind]` goes through `Object.hasOwn` and a
+  `typeof` re-check, so a kind named `toString` or `constructor` is absent rather than resolving to
+  an inherited function, and a non-string id never reaches `bucketOf`. Same rule for the targeting
+  map, which is why the loop is `for…in` + `Object.hasOwn` and not `Object.entries`.
+- **Every app-supplied string in a `fix:` goes through `JSON.stringify`, and a subject kind becomes
+  a computed key.** A `bank-integration` kind is not a valid identifier, so `{ bank-integration: … }`
+  would be a fix that does not parse — axiom 4 wants an instruction that runs. Pinned by
+  `errors.test.ts` running the generated snippet through `new Function`.
+- **An unknown key throws.** Answering `false` is a branch that never runs and never says so.
+- `default: true` beside a `rollout` is refused: the two answer the same actors and disagree.
+
+## Open
+
+- Nothing calls `flagsReport()` yet. It is the projection an `x flags [--json]` command and an MCP
+  `flags.list` tool should read; neither exists.
+
+## Commands
+
+```
+bun test packages/flags
+bun run --filter @ultimat3/flags typecheck
+```

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 developerz.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,189 @@
+# @ultimat3/flags
+
+Feature flags: permanent switches, and temporary ones that cannot be forgotten.
+
+Feature flags are normally a bad trade — N flags are 2^N states nothing tested. This package takes
+the trade only on terms that bound the exponent: every flag declares which of two kinds it is, and
+a `temporary` flag carries an expiry it cannot be declared without. Past that date, every
+evaluation reports the flag to the app's error monitor and the projection lists it as expired. The
+permanent set is a product surface; the temporary set is forced to shrink.
+
+## The two kinds
+
+| Kind | Meaning | Lifecycle rule |
+|---|---|---|
+| `permanent` | a real product or ops switch — a plan capability, a kill switch, a rollout that became the product | none; it legitimately lives forever |
+| `temporary` | scaffolding around an in-progress change | `expiresAt` and `owner` are **required**; past the expiry every evaluation reports `X_FLAG_EXPIRED` |
+
+Omitting `expiresAt` on a `temporary` flag is a **type** error, not a lint rule —
+`FlagExpiryIsMandatory` in `src/flag.ts` is a compile-time assertion that fails `tsc` if the union
+is ever loosened. `toFlag()` re-checks it at runtime, because a store snapshot and a plain-JS
+caller have no types to be checked by.
+
+## Declaring
+
+```ts
+import { defineFlag } from '@ultimat3/flags';
+
+export const dunning = defineFlag({
+  kind: 'permanent',
+  key: 'billing.dunning-emails',
+  description: 'ops kill switch for dunning email delivery',
+  targeting: { default: true },
+});
+
+export const newTaxEngine = defineFlag({
+  kind: 'temporary',
+  key: 'checkout.new-tax-engine',
+  description: 'routes checkout through the rewritten tax engine',
+  owner: 'payments',
+  expiresAt: '2026-12-01',
+  targeting: { default: false, rollout: 10, roles: ['staff'] },
+});
+```
+
+`defineFlag()` is a `define*` helper, like `defineRoles` and `defineCatalogs`. It is **not** a ninth
+primitive: a flag has no handler, no input schema and no surface of its own, so there is nothing for
+the registrar to project. The eight primitives stay eight.
+
+## Reading
+
+```ts
+import { isEnabled } from '@ultimat3/flags';
+
+if (isEnabled('checkout.new-tax-engine', actor)) {
+  // …
+}
+
+// with the app's own records in play
+if (isEnabled('scraper.persist-profile', actor, { bank: bank.id })) {
+  // …
+}
+```
+
+Synchronous, for the same reason `can()` is: this runs inside policy predicates and render passes,
+and an `await` there turns every guarded branch into an async boundary. An undeclared key throws
+`X_FLAG_UNKNOWN` rather than answering `false` — a typo that reads as "off" is a branch that
+silently never runs in production.
+
+## Targeting
+
+| Field | Meaning |
+|---|---|
+| `default` | the answer when no allow list and no rollout claims this actor |
+| `actors` | actor ids that are always on, ahead of any rollout |
+| `roles` | actor roles that are always on, ahead of any rollout |
+| `orgs` | org ids that are always on — shorthand for the `org` subject kind, read from `actor.orgId` |
+| `subjects` | allow lists for the app's own record kinds: `{ bank: ['bank_integration:bbva'] }` |
+| `rollout` | whole percentage 0-100, stable per bucketing subject |
+| `bucketBy` | which subject kind the rollout divides: `'actor'` (default), `'org'`, or any kind the call site carries |
+
+Order is allow lists → rollout → default. `actors`, `roles`, `orgs` and `subjects` are one rank —
+any hit is `true`. An operator who names a subject is not overruled by a hash. A rollout buckets
+`fnv1a(key + ':' + subjectId) % 100`, never `Math.random()`: one subject gets one answer on every
+call, in every process, without the nodes talking to each other.
+
+## Subjects — what a flag decides about
+
+A flag decides about an **identified record**: a user, a tenant, a bank integration, a device. The
+actor is one subject kind among several, not a privileged one.
+
+| Kind | Where its id comes from |
+|---|---|
+| `actor` | `actor.id` — spelled `actors` in targeting |
+| `org` | `actor.orgId` — spelled `orgs` in targeting |
+| anything else | the `subjects` argument at the call site |
+
+```ts
+// whole tenants, named — the 90% case, which is why it has a shorthand
+targeting: { default: false, orgs: ['org_acme'] }
+
+// 10% of tenants, each one whole
+targeting: { default: false, rollout: 10, bucketBy: 'org' }
+
+// the app's own record kind
+targeting: { default: false, subjects: { bank: ['bank_integration:bbva'] } }
+isEnabled('scraper.persist-profile', actor, { bank: 'bank_integration:bbva' });
+
+// 10% of banks, each bank whole
+targeting: { default: false, rollout: 10, bucketBy: 'bank' }
+```
+
+`actor` and `org` are resolved from the `Actor` and **never** from the call-site map — one source
+per kind, so there is no precedence rule to remember and no second place a tenant can come from.
+Every other kind is the app's vocabulary; the kind space is open, exactly like the flag key space.
+
+Bucketing by a record is what keeps it **whole**. An actor-bucketed rollout cuts through a tenant:
+3 of an org's 30 members on the new export path and 27 on the old, sharing documents, filing a bug
+nobody can reproduce. `bucketBy` puts the whole subject on one side. `'actor'` stays the default,
+so every flag declared before this axis answers exactly as it did.
+
+`roles` is deliberately **not** a subject kind: a role is a predicate over the actor, not an
+identified record, so it has no id to hash and cannot bucket a rollout.
+
+### A missing subject is an error, not a fallback
+
+If targeting decides by a kind the evaluation context does not carry, `isEnabled()` throws
+`X_FLAG_SUBJECT_REQUIRED`. It never falls back to the actor axis or to `default`: an answer about a
+record computed from whoever happened to be calling is the exact failure this axis removes, and it
+looks like it worked. Every declared kind is resolved before any of them can answer, so the raise
+does not depend on the order the keys sit in.
+
+A `null` actor is the one exception and still gets `default` — it says there is no evaluation
+context at all, every such call answers alike, and no single subject is split.
+
+## Overrides, out of band
+
+```ts
+applyFlagSnapshot({ 'billing.dunning-emails': { default: false } });
+```
+
+This is the half that keeps evaluation synchronous. A poller, a job or a realtime channel lands the
+store's targeting; `isEnabled()` never loads anything. Keys this build does not declare are
+returned in `unknown` rather than thrown — a control plane is routinely ahead of a deploy, and a
+kill switch that refuses to land because the payload mentioned tomorrow's flag is one that does not
+work on the day it is needed.
+
+## Reporting
+
+There is no reporter seam in this package. An overdue flag goes through `@ultimat3/core`'s
+`ErrorReporter` — the framework's one error-monitoring seam — as a `warning` from `source:
+'process'`, so an app wires its monitor in exactly one place:
+
+```ts
+configureErrorReporting({ reporter: sentryErrorReporter({ dsn }) });
+```
+
+What this package adds is the rate limit core has no opinion about: one report per flag per
+`DEFAULT_REPORT_INTERVAL_MS` (1 hour), on the **monotonic** clock, so a flag read on every request
+does not become the loudest thing in the monitor — which is how a report that fires per call ends
+up muted and the debt invisible again. `configureFlags({ clock, reportEveryMs })` tunes it.
+
+## Projection
+
+`flagsReport()` returns every declared flag with its kind, expiry, owner and whether it is expired,
+sorted by key, plus the expired keys lifted out. It is the one shape `x flags --json`, an MCP tool
+and the manifest should all read, so none of them recomputes "expired".
+
+## What it owns
+
+| Module | Owns |
+|---|---|
+| `src/flag.ts` | the two kinds, the compile-time expiry rule, normalisation |
+| `src/targeting.ts` | who a flag is on for; declaration-time validation |
+| `src/subject.ts` | what a flag decides about — subject kinds and how each resolves to an id |
+| `src/bucket.ts` | the stable `(flag, subject)` bucket — FNV-1a, never `Math.random()` |
+| `src/registry.ts` | `defineFlag`, key → flag, `applyFlagSnapshot` |
+| `src/runtime.ts` | the clock and the per-flag report rate limit over core's `reportError` |
+| `src/evaluate.ts` | `isEnabled()` — the one way to ask |
+| `src/projection.ts` | `flagsReport()` for the CLI, MCP and the manifest |
+| `src/errors.ts` | this package's X_* codes |
+
+## Boundary
+
+Tier 1. May import tiers 0-0 only — enforced by `bun run scripts/boundaries.ts`.
+
+## Errors
+
+`X_FLAG_DUPLICATE` · `X_FLAG_EXPIRED` · `X_FLAG_EXPIRY_INVALID` · `X_FLAG_SUBJECT_REQUIRED` ·
+`X_FLAG_TARGETING_INVALID` · `X_FLAG_UNKNOWN`

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@ultimat3/flags",
+  "version": "2.0.0",
+  "description": "Feature flags: permanent switches, and temporary ones that cannot be forgotten",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/developerz-ai/ultimate.git",
+    "directory": "packages/flags"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "CLAUDE.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@ultimat3/core": "2.0.0"
+  }
+}

package/src/bucket.ts

@@ -0,0 +1,36 @@
+// Single responsibility: the stable bucket a (flag, subject) pair falls into. The subject is an
+// actor id or an org id — same hash either way, so a tenant is whole. Never `Math.random()`:
+// a rollout that re-rolls per call shows one user the new experience on one request and the old
+// one on the next, which is a worse product than no rollout at all — and untestable besides.
+
+/** A rollout is declared as a percentage, so the bucket space is 100. */
+export const BUCKETS = 100;
+
+const FNV_OFFSET_BASIS = 0x811c_9dc5;
+const FNV_PRIME = 0x0100_0193;
+
+/**
+ * 32-bit FNV-1a. Chosen over a cryptographic digest because bucketing is not a security decision
+ * and this one is synchronous, dependency-free and identical in every process — which is the
+ * property that matters: two nodes must agree about one actor without talking to each other.
+ */
+export function fnv1a(text: string): number {
+  let hash = FNV_OFFSET_BASIS;
+  for (let index = 0; index < text.length; index += 1) {
+    hash ^= text.charCodeAt(index);
+    hash = Math.imul(hash, FNV_PRIME);
+  }
+  return hash >>> 0;
+}
+
+/**
+ * The flag key is hashed WITH the subject id, not the subject id alone: hashing the subject by
+ * itself would put the same unlucky cohort in the first 10% of every 10% rollout the app ever
+ * runs, so one group of users — or one group of tenants — would meet every half-finished feature.
+ *
+ * `subjectId` is whatever axis the targeting buckets by: an actor id, or an org id when
+ * `bucketBy: 'org'` keeps a tenant on one side of the boundary. Pure, so two nodes agree about a
+ * subject without talking, and a restart does not re-roll anyone.
+ */
+export const bucketOf = (key: string, subjectId: string): number =>
+  fnv1a(`${key}:${subjectId}`) % BUCKETS;

package/src/errors.ts

@@ -0,0 +1,145 @@
+// The X_* codes owned by @ultimat3/flags. Each names the exact edit that resolves it.
+// `X_FLAG_EXPIRED` is the odd one out on purpose: it is REPORTED to the error monitor, never
+// thrown, because an overdue flag must become impossible to forget without taking production
+// down with it — the branch keeps working, the debt stops being invisible.
+import { registerErrorCodes, UltimateError } from '@ultimat3/core';
+
+export const FLAGS_ERROR_CODES = [
+  'X_FLAG_DUPLICATE',
+  'X_FLAG_EXPIRED',
+  'X_FLAG_EXPIRY_INVALID',
+  'X_FLAG_SUBJECT_REQUIRED',
+  'X_FLAG_TARGETING_INVALID',
+  'X_FLAG_UNKNOWN',
+] as const;
+
+export type FlagsErrorCode = (typeof FLAGS_ERROR_CODES)[number];
+
+export const FLAGS_ERROR_TITLES: Readonly<Record<FlagsErrorCode, string>> = {
+  X_FLAG_DUPLICATE: 'two flags were declared with the same key',
+  X_FLAG_EXPIRED: 'a temporary flag is past its expiry and is still being evaluated',
+  X_FLAG_EXPIRY_INVALID: 'a temporary flag has no usable expiry date',
+  X_FLAG_SUBJECT_REQUIRED: 'a flag decides by a subject the evaluation context does not carry',
+  X_FLAG_TARGETING_INVALID: 'flag targeting is out of range or malformed',
+  X_FLAG_UNKNOWN: 'no flag is declared under this key',
+};
+
+// Registered unconditionally at import, like every other package: a second package claiming one
+// of these codes must surface as X_ERROR_CODE_DUPLICATE, never as a silent first-wins.
+registerErrorCodes(
+  Object.fromEntries(Object.entries(FLAGS_ERROR_TITLES).map(([code, title]) => [code, { title }])),
+);
+
+export class FlagsError extends UltimateError {
+  override readonly name = 'FlagsError';
+
+  constructor(init: {
+    code: FlagsErrorCode;
+    cause: string;
+    fix: string;
+    meta?: Readonly<Record<string, unknown>> | undefined;
+  }) {
+    super({
+      code: init.code,
+      cause: init.cause,
+      fix: init.fix,
+      docs: `https://ultimate.dev/errors/${init.code}`,
+      meta: init.meta,
+    });
+  }
+}
+
+export const flagDuplicate = (key: string): FlagsError =>
+  new FlagsError({
+    code: 'X_FLAG_DUPLICATE',
+    cause: `"${key}" is already declared, so one of the two declarations would decide nothing`,
+    fix: `rename one of the two defineFlag({ key: '${key}' }) declarations`,
+    meta: { key },
+  });
+
+export const flagUnknown = (key: string, known: readonly string[]): FlagsError =>
+  new FlagsError({
+    code: 'X_FLAG_UNKNOWN',
+    cause: `"${key}" is not declared (${known.length} flags known), so it has no default, no owner and no expiry`,
+    fix: `declare it with defineFlag({ key: '${key}', ... }), or correct the key at the isEnabled() call site`,
+    meta: { key },
+  });
+
+/** `fix` is a parameter because a bad `bucketBy` is not repaired by editing `rollout` — axiom 4. */
+export const flagTargetingInvalid = (key: string, problem: string, fix?: string): FlagsError =>
+  new FlagsError({
+    code: 'X_FLAG_TARGETING_INVALID',
+    cause: `${key}: ${problem}`,
+    fix: fix ?? `set rollout to an integer 0-100 in defineFlag({ key: '${key}' })`,
+    meta: { key },
+  });
+
+/** Which targeting field asked for the subject, so the fix names an edit rather than a mechanism. */
+export type FlagSubjectVia = 'orgs' | 'subjects' | 'bucketBy';
+
+/**
+ * Thrown, never softened into a fallback. Answering a subject-scoped flag from the actor axis — or
+ * from the declared default — is the exact failure the subject axis exists to remove: it looks
+ * like it worked, and the record finds out when half of it is on a different code path.
+ *
+ * The fix differs by kind because the edit does: a missing org is repaired where the actor is
+ * minted, a missing record is repaired at the call site that already holds it.
+ */
+export const flagSubjectRequired = (init: {
+  key: string;
+  kind: string;
+  actorId: string;
+  via: FlagSubjectVia;
+}): FlagsError =>
+  new FlagsError({
+    code: 'X_FLAG_SUBJECT_REQUIRED',
+    cause: `${init.key} decides by the "${init.kind}" subject (targeting.${init.via}) but the evaluation context carries no ${init.kind} id for actor "${init.actorId}", so there is nothing to decide about`,
+    // Every app-supplied string goes through JSON.stringify, and the kind becomes a COMPUTED key:
+    // a `bank-integration` kind — the realistic shape, next to treasury's `bank_integration:` ids
+    // — is not a valid identifier, so `{ bank-integration: … }` would hand the reader a fix that
+    // does not parse. Axiom 4: an instruction that cannot be run is not one.
+    fix:
+      init.kind === 'org'
+        ? `mint the actor with its tenant — userActor({ id: ${JSON.stringify(init.actorId)}, orgId: '<org>' }) — before the isEnabled(${JSON.stringify(init.key)}) call, or drop ${init.via} from defineFlag({ key: ${JSON.stringify(init.key)} })`
+        : `pass the record at the call site — isEnabled(${JSON.stringify(init.key)}, actor, { [${JSON.stringify(init.kind)}]: '<id>' }) — or drop the ${JSON.stringify(init.kind)} ${init.via} entry from defineFlag({ key: ${JSON.stringify(init.key)} })`,
+    meta: { key: init.key, kind: init.kind, actorId: init.actorId, via: init.via },
+  });
+
+/**
+ * `JSON.stringify` throws on a bigint or a cycle, and RUNS a `toJSON` the value carries — so an
+ * app object can hijack an error constructor with its own throw, and the caller then catches
+ * something that is not `X_FLAG_EXPIRY_INVALID`. A cause only has to describe, so a value that
+ * defeats rendering degrades to its type rather than destroying the refusal.
+ */
+const renderGiven = (given: unknown): string => {
+  if (given === undefined) return 'undefined';
+  if (typeof given === 'bigint') return `${given}n`;
+  if (typeof given === 'symbol') return String(given);
+  try {
+    return JSON.stringify(given) ?? String(given);
+  } catch {
+    return `a ${typeof given} that cannot be rendered`;
+  }
+};
+
+export const flagExpiryInvalid = (key: string, given: unknown): FlagsError =>
+  new FlagsError({
+    code: 'X_FLAG_EXPIRY_INVALID',
+    cause: `${key} is a temporary flag whose expiresAt is ${renderGiven(given)}, which is not a date`,
+    fix: `set expiresAt to an ISO-8601 date such as '2026-12-01' in defineFlag({ key: '${key}' })`,
+    meta: { key },
+  });
+
+/** Built, handed to the reporter, and never thrown. See this file's header for why. */
+export const flagExpired = (init: {
+  key: string;
+  owner: string;
+  expiresAt: string;
+  overdueDays: number;
+}): FlagsError =>
+  new FlagsError({
+    code: 'X_FLAG_EXPIRED',
+    cause: `${init.key} expired ${init.overdueDays} day(s) ago (${init.expiresAt}, owner ${init.owner}) and is still being evaluated`,
+    fix: `delete the ${init.key} branch and its defineFlag() declaration, or move it to kind: 'permanent' if it is a real product switch`,
+    meta: { key: init.key, owner: init.owner, expiresAt: init.expiresAt },
+  });

package/src/evaluate.ts

@@ -0,0 +1,55 @@
+// Single responsibility: `isEnabled()` — the one way to ask a flag a question. Synchronous, for
+// the same reason `can()` is: this runs inside policy predicates and render passes, and an `await`
+// there turns every guarded branch into an async boundary.
+
+import type { Actor } from '@ultimat3/core';
+import { flagExpired } from './errors';
+import type { Flag } from './flag';
+import { flagFor } from './registry';
+import { flagsClock, reportOnce } from './runtime';
+import type { FlagSubjects } from './subject';
+import { evaluateTargeting } from './targeting';
+
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+/**
+ * The lifecycle rule, enforced on the one path nobody can avoid. An overdue temporary flag reports
+ * itself where it is USED, not where it is declared — a declaration is read once at boot and can
+ * sit in a module nothing evaluates, while an evaluation proves the branch is still live.
+ *
+ * It reports and returns; it never throws. An expiry is a debt, not an outage, and a framework
+ * that took production down on a date nobody remembered setting would teach everyone to declare
+ * every flag `permanent`, which is the failure this design exists to prevent.
+ */
+function reportIfOverdue(flag: Flag): void {
+  if (flag.expiresAtMs === null || flag.owner === null || flag.expiresAt === null) return;
+  const nowMs = flagsClock().now().getTime();
+  if (nowMs < flag.expiresAtMs) return;
+  const expiresAt = flag.expiresAt;
+  const owner = flag.owner;
+  const overdueDays = Math.floor((nowMs - flag.expiresAtMs) / MS_PER_DAY);
+  reportOnce(flag.key, () => flagExpired({ key: flag.key, owner, expiresAt, overdueDays }));
+}
+
+/**
+ * Is `key` on for `actor`? An undeclared key throws `X_FLAG_UNKNOWN` rather than answering `false`
+ * — see `flagFor`.
+ *
+ * `actor` is passed rather than read from the ambient context on purpose: a policy predicate,
+ * a job and a render pass each already hold the actor they are deciding about, and reading an
+ * ambient one would let a job evaluate a flag for whoever enqueued it.
+ *
+ * `subjects` carries the app's own records in play — `{ bank: 'bank_integration:bbva' }` — for a
+ * flag targeted at something other than the caller. Same reasoning as `actor`: the call site
+ * already holds the record it is deciding about. A flag that needs a kind the call site did not
+ * pass raises `X_FLAG_SUBJECT_REQUIRED` rather than quietly deciding about somebody else.
+ */
+export function isEnabled(
+  key: string,
+  actor: Actor | null,
+  subjects?: FlagSubjects | undefined,
+): boolean {
+  const flag = flagFor(key);
+  reportIfOverdue(flag);
+  return evaluateTargeting(flag.key, flag.targeting, actor, subjects);
+}

package/src/flag.ts

@@ -0,0 +1,109 @@
+// Single responsibility: what a flag IS — the two kinds, and the normalisation from a declaration
+// to the frozen record everything else reads.
+//
+// The two kinds are the whole answer to "N flags = 2^N untested states". A `permanent` flag is a
+// product or ops switch that legitimately outlives the change that introduced it. A `temporary`
+// flag is scaffolding, so it carries an expiry and an owner, and past that date every evaluation
+// reports it (see `evaluate.ts`). The state space stays bounded because the temporary half is
+// forced to shrink.
+
+import { flagExpiryInvalid } from './errors';
+import type { FlagTargeting } from './targeting';
+import { assertTargeting } from './targeting';
+
+export const FLAG_KINDS = ['permanent', 'temporary'] as const;
+
+export type FlagKind = (typeof FLAG_KINDS)[number];
+
+export interface PermanentFlagDef {
+  readonly kind: 'permanent';
+  readonly key: string;
+  /** What the switch means. The projection prints it; it is all a reader has to go on. */
+  readonly description: string;
+  readonly targeting: FlagTargeting;
+}
+
+export interface TemporaryFlagDef {
+  readonly kind: 'temporary';
+  readonly key: string;
+  readonly description: string;
+  readonly targeting: FlagTargeting;
+  /** ISO-8601 date the scaffolding is due to come down. Required — see `FlagExpiryIsMandatory`. */
+  readonly expiresAt: string;
+  /** Who takes it down. A temporary flag with no owner is one nobody removes. */
+  readonly owner: string;
+}
+
+export type FlagDef = PermanentFlagDef | TemporaryFlagDef;
+
+type Assert<T extends true> = T;
+
+/**
+ * Compile-time proof that `kind: 'temporary'` cannot be declared without an expiry: a temporary
+ * shape missing `expiresAt` must NOT be assignable to `FlagDef`. Loosen the union and the
+ * conditional yields `false`, `Assert<false>` fails its constraint, and `tsc -b packages/flags`
+ * goes red here. Axiom 3 — the rule is a build error, not a comment in a style guide.
+ */
+export type FlagExpiryIsMandatory = Assert<
+  {
+    readonly kind: 'temporary';
+    readonly key: string;
+    readonly description: string;
+    readonly targeting: FlagTargeting;
+    readonly owner: string;
+  } extends FlagDef
+    ? false
+    : true
+>;
+
+/** The normalised record. Both kinds share one shape so nothing downstream branches on kind. */
+export interface Flag {
+  readonly key: string;
+  readonly kind: FlagKind;
+  readonly description: string;
+  readonly targeting: FlagTargeting;
+  /** ISO-8601 as declared, `null` for a permanent flag. */
+  readonly expiresAt: string | null;
+  /** Epoch ms of `expiresAt`, precomputed so evaluation never parses a date. */
+  readonly expiresAtMs: number | null;
+  readonly owner: string | null;
+}
+
+/**
+ * Declaration → `Flag`, with both invariants enforced here rather than at the first evaluation.
+ * The expiry is re-checked at runtime even though the type already demands it: a snapshot pushed
+ * from a store, or a plain-JS caller, has no types to be checked by.
+ */
+export function toFlag(def: FlagDef): Flag {
+  assertTargeting(def.key, def.targeting);
+  if (def.kind === 'permanent') {
+    return Object.freeze({
+      key: def.key,
+      kind: def.kind,
+      description: def.description,
+      targeting: def.targeting,
+      expiresAt: null,
+      expiresAtMs: null,
+      owner: null,
+    });
+  }
+  // A bare ISO date parses as UTC midnight, so the deadline is the same instant on every node —
+  // no ambient zone, which is the framework's rule about dates applied to a deadline.
+  const expiresAtMs = Date.parse(def.expiresAt);
+  if (Number.isNaN(expiresAtMs)) throw flagExpiryInvalid(def.key, def.expiresAt);
+  return Object.freeze({
+    key: def.key,
+    kind: def.kind,
+    description: def.description,
+    targeting: def.targeting,
+    expiresAt: def.expiresAt,
+    expiresAtMs,
+    owner: def.owner,
+  });
+}
+
+/** Re-target a declared flag without re-declaring it — how `applyFlagSnapshot` lands an override. */
+export function withTargeting(flag: Flag, targeting: FlagTargeting): Flag {
+  assertTargeting(flag.key, targeting);
+  return Object.freeze({ ...flag, targeting });
+}

package/src/index.ts

@@ -0,0 +1,36 @@
+// Public API of @ultimat3/flags. Explicit re-exports only.
+
+export { BUCKETS, bucketOf, fnv1a } from './bucket';
+export type { FlagSubjectVia, FlagsErrorCode } from './errors';
+export {
+  FLAGS_ERROR_CODES,
+  FLAGS_ERROR_TITLES,
+  FlagsError,
+  flagDuplicate,
+  flagExpired,
+  flagExpiryInvalid,
+  flagSubjectRequired,
+  flagTargetingInvalid,
+  flagUnknown,
+} from './errors';
+export { isEnabled } from './evaluate';
+export type {
+  Flag,
+  FlagDef,
+  FlagExpiryIsMandatory,
+  FlagKind,
+  PermanentFlagDef,
+  TemporaryFlagDef,
+} from './flag';
+export { FLAG_KINDS } from './flag';
+export type { FlagFacts, FlagsReport } from './projection';
+export { flagsReport } from './projection';
+export type { SnapshotResult } from './registry';
+export { allFlags, applyFlagSnapshot, defineFlag, hasFlag, resetFlags } from './registry';
+export type { FlagsRuntimeOptions } from './runtime';
+// The reporter seam is `@ultimat3/core`'s `ErrorReporter`, wired once with
+// `configureErrorReporting()`. This package deliberately re-exports none of it.
+export { configureFlags, DEFAULT_REPORT_INTERVAL_MS, resetFlagReporting } from './runtime';
+export type { BuiltInSubjectKind, FlagSubjects } from './subject';
+export { BUILT_IN_SUBJECT_KINDS } from './subject';
+export type { FlagTargeting } from './targeting';

package/src/projection.ts

@@ -0,0 +1,43 @@
+// Single responsibility: the declared flags as data — one JSON-safe shape for `x flags --json`,
+// the MCP tool and the manifest, so all three answer "what is expired?" identically instead of
+// each computing it. Same rule as `listErrorCodes()`: the projection lives with the registry.
+
+import type { FlagKind } from './flag';
+import { allFlags } from './registry';
+import { flagsClock } from './runtime';
+import type { FlagTargeting } from './targeting';
+
+export interface FlagFacts {
+  readonly key: string;
+  readonly kind: FlagKind;
+  readonly description: string;
+  readonly targeting: FlagTargeting;
+  /** ISO-8601, `null` for a permanent flag. */
+  readonly expiresAt: string | null;
+  readonly owner: string | null;
+  /** Past its expiry as of this call. Always `false` for a permanent flag — it has no expiry. */
+  readonly expired: boolean;
+}
+
+export interface FlagsReport {
+  readonly flags: readonly FlagFacts[];
+  /** The expired keys, lifted out: the one number a gate or a dashboard wants is this length. */
+  readonly expired: readonly string[];
+}
+
+/** Sorted by key, so a diff of two reports is a diff of what changed. */
+export function flagsReport(): FlagsReport {
+  const nowMs = flagsClock().now().getTime();
+  const flags = allFlags().map(
+    (flag): FlagFacts => ({
+      key: flag.key,
+      kind: flag.kind,
+      description: flag.description,
+      targeting: flag.targeting,
+      expiresAt: flag.expiresAt,
+      owner: flag.owner,
+      expired: flag.expiresAtMs !== null && nowMs >= flag.expiresAtMs,
+    }),
+  );
+  return { flags, expired: flags.filter((flag) => flag.expired).map((flag) => flag.key) };
+}

package/src/registry.ts

@@ -0,0 +1,78 @@
+// Single responsibility: the declared set of flags for this process — the one place a key resolves
+// to a `Flag`. Process-global and filled at import time, exactly like the error-code registry, so
+// evaluation is a map lookup rather than a load.
+
+import { flagDuplicate, flagUnknown } from './errors';
+import type { Flag, FlagDef } from './flag';
+import { toFlag, withTargeting } from './flag';
+import type { FlagTargeting } from './targeting';
+
+const flags = new Map<string, Flag>();
+
+/**
+ * The one call an app makes to declare a flag. A `define*` helper, deliberately NOT a ninth
+ * primitive: a flag is a declaration plus a pure predicate, it has no handler, no schema and no
+ * surface of its own — the same shape as `defineRoles` and `defineCatalogs`.
+ */
+export function defineFlag(def: FlagDef): Flag {
+  const flag = toFlag(def);
+  if (flags.has(flag.key)) throw flagDuplicate(flag.key);
+  flags.set(flag.key, flag);
+  return flag;
+}
+
+/**
+ * Throws rather than answering `false` for an unknown key. A typo that reads as "off" is the
+ * failure mode a flag system exists to have: the branch silently never runs, in production, and
+ * nothing anywhere says so.
+ */
+export function flagFor(key: string): Flag {
+  const flag = flags.get(key);
+  if (flag === undefined) throw flagUnknown(key, [...flags.keys()]);
+  return flag;
+}
+
+export const hasFlag = (key: string): boolean => flags.has(key);
+
+/** Sorted by key — the projection and the manifest both need a stable order. */
+export const allFlags = (): readonly Flag[] =>
+  [...flags.values()].sort((a, b) => a.key.localeCompare(b.key));
+
+export interface SnapshotResult {
+  /** Keys whose targeting was replaced. */
+  readonly applied: readonly string[];
+  /** Keys the store carried that this build does not declare. */
+  readonly unknown: readonly string[];
+}
+
+/**
+ * Land a store's targeting on the declared flags. This is the out-of-band half that keeps
+ * `isEnabled()` synchronous: a poller, a job or a realtime channel calls this, and evaluation
+ * never awaits anything.
+ *
+ * Unknown keys are reported, not thrown: a control plane is routinely ahead of a deploy, and a
+ * kill switch that refuses to land because the payload also mentioned tomorrow's flag is a kill
+ * switch that does not work on the day it is needed. A bad *targeting* still throws — landing a
+ * `rollout: 0.5` would silently switch a feature off for everyone.
+ */
+export function applyFlagSnapshot(
+  snapshot: Readonly<Record<string, FlagTargeting>>,
+): SnapshotResult {
+  const applied: string[] = [];
+  const unknown: string[] = [];
+  for (const [key, targeting] of Object.entries(snapshot)) {
+    const flag = flags.get(key);
+    if (flag === undefined) {
+      unknown.push(key);
+      continue;
+    }
+    flags.set(key, withTargeting(flag, targeting));
+    applied.push(key);
+  }
+  return { applied, unknown };
+}
+
+/** Test-only. Production declares once at import and never withdraws. */
+export function resetFlags(): void {
+  flags.clear();
+}

package/src/runtime.ts

@@ -0,0 +1,65 @@
+// Single responsibility: the two ambient things an evaluation needs that the declaration cannot
+// carry — what "now" is, and how often the same overdue flag may report.
+//
+// The reporter itself is NOT here. `@ultimat3/core`'s `ErrorReporter` is the framework's one
+// error-monitoring seam; a second one in this package would be a second place an app has to wire
+// its monitor, and two places to look when a report does not arrive. What this package adds is the
+// rate limit, which core deliberately has no opinion about: `reportError` is called once per
+// caught failure, while a flag is evaluated on every request.
+
+import type { Clock, UltimateError } from '@ultimat3/core';
+import { reportError, systemClock } from '@ultimat3/core';
+
+/**
+ * One hour. Small enough that an overdue flag shows up the same day, large enough that a flag read
+ * on every request does not become the loudest thing in the monitor — which is how a report that
+ * fires per call ends up muted, and the debt invisible again.
+ */
+export const DEFAULT_REPORT_INTERVAL_MS = 60 * 60 * 1000;
+
+export interface FlagsRuntimeOptions {
+  readonly clock?: Clock | undefined;
+  /** Minimum gap between two reports of the SAME flag key. */
+  readonly reportEveryMs?: number | undefined;
+}
+
+let clock: Clock = systemClock;
+let reportEveryMs = DEFAULT_REPORT_INTERVAL_MS;
+const lastReportedAt = new Map<string, number>();
+
+export function configureFlags(options: FlagsRuntimeOptions): void {
+  if (options.clock !== undefined) clock = options.clock;
+  if (options.reportEveryMs !== undefined) reportEveryMs = options.reportEveryMs;
+}
+
+export const flagsClock = (): Clock => clock;
+
+/**
+ * Report `build()`'s error through core's seam at most once per `reportEveryMs` for this key, and
+ * say whether it did. The rate limit is keyed on the MONOTONIC clock: a wall-clock jump — an NTP
+ * correction, a container resuming — must not reopen the window and flood the monitor.
+ *
+ * The error is built lazily, so a rate-limited call costs a map lookup and a subtraction. That
+ * matters: this sits on the same path as `can()`.
+ *
+ * `severity: 'warning'` because the framework recovered — the flag still answered. `source:
+ * 'process'` because an overdue flag is a fact about this deploy, not about whichever request
+ * happened to evaluate it first.
+ */
+export function reportOnce(key: string, build: () => UltimateError): boolean {
+  const now = clock.monotonic();
+  const previous = lastReportedAt.get(key);
+  if (previous !== undefined && now - previous < reportEveryMs) return false;
+  lastReportedAt.set(key, now);
+  // `reportError` never throws and logs a failing transport itself, so an evaluation cannot fail
+  // because the monitor is down.
+  reportError(build(), { source: 'process', severity: 'warning', scope: { operation: key } });
+  return true;
+}
+
+/** Test-only, and the counterpart to every other reset in the framework. */
+export function resetFlagReporting(): void {
+  clock = systemClock;
+  reportEveryMs = DEFAULT_REPORT_INTERVAL_MS;
+  lastReportedAt.clear();
+}

package/src/subject.ts

@@ -0,0 +1,78 @@
+// Single responsibility: what a flag decides ABOUT, and how a subject kind resolves to the one id
+// that gets matched or hashed. A subject is any identified record — a tenant, a bank integration,
+// a device — which is the generalisation of the actor axis, not a second mechanism beside it.
+
+import type { Actor } from '@ultimat3/core';
+import type { FlagSubjectVia } from './errors';
+import { flagSubjectRequired } from './errors';
+
+/**
+ * The records in play at ONE evaluation, keyed by kind: `{ bank: 'bank_integration:bbva' }`.
+ *
+ * A map rather than a list of `{ kind, id }` because a single evaluation has a single bank, a
+ * single project, a single device: the shape makes a duplicate kind unrepresentable instead of a
+ * rule nothing enforces. The id is the app's — an opaque string, never parsed here.
+ */
+export type FlagSubjects = Readonly<Record<string, string>>;
+
+/**
+ * The two kinds every app has, and the two an `Actor` already carries. Everything else is the
+ * app's own vocabulary and arrives in `FlagSubjects`.
+ *
+ * A built-in kind is resolved from the actor and NEVER from the map. That is what keeps this a
+ * single mechanism rather than two: one source per kind, so there is no precedence rule to
+ * remember and no second place a tenant can come from. Passing `org` at a call site is dead data,
+ * and it cannot produce a wrong answer — without `actor.orgId` the evaluation raises, and the fix
+ * line says to mint the actor with its org.
+ */
+export const BUILT_IN_SUBJECT_KINDS = ['actor', 'org'] as const;
+
+export type BuiltInSubjectKind = (typeof BUILT_IN_SUBJECT_KINDS)[number];
+
+export const isBuiltInSubjectKind = (kind: string): kind is BuiltInSubjectKind =>
+  (BUILT_IN_SUBJECT_KINDS as readonly string[]).includes(kind);
+
+/**
+ * The id for `kind`, or a loud failure — never a fallback to the actor and never the declared
+ * default. An answer about a record computed from whoever happened to be calling is the bug this
+ * axis removes: it looks like it worked. An empty string is absent, not an id; it would otherwise
+ * match an allow list entry or hash to a real bucket.
+ *
+ * The kind space is open, exactly like the flag key space. A typo'd kind raises here on the first
+ * evaluation, which is the same loud failure an undeclared key already gets from `X_FLAG_UNKNOWN`
+ * — a registry of kinds would be a second declaration surface buying a check this already makes.
+ */
+export function subjectIdOf(init: {
+  readonly key: string;
+  readonly kind: string;
+  readonly actor: Actor;
+  readonly subjects: FlagSubjects | undefined;
+  readonly via: FlagSubjectVia;
+}): string {
+  const { key, kind, actor, subjects, via } = init;
+  const id = resolve(kind, actor, subjects);
+  if (id === undefined || id === '') {
+    throw flagSubjectRequired({ key, kind, actorId: actor.id, via });
+  }
+  return id;
+}
+
+/**
+ * Own properties only. `subjects['toString']` would otherwise walk the prototype chain and hand
+ * back a function where an id belongs — a weird downstream failure instead of the clean
+ * `X_FLAG_SUBJECT_REQUIRED` this package designed for exactly that case.
+ *
+ * The `typeof` re-check is for JS callers and store-shaped data: an id is a string or it is
+ * nothing, and a number reaching `bucketOf` would hash to a real bucket rather than raise.
+ */
+function resolve(
+  kind: string,
+  actor: Actor,
+  subjects: FlagSubjects | undefined,
+): string | undefined {
+  if (kind === 'actor') return actor.id;
+  if (kind === 'org') return actor.orgId;
+  if (subjects === undefined || !Object.hasOwn(subjects, kind)) return undefined;
+  const id = subjects[kind];
+  return typeof id === 'string' ? id : undefined;
+}

package/src/targeting.ts

@@ -0,0 +1,163 @@
+// Single responsibility: who a flag is on for. Pure and synchronous — this is the code that runs
+// inside a policy predicate and a render pass, so it never awaits, never reads a store and never
+// touches a clock. Loading the store is somebody else's job (`applyFlagSnapshot`).
+import type { Actor } from '@ultimat3/core';
+import { hasRole } from '@ultimat3/core';
+import { BUCKETS, bucketOf } from './bucket';
+import { flagTargetingInvalid } from './errors';
+import type { FlagSubjects } from './subject';
+import { BUILT_IN_SUBJECT_KINDS, isBuiltInSubjectKind, subjectIdOf } from './subject';
+
+export interface FlagTargeting {
+  /** The answer when no allow list and no rollout claims this actor. `false` is off, `true` is on. */
+  readonly default: boolean;
+  /** Actor ids that are always on, ahead of any rollout — shorthand for the `actor` subject kind. */
+  readonly actors?: readonly string[] | undefined;
+  /** Actor roles that are always on. NOT a subject: a role is a predicate, not an identified record. */
+  readonly roles?: readonly string[] | undefined;
+  /** Org ids that are always on — shorthand for the `org` subject kind, read from `actor.orgId`. */
+  readonly orgs?: readonly string[] | undefined;
+  /**
+   * Allow lists for the app's own record kinds: `{ bank: ['bank_integration:bbva'] }`. One rank
+   * with `actors`, `roles` and `orgs` — any hit is `true`, which is the same OR Flipper applies
+   * across the actors handed to one `enabled?` call.
+   *
+   * Built-in kinds are refused here: `actors` and `orgs` are their one spelling.
+   */
+  readonly subjects?: Readonly<Record<string, readonly string[]>> | undefined;
+  /** Percentage of the bucketing subject, 0-100 inclusive. Stable: one subject, one answer. */
+  readonly rollout?: number | undefined;
+  /**
+   * Which subject kind the `rollout` divides — `'actor'` (the default), `'org'`, or any kind the
+   * call site carries. The kind space is open on purpose, like the flag key space.
+   *
+   * Bucketing by a record is what keeps it whole: an org whose members share documents, or a bank
+   * integration whose connections share a scraper, must be entirely on the new path or entirely
+   * on the old one. `'actor'` stays the default, so every flag declared before this axis existed
+   * answers exactly as it did.
+   */
+  readonly bucketBy?: string | undefined;
+}
+
+/**
+ * Declaration-time validation, the way `can()` validates its permission rather than waiting for a
+ * request. Each rule closes a way for a flag to look wired and decide nothing:
+ *
+ * | Rejected | Why |
+ * |---|---|
+ * | `rollout: 0.5` | read as a fraction it means "half", read as a percentage it means "nobody" |
+ * | `default: true` with a `rollout` | the two answer the same actors and disagree; there is no reading of "on for everyone, and also on for 10%" |
+ * | `bucketBy` with no `rollout` | it names what a rollout divides, and there is no rollout to divide |
+ * | a blank `bucketBy` | names no kind at all |
+ * | `subjects.actor` / `subjects.org` | `actors` and `orgs` are the one spelling; two would disagree |
+ * | a `subjects` entry that is not a list of non-empty ids | reachable from a store snapshot, and it matches nothing while reading as an allow list |
+ *
+ * The `subjects` checks narrow by hand rather than through a schema: this package's other runtime
+ * re-checks (`Number.isInteger`, `Date.parse`) do the same, and a dependency here would buy one
+ * validation on a path that must stay allocation-free.
+ */
+export function assertTargeting(key: string, targeting: FlagTargeting): void {
+  const { bucketBy, rollout } = targeting;
+  if (targeting.subjects !== undefined) assertSubjects(key, targeting.subjects);
+  if (bucketBy !== undefined) {
+    if (typeof bucketBy !== 'string' || bucketBy.trim() === '') {
+      throw flagTargetingInvalid(
+        key,
+        `bucketBy is ${JSON.stringify(bucketBy)}, which names no subject kind`,
+        `set bucketBy to a subject kind — '${BUILT_IN_SUBJECT_KINDS.join("', '")}', or one your call site passes — in defineFlag({ key: '${key}' })`,
+      );
+    }
+    if (rollout === undefined) {
+      throw flagTargetingInvalid(
+        key,
+        `bucketBy is '${bucketBy}' with no rollout, so it divides nothing`,
+        `add a rollout to defineFlag({ key: '${key}' }), or remove bucketBy`,
+      );
+    }
+  }
+  if (rollout === undefined) return;
+  if (!Number.isInteger(rollout)) {
+    const problem = `rollout is ${rollout}; a rollout is a whole percentage, not a fraction`;
+    throw flagTargetingInvalid(key, problem);
+  }
+  if (rollout < 0 || rollout > BUCKETS) {
+    throw flagTargetingInvalid(key, `rollout is ${rollout}, outside 0-${BUCKETS}`);
+  }
+  if (targeting.default) {
+    throw flagTargetingInvalid(key, `default is true and rollout is ${rollout}; the two disagree`);
+  }
+}
+
+function assertSubjects(key: string, subjects: Readonly<Record<string, readonly string[]>>): void {
+  const fix = `give each subjects entry a kind and a list of ids — { bank: ['bank_integration:bbva'] } — in defineFlag({ key: '${key}' })`;
+  for (const [kind, ids] of Object.entries<unknown>(subjects)) {
+    if (kind.trim() === '') throw flagTargetingInvalid(key, 'a subjects kind is blank', fix);
+    if (isBuiltInSubjectKind(kind)) {
+      throw flagTargetingInvalid(
+        key,
+        `subjects.${kind} restates a built-in kind`,
+        `use ${kind === 'org' ? 'orgs' : 'actors'} instead of subjects.${kind} in defineFlag({ key: '${key}' })`,
+      );
+    }
+    if (!Array.isArray(ids)) {
+      throw flagTargetingInvalid(key, `subjects.${kind} is not a list of ids`, fix);
+    }
+    for (const id of ids as readonly unknown[]) {
+      if (typeof id !== 'string' || id === '') {
+        throw flagTargetingInvalid(key, `subjects.${kind} holds an id that is not a string`, fix);
+      }
+    }
+  }
+}
+
+/**
+ * Allow lists first, rollout second, declared default last. That order is the contract: a subject
+ * an operator explicitly named must not depend on where a hash happened to put it, which is the
+ * whole reason an allow list exists. `actors`, `roles`, `orgs` and `subjects` are ONE rank — any
+ * hit is `true`, so their order among themselves is not observable, which is the same OR Flipper
+ * applies across the actors passed to a single `enabled?` call.
+ *
+ * A `null` actor gets the default and nothing else. There is no id to hash, so a rollout could
+ * only be answered by re-rolling per call — the one thing this file refuses to do. An anonymous
+ * `Actor` DOES have an id (`anonymous`), so every anonymous visitor shares one bucket: one
+ * identity, one answer, which is what the anonymous actor already means everywhere else. `null`
+ * does NOT raise `X_FLAG_SUBJECT_REQUIRED`: it says there is no evaluation context at all, and
+ * every such call gets the same answer, so no single subject is split — which is the failure being
+ * designed out. A context that exists but lacks the kind is the ambiguous case, and that throws.
+ *
+ * Every kind the targeting declares resolves before any branch answers, so whether a call raises
+ * `X_FLAG_SUBJECT_REQUIRED` depends only on the flag and the context — never on which allow list
+ * happened to match first, nor on the order the keys sit in.
+ */
+export function evaluateTargeting(
+  key: string,
+  targeting: FlagTargeting,
+  actor: Actor | null,
+  subjects?: FlagSubjects | undefined,
+): boolean {
+  if (actor === null) return targeting.default;
+  // Nothing answers until every declared kind has resolved. Returning early on an allow-list hit
+  // would hide a missing record from exactly the callers who are on the list: the call site ships
+  // green, and raises later only for everybody else. `allowed` accumulates instead of returning.
+  let allowed = targeting.actors?.includes(actor.id) === true;
+  if (targeting.roles?.some((role) => hasRole(actor, role)) === true) allowed = true;
+  if (targeting.orgs !== undefined) {
+    const orgId = subjectIdOf({ key, kind: 'org', actor, subjects, via: 'orgs' });
+    if (targeting.orgs.includes(orgId)) allowed = true;
+  }
+  if (targeting.subjects !== undefined) {
+    // `for…in` + `Object.hasOwn` rather than `Object.entries`: own keys only, and no array pair
+    // allocated per declared kind on a path that runs inside policy predicates.
+    for (const kind in targeting.subjects) {
+      if (!Object.hasOwn(targeting.subjects, kind)) continue;
+      const id = subjectIdOf({ key, kind, actor, subjects, via: 'subjects' });
+      if (targeting.subjects[kind]?.includes(id) === true) allowed = true;
+    }
+  }
+  if (targeting.rollout === undefined) return allowed || targeting.default;
+  const subjectId =
+    targeting.bucketBy === undefined
+      ? actor.id
+      : subjectIdOf({ key, kind: targeting.bucketBy, actor, subjects, via: 'bucketBy' });
+  return allowed || bucketOf(key, subjectId) < targeting.rollout;
+}