@caelo-cms/shared 0.11.4 → 0.11.6

package/dist/pool-budget.js

@@ -0,0 +1,151 @@
+// SPDX-License-Identifier: MPL-2.0
+/**
+ * Issue #1254 — the database connection budget of an install.
+ *
+ * Every Caelo process that talks to Postgres holds connection pools, and
+ * they all draw from ONE server-wide `max_connections` (cms_admin and
+ * cms_public live on the same server). Before #1254 every pool took Bun's
+ * default of 10, so the admin alone asked for `adminMaxInstances × 2 × 10`
+ * — exactly the 100 slots of a default install, with nothing left for the
+ * gateway, the static generator, migrations or the provider's own agents.
+ * Under load the last admin instance to scale up could not connect at all.
+ *
+ * The budget turns that around: provisioning states how many connections
+ * the server has and how many instances may run, every fixed consumer is
+ * named as a {@link PoolBudgetReserve}, and what is left is split across
+ * the admin instances' cms_admin pools — the pool the write path uses.
+ * The admin's cms_public pool is small and fixed: the admin only reads
+ * plugin data there and publishes the gateway projection.
+ *
+ * Why not simply raise the pool: a larger pool only moves the wait from
+ * the pool to the server. A pool sized past the budget fails with "too
+ * many clients" at the worst moment (scale-out under load) instead of
+ * waiting a bounded time for a free connection of its own pool
+ * (query-api pool-guard.ts). docs/dev/connection-budget.md has the long
+ * version.
+ *
+ * Pure module — no I/O. Used by the provisioning stacks (which set the
+ * resulting env on each service) and re-exported by `@caelo-cms/query-api`.
+ */
+/** Env var sizing every pool of a `DatabaseAdapter` (both pools, unless the next one is set). */
+export const DB_POOL_MAX_ENV = "CAELO_DB_POOL_MAX";
+/**
+ * Env var sizing the cms_public pool of a `DatabaseAdapter` on its own. It
+ * wins over {@link DB_POOL_MAX_ENV} for that pool, so the admin can run a
+ * large cms_admin pool next to a small cms_public one.
+ */
+export const DB_PUBLIC_POOL_MAX_ENV = "CAELO_DB_PUBLIC_POOL_MAX";
+/** Smallest pool a `DatabaseAdapter` accepts: one connection self-deadlocks it. */
+export const MIN_POOL_MAX = 2;
+/**
+ * Smallest cms_admin pool the budget hands an admin instance. Below it a
+ * handful of concurrent editors and agents queue on every write; an install
+ * whose server cannot afford it must get a larger tier or fewer instances,
+ * so {@link computePoolBudget} refuses instead of shipping a starved pool.
+ */
+export const ADMIN_POOL_FLOOR = 4;
+/** The admin's cms_public pool: plugin-data reads and the gateway projection. */
+export const ADMIN_PUBLIC_POOL_MAX = 4;
+/** The gateway's only pool (public_role on cms_public), per instance. */
+export const GATEWAY_POOL_MAX = 2;
+/**
+ * Each pool of one static-generator subprocess. A build runs in ONE
+ * transaction (pool-guard.ts LONG_TRANSACTION_ALLOWLIST) and takes no
+ * second checkout, so the minimum pool ({@link MIN_POOL_MAX}) is enough.
+ */
+export const GENERATOR_POOL_MAX = 2;
+/**
+ * #1267 — the dedicated connection each admin instance keeps open for
+ * `LISTEN` on the change journal's wake-up channel. A LISTEN connection is
+ * held for the instance's lifetime and can never serve a query of the pool,
+ * so it is budgeted outside the pools, one per admin instance.
+ */
+export const LISTEN_CONNECTIONS_PER_ADMIN_INSTANCE = 1;
+/**
+ * The connection each gateway instance keeps open for `LISTEN
+ * caelo_gateway_settings` on cms_public (api-gateway server.ts): outside the
+ * gateway's pool, held for the instance's lifetime.
+ */
+export const LISTEN_CONNECTIONS_PER_GATEWAY_INSTANCE = 1;
+function positiveInteger(value, name, min) {
+    if (!Number.isInteger(value) || value < min) {
+        throw new Error(`pool budget: ${name} must be an integer >= ${min} (got ${value})`);
+    }
+}
+/**
+ * Split `maxConnections` across every process of the install.
+ *
+ * `adminPoolMax = floor((maxConnections − Σ reserves) / adminMaxInstances)`,
+ * where the reserves are the fixed consumers of {@link PoolBudgetInput} plus
+ * `gateway = gatewayMaxInstances × GATEWAY_POOL_MAX`,
+ * `generator = concurrentBuilds × 2 × GENERATOR_POOL_MAX`,
+ * `listen = adminMaxInstances × LISTEN_CONNECTIONS_PER_ADMIN_INSTANCE`,
+ * `gateway-listen = gatewayMaxInstances × LISTEN_CONNECTIONS_PER_GATEWAY_INSTANCE` and
+ * `admin-public = adminMaxInstances × ADMIN_PUBLIC_POOL_MAX`.
+ *
+ * @throws Error naming what to change when the server cannot give every
+ *   admin instance at least {@link ADMIN_POOL_FLOOR} cms_admin connections.
+ *
+ * @example
+ *   computePoolBudget({ maxConnections: 100, adminMaxInstances: 5,
+ *     gatewayMaxInstances: 10, concurrentBuilds: 2, maintenanceReserve: 5,
+ *     migrationsReserve: 2, jobsReserve: 4 }).adminPoolMax // → 7
+ */
+export function computePoolBudget(input) {
+    positiveInteger(input.maxConnections, "maxConnections", 1);
+    positiveInteger(input.adminMaxInstances, "adminMaxInstances", 1);
+    positiveInteger(input.gatewayMaxInstances, "gatewayMaxInstances", 0);
+    positiveInteger(input.concurrentBuilds, "concurrentBuilds", 0);
+    positiveInteger(input.maintenanceReserve, "maintenanceReserve", 0);
+    positiveInteger(input.migrationsReserve, "migrationsReserve", 0);
+    positiveInteger(input.jobsReserve, "jobsReserve", 0);
+    const reserves = [
+        { name: "maintenance", connections: input.maintenanceReserve },
+        { name: "migrations", connections: input.migrationsReserve },
+        { name: "jobs", connections: input.jobsReserve },
+        { name: "generator", connections: input.concurrentBuilds * 2 * GENERATOR_POOL_MAX },
+        { name: "gateway", connections: input.gatewayMaxInstances * GATEWAY_POOL_MAX },
+        {
+            name: "listen",
+            connections: input.adminMaxInstances * LISTEN_CONNECTIONS_PER_ADMIN_INSTANCE,
+        },
+        {
+            name: "gateway-listen",
+            connections: input.gatewayMaxInstances * LISTEN_CONNECTIONS_PER_GATEWAY_INSTANCE,
+        },
+        { name: "admin-public", connections: input.adminMaxInstances * ADMIN_PUBLIC_POOL_MAX },
+    ];
+    const reserved = reserves.reduce((sum, r) => sum + r.connections, 0);
+    const forAdmin = input.maxConnections - reserved;
+    const adminPoolMax = Math.floor(forAdmin / input.adminMaxInstances);
+    if (adminPoolMax < ADMIN_POOL_FLOOR) {
+        const needed = reserved + ADMIN_POOL_FLOOR * input.adminMaxInstances;
+        const breakdown = reserves.map((r) => `${r.name} ${r.connections}`).join(", ");
+        throw new Error(`pool budget: max_connections ${input.maxConnections} cannot give each of ${input.adminMaxInstances} admin instances the minimum of ${ADMIN_POOL_FLOOR} cms_admin connections ` +
+            `(reserved: ${breakdown}; ${needed} needed). Raise maxConnections to at least ${needed} (a larger database tier may be required), ` +
+            "or lower adminMaxInstances / gatewayMaxInstances.");
+    }
+    return {
+        adminPoolMax,
+        adminPublicPoolMax: ADMIN_PUBLIC_POOL_MAX,
+        gatewayPoolMax: GATEWAY_POOL_MAX,
+        generatorPoolMax: GENERATOR_POOL_MAX,
+        reserves,
+        unassigned: forAdmin - adminPoolMax * input.adminMaxInstances,
+    };
+}
+/**
+ * The env that sizes `service`'s pools from `budget`, for the stacks to set.
+ * The admin gets both pools; the gateway, whose only pool is cms_public,
+ * gets just that one.
+ */
+export function poolBudgetEnv(budget, service) {
+    if (service === "gateway") {
+        return [{ name: DB_PUBLIC_POOL_MAX_ENV, value: String(budget.gatewayPoolMax) }];
+    }
+    return [
+        { name: DB_POOL_MAX_ENV, value: String(budget.adminPoolMax) },
+        { name: DB_PUBLIC_POOL_MAX_ENV, value: String(budget.adminPublicPoolMax) },
+    ];
+}
+//# sourceMappingURL=pool-budget.js.map

