@elytracms/studio 0.0.102 → 0.0.104

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

@@ -50,11 +50,19 @@
  *   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}).
+ *   ({@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, readAssetId, rebuildFromChildren, referenceNode, resolveDocumentTitle, 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() };
@@ -150,16 +158,65 @@ 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, false));
+    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;
+    });
 }
 /**
  * `isRoot` — whether `pos` is the write's root (the field, or the prop a node change
@@ -170,8 +227,18 @@ 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 (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({
@@ -211,10 +278,13 @@ function convertWritable(pos, current, ctx, problems, root, isRoot) {
         (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: lockedRemovalMessage(subject(pos, root), root, lost.length > 0 ? lost : held, shortened),
+        message: judged.some((entry) => entry.opaque !== undefined)
+            ? unreadableLockedMessage(subject(pos, root), root, judged)
+            : lockedRemovalMessage(subject(pos, root), root, judged, shortened),
         locked: true,
     });
     return current;
@@ -224,6 +294,26 @@ function convertWritable(pos, current, ctx, problems, root, isRoot) {
 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
@@ -253,20 +343,48 @@ function lockedPositionsUnder(position, positionCtx) {
             out.set(key, { value: pos.value, lock, at: pos.at });
             return;
         }
-        for (const child of childPositions(pos, positionCtx))
-            visit(child, lockedChildKey(pos, key, child));
+        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;
 }
-/** The defined locked values of `before` that `after` does not hold, unchanged, at their key. */
+/** 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) {
-    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];
-    });
+    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
@@ -295,7 +413,9 @@ export function withLockedFrom(position, current, ctx) {
     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)));
+        // 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, '');
 }
@@ -303,7 +423,10 @@ export function withLockedFrom(position, current, ctx) {
  * 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.
+ * 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 } : {};
@@ -311,7 +434,7 @@ export function lockedChanges(position, next, ctx) {
     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] : []),
+        created: [...after].flatMap(([key, entry]) => entry.opaque === undefined && isPresent(entry.value) && !isPresent(before.get(key)?.value) ? [entry] : []),
     };
 }
 /**
@@ -421,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 ?? {};
@@ -503,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) {
@@ -513,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,
@@ -539,7 +687,7 @@ export function fromWriterFormAtNode(field, displayed, nodeId, prop, raw, ctx, l
     // 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 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 }
@@ -574,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;
@@ -595,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);
 }
@@ -618,6 +770,13 @@ export function rebuildTextPositions(position, ctx, replace) {
  * ({@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')
@@ -632,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
@@ -650,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);