@caelo-cms/shared 0.10.22 → 0.10.24

package/src/result.ts

@@ -0,0 +1,29 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Discriminated-union Result type. Used at the Query API boundary where errors are
+ * expected (validation, RLS denials, unknown operations) and throwing is reserved
+ * for genuinely exceptional conditions (lost DB connection, logic bug).
+ *
+ * Per CLAUDE.md §4: "errors are values where it matters".
+ */
+
+export type Ok<T> = { readonly ok: true; readonly value: T };
+export type Err<E> = { readonly ok: false; readonly error: E };
+export type Result<T, E> = Ok<T> | Err<E>;
+
+export function ok<T>(value: T): Ok<T> {
+  return { ok: true, value };
+}
+
+export function err<E>(error: E): Err<E> {
+  return { ok: false, error };
+}
+
+export function isOk<T, E>(result: Result<T, E>): result is Ok<T> {
+  return result.ok;
+}
+
+export function isErr<T, E>(result: Result<T, E>): result is Err<E> {
+  return !result.ok;
+}

package/src/safe-keys.ts

@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Keys that, when used as a dynamic property name on a plain object,
+ * mutate the prototype chain instead of the object's own data — the
+ * prototype-pollution vector. Any code that assigns into an object with
+ * a key derived from external input (imported CSS variable names, dotted
+ * write paths from forms/AI) must reject these first.
+ */
+const UNSAFE_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
+/**
+ * True when `key` would pollute the prototype chain if used as a dynamic
+ * assignment target (`obj[key] = …`). Callers skip or reject such keys.
+ *
+ * @param key The candidate property name (e.g. a parsed token name or a
+ *            path segment).
+ */
+export function isUnsafeKey(key: string): boolean {
+  return UNSAFE_KEYS.has(key);
+}

package/src/seo.test.ts