package/dist/pool-budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool-budget.js","sourceRoot":"","sources":["../src/pool-budget.ts"],"names":[],"mappings":"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"}

package/dist/themes-errors.js

@@ -160,7 +160,7 @@ export class TokenCategoryMismatch extends Error {
     expected;
     got;
     constructor(canonicalPath, expected, got) {
-        super(`TokenCategoryMismatch: '${canonicalPath}' expects a ${expected} value, got a ${got} — re-send with a value matching ${expected}.`);
+        super(`TokenCategoryMismatch: '${canonicalPath}' expects a ${expected} value, got a ${got} — use a value matching ${expected}.`);
         this.name = "TokenCategoryMismatch";
         this.canonicalPath = canonicalPath;
         this.expected = expected;

package/dist/themes-errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"themes-errors.js","sourceRoot":"","sources":["../src/themes-errors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"themes-errors.js","sourceRoot":"","sources":["../src/themes-errors.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -19,7 +19,7 @@
  * Format: SemVer 2.0.0. Pre-1.0 minor bumps are breaking; post-1.0
  * follow standard SemVer.
  */
-export declare const CAELO_VERSION = "0.11.4";
+export declare const CAELO_VERSION = "0.11.6";
 /**
  * Deprecated alias for back-compat — early P17 work spelled this
  * `CALEO_VERSION` (typo of "Caelo"). New code should import
@@ -31,7 +31,7 @@ export declare const CAELO_VERSION = "0.11.4";
  *
  * @deprecated use CAELO_VERSION
  */
-export declare const CALEO_VERSION = "0.11.4";
+export declare const CALEO_VERSION = "0.11.6";
 /**
  * Parsed shape — major/minor/patch + optional pre-release tag.
  * Stable interface for callers that need to feature-gate (rare —

package/dist/version.js

@@ -20,7 +20,7 @@
  * Format: SemVer 2.0.0. Pre-1.0 minor bumps are breaking; post-1.0
  * follow standard SemVer.
  */
-export const CAELO_VERSION = "0.11.4";
+export const CAELO_VERSION = "0.11.6";
 /**
  * Deprecated alias for back-compat — early P17 work spelled this
  * `CALEO_VERSION` (typo of "Caelo"). New code should import

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caelo-cms/shared",
-  "version": "0.11.4",
+  "version": "0.11.6",
   "private": false,
   "license": "MPL-2.0",
   "description": "Shared Zod schemas + types + the two-pass HTML composer used by every Caelo CMS workspace package. Stable enough for plugin authors and embedders to depend on directly.",

package/src/ai-tools.ts

@@ -19,6 +19,7 @@ import {
   forkPlacementContentSchema,
   type ModuleField,
   moduleFieldSchema,
+  newPageTypeSchema,
   pageShortTitleSchema,
   pageTypeSlugSchema,
   setPlacementContentSchema,
@@ -333,6 +334,13 @@ export const chatCreateSessionInput = z
      * draft: an explicit experiment ("try a redesign") or a site migration.
      */
     isolation: z.enum(["experiment", "migration"]).optional(),
+    /**
+     * Issue #1253 — the session is an external agent's (one chat per
+     * agent): the client app it works for ("Claude Code", a token's label).
+     * The chat list groups such chats per client, and Live Edit never picks
+     * one as the operator's own chat.
+     */
+    agentClient: z.string().min(1).max(200).optional(),
   })
   .strict();
 
@@ -584,8 +592,10 @@ export const createTemplateToolInput = z
     html: sourceTextArg(z.string().min(1).max(2_000_000), "html"),
     css: sourceTextArg(z.string().max(2_000_000), "css").default(""),
     layoutId: z.string().uuid().optional(),
-    /** Epic #1107 — the page type (slug) this template serves; omit for the site default. */
+    /** #1276 — exactly one of: the existing page type this template serves… */
     pageType: pageTypeSlugSchema.optional(),
+    /** …or a new page type created with this template as its default. */
+    newPageType: newPageTypeSchema.optional(),
     // Optional block-set metadata, symmetric with create_layout. Omit to
     // auto-derive blocks from <caelo-slot> tags; pass to set displayName /
     // position (each name must match a slot). Enforced op-side in
@@ -650,15 +660,12 @@ export const createLayoutToolInput = z
   })
   .strict();
 
