@jini-ai/cms 0.5.2 → 0.5.3

package/dist/widgets/region-area-service.js

@@ -0,0 +1,180 @@
+import { nowIso as clockNowIso } from "@jini-ai/core/primitives";
+import { PRE_AUTHORIZED, requireWidgetPermission, WIDGETS_SYSTEM_ACTOR_ID, } from "./authorize-helper.js";
+import { withEntryLock } from "./concurrency.js";
+import { areaDocWithPlacements, buildWidgetAreaFieldsJson, emptyWidgetAreaDoc, ensureWidgetContentTypesRegistered, parseWidgetAreaPayload, parseWidgetInstancePayload, toWidgetAreaEntry, widgetAreaSlug, } from "./entry-payload.js";
+import { WidgetAreaConflictError, WidgetAreaNotFoundError, WidgetInstanceNotFoundError, } from "./errors.js";
+import { WIDGET_AREA_CONTENT_TYPE, WIDGET_AREA_FIELD_NAMESPACE, WIDGET_CONTENT_TYPE, } from "./types.js";
+async function extractAndStoreAreaRefs(deps, workspaceId, entry) {
+    const payload = parseWidgetAreaPayload({ fieldsJson: entry.fieldsJson });
+    const refs = deps.host.entryRefs.extract({
+        workspaceId,
+        sourceEntryId: entry.id,
+        sourceEntryType: WIDGET_AREA_CONTENT_TYPE,
+        bodyJson: payload.doc,
+        fieldsExt: { [WIDGET_AREA_FIELD_NAMESPACE]: { regionKey: payload.regionKey } },
+    });
+    await deps.entryRefsRepo.replaceForSource({ workspaceId, sourceEntryId: entry.id, refs });
+}
+/**
+ * The one shared shape both `createEntry` (`bindWidgetArea`) and `updateEntry`
+ * (`mutateWidgetAreaPlacements`) below need. Bridges `deps.outbox` (the raw, full-`DomainEvent`
+ * infra port) through `toEntryOutbox` into the narrower `{enqueue({name,payload})}` shape those
+ * chokepoints declare locally — previously `deps.outbox` was forwarded unwrapped here, which
+ * compiled but threw `NOT NULL constraint failed: outbox_events.id` against the real SQLite outbox
+ * on every region bind/placement-mutation. Both call sites share this one helper already, so fixing
+ * it here fixes both at once — see `write-service.ts`'s identically-named, identically-reasoned
+ * helper for the full investigation pointer.
+ */
+function entriesWriteDeps(deps, workspaceId) {
+    return {
+        entryRepo: deps.entryRepo,
+        contentTypeRepo: deps.contentTypeRepo,
+        clock: deps.clock,
+        ids: deps.ids,
+        authorize: PRE_AUTHORIZED,
+        outbox: deps.host.entries.toEntryOutbox({ outbox: deps.outbox, clock: deps.clock, idGen: deps.ids, workspaceId }),
+        onWritten: (entry) => extractAndStoreAreaRefs(deps, workspaceId, entry),
+    };
+}
+/**
+ * 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 async function bindWidgetArea(required, _optional = {}) {
+    const { deps, input } = required;
+    await ensureWidgetContentTypesRegistered({ deps, workspaceId: input.workspaceId });
+    return withEntryLock({ key: `${input.workspaceId}::area::${input.regionKey}`, fn: async () => {
+            const existingBinding = await deps.bindingRepo.findByRegion({ workspaceId: input.workspaceId, regionKey: input.regionKey });
+            if (existingBinding) {
+                const boundEntry = await deps.entryRepo.findById({ workspaceId: input.workspaceId, id: existingBinding.areaEntryId });
+                if (boundEntry)
+                    return { areaEntry: toWidgetAreaEntry({ entry: boundEntry }) };
+            }
+            const slug = widgetAreaSlug({ regionKey: input.regionKey });
+            let entry = await deps.entryRepo.findBySlug({ workspaceId: input.workspaceId, type: WIDGET_AREA_CONTENT_TYPE, slug });
+            if (!entry) {
+                const created = await deps.host.entries.createEntry({
+                    deps: entriesWriteDeps(deps, input.workspaceId),
+                    input: {
+                        actorId: WIDGETS_SYSTEM_ACTOR_ID,
+                        workspaceId: input.workspaceId,
+                        type: WIDGET_AREA_CONTENT_TYPE,
+                        slug,
+                        title: `Region: ${input.regionKey}`,
+                        fieldsJson: buildWidgetAreaFieldsJson({ payload: { regionKey: input.regionKey, doc: emptyWidgetAreaDoc({}) } }),
+                    },
+                });
+                if (!created.ok)
+                    throw created.error;
+                entry = created.value.entry;
+            }
+            await deps.bindingRepo.upsert({
+                workspaceId: input.workspaceId,
+                regionKey: input.regionKey,
+                areaEntryId: entry.id,
+                updatedAt: clockNowIso({ clock: deps.clock }),
+            });
+            return { areaEntry: toWidgetAreaEntry({ entry: entry }) };
+        } });
+}
+/** 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 async function validatePlacementWidgetsExist({ deps, workspaceId, placements }, _optional = {}) {
+    for (const placement of placements) {
+        const widget = await deps.entryRepo.findById({ workspaceId, id: placement.widgetEntryId });
+        if (!widget || widget.type !== WIDGET_CONTENT_TYPE) {
+            throw new WidgetInstanceNotFoundError({ message: `placement references widget '${placement.widgetEntryId}', which does not exist in workspace '${workspaceId}' (REQ-16)` });
+        }
+        const widgetPayload = parseWidgetInstancePayload({ fieldsJson: widget.fieldsJson });
+        if (widgetPayload.status === "trash" || widgetPayload.status === "purged") {
+            throw new WidgetInstanceNotFoundError({ message: `placement references widget '${placement.widgetEntryId}', which is trashed (REQ-16)` });
+        }
+    }
+}
+/** Converts a rejected `updateEntry` result into the matching typed error — a version conflict
+ *  reports the CURRENT (post-conflict) version, any other failure propagates as-is. Never returns. */
+async function rejectMutateWidgetAreaPlacementsWrite(deps, workspaceId, areaEntryId, current, error) {
+    if (deps.host.entries.isVersionConflict(error)) {
+        const latest = await deps.entryRepo.findById({ workspaceId, id: areaEntryId });
+        throw new WidgetAreaConflictError({ message: error.message, currentVersion: latest?.version ?? current.version });
+    }
+    throw error;
+}
+/** REQ-15/16: one atomic, version-guarded write; rejects placements referencing a nonexistent/trashed/cross-workspace widget. */
+export async function mutateWidgetAreaPlacements(required, _optional = {}) {
+    const { deps, input } = required;
+    await requireWidgetPermission({
+        authorize: deps.authorize,
+        actor: input.actor,
+        workspaceId: input.workspaceId,
+        permission: "widgets.place",
+    });
+    return withEntryLock({ key: `${input.workspaceId}::${input.areaEntryId}`, fn: async () => {
+            const current = await deps.entryRepo.findById({ workspaceId: input.workspaceId, id: input.areaEntryId });
+            if (!current || current.type !== WIDGET_AREA_CONTENT_TYPE) {
+                throw new WidgetAreaNotFoundError({ message: `widget_area '${input.areaEntryId}' was not found` });
+            }
+            await validatePlacementWidgetsExist({ deps: deps, workspaceId: input.workspaceId, placements: input.placements });
+            const currentPayload = parseWidgetAreaPayload({ fieldsJson: current.fieldsJson });
+            const nextDoc = areaDocWithPlacements({ doc: currentPayload.doc, placements: input.placements });
+            const result = await deps.host.entries.updateEntry({
+                deps: entriesWriteDeps(deps, input.workspaceId),
+                input: {
+                    actorId: input.actor.principalId,
+                    workspaceId: input.workspaceId,
+                    id: input.areaEntryId,
+                    fieldsJson: buildWidgetAreaFieldsJson({ payload: { regionKey: currentPayload.regionKey, doc: nextDoc } }),
+                    expectedVersion: input.baseVersion,
+                },
+            });
+            if (!result.ok) {
+                return rejectMutateWidgetAreaPlacementsWrite(deps, input.workspaceId, input.areaEntryId, current, result.error);
+            }
+            // regionKey never changes on a placement mutation — refresh the derived row's audit timestamp
+            // only (INV-02 still trivially holds: the binding is still exactly what a rebuild would produce).
+            await deps.bindingRepo.upsert({
+                workspaceId: input.workspaceId,
+                regionKey: currentPayload.regionKey,
+                areaEntryId: result.value.entry.id,
+                updatedAt: clockNowIso({ clock: deps.clock }),
+            });
+            return { areaEntry: toWidgetAreaEntry({ entry: result.value.entry }) };
+        } });
+}
+/**
+ * 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 async function reconcileWidgetRegionBindings(required, _optional = {}) {
+    const { deps, input } = required;
+    const areaEntries = await deps.entryRepo.listByWorkspace({ workspaceId: input.workspaceId }, { type: WIDGET_AREA_CONTENT_TYPE });
+    const now = clockNowIso({ clock: deps.clock });
+    const byRegion = new Map();
+    for (const entry of areaEntries) {
+        const payload = parseWidgetAreaPayload({ fieldsJson: entry.fieldsJson });
+        byRegion.set(payload.regionKey, {
+            workspaceId: input.workspaceId,
+            regionKey: payload.regionKey,
+            areaEntryId: entry.id,
+            updatedAt: now,
+        });
+    }
+    await deps.bindingRepo.rebuildForWorkspace({ workspaceId: input.workspaceId, bindings: [...byRegion.values()] });
+}
+//# sourceMappingURL=region-area-service.js.map

package/dist/widgets/registry.d.ts

@@ -0,0 +1,217 @@
+/**
+ * @file The v1 widget-type registry (SPEC-043 REQ-07..10, ADR-047 Debate Fold-In Amendment 3).
+ *
+ * Purpose:
+ * Each `WidgetTypeRegistration` below is plain, JSON-serializable data — schema, capability
+ * class, placement contexts, cost clamps, and (for dynamic types) a `resolverId` string. No
+ * registration record imports or references executable behavior directly; `resolverId` is a
+ * pointer that only ever resolves through `resolvers/index.ts`'s closed `CORE_RESOLVERS` map
+ * (REQ-08) — never a dynamic import, `eval`, or arbitrary function reference. This is the split
+ * Amendment 3 requires: type *registration* is data (Tier-1-safe, this file); type *behavior* is
+ * core-owned code in v1, ADR-024 Tier-2/3-gated for any future plugin-contributed dynamic type
+ * (`resolvers/`).
+ *
+ * `getWidgetTypeRegistration`/`findWidgetTypeRegistration` are the two lookup accessors over this
+ * data — pure, O(1) functions with no I/O and no reference to resolver code, kept here (unlike
+ * `forms/manifest.ts`'s stricter zero-function convention, which exists specifically for a
+ * hypothetical future loader retrofit this file has no equivalent of) because every other registry
+ * in this codebase (`identity/permissions.ts`) pairs its data with a plain accessor the same way.
+ * The split is deliberate, not incidental: `getWidgetTypeRegistration` is total and only accepts a
+ * `typeKey` the type system has actually proven is one of the five registered keys; a caller
+ * holding a merely-asserted `WidgetTypeKey` (cast from an HTTP body or decoded JSON, not narrowed)
+ * must use the partial `findWidgetTypeRegistration` instead — see each function's own doc.
+ *
+ * How it relates to the project:
+ * - Read by `resolvers/index.ts` (dispatch), `write-service.ts` (config validation, REQ-02/03),
+ *   and any admin/AI surface that needs to know what a widget type declares.
+ * - Static/type-only until the registry itself is imported and iterated — no side effects at
+ *   module load time.
+ */
+import type { WidgetTypeKey, WidgetTypeRegistration } from "./types.js";
+/**
+ * The complete v1 widget-type registry (REQ-09), keyed by the closed `WidgetTypeKey` union rather
+ * than held as an array. Declared with `satisfies` rather than a `: Readonly<Record<...>>`
+ * annotation — a `:` annotation would widen every entry back to the shared `WidgetTypeRegistration`
+ * interface (losing e.g. `RECENT_ENTRIES_REGISTRATION`'s own non-optional `clamps.maxItems`);
+ * `satisfies` checks the same shape constraint (every `WidgetTypeKey` has an entry, which is what
+ * makes `getWidgetTypeRegistration` below total) while keeping each entry's own literal type intact.
+ * Iterate with `Object.values(...)` where the whole table is needed (e.g. `agent-tools.ts`'s
+ * published-type-list).
+ */
+export declare const WIDGET_TYPE_REGISTRATIONS: {
+    text: {
+        typeKey: "text";
+        capability: "static";
+        configSchema: {
+            type: string;
+            properties: {
+                body: {
+                    type: string;
+                };
+            };
+            required: string[];
+            additionalProperties: false;
+        };
+        placementContexts: ("region" | "inline")[];
+        clamps: {
+            timeoutMs: number;
+        };
+    };
+    "social-links": {
+        typeKey: "social-links";
+        capability: "static";
+        configSchema: {
+            type: string;
+            properties: {
+                links: {
+                    type: string;
+                    items: {
+                        type: string;
+                        properties: {
+                            platform: {
+                                type: string;
+                            };
+                            url: {
+                                type: string;
+                            };
+                        };
+                        required: string[];
+                        additionalProperties: false;
+                    };
+                    maxItems: number;
+                };
+            };
+            required: string[];
+            additionalProperties: false;
+        };
+        placementContexts: ("region" | "inline")[];
+        clamps: {
+            timeoutMs: number;
+        };
+    };
+    "recent-entries": {
+        typeKey: "recent-entries";
+        capability: "query";
+        configSchema: {
+            type: string;
+            properties: {
+                maxItems: {
+                    type: string;
+                    minimum: number;
+                    maximum: number;
+                };
+                categoryTermId: {
+                    type: string;
+                    "x-ref-target": string;
+                };
+                collection: {
+                    type: string;
+                };
+                where: {
+                    type: string;
+                };
+                sort: {
+                    type: string;
+                };
+                fields: {
+                    type: string;
+                    maxItems: number;
+                    items: {
+                        type: string;
+                    };
+                };
+                layout: {
+                    type: string;
+                };
+                columns: {
+                    type: string;
+                    minimum: number;
+                    maximum: number;
+                };
+                structuredData: {
+                    type: string;
+                };
+            };
+            required: string[];
+            additionalProperties: false;
+        };
+        placementContexts: ("region" | "inline")[];
+        clamps: {
+            maxItems: number;
+            timeoutMs: number;
+        };
+        resolverId: string;
+    };
+    menu: {
+        typeKey: "menu";
+        capability: "entry-reference";
+        configSchema: {
+            type: string;
+            properties: {
+                menuRef: {
+                    type: string;
+                    "x-ref-target": string;
+                };
+            };
+            required: string[];
+            additionalProperties: false;
+        };
+        placementContexts: ("region" | "inline")[];
+        clamps: {
+            timeoutMs: number;
+        };
+        resolverId: string;
+    };
+    "contact-form": {
+        typeKey: "contact-form";
+        capability: "form";
+        configSchema: {
+            type: string;
+            properties: {
+                formDefinitionId: {
+                    type: string;
+                    "x-ref-target": string;
+                };
+                successMessage: {
+                    type: string;
+                };
+            };
+            required: string[];
+            additionalProperties: false;
+        };
+        placementContexts: ("region" | "inline")[];
+        clamps: {
+            timeoutMs: number;
+        };
+        resolverId: string;
+    };
+};
+/**
+ * The total lookup accessor — pure, O(1), no I/O. Only valid for a `typeKey` already narrowed to
+ * `WidgetTypeKey` by the type system itself (a literal, or a value whose type was proven, not
+ * asserted). For a raw/untrusted string that merely claims to be a `WidgetTypeKey` (an HTTP body
+ * field cast at the boundary, e.g. `server/routes/admin/widgets/create.ts`, or a value decoded out
+ * of stored JSON via `entry-payload.ts`'s `parseWidgetInstancePayload`), `undefined` is genuinely
+ * reachable — use `findWidgetTypeRegistration` instead; do not smuggle an unverified string past
+ * this signature with a cast.
+ *
+ * Generic over the specific key, rather than fixed to the `WidgetTypeRegistration` interface, so a
+ * literal call site (`getWidgetTypeRegistration("recent-entries")`) gets back
+ * `WIDGET_TYPE_REGISTRATIONS`'s own entry type for that key — e.g. with `clamps.maxItems: number`,
+ * not the interface's shared `maxItems?: number` — instead of forcing an artificial fallback
+ * (`?? 20`) that coverage could never actually exercise for that one call site.
+ */
+export declare function getWidgetTypeRegistration<K extends WidgetTypeKey>({ typeKey }: {
+    typeKey: K;
+}, _optional?: Record<string, never>): (typeof WIDGET_TYPE_REGISTRATIONS)[K];
+/**
+ * The partial lookup accessor for a raw, untrusted string that has not been proven to be a
+ * `WidgetTypeKey` — only asserted to be one at some upstream boundary (an HTTP body field, or a
+ * value decoded out of stored JSON). Returns `undefined` for any string that isn't one of the five
+ * registered keys, which callers at those boundaries must handle for real (see
+ * `write-service.ts`'s `WidgetTypeUnregisteredError`, `resolvers/index.ts`'s `"unknown-type"`).
+ */
+export declare function findWidgetTypeRegistration({ raw }: {
+    raw: string;
+}, _optional?: Record<string, never>): WidgetTypeRegistration | undefined;
+//# sourceMappingURL=registry.d.ts.map