@@ -0,0 +1,194 @@
+// SPDX-License-Identifier: MPL-2.0
+
+import { describe, expect, it } from "bun:test";
+import {
+  injectSeoIntoHead,
+  renderSeoHead,
+  resolveCanonicalUrl,
+  seoAutofillInputSchema,
+  seoOptimizeInputSchema,
+  seoSetInputSchema,
+  siteDefaultsSetSeoInputSchema,
+} from "./seo.js";
+
+describe("resolveCanonicalUrl", () => {
+  it("uses the explicit override when provided", () => {
+    expect(
+      resolveCanonicalUrl({
+        siteBaseUrl: "https://example.com",
+        pageSlug: "anything",
+        override: "https://canonical.example.com/x",
+      }),
+    ).toBe("https://canonical.example.com/x");
+  });
+
+  it("renders home as the root path", () => {
+    expect(
+      resolveCanonicalUrl({
+        siteBaseUrl: "https://example.com",
+        pageSlug: "home",
+        override: null,
+      }),
+    ).toBe("https://example.com/");
+  });
+
+  it("trims trailing slash on the base URL", () => {
+    expect(
+      resolveCanonicalUrl({
+        siteBaseUrl: "https://example.com/",
+        pageSlug: "about",
+        override: null,
+      }),
+    ).toBe("https://example.com/about/");
+  });
+
+  describe("v0.2.85 — pageUrlStyle='no-extension'", () => {
+    it("omits the trailing slash for non-home pages", () => {
+      expect(
+        resolveCanonicalUrl({
+          siteBaseUrl: "https://example.com",
+          pageSlug: "about",
+          override: null,
+          pageUrlStyle: "no-extension",
+        }),
+      ).toBe("https://example.com/about");
+    });
+
+    it("keeps the root URL for the home page", () => {
+      expect(
+        resolveCanonicalUrl({
+          siteBaseUrl: "https://example.com",
+          pageSlug: "home",
+          override: null,
+          pageUrlStyle: "no-extension",
+        }),
+      ).toBe("https://example.com/");
+    });
+
+    it("default style preserves pre-v0.2.85 trailing-slash behavior", () => {
+      expect(
+        resolveCanonicalUrl({
+          siteBaseUrl: "https://example.com",
+          pageSlug: "about",
+          override: null,
+        }),
+      ).toBe("https://example.com/about/");
+    });
+  });
+});
+
+describe("renderSeoHead", () => {
+  const base = {
+    title: "Welcome",
+    metaDescription: "A sample description.",
+    canonical: "https://example.com/",
+    noindex: false,
+    ogImageUrl: null,
+    organization: {},
+  };
+
+  it("emits canonical + og:type + og:url for the simplest valid input", () => {
+    const head = renderSeoHead(base);
+    expect(head).toContain("<title>Welcome</title>");
+    expect(head).toContain('<meta name="description" content="A sample description." />');
+    expect(head).toContain('<link rel="canonical" href="https://example.com/" />');
+    expect(head).toContain('<meta property="og:type" content="website" />');
+    expect(head).toContain('<meta property="og:url" content="https://example.com/" />');
+  });
+
+  it("emits noindex meta only when set", () => {
+    expect(renderSeoHead(base)).not.toContain('content="noindex"');
+    expect(renderSeoHead({ ...base, noindex: true })).toContain(
+      '<meta name="robots" content="noindex" />',
+    );
+  });
+
+  it("emits og:image and twitter summary_large_image when provided", () => {
+    const head = renderSeoHead({ ...base, ogImageUrl: "https://example.com/_assets/x/orig.png" });
+    expect(head).toContain(
+      '<meta property="og:image" content="https://example.com/_assets/x/orig.png" />',
+    );
+    expect(head).toContain('<meta name="twitter:card" content="summary_large_image" />');
+  });
+
+  it("emits a JSON-LD WebPage block; encodes the < character to avoid script-tag breaks", () => {
+    const head = renderSeoHead({
+      ...base,
+      title: "Tag <foo>",
+      organization: { name: "Caelo Inc.", url: "https://caelo.example" },
+    });
+    expect(head).toContain('<script type="application/ld+json">');
+    expect(head).not.toContain("<foo>"); // angle bracket inside script ld+json should be escaped
+    expect(head).toContain('"publisher"');
+    expect(head).toContain('"Caelo Inc."');
+  });
+
+  it("HTML-encodes attribute values to block injection", () => {
+    const head = renderSeoHead({
+      ...base,
+      title: 'Quote "test"',
+      metaDescription: "<script>alert(1)</script>",
+    });
+    expect(head).toContain('content="Quote &quot;test&quot;"');
+    expect(head).toContain("&lt;script&gt;alert(1)&lt;/script&gt;");
+  });
+});
+
+describe("injectSeoIntoHead", () => {
+  it("strips a layout-supplied <title> and injects the head block before </head>", () => {
+    const html = "<html><head><title>OldTitle</title></head><body>x</body></html>";
+    const out = injectSeoIntoHead(html, "<title>NewTitle</title>");
+    expect(out).not.toContain("OldTitle");
+    expect(out).toContain("NewTitle");
+    expect(out.indexOf("NewTitle")).toBeLessThan(out.indexOf("</head>"));
+  });
+
+  it("falls back to prepending when the document has no </head>", () => {
+    expect(injectSeoIntoHead("<body>x</body>", "<title>X</title>")).toContain("<title>X</title>");
+  });
+});
+
+describe("schemas", () => {
+  it("seoAutofillInputSchema rejects empty meta description", () => {
+    const r = seoAutofillInputSchema.safeParse({
+      pageId: "11111111-1111-4111-8111-111111111111",
+      metaDescription: "",
+    });
+    expect(r.success).toBe(false);
+  });
+
+  it("seoOptimizeInputSchema accepts context near the cap", () => {
+    const r = seoOptimizeInputSchema.safeParse({
+      pageId: "11111111-1111-4111-8111-111111111111",
+      metaDescription: "A description.",
+      context: "x".repeat(3500),
+    });
+    expect(r.success).toBe(true);
+  });
+
+  it("seoOptimizeInputSchema rejects context above the cap", () => {
+    const r = seoOptimizeInputSchema.safeParse({
+      pageId: "11111111-1111-4111-8111-111111111111",
+      metaDescription: "A description.",
+      context: "x".repeat(4001),
+    });
+    expect(r.success).toBe(false);
+  });
+
+  it("seoSetInputSchema rejects priority above 1", () => {
+    const r = seoSetInputSchema.safeParse({
+      pageId: "11111111-1111-4111-8111-111111111111",
+      priority: 1.1,
+    });
+    expect(r.success).toBe(false);
+  });
+
+  it("siteDefaultsSetSeoInputSchema rejects non-URL siteBaseUrl", () => {
+    const r = siteDefaultsSetSeoInputSchema.safeParse({
+      siteBaseUrl: "not a url",
+      sitemapEnabled: true,
+      organizationJson: {},
+    });
+    expect(r.success).toBe(false);
+  });
+});

