@jini-ai/admin 0.4.2 → 0.4.4

package/dist/comments/rules.js

@@ -0,0 +1,199 @@
+import { describeApiError } from '../core/transport/errors.js';
+import { hasPermission } from '../core/permissions/rules.js';
+import { englishComments } from './messages.en.js';
+/** Host transports retain their error class; status/body are the shared wire contract. */
+function isCommentsConflict({ e }) {
+    return e instanceof Error && 'status' in e && e.status === 409;
+}
+/**
+ * @file Pure logic for the `comments` feature — everything that computes a value rather than
+ * rendering one. Follows the `posts/rules.ts` convention: no React import, no hooks, directly
+ * testable.
+ *
+ * Moved here from `react/pages/CommentsPage.tsx`: `RowActionState`/`emptyRowState` and `describeModerationError`/
+ * `truncate` (already module-scope free functions in the original, just not exported), the
+ * moderation-queue row-menu item builder (a permission-and-status branch per action), and the
+ * Comments-settings patch builder plus its validation (REQ-08/09/10).
+ *
+ * `KEYS` (fetch-query migration, 2026-08-12): three independent resources this feature's three
+ * hooks each own — the operator's own effective permissions, the moderation queue (one cache
+ * identity PER status filter, `queue(status)`), and the settings form. `queueRoot` is the
+ * INVALIDATION target for a moderation action succeeding, not a read key of its own: a moderate/
+ * purge action always moves a comment to a DIFFERENT status than the one currently filtered, so the
+ * pre-migration `reloadFirstPage()` only ever refreshed the CURRENT filter's page — leaving a
+ * previously-visited OTHER status tab's cache stale (missing the comment) until the operator
+ * happened to force a reload. Invalidating the shared `["comments","queue"]` prefix instead
+ * refreshes every status tab's cache at once (matching by prefix — see `@jini-ai/ui/fetch-query`'s
+ * `QueryKey` doc), closing that gap; see `react/hooks/use-comment-queue.hooks.ts`'s own doc comment.
+ */
+export const KEYS = {
+    permissions: ["comments", "permissions"],
+    queueRoot: ["comments", "queue"],
+    queue: (status) => ["comments", "queue", status],
+    settings: ["comments", "settings"],
+};
+/** The moderation queue's name on `lib/content-refresh-bus.ts` — see `taxonomy/rules.ts`'s
+ *  `TAXONOMY_RESOURCE` for why this is a plain colocated constant rather than a shared registry.
+ *  Agent-writable via `comments_approve_comment`/`comments_mark_comment_spam`/
+ *  `comments_trash_comment`/`comments_restore_comment` (`apps/website/src/features/comments/
+ *  agent-tools.ts`), all of which move a comment between statuses this queue lists.
+ *
+ *  There is deliberately NO sibling `COMMENTS_SETTINGS_RESOURCE`: `react/hooks/use-comment-settings.hooks.ts`'s
+ *  own header records a real, already-fixed lost-update bug (TM-TOVU-2026-08-12-A) whose fix is a
+ *  ONE-SHOT seed guard that refuses to re-seed `settings` from any later successful load, including
+ *  this bus's own out-of-band notification. Wiring that hook to the bus would either do nothing
+ *  (the guard blocks it) or, if the guard were bypassed instead, reintroduce the exact silent
+ *  revert the guard exists to prevent — so `comments_update_settings` stays unwired to this bus on
+ *  purpose. See that hook's own file header for the full incident record. */
+export const COMMENTS_QUEUE_RESOURCE = "comments-queue";
+export function emptyRowState(_required = {}, _optional = {}) {
+    return { busy: false, error: null };
+}
+/** REQ-07: a 409 (stale `expectedVersion`) gets its own message instead of the generic fallback,
+ * using the route's own `{error, currentVersion}` body when present. */
+export function describeModerationError({ e }, { t = englishComments } = {}) {
+    if (isCommentsConflict({ e })) {
+        const currentVersion = typeof e.body?.currentVersion === "number" ? e.body.currentVersion : undefined;
+        if (currentVersion !== undefined) {
+            return t("This comment changed since you loaded it (current version {currentVersion}) — refresh and try again.").replace("{currentVersion}", String(currentVersion));
+        }
+        return t("This comment changed since you loaded it — refresh and try again.");
+    }
+    return describeApiError({ e, fallback: t("Failed to update comment.") });
+}
+export function truncate({ text, max }, _optional = {}) {
+    return text.length > max ? `${text.slice(0, max)}…` : text;
+}
+function approveItem(comment, perms, handlers, t) {
+    if (comment.status === "approved" || !perms.canModerate)
+        return null;
+    return { key: "approve", label: t("Approve"), onSelect: () => handlers.onModerate(comment, "approve") };
+}
+function spamItem(comment, perms, handlers, t) {
+    if (comment.status === "spam" || !perms.canModerate)
+        return null;
+    return { key: "spam", label: t("Spam"), onSelect: () => handlers.onModerate(comment, "spam") };
+}
+function trashItem(comment, perms, handlers, t) {
+    if (comment.status === "trash" || !perms.canDelete)
+        return null;
+    return { key: "trash", label: t("Trash"), onSelect: () => handlers.onModerate(comment, "trash") };
+}
+function restoreItem(comment, perms, handlers, t) {
+    const isRestorable = comment.status === "spam" || comment.status === "trash";
+    if (!isRestorable || !perms.canModerate)
+        return null;
+    return { key: "restore", label: t("Restore"), onSelect: () => handlers.onModerate(comment, "restore") };
+}
+/** REQ-06: purge only ever surfaces from the trash filter view (`currentFilterStatus === "trash"`),
+ *  not merely a trashed comment reached under a different filter. Genuinely destructive (its own
+ *  confirm copy: "cannot be undone") — `destructive: true`, unlike the reversible actions above. */
+function purgeItem(comment, currentFilterStatus, perms, handlers, t) {
+    const inTrashFilter = currentFilterStatus === "trash" && comment.status === "trash";
+    if (!inTrashFilter || !perms.canForceDelete)
+        return null;
+    return { key: "purge", label: t("Purge"), destructive: true, onSelect: () => handlers.onRequestPurge(comment) };
+}
+/** At-rest row actions for `RowMenu` — every condition here is copied verbatim from the inline
+ *  buttons this replaces, so a permission/status combination that used to hide a button still
+ *  omits the matching menu item rather than rendering a guaranteed-failing click. Each candidate
+ *  item is its own single-condition pure function above; this just resolves permissions once and
+ *  filters out the misses.
+ *
+ * @complexity Time: O(p) for three permission scans, p = effective grant count; output space is
+ * constant, with at most five menu entries. Permission ownership stays in the core helper.
+ */
+export function commentRowMenuItems({ comment, context, handlers }, { t = englishComments } = {}) {
+    const perms = {
+        canModerate: hasPermission({ permissions: context.permissions, permission: "comments.moderate" }),
+        canDelete: hasPermission({ permissions: context.permissions, permission: "comments.delete" }),
+        canForceDelete: hasPermission({ permissions: context.permissions, permission: "comments.delete.force" }),
+    };
+    const candidates = [
+        approveItem(comment, perms, handlers, t),
+        spamItem(comment, perms, handlers, t),
+        trashItem(comment, perms, handlers, t),
+        restoreItem(comment, perms, handlers, t),
+        purgeItem(comment, context.currentFilterStatus, perms, handlers, t),
+    ];
+    return candidates.filter((item) => item !== null);
+}
+/** A blank or non-numeric raw value means "no opinion" — the field is left out of the patch
+ *  rather than coerced to `0`/`NaN`. Shared by every numeric settings field except
+ *  `closeAfterDays`, whose blank case means something else (see {@link parseCloseAfterDays}). */
+export function parseOptionalNumber({ raw }, _optional = {}) {
+    if (raw === "")
+        return undefined;
+    const value = Number(raw);
+    return Number.isFinite(value) ? value : undefined;
+}
+/** REQ-10: blank means "never closes" -> `null` on the wire; the UI never sends the backend's own
+ *  `-1` sentinel, only `null` or a positive number. A non-numeric raw value is "no opinion"
+ *  (`undefined`), same as the other numeric fields. */
+export function parseCloseAfterDays({ raw }, _optional = {}) {
+    const trimmed = raw.trim();
+    if (trimmed === "")
+        return null;
+    const value = Number(trimmed);
+    return Number.isFinite(value) ? value : undefined;
+}
+function diffCheckboxField(form, key, current) {
+    const value = form.get(key) === "on";
+    return value !== current[key] ? { [key]: value } : undefined;
+}
+function diffNumberField(form, key, current) {
+    const value = parseOptionalNumber({ raw: String(form.get(key) ?? "") });
+    return value !== undefined && value !== current[key] ? { [key]: value } : undefined;
+}
+function diffCloseAfterDaysField(form, current) {
+    const closeAfterDays = parseCloseAfterDays({ raw: String(form.get("closeAfterDays") ?? "") });
+    return closeAfterDays !== undefined && closeAfterDays !== current.closeAfterDays ? { closeAfterDays } : undefined;
+}
+/** REQ-08/09/10: builds a partial patch containing only the fields the operator actually changed
+ * (the backend's `setCommentsSettings` is a partial-patch contract — REQ-08 asks the client to
+ * mirror that instead of always sending the full object, as `Seo.tsx`'s form does). Each field's
+ * diff logic is a standalone pure helper above so it can be tested (and reasoned about) on its
+ * own; this function is just the merge. */
+export function buildSettingsPatch(required, _optional = {}) {
+    const { form, current } = required;
+    return {
+        ...diffCheckboxField(form, "enabled", current),
+        ...diffCheckboxField(form, "requireModeration", current),
+        ...diffNumberField(form, "maxDepth", current),
+        ...diffCloseAfterDaysField(form, current),
+        ...diffNumberField(form, "spamAutoRejectScore", current),
+        ...diffNumberField(form, "maxPerIpPerHour", current),
+    };
+}
+/** REQ-09: client-side validates `spamAutoRejectScore` before the network call — mirrors the
+ * backend's own `validateCommentsSettingsPatch` bound (`src/comments/settings.ts`). Returns the
+ * error message to show, or `null` when the patch is valid. Split out of `save`'s body (originally
+ * an inline `if`) because it is the one piece of that flow that computes a value rather than
+ * performing an effect. */
+export function validateSettingsPatch({ patch }, { t = englishComments } = {}) {
+    if (patch.spamAutoRejectScore !== undefined && (patch.spamAutoRejectScore < 0 || patch.spamAutoRejectScore > 1)) {
+        return t("Spam auto-reject score must be between 0 and 1.");
+    }
+    return null;
+}
+/**
+ * `useCommentSettings`'s error banner, extracted out of that hook (`refactor/fetch-query`
+ * complexity pass, 2026-08-12 — same reason `redirects/rules.ts`'s `visibleRedirectsError` was
+ * extracted). Precedence, highest first: a client-side validation failure (the operator hasn't even
+ * submitted a valid patch yet — a stale write/list error underneath it would be a confusing second
+ * message), then the save write's own failure, then — only before `settings` has ever loaded — the
+ * list-read failure, matching every other migrated feature's "a later background failure must not
+ * blank an already-rendered screen" guard.
+ *
+ * @complexity Time/space: O(1) — four fixed checks, no iteration.
+ */
+export function visibleCommentSettingsError(params, _optional = {}) {
+    if (params.validationError)
+        return params.validationError;
+    if (params.saveError)
+        return describeApiError({ e: params.saveError, fallback: params.saveFallback });
+    if (params.hasSettings)
+        return null;
+    return params.listError ? describeApiError({ e: params.listError, fallback: params.listFallback }) : null;
+}
+//# sourceMappingURL=rules.js.map