package/dist/widgets/registry.js

@@ -0,0 +1,172 @@
+/** `text` — static, no resolver (REQ-10). A single free-form rich-text field. */
+const TEXT_REGISTRATION = {
+    typeKey: "text",
+    capability: "static",
+    configSchema: {
+        type: "object",
+        properties: { body: { type: "string" } },
+        required: ["body"],
+        additionalProperties: false,
+    },
+    placementContexts: ["region", "inline"],
+    clamps: { timeoutMs: 0 },
+};
+/** `social-links` — static, no resolver. An ordered list of `{ platform, url }` pairs. */
+const SOCIAL_LINKS_REGISTRATION = {
+    typeKey: "social-links",
+    capability: "static",
+    configSchema: {
+        type: "object",
+        properties: {
+            links: {
+                type: "array",
+                items: {
+                    type: "object",
+                    properties: { platform: { type: "string" }, url: { type: "string" } },
+                    required: ["platform", "url"],
+                    additionalProperties: false,
+                },
+                maxItems: 20,
+            },
+        },
+        required: ["links"],
+        additionalProperties: false,
+    },
+    placementContexts: ["region", "inline"],
+    clamps: { timeoutMs: 0 },
+};
+/**
+ * `recent-entries` — dynamic, `query` capability. `maxItems` is clamped at the
+ * REGISTRATION level (the ceiling any instance's own config may request) AND
+ * re-enforced at the orchestration layer (REQ-25) — defense in depth, not
+ * redundant: this value is what a resolver *may* return at most; the
+ * orchestrator enforces it independent of the resolver's own discipline.
+ *
+ * Declared with `satisfies` rather than a `: WidgetTypeRegistration` annotation so this constant
+ * keeps its own literal shape — `clamps.maxItems: number`, not the shared interface's
+ * `maxItems?: number` — letting `getWidgetTypeRegistration("recent-entries")` (registry.ts) return
+ * a type that's honestly non-optional for THIS registration, without lying for the other four
+ * (`text`/`social-links`/`menu`/`contact-form`) that genuinely have no maxItems clamp.
+ *
+ * Collections plan R1 (2026-09-23): this widget becomes "Collection list" — it now accepts the
+ * same `collection`/`where`/`sort`/`fields`/`layout`/`columns` config keys the `{"type":"collection"}`
+ * marker does (`resolvers/recent-entries.ts` shares C1's `parseCollectionListConfig` parser for
+ * them). `maxItems` stays required and the type key stays `"recent-entries"` — no data migration —
+ * so every existing config (just `{maxItems}`, optionally `categoryTermId`) still validates and
+ * still means exactly what it meant before (D7): no `collection` set means "every user content
+ * type", `sort` defaults to `"updated"`. This write-time schema only checks shape (type/bounds);
+ * `parseCollectionListConfig` does the real field-name/value validation at resolve time.
+ */
+const RECENT_ENTRIES_REGISTRATION = {
+    typeKey: "recent-entries",
+    capability: "query",
+    configSchema: {
+        type: "object",
+        properties: {
+            maxItems: { type: "integer", minimum: 1, maximum: 20 },
+            // REQ-32/EC-03: a taxonomy-term-target soft reference, extracted into entry_refs with
+            // targetKind 'term' (no safe-delete guarantee) — see core/entry-refs/extractor.ts.
+            categoryTermId: { type: "string", "x-ref-target": "term" },
+            // Collections plan R1 additions — shape-only here; `parseCollectionListConfig` (shared with
+            // the `collection` marker, C1) validates field names/values against the named content type.
+            collection: { type: "string" },
+            where: { type: "object" },
+            sort: { type: "string" },
+            fields: { type: "array", maxItems: 20, items: { type: "string" } },
+            layout: { type: "string" },
+            columns: { type: "integer", minimum: 1, maximum: 6 },
+            // AW-7: opt-in schema.org block ("faq-page"); shape-only like `layout`, parsed in public-list.ts.
+            structuredData: { type: "string" },
+        },
+        required: ["maxItems"],
+        additionalProperties: false,
+    },
+    placementContexts: ["region", "inline"],
+    clamps: { maxItems: 20, timeoutMs: 500 },
+    resolverId: "recent-entries",
+};
+/** `menu` — dynamic, `entry-reference` capability. Delegates entirely to `navigation/resolver.ts`. */
+const MENU_REGISTRATION = {
+    typeKey: "menu",
+    capability: "entry-reference",
+    configSchema: {
+        type: "object",
+        // REQ-31: menuRef is an entry-target ref, extracted into entry_refs — see
+        // core/entry-refs/extractor.ts (matches the CONTACT_FORM_REGISTRATION 'x-ref-target' pattern
+        // below).
+        properties: { menuRef: { type: "string", "x-ref-target": "entry" } },
+        required: ["menuRef"],
+        additionalProperties: false,
+    },
+    placementContexts: ["region", "inline"],
+    clamps: { timeoutMs: 500 },
+    resolverId: "menu",
+};
+/**
+ * `contact-form` — dynamic, `form` capability. A thin adapter over `src/forms/`
+ * (REQ-36..39) — this registration carries no submission/rate-limit/mail
+ * config of its own; `formDefinitionId` is a ref-typed field extracted into
+ * `entry_refs` (REQ-31).
+ */
+const CONTACT_FORM_REGISTRATION = {
+    typeKey: "contact-form",
+    capability: "form",
+    configSchema: {
+        type: "object",
+        properties: {
+            formDefinitionId: { type: "string", "x-ref-target": "entry" },
+            successMessage: { type: "string" },
+        },
+        required: ["formDefinitionId"],
+        additionalProperties: false,
+    },
+    placementContexts: ["region", "inline"],
+    clamps: { timeoutMs: 500 },
+    resolverId: "contact-form",
+};
+/**
+ * The complete v1 widget-type registry (REQ-09), keyed by the closed `WidgetTypeKey` union rather
+ * than held as an array. Declared with `satisfies` rather than a `: Readonly<Record<...>>`
+ * annotation — a `:` annotation would widen every entry back to the shared `WidgetTypeRegistration`
+ * interface (losing e.g. `RECENT_ENTRIES_REGISTRATION`'s own non-optional `clamps.maxItems`);
+ * `satisfies` checks the same shape constraint (every `WidgetTypeKey` has an entry, which is what
+ * makes `getWidgetTypeRegistration` below total) while keeping each entry's own literal type intact.
+ * Iterate with `Object.values(...)` where the whole table is needed (e.g. `agent-tools.ts`'s
+ * published-type-list).
+ */
+export const WIDGET_TYPE_REGISTRATIONS = {
+    text: TEXT_REGISTRATION,
+    "social-links": SOCIAL_LINKS_REGISTRATION,
+    "recent-entries": RECENT_ENTRIES_REGISTRATION,
+    menu: MENU_REGISTRATION,
+    "contact-form": CONTACT_FORM_REGISTRATION,
+};
+/**
+ * The total lookup accessor — pure, O(1), no I/O. Only valid for a `typeKey` already narrowed to
+ * `WidgetTypeKey` by the type system itself (a literal, or a value whose type was proven, not
+ * asserted). For a raw/untrusted string that merely claims to be a `WidgetTypeKey` (an HTTP body
+ * field cast at the boundary, e.g. `server/routes/admin/widgets/create.ts`, or a value decoded out
+ * of stored JSON via `entry-payload.ts`'s `parseWidgetInstancePayload`), `undefined` is genuinely
+ * reachable — use `findWidgetTypeRegistration` instead; do not smuggle an unverified string past
+ * this signature with a cast.
+ *
+ * Generic over the specific key, rather than fixed to the `WidgetTypeRegistration` interface, so a
+ * literal call site (`getWidgetTypeRegistration("recent-entries")`) gets back
+ * `WIDGET_TYPE_REGISTRATIONS`'s own entry type for that key — e.g. with `clamps.maxItems: number`,
+ * not the interface's shared `maxItems?: number` — instead of forcing an artificial fallback
+ * (`?? 20`) that coverage could never actually exercise for that one call site.
+ */
+export function getWidgetTypeRegistration({ typeKey }, _optional = {}) {
+    return WIDGET_TYPE_REGISTRATIONS[typeKey];
+}
+/**
+ * The partial lookup accessor for a raw, untrusted string that has not been proven to be a
+ * `WidgetTypeKey` — only asserted to be one at some upstream boundary (an HTTP body field, or a
+ * value decoded out of stored JSON). Returns `undefined` for any string that isn't one of the five
+ * registered keys, which callers at those boundaries must handle for real (see
+ * `write-service.ts`'s `WidgetTypeUnregisteredError`, `resolvers/index.ts`'s `"unknown-type"`).
+ */
+export function findWidgetTypeRegistration({ raw }, _optional = {}) {
+    return Object.values(WIDGET_TYPE_REGISTRATIONS).find((registration) => registration.typeKey === raw);
+}
+//# sourceMappingURL=registry.js.map