package/src/seo.ts

@@ -0,0 +1,233 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Phase 8 — SEO primitives. Per-page SEO is structured fields only;
+ * the renderer projects them into <head> meta + canonical + JSON-LD.
+ * Per CLAUDE.md §2 "no raw HTML into <head>" — every Zod schema below
+ * is on `.strict()` so the AI cannot smuggle additional keys.
+ */
+
+import { z } from "zod";
+import { isHomeSlug } from "./i18n.js";
+
+export const CHANGEFREQ_VALUES = [
+  "always",
+  "hourly",
+  "daily",
+  "weekly",
+  "monthly",
+  "yearly",
+  "never",
+] as const;
+export type Changefreq = (typeof CHANGEFREQ_VALUES)[number];
+
+/** Recommended length caps — server enforces, client trims with feedback. */
+export const SEO_TITLE_RECOMMENDED_MAX = 60;
+export const SEO_DESCRIPTION_RECOMMENDED_MAX = 160;
+
+export const SEO_DESCRIPTION_HARD_MAX = 320;
+export const SEO_CANONICAL_MAX = 2048;
+
+export const seoSetInputSchema = z
+  .object({
+    pageId: z.string().uuid(),
+    metaDescription: z.string().max(SEO_DESCRIPTION_HARD_MAX).optional(),
+    ogImageAssetId: z.string().uuid().nullable().optional(),
+    canonicalUrl: z.string().max(SEO_CANONICAL_MAX).nullable().optional(),
+    noindex: z.boolean().optional(),
+    changefreq: z.enum(CHANGEFREQ_VALUES).optional(),
+    priority: z.number().min(0).max(1).optional(),
+  })
+  .strict();
+export type SeoSetInput = z.infer<typeof seoSetInputSchema>;
+
+export const seoAutofillInputSchema = z
+  .object({
+    pageId: z.string().uuid(),
+    metaDescription: z.string().min(1).max(SEO_DESCRIPTION_HARD_MAX),
+    ogImageAssetId: z.string().uuid().nullable().optional(),
+  })
+  .strict();
+export type SeoAutofillInput = z.infer<typeof seoAutofillInputSchema>;
+
+export const seoOptimizeInputSchema = z
+  .object({
+    pageId: z.string().uuid(),
+    metaDescription: z.string().min(1).max(SEO_DESCRIPTION_HARD_MAX),
+    ogImageAssetId: z.string().uuid().nullable().optional(),
+    /** Optional user-supplied context (keyword research, intent shifts) recorded in audit. */
+    context: z.string().max(4000).optional(),
+  })
+  .strict();
+export type SeoOptimizeInput = z.infer<typeof seoOptimizeInputSchema>;
+
+export const siteDefaultsSetSeoInputSchema = z
+  .object({
+    siteBaseUrl: z
+      .string()
+      .min(1)
+      .max(2048)
+      .url("siteBaseUrl must be an absolute URL (https://example.com)"),
+    sitemapEnabled: z.boolean(),
+    organizationJson: z
+      .object({
+        name: z.string().max(256).optional(),
+        url: z.string().max(2048).optional(),
+        logo: z.string().max(2048).optional(),
+        sameAs: z.array(z.string().max(2048)).max(20).optional(),
+      })
+      .strict()
+      .default({}),
+  })
+  .strict();
+export type SiteDefaultsSetSeoInput = z.infer<typeof siteDefaultsSetSeoInputSchema>;
+
+export interface PageSeoRow {
+  pageId: string;
+  metaDescription: string;
+  ogImageAssetId: string | null;
+  canonicalUrl: string | null;
+  noindex: boolean;
+  changefreq: Changefreq;
+  priority: number;
+  autofilledAt: string | null;
+  optimizedAt: string | null;
+  updatedAt: string;
+}
+
+export interface SiteSeoSettings {
+  siteBaseUrl: string;
+  sitemapEnabled: boolean;
+  organization: {
+    name?: string;
+    url?: string;
+    logo?: string;
+    sameAs?: string[];
+  };
+}
+
+/**
+ * Resolve the canonical URL for a page. If `pages_seo.canonical_url`
+ * is set it wins; otherwise build `<siteBaseUrl>/<slug>` (home pages
+ * canonicalize to the bare base URL). URL shaping beyond base + slug
+ * becomes a plugin contribution on the URL composition point (#390).
+ */
+export function resolveCanonicalUrl(args: {
+  siteBaseUrl: string;
+  pageSlug: string;
+  override: string | null;
+  /**
+   * v0.2.85 — page emission style. 'directory' (default) → URLs end
+   * in `/<slug>/`; 'no-extension' → URLs end in `/<slug>` (no
+   * trailing slash) to match what the bucket actually serves when
+   * pages are emitted as bare slugs.
+   */
+  pageUrlStyle?: "directory" | "no-extension";
+  /**
+   * 0184 — explicit homepage designation. When true this page IS the
+   * site root and canonicalizes to `<base>/` regardless of its slug.
+   * Uses the same predicate (`isHomeSlug`) as the magic-slug fallback
+   * so canonical agrees with the emitted output path.
+   */
+  isHomePage?: boolean;
+}): string {
+  if (args.override && args.override.length > 0) return args.override;
+  const base = args.siteBaseUrl.replace(/\/$/, "");
+  const isHome = args.isHomePage === true || isHomeSlug(args.pageSlug);
+  const cleanSlug = isHome ? "" : args.pageSlug;
+  const style = args.pageUrlStyle ?? "directory";
+  // Tail = the slug portion of the canonical URL, with the trailing
+  // shape dictated by the page-emission style. Home pages always
+  // resolve to the base URL (no tail) regardless of style.
+  const tail = cleanSlug ? (style === "no-extension" ? cleanSlug : `${cleanSlug}/`) : "";
+  return tail ? `${base}/${tail}` : `${base}/`;
+}
+
+export interface SeoMetaInput {
+  title: string;
+  metaDescription: string;
+  canonical: string;
+  noindex: boolean;
+  ogImageUrl: string | null;
+  organization: SiteSeoSettings["organization"];
+}
+
+/**
+ * Render the <head> meta block for a page. Returns the HTML string
+ * the renderer injects just before </head>. Order is canonical
+ * (W3C-recommended): charset / viewport stay in the layout; meta
+ * description + canonical + robots + Open Graph + Twitter card +
+ * JSON-LD.
+ *
+ * No raw HTML escape hatch — every variable is HTML-attribute-encoded.
+ */
+export function renderSeoHead(input: SeoMetaInput): string {
+  const enc = (s: string): string =>
+    s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+
+  const lines: string[] = [];
+  lines.push(`<title>${enc(input.title)}</title>`);
+  if (input.metaDescription) {
+    lines.push(`<meta name="description" content="${enc(input.metaDescription)}" />`);
+  }
+  lines.push(`<link rel="canonical" href="${enc(input.canonical)}" />`);
+  if (input.noindex) {
+    lines.push(`<meta name="robots" content="noindex" />`);
+  }
+  // Open Graph
+  lines.push(`<meta property="og:title" content="${enc(input.title)}" />`);
+  if (input.metaDescription) {
+    lines.push(`<meta property="og:description" content="${enc(input.metaDescription)}" />`);
+  }
+  lines.push(`<meta property="og:type" content="website" />`);
+  lines.push(`<meta property="og:url" content="${enc(input.canonical)}" />`);
+  if (input.ogImageUrl) {
+    lines.push(`<meta property="og:image" content="${enc(input.ogImageUrl)}" />`);
+  }
+  // Twitter card
+  lines.push(
+    `<meta name="twitter:card" content="${input.ogImageUrl ? "summary_large_image" : "summary"}" />`,
+  );
+  // JSON-LD WebPage block referencing the Organization (when set).
+  const ld: Record<string, unknown> = {
+    "@context": "https://schema.org",
+    "@type": "WebPage",
+    name: input.title,
+    url: input.canonical,
+  };
+  if (input.metaDescription) ld.description = input.metaDescription;
+  if (input.ogImageUrl) ld.image = input.ogImageUrl;
+  if (input.organization.name) {
+    ld.publisher = {
+      "@type": "Organization",
+      name: input.organization.name,
+      ...(input.organization.url ? { url: input.organization.url } : {}),
+      ...(input.organization.logo
+        ? { logo: { "@type": "ImageObject", url: input.organization.logo } }
+        : {}),
+      ...(input.organization.sameAs?.length ? { sameAs: input.organization.sameAs } : {}),
+    };
+  }
+  lines.push(
+    `<script type="application/ld+json">${JSON.stringify(ld).replace(/</g, "\\u003c")}</script>`,
+  );
+  return lines.join("\n");
+}
+
+/**
+ * Inject `renderSeoHead`'s output just before `</head>`. Replaces any
+ * existing `<title>` so the page-level title wins over a layout-
+ * supplied default. Pre-existing meta tags from the layout are left
+ * alone — authors can still drop e.g. `<meta name="theme-color">` in
+ * the layout HTML.
+ */
+export function injectSeoIntoHead(html: string, headBlock: string): string {
+  // Strip a layout-supplied <title> if present; we'll re-emit it in
+  // the headBlock at the right position.
+  const titleStripped = html.replace(/<title\b[^>]*>[\s\S]*?<\/title>/i, "");
+  if (titleStripped.includes("</head>")) {
+    return titleStripped.replace("</head>", `${headBlock}\n</head>`);
+  }
+  // No closing head tag — prepend the block to the document.
+  return `${headBlock}\n${titleStripped}`;
+}

