yarramate 1.5.0 → 1.7.0

package/dist/visual-app-lib/types/adapters/visual/workspace-model.d.ts

@@ -57,10 +57,20 @@ export interface DismissedQuestion {
 export declare const interrogationOverlayOf: (compiled: {
     readonly graph: SemanticGraph;
     readonly profileContext: ResolvedProfileContext;
-}, catalogue: {
+}, 
+/**
+ * The catalogue, or the composed SET a workspace carries (#345, ADR 0129).
+ * A set rather than one document so the pane asks the same interview the
+ * CLI does over the same workspace: an editor showing fewer questions than
+ * `design` does over the same files is a disagreement with no symptom.
+ */
+catalogue: {
     readonly path: string;
     readonly source: string;
-}, 
+} | readonly {
+    readonly path: string;
+    readonly source: string;
+}[], 
 /**
  * What the host has already dealt with (#328). Evaluation is unchanged and
  * the model is untouched: this decides only what the pane draws, because a
@@ -83,7 +93,10 @@ export declare const renderedWorkspaceOf: (compiled: {
 }, views: readonly VisualViewSummary[], metadata: Omit<VisualRenderedModel, "graph" | "vocabulary" | "interrogation">, catalogue?: {
     readonly path: string;
     readonly source: string;
-}, dismissed?: readonly DismissedQuestion[]) => {
+} | readonly {
+    readonly path: string;
+    readonly source: string;
+}[], dismissed?: readonly DismissedQuestion[]) => {
     readonly model: VisualRenderedModel;
     readonly views: readonly VisualViewSummary[];
 };

package/dist/visual-app-lib/types/interrogate-command.d.ts

@@ -188,14 +188,29 @@ export interface InterrogationSummary {
 export interface InterrogationReport {
     readonly format: 'yarramate/interrogation-report/v1';
     readonly workspace: string;
+    /** The BASE catalogue, `id@version`. Unchanged in shape by composition. */
     readonly catalogue: string;
+    /**
+     * Every contributing catalogue as `id@version`, base first, when more than
+     * one contributed (#345, ADR 0129). Optional so that adding it breaks no
+     * constructor, and `catalogue` keeps its value shape so it breaks no reader.
+     */
+    readonly catalogues?: readonly string[];
     /** {@link INTERROGATION_SEMANTICS_VERSION} at the time of evaluation. */
     readonly semantics: string;
     readonly summary: InterrogationSummary;
     readonly waves: readonly ReportWave[];
 }
 export declare const renderQuestion: (template: string, subjectId: string, subjectName: string | undefined, counterparts?: readonly string[]) => string;
