@elytracms/studio 0.0.101 → 0.0.103

package/dist/lib/ai/writer-form.js

@@ -41,11 +41,28 @@
  *   `writerLockOf` locks (`ai.exclude` or `form.readOnly`, and everything below it) keeps
  *   its CURRENT value. Leaving it out of the written value, or echoing it back unchanged,
  *   is no write; any other value is reported as a `locked` problem (create drops it, edit
- *   refuses — the same two policies as the id leash).
+ *   refuses — the same two policies as the id leash);
+ * - **the locked-content judge** (EC-738) — a write to a WRITABLE position must not erase
+ *   the locked content below it, which its own walk never visits: a holder omitted below
+ *   the write's root keeps its current value whole (omission is no write — and the model
+ *   may not know the holder holds anything, EC-741); an explicit removal (a root `null` /
+ *   omitted value, a nested `null`, a shorter list, a removed asset entry) of a holder whose
+ *   current value holds a defined locked value is a `locked` problem, located at the holder,
+ *   and the holder keeps its current value. A repeater whose items hold one cannot be
+ *   shortened at all (items are matched by index). Translate reuses the judge
+ *   ({@link withLockedFrom}, {@link lockedChanges});
+ * - **the unreadable value** (EC-748, Codex r9 F44) — a stored value the traversal cannot
+ *   read (a holder of the other cardinality after a schema edit, a repeater item that is no
+ *   object, a body that is no v2 sequence, a body read without the prop lookup, …) is
+ *   judged by its DECLARATION (`declarationMayHold`, failing closed on bodies), never read
+ *   as empty: the model read WITHHOLDS it when it may hold an excluded value, and a write
+ *   that would change or clear it is REFUSED when it may hold a locked one — until a non-AI
+ *   save stores it in its canonical form. A value the MODEL writes in a shape its
+ *   declaration does not read is refused too (nothing below it could be leashed or judged).
  *
  * Pure and deterministic; no provider, no I/O.
  */
-import { carryAssetPlacements, childPositions, fieldPath, fieldTypeOf, fieldValuePosition, isSequenceValue, rebuildFromChildren, referenceNode, seedObjectItem, sequenceComponentNodes, walkReferences, walkValuePositions, writerLockOf, } from '@elytracms/core/cms-core';
+import { carryAssetPlacements, childPositions, declarationMayHold, fieldPath, fieldTypeOf, fieldValuePosition, isOpaquePosition, isSequenceValue, readAssetId, rebuildFromChildren, referenceNode, resolveDocumentTitle, seedObjectItem, selfTypeFieldValue, sequenceComponentNodes, walkReferences, walkValuePositions, writerLockOf, } from '@elytracms/core/cms-core';
 import { parseRichTextValue, richTextValueToMarkdownProse } from '@elytracms/core/rich-text';
 import { richTextValueFromModelInput } from './rich-text-input.js';
 export const NO_HELD_REFERENCES = { documents: new Map(), assets: new Set() };