package/src/skills.ts

@@ -0,0 +1,48 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Skill metadata shapes shared across the Query API + chat-runner.
+ *
+ * Skills use PROGRESSIVE DISCLOSURE (the Anthropic Agent Skills shape): a
+ * static `## Skills` index (slug + description) sits in the cached system
+ * prompt, and the model pulls a skill's full body into the conversation on
+ * demand via the `load_skill` tool (its body then lives in the append-only
+ * message history for the rest of the chat).
+ *
+ * `skillAutoEngagementHints` no longer drives SELECTION — the model
+ * self-selects from the descriptions. The hints now only shape how prominently
+ * a skill is presented in the index: `alwaysOn` skills get an "always applies"
+ * callout, `chipTrigger` skills a "when element chips are attached" callout.
+ * (The old keyword/chip/always-on MATCHER + engagement resolver were removed
+ * once progressive disclosure replaced them.)
+ */
+
+import { z } from "zod";
+
+export const skillAutoEngagementHints = z
+  .object({
+    /**
+     * Lowercase substrings that once boosted the auto-matcher. The matcher is
+     * gone (progressive disclosure); retained in the schema so seeded rows that
+     * still carry keywords parse under `.strict()`. No runtime effect today.
+     */
+    keywords: z.array(z.string().min(1).max(80)).default([]),
+    /** Listed under the index's "when element chips are attached" callout. */
+    chipTrigger: z.boolean().default(false),
+    /** Listed under the index's "always applies" callout (e.g. brand-voice-guard). */
+    alwaysOn: z.boolean().default(false),
+  })
+  .strict();
+export type SkillAutoEngagementHints = z.infer<typeof skillAutoEngagementHints>;
+
+/** How a loaded skill came to be engaged this chat. */
+export type EngagementSource = "auto" | "manual" | "pinned";
+
+/** A skill the model has loaded (via load_skill) in the current chat. */
+export interface ChatEngagement {
+  readonly skillId: string;
+  readonly slug: string;
+  readonly displayName: string;
+  readonly source: EngagementSource;
+  readonly rationale: string;
+}

