@caelo-cms/shared 0.11.4 → 0.11.6

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";

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),

package/src/phase-timer.test.ts

@@ -45,4 +45,41 @@ describe("PhaseTimer", () => {
     expect(t.phases()).toHaveLength(1);
     for (const p of t.phases()) expect(phaseTimingSchema.parse(p)).toEqual(p);
   });
+
+  it("lapParts closes a step as the phases measured inside it plus the rest (#1271)", async () => {
+    const t = new PhaseTimer(clock(0, 1, 4, 5, 9, 20));
+    const parts = new Map<string, { ms: number }>();
+    await t.measure(parts, "compose", () => undefined);
+    await t.measure(parts, "compose", async () => undefined);
+    t.lapParts(parts, "batches");
+    expect(t.phases()).toEqual([
+      { phase: "compose", ms: 7 },
+      { phase: "batches", ms: 13 },
+    ]);
+  });
+
+  it("a memory timer records each step's peak RSS and stops sampling when closed (#1271)", async () => {
+    const t = PhaseTimer.withMemory();
+    try {
+      const hold: Uint8Array[] = [];
+      const parts = new Map<string, { ms: number; peakRssMb?: number }>();
+      await t.measure(parts, "alloc", async () => {
+        for (let i = 0; i < 16; i += 1) hold.push(new Uint8Array(4 * 1024 * 1024).fill(i + 1));
+        await Bun.sleep(60);
+      });
+      expect(parts.get("alloc")?.peakRssMb ?? 0).toBeGreaterThan(0);
+      t.lap("x");
+      expect(t.phases()[0]?.peakRssMb ?? 0).toBeGreaterThan(0);
+      expect(hold.length).toBe(16);
+      for (const p of t.phases()) expect(phaseTimingSchema.parse(p)).toEqual(p);
+    } finally {
+      t.close();
+    }
+  });
+
+  it("include keeps a step's peak RSS", () => {
+    const t = new PhaseTimer(clock(0, 1));
+    t.include("generator", [{ phase: "compose", ms: 3, peakRssMb: 120 }]);
+    expect(t.phases()).toEqual([{ phase: "generator.compose", ms: 3, peakRssMb: 120 }]);
+  });
 });

package/src/phase-timer.ts

@@ -9,6 +9,15 @@
  * Laps instead of wrapped callbacks: `lap("x")` closes the step that ran
  * since the previous lap, so a long function gets one line per boundary
  * and keeps its control flow (early throws, shared locals) as it is.
+ *
+ * #1271 — with `{ memory: true }` every step also carries
+ *   - the peak resident memory of the process while it ran (`peakRssMb`):
+ *     sampled every {@link RSS_SAMPLE_MS} by one shared timer that runs only
+ *     while a memory timer is open ({@link PhaseTimer.close}), plus a reading
+ *     at every lap;
+ *   - the CPU time the process spent in it (`cpuMs`, user + system, every
+ *     thread of the process — zlib and the other runtime workers included).
+ *     `cpuMs / ms` is the number of cores the step kept busy.
  */
 
 import { z } from "zod";
@@ -17,29 +26,176 @@ import { z } from "zod";
 export const phaseTimingSchema = z.object({
   phase: z.string().min(1),
   ms: z.number().int().nonnegative(),
+  /** #1271 — the process's peak resident memory during the step, in MiB. */
+  peakRssMb: z.number().int().nonnegative().optional(),
+  /** #1271 — CPU time (user + system, all threads) the process spent in the step, in ms. */
+  cpuMs: z.number().int().nonnegative().optional(),
 });
 export type PhaseTiming = z.infer<typeof phaseTimingSchema>;
 