package/dist/core/index.d.ts

@@ -17,9 +17,11 @@ export type { AdminClient, AdminRouteGroupFactory, AdminTransport, AdminFetch, H
 export type { GatedConfirmResult, GatedOperation, GatedPlanResult } from './gated/types.js';
 export type { DataTableSortDirection, DataTableSortState } from './data-table/types.js';
 export type { AdminAnalyticsHit, AdminAnalyticsPort, AdminAuthPort, AdminAuthUser, AdminComment, AdminCommentsPort, AdminCommentsQueuePage, AdminDatabasePort, AdminDegradedBanner, AdminDisclosureResult, AdminExtensionEnabledResult, AdminExtensionsPort, AdminIdentityPort, AdminIdentityUser, AdminIntegrationDelivery, AdminIntegrationDeliverySummary, AdminIntegrationSubscription, AdminIntegrationsPort, AdminLedgerRow, AdminMedia, AdminMediaPort, AdminMember, AdminMembersPort, AdminPlugin, AdminPolicy, AdminRecoveryDeepLinkResult, AdminRecoveryPort, AdminRecoveryStatus, AdminRestorePoint, AdminRestorePointSummary, AdminRole, AdminSettingsPort, AdminWorkspace, AdminWorkspacePort, CategoryCount, CommentModerationAction, CommentsSettings, CommentStatus, DatabaseContextEnvelope, DegradedBannerActionKind, DegradedBannerKind, MigrateForwardResult, RestoreConfirmInput, RestoreExecuteInput, RestoreExecuteResult, RestorePointCostClass, SettingResolvedValue, SettingResetResponse, SettingScope, SettingValueResponse, } from './ports/index.js';
-export type { AdminAssignMenuLocationResult, AdminDeleteMenuResult, AdminFormCreateInput, AdminFormDefinition, AdminFormField, AdminFormNotifyConfig, AdminFormsPort, AdminFormSubmission, AdminFormSubmissionPage, AdminFormUpdatePatch, AdminMenu, AdminMenuBinding, AdminMenuCreateInput, AdminMenuCustomTarget, AdminMenuEntryTarget, AdminMenuItem, AdminMenuItemAttrs, AdminMenuRouteTarget, AdminMenusPort, AdminMenuTarget, AdminMenuTermTarget, AdminMenuUpdateTreeInput, AdminMenuUrlTarget, AdminRedirect, AdminRedirectCreateInput, AdminRedirectHitStats, AdminRedirectImportFailure, AdminRedirectImportResult, AdminRedirectListFilter, AdminRedirectsPort, AdminRedirectUpdatePatch, AdminSeoAnalysis, AdminSeoIssue, AdminSeoMeta, AdminSeoOpenGraph, AdminSeoOverrides, AdminSeoPort, AdminSeoRobotsDirective, AdminSeoRobotsRule, AdminSeoSettings, AdminSeoTwitterCard, FormDefinitionStatus, FormFieldType, MenuStatus, NavTargetKind, RedirectMatchType, RedirectSource, RedirectStatus, RedirectStatusCode, SeoIssueSeverity, SeoOpenGraphType, SeoTwitterCardKind, } from './ports/index.js';
+export type { AdminAssignMenuLocationResult, AdminDeleteMenuResult, AdminFormCreateInput, AdminFormDefinition, AdminFormField, AdminFormNotifyConfig, AdminFormsPort, AdminFormSubmission, AdminFormSubmissionPage, AdminFormUpdatePatch, AdminMenu, AdminMenuBinding, AdminMenuCreateInput, AdminMenuCustomTarget, AdminMenuEntryTarget, AdminMenuItem, AdminMenuItemAttrs, AdminMenuRouteTarget, AdminMenusPort, AdminMenuTarget, AdminMenuTermTarget, AdminMenuUpdateTreeInput, AdminMenuUrlTarget, AdminRedirect, AdminRedirectCreateInput, AdminRedirectHitStats, AdminRedirectImportFailure, AdminRedirectImportResult, AdminRedirectListFilter, AdminRedirectsPort, AdminRedirectUpdatePatch, AdminSeoAnalysis, AdminSeoEntryChoice, AdminSeoIssue, AdminSeoMeta, AdminSeoOpenGraph, AdminSeoOverrides, AdminSeoOverridesPatch, AdminSeoPort, AdminSeoRobotsDirective, AdminSeoRobotsRule, AdminSeoSettings, AdminSeoSettingsPatch, AdminSeoTwitterCard, FormDefinitionStatus, FormFieldType, MenuStatus, NavTargetKind, RedirectMatchType, RedirectSource, RedirectStatus, RedirectStatusCode, SeoIssueSeverity, SeoOpenGraphType, SeoTwitterCardKind, } from './ports/index.js';
 export type { AdminEntityDescriptor, AdminEntityField, AdminEntityFieldKind, AdminEntityFilter, AdminEntityJsonField, AdminEntityListQuery, AdminEntityPage, AdminEntityPort, AdminEntityRegistry, AdminEntityRelationField, AdminEntityRow, AdminEntityRowData, AdminEntityScalarField, AdminErasedEntityPort, } from './ports/index.js';
 export { createAdminEntityRegistry, describeAdminEntityFieldMismatch, eraseEntityPort, getErasedEntityPort, listErasedEntityPorts, } from './entities/rules.js';
 export type { AdminEntityErasureOptions, AdminEntityRowViolation } from './entities/rules.js';
 export type { AdminShellContext, AdminShellNavigationPort, AdminShellSession, AdminShellSessionPort } from './ports/shell.js';
+export { loadNamespaceValues, saveChangedEntries, readString, readBoolean, readNumber } from './ledger-slice.js';
+export type { LedgerEntry, LedgerCandidate } from './ledger-slice.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/index.js

@@ -13,4 +13,5 @@ export { hasPermission } from './permissions/rules.js';
 // Transport — the seam every route group is built on.
 export { AdminApiError, createAdminClient, createHttpTransport, describeApiError, } from './transport/index.js';
 export { createAdminEntityRegistry, describeAdminEntityFieldMismatch, eraseEntityPort, getErasedEntityPort, listErasedEntityPorts, } from './entities/rules.js';
+export { loadNamespaceValues, saveChangedEntries, readString, readBoolean, readNumber } from './ledger-slice.js';
 //# sourceMappingURL=index.js.map

package/dist/core/ledger-slice.d.ts

@@ -0,0 +1,90 @@
+/**
+ * @file The shared read/diff-write half of every settings-dialog tab adapter.
+ *
+ * Each tab maps a SPEC-007 ledger namespace onto one `@jini-ai/ui` config
+ * object. Three things are identical across all of them and live here:
+ *
+ * 1. **Cold-start tolerance.** A namespace with no registered definitions
+ *    404s, which is the expected state before the boot registrar has run (or
+ *    on a database predating the tab). That is not an error worth surfacing —
+ *    it means "use defaults". Every OTHER failure still propagates.
+ * 2. **Field-level diffing.** The ledger is append-only per key
+ *    (ADR-028 §4), so writing all N keys on every save would burn N revisions
+ *    per keystroke. Only changed keys are written.
+ * 3. **Typed reads.** Ledger values arrive as `unknown`; a missing or
+ *    wrong-typed value falls back field by field rather than throwing, so a
+ *    partially-written namespace still yields a usable config.
+ *
+ * What deliberately does NOT live here: anything about a specific tab's
+ * shape, and anything about credentials. `execution-settings.ts` keeps its own
+ * localStorage half because the ADR-028 §6 secret gate is an execution-tab
+ * problem, not a general one — see that file's header.
+ */
+import type { AdminSettingsPort, SettingScope } from "./ports/settings.js";
+/** A single ledger write: the key within the namespace and its new JSON value. */
+export interface LedgerEntry {
+    key: string;
+    valueJson: unknown;
+}
+/** A candidate write plus whether it actually differs from the persisted value. */
+export interface LedgerCandidate extends LedgerEntry {
+    changed: boolean;
+}
+/**
+ * Reads every effective value in `namespace` as a key -> value map.
+ *
+ * Returns an EMPTY map (not an error) when the namespace has no registered
+ * definitions yet — see this file's header, item 1. Any other failure
+ * propagates, per the error-reporting contract: a network error or a 500 must
+ * not be laundered into "no settings", which would silently show defaults and
+ * then overwrite real saved values on the next keystroke.
+ */
+export declare function loadNamespaceValues({ namespace, port }: {
+    namespace: string;
+    port: Pick<AdminSettingsPort, "getSettingsEffective">;
+}, { isUnregisteredNamespace }: {
+    isUnregisteredNamespace: (required: {
+        error: unknown;
+    }, optional?: Record<string, never>) => boolean;
+}): Promise<Map<string, unknown>>;
+/**
+ * Writes the changed subset of `candidates`, in order, and returns the keys
+ * actually written.
+ *
+ * Sequential rather than parallel on purpose: each `setSetting` opens the
+ * settings write chokepoint's transaction, and concurrent openers throw on the
+ * SQLite root — the same hazard the server's boot registrars chain around.
+ */
+export declare function saveChangedEntries({ namespace, scope, candidates, port }: {
+    namespace: string;
+    scope: SettingScope;
+    candidates: readonly LedgerCandidate[];
+    port: Pick<AdminSettingsPort, "setSetting">;
+}, _options?: Record<string, never>): Promise<readonly string[]>;
+/** Reads a string, falling back when the key is absent or holds another type. */
+export declare function readString({ values, key, fallback }: {
+    values: ReadonlyMap<string, unknown>;
+    key: string;
+    fallback: string;
+}, _options?: Record<string, never>): string;
+/** Reads a boolean, falling back when the key is absent or holds another type. */
+export declare function readBoolean({ values, key, fallback }: {
+    values: ReadonlyMap<string, unknown>;
+    key: string;
+    fallback: boolean;
+}, _options?: Record<string, never>): boolean;
+/**
+ * Reads a finite number, falling back when the key is absent, holds another
+ * type, or holds `NaN`/`Infinity`.
+ *
+ * The finiteness check matters because these values round-trip through JSON,
+ * where `NaN` and `Infinity` serialize to `null` — a value that survived a
+ * write but not a read would otherwise reach a tab as a number it cannot
+ * render.
+ */
+export declare function readNumber({ values, key, fallback }: {
+    values: ReadonlyMap<string, unknown>;
+    key: string;
+    fallback: number;
+}, _options?: Record<string, never>): number;
+//# sourceMappingURL=ledger-slice.d.ts.map

package/dist/core/ledger-slice.js

@@ -0,0 +1,81 @@
+/**
+ * @file The shared read/diff-write half of every settings-dialog tab adapter.
+ *
+ * Each tab maps a SPEC-007 ledger namespace onto one `@jini-ai/ui` config
+ * object. Three things are identical across all of them and live here:
+ *
+ * 1. **Cold-start tolerance.** A namespace with no registered definitions
+ *    404s, which is the expected state before the boot registrar has run (or
+ *    on a database predating the tab). That is not an error worth surfacing —
+ *    it means "use defaults". Every OTHER failure still propagates.
+ * 2. **Field-level diffing.** The ledger is append-only per key
+ *    (ADR-028 §4), so writing all N keys on every save would burn N revisions
+ *    per keystroke. Only changed keys are written.
+ * 3. **Typed reads.** Ledger values arrive as `unknown`; a missing or
+ *    wrong-typed value falls back field by field rather than throwing, so a
+ *    partially-written namespace still yields a usable config.
+ *
+ * What deliberately does NOT live here: anything about a specific tab's
+ * shape, and anything about credentials. `execution-settings.ts` keeps its own
+ * localStorage half because the ADR-028 §6 secret gate is an execution-tab
+ * problem, not a general one — see that file's header.
+ */
+/**
+ * Reads every effective value in `namespace` as a key -> value map.
+ *
+ * Returns an EMPTY map (not an error) when the namespace has no registered
+ * definitions yet — see this file's header, item 1. Any other failure
+ * propagates, per the error-reporting contract: a network error or a 500 must
+ * not be laundered into "no settings", which would silently show defaults and
+ * then overwrite real saved values on the next keystroke.
+ */
+export async function loadNamespaceValues({ namespace, port }, { isUnregisteredNamespace }) {
+    try {
+        const data = await port.getSettingsEffective({ namespace }, {});
+        return new Map(data.map((row) => [row.key, row.value]));
+    }
+    catch (error) {
+        if (isUnregisteredNamespace({ error }, {}))
+            return new Map();
+        throw error;
+    }
+}
+/**
+ * Writes the changed subset of `candidates`, in order, and returns the keys
+ * actually written.
+ *
+ * Sequential rather than parallel on purpose: each `setSetting` opens the
+ * settings write chokepoint's transaction, and concurrent openers throw on the
+ * SQLite root — the same hazard the server's boot registrars chain around.
+ */
+export async function saveChangedEntries({ namespace, scope, candidates, port }, _options = {}) {
+    const changed = candidates.filter((candidate) => candidate.changed);
+    for (const { key, valueJson } of changed) {
+        await port.setSetting({ namespace, key, scope, value: valueJson }, {});
+    }
+    return changed.map((entry) => entry.key);
+}
+/** Reads a string, falling back when the key is absent or holds another type. */
+export function readString({ values, key, fallback }, _options = {}) {
+    const value = values.get(key);
+    return typeof value === "string" ? value : fallback;
+}
+/** Reads a boolean, falling back when the key is absent or holds another type. */
+export function readBoolean({ values, key, fallback }, _options = {}) {
+    const value = values.get(key);
+    return typeof value === "boolean" ? value : fallback;
+}
+/**
+ * Reads a finite number, falling back when the key is absent, holds another
+ * type, or holds `NaN`/`Infinity`.
+ *
+ * The finiteness check matters because these values round-trip through JSON,
+ * where `NaN` and `Infinity` serialize to `null` — a value that survived a
+ * write but not a read would otherwise reach a tab as a number it cannot
+ * render.
+ */
+export function readNumber({ values, key, fallback }, _options = {}) {
+    const value = values.get(key);
+    return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+//# sourceMappingURL=ledger-slice.js.map

package/dist/core/ports/comments.d.ts

@@ -24,6 +24,8 @@ export type CommentStatus = "pending" | "approved" | "spam" | "trash";
 /** A comment as it appears in the moderation queue. */
 export interface AdminComment {
     readonly id: string;
+    /** Optional workspace metadata retained from host queue responses; scoping stays in the transport. */
+    readonly workspaceId?: string;
     readonly entryId: string;
     /** Null for a top-level comment. */
     readonly parentId: string | null;

package/dist/core/ports/forms.d.ts

@@ -44,11 +44,11 @@
  * constraint documented, rather than being narrowed to a shape that can't express a removal
  * attempt at all.
  *
- * ## Submissions are the one place with a real hard delete
+ * ## Submission deletion moves to Trash
  *
- * Unlike definitions, `FormSubmissionRepoPort` does expose a permanent delete — the reference repo
- * port's own doc comment calls this out as "the one asymmetry." `deleteFormSubmission` is
- * genuinely irreversible; do not offer it with "undo" affordances.
+ * `deleteFormSubmission` models the admin HTTP operation: reversible removal from active reads.
+ * The underlying repository's hard-delete primitive is not this admin contract. Restoration and
+ * permanent deletion belong to the generic Trash owner (Coordinator authorization, 2026-10-08).
  *
  * ## Open vs. closed unions
  *
@@ -69,6 +69,8 @@ export interface AdminFormField {
     readonly type: FormFieldType;
     readonly required: boolean;
     readonly maxLength?: number | null;
+    readonly className?: string | undefined;
+    readonly attributes?: Readonly<Record<string, string>> | undefined;
 }
 export interface AdminFormNotifyConfig {
     readonly enabled: boolean;
@@ -83,6 +85,9 @@ export interface AdminFormDefinition {
     readonly status: FormDefinitionStatus;
     readonly createdAt: string;
     readonly updatedAt: string;
+    /** HTML authoring is explicit; absent mode means the existing Builder contract. */
+    readonly mode?: "builder" | "html" | undefined;
+    readonly html?: string | undefined;
 }
 export interface AdminFormSubmission {
     readonly id: string;
@@ -91,6 +96,8 @@ export interface AdminFormSubmission {
     readonly data: Readonly<Record<string, string | boolean>>;
     readonly sourceIp: string;
     readonly submittedAt: string;
+    /** Missing means active for older wire records. Trash preserves the original submission data. */
+    readonly status?: "active" | "trash";
 }
 /** A keyset-paginated page of submissions, newest-first. */
 export interface AdminFormSubmissionPage {
@@ -101,11 +108,16 @@ export interface AdminFormCreateInput {
     readonly name: string;
     readonly slug: string;
     readonly fields: readonly AdminFormField[];
+    readonly mode?: "builder" | "html" | undefined;
+    readonly html?: string | undefined;
     readonly notify?: AdminFormNotifyConfig;
 }
 /** No `slug` — see file header. */
 export interface AdminFormUpdatePatch {
     readonly name?: string;
+    /** A mode/body patch uses the authoring route; an ordinary patch keeps the CRUD route. */
+    readonly mode?: "builder" | "html" | undefined;
+    readonly html?: string | undefined;
     /** Whole-array replace with an add/edit-only constraint — see file header. */
     readonly fields?: readonly AdminFormField[];
     readonly notify?: AdminFormNotifyConfig;
@@ -132,11 +144,11 @@ export interface AdminFormsPort {
         formId: string;
         submissionId: string;
     }): Promise<AdminFormSubmission>;
-    /** Permanent delete — the one hard delete in this port. See file header on why form
-     *  DEFINITIONS have no equivalent. */
+    /** Move to Trash, preserving data while hiding it from active list/detail reads. The form must
+     * own this submission; restoration and permanent deletion remain with the generic Trash owner. */
     deleteFormSubmission(requiredArgs: {
         formId: string;
         submissionId: string;
-    }): Promise<void>;
+    }, optionalArgs?: Record<string, never>): Promise<void>;
 }
 //# sourceMappingURL=forms.d.ts.map

package/dist/core/ports/forms.js

@@ -44,11 +44,11 @@
  * constraint documented, rather than being narrowed to a shape that can't express a removal
  * attempt at all.
  *
- * ## Submissions are the one place with a real hard delete
+ * ## Submission deletion moves to Trash
  *
- * Unlike definitions, `FormSubmissionRepoPort` does expose a permanent delete — the reference repo
- * port's own doc comment calls this out as "the one asymmetry." `deleteFormSubmission` is
- * genuinely irreversible; do not offer it with "undo" affordances.
+ * `deleteFormSubmission` models the admin HTTP operation: reversible removal from active reads.
+ * The underlying repository's hard-delete primitive is not this admin contract. Restoration and
+ * permanent deletion belong to the generic Trash owner (Coordinator authorization, 2026-10-08).
  *
  * ## Open vs. closed unions
  *

package/dist/core/ports/index.d.ts

@@ -14,7 +14,7 @@ export type { AdminExtensionEnabledResult, AdminExtensionsPort, AdminPlugin } fr
 export type { AdminAnalyticsHit, AdminAnalyticsPort } from './analytics.js';
 export type { AdminWorkspace, AdminWorkspacePort } from './workspace.js';
 export type { AdminIdentityPort, AdminIdentityUser, AdminPolicy, AdminRole, } from './identity.js';
-export type { AdminSeoAnalysis, AdminSeoIssue, AdminSeoMeta, AdminSeoOpenGraph, AdminSeoOverrides, AdminSeoPort, AdminSeoRobotsDirective, AdminSeoRobotsRule, AdminSeoSettings, AdminSeoTwitterCard, SeoIssueSeverity, SeoOpenGraphType, SeoTwitterCardKind, } from './seo.js';
+export type { AdminSeoAnalysis, AdminSeoEntryChoice, AdminSeoIssue, AdminSeoMeta, AdminSeoOpenGraph, AdminSeoOverrides, AdminSeoOverridesPatch, AdminSeoPort, AdminSeoRobotsDirective, AdminSeoRobotsRule, AdminSeoSettings, AdminSeoSettingsPatch, AdminSeoTwitterCard, SeoIssueSeverity, SeoOpenGraphType, SeoTwitterCardKind, } from './seo.js';
 export type { AdminRedirect, AdminRedirectCreateInput, AdminRedirectHitStats, AdminRedirectImportFailure, AdminRedirectImportResult, AdminRedirectListFilter, AdminRedirectsPort, AdminRedirectUpdatePatch, RedirectMatchType, RedirectSource, RedirectStatus, RedirectStatusCode, } from './redirects.js';
 export type { AdminAssignMenuLocationResult, AdminDeleteMenuResult, AdminMenu, AdminMenuBinding, AdminMenuCreateInput, AdminMenuCustomTarget, AdminMenuEntryTarget, AdminMenuItem, AdminMenuItemAttrs, AdminMenuRouteTarget, AdminMenusPort, AdminMenuTarget, AdminMenuTermTarget, AdminMenuUpdateTreeInput, AdminMenuUrlTarget, MenuStatus, NavTargetKind, } from './menus.js';
 export type { AdminFormCreateInput, AdminFormDefinition, AdminFormField, AdminFormNotifyConfig, AdminFormsPort, AdminFormSubmission, AdminFormSubmissionPage, AdminFormUpdatePatch, FormDefinitionStatus, FormFieldType, } from './forms.js';

package/dist/core/ports/seo.d.ts

@@ -43,10 +43,9 @@ export type SeoTwitterCardKind = "summary" | "summary_large_image";
 export type SeoIssueSeverity = "error" | "warning" | "info" | (string & {});
 /**
  * The author-authored override bag for one entry. Every field is OPTIONAL — omitting a field
- * means "derive from site defaults / the content itself," not "clear it"; `putSeoEntry` merge-
- * patches this bag onto whatever was previously stored; there is no way to unset a single
- * previously-set field back to "derive" short of the host's own reset affordance (the reference
- * implementation has none either).
+ * means "derive from site defaults / the content itself," not "clear it". `putSeoEntry` accepts
+ * AdminSeoOverridesPatch, which adds null as the remove-override sentinel; omission leaves a
+ * previously stored override unchanged. The resolved read shape never contains null clears.
  */
 export interface AdminSeoOverrides {
     readonly title?: string;
@@ -132,6 +131,21 @@ export interface AdminSeoSettings {
     readonly sitemapEnabled: boolean;
     readonly robotsRules: readonly AdminSeoRobotsRule[];
 }
+/** Write-only clear sentinels: null removes a value; omission leaves it unchanged. */
+export type AdminSeoOverridesPatch = {
+    [K in keyof AdminSeoOverrides]?: AdminSeoOverrides[K] | null;
+};
+export type AdminSeoSettingsPatch = Partial<Omit<AdminSeoSettings, 'defaultDescription' | 'defaultOgImage' | 'twitterSite'>> & {
+    defaultDescription?: string | null;
+    defaultOgImage?: string | null;
+    twitterSite?: string | null;
+};
+/** Picker projection. Hosts may return additional content fields without a CMS dependency. */
+export interface AdminSeoEntryChoice {
+    readonly id: string;
+    readonly title: string;
+    readonly status: string;
+}
 export interface AdminSeoPort {
     getSeoEntry(requiredArgs: {
         entryId: string;
@@ -139,15 +153,28 @@ export interface AdminSeoPort {
     /** Merge-patches the override bag and returns the newly-resolved meta — see file header. */
     putSeoEntry(requiredArgs: {
         entryId: string;
-    }, optionalArgs?: AdminSeoOverrides): Promise<AdminSeoMeta>;
+    }, optionalArgs?: AdminSeoOverridesPatch): Promise<AdminSeoMeta>;
     analyzeSeoEntry(requiredArgs: {
         entryId: string;
     }): Promise<AdminSeoAnalysis>;
     getSeoSettings(requiredArgs: Record<string, never>): Promise<AdminSeoSettings>;
-    putSeoSettings(requiredArgs: Record<string, never>, optionalArgs?: Partial<AdminSeoSettings>): Promise<AdminSeoSettings>;
+    putSeoSettings(requiredArgs: Record<string, never>, optionalArgs?: AdminSeoSettingsPatch): Promise<AdminSeoSettings>;
     /** Fire-and-accept trigger, not a trackable job — see file header. */
     regenerateSeoSitemap(requiredArgs: Record<string, never>): Promise<{
         accepted: boolean;
     }>;
+    /** Existing post/page reads, in their original order; authorization remains host-owned. */
+    listSeoPosts(requiredArgs: Record<string, never>, optionalArgs?: Record<string, never>): Promise<readonly AdminSeoEntryChoice[]>;
+    listSeoPages(requiredArgs: Record<string, never>, optionalArgs?: Record<string, never>): Promise<readonly AdminSeoEntryChoice[]>;
+    /** Exact public sitemap response, never reconstructed from admin entries. */
+    fetchSitemapXml(requiredArgs: Record<string, never>, optionalArgs?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        text: string;
+    }>;
+    /** Original thumbnail URL; media-reference resolution stays on the server. */
+    mediaOriginalUrl(requiredArgs: {
+        id: string;
+    }, optionalArgs?: Record<string, never>): string;
 }
 //# sourceMappingURL=seo.d.ts.map

package/dist/core/react/bind-react.d.ts

@@ -0,0 +1,46 @@
+import type { ComponentType, ReactNode, LazyExoticComponent, Context as ReactContext } from 'react';
+import type { AdminInstance, AdminModule, ScopedPorts } from '../module/types.js';
+export interface TabViewProps {
+    readonly params: Readonly<Record<string, unknown>>;
+    readonly permissions?: readonly string[];
+}
+export interface ModulePageProps {
+    readonly tabs: Readonly<Record<string, LazyExoticComponent<ComponentType<TabViewProps>>>>;
+    readonly description: ReturnType<AdminInstance['describe']>['pages'][number];
+    readonly requestedTab?: string;
+    readonly onTabChange?: (required: {
+        tab: string;
+    }, optional?: Record<string, never>) => void;
+}
+type Loader<P> = () => Promise<{
+    default: ComponentType<P>;
+}>;
+export type ReactViews<M extends AdminModule> = {
+    readonly [P in keyof M['pages']]: {
+        readonly page: Loader<ModulePageProps>;
+        readonly tabs: {
+            readonly [T in keyof M['pages'][P]['tabs']]: Loader<TabViewProps>;
+        };
+    };
+};
+/** Every page and tab is lazy. The only port context is private to this binding;
+ * a sibling module can never read another module's dependencies through a global locator. */
+export declare function bindReact<const M extends AdminModule>({ module, views }: {
+    module: M;
+    views: ReactViews<M>;
+}, { context }?: {
+    context?: ReactContext<ScopedPorts<M> | null>;
+}): {
+    module: M;
+    pages: { [P in keyof M["pages"]]: {
+        Page: LazyExoticComponent<ComponentType<ModulePageProps>>;
+        tabs: { [T in keyof M["pages"][P]["tabs"]]: LazyExoticComponent<ComponentType<TabViewProps>>; };
+    }; };
+    Provider: ({ admin, children }: {
+        admin: AdminInstance;
+        children: ReactNode;
+    }, _optional?: Record<string, never>) => import("react").FunctionComponentElement<import("react").ProviderProps<ScopedPorts<M> | null>>;
+    usePorts: (_required?: Record<string, never>, _optional?: Record<string, never>) => ScopedPorts<M>;
+};
+export {};
+//# sourceMappingURL=bind-react.d.ts.map