@caelo-cms/shared 0.11.5 → 0.11.7

package/src/change-journal.ts

@@ -0,0 +1,325 @@
+// 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",
+  content_instance_refs:
+    "derived (synchronous, #1287): the ids and media slugs each content instance's values reference, maintained by triggers on the journaled content_instances; rebuilt by content_instances.rebuild_refs",
+  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";

package/src/content.ts

@@ -15,6 +15,7 @@ import { hasEscapedLineBreaks } from "./escaped-line-breaks.js";
 import { DEFAULT_LIST_TYPES, SITE_TEXTS_LIST_TYPE } from "./lists/default-types.js";
 import { listItemInputSchema } from "./lists/items.js";
 import { LIST_MAX_ITEMS, sourceDefSchema } from "./lists/list-type.js";
+import { pageTypeDefSchema } from "./lists/page-type.js";
 import { listPaginationSchema } from "./lists/pagination.js";
 import { LIST_REF_RE } from "./lists/refs.js";
 
@@ -185,7 +186,7 @@ const noCdata = (value: string): boolean => !value.includes(CDATA_OPEN);
 const cdataMessage = (field: "css" | "js"): string =>
   `${field} contains an XML CDATA marker (${CDATA_OPEN}) — module ${field} is stored and served ` +
   `verbatim, so CDATA wrappers reach the browser unparsed and break rendering. ` +
-  `Remove the wrapper and resend plain ${field === "css" ? "CSS" : "JavaScript"}.`;
+  `Remove the wrapper: pass plain ${field === "css" ? "CSS" : "JavaScript"}.`;
 
 const moduleCss = z
   .string()
@@ -624,17 +625,37 @@ export const pageTypeSlugSchema = z
     "page type slug: lowercase letters, digits, hyphens",
   );
 