+/** How often the open memory timers sample the resident set. */
+export const RSS_SAMPLE_MS = 25;
+
+const MIB = 1024 * 1024;
+
+/** Process CPU time so far (user + system), in ms; 0 where there is no process. */
+function cpuNow(): number {
+  if (typeof process === "undefined" || typeof process.cpuUsage !== "function") return 0;
+  const u = process.cpuUsage();
+  return (u.user + u.system) / 1000;
+}
+
+function rssNow(): number {
+  return typeof process !== "undefined" && typeof process.memoryUsage === "function"
+    ? process.memoryUsage().rss
+    : 0;
+}
+
+/**
+ * The one sampler of this process: its timer runs while at least one memory
+ * timer is open, and every open timer sees each sample.
+ */
+const sampler = (() => {
+  const listeners = new Set<(rss: number) => void>();
+  let timer: ReturnType<typeof setInterval> | null = null;
+  return {
+    add(fn: (rss: number) => void): void {
+      listeners.add(fn);
+      if (timer === null) {
+        timer = setInterval(() => {
+          const rss = rssNow();
+          for (const l of listeners) l(rss);
+        }, RSS_SAMPLE_MS);
+        // Never what keeps the process alive.
+        (timer as { unref?: () => void }).unref?.();
+      }
+    },
+    remove(fn: (rss: number) => void): void {
+      listeners.delete(fn);
+      if (listeners.size === 0 && timer !== null) {
+        clearInterval(timer);
+        timer = null;
+      }
+    },
+  };
+})();
+
+/** What {@link PhaseTimer.measure} adds up for one repeated step. */
+export interface PartTiming {
+  ms: number;
+  peakRssMb?: number;
+  cpuMs?: number;
+}
+
 export class PhaseTimer {
   readonly #now: () => number;
   readonly #phases: PhaseTiming[] = [];
   readonly #start: number;
+  readonly #listener: ((rss: number) => void) | null;
   #last: number;
+  #peak = 0;
+  #lastCpu = 0;
 
-  /** @param now clock in milliseconds; injectable for tests. */
-  constructor(now: () => number = () => performance.now()) {
+  /**
+   * @param now clock in milliseconds; injectable for tests.
+   * @param opts.memory record each step's peak RSS (see the file header);
+   *   the timer must then be {@link close}d.
+   */
+  constructor(now: () => number = () => performance.now(), opts: { memory?: boolean } = {}) {
     this.#now = now;
     this.#start = now();
     this.#last = this.#start;
+    if (opts.memory) {
+      this.#peak = rssNow();
+      this.#lastCpu = cpuNow();
+      this.#listener = (rss) => {
+        if (rss > this.#peak) this.#peak = rss;
+      };
+      sampler.add(this.#listener);
+    } else {
+      this.#listener = null;
+    }
+  }
+
+  /** A timer that records peak RSS per step (`new PhaseTimer(undefined, { memory: true })`). */
+  static withMemory(): PhaseTimer {
+    return new PhaseTimer(undefined, { memory: true });
   }
 
   /** Close the step that ran since the previous lap (or construction) as `phase`. */
   lap(phase: string): void {
     const t = this.#now();
-    this.#phases.push({ phase, ms: Math.round(t - this.#last) });
+    this.#phases.push({
+      phase,
+      ms: Math.round(t - this.#last),
+      ...this.#takePeak(),
+      ...this.#takeCpu(0),
+    });
     this.#last = t;
   }
 
+  /**
+   * Close the step since the previous lap as several phases measured
+   * inside it (`parts`, ms and peak each — e.g. the passes of every page
+   * batch summed), plus `rest` for whatever of the step they do not cover.
+   */
+  lapParts(parts: ReadonlyMap<string, PartTiming>, rest: string): void {
+    const t = this.#now();
+    const elapsed = t - this.#last;
+    let covered = 0;
+    let coveredCpu = 0;
+    for (const [phase, p] of parts) {
+      covered += p.ms;
+      coveredCpu += p.cpuMs ?? 0;
+      this.#phases.push({
+        phase,
+        ms: Math.round(p.ms),
+        ...(p.peakRssMb !== undefined ? { peakRssMb: p.peakRssMb } : {}),
+        ...(p.cpuMs !== undefined ? { cpuMs: Math.round(p.cpuMs) } : {}),
+      });
+    }
+    this.#phases.push({
+      phase: rest,
+      ms: Math.max(0, Math.round(elapsed - covered)),
+      ...this.#takePeak(),
+      ...this.#takeCpu(coveredCpu),
+    });
+    this.#last = t;
+  }
+
+  /**
+   * Run `fn` and add its duration (and, for a memory timer, its peak RSS)
+   * to `into[phase]` — for steps that repeat per batch, summed by
+   * {@link lapParts}.
+   */
+  async measure<T>(
+    into: Map<string, PartTiming>,
+    phase: string,
+    fn: () => Promise<T> | T,
+  ): Promise<T> {
+    const peakBefore = this.#peak;
+    if (this.#listener) this.#peak = rssNow();
+    const t0 = this.#now();
+    const cpu0 = this.#listener ? cpuNow() : 0;
+    try {
+      return await fn();
+    } finally {
+      const prev = into.get(phase) ?? { ms: 0 };
+      const ms = prev.ms + (this.#now() - t0);
+      if (this.#listener) {
+        const peak = Math.max(this.#peak, rssNow());
+        into.set(phase, {
+          ms,
+          peakRssMb: Math.max(prev.peakRssMb ?? 0, Math.round(peak / MIB)),
+          cpuMs: (prev.cpuMs ?? 0) + (cpuNow() - cpu0),
+        });
+        this.#peak = Math.max(peakBefore, peak);
+      } else {
+        into.set(phase, { ms });
+      }
+    }
+  }
+
   /**
    * Append steps timed elsewhere (the generator subprocess, a publisher)
    * as `<prefix>.<phase>`. They ran inside the current lap, so the lap that
@@ -47,7 +203,7 @@ export class PhaseTimer {
    * around them, e.g. spawning the subprocess).
    */
   include(prefix: string, phases: readonly PhaseTiming[]): void {
-    for (const p of phases) this.#phases.push({ phase: `${prefix}.${p.phase}`, ms: p.ms });
+    for (const p of phases) this.#phases.push({ ...p, phase: `${prefix}.${p.phase}` });
   }
 
   /** Milliseconds since construction. */
@@ -59,4 +215,26 @@ export class PhaseTimer {
   phases(): PhaseTiming[] {
     return [...this.#phases];
   }
+
+  /** Stop sampling memory (a memory timer must be closed; idempotent). */
+  close(): void {
+    if (this.#listener) sampler.remove(this.#listener);
+  }
+
+  /** CPU time since the previous lap, less what parts already account for. */
+  #takeCpu(covered: number): { cpuMs?: number } {
+    if (!this.#listener) return {};
+    const now = cpuNow();
+    const spent = now - this.#lastCpu - covered;
+    this.#lastCpu = now;
+    return { cpuMs: Math.max(0, Math.round(spent)) };
+  }
+
+  /** The peak since the previous lap, then restart it from now. */
+  #takePeak(): { peakRssMb?: number } {
+    if (!this.#listener) return {};
+    const peak = Math.max(this.#peak, rssNow());
+    this.#peak = rssNow();
+    return { peakRssMb: Math.round(peak / MIB) };
+  }
 }