@jini-ai/cms 0.3.11 → 0.4.0

package/dist/content-types/errors.js

@@ -30,41 +30,45 @@ import { ToolInputError } from "@jini-ai/core";
  * marker above.
  */
 export class ForbiddenError extends ToolInputError {
-    constructor(message) {
-        super(message);
+    constructor({ message }, _optional = {}) {
+        super({ message });
         this.name = "ForbiddenError";
     }
 }
-/** CIC U-002-B1 guard 1 — `key`/field-name grammar gate `^[a-z][a-z0-9_]{0,63}$` (U-001-B2). */
+/** guard 1 — `key`/field-name grammar gate `^[a-z][a-z0-9_]{0,63}$`. See docs/decisions/DR-001-safe-schema-and-index-transitions.md. */
 export class InvalidKeyGrammarError extends ToolInputError {
-    constructor(message) {
-        super(message);
+    constructor(requiredArgs, optionalArgs = {}) {
+        const { message } = requiredArgs;
+        super({ message: message });
         this.name = "InvalidKeyGrammarError";
     }
 }
-/** CIC U-002-B1 guard 2 — `key` is one of the permanently reserved legacy `posts` keys. */
+/** guard 2 — `key` is one of the permanently reserved legacy `posts` keys. See docs/decisions/DR-001-safe-schema-and-index-transitions.md. */
 export class ReservedContentTypeKeyError extends ToolInputError {
-    constructor(message) {
-        super(message);
+    constructor(requiredArgs, optionalArgs = {}) {
+        const { message } = requiredArgs;
+        super({ message: message });
         this.name = "ReservedContentTypeKeyError";
     }
 }
-/** CIC U-002-B1 guard 3 — a field name fails the identifier grammar gate. */
+/** guard 3 — a field name fails the identifier grammar gate. See docs/decisions/DR-001-safe-schema-and-index-transitions.md. */
 export class InvalidFieldNameGrammarError extends ToolInputError {
-    constructor(message) {
-        super(message);
+    constructor(requiredArgs, optionalArgs = {}) {
+        const { message } = requiredArgs;
+        super({ message: message });
         this.name = "InvalidFieldNameGrammarError";
     }
 }
-/** CIC U-001-B1 / U-002-B1 guard 4 — a field `kind` is not one of the closed field-kind enum. */
+/** guard 4 — a field `kind` is not one of the closed field-kind enum. See docs/decisions/DR-001-safe-schema-and-index-transitions.md. */
 export class InvalidFieldKindError extends ToolInputError {
-    constructor(message) {
-        super(message);
+    constructor(requiredArgs, optionalArgs = {}) {
+        const { message } = requiredArgs;
+        super({ message: message });
         this.name = "InvalidFieldKindError";
     }
 }
 /**
- * CIC U-002-B1 guard 4b — a field declares a STORAGE-ONLY `kind` (`json`) together with
+ * guard 4b — a field declares a STORAGE-ONLY `kind` (`json`) together with
  * `queryable: true`. The kind itself is legal and the field may be declared and written; what is
  * rejected is the pairing, because a storage-only kind has no `CAST` target and therefore no index
  * to provision.
@@ -77,10 +81,12 @@ export class InvalidFieldKindError extends ToolInputError {
  * `400 VALIDATION_ERROR` with no coordinated change, and the relationship is honest — this IS a
  * rejection of the field's kind, in the context the kind was used. `.name` still distinguishes it
  * for any caller that wants the finer signal.
+ * See docs/decisions/DR-001-safe-schema-and-index-transitions.md.
  */
 export class StorageOnlyFieldNotQueryableError extends InvalidFieldKindError {
-    constructor(message) {
-        super(message);
+    constructor(requiredArgs, optionalArgs = {}) {
+        const { message } = requiredArgs;
+        super({ message: message });
         this.name = "StorageOnlyFieldNotQueryableError";
     }
 }
@@ -89,7 +95,7 @@ export class StorageOnlyFieldNotQueryableError extends InvalidFieldKindError {
  * shape the `ContentTypeFieldDef[]` contract does not describe at all (a non-array, a non-object
  * element, a missing/mistyped `name`/`required`/`queryable`, or an unrecognized key).
  *
- * Distinct from the five CIC U-002-B1 guard errors on purpose: those judge a well-formed field
+ * Distinct from the five guard errors on purpose: those judge a well-formed field
  * definition against a domain rule, and they remain the sole owners of the grammar, kind-enum and
  * queryable-cap decisions. This one fires strictly earlier, at the untrusted-input boundary
  * (`field-defs.ts`), for payloads the guards could not have judged without either crashing or
@@ -97,33 +103,37 @@ export class StorageOnlyFieldNotQueryableError extends InvalidFieldKindError {
  *
  * `violation.received` names the offending value's TYPE, never the value — a field payload can
  * carry operator content, and this message reaches both an HTTP client and a model.
+ * See docs/decisions/DR-001-safe-schema-and-index-transitions.md.
  */
 export class InvalidFieldShapeError extends ToolInputError {
     code = "VALIDATION_ERROR";
     violation;
     constructor(violation) {
-        super(`${violation.path} must be ${violation.expected}, received ${violation.received}`);
+        super({ message: `${violation.path} must be ${violation.expected}, received ${violation.received}` });
         this.name = "InvalidFieldShapeError";
         this.violation = violation;
     }
 }
-/** CIC U-002-B1 guard 5 — more than the per-type cap of `queryable` fields were submitted. */
+/** guard 5 — more than the per-type cap of `queryable` fields were submitted. See docs/decisions/DR-001-safe-schema-and-index-transitions.md. */
 export class QueryableFieldCapExceededError extends ToolInputError {
-    constructor(message) {
-        super(message);
+    constructor(requiredArgs, optionalArgs = {}) {
+        const { message } = requiredArgs;
+        super({ message: message });
         this.name = "QueryableFieldCapExceededError";
     }
 }
-/** CIC U-004-B1 — `expectedVersion` did not match the current row's version (OCC conflict). */
+/** — `expectedVersion` did not match the current row's version (OCC conflict). See docs/decisions/DR-001-safe-schema-and-index-transitions.md. */
 export class VersionConflictError extends ToolInputError {
-    constructor(message) {
-        super(message);
+    constructor(requiredArgs, optionalArgs = {}) {
+        const { message } = requiredArgs;
+        super({ message: message });
         this.name = "VersionConflictError";
     }
 }
 export class ContentTypeNotFoundError extends ToolInputError {
-    constructor(message) {
-        super(message);
+    constructor(requiredArgs, optionalArgs = {}) {
+        const { message } = requiredArgs;
+        super({ message: message });
         this.name = "CONTENT_TYPE_NOT_FOUND";
     }
 }
@@ -131,17 +141,20 @@ export class ContentTypeNotFoundError extends ToolInputError {
  * Row 7 (web-high fix plan, 2026-09-24) — `registerContentType` loaded no existing row before
  * saving, so two concurrent first-widget creates (or a caller retrying an existing key) could
  * silently overwrite the current fields, and registering a tombstoned key could resurrect it
- * (INV-06 forbids any transition out of tombstone, including via a fresh register). Thrown when
+ * ( forbids any transition out of tombstone, including via a fresh register). Thrown when
  * `deps.repo.findByKey` already returns a row for the key, whether that row is active/deprecated
  * or tombstoned — `tombstoned` distinguishes the two so a caller/HTTP route can give the right
  * guidance (retry with update-fields, vs. the key is permanently gone).
+ * See docs/decisions/DR-001-safe-schema-and-index-transitions.md.
  */
 export class ContentTypeAlreadyExistsError extends ToolInputError {
     tombstoned;
-    constructor(key, tombstoned) {
-        super(tombstoned
-            ? `content type '${key}' was permanently deleted; its key can't be reused (INV-06)`
-            : `content type '${key}' already exists; use collections_content_type_update_fields to change its fields`);
+    constructor(requiredArgs, optionalArgs = {}) {
+        const { key, tombstoned } = requiredArgs;
+        super({ message: tombstoned
+                // See docs/decisions/DR-001-safe-schema-and-index-transitions.md for the invariant behind this refusal; keep external identifiers out of caller-facing messages.
+                ? `content type '${key}' was permanently deleted; its key can't be reused`
+                : `content type '${key}' already exists; use collections_content_type_update_fields to change its fields` });
         this.name = "ContentTypeAlreadyExistsError";
         this.tombstoned = tombstoned;
     }
@@ -150,23 +163,27 @@ export class ContentTypeAlreadyExistsError extends ToolInputError {
 export class ValidationError extends ToolInputError {
     code = "VALIDATION_ERROR";
     details;
-    constructor(message, reason) {
-        super(message);
+    constructor(requiredArgs, optionalArgs = {}) {
+        const { message, reason } = requiredArgs;
+        super({ message: message });
         this.name = "VALIDATION_ERROR";
         this.details = { reason };
     }
 }
-/** REQ-09..12 lifecycle state-machine guard rejection (INV-06 terminal-tombstone, EC-09 deprecate-first). */
+/**..12 lifecycle state-machine guard rejection ( terminal-tombstone, deprecate-first). See docs/decisions/DR-001-safe-schema-and-index-transitions.md. */
 export class ContentTypeLifecycleError extends ToolInputError {
-    constructor(message) {
-        super(message);
+    constructor(requiredArgs, optionalArgs = {}) {
+        const { message } = requiredArgs;
+        super({ message: message });
         this.name = "ContentTypeLifecycleError";
     }
 }
-/** REQ-20 `planCleanup` eligibility-gate rejection; `reason` is one of a closed, ordered set. */
+/** `planCleanup` eligibility-gate rejection; `reason` is one of a closed, ordered set. See docs/decisions/DR-001-safe-schema-and-index-transitions.md. */
 export class CleanupNotEligibleError extends Error {
     reason;
-    constructor(reason, message) {
+    constructor(requiredArgs, optionalArgs = {}) {
+        const { reason } = requiredArgs;
+        const { message } = optionalArgs;
         super(message ?? `cleanup is not eligible: ${reason}`);
         this.name = "CleanupNotEligibleError";
         this.reason = reason;

package/dist/content-types/field-defs.d.ts

@@ -1,10 +1,11 @@
-import { type ContentTypeFieldDef, type Result } from "./types.js";
+import { type Result } from "@jini-ai/core/primitives";
+import { type ContentTypeFieldDef } from "./types.js";
 /**
  * Validates an untrusted value against the `ContentTypeFieldDef[]` contract, returning either the
  * verified array or the first structural violation found.
  *
  * Stops at the first violation rather than collecting all of them, matching the
- * stop-at-first-failure convention CIC U-002-B1 already establishes for the domain guard chain
+ * stop-at-first-failure convention already establishes for the domain guard chain
  * this function feeds.
  *
  * @param value - The untrusted `fields` payload: a parsed JSON body's property, or an agent tool's
@@ -17,9 +18,12 @@ import { type ContentTypeFieldDef, type Result } from "./types.js";
  * @complexity O(f·k) time with f = element count (bounded by {@link MAX_FIELD_DEFS}) and k = 4
  * fixed keys, so effectively O(f); O(f) space for the returned array.
  * @example
- * const parsed = parseContentTypeFieldDefs([{ name: "servings", kind: "integer", required: false, queryable: true }]);
+ * const parsed = parseContentTypeFieldDefs({ value: [{ name: "servings", kind: "integer", required: false, queryable: true }] });
  * if (!parsed.ok) return { ok: false, error: parsed.error };
  * @overallScore 100
+ * See docs/decisions/DR-001-safe-schema-and-index-transitions.md.
  */
-export declare function parseContentTypeFieldDefs(value: unknown): Result<ContentTypeFieldDef[], Error>;
+export declare function parseContentTypeFieldDefs(requiredArgs: {
+    value: unknown;
+}, optionalArgs?: Record<string, never>): Result<ContentTypeFieldDef[], Error>;
 //# sourceMappingURL=field-defs.d.ts.map

package/dist/content-types/field-defs.js

@@ -10,22 +10,22 @@
  * validation, which left three real gaps:
  *
  * 1. `required` and `queryable` were never type-checked anywhere in the codebase, so
- *    `queryable: "yes"` counted as queryable (`write-service.ts`'s `countQueryableFields` filters
- *    on truthiness) and `required: "maybe"` was persisted verbatim into the stored record and its
- *    revision `stateJson`. That is a data-integrity gap, not merely a sloppy contract.
+ * `queryable: "yes"` counted as queryable (`write-service.ts`'s `countQueryableFields` filters
+ * on truthiness) and `required: "maybe"` was persisted verbatim into the stored record and its
+ * revision `stateJson`. That is a data-integrity gap, not merely a sloppy contract.
  * 2. A non-object element (`fields: [null]`) made the field-name grammar guard throw a bare
- *    `TypeError` on `field.name` instead of returning a typed rejection — a 500 on the HTTP path
- *    and an opaque `'failed'` tool execution on the agent path.
+ * `TypeError` on `field.name` instead of returning a typed rejection — a 500 on the HTTP path
+ * and an opaque `'failed'` tool execution on the agent path.
  * 3. A misspelled key (`queryible: true`) was silently dropped rather than reported, so a caller
- *    got a field that was quietly non-queryable with no indication why.
+ * got a field that was quietly non-queryable with no indication why.
  *
  * Division of responsibility (deliberate, and the reason this module is narrow):
  * this module owns STRUCTURE only — array-ness, element object-ness, the four keys and their
  * types. It does NOT own the domain rules. The field-name grammar gate, the reserved-key check and
- * the queryable-field cap stay solely in `write-service.ts`'s CIC U-002-B1 guard chain, whose
+ * the queryable-field cap stay solely in `write-service.ts`'s guard chain, whose
  * fixed order (`key grammar -> reserved-key -> field-name grammar -> field-kind -> queryable-cap`)
  * and stop-at-first-failure behavior are pinned by
- * `__tests__/unit/write-service.register.unit.test.ts` (AC-38). Duplicating any of those here
+ * `__tests__/unit/write-service.register.unit.test.ts`. Duplicating any of those here
  * would either reorder that chain for boundary callers or create a second source of truth for a
  * rule that must have exactly one definition.
  *
@@ -38,8 +38,10 @@
  * Architectural role:
  * `features/content-types` domain logic. Pure — no I/O, no clock, no repo. Depends only on this
  * package's own `types.ts` and `errors.ts`.
+ * See docs/decisions/DR-001-safe-schema-and-index-transitions.md.
  */
 import { InvalidFieldKindError, InvalidFieldShapeError } from "./errors.js";
+import {} from "@jini-ai/core/primitives";
 import { isContentTypeFieldKind } from "./types.js";
 /**
  * The complete, closed key set of a `ContentTypeFieldDef`. Any other key is rejected rather than
@@ -78,7 +80,7 @@ function isPlainObject(value) {
  * verified array or the first structural violation found.
  *
  * Stops at the first violation rather than collecting all of them, matching the
- * stop-at-first-failure convention CIC U-002-B1 already establishes for the domain guard chain
+ * stop-at-first-failure convention already establishes for the domain guard chain
  * this function feeds.
  *
  * @param value - The untrusted `fields` payload: a parsed JSON body's property, or an agent tool's
@@ -91,11 +93,13 @@ function isPlainObject(value) {
  * @complexity O(f·k) time with f = element count (bounded by {@link MAX_FIELD_DEFS}) and k = 4
  * fixed keys, so effectively O(f); O(f) space for the returned array.
  * @example
- * const parsed = parseContentTypeFieldDefs([{ name: "servings", kind: "integer", required: false, queryable: true }]);
+ * const parsed = parseContentTypeFieldDefs({ value: [{ name: "servings", kind: "integer", required: false, queryable: true }] });
  * if (!parsed.ok) return { ok: false, error: parsed.error };
  * @overallScore 100
+ * See docs/decisions/DR-001-safe-schema-and-index-transitions.md.
  */
-export function parseContentTypeFieldDefs(value) {
+export function parseContentTypeFieldDefs(requiredArgs, optionalArgs = {}) {
+    const { value } = requiredArgs;
     if (!Array.isArray(value)) {
         return { ok: false, error: new InvalidFieldShapeError({ path: "fields", expected: "an array", received: describeType(value) }) };
     }
@@ -147,9 +151,10 @@ function parseOneFieldDef(element, at) {
     if (typeof element.kind !== "string") {
         return { ok: false, error: new InvalidFieldShapeError({ path: `${at}.kind`, expected: "a string", received: describeType(element.kind) }) };
     }
-    if (!isContentTypeFieldKind(element.kind)) {
-        return { ok: false, error: new InvalidFieldKindError(`field '${element.name}' has kind '${element.kind}', not one of the closed field-kind enum`) };
+    const kind = { value: element.kind };
+    if (!isContentTypeFieldKind(kind)) {
+        return { ok: false, error: new InvalidFieldKindError({ message: `field '${element.name}' has kind '${element.kind}', not one of the closed field-kind enum` }) };
     }
-    return { ok: true, value: { name: element.name, kind: element.kind, required: element.required, queryable: element.queryable } };
+    return { ok: true, value: { name: element.name, kind: kind.value, required: element.required, queryable: element.queryable } };
 }
 //# sourceMappingURL=field-defs.js.map

package/dist/content-types/index-provisioning.d.ts

@@ -1,47 +1,47 @@
 import { type ContentTypeFieldKind, type IndexableFieldKind } from "./types.js";
 /**
- * @file CIC U-001 — the `kind`->`CAST` fixed lookup table, the identifier grammar
+ * @file the `kind`->`CAST` fixed lookup table, the identifier grammar
  * gate, the workspace-scoped queryable-index naming scheme, and the before/after index-transition
  * resolver (grammar-and-workspace-scoping folds).
  *
  * Purpose:
  * THIS IS THE HIGHEST-SECURITY-SEVERITY MODULE IN THE 5-PACKAGE PIPELINE — every value that ends
- * up inside a `CREATE INDEX ... CAST(json_extract(fields,'$.ext.{ns}.{field}') AS {type})`
+ * up inside a `CREATE INDEX... CAST(json_extract(fields,'$.ext.{ns}.{field}') AS {type})`
  * statement is produced here, and only here:
- *   - `mapFieldKindToCast` (U-001-B1). STATE THE INVARIANT PRECISELY, because an earlier version
- *     of this comment did not and the imprecision was itself a hazard: it said "a fixed, hardcoded
- *     5-entry table", which reads as though the ENTRY COUNT were the defense. It is not. Neither
- *     the number of keys nor the number of distinct values is the security boundary.
+ * - `mapFieldKindToCast`. STATE THE INVARIANT PRECISELY, because an earlier version
+ * of this comment did not and the imprecision was itself a hazard: it said "a fixed, hardcoded
+ * 5-entry table", which reads as though the ENTRY COUNT were the defense. It is not. Neither
+ * the number of keys nor the number of distinct values is the security boundary.
  *
- *     THE DEFENSE IS: this function returns a VALUE FROM THE TABLE and never returns, echoes, or
- *     interpolates its own ARGUMENT. The function has exactly one `return`, and it is a table
- *     lookup. Therefore the set of strings that can reach a `CAST(... AS {type})` position is
- *     exactly the set of string literals written into `KIND_TO_CAST_LITERAL` in this source file —
- *     compile-time constants, every one — no matter what an operator, an agent, or an attacker
- *     supplies as `kind`. A 50-entry table of literals would be exactly as safe as a 5-entry one.
+ * THE DEFENSE IS: this function returns a VALUE FROM THE TABLE and never returns, echoes, or
+ * interpolates its own ARGUMENT. The function has exactly one `return`, and it is a table
+ * lookup. Therefore the set of strings that can reach a `CAST(... AS {type})` position is
+ * exactly the set of string literals written into `KIND_TO_CAST_LITERAL` in this source file —
+ * compile-time constants, every one — no matter what an operator, an agent, or an attacker
+ * supplies as `kind`. A 50-entry table of literals would be exactly as safe as a 5-entry one.
  *
- *     What follows from that, and what a maintainer actually needs to know:
- *       * Adding a KEY whose value is an existing literal cannot widen the DDL alphabet. It is not
- *         a security event and does not need to be feared as one. (`relation: "TEXT"` is exactly
- *         this: `"TEXT"` was already present twice.)
- *       * Adding a new VALUE does widen it, and must be reviewed as a DDL change.
- *       * Returning, concatenating, or template-interpolating `kind` itself — or reading the table
- *         with a fallback such as `?? kind` — BREAKS the invariant outright. That is the edit to
- *         refuse, and it is the one the old "5-entry" phrasing gave no way to recognise.
- *     The reachable-value set is pinned executably by `HISTORICAL_DDL_ALPHABET` in
- *     `__tests__/field-kind-widening.test.ts`, so this claim is a failing test and not only prose.
+ * What follows from that, and what a maintainer actually needs to know:
+ * * Adding a KEY whose value is an existing literal cannot widen the DDL alphabet. It is not
+ * a security event and does not need to be feared as one. (`relation: "TEXT"` is exactly
+ * this: `"TEXT"` was already present twice.)
+ * * Adding a new VALUE does widen it, and must be reviewed as a DDL change.
+ * * Returning, concatenating, or template-interpolating `kind` itself — or reading the table
+ * with a fallback such as `?? kind` — BREAKS the invariant outright. That is the edit to
+ * refuse, and it is the one the old "5-entry" phrasing gave no way to recognise.
+ * The reachable-value set is pinned executably by `HISTORICAL_DDL_ALPHABET` in
+ * `__tests__/field-kind-widening.test.ts`, so this claim is a failing test and not only prose.
  *
- *     Degraded failure mode, stated so the blast radius is known: if every runtime guard below
- *     were deleted, a storage-only kind would reach the table and `KIND_TO_CAST_LITERAL["json"]`
- *     would evaluate to `undefined` — a SQL syntax error and a loud broken feature, never an
- *     operator-controlled string. Total guard removal degrades this module to unavailable, not to
- *     injectable. That is the property worth preserving through any future change.
- *   - `validateIdentifierGrammar`/`buildQueryableFieldIndexName` gate every `key`/field name
- *     through `^[a-z][a-z0-9_]{0,63}$` before it can reach an index-name segment or JSON-path
- *     literal (U-001-B2), and join grammar-gated segments with `/` — a delimiter outside the
- *     grammar's own alphabet `[a-z0-9_]`, closing the namespace-injectivity collision class
- *     (U-001-B3) — and fold in a workspace-derived segment so two workspaces defining the same
- *     `(key, field)` pair never collide on index identity.
+ * Degraded failure mode, stated so the blast radius is known: if every runtime guard below
+ * were deleted, a storage-only kind would reach the table and `KIND_TO_CAST_LITERAL["json"]`
+ * would evaluate to `undefined` — a SQL syntax error and a loud broken feature, never an
+ * operator-controlled string. Total guard removal degrades this module to unavailable, not to
+ * injectable. That is the property worth preserving through any future change.
+ * - `validateIdentifierGrammar`/`buildQueryableFieldIndexName` gate every `key`/field name
+ * through `^[a-z][a-z0-9_]{0,63}$` before it can reach an index-name segment or JSON-path
+ * literal, and join grammar-gated segments with `/` — a delimiter outside the
+ * grammar's own alphabet `[a-z0-9_]`, closing the namespace-injectivity collision class
+ * — and fold in a workspace-derived segment so two workspaces defining the same
+ * `(key, field)` pair never collide on index identity.
  *
  * How it relates to the project:
  * `resolveFieldIndexTransition` deliberately still ACCEPTS a storage-only kind on its `none` and
@@ -51,35 +51,40 @@ import { type ContentTypeFieldKind, type IndexableFieldKind } from "./types.js";
  *
  * `write-service.ts`'s `registerContentType`/`updateContentTypeFields` call
  * `resolveFieldIndexTransition` once per field (never two independent kind/queryable branches —
- * CIC U-003-B1) and hand the result to the injected `indexProvisioner` port, which is the only
+ * ) and hand the result to the injected `indexProvisioner` port, which is the only
  * thing that ever issues the real `CREATE INDEX`/`DROP INDEX` DDL (this module only decides what
  * to build, never executes DDL itself).
  *
  * Architectural role:
- * `features/content-types` domain logic. No dependencies beyond `node:crypto` (workspace-segment
- * hashing) and this package's own `errors.ts`/`types.ts`.
+ * `features/content-types` domain logic. Workspace-segment hashing uses Web Crypto so this
+ * universal entry needs only standard runtime APIs and this package's own `errors.ts`/`types.ts`.
+ * See docs/decisions/DR-001-safe-schema-and-index-transitions.md.
  */
 /**
- * U-001-B2 — the closed identifier grammar every `content_types.key` and field name must satisfy,
+ * — the closed identifier grammar every `content_types.key` and field name must satisfy,
  * as a pattern string so the agent-facing JSON Schemas in `agent-tools.ts` can publish the very
  * same grammar instead of restating it. A cross-cutting single-source-of-truth governance rule makes this grammar load-bearing for DDL
  * safety, so it must have exactly one definition; {@link IDENTIFIER_GRAMMAR} is compiled from this
  * string rather than written twice.
+ * See docs/decisions/DR-001-safe-schema-and-index-transitions.md.
  */
 export declare const IDENTIFIER_GRAMMAR_PATTERN = "^[a-z][a-z0-9_]{0,63}$";
 /**
- * Structural grammar gate for a `content_types.key` or field name (U-001-B2).
+ * Structural grammar gate for a `content_types.key` or field name.
  *
  * @complexity O(n) in the string's length (regex match), bounded at 64 chars.
  * @overallScore 100
+ * See docs/decisions/DR-001-safe-schema-and-index-transitions.md.
  */
-export declare function validateIdentifierGrammar(value: string): boolean;
+export declare function validateIdentifierGrammar(requiredArgs: {
+    value: string;
+}, optionalArgs?: Record<string, never>): boolean;
 /**
  * Maps an INDEXABLE field `kind` to its fixed `CAST(... AS {type})` type token. Throws
  * {@link InvalidFieldKindError} for anything that is not exactly one of `INDEXABLE_FIELD_KINDS` —
  * including a storage-only kind such as `json`, which is a legal kind to declare but has no CAST
  * target. This is a lookup, never a template, so an adversarial payload can never reach the
- * returned string (U-001-B1).
+ * returned string.
  *
  * The PARAMETER type is deliberately the wider `ContentTypeFieldKind`. Narrowing it would be a
  * breaking change for `@jini-ai/cms`'s public consumers (`content-types/index.ts` documents this
@@ -93,23 +98,31 @@ export declare function validateIdentifierGrammar(value: string): boolean;
  *
  * @complexity O(1) — a fixed-size object lookup behind a fixed-size membership test.
  * @overallScore 100
+ * See docs/decisions/DR-001-safe-schema-and-index-transitions.md.
  */
-export declare function mapFieldKindToCast(kind: ContentTypeFieldKind): string;
+export declare function mapFieldKindToCast(requiredArgs: {
+    kind: ContentTypeFieldKind;
+}, optionalArgs?: Record<string, never>): string;
 /**
  * Builds the workspace-scoped queryable-field index identity for `(workspaceId, contentTypeKey,
  * fieldName)`. Both `contentTypeKey` and `fieldName` are grammar-gated first — a failure throws
- * before any index name is produced (U-001-B2). Segments are joined with `/`, a delimiter outside
+ * before any index name is produced. Segments are joined with `/`, a delimiter outside
  * the grammar's own alphabet `[a-z0-9_]`, so distinct `(key, name)` pairs can never collide by
- * boundary-shifting (U-001-B3, e.g. `("a_b","c")` vs `("a","b_c")`).
+ * boundary-shifting (e.g. `("a_b","c")` vs `("a","b_c")`).
+ *
+ * Returns a promise for the unchanged index identity. Grammar failures still throw
+ * synchronously before hashing; Web Crypto failures reject the promise. Callers must await
+ * the name before using it in DDL.
  *
- * @complexity O(1) plus two grammar checks and one SHA-256 hash.
+ * @complexity O(n) time and space in the UTF-8 workspace ID length, plus two grammar checks.
  * @overallScore 100
+ * See docs/decisions/DR-001-safe-schema-and-index-transitions.md.
  */
 export declare function buildQueryableFieldIndexName(params: {
     workspaceId: string;
     contentTypeKey: string;
     fieldName: string;
-}): string;
+}): Promise<string>;
 /** A field's `(kind, queryable)` pair at one side of an update call, or `undefined` if absent (new/removed). */
 export type FieldIndexState = {
     kind: ContentTypeFieldKind;
@@ -125,13 +138,14 @@ export interface FieldIndexTransition {
     newKind?: IndexableFieldKind;
 }
 /**
- * CIC U-003-B1 — resolves a single field's index transition from ONE before/after comparison of
+ * — resolves a single field's index transition from ONE before/after comparison of
  * its `(kind, queryable)` pair, never from two independent branches that each assume the other
  * property is unchanged (the bug class this closes: a field whose `kind` AND `queryable` both
- * change in the same call must still resolve correctly — REQ-30(b)).
+ * change in the same call must still resolve correctly — (b)).
  *
  * @complexity O(1) — four comparisons, one of four fixed outcomes.
  * @overallScore 100
+ * See docs/decisions/DR-001-safe-schema-and-index-transitions.md.
  */
 export declare function resolveFieldIndexTransition(params: {
     before: FieldIndexState;