yarramate 1.5.0 → 1.6.0

package/dist/cli-support.d.ts

@@ -7,7 +7,7 @@ export interface CliResult {
 export declare const isMainModule: (moduleUrl: string, entrypoint: string | undefined) => boolean;
 export declare const packageVersion: string;
 export declare const versionResult: (binary: string) => CliResult;
-export declare const usage = "Usage:\n  yarramate init <directory> [--no-pointer]\n  yarramate design <workspace.yaml> [--subject <subject-id>] [--catalogue <catalogue.yaml>] [--facilitate] [--json]\n  yarramate apply <operations.yaml> <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> \"<free text>\" | <subject-id> ... | <projection.yaml> [--budget <tokens>] [--neighbours <n>] [--json]\n  yarramate ask <workspace.yaml> --subjects [--kind <term>] [--status <status>] [--json]\n  yarramate ask <workspace.yaml> --kinds [--json]\n  yarramate ask <workspace.yaml> --advise \"<topic>\" [--budget <tokens>] [--neighbours <n>] [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --where \"<free text>\" | <subject-id> ... [--json]\n  yarramate ask <workspace.yaml> --next [--json]\n  yarramate ask <workspace.yaml> --open [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --compare <from-state> <to-state> [--json]\n  yarramate ask <workspace.yaml> --changed <git-range> [--budget <tokens>] [--neighbours <n>] [--json]\n  yarramate check <source.yaml> [source.yaml ...] [--json] [--strict]\n  yarramate reconcile <workspace.yaml> [--json]\n  yarramate export graph <workspace.yaml> [--out <file>]\n  yarramate export markdown <projection.yaml> <workspace.yaml> [--out <file>]\n  yarramate export markdown --changed <git-range> <workspace.yaml> [--out <file>]\n  yarramate export briefs <projection.yaml> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export briefs --changed <git-range> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export rtm <workspace.yaml> --out <directory>\n  yarramate export likec4 <likec4-project.yaml> <output-dir> <workspace.yaml> [--changed <git-range>]\n";
+export declare const usage = "Usage:\n  yarramate init <directory> [--no-pointer]\n  yarramate design <workspace.yaml> [--subject <subject-id>] [--catalogue <catalogue.yaml>] [--facilitate] [--json]\n  yarramate apply <operations.yaml> <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> \"<free text>\" | <subject-id> ... | <projection.yaml> [--budget <tokens>] [--neighbours <n>] [--json]\n  yarramate ask <workspace.yaml> --subjects [--kind <term>] [--status <status>] [--json]\n  yarramate ask <workspace.yaml> --kinds [--json]\n  yarramate ask <workspace.yaml> --advise \"<topic>\" [--budget <tokens>] [--neighbours <n>] [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --where \"<free text>\" | <subject-id> ... [--json]\n  yarramate ask <workspace.yaml> --next [--json]\n  yarramate ask <workspace.yaml> --open [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --compare <from-state> <to-state> [--json]\n  yarramate ask <workspace.yaml> --changed <git-range> [--budget <tokens>] [--neighbours <n>] [--json]\n  yarramate check <source.yaml> [source.yaml ...] [--json] [--strict]\n  yarramate reconcile <workspace.yaml> [--json]\n  yarramate export graph <workspace.yaml> [--out <file>]\n  yarramate export markdown <projection.yaml> <workspace.yaml> [--out <file>]\n  yarramate export markdown --changed <git-range> <workspace.yaml> [--out <file>]\n  yarramate export briefs <projection.yaml> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export briefs --changed <git-range> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export rtm <workspace.yaml> --out <directory>\n  yarramate export xlsx <projection.yaml> <workspace.yaml> --out <file>\n  yarramate import xlsx <workbook.xlsx> <workspace.yaml> [--json]\n  yarramate export likec4 <likec4-project.yaml> <output-dir> <workspace.yaml> [--changed <git-range>]\n";
 export declare const diagnosticJson: (diagnostics: unknown) => string;
 export declare const checkResultJson: (ok: boolean, diagnostics: unknown, counted?: {
     readonly documents: number;

package/dist/cli-support.js

@@ -22,7 +22,7 @@ export const versionResult = (binary) => ({
     stdout: `${binary} ${packageVersion}\n`,
     stderr: '',
 });
-export const usage = 'Usage:\n  yarramate init <directory> [--no-pointer]\n  yarramate design <workspace.yaml> [--subject <subject-id>] [--catalogue <catalogue.yaml>] [--facilitate] [--json]\n  yarramate apply <operations.yaml> <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> "<free text>" | <subject-id> ... | <projection.yaml> [--budget <tokens>] [--neighbours <n>] [--json]\n  yarramate ask <workspace.yaml> --subjects [--kind <term>] [--status <status>] [--json]\n  yarramate ask <workspace.yaml> --kinds [--json]\n  yarramate ask <workspace.yaml> --advise "<topic>" [--budget <tokens>] [--neighbours <n>] [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --where "<free text>" | <subject-id> ... [--json]\n  yarramate ask <workspace.yaml> --next [--json]\n  yarramate ask <workspace.yaml> --open [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --compare <from-state> <to-state> [--json]\n  yarramate ask <workspace.yaml> --changed <git-range> [--budget <tokens>] [--neighbours <n>] [--json]\n  yarramate check <source.yaml> [source.yaml ...] [--json] [--strict]\n  yarramate reconcile <workspace.yaml> [--json]\n  yarramate export graph <workspace.yaml> [--out <file>]\n  yarramate export markdown <projection.yaml> <workspace.yaml> [--out <file>]\n  yarramate export markdown --changed <git-range> <workspace.yaml> [--out <file>]\n  yarramate export briefs <projection.yaml> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export briefs --changed <git-range> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export rtm <workspace.yaml> --out <directory>\n  yarramate export likec4 <likec4-project.yaml> <output-dir> <workspace.yaml> [--changed <git-range>]\n';
+export const usage = 'Usage:\n  yarramate init <directory> [--no-pointer]\n  yarramate design <workspace.yaml> [--subject <subject-id>] [--catalogue <catalogue.yaml>] [--facilitate] [--json]\n  yarramate apply <operations.yaml> <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> "<free text>" | <subject-id> ... | <projection.yaml> [--budget <tokens>] [--neighbours <n>] [--json]\n  yarramate ask <workspace.yaml> --subjects [--kind <term>] [--status <status>] [--json]\n  yarramate ask <workspace.yaml> --kinds [--json]\n  yarramate ask <workspace.yaml> --advise "<topic>" [--budget <tokens>] [--neighbours <n>] [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --where "<free text>" | <subject-id> ... [--json]\n  yarramate ask <workspace.yaml> --next [--json]\n  yarramate ask <workspace.yaml> --open [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --compare <from-state> <to-state> [--json]\n  yarramate ask <workspace.yaml> --changed <git-range> [--budget <tokens>] [--neighbours <n>] [--json]\n  yarramate check <source.yaml> [source.yaml ...] [--json] [--strict]\n  yarramate reconcile <workspace.yaml> [--json]\n  yarramate export graph <workspace.yaml> [--out <file>]\n  yarramate export markdown <projection.yaml> <workspace.yaml> [--out <file>]\n  yarramate export markdown --changed <git-range> <workspace.yaml> [--out <file>]\n  yarramate export briefs <projection.yaml> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export briefs --changed <git-range> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export rtm <workspace.yaml> --out <directory>\n  yarramate export xlsx <projection.yaml> <workspace.yaml> --out <file>\n  yarramate import xlsx <workbook.xlsx> <workspace.yaml> [--json]\n  yarramate export likec4 <likec4-project.yaml> <output-dir> <workspace.yaml> [--changed <git-range>]\n';
 export const diagnosticJson = (diagnostics) => `${JSON.stringify({
     format: 'yarramate/diagnostic-result/v1',
     diagnostics,

package/dist/cli.d.ts

@@ -3,3 +3,13 @@ import { type CliResult } from './cli-support.js';
 export type { CliResult } from './cli-support.js';
 export declare const deriveInitId: (directory: string) => string;
 export declare function runCli(args: readonly string[], cwd?: string): CliResult;
+/**
+ * Every verb, including the one that cannot be synchronous.
+ *
+ * `import xlsx` has to inflate a workbook, and the only inflater available
+ * everywhere this runs is `DecompressionStream`, which is async. Widening
+ * `runCli` to return a promise would change the type every one of its callers
+ * reads - the readers half of the rule in CONTRIBUTING.md - so the async verb
+ * gets its own entry and `runCli` keeps its signature.
+ */
+export declare function runCliAsync(args: readonly string[], cwd?: string): Promise<CliResult>;

package/dist/cli.js

@@ -5,6 +5,7 @@ import { compileWorkspace } from './compiler.js';
 import { diagnosticJson, isMainModule, usage, versionResult, } from './cli-support.js';
 import { runAskCommand } from './ask-command.js';
 import { runCheckCommand } from './check-command.js';
+import { runImportCommand } from './import-command.js';
 import { runExportCommand } from './export-command.js';
 import { runApplyCommand } from './apply-cli.js';
 import { runDesignCommand } from './design-command.js';
@@ -227,8 +228,23 @@ export function runCli(args, cwd = process.cwd()) {
     }
     return { exitCode: 2, stdout: '', stderr: usage };
 }
+/**
+ * Every verb, including the one that cannot be synchronous.
+ *
+ * `import xlsx` has to inflate a workbook, and the only inflater available
+ * everywhere this runs is `DecompressionStream`, which is async. Widening
+ * `runCli` to return a promise would change the type every one of its callers
+ * reads - the readers half of the rule in CONTRIBUTING.md - so the async verb
+ * gets its own entry and `runCli` keeps its signature.
+ */
+export async function runCliAsync(args, cwd = process.cwd()) {
+    const [command, ...options] = args;
+    if (command === 'import')
+        return runImportCommand(options, cwd);
+    return runCli(args, cwd);
+}
 if (isMainModule(import.meta.url, process.argv[1])) {
-    const result = runCli(process.argv.slice(2));
+    const result = await runCliAsync(process.argv.slice(2));
     process.stdout.write(result.stdout);
     process.stderr.write(result.stderr);
     process.exitCode = result.exitCode;

package/dist/export-command.js

@@ -1,16 +1,18 @@
 import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, writeFileSync, } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseDocument } from 'yaml';
 import { renderBrief } from './brief.js';
 import { deriveChangedSubjects } from './changed.js';
-import { humanDiagnostics, usage } from './cli-support.js';
+import { humanDiagnostics, packageVersion, usage, } from './cli-support.js';
 import { compileWorkspaceWithProfileContext, } from './compiler.js';
 import { serializeSemanticGraph } from './graph.js';
 import { evaluateEvidenceWorkspace, loadEvidence, } from './evidence.js';
 import { evaluateProjection, loadProjection, renderProjectionMarkdown, } from './projection.js';
 import { buildRtm, renderRtmMarkdown } from './rtm.js';
+import { workbookFrom } from './workbook.js';
 import { loadWorkspaceManifest } from './workspace.js';
 // The adapter stays a separate process behind the verb: the core never
 // imports adapter code (the adapter-runtime-dependency exclusion), it
@@ -74,7 +76,7 @@ const parseExportOptions = (options) => {
 export function runExportCommand(options, cwd) {
     const [kind, ...rest] = options;
     if (kind === undefined ||
-        !['graph', 'markdown', 'briefs', 'rtm', 'likec4'].includes(kind)) {
+        !['graph', 'markdown', 'briefs', 'rtm', 'likec4', 'xlsx'].includes(kind)) {
         return { exitCode: 2, stdout: '', stderr: usage };
     }
     const parsed = parseExportOptions(rest);
@@ -128,7 +130,8 @@ export function runExportCommand(options, cwd) {
         parsed.json ||
         (usesChanged && (kind === 'graph' || kind === 'rtm')) ||
         (parsed.budget !== undefined && kind !== 'briefs') ||
-        ((kind === 'briefs' || kind === 'rtm') && parsed.out === undefined)) {
+        ((kind === 'briefs' || kind === 'rtm' || kind === 'xlsx') &&
+            parsed.out === undefined)) {
         return { exitCode: 2, stdout: '', stderr: usage };
     }
     try {
@@ -149,14 +152,17 @@ export function runExportCommand(options, cwd) {
         if (!loadedWorkspace.ok)
             return failed(loadedWorkspace.diagnostics);
         const workspace = loadedWorkspace.workspace;
-        const compilation = compileWorkspaceWithProfileContext([
+        // Named rather than inlined so the workbook can pin its digests against
+        // exactly the bytes that compiled, the way a visual commit does (#355).
+        const sources = [
             ...workspace.profiles,
             ...workspace.patterns,
             ...workspace.documents,
         ].map((path) => ({
             path,
             source: readFileSync(resolve(cwd, path), 'utf8'),
-        })));
+        }));
+        const compilation = compileWorkspaceWithProfileContext(sources);
         if (!compilation.ok)
             return failed(compilation.diagnostics);
         if (kind === 'rtm') {
@@ -246,6 +252,36 @@ export function runExportCommand(options, cwd) {
                 return failed(loadedProjection.diagnostics);
             result = evaluateProjection(compilation.graph, loadedProjection.projection, compilation.profileContext);
         }
+        if (kind === 'xlsx') {
+            // A workbook an architect can work in (#355). It takes a PROJECTION,
+            // like markdown and briefs do, which is what gives it version selection
+            // for free: a projection query already has a `states` facet, so
+            // "export the target state" is an existing capability rather than a
+            // flag competing with it.
+            const bytes = workbookFrom(result, {
+                workspace: workspace.id,
+                yarramateVersion: packageVersion,
+                sourceDigests: Object.fromEntries(sources.map(({ path, source }) => [
+                    path,
+                    createHash('sha256').update(source, 'utf8').digest('hex'),
+                ])),
+                conceptKinds: [
+                    ...compilation.profileContext.conceptKindLineages.keys(),
+                ].sort(),
+                relationshipKinds: [
+                    ...compilation.profileContext.relationshipKindLineages.keys(),
+                ].sort(),
+                statuses: ['planned', 'current', 'retired'],
+            });
+            const outPath = resolve(cwd, parsed.out);
+            mkdirSync(dirname(outPath), { recursive: true });
+            writeFileSync(outPath, bytes);
+            return {
+                exitCode: 0,
+                stdout: `Wrote workbook to ${parsed.out}\n`,
+                stderr: '',
+            };
+        }
         if (kind === 'markdown') {
             const rendered = renderProjectionMarkdown(result, compilation.profileContext);
             if (parsed.out === undefined) {

package/dist/import-command.d.ts

@@ -0,0 +1,16 @@
+import { type CliResult } from './cli-support.js';
+/**
+ * `yarramate import xlsx <file> <workspace.yaml>` (#355, ADR 0127).
+ *
+ * The workbook carries its own ancestor, so this is a three-way merge rather
+ * than an overwrite: the author's edits are measured against `~Baseline`, the
+ * repository's drift is measured against the same, and only a field both moved
+ * is refused. Everything the author changed that the repository left alone
+ * merges cleanly, which is what makes a week-long workbook cycle usable.
+ *
+ * Edits land as `yarramate/operations/v1` through `apply`, so untouched YAML
+ * keeps its comments, key order and formatting, and the whole import passes
+ * the atomic compile gate. A workbook that would produce an uncompilable model
+ * is refused whole rather than half written.
+ */
+export declare function runImportCommand(options: readonly string[], cwd: string): Promise<CliResult>;

package/dist/import-command.js

@@ -0,0 +1,156 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { runApplyCommand } from './apply-cli.js';
+import { humanDiagnostics, packageVersion, usage } from './cli-support.js';
+import { compileWorkspaceWithProfileContext } from './compiler.js';
+import { evaluateProjection } from './projection.js';
+import { loadWorkspaceManifest } from './workspace.js';
+import { buildWorkbookSheets } from './workbook.js';
+import { baselineSheets, mergeWorkbook } from './workbook-merge.js';
+import { operationsFrom, operationsDocument } from './workbook-operations.js';
+import { readWorkbook } from './workbook-read.js';
+import { writeFileSync, mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { stringify } from 'yaml';
+/**
+ * `yarramate import xlsx <file> <workspace.yaml>` (#355, ADR 0127).
+ *
+ * The workbook carries its own ancestor, so this is a three-way merge rather
+ * than an overwrite: the author's edits are measured against `~Baseline`, the
+ * repository's drift is measured against the same, and only a field both moved
+ * is refused. Everything the author changed that the repository left alone
+ * merges cleanly, which is what makes a week-long workbook cycle usable.
+ *
+ * Edits land as `yarramate/operations/v1` through `apply`, so untouched YAML
+ * keeps its comments, key order and formatting, and the whole import passes
+ * the atomic compile gate. A workbook that would produce an uncompilable model
+ * is refused whole rather than half written.
+ */
+export async function runImportCommand(options, cwd) {
+    const [kind, ...rest] = options;
+    if (kind !== 'xlsx')
+        return { exitCode: 2, stdout: '', stderr: usage };
+    const json = rest.includes('--json');
+    const positionals = rest.filter((option) => option !== '--json');
+    const [workbookPath, workspacePath] = positionals;
+    if (positionals.length !== 2 ||
+        workbookPath === undefined ||
+        workspacePath === undefined) {
+        return { exitCode: 2, stdout: '', stderr: usage };
+    }
+    const manifestPath = resolve(cwd, workspacePath);
+    let manifestSource;
+    let workbookBytes;
+    try {
+        manifestSource = readFileSync(manifestPath, 'utf8');
+        workbookBytes = new Uint8Array(readFileSync(resolve(cwd, workbookPath)));
+    }
+    catch (cause) {
+        return {
+            exitCode: 1,
+            stdout: '',
+            stderr: `${cause instanceof Error ? cause.message : String(cause)}\n`,
+        };
+    }
+    const loaded = loadWorkspaceManifest({ path: workspacePath, source: manifestSource }, cwd);
+    if (!loaded.ok) {
+        return {
+            exitCode: 1,
+            stdout: '',
+            stderr: humanDiagnostics(loaded.diagnostics),
+        };
+    }
+    const workspace = loaded.workspace;
+    const sources = [
+        ...workspace.profiles,
+        ...workspace.patterns,
+        ...workspace.documents,
+    ].map((path) => ({ path, source: readFileSync(resolve(cwd, path), 'utf8') }));
+    const compilation = compileWorkspaceWithProfileContext(sources);
+    if (!compilation.ok) {
+        return {
+            exitCode: 1,
+            stdout: '',
+            stderr: humanDiagnostics(compilation.diagnostics),
+        };
+    }
+    const read = await readWorkbook(workbookBytes);
+    if (!read.ok) {
+        return { exitCode: 1, stdout: '', stderr: `${read.reason}\n` };
+    }
+    const baselineRows = read.sheets.get('~Baseline');
+    if (baselineRows === undefined) {
+        // Without the ancestor there is no way to tell the author's edit from the
+        // repository's drift, and guessing would silently discard one of them.
+        return {
+            exitCode: 1,
+            stdout: '',
+            stderr: 'This workbook carries no ~Baseline sheet, so it was not produced by ' +
+                '`yarramate export xlsx` and there is no ancestor to merge against.\n',
+        };
+    }
+    const projectionId = read.sheets.get('~Meta')?.find((row) => row[0] === 'Projection')?.[1];
+    const result = evaluateProjection(compilation.graph, {
+        format: 'yarramate/projection/v1',
+        id: projectionId ?? 'imported',
+        version: '1.0',
+        query: {},
+    }, compilation.profileContext);
+    const current = buildWorkbookSheets(result, {
+        workspace: workspace.id,
+        yarramateVersion: packageVersion,
+        sourceDigests: {},
+        conceptKinds: [],
+        relationshipKinds: [],
+        statuses: [],
+    });
+    const report = mergeWorkbook(read.sheets, baselineSheets(baselineRows), current);
+    const planned = operationsFrom(report, read.sheets);
+    if (report.conflicts.length > 0) {
+        const lines = report.conflicts.map(({ sheet, id, column, from, to, theirs }) => `  ${sheet} "${id}" ${column}: you wrote ${JSON.stringify(to)}, ` +
+            `the workspace now has ${JSON.stringify(theirs)}, both from ${JSON.stringify(from)}`);
+        return {
+            exitCode: 1,
+            stdout: '',
+            stderr: `${report.conflicts.length} field${report.conflicts.length === 1 ? '' : 's'} changed in the workbook and in the workspace since the workbook was made. ` +
+                'Nothing was written.\n' +
+                `${lines.join('\n')}\n`,
+        };
+    }
+    const notes = [
+        ...planned.refusals.map((reason) => `  not imported: ${reason}`),
+        ...report.missing.map(({ sheet, id }) => `  not imported: ${sheet} "${id}" is absent from the workbook; ` +
+            'a missing row is never a deletion'),
+    ];
+    if (planned.operations.length === 0) {
+        const summary = `Nothing to import: the workbook matches the workspace.\n`;
+        return {
+            exitCode: 0,
+            stdout: json
+                ? `${JSON.stringify({ format: 'yarramate/import-result/v1', operations: 0, notes }, null, 2)}\n`
+                : summary + (notes.length > 0 ? `${notes.join('\n')}\n` : ''),
+            stderr: '',
+        };
+    }
+    // Handed to `apply` rather than written directly: one mutation path, one
+    // atomic gate, and the surgical YAML editing that keeps comments.
+    const scratch = mkdtempSync(join(tmpdir(), 'yarramate-import-'));
+    const operationsPath = join(scratch, 'operations.yaml');
+    writeFileSync(operationsPath, stringify(operationsDocument(planned.operations)), 'utf8');
+    const applied = runApplyCommand([operationsPath, workspacePath], cwd);
+    if (applied.exitCode !== 0)
+        return applied;
+    const summary = `Imported ${planned.operations.length} change${planned.operations.length === 1 ? '' : 's'} from ${workbookPath}\n`;
+    return {
+        exitCode: 0,
+        stdout: json
+            ? `${JSON.stringify({
+                format: 'yarramate/import-result/v1',
+                operations: planned.operations.length,
+                notes,
+            }, null, 2)}\n`
+            : summary + (notes.length > 0 ? `${notes.join('\n')}\n` : ''),
+        stderr: '',
+    };
+}

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-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>;