@cosmicdrift/kumiko-framework 0.304.0 → 0.305.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.304.0",
+  "version": "0.305.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -198,8 +198,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.304.0",
-    "@cosmicdrift/kumiko-types": "0.304.0",
+    "@cosmicdrift/kumiko-http": "0.305.0",
+    "@cosmicdrift/kumiko-types": "0.305.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -215,7 +215,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.304.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.305.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/api/__tests__/extra-route-rejection.test.ts

@@ -0,0 +1,38 @@
+// Constructor invariants for ExtraRouteRejection's `retryAfterSeconds` option
+// (kumiko-framework#3168): it only makes sense together with 503 and must
+// render as a valid Retry-After delta-seconds header.
+
+import { describe, expect, test } from "bun:test";
+import { ExtraRouteRejection } from "../extra-route";
+
+describe("ExtraRouteRejection retryAfterSeconds invariants", () => {
+  test("retryAfterSeconds with a non-503 status throws RangeError", () => {
+    expect(
+      () => new ExtraRouteRejection(404, { error: "x" }, undefined, { retryAfterSeconds: 30 }),
+    ).toThrow(RangeError);
+  });
+
+  test("negative retryAfterSeconds throws RangeError", () => {
+    expect(
+      () => new ExtraRouteRejection(503, { error: "x" }, undefined, { retryAfterSeconds: -1 }),
+    ).toThrow(RangeError);
+  });
+
+  test("non-integer retryAfterSeconds throws RangeError", () => {
+    expect(
+      () => new ExtraRouteRejection(503, { error: "x" }, undefined, { retryAfterSeconds: 1.5 }),
+    ).toThrow(RangeError);
+  });
+
+  test("retryAfterSeconds: 0 with status 503 is accepted", () => {
+    const rejection = new ExtraRouteRejection(503, { error: "x" }, undefined, {
+      retryAfterSeconds: 0,
+    });
+    expect(rejection.retryAfterSeconds).toBe(0);
+  });
+
+  test("no options leaves retryAfterSeconds undefined", () => {
+    const rejection = new ExtraRouteRejection(503, { error: "x" });
+    expect(rejection.retryAfterSeconds).toBeUndefined();
+  });
+});

package/src/api/__tests__/extra-routes.integration.test.ts