package/src/snapshots.test.ts

@@ -0,0 +1,80 @@
+// SPDX-License-Identifier: MPL-2.0
+
+import { describe, expect, it } from "bun:test";
+import {
+  moduleImpactInput,
+  revertModuleInput,
+  revertPageInput,
+  revertSiteInput,
+  revertTemplateInput,
+  snapshotGetInput,
+  snapshotsListInput,
+} from "./snapshots.js";
+
+const UUID = "11111111-1111-4111-8111-111111111111";
+const UUID_2 = "22222222-2222-4222-8222-222222222222";
+
+describe("snapshotsListInput", () => {
+  it("defaults limit to 50 when omitted", () => {
+    const r = snapshotsListInput.safeParse({});
+    expect(r.success).toBe(true);
+    if (!r.success) return;
+    expect(r.data.limit).toBe(50);
+  });
+
+  it("rejects unknown keys (strict)", () => {
+    const r = snapshotsListInput.safeParse({ limit: 10, unexpected: 1 });
+    expect(r.success).toBe(false);
+  });
+
+  it("clamps limit between 1 and 200", () => {
+    expect(snapshotsListInput.safeParse({ limit: 0 }).success).toBe(false);
+    expect(snapshotsListInput.safeParse({ limit: 201 }).success).toBe(false);
+    expect(snapshotsListInput.safeParse({ limit: 200 }).success).toBe(true);
+  });
+
+  it("accepts an ISO timestamp for `before`", () => {
+    const r = snapshotsListInput.safeParse({ before: "2026-04-26T10:00:00.000Z" });
+    expect(r.success).toBe(true);
+  });
+});
+
+describe("revert input schemas", () => {
+  it("revertSiteInput requires a uuid snapshotId", () => {
+    expect(revertSiteInput.safeParse({ snapshotId: UUID }).success).toBe(true);
+    expect(revertSiteInput.safeParse({ snapshotId: "not-a-uuid" }).success).toBe(false);
+  });
+
+  it("revertModuleInput requires both moduleId and snapshotId", () => {
+    expect(revertModuleInput.safeParse({ moduleId: UUID, snapshotId: UUID_2 }).success).toBe(true);
+    expect(revertModuleInput.safeParse({ moduleId: UUID }).success).toBe(false);
+  });
+
+  it("rejects unknown keys on revertPageInput", () => {
+    const r = revertPageInput.safeParse({
+      pageId: UUID,
+      snapshotId: UUID_2,
+      extra: "noop",
+    });
+    expect(r.success).toBe(false);
+  });
+
+  it("revertTemplateInput rejects an unknown key", () => {
+    const r = revertTemplateInput.safeParse({
+      templateId: UUID,
+      snapshotId: UUID_2,
+      extra: 1,
+    });
+    expect(r.success).toBe(false);
+  });
+});
+
+describe("get / impact inputs", () => {
+  it("snapshotGetInput accepts a uuid", () => {
+    expect(snapshotGetInput.safeParse({ snapshotId: UUID }).success).toBe(true);
+  });
+  it("moduleImpactInput accepts a uuid and rejects other keys", () => {
+    expect(moduleImpactInput.safeParse({ moduleId: UUID }).success).toBe(true);
+    expect(moduleImpactInput.safeParse({ moduleId: UUID, foo: 1 }).success).toBe(false);
+  });
+});

