@jini-ai/cms 0.5.2 → 0.5.3

package/dist/settings/express/stream.d.ts

@@ -0,0 +1,24 @@
+import type { Request, Response } from "express";
+import type { Authorize, SettingsChangeFeed, SettingsHttpOptions, Scheduler } from "./contracts.js";
+interface StreamRequired {
+    request: Request;
+    response: Response;
+    workspaceId: string;
+    principalId: string;
+    changeFeed: SettingsChangeFeed;
+    authorize: Authorize;
+    permission: string;
+    scheduler: Scheduler;
+    onClose: (required: {
+        close: () => void;
+    }) => void;
+    isDisposed: () => boolean;
+}
+/** Starts after HTTP authorization. All scheduling and storage are injected. */
+/** Poll with bounded pages, tenant-scoped ids and retryable reads; close cancels all schedules.
+ * O(page size) per tick and O(1) connection state; repository effects live behind the feed port.
+ * Invalid scheduler intervals/page sizes throw RangeError before opening; initial read errors propagate.
+ */
+export declare function openSettingsChangeStream(required: StreamRequired, optional?: SettingsHttpOptions): Promise<() => void>;
+export {};
+//# sourceMappingURL=stream.d.ts.map

package/dist/settings/express/stream.js

@@ -0,0 +1,147 @@
+/** Starts after HTTP authorization. All scheduling and storage are injected. */
+/** Poll with bounded pages, tenant-scoped ids and retryable reads; close cancels all schedules.
+ * O(page size) per tick and O(1) connection state; repository effects live behind the feed port.
+ * Invalid scheduler intervals/page sizes throw RangeError before opening; initial read errors propagate.
+ */
+export async function openSettingsChangeStream(required, optional = {}) {
+    const { request, response, workspaceId, principalId, changeFeed, scheduler } = required;
+    const pageSize = optional.revisionPageSize ?? 200;
+    const intervals = [optional.pollIntervalMs ?? 1_000, optional.keepaliveIntervalMs ?? 25_000, optional.reauthorizeIntervalMs ?? 30_000];
+    if (!Number.isSafeInteger(pageSize) || pageSize <= 0 || intervals.some((n) => !Number.isFinite(n) || n <= 0)) {
+        throw new RangeError("settings feed page size and intervals must be positive");
+    }
+    let closed = false;
+    let ticking = false;
+    let checkingAuthorization = false;
+    const cancellations = [];
+    const reportError = (operation, error) => {
+        // Reporting is best-effort: a host hook must never turn recovery into an unhandled rejection.
+        try {
+            if (optional.onError)
+                optional.onError({ operation, error });
+            else
+                console.error(`[settings] change feed ${operation} failed`, error);
+        }
+        catch { /* Diagnostic failures cannot interrupt stream cleanup or retries. */ }
+    };
+    const recover = (operation, effect) => {
+        try {
+            effect();
+        }
+        catch (error) {
+            reportError(operation, error);
+        }
+    };
+    const release = () => {
+        // Every resource gets its own recovery boundary so one failing cancellation cannot leak others.
+        for (const cancel of cancellations.splice(0))
+            recover("cancel", cancel);
+        recover("request-listener", () => { request.off("close", close); });
+        recover("response-listener", () => { response.off("close", close); });
+    };
+    const close = () => {
+        if (closed)
+            return;
+        closed = true;
+        release();
+        recover("close", () => { required.onClose({ close }); });
+        if (!response.writableEnded && !response.destroyed)
+            recover("end", () => { response.end(); });
+    };
+    request.on("close", close);
+    response.on("close", close);
+    try {
+        const head = await changeFeed.head({});
+        if (closed || required.isDisposed() || response.destroyed || response.writableEnded) {
+            close();
+            return close;
+        }
+        const resumeFrom = Number(request.headers["last-event-id"]);
+        let cursor = Number.isFinite(resumeFrom) && resumeFrom >= 0 ? Math.min(resumeFrom, head) : head;
+        let lastEmittedId = cursor;
+        const viewer = { workspaceId, principalId };
+        response.writeHead(200, {
+            "Content-Type": "text/event-stream", "Cache-Control": "no-cache, no-transform",
+            ...(request.httpVersionMajor < 2 ? { Connection: "keep-alive" } : {}), "X-Accel-Buffering": "no",
+        });
+        const tick = async () => {
+            if (closed || ticking)
+                return;
+            ticking = true;
+            try {
+                // Snapshot head before the page: concurrent writes must never be skipped.
+                const ledgerHead = await changeFeed.head({});
+                if (closed)
+                    return;
+                const batch = await changeFeed.collect({ sinceSeq: cursor, limit: pageSize, viewer });
+                if (closed)
+                    return;
+                const examined = batch.examinedCount < pageSize ? ledgerHead : batch.cursor;
+                cursor = Math.max(cursor, examined, batch.cursor);
+                if (!batch.namespaces.length)
+                    return;
+                // The internal global head is never disclosed as an event id.
+                lastEmittedId = Math.max(lastEmittedId, batch.cursor);
+                response.write(`id: ${lastEmittedId}\nevent: settings-changed\ndata: ${JSON.stringify({ namespaces: batch.namespaces })}\n\n`);
+            }
+            catch (error) {
+                if (!closed)
+                    reportError("poll", error);
+            }
+            finally {
+                ticking = false;
+            }
+        };
+        const reauthorize = async () => {
+            if (closed || checkingAuthorization)
+                return;
+            checkingAuthorization = true;
+            try {
+                const result = await required.authorize({ principalId, workspaceId, permission: required.permission, entityType: "setting-value" });
+                if (!closed && !result.allowed)
+                    close();
+            }
+            catch (error) {
+                if (!closed)
+                    reportError("re-authorization", error);
+            }
+            finally {
+                checkingAuthorization = false;
+            }
+        };
+        const schedule = (intervalMs, callback) => {
+            const cancel = scheduler.every({ intervalMs, callback });
+            if (closed)
+                recover("cancel", cancel);
+            else
+                cancellations.push(cancel);
+        };
+        schedule(intervals[0], () => { void tick(); });
+        schedule(intervals[1], () => {
+            if (closed)
+                return;
+            try {
+                response.write(": keepalive\n\n");
+            }
+            catch (error) {
+                reportError("keepalive", error);
+                close();
+            }
+        });
+        schedule(intervals[2], () => { void reauthorize(); });
+        if (!closed)
+            response.write(": connected\n\n");
+        return close;
+    }
+    catch (error) {
+        // Cancel schedules even when opening a feed fails. Let the HTTP wrapper map the error.
+        if (response.headersSent)
+            close();
+        else {
+            closed = true;
+            release();
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=stream.js.map

package/dist/settings/index.d.ts

@@ -1,40 +1,5 @@
-/**
- * @file Public surface (barrel) for the `settings` library.
- *
- * A module's public contract is its `index.ts` — deep imports from outside
- * this directory should go through here.
- *
- * A host's `repo.sqlite.ts` adapter and any one-time brownfield migration of a
- * host's own legacy pre-ledger settings table are NOT part of this package —
- * a fresh host has no legacy data to migrate, and a SQLite adapter names a
- * host's own database schema. Both stay host-side, composed against the
- * `SettingsRepoPort` this barrel exports.
+/** @deprecated For one compatibility release: settings are generic and owned by core.
+ * Re-export the owner so published consumers retain function, error and cache identities.
  */
-export { SCOPE_BIT, type SettingScope, type SettingOwnerKind, type DefinitionStatus, type ValueState, type RevisionEntityKind, type RevisionOp, type SettingValueSchema, type SettingDefinitionRecord, type SettingValueRecord, type SettingRevisionRecord, type SettingScopeContext, } from "./types.js";
-export { DefinitionInvalidError, ScopeNotAllowedError, SecretNotSupportedError, ValueValidationFailedError, RenameRetypeConflictError, AliasDepthExceededError, DefinitionTombstonedError, DefinitionNotFoundError, PurgeRequiredError, ForbiddenError, PrincipalNotFoundError, } from "./errors.js";
-export type { SettingsRepoPort } from "./ports.js";
-export { InMemorySettingsRepo } from "./repo.memory.js";
-export { type DefinitionInput, validateDefinitionInput, validateValueAgainstSchema, registerCoercer, invalidateDefinitionNamespaceCache, invalidateWorkspaceSettingsCache, resolveDefinitionRaw, resolveDefinition, type ResolvedSetting, getEffective, } from "./settings.js";
-export { type AuthorizeFn, type SettingsWriteServiceDeps, deriveRequiredPermission, type RegisterDefinitionsRequired, registerDefinitions, type SetValueRequired, set, type ClearValueRequired, clear, type ResetNamespaceRequired, resetNamespace, type RenameDefinitionRequired, renameDefinition, type RetypeDefinitionRequired, retypeDefinition, type ReconcileDefinitionDefaultRequired, reconcileDefinitionDefault, type DeprecateDefinitionRequired, deprecateDefinition, type TombstoneDefinitionRequired, tombstoneDefinition, } from "./write-service.js";
-export { type PurgeServiceDeps, type PurgeTenantSettingsRequired, purgeTenantSettings, } from "./purge-service.js";
-export { type ChangeFeedViewer, isRevisionVisibleTo, type ChangeFeedBatch, collectChangedNamespaces, } from "./change-feed.js";
-export { type DefinitionOpRequestItem, type DefinitionOpContext, type DefinitionOpHandler, NON_REGISTER_DEFINITION_OP_NAMES, type NonRegisterDefinitionOp, parseNonRegisterDefinitionOp, NON_REGISTER_DEFINITION_OPS, } from "./definitions-dispatch.js";
-export { type SettingDefinitionSpec, type EnsureSettingDefinitionsDeps, type EnsureSettingDefinitionsInput, ensureSettingDefinitions, } from "./ensure-definitions.js";
-export { INSTRUCTIONS_NAMESPACE, NOTIFICATIONS_NAMESPACE, PRIVACY_NAMESPACE, APPEARANCE_NAMESPACE, LANGUAGE_NAMESPACE, type EnsureSettingsUiTabDefinitionsInput, ensureSettingsUiTabDefinitions, } from "./ui-tab-definitions.js";
-export { type AgentWritablePreference, AGENT_PREFERENCE_WRITE_SCOPE, AGENT_WRITABLE_PREFERENCES, AGENT_WRITABLE_PREFERENCE_IDS, resolveAgentWritablePreference, AGENT_PREFERENCE_REQUIRED_SCOPE_BIT, } from "./agent-writable-preferences.js";
-/** The agent-tool catalog for this domain. */
-export { getSettingsAgentToolCatalog, } from "./agent-tools.js";
-/**
- * The agent-tool wiring for this domain.
- *
- * `SettingsToolDeps` is declared structurally rather than derived from any host's request-scoped
- * dependency bag, which is what lets a host satisfy it by passing whatever object it already has —
- * the shape is the contract, so no host type needs to be named here.
- */
-export { buildSettingsRegistrations, settingsDerivedRisk, type SettingsToolDeps, } from "./tool-registrations.js";
-/** The settings-dialog chrome copy (24 generic tab labels/subtitles), shared across every host. */
-export { SETTINGS_DIALOG_DICTIONARIES, translateSettingsDialog } from "./dictionaries/index.js";
-export { AGENT_WRITE_CONFIRMATION_SETTINGS, AGENT_WRITE_DENIED_SETTINGS, findAgentWriteRule, type AgentSettingWriteRule } from "./agent-write-denylist.js";
-export type { SettingsWriteConfirmation, SettingsValueWriteToolId } from "./agent-value-write-tools.js";
-export type { SettingsPrincipalLookupPort } from "./principal-lookup.js";
+export * from "@jini-ai/core/settings";
 //# sourceMappingURL=index.d.ts.map

package/dist/settings/index.js

@@ -1,37 +1,5 @@
-/**
- * @file Public surface (barrel) for the `settings` library.
- *
- * A module's public contract is its `index.ts` — deep imports from outside
- * this directory should go through here.
- *
- * A host's `repo.sqlite.ts` adapter and any one-time brownfield migration of a
- * host's own legacy pre-ledger settings table are NOT part of this package —
- * a fresh host has no legacy data to migrate, and a SQLite adapter names a
- * host's own database schema. Both stay host-side, composed against the
- * `SettingsRepoPort` this barrel exports.
+/** @deprecated For one compatibility release: settings are generic and owned by core.
+ * Re-export the owner so published consumers retain function, error and cache identities.
  */
-export { SCOPE_BIT, } from "./types.js";
-export { DefinitionInvalidError, ScopeNotAllowedError, SecretNotSupportedError, ValueValidationFailedError, RenameRetypeConflictError, AliasDepthExceededError, DefinitionTombstonedError, DefinitionNotFoundError, PurgeRequiredError, ForbiddenError, PrincipalNotFoundError, } from "./errors.js";
-export { InMemorySettingsRepo } from "./repo.memory.js";
-export { validateDefinitionInput, validateValueAgainstSchema, registerCoercer, invalidateDefinitionNamespaceCache, invalidateWorkspaceSettingsCache, resolveDefinitionRaw, resolveDefinition, getEffective, } from "./settings.js";
-export { deriveRequiredPermission, registerDefinitions, set, clear, resetNamespace, renameDefinition, retypeDefinition, reconcileDefinitionDefault, deprecateDefinition, tombstoneDefinition, } from "./write-service.js";
-export { purgeTenantSettings, } from "./purge-service.js";
-export { isRevisionVisibleTo, collectChangedNamespaces, } from "./change-feed.js";
-export { NON_REGISTER_DEFINITION_OP_NAMES, parseNonRegisterDefinitionOp, NON_REGISTER_DEFINITION_OPS, } from "./definitions-dispatch.js";
-export { ensureSettingDefinitions, } from "./ensure-definitions.js";
-export { INSTRUCTIONS_NAMESPACE, NOTIFICATIONS_NAMESPACE, PRIVACY_NAMESPACE, APPEARANCE_NAMESPACE, LANGUAGE_NAMESPACE, ensureSettingsUiTabDefinitions, } from "./ui-tab-definitions.js";
-export { AGENT_PREFERENCE_WRITE_SCOPE, AGENT_WRITABLE_PREFERENCES, AGENT_WRITABLE_PREFERENCE_IDS, resolveAgentWritablePreference, AGENT_PREFERENCE_REQUIRED_SCOPE_BIT, } from "./agent-writable-preferences.js";
-/** The agent-tool catalog for this domain. */
-export { getSettingsAgentToolCatalog, } from "./agent-tools.js";
-/**
- * The agent-tool wiring for this domain.
- *
- * `SettingsToolDeps` is declared structurally rather than derived from any host's request-scoped
- * dependency bag, which is what lets a host satisfy it by passing whatever object it already has —
- * the shape is the contract, so no host type needs to be named here.
- */
-export { buildSettingsRegistrations, settingsDerivedRisk, } from "./tool-registrations.js";
-/** The settings-dialog chrome copy (24 generic tab labels/subtitles), shared across every host. */
-export { SETTINGS_DIALOG_DICTIONARIES, translateSettingsDialog } from "./dictionaries/index.js";
-export { AGENT_WRITE_CONFIRMATION_SETTINGS, AGENT_WRITE_DENIED_SETTINGS, findAgentWriteRule } from "./agent-write-denylist.js";
+export * from "@jini-ai/core/settings";
 //# sourceMappingURL=index.js.map

package/dist/taxonomy/write-service.d.ts

@@ -1,3 +1,5 @@
+import type { TransactionalRepoPort } from "../core/ports.js";
+export type { TransactionalRepoPort } from "../core/ports.js";
 import type { Clock, IdGenerator } from "@jini-ai/core/primitives";
 import type { TermListPort } from "./list.js";
 /**
@@ -459,36 +461,6 @@ export declare class TaxonomyHasAssignedContentError extends Error {
         assignedCount: number;
     }, _optionalArgs?: Record<string, never>);
 }
-/**
- * Opens/commits/rolls back one transaction around `fn` — the same shape and contract as this
- * codebase's other write chokepoints that need one (`RedirectsWriteDeps.transaction`,
- * `SqliteSettingsRepo.transaction`).
- *
- * `deleteTerm`/`deleteTaxonomy` run their ENTIRE body — every guard read (`findById`,
- * `countChildren`, `countByTerm`) AND every write (`delete`, `revisions.insert`, `outbox.enqueue`)
- * — inside one call to this. Two failure modes this closes that a guard-then-transaction split
- * would not:
- *
- * 1. **TOCTOU on the guard.** A guard read taken BEFORE the transaction opens can go stale the
- *    instant it returns — content can be assigned to the term in the gap between the read and the
- *    delete, and the delete would proceed having checked a now-wrong count. Putting the read
- *    inside the same transaction as the delete is what makes the guard's answer still true at the
- *    moment the delete actually runs.
- * 2. **Partial cascade.** `deleteTaxonomy` deletes N member terms then the taxonomy row itself,
- *    with no FK/CASCADE at the schema level (`db/schema.ts` — `taxonomies`/`terms`/`entry_terms`/
- *    `taxonomy_revisions` are plain columns, no foreign keys) to undo a mid-cascade failure. A
- *    real transaction is the only thing that can.
- *
- * A caller-supplied identity/no-op implementation is a valid choice for a backend that has no
- * separate transaction primitive to offer (see `repo.memory.ts`'s `InMemoryTaxonomyRepo` for the
- * disclosed rationale) — the port exists so `deleteTerm`/`deleteTaxonomy` never have to know which
- * kind of backend they're running against.
- */
-export interface TransactionalRepoPort {
-    transaction<T>({ fn }: {
-        fn: () => Promise<T>;
-    }): Promise<T>;
-}
 export interface DeleteTermRequired {
     deps: WriteServiceDeps & {
         terms: DeletableTermRepoPort;

package/dist/widgets/authorize-helper.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @file Shared `authorize()` plumbing for `write-service.ts`/`region-area-service.ts` (SPEC-043
+ * REQ-40/41, INV-07).
+ *
+ * Purpose:
+ * `AuthorizeFn` mirrors `features/entries/write-service.ts`'s `AuthorizeFn` shape structurally (no
+ * shared import, kept decoupled — the same "no shared import" convention that file's own header
+ * documents against `features/content-types`). `requireWidgetPermission` is the ONE place a
+ * `widgets.*` permission string gets checked before a mutation proceeds.
+ *
+ * `PRE_AUTHORIZED` exists because this library composes `features/entries/write-service.ts`'s
+ * `createEntry`/`updateEntry` and `features/content-types/write-service.ts`'s `registerContentType`
+ * — both of which perform their OWN internal `authorize()` call, hardcoded to the
+ * `admin.collections.manage` permission (the generic Collections-domain permission, unrelated to
+ * widgets' own `widgets.*` model, and not modifiable — see this task's scope boundary on
+ * `features/entries`). Since the real, authoritative check for a widget mutation is the
+ * `widgets.*` check `requireWidgetPermission` already performed one layer up, `PRE_AUTHORIZED` is
+ * passed as those composed functions' own `authorize` dependency so their internal check is not a
+ * second, differently-scoped gate a legitimate `widgets.*`-holding caller could be incorrectly
+ * rejected by.
+ */
+export type WidgetsAuthorizeFn = (params: {
+    principalId: string;
+    permission: string;
+    workspaceId: string;
+}) => Promise<{
+    allowed: boolean;
+    reason: string;
+}>;
+export declare function requireWidgetPermission(required: {
+    authorize: WidgetsAuthorizeFn;
+    actor: {
+        principalId: string;
+    };
+    workspaceId: string;
+    permission: string;
+}, _optional?: Record<string, never>): Promise<void>;
+/** See file header — passed as the composed entries/content-types chokepoints' own `authorize` dep. */
+export declare const PRE_AUTHORIZED: WidgetsAuthorizeFn;
+/** The actor id attributed to fully-automatic, system-driven writes (content-type seeding, theme-activation region seeding — REQ-13). Mirrors `server/seed.ts`'s `SETTINGS_MIGRATION_SYSTEM_PRINCIPAL_ID` convention. */
+export declare const WIDGETS_SYSTEM_ACTOR_ID = "system-widgets";
+//# sourceMappingURL=authorize-helper.d.ts.map

package/dist/widgets/authorize-helper.js

@@ -0,0 +1,16 @@
+import { WidgetForbiddenError } from "./errors.js";
+export async function requireWidgetPermission(required, _optional = {}) {
+    const { authorize, actor, workspaceId, permission } = required;
+    const result = await authorize({ principalId: actor.principalId, permission, workspaceId });
+    if (!result.allowed) {
+        throw new WidgetForbiddenError({ message: `principal '${actor.principalId}' lacks permission '${permission}' (${result.reason})` });
+    }
+}
+/** See file header — passed as the composed entries/content-types chokepoints' own `authorize` dep. */
+export const PRE_AUTHORIZED = async () => ({
+    allowed: true,
+    reason: "widgets: authorized upstream via the widgets.* permission check",
+});
+/** The actor id attributed to fully-automatic, system-driven writes (content-type seeding, theme-activation region seeding — REQ-13). Mirrors `server/seed.ts`'s `SETTINGS_MIGRATION_SYSTEM_PRINCIPAL_ID` convention. */
+export const WIDGETS_SYSTEM_ACTOR_ID = "system-widgets";
+//# sourceMappingURL=authorize-helper.js.map

package/dist/widgets/concurrency.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Runs `fn` exclusively with respect to every other `withEntryLock` call sharing the same `key` —
+ * callers queue in call order, each waiting for the previous holder to finish.
+ *
+ * @complexity O(1) scheduling overhead beyond `fn`'s own cost.
+ * @overallScore 100
+ */
+export declare function withEntryLock<T>({ key, fn }: {
+    key: string;
+    fn: () => Promise<T>;
+}, _optional?: Record<string, never>): Promise<T>;
+//# sourceMappingURL=concurrency.d.ts.map

package/dist/widgets/concurrency.js

@@ -0,0 +1,44 @@
+/**
+ * @file A tiny per-key async mutex (SPEC-043 REQ-06/15, AC-04/EC-02).
+ *
+ * Purpose:
+ * `features/entries/write-service.ts`'s `updateEntry` reads the current row, checks
+ * `expectedVersion`, then writes — but `InMemoryEntryRepo.transaction` provides no real
+ * serialization (`async transaction(fn) { return fn(); }`), and the version check itself happens
+ * BEFORE that transaction call. Two truly concurrent callers racing the same entry id can both
+ * observe the pre-write version and both pass the check under the in-memory adapter (the real
+ * `SqliteEntryRepo.transaction`'s `BEGIN IMMEDIATE` already serializes real concurrent writers at
+ * the DB layer — this mutex is redundant-but-harmless there, and load-bearing for the in-memory
+ * path this test suite's concurrency assertions exercise).
+ *
+ * This module serializes the whole "read current version -> validate -> call updateEntry" sequence
+ * per entry id at the WIDGETS domain layer, restoring correct optimistic-concurrency semantics
+ * deterministically regardless of the underlying repo adapter's own concurrency properties.
+ *
+ * Architectural role:
+ * `widgets` domain-internal helper, not a frozen public contract.
+ */
+const locks = new Map();
+/**
+ * Runs `fn` exclusively with respect to every other `withEntryLock` call sharing the same `key` —
+ * callers queue in call order, each waiting for the previous holder to finish.
+ *
+ * @complexity O(1) scheduling overhead beyond `fn`'s own cost.
+ * @overallScore 100
+ */
+export async function withEntryLock({ key, fn }, _optional = {}) {
+    const previous = locks.get(key) ?? Promise.resolve();
+    let release;
+    const next = new Promise((resolve) => {
+        release = resolve;
+    });
+    locks.set(key, previous.then(() => next));
+    await previous;
+    try {
+        return await fn();
+    }
+    finally {
+        release();
+    }
+}
+//# sourceMappingURL=concurrency.js.map

package/dist/widgets/config-validation.d.ts

@@ -0,0 +1,34 @@
+export interface WidgetConfigFieldError {
+    readonly field: string;
+    readonly reason: string;
+}
+export interface ValidateWidgetConfigResult {
+    readonly valid: boolean;
+    readonly fieldErrors: WidgetConfigFieldError[];
+}
+/**
+ * Validates `config` against a widget type's registered `configSchema` (REQ-02). The registered
+ * schema is always the authority — a type's own `clamps` (e.g. `recent-entries`' `maxItems: 20`)
+ * are already expressed as `maximum` constraints inside the schema itself (`registry.ts`), so no
+ * separate clamp check is needed here to satisfy AC-02.
+ *
+ * @complexity O(n) over the config bag's total node count.
+ * @overallScore 100
+ */
+export declare function validateWidgetConfig(required: {
+    schema: Record<string, unknown>;
+    config: Record<string, unknown>;
+}, _optional?: Record<string, never>): ValidateWidgetConfigResult;
+/**
+ * Every free-text string `config` holds where its type's `configSchema` declares one — a `text`
+ * widget's `body`, each social link's `url`. Ref fields (`x-ref-target`) are left out (they name
+ * other content by id) and so is anything the schema does not declare (`recent-entries`' `where`).
+ * The publish carry-along (`publish-content.ts`) reads media URLs out of these.
+ *
+ * @complexity O(n) over the config's declared nodes.
+ */
+export declare function collectWidgetConfigStrings(required: {
+    schema: Record<string, unknown>;
+    config: Record<string, unknown>;
+}, _optional?: Record<string, never>): string[];
+//# sourceMappingURL=config-validation.d.ts.map

package/dist/widgets/config-validation.js

@@ -0,0 +1,125 @@
+import { isNonArrayRecord } from "@jini-ai/core";
+/** Reports every key in `schema.required` that is missing from `value`. */
+function validateRequiredKeys(value, schema, path, errors) {
+    for (const key of schema.required ?? []) {
+        if (!(key in value))
+            errors.push({ field: `${path}.${key}`, reason: "required field is missing" });
+    }
+}
+/** Recurses into each `value` key that has a declared `schema.properties` entry; flags the rest when `additionalProperties` is `false`. */
+function walkObjectProperties(value, schema, path, errors) {
+    for (const [key, fieldValue] of Object.entries(value)) {
+        const propSchema = schema.properties?.[key];
+        if (!propSchema) {
+            if (schema.additionalProperties === false) {
+                errors.push({ field: `${path}.${key}`, reason: "unrecognized field: not present in the registered schema" });
+            }
+            continue;
+        }
+        walk(fieldValue, propSchema, `${path}.${key}`, errors);
+    }
+}
+/** Checks `required` keys are present and recurses into each declared property (schema.type === "object"). */
+function walkObject(value, schema, path, errors) {
+    const record = { value };
+    if (!isNonArrayRecord(record)) {
+        errors.push({ field: path, reason: "expected an object" });
+        return;
+    }
+    validateRequiredKeys(record.value, schema, path, errors);
+    walkObjectProperties(record.value, schema, path, errors);
+}
+/** schema.type === "string": type check only, no length/pattern constraint in this subset. */
+function walkString(value, path, errors) {
+    if (typeof value !== "string")
+        errors.push({ field: path, reason: "expected a string" });
+}
+/** schema.type === "integer": type check plus optional `minimum`/`maximum` bounds. */
+function walkInteger(value, schema, path, errors) {
+    if (typeof value !== "number" || !Number.isInteger(value)) {
+        errors.push({ field: path, reason: "expected an integer" });
+        return;
+    }
+    if (schema.minimum !== undefined && value < schema.minimum) {
+        errors.push({ field: path, reason: `below the minimum of ${schema.minimum}` });
+    }
+    if (schema.maximum !== undefined && value > schema.maximum) {
+        errors.push({ field: path, reason: `above the maximum of ${schema.maximum}` });
+    }
+}
+/** schema.type === "array": type check, optional `maxItems` bound, and recursion into `items`. */
+function walkArray(value, schema, path, errors) {
+    if (!Array.isArray(value)) {
+        errors.push({ field: path, reason: "expected an array" });
+        return;
+    }
+    if (schema.maxItems !== undefined && value.length > schema.maxItems) {
+        errors.push({ field: path, reason: `exceeds the maximum item count of ${schema.maxItems}` });
+    }
+    if (schema.items) {
+        value.forEach((item, index) => {
+            walk(item, schema.items, `${path}[${index}]`, errors);
+        });
+    }
+}
+/** Dispatches to the per-type walker for `schema.type` (object/string/integer/array); unspecified or boolean types accept anything. */
+function walk(value, schema, path, errors) {
+    switch (schema.type) {
+        case "object":
+            walkObject(value, schema, path, errors);
+            return;
+        case "string":
+            walkString(value, path, errors);
+            return;
+        case "integer":
+            walkInteger(value, schema, path, errors);
+            return;
+        case "array":
+            walkArray(value, schema, path, errors);
+            return;
+        default:
+            // boolean / unspecified schema type: accept anything (no v1 registration needs this).
+            return;
+    }
+}
+/**
+ * Validates `config` against a widget type's registered `configSchema` (REQ-02). The registered
+ * schema is always the authority — a type's own `clamps` (e.g. `recent-entries`' `maxItems: 20`)
+ * are already expressed as `maximum` constraints inside the schema itself (`registry.ts`), so no
+ * separate clamp check is needed here to satisfy AC-02.
+ *
+ * @complexity O(n) over the config bag's total node count.
+ * @overallScore 100
+ */
+export function validateWidgetConfig(required, _optional = {}) {
+    const errors = [];
+    walk(required.config, required.schema, "config", errors);
+    return { valid: errors.length === 0, fieldErrors: errors };
+}
+/** Pushes each declared free-text string under `schema` (recursion into declared `properties` and
+ *  `items` only). @complexity O(n) over the config's declared nodes. */
+function collectStrings(value, schema, out) {
+    const record = { value };
+    if (schema.type === "string" && typeof value === "string" && schema["x-ref-target"] === undefined)
+        out.push(value);
+    else if (schema.type === "array" && Array.isArray(value) && schema.items)
+        for (const item of value)
+            collectStrings(item, schema.items, out);
+    else if (schema.type === "object" && isNonArrayRecord(record))
+        for (const [key, propSchema] of Object.entries(schema.properties ?? {}))
+            collectStrings(record.value[key], propSchema, out);
+}
+/**
+ * Every free-text string `config` holds where its type's `configSchema` declares one — a `text`
+ * widget's `body`, each social link's `url`. Ref fields (`x-ref-target`) are left out (they name
+ * other content by id) and so is anything the schema does not declare (`recent-entries`' `where`).
+ * The publish carry-along (`publish-content.ts`) reads media URLs out of these.
+ *
+ * @complexity O(n) over the config's declared nodes.
+ */
+export function collectWidgetConfigStrings(required, _optional = {}) {
+    const out = [];
+    collectStrings(required.config, required.schema, out);
+    return out;
+}
+//# sourceMappingURL=config-validation.js.map