@elytracms/studio 0.0.100 → 0.0.102

package/dist/lib/ai/writer-form.d.ts

@@ -1,4 +1,4 @@
-import type { CmsDocument, CollectionDef, FieldDef, PropFieldLookup, ValuePath, ValuePosition } from '@elytracms/core/cms-core';
+import type { CmsDocument, CollectionDef, FieldDef, PropFieldLookup, ValuePath, ValuePosition, WriterLock } from '@elytracms/core/cms-core';
 import type { WriterLeash } from './types.js';
 /** The ids a document already references — reusable anywhere in it without a search. */
 export interface HeldReferences {
@@ -34,7 +34,14 @@ export interface WriterFormProblem {
     readonly message: string;
     /** An id outside the leash: it was REMOVED from the converted value. */
     readonly leash?: true;
+    /** A write to a writer-locked position (EC-716): the position KEPT its current value. */
+    readonly locked?: true;
 }
+/**
+ * What a writer is told about a write to a locked position (EC-716) — one wording for the
+ * create's dropped-value warning, the edit's refusal and a component prop's refusal.
+ */
+export declare function lockedWriteMessage(subjectText: string, lock: WriterLock): string;
 export interface FromWriterFormResult {
     /** The stored form (`undefined` — clear the position). */
     readonly value: unknown;
@@ -49,6 +56,40 @@ export interface FromWriterFormResult {
 export declare function fromWriterForm(position: ValuePosition, current: unknown, ctx: WriterFormContext): FromWriterFormResult;
 /** {@link fromWriterForm} for a top-level field's value. */
 export declare function fromWriterFieldValue(field: FieldDef, raw: unknown, current: unknown, ctx: WriterFormContext, locale?: string): FromWriterFormResult;
+/**
+ * One writer-locked position under a value — the TOPMOST locked one on its branch (it stands
+ * for everything below it, which is locked too) — with its value (possibly absent: the
+ * position exists because its holder does), its lock and its location below the field.
+ */
+export interface LockedPosition {
+    readonly value: unknown;
+    readonly lock: WriterLock;
+    readonly at: readonly (string | number)[];
+}
+/**
+ * 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 declare function lockedRemovalMessage(holder: string, root: string, locked: readonly LockedPosition[], shortened: boolean): string;
+/**
+ * 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 declare function withLockedFrom(position: ValuePosition, current: unknown, ctx: Pick<WriterFormContext, 'lookupManifest'>): unknown;
+/**
+ * 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.
+ */
+export declare function lockedChanges(position: ValuePosition, next: unknown, ctx: Pick<WriterFormContext, 'lookupManifest'>): {
+    readonly lost: readonly LockedPosition[];
+    readonly created: readonly LockedPosition[];
+};
 export type FromWriterFormAtNodeResult = {
     readonly ok: true;
     /** The field's next value (the displayed value with the one prop converted). */
@@ -84,8 +125,9 @@ export declare function isTextPosition(position: ValuePosition): boolean;
  * same traversal"): a `text` value, and a `richText` / `blocks` sequence (its prose —
  * the sequence's own text — is the caller's to split) together with every text position
  * below it: component text props in a composition and in rich-text embeds, object
- * sub-fields, repeater items, asset placement sub-fields. An `ai.exclude` position (and
- * everything below it) is not text a writer may touch. Depth-first, document order.
+ * sub-fields, repeater items, asset placement sub-fields. A writer-locked position
+ * (EC-716: `ai.exclude` or `form.readOnly`) and everything below it is not text a writer
+ * may touch — not a unit, and so never a skip either. Depth-first, document order.
  */
 export declare function textPositionsOf(position: ValuePosition, ctx: Pick<WriterFormContext, 'lookupManifest'>): ValuePosition[];
 /**
@@ -104,6 +146,16 @@ export declare function rebuildTextPositions(position: ValuePosition, ctx: Pick<
  * 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.
  */
 export declare function toWriterForm(position: ValuePosition, ctx: Pick<WriterFormContext, 'lookupManifest'>): unknown;
 /**
@@ -112,5 +164,22 @@ export declare function toWriterForm(position: ValuePosition, ctx: Pick<WriterFo
  * — in first-seen order. What the `getDocument` output's prop catalog lists.
  */
 export declare function componentIdsOf(collection: CollectionDef, document: CmsDocument, lookupManifest: PropFieldLookup): string[];
+/**
+ * {@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 declare function toWriterValues(collection: CollectionDef, bag: Readonly<Record<string, unknown>>, ctx: Pick<WriterFormContext, 'lookupManifest'>, locale?: string): Record<string, unknown>;
 /** {@link toWriterForm} over every field of every bucket of a document. */
 export declare function toWriterDocument(collection: CollectionDef, document: CmsDocument, ctx: Pick<WriterFormContext, 'lookupManifest'>): CmsDocument;
+/**
+ * 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 declare function modelFacingTitle(collection: CollectionDef, values: Readonly<Record<string, unknown>>, fallbackId: string, ctx?: Pick<WriterFormContext, 'lookupManifest'>): string;

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

@@ -36,11 +36,25 @@
  *   (`FIELD_TYPES.blocks.writer === 'composition'`), and a rich-text value must keep the
  *   component nodes it holds (same ids, same components, same places). A component's
  *   PROP is content — {@link fromWriterFormAtNode} changes one, by its node, at any depth
- *   the traversal reaches.
+ *   the traversal reaches;
+ * - **the writer lock** (EC-716, owner ruling "Yes, honour readOnly") — a position core's
+ *   `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);
+ * - **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}).
  *
  * Pure and deterministic; no provider, no I/O.
  */
-import { carryAssetPlacements, childPositions, fieldPath, fieldTypeOf, fieldValuePosition, isSequenceValue, rebuildFromChildren, referenceNode, sequenceComponentNodes, walkReferences, walkValuePositions, } from '@elytracms/core/cms-core';
+import { carryAssetPlacements, childPositions, fieldPath, fieldTypeOf, fieldValuePosition, isSequenceValue, readAssetId, rebuildFromChildren, referenceNode, resolveDocumentTitle, seedObjectItem, 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() };
@@ -65,6 +79,15 @@ export function heldReferencesOf(document) {
     });
     return { documents, assets };
 }
+/**
+ * What a writer is told about a write to a locked position (EC-716) — one wording for the
+ * create's dropped-value warning, the edit's refusal and a component prop's refusal.
+ */
+export function lockedWriteMessage(subjectText, lock) {
+    return lock === 'excluded'
+        ? `${subjectText} must not be edited by the assistant.`
+        : `${subjectText} is read-only — no one changes it in the studio, the assistant included.`;
+}
 // --- Writer form → stored form -------------------------------------------------------
 /**
  * Convert a value a model authored at `position` (its `value` is the WRITER form) into
@@ -73,8 +96,12 @@ export function heldReferencesOf(document) {
  * 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. */
@@ -132,9 +159,196 @@ function convertChildren(pos, current, ctx, problems, root) {
             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));
