yarramate 1.4.1 → 1.6.0

package/dist/workbook.js

@@ -0,0 +1,293 @@
+import { writeXlsx } from './workbook-xlsx.js';
+/**
+ * The model as a workbook an architect can work in (#355).
+ *
+ * The shape is borrowed from a real consulting workbook rather than invented:
+ * identity is columnar and readability is derived. A stable id in column A,
+ * foreign keys inline, and an adjacent `(auto)` column carrying the referenced
+ * subject's NAME so a sheet reads without hunting across tabs. The id is what
+ * round-trips; the `(auto)` column is a convenience and is ignored on import.
+ *
+ * Losslessness does not depend on this file enumerating every predicate
+ * correctly. Well-known predicates become columns because a person needs them
+ * to be columns; **everything else lands in `07 Other Facts` verbatim**, so a
+ * predicate added to the compiler after this was written still survives a
+ * round trip. A mapping that silently dropped what it did not recognise is the
+ * failure this design exists to avoid.
+ */
+export const WORKBOOK_FORMAT = 'yarramate/workbook/v1';
+/** Consumed into a column on `01 Concepts`, in this order. */
+const CONCEPT_COLUMNS = [
+    ['yarramate/concept/kind', 'Kind'],
+    ['yarramate/concept/name', 'Name'],
+    ['yarramate/concept/description', 'Description'],
+    ['yarramate/lifecycle/status', 'Status'],
+    ['yarramate/ownership/owner', 'Owner'],
+    ['yarramate/organisation/folder', 'Folder'],
+];
+/** Consumed into a column on `02 Relationships`, in this order. */
+const RELATIONSHIP_COLUMNS = [
+    ['yarramate/relationship/name', 'Name'],
+    ['yarramate/relationship/description', 'Description'],
+    ['yarramate/access/mode', 'Mode'],
+    ['yarramate/flow/content', 'Content'],
+    ['yarramate/lifecycle/status', 'Status'],
+];
+/**
+ * Consumed into a column on `03 States`.
+ *
+ * `concept/kind` is here as well as on `01 Concepts` because a state IS a
+ * concept: it carries an ordinary kind (`plateau`) alongside its state type
+ * (`baseline`, `transition`, `target`). Omitting it dropped four kind claims
+ * into the overflow sheet, which round-tripped correctly and read as though
+ * the mapping had not recognised them.
+ */
+const STATE_COLUMNS = [
+    ['yarramate/concept/kind', 'Kind'],
+    ['yarramate/state/type', 'State kind'],
+    ['yarramate/concept/name', 'Name'],
+    ['yarramate/concept/description', 'Description'],
+];
+/** Ref-valued predicates that get their own sheet rather than the overflow. */
+const REFERENCE_PREDICATES = new Set([
+    'yarramate/reference/refers-to',
+    'yarramate/lineage/supersedes',
+    'yarramate/lineage/supersedes-respect',
+    'yarramate/identity/distinct-from',
+    'yarramate/constraint/requires',
+    'yarramate/constraint/expects',
+]);
+const ALIAS_PREDICATE = 'yarramate/concept/alias';
+const PRESENT_IN_PREDICATE = 'yarramate/state/present-in';
+const STATE_TYPE_PREDICATE = 'yarramate/state/type';
+const STATE_AFTER_PREDICATE = 'yarramate/state/after';
+const KIND_PREDICATE = 'yarramate/concept/kind';
+const NAME_PREDICATE = 'yarramate/concept/name';
+const valueOf = (claim) => 'value' in claim.object ? claim.object.value : claim.object.ref;
+const isRef = (claim) => 'ref' in claim.object;
+/**
+ * A relationship IS a claim: its `id` is the relationship id, its `subject` is
+ * the source, its `predicate` is the kind and its object refs the target.
+ * Claims ABOUT a relationship carry that id as their own subject.
+ */
+const relationshipClaims = (result) => {
+    const relationshipIds = new Set(result.subjects
+        .filter(({ type }) => type === 'relationship')
+        .map(({ id }) => id));
+    return result.claims.filter((claim) => relationshipIds.has(claim.id));
+};
+export const buildWorkbookSheets = (result, provenance) => {
+    const conceptIds = new Set(result.subjects.filter(({ type }) => type === 'concept').map(({ id }) => id));
+    const relationshipIds = new Set(result.subjects
+        .filter(({ type }) => type === 'relationship')
+        .map(({ id }) => id));
+    const bySubject = new Map();
+    for (const claim of result.claims) {
+        const held = bySubject.get(claim.subject);
+        if (held === undefined)
+            bySubject.set(claim.subject, [claim]);
+        else
+            held.push(claim);
+    }
+    const nameOf = (id) => {
+        const claim = bySubject
+            .get(id)
+            ?.find(({ predicate }) => predicate === NAME_PREDICATE);
+        return claim === undefined ? '' : valueOf(claim);
+    };
+    const first = (id, predicate) => {
+        const claim = bySubject.get(id)?.find((held) => held.predicate === predicate);
+        return claim === undefined ? '' : valueOf(claim);
+    };
+    /**
+     * The document a subject is declared in, as a PATH.
+     *
+     * Carried because an `apply` operation targets a document path, so without
+     * it a workbook can say what a subject is and not where it lives, and
+     * nothing can be written back. Every claim knows its own source, so this is
+     * recovered rather than guessed.
+     */
+    const documentOf = (id) => bySubject.get(id)?.[0]?.source.path ?? '';
+    const documentOfClaim = (claim) => claim.source.path;
+    // A state is an ordinary concept carrying state predicates, so it is lifted
+    // onto its own sheet rather than being a second kind of thing.
+    const stateIds = new Set([...conceptIds].filter((id) => bySubject
+        .get(id)
+        ?.some(({ predicate }) => predicate === STATE_TYPE_PREDICATE) === true));
+    /** Every claim a column or a named sheet has already carried. */
+    const consumed = new Set();
+    const consume = (id, predicate) => {
+        const claim = bySubject.get(id)?.find((held) => held.predicate === predicate);
+        if (claim !== undefined)
+            consumed.add(claim.id);
+    };
+    const conceptRows = [
+        ['Concept ID', ...CONCEPT_COLUMNS.map(([, label]) => label), 'Document'],
+    ];
+    for (const id of [...conceptIds].filter((one) => !stateIds.has(one)).sort()) {
+        for (const [predicate] of CONCEPT_COLUMNS)
+            consume(id, predicate);
+        conceptRows.push([
+            id,
+            ...CONCEPT_COLUMNS.map(([predicate]) => first(id, predicate)),
+            documentOf(id),
+        ]);
+    }
+    const relationshipRows = [
+        [
+            'Relationship ID',
+            'Kind',
+            'From',
+            '↳ From name (auto)',
+            'To',
+            '↳ To name (auto)',
+            ...RELATIONSHIP_COLUMNS.map(([, label]) => label),
+            'Document',
+        ],
+    ];
+    for (const claim of [...relationshipClaims(result)].sort((left, right) => left.id < right.id ? -1 : left.id > right.id ? 1 : 0)) {
+        consumed.add(claim.id);
+        for (const [predicate] of RELATIONSHIP_COLUMNS)
+            consume(claim.id, predicate);
+        const target = 'ref' in claim.object ? claim.object.ref : '';
+        relationshipRows.push([
+            claim.id,
+            claim.predicate,
+            claim.subject,
+            nameOf(claim.subject),
+            target,
+            nameOf(target),
+            ...RELATIONSHIP_COLUMNS.map(([predicate]) => first(claim.id, predicate)),
+            documentOfClaim(claim),
+        ]);
+    }
+    const stateRows = [
+        [
+            'State ID',
+            ...STATE_COLUMNS.map(([, label]) => label),
+            'After',
+            '↳ After name (auto)',
+            'Document',
+        ],
+    ];
+    for (const id of [...stateIds].sort()) {
+        for (const [predicate] of STATE_COLUMNS)
+            consume(id, predicate);
+        consume(id, STATE_AFTER_PREDICATE);
+        const after = first(id, STATE_AFTER_PREDICATE);
+        stateRows.push([
+            id,
+            ...STATE_COLUMNS.map(([predicate]) => first(id, predicate)),
+            after,
+            nameOf(after),
+            documentOf(id),
+        ]);
+    }
+    const presentInRows = [
+        ['Subject ID', '↳ Subject name (auto)', 'State ID', '↳ State name (auto)'],
+    ];
+    const referenceRows = [
+        ['Subject ID', '↳ Subject name (auto)', 'Predicate', 'Target ID', '↳ Target name (auto)'],
+    ];
+    const aliasRows = [['Subject ID', '↳ Subject name (auto)', 'Also known as']];
+    const otherRows = [['Subject ID', 'Predicate', 'Value', 'Target ID']];
+    for (const claim of result.claims) {
+        if (consumed.has(claim.id))
+            continue;
+        if (relationshipIds.has(claim.id))
+            continue;
+        if (claim.predicate === PRESENT_IN_PREDICATE) {
+            const state = valueOf(claim);
+            presentInRows.push([claim.subject, nameOf(claim.subject), state, nameOf(state)]);
+            continue;
+        }
+        if (claim.predicate === ALIAS_PREDICATE) {
+            aliasRows.push([claim.subject, nameOf(claim.subject), valueOf(claim)]);
+            continue;
+        }
+        if (REFERENCE_PREDICATES.has(claim.predicate)) {
+            const target = valueOf(claim);
+            referenceRows.push([
+                claim.subject,
+                nameOf(claim.subject),
+                claim.predicate,
+                target,
+                nameOf(target),
+            ]);
+            continue;
+        }
+        // The overflow, and the reason a round trip stays lossless when the
+        // compiler grows a predicate this file has never heard of.
+        otherRows.push([
+            claim.subject,
+            claim.predicate,
+            isRef(claim) ? '' : valueOf(claim),
+            isRef(claim) ? valueOf(claim) : '',
+        ]);
+    }
+    const readMe = [
+        ['YarraMate workbook'],
+        [],
+        ['Workspace', provenance.workspace],
+        ['Projection', result.projection],
+        ['Built by', `yarramate ${provenance.yarramateVersion}`],
+        [],
+        ['How to use this'],
+        ['1.', 'Edit the numbered sheets. Column A is the identity of the row and is what the model is keyed on.'],
+        ['2.', 'A column marked (auto) is derived for readability. Edits to it are ignored.'],
+        ['3.', 'Add a row with a new ID to add a subject. Kind and Status are dropdowns, and Document says which file it belongs to.'],
+        ['4.', 'Deleting a row does NOT delete anything. Removals are reported, never applied.'],
+        ['5.', 'Send the file back and import it. Your edits are merged; only a field changed on both sides is refused.'],
+        [],
+        ['Sheets beginning ~ are machinery. Do not edit them.'],
+    ];
+    const listColumns = [
+        ['Concept kind', ...provenance.conceptKinds],
+        ['Relationship kind', ...provenance.relationshipKinds],
+        ['Status', ...provenance.statuses],
+    ];
+    const listHeight = Math.max(...listColumns.map((column) => column.length));
+    const listRows = [];
+    for (let row = 0; row < listHeight; row += 1) {
+        listRows.push(listColumns.map((column) => column[row] ?? ''));
+    }
+    const metaRows = [
+        ['Key', 'Value'],
+        ['Format', WORKBOOK_FORMAT],
+        ['Workspace', provenance.workspace],
+        ['Projection', result.projection],
+        ['YarraMate version', provenance.yarramateVersion],
+        ...Object.entries(provenance.sourceDigests)
+            .sort(([left], [right]) => (left < right ? -1 : 1))
+            .map(([path, digest]) => [`Digest ${path}`, digest]),
+    ];
+    const working = [
+        { name: '00 Read Me', rows: readMe },
+        { name: '01 Concepts', rows: conceptRows, frozenRows: 1 },
+        { name: '02 Relationships', rows: relationshipRows, frozenRows: 1 },
+        { name: '03 States', rows: stateRows, frozenRows: 1 },
+        { name: '04 Present In', rows: presentInRows, frozenRows: 1 },
+        { name: '05 References', rows: referenceRows, frozenRows: 1 },
+        { name: '06 Aliases', rows: aliasRows, frozenRows: 1 },
+        { name: '07 Other Facts', rows: otherRows, frozenRows: 1 },
+    ];
+    // The merge ancestor. Never edited, never updated: it records what the model
+    // looked like when this workbook was made, so import can tell an FDE's edit
+    // from a change the repository made underneath since. Each row carries its
+    // sheet name so one sheet can hold them all.
+    const baselineRows = [['Sheet', 'Cells...']];
+    for (const sheet of working) {
+        if (sheet.name === '00 Read Me')
+            continue;
+        for (const row of sheet.rows)
+            baselineRows.push([sheet.name, ...row]);
+    }
+    return [
+        ...working,
+        { name: '~Lists', state: 'hidden', rows: listRows },
+        { name: '~Meta', state: 'hidden', rows: metaRows },
+        { name: '~Baseline', state: 'veryHidden', rows: baselineRows },
+    ];
+};
+/** The workbook, as bytes. Synchronous and deterministic. */
+export const workbookFrom = (result, provenance) => writeXlsx(buildWorkbookSheets(result, provenance));

