@thomasfosterau/pulpit 0.0.0 → 0.1.0

package/dist/subtype.js

@@ -0,0 +1,1300 @@
+/**
+ * **The subtype operation factory** — a leaf's CRUD, version history and
+ * list, gated by its access kind, over the version chain and a
+ * current-version view.
+ *
+ * The behavioural spec is gardeneria's `apps/api/src/operations/subtype.ts`
+ * (`defineNodeSubtypeE`, `LeafAccess`, the gates `requireWriterE` /
+ * `requireCreatorE` / `stampOwnerE` / `ownedListFilterE`), its
+ * `packages/database/src/guards.ts` (`canViewOwnedE`, `ownedReadScopeE`) and
+ * website's `apps/api/src/operations/to-resource.ts`
+ * (`loadListVisibilityFilters`, the two-state list predicate). A `#NNN` here
+ * names a gardeneria issue.
+ *
+ * ## Access kinds
+ *
+ * - `reference` — corpus material. Create / update / delete / restore gate on
+ *   the corpus-write rung; when the view has a `visibility` column, reads
+ *   show only `public` rows below the view-private rung, apart from the
+ *   soft-delete axis, and the `followers` rows whose declared
+ *   `followersOfColumn` names the viewer or an account they follow
+ *   (pulpit#92). A
+ *   write or history read to an existing row also needs the row to be one
+ *   `get` would serve the caller (pulpit#101).
+ * - `owned` — a member's own row. Create gates on any signed-in account and
+ *   stamps the owner; every other write loads the owner and gates on
+ *   owner-or-moderator (a missing owner is `NotFound`, never an open gate);
+ *   `get` applies {@link canViewOwned} to the row; `list` applies the same
+ *   facts as a {@link ListFilter} ({@link ownedListFilter}), so the two can
+ *   never disagree.
+ *
+ * ## Invariants
+ *
+ * - A read (`get` / `getMany` / `list`) answers a hidden row as
+ *   {@link NodeNotFound} or omits it, never {@link Forbidden}
+ *   (`SEC-AUTH-ENUM-001`): a 403 would confirm the row exists. The write and
+ *   history gate ({@link requireWriter}) does answer `Forbidden` for an
+ *   existing owned row the caller doesn't own, whatever its visibility, so
+ *   it deliberately confirms existence to a signed-in caller (pulpit#24;
+ *   SECURITY.md → "Existence disclosure by the write gates"). On a reference
+ *   leaf, a corpus writer's write or history read to a row `get` hides from
+ *   them fails `NodeNotFound`, as `get` does, before the chain is reached
+ *   (pulpit#101, `PUB-009`).
+ * - A list's order ({@link ListOrder}) only places the rows its filters
+ *   chose: it never changes membership or the total, and a column that is
+ *   not sortable (outside the leaf's `sortable` allow-list or, without one,
+ *   the view's declared `columns`) fails {@link InvalidListOrder} before
+ *   anything is read, never reaching the store (pulpit#112).
+ * - Soft-deleted rows are visible only to the view-deleted rung, and a list
+ *   includes them only when the caller also asked (`includeDeleted`).
+ * - A declaration naming columns the view lacks fails closed — nothing lists,
+ *   and `get` / `getMany` show nothing.
+ * - The follower seam, when a runtime does not provide one, answers "nobody
+ *   follows anybody" — a `followers` row is then its owner's and the rung's
+ *   alone. Fail closed.
+ *
+ * ## Lifecycle hooks
+ *
+ * A leaf's write side effects compose as {@link LifecycleHooks} (pulpit#45):
+ * before hooks run inside each write, after its gate and before the append,
+ * and may transform the patch or refuse the write ({@link WriteRejected});
+ * after hooks run in {@link subtypeHandlers} once the write's transaction
+ * has returned, and never fail it. The cache write-through is the first
+ * after hook ({@link cacheWriteThrough}). Events fire on explicit writes
+ * only: a future `publishedAt` arriving emits nothing (`./publication`'s
+ * `duePublications` drives an application's sweep instead).
+ *
+ * ## Seams
+ *
+ * Three things the kernel does not own, each an explicit parameter rather
+ * than an import (see the package README → Seams for each one's expected
+ * shape and which package, if any, fills it):
+ *
+ * - the **viewer** and the **role axes** ({@link Viewer}, {@link AccessPolicy})
+ *   and the **follower** answer — effect-auth's session context, role ladder
+ *   and `IsFollower`. Its read scope (`OwnedAccess` / `Guard` / `Ladder` /
+ *   `Cacheability`) is on effect-auth's `trunk` but unpublished (release PR
+ *   effect-auth#177);
+ * - the **current-version view** ({@link LeafStore}) — a Drizzle store over
+ *   effect-drizzle-ext's `makeCurrentVersionView`;
+ * - the **handlers config** the factory's operations plug into
+ *   ({@link subtypeHandlers}) — the record a JSON:API server's resource
+ *   handlers are expected to accept (effect-jsonapi's `ResourceHandlers`,
+ *   exported since 0.15.0 but not yet wired here; pulpit#5), with the
+ *   write-through to the resource cache the application fills.
+ *
+ * @copyright Thomas Foster
+ * @module pulpit/subtype
+ * @since 0.1.0
+ */
+import * as Array from "effect/Array";
+import * as Arr from "effect/Array";
+import * as Cause from "effect/Cause";
+import * as Clock from "effect/Clock";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as HashMap from "effect/HashMap";
+import * as HashSet from "effect/HashSet";
+import * as Match from "effect/Match";
+import * as Option from "effect/Option";
+import * as Predicate from "effect/Predicate";
+import * as Record from "effect/Record";
+import * as Ref from "effect/Ref";
+import * as Str from "effect/String";
+import * as Schema from "effect/Schema";
+import { ResourceHandlers } from "@thomasfosterau/effect-jsonapi";
+import { always, and, anyOf, eq, isIn, locale as localeIn, LOCALE_COLUMN, ne, never, or, } from "./filter.js";
+import { byCodePoint } from "./internal/list-order.js";
+import { canViewOwnedRow, declaresColumns, ownedFacts } from "./internal/owned-columns.js";
+import { canViewReferenceRow, referenceListFilter } from "./internal/reference-columns.js";
+import { defineVersionChain, NodeNotFound, MAX_HISTORY_LIMIT, VersionNotFound as VersionNotFoundError, } from "./version-chain.js";
+/** The write clock: the current instant, as the `Date` a fact stores. */
+const nowDate = Effect.map(Clock.currentTimeMillis, (millis) => DateTime.toDate(DateTime.makeUnsafe(millis)));
+/**
+ * The fail-closed follower seam: nobody follows anybody. `nobody` is the
+ * matches-nothing value of the `in` node (SQL: `(select null::uuid where false)`).
+ *
+ * @since 0.1.0
+ */
+export const nobodyFollows = (nobody) => ({
+    isFollower: () => Effect.succeed(false),
+    following: () => nobody,
+});
+// ── Errors ────────────────────────────────────────────────────────────
+/**
+ * No signed-in viewer where one is required: the wire's 401.
+ *
+ * @since 0.1.0
+ */
+export class Unauthorized extends Schema.TaggedError()("Unauthorized", {}) {
+}
+/**
+ * A signed-in viewer below the rung a write needs: the wire's 403. Never used to hide a row.
+ *
+ * @since 0.1.0
+ */
+export class Forbidden extends Schema.TaggedError()("Forbidden", {}) {
+}
+/**
+ * A list order the leaf does not sort by: a key whose column is not sortable
+ * (outside the leaf's `sortable` allow-list or, without one, outside the
+ * view's declared `LeafStore.columns`), a direction other than `asc` /
+ * `desc`, or input not shaped as an order at all (an `orderBy` that is not
+ * an array, a key that is not an object, a `column` that is not a string).
+ * The wire's 400. The order is checked before the viewer or anything else is
+ * read, so it says nothing about any row, but **it does say which columns
+ * are sortable**: without a `sortable` allow-list, that a name is (or is
+ * not) one of the view's columns. `column` is the caller's own key, never
+ * passed to the store, or `""` when the key carries no string column
+ * (pulpit#112).
+ *
+ * @since 0.1.0
+ */
+export class InvalidListOrder extends Schema.TaggedError()("InvalidListOrder", {
+    type: Schema.String,
+    column: Schema.String,
+}) {
+}
+/**
+ * A leaf declared against the rules: a `sortable` entry that is not one of
+ * its view's `LeafStore.columns`. Thrown by {@link defineSubtype} when the
+ * leaf is declared, never an Effect failure, like `./edges`'
+ * `EdgeDeclarationError`: a misspelt allow-list entry must stop its module
+ * loading rather than silently leave a column unsortable (pulpit#112).
+ *
+ * @since 0.1.0
+ */
+export class SubtypeDeclarationError extends Schema.TaggedError()("SubtypeDeclarationError", { message: Schema.String }) {
+}
+/**
+ * Resolve a viewer's {@link ReadScope}.
+ *
+ * @since 0.1.0
+ */
+export const readScopeFor = (viewer, policy, followers) => Option.match(viewer, {
+    onNone: () => ({ kind: "public" }),
+    onSome: (account) => policy.canViewPrivate(account)
+        ? { kind: "all" }
+        : { kind: "member", userId: account.id, following: followers.following(account.id) },
+});
+/**
+ * The owned-material read predicate — the single interpretation of the
+ * three-state visibility axis plus the orthogonal `draft` axis (#1118):
+ *
+ * | visibility  | who may view                                                   |
+ * | ----------- | -------------------------------------------------------------- |
+ * | `public`    | everyone, anonymous included                                   |
+ * | `followers` | the owner; the owner's followers; the view-private rung        |
+ * | `private`   | the owner; the view-private rung                               |
+ *
+ * `draft: true` narrows whatever `visibility` allows down to the owner and
+ * the rung — a `public` draft is exactly as hidden as a `private` one — and
+ * so does `unapproved: true` on a moderated leaf (a `pending` or `rejected`
+ * row reads only to its author and the rung, pulpit#154). Never
+ * fails; callers turn `false` into {@link NodeNotFound}.
+ *
+ * `defineSubtype`'s `get` / `getMany` and `./edges`' `canViewEndpoint`
+ * apply the same predicate to the row they read. There, an owner column
+ * holding no string (a `NULL`, an absent key) reads as no owner: no viewer
+ * is its owner and the follower seam is never asked, so the row shows only
+ * when `public`, not a draft and not unapproved, or to the rung, as {@link ownedListFilter}
+ * lists it (`SEC-AUTH-ENUM-001`).
+ *
+ * @since 0.1.0
+ */
+export const canViewOwned = (viewer, policy, followers, row) => canViewOwnedRow(viewer, policy, followers, { ...row, ownerId: Option.some(row.ownerId) });
+/**
+ * The owned-leaf access declaration with the conventional factory-built column names.
+ *
+ * @since 0.1.0
+ */
+export const ownedAccess = (options = {}) => ({
+    kind: "owned",
+    ownerColumn: "ownerId",
+    visibilityColumn: "visibility",
+    draftColumn: options.draft === true ? Option.some("draft") : Option.none(),
+    moderationColumn: options.moderation === true ? Option.some("moderationState") : Option.none(),
+});
+/**
+ * The owned-leaf LIST filter — {@link ReadScope} rendered over the leaf's
+ * declared view columns. When the leaf carries a draft column, every
+ * non-owner arm additionally requires `draft = false`, and when it carries a
+ * moderation column, `moderation = 'approved'`; the owner's own arm never
+ * does, so a member lists their own drafts and unapproved rows. Columns the view lacks
+ * fail closed.
+ *
+ * @since 0.1.0
+ */
+export const ownedListFilter = (access, viewColumns, scope) => {
+    if (!declaresColumns(access, viewColumns))
+        return never;
+    const published = (filter) => and(filter, ...Option.toArray(Option.map(access.draftColumn, (draft) => eq(draft, false))), ...Option.toArray(Option.map(access.moderationColumn, (moderation) => eq(moderation, "approved"))));
+    return Match.value(scope).pipe(Match.discriminatorsExhaustive("kind")({
+        all: () => always,
+        public: () => published(eq(access.visibilityColumn, "public")),
+        member: (member) => or(published(eq(access.visibilityColumn, "public")), eq(access.ownerColumn, member.userId), published(and(eq(access.visibilityColumn, "followers"), isIn(access.ownerColumn, member.following)))),
+    }));
+};
+/**
+ * The soft-delete arm of every list: tombstones only when the caller asked
+ * AND holds the view-deleted rung — asking without the rung changes nothing.
+ *
+ * @since 0.1.0
+ */
+export const softDeleteFilter = (viewer, policy, includeDeleted) => includeDeleted && Option.exists(viewer, policy.canViewDeleted) ? always : ne("action", "delete");
+/**
+ * The reference-leaf privacy arm (`PUB-009`): `visibility = 'public'` unless
+ * the viewer holds the view-private rung, or the view has no visibility
+ * column (an Entity leaf rides no such axis). Given a followers arm (the
+ * leaf's `access`, declaring `followersOfColumn` over a view that carries
+ * it, and the follower seam), a signed-in viewer also lists the `followers`
+ * rows whose column names them or an account they follow (pulpit#92):
+ * `visibility = 'followers' AND (<followersOfColumn> = <viewer> OR
+ * <followersOfColumn> IN (<following>))`. Without one (the default,
+ * `Option.none()`), a `followers` row is the view-private rung's alone.
+ * Pass `Option.some({ access, followers })` whenever the leaf declares
+ * `followersOfColumn`: `defineSubtype`'s `get` / `getMany` read the
+ * declared column, so the three-argument form agrees with them only for a
+ * leaf without it (for one with it, `get` serves `followers` rows this
+ * hides).
+ *
+ * @since 0.1.0
+ */
+export const referencePrivacyFilter = (viewer, policy, viewColumns, followersArm = Option.none()) => Option.match(followersArm, {
+    onNone: () => referenceListFilter({}, viewColumns, publicOrAll(viewer, policy)),
+    onSome: (arm) => referenceListFilter(arm.access, viewColumns, readScopeFor(viewer, policy, arm.followers)),
+});
+/** A read scope without the follower set: a member reads as the anonymous do. */
+const publicOrAll = (viewer, policy) => Option.exists(viewer, policy.canViewPrivate) ? { kind: "all" } : { kind: "public" };
+// ── The write gates ───────────────────────────────────────────────────
+const signedIn = (viewer) => Effect.fromOption(viewer, () => new Unauthorized());
+const atRung = (viewer, admits) => Effect.filterOrFail(signedIn(viewer), admits, () => new Forbidden());
+/**
+ * The gate for a CREATE: reference data → the corpus-write rung; owned → any signed-in account.
+ *
+ * @since 0.1.0
+ */
+export const requireCreator = (access, viewer, policy) => access.kind === "reference" ? atRung(viewer, policy.canWriteCorpus) : signedIn(viewer);
+/**
+ * The gate for a write to an EXISTING row: reference data → the corpus-write
+ * rung; owned material → the row's owner or the moderate rung. A missing
+ * owner on an owned leaf is {@link NodeNotFound}, never an open gate.
+ *
+ * On an owned leaf it never reads the row's visibility, draft or delete state:
+ * a signed-in caller who is neither the owner nor at the moderate rung gets
+ * {@link Forbidden} for any row with an owner record,
+ * hidden or not, so the gate deliberately confirms existence (pulpit#24, an
+ * exception to `SEC-AUTH-ENUM-001`; SECURITY.md → "Existence disclosure by the
+ * write gates"). An anonymous caller gets `Unauthorized` for every id.
+ *
+ * On a reference leaf this is the rung check alone: it reads no row, so it
+ * answers `Unauthorized` / `Forbidden` alike for every id. `defineSubtype`
+ * follows it with the read rung the row demands (pulpit#101): a row its `get`
+ * hides from the caller fails {@link NodeNotFound}, as `get` does
+ * (`PUB-009`, `SEC-AUTH-ENUM-001`). A caller using this gate directly on a
+ * reference row must apply that check too.
+ *
+ * @since 0.1.0
+ */
+export const requireWriter = (access, viewer, policy, row, ownerOf) => access.kind === "reference"
+    ? atRung(viewer, policy.canWriteCorpus)
+    : Effect.gen(function* () {
+        const account = yield* signedIn(viewer);
+        const owner = yield* ownerOf;
+        if (Option.isNone(owner))
+            return yield* new NodeNotFound(row);
+        if (account.id === owner.value || policy.canModerate(account))
+            return account;
+        return yield* new Forbidden();
+    });
+/**
+ * The resource-object `meta` a {@link SubtypeDefinition.toResource} mapper
+ * stamps: the row's head version as a decimal string (`bigint` has no JSON
+ * form). It reaches only a resource the read already serves the viewer, so it
+ * discloses nothing about a hidden row (`SEC-AUTH-ENUM-001`); what it does
+ * disclose about a shown one is how many versions its chain holds.
+ *
+ * @example
+ * ```ts
+ * import { strictEqual } from "node:assert";
+ * import { versionMeta } from "@thomasfosterau/pulpit/subtype";
+ *
+ * const row = { id: "post-1", version: 3n, action: "update" as const, title: "Hello" };
+ * const resource = { type: "posts", id: row.id, meta: versionMeta(row) };
+ * strictEqual(resource.meta.version, "3");
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const versionMeta = (row) => ({
+    version: String(row.version),
+});
+// A version is a non-negative integer with no leading zero: anything else in
+// `meta.version` is not one this kernel stamped.
+const StampedVersion = Schema.Struct({
+    meta: Schema.Struct({
+        version: Schema.String.check(Schema.isPattern(/^(?:0|[1-9][0-9]*)$/, { description: "a head version in decimal" })),
+    }),
+});
+/**
+ * A single-resource response's `ETag` header value, read from the
+ * resource's `meta.version` ({@link versionMeta}): a strong tag (`"3"`)
+ * whose value is the head version, so the `If-Match` a client echoes names
+ * the version its write expects ({@link UpdateRequest.expectedVersion}; the
+ * header's mapping onto it is effect-jsonapi's, which 0.17.0 lacks). None when the value carries no
+ * decimal `meta.version`; a collection response takes none, having no single
+ * version to tag. Never fails.
+ *
+ * @example
+ * ```ts
+ * import { strictEqual } from "node:assert";
+ * import { Option } from "effect";
+ * import { versionEtag } from "@thomasfosterau/pulpit/subtype";
+ *
+ * const read = { type: "posts", id: "post-1", meta: { version: "3" } };
+ * strictEqual(Option.getOrElse(versionEtag(read), () => "none"), '"3"');
+ * const unstamped = { type: "posts", id: "post-1", meta: {} };
+ * strictEqual(Option.isNone(versionEtag(unstamped)), true);
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const versionEtag = (resource) => Option.map(Schema.decodeUnknownOption(StampedVersion)(resource), ({ meta }) => `"${meta.version}"`);
+/**
+ * The hard cap on a page (`SEC-INPUT-003`): no request drives an unbounded `LIMIT`.
+ *
+ * @since 0.1.0
+ */
+export const MAX_PAGE_LIMIT = 1000;
+/**
+ * A publication operation on a node with no live version (`discardDraft`
+ * with nothing published): the wire's 409.
+ *
+ * @since 0.1.0
+ */
+export class NotPublished extends Schema.TaggedError()("NotPublished", {
+    type: Schema.String,
+    id: Schema.String,
+}) {
+}
+// ── The lifecycle hook seam ───────────────────────────────────────────
+/**
+ * A before hook's refusal: the write it was shown does not happen, and the
+ * caller's transaction rolls back with it. `reason` is the hook's own,
+ * for the wire's 422 (or whatever the application maps it to).
+ *
+ * @since 0.1.0
+ */
+export class WriteRejected extends Schema.TaggedError()("WriteRejected", {
+    type: Schema.String,
+    id: Schema.String,
+    action: Schema.String,
+    reason: Schema.String,
+}) {
+}
+/**
+ * No hooks: the default for a leaf that declares none.
+ *
+ * @since 0.1.0
+ */
+export const noHooks = () => ({ before: [], after: [] });
+/**
+ * Concatenate hook sets in order: `a`'s before hooks run before `b`'s, and
+ * likewise after. The first set's `afterFailure` that is given wins.
+ *
+ * @example
+ * ```ts
+ * import { strictEqual } from "node:assert";
+ * import * as Effect from "effect/Effect";
+ * import { composeHooks, noHooks, type BeforeWriteHook } from "@thomasfosterau/pulpit/subtype";
+ *
+ * const audit: BeforeWriteHook<never, never> = {
+ *   name: "audit",
+ *   run: (event) => Effect.succeed(event.patch),
+ * };
+ * const hooks = composeHooks({ before: [audit], after: [] }, noHooks());
+ * strictEqual(hooks.before[0]?.name, "audit");
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const composeHooks = (...sets) => {
+    const afterFailure = Array.findFirst(sets, (set) => set.afterFailure !== undefined);
+    return {
+        before: Array.flatMap(sets, (set) => set.before),
+        after: Array.flatMap(sets, (set) => set.after),
+        afterFailure: Option.getOrUndefined(Option.flatMapNullishOr(afterFailure, (set) => set.afterFailure)),
+    };
+};
+/** Run the before hooks in order, each shown the patch the previous one returned. */
+const runBefore = (hooks, event) => Effect.reduce(hooks, () => event.patch, (patch, hook) => hook.run({ ...event, patch }).pipe(Effect.withSpan(`${event.type}.before.${hook.name}`)));
+/**
+ * Run the before hooks' locale passes in order, each shown the previous
+ * one's locale patch. A hook with no `locales` pass refuses a write that
+ * carries any locale change (fail closed, pulpit#56) and passes `{}` on.
+ */
+const runBeforeLocales = (hooks, event) => Effect.reduce(hooks, () => event.locales ?? {}, (locales, hook) => hook.locales === undefined
+    ? Array.isReadonlyArrayNonEmpty(writtenKeys(locales))
+        ? Effect.fail(new WriteRejected({
+            type: event.type,
+            id: event.id,
+            action: event.action,
+            reason: `before hook '${hook.name}' does not handle a locale patch`,
+        }))
+        : Effect.succeed(locales)
+    : hook
+        .locales({ ...event, locales })
+        .pipe(Effect.withSpan(`${event.type}.before.${hook.name}.locales`)));
+/** Run the after hooks in order, each failure handed to the policy, never to the write. */
+const runAfter = (hooks, event) => Effect.forEach(hooks.after, (hook) => hook.run(event).pipe(Effect.withSpan(`${event.type}.after.${hook.name}`), Effect.catchCause((cause) => hooks.afterFailure === "defect"
+    ? Effect.die(Cause.squash(cause))
+    : Effect.logError(`${event.type}.after.${hook.name} failed`, cause))), { concurrency: 1, discard: true });
+// ── The factory ───────────────────────────────────────────────────────
+/**
+ * A key's column when it is an object with a string `column`, else `""`.
+ * Typed as the request types it, but read as a caller may really send it.
+ */
+const columnOf = (key) => Predicate.isObject(key) && Predicate.isString(key.column) ? key.column : "";
+/**
+ * A list request's order as the store receives it: an array whose every key
+ * is an object with a sortable string `column` and a direction `asc` or
+ * `desc`, or {@link InvalidListOrder} for the first key that isn't (or for an
+ * `orderBy` that is no array), so no unsortable name reaches SQL and no
+ * out-of-type input dies. A repeated column is dropped (its first key
+ * already ordered every tie it could), which bounds the keys by the view's
+ * columns; each key is rebuilt, so nothing but `column` and `direction`
+ * reaches the store.
+ */
+const checkedOrder = (type, isSortable, keys) => {
+    // The request's types are not checked at runtime: a decoded query or an
+    // untyped caller can send any value here, so every guard reads it as such.
+    const isKey = (key) => Predicate.isObject(key) &&
+        Predicate.isString(key.column) &&
+        isSortable(key.column) &&
+        (key.direction === "asc" || key.direction === "desc");
+    // A boolean, not a guard: narrowing a typed array to `Array<unknown>` would lose its keys' type.
+    const isList = (value) => Array.isArray(value);
+    if (!isList(keys))
+        return Effect.fail(new InvalidListOrder({ type, column: columnOf(keys) }));
+    return Option.match(Array.findFirst(keys, (key) => !isKey(key)), {
+        onNone: () => Effect.succeed(Array.map(Array.dedupeWith(keys, (self, that) => self.column === that.column), ({ column, direction }) => ({ column, direction }))),
+        onSome: (key) => Effect.fail(new InvalidListOrder({ type, column: columnOf(key) })),
+    });
+};
+/**
+ * The leaf's sortable-column test, its `sortable` allow-list checked against
+ * the view's columns once, when the leaf is declared: an entry outside them
+ * throws {@link SubtypeDeclarationError}. Without an allow-list, every
+ * declared view column is sortable.
+ */
+const sortableColumns = (type, columns, 
+// oxlint-disable-next-line effect/prefer-option-over-null -- `SubtypeDefinition.sortable` as declared, an optional `?: T | undefined` field (AGENTS.md → Conventions)
+sortable) => {
+    if (sortable === undefined)
+        return (column) => columns.has(column);
+    const undeclared = Array.findFirst(sortable, (column) => !columns.has(column));
+    if (Option.isSome(undeclared)) {
+        throw new SubtypeDeclarationError({
+            message: `${type}: sortable names '${undeclared.value}', which is not a column of the view`,
+        });
+    }
+    return (column) => Array.contains(sortable, column);
+};
+/**
+ * Bind a leaf's operations. Every produced operation is traced as
+ * `${type}.<operation>`; the write operations run in the caller's
+ * transaction (the boundary is the handler seam's, website #1883).
+ *
+ * Throws {@link SubtypeDeclarationError}, when the leaf is declared, for a
+ * `sortable` entry that is not a column of the view.
+ *
+ * @since 0.1.0
+ */
+export const defineSubtype = (definition) => {
+    const { type, access, leaves, policy, followers, toResource } = definition;
+    const hooks = definition.hooks ?? Effect.succeed(noHooks());
+    // The history reads run no hook, so they read through a chain bound without one.
+    const history = defineVersionChain(type, definition.chain);
+    // Bound only for a leaf that declares hooks, so a leaf without them reads nothing extra.
+    const chain = defineVersionChain(type, definition.chain, definition.hooks === undefined
+        ? {}
+        : {
+            beforeAppend: (event) => Effect.flatMap(hooks, ({ before }) => Array.isReadonlyArrayNonEmpty(before)
+                ? Effect.flatMap(definition.viewer, (viewer) => runBefore(before, { ...event, type, viewer }))
+                : Effect.succeed(event.patch)),
+            beforeAppendLocales: (event) => Effect.flatMap(hooks, ({ before }) => Array.isReadonlyArrayNonEmpty(before)
+                ? Effect.flatMap(definition.viewer, (viewer) => runBeforeLocales(before, { ...event, type, viewer }))
+                : Effect.succeed(event.locales ?? {})),
+        });
+    const actor = (account) => Option.some(account.id);
+    // The view's column set is fixed at bind time, so the owned leaf's
+    // declared-column check is answered once, not per row.
+    const ownedColumnsDeclared = access.kind === "owned" && declaresColumns(access, leaves.columns);
+    // Checked here, so a misspelt `sortable` entry throws when the leaf is declared.
+    const isSortable = sortableColumns(type, leaves.columns, definition.sortable);
+    // Checked here too, so a projection naming a column the view lacks throws when the leaf is declared.
+    if (definition.search !== undefined)
+        checkSearchProjection(definition.search, leaves.columns);
+    // And the locale level, so a translated column the view lacks throws at declaration.
+    const localeLevel = Option.fromUndefinedOr(definition.locales);
+    if (Option.isSome(localeLevel)) {
+        checkLocaleLevel(localeLevel.value, leaves.columns, [
+            ...accessColumns(access),
+            ...(definition.publication === undefined ? [] : PUBLICATION_COLUMNS),
+        ]);
+    }
+    /**
+     * The write's locale level checked against the declaration (pulpit#56):
+     * shared columns in `state`, translated ones per locale, every locale tag
+     * non-empty; a leaf with none takes no locale. Runs after the gate.
+     */
+    const lockedLocales = (id, action, state, locales) => Option.match(localeViolation(Option.map(localeLevel, (level) => level.columns), state, locales), {
+        onNone: () => Effect.void,
+        onSome: (reason) => Effect.fail(new WriteRejected({ type, id, action, reason })),
+    });
+    /**
+     * The row's own visibility, by access kind; the soft-delete axis is checked
+     * by the caller. It fails closed exactly where the list filter does, so
+     * `get` / `getMany` never serve a row `list` hides (SEC-AUTH-ENUM-001): an
+     * owned leaf whose view lacks a declared column shows no row, as
+     * `ownedListFilter` lists none; a reference row shows only when the view
+     * has no `visibility` column, the viewer holds the view-private rung, its
+     * visibility is exactly `public`, or it is exactly `followers` and the
+     * viewer is, or follows, the account its declared `followersOfColumn` names, as
+     * `referencePrivacyFilter` lists (pulpit#92). The reference arm is one
+     * shared predicate with `./edges`' `canViewEndpoint`.
+     */
+    const rowVisible = (viewer, row) => {
+        if (access.kind === "reference") {
+            return canViewReferenceRow(access, leaves.columns, viewer, policy, followers, row);
+        }
+        return ownedColumnsDeclared
+            ? canViewOwnedRow(viewer, policy, followers, ownedFacts(access, row))
+            : Effect.succeed(false);
+    };
+    const visible = (viewer, row) => row.action === "delete" && !Option.exists(viewer, policy.canViewDeleted)
+        ? Effect.succeed(false)
+        : rowVisible(viewer, row);
+    const publication = Option.fromUndefinedOr(definition.publication);
+    /** Whether the viewer's rung reads every head: the view-private rung, or a reference leaf's corpus writers. */
+    const readsHeadByRung = (viewer) => Option.exists(viewer, (account) => policy.canViewPrivate(account) ||
+        (access.kind === "reference" && policy.canWriteCorpus(account)));
+    /** Whether the viewer reads this node's head: by rung, or as its owner. */
+    const readsHeadOf = (viewer, head) => readsHeadByRung(viewer) ||
+        (access.kind === "owned" &&
+            Option.exists(viewer, (account) => Option.contains(ownedFacts(access, head).ownerId, account.id)));
+    /**
+     * The row the viewer reads for a node whose head is `head`: the head
+     * itself, or on a publish-gated leaf, for a viewer who doesn't read it,
+     * the live row (none without one).
+     */
+    const chosenRow = (viewer, head) => Option.match(publication, {
+        onNone: () => Effect.succeedSome(head),
+        onSome: ({ live }) => readsHeadOf(viewer, head) ? Effect.succeedSome(head) : live.get(head.id),
+    });
+    /**
+     * The row `get` serves the viewer: a missing or hidden row is the same
+     * {@link NodeNotFound} (SEC-AUTH-ENUM-001). `get` and the reference write
+     * gate both read through it, so they can never disagree (pulpit#101).
+     */
+    const visibleRow = (viewer, id) => Effect.gen(function* () {
+        const head = yield* leaves.get(id);
+        const row = Option.isSome(head) ? yield* chosenRow(viewer, head.value) : Option.none();
+        if (Option.isSome(row) && (yield* visible(viewer, row.value)))
+            return row.value;
+        return yield* new NodeNotFound({ type, id });
+    });
+    /** Whether this request holds a preview grant for `id` (a publish-gated leaf's alone). */
+    const previewing = (id) => Option.match(Option.flatMapNullishOr(publication, (declared) => declared.preview), {
+        onNone: () => Effect.succeed(false),
+        onSome: (grant) => Effect.map(grant, (granted) => Option.contains(granted, id)),
+    });
+    /**
+     * The gate for a write or history read to an existing row. On a reference
+     * leaf, the corpus-write rung and then the read rung the row demands: a
+     * corpus writer who can't `get` the row learns `NodeNotFound`, exactly as
+     * from `get`, before any content is read or written (pulpit#101,
+     * `PUB-009`). The rung check runs first and reads no row, so a caller below
+     * it gets `Unauthorized` / `Forbidden` for every id alike. An owned leaf's
+     * gate is unchanged (pulpit#24).
+     */
+    const writer = (viewer, id) => Effect.tap(requireWriter(access, viewer, policy, { type, id }, leaves.ownerOf(id)), () => access.kind === "reference" ? Effect.asVoid(visibleRow(viewer, id)) : Effect.void);
+    const create = Effect.fn(`${type}.create`)(function* (input) {
+        const account = yield* requireCreator(access, yield* definition.viewer, policy);
+        yield* lockedLocales(Option.getOrElse(input.id, () => ""), "create", input.state, input.locales ?? {});
+        const written = yield* chain.create({ ...input, actorId: actor(account) });
+        if (access.kind === "owned")
+            yield* leaves.stampOwner(written.id, account.id);
+        return written;
+    });
+    const update = Effect.fn(`${type}.update`)(function* (input) {
+        const account = yield* writer(yield* definition.viewer, input.id);
+        yield* lockedLocales(input.id, "update", input.patch, input.locales ?? {});
+        return yield* chain.update({ ...input, actorId: actor(account) });
+    });
+    const restore = Effect.fn(`${type}.restore`)(function* (input) {
+        const account = yield* writer(yield* definition.viewer, input.id);
+        yield* lockedLocales(input.id, "restore", input.patch, input.locales ?? {});
+        return yield* chain.restore({ ...input, actorId: actor(account) });
+    });
+    const softDelete = Effect.fn(`${type}.delete`)(function* (id, precondition = {}) {
+        const account = yield* writer(yield* definition.viewer, id);
+        return yield* chain.delete(id, actor(account), precondition);
+    });
+    const get = Effect.fn(`${type}.get`)(function* (id) {
+        // A preview grant serves exactly its node's head, unless tombstoned.
+        if (yield* previewing(id)) {
+            const head = yield* leaves.get(id);
+            if (Option.isSome(head) && head.value.action !== "delete")
+                return toResource(head.value);
+        }
+        // Hidden and missing are the same answer (SEC-AUTH-ENUM-001).
+        return toResource(yield* visibleRow(yield* definition.viewer, id));
+    });
+    const owners = Effect.fn(`${type}.owners`)(function* (request) {
+        if (access.kind !== "owned")
+            return { rows: [], total: 0 };
+        const viewer = yield* definition.viewer;
+        const among = request.among === undefined ? always : anyOf(access.ownerColumn, request.among);
+        const query = {
+            column: access.ownerColumn,
+            where: searchScopeFilter({ access, columns: leaves.columns, policy, followers }, viewer, {
+                includeDeleted: request.includeDeleted,
+                where: among,
+            }),
+            limit: Math.max(1, Math.min(Math.trunc(request.limit), MAX_PAGE_LIMIT)),
+            offset: Math.max(0, Math.trunc(request.offset)),
+        };
+        // The same choice `list` makes: the head by rung, else live rows and the viewer's own heads.
+        return yield* Option.match(publication, {
+            onNone: () => leaves.distinct(query),
+            onSome: ({ live }) => readsHeadByRung(viewer)
+                ? leaves.distinct(query)
+                : live.distinct({ ...query, headFor: ownHeads(viewer) }),
+        });
+    });
+    const getLocalised = Effect.fn(`${type}.getLocalised`)(function* (id, locales) {
+        const viewer = yield* definition.viewer;
+        // The node's own gate, exactly as `get` runs it: a preview grant reads
+        // its node's head unless tombstoned, anyone else the row `get` serves.
+        const preview = (yield* previewing(id))
+            ? Option.filter(yield* leaves.get(id), (head) => head.action !== "delete")
+            : Option.none();
+        const shown = Option.isSome(preview) ? preview.value : yield* visibleRow(viewer, id);
+        if (Option.isNone(localeLevel))
+            return yield* new NodeNotFound({ type, id });
+        // One read of the requested locales' rows, from the version the gate chose.
+        const wanted = Array.dedupe(locales);
+        const query = {
+            where: and(eq("id", id), localeIn(wanted)),
+            orderBy: [],
+            limit: Math.max(1, Math.min(wanted.length, MAX_PAGE_LIMIT)),
+            offset: 0,
+        };
+        const page = yield* Option.match(publication, {
+            onNone: () => leaves.list(query),
+            onSome: ({ live }) => Option.isSome(preview) || readsHeadOf(viewer, shown)
+                ? leaves.list(query)
+                : live.list({ ...query, headFor: never }),
+        });
+        // Defence in depth: each locale row passes the node's read gate itself,
+        // so a store that joined a locale row onto other access facts serves none.
+        const readable = Option.isSome(preview)
+            ? page.rows
+            : yield* Effect.filter(page.rows, (row) => visible(viewer, row));
+        const found = Array.findFirst(wanted, (tag) => Array.findFirst(readable, (row) => row[LOCALE_COLUMN] === tag).pipe(Option.map((row) => ({
+            locale: tag,
+            resource: toResource(row),
+        }))));
+        if (Option.isNone(found))
+            return yield* new NodeNotFound({ type, id });
+        return found.value;
+    });
+    /** The rows a viewer reads for these heads: the heads they read, and one live read for the rest. */
+    const chosenRows = (viewer, heads) => Option.match(publication, {
+        onNone: () => Effect.succeed(heads),
+        onSome: ({ live }) => {
+            const own = Array.filter(heads, (head) => readsHeadOf(viewer, head));
+            const others = Array.filter(heads, (head) => !readsHeadOf(viewer, head));
+            return Array.isReadonlyArrayNonEmpty(others)
+                ? Effect.map(live.getMany(Array.map(others, (head) => head.id)), (lives) => [...own, ...lives])
+                : Effect.succeed(own);
+        },
+    });
+    const getMany = Effect.fn(`${type}.getMany`)(function* (ids) {
+        if (!Array.isReadonlyArrayNonEmpty(ids))
+            return HashMap.empty();
+        const viewer = yield* definition.viewer;
+        const rows = yield* chosenRows(viewer, yield* leaves.getMany(Array.dedupe(ids)));
+        const shown = yield* Effect.filter(rows, (row) => visible(viewer, row));
+        return HashMap.fromIterable(Array.map(shown, (row) => [row.id, toResource(row)]));
+    });
+    /** The heads a viewer below the head-reading rungs reads: their own, on an owned leaf. */
+    const ownHeads = (viewer) => access.kind === "owned"
+        ? Option.match(viewer, {
+            onNone: () => never,
+            onSome: (account) => eq(access.ownerColumn, account.id),
+        })
+        : never;
+    const list = Effect.fn(`${type}.list`)(function* (request) {
+        const orderBy = yield* checkedOrder(type, isSortable, request.orderBy ?? []);
+        const viewer = yield* definition.viewer;
+        const where = searchScopeFilter({ access, columns: leaves.columns, policy, followers }, viewer, request);
+        const query = {
+            where,
+            orderBy,
+            limit: Math.max(1, Math.min(Math.trunc(request.limit), MAX_PAGE_LIMIT)),
+            offset: Math.max(0, Math.trunc(request.offset)),
+        };
+        // On a publish-gated leaf, a viewer below the head-reading rungs lists
+        // live rows, and their own rows at the head, as `get` reads them.
+        const page = yield* Option.match(publication, {
+            onNone: () => leaves.list(query),
+            onSome: ({ live }) => readsHeadByRung(viewer)
+                ? leaves.list(query)
+                : live.list({ ...query, headFor: ownHeads(viewer) }),
+        });
+        return { rows: page.rows.map(toResource), total: page.total };
+    });
+    /**
+     * A history read (`READ-009`): the viewer's {@link writer} gate on `id`,
+     * then `read`. `getVersion` and `compare` both run through it, so their
+     * gate is one code path and `read` never runs for a caller it refuses.
+     */
+    const historyRead = (id, read) => Effect.andThen(Effect.flatMap(definition.viewer, (viewer) => writer(viewer, id)), read);
+    const getVersion = Effect.fn(`${type}.getVersion`)(function* (id, version) {
+        return yield* historyRead(id, history.getVersion(id, version));
+    });
+    const compare = Effect.fn(`${type}.compare`)(function* (id, from, to) {
+        return yield* historyRead(id, history.compare(id, from, to));
+    });
+    const restoreVersion = Effect.fn(`${type}.restoreVersion`)(function* (id, version, precondition = {}) {
+        const account = yield* writer(yield* definition.viewer, id);
+        return yield* chain.restoreVersion(id, version, actor(account), precondition);
+    });
+    const publicResource = Effect.fn(`${type}.publicResource`)(function* (id) {
+        return yield* visibleRow(Option.none(), id).pipe(Effect.map((row) => Option.some(toResource(row))), Effect.catchTag("NodeNotFound", () => Effect.succeed(Option.none())));
+    });
+    const authorize = Effect.fn(`${type}.authorize`)(function* (id) {
+        return yield* writer(yield* definition.viewer, id);
+    });
+    /** A publication's before hooks: shown the head, an empty patch; the returned patch is ignored. */
+    const beforePublication = (action, id, viewer, account) => definition.hooks === undefined
+        ? Effect.void
+        : Effect.gen(function* () {
+            const { before } = yield* hooks;
+            if (!Array.isReadonlyArrayNonEmpty(before))
+                return;
+            const head = yield* definition.chain.head(id);
+            const prior = Option.isSome(head)
+                ? yield* definition.chain.snapshot(id, head.value.version)
+                : Option.none();
+            yield* runBefore(before, {
+                action,
+                id,
+                prior,
+                patch: {},
+                actorId: actor(account),
+                type,
+                viewer,
+            });
+        });
+    const publicationOps = Option.map(publication, ({ facts }) => ({
+        publish: Effect.fn(`${type}.publish`)(function* (id, options = {}) {
+            const viewer = yield* definition.viewer;
+            const account = yield* writer(viewer, id);
+            const head = yield* definition.chain.head(id);
+            if (Option.isNone(head) || head.value.action === "delete") {
+                return yield* new NodeNotFound({ type, id });
+            }
+            const version = options.version ?? head.value.version;
+            const snapshot = yield* definition.chain.snapshot(id, version);
+            if (Option.isNone(snapshot) || snapshot.value.action === "delete") {
+                return yield* new VersionNotFoundError({ type, id, version });
+            }
+            yield* beforePublication("publish", id, viewer, account);
+            const now = yield* nowDate;
+            const fact = {
+                id,
+                version: Option.some(version),
+                at: options.at ?? now,
+                actorId: actor(account),
+                recordedAt: now,
+            };
+            yield* facts.record(fact);
+            return { fact, head: head.value.version };
+        }),
+        unpublish: Effect.fn(`${type}.unpublish`)(function* (id) {
+            const viewer = yield* definition.viewer;
+            const account = yield* writer(viewer, id);
+            const head = yield* definition.chain.head(id);
+            if (Option.isNone(head))
+                return yield* new NodeNotFound({ type, id });
+            yield* beforePublication("unpublish", id, viewer, account);
+            const now = yield* nowDate;
+            const fact = {
+                id,
+                version: Option.none(),
+                at: now,
+                actorId: actor(account),
+                recordedAt: now,
+            };
+            yield* facts.record(fact);
+            return { fact, head: head.value.version };
+        }),
+        discardDraft: Effect.fn(`${type}.discardDraft`)(function* (id, precondition = {}) {
+            const account = yield* writer(yield* definition.viewer, id);
+            const live = Option.flatMap(yield* facts.effective(id), (fact) => fact.version);
+            if (Option.isNone(live))
+                return yield* new NotPublished({ type, id });
+            const head = yield* definition.chain.head(id);
+            if (Option.exists(head, (entry) => entry.version === live.value)) {
+                return { id, version: live.value };
+            }
+            return yield* chain.restoreVersion(id, live.value, actor(account), precondition);
+        }),
+        facts: Effect.fn(`${type}.publicationFacts`)(function* (id) {
+            return yield* historyRead(id, facts.facts(id, MAX_HISTORY_LIMIT));
+        }),
+    }));
+    return {
+        type,
+        access,
+        hooks,
+        publication: publicationOps,
+        publicResource,
+        authorize,
+        create,
+        update,
+        restore,
+        delete: softDelete,
+        get,
+        getLocalised,
+        owners,
+        getMany,
+        list,
+        getVersion,
+        compare,
+        restoreVersion,
+    };
+};
+const checkSearchProjection = (projection, columns) => {
+    const named = [
+        ...Array.map(projection.fields, (field) => field.column),
+        ...Option.toArray(projection.languageColumn),
+    ];
+    const undeclared = Array.findFirst(named, (column) => !columns.has(column));
+    if (Option.isSome(undeclared)) {
+        throw new SubtypeDeclarationError({
+            message: `search names '${undeclared.value}', which is not a column of the view`,
+        });
+    }
+};
+/**
+ * Declare a {@link SearchProjection}. Throws {@link SubtypeDeclarationError}
+ * at import, as a registry violation is, for no field, a column named twice
+ * or a weight outside `A`–`D`; {@link defineSubtype} checks the columns
+ * against the view.
+ *
+ * @example
+ * ```ts
+ * import { strictEqual } from "node:assert";
+ * import { defineSearchProjection } from "@thomasfosterau/pulpit/subtype";
+ *
+ * const posts = defineSearchProjection({
+ *   fields: [
+ *     { column: "title", weight: "A" },
+ *     { column: "excerpt", weight: "B" },
+ *   ],
+ *   languageColumn: "language",
+ * });
+ * strictEqual(posts.fields.length, 2);
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const defineSearchProjection = (declaration) => {
+    if (!Array.isReadonlyArrayNonEmpty(declaration.fields)) {
+        throw new SubtypeDeclarationError({ message: "search declares no field" });
+    }
+    const repeated = Array.findFirst(declaration.fields, (field, index) => declaration.fields.slice(0, index).some((earlier) => earlier.column === field.column));
+    if (Option.isSome(repeated)) {
+        throw new SubtypeDeclarationError({
+            message: `search names '${repeated.value.column}' twice`,
+        });
+    }
+    const unweighted = Array.findFirst(declaration.fields, (field) => !Array.contains(["A", "B", "C", "D"], field.weight));
+    if (Option.isSome(unweighted)) {
+        throw new SubtypeDeclarationError({
+            message: `search weighs '${unweighted.value.column}' outside A–D`,
+        });
+    }
+    return {
+        fields: declaration.fields,
+        languageColumn: Option.fromNullishOr(declaration.languageColumn),
+    };
+};
+/**
+ * The read scope a search over one leaf must apply to its hits: exactly the
+ * filter {@link defineSubtype}'s `list` reads under (`list` calls this), the
+ * soft-delete arm, the access kind's privacy arm (owned visibility and draft
+ * through {@link ownedListFilter}; the reference privacy arm with its
+ * followers, `PUB-009`) and the family's own `where`, so a search can never
+ * surface a row `list` hides (`SEC-AUTH-ENUM-001`). The application renders
+ * it into its search query as the list store renders it into the list's. On
+ * a leaf with the live pointer ({@link SubtypeDefinition.publication}) the
+ * search matches over the rows {@link LiveView}'s `list` reads (the viewer's
+ * own at the head, every other node's live row), never every head, so a
+ * match never scores text a reader cannot see.
+ *
+ * @since 0.1.0
+ */
+export const searchScopeFilter = (leaf, viewer, request) => {
+    const { access, columns, policy, followers } = leaf;
+    const privacy = access.kind === "owned"
+        ? ownedListFilter(access, columns, readScopeFor(viewer, policy, followers))
+        : referencePrivacyFilter(viewer, policy, columns, Option.some({ access, followers }));
+    return and(softDeleteFilter(viewer, policy, request.includeDeleted), privacy, request.where);
+};
+/**
+ * Hydrate ranked search hits through the leaf's gated `getMany`: one read
+ * for every hit, each re-checked against the viewer by the same predicate
+ * `get` applies, so a stale or poisoned index (a hit the search scope should
+ * have excluded, or one hidden since it was indexed) never leaks a row
+ * (`SEC-AUTH-ENUM-001`). The hits keep their rank order, a hidden or
+ * missing one is dropped, and a repeated id keeps its first, best rank.
+ * Fails with the store's `E`.
+ *
+ * @since 0.1.0
+ */
+export const hydrateSearchHits = (ops, hits) => {
+    const ranked = Array.dedupeWith(hits, (a, b) => a.id === b.id);
+    return Effect.map(ops.getMany(Array.map(ranked, (hit) => hit.id)), (shown) => Array.flatMap(ranked, (hit) => Option.toArray(Option.map(HashMap.get(shown, hit.id), (resource) => ({ hit, resource })))));
+};
+/**
+ * The resource cache's write-through as an {@link AfterWriteHook}: a write
+ * whose writer re-read the resource sets it, and any other (a `delete`, or a
+ * write whose re-read failed or no longer shows the row) evicts it
+ * (`CACHE-AUTH-005`). {@link subtypeHandlers} runs it first, before the
+ * leaf's own after hooks, whenever its config has a cache. Never fails.
+ *
+ * @since 0.1.0
+ */
+export const cacheWriteThrough = (cache) => ({
+    name: "cache",
+    run: ({ write, resource }) => Option.match(resource, {
+        onNone: () => cache.delete(write.id, write.version),
+        onSome: (value) => cache.set(write.id, value, write.version),
+    }),
+});
+/**
+ * Wrap a leaf's operations as its handler record. An owned leaf may still
+ * be cached — `CACHE-AUTH-005` is enforced by the cache's serveability
+ * policy (`./publication`'s `isPubliclyServeable` with `owned: true`), which
+ * only ever holds its public rows, and by the handlers' own eviction when a
+ * committed write can't be re-read or written through (see
+ * {@link SubtypeHandlers}). Each write fails with its operation's error, or
+ * with the re-read's unless that is `NodeNotFound` (a write hidden from its
+ * writer, answered as a {@link CommittedWrite} with no resource).
+ *
+ * @since 0.1.0
+ */
+export const subtypeHandlers = (ops, config) => {
+    const evict = ({ id, version }) => Option.match(config.cache, {
+        onNone: () => Effect.void,
+        onSome: (cache) => cache.delete(id, version),
+    });
+    // A write runs under `uninterruptibleMask`: the chain write (inside
+    // `transact`) and the re-read stay interruptible through `restore`, but
+    // the step between them, and the cache step after, cannot be skipped by
+    // an interrupt, so a committed write always reaches its write-through or
+    // eviction (`CACHE-AUTH-005`). Once the operation itself has succeeded
+    // (its gate passed and the chain write ran), any later failure of the
+    // boundary, an interrupt included, evicts: the write may have committed.
+    // A request the gate refused never evicts, so a forbidden request can't
+    // bust the cache. The flag is cleared at the start of each attempt, so a
+    // `transact` that retries internally, rolling back an attempt that wrote,
+    // evicts only when its last attempt wrote.
+    const committed = (restore, operation) => Effect.flatMap(Ref.make(Option.none()), (wrote) => restore(config.transact(Effect.andThen(Ref.set(wrote, Option.none()), Effect.tap(operation, ({ id, version }) => Ref.set(wrote, Option.some({ id, version })))))).pipe(Effect.onError(() => Effect.flatMap(Ref.get(wrote), Option.match({ onNone: () => Effect.void, onSome: evict })))));
+    /**
+     * The cache write-through. On a publish-gated leaf the writer's re-read
+     * is the head, which must never reach a public cache, so the cache is
+     * given the resource as an anonymous reader gets it (the live version),
+     * or evicts (`CACHE-AUTH-005`).
+     */
+    const cacheHook = (cache) => Option.isNone(ops.publication)
+        ? cacheWriteThrough(cache)
+        : {
+            name: "cache",
+            run: (event) => ops.publicResource(event.write.id).pipe(Effect.flatMap((resource) => cacheWriteThrough(cache).run({ ...event, resource })), Effect.catchCause(() => cache.delete(event.write.id, event.write.version))),
+        };
+    /**
+     * The cache step inside an outer transaction: the write hasn't committed,
+     * so evict at its version and cache nothing (pulpit#124).
+     */
+    const evictHook = (cache) => ({
+        name: "cache",
+        run: ({ write }) => cache.delete(write.id, write.version),
+    });
+    /**
+     * The after hooks for one write whose `transact` has returned: the cache
+     * step first (when the leaf has a cache; a write-through, or an eviction
+     * inside an outer transaction), then the leaf's own, in order.
+     */
+    const after = (event) => Effect.flatMap(Effect.zip(ops.hooks, config.inTransaction), ([hooks, nested]) => runAfter({
+        ...hooks,
+        after: [
+            ...Option.toArray(Option.map(config.cache, nested ? evictHook : cacheHook)),
+            ...hooks.after,
+        ],
+    }, event));
+    /**
+     * A publication fact, recorded in `transact`, then the after hooks with
+     * the resource as the writer now reads it.
+     */
+    const published = (action, operation) => Effect.uninterruptibleMask((restore) => Effect.tap(restore(config.transact(operation)), ({ fact, head }) => Effect.flatMap(Effect.option(restore(ops.get(fact.id))), (resource) => after({
+        type: ops.type,
+        action,
+        write: { id: fact.id, version: head },
+        resource,
+        publication: Option.some(fact),
+    }))));
+    // The re-read runs as the writer, after the write committed, and its
+    // outcome is the after hooks' `resource`. When it fails (the write hid
+    // the row from its own writer: a corpus writer below the view-private
+    // rung making a reference row `private`; a store error; an interrupt),
+    // the resource is none and the cache hook evicts: the cache must never go
+    // on serving the superseded resource, whatever the writer may read now
+    // (`CACHE-AUTH-005`, pulpit#107). A `NodeNotFound` re-read is a write
+    // hidden from its writer: it answers the committed write with no resource,
+    // not a 404 for a write that committed. Any other failure fails the
+    // handler with the re-read's own cause.
+    const write = (action, operation) => Effect.uninterruptibleMask((restore) => Effect.flatMap(committed(restore, operation), (written) => Effect.flatMap(Effect.exit(restore(ops.get(written.id))), (reread) => Effect.andThen(after({
+        type: ops.type,
+        action,
+        write: { id: written.id, version: written.version },
+        resource: Exit.isSuccess(reread) ? Option.some(reread.value) : Option.none(),
+        publication: Option.none(),
+    }), reread.pipe(Effect.map(Option.some), Effect.catchTag("NodeNotFound", () => Effect.succeedNone), Effect.map((resource) => ({
+        id: written.id,
+        version: written.version,
+        resource,
+    })))))));
+    return {
+        list: ops.list,
+        get: ops.get,
+        create: (input) => write("create", ops.create(input)),
+        update: (input) => write("update", ops.update(input)),
+        restore: (input) => write("restore", ops.restore(input)),
+        // An already tombstoned node wrote nothing, so it emits nothing; its
+        // cache entry is still evicted, as every delete's is.
+        delete: (id, precondition) => Effect.uninterruptibleMask((restore) => Effect.flatMap(committed(restore, ops.delete(id, precondition)), (written) => written.alreadyDeleted
+            ? evict(written)
+            : after({
+                type: ops.type,
+                action: "delete",
+                write: { id: written.id, version: written.version },
+                resource: Option.none(),
+                publication: Option.none(),
+            }))),
+        restoreVersion: (input) => write("restoreVersion", ops.restoreVersion(input.id, input.version, { expectedVersion: input.expectedVersion })),
+        publication: Option.map(ops.publication, (publication) => ({
+            publish: (id, options) => published("publish", publication.publish(id, options)),
+            unpublish: (id) => published("unpublish", publication.unpublish(id)),
+            discardDraft: (id, precondition) => Effect.uninterruptibleMask((restore) => Effect.tap(committed(restore, publication.discardDraft(id, precondition)), (written) => Effect.flatMap(Effect.option(restore(ops.get(written.id))), (resource) => after({
+                type: ops.type,
+                action: "restoreVersion",
+                write: written,
+                resource,
+                publication: Option.none(),
+            })))),
+            facts: publication.facts,
+        })),
+    };
+};
+/**
+ * A leaf's {@link SubtypeHandlers} as effect-jsonapi's CRUD handlers
+ * (`ResourceHandlers.make`), keyed by the endpoint names `Group.flat`
+ * declares (pulpit#5). Each write goes through the record, so it keeps the
+ * record's `transact` boundary, writer re-read, lifecycle hooks and cache
+ * write-through (`CACHE-AUTH-005`); effect-jsonapi is given no `cache` and no
+ * `transact` of its own, and its mutation tail re-reads the row once more
+ * with `get` to assemble the document. `list` answers the page with the
+ * unpaged total, and `delete` the 204. `restore` and `restoreVersion` have no
+ * JSON:API endpoint and stay on the record. The handlers fail with the
+ * record's errors (and effect-jsonapi's `Conflict` for an `update` whose
+ * payload id is not the route's, before any operation runs); mapping them to
+ * the wire is the application's `ServerErrors`.
+ *
+ * A `create` / `update` whose committed write hides the row from its writer
+ * (the re-read fails `NodeNotFound`) answers effect-jsonapi's committed
+ * identifier document, `{ data: { type, id, meta: { version } } }` at the
+ * endpoint's own status, not a 404 (effect-jsonapi's `hiddenWrite`,
+ * pulpit#107). Declare the group with `Group.flat({ …, hiddenWrites: true })`
+ * so its `create` / `update` success admits that document.
+ *
+ * @since 0.1.0
+ */
+export const subtypeResourceHandlers = (handlers, config) => {
+    const { type, listRequest, createInput, updateInput, ...rest } = config;
+    return ResourceHandlers.make({
+        ...rest,
+        hiddenWrite: { type, when: (error) => Predicate.isTagged(error, "NodeNotFound") },
+        ops: {
+            list: (query) => Effect.map(handlers.list(listRequest(query)), (page) => ({
+                items: page.rows,
+                totalCount: page.total,
+            })),
+            get: handlers.get,
+            // The committed version rides along: a write hidden from its writer
+            // answers it as `data.meta.version` (pulpit#107).
+            create: (payload) => Effect.map(handlers.create(createInput(payload)), ({ id, version }) => ({ id, version })),
+            update: (payload) => Effect.map(handlers.update(updateInput(payload)), ({ id, version }) => ({ id, version })),
+            delete: (id) => handlers.delete(id),
+        },
+    });
+};
+/** The names a view keeps for itself: no translated column may take one. */
+const RESERVED_COLUMNS = HashSet.make("id", "version", "action", LOCALE_COLUMN);
+/**
+ * The columns a leaf's read gate reads (pulpit#56): none of them may be
+ * translated, so every locale row carries the node's one owner, visibility,
+ * draft and moderation state.
+ */
+const accessColumns = (access) => access.kind === "owned"
+    ? [
+        access.ownerColumn,
+        access.visibilityColumn,
+        ...Option.toArray(access.draftColumn),
+        ...Option.toArray(access.moderationColumn),
+    ]
+    : ["visibility", ...(access.followersOfColumn === undefined ? [] : [access.followersOfColumn])];
+/** The columns a live view stamps on a publish-gated leaf's rows. */
+const PUBLICATION_COLUMNS = ["draft", "publishedAt"];
+const checkLocaleLevel = (level, columns, gated) => {
+    const gate = Array.findFirst(level.columns, (column) => gated.includes(column));
+    if (Option.isSome(gate)) {
+        throw new SubtypeDeclarationError({
+            message: `locales names '${gate.value}', which the read gate reads: it must be shared`,
+        });
+    }
+    const undeclared = Array.findFirst([...level.columns, LOCALE_COLUMN], (column) => !columns.has(column));
+    if (Option.isSome(undeclared)) {
+        throw new SubtypeDeclarationError({
+            message: `locales names '${undeclared.value}', which is not a column of the view`,
+        });
+    }
+};
+/** The keys of a patch that set or clear a value (an `undefined` key carries forward). */
+const writtenKeys = (patch) => Array.filter(Record.keys(patch), (key) => patch[key] !== undefined);
+/**
+ * Why a write breaks the locale level, or none: `translated` is the leaf's
+ * declared columns (none for a leaf with no locale level).
+ */
+const localeViolation = (translated, state, locales) => {
+    const tags = writtenKeys(locales);
+    if (Option.isNone(translated)) {
+        return Array.isReadonlyArrayNonEmpty(tags)
+            ? Option.some("the leaf declares no locale level")
+            : Option.none();
+    }
+    const isTranslated = (column) => translated.value.includes(column);
+    const shared = Array.findFirst(writtenKeys(state), isTranslated);
+    if (Option.isSome(shared)) {
+        return Option.some(`'${shared.value}' is translated: write it per locale`);
+    }
+    if (tags.some(Str.isEmpty))
+        return Option.some("a locale tag is empty");
+    return Array.findFirst(tags, (tag) => Option.fromNullishOr(locales[tag]).pipe(Option.flatMap((change) => Array.findFirst(writtenKeys(change), (column) => !isTranslated(column))), Option.map((column) => `locale '${tag}' names '${column}', a shared column: write it once, for every locale`)));
+};
+/**
+ * Declare a {@link LocaleLevel}. Throws {@link SubtypeDeclarationError} at
+ * import, as a registry violation is, for no column, a column named twice or
+ * one the view keeps for itself (`id`, `version`, `action`,
+ * {@link LOCALE_COLUMN}); {@link defineSubtype} checks the columns against
+ * the view.
+ *
+ * @example
+ * ```ts
+ * import { deepStrictEqual } from "node:assert";
+ * import { defineLocaleLevel } from "@thomasfosterau/pulpit/subtype";
+ *
+ * const pages = defineLocaleLevel({ columns: ["title", "body", "slug"] });
+ * deepStrictEqual(pages.columns, ["title", "body", "slug"]);
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const defineLocaleLevel = (declaration) => {
+    if (!Array.isReadonlyArrayNonEmpty(declaration.columns)) {
+        throw new SubtypeDeclarationError({ message: "locales declares no column" });
+    }
+    const repeated = Array.findFirst(declaration.columns, (column, index) => declaration.columns.slice(0, index).includes(column));
+    if (Option.isSome(repeated)) {
+        throw new SubtypeDeclarationError({ message: `locales names '${repeated.value}' twice` });
+    }
+    const reserved = Array.findFirst(declaration.columns, (column) => HashSet.has(RESERVED_COLUMNS, column));
+    if (Option.isSome(reserved)) {
+        throw new SubtypeDeclarationError({
+            message: `locales names '${reserved.value}', which the view keeps for itself`,
+        });
+    }
+    return { columns: [...declaration.columns] };
+};
+// ── Owners across leaves ──────────────────────────────────────────────
+/**
+ * {@link readableOwners} refused a union it could not make exact: a leaf
+ * has more readable owners than one read returns ({@link MAX_PAGE_LIMIT}),
+ * so the union and its total would be short (`SEC-INPUT-003`).
+ *
+ * @since 0.1.0
+ */
+export class OwnerSetTooLarge extends Schema.TaggedError()("OwnerSetTooLarge", {
+    type: Schema.String,
+}) {
+}
+/**
+ * The accounts that own at least one row the viewer may list in any of
+ * `leaves` (pulpit#186): the union of each leaf's
+ * {@link SubtypeOps.owners}, deduplicated in code-point order, paged by
+ * `request`, with the exact union size as `total`. One read per leaf, each
+ * for every owner it has (up to {@link MAX_PAGE_LIMIT}): a leaf with more
+ * fails {@link OwnerSetTooLarge} rather than answer a short union. With
+ * `among` (at most `MAX_SET_VALUES` ids) no leaf can exceed it. A hidden row
+ * never contributes its owner (`SEC-AUTH-ENUM-001`). Fails otherwise only
+ * with the stores' `E`.
+ *
+ * @example
+ * ```ts
+ * import { deepStrictEqual } from "node:assert";
+ * import * as Effect from "effect/Effect";
+ * import { readableOwners } from "@thomasfosterau/pulpit/subtype";
+ *
+ * const leaf = (type: string, owners: ReadonlyArray<string>) => ({
+ *   type,
+ *   owners: () => Effect.succeed({ rows: owners, total: owners.length }),
+ * });
+ * const page = Effect.runSync(
+ *   readableOwners([leaf("posts", ["ana", "bo"]), leaf("pages", ["bo", "cy"])], {
+ *     limit: 10,
+ *     offset: 0,
+ *     includeDeleted: false,
+ *   }),
+ * );
+ * deepStrictEqual(page, { rows: ["ana", "bo", "cy"], total: 3 });
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const readableOwners = (leaves, request) => Effect.gen(function* () {
+    const every = { ...request, limit: MAX_PAGE_LIMIT, offset: 0 };
+    const pages = yield* Effect.forEach(leaves, (leaf) => Effect.flatMap(leaf.owners(every), (page) => page.total > page.rows.length
+        ? Effect.fail(new OwnerSetTooLarge({ type: leaf.type }))
+        : Effect.succeed(page.rows)), { concurrency: 1 });
+    const union = Arr.sort(Array.dedupe(Array.flatten(pages)), byCodePoint);
+    const limit = Math.max(1, Math.min(Math.trunc(request.limit), MAX_PAGE_LIMIT));
+    const offset = Math.max(0, Math.trunc(request.offset));
+    return { rows: union.slice(offset, offset + limit), total: union.length };
+});
+//# sourceMappingURL=subtype.js.map