+}
+/**
+ * `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 convertWritable(pos, current, ctx, problems, root, isRoot);
+    if (pos.value === undefined || isEcho(pos, current, ctx, root))
+        return current;
+    problems.push({
+        at: pos.at,
+        code: 'invalid-field-value',
+        message: lockedWriteMessage(`Field ${subject(pos, root)}`, lock),
+        locked: true,
+    });
+    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;
+    problems.push({
+        at: pos.at,
+        code: 'invalid-field-value',
+        message: lockedRemovalMessage(subject(pos, root), root, lost.length > 0 ? lost : held, 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 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))
+            visit(child, lockedChildKey(pos, key, child));
+    };
+    visit(position, '');
+    return out;
+}
+/** The defined locked values of `before` that `after` does not hold, unchanged, at their key. */
+function lockedLosses(before, after) {
+    return [...before].flatMap(([key, entry]) => {
+        if (!isPresent(entry.value))
+            return [];
+        const now = after.get(key);
+        return now && isPresent(now.value) && canonicalJson(now.value) === canonicalJson(entry.value) ? [] : [entry];
+    });
+}
+/**
+ * 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;
+        return rebuildFromChildren(pos, positionCtx, (child) => rebuild(child, lockedChildKey(pos, key, child)));
+    };
+    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.
+ */
+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]) => 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
+ * in ({@link toWriterForm}: rich text as markdown), or in any writer form that converts to
+ * exactly the stored value.
+ */
+function isEcho(pos, current, ctx, root) {
+    const written = pos.value;
+    if (written === null)
+        return current === undefined || current === null;
+    if (current === undefined || current === null)
+        return false;
+    const json = canonicalJson(written);
+    if (json === canonicalJson(current))
+        return true;
+    if (json === canonicalJson(toWriterForm({ ...pos, value: current }, ctx)))
+        return true;
+    const scratch = [];
+    const stored = convertValue(pos, current, ctx, scratch, root);
+    return scratch.length === 0 && canonicalJson(stored) === canonicalJson(current);
+}
+/**
+ * A repeater's current value with every item the written list adds seeded the way a
+ * manual "add item" seeds it (core's `seedObjectItem`), so a locked sub-field of a NEW item
+ * keeps its default rather than staying empty (EC-716, sol-C 22 at item level). Items are
+ * matched by index — the matching the converter uses for every repeater.
+ */
+function withSeededItems(current, length, fields) {
+    const items = Array.isArray(current) ? current : [];
+    if (items.length >= length)
+        return current;
+    return [...items, ...Array.from({ length: length - items.length }, () => seedObjectItem(fields))];
 }