package/src/snapshots.ts

@@ -0,0 +1,81 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Zod input schemas for the P4 snapshot ops. Lives in @caelo-cms/shared so that
+ * route actions and the ops themselves import from a single source — same
+ * pattern as packages/shared/src/content.ts for P3.
+ *
+ * Every schema is `.strict()` so unknown keys are rejected at the Validator
+ * before the handler runs. Snapshot state JSONB is *not* validated by Zod
+ * here — it is emitted by trusted ops, never user-supplied (see CMS plan
+ * §"Validator rules").
+ */
+
+import { z } from "zod";
+
+export const snapshotsListInput = z
+  .object({
+    /** ISO timestamp; only snapshots strictly before this are returned. */
+    before: z.string().datetime().optional(),
+    limit: z.number().int().min(1).max(200).default(50),
+    /** When set, only snapshots that touched this module are returned. */
+    forModuleId: z.string().uuid().optional(),
+    /** When set, only snapshots that touched this page (metadata or layout). */
+    forPageId: z.string().uuid().optional(),
+    /** When set, only snapshots that touched this template (incl. block changes). */
+    forTemplateId: z.string().uuid().optional(),
+    /** When set, only snapshots whose op_kind matches one of these values. */
+    opKinds: z.array(z.string()).optional(),
+    /** When true, archived snapshots are also returned. Defaults to false. */
+    includeArchived: z.boolean().default(false),
+    /** v0.6.0 — only snapshots tagged with this chat's branch are returned.
+     * Used by `revert_chat_changes` to enumerate everything one chat did
+     * without scanning the full timeline. */
+    forChatBranchId: z.string().uuid().optional(),
+  })
+  .strict();
+
+export const archiveOlderThanInput = z
+  .object({
+    /** ISO timestamp; snapshots with `created_at < before` get archived_at set. */
+    before: z.string().datetime(),
+    /** Hard cap to keep one call from updating the whole table by mistake. */
+    limit: z.number().int().min(1).max(10_000).default(1000),
+  })
+  .strict();
+export type ArchiveOlderThanInput = z.infer<typeof archiveOlderThanInput>;
+
+export const snapshotGetInput = z.object({ snapshotId: z.string().uuid() }).strict();
+
+export const moduleImpactInput = z.object({ moduleId: z.string().uuid() }).strict();
+
+export const revertSiteInput = z.object({ snapshotId: z.string().uuid() }).strict();
+
+export const revertModuleInput = z
+  .object({
+    moduleId: z.string().uuid(),
+    snapshotId: z.string().uuid(),
+  })
+  .strict();
+
+export const revertTemplateInput = z
+  .object({
+    templateId: z.string().uuid(),
+    snapshotId: z.string().uuid(),
+  })
+  .strict();
+
+export const revertPageInput = z
+  .object({
+    pageId: z.string().uuid(),
+    snapshotId: z.string().uuid(),
+  })
+  .strict();
+
+export type SnapshotsListInput = z.infer<typeof snapshotsListInput>;
+export type SnapshotGetInput = z.infer<typeof snapshotGetInput>;
+export type ModuleImpactInput = z.infer<typeof moduleImpactInput>;
+export type RevertSiteInput = z.infer<typeof revertSiteInput>;
+export type RevertModuleInput = z.infer<typeof revertModuleInput>;
+export type RevertTemplateInput = z.infer<typeof revertTemplateInput>;
+export type RevertPageInput = z.infer<typeof revertPageInput>;