yarramate 1.5.0 → 1.7.0

package/dist/workbook.js

@@ -0,0 +1,308 @@
+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.'],
+        [],
+        [],
+        ['What this holds, and what it does not'],
+        [
+            '',
+            `A projection is a QUERY, so this workbook is the slice it names: ${conceptRows.length - 1} concepts and ${relationshipRows.length - 1} relationships.`,
+        ],
+        [
+            '',
+            'Everything the model knows about a subject that IS here is here, including anything these columns do not model, on 07 Other Facts.',
+        ],
+        [
+            '',
+            'A subject outside the slice has no row, and importing this file cannot change it. A narrow workbook is safe against a wide model.',
+        ],
+        [],
+        ['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/dist/workspace.d.ts

@@ -7,6 +7,7 @@ export interface WorkspaceManifest {
     readonly projections: readonly string[];
     readonly adapterMappings: readonly string[];
     readonly patterns?: readonly string[];
+    readonly questions?: readonly string[];
     readonly evidence?: readonly string[];
     readonly contracts?: readonly string[];
 }
@@ -17,6 +18,20 @@ export interface ResolvedWorkspace {
     readonly projections: readonly string[];
     readonly adapterMappings: readonly string[];
     readonly patterns: readonly string[];
+    /**
+     * Question catalogues the workspace itself carries (#345, ADR 0129).
+     * ADDITIVE to the shipped catalogue: `--catalogue` replaces the base, this
+     * adds to it, which is what lets a consultant author a question mid
+     * engagement without a product release.
+     *
+     * OPTIONAL in the type although `loadWorkspaceManifest` always populates it,
+     * and that is deliberate. `ResolvedWorkspace` is published, and adding
+     * `patterns` to it as a required field broke a consumer's production module:
+     * a required field is free for readers and a break for CONSTRUCTORS. Six
+     * fixtures in this repository construct one, which is the same signal from
+     * inside. Read it as `workspace.questions ?? []`.
+     */
+    readonly questions?: readonly string[];
     readonly evidence: readonly string[];
     readonly contracts: readonly string[];
 }

package/dist/workspace.js

@@ -107,6 +107,7 @@ export function loadWorkspaceManifest(source, cwd) {
         projections: expand('projections', 'projection', value.projections),
         adapterMappings: expand('adapterMappings', 'adapter mapping', value.adapterMappings),
         patterns: expand('patterns', 'pattern', value.patterns ?? []),
+        questions: expand('questions', 'question catalogue', value.questions ?? []),
         evidence: expand('evidence', 'evidence', value.evidence ?? []),
         contracts: expand('contracts', 'Core contract', value.contracts ?? []),
     };

package/docs/CONSUMING-YARRAMATE.md

@@ -408,6 +408,133 @@ 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
+```
+
+**Which makes a workbook a SLICE, and it is worth being plain about that.** An
+omitted facet imposes no constraint, so `query: {}` exports the whole model,
+and every facet you name narrows it. For a subject the query selected, nothing
+is dropped: the projection filters claims by subject membership rather than by
+predicate, so every fact about an included subject arrives, and `07 Other
+Facts` catches whatever the named columns do not model. For a subject it did
+not select, there is simply no row, and a missing row is never a deletion, so
+**a narrow workbook cannot damage a wide model on the way back in**. The
+`00 Read Me` sheet says all of this and reports the counts the slice actually
+has, because an FDE handed a filtered workbook with no note will read it as
+the model.
+
+**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.
+
+**On a host with no Node**, `yarramate/workbook/import` publishes the same
+three steps the CLI runs, so ingesting a workbook is not CLI-only:
+
+```ts
+import {
+  readWorkbook,
+  baselineSheets,
+  mergeWorkbook,
+  operationsFrom,
+  operationsDocument,
+} from 'yarramate/workbook/import'
+
+const read = await readWorkbook(bytes)
+if (!read.ok) return refuse(read.reason)
+
+const ancestor = read.sheets.get('~Baseline')
+if (ancestor === undefined) return refuse('not produced by yarramate export xlsx')
+
+const report = mergeWorkbook(
+  read.sheets,
+  baselineSheets(ancestor),
+  buildWorkbookSheets(currentResult, provenance),
+)
+if (report.conflicts.length > 0) return refuse(report.conflicts)
+
+const { operations, refusals } = operationsFrom(report, read.sheets)
+await apply(operationsDocument(operations))
+```
+
+`readWorkbook` is **async** while the writer is synchronous, and deliberately
+so: a workbook this package wrote has stored entries and inline strings, but
+one a person saved from Excel comes back deflated and shared-stringed, and
+inflation is only offered as a stream (`DecompressionStream('deflate-raw')`,
+present on Workers, in browsers and in Node 18+). Keeping the writer
+synchronous is what stops it infecting a synchronous store on the host side.
+
+It is a **separate subpath** from `yarramate/workbook` on purpose. The package
+declares no `sideEffects` field, so a bundler must assume every module might
+have one and cannot shake an unused re-export away; a host that only generates
+workbooks would otherwise carry the reader, the merge and the operations
+emitter it never calls. `test/export-purity.test.ts` holds the two entries
+disjoint as well as pure.
+
+The host keeps three jobs: reading the bytes, evaluating the projection that
+says what the model holds **now** (the third argument to `mergeWorkbook`, which
+is what measures repo drift in the same terms the author edited in), and
+applying the operations. Refusal wording is the host's too. The `Conflict`
+values name the sheet, row, column, what the author wrote, what the workspace
+now holds and their common ancestor, which reads like a merge tool rather than
+like something you hand a consultant.
+
 ## 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.5.0",
+  "version": "1.7.0",
   "description": "Tool-neutral semantic architecture engine and guided methodology",
   "license": "MIT",
   "repository": {
@@ -58,6 +58,14 @@
       "types": "./dist/interrogation-entry.d.ts",
       "import": "./dist/interrogation-entry.js"
     },
+    "./workbook": {
+      "types": "./dist/workbook-entry.d.ts",
+      "import": "./dist/workbook-entry.js"
+    },
+    "./workbook/import": {
+      "types": "./dist/workbook-import-entry.d.ts",
+      "import": "./dist/workbook-import-entry.js"
+    },
     "./visual-app": {
       "types": "./dist/visual-app-lib/editor.d.ts",
       "import": "./dist/visual-app-lib/editor.js"

package/schema/yarramate-interrogation-report.schema.json

@@ -24,6 +24,15 @@
       "type": "string",
       "minLength": 1
     },
+    "catalogues": {
+      "description": "Every catalogue that contributed, as id@version, base first (#345, ADR 0129). Present only when more than one did. OPTIONAL, and `catalogue` keeps naming the base with its existing value shape, because turning that field into an array would break every reader: an optional additive field is free for readers and does not force constructors. Question ids in this report are qualified as catalogue#question and carry NO version, so a catalogue version bump strands no stored judgment keyed on them; the versions live here instead.",
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
     "semantics": {
       "type": "string",
       "minLength": 1,

package/schema/yarramate-question-catalogue.schema.json

@@ -44,9 +44,9 @@
       }
     },
     "waves": {
-      "description": "Ordered interview phases. Array order is interview order. The wave taxonomy is catalogue opinion, not engine semantics.",
+      "description": "Ordered interview phases. Array order is interview order. The wave taxonomy is catalogue opinion, not engine semantics. MAY BE EMPTY (#345, ADR 0129): a catalogue that only contributes questions to waves ANOTHER catalogue declared is the ordinary shape of a project catalogue, and requiring a wave here would force it to declare one it does not want - which is refused as a duplicate the moment two catalogues do it. Evaluated alone, a catalogue with no waves and a question naming one is YM911, correctly: nothing declares it.",
       "type": "array",
-      "minItems": 1,
+      "minItems": 0,
       "items": {
         "type": "object",
         "additionalProperties": false,
@@ -112,7 +112,6 @@
       "description": "Which subjects a subject-scope question applies to. Field vocabulary mirrors the projection query selector (ADR 0017).",
       "type": "object",
       "additionalProperties": false,
-      
       "properties": {
         "kinds": {
           "type": "array",

package/schema/yarramate-workspace.schema.json

@@ -32,6 +32,10 @@
       "description": "yarramate/pattern/v1 documents: the shape a concept kind promises, and the wiring the compiler mints between an instance and the parts it binds (ADR 0123). Structure, where profiles declare vocabulary. Optional, like evidence and contracts.",
       "$ref": "#/$defs/patterns"
     },
+    "questions": {
+      "description": "yarramate/question-catalogue/v1 documents the WORKSPACE carries: questions true of this engagement and nowhere else (#345, ADR 0129). ADDITIVE to the shipped catalogue rather than replacing it, which is what --catalogue and MountOptions.catalogue do. Question ids are qualified as catalogue#question on the way out, so two catalogues may carry the same local id. A wave is declared exactly once across the resolved set, and any catalogue may contribute questions to a wave it did not declare. Optional, like patterns, evidence and contracts.",
+      "$ref": "#/$defs/patterns"
+    },
     "adapterMappings": {
       "$ref": "#/$defs/patterns"
     },