-export declare function evaluateCatalogue(catalogue: QuestionCatalogue, graph: SemanticGraph, profileContext?: ResolvedProfileContext, evidence?: readonly CatalogueEvidenceObservation[]): Omit<InterrogationReport, 'workspace'>;
+export declare function evaluateCatalogue(catalogue: QuestionCatalogue, graph: SemanticGraph, profileContext?: ResolvedProfileContext, evidence?: readonly CatalogueEvidenceObservation[], 
+/**
+ * Contributing catalogues, from {@link composeCatalogues}. Composition
+ * happens BEFORE evaluation and hands this function an ordinary catalogue,
+ * so the only thing evaluation learns about composition is what to name in
+ * the report. A fifth optional parameter rather than an options object,
+ * because this signature is published and a consumer already calls it.
+ */
+catalogues?: readonly string[]): Omit<InterrogationReport, 'workspace'>;
 export type CatalogueLoadResult = {
     readonly ok: true;
     readonly catalogue: QuestionCatalogue;
@@ -203,5 +218,71 @@ export type CatalogueLoadResult = {
     readonly ok: false;
     readonly diagnostics: readonly Diagnostic[];
 };
+/**
+ * A catalogue is qualified on the way OUT, never in what an author writes.
+ *
+ * The authored schema keeps ids local (`^[a-z][a-z0-9-]*$`) and that does not
+ * change; a consultant writes `regulator-signoff`, not
+ * `consulting#regulator-signoff`. The engine qualifies when it composes, which
+ * is the only moment two catalogues can be confused for each other.
+ *
+ * NO VERSION, and that is the decision rather than an omission (ADR 0129).
+ * `core-enrichment` went 1.0 to 1.3 in a single day renaming nothing; a
+ * versioned identity would have stranded every stored dismissal in every
+ * adopter's database three times that day, for changes that removed no
+ * question. Versioned identity is safe for things that are AUTHORED - a
+ * document keeps naming the version it was written against and an author
+ * updates it deliberately - and unsafe for things that are STORED, because a
+ * row in someone's database has no author to update it.
+ */
+export declare const qualifiedQuestionId: (catalogueId: string, questionId: string) => string;
+export interface ComposedCatalogue {
+    /**
+     * The composed catalogue, ready for `evaluateCatalogue`. Structurally a
+     * `QuestionCatalogue`, but its question ids are QUALIFIED, so it is a
+     * composition result rather than something an author could have written and
+     * must never be validated against the authored schema again.
+     */
+    readonly catalogue: QuestionCatalogue;
+    /** Every contributing catalogue as `id@version`, base first. */
+    readonly catalogues: readonly string[];
+}
+export type CatalogueCompositionResult = {
+    readonly ok: true;
+    readonly composed: ComposedCatalogue;
+} | {
+    readonly ok: false;
+    readonly diagnostics: readonly Diagnostic[];
+};
+/**
+ * Compose a base catalogue with the ones a workspace carries (#345, ADR 0129).
+ *
+ * ADDITIVE. `--catalogue` and `MountOptions.catalogue` replace the base; this
+ * adds to it, which is what lets a consultant author a question at any point
+ * in an engagement with no product release.
+ *
+ * A WAVE IS DECLARED EXACTLY ONCE across the resolved set, and any catalogue
+ * may contribute questions to a wave it did not declare. That one rule settles
+ * three questions composition would otherwise raise. Wave identity: a project
+ * catalogue joins a declared wave rather than colliding with it. Ordering:
+ * only a declaration places a wave, so the base's order is untouched and new
+ * waves append. And the `opensWhen` precedence ADR 0125 made load-bearing does
+ * not arise at all, because there is only ever one declarer to ask.
+ *
+ * QUALIFICATION IS A PROPERTY OF COMPOSITION, NOT OF EVALUATION. A caller
+ * that hands `evaluateCatalogue` a catalogue directly still gets local ids,
+ * exactly as before this existed. Route through here even for ONE catalogue -
+ * which is what every CLI verb does - and ids are qualified from the start, so
+ * they do not change later when a workspace first carries a question of its
+ * own. That transition is the one thing an adopter keying stored judgments on
+ * a question id must not experience, and composing unconditionally is how it
+ * is avoided.
+ *
+ * ID COLLISIONS DISSOLVE rather than being resolved. Two catalogues may both
+ * carry `outcome-missing`; qualified, they are two different questions. There
+ * is no merge rule, no last-wins and no refusal, because there is nothing to
+ * merge.
+ */
+export declare function composeCatalogues(sources: readonly WorkspaceSource[], profileContext?: ResolvedProfileContext): CatalogueCompositionResult;
 export declare function loadQuestionCatalogue(catalogueSource: WorkspaceSource, profileContext?: ResolvedProfileContext): CatalogueLoadResult;
 export declare function renderInterrogationReport(report: InterrogationReport): string;

package/dist/visual-app-lib/types/projection.d.ts

@@ -108,6 +108,53 @@ export interface ProjectionExclusion {
     readonly id: string;
     readonly facet: ConceptFacet;
 }
+/** A query facet naming something the model does not have. */
+export interface UnmatchedSelector {
+    readonly facet: string;
+    readonly value: string;
+    /** The closest name the facet does offer, when one is close enough to be a likely typo. */
+    readonly nearest?: string;
+}
+/**
+ * Every value in a projection query that names nothing.
+ *
+ * A projection is a DOCUMENT, and a query holds references the same way a
+ * relationship does. YarraMate refuses a relationship pointing at a concept
+ * that does not exist; it did not refuse a query naming a state that does not
+ * exist, and the symptom is silent. `states: [target-stat]` selects no state,
+ * which selects no subject, which exports a clean empty artifact with exit 0.
+ * Someone hands that to a client.
+ *
+ * Checked at `check`, not at `export`, because the typo is in a file rather
+ * than in an invocation: CI catches it, and every verb over the same
+ * projection inherits the guard instead of each growing its own.
+ *
+ * ONLY FACETS WITH A CLOSED NAMESPACE ARE CHECKED. `statuses` and
+ * `excludeStatuses` are schema enums, refused upstream before this runs.
+ * Everything else names something: `owners` and `constraints` are REFS to
+ * concepts, which the compiler itself proves by refusing an unresolved owner
+ * with YM304, so their namespace is the subject list like `subjects`.
+ *
+ * Each namespace is derived the way the FILTER derives it, so the check cannot
+ * drift from what it guards: `documents` reads the same provenance the
+ * `documents` facet compares against, and `states` is the same
+ * `yarramate/state/type` scan `conceptSelector` runs.
+ *
+ * A kind whose profile is not loaded is DORMANT rather than wrong, the same
+ * distinction #351 drew for question catalogues, so the kind facets are
+ * checked only when a profile context is present.
+ *
+ * An empty RESULT is not reported here and must not be. A query whose every
+ * name resolves and which selects nothing is a real answer to a real question:
+ * a target state nobody has populated yet is empty, correctly.
+ */
+export declare function unmatchedSelectors(graph: SemanticGraph, projection: ProjectionDefinition, profileContext?: ResolvedProfileContext): readonly UnmatchedSelector[];
+/**
+ * {@link unmatchedSelectors} as diagnostics, built HERE rather than at each
+ * caller so `check`, and anything that adopts this later, refuse in identical
+ * words with an identical code.
+ */
+export declare function projectionReferenceDiagnostics(source: WorkspaceSource, projection: ProjectionDefinition, graph: SemanticGraph, profileContext?: ResolvedProfileContext): readonly Diagnostic[];
 /**
  * Every concept a query leaves out, and the facet that left it out.
  *

package/dist/visual-app-lib/types/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/workbook-entry.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `yarramate/workbook` — the workbook writer, for a host that has no Node.
+ *
+ * ApertureX generates these inside a Cloudflare Worker (#355), so this entry
+ * carries the same guarantee `./interrogation` does and is held to it by
+ * `test/export-purity.test.ts`: no Node builtins, no `ws`, no session server,
+ * and no RUNTIME import of the compiler, whose Ajv and YAML weight would
+ * otherwise land in a Durable Object that only wants to write a spreadsheet.
+ * The compiler is reached for types alone.
+ *
+ * A caller hands over an already-evaluated `ProjectionResult` — plain data —
+ * and gets bytes back. Evaluating the projection is the caller's business,
+ * which is what keeps schema validation out of this import graph.
+ */
+export { workbookFrom, buildWorkbookSheets, WORKBOOK_FORMAT, type WorkbookProvenance, } from './workbook.js';
+export { writeXlsx, columnName, escapeXml, sheetNameIsLegal, type WorkbookSheet, type SheetState, } from './workbook-xlsx.js';

package/dist/workbook-entry.js

@@ -0,0 +1,16 @@
+/**
+ * `yarramate/workbook` — the workbook writer, for a host that has no Node.
+ *
+ * ApertureX generates these inside a Cloudflare Worker (#355), so this entry
+ * carries the same guarantee `./interrogation` does and is held to it by
+ * `test/export-purity.test.ts`: no Node builtins, no `ws`, no session server,
+ * and no RUNTIME import of the compiler, whose Ajv and YAML weight would
+ * otherwise land in a Durable Object that only wants to write a spreadsheet.
+ * The compiler is reached for types alone.
+ *
+ * A caller hands over an already-evaluated `ProjectionResult` — plain data —
+ * and gets bytes back. Evaluating the projection is the caller's business,
+ * which is what keeps schema validation out of this import graph.
+ */
+export { workbookFrom, buildWorkbookSheets, WORKBOOK_FORMAT, } from './workbook.js';
+export { writeXlsx, columnName, escapeXml, sheetNameIsLegal, } from './workbook-xlsx.js';

package/dist/workbook-import-entry.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `yarramate/workbook/import` — reading an edited workbook back, for a host
+ * that has no Node.
+ *
+ * A SEPARATE subpath from `yarramate/workbook` rather than more exports on it,
+ * because the package declares no `sideEffects` field and a bundler must
+ * therefore assume every module might have one. A Worker that only GENERATES
+ * workbooks would otherwise carry the reader, the merge and the operations
+ * emitter it never calls, and small bundles are the reason the xlsx container
+ * is hand-written in the first place (#355).
+ *
+ * Held to the same bar as `./workbook` and `./interrogation` by
+ * `test/export-purity.test.ts`: no Node builtins, no `ws`, no session server,
+ * no runtime import of the compiler. `workbook-read.ts` imports nothing at
+ * all; inflation uses `DecompressionStream('deflate-raw')`, which Workers,
+ * browsers and Node 18+ all have.
+ *
+ * The reader is ASYNC and the writer is not, deliberately. 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.
+ *
+ * What a host still owns: reading the bytes, evaluating the projection that
+ * says what the workbook SHOULD hold now, and applying the operations. This
+ * entry turns bytes into sheets, sheets into a merge report, and a merge
+ * report into `yarramate/operations/v1`.
+ */
+export { readWorkbook, unzipEntries, columnIndexOf, decodeXmlText, type WorkbookRead, type ZipReadFailure, } from './workbook-read.js';
+export { mergeWorkbook, mergeSheet, keySheet, baselineSheets, isDerivedColumn, type KeyedSheet, type CellChange, type Conflict, type MergeReport, } from './workbook-merge.js';
+export { operationsFrom, operationsDocument, type OperationsResult, } from './workbook-operations.js';

package/dist/workbook-import-entry.js

@@ -0,0 +1,30 @@
+/**
+ * `yarramate/workbook/import` — reading an edited workbook back, for a host
+ * that has no Node.
+ *
+ * A SEPARATE subpath from `yarramate/workbook` rather than more exports on it,
+ * because the package declares no `sideEffects` field and a bundler must
+ * therefore assume every module might have one. A Worker that only GENERATES
+ * workbooks would otherwise carry the reader, the merge and the operations
+ * emitter it never calls, and small bundles are the reason the xlsx container
+ * is hand-written in the first place (#355).
+ *
+ * Held to the same bar as `./workbook` and `./interrogation` by
+ * `test/export-purity.test.ts`: no Node builtins, no `ws`, no session server,
+ * no runtime import of the compiler. `workbook-read.ts` imports nothing at
+ * all; inflation uses `DecompressionStream('deflate-raw')`, which Workers,
+ * browsers and Node 18+ all have.
+ *
+ * The reader is ASYNC and the writer is not, deliberately. 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.
+ *
+ * What a host still owns: reading the bytes, evaluating the projection that
+ * says what the workbook SHOULD hold now, and applying the operations. This
+ * entry turns bytes into sheets, sheets into a merge report, and a merge
+ * report into `yarramate/operations/v1`.
+ */
+export { readWorkbook, unzipEntries, columnIndexOf, decodeXmlText, } from './workbook-read.js';
+export { mergeWorkbook, mergeSheet, keySheet, baselineSheets, isDerivedColumn, } from './workbook-merge.js';
+export { operationsFrom, operationsDocument, } from './workbook-operations.js';

package/dist/workbook-merge.d.ts

@@ -0,0 +1,77 @@
+import type { WorkbookSheet } from './workbook-xlsx.js';
+/**
+ * Turning an edited workbook back into operations (#355, ADR 0127).
+ *
+ * The workbook carries its own ancestor. `~Baseline` is a copy of the working
+ * rows exactly as exported, never edited and never updated, and it is what
+ * makes this a THREE-way merge rather than an overwrite: without it, "this
+ * cell differs from the model" cannot distinguish *the author changed it* from
+ * *the repository moved underneath since the workbook was made*, and the
+ * second is silently clobbered.
+ *
+ * So the comparison is run twice:
+ *
+ *   working vs baseline  ->  what the author did
+ *   current vs baseline  ->  what the repository did since
+ *
+ * A cell both changed is a conflict and is refused, naming the field and both
+ * values. Everything else merges. Nothing is written for a conflict, because
+ * `apply` is atomic and a half-applied workbook is worse than a refused one.
+ */
+/** A sheet reduced to rows keyed by the id in column A. */
+export interface KeyedSheet {
+    readonly header: readonly string[];
+    readonly rows: ReadonlyMap<string, readonly string[]>;
+}
+export interface CellChange {
+    readonly sheet: string;
+    readonly id: string;
+    readonly column: string;
+    readonly from: string;
+    readonly to: string;
+}
+export interface Conflict extends CellChange {
+    /** What the repository moved the same field to since the export. */
+    readonly theirs: string;
+}
+export interface MergeReport {
+    readonly changes: readonly CellChange[];
+    readonly added: readonly {
+        readonly sheet: string;
+        readonly id: string;
+    }[];
+    readonly conflicts: readonly Conflict[];
+    /**
+     * Rows the workbook no longer has. Reported, never actioned: a row deleted
+     * by accident in a spreadsheet has no symptom, and deletion is not a thing
+     * this import does.
+     */
+    readonly missing: readonly {
+        readonly sheet: string;
+        readonly id: string;
+    }[];
+}
+/** A column whose value is derived for readability and ignored on the way back. */
+export declare const isDerivedColumn: (label: string) => boolean;
+export declare const keySheet: (rows: readonly (readonly string[])[]) => KeyedSheet;
+/**
+ * The baseline sheet holds every working row prefixed by its sheet name, so
+ * one hidden sheet can carry them all. This puts them back.
+ */
+export declare const baselineSheets: (rows: readonly (readonly string[])[]) => ReadonlyMap<string, readonly (readonly string[])[]>;
+/**
+ * Three-way merge over one sheet.
+ *
+ * `current` is the sheet as it would be exported from the model right now, so
+ * drift is measured in exactly the terms the author edited in rather than
+ * against the YAML.
+ */
+export declare const mergeSheet: (sheet: string, working: KeyedSheet, baseline: KeyedSheet, current: KeyedSheet) => MergeReport;
+/**
+ * Merge every working sheet the workbook and the model share.
+ *
+ * A sheet present in one and not the other is skipped rather than guessed at:
+ * the machinery sheets are not working data, and a sheet the model no longer
+ * produces is not something an import should invent operations for.
+ */
+export declare const mergeWorkbook: (working: ReadonlyMap<string, readonly (readonly string[])[]>, baseline: ReadonlyMap<string, readonly (readonly string[])[]>, current: readonly WorkbookSheet[]) => MergeReport;

package/dist/workbook-merge.js

@@ -0,0 +1,108 @@
+/** A column whose value is derived for readability and ignored on the way back. */
+export const isDerivedColumn = (label) => label.startsWith('↳');
+export const keySheet = (rows) => {
+    const header = rows[0] ?? [];
+    const keyed = new Map();
+    for (const row of rows.slice(1)) {
+        const id = row[0] ?? '';
+        if (id === '')
+            continue;
+        keyed.set(id, row);
+    }
+    return { header, rows: keyed };
+};
+/**
+ * The baseline sheet holds every working row prefixed by its sheet name, so
+ * one hidden sheet can carry them all. This puts them back.
+ */
+export const baselineSheets = (rows) => {
+    const sheets = new Map();
+    for (const row of rows.slice(1)) {
+        const name = row[0] ?? '';
+        if (name === '')
+            continue;
+        const held = sheets.get(name);
+        if (held === undefined)
+            sheets.set(name, [row.slice(1)]);
+        else
+            held.push(row.slice(1));
+    }
+    return sheets;
+};
+const cellsOf = (header, row) => {
+    const cells = new Map();
+    if (row === undefined)
+        return cells;
+    header.forEach((label, index) => {
+        if (isDerivedColumn(label))
+            return;
+        cells.set(label, row[index] ?? '');
+    });
+    return cells;
+};
+/**
+ * Three-way merge over one sheet.
+ *
+ * `current` is the sheet as it would be exported from the model right now, so
+ * drift is measured in exactly the terms the author edited in rather than
+ * against the YAML.
+ */
+export const mergeSheet = (sheet, working, baseline, current) => {
+    const changes = [];
+    const added = [];
+    const conflicts = [];
+    const missing = [];
+    for (const [id, row] of working.rows) {
+        const before = baseline.rows.get(id);
+        if (before === undefined) {
+            added.push({ sheet, id });
+            continue;
+        }
+        const mine = cellsOf(working.header, row);
+        const ancestor = cellsOf(baseline.header, before);
+        const theirs = cellsOf(current.header, current.rows.get(id));
+        for (const [column, value] of mine) {
+            const was = ancestor.get(column) ?? '';
+            if (value === was)
+                continue;
+            const now = theirs.get(column) ?? was;
+            if (now !== was && now !== value) {
+                // Both moved, and not to the same place.
+                conflicts.push({ sheet, id, column, from: was, to: value, theirs: now });
+                continue;
+            }
+            changes.push({ sheet, id, column, from: was, to: value });
+        }
+    }
+    for (const id of baseline.rows.keys()) {
+        if (!working.rows.has(id))
+            missing.push({ sheet, id });
+    }
+    return { changes, added, conflicts, missing };
+};
+const EMPTY = { header: [], rows: new Map() };
+/**
+ * Merge every working sheet the workbook and the model share.
+ *
+ * A sheet present in one and not the other is skipped rather than guessed at:
+ * the machinery sheets are not working data, and a sheet the model no longer
+ * produces is not something an import should invent operations for.
+ */
+export const mergeWorkbook = (working, baseline, current) => {
+    const currentByName = new Map(current.map((sheet) => [sheet.name, sheet.rows]));
+    const reports = [];
+    for (const [name, rows] of working) {
+        if (name.startsWith('~') || name === '00 Read Me')
+            continue;
+        const ancestor = baseline.get(name);
+        if (ancestor === undefined)
+            continue;
+        reports.push(mergeSheet(name, keySheet(rows), keySheet(ancestor), currentByName.has(name) ? keySheet(currentByName.get(name)) : EMPTY));
+    }
+    return {
+        changes: reports.flatMap(({ changes }) => changes),
+        added: reports.flatMap(({ added }) => added),
+        conflicts: reports.flatMap(({ conflicts }) => conflicts),
+        missing: reports.flatMap(({ missing }) => missing),
+    };
+};

package/dist/workbook-operations.d.ts

@@ -0,0 +1,9 @@
+import type { MergeReport } from './workbook-merge.js';
+export interface OperationsResult {
+    readonly operations: readonly Record<string, unknown>[];
+    /** Rows that cannot be turned into an operation, with the reason. */
+    readonly refusals: readonly string[];
+}
+export declare const operationsFrom: (report: MergeReport, working: ReadonlyMap<string, readonly (readonly string[])[]>) => OperationsResult;
+/** The operations document `apply` takes. */
+export declare const operationsDocument: (operations: readonly Record<string, unknown>[]) => Record<string, unknown>;

package/dist/workbook-operations.js

@@ -0,0 +1,139 @@
+import { keySheet } from './workbook-merge.js';
+/**
+ * Merged workbook edits, as `yarramate/operations/v1` (#355, ADR 0127).
+ *
+ * Operations rather than a rewrite, because `applyOperations` edits YAML
+ * SURGICALLY: comments, key order and formatting survive an import, and a
+ * workbook imported with no edits produces no diff at all. Regenerating the
+ * documents would be simpler and would destroy the rationale the models carry.
+ *
+ * It also means every edit passes the atomic compile gate on the way in. A
+ * workbook that would produce an uncompilable model is refused whole, rather
+ * than half-written.
+ */
+/** Column label to the field name `conceptFields` / `relationshipFields` uses. */
+const CONCEPT_FIELDS = {
+    Kind: 'kind',
+    Name: 'name',
+    Description: 'description',
+    Status: 'status',
+    Owner: 'owner',
+};
+const RELATIONSHIP_FIELDS = {
+    Kind: 'kind',
+    From: 'from',
+    To: 'to',
+    Name: 'name',
+    Description: 'description',
+    Status: 'status',
+    Mode: 'mode',
+    Content: 'content',
+};
+const CONCEPT_SHEETS = new Set(['01 Concepts', '03 States']);
+const RELATIONSHIP_SHEET = '02 Relationships';
+/**
+ * A kind is written as a qualified identity in the workbook
+ * (`yarramate/core@0.1#serving`) because that is what the graph carries, and a
+ * document declares the LOCAL name (`serving`). The profile prefix is dropped
+ * on the way back rather than written into a document that would then not
+ * compile.
+ */
+const localKind = (value) => {
+    const hash = value.indexOf('#');
+    return hash < 0 ? value : value.slice(hash + 1);
+};
+export const operationsFrom = (report, working) => {
+    const operations = [];
+    const refusals = [];
+    const sheets = new Map([...working].map(([name, rows]) => [name, keySheet(rows)]));
+    const documentOf = (sheet, id) => {
+        const keyed = sheets.get(sheet);
+        if (keyed === undefined)
+            return '';
+        const at = keyed.header.indexOf('Document');
+        if (at < 0)
+            return '';
+        return keyed.rows.get(id)?.[at] ?? '';
+    };
+    const cell = (sheet, id, column) => {
+        const keyed = sheets.get(sheet);
+        if (keyed === undefined)
+            return '';
+        const at = keyed.header.indexOf(column);
+        if (at < 0)
+            return '';
+        return keyed.rows.get(id)?.[at] ?? '';
+    };
+    // Updates, grouped so one subject with three edited cells is one operation
+    // rather than three.
+    const updates = new Map();
+    for (const change of report.changes) {
+        const isConcept = CONCEPT_SHEETS.has(change.sheet);
+        const isRelationship = change.sheet === RELATIONSHIP_SHEET;
+        if (!isConcept && !isRelationship) {
+            // The satellite sheets carry list-valued facts, which are a different
+            // shape of edit and are not attempted here.
+            refusals.push(`${change.sheet} row "${change.id}": editing ${change.column} on this sheet is not supported yet`);
+            continue;
+        }
+        const fields = isConcept ? CONCEPT_FIELDS : RELATIONSHIP_FIELDS;
+        const field = fields[change.column];
+        if (field === undefined) {
+            if (change.column !== 'Document') {
+                refusals.push(`${change.sheet} row "${change.id}": ${change.column} cannot be written back`);
+            }
+            continue;
+        }
+        const document = documentOf(change.sheet, change.id);
+        if (document === '') {
+            refusals.push(`${change.sheet} row "${change.id}": no Document, so there is nowhere to write it`);
+            continue;
+        }
+        const key = `${change.sheet}|${change.id}`;
+        const held = updates.get(key) ?? {
+            op: isConcept ? 'update-concept' : 'update-relationship',
+            document,
+            [isConcept ? 'concept' : 'relationship']: { id: change.id },
+        };
+        const target = held[isConcept ? 'concept' : 'relationship'];
+        target[field] = field === 'kind' ? localKind(change.to) : change.to;
+        updates.set(key, held);
+    }
+    operations.push(...updates.values());
+    for (const { sheet, id } of report.added) {
+        const isConcept = CONCEPT_SHEETS.has(sheet);
+        const isRelationship = sheet === RELATIONSHIP_SHEET;
+        if (!isConcept && !isRelationship) {
+            refusals.push(`${sheet} row "${id}": adding a row to this sheet is not supported yet`);
+            continue;
+        }
+        const document = documentOf(sheet, id);
+        if (document === '') {
+            refusals.push(`${sheet} row "${id}": a new row needs a Document saying which file it belongs to`);
+            continue;
+        }
+        const fields = isConcept ? CONCEPT_FIELDS : RELATIONSHIP_FIELDS;
+        const body = { id };
+        for (const [column, field] of Object.entries(fields)) {
+            const value = cell(sheet, id, column);
+            if (value === '')
+                continue;
+            body[field] = field === 'kind' ? localKind(value) : value;
+        }
+        if (body.kind === undefined) {
+            refusals.push(`${sheet} row "${id}": a new row needs a Kind`);
+            continue;
+        }
+        operations.push({
+            op: isConcept ? 'add-concept' : 'add-relationship',
+            document,
+            [isConcept ? 'concept' : 'relationship']: body,
+        });
+    }
+    return { operations, refusals };
+};
+/** The operations document `apply` takes. */
+export const operationsDocument = (operations) => ({
+    format: 'yarramate/operations/v1',
+    operations,
+});