@@ -87,8 +104,12 @@ export function lockedWriteMessage(subjectText, lock) {
  * which the placement carry and the composition leash read. `null` / `undefined` clears.
  */
 export function fromWriterForm(position, current, ctx) {
+    return convertRoot(position, current, ctx, position.field.name);
+}
+/** One write, rooted at `position`; `root` names the top-level field in messages. */
+function convertRoot(position, current, ctx, root) {
     const problems = [];
-    const value = convert(position, current, ctx, problems, position.field.name);
+    const value = convert(position, current, ctx, problems, root, true);
     return { value, problems };
 }
 /** {@link fromWriterForm} for a top-level field's value. */
@@ -137,23 +158,87 @@ function childKey(parent, child) {
         ? `node:${child.component.nodeId}:${child.field.name}`
         : `at:${JSON.stringify(child.at.slice(parent.at.length))}`;
 }
+/** {@link childKey} for a value the traversal cannot read, in its own key space (EC-748). */
+function opaqueChildKey(parent, child) {
+    return child.opaque === 'not-a-static-prop' && child.component
+        ? `opaque:node:${child.component.nodeId}:${child.declaration.name}`
+        : `opaque:at:${JSON.stringify(child.at.slice(parent.at.length))}`;
+}
+/** The model-facing name of an unreadable value: its declaration's name, located when nested. */
+function opaqueSubject(position, root) {
+    const name = `"${position.declaration.name}"`;
+    return position.at.length === 0 ? name : `${name} (at ${label(root, position.at)})`;
+}
+/**
+ * What a writer is told about a value it wrote in a shape the declaration does not read
+ * (EC-748): nothing below it could be converted, leashed or judged for locks, so it is not
+ * written — said in the shape the field does take.
+ */
+function unreadableWriteMessage(position, root) {
+    const what = `Field ${opaqueSubject(position, root)}`;
+    switch (position.opaque) {
+        case 'cardinality':
+            return Array.isArray(position.value)
+                ? `${what} holds one value, not a list — send the value itself.`
+                : `${what} holds a list — send a list.`;
+        case 'not-an-object':
+            return `${what} takes an object of its declared sub-fields.`;
+        case 'not-an-asset':
+            return `${what} takes asset id string(s) from listAssets results.`;
+        case 'not-a-sequence':
+            return `${what} takes rich text as markdown, or the stored { version: 2, content } object.`;
+        case 'not-a-static-prop':
+            return `${what} is a component prop stored as no { value } member; the assistant cannot write it.`;
+        case 'no-prop-declarations':
+            return `${what} holds components whose props cannot be judged here: the project's components are not available.`;
+    }
+}
 /** Convert every child position of `pos` (its value already in a readable shape). */
 function convertChildren(pos, current, ctx, problems, root) {
     const positionCtx = ctx.lookupManifest ? { lookupManifest: ctx.lookupManifest } : {};
     const currentChildren = new Map();
     if (current !== undefined) {
         for (const child of childPositions({ ...pos, value: current }, positionCtx)) {
-            currentChildren.set(childKey(pos, child), child.value);
+            if (isOpaquePosition(child))
+                currentChildren.set(opaqueChildKey(pos, child), child.value);
+            else
+                currentChildren.set(childKey(pos, child), child.value);
         }
     }
-    return rebuildFromChildren(pos, positionCtx, (child) => convert(child, currentChildren.get(childKey(pos, child)), ctx, problems, root));
+    return rebuildFromChildren(pos, positionCtx, (child) => convert(child, currentChildren.get(childKey(pos, child)), ctx, problems, root, false), 
+    // EC-748: a value the model wrote in a shape its declaration does not read — nothing
+    // below it can be converted, leashed or judged for locks (a list written for a single
+    // object would reach a locked sub-field through the canonicaliser's unwrap). The stored
+    // value echoed back, unchanged, is no write; anything else is a problem, and not written.
+    (unreadable) => {
+        const stored = currentChildren.get(opaqueChildKey(pos, unreadable));
+        if (stored !== undefined && canonicalJson(stored) === canonicalJson(unreadable.value))
+            return unreadable.value;
+        problems.push({ at: unreadable.at, code: 'invalid-field-value', message: unreadableWriteMessage(unreadable, root) });
+        return undefined;
+    });
 }
-function convert(pos, current, ctx, problems, root) {
+/**
+ * `isRoot` — whether `pos` is the write's root (the field, or the prop a node change
+ * names): there an omitted value CLEARS (`update-fields`: "`null` / omitted clears");
+ * below it an omitted holder of locked content is kept whole (EC-738).
+ */
+function convert(pos, current, ctx, problems, root, isRoot) {
     // EC-716: a locked position keeps its current value — and so, by not being visited,
     // does everything below it (the lock cascades as the form's `readOnly` does).
     const lock = writerLockOf(pos.field);
-    if (lock === undefined)
-        return convertValue(pos, current, ctx, problems, root);
+    if (lock === undefined) {
+        const written = convertWritable(pos, current, ctx, problems, root, isRoot);
+        // EC-748: a component prop is judged against its canonical form (THE drift issue, at prop
+        // depth), and a proposal's write does not re-canonicalise props (update-fields: it would
+        // rewrite every untouched node's wrappers) — so a prop the converter WRITES is stored in
+        // its canonical form here, by the write lens itself (`writeField` does it for a field): a
+        // multi-select's lone option becomes a list, an emptied list or sequence absent. A value
+        // kept as it is (`current`) is never rewritten.
+        if (pos.kind !== 'prop' || written === current || written === undefined)
+            return written;
+        return selfTypeFieldValue(pos.field, written, ctx.lookupManifest ? { lookupManifest: ctx.lookupManifest } : {});
+    }
     if (pos.value === undefined || isEcho(pos, current, ctx, root))
         return current;
     problems.push({
@@ -164,6 +249,194 @@ function convert(pos, current, ctx, problems, root) {
     });
     return current;
 }
+/**
+ * {@link convert} for a WRITABLE position, judged for the locked content below it (EC-738).
+ * The conversion never visits a locked position its written value no longer holds (a
+ * cleared object, a shortened list, a removed asset entry), so the judge compares the locked
+ * values under the CURRENT value with those under the converted one.
+ */
+function convertWritable(pos, current, ctx, problems, root, isRoot) {
+    if (!isPresent(current))
+        return convertValue(pos, current, ctx, problems, root);
+    const positionCtx = ctx.lookupManifest ? { lookupManifest: ctx.lookupManifest } : {};
+    const before = lockedPositionsUnder({ ...pos, value: current }, positionCtx);
+    const held = [...before.values()].filter((entry) => isPresent(entry.value));
+    if (held.length === 0)
+        return convertValue(pos, current, ctx, problems, root);
+    // An omission below the write's root is no write (EC-716's rule for a locked position,
+    // applied to the holder of one): the holder keeps its current value, whole.
+    if (!isRoot && pos.value === undefined)
+        return current;
+    const next = convertValue(pos, current, ctx, problems, root);
+    const lost = lockedLosses(before, lockedPositionsUnder({ ...pos, value: next }, positionCtx));
+    // A repeater's items are matched by INDEX: removing one shifts every later item's
+    // writable content onto the locked values of the item before it — invisible to a per-key
+    // comparison, so any shortening of a repeater that holds locked content is refused.
+    const shortened = pos.field.type === 'object' &&
+        pos.field.multiple === true &&
+        Array.isArray(current) &&
+        (Array.isArray(next) ? next.length : 0) < current.length;
+    if (lost.length === 0 && !shortened)
+        return next;
+    const judged = lost.length > 0 ? lost : held;
+    problems.push({
+        at: pos.at,
+        code: 'invalid-field-value',
+        message: judged.some((entry) => entry.opaque !== undefined)
+            ? unreadableLockedMessage(subject(pos, root), root, judged)
+            : lockedRemovalMessage(subject(pos, root), root, judged, shortened),
+        locked: true,
+    });
+    return current;
+}
+// --- The locked-content judge (EC-738) -----------------------------------------------
+/** A value that is there (`undefined` / `null` — nothing to lose; the converter's own rule). */
+function isPresent(value) {
+    return value !== undefined && value !== null;
+}
+/**
+ * The writer lock an unreadable value's declaration may hold (EC-748): `excluded` when it may
+ * hold an `ai.exclude` position, else `read-only` when it may hold a `form.readOnly` one, else
+ * none — over the declaration alone (`declarationMayHold`: a body may hold any component, so
+ * it may hold either; `excluded` wins, the stricter lock).
+ */
+export function declaredWriterLock(declaration) {
+    if (declarationMayHold(declaration, (field) => writerLockOf(field) === 'excluded'))
+        return 'excluded';
+    if (declarationMayHold(declaration, (field) => writerLockOf(field) === 'read-only'))
+        return 'read-only';
+    return undefined;
+}
+/** {@link lockedChildKey} for a value the traversal cannot read — its own key space (EC-748). */
+function lockedOpaqueKey(parent, parentKey, child) {
+    if (child.opaque === 'not-a-static-prop' && child.component) {
+        return `opaque:node:${child.component.nodeId}:${child.declaration.name}`;
+    }
+    return `${parentKey}/opaque:${JSON.stringify(child.at.slice(parent.at.length))}`;
+}
+/**
+ * The key matching a child position across two values of one position: a component prop by
+ * its NODE (ids are unique in a document and survive a prose edit that shifts indices), an
+ * entry of an asset LIST by its asset id and occurrence (the carry's own matching,
+ * `carryAssetPlacements` — a reordered gallery keeps each placement), anything else by its
+ * location below the parent (a repeater item by index, a sub-field by name).
+ */
+function lockedChildKey(parent, parentKey, child) {
+    if (child.kind === 'prop' && child.component)
+        return `node:${child.component.nodeId}:${child.field.name}`;
+    const below = child.at.slice(parent.at.length);
+    if (parent.field.type === 'asset' && parent.field.multiple !== false && Array.isArray(parent.value)) {
+        const index = below[0];
+        const entries = parent.value;
+        const id = readAssetId(entries[index]);
+        const occurrence = entries.slice(0, index).filter((entry) => readAssetId(entry) === id).length;
+        return `${parentKey}/asset:${JSON.stringify(id)}#${occurrence}/${JSON.stringify(below.slice(1))}`;
+    }
+    return `${parentKey}/${JSON.stringify(below)}`;
+}
+/** Every topmost writer-locked position at or below `position`, by {@link lockedChildKey}. */
+function lockedPositionsUnder(position, positionCtx) {
+    const out = new Map();
+    const visit = (pos, key) => {
+        const lock = writerLockOf(pos.field);
+        if (lock !== undefined) {
+            out.set(key, { value: pos.value, lock, at: pos.at });
+            return;
+        }
+        for (const child of childPositions(pos, positionCtx)) {
+            if (!isOpaquePosition(child)) {
+                visit(child, lockedChildKey(pos, key, child));
+                continue;
+            }
+            // EC-748: what cannot be read is judged by its declaration — never "nothing locked here".
+            const lock = declaredWriterLock(child.declaration);
+            if (lock !== undefined)
+                out.set(lockedOpaqueKey(pos, key, child), { value: child.value, lock, at: child.at, opaque: child.opaque });
+        }
+    };
+    visit(position, '');
+    return out;
+}
+/** Whether `entry` sits in `other` unchanged at `key` (a defined value, the same JSON). */
+function keptAt(other, key, entry) {
+    const now = other.get(key);
+    return now !== undefined && isPresent(now.value) && canonicalJson(now.value) === canonicalJson(entry.value);
+}
+/**
+ * The defined locked values of `before` that `after` does not hold, unchanged, at their key —
+ * and (EC-748) every unreadable value that may hold one on EITHER side and is not on the other
+ * unchanged: what it holds cannot be compared, so a change to it (or one written where none
+ * was) is counted lost — fail closed.
+ */
+function lockedLosses(before, after) {
+    const lost = [...before].flatMap(([key, entry]) => (isPresent(entry.value) && !keptAt(after, key, entry) ? [entry] : []));
+    const written = [...after].flatMap(([key, entry]) => entry.opaque !== undefined && isPresent(entry.value) && !keptAt(before, key, entry) ? [entry] : []);
+    return [...lost, ...written];
+}
+/**
+ * What a writer is told about a write that would change or clear a value stored in a shape
+ * its declaration cannot read, which may hold locked content (EC-748), located at the holder
+ * the model wrote. Its content is never named (it cannot be read — and excluded content may
+ * not be disclosed, EC-741); the repair is a save outside the assistant.
+ */
+export function unreadableLockedMessage(holder, root, locked) {
+    const excluded = locked.some((entry) => entry.lock === 'excluded');
+    const where = locked.filter((entry) => entry.opaque !== undefined && entry.at.length > 0).map((entry) => label(root, entry.at));
+    const at = !excluded && where.length > 0 ? ` (${where.join(', ')})` : '';
+    const what = excluded ? 'content the assistant must not change' : 'read-only content';
+    return `Field ${holder} holds a value stored in a shape its declaration cannot read${at} — it was saved under an earlier schema or written past the editor — and it may hold ${what}; the assistant cannot change, replace or clear it. Repair it outside the assistant: save the field again in the editor, in the shape its declaration reads; then the assistant can change its other values.`;
+}
+/**
+ * What a writer is told about a write that would remove locked content (EC-738), located at
+ * the HOLDER the model wrote. Read-only content is named (the model reads it); excluded
+ * content never is (EC-741: the model never sees it, so naming its path would disclose it).
+ */
+export function lockedRemovalMessage(holder, root, locked, shortened) {
+    const excluded = locked.some((entry) => entry.lock === 'excluded');
+    const what = excluded
+        ? 'content the assistant must not change'
+        : `read-only content (${locked.map((entry) => label(root, entry.at)).join(', ')}) — no one changes it in the studio, the assistant included`;
+    return shortened
+        ? `Field ${holder} holds ${what}; the assistant cannot remove items from it (items are matched by position, so removing one would delete that content or move it onto another item). Keep every item and change only their other values.`
+        : `Field ${holder} holds ${what}; the assistant cannot clear or remove it. Change only its other values.`;
+}
+/**
+ * The value at `position` with every writer-locked position taken from `current` by key
+ * (EC-738, translate): where `current` holds that position — its value, an absent one
+ * included — the current one wins; a position `current` does not hold at all (a new item, a
+ * node it lacks) keeps `position`'s own. {@link lockedChanges} then says whether that kept
+ * the locked content as it is.
+ */
+export function withLockedFrom(position, current, ctx) {
+    const positionCtx = ctx.lookupManifest ? { lookupManifest: ctx.lookupManifest } : {};
+    const held = lockedPositionsUnder({ ...position, value: current }, positionCtx);
+    const rebuild = (pos, key) => {
+        if (writerLockOf(pos.field) !== undefined)
+            return held.has(key) ? held.get(key).value : pos.value;
+        // EC-748: a value `position` holds unreadably is kept as it is — nothing below it can be
+        // matched by key — and {@link lockedChanges} counts it lost unless `current` holds it too.
+        return rebuildFromChildren(pos, positionCtx, (child) => rebuild(child, lockedChildKey(pos, key, child)), (unreadable) => unreadable.value);
+    };
+    return rebuild(position, '');
+}
+/**
+ * The locked values a write from `position.value` (the CURRENT value) to `next` would lose or
+ * create, judged both ways (EC-738, translate): `lost` — a defined locked value `next` does
+ * not hold unchanged; `created` — a defined locked value `next` holds where the current value
+ * holds none. EC-748: a value stored in a shape its declaration cannot read, which may hold a
+ * locked value, on EITHER side and not on the other unchanged, is `lost` (fail closed) — so a
+ * drifted target keeps its value whole, and a drifted source never copies its locked values
+ * across.
+ */
+export function lockedChanges(position, next, ctx) {
+    const positionCtx = ctx.lookupManifest ? { lookupManifest: ctx.lookupManifest } : {};
+    const before = lockedPositionsUnder(position, positionCtx);
+    const after = lockedPositionsUnder({ ...position, value: next }, positionCtx);
+    return {
+        lost: lockedLosses(before, after),
+        created: [...after].flatMap(([key, entry]) => entry.opaque === undefined && isPresent(entry.value) && !isPresent(before.get(key)?.value) ? [entry] : []),
+    };
+}
 /**
  * Whether a value written to a locked position leaves it as it is: a clear of an empty
  * position, or the current value echoed back — as stored, in the form the model READ it
@@ -208,8 +481,13 @@ function convertValue(pos, current, ctx, problems, root) {
     switch (fieldTypeOf(field).writer) {
         case 'composition': {
             // 4c: a composition is never written whole — the value stays exactly what it is
-            // (re-sending it unchanged is no change); its props change one at a time.
-            if (canonicalJson(raw) === canonicalJson(current))
+            // (re-sending it unchanged is no change); its props change one at a time. EC-741:
+            // "unchanged" includes the value as the model READ it ({@link toWriterForm}: excluded
+            // props absent, rich-text props as markdown) — the rule `isEcho` reads.
+            const json = canonicalJson(raw);
+            if (json === canonicalJson(current))
+                return current;
+            if (current !== undefined && json === canonicalJson(toWriterForm({ ...pos, value: current }, ctx)))
                 return current;
             return report('invalid-field-value', `Field ${subject(pos, root)} is a page-builder composition: adding, reordering or removing its components is done on the canvas, not by the assistant. Change one component's prop with blockId + prop (the component's id from getDocument).`);
         }
@@ -266,7 +544,11 @@ function convertValue(pos, current, ctx, problems, root) {
                 return undefined;
             // EC-558 / 2c: the ONE carry rule — a held placement keeps its per-use sub-fields,
             // a swap carries them to the new image, a new id is an envelope.
-            const carried = carryAssetPlacements(current, asset.multiple === true ? { multiple: true, ids: kept.map((e) => e.id) } : { multiple: false, id: kept[0].id });
+            const carriedAsStored = carryAssetPlacements(current, asset.multiple === true ? { multiple: true, ids: kept.map((e) => e.id) } : { multiple: false, id: kept[0].id });
+            // EC-748: the carry hands back a single field's stored one-item list as it is (same id);
+            // the WRITTEN value takes the declared cardinality — the model wrote one value. (Whether
+            // replacing that unreadable stored list is allowed is the lock judge's question.)
+            const carried = asset.multiple !== true && Array.isArray(carriedAsStored) ? carriedAsStored[0] : carriedAsStored;
             // The writer's own sub-field values win over the carried ones.
             const withWriter = (entry, index) => {
                 const rest = kept[index]?.rest ?? {};
@@ -348,6 +630,8 @@ export function fromWriterFormAtNode(field, displayed, nodeId, prop, raw, ctx, l
     let targetLock;
     const declared = [];
     let componentId;
+    // EC-748: the target prop stored as no static member — declared, but unreadable.
+    let unreadableTarget = false;
     const visit = (position, inherited) => {
         const lock = writerLockOf(position.field) ?? inherited;
         if (position.kind === 'prop' && position.component?.nodeId === nodeId) {
@@ -358,10 +642,29 @@ export function fromWriterFormAtNode(field, displayed, nodeId, prop, raw, ctx, l
                 targetLock = lock;
             }
         }
-        for (const child of childPositions(position, positionCtx))
-            visit(child, lock);
+        for (const child of childPositions(position, positionCtx)) {
+            if (!isOpaquePosition(child)) {
+                visit(child, lock);
+                continue;
+            }
+            // EC-748: a node inside a value the traversal cannot read is not addressable — it is not
+            // found (the write never reaches into an unreadable holder); a prop of the node stored as
+            // no static member is declared but cannot be written.
+            if (child.opaque === 'not-a-static-prop' && child.component?.nodeId === nodeId) {
+                componentId = child.component.componentId;
+                declared.push(child.declaration.name);
+                if (child.declaration.name === prop)
+                    unreadableTarget = true;
+            }
+        }
     };
     visit(root, undefined);
+    if (!target && unreadableTarget) {
+        return {
+            ok: false,
+            message: `Prop "${prop}" of component "${nodeId}" (${componentId}) is stored as no { value } member (a retired shape); the assistant cannot change it. Repair it outside the assistant: set the prop again in the editor.`,
+        };
+    }
     if (target && targetLock !== undefined) {
         return {
             ok: false,
@@ -381,8 +684,10 @@ export function fromWriterFormAtNode(field, displayed, nodeId, prop, raw, ctx, l
         };
     }
     const found = target;
-    const { value: converted, problems } = fromWriterForm({ ...found, value: raw }, found.value, ctx);
-    const rebuild = (position) => rebuildFromChildren(position, positionCtx, (child) => (isTarget(child) ? converted : rebuild(child)));
+    // The prop is the write's ROOT (an omitted value clears it); messages locate positions
+    // from the top-level field (`body.content[0].props.group.locked`).
+    const { value: converted, problems } = convertRoot({ ...found, value: raw }, found.value, ctx, field.name);
+    const rebuild = (position) => rebuildFromChildren(position, positionCtx, (child) => (isTarget(child) ? converted : rebuild(child)), (unreadable) => unreadable.value);
     const value = rebuild(root);
     return found.exact
         ? { ok: true, value, path: found.path, propValue: converted, exact: true, problems }
@@ -417,8 +722,11 @@ export function textPositionsOf(position, ctx) {
             out.push(current);
         if (current.field.type === 'text')
             return;
+        // EC-748: a value the traversal cannot read yields no unit — its text cannot be found
+        // (and translate skips a bucket where one may hold locked content: `lockedChanges`).
         for (const child of childPositions(current, positionCtx))
-            visit(child);
+            if (!isOpaquePosition(child))
+                visit(child);
     };
     visit(position);
     return out;
@@ -438,7 +746,8 @@ export function rebuildTextPositions(position, ctx, replace) {
         if (current.field.type === 'text')
             return replace(current);
         const value = isTextPosition(current) ? replace(current) : current.value;
-        return rebuildFromChildren({ ...current, value }, positionCtx, rebuild);
+        // EC-748: an unreadable value comes back as it was (it held no unit).
+        return rebuildFromChildren({ ...current, value }, positionCtx, rebuild, (unreadable) => unreadable.value);
     };
     return rebuild(position);
 }
@@ -451,8 +760,27 @@ export function rebuildTextPositions(position, ctx, replace) {
  * stays, so nothing echoed back can silently lose structure), at EVERY position: a
  * top-level field, an object sub-field, a repeater item, a component's rich-text prop.
  * Everything else reads as stored (envelopes are writer forms too).
+ *
+ * **THE model-read projection** (EC-741): a position core's `writerLockOf` marks
+ * `excluded` (`ai: { exclude: true }` — "the model never sees or writes the field") reads
+ * as ABSENT, and so does everything below it, at every depth: a sub-field, a repeater
+ * item's sub-field, a placement sub-field, a component prop in a composition, a slot or
+ * typography content. A `read-only` position stays readable. Every model read crosses this
+ * one fold — `getDocument`'s output, the titles the model is shown
+ * ({@link modelFacingTitle}) and the echo checks (a value the model read and sent back is
+ * no change) — so what the model can see and what it can echo are one declaration. The raw
+ * stored document stays local: proposals are always built and validated against it.
+ *
+ * EC-748 (Codex r9 F44): a stored value the traversal cannot read (a holder of the other
+ * cardinality after a schema edit, a repeater item that is no object, a body that is no v2
+ * sequence or is read without the prop lookup, …) is WITHHELD — absent where it sits: the
+ * field, the list entry, the prop — whenever its declaration may hold an excluded position
+ * (`declaredWriterLock`, failing closed on bodies). What cannot be read cannot be projected,
+ * so it is never sent whole. One that may hold none reads as stored.
  */
 export function toWriterForm(position, ctx) {
+    if (writerLockOf(position.field) === 'excluded')
+        return undefined;
     const { value } = position;
     if (value === undefined || value === null)
         return value;
@@ -463,7 +791,7 @@ export function toWriterForm(position, ctx) {
         if (markdown !== undefined)
             return markdown;
     }
-    return rebuildFromChildren(position, positionCtx, (child) => toWriterForm(child, ctx));
+    return rebuildFromChildren(position, positionCtx, (child) => toWriterForm(child, ctx), (unreadable) => (declaredWriterLock(unreadable.declaration) === 'excluded' ? undefined : unreadable.value));
 }
 /**
  * The components a document holds whose props a writer may change — every component
@@ -481,7 +809,9 @@ export function componentIdsOf(collection, document, lookupManifest) {
             walkValuePositions(fieldValuePosition(field, value), { lookupManifest }, (position) => {
                 if (position.kind === 'prop' && position.component)
                     ids.add(position.component.componentId);
-            });
+            }, 
+            // EC-748: a component inside a value the traversal cannot read has no prop a writer can change.
+            () => { });
         }
     };
     visitBucket(document.values);
@@ -489,28 +819,50 @@ export function componentIdsOf(collection, document, lookupManifest) {
         visitBucket(bucket);
     return [...ids];
 }
+/**
+ * {@link toWriterForm} over one values bag: each declared field in its read form, an
+ * excluded one (and an excluded position inside any field) left out. A key the collection
+ * does not declare reads as stored (AD-14: the schema is a lens).
+ */
+export function toWriterValues(collection, bag, ctx, locale) {
+    let next;
+    for (const field of collection.fields) {
+        if (!Object.hasOwn(bag, field.name))
+            continue;
+        const value = bag[field.name];
+        const read = toWriterForm(fieldValuePosition(field, value, locale !== undefined ? { locale } : {}), ctx);
+        if (read === value)
+            continue;
+        next ??= { ...bag };
+        if (read === undefined)
+            delete next[field.name];
+        else
+            next[field.name] = read;
+    }
+    return next ?? bag;
+}
 /** {@link toWriterForm} over every field of every bucket of a document. */
 export function toWriterDocument(collection, document, ctx) {
-    const byName = new Map(collection.fields.map((field) => [field.name, field]));
-    const mapBucket = (bucket, locale) => {
-        let next = bucket;
-        for (const [name, value] of Object.entries(bucket)) {
-            const field = byName.get(name);
-            if (!field)
-                continue;
-            const read = toWriterForm(fieldValuePosition(field, value, locale !== undefined ? { locale } : {}), ctx);
-            if (read === value)
-                continue;
-            if (next === bucket)
-                next = { ...bucket };
-            next[name] = read;
-        }
-        return next;
-    };
-    const values = mapBucket(document.values);
+    const values = toWriterValues(collection, document.values, ctx);
     const localized = document.localized
-        ? Object.fromEntries(Object.entries(document.localized).map(([locale, bucket]) => [locale, mapBucket(bucket, locale)]))
+        ? Object.fromEntries(Object.entries(document.localized).map(([locale, bucket]) => [
+            locale,
+            toWriterValues(collection, bucket, ctx, locale),
+        ]))
         : undefined;
     return { ...document, values, ...(localized ? { localized } : {}) };
 }
+/**
+ * The title a MODEL is shown for a document (EC-741) — core's `resolveDocumentTitle` over
+ * the projected values ({@link toWriterValues}), so an excluded field never reaches the
+ * model as a title: neither as the named or first-field fallback, nor through a function
+ * `titleField` that reads it (the function sees the field absent). Every title the model
+ * reads goes through here: the `updateFields` / `createDocument` outputs, the
+ * `searchDocuments` results (their query is matched against this title too, so an
+ * excluded value cannot be probed by search) and the system prompt's "currently open"
+ * line. `values` is the bag the caller resolves titles from (a locale's merged values).
+ */
+export function modelFacingTitle(collection, values, fallbackId, ctx = {}) {
+    return resolveDocumentTitle(collection, toWriterValues(collection, values, ctx), fallbackId);
+}
 //# sourceMappingURL=writer-form.js.map