+/** #1276 — the default layout only: there is no default template or page type. */
 export const setSiteDefaultsToolInput = z
   .object({
-    defaultLayoutSlug: slugInputSchema.optional(),
-    defaultTemplateSlug: slugInputSchema.optional(),
+    defaultLayoutSlug: slugInputSchema,
   })
-  .strict()
-  .refine((v) => v.defaultLayoutSlug !== undefined || v.defaultTemplateSlug !== undefined, {
-    message: "must provide at least one of defaultLayoutSlug, defaultTemplateSlug",
-  });
+  .strict();
 
 /**
  * P6.7.7 — content-ops follow-ups: clone a page, swap a page's
@@ -674,6 +681,8 @@ export const duplicatePageToolInput = z
     /** #1142 — the copy's breadcrumb label; omitted = newTitle when given, else the source's. */
     newShortTitle: pageShortTitleSchema.optional(),
     targetTemplateId: z.string().uuid().optional(),
+    /** #1276 — the copy's page type (slug); omitted = the source's. */
+    pageType: pageTypeSlugSchema.optional(),
     /** Where the copy sits: a parent page id, or null for the top level.
      *  Omitted = next to the source (same parent). */
     newParentPageId: z.string().uuid().nullable().optional(),
@@ -1073,7 +1082,13 @@ export const bootstrapSiteScaffoldToolInput = z
     templateSlug: z.string().min(1).max(120).optional(),
     /** Display name for the new template. Defaults to `Home template`. */
     templateDisplayName: z.string().min(1).max(256).optional(),
