@elytracms/studio 0.0.91 → 0.0.93

package/dist/lib/ai/shape.d.ts

@@ -1,6 +1,6 @@
 import type { CollectionDef, JsonSchema } from '@elytracms/core/cms-core';
-import type { AssetCandidates, RelationCandidates } from './types.js';
-/** A relation field's resolved candidate set — how the engine maps ids → reference envelopes. */
+import type { WriterLeash } from './types.js';
+/** A top-level relation field's resolved candidate set (the enum the model chose from). */
 export interface TargetRelationField {
     fieldName: string;
     /** The relation's target collection id. */
@@ -9,7 +9,7 @@ export interface TargetRelationField {
     /** The allowed candidate ids (the enum the model chose from). */
     candidateIds: string[];
 }
-/** An asset field's resolved candidate set — how the engine maps ids → asset envelopes (EC-381). */
+/** A top-level asset field's resolved candidate set (EC-381). */
 export interface TargetAssetField {
     fieldName: string;
     multiple: boolean;
@@ -22,26 +22,26 @@ export interface TargetShape {
     schema: JsonSchema;
     /** Field names removed by `ai.exclude` (untouchable). */
     excluded: string[];
+    /** Field names omitted because a writer never writes them — a composition (4c). */
+    compositions: string[];
     /** Field names whose values route under `localized[locale]`. */
     localizedFields: string[];
-    /** Relation fields with their candidate enums. */
+    /** Top-level relation fields with their candidate enums. */
     relationFields: TargetRelationField[];
-    /** Asset fields with their candidate enums (EC-381). */
+    /** Top-level asset fields with their candidate enums (EC-381). */
     assetFields: TargetAssetField[];
 }
 export interface BuildTargetShapeInput {
     collection: CollectionDef;
-    /** Relation candidate ids by field — a relation field with none is omitted from the shape. */
-    candidates?: RelationCandidates;
-    /** Asset candidate ids by field — an asset field with none is omitted from the shape (EC-381). */
-    assetCandidates?: AssetCandidates;
+    /** What the model searched — the id leash at every position (absent → nothing searched). */
+    leash?: WriterLeash;
     /** UI locale for resolving field labels into descriptions. */
     locale?: string;
 }
 /**
- * Build the leash-aware target shape from a collection + candidates. Deterministic;
- * never throws. Reuses `collectionJsonSchema` as the base (its `required` list), then
- * gives every property its writer form (EC-556) or its id-enum leash, and strips
- * excluded fields.
+ * Build the leash-aware target shape from a collection + what the model searched.
+ * Deterministic; never throws. Reuses `collectionJsonSchema` as the base (its
+ * `required` list), then gives every property its writer form (EC-556) — id enums at
+ * every depth (EC-593) — and strips excluded fields and compositions.
  */
 export declare function buildTargetShape(input: BuildTargetShapeInput): TargetShape;

package/dist/lib/ai/shape.js

@@ -2,24 +2,28 @@
  * Target-shape derivation for `applyContentWithShape` (EC-331).
  *
  * Reuses the existing collection→JSON-Schema derivation (`collectionJsonSchema`,
- * cms-core) rather than writing a new one, then applies the three leashes the AI
- * engine adds on top:
+ * cms-core) rather than writing a new one, then applies the leashes the AI engine
+ * adds on top:
  *
  *  - `ai.exclude` fields are removed entirely (the model never sees them → cannot
  *    write them).
- *  - relation fields become an ENUM over the provided candidate ids (or are omitted
- *    when no candidates exist) — so a hallucinated relation id is not representable
- *    as valid structured output.
- *  - asset/image fields become an ENUM over the searched library asset ids (or are
- *    omitted when none were searched) — EC-381, the SAME leash as relations: a
- *    proposed asset id must be a real, `listAssets`-returned library asset, and a
- *    create shape with no searched assets simply has no asset property (empty beats
- *    wrong; the assistant never generates or uploads).
+ *  - relation ids become an ENUM over the searched candidates of the relation's
+ *    target (or the position is omitted when none were searched) — so a hallucinated
+ *    relation id is not representable as valid structured output.
+ *  - asset ids become an ENUM over the searched library assets that fit the
+ *    position's `accept` (or the position is omitted when none fit) — EC-381, the SAME
+ *    leash as relations: a proposed asset id must be a real, `listAssets`-returned
+ *    library asset (empty beats wrong; the assistant never generates or uploads).
+ *    EC-593: both leashes hold at EVERY depth — a relation in an object, an asset in a
+ *    repeater item — not only on a top-level field (`writerFieldSchema(field, leash)`).
  *  - rich-text fields are MARKDOWN STRINGS (EC-379): the description names the
- *    allowed subset, and the engine converts md → the `{ version, doc }` storage
- *    envelope at proposal-build time. The field's `allow` config leashes component
- *    EMBEDS only — markdown cannot express an embed, so the leash is satisfied by
- *    construction (and still enforced downstream by `validateRichTextEmbeds`).
+ *    allowed subset, and the engine converts md → the `{ version: 2, content }` storage
+ *    value at proposal-build time (`writer-form.ts`). The field's `allow` config leashes
+ *    component EMBEDS only — markdown cannot express an embed, so the leash is
+ *    satisfied by construction (and still enforced downstream by `validateRichTextEmbeds`).
+ *  - a composition (`blocks`) has NO writer form (ratified 4c, EC-593): it is omitted,
+ *    and the schema's own description says so — the omission is visible, never a field
+ *    the model simply never hears of.
  *
  * Localized fields stay flat in the shape (the model authors one locale at a time);
  * the engine routes their values under `localized[locale]`.
@@ -46,12 +50,12 @@
  * EC-556 — the projection is VALIDATOR-facing (the value at rest: asset/relation
  * envelopes, the v2 rich-text object). Every property here is its WRITER form
  * (`writerFieldSchema`), derived from that projection at every depth — a bare asset
- * id, a `{ collection, id }` reference, a markdown string — so an asset, relation or
- * rich-text SUBFIELD of an `object` is told the same form as a top-level one. The
- * top-level relation/asset id enums (EC-381) override the writer form there.
+ * id, a relation id, a markdown string — so an asset, relation or rich-text SUBFIELD of
+ * an `object` is told the same form as a top-level one.
  */
 import { collectionJsonSchema, resolveLabel } from '@elytracms/core/cms-core';
 import { constraintSentence, toModelFacingSchema, writerFieldSchema } from './constraints.js';
+import { NO_SEARCHED_IDS } from './leash.js';
 /**
  * A field's model-facing description: resolved label + optional `ai.hint` + the
  * constraint clause (EC-473). The constraints are stated in PROSE because that is
@@ -66,17 +70,19 @@ function describe(field, locale) {
     return parts.length > 0 ? parts.join(' — ') : undefined;
 }
 /**
- * Build the leash-aware target shape from a collection + candidates. Deterministic;
- * never throws. Reuses `collectionJsonSchema` as the base (its `required` list), then
- * gives every property its writer form (EC-556) or its id-enum leash, and strips
- * excluded fields.
+ * Build the leash-aware target shape from a collection + what the model searched.
+ * Deterministic; never throws. Reuses `collectionJsonSchema` as the base (its
+ * `required` list), then gives every property its writer form (EC-556) — id enums at
+ * every depth (EC-593) — and strips excluded fields and compositions.
  */
 export function buildTargetShape(input) {
+    const leash = input.leash ?? NO_SEARCHED_IDS;
     const base = collectionJsonSchema(input.collection);
     const properties = {
         ...(base.properties ?? {}),
     };
     const excluded = [];
+    const compositions = [];
     const localizedFields = [];
     const relationFields = [];
     const assetFields = [];
@@ -88,82 +94,46 @@ export function buildTargetShape(input) {
             delete properties[field.name];
             continue;
         }
+        // EC-556: the writer form at every depth (rich text → markdown, EC-379 / D2;
+        // nested asset / relation → the bare forms the write-time lens wraps); EC-593:
+        // every id an enum over what was searched for that position.
+        const written = writerFieldSchema(field, leash);
+        if (written === undefined) {
+            // No writer form: a composition (4c), or a relation / asset with nothing
+            // searched for it — the model cannot emit a value, so a hallucinated id is
+            // structurally impossible (empty beats wrong).
+            if (field.type === 'blocks')
+                compositions.push(field.name);
+            delete properties[field.name];
+            continue;
+        }
         if (field.type === 'relation') {
-            const candidates = input.candidates?.[field.name] ?? [];
-            if (candidates.length === 0) {
-                // No candidate ids ⇒ omit the field: the model cannot emit a relation value
-                // at all, so a hallucinated id is structurally impossible.
-                delete properties[field.name];
-                continue;
-            }
-            const ids = candidates.map((c) => c.id);
-            const label = candidates
-                .map((c) => (c.label ? `${c.id} (${c.label})` : c.id))
-                .join(', ');
-            const idSchema = {
-                type: 'string',
-                enum: ids,
-                description: `Choose one of: ${label}`,
-            };
-            properties[field.name] = field.multiple ? { type: 'array', items: idSchema } : idSchema;
-            relationFields.push({
-                fieldName: field.name,
-                target: field.target,
-                multiple: field.multiple,
-                candidateIds: ids,
-            });
+            const candidateIds = leash.relationCandidates(field.target).map((c) => c.id);
+            relationFields.push({ fieldName: field.name, target: field.target, multiple: field.multiple, candidateIds });
         }
         else if (field.type === 'asset') {
-            // EC-381 — same leash as relations: an asset field is an enum over the ids
-            // the model actually searched in the media library (`listAssets`). No
-            // searched assets ⇒ omit the field, so the proposal simply leaves it empty
-            // (an invented / to-be-uploaded id is structurally unrepresentable).
-            const candidates = input.assetCandidates?.[field.name] ?? [];
-            if (candidates.length === 0) {
-                delete properties[field.name];
-                continue;
-            }
-            const ids = candidates.map((c) => c.id);
-            const label = candidates
-                .map((c) => (c.label ? `${c.id} (${c.label})` : c.id))
-                .join(', ');
-            const idSchema = {
-                type: 'string',
-                enum: ids,
-                description: `Choose an EXISTING library asset id, one of: ${label}. Leave empty if none fits.`,
-            };
-            properties[field.name] = field.multiple ? { type: 'array', items: idSchema } : idSchema;
-            assetFields.push({ fieldName: field.name, multiple: field.multiple, candidateIds: ids });
-        }
-        else {
-            // EC-556: the writer form at every depth (rich text → markdown, EC-379 / D2;
-            // nested asset / relation → the bare forms the write-time lens wraps).
-            properties[field.name] = writerFieldSchema(field);
+            const candidateIds = leash.assetCandidates(field).map((c) => c.id);
+            assetFields.push({ fieldName: field.name, multiple: field.multiple, candidateIds });
         }
-        const prop = properties[field.name];
-        if (prop) {
-            // EC-473: a `pattern` next to a `format` is 200+ characters that teach the
-            // model nothing — the format (and the prose constraints below) say it better.
-            // EC-505: and a `date`'s `['string','number']` union becomes the ISO string
-            // the model is actually asked to author.
-            const stripped = toModelFacingSchema(prop);
-            const desc = describe(field, input.locale);
-            // Preserve an existing description (e.g. relation enum / rich-text note), but
-            // append the constraint clause to it — the enum leash and the value rules are
-            // different facts and the model needs both.
-            const next = stripped === prop ? prop : { ...stripped };
-            if (desc !== undefined) {
-                const existing = typeof next.description === 'string' ? next.description : undefined;
-                const constraints = constraintSentence(field);
-                next.description =
-                    existing === undefined
-                        ? desc
-                        : constraints !== undefined
-                            ? `${existing} — ${constraints}`
-                            : existing;
-            }
-            properties[field.name] = next;
+        // EC-473: a `pattern` next to a `format` is 200+ characters that teach the
+        // model nothing — the format (and the prose constraints below) say it better.
+        const stripped = toModelFacingSchema(written);
+        const desc = describe(field, input.locale);
+        // Preserve an existing description (e.g. relation enum / rich-text note), but
+        // append the constraint clause to it — the enum leash and the value rules are
+        // different facts and the model needs both.
+        const next = stripped === written ? { ...written } : { ...stripped };
+        if (desc !== undefined) {
+            const existing = typeof next.description === 'string' ? next.description : undefined;
+            const constraints = constraintSentence(field);
+            next.description =
+                existing === undefined
+                    ? desc
+                    : constraints !== undefined
+                        ? `${existing} — ${constraints}`
+                        : existing;
         }
+        properties[field.name] = next;
     }
     const requiredIn = Array.isArray(base.required) ? base.required : [];
     const required = requiredIn.filter((n) => !excluded.includes(n) && properties[n] !== undefined);
@@ -172,7 +142,13 @@ export function buildTargetShape(input) {
         properties,
         additionalProperties: false,
         ...(required.length > 0 ? { required } : {}),
+        // 4c (EC-593): the omission is said, not silent.
+        ...(compositions.length > 0
+            ? {
+                description: `Not part of this object: ${compositions.join(', ')} — page-builder composition${compositions.length > 1 ? 's' : ''} whose components are added, moved and removed on the canvas, never by the assistant.`,
+            }
+            : {}),
     };
-    return { schema, excluded, localizedFields, relationFields, assetFields };
+    return { schema, excluded, compositions, localizedFields, relationFields, assetFields };
 }
 //# sourceMappingURL=shape.js.map

package/dist/lib/ai/shape.js.map

@@ -1 +1 @@
-{"version":3,"file":"shape.js","sourceRoot":"","sources":["../../../src/lib/ai/shape.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAE7E,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AA6C1F;;;;;GAKG;AACH,SAAS,QAAQ,CAAC,KAAe,EAAE,MAAe;IAChD,MAAM,KAAK,GAAG,YAAY,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,KAAK,CAAC,IAAI,CAAA;IACnE,MAAM,IAAI,GAAG,KAAK,CAAC,EAAE,EAAE,IAAI,CAAA;IAC3B,MAAM,WAAW,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAA;IAC7C,MAAM,KAAK,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC,MAAM,CAC7C,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAC1D,CAAA;IACD,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;AACzD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAA4B;IAC3D,MAAM,IAAI,GAAG,oBAAoB,CAAC,KAAK,CAAC,UAAU,CAAC,CAAA;IACnD,MAAM,UAAU,GAA+B;QAC7C,GAAG,CAAE,IAAI,CAAC,UAAyC,IAAI,EAAE,CAAC;KAC3D,CAAA;IACD,MAAM,QAAQ,GAAa,EAAE,CAAA;IAC7B,MAAM,eAAe,GAAa,EAAE,CAAA;IACpC,MAAM,cAAc,GAA0B,EAAE,CAAA;IAChD,MAAM,WAAW,GAAuB,EAAE,CAAA;IAE1C,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,UAAU,CAAC,MAAM,EAAE,CAAC;QAC5C,IAAI,KAAK,CAAC,SAAS;YAAE,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;QAErD,IAAI,KAAK,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC;YACtB,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;YACzB,OAAO,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;YAC7B,SAAQ;QACV,CAAC;QAED,IAAI,KAAK,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YAC9B,MAAM,UAAU,GAAG,KAAK,CAAC,UAAU,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,CAAA;YACvD,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC5B,4EAA4E;gBAC5E,2DAA2D;gBAC3D,OAAO,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;gBAC7B,SAAQ;YACV,CAAC;YACD,MAAM,GAAG,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;YACvC,MAAM,KAAK,GAAG,UAAU;iBACrB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;iBACrD,IAAI,CAAC,IAAI,CAAC,CAAA;YACb,MAAM,QAAQ,GAAe;gBAC3B,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,GAAG;gBACT,WAAW,EAAE,kBAAkB,KAAK,EAAE;aACvC,CAAA;YACD,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAA;YACvF,cAAc,CAAC,IAAI,CAAC;gBAClB,SAAS,EAAE,KAAK,CAAC,IAAI;gBACrB,MAAM,EAAE,KAAK,CAAC,MAAM;gBACpB,QAAQ,EAAE,KAAK,CAAC,QAAQ;gBACxB,YAAY,EAAE,GAAG;aAClB,CAAC,CAAA;QACJ,CAAC;aAAM,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;YAClC,2EAA2E;YAC3E,sEAAsE;YACtE,2EAA2E;YAC3E,qEAAqE;YACrE,MAAM,UAAU,GAAG,KAAK,CAAC,eAAe,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,CAAA;YAC5D,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC5B,OAAO,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;gBAC7B,SAAQ;YACV,CAAC;YACD,MAAM,GAAG,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;YACvC,MAAM,KAAK,GAAG,UAAU;iBACrB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;iBACrD,IAAI,CAAC,IAAI,CAAC,CAAA;YACb,MAAM,QAAQ,GAAe;gBAC3B,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,GAAG;gBACT,WAAW,EAAE,gDAAgD,KAAK,6BAA6B;aAChG,CAAA;YACD,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAA;YACvF,WAAW,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,EAAE,CAAC,CAAA;QAC1F,CAAC;aAAM,CAAC;YACN,6EAA6E;YAC7E,uEAAuE;YACvE,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAA;QACnD,CAAC;QAED,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;QACnC,IAAI,IAAI,EAAE,CAAC;YACT,2EAA2E;YAC3E,8EAA8E;YAC9E,4EAA4E;YAC5E,yCAAyC;YACzC,MAAM,QAAQ,GAAG,mBAAmB,CAAC,IAAI,CAAC,CAAA;YAC1C,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;YAC1C,8EAA8E;YAC9E,8EAA8E;YAC9E,4CAA4C;YAC5C,MAAM,IAAI,GAAe,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,QAAQ,EAAE,CAAA;YACnE,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;gBACvB,MAAM,QAAQ,GAAG,OAAO,IAAI,CAAC,WAAW,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS,CAAA;gBACpF,MAAM,WAAW,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAA;gBAC7C,IAAI,CAAC,WAAW;oBACd,QAAQ,KAAK,SAAS;wBACpB,CAAC,CAAC,IAAI;wBACN,CAAC,CAAC,WAAW,KAAK,SAAS;4BACzB,CAAC,CAAC,GAAG,QAAQ,MAAM,WAAW,EAAE;4BAChC,CAAC,CAAC,QAAQ,CAAA;YAClB,CAAC;YACD,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;QAC/B,CAAC;IACH,CAAC;IAED,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAE,IAAI,CAAC,QAAqB,CAAC,CAAC,CAAC,EAAE,CAAA;IAClF,MAAM,QAAQ,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,CAAA;IAE/F,MAAM,MAAM,GAAe;QACzB,IAAI,EAAE,QAAQ;QACd,UAAU;QACV,oBAAoB,EAAE,KAAK;QAC3B,GAAG,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC7C,CAAA;IACD,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,EAAE,cAAc,EAAE,WAAW,EAAE,CAAA;AAC3E,CAAC","sourcesContent":["/**\n * Target-shape derivation for `applyContentWithShape` (EC-331).\n *\n * Reuses the existing collection→JSON-Schema derivation (`collectionJsonSchema`,\n * cms-core) rather than writing a new one, then applies the three leashes the AI\n * engine adds on top:\n *\n *  - `ai.exclude` fields are removed entirely (the model never sees them → cannot\n *    write them).\n *  - relation fields become an ENUM over the provided candidate ids (or are omitted\n *    when no candidates exist) — so a hallucinated relation id is not representable\n *    as valid structured output.\n *  - asset/image fields become an ENUM over the searched library asset ids (or are\n *    omitted when none were searched) — EC-381, the SAME leash as relations: a\n *    proposed asset id must be a real, `listAssets`-returned library asset, and a\n *    create shape with no searched assets simply has no asset property (empty beats\n *    wrong; the assistant never generates or uploads).\n *  - rich-text fields are MARKDOWN STRINGS (EC-379): the description names the\n *    allowed subset, and the engine converts md → the `{ version, doc }` storage\n *    envelope at proposal-build time. The field's `allow` config leashes component\n *    EMBEDS only — markdown cannot express an embed, so the leash is satisfied by\n *    construction (and still enforced downstream by `validateRichTextEmbeds`).\n *\n * Localized fields stay flat in the shape (the model authors one locale at a time);\n * the engine routes their values under `localized[locale]`.\n *\n * EC-473 — the shape now consumes the ONE constraint projection, so a rule declared\n * in config actually reaches the model:\n *\n *  - `collectionJsonSchema` merges declarative rules with the fragment derived from\n *    a schema-form `validation.validate`, so `{ min: 2 }` and `z.string().min(2)`\n *    arrive identically (and a declared DATE RANGE arrives at all — it previously\n *    reached no consumer whatsoever);\n *  - a rich-text field no longer OVERWRITES its constraints: the markdown schema is\n *    merged over them instead of replacing them (measured drift, EC-474 §2);\n *  - a `pattern` is dropped wherever a `format` explains the same thing (a\n *    200-character email regex teaches a model nothing and costs real tokens);\n *  - a field whose projection is knowingly partial (`schemaComplete: false`) SAYS SO\n *    in its description rather than presenting the partial rule as the whole rule.\n *\n * EC-505 — one further narrowing of what the model is TOLD (never of what the engine\n * accepts): a `date` property is `type: 'string'` + `format: 'date-time'` rather than\n * the `['string','number']` union the general projection carries, because the model is\n * asked to author an ISO instant (EC-472) and some providers reject a union `type`.\n *\n * EC-556 — the projection is VALIDATOR-facing (the value at rest: asset/relation\n * envelopes, the v2 rich-text object). Every property here is its WRITER form\n * (`writerFieldSchema`), derived from that projection at every depth — a bare asset\n * id, a `{ collection, id }` reference, a markdown string — so an asset, relation or\n * rich-text SUBFIELD of an `object` is told the same form as a top-level one. The\n * top-level relation/asset id enums (EC-381) override the writer form there.\n */\nimport { collectionJsonSchema, resolveLabel } from '@elytracms/core/cms-core'\nimport type { CollectionDef, FieldDef, JsonSchema } from '@elytracms/core/cms-core'\nimport { constraintSentence, toModelFacingSchema, writerFieldSchema } from './constraints'\nimport type { AssetCandidates, RelationCandidates } from './types'\n\n/** A relation field's resolved candidate set — how the engine maps ids → reference envelopes. */\nexport interface TargetRelationField {\n  fieldName: string\n  /** The relation's target collection id. */\n  target: string\n  multiple: boolean\n  /** The allowed candidate ids (the enum the model chose from). */\n  candidateIds: string[]\n}\n\n/** An asset field's resolved candidate set — how the engine maps ids → asset envelopes (EC-381). */\nexport interface TargetAssetField {\n  fieldName: string\n  multiple: boolean\n  /** The allowed library asset ids (the enum the model chose from). */\n  candidateIds: string[]\n}\n\n/** The derived target shape + the metadata the engine needs to post-process the output. */\nexport interface TargetShape {\n  /** The JSON Schema the structured output must satisfy. */\n  schema: JsonSchema\n  /** Field names removed by `ai.exclude` (untouchable). */\n  excluded: string[]\n  /** Field names whose values route under `localized[locale]`. */\n  localizedFields: string[]\n  /** Relation fields with their candidate enums. */\n  relationFields: TargetRelationField[]\n  /** Asset fields with their candidate enums (EC-381). */\n  assetFields: TargetAssetField[]\n}\n\nexport interface BuildTargetShapeInput {\n  collection: CollectionDef\n  /** Relation candidate ids by field — a relation field with none is omitted from the shape. */\n  candidates?: RelationCandidates\n  /** Asset candidate ids by field — an asset field with none is omitted from the shape (EC-381). */\n  assetCandidates?: AssetCandidates\n  /** UI locale for resolving field labels into descriptions. */\n  locale?: string\n}\n\n/**\n * A field's model-facing description: resolved label + optional `ai.hint` + the\n * constraint clause (EC-473). The constraints are stated in PROSE because that is\n * what a model acts on — the same facts also ride as JSON-Schema keywords for the\n * structured-output validator, which is a different reader.\n */\nfunction describe(field: FieldDef, locale?: string): string | undefined {\n  const label = resolveLabel(field.form?.label, locale) ?? field.name\n  const hint = field.ai?.hint\n  const constraints = constraintSentence(field)\n  const parts = [label, hint, constraints].filter(\n    (p): p is string => typeof p === 'string' && p.length > 0,\n  )\n  return parts.length > 0 ? parts.join(' — ') : undefined\n}\n\n/**\n * Build the leash-aware target shape from a collection + candidates. Deterministic;\n * never throws. Reuses `collectionJsonSchema` as the base (its `required` list), then\n * gives every property its writer form (EC-556) or its id-enum leash, and strips\n * excluded fields.\n */\nexport function buildTargetShape(input: BuildTargetShapeInput): TargetShape {\n  const base = collectionJsonSchema(input.collection)\n  const properties: Record<string, JsonSchema> = {\n    ...((base.properties as Record<string, JsonSchema>) ?? {}),\n  }\n  const excluded: string[] = []\n  const localizedFields: string[] = []\n  const relationFields: TargetRelationField[] = []\n  const assetFields: TargetAssetField[] = []\n\n  for (const field of input.collection.fields) {\n    if (field.localized) localizedFields.push(field.name)\n\n    if (field.ai?.exclude) {\n      excluded.push(field.name)\n      delete properties[field.name]\n      continue\n    }\n\n    if (field.type === 'relation') {\n      const candidates = input.candidates?.[field.name] ?? []\n      if (candidates.length === 0) {\n        // No candidate ids ⇒ omit the field: the model cannot emit a relation value\n        // at all, so a hallucinated id is structurally impossible.\n        delete properties[field.name]\n        continue\n      }\n      const ids = candidates.map((c) => c.id)\n      const label = candidates\n        .map((c) => (c.label ? `${c.id} (${c.label})` : c.id))\n        .join(', ')\n      const idSchema: JsonSchema = {\n        type: 'string',\n        enum: ids,\n        description: `Choose one of: ${label}`,\n      }\n      properties[field.name] = field.multiple ? { type: 'array', items: idSchema } : idSchema\n      relationFields.push({\n        fieldName: field.name,\n        target: field.target,\n        multiple: field.multiple,\n        candidateIds: ids,\n      })\n    } else if (field.type === 'asset') {\n      // EC-381 — same leash as relations: an asset field is an enum over the ids\n      // the model actually searched in the media library (`listAssets`). No\n      // searched assets ⇒ omit the field, so the proposal simply leaves it empty\n      // (an invented / to-be-uploaded id is structurally unrepresentable).\n      const candidates = input.assetCandidates?.[field.name] ?? []\n      if (candidates.length === 0) {\n        delete properties[field.name]\n        continue\n      }\n      const ids = candidates.map((c) => c.id)\n      const label = candidates\n        .map((c) => (c.label ? `${c.id} (${c.label})` : c.id))\n        .join(', ')\n      const idSchema: JsonSchema = {\n        type: 'string',\n        enum: ids,\n        description: `Choose an EXISTING library asset id, one of: ${label}. Leave empty if none fits.`,\n      }\n      properties[field.name] = field.multiple ? { type: 'array', items: idSchema } : idSchema\n      assetFields.push({ fieldName: field.name, multiple: field.multiple, candidateIds: ids })\n    } else {\n      // EC-556: the writer form at every depth (rich text → markdown, EC-379 / D2;\n      // nested asset / relation → the bare forms the write-time lens wraps).\n      properties[field.name] = writerFieldSchema(field)\n    }\n\n    const prop = properties[field.name]\n    if (prop) {\n      // EC-473: a `pattern` next to a `format` is 200+ characters that teach the\n      // model nothing — the format (and the prose constraints below) say it better.\n      // EC-505: and a `date`'s `['string','number']` union becomes the ISO string\n      // the model is actually asked to author.\n      const stripped = toModelFacingSchema(prop)\n      const desc = describe(field, input.locale)\n      // Preserve an existing description (e.g. relation enum / rich-text note), but\n      // append the constraint clause to it — the enum leash and the value rules are\n      // different facts and the model needs both.\n      const next: JsonSchema = stripped === prop ? prop : { ...stripped }\n      if (desc !== undefined) {\n        const existing = typeof next.description === 'string' ? next.description : undefined\n        const constraints = constraintSentence(field)\n        next.description =\n          existing === undefined\n            ? desc\n            : constraints !== undefined\n              ? `${existing} — ${constraints}`\n              : existing\n      }\n      properties[field.name] = next\n    }\n  }\n\n  const requiredIn = Array.isArray(base.required) ? (base.required as string[]) : []\n  const required = requiredIn.filter((n) => !excluded.includes(n) && properties[n] !== undefined)\n\n  const schema: JsonSchema = {\n    type: 'object',\n    properties,\n    additionalProperties: false,\n    ...(required.length > 0 ? { required } : {}),\n  }\n  return { schema, excluded, localizedFields, relationFields, assetFields }\n}\n"]}
+{"version":3,"file":"shape.js","sourceRoot":"","sources":["../../../src/lib/ai/shape.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Target-shape derivation for `applyContentWithShape` (EC-331).\n *\n * Reuses the existing collection→JSON-Schema derivation (`collectionJsonSchema`,\n * cms-core) rather than writing a new one, then applies the leashes the AI engine\n * adds on top:\n *\n *  - `ai.exclude` fields are removed entirely (the model never sees them → cannot\n *    write them).\n *  - relation ids become an ENUM over the searched candidates of the relation's\n *    target (or the position is omitted when none were searched) — so a hallucinated\n *    relation id is not representable as valid structured output.\n *  - asset ids become an ENUM over the searched library assets that fit the\n *    position's `accept` (or the position is omitted when none fit) — EC-381, the SAME\n *    leash as relations: a proposed asset id must be a real, `listAssets`-returned\n *    library asset (empty beats wrong; the assistant never generates or uploads).\n *    EC-593: both leashes hold at EVERY depth — a relation in an object, an asset in a\n *    repeater item — not only on a top-level field (`writerFieldSchema(field, leash)`).\n *  - rich-text fields are MARKDOWN STRINGS (EC-379): the description names the\n *    allowed subset, and the engine converts md → the `{ version: 2, content }` storage\n *    value at proposal-build time (`writer-form.ts`). The field's `allow` config leashes\n *    component EMBEDS only — markdown cannot express an embed, so the leash is\n *    satisfied by construction (and still enforced downstream by `validateRichTextEmbeds`).\n *  - a composition (`blocks`) has NO writer form (ratified 4c, EC-593): it is omitted,\n *    and the schema's own description says so — the omission is visible, never a field\n *    the model simply never hears of.\n *\n * Localized fields stay flat in the shape (the model authors one locale at a time);\n * the engine routes their values under `localized[locale]`.\n *\n * EC-473 — the shape now consumes the ONE constraint projection, so a rule declared\n * in config actually reaches the model:\n *\n *  - `collectionJsonSchema` merges declarative rules with the fragment derived from\n *    a schema-form `validation.validate`, so `{ min: 2 }` and `z.string().min(2)`\n *    arrive identically (and a declared DATE RANGE arrives at all — it previously\n *    reached no consumer whatsoever);\n *  - a rich-text field no longer OVERWRITES its constraints: the markdown schema is\n *    merged over them instead of replacing them (measured drift, EC-474 §2);\n *  - a `pattern` is dropped wherever a `format` explains the same thing (a\n *    200-character email regex teaches a model nothing and costs real tokens);\n *  - a field whose projection is knowingly partial (`schemaComplete: false`) SAYS SO\n *    in its description rather than presenting the partial rule as the whole rule.\n *\n * EC-505 — one further narrowing of what the model is TOLD (never of what the engine\n * accepts): a `date` property is `type: 'string'` + `format: 'date-time'` rather than\n * the `['string','number']` union the general projection carries, because the model is\n * asked to author an ISO instant (EC-472) and some providers reject a union `type`.\n *\n * EC-556 — the projection is VALIDATOR-facing (the value at rest: asset/relation\n * envelopes, the v2 rich-text object). Every property here is its WRITER form\n * (`writerFieldSchema`), derived from that projection at every depth — a bare asset\n * id, a relation id, a markdown string — so an asset, relation or rich-text SUBFIELD of\n * an `object` is told the same form as a top-level one.\n */\nimport { collectionJsonSchema, resolveLabel } from '@elytracms/core/cms-core'\nimport type { CollectionDef, FieldDef, JsonSchema } from '@elytracms/core/cms-core'\nimport { constraintSentence, toModelFacingSchema, writerFieldSchema } from './constraints'\nimport { NO_SEARCHED_IDS } from './leash'\nimport type { WriterLeash } from './types'\n\n/** A top-level relation field's resolved candidate set (the enum the model chose from). */\nexport interface TargetRelationField {\n  fieldName: string\n  /** The relation's target collection id. */\n  target: string\n  multiple: boolean\n  /** The allowed candidate ids (the enum the model chose from). */\n  candidateIds: string[]\n}\n\n/** A top-level asset field's resolved candidate set (EC-381). */\nexport interface TargetAssetField {\n  fieldName: string\n  multiple: boolean\n  /** The allowed library asset ids (the enum the model chose from). */\n  candidateIds: string[]\n}\n\n/** The derived target shape + the metadata the engine needs to post-process the output. */\nexport interface TargetShape {\n  /** The JSON Schema the structured output must satisfy. */\n  schema: JsonSchema\n  /** Field names removed by `ai.exclude` (untouchable). */\n  excluded: string[]\n  /** Field names omitted because a writer never writes them — a composition (4c). */\n  compositions: string[]\n  /** Field names whose values route under `localized[locale]`. */\n  localizedFields: string[]\n  /** Top-level relation fields with their candidate enums. */\n  relationFields: TargetRelationField[]\n  /** Top-level asset fields with their candidate enums (EC-381). */\n  assetFields: TargetAssetField[]\n}\n\nexport interface BuildTargetShapeInput {\n  collection: CollectionDef\n  /** What the model searched — the id leash at every position (absent → nothing searched). */\n  leash?: WriterLeash\n  /** UI locale for resolving field labels into descriptions. */\n  locale?: string\n}\n\n/**\n * A field's model-facing description: resolved label + optional `ai.hint` + the\n * constraint clause (EC-473). The constraints are stated in PROSE because that is\n * what a model acts on — the same facts also ride as JSON-Schema keywords for the\n * structured-output validator, which is a different reader.\n */\nfunction describe(field: FieldDef, locale?: string): string | undefined {\n  const label = resolveLabel(field.form?.label, locale) ?? field.name\n  const hint = field.ai?.hint\n  const constraints = constraintSentence(field)\n  const parts = [label, hint, constraints].filter(\n    (p): p is string => typeof p === 'string' && p.length > 0,\n  )\n  return parts.length > 0 ? parts.join(' — ') : undefined\n}\n\n/**\n * Build the leash-aware target shape from a collection + what the model searched.\n * Deterministic; never throws. Reuses `collectionJsonSchema` as the base (its\n * `required` list), then gives every property its writer form (EC-556) — id enums at\n * every depth (EC-593) — and strips excluded fields and compositions.\n */\nexport function buildTargetShape(input: BuildTargetShapeInput): TargetShape {\n  const leash = input.leash ?? NO_SEARCHED_IDS\n  const base = collectionJsonSchema(input.collection)\n  const properties: Record<string, JsonSchema> = {\n    ...((base.properties as Record<string, JsonSchema>) ?? {}),\n  }\n  const excluded: string[] = []\n  const compositions: string[] = []\n  const localizedFields: string[] = []\n  const relationFields: TargetRelationField[] = []\n  const assetFields: TargetAssetField[] = []\n\n  for (const field of input.collection.fields) {\n    if (field.localized) localizedFields.push(field.name)\n\n    if (field.ai?.exclude) {\n      excluded.push(field.name)\n      delete properties[field.name]\n      continue\n    }\n\n    // EC-556: the writer form at every depth (rich text → markdown, EC-379 / D2;\n    // nested asset / relation → the bare forms the write-time lens wraps); EC-593:\n    // every id an enum over what was searched for that position.\n    const written = writerFieldSchema(field, leash)\n    if (written === undefined) {\n      // No writer form: a composition (4c), or a relation / asset with nothing\n      // searched for it — the model cannot emit a value, so a hallucinated id is\n      // structurally impossible (empty beats wrong).\n      if (field.type === 'blocks') compositions.push(field.name)\n      delete properties[field.name]\n      continue\n    }\n    if (field.type === 'relation') {\n      const candidateIds = leash.relationCandidates(field.target).map((c) => c.id)\n      relationFields.push({ fieldName: field.name, target: field.target, multiple: field.multiple, candidateIds })\n    } else if (field.type === 'asset') {\n      const candidateIds = leash.assetCandidates(field).map((c) => c.id)\n      assetFields.push({ fieldName: field.name, multiple: field.multiple, candidateIds })\n    }\n\n    // EC-473: a `pattern` next to a `format` is 200+ characters that teach the\n    // model nothing — the format (and the prose constraints below) say it better.\n    const stripped = toModelFacingSchema(written)\n    const desc = describe(field, input.locale)\n    // Preserve an existing description (e.g. relation enum / rich-text note), but\n    // append the constraint clause to it — the enum leash and the value rules are\n    // different facts and the model needs both.\n    const next: JsonSchema = stripped === written ? { ...written } : { ...stripped }\n    if (desc !== undefined) {\n      const existing = typeof next.description === 'string' ? next.description : undefined\n      const constraints = constraintSentence(field)\n      next.description =\n        existing === undefined\n          ? desc\n          : constraints !== undefined\n            ? `${existing} — ${constraints}`\n            : existing\n    }\n    properties[field.name] = next\n  }\n\n  const requiredIn = Array.isArray(base.required) ? (base.required as string[]) : []\n  const required = requiredIn.filter((n) => !excluded.includes(n) && properties[n] !== undefined)\n\n  const schema: JsonSchema = {\n    type: 'object',\n    properties,\n    additionalProperties: false,\n    ...(required.length > 0 ? { required } : {}),\n    // 4c (EC-593): the omission is said, not silent.\n    ...(compositions.length > 0\n      ? {\n          description: `Not part of this object: ${compositions.join(', ')} — page-builder composition${compositions.length > 1 ? 's' : ''} whose components are added, moved and removed on the canvas, never by the assistant.`,\n        }\n      : {}),\n  }\n  return { schema, excluded, compositions, localizedFields, relationFields, assetFields }\n}\n"]}

package/dist/lib/ai/tools.d.ts

@@ -33,25 +33,18 @@
  */
 import { z } from 'zod';
 import type { CmsDocument, CollectionDef, CollectionRegistry, LocaleConfig, ValidateDocumentOptions } from '@elytracms/core/cms-core';
-import type { ComponentManifest } from '@elytracms/core/component-registry';
+import type { SearchedAsset, SearchedDocument } from './leash.js';
+import type { TranslateSkip } from './translate-document.js';
 import type { ChatProposal } from './chat-state.js';
-import type { AiProvider, AssetCandidates, RelationCandidates, ResolvedKnowledge } from './types.js';
+import type { AiProvider, ResolvedKnowledge, WriterLeash } from './types.js';
 /** A document the model may reference as a relation target (from a `searchDocuments` read). */
-export interface DocumentSearchResult {
-    id: string;
-    title?: string;
-}
+export type DocumentSearchResult = SearchedDocument;
 /**
  * An asset the model may reference (from a `listAssets` read). EC-588: it carries the
- * two facts a field's `accept` is judged on, so each asset field's candidates can be
- * filtered to what that field takes — and the model can see what each asset is.
+ * two facts a field's `accept` is judged on, so each asset position's candidates can be
+ * filtered to what that position takes — and the model can see what each asset is.
  */
-export interface AssetSearchResult {
-    id: string;
-    title?: string;
-    contentType: string;
-    filename: string;
-}
+export type AssetSearchResult = SearchedAsset;
 /**
  * The client-side, operations-backed readers the executor calls. The studio binds
  * these to the user's authenticated operations client; tests bind an in-memory fake.
@@ -201,26 +194,18 @@ export type ChatToolOutcome = {
 };
 /**
  * The per-conversation candidate store: every `searchDocuments` result is recorded
- * per relation target collection, every `listAssets` result into one flat library
- * pool (EC-381), and the terminal tools may only reference the ids gathered here
- * (the `applyContentWithShape` / `buildUpdateProposal` enum + drop/loud leash makes
- * a hallucinated relation OR asset id structurally unrepresentable / fail loud).
- * Held by the panel per conversation — a new conversation (EC-380 clear) starts an
- * empty store.
+ * per collection, every `listAssets` result into one flat library pool (EC-381), and
+ * the terminal tools may only reference the ids gathered here. The store IS the
+ * {@link WriterLeash} the engines ask per position (EC-593): a relation by its target
+ * collection, an asset by its declaration's `accept` (EC-588) — so a nested relation, a
+ * component's asset prop and a top-level field are leashed by the same two questions
+ * (the create enum + drop, the update loud refusal). Held by the panel per
+ * conversation — a new conversation (EC-380 clear) starts an empty store.
  */
-export interface ChatCandidateStore {
+export interface ChatCandidateStore extends WriterLeash {
     record(collection: string, results: readonly DocumentSearchResult[]): void;
     /** Record every `listAssets` result into the flat library pool (EC-381). */
     recordAssets(results: readonly AssetSearchResult[]): void;
-    /** Candidates for a target collection's relation fields, keyed by field name. */
-    candidatesFor(collection: CollectionDef): RelationCandidates;
-    /**
-     * Candidates for a target collection's asset/image fields (EC-381), keyed by
-     * field name — the one flat searched-asset pool (`listAssets` has no field
-     * dimension), filtered per field by that field's `accept` (EC-588). A field with no
-     * fitting candidate is absent, so it is omitted from the shape (empty beats wrong).
-     */
-    assetCandidatesFor(collection: CollectionDef): AssetCandidates;
 }
 export declare function createChatCandidateStore(): ChatCandidateStore;
 export interface ChatToolExecutorOptions {
@@ -249,8 +234,6 @@ export interface ChatToolExecutorOptions {
     currentDocument?: () => CurrentDocumentRef | null | undefined;
     /** Current knowledge snapshot (thunk — the body thunk refreshes it per request). */
     knowledge?: () => ResolvedKnowledge | undefined;
-    /** Component manifests — context for `allow`-leashed richText/blocks fields. */
-    components?: readonly ComponentManifest[];
     /** Target locale for localized fields. */
     locale?: string;
     /** Locale config — required for `translateDocument`. */
@@ -260,7 +243,9 @@ export interface ChatToolExecutorOptions {
      * `gateValidateOptions(...)`, forwarded whole to every engine below. EC-473
      * made the assistant's gate the editor's gate; passing one bag instead of five
      * keys makes it stay that way, because a key can no longer be dropped by being
-     * forgotten at one of the three call sites this replaced.
+     * forgotten at one of the three call sites this replaced. Its `lookupManifest` is
+     * also how the writer-form converter and the read form reach component props
+     * (EC-593) — the props the validator judges, no second component source.
      */
     validateOptions?: ValidateDocumentOptions;
     /** Max repair attempts inside `applyContentWithShape`. */
@@ -272,16 +257,26 @@ export interface ChatToolExecutorOptions {
 export interface ChatToolExecutor {
     execute(call: ChatToolCall): Promise<ChatToolOutcome>;
 }
+/** A translate skip as one model-facing phrase: `menu[1].label (de): the provider returned no text`. */
+export declare function describeTranslateSkip(skip: TranslateSkip): string;
 /**
- * The MODEL-facing view of a document (EC-379): rich-text field values are
- * projected to markdown strings — but ONLY when the engine's loss-guarded
- * inverse can express them faithfully (subset-only content, round-trip proven).
- * A document carrying embeds, internal `ref` links, or out-of-subset marks keeps
- * its `{ version, doc }` envelope, so nothing the model later echoes back can
- * silently lose structure. Applies to the `getDocument` TOOL OUTPUT only; the
- * proposal/apply paths always read the raw stored document.
+ * The `getDocument` output (EC-379 → EC-593): the document in the form the model reads
+ * — the ONE converter's read side (`toWriterDocument`), so rich text is a markdown
+ * string at EVERY depth where the engine's loss-guarded inverse can express it
+ * faithfully (a top-level field, an object sub-field, a repeater item, a component's
+ * rich-text prop), and keeps its stored `{ version: 2, content }` value otherwise (embeds,
+ * internal `ref` links, out-of-subset marks), so nothing the model later echoes back can
+ * silently lose structure. It used to project TOP-LEVEL rich text only (SHAPES #29: a
+ * nested value read as v2 while every writer was told markdown).
+ *
+ * `components` is the catalog's prop half (RULES F3d): for every component on the
+ * document, the props `updateFields` may change and the rules each value must satisfy,
+ * read off the same declarations the validator judges (`lookupManifest`). Applies to
+ * the TOOL OUTPUT only; the proposal/apply paths always read the raw stored document.
  */
-export declare function projectRichTextAsMarkdown(document: CmsDocument, collection: CollectionDef): CmsDocument;
+export declare function modelFacingDocument(document: CmsDocument, collection: CollectionDef, validateOptions?: ValidateDocumentOptions): CmsDocument & {
+    components?: Record<string, string[]>;
+};
 /**
  * Build the client executor map. Every entry validates its input against
  * {@link chatToolDefinitions}' zod schema (the route validates UIMessages only