yarramate 0.7.0 → 0.7.1

package/dist/apply-command.js

@@ -1,6 +1,6 @@
 import { readFileSync, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { isSeq, parseDocument } from 'yaml';
+import { isMap, isScalar, isSeq, parseDocument, stringify, } from 'yaml';
 import Ajv2020Module from 'ajv/dist/2020.js';
 import { diagnosticJson, humanDiagnostics, usage, } from './cli-support.js';
 import { compileWorkspace } from './compiler.js';
@@ -11,48 +11,170 @@ import operationsSchema from '../schema/yarramate-operations.schema.json' with {
 };
 const Ajv2020 = Ajv2020Module.default;
 const validateOperations = new Ajv2020({ allErrors: true }).compile(operationsSchema);
-// Scalar fields replace; list fields append. An answer enriches what is
-// there — it never silently shrinks it (removals stay Git edits).
+// Scalar fields replace; list fields append; `remove` retracts (ADR 0062).
+// An answer enriches what is there and may explicitly take back what it
+// asserted — it never silently shrinks anything.
 const SCALAR_CONCEPT_FIELDS = ['kind', 'name', 'description', 'status', 'owner'];
 const LIST_CONCEPT_FIELDS = ['constraints', 'references', 'presentIn', 'attestations'];
 const SCALAR_RELATIONSHIP_FIELDS = ['kind', 'from', 'to', 'name', 'description', 'status', 'mode', 'content'];
 const LIST_RELATIONSHIP_FIELDS = ['references', 'presentIn'];
-const appendBlockItem = (document, collection, item) => {
-    document.addIn([collection], item);
-    const sequence = document.getIn([collection], true);
-    if (isSeq(sequence)) {
-        sequence.flow = false;
+// ---------------------------------------------------------------------------
+// The splice layer. Every operation becomes a minimal text edit against the
+// document's current source, so bytes the batch never touched stay
+// byte-identical — an apply diff is exactly the answer it landed (#114).
+// The atomic compile gate below validates the spliced text itself, so any
+// splice defect rejects the batch loudly instead of corrupting a document.
+const lineStartOf = (source, offset) => source.lastIndexOf('\n', offset - 1) + 1;
+const indentAt = (source, offset) => offset - lineStartOf(source, offset);
+// End of the last line a node occupies, extended through its newline.
+const lineEndAfter = (source, offset) => {
+    const newline = source.indexOf('\n', Math.max(offset - 1, 0));
+    return newline === -1 ? source.length : newline + 1;
+};
+const reindent = (text, indent) => text.split('\n').join(`\n${' '.repeat(indent)}`);
+// A plain value as YAML source. lineWidth 0 keeps strings we author on one
+// line; genuinely multi-line strings become block scalars and are re-indented
+// by the caller.
+const valueText = (value) => stringify(value, { lineWidth: 0 }).trimEnd();
+const pairFor = (map, key) => map.items.find((pair) => isScalar(pair.key) && pair.key.value === key);
+const nodeRange = (node) => {
+    const range = node.range;
+    if (range === undefined) {
+        throw new Error('YAML node has no source range');
+    }
+    return range;
+};
+// Renders `items` as block sequence entries at the given marker indent.
+const sequenceEntries = (items, markerIndent) => {
+    const rendered = stringify(items, { lineWidth: 0 }).trimEnd();
+    return `${' '.repeat(markerIndent)}${reindent(rendered, markerIndent)}`;
+};
+const splice = (source, start, end, text) => source.slice(0, start) + text + source.slice(end);
+// Insert a newline-terminated block at a line boundary, tolerating a
+// source that does not end in a newline.
+const insertBlock = (source, insertAt, block) => splice(source, insertAt, insertAt, insertAt > 0 && source[insertAt - 1] !== '\n' ? `\n${block}` : block);
+// Node ranges may extend past their trailing newline to the start of the
+// next line; anchor insertions on the last CONTENT line instead.
+const afterContentLine = (source, offset) => {
+    let anchor = offset;
+    while (anchor > 0 && source[anchor - 1] === '\n')
+        anchor -= 1;
+    return lineEndAfter(source, anchor);
+};
+// Where a new field of an item lands: after the last line of the item's
+// final pair.
+const itemFieldInsertAt = (source, map) => {
+    const lastPair = map.items[map.items.length - 1];
+    const anchor = lastPair.value === null || lastPair.value === undefined
+        ? nodeRange(lastPair.key)[2]
+        : nodeRange(lastPair.value)[1];
+    return afterContentLine(source, anchor);
+};
+// Appends one item to a top-level block collection (`concepts:` or
+// `relationships:`), creating or converting the collection when needed.
+const appendCollectionItem = (source, collection, item) => {
+    const document = parseDocument(source);
+    const root = document.contents;
+    if (!isMap(root))
+        throw new Error('Document root is not a mapping');
+    const pair = pairFor(root, collection);
+    if (pair === undefined) {
+        const base = source.endsWith('\n') ? source : `${source}\n`;
+        return `${base}${collection}:\n${sequenceEntries([item], 2)}\n`;
+    }
+    const sequence = pair.value;
+    if (isSeq(sequence) && !sequence.flow && sequence.items.length > 0) {
+        const lastItem = sequence.items[sequence.items.length - 1];
+        const markerIndent = indentAt(source, nodeRange(lastItem)[0]) - 2;
+        const insertAt = lineEndAfter(source, nodeRange(lastItem)[2]);
+        return insertBlock(source, insertAt, `${sequenceEntries([item], markerIndent)}\n`);
     }
+    if (!isSeq(sequence)) {
+        // `concepts:` with no value at all: append the block under the key.
+        const insertAt = lineEndAfter(source, nodeRange(pair.key)[2]);
+        return insertBlock(source, insertAt, `${sequenceEntries([item], 2)}\n`);
+    }
+    // Empty or flow collection: replace the whole value with a block
+    // sequence carrying any existing entries plus the new one, consuming
+    // the space that separated it from the key.
+    const existing = sequence.items.length > 0
+        ? sequence.toJSON()
+        : [];
+    let [start] = nodeRange(sequence);
+    const valueEnd = nodeRange(sequence)[1];
+    while (start > 0 && source[start - 1] === ' ')
+        start -= 1;
+    return splice(source, start, valueEnd, `\n${sequenceEntries([...existing, item], 2)}`);
 };
-const findItem = (document, collection, id) => {
-    const sequence = document.get(collection, true);
-    if (!isSeq(sequence))
+const itemMap = (source, collection, id) => {
+    const document = parseDocument(source);
+    const root = document.contents;
+    if (!isMap(root))
+        return undefined;
+    const pair = pairFor(root, collection);
+    if (pair === undefined || !isSeq(pair.value))
         return undefined;
-    return sequence.items.find((item) => typeof item === 'object' &&
-        item !== null &&
-        'get' in item &&
-        item.get('id') === id);
+    const found = pair.value.items.find((candidate) => isMap(candidate) &&
+        candidate.items.some((field) => isScalar(field.key) &&
+            field.key.value === 'id' &&
+            isScalar(field.value) &&
+            field.value.value === id));
+    return found === undefined ? undefined : { map: found };
 };
-const applyFields = (document, item, fields, scalars, lists) => {
-    for (const key of scalars) {
-        if (fields[key] !== undefined)
-            item.set(key, fields[key]);
+// The indent item fields sit at, read off the item's own first field.
+const fieldIndentOf = (source, map) => indentAt(source, nodeRange(map.items[0].key)[0]);
+const setScalarField = (source, map, key, value) => {
+    const indent = fieldIndentOf(source, map);
+    const rendered = reindent(valueText(value), indent + 2);
+    const pair = pairFor(map, key);
+    if (pair === undefined) {
+        return insertBlock(source, itemFieldInsertAt(source, map), `${' '.repeat(indent)}${key}: ${rendered}\n`);
     }
-    for (const key of lists) {
-        const additions = fields[key];
-        if (additions === undefined || additions.length === 0)
-            continue;
-        const existing = item.get(key);
-        if (existing === undefined) {
-            item.set(key, additions);
-        }
-        else if (isSeq(existing)) {
-            for (const entry of additions) {
-                existing.items.push(document.createNode(entry));
-            }
-        }
+    const [start, valueEnd] = nodeRange(pair.value);
+    return splice(source, start, valueEnd, rendered);
+};
+const appendListField = (source, map, key, additions) => {
+    const indent = fieldIndentOf(source, map);
+    const pair = pairFor(map, key);
+    if (pair === undefined) {
+        return insertBlock(source, itemFieldInsertAt(source, map), `${' '.repeat(indent)}${key}:\n${sequenceEntries(additions, indent + 2)}\n`);
+    }
+    const sequence = pair.value;
+    if (isSeq(sequence) && !sequence.flow && sequence.items.length > 0) {
+        const lastItem = sequence.items[sequence.items.length - 1];
+        const markerIndent = indentAt(source, nodeRange(lastItem)[0]) - 2;
+        const insertAt = lineEndAfter(source, nodeRange(lastItem)[2]);
+        return insertBlock(source, insertAt, `${sequenceEntries(additions, markerIndent)}\n`);
     }
+    const existing = isSeq(sequence) && sequence.items.length > 0
+        ? sequence.toJSON()
+        : [];
+    const merged = [...existing, ...additions];
+    const [start, valueEnd] = isSeq(sequence)
+        ? nodeRange(sequence)
+        : nodeRange(pair.value);
+    if (isSeq(sequence) && sequence.flow) {
+        const flow = stringify(merged, {
+            collectionStyle: 'flow',
+            lineWidth: 0,
+        }).trimEnd();
+        return splice(source, start, valueEnd, flow);
+    }
+    return splice(source, start, valueEnd, `\n${sequenceEntries(merged, indent + 2)}`);
+};
+// Retraction (#115): delete the field's whole entry, from the start of its
+// key line through the end of its value's last line.
+const removeField = (source, map, key) => {
+    const pair = pairFor(map, key);
+    if (pair === undefined)
+        return undefined;
+    const start = lineStartOf(source, nodeRange(pair.key)[0]);
+    const valueEnd = pair.value === null || pair.value === undefined
+        ? nodeRange(pair.key)[2]
+        : nodeRange(pair.value)[2];
+    return splice(source, start, lineEndAfter(source, valueEnd), '');
 };
+// ---------------------------------------------------------------------------
 export function runApplyCommand(options, cwd) {
     const json = options.includes('--json');
     const rest = options.filter((option) => option !== '--json');
@@ -91,7 +213,7 @@ export function runApplyCommand(options, cwd) {
         // Documents are addressed by their manifest paths; an operation aimed
         // anywhere else is rejected before anything is touched.
         const workspaceDocuments = new Map(workspace.documents.map((path) => [resolve(cwd, path), path]));
-        const parsed = new Map();
+        const candidates = new Map();
         const counts = {
             addedConcepts: 0,
             addedRelationships: 0,
@@ -112,35 +234,63 @@ export function runApplyCommand(options, cwd) {
                     locate(`Operation ${index} targets "${operation.document}", which is not a document of workspace "${workspace.id}"`),
                 ]);
             }
-            let document = parsed.get(absolute);
-            if (document === undefined) {
-                document = parseDocument(readFileSync(absolute, 'utf8'));
-                parsed.set(absolute, document);
+            let source = candidates.get(absolute);
+            if (source === undefined) {
+                source = readFileSync(absolute, 'utf8');
             }
             if (operation.op === 'add-concept') {
-                appendBlockItem(document, 'concepts', operation.concept);
+                source = appendCollectionItem(source, 'concepts', operation.concept);
                 counts.addedConcepts += 1;
             }
             else if (operation.op === 'add-relationship') {
-                appendBlockItem(document, 'relationships', operation.relationship);
+                source = appendCollectionItem(source, 'relationships', operation.relationship);
                 counts.addedRelationships += 1;
             }
             else {
                 const collection = operation.op === 'update-concept' ? 'concepts' : 'relationships';
-                const payload = operation.op === 'update-concept'
+                const payload = (operation.op === 'update-concept'
                     ? operation.concept
-                    : operation.relationship;
-                const item = findItem(document, collection, payload.id);
-                if (item === undefined) {
+                    : operation.relationship);
+                const scalars = operation.op === 'update-concept'
+                    ? SCALAR_CONCEPT_FIELDS
+                    : SCALAR_RELATIONSHIP_FIELDS;
+                const lists = operation.op === 'update-concept'
+                    ? LIST_CONCEPT_FIELDS
+                    : LIST_RELATIONSHIP_FIELDS;
+                const id = payload.id;
+                const removals = operation.remove ?? [];
+                const contradiction = removals.find((key) => payload[key] !== undefined);
+                if (contradiction !== undefined) {
                     return failed([
-                        locate(`Operation ${index} updates "${payload.id}", which does not exist in ${operation.document}`),
+                        locate(`Operation ${index} both sets and removes "${contradiction}" on "${id}"`),
                     ]);
                 }
-                applyFields(document, item, payload, operation.op === 'update-concept'
-                    ? SCALAR_CONCEPT_FIELDS
-                    : SCALAR_RELATIONSHIP_FIELDS, operation.op === 'update-concept'
-                    ? LIST_CONCEPT_FIELDS
-                    : LIST_RELATIONSHIP_FIELDS);
+                const located = itemMap(source, collection, id);
+                if (located === undefined) {
+                    return failed([
+                        locate(`Operation ${index} updates "${id}", which does not exist in ${operation.document}`),
+                    ]);
+                }
+                for (const key of scalars) {
+                    if (payload[key] === undefined)
+                        continue;
+                    source = setScalarField(source, itemMap(source, collection, id).map, key, payload[key]);
+                }
+                for (const key of lists) {
+                    const additions = payload[key];
+                    if (additions === undefined || additions.length === 0)
+                        continue;
+                    source = appendListField(source, itemMap(source, collection, id).map, key, additions);
+                }
+                for (const key of removals) {
+                    const removed = removeField(source, itemMap(source, collection, id).map, key);
+                    if (removed === undefined) {
+                        return failed([
+                            locate(`Operation ${index} removes "${key}", which is not set on "${id}"`),
+                        ]);
+                    }
+                    source = removed;
+                }
                 if (operation.op === 'update-concept') {
                     counts.updatedConcepts += 1;
                 }
@@ -148,13 +298,10 @@ export function runApplyCommand(options, cwd) {
                     counts.updatedRelationships += 1;
                 }
             }
+            candidates.set(absolute, source);
         }
         // The atomic gate: the whole candidate workspace must compile before a
         // single byte is written; any diagnostic rejects the entire batch.
-        const candidates = new Map([...parsed.entries()].map(([absolute, document]) => [
-            absolute,
-            document.toString({ lineWidth: 0 }),
-        ]));
         const compilation = compileWorkspace([...workspace.profiles, ...workspace.documents].map((path) => {
             const absolute = resolve(cwd, path);
             return {
@@ -167,7 +314,7 @@ export function runApplyCommand(options, cwd) {
         for (const [absolute, source] of candidates) {
             writeFileSync(absolute, source, 'utf8');
         }
-        const touched = [...parsed.keys()]
+        const touched = [...candidates.keys()]
             .map((absolute) => workspaceDocuments.get(absolute))
             .sort();
         if (json) {

package/dist/design-command.js

@@ -56,6 +56,10 @@ const selectStep = (report, subjectFilter) => {
                 ...(subjects.length > 1
                     ? { remainingSubjects: subjects.length - 1 }
                     : {}),
+                // The full roster sharing this question (#116): when one policy
+                // answer covers many subjects, the harness can collect it once
+                // and land one apply batch instead of interviewing N times.
+                openSubjects: subjects.map(({ id }) => id),
             };
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yarramate",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Tool-neutral semantic architecture engine and guided methodology",
   "license": "MIT",
   "repository": {

package/schema/yarramate-design-step.schema.json

@@ -139,6 +139,14 @@
             "remainingSubjects": {
               "type": "integer",
               "minimum": 1
+            },
+            "openSubjects": {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "type": "string",
+                "minLength": 1
+              }
             }
           }
         }

package/schema/yarramate-operations.schema.json

@@ -264,6 +264,22 @@
                   "type": "object"
                 }
               ]
+            },
+            "remove": {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "enum": [
+                  "name",
+                  "description",
+                  "status",
+                  "owner",
+                  "constraints",
+                  "references",
+                  "presentIn",
+                  "attestations"
+                ]
+              }
             }
           }
         },
@@ -294,6 +310,21 @@
                   "type": "object"
                 }
               ]
+            },
+            "remove": {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "enum": [
+                  "name",
+                  "description",
+                  "status",
+                  "mode",
+                  "content",
+                  "references",
+                  "presentIn"
+                ]
+              }
             }
           }
         }

package/skills/yarramate-architecture/SKILL.md

@@ -129,7 +129,11 @@ yarramate design .yarramate/workspace.yaml
    .yarramate/workspace.yaml`), then re-run `design` — the next question is
    recomputed from the model, so the loop is resumable across sessions and
    agents with no handover. Use `--subject <id>` to focus the interview on
-   one element. The interview is complete when `design` says so.
+   one element. When a step reports many `openSubjects` sharing one
+   question (ownership is the classic case), do not interview N times:
+   collect the policy answer once — "who owns what, by area" — and land it
+   across every listed subject as one apply batch. The interview is
+   complete when `design` says so.
 5. Create:
    - an alternatives projection for the decision;
    - a bounded target projection for implementation agents.