+/**
+ * #1276 — slugs a new page type is deliberately distinct from: the
+ * duplicate guard refuses a new type whose slug normalises to an existing
+ * one (`blogs` next to `blog`) unless the caller names it here.
+ */
+export const pageTypeDistinctFromSchema = z.array(pageTypeSlugSchema).max(16);
+
+/**
+ * #1276 — a page type created together with its first template
+ * (`templates.create` `newPageType`): the definition without `templates`
+ * and `defaultTemplate`, which are the new template.
+ */
+export const newPageTypeSchema = pageTypeDefSchema
+  .omit({ templates: true, defaultTemplate: true })
+  .extend({ distinctFrom: pageTypeDistinctFromSchema.optional() })
+  .strict();
+export type NewPageTypeInput = z.infer<typeof newPageTypeSchema>;
+
 export const templateCreateSchema = z
   .object({
     slug: slugSchema,
     displayName: displayNameSchema,
     /**
-     * Epic #1107 — the page type (slug) this template serves; the template
-     * is appended to that type's `templates`. Omit for the site's default
-     * page type (`site_defaults.default_page_type_id`, stored data — not a
-     * render-time fallback).
+     * Epic #1107 / #1276 — the page type this template serves. Exactly one
+     * of `pageType` (an existing type's slug: the template is appended to
+     * its `templates`) and `newPageType` (a new type created in the same
+     * transaction with this template as its `defaultTemplate`) is
+     * required; `templates.create` refuses neither or both.
      */
     pageType: pageTypeSlugSchema.optional(),
+    newPageType: newPageTypeSchema.optional(),
     html: z
       .string()
       .max(TEMPLATE_HTML_MAX, `html exceeds ${TEMPLATE_HTML_MAX} bytes`)
@@ -736,9 +757,9 @@ export const pageCreateSchema = z
      */
     shortTitle: pageShortTitleSchema.optional(),
     /**
-     * P6.7.6 — optional. When omitted, the handler resolves to
-     * `site_defaults.default_template_id` at create time. Stored data,
-     * not a render-time fallback (CLAUDE.md §2 no-fallbacks).
+     * Optional: one of the page type's templates; omitted = the type's
+     * `defaultTemplate`. Without `pageType` it must belong to exactly one
+     * page type, which the page then gets (#1276).
      */
     templateId: z.string().uuid().optional(),
     /**
@@ -756,9 +777,9 @@ export const pageCreateSchema = z
      */
     parentPageId: z.string().uuid().nullable().optional(),
     /**
-     * Epic #1107 — what the page IS (page type slug). Omit to take the type
-     * whose `templates` contain the template; with neither `pageType` nor
-     * `templateId`, the site's default page type and its default template.
+     * Epic #1107 — what the page IS (page type slug). Required unless
+     * `templateId` belongs to exactly one page type; there is no stored
+     * default type (#1276), so a create with neither is refused.
      */
     pageType: pageTypeSlugSchema.optional(),
     /** Property values, validated against the page type. */

package/src/index.ts

@@ -9,6 +9,7 @@ export * from "./base-css.js";
 export * from "./bug-intake.js";
 export * from "./build-page.js";
 export * from "./cap-failures.js";
+export * from "./change-journal.js";
 export * from "./cloud-shell-install.js";
 export * from "./content.js";
 export * from "./context.js";
@@ -55,6 +56,7 @@ export * from "./page-log.js";
 export * from "./phase-timer.js";
 export * from "./platform-updates.js";
 export * from "./plugin-preview.js";
+export * from "./pool-budget.js";
 export * from "./preview-compose.js";
 export * from "./preview-scanner.js";
 export * from "./proposal-status.js";
@@ -77,6 +79,7 @@ export * from "./seo.js";
 export * from "./skills.js";
 export * from "./snapshots.js";
 export * from "./source-text-transport.js";
+export * from "./stage-status.js";
 export * from "./staging-gate.js";
 export * from "./static-cache-policy.js";
 export * from "./static-security-headers.js";

package/src/lists/fields.ts

@@ -56,6 +56,12 @@ export const LIST_RESERVED_NAMES: ReadonlySet<string> = new Set([
 /** Name prefixes reserved as a family (see {@link LIST_RESERVED_NAMES}). */
 export const LIST_RESERVED_PREFIXES = ["is_", "has_", "count_"] as const;
 
+/**
+ * The reserved names as one clause for an error (#1277: the tool
+ * description no longer lists them, so the refusal does).
+ */
+export const LIST_RESERVED_NAMES_CLAUSE = `reserved: ${[...LIST_RESERVED_NAMES].join(", ")}, ${LIST_RESERVED_PREFIXES.map((p) => `${p}*`).join(", ")}`;
+
 /** True when `name` is taken by the engine (see {@link LIST_RESERVED_NAMES}). */
 export function isReservedListName(name: string): boolean {
   return LIST_RESERVED_NAMES.has(name) || LIST_RESERVED_PREFIXES.some((p) => name.startsWith(p));
@@ -256,7 +262,7 @@ export function checkFieldDef(field: FieldDef, path: string): ListIssue[] {
   if (isReservedListName(field.name)) {
     issues.push({
       path,
-      message: `field name "${field.name}" is reserved by the template engine — pick another name.`,
+      message: `field name "${field.name}" is reserved by the template engine (${LIST_RESERVED_NAMES_CLAUSE}) — pick another name.`,
     });
   }
   if (field.default !== undefined) {

package/src/lists/list-fixtures.test.ts

@@ -262,6 +262,7 @@ export function fixtureData(
             slug: "news",
             name: "News",
             purpose: "News posts.",
+            collection: true,
             templates: [id(801)],
             defaultTemplate: id(801),
             properties: [

package/src/lists/list-type.ts

@@ -17,6 +17,7 @@ import {
   fieldDefSchema,
   fieldExtSchema,
   isReservedListName,
+  LIST_RESERVED_NAMES_CLAUSE,
   type ListIssue,
   listNameSchema,
 } from "./fields.js";
@@ -180,7 +181,10 @@ export function checkListTypeDef(def: ListTypeDef): ListIssue[] {
   for (const [kind, node] of Object.entries(def.nodes)) {
     const at = `nodes.${kind}`;
     if (isReservedListName(kind)) {
-      issues.push({ path: at, message: `node kind "${kind}" is a reserved name — rename it.` });
+      issues.push({
+        path: at,
+        message: `node kind "${kind}" is a reserved name (${LIST_RESERVED_NAMES_CLAUSE}) — rename it.`,
+      });
     }
     const seen = new Set<string>();
     node.fields.forEach((f, i) => {
@@ -193,7 +197,7 @@ export function checkListTypeDef(def: ListTypeDef): ListIssue[] {
       if (isReservedListName(node.children.name)) {
         issues.push({
           path: `${at}.children.name`,
-          message: `children name "${node.children.name}" is reserved — pick another loop name.`,
+          message: `children name "${node.children.name}" is reserved (${LIST_RESERVED_NAMES_CLAUSE}) — pick another loop name.`,
         });
       }
       if (seen.has(node.children.name)) {

package/src/lists/lists.test.ts

@@ -295,6 +295,7 @@ describe("page types and addresses", () => {
       slug: "news",
       name: "News",
       purpose: "Dated announcements",
+      collection: true,
       templates: [PAGE],
       defaultTemplate: LIST,
       properties: [{ name: "teaser", label: "T", type: "module" }],

package/src/lists/page-type.ts

@@ -17,6 +17,13 @@ export const pageTypeDefSchema = z
     slug: z.string().regex(/^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/),
     name: z.string().min(1).max(200),
     purpose: z.string().min(1).max(1000),
+    /**
+     * A collection of many similar pages meant to be listed or queried
+     * (blog, news, products, jobs, docs) — true; standalone pages (home,
+     * about / team / contact, legal, landing, utility) — false. The
+     * manual-page-listing check looks only at collection types (0450).
+     */
+    collection: z.boolean(),
     /** Template ids a page of this type may bind to. */
     templates: z.array(z.string().uuid()).min(1).max(64),
     defaultTemplate: z.string().uuid(),

package/src/live-events.ts

@@ -11,9 +11,13 @@
  * it is safe to hand to every signed-in tab. The read that follows goes
  * through the endpoint's own permission checks.
  *
- * Topics come from the names of operations that committed (the Query API's
- * `observeCommittedOperations`). Only WRITE operations are listed: a read
- * classified as a change would make every refresh announce another change.
+ * Operational topics come from the names of operations that committed (the
+ * Query API's `observeCommittedOperations`). Only WRITE operations are
+ * listed: a read classified as a change would make every refresh announce
+ * another change. Entity-derived topics (`draft`) come from the change
+ * journal instead (issue #1267): they fire exactly when a committed write
+ * changed a journaled row, on whichever instance it committed, and never
+ * for a write that changed nothing.
  */
 
 /** One surface an editor tab may need to re-read. */
@@ -30,6 +34,12 @@ export const LIVE_TOPICS = [
   "crawl",
   /** Deploy runs (Stage, Publish live, rollback). */
   "deploys",
+  /**
+   * Site content changed: a journaled row committed (a chat's or an MCP
+   * agent's write, a Stage, an undo, a settings change). From the change
+   * journal, never from an op name (#1267).
+   */
+  "draft",
 ] as const;
 
 export type LiveTopic = (typeof LIVE_TOPICS)[number];
@@ -70,6 +80,11 @@ const EXACT: Readonly<Record<string, readonly LiveTopic[]>> = {
   // An external agent's tool call: first sight of it lists it as running,
   // and it may have queued a card.
   "chat.touch_external_agent": ["agents", "pending"],
+  // The same presence row, written by Power-MCP's bookkeeping around each
+  // tool call (#1253): both mark the agent present (as the touch did), and
+  // the finish follows a card the tool may have queued.
+  "mcp.begin_tool_call": ["agents"],
+  "mcp.finish_tool_call": ["agents", "pending"],
   "chat.record_turn_approvals": ["pending"],
   "chat.decide_turn_approval": ["pending"],
   "chat.supersede_turn_approvals": ["pending"],

package/src/media.test.ts

@@ -103,12 +103,43 @@ describe("media schemas", () => {
           height: 1080,
           sizeBytes: 1024,
           storageKey: `${"a".repeat(64)}/orig.jpg`,
+          digest: {
+            contentSha256: "b".repeat(64),
+            size: 1024,
+            gzipSha256: "c".repeat(64),
+            gzipSize: 1000,
+            profile: "gzip9-0123456789abcdef",
+          },
         },
       ],
     });
     expect(r.success).toBe(true);
   });
 
+  it("mediaUploadInputSchema requires each variant's published digests (#1271)", () => {
+    const r = mediaUploadInputSchema.safeParse({
+      sha256: "a".repeat(64),
+      originalName: "hero.jpg",
+      mime: "image/jpeg",
+      sizeBytes: 1024,
+      width: 1920,
+      height: 1080,
+      alt: "",
+      storageKey: `${"a".repeat(64)}/orig.jpg`,
+      variants: [
+        {
+          variant: "orig",
+          format: "jpeg",
+          width: 1920,
+          height: 1080,
+          sizeBytes: 1024,
+          storageKey: `${"a".repeat(64)}/orig.jpg`,
+        },
+      ],
+    });
+    expect(r.success).toBe(false);
+  });
+
   it("mediaUploadInputSchema rejects non-hex sha256", () => {
     const r = mediaUploadInputSchema.safeParse({
       sha256: "not-a-sha",

package/src/media.ts

@@ -295,6 +295,21 @@ const mediaRefPattern =
 
 const sha256Schema = z.string().regex(/^[0-9a-f]{64}$/, "must be hex sha256");
 
+/**
+ * #1271 — the published digests of one stored media file (the static
+ * generator's `published-digest.ts`), stored with its variant row so no
+ * build reads the file to name or upload it.
+ */
+export const publishedDigestSchema = z
+  .object({
+    contentSha256: sha256Schema,
+    size: z.number().int().nonnegative(),
+    gzipSha256: sha256Schema,
+    gzipSize: z.number().int().nonnegative(),
+    profile: z.string().min(1).max(64),
+  })
+  .strict();
+
 /**
  * #531 — `library` assets are listed and placeable on pages; `reference`
  * assets exist only to guide image generation/editing: hidden from the
@@ -345,6 +360,8 @@ export const mediaUploadInputSchema = z
           height: z.number().int().positive().nullable(),
           sizeBytes: z.number().int().positive(),
           storageKey: z.string().min(1),
+          /** #1271 — taken from the bytes the writer stored (runMediaPipeline). */
+          digest: publishedDigestSchema,
         }),
       )
       .min(1),