@jini-ai/cms 0.5.2 → 0.5.3

package/dist/widgets/page-embed-types.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @file The page-embed stage's own marker types, as a dependency-free leaf.
+ *
+ * `resolver-service.ts`'s `HTML_EMBED_RESOLVERS` is the registry these name; it `satisfies`
+ * `Record<PageEmbedType, …>`, so the compiler fails if the two ever disagree in either direction.
+ * The list lives here rather than being read off that registry because `render.ts` needs
+ * `isPageEmbedType`, and `render.ts` is loaded by every theme render worker (`handlebars-worker.ts`,
+ * `liquid-worker.ts`). Importing `resolver-service.ts` from there pulled its post/media/entries
+ * services, and through them the DB kernels and the S3 blob client, into every worker spawn:
+ * ~990 modules and seconds of cold start per render (see `__tests__/worker-import-graph.test.ts`
+ * under `server/inbound/public-http/http/site/`).
+ */
+export declare const PAGE_EMBED_TYPES: readonly ["widget", "form", "taxonomy", "media", "post", "content"];
+export type PageEmbedType = (typeof PAGE_EMBED_TYPES)[number];
+/**
+ * Does the page-embed stage OWN this marker type — i.e. is a REQ-28 placeholder the honest answer
+ * when it fails to resolve?
+ *
+ * This question did not exist before the 2026-08-10 marker unification, and its absence was a real
+ * bug for exactly as long as the unification was half-done. `html-embeds.ts` used to match only an
+ * empty `<div data-embed-type="…">`, so a theme's own `partial`/`menu` markers were INVISIBLE to
+ * this stage — "unknown type" could only ever mean an author's typo, and rendering the REQ-28
+ * placeholder for it was right. Sharing one permissive parser made every marker visible to every
+ * consumer, so `renderHtmlPageBody` began substituting placeholders over the nav, the docs menu, and
+ * the footer of any post rendered through a theme template — three markers a LATER stage
+ * (`static-render.ts`'s `resolveSlots`/`injectMenuEmbeds`) owns and would have resolved.
+ *
+ * So ownership must be asked of the resolver registry (`resolver-service.ts`'s
+ * `HTML_EMBED_RESOLVERS`, whose keys are exactly {@link PAGE_EMBED_TYPES}), never inferred from
+ * "did resolution produce anything". A type present there that failed to resolve still degrades to
+ * the placeholder — that is REQ-28 and unchanged. A type absent from there is not this stage's to
+ * render OR to blank: it is left exactly as authored, which is the shared parser's own "unresolved
+ * means untouched" invariant.
+ *
+ * The cost of being wrong is asymmetric and that is why the default is untouched: a marker wrongly
+ * left alone is visible in the output the moment anyone looks at the page, while a marker wrongly
+ * replaced is a silently-deleted nav that renders as a tidy, plausible page with a hole in it.
+ */
+export declare function isPageEmbedType({ type }: {
+    type: string;
+}, _optional?: Record<string, never>): boolean;
+//# sourceMappingURL=page-embed-types.d.ts.map

package/dist/widgets/page-embed-types.js