-function convert(pos, current, ctx, problems, root) {
+/** {@link convert} for a position no lock holds: the writer form → the stored form. */
+function convertValue(pos, current, ctx, problems, root) {
     const { field } = pos;
     const raw = pos.value === null ? undefined : pos.value;
     const report = (code, message, leash) => {
@@ -144,8 +358,13 @@ function convert(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).`);
         }
@@ -246,9 +465,15 @@ function convert(pos, current, ctx, problems, root) {
                 return undefined;
             return relation.multiple === true ? refs : refs[0];
         }
-        case 'object':
+        case 'object': {
             // A value of the wrong shape has no children; the validator names it.
-            return raw === undefined ? undefined : convertChildren({ ...pos, value: raw }, current, ctx, problems, root);
+            if (raw === undefined)
+                return undefined;
+            const base = field.type === 'object' && field.multiple && Array.isArray(raw)
+                ? withSeededItems(current, raw.length, field.fields)
+                : current;
+            return convertChildren({ ...pos, value: raw }, base, ctx, problems, root);
+        }
         case 'value':
             return raw;
     }
@@ -273,16 +498,31 @@ export function fromWriterFormAtNode(field, displayed, nodeId, prop, raw, ctx, l
     const root = fieldValuePosition(field, displayed, locale !== undefined ? { locale } : {});
     const isTarget = (position) => position.kind === 'prop' && position.component?.nodeId === nodeId && position.field.name === prop;
     let target;
+    // EC-716: the lock the target sits under — its own, or the nearest locked ancestor's
+    // (a component embedded in a read-only rich-text prop, a prop of a locked object…).
+    let targetLock;
     const declared = [];
     let componentId;
-    walkValuePositions(root, positionCtx, (position) => {
-        if (position.kind !== 'prop' || position.component?.nodeId !== nodeId)
-            return;
-        componentId = position.component.componentId;
-        declared.push(position.field.name);
-        if (target === undefined && position.field.name === prop)
-            target = position;
-    });
+    const visit = (position, inherited) => {
+        const lock = writerLockOf(position.field) ?? inherited;
+        if (position.kind === 'prop' && position.component?.nodeId === nodeId) {
+            componentId = position.component.componentId;
+            declared.push(position.field.name);
+            if (target === undefined && position.field.name === prop) {
+                target = position;
+                targetLock = lock;
+            }
+        }
+        for (const child of childPositions(position, positionCtx))
+            visit(child, lock);
+    };
+    visit(root, undefined);
+    if (target && targetLock !== undefined) {
+        return {
+            ok: false,
+            message: lockedWriteMessage(`Prop "${prop}" of component "${nodeId}" (${componentId})`, targetLock),
+        };
+    }
     if (!target) {
         if (componentId === undefined) {
             return {
@@ -296,7 +536,9 @@ export function fromWriterFormAtNode(field, displayed, nodeId, prop, raw, ctx, l
         };
     }
     const found = target;
-    const { value: converted, problems } = fromWriterForm({ ...found, value: raw }, found.value, ctx);
+    // 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)));
     const value = rebuild(root);
     return found.exact
@@ -309,22 +551,24 @@ export function isTextPosition(position) {
     const { type } = position.field;
     return type === 'text' || type === 'richText' || type === 'blocks';
 }
-function isExcludedBelow(position) {
-    return position.at.length > 0 && position.field.ai?.exclude === true;
+/** EC-716: a writer-locked position — no unit, no write, nothing below it either. */
+function isLocked(position) {
+    return writerLockOf(position.field) !== undefined;
 }
 /**
  * Every TEXT position at or below `position` (EC-593, ratified 4e — "translate uses the
  * same traversal"): a `text` value, and a `richText` / `blocks` sequence (its prose —
  * the sequence's own text — is the caller's to split) together with every text position
  * below it: component text props in a composition and in rich-text embeds, object
- * sub-fields, repeater items, asset placement sub-fields. An `ai.exclude` position (and
- * everything below it) is not text a writer may touch. Depth-first, document order.
+ * sub-fields, repeater items, asset placement sub-fields. A writer-locked position
+ * (EC-716: `ai.exclude` or `form.readOnly`) and everything below it is not text a writer
+ * may touch — not a unit, and so never a skip either. Depth-first, document order.
  */
 export function textPositionsOf(position, ctx) {
     const positionCtx = ctx.lookupManifest ? { lookupManifest: ctx.lookupManifest } : {};
     const out = [];
     const visit = (current) => {
-        if (isExcludedBelow(current))
+        if (isLocked(current))
             return;
         if (isTextPosition(current))
             out.push(current);
@@ -346,7 +590,7 @@ export function textPositionsOf(position, ctx) {
 export function rebuildTextPositions(position, ctx, replace) {
     const positionCtx = ctx.lookupManifest ? { lookupManifest: ctx.lookupManifest } : {};
     const rebuild = (current) => {
-        if (isExcludedBelow(current))
+        if (isLocked(current))
             return current.value;
         if (current.field.type === 'text')
             return replace(current);
@@ -364,8 +608,20 @@ 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.
  */
 export function toWriterForm(position, ctx) {
+    if (writerLockOf(position.field) === 'excluded')
+        return undefined;
     const { value } = position;
     if (value === undefined || value === null)
         return value;
@@ -402,28 +658,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