package/dist/widgets/repo.memory.d.ts

@@ -0,0 +1,41 @@
+import type { UUID } from "@jini-ai/core/primitives";
+import type { WidgetRegionBindingRepoPort } from "./ports.js";
+import type { WidgetRegionBindingRow, WidgetRegionKey } from "./types.js";
+/**
+ * @file In-memory `WidgetRegionBindingRepoPort` adapter (ADR-006 rule-of-two "one being built now"
+ * half — `repo.sqlite.ts` is the other), mirroring `navigation/repo.memory.ts`'s
+ * `InMemoryNavLocationBindingRepo` exactly: enforces `UNIQUE(workspace_id, region_key)` by storing
+ * at most one row per `(workspaceId, regionKey)` pair, `upsert` replacing any prior row for that
+ * key (last-writer-wins, same discipline `NavLocationBindingRepoPort.upsert` documents).
+ *
+ * Architectural role:
+ * Infrastructure adapter (in-memory). No feature logic — that is `region-area-service.ts`'s job;
+ * this class is a dumb, uniqueness-enforcing collection.
+ */
+export declare class InMemoryWidgetRegionBindingRepo implements WidgetRegionBindingRepoPort {
+    private rows;
+    constructor(initialRows?: WidgetRegionBindingRow[]);
+    findByRegion(required: {
+        workspaceId: UUID;
+        regionKey: WidgetRegionKey;
+    }): Promise<WidgetRegionBindingRow | null>;
+    listByWorkspace(required: {
+        workspaceId: UUID;
+    }): Promise<WidgetRegionBindingRow[]>;
+    upsert(required: {
+        workspaceId: UUID;
+        regionKey: WidgetRegionKey;
+        areaEntryId: UUID;
+        updatedAt: string;
+    }): Promise<WidgetRegionBindingRow>;
+    /** REQ-14 — a theme switch orphaned this region key: drop the binding row, retain the underlying `widget_area` entry (untouched by this port). */
+    markInactive(required: {
+        workspaceId: UUID;
+        regionKey: WidgetRegionKey;
+    }): Promise<void>;
+    rebuildForWorkspace(required: {
+        workspaceId: UUID;
+        bindings: readonly WidgetRegionBindingRow[];
+    }): Promise<void>;
+}
+//# sourceMappingURL=repo.memory.d.ts.map

