@pipefy/pipefy-process-coder 0.1.0 → 0.1.2

package/dist/workspace/flows.js

@@ -0,0 +1,149 @@
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import { mkdirp, exists, writeJson, readJson } from "../util/fsx.js";
+import { flowBaselineFile } from "./layout.js";
+import { slug } from "../util/slug.js";
+import { canonicalString } from "../util/json.js";
+import { unlinkFlow, linkFlow } from "../codec/flow.js";
+/**
+ * The `flows/` half of a workspace.
+ *
+ * A pipe's iPaaS flows are entities of that pipe — the pipe's own webhook URLs
+ * carry their ids — so they live beside `pipes/`, read by the same pull and
+ * written by the same apply.
+ *
+ *   pipes/<id>--<name>/flows/
+ *     _meta.json                    coverage, projectId, counts, read time
+ *     connections.json              externalId, pieceName, displayName, status
+ *     pieces.json                   pieceName -> version the instance offers
+ *     _readonly/flow-runs.json      recent outcomes; never written back
+ *     <flowId>--<slug>/
+ *       flow.json                   the flow row
+ *       version.json                the version row, without the trigger
+ *       nodes/NN--<name>.json       one node per file, in execution order
+ *
+ * Coverage matters here as much as anywhere: a pipe whose iPaaS could not be
+ * reached gets `unknown`, which is never read as "this pipe has no flows".
+ */
+export const FLOWS_DIR = 'flows';
+/**
+ * The flows directory of ONE repo. Under the repo, not at the workspace root:
+ * a workspace can hold several pipes, each with its own iPaaS workspace, and a
+ * shared directory meant the second pipe's pull deleted the first pipe's flows.
+ */
+export const flowsRoot = (repoDir) => join(repoDir, FLOWS_DIR);
+export const flowDirName = (tree) => {
+    const id = tree.flow['id'] ? String(tree.flow['id']) : '_new';
+    return `${id}--${slug(String(tree.version['displayName'] ?? 'flow'))}`;
+};
+/** The empty section, for a pipe with no iPaaS or one that could not be read. */
+export const unknownFlows = (reason) => ({
+    meta: { coverage: 'unknown', readAt: new Date().toISOString(), reason, notes: [reason] },
+    flows: [],
+    connections: [],
+    pieces: {},
+    runs: [],
+});
+// ── write ───────────────────────────────────────────────────────────────────
+export const writeFlows = async (workspace, section) => {
+    const root = flowsRoot(workspace);
+    /**
+     * Rewritten wholesale rather than merged: a flow deleted upstream has to
+     * disappear from the workspace too, and a leftover directory would be read as a
+     * flow the author wants created.
+     */
+    if (await exists(root))
+        await fs.rm(root, { recursive: true, force: true });
+    await mkdirp(join(root, '_readonly'));
+    const written = [];
+    const put = async (path, value) => {
+        await writeJson(path, value);
+        written.push(path);
+    };
+    await put(join(root, '_meta.json'), section.meta);
+    await put(join(root, 'connections.json'), section.connections);
+    await put(join(root, 'pieces.json'), section.pieces);
+    await put(join(root, '_readonly', 'flow-runs.json'), section.runs);
+    for (const tree of section.flows) {
+        const dir = join(root, flowDirName(tree));
+        await mkdirp(join(dir, 'nodes'));
+        await put(join(dir, 'flow.json'), tree.flow);
+        await put(join(dir, 'version.json'), tree.version);
+        for (const [i, node] of tree.nodes.entries()) {
+            await put(join(dir, 'nodes', `${String(i).padStart(2, '0')}--${node.name}.json`), node);
+        }
+    }
+    return written;
+};
+// ── read ────────────────────────────────────────────────────────────────────
+export const readFlows = async (workspace) => {
+    const root = flowsRoot(workspace);
+    if (!(await exists(root)))
+        return null;
+    const meta = (await readJson(join(root, '_meta.json')).catch(() => null)) ?? {
+        coverage: 'unknown',
+        readAt: new Date().toISOString(),
+        notes: ['flows/_meta.json is missing, so coverage is unknown'],
+    };
+    const connections = (await readJson(join(root, 'connections.json')).catch(() => [])) ?? [];
+    const pieces = (await readJson(join(root, 'pieces.json')).catch(() => ({}))) ?? {};
+    const runs = (await readJson(join(root, '_readonly', 'flow-runs.json')).catch(() => [])) ?? [];
+    const flows = [];
+    for (const entry of await fs.readdir(root, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        /**
+         * Only the tool's own metadata directories are skipped, not everything with a
+         * leading underscore.
+         *
+         * `flowDirName` names a flow that does not exist yet `_new--<slug>`, so a
+         * blanket `startsWith('_')` filter made an authored flow invisible to the
+         * reader that produced it — the diff reported "no changes" over a whole flow
+         * waiting to be created.
+         */
+        if (entry.name === '_readonly')
+            continue;
+        const dir = join(root, entry.name);
+        const flow = await readJson(join(dir, 'flow.json'));
+        const version = await readJson(join(dir, 'version.json'));
+        const nodeDir = join(dir, 'nodes');
+        const files = (await fs.readdir(nodeDir)).filter((f) => f.endsWith('.json')).sort();
+        const nodes = [];
+        for (const f of files) {
+            const node = await readJson(join(nodeDir, f));
+            nodes.push({ ...node, name: String(node['name'] ?? ''), type: String(node['type'] ?? '') });
+        }
+        /**
+         * Order comes from the filename prefix, which is how the codec wrote it — but
+         * the trigger must be first for `linkFlow` to find the head of the chain, and
+         * a rename could put something else there.
+         */
+        const triggerAt = nodes.findIndex((n) => n.name === 'trigger');
+        if (triggerAt > 0)
+            nodes.unshift(...nodes.splice(triggerAt, 1));
+        flows.push({ flow, version, nodes });
+    }
+    return { meta, flows, connections, pieces, runs };
+};
+/**
+ * Record what was just read as the baseline, so the next diff has a past to
+ * compare against without touching the network.
+ */
+export const writeFlowBaseline = (workspaceRoot, repoId, section) => writeJson(flowBaselineFile(workspaceRoot, repoId), section);
+/** The recorded flow baseline, or null when this repo has never been pulled. */
+export const readFlowBaseline = async (workspaceRoot, repoId) => {
+    try {
+        return await readJson(flowBaselineFile(workspaceRoot, repoId));
+    }
+    catch {
+        return null;
+    }
+};
+/** The flow row as the API would return it, for comparison and for operations. */
+export const asApiFlow = (tree) => linkFlow(tree);
+/** Whether two flow trees are the same, ignoring `_` metadata differences in order. */
+export const sameFlow = (a, b) => canonicalString(linkFlow(a)) === canonicalString(linkFlow(b));
+export const flowIdOf = (tree) => tree.flow['id'] ? String(tree.flow['id']) : null;
+export const isNewFlow = (tree) => !flowIdOf(tree) || tree.flow['_new'] === true;
+/** Rebuild a tree from an API flow row, for the read path and for verification. */
+export const treeFromApi = (row) => unlinkFlow(row);

package/dist/workspace/layout.js

@@ -0,0 +1,146 @@
+import { join } from 'node:path';
+import { slug } from "../util/slug.js";
+/**
+ * Workspace layout — PLAN.md §4.
+ *
+ * Two deliberate deviations from the plan's sketch, both to make the edit loop
+ * shorter, and both noted in the generated AGENTS.md:
+ *
+ *  - `phase-jumps.json` is gone. A phase's jump set lives in the phase file as
+ *    `jump_target_ids`, because the internal endpoint is per-phase and
+ *    set-replacing (PLAN.md §2.1), so the set is the honest shape and there is
+ *    no second file to keep consistent.
+ *  - `webhooks.json` is one array file rather than a directory, matching
+ *    `labels.json`. Webhooks are few and have no sub-entities.
+ */
+export const PPC_DIR = '.ppc';
+export const paths = (root) => ({
+    root,
+    workspaceFile: join(root, 'workspace.json'),
+    /**
+     * `AGENTS.md`, not `CLAUDE.md`: the emerging cross-tool convention (this
+     * repo's own top-level docs already use it) — the file is read by whatever
+     * agent is editing the workspace, not only Claude Code.
+     */
+    agentsMd: join(root, 'AGENTS.md'),
+    mappingMd: join(root, 'MAPPING.md'),
+    capabilitiesMd: join(root, 'CAPABILITIES.md'),
+    referenceMd: join(root, 'REFERENCE.md'),
+    pipe: join(root, PPC_DIR),
+    lock: join(root, PPC_DIR, 'lock.json'),
+    capabilities: join(root, PPC_DIR, 'capabilities.json'),
+    /**
+     * The closed sets the API publishes, read on the last pull. Cached so
+     * validate, plan and apply can refuse a wrong value offline and name it.
+     */
+    reference: join(root, PPC_DIR, 'reference.json'),
+    baselineDir: join(root, PPC_DIR, 'baseline'),
+    plansDir: join(root, PPC_DIR, 'plans'),
+    pipesDir: join(root, 'pipes'),
+    databasesDir: join(root, 'databases'),
+    gitignore: join(root, '.gitignore'),
+});
+/**
+ * `pipes/<numericId>--<slug>` / `databases/<internalId>--<apiId>--<slug>`.
+ *
+ * A database carries two identities — a numeric internal id and an api id — and
+ * `table(id:)` answers to both. Putting both in the directory name is what makes
+ * the duality visible rather than a footnote: whichever spelling you pull with,
+ * you land in the same directory, and the one you did not use is right there when
+ * you need to cross-reference a connector field (which carries the numeric form)
+ * against an API response (which carries the slug).
+ */
+export const repoDirName = (ref) => ref.kind === 'table' && ref.apiId && ref.apiId !== String(ref.id)
+    ? `${ref.id}--${ref.apiId}--${slug(ref.name)}`
+    : `${ref.id}--${slug(ref.name)}`;
+export const repoDir = (root, ref) => join(ref.kind === 'table' ? paths(root).databasesDir : paths(root).pipesDir, repoDirName(ref));
+/**
+ * The files of one repo.
+ *
+ * `kind` decides one name: a database's root row is `table.json`, not
+ * `pipe.json`. It is worth the parameter because a file called `pipe.json`
+ * inside `databases/` teaches a reader something false about the platform, and
+ * this workspace is read by agents that have no other source of truth.
+ *
+ * Required rather than defaulted: a caller who forgets would silently get pipe
+ * paths for a database and a mysteriously absent root file.
+ */
+export const repoPaths = (dir, kind = 'pipe') => ({
+    dir,
+    meta: join(dir, '_meta.json'),
+    repo: join(dir, kind === 'table' ? 'table.json' : 'pipe.json'),
+    /** Both spellings, so a directory can be recognised before its kind is known. */
+    repoCandidates: [join(dir, 'pipe.json'), join(dir, 'table.json')],
+    phasesDir: join(dir, 'phases'),
+    automationsDir: join(dir, 'automations'),
+    fieldConditionsDir: join(dir, 'field-conditions'),
+    labels: join(dir, 'labels.json'),
+    webhooks: join(dir, 'webhooks.json'),
+    publicForm: join(dir, 'public-form.json'),
+    preferences: join(dir, 'preferences.json'),
+    relations: join(dir, 'relations.json'),
+    readonlyDir: join(dir, '_readonly'),
+    agentsDir: join(dir, 'agents'),
+});
+/** Baseline is stored as the payload envelope: one file, and diff-ready. */
+export const baselineFile = (root, repoId) => join(paths(root).baselineDir, `${repoId}.json`);
+/**
+ * The agent baseline: what a repo's AI agents looked like at the last pull.
+ *
+ * Stored separately from the payload envelope for the same reason flows are:
+ * agents are not in it, they come from a different query, keyed by the pipe's
+ * uuid rather than its id (src/pipefy/agents.ts).
+ */
+export const agentBaselineFile = (root, repoId) => join(paths(root).baselineDir, `${repoId}.agents.json`);
+/**
+ * The flow baseline: what a repo's iPaaS flows looked like at the last pull.
+ *
+ * Stored separately from the payload envelope because flows are not in it —
+ * they come from a different endpoint. Without this the flow diff had no
+ * recorded past to compare against and had to re-read the pipe live every time,
+ * which meant no offline diff and no record of what was pulled.
+ */
+export const flowBaselineFile = (root, repoId) => join(paths(root).baselineDir, `${repoId}.flows.json`);
+export const planFile = (root, planId) => join(paths(root).plansDir, `${planId}.json`);
+/**
+ * How a finished plan is named.
+ *
+ * A plan file is the record `--resume` replays, and it is written before the
+ * first request and rewritten after every step, so a crash mid-apply is
+ * resumable. That made `.ppc/plans/` a list of filenames that all look alike,
+ * with no way to tell an applied plan from one still waiting — the outcome was
+ * only inside the JSON, or via `pipe status`.
+ *
+ * So the outcome goes in the name once the apply is over. **No suffix means it
+ * was never applied**, which is the state a bare `pipe plan` leaves behind.
+ * The plan id does not change, so every `--resume <id>` instruction still works.
+ */
+export const PLAN_SUFFIX = {
+    applied: '--applied',
+    'partially-applied': '--partial',
+    failed: '--failed',
+};
+export const planFileFor = (root, planId, status) => join(paths(root).plansDir, `${planId}${PLAN_SUFFIX[status] ?? ''}.json`);
+/**
+ * The file holding a plan, whatever it was renamed to. Returns null if there is
+ * none — the caller decides whether that is an error.
+ */
+export const findPlanFile = async (root, planId) => {
+    const { access } = await import('node:fs/promises');
+    const candidates = [planFile(root, planId), ...Object.values(PLAN_SUFFIX).map((sfx) => join(paths(root).plansDir, `${planId}${sfx}.json`))];
+    for (const c of candidates) {
+        try {
+            await access(c);
+            return c;
+        }
+        catch {
+            // try the next spelling
+        }
+    }
+    return null;
+};
+/** Paths under a repo dir that must never be edited — checked by path alone. */
+export const isReadonlyPath = (relPath) => {
+    const p = relPath.replace(/\\/g, '/');
+    return p.includes('/_readonly/') || p.startsWith('_readonly/');
+};

package/dist/workspace/lock.js

@@ -0,0 +1,83 @@
+import { relative } from 'node:path';
+import { exists, readJson, writeJson } from "../util/fsx.js";
+import { baselineFile, paths, repoDir } from "./layout.js";
+export const emptyLock = (rootRepoId, organizationId, depth) => ({
+    version: 1,
+    updatedAt: new Date().toISOString(),
+    rootRepoId,
+    organizationId,
+    depth,
+    repos: [],
+    edges: [],
+});
+export const readLock = async (root) => {
+    const p = paths(root).lock;
+    if (!(await exists(p)))
+        return null;
+    return readJson(p);
+};
+export const writeLock = async (root, lock) => {
+    lock.updatedAt = new Date().toISOString();
+    await writeJson(paths(root).lock, lock);
+};
+const identityFor = (tree) => {
+    const grab = (rows) => {
+        const out = {};
+        for (const r of rows) {
+            const uuid = r['uuid'];
+            const id = Number(r['id']);
+            if (typeof uuid === 'string' && uuid && Number.isFinite(id))
+                out[uuid] = id;
+        }
+        return out;
+    };
+    return {
+        phases: grab(tree.phases),
+        fields: grab(tree.phases.flatMap((p) => p.fields)),
+        automations: grab(tree.automations),
+        labels: grab(tree.labels),
+    };
+};
+export const upsertRepo = (lock, ref, root, tree) => {
+    const entry = {
+        kind: ref.kind,
+        id: ref.id,
+        apiId: ref.apiId,
+        uuid: tree.repo['uuid'] ?? ref.uuid ?? null,
+        name: tree.repo['name'] ?? ref.name ?? null,
+        dir: relative(root, repoDir(root, ref)).replace(/\\/g, '/'),
+        via: ref.via,
+        depth: ref.depth,
+        source: tree.meta.source,
+        versionId: tree.meta.versionId ?? null,
+        readAt: tree.meta.readAt,
+        coverage: tree.meta.coverage,
+        identity: identityFor(tree),
+        fieldSlugs: Object.fromEntries(tree.phases
+            .flatMap((p) => p.fields)
+            .filter((f) => f['slug'])
+            .map((f) => [String(f['id']), String(f['slug'])])),
+    };
+    const i = lock.repos.findIndex((r) => r.id === ref.id);
+    if (i >= 0)
+        lock.repos[i] = entry;
+    else
+        lock.repos.push(entry);
+    return entry;
+};
+export const lookupRepo = (lock, idOrName) => {
+    const byId = lock.repos.find((r) => String(r.id) === idOrName || r.apiId === idOrName);
+    if (byId)
+        return byId;
+    const needle = idOrName.toLowerCase();
+    return lock.repos.find((r) => (r.name ?? '').toLowerCase() === needle || r.dir.toLowerCase().includes(needle));
+};
+export const rootRepo = (lock) => lock.repos.find((r) => r.id === lock.rootRepoId);
+export const baselinePathFor = (root, repoId) => baselineFile(root, repoId);
+export const readWorkspace = async (root) => {
+    const p = paths(root).workspaceFile;
+    if (!(await exists(p)))
+        return null;
+    return readJson(p);
+};
+export const writeWorkspace = (root, w) => writeJson(paths(root).workspaceFile, w);

package/dist/workspace/read.js

@@ -0,0 +1,168 @@
+import { basename, dirname } from 'node:path';
+import { exists, listJson, readJson } from "../util/fsx.js";
+import { UserError } from "../util/log.js";
+import { fullCoverage } from "../model/payload.js";
+import { repoPaths } from "./layout.js";
+import { AGENT_DIR_TAG } from "./agents.js";
+/**
+ * files → tree. The exact inverse of write.ts, so that
+ * `readTree(writeTree(t)) ≡ t` and the edited workspace can be diffed against
+ * the baseline with no special cases.
+ *
+ * Ordering never comes from filenames: the index-prefixed names are for humans,
+ * and `index` inside the file is authoritative. A phase Claude renumbered by
+ * editing `index` therefore works without renaming any file.
+ */
+const num = (v) => {
+    const n = Number(v);
+    return Number.isFinite(n) ? n : 0;
+};
+/**
+ * An id, or the placeholder that stands for one, or `null` — a real jump
+ * target state (a jump slot enabled with no destination phase chosen), not
+ * an absence. Must be checked before `Number(v)`: `Number(null)` is `0`, a
+ * finite number, which would otherwise turn a null jump into a jump to
+ * phase 0 — the exact failure mode this function exists to avoid for typos
+ * and placeholders.
+ *
+ * `num` collapses anything non-numeric to 0, which is right for an index and
+ * catastrophic for an id list: a phase jumping to a phase created in the same
+ * edit is written `"%{_new:<uuid>}"`, exactly as the generated AGENTS.md
+ * instructs, and `num` turned that into a jump to phase 0 — accepted by the
+ * validator, sent to the API, and impossible to explain. A typo met the same
+ * fate. Non-numeric values are kept verbatim so the validator can judge them.
+ */
+const idOrPlaceholder = (v) => {
+    if (v === null)
+        return null;
+    const n = Number(v);
+    if (Number.isFinite(n) && v !== '')
+        return n;
+    return String(v);
+};
+const readArrayFile = async (path) => {
+    if (!(await exists(path)))
+        return [];
+    const v = await readJson(path);
+    if (v === null)
+        return [];
+    if (!Array.isArray(v))
+        throw new UserError(`${path}: expected a JSON array`);
+    return v;
+};
+const readObjectFile = async (path) => {
+    if (!(await exists(path)))
+        return null;
+    const v = await readJson(path);
+    if (v === null)
+        return null;
+    if (typeof v !== 'object' || Array.isArray(v))
+        throw new UserError(`${path}: expected a JSON object or null`);
+    return v;
+};
+const readDirOf = async (dir) => {
+    const files = (await listJson(dir)).filter((f) => basename(f) !== '_meta.json');
+    const out = [];
+    for (const f of files)
+        out.push({ path: f, value: await readJson(f) });
+    return out;
+};
+export const readTree = async (dir) => {
+    /**
+     * The kind comes from `_meta.json`, which is written first and whose path does
+     * not depend on the kind. Falling back to probing both spellings keeps a
+     * hand-made directory readable.
+     */
+    const meta = ((await readObjectFile(repoPaths(dir).meta)) ?? {});
+    const p = repoPaths(dir, meta.repoKind === 'table' ? 'table' : 'pipe');
+    let repoFile = p.repo;
+    if (!(await exists(repoFile))) {
+        const found = [];
+        for (const c of p.repoCandidates)
+            if (await exists(c))
+                found.push(c);
+        if (!found.length) {
+            throw new UserError(`${dir} is not a pulled repo directory (no pipe.json or table.json)`);
+        }
+        repoFile = found[0];
+    }
+    const repo = (await readObjectFile(repoFile)) ?? {};
+    const phaseFiles = await readDirOf(p.phasesDir);
+    const phases = phaseFiles
+        .map(({ path, value }) => {
+        if (!value || typeof value !== 'object')
+            throw new UserError(`${path}: expected a phase object`);
+        return {
+            ...value,
+            fields: Array.isArray(value.fields) ? value.fields : [],
+            jump_target_ids: Array.isArray(value.jump_target_ids) ? value.jump_target_ids.map(idOrPlaceholder) : [],
+            team_member_ids: Array.isArray(value.team_member_ids) ? value.team_member_ids.map(idOrPlaceholder) : [],
+        };
+    })
+        .sort((a, b) => num(a['index']) - num(b['index']) || num(a['id']) - num(b['id']));
+    const normaliseAutomation = (path, value) => {
+        if (!value || typeof value !== 'object')
+            throw new UserError(`${path}: expected an automation object`);
+        const v = value;
+        return {
+            ...v,
+            condition: v.condition ?? null,
+            field_maps: Array.isArray(v.field_maps) ? v.field_maps : [],
+            distribute_assignments: Array.isArray(v.distribute_assignments) ? v.distribute_assignments : [],
+            response_schemas: Array.isArray(v.response_schemas) ? v.response_schemas : [],
+        };
+    };
+    const automations = (await readDirOf(p.automationsDir)).map(({ path, value }) => normaliseAutomation(path, value));
+    /**
+     * A behavior — an automation folded under its agent's `behaviors/` instead
+     * of `automations/`, per workspace/agents.ts. `_agent_dir` is not read from
+     * the file (it is never written there); it is derived from where the file
+     * physically is, which is the only record of the link there is.
+     */
+    for (const path of await listJson(p.agentsDir)) {
+        if (basename(dirname(path)) !== 'behaviors')
+            continue;
+        const agentDir = basename(dirname(dirname(path)));
+        const value = await readJson(path);
+        automations.push({ ...normaliseAutomation(path, value), [AGENT_DIR_TAG]: agentDir });
+    }
+    const field_conditions = (await readDirOf(p.fieldConditionsDir))
+        .map(({ path, value }) => {
+        if (!value || typeof value !== 'object')
+            throw new UserError(`${path}: expected a field condition object`);
+        return {
+            ...value,
+            actions: Array.isArray(value.actions) ? value.actions : [],
+            condition: value.condition ?? null,
+        };
+    })
+        .sort((a, b) => num(a['index']) - num(b['index']) || num(a['id']) - num(b['id']));
+    const relationsFile = (await readObjectFile(p.relations)) ?? {};
+    const pipe_relations = Array.isArray(relationsFile['pipe_relations']) ? relationsFile['pipe_relations'] : [];
+    return {
+        meta: {
+            source: meta.source ?? 'reconstructed',
+            versionId: meta.versionId ?? null,
+            readAt: meta.readAt ?? new Date().toISOString(),
+            repoKind: meta.repoKind ?? 'pipe',
+            coverage: meta.coverage ?? fullCoverage('unknown'),
+            repo_columns: meta.repo_columns ?? 'complete',
+            notes: meta.notes ?? [],
+        },
+        repo,
+        phases,
+        automations,
+        field_conditions,
+        labels: await readArrayFile(p.labels),
+        webhooks: await readArrayFile(p.webhooks),
+        pipe_relations,
+        public_form: await readObjectFile(p.publicForm),
+        preferences: await readObjectFile(p.preferences),
+        readonly: {
+            email_templates: await readArrayFile(`${p.readonlyDir}/email-templates.json`),
+            email_inboxes: await readArrayFile(`${p.readonlyDir}/email-inboxes.json`),
+            visibilities: await readArrayFile(`${p.readonlyDir}/visibilities.json`),
+            field_maps: await readArrayFile(`${p.readonlyDir}/field-maps.json`),
+        },
+    };
+};

package/dist/workspace/reference.js

@@ -0,0 +1,24 @@
+import { readFile } from 'node:fs/promises';
+import { paths } from "./layout.js";
+import { debug } from "../util/log.js";
+/**
+ * Load the cached closed sets, or null.
+ *
+ * Null on anything: no file, unreadable, malformed. Every consumer treats null
+ * as "these checks are skipped" and never as "this value is fine", so a
+ * workspace pulled by an older build loses the check rather than gaining a
+ * wrong answer.
+ */
+export const loadReference = async (root) => {
+    try {
+        const raw = await readFile(paths(root).reference, 'utf8');
+        const ref = JSON.parse(raw);
+        if (!ref || typeof ref !== 'object' || !Array.isArray(ref.events))
+            return null;
+        return ref;
+    }
+    catch (e) {
+        debug(`no cached reference: ${e.message}`);
+        return null;
+    }
+};