@@ -461,6 +461,14 @@ describe("extraRoutes: entry:signature", () => {
       if (req.headers["x-force-404"] === "1") {
         throw new ExtraRouteRejection(404, { error: "unknown-provider" });
       }
+      if (req.headers["x-force-503"] === "retry") {
+        throw new ExtraRouteRejection(503, { error: "not-ready" }, undefined, {
+          retryAfterSeconds: 30,
+        });
+      }
+      if (req.headers["x-force-503"] === "plain") {
+        throw new ExtraRouteRejection(503, { error: "not-ready" });
+      }
       if (req.headers["x-hmac"] !== signHmac(req.rawBody)) {
         throw new Error("signature mismatch");
       }
@@ -536,6 +544,28 @@ describe("extraRoutes: entry:signature", () => {
     expect(await res.json()).toEqual({ error: "unknown-provider" });
   });
 
+  test("verify() throwing ExtraRouteRejection(503, body, options) surfaces the body and Retry-After header", async () => {
+    const res = await stack.app.request("/webhooks/probe", {
+      method: "POST",
+      headers: { "x-force-503": "retry", "content-type": "application/json" },
+      body: JSON.stringify({ note: "x" }),
+    });
+    expect(res.status).toBe(503);
+    expect(await res.json()).toEqual({ error: "not-ready" });
+    expect(res.headers.get("retry-after")).toBe("30");
+  });
+
+  test("verify() throwing ExtraRouteRejection(503, body) without options omits the Retry-After header", async () => {
+    const res = await stack.app.request("/webhooks/probe", {
+      method: "POST",
+      headers: { "x-force-503": "plain", "content-type": "application/json" },
+      body: JSON.stringify({ note: "x" }),
+    });
+    expect(res.status).toBe(503);
+    expect(await res.json()).toEqual({ error: "not-ready" });
+    expect(res.headers.get("retry-after")).toBeNull();
+  });
+
   test("mounted under /api/:provider — no session needed, honoPathToRegex matches the :param, rawBody arrives intact through /api/*", async () => {
     const rawBody = JSON.stringify({ event: "payment.succeeded" });
     const res = await stack.app.request("/api/webhooks/stripe", {

package/src/api/__tests__/server-error-logging.test.ts

@@ -27,6 +27,14 @@ const boomFeature = defineFeature("boom", (r) => {
     },
     openToAll,
   );
+  r.writeHandler(
+    "explode",
+    z.object({}),
+    async () => {
+      throw new Error("disk on fire during write");
+    },
+    openToAll,
+  );
   r.queryHandler(
     "decode",
     z.object({}),
@@ -140,6 +148,31 @@ describe("HTTP layer logs unexpected 5xx faults", () => {
     }
   });
 
+  test("a throwing write 500s AND its cause reaches the log (reraise keeps the cause)", async () => {
+    const calls: unknown[][] = [];
+    const spy = spyOn(console, "error").mockImplementation((...args) => {
+      calls.push(args);
+    });
+    try {
+      const res = await app.request("/api/write", {
+        method: "POST",
+        headers: await auth(),
+        body: JSON.stringify({ type: "boom:write:explode", payload: {} }),
+      });
+      expect(res.status).toBe(500);
+      const hit = calls.find(
+        (args) => typeof args[0] === "string" && args[0].includes("[api] handler failed"),
+      );
+      const data = hit?.[1];
+      expect(isRecord(data)).toBe(true);
+      if (!isRecord(data)) return;
+      expect(data["type"]).toBe("boom:write:explode");
+      expect(data["cause"]).toBe("disk on fire during write");
+    } finally {
+      spy.mockRestore();
+    }
+  });
+
   test("a 404 stays off the error level (it is a client outcome, not a server fault)", async () => {
     const { status, errors } = await queryWithCapturedWarnings("nope:query:nothing", {});
     expect(status).toBe(404);

package/src/api/api-constants.ts

@@ -101,6 +101,19 @@ export const BODY_LIMIT_OPT_OUT_PATHS: ReadonlySet<string> = new Set([
   `/api${Routes.files}`,
 ]);
 
+// authEndpointRateLimit (L2) exceptions, exact method+path match, no prefix/glob.
+// A forgotten entry here is safe (over-limited, not unlimited).
+export const AUTH_RATE_LIMIT_EXEMPT_ROUTES: ReadonlyArray<{
+  readonly method: string;
+  readonly path: string;
+}> = [{ method: "GET", path: `/api${Routes.authTenants}` }];
+
+export function isAuthRateLimitExempt(method: string, path: string): boolean {
+  return AUTH_RATE_LIMIT_EXEMPT_ROUTES.some(
+    (route) => route.method === method && route.path === path,
+  );
+}
+
 // Methods that can mutate server state. GET/HEAD/OPTIONS are safe under
 // CORS + SameSite-cookie semantics and skip the CSRF / Origin guards entirely.
 export const STATE_CHANGING_METHODS: ReadonlySet<string> = new Set([

package/src/api/extra-route.ts

@@ -128,19 +128,48 @@ export function signatureRoute<T>(def: SignatureExtraRoute<T>): ExtraRouteDefini
   return def as unknown as SignatureExtraRoute<unknown>;
 }
 
-export type ExtraRouteRejectionStatus = 400 | 401 | 403 | 404 | 500;
+export type ExtraRouteRejectionStatus = 400 | 401 | 403 | 404 | 500 | 503;
+
+export type ExtraRouteRejectionOptions = { readonly retryAfterSeconds?: number };
 
 /** Thrown by `verify()` to reject a signature route with a specific status +
  *  JSON body. Any other throw from `verify()` is mapped to 401
- *  `extra_route_signature_invalid` by the buildServer wrapper. */
+ *  `extra_route_signature_invalid` by the buildServer wrapper.
+ *
+ *  503 signals "temporarily not ready" (e.g. a dependency the verify step
+ *  needs is down) — webhook providers like Stripe retry on 503.
+ *  `options.retryAfterSeconds` renders as the `Retry-After` header. */
 export class ExtraRouteRejection extends Error {
   readonly status: ExtraRouteRejectionStatus;
   readonly body: unknown;
-
-  constructor(status: ExtraRouteRejectionStatus, body: unknown, message?: string) {
+  readonly retryAfterSeconds: number | undefined;
+
+  constructor(
+    status: ExtraRouteRejectionStatus,
+    body: unknown,
+    message?: string,
+    options?: ExtraRouteRejectionOptions,
+  ) {
     super(message ?? `extra route rejected with status ${status}`);
     this.name = "ExtraRouteRejection";
     this.status = status;
     this.body = body;
+    const retryAfterSeconds = options?.retryAfterSeconds;
+    if (retryAfterSeconds !== undefined) {
+      // Retry-After is only meaningful for 503 in this union (RFC 9110) and
+      // is rendered as a delta-seconds header — reject anything that could
+      // not survive that round-trip.
+      if (status !== 503) {
+        throw new RangeError(
+          "ExtraRouteRejection: retryAfterSeconds is only valid with status 503",
+        );
+      }
+      if (!Number.isInteger(retryAfterSeconds) || retryAfterSeconds < 0) {
+        throw new RangeError(
+          "ExtraRouteRejection: retryAfterSeconds must be a non-negative integer",
+        );
+      }
+    }
+    this.retryAfterSeconds = retryAfterSeconds;
   }
 }

package/src/api/index.ts

@@ -33,6 +33,7 @@ export type {
   AnonymousExtraRouteDeps,
   ExtraRouteDefinition,
   ExtraRouteEntry,
+  ExtraRouteRejectionOptions,
   ExtraRouteRejectionStatus,
   SignatureExtraRoute,
   SignatureExtraRouteDeps,

package/src/api/server.ts

@@ -160,14 +160,17 @@ export type ServerOptions = {
   //     of the app process.
   //   - `auth`: gates a single path-pattern (default `/api/auth/*`)
   //     with tighter limits. Typically `limit: 5, windowSeconds: 60`
-  //     to slow brute-force without breaking real users.
+  //     to slow brute-force without breaking real users. GET /api/auth/tenants
+  //     (session read, called on every page load) is always exempt — see
+  //     AUTH_RATE_LIMIT_EXEMPT_ROUTES in api-constants.ts.
   // Both omitted → no L1/L2 wired and no resolver auto-built unless an
   // L3 handler declared `rateLimit:`. This keeps zero-cost when unused.
   rateLimit?: {
     readonly global?: Omit<GlobalIpRateLimitOptions, "resolver">;
     readonly auth?: Omit<AuthEndpointRateLimitOptions, "resolver"> & {
       // Path-pattern the L2 middleware applies to. Default `/api/auth/*`.
-      // Override for apps with a different auth route layout.
+      // Override for apps with a different auth route layout. The
+      // GET /api/auth/tenants exemption above applies regardless of `path`.
       readonly path?: string;
     };
   };
@@ -1178,6 +1181,9 @@ function buildExtraRouteHonoHandler(
           );
         } catch (e) {
           if (e instanceof ExtraRouteRejection) {
+            if (e.retryAfterSeconds !== undefined) {
+              return c.json(e.body, e.status, { "Retry-After": String(e.retryAfterSeconds) });
+            }
             return c.json(e.body, e.status);
           }
           return c.json(

package/src/changes.json

@@ -1,4 +1,46 @@
 [
+  {
+    "version": "0.305.0",
+    "type": "breaking",
+    "title": "rateLimit.auth (L2) no longer throttles GET /api/auth/tenants",
+    "detail": "The SPA's own session bootstrap called GET /api/auth/tenants on every\npage load, which counted against the L2 auth-endpoint bucket and threw\n429 on the 6th page load within a minute. This route is now exempted\nfrom rateLimit.auth by exact method+path match; all other auth routes\n(including POST on the same path, if ever added) are unaffected.",
+    "migration": "Apps using the default rateLimit.auth need no changes. Apps that want\nto keep throttling GET /api/auth/tenants should rely on rateLimit.global\n(L1, IP-based) instead. Credential-submitting POST routes are unaffected\neven when rateLimit.auth's `path` option is customized."
+  },
+  {
+    "version": "0.305.0",
+    "type": "fix",
+    "title": "KUMIKO_DRY_RUN_ENV=pulumi and =k8s now list optional env keys (e.g. PROMETHEUS_METRICS_TOKEN) as commented-out lines under an \"Optional\" header, with secret flag, generator and description; defaulted keys stay omitted",
+    "migration": "No action needed. Uncomment and set an optional line only when you want to enable that feature."
+  },
+  {
+    "version": "0.305.0",
+    "type": "improvement",
+    "title": "ExtraRouteRejection supports 503 + Retry-After for signature routes whose verify() is temporarily unable to run"
+  },
+  {
+    "version": "0.305.0",
+    "type": "fix",
+    "title": "Job backoff now waits between retries: backoff defaults to a 1000 ms base delay and accepts { type, delayMs } (fw#3167)",
+    "detail": "Previously, jobs with backoff set retried immediately: BullMQ received only { type } with no delay, and its fixed/exponential strategies compute NaN/undefined without one (falsy, so no wait). Now \"fixed\" waits a constant 1000 ms and \"exponential\" waits 1000/2000/4000 ms... between attempts by default. Jobs with a high retries count will therefore take noticeably longer to reach their final failure. A new object form, backoff: { type, delayMs }, lets a job configure its own base delay instead of the 1000 ms default."
+  },
+  {
+    "version": "0.305.0",
+    "type": "breaking",
+    "title": "Writes under an anonymous root need access.personalData: \"public-intake\" at runtime, across feature boundaries (fw#3165)",
+    "detail": "The boot check from fw#2885 only sees personal-data keys in an anonymous write handler's own input schema, for entities of its own feature. Every public dispatch (write, batch command, query, stream) now computes a WriteOrigin (root handler, anonymous root, public-intake declared) once. Every nested call inherits it: ctx.write, ctx.writeAs, ctx.query, ctx.queryAs, nested writes and afterCommit hooks. When the root is anonymous and does not declare public-intake, a write that touches a personal-data field (pii / userOwned / recordOwned) of any registered entity fails with AccessDeniedError, details.reason \"public_intake_required\". The error details name the root handler, the table and the fields, never the values. The check runs in TenantDb.insertOne/updateMany, in db.global().insertOne/updateMany and in the event-sourced create/update executor, after preSave and before the event append. It also covers rebound TenantDbs (acknowledgeCrossTenant, hook re-gating). Authenticated sessions are not affected. Not gated: ctx.db.unsafeRaw (covered by escapeHatch plus audit); ctx.appendEvent on a feature's own events (foreign events are already rejected); tables outside the registered entities; jobs and event subscribers queued from an anonymous root; and TenantDbs that handler code builds directly with createTenantDb. The last two are tracked in fw#3185, which also lists the bundled auth-email-password and user-data-rights flows that go through unsafeRaw or createTenantDb.",
+    "migration": "A write handler that anonymous callers can reach (roles include \"anonymous\") and that writes a personal-data field (pii / userOwned / recordOwned) of any entity must declare access: { roles: [..., \"anonymous\"], personalData: \"public-intake\" }. This applies whether the handler writes the field itself or through ctx.db, the CRUD executor, ctx.write, ctx.writeAs/queryAs or a postSave/afterCommit hook, and it applies across features. Without the declaration the write now fails with AccessDeniedError (details.reason \"public_intake_required\"). A failing afterCommit hook is only logged, and its write does not happen. Known consumer handlers, measured on 23.09.2026: offlot-app waitlist:submit, vehicle-enquiry:submit and try-first:set-contact; publicstatus email-subscriber:subscribe; show-pony rsvp:submit. Add the declaration if the anonymous intake is intended (the handler's rateLimit is then the only protection). Otherwise stop writing the field from the anonymous path."
+  },
+  {
+    "version": "0.305.0",
+    "type": "improvement",
+    "title": "setupTestStack accepts a metrics option, forwarded to buildServer like runProdApp (fw#3182)",
+    "detail": "TestStackOptions gains an optional metrics field forwarded to buildServer, same as runProdApp. Spread resolveObservabilityWiring(token) into setupTestStack/setupTestStackFromFeatures/setupAppTestStack to get /metrics mounted in integration tests with the same token-gated PrometheusMeter-backed behavior as prod."
+  },
+  {
+    "version": "0.305.0",
+    "type": "fix",
+    "title": "Write-path 5xx logs now include the original cause chain"
+  },
   {
     "version": "0.303.0",
     "type": "breaking",

package/src/db/event-store-executor-write.ts

@@ -31,6 +31,7 @@ import {
   tryMapUniqueViolation,
 } from "./event-store-executor-context";
 import { runInSavepointIfSupported } from "./query";
+import { assertPersonalDataWrite, tableNameOf } from "./tenant-db";
 import { tenantDbRunner } from "./tenant-db-runner";
 
 // Art. 17 erasure runs as the framework operator, not as a row owner; a
@@ -145,6 +146,9 @@ export function createWriteVerbs(
       if ("failure" in preSaveResult) return preSaveResult.failure;
       const data = preSaveResult.data;
 
+      // After preSave so derived fields count, before the event append so nothing persists.
+      assertPersonalDataWrite(db, tableNameOf(table), Object.keys(data), entity);
+
       // H.2 — entity-level write-ownership on create. No oldRow exists, so
       // only the new row is checked. No Straddle concern for creates.
       if (!userCanCreateFieldRow(user, entity.access?.write, data)) {
@@ -334,6 +338,9 @@ export function createWriteVerbs(
       if ("failure" in preSaveResult) return preSaveResult.failure;
       const changes = preSaveResult.data;
 
+      // After preSave so derived fields count, before the event append so nothing persists.
+      assertPersonalDataWrite(db, tableNameOf(table), Object.keys(changes), entity);
+
       // H.2 — entity-level write-ownership on update. Load old row (already
       // done above), build post-change row via shallow merge. Straddle-safe
       // multi-role check: at least one role must accept BOTH old and new —

package/src/db/tenant-db.ts

@@ -24,6 +24,7 @@ import {
   type SelectOptions,
   type WhereObject,
 } from "../db/query";
+import type { EntityDefinition } from "../engine/types/fields";
 import { SYSTEM_TENANT_ID, type TenantId } from "../engine/types/identifiers";
 import { AccessDeniedError, InternalError, memberResolutionReadOnlyDenied } from "../errors";
 import { emitDbQuery, type Meter, registerStandardMetrics, type Tracer } from "../observability";
@@ -45,6 +46,21 @@ const declaredUnsafeRawRunners = new WeakMap<
   (reason: string) => DbRunner
 >();
 
+// The CRUD executor writes through tenantDbRunner, not insertOne, so it asks the
+// TenantDb it was handed for its gate. Bound inside createTenantDb so rebound instances
+// (withUnsafeRawGrant, acknowledgeConventionCrossTenant) carry it too.
+const personalDataGates = new WeakMap<TenantDb, PersonalDataGate>();
+
+// The executor passes its entity so the check does not depend on the table-name lookup.
+export function assertPersonalDataWrite(
+  db: TenantDb,
+  tableName: string,
+  keys: readonly string[],
+  entity: EntityDefinition,
+): void {
+  personalDataGates.get(db)?.(tableName, keys, entity);
+}
+
 // Framework-private (not re-exported from db/index.ts): same grant check + audit as unsafeRaw, for engine forwarding.
 export function unsafeRawForDeclaredStep(
   holder: TenantDb | UncheckedSystemDb,
@@ -170,7 +186,7 @@ export function castTenantRows<T>(rows: readonly Record<string, unknown>[]): rea
   return rows as unknown as readonly T[];
 }
 
-function tableNameOf(table: Table | EntityTableMeta): string {
+export function tableNameOf(table: Table | EntityTableMeta): string {
   const sym = (table as Record<symbol, unknown>)[KUMIKO_NAME_SYMBOL];
   if (typeof sym === "string") return sym;
   return asEntityTableMeta(table)?.tableName ?? "<unknown>";
@@ -205,8 +221,16 @@ export type TenantDbGrants = {
   // Set for a resolved member principal (ctx.queryAsMember): no raw DbRunner leaves
   // this TenantDb, so no handler can COMMIT/RELEASE SAVEPOINT out of the READ ONLY scope.
   readonly memberReadOnly?: boolean;
+  // Set only for an anonymous root without personalData: "public-intake" (write-origin.ts).
+  readonly personalDataGate?: PersonalDataGate;
 };
 
+export type PersonalDataGate = (
+  tableName: string,
+  keys: readonly string[],
+  entity?: EntityDefinition,
+) => void;
+
 const unsafeRawRebinders = new WeakMap<
   TenantDb,
   (grant: EscapeHatchDeclaration | undefined) => TenantDb
@@ -347,6 +371,20 @@ export function createTenantDb(
     return grants?.globalWrites?.reason ?? "";
   }
 
+  function personalDataDenied(
+    table: Table | EntityTableMeta,
+    keys: readonly string[],
+  ): AccessDeniedError | undefined {
+    if (!grants?.personalDataGate) return undefined;
+    try {
+      grants.personalDataGate(tableNameOf(table), keys);
+      return undefined;
+    } catch (e) {
+      if (e instanceof AccessDeniedError) return e;
+      throw e;
+    }
+  }
+
   function foreignTenantOnGlobalWrite(
     table: Table | EntityTableMeta,
     tenantIdValue: unknown,
@@ -379,7 +417,9 @@ export function createTenantDb(
         values: Record<string, unknown>,
       ): Promise<T | undefined> {
         const denied =
-          missingEscapeHatch(table) ?? foreignTenantOnGlobalWrite(table, values["tenantId"]);
+          missingEscapeHatch(table) ??
+          foreignTenantOnGlobalWrite(table, values["tenantId"]) ??
+          personalDataDenied(table, Object.keys(values));
         if (denied) return Promise.reject(denied);
         report("global-write", globalWriteReason());
         return withDbSpan("insert", table, async () => bunInsertOne<T>(db, table, values));
@@ -389,7 +429,9 @@ export function createTenantDb(
         where: WhereObject,
       ): Promise<readonly T[]> {
         const denied =
-          missingEscapeHatch(table) ?? foreignTenantOnGlobalWrite(table, set["tenantId"]);
+          missingEscapeHatch(table) ??
+          foreignTenantOnGlobalWrite(table, set["tenantId"]) ??
+          personalDataDenied(table, Object.keys(set));
         if (denied) return Promise.reject(denied);
         if (!where || Object.keys(where).length === 0) {
           return Promise.reject(
@@ -483,6 +525,8 @@ export function createTenantDb(
         );
         if (denied) return Promise.reject(denied);
       }
+      const personalDenied = personalDataDenied(table, Object.keys(values));
+      if (personalDenied) return Promise.reject(personalDenied);
       const data = insertValues(table, values);
       return withDbSpan("insert", table, async () => bunInsertOne<T>(db, table, data));
     },
@@ -499,6 +543,8 @@ export function createTenantDb(
           ),
         );
       }
+      const personalDenied = personalDataDenied(table, Object.keys(set));
+      if (personalDenied) return Promise.reject(personalDenied);
       const filter = writeWhere(table, where);
       return withDbSpan("update", table, async () => bunUpdateMany<T>(db, table, set, filter));
     },
@@ -525,6 +571,7 @@ export function createTenantDb(
     return createTenantDb(db, tenantId, "system", tracer, meter, signal, grants);
   });
   bindTenantDbRunner(tenantDb, db);
+  if (grants?.personalDataGate) personalDataGates.set(tenantDb, grants.personalDataGate);
   return tenantDb;
 }
 

package/src/engine/boot-validator/access-declarations.ts

@@ -1,68 +1,20 @@
+import {
+  accessAllowsAnonymous,
+  declaredPersonalData,
+  personalFieldNames,
+} from "../personal-data-fields";
 import { ANONYMOUS_ROLE } from "../system-user";
 import type {
   AccessRule,
   FeatureDefinition,
-  OwnershipMap,
-  OwnershipRule,
   QueryHandlerDef,
   StreamHandlerDef,
   WriteHandlerDef,
 } from "../types";
-import type { EntityDefinition, ResolvedPiiFlags } from "../types/fields";
 import { collectZodObjectKeys } from "./zod-shape";
 
 type HandlerKind = "write" | "query" | "stream";
 
-// Personal-data annotation check mirrors pii-retention.ts's hasAnonymizableSubjectField,
-// minus tenantOwned: a tenant-scoped field isn't an individual's personal data in the
-// sense the openToAll personal-data check is guarding against.
-function isPersonalDataField(field: unknown): boolean {
-  const annot = field as ResolvedPiiFlags; // @cast-boundary schema-walk — see pii-retention.ts
-  return Boolean(annot.pii || annot.userOwned || annot.recordOwned);
-}
-
-function isCallerIdRuleOn(rule: OwnershipRule, column: string): boolean {
-  if (rule === "all" || rule.kind !== "from") return false;
-  return rule.refKind === "user" && rule.refPath === "id" && rule.column === column;
-}
-
-// The executor checks access.write against every created/updated row; one "all" role
-// or an empty map (= public) lets a caller write rows owned by someone else.
-function writeMapBindsRowsToCaller(
-  writeMap: OwnershipMap | undefined,
-  ownerColumn: string,
-): boolean {
-  const rules = Object.values(writeMap ?? {});
-  return rules.length > 0 && rules.every((rule) => isCallerIdRuleOn(rule, ownerColumn));
-}
-
-const ROW_ID_COLUMN = "id";
-
-// A self/record-owned field's subject is the row itself, so only from("user:id", "id")
-// makes that row the caller — on any other entity "self" names a third party.
-function callerBindingColumn(annot: ResolvedPiiFlags): string | undefined {
-  if (annot.userOwned) return annot.userOwned.ownerField;
-  if (annot.pii || annot.recordOwned) return ROW_ID_COLUMN;
-  return undefined;
-}
-
-function isOwnerBoundField(field: unknown, entity: EntityDefinition): boolean {
-  const column = callerBindingColumn(field as ResolvedPiiFlags); // @cast-boundary schema-walk — see pii-retention.ts
-  return column !== undefined && writeMapBindsRowsToCaller(entity.access?.write, column);
-}
-
-function personalFieldNames(
-  entity: EntityDefinition,
-  honorOwnerBinding: boolean,
-): ReadonlySet<string> {
-  const names = new Set<string>();
-  for (const [fieldName, field] of Object.entries(entity.fields)) {
-    const exempt = honorOwnerBinding && isOwnerBoundField(field, entity);
-    if (isPersonalDataField(field) && !exempt) names.add(fieldName);
-  }
-  return names;
-}
-
 // escapeHatch and r.systemScope() can write around the entity's write map
 // (db.global(), systemDb, SYSTEM identity), so the map no longer vouches for the row.
 function canWriteAroundExecutor(feature: FeatureDefinition, handler: WriteHandlerDef): boolean {
@@ -104,19 +56,6 @@ function hasOpenToAll(access: AccessRule): boolean {
   return "openToAll" in access;
 }
 
-// Read via `unknown`: access can come from untyped sources (pattern JSON, Designer).
-function declaredPersonalData(access: AccessRule): unknown {
-  if (!("openToAll" in access)) return access.personalData;
-  const openToAll: unknown = access.openToAll;
-  if (typeof openToAll !== "object" || openToAll === null) return undefined;
-  return "personalData" in openToAll ? openToAll.personalData : undefined;
-}
-
-function accessAllowsAnonymous(access: AccessRule): boolean {
-  if ("openToAll" in access) return false;
-  return Array.isArray(access.roles) && access.roles.includes(ANONYMOUS_ROLE);
-}
-
 function declaresTenantMembersPersonalData(access: AccessRule): boolean {
   return declaredPersonalData(access) === "tenant-members";
 }

package/src/engine/index.ts

@@ -410,6 +410,8 @@ export type {
   HookMap,
   ImageFieldDef,
   ImagesFieldDef,
+  JobBackoff,
+  JobBackoffStrategy,
   JobContext,
   JobDefinition,
   JobHandlerFn,

package/src/engine/personal-data-fields.ts

@@ -0,0 +1,66 @@
+import { ANONYMOUS_ROLE } from "./system-user";
+import type { AccessRule, OwnershipMap, OwnershipRule } from "./types";
+import type { EntityDefinition, ResolvedPiiFlags } from "./types/fields";
+
+// Personal-data annotation check mirrors pii-retention.ts's hasAnonymizableSubjectField,
+// minus tenantOwned: a tenant-scoped field isn't an individual's personal data in the
+// sense the openToAll / public-intake personal-data checks are guarding against.
+function isPersonalDataField(field: unknown): boolean {
+  const annot = field as ResolvedPiiFlags; // @cast-boundary schema-walk — see pii-retention.ts
+  return Boolean(annot.pii || annot.userOwned || annot.recordOwned);
+}
+
+function isCallerIdRuleOn(rule: OwnershipRule, column: string): boolean {
+  if (rule === "all" || rule.kind !== "from") return false;
+  return rule.refKind === "user" && rule.refPath === "id" && rule.column === column;
+}
+
+// The executor checks access.write against every created/updated row; one "all" role
+// or an empty map (= public) lets a caller write rows owned by someone else.
+function writeMapBindsRowsToCaller(
+  writeMap: OwnershipMap | undefined,
+  ownerColumn: string,
+): boolean {
+  const rules = Object.values(writeMap ?? {});
+  return rules.length > 0 && rules.every((rule) => isCallerIdRuleOn(rule, ownerColumn));
+}
+
+const ROW_ID_COLUMN = "id";
+
+// A self/record-owned field's subject is the row itself, so only from("user:id", "id")
+// makes that row the caller — on any other entity "self" names a third party.
+function callerBindingColumn(annot: ResolvedPiiFlags): string | undefined {
+  if (annot.userOwned) return annot.userOwned.ownerField;
+  if (annot.pii || annot.recordOwned) return ROW_ID_COLUMN;
+  return undefined;
+}
+
+function isOwnerBoundField(field: unknown, entity: EntityDefinition): boolean {
+  const column = callerBindingColumn(field as ResolvedPiiFlags); // @cast-boundary schema-walk — see pii-retention.ts
+  return column !== undefined && writeMapBindsRowsToCaller(entity.access?.write, column);
+}
+
+export function personalFieldNames(
+  entity: EntityDefinition,
+  honorOwnerBinding: boolean,
+): ReadonlySet<string> {
+  const names = new Set<string>();
+  for (const [fieldName, field] of Object.entries(entity.fields)) {
+    const exempt = honorOwnerBinding && isOwnerBoundField(field, entity);
+    if (isPersonalDataField(field) && !exempt) names.add(fieldName);
+  }
+  return names;
+}
+
+// Read via `unknown`: access can come from untyped sources (pattern JSON, Designer).
+export function declaredPersonalData(access: AccessRule): unknown {
+  if (!("openToAll" in access)) return access.personalData;
+  const openToAll: unknown = access.openToAll;
+  if (typeof openToAll !== "object" || openToAll === null) return undefined;
+  return "personalData" in openToAll ? openToAll.personalData : undefined;
+}
+
+export function accessAllowsAnonymous(access: AccessRule): boolean {
+  if ("openToAll" in access) return false;
+  return Array.isArray(access.roles) && access.roles.includes(ANONYMOUS_ROLE);
+}