package/dist/widgets/repo.memory.js

@@ -0,0 +1,48 @@
+/**
+ * @file In-memory `WidgetRegionBindingRepoPort` adapter (ADR-006 rule-of-two "one being built now"
+ * half — `repo.sqlite.ts` is the other), mirroring `navigation/repo.memory.ts`'s
+ * `InMemoryNavLocationBindingRepo` exactly: enforces `UNIQUE(workspace_id, region_key)` by storing
+ * at most one row per `(workspaceId, regionKey)` pair, `upsert` replacing any prior row for that
+ * key (last-writer-wins, same discipline `NavLocationBindingRepoPort.upsert` documents).
+ *
+ * Architectural role:
+ * Infrastructure adapter (in-memory). No feature logic — that is `region-area-service.ts`'s job;
+ * this class is a dumb, uniqueness-enforcing collection.
+ */
+export class InMemoryWidgetRegionBindingRepo {
+    rows;
+    constructor(initialRows = []) {
+        this.rows = [...initialRows];
+    }
+    async findByRegion(required) {
+        return (this.rows.find((row) => row.workspaceId === required.workspaceId && row.regionKey === required.regionKey) ?? null);
+    }
+    async listByWorkspace(required) {
+        return this.rows.filter((row) => row.workspaceId === required.workspaceId);
+    }
+    async upsert(required) {
+        const row = {
+            workspaceId: required.workspaceId,
+            regionKey: required.regionKey,
+            areaEntryId: required.areaEntryId,
+            updatedAt: required.updatedAt,
+        };
+        const index = this.rows.findIndex((existing) => existing.workspaceId === required.workspaceId && existing.regionKey === required.regionKey);
+        if (index === -1) {
+            this.rows.push(row);
+        }
+        else {
+            this.rows[index] = row;
+        }
+        return row;
+    }
+    /** REQ-14 — a theme switch orphaned this region key: drop the binding row, retain the underlying `widget_area` entry (untouched by this port). */
+    async markInactive(required) {
+        this.rows = this.rows.filter((row) => !(row.workspaceId === required.workspaceId && row.regionKey === required.regionKey));
+    }
+    async rebuildForWorkspace(required) {
+        const others = this.rows.filter((row) => row.workspaceId !== required.workspaceId);
+        this.rows = [...others, ...required.bindings];
+    }
+}
+//# sourceMappingURL=repo.memory.js.map