package/docs/CONSUMING-YARRAMATE.md

@@ -408,6 +408,70 @@ socket/session host.
 
 [...]
 
+## The model as an Excel workbook
+
+`yarramate export xlsx <projection.yaml> <workspace.yaml> --out <file>` writes
+a workbook an architect or FDE can work in, and `yarramate/workbook` publishes
+the writer for a host that has no Node:
+
+```ts
+import { workbookFrom } from 'yarramate/workbook'
+
+const bytes = workbookFrom(projectionResult, {
+  workspace: 'acme',
+  yarramateVersion: '1.5.0',
+  sourceDigests,
+  conceptKinds,
+  relationshipKinds,
+  statuses: ['planned', 'current', 'retired'],
+})
+```
+
+Synchronous, dependency-free and deterministic: the same input always produces
+the same bytes. The import graph is held free of Node builtins and of the
+compiler at runtime, so it fits a Cloudflare Worker or a Durable Object. A
+caller hands over an already-evaluated `ProjectionResult`, which is what keeps
+schema validation out of that graph.
+
+**It takes a projection**, so it inherits every facet a projection query has.
+That is how a caller chooses which *version* to export: a query naming
+`states` produces a workbook of that architecture state, with no separate
+flag.
+
+```yaml
+query:
+  states:
+    - target-state
+```
+
+**Reading the sheets.** Column A is always the id and is what the model is
+keyed on. A column headed `↳ … (auto)` is derived for readability and is
+ignored on the way back. Kind and status columns are drawn from the compiled
+profile, so they carry the vocabulary that workspace actually has.
+
+Sheets beginning `~` are machinery. `~Meta` records the format, the versions
+and the source digests. `~Baseline` is a hidden copy of the working rows
+exactly as exported, and exists so a later import can tell an author's edit
+from a change the repository made underneath. Neither is edited.
+
+Anything the mapping does not recognise is carried verbatim on `07 Other
+Facts` rather than dropped, so a workbook stays lossless across a compiler
+that grows new predicates.
+
+**Reading one back.** `yarramate import xlsx <workbook.xlsx> <workspace.yaml>`
+merges an edited workbook into the model. An unedited round trip changes
+nothing, byte for byte.
+
+Edits land as `yarramate/operations/v1` through `apply`, so untouched YAML
+keeps its comments, key order and formatting, and the import passes the same
+atomic gate every other write does.
+
+It is a three-way merge. `~Baseline` is the ancestor, so an edit the workspace
+did not touch merges even if the repository moved on; only a field changed on
+**both** sides is refused, and a refusal writes nothing anywhere. A missing row
+is reported and never treated as a deletion, and a new row needs its `Document`
+column filled in.
+
 ## MCP server for agent harnesses
 
 Harnesses that load MCP servers can connect the bundled read-only adapter:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yarramate",
-  "version": "1.4.1",
+  "version": "1.6.0",
   "description": "Tool-neutral semantic architecture engine and guided methodology",
   "license": "MIT",
   "repository": {
@@ -58,6 +58,10 @@
       "types": "./dist/interrogation-entry.d.ts",
       "import": "./dist/interrogation-entry.js"
     },
+    "./workbook": {
+      "types": "./dist/workbook-entry.d.ts",
+      "import": "./dist/workbook-entry.js"
+    },
     "./visual-app": {
       "types": "./dist/visual-app-lib/editor.d.ts",
       "import": "./dist/visual-app-lib/editor.js"