@caelo-cms/shared 0.10.22 → 0.10.23

package/src/auth-forms.ts

@@ -0,0 +1,36 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * P6.6 closing pass — Zod schemas for the auth-side forms (setup,
+ * login). Lives in @caelo-cms/shared so the SvelteKit route's inline
+ * client-side validation helper (`bindZodForm`) and the server-side
+ * `users.create_first_owner` / `auth.login` handlers can both
+ * consume the same source-of-truth.
+ *
+ * Kept separate from `content.ts` because auth shape is independent
+ * of content-layer evolution; bumping a min-password requirement here
+ * shouldn't churn the page schemas.
+ */
+
+import { z } from "zod";
+
+export const setupFormSchema = z
+  .object({
+    displayName: z.string().min(1, "required").max(128),
+    email: z.string().email("must be a valid email").max(254),
+    // Client-side floor mirrors the server strength policy's length rule
+    // (validatePasswordStrength / MIN_PASSWORD_LENGTH); the server also checks
+    // common-list, sequences and personal-info and returns the real reason.
+    password: z.string().min(10, "at least 10 characters").max(256),
+  })
+  .strict();
+
+export const loginFormSchema = z
+  .object({
+    email: z.string().email("must be a valid email").max(254),
+    password: z.string().min(1, "required").max(256),
+  })
+  .strict();
+
+export type SetupFormInput = z.infer<typeof setupFormSchema>;
+export type LoginFormInput = z.infer<typeof loginFormSchema>;

package/src/base-css.ts

@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * issue #151 (re-scoped, epic #149) — the INVISIBLE technical baseline.
+ *
+ * Deliberately carries ZERO visible design opinion: no type scale, no
+ * colors, no element styling — every visible default is compiled per
+ * site from that site's chosen design (#164), because a global look
+ * would homogenize Caelo sites (the operator explicitly rejected that).
+ *
+ * What remains is the technical floor every hand-built page and every
+ * Genesis draft silently assumes, and whose absence produces the
+ * "subtly broken" rendering class from the epic review:
+ *
+ *   - border-box sizing (the universal expectation since ~2013);
+ *   - no default body margin (the 8px UA gutter breaks full-bleed
+ *     heroes on every design);
+ *   - media elements can't overflow their container (mobile-first
+ *     drafts assume it);
+ *   - form controls inherit the page's font instead of UA chrome.
+ *
+ * Injected as `<style data-source="base">` between the theme vars and
+ * the aggregated module CSS, so any module rule overrides it trivially.
+ */
+
+export const BASE_TECHNICAL_CSS =
+  "*,*::before,*::after{box-sizing:border-box}" +
+  "body{margin:0}" +
+  "img,picture,video,canvas,svg{display:block;max-width:100%}" +
+  "input,button,textarea,select{font:inherit}";

package/src/build-page.test.ts

@@ -0,0 +1,228 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Issue #299 — input-schema tests for the bulk build path. The contract
+ * under test: invalid entries fail LOUD with the failing element's index
+ * in the Zod path (so the dispatcher's error names `modules[i]` /
+ * `instances[i]`), and the mode gates (page: pageId XOR slug+title;
+ * module: moduleId XOR displayName+html) reject ambiguous calls.
+ */
+
+import { describe, expect, it } from "bun:test";
+import {
+  buildPageContentSchema,
+  buildPageInputSchema,
+  contentInstancesCreateManySchema,
+  pageModuleContentSetManySchema,
+} from "./build-page.js";
+
+// Zod 4's .uuid() enforces RFC 4122 version/variant bits — use real
+// v4-shaped constants, not sequential zero-padded strings.
+const UUID = "11111111-1111-4111-8111-111111111111";
+const UUID2 = "22222222-2222-4222-8222-222222222222";
+
+const mintModule = {
+  blockName: "content",
+  displayName: "Hero",
+  html: "<section><h1>{{hero_title}}</h1></section>",
+  description: "Homepage hero",
+  kind: "hero",
+  fields: [{ name: "hero_title", kind: "text", label: "Hero title" }],
+} as const;
+
+describe("buildPageInputSchema — page target modes", () => {
+  it("accepts create mode (slug + title) with defaults applied downstream", () => {
+    const r = buildPageInputSchema.safeParse({
+      page: { slug: "pricing", title: "Pricing" },
+      modules: [mintModule],
+    });
+    expect(r.success).toBe(true);
+  });
+
+  it("accepts existing mode (pageId only)", () => {
+    const r = buildPageInputSchema.safeParse({
+      page: { pageId: UUID },
+      modules: [{ blockName: "content", moduleId: UUID2 }],
+    });
+    expect(r.success).toBe(true);
+  });
+
+  it("rejects pageId mixed with create keys, naming the offending keys", () => {
+    const r = buildPageInputSchema.safeParse({
+      page: { pageId: UUID, slug: "pricing", title: "Pricing" },
+      modules: [mintModule],
+    });
+    expect(r.success).toBe(false);
+    if (r.success) return;
+    const issue = r.error.issues[0]!;
+    expect(issue.message).toContain("pageId targets an EXISTING page");
+    expect(issue.message).toContain("slug");
+    expect(issue.message).toContain("title");
+  });
+
+  it("rejects a page target with neither pageId nor slug+title", () => {
+    const r = buildPageInputSchema.safeParse({
+      page: { slug: "pricing" },
+      modules: [mintModule],
+    });
+    expect(r.success).toBe(false);
+    if (r.success) return;
+    expect(r.error.issues[0]!.message).toContain("`slug` + `title`");
+  });
+});
+
+describe("buildPageInputSchema — module entry modes name the failing index", () => {
+  it("TOLERATES a moduleId entry carrying authoring keys (incl. structural) — placement-only, handler surfaces the ignored-authoring info", () => {
+    // §1A/§11 — a placement that CAN succeed must never fail over an extra
+    // field. moduleId + html + displayName is a valid placement; the handler
+    // (not the schema) reports which carried fields were not applied.
+    const r = buildPageInputSchema.safeParse({
+      page: { slug: "pricing", title: "Pricing" },
+      modules: [
+        mintModule,
+        { blockName: "content", moduleId: UUID2, html: "<p>x</p>", displayName: "Dup" },
+      ],
+    });
+    expect(r.success).toBe(true);
+  });
+
+  it("TOLERATES a moduleId entry carrying only metadata (displayName) — the handler ignores it", () => {
+    const r = buildPageInputSchema.safeParse({
+      page: { slug: "pricing", title: "Pricing" },
+      modules: [{ blockName: "content", moduleId: UUID2, displayName: "Site Header" }],
+    });
+    expect(r.success).toBe(true);
+  });
+
+  it("rejects an entry with neither moduleId nor displayName+html, at its index", () => {
+    const r = buildPageInputSchema.safeParse({
+      page: { slug: "pricing", title: "Pricing" },
+      modules: [mintModule, mintModule, { blockName: "content" }],
+    });
+    expect(r.success).toBe(false);
+    if (r.success) return;
+    const issue = r.error.issues.find((i) => i.message.includes("Pass either `moduleId`"));
+    expect(issue).toBeDefined();
+    expect(issue!.path[0]).toBe("modules");
+    expect(issue!.path[1]).toBe(2);
+  });
+
+  it("list-shaped field kinds are representable (CLAUDE.md §1A — no numbered scalars)", () => {
+    const r = buildPageInputSchema.safeParse({
+      page: { slug: "p", title: "P" },
+      modules: [
+        {
+          blockName: "content",
+          displayName: "Nav",
+          html: "<nav>{{#nav_links}}<a href='{{href}}'>{{label}}</a>{{/nav_links}}</nav>",
+          fields: [
+            { name: "nav_links", kind: "link-list", label: "Nav links" },
+            { name: "tags", kind: "text-list", label: "Tags", min: 0, max: 12 },
+          ],
+        },
+      ],
+    });
+    expect(r.success).toBe(true);
+  });
+
+  it("caps the batch at 40 modules", () => {
+    const r = buildPageInputSchema.safeParse({
+      page: { slug: "p", title: "P" },
+      modules: Array.from({ length: 41 }, () => mintModule),
+    });
+    expect(r.success).toBe(false);
+  });
+});
+
+describe("buildPageContentSchema — the three sources", () => {
+  it("inline requires values", () => {
+    expect(buildPageContentSchema.safeParse({ source: "inline" }).success).toBe(false);
+    expect(
+      buildPageContentSchema.safeParse({ source: "inline", values: { hero_title: "x" } }).success,
+    ).toBe(true);
+  });
+
+  it("shared requires purpose and defaults syncMode to synced", () => {
+    const missing = buildPageContentSchema.safeParse({ source: "shared", values: {} });
+    expect(missing.success).toBe(false);
+    const r = buildPageContentSchema.safeParse({
+      source: "shared",
+      purpose: "Footer CTA shared across product pages",
+      values: { cta_label: "Go" },
+    });
+    expect(r.success).toBe(true);
+    if (!r.success || r.data.source !== "shared") return;
+    expect(r.data.syncMode).toBe("synced");
+  });
+
+  it("existing requires contentInstanceId and defaults syncMode to synced", () => {
+    const r = buildPageContentSchema.safeParse({ source: "existing", contentInstanceId: UUID });
+    expect(r.success).toBe(true);
+    if (!r.success || r.data.source !== "existing") return;
+    expect(r.data.syncMode).toBe("synced");
+  });
+
+  it("rejects cross-variant keys (purpose on inline)", () => {
+    const r = buildPageContentSchema.safeParse({
+      source: "inline",
+      values: {},
+      purpose: "nope",
+    });
+    expect(r.success).toBe(false);
+  });
+});
+
+describe("contentInstancesCreateManySchema", () => {
+  it("accepts a batch of singular-shaped items", () => {
+    const r = contentInstancesCreateManySchema.safeParse({
+      instances: [
+        { moduleId: UUID, values: { a: 1 } },
+        { moduleId: UUID2, purpose: "shared cta", values: {} },
+      ],
+    });
+    expect(r.success).toBe(true);
+  });
+
+  it("names the failing item index in the Zod path", () => {
+    const r = contentInstancesCreateManySchema.safeParse({
+      instances: [{ moduleId: UUID }, { moduleId: "not-a-uuid" }],
+    });
+    expect(r.success).toBe(false);
+    if (r.success) return;
+    const issue = r.error.issues[0]!;
+    expect(issue.path[0]).toBe("instances");
+    expect(issue.path[1]).toBe(1);
+    expect(issue.path[2]).toBe("moduleId");
+  });
+
+  it("rejects an empty batch", () => {
+    expect(contentInstancesCreateManySchema.safeParse({ instances: [] }).success).toBe(false);
+  });
+});
+
+describe("pageModuleContentSetManySchema", () => {
+  it("accepts multi-page batches", () => {
+    const r = pageModuleContentSetManySchema.safeParse({
+      items: [
+        { pageId: UUID, blockName: "content", position: 0, contentValues: { t: "x" } },
+        { pageId: UUID2, blockName: "content", position: 3, contentValues: {} },
+      ],
+    });
+    expect(r.success).toBe(true);
+  });
+
+  it("names the failing item index + field in the Zod path", () => {
+    const r = pageModuleContentSetManySchema.safeParse({
+      items: [
+        { pageId: UUID, blockName: "content", position: 0, contentValues: {} },
+        { pageId: UUID, blockName: "content", position: -1, contentValues: {} },
+      ],
+    });
+    expect(r.success).toBe(false);
+    if (r.success) return;
+    const issue = r.error.issues[0]!;
+    expect(issue.path[0]).toBe("items");
+    expect(issue.path[1]).toBe(1);
+    expect(issue.path[2]).toBe("position");
+  });
+});

package/src/build-page.ts

@@ -0,0 +1,319 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Issue #299 — bulk build-path schemas (CLAUDE.md §11 bulk-first).
+ *
+ * Run #15 telemetry showed the AI assembling ~14 pages through ~100
+ * singular round-trips (36× add_module_to_page, 29× set_page_module_content,
+ * 9× create_content_instance, 8× create_page) at 110K–556K input tokens
+ * per call. These schemas back the three ops that collapse that chain:
+ *
+ *   - `pages.build_page`                — ONE call: page (new or existing)
+ *     + ordered modules + content instances + placements, one transaction.
+ *   - `content_instances.create_many`   — batch instance minting.
+ *   - `page_module_content.set_many`    — batch content fill on existing
+ *     placements.
+ *
+ * All three are all-or-nothing: any validation error aborts the whole
+ * call with a message naming the failing element index (and field where
+ * one is involved), so partial failure is impossible (§11).
+ */
+
+import { z } from "zod";
+import {
+  contentInstanceCreateSchema,
+  localeSchema,
+  MODULE_CSS_MAX,
+  MODULE_HTML_MAX,
+  MODULE_JS_MAX,
+  moduleFieldSchema,
+  moduleKindSchema,
+  pageStatusSchema,
+  slugSchema,
+  syncModeSchema,
+} from "./content.js";
+
+/** Content values keyed by the module's declared field names. */
+const contentValuesSchema = z.record(z.string(), z.unknown());
+
+/**
+ * Per-module content payload — a discriminated union mirroring the three
+ * existing content paths so build_page adds NO new semantics, only batching:
+ *
+ *   - `inline`   → mint a private (unsynced) content_instance carrying
+ *     `values`, exactly what `set_page_module_content` produces for a
+ *     fresh placement.
+ *   - `shared`   → mint a reusable content_instance (purpose required —
+ *     same decision-support contract as `create_content_instance`) and
+ *     bind this placement to it, `synced` by default.
+ *   - `existing` → bind an already-minted content_instance (reuse-first
+ *     per CLAUDE.md §1A) — the batched form of `set_placement_content`.
+ *
+ * Omitting `content` mints an empty unsynced instance, matching what
+ * `pages.set_modules` does for a net-new placement today.
+ */
+export const buildPageContentSchema = z.discriminatedUnion("source", [
+  z
+    .object({
+      source: z.literal("inline"),
+      values: contentValuesSchema,
+    })
+    .strict(),
+  z
+    .object({
+      source: z.literal("shared"),
+      values: contentValuesSchema.default({}),
+      /** Why this row exists as a shared instance — see CLAUDE.md §1A. */
+      purpose: z.string().min(1).max(1000),
+      slug: slugSchema.optional(),
+      displayName: z.string().min(1).max(128).optional(),
+      syncMode: syncModeSchema.default("synced"),
+    })
+    .strict(),
+  z
+    .object({
+      source: z.literal("existing"),
+      contentInstanceId: z.string().uuid(),
+      syncMode: syncModeSchema.default("synced"),
+    })
+    .strict(),
+]);
+export type BuildPageContent = z.infer<typeof buildPageContentSchema>;
+
+/**
+ * One module entry in a build_page call. Two modes per entry, identical
+ * to `add_module_to_page` (issue #159):
+ *
+ *   - **Mint mode** — `displayName` + `html` (+ `fields`, `description`,
+ *     `kind`, `type`, `css`, `js`). The op creates the module through the
+ *     same `modules.create` path (extractor fallback, type derivation,
+ *     snapshot) the singular tool uses.
+ *   - **Place mode** — `moduleId` of an existing module. Placement-only:
+ *     extra authoring keys are TOLERATED (§1A/§11 — a placement that can
+ *     succeed must not fail over an extra field) but NOT applied; the op
+ *     surfaces an info naming any carried field whose value differs from the
+ *     module's stored one, pointing at edit_module (§2 — no silent drop).
+ *
+ * The element-level superRefine reports issues WITH the element's array
+ * index in the Zod path, so a mode error fails as `modules[3]: …`.
+ */
+export const buildPageModuleSchema = z
+  .object({
+    /**
+     * Template block to place into — must exist on the page's template.
+     * OMIT for a DETACHED entry: the module + its content_instance are
+     * created but NOT placed on the page — used for nested-only modules
+     * that later entries embed via `{"$ref": "<ref>"}` in a
+     * module / module-list field value. A detached entry requires `ref`.
+     */
+    blockName: slugSchema.optional(),
+    /**
+     * Local handle other entries in the SAME call can reference: a
+     * module/module-list field value of `{"$ref": "<ref>"}` resolves to
+     * this entry's `{moduleId, contentInstanceId}`. Entries resolve in
+     * array order, so referenced entries must come FIRST.
+     */
+    ref: z
+      .string()
+      .regex(/^[a-z][a-z0-9_-]{0,31}$/, "ref must be a short lowercase handle")
+      .optional(),
+    /**
+     * Place mode: an existing module from `## Modules` (UUID), or a
+     * module minted EARLIER IN THIS CALL via `{"$ref": "<handle>"}` —
+     * the second-placement case (e.g. three feature cards reusing one
+     * card module). Live-edit run A showed the model writing
+     * `moduleId: "$feat1"` unprompted; the union makes that intent
+     * expressible instead of a validation dead-end.
+     */
+    moduleId: z
+      .union([
+        z
+          .string()
+          .uuid(
+            'moduleId must be a UUID from ## Modules — to re-place a module minted earlier in THIS call, pass {"$ref": "<its ref>"} instead',
+          ),
+        z.object({ $ref: z.string() }).strict(),
+      ])
+      .optional(),
+    /** Mint mode: authoring surface, mirrors add_module_to_page. */
+    displayName: z.string().min(1).max(128).optional(),
+    description: z.string().max(1000).optional(),
+    kind: moduleKindSchema.optional(),
+    type: slugSchema.optional(),
+    html: z.string().min(1).max(MODULE_HTML_MAX).optional(),
+    css: z.string().max(MODULE_CSS_MAX).optional(),
+    js: z.string().max(MODULE_JS_MAX).optional(),
+    fields: z.array(moduleFieldSchema).max(64).optional(),
+    /** issue #164 slice 2 — opt-in mechanical token binding (tool layer). */
+    bindThemeLiterals: z.boolean().optional(),
+    content: buildPageContentSchema.optional(),
+  })
+  .strict()
+  .superRefine((entry, ctx) => {
+    if (entry.blockName === undefined && entry.ref === undefined) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message:
+          "An entry without `blockName` is a DETACHED (nested-only) module and requires `ref` " +
+          'so a later entry can embed it via {"$ref": "<ref>"} — otherwise it would be unreachable. ' +
+          "Pass `blockName` to place it on the page instead.",
+      });
+    }
+    // `moduleId` is PLACEMENT-ONLY: a placement that CAN succeed must never
+    // fail over an extra field (§1A/§11), so we do NOT reject a moduleId entry
+    // that also carries authoring fields. But those fields are NOT applied here
+    // (build_page places; it does not re-author a shared module). To avoid a
+    // SILENT dropped change (§2), the HANDLER surfaces an INFO in the result
+    // naming any ignored authoring field whose value DIFFERS from the module's
+    // stored one, and points at edit_module. The schema can't do that check (no
+    // DB), so it just allows the entry through.
+    if (entry.moduleId !== undefined) return;
+    if (entry.displayName === undefined || entry.html === undefined) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message:
+          "Pass either `moduleId` (place an existing module from ## Modules) " +
+          "or `displayName` + `html` (mint a new module).",
+      });
+    }
+  });
+export type BuildPageModule = z.infer<typeof buildPageModuleSchema>;
+
+/**
+ * Target page — exactly one of two shapes:
+ *
+ *   - `{ pageId }`                       → build onto an existing page
+ *     (modules are APPENDED to the named blocks in listed order).
+ *   - `{ slug, title, … }`               → create the page first (same
+ *     resolution rules as `pages.create`: templateId optional when
+ *     site_defaults carries a default).
+ */
+export const buildPageTargetSchema = z
+  .object({
+    pageId: z.string().uuid().optional(),
+    slug: slugSchema.optional(),
+    title: z.string().min(1).max(256).optional(),
+    name: z.string().min(1).max(256).optional(),
+    locale: localeSchema.optional(),
+    templateId: z.string().uuid().optional(),
+    status: pageStatusSchema.optional(),
+    /**
+     * Migration linkage (issue #278 flow): the `import_pages` row this
+     * page rebuilds. The op stamps `import_pages.accepted_page_id` with
+     * the built page's id so fidelity / inventory / media-migration reads
+     * resolve via that pointer regardless of slug. It ALSO makes the
+     * build idempotent — a second build_page for the same importPageId
+     * REBUILDS the already-linked page instead of minting a duplicate.
+     * Compatible with either target shape (create OR existing pageId).
+     */
+    importPageId: z.string().uuid().optional(),
+  })
+  .strict()
+  .superRefine((page, ctx) => {
+    const createKeys = (
+      ["slug", "title", "name", "locale", "templateId", "status"] as const
+    ).filter((k) => page[k] !== undefined);
+    if (page.pageId !== undefined) {
+      if (createKeys.length > 0) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message:
+            `pageId targets an EXISTING page — drop ${createKeys.join(", ")}. ` +
+            "To create a new page instead, omit pageId and pass slug + title.",
+        });
+      }
+      return;
+    }
+    if (page.slug === undefined || page.title === undefined) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message:
+          "Pass either `pageId` (build onto an existing page) or `slug` + `title` (create the page in the same call).",
+      });
+    }
+  });
+export type BuildPageTarget = z.infer<typeof buildPageTargetSchema>;
+
+/** `pages.build_page` op input. */
+export const buildPageInputSchema = z
+  .object({
+    page: buildPageTargetSchema,
+    // min 0: build_page is the SINGLE page-creation tool. An empty modules
+    // array creates an intentionally empty page shell (the case that used to
+    // need the now-removed create_page); a populated array builds the whole
+    // page in one transaction (the common case).
+    modules: z.array(buildPageModuleSchema).max(40),
+  })
+  .strict()
+  .superRefine((input, ctx) => {
+    // `ref` handles must be unique — a duplicate would silently shadow
+    // the earlier entry when a later {"$ref"} resolves.
+    const seen = new Set<string>();
+    for (const [i, entry] of input.modules.entries()) {
+      if (entry.ref === undefined) continue;
+      if (seen.has(entry.ref)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["modules", i, "ref"],
+          message: `duplicate ref "${entry.ref}" — each ref handle must be unique within the call`,
+        });
+      }
+      seen.add(entry.ref);
+    }
+  });
+export type BuildPageInput = z.infer<typeof buildPageInputSchema>;
+
+/** `pages.build_page` op output — one row per placed module, in input order. */
+export const buildPagePlacementResultSchema = z.object({
+  blockName: z.string(),
+  position: z.number().int().nonnegative(),
+  moduleId: z.string(),
+  contentInstanceId: z.string(),
+  syncMode: syncModeSchema,
+  /** True when this call minted the module (mint mode). */
+  minted: z.boolean(),
+});
+export type BuildPagePlacementResult = z.infer<typeof buildPagePlacementResultSchema>;
+
+// ─── content_instances.create_many ───────────────────────────────────
+
+/**
+ * Batch form of `content_instances.create`. Each item is the exact
+ * singular input; the handler runs the singular path per item inside
+ * ONE transaction (all-or-nothing — a failure at index i rolls back
+ * items 0..i-1 and the error names `instances[i]`).
+ */
+export const contentInstancesCreateManySchema = z
+  .object({
+    instances: z.array(contentInstanceCreateSchema).min(1).max(100),
+  })
+  .strict();
+export type ContentInstancesCreateManyInput = z.infer<typeof contentInstancesCreateManySchema>;
+
+// ─── page_module_content.set_many ────────────────────────────────────
+
+/**
+ * Batch form of `page_module_content.set` — a content-only pass over N
+ * existing placements (typically one page's worth, but cross-page items
+ * are fine). All-or-nothing in one transaction; failures name `items[i]`
+ * plus the placement coordinates and, for value-shape errors, the field.
+ */
+export const pageModuleContentSetManySchema = z
+  .object({
+    items: z
+      .array(
+        z
+          .object({
+            pageId: z.string().uuid(),
+            blockName: z.string().min(1).max(80),
+            position: z.number().int().nonnegative(),
+            /** Keyed by module field name. Fully replaces existing values. */
+            contentValues: contentValuesSchema,
+          })
+          .strict(),
+      )
+      .min(1)
+      .max(100),
+  })
+  .strict();
+export type PageModuleContentSetManyInput = z.infer<typeof pageModuleContentSetManySchema>;

package/src/cap-failures.ts

@@ -0,0 +1,67 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * P16 hardening — track consecutive cap-lookup failures so a flaky DB
+ * query doesn't silently disable AI cost enforcement.
+ *
+ * The plugin-host's `ctx.ai.complete` and chat-runner's daily-budget
+ * pre-flight both consult `ai_calls.aggregate_per_plugin` /
+ * `ai_budgets.status` before dispatching to the provider. Today a thrown
+ * error there is swallowed (so a working plugin doesn't break on a DB
+ * hiccup). That's the right default — but unbounded silent retries =
+ * "no enforcement at all under sustained DB pressure".
+ *
+ * The counter trips a per-key fail-closed mode after `LOOKUP_FAIL_THRESHOLD`
+ * consecutive misses; the next call is blocked with a structured error,
+ * the trip is reset on the first successful lookup. A success after one
+ * miss does NOT trip — only a sustained failure does.
+ */
+
+const LOOKUP_FAIL_THRESHOLD = 3;
+const counters = new Map<string, number>();
+
+/** Total fail-closed trips since process start — surfaced in /security/costs. */
+let totalTrips = 0;
+
+export function recordCapLookupSuccess(key: string): void {
+  counters.delete(key);
+}
+
+/**
+ * Record a cap-lookup failure. Returns `true` when the threshold has been
+ * crossed and the caller MUST fail closed instead of swallowing the error.
+ */
+export function recordCapLookupFailure(key: string): boolean {
+  const next = (counters.get(key) ?? 0) + 1;
+  counters.set(key, next);
+  if (next === LOOKUP_FAIL_THRESHOLD) {
+    totalTrips++;
+    console.warn(
+      JSON.stringify({
+        level: "warn",
+        msg: "ai-cap-lookup fail-closed tripped",
+        key,
+        consecutiveFailures: next,
+      }),
+    );
+  }
+  return next >= LOOKUP_FAIL_THRESHOLD;
+}
+
+/** Snapshot for the cost dashboard. */
+export function getCapLookupHealth(): {
+  trippedKeys: Array<{ key: string; consecutiveFailures: number }>;
+  totalTrips: number;
+} {
+  const tripped: Array<{ key: string; consecutiveFailures: number }> = [];
+  for (const [key, count] of counters.entries()) {
+    if (count >= LOOKUP_FAIL_THRESHOLD) tripped.push({ key, consecutiveFailures: count });
+  }
+  return { trippedKeys: tripped, totalTrips };
+}
+
+/** Test-only reset. */
+export function resetCapLookupCounters(): void {
+  counters.clear();
+  totalTrips = 0;
+}