@@ -0,0 +1,42 @@
+/**
+ * @file The page-embed stage's own marker types, as a dependency-free leaf.
+ *
+ * `resolver-service.ts`'s `HTML_EMBED_RESOLVERS` is the registry these name; it `satisfies`
+ * `Record<PageEmbedType, …>`, so the compiler fails if the two ever disagree in either direction.
+ * The list lives here rather than being read off that registry because `render.ts` needs
+ * `isPageEmbedType`, and `render.ts` is loaded by every theme render worker (`handlebars-worker.ts`,
+ * `liquid-worker.ts`). Importing `resolver-service.ts` from there pulled its post/media/entries
+ * services, and through them the DB kernels and the S3 blob client, into every worker spawn:
+ * ~990 modules and seconds of cold start per render (see `__tests__/worker-import-graph.test.ts`
+ * under `server/inbound/public-http/http/site/`).
+ */
+export const PAGE_EMBED_TYPES = ["widget", "form", "taxonomy", "media", "post", "content"];
+const PAGE_EMBED_TYPE_SET = new Set(PAGE_EMBED_TYPES);
+/**
+ * Does the page-embed stage OWN this marker type — i.e. is a REQ-28 placeholder the honest answer
+ * when it fails to resolve?
+ *
+ * This question did not exist before the 2026-08-10 marker unification, and its absence was a real
+ * bug for exactly as long as the unification was half-done. `html-embeds.ts` used to match only an
+ * empty `<div data-embed-type="…">`, so a theme's own `partial`/`menu` markers were INVISIBLE to
+ * this stage — "unknown type" could only ever mean an author's typo, and rendering the REQ-28
+ * placeholder for it was right. Sharing one permissive parser made every marker visible to every
+ * consumer, so `renderHtmlPageBody` began substituting placeholders over the nav, the docs menu, and
+ * the footer of any post rendered through a theme template — three markers a LATER stage
+ * (`static-render.ts`'s `resolveSlots`/`injectMenuEmbeds`) owns and would have resolved.
+ *
+ * So ownership must be asked of the resolver registry (`resolver-service.ts`'s
+ * `HTML_EMBED_RESOLVERS`, whose keys are exactly {@link PAGE_EMBED_TYPES}), never inferred from
+ * "did resolution produce anything". A type present there that failed to resolve still degrades to
+ * the placeholder — that is REQ-28 and unchanged. A type absent from there is not this stage's to
+ * render OR to blank: it is left exactly as authored, which is the shared parser's own "unresolved
+ * means untouched" invariant.
+ *
+ * The cost of being wrong is asymmetric and that is why the default is untouched: a marker wrongly
+ * left alone is visible in the output the moment anyone looks at the page, while a marker wrongly
+ * replaced is a silently-deleted nav that renders as a tidy, plausible page with a hole in it.
+ */
+export function isPageEmbedType({ type }, _optional = {}) {
+    return PAGE_EMBED_TYPE_SET.has(type);
+}
+//# sourceMappingURL=page-embed-types.js.map

package/dist/widgets/ports.d.ts