-    /** Whether to pin the new layout+template as site_defaults. Defaults to true. */
+    /**
+     * #1276 — the page type the new template serves (every template has
+     * one). An existing slug joins that type; else the type is created
+     * with the template. Defaults to the `home` page type.
+     */
+    templatePageType: newPageTypeSchema.optional(),
+    /** Whether to pin the new layout as the site's default layout. Defaults to true. */
     setAsDefaults: z.boolean().optional(),
   })
   .strict();

package/src/change-journal.ts

@@ -0,0 +1,323 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Issue #1267 — the change journal's registry: which `cms_admin` tables
+ * write journal rows, under which kind, and why every other table does not.
+ * The contract is `docs/dev/state-and-changes.md`.
+ *
+ * The journal (`entity_changes`, migration 0430) is written by generic row
+ * triggers that migrations attach with `caelo_journal_attach(...)`. This
+ * file is the readable copy of that set, and the CI test
+ * `change-journal-registry.integration.test.ts` holds both in step: every
+ * `cms_admin` table must be either journaled here with the exact trigger
+ * arguments the database carries, or exempt here with a written reason. A
+ * new table that is neither fails CI, so no table can silently fall
+ * outside the journal.
+ *
+ * Plugin storage tables (`plugin_<slug>.*`) are not listed: the host
+ * attaches the trigger when it provisions a plugin's schema, under the kind
+ * `plugin_storage` keyed on the plugin's id (never on its reusable slug), so
+ * a new plugin or domain needs no journal migration.
+ */
+
+/** Every kind a journal row can carry. A consumer names the kinds it reads. */
+export const JOURNAL_KINDS = [
+  "page",
+  "page_terms",
+  "page_seo",
+  "page_layout",
+  "page_module_content",
+  "module",
+  "template",
+  "template_blocks",
+  "layout",
+  "layout_blocks",
+  "layout_module",
+  "content_instance",
+  "list",
+  "list_type",
+  "page_type",
+  "theme",
+  "media",
+  "media_variant",
+  "media_crop",
+  "font",
+  "redirect",
+  "domain",
+  "site_defaults",
+  "site_settings",
+  "site_memory",
+  "skill",
+  "plugin",
+  "plugin_installation",
+  "plugin_grant",
+  "plugin_file",
+  "plugin_row",
+  "plugin_storage",
+  "snapshot",
+] as const;
+
+/** One kind of the journal (`entity_changes.kind`). */
+export type JournalKind = (typeof JOURNAL_KINDS)[number];
+
+const KIND_SET: ReadonlySet<string> = new Set(JOURNAL_KINDS);
+
+/** Is `value` a journal kind? */
+export function isJournalKind(value: string): value is JournalKind {
+  return KIND_SET.has(value);
+}
+
+/**
+ * How a journaled table's rows map to journal rows (the trigger's
+ * arguments, `caelo_journal_attach` in migration 0430):
+ *
+ * - `row` — a live entity table. The journal row carries the entity id
+ *   (`key`), the row's own branch when the table has one (`branch`), and
+ *   the chat from the writing transaction's attribution settings.
+ * - `snapshot` — an entity snapshot table. Branch, chat and snapshot id
+ *   come from the snapshot's `site_snapshots` header, and an inserted
+ *   snapshot records the snapshot it replaces on the same line
+ *   (`prev_snapshot_id`), so a consumer can diff the two states.
+ * - `header` — `site_snapshots` itself: Stage (`staged_at`), undo
+ *   (`undone_at`) and lock takeover (`chat_branch_id`) are UPDATEs of it.
+ */
+export type JournalMode = "row" | "snapshot" | "header";
+
+/** One journaled table, exactly as its trigger is attached. */
+export interface JournaledTable {
+  readonly kind: JournalKind;
+  readonly mode: JournalMode;
+  /** The column that holds the entity id (`entity_changes.row_id`). */
+  readonly key: string;
+  /** The primary-key columns an UPDATE's old and new rows are paired on. */
+  readonly pair: readonly string[];
+  /** A column naming the entity this row belongs to (`entity_changes.parent_id`). */
+  readonly parent?: string;
+  /** The row's own branch column (`row` mode only). */
+  readonly branch?: string;
+  /** The column holding the owning plugin's id. */
+  readonly plugin?: string;
+}
+
+const row = (
+  kind: JournalKind,
+  key: string,
+  pair: readonly string[],
+  extra: Partial<Pick<JournaledTable, "parent" | "branch" | "plugin">> = {},
+): JournaledTable => ({ kind, mode: "row", key, pair, ...extra });
+
+const snapshot = (
+  kind: JournalKind,
+  key: string,
+  extra: Partial<Pick<JournaledTable, "parent" | "plugin">> = {},
+): JournaledTable => ({ kind, mode: "snapshot", key, pair: ["id"], ...extra });
+
+/**
+ * The journaled `cms_admin` tables. Everything an editor, a render, a
+ * build or a plugin derives from: content and its snapshots, media,
+ * settings that render into pages, redirects, plugins and their grants.
+ */
+export const JOURNALED_TABLES: Readonly<Record<string, JournaledTable>> = {
+  pages: row("page", "id", ["id"], { branch: "chat_branch_id" }),
+  page_terms: row("page_terms", "page_id", ["page_id", "list_id", "item_id"]),
+  pages_seo: row("page_seo", "page_id", ["page_id"]),
+  page_modules: row("page_layout", "page_id", ["page_id", "block_name", "position"]),
+  page_module_content: row("page_module_content", "id", ["id"], { parent: "page_id" }),
+  modules: row("module", "id", ["id"], { branch: "chat_branch_id" }),
+  templates: row("template", "id", ["id"], { branch: "chat_branch_id" }),
+  template_blocks: row("template_blocks", "template_id", ["template_id", "name"]),
+  layouts: row("layout", "id", ["id"], { branch: "chat_branch_id" }),
+  layout_blocks: row("layout_blocks", "layout_id", ["layout_id", "name"]),
+  layout_modules: row("layout_module", "layout_id", ["layout_id", "block_name", "position"]),
+  content_instances: row("content_instance", "id", ["id"], {
+    branch: "chat_branch_id",
+    parent: "module_id",
+  }),
+  lists: row("list", "id", ["id"], { branch: "chat_branch_id" }),
+  list_types: row("list_type", "id", ["id"], { branch: "chat_branch_id" }),
+  page_types: row("page_type", "id", ["id"], { branch: "chat_branch_id" }),
+  themes: row("theme", "id", ["id"]),
+  media_assets: row("media", "id", ["id"]),
+  media_variants: row("media_variant", "asset_id", ["asset_id", "variant"]),
+  media_crops: row("media_crop", "id", ["id"], { parent: "asset_id" }),
+  font_assets: row("font", "id", ["id"]),
+  redirects: row("redirect", "id", ["id"]),
+  domains: row("domain", "id", ["id"]),
+  site_defaults: row("site_defaults", "id", ["id"]),
+  site_settings: row("site_settings", "id", ["id"]),
+  site_ai_memory: row("site_memory", "id", ["id"]),
+  skills: row("skill", "id", ["id"]),
+  plugins: row("plugin", "id", ["id"]),
+  plugin_installation_versions: row("plugin_installation", "id", ["id"], { parent: "plugin_id" }),
+  plugin_capability_grants: row("plugin_grant", "id", ["id"], { parent: "plugin_id" }),
+  plugin_private_files: row("plugin_file", "id", ["plugin_id", "id"], { plugin: "plugin_id" }),
+
+  site_snapshots: { kind: "snapshot", mode: "header", key: "id", pair: ["id"] },
+  page_snapshots: snapshot("page", "page_id"),
+  page_layout_snapshots: snapshot("page_layout", "page_id"),
+  page_module_content_snapshots: snapshot("page_module_content", "page_module_content_id", {
+    parent: "page_id",
+  }),
+  module_snapshots: snapshot("module", "module_id"),
+  template_snapshots: snapshot("template", "template_id"),
+  layout_module_snapshots: snapshot("layout_module", "layout_id"),
+  content_instance_snapshots: snapshot("content_instance", "content_instance_id"),
+  list_snapshots: snapshot("list", "list_id"),
+  list_type_snapshots: snapshot("list_type", "list_type_id"),
+  page_type_snapshots: snapshot("page_type", "page_type_id"),
+  theme_snapshots: snapshot("theme", "theme_id"),
+  plugin_row_snapshots: snapshot("plugin_row", "row_id", {
+    parent: "table_name",
+    plugin: "plugin_id",
+  }),
+};
+
+const QUEUE = "a proposal queue; its changes reach editors as the op-classified `pending` topic";
+const LOG = "an append-only log or history; nothing is derived from it";
+const LEASE = "a lease or lock that coordinates processes; nothing is derived from it";
+const SECURITY = "identity and permission rows, read per request by the auth layer";
+const RUNTIME = "runtime bookkeeping of a process (health, progress, cache)";
+const RETIRED = "retired by #1267; nothing reads it any more, migration 0442 drops it";
+const RETIRED_SIGNAL =
+  "retired by #1267; nothing reads it, its writer triggers stay one release for the previous image (roll, rollback), migration 0442 drops both";
+
+/**
+ * Every `cms_admin` table that writes no journal rows, with the reason.
+ * Adding a table here is a decision a reviewer reads, not a default.
+ */
+export const JOURNAL_EXEMPT_TABLES: Readonly<Record<string, string>> = {
+  __drizzle_migrations: "the migration runner's own bookkeeping",
+  entity_changes: "the journal itself",
+  entity_change_horizons: "the journal's garbage-collection horizons",
+  change_consumers: "the journal's consumer cursors",
+  domain_events: RETIRED,
+  font_usage_changes: RETIRED_SIGNAL,
+  site_view_generation: RETIRED_SIGNAL,
+  plugin_event_cursors: RETIRED,
+
+  actors: SECURITY,
+  users: SECURITY,
+  roles: SECURITY,
+  permissions: SECURITY,
+  role_permissions: SECURITY,
+  user_roles: SECURITY,
+  sessions: SECURITY,
+  password_reset_tokens: SECURITY,
+  owner_bootstrap_tokens: SECURITY,
+  mcp_tokens: SECURITY,
+  mcp_remote_connections: SECURITY,
+  mcp_remote_access_blocks: SECURITY,
+  mcp_transport_sessions: SECURITY,
+  operator_oauth_client: SECURITY,
+  credential_handoffs:
+    "one-time credentials an approval left; delivered as the `credentials` topic",
+  user_preferences: "one person's editor preferences, read only by that person's own requests",
+  skill_pin_defaults: "one person's skill pins, read only by that person's own chats",
+
+  audit_events: LOG,
+  ai_calls: LOG,
+  ai_bug_reports: LOG,
+  ai_moduleize_attempts: LOG,
+  page_edit_log: LOG,
+  import_run_events: LOG,
+  platform_update_events: LOG,
+  plugin_errors: LOG,
+  redirect_syncs: LOG,
+  operator_access_sync_runs: LOG,
+  link_migration_runs: LOG,
+  comment_archive:
+    "visitor comments copied from cms_public: untrusted visitor data, nothing is derived from it",
+
+  chat_sessions:
+    "conversation metadata; what a chat changed is journaled through its snapshots, its run state reaches editors as the `agents` topic",
+  chat_messages: "conversation history (the provider's message log)",
+  chat_tool_results: "conversation history (tool results)",
+  chat_agent_runs: "running agents; reach editors as the op-classified `agents` topic",
+  chat_turn_approvals: "paused approval cards; reach editors as the `pending` topic",
+  chat_turn_leases: LEASE,
+  chat_entity_locks:
+    "cross-branch entity locks; a takeover re-points the snapshots, which are journaled",
+  chat_lock_takeovers: LOG,
+  chat_branch_publish_marks:
+    "which branch states reached main; the Stage that writes it also updates the journaled site_snapshots",
+  draft_entity_observations: "which draft entity states a chat has read (conflict detection)",
+  subagent_runs: "subagent bookkeeping of a chat turn",
+  mcp_approval_handoffs: "approval hand-offs to an MCP client",
+  tool_approval_actions: "approval decisions of chat tool calls",
+  plugin_tool_approval_bindings: "the binding of an approved plugin tool call to its arguments",
+  site_draft: "the shared draft branch's registry row; branch changes are journaled as snapshots",
+  genesis_drafts: "design drafts before a site exists; no page renders from them",
+  image_requests: "image generation requests; the resulting media asset is journaled",
+  media_alt_proposals:
+    "alt-text suggestions awaiting review; the accepted alt is journaled on media_assets",
+  entity_leases: LEASE,
+  deploy_leases: LEASE,
+  plugin_activation_leases: LEASE,
+  rate_limit_buckets: "visitor and login rate-limit counters",
+  rate_limit_profiles: "gateway rate-limit profiles, published to the gateway's projection",
+  plugin_rate_limit_overrides:
+    "gateway rate-limit overrides, published to the gateway's projection",
+  plugin_rate_limit_proposals: QUEUE,
+
+  ai_providers: "Owner AI configuration; read per call, nothing is derived from it",
+  ai_budgets: "Owner AI budgets; read per call, nothing is derived from it",
+  ai_pricing: "Owner AI pricing; read per call, nothing is derived from it",
+  email_config: "Owner email configuration; read per send",
+  telemetry_settings: "the install's telemetry consent",
+  staging_access:
+    "staging access settings, synced to the hosting provider on save (docs/dev/redirects-and-settings-sync.md)",
+  provisioning_outputs: "what the provisioner recorded about the install",
+  release_check_cache: RUNTIME,
+  deploy_targets: "deploy target configuration; read by the deploy ops",
+  deploy_runs: "deploy runs; reach editors as the op-classified `deploys` topic",
+  redirect_sync_state: RUNTIME,
+  redirect_changes:
+    "which transactions changed redirects, folded by the redirect sync; the journaled redirects table is the source",
+  static_bakes: "derived build output of plugin-baked regions",
+  plugin_data_build_state: RUNTIME,
+  plugin_data_stale_pages: "derived: which pages' baked plugin regions are stale",
+  plugin_runtime: RUNTIME,
+  plugin_schema_migrations: "plugin DDL bookkeeping",
+  plugin_schema_provisions: "plugin DDL bookkeeping",
+  plugin_private_file_chunks:
+    "the bytes of plugin_private_files rows, journaled through the file row",
+  public_projection_outbox: "the outbox of the cms_public projection, drained by its publisher",
+  platform_update_agent: RUNTIME,
+  platform_update_notifications: RUNTIME,
+  platform_update_policy: "the Owner's update policy, read by the update scheduler",
+  platform_update_requests: "update requests, run by the upgrader job",
+  platform_update_scheduler: RUNTIME,
+
+  import_runs: "site-import runs; reach editors as the op-classified `crawl` topic",
+  import_pages: "crawled pages of a site import, before they become pages",
+  import_run_links: "links found by a site import",
+  quality_audit_runs: "quality audits; reach editors as the op-classified `quality` topic",
+  quality_audit_pages: "quality audit results per page",
+  quality_baselines: "quality baselines per page, written by the audit worker",
+  quality_acceptances: "accepted quality findings; reach editors as the `quality` topic",
+  site_memory_proposals: QUEUE,
+  skill_proposals: QUEUE,
+
+  ai_providers_pending_actions: QUEUE,
+  deploy_pending_actions: QUEUE,
+  domain_pending_actions: QUEUE,
+  email_config_pending_actions: QUEUE,
+  layout_pending_actions: QUEUE,
+  mcp_token_pending_actions: QUEUE,
+  owner_settings_pending_actions: QUEUE,
+  plugin_pending_actions: QUEUE,
+  quality_pending_actions: QUEUE,
+  role_pending_actions: QUEUE,
+  site_defaults_pending_actions: QUEUE,
+  snapshot_revert_pending_actions: QUEUE,
+  template_pending_actions: QUEUE,
+  theme_pending_actions: QUEUE,
+  url_migration_pending_actions: QUEUE,
+  user_pending_actions: QUEUE,
+};
+
+/** NOTIFY channel the journal trigger wakes consumers on (payload empty). */
+export const JOURNAL_CHANNEL = "caelo_entity_changes";
+
+/** NOTIFY channel carrying operation-classified live topics across instances. */
+export const LIVE_TOPICS_CHANNEL = "caelo_live_topics";