@@ -0,0 +1,142 @@
+/**
+ * @file Ports + typed-call contracts for the Tovu `widgets` library (ADR-047, SPEC-043).
+ *
+ * ADR-006 (rule-of-two) applied the way ADR-029 §5 already set precedent:
+ *
+ * - **`WidgetRegionBindingRepoPort` IS a port.** It persists the derived
+ *   `widget_region_bindings` index — two real adapters, in-memory + SQLite,
+ *   mirroring `NavLocationBindingRepoPort` exactly.
+ *
+ * - **Widget instances add NO new persistence port.** A widget instance is an
+ *   ADR-022 entry; it rides the existing entries repo (already rule-of-two).
+ *
+ * - **`widget_area` entries add NO new persistence port either** — same
+ *   reasoning, they are entries too (ADR-047 Debate Fold-In Amendment 1).
+ *
+ * - **Resolution (`WidgetResolver`, `widgets/types.ts`) is NOT a port** — one
+ *   evaluator per registered type, dispatched through the closed
+ *   `CORE_RESOLVERS` map (`resolvers/index.ts`), not injected. Promote to a
+ *   port only if a second real implementation of a given type's resolution
+ *   logic appears (ADR-029 §5's anti-port-mania call, applied identically).
+ *
+ * INTERFACES ONLY. No feature logic lives here.
+ */
+import type { ISODateTime, UUID } from "@jini-ai/core/primitives";
+import type { WidgetRegionBindingRow, WidgetRegionDescriptor, WidgetRegionKey } from "./types.js";
+/**
+ * Persistence for the derived `widget_region_bindings` index. Writes happen
+ * only inside the same transaction as the `widget_area` entry mutation that
+ * changed `regionKey` (single write chokepoint, ADR-022 §4a) — this port is
+ * the storage seam, not a second write path. `rebuildForWorkspace` exists
+ * because the index is **rebuildable by definition** — a full rescan of
+ * `widget_area` entries can always reconstruct it (INV-02).
+ */
+export interface WidgetRegionBindingRepoPort {
+    /** The `widget_area` entry currently bound to a region, if any. */
+    findByRegion(required: {
+        workspaceId: UUID;
+        regionKey: WidgetRegionKey;
+    }): Promise<WidgetRegionBindingRow | null>;
+    /** Every binding in the workspace (admin overview + render prefetch). */
+    listByWorkspace(required: {
+        workspaceId: UUID;
+    }): Promise<WidgetRegionBindingRow[]>;
+    /**
+     * Assign a region to a `widget_area` entry. Honors
+     * `UNIQUE (workspace_id, region_key)`. Called only from
+     * `region-area-service.ts`'s `reconcileWidgetRegionBindings` — never
+     * directly by a route handler or any other caller (INV-02).
+     */
+    upsert(required: {
+        workspaceId: UUID;
+        regionKey: WidgetRegionKey;
+        areaEntryId: UUID;
+        updatedAt: ISODateTime;
+    }): Promise<WidgetRegionBindingRow>;
+    /** Mark a region binding inactive (theme switch orphaned the region key — REQ-14). Never deletes the underlying `widget_area` entry. */
+    markInactive(required: {
+        workspaceId: UUID;
+        regionKey: WidgetRegionKey;
+    }): Promise<void>;
+    /**
+     * Rebuild the whole workspace's index from the authoritative `widget_area`
+     * entries. The index is derived + rebuildable, so this is always safe.
+     */
+    rebuildForWorkspace(required: {
+        workspaceId: UUID;
+        bindings: readonly WidgetRegionBindingRow[];
+    }): Promise<void>;
+}
+/** Registry of theme/plugin-declared widget regions (mirrors `NavLocationRegistry`). */
+export interface WidgetRegionRegistry {
+    list(required: {
+        workspaceId: UUID;
+    }): WidgetRegionDescriptor[];
+    get(required: {
+        workspaceId: UUID;
+        key: WidgetRegionKey;
+    }): WidgetRegionDescriptor | null;
+}
+/**
+ * The function `trashWidgetInstance` receives to move a widget to the Trash, bound to the `"widget"`
+ * type at the composition root. Structurally typed on purpose: this feature imports nothing from
+ * `features/trash`.
+ */
+export type RemoveWidgetFn = (required: {
+    workspaceId: UUID;
+    id: UUID;
+    display: {
+        title: string;
+        subtitle?: string | null;
+    };
+    at: string;
+    expectedVersion: number | null;
+    actor: {
+        principalId: string;
+        pluginId?: string | null;
+    };
+    /** The status a restore brings back, when the Trash cannot read it off a column — only the
+     *  legacy-widget adoption states one (`"active"`). */
+    priorMarker?: string | null;
+}) => Promise<{
+    ok: true;
+    version: number | null;
+} | {
+    ok: false;
+    reason: "not-found" | "version-changed";
+}>;
+/** Structural reference-index row: the host owns extraction and persistence. */
+export interface EntryRefRow {
+    readonly workspaceId: UUID;
+    readonly sourceEntryId: UUID;
+    readonly sourceKind: "widget-area-placement" | "widget-embed" | "config-field" | "page-html-embed";
+    readonly fieldPath: string;
+    readonly targetKind: "entry" | "term" | "asset";
+    readonly targetId: UUID;
+}
+/** The one reference-index operation widgets performs; no extractor implementation is copied. */
+export interface EntryRefsRepoPort {
+    replaceForSource(required: {
+        workspaceId: UUID;
+        sourceEntryId: UUID;
+        refs: readonly EntryRefRow[];
+    }): Promise<void>;
+    findBySource(required: {
+        workspaceId: UUID;
+        sourceEntryId: UUID;
+    }): Promise<EntryRefRow[]>;
+    findByTarget(required: {
+        workspaceId: UUID;
+        targetKind: EntryRefRow["targetKind"];
+        targetId: UUID;
+    }): Promise<EntryRefRow[]>;
+    removeBySource(required: {
+        workspaceId: UUID;
+        sourceEntryId: UUID;
+    }): Promise<void>;
+    rebuildForWorkspace(required: {
+        workspaceId: UUID;
+        refs: readonly EntryRefRow[];
+    }): Promise<void>;
+}
+//# sourceMappingURL=ports.d.ts.map

package/dist/widgets/ports.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ports.js.map

package/dist/widgets/read-service.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @file Widget-instance READ accessors (SPEC-043 REQ-04) — `write-service.ts` only ever exported
+ * create/update/trash/purge; this file is the missing `widgets.read`-gated get/list side, named
+ * separately per `features/entries`' own `write-service.ts`/`list.ts` split convention.
+ *
+ * External /audit-work finding (2026-07-21, ADR-047): confirmed no read/list accessor existed in
+ * this package at all — the admin `get-by-id`/`list` routes (`routes/admin/widgets/*.ts`) this
+ * dispatch builds depend on it directly.
+ *
+ * Disclosed, not silently omitted: REQ-04 also asks for "its full revision history." No revision-
+ * READ capability exists anywhere in `features/entries` today for ANY content type (confirmed:
+ * `EntryRepoPort` only exposes `appendRevision`, never a corresponding list/read method — neither
+ * `InMemoryEntryRepo` nor `SqliteEntryRepo` exposes one either, even as an extra, non-port method).
+ * That is a real, pre-existing gap in the shared chokepoint, not a widgets-specific hole, and
+ * meaningfully larger than the two additive fixes this dispatch already made to
+ * `features/entries/write-service.ts` (the `onWritten` hook, the `bodyJson` parameter) — it needs
+ * its own port + both adapters, a bigger shared-module change than this dispatch is authorized to
+ * make unilaterally. `getWidgetInstance` below returns current state only; `revisions: []` is
+ * returned as an honest placeholder shape (not a silently-dropped field) so callers/tests have a
+ * stable contract to code against once the underlying capability lands.
+ *
+ * Architectural role:
+ * `widgets` domain logic, read side.
+ */
+import type { UUID } from "@jini-ai/core/primitives";
+import type { EntryListPort, EntryRepoPort } from "../entries/index.js";
+import { type WidgetsAuthorizeFn } from "./authorize-helper.js";
+import type { WidgetInstanceEntry } from "./types.js";
+export interface WidgetReadServiceDeps {
+    entryRepo: EntryRepoPort & EntryListPort;
+    authorize: WidgetsAuthorizeFn;
+}
+export interface GetWidgetInstanceInput {
+    readonly workspaceId: UUID;
+    readonly actor: {
+        readonly principalId: UUID;
+    };
+    readonly widgetInstanceId: UUID;
+}
+export interface GetWidgetInstanceRequired {
+    deps: WidgetReadServiceDeps;
+    input: GetWidgetInstanceInput;
+}
+/** REQ-04: read a widget instance's current state (+ revision history — see this file's header for
+ * the disclosed gap on that half). Returns any status (`active`/`trash`/`purged`) — the caller
+ * decides whether a non-`active` instance is presentable (e.g. an admin editor still shows a
+ * trashed instance so it can be restored/inspected).
+ *
+ * `widgetInstanceId` is resolved slug-first, id-second — same order/rationale as posts'
+ * `getAdminPostByIdOrSlug` (`src/features/post/post.ts`) and forms'
+ * `resolveFormDefinitionByIdOrSlug` (`server/inbound/admin-http/routes/forms/resolve-definition.ts`):
+ * the admin widget editor's URL now carries the widget's slug (`WidgetsLibrary.tsx`'s row link,
+ * `use-widget-instance-editor.hooks.ts`'s create-navigate), so this param may itself BE that slug.
+ * An old id-based bookmark/link still resolves via the `findById` fallback. */
+export declare function getWidgetInstance(required: GetWidgetInstanceRequired, _optional?: Record<string, never>): Promise<{
+    instance: WidgetInstanceEntry;
+    revisions: [];
+}>;
+export interface ListWidgetInstancesInput {
+    readonly workspaceId: UUID;
+    readonly actor: {
+        readonly principalId: UUID;
+    };
+    /** Narrow to one widget type; omitted lists every type (mirrors `EntryListPort.listByWorkspace`'s
+     * own optional-`type` shape). */
+    readonly widgetType?: string;
+    /** Excludes `trash`/`purged` instances by default — the library screen's default view (REQ-04
+     * read access still covers reading a specific trashed instance directly via `getWidgetInstance`,
+     * this is only the list's default filter). */
+    readonly includeInactive?: boolean;
+}
+export interface ListWidgetInstancesRequired {
+    deps: WidgetReadServiceDeps;
+    input: ListWidgetInstancesInput;
+}
+export declare function listWidgetInstances(required: ListWidgetInstancesRequired, _optional?: Record<string, never>): Promise<{
+    instances: WidgetInstanceEntry[];
+    skippedCount: number;
+    skippedIds: string[];
+}>;
+//# sourceMappingURL=read-service.d.ts.map

package/dist/widgets/read-service.js

@@ -0,0 +1,79 @@
+import { requireWidgetPermission } from "./authorize-helper.js";
+import { WidgetInstanceNotFoundError } from "./errors.js";
+import { toWidgetInstanceEntry } from "./entry-payload.js";
+import { WIDGET_CONTENT_TYPE } from "./types.js";
+/** REQ-04: read a widget instance's current state (+ revision history — see this file's header for
+ * the disclosed gap on that half). Returns any status (`active`/`trash`/`purged`) — the caller
+ * decides whether a non-`active` instance is presentable (e.g. an admin editor still shows a
+ * trashed instance so it can be restored/inspected).
+ *
+ * `widgetInstanceId` is resolved slug-first, id-second — same order/rationale as posts'
+ * `getAdminPostByIdOrSlug` (`src/features/post/post.ts`) and forms'
+ * `resolveFormDefinitionByIdOrSlug` (`server/inbound/admin-http/routes/forms/resolve-definition.ts`):
+ * the admin widget editor's URL now carries the widget's slug (`WidgetsLibrary.tsx`'s row link,
+ * `use-widget-instance-editor.hooks.ts`'s create-navigate), so this param may itself BE that slug.
+ * An old id-based bookmark/link still resolves via the `findById` fallback. */
+export async function getWidgetInstance(required, _optional = {}) {
+    const { deps, input } = required;
+    await requireWidgetPermission({
+        authorize: deps.authorize,
+        actor: input.actor,
+        workspaceId: input.workspaceId,
+        permission: "widgets.read",
+    });
+    const bySlug = await deps.entryRepo.findBySlug({
+        workspaceId: input.workspaceId,
+        type: WIDGET_CONTENT_TYPE,
+        slug: input.widgetInstanceId.trim().toLowerCase(),
+    });
+    const entry = bySlug ?? (await deps.entryRepo.findById({ workspaceId: input.workspaceId, id: input.widgetInstanceId }));
+    if (!entry || entry.type !== WIDGET_CONTENT_TYPE) {
+        throw new WidgetInstanceNotFoundError({ message: `widget instance '${input.widgetInstanceId}' was not found` });
+    }
+    return { instance: toWidgetInstanceEntry({ entry: entry }), revisions: [] };
+}
+export async function listWidgetInstances(required, _optional = {}) {
+    const { deps, input } = required;
+    await requireWidgetPermission({
+        authorize: deps.authorize,
+        actor: input.actor,
+        workspaceId: input.workspaceId,
+        permission: "widgets.read",
+    });
+    const rows = await deps.entryRepo.listByWorkspace({ workspaceId: input.workspaceId }, { type: WIDGET_CONTENT_TYPE });
+    const instances = [];
+    let skippedCount = 0;
+    const skippedIds = [];
+    for (const row of rows) {
+        let instance;
+        try {
+            instance = toWidgetInstanceEntry({ entry: row });
+        }
+        catch {
+            // A malformed widget-instance row (e.g. wiped by an unrelated generic-entry update that
+            // bypassed this feature's own write path) is skipped, not a 500 for the whole admin library
+            // screen (Fable adversarial-review fix, 2026-07-21, Finding B).
+            //
+            // 2026-08-03 (dossier C5 follow-up): the skip itself was silent — nothing recorded that a row
+            // never reached the caller, so a genuinely corrupted widget could vanish from the library with
+            // zero trace. Kept the skip (a malformed row must not 500 the whole screen), added a
+            // server-side log line plus returned count and IDs so it's observable instead of invisible.
+            // Deliberately logs only `row.id`/`workspaceId`, never `row.fieldsJson` — a malformed payload
+            // may hold arbitrary caller-supplied content, and this line is not the place to disclose it.
+            console.warn("[widgets] listWidgetInstances: skipping malformed widget-instance row", {
+                entryId: row.id,
+                workspaceId: input.workspaceId,
+            });
+            skippedCount += 1;
+            skippedIds.push(row.id);
+            continue;
+        }
+        if (input.widgetType && instance.widgetType !== input.widgetType)
+            continue;
+        if (!input.includeInactive && instance.status !== "active")
+            continue;
+        instances.push(instance);
+    }
+    return { instances, skippedCount, skippedIds };
+}
+//# sourceMappingURL=read-service.js.map

package/dist/widgets/region-area-service.d.ts

@@ -0,0 +1,110 @@
+import type { WidgetHostPorts } from "./host-ports.js";
+/**
+ * @file `widget_area` entry CRUD + whole-document placement mutation + the derived binding-table
+ * reconcile step (SPEC-043 REQ-11..17; ADR-047 Debate Fold-In Amendment 1).
+ *
+ * Purpose:
+ * Deliberately mirrors `navigation/reconcile.ts` — same reconcile-not-author discipline for
+ * `widget_region_bindings` that `nav_location_bindings` already established.
+ * `reconcileWidgetRegionBindings` is the ONLY code path permitted to write the binding table
+ * (INV-02); no other file in this package calls `WidgetRegionBindingRepoPort.upsert`/`markInactive`
+ * outside `bindWidgetArea`/`mutateWidgetAreaPlacements`, which both delegate their binding-table
+ * writes through this same discipline.
+ *
+ * `entry_refs` extraction (INV-06) runs inside the same DB transaction as the triggering
+ * `createEntry`/`updateEntry` call, via `deps.onWritten` — see `write-service.ts`'s file header for
+ * the full reasoning (identical here).
+ *
+ * Architectural role:
+ * `widgets` domain logic (implementation outline C-006).
+ */
+import type { Clock as ClockPort, UUID } from "@jini-ai/core/primitives";
+import type { OutboxPort } from "../core/index.js";
+import type { EntryRefsRepoPort } from "./ports.js";
+import type { ContentTypeRepoPort } from "../content-types/index.js";
+import type { EntryListPort, EntryRepoPort } from "../entries/index.js";
+import { type WidgetsAuthorizeFn } from "./authorize-helper.js";
+import type { WidgetRegionBindingRepoPort } from "./ports.js";
+import type { WidgetAreaEntry, WidgetPlacementNode, WidgetRegionKey } from "./types.js";
+export interface RegionAreaServiceDeps {
+    host: Pick<WidgetHostPorts, "entries" | "contentTypes" | "entryRefs">;
+    entryRepo: EntryRepoPort & EntryListPort;
+    contentTypeRepo: ContentTypeRepoPort;
+    entryRefsRepo: EntryRefsRepoPort;
+    bindingRepo: WidgetRegionBindingRepoPort;
+    clock: ClockPort;
+    ids: {
+        newId: () => string;
+    };
+    authorize: WidgetsAuthorizeFn;
+    outbox: OutboxPort;
+}
+export interface BindWidgetAreaInput {
+    readonly workspaceId: UUID;
+    readonly regionKey: WidgetRegionKey;
+}
+export interface BindWidgetAreaRequired {
+    deps: RegionAreaServiceDeps;
+    input: BindWidgetAreaInput;
+}
+/**
+ * REQ-13: seeds a `widget_area` entry for a region with no existing binding (called on theme
+ * activation — a system/boot operation, not a user-initiated `widgets.place` mutation, so no
+ * `authorize()` gate here, matching how `navigation`'s location seeding is likewise boot-driven).
+ * Idempotent: a region already bound (or an existing-but-unbound `widget_area` entry for that
+ * region key, found via its deterministic slug) is reused, never duplicated.
+ */
+export declare function bindWidgetArea(required: BindWidgetAreaRequired, _optional?: Record<string, never>): Promise<{
+    areaEntry: WidgetAreaEntry;
+}>;
+export interface MutateWidgetAreaPlacementsInput {
+    readonly workspaceId: UUID;
+    readonly actor: {
+        readonly principalId: UUID;
+    };
+    readonly areaEntryId: UUID;
+    readonly baseVersion: number;
+    /** The complete resulting ordered list — always a whole-document write, never a per-row patch (INV-03). */
+    readonly placements: readonly WidgetPlacementNode[];
+}
+export interface MutateWidgetAreaPlacementsRequired {
+    deps: RegionAreaServiceDeps;
+    input: MutateWidgetAreaPlacementsInput;
+}
+/** REQ-16/AC-10: every referenced widgetEntryId must exist, be a live (non-trashed) widget instance,
+ *  in this same workspace — checked before any write. Throws the first violation found. */
+export declare function validatePlacementWidgetsExist({ deps, workspaceId, placements }: {
+    deps: RegionAreaServiceDeps;
+    workspaceId: UUID;
+    placements: readonly WidgetPlacementNode[];
+}, _optional?: Record<string, never>): Promise<void>;
+/** REQ-15/16: one atomic, version-guarded write; rejects placements referencing a nonexistent/trashed/cross-workspace widget. */
+export declare function mutateWidgetAreaPlacements(required: MutateWidgetAreaPlacementsRequired, _optional?: Record<string, never>): Promise<{
+    areaEntry: WidgetAreaEntry;
+}>;
+export interface ReconcileWidgetRegionBindingsInput {
+    readonly workspaceId: UUID;
+}
+export interface ReconcileWidgetRegionBindingsRequired {
+    deps: RegionAreaServiceDeps;
+    input: ReconcileWidgetRegionBindingsInput;
+}
+/**
+ * REQ-12/14: reconciles `widget_region_bindings` from the authoritative `widget_area` entries. The
+ * sole write path for the binding table (INV-02) — a full rescan-and-replace, exactly mirroring
+ * `navigation/reconcile.ts`'s `rebuildNavLocationBindings`. A region key present on more than one
+ * `widget_area` entry (a data-drift edge case the invariant should otherwise prevent) resolves
+ * last-writer-wins by iteration order, consistent with `WidgetRegionBindingRepoPort.upsert`'s own
+ * semantics elsewhere in this library.
+ *
+ * Orphan handling (REQ-14): this reconcile pass only ever WRITES rows implied by live `widget_area`
+ * entries — it never independently marks a row inactive for a region no theme declares anymore
+ * (that requires theme-declaration data this function is not given). `markInactive` is `widgets/
+ * repo.{memory,sqlite}.ts`'s own export for that call site (out of this task's scope — no HTTP/
+ * theme-activation route exists yet to drive it).
+ *
+ * @complexity O(n) over the workspace's `widget_area` entry count.
+ * @overallScore 100
+ */
+export declare function reconcileWidgetRegionBindings(required: ReconcileWidgetRegionBindingsRequired, _optional?: Record<string, never>): Promise<void>;
+//# sourceMappingURL=region-area-service.d.ts.map