@ifc-lite/cli 0.33.1 → 0.34.0

package/README.md

@@ -32,7 +32,7 @@ pending generic mutation overlays are not included until reload.
 - `info` - model summary: schema, entities, storeys
 - `query` - query entities by type, properties, quantities; supports `--sum`, `--group-by`, `--spatial`
 - `props` - all properties for a single entity (`--id N`)
-- `export` - export to `csv`, `json`, `ifc`, or `hbjson`
+- `export` - export to `csv`, `json`, `ifc`, `obj`, `gltf`, `glb`, `jsonld`, `ifcx`, `usd`, `step`, `hbjson`, or `dfjson`
 - `ids` - validate against buildingSMART IDS rules
 - `validate` - structural validation checks
 - `stats` - auto-calculated model KPIs and health check
@@ -43,11 +43,18 @@ pending generic mutation overlays are not included until reload.
 - `merge` - merge multiple IFC files into one federated file
 - `convert` - convert between IFC schema versions (`--schema IFC4`)
 - `diff` - compare two IFC files
+- `rekey` - carry a table keyed on old element keys across a revision
 - `eval` / `run` - run SDK expressions or scripts against a model
 - `ask` - natural language BIM queries
 - `view` - interactive 3D viewer in the browser, controllable via REST (`/api/command`)
 - `analyze` - query plus colorize/isolate/heatmap results in the running viewer
+- `simplify` - demesher: simplify meshes, write a lighter IFC
 - `mcp` - start an MCP server bound to one or more IFC files (stdio or http)
+- `layer` - layered change tracking over a local store (`.ifc-lite/`)
+- `ref` - manage named refs in the layer store
+- `anonymize` - export selected objects + context as an anonymized IFC
+- `schedule` - tabular schedule of one class (csv/json/md/html)
+- `delivery` - repeatable delivery check (structural + IDS) from a saved recipe
 - `gym` - reset/step/reward environment loop over the existing schema/clash/ids checks (see below)
 - `schema`, `bsdd`, `diagnose-geometry`, `extract-entities`, `generate-spaces`, `lod`, `ext` - see `ifc-lite --help`
 

package/dist/commands/diff-content-io.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Refuse to run at all if `--identity-out` names one of the two input models.
+ *
+ * The sidecar is a JSON document. Writing it over an IFC file destroys the
+ * user's model, and a mistyped or shell-completed path is all it takes — the
+ * two arguments right before it are IFC paths. So this is checked first, and
+ * the command exits without reading, comparing, or writing anything.
+ *
+ * Two independent tests, because a path string is not a file:
+ *
+ * 1. Resolved paths are equal. Catches `./v1.ifc` vs `v1.ifc` vs `sub/../v1.ifc`
+ *    with no filesystem access, and is the whole answer on a platform where
+ *    `stat` reports no usable inode.
+ * 2. The output already exists AND is the same file as an input, by device +
+ *    inode. This is the exhaustive test: it catches a symlink, a hard link, a
+ *    bind mount, and `V1.IFC` on a case-insensitive filesystem — every way two
+ *    different strings can name one file. It is also sufficient on its own for
+ *    the destructive case, because a path that does not resolve to an existing
+ *    file cannot be overwriting an input: the inputs must exist to be read.
+ *
+ * `--identity-in` and `--identity-out` naming the SAME sidecar is not checked
+ * here, because that is the carry-forward workflow this feature is built around
+ * (read the accepted claims, write back the ones that still held).
+ */
+export declare function refuseOverwritingAnInput(options: {
+    basePath: string;
+    headPath: string;
+    identityOut?: string;
+    lineageOut?: string;
+}): Promise<void>;
+/**
+ * Read one of the two input models, reporting a missing or unreadable path the
+ * way the rest of the command reports problems rather than throwing a raw
+ * `ENOENT` stack at the user — the same treatment `readVerifiedSidecar` gives
+ * the sidecar.
+ */
+export declare function readModel(path: string): Promise<Uint8Array>;
+/**
+ * Unwrap a possible `.ifcZIP` container into its STEP bytes, reporting a
+ * corrupt zip the way the rest of the command reports problems (see
+ * {@link readModel}) rather than throwing a raw error. Ordinary `.ifc` bytes
+ * pass through unchanged (cheap magic-byte check — `unwrapIfcZipView`).
+ *
+ * Called once per file and the result reused by both the parser and (when
+ * `--geometry` runs) the wasm mesh pass — passing the ORIGINAL, possibly
+ * zipped bytes to the mesh pass would feed it a zip container instead of STEP
+ * text (issue #4956 review).
+ */
+export declare function unwrapModel(bytes: Uint8Array, label: string): Promise<Uint8Array>;
+//# sourceMappingURL=diff-content-io.d.ts.map

package/dist/commands/diff-content-io.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff-content-io.d.ts","sourceRoot":"","sources":["../../src/commands/diff-content-io.ts"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,wBAAwB,CAAC,OAAO,EAAE;IACtD,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG,OAAO,CAAC,IAAI,CAAC,CAmBhB;AAgBD;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAMjE;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,WAAW,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAMvF"}

package/dist/commands/diff-content-io.js

@@ -0,0 +1,104 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+/**
+ * File-level I/O for `ifc-lite diff --by-content`: reading the two input
+ * models (and unwrapping a possible `.ifcZIP` container), and refusing to run
+ * at all when an output path would overwrite one of them. Split out of
+ * `diff-content.ts` for size.
+ */
+import { readFile, stat } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { unwrapIfcZipView } from '@ifc-lite/parser';
+import { fatal } from '../output.js';
+/**
+ * Refuse to run at all if `--identity-out` names one of the two input models.
+ *
+ * The sidecar is a JSON document. Writing it over an IFC file destroys the
+ * user's model, and a mistyped or shell-completed path is all it takes — the
+ * two arguments right before it are IFC paths. So this is checked first, and
+ * the command exits without reading, comparing, or writing anything.
+ *
+ * Two independent tests, because a path string is not a file:
+ *
+ * 1. Resolved paths are equal. Catches `./v1.ifc` vs `v1.ifc` vs `sub/../v1.ifc`
+ *    with no filesystem access, and is the whole answer on a platform where
+ *    `stat` reports no usable inode.
+ * 2. The output already exists AND is the same file as an input, by device +
+ *    inode. This is the exhaustive test: it catches a symlink, a hard link, a
+ *    bind mount, and `V1.IFC` on a case-insensitive filesystem — every way two
+ *    different strings can name one file. It is also sufficient on its own for
+ *    the destructive case, because a path that does not resolve to an existing
+ *    file cannot be overwriting an input: the inputs must exist to be read.
+ *
+ * `--identity-in` and `--identity-out` naming the SAME sidecar is not checked
+ * here, because that is the carry-forward workflow this feature is built around
+ * (read the accepted claims, write back the ones that still held).
+ */
+export async function refuseOverwritingAnInput(options) {
+    for (const [flag, target] of [
+        ['--identity-out', options.identityOut],
+        ['--lineage-out', options.lineageOut],
+    ]) {
+        if (target === undefined)
+            continue;
+        const out = resolve(target);
+        const outStat = await statOrUndefined(target);
+        for (const [label, input] of [
+            ['base model', options.basePath],
+            ['head model', options.headPath],
+        ]) {
+            if (resolve(input) !== out && !isSameFile(outStat, await statOrUndefined(input)))
+                continue;
+            fatal(`${flag} ${target} is the ${label} (${input}). ` +
+                'Writing there would overwrite the input file.');
+        }
+    }
+}
+async function statOrUndefined(path) {
+    // A missing or unreadable path cannot be an input file being overwritten;
+    // reading the models is what reports it, with its own message.
+    try {
+        return await stat(path);
+    }
+    catch {
+        return undefined;
+    }
+}
+function isSameFile(a, b) {
+    return a !== undefined && b !== undefined && a.dev === b.dev && a.ino === b.ino;
+}
+/**
+ * Read one of the two input models, reporting a missing or unreadable path the
+ * way the rest of the command reports problems rather than throwing a raw
+ * `ENOENT` stack at the user — the same treatment `readVerifiedSidecar` gives
+ * the sidecar.
+ */
+export async function readModel(path) {
+    try {
+        return await readFile(path);
+    }
+    catch (error) {
+        return fatal(`Cannot read ${path}: ${error.message}`);
+    }
+}
+/**
+ * Unwrap a possible `.ifcZIP` container into its STEP bytes, reporting a
+ * corrupt zip the way the rest of the command reports problems (see
+ * {@link readModel}) rather than throwing a raw error. Ordinary `.ifc` bytes
+ * pass through unchanged (cheap magic-byte check — `unwrapIfcZipView`).
+ *
+ * Called once per file and the result reused by both the parser and (when
+ * `--geometry` runs) the wasm mesh pass — passing the ORIGINAL, possibly
+ * zipped bytes to the mesh pass would feed it a zip container instead of STEP
+ * text (issue #4956 review).
+ */
+export async function unwrapModel(bytes, label) {
+    try {
+        return new Uint8Array(await unwrapIfcZipView(bytes));
+    }
+    catch (error) {
+        return fatal(`Cannot read ${label}: ${error.message}`);
+    }
+}
+//# sourceMappingURL=diff-content-io.js.map

package/dist/commands/diff-content-io.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff-content-io.js","sourceRoot":"","sources":["../../src/commands/diff-content-io.ts"],"names":[],"mappings":"AAAA;;+DAE+D;AAE/D;;;;;GAKG;AAEH,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAAC,OAK9C;IACC,KAAK,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI;QAC3B,CAAC,gBAAgB,EAAE,OAAO,CAAC,WAAW,CAAC;QACvC,CAAC,eAAe,EAAE,OAAO,CAAC,UAAU,CAAC;KAC7B,EAAE,CAAC;QACX,IAAI,MAAM,KAAK,SAAS;YAAE,SAAS;QACnC,MAAM,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;QAC5B,MAAM,OAAO,GAAG,MAAM,eAAe,CAAC,MAAM,CAAC,CAAC;QAC9C,KAAK,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI;YAC3B,CAAC,YAAY,EAAE,OAAO,CAAC,QAAQ,CAAC;YAChC,CAAC,YAAY,EAAE,OAAO,CAAC,QAAQ,CAAC;SACxB,EAAE,CAAC;YACX,IAAI,OAAO,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,MAAM,eAAe,CAAC,KAAK,CAAC,CAAC;gBAAE,SAAS;YAC3F,KAAK,CACH,GAAG,IAAI,IAAI,MAAM,WAAW,KAAK,KAAK,KAAK,KAAK;gBAC9C,+CAA+C,CAClD,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC;AAED,KAAK,UAAU,eAAe,CAAC,IAAY;IACzC,0EAA0E;IAC1E,+DAA+D;IAC/D,IAAI,CAAC;QACH,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,SAAS,UAAU,CAAC,CAAoB,EAAE,CAAoB;IAC5D,OAAO,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC;AAClF,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,IAAY;IAC1C,IAAI,CAAC;QACH,OAAO,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,KAAK,CAAC,eAAe,IAAI,KAAM,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;IACnE,CAAC;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,KAAiB,EAAE,KAAa;IAChE,IAAI,CAAC;QACH,OAAO,IAAI,UAAU,CAAC,MAAM,gBAAgB,CAAC,KAAK,CAAC,CAAC,CAAC;IACvD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,KAAK,CAAC,eAAe,KAAK,KAAM,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;IACpE,CAAC;AACH,CAAC"}

package/dist/commands/diff-content-report.d.ts

@@ -0,0 +1,23 @@
+/** The human-readable report of `ifc-lite diff --by-content`; the JSON form
+ *  lives with the command in `diff-content.ts`. Split out for size. */
+import type { IdentityMapEntry, LineageEntry, ModelDiff } from '@ifc-lite/diff';
+import type { DiffRef } from './diff-engine.js';
+export declare function printReport(report: {
+    basePath: string;
+    headPath: string;
+    diff: ModelDiff<DiffRef>;
+    appliedCount: number;
+    ignoredCount: number;
+    identityIn?: string;
+    written?: {
+        path: string;
+        entries: IdentityMapEntry[];
+    };
+    lineageIn?: string;
+    lineageWritten?: {
+        path: string;
+        entries: LineageEntry[];
+    };
+    keyProperty?: string;
+}): void;
+//# sourceMappingURL=diff-content-report.d.ts.map

package/dist/commands/diff-content-report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff-content-report.d.ts","sourceRoot":"","sources":["../../src/commands/diff-content-report.ts"],"names":[],"mappings":"AAIA;uEACuE;AAEvE,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAEhD,wBAAgB,WAAW,CAAC,MAAM,EAAE;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,SAAS,CAAC,OAAO,CAAC,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,gBAAgB,EAAE,CAAA;KAAE,CAAC;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,YAAY,EAAE,CAAA;KAAE,CAAC;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG,IAAI,CAsEP"}

package/dist/commands/diff-content-report.js

@@ -0,0 +1,67 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+export function printReport(report) {
+    const { diff } = report;
+    const out = (line) => {
+        process.stdout.write(`${line}\n`);
+    };
+    out('');
+    out(`  Base: ${report.basePath}`);
+    out(`  Head: ${report.headPath}`);
+    out(`  Scope: ${diff.scope}` +
+        (diff.scope === 'data' ? ' (pass --geometry for world geometry hashes + boxes)' : ''));
+    if (report.keyProperty)
+        out(`  Key:   ${report.keyProperty} (GlobalId where absent)`);
+    out('');
+    out(`  Unchanged: ${diff.counts.unchanged}`);
+    out(`  Modified:  ${diff.counts.modified}`);
+    out(`  Added:     ${diff.counts.added}`);
+    out(`  Deleted:   ${diff.counts.deleted}`);
+    const byKind = new Map();
+    for (const match of diff.contentMatches ?? []) {
+        byKind.set(match.kind, (byKind.get(match.kind) ?? 0) + 1);
+    }
+    out('');
+    if (byKind.size === 0) {
+        out('  Content matches: none');
+    }
+    else {
+        out('  Content matches:');
+        for (const [kind, count] of [...byKind].sort()) {
+            out(`    ${kind.padEnd(13)} ${count}`);
+        }
+        out('    (renamed / moved / reshaped / respecified are resolved; the rest need a human)');
+    }
+    if (diff.splitMerges) {
+        out('');
+        out(diff.splitMerges.length === 0
+            ? '  Split/merge claims: none'
+            : `  Split/merge claims: ${diff.splitMerges.length}`);
+    }
+    if (diff.successors) {
+        out('');
+        out(diff.successors.length === 0
+            ? '  Successor claims: none'
+            : `  Successor claims: ${diff.successors.length} (suggestions — review before accepting)`);
+    }
+    if (report.identityIn) {
+        out('');
+        out(`  Identity map in:  ${report.identityIn}`);
+        out(`    applied: ${report.appliedCount}, ignored: ${report.ignoredCount}`);
+    }
+    if (report.written) {
+        out('');
+        out(`  Identity map out: ${report.written.path} (${report.written.entries.length} claims)`);
+    }
+    if (report.lineageIn) {
+        out('');
+        out(`  Lineage in:  ${report.lineageIn}`);
+    }
+    if (report.lineageWritten) {
+        out('');
+        out(`  Lineage out: ${report.lineageWritten.path} (${report.lineageWritten.entries.length} entries)`);
+    }
+    out('');
+}
+//# sourceMappingURL=diff-content-report.js.map

package/dist/commands/diff-content-report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff-content-report.js","sourceRoot":"","sources":["../../src/commands/diff-content-report.ts"],"names":[],"mappings":"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"}

package/dist/commands/diff-content.d.ts

@@ -5,6 +5,25 @@ export interface ContentDiffOptions {
     identityIn?: string;
     /** `--identity-out`: where to write the sidecar this run establishes. */
     identityOut?: string;
+    /** `--lineage-in`: a lineage whose 1:1 entries are replayed as key aliases. */
+    lineageIn?: string;
+    /** `--lineage-out`: where to write the lineage this run establishes. */
+    lineageOut?: string;
+    /** `--accept`: a reviewed identity map folded into the lineage as `replaced`. */
+    accept?: string;
+    /** `--key-from`: `Tag` or `Pset.Prop`, the authored key to compare on. */
+    keyFrom?: string;
+    /** `--geometry`: run the wasm mesh pass and attach world geometry hashes,
+     *  boxes and volumes, promoting the comparison from `data` to `both`
+     *  scope (issue #4956). Skips with a stderr warning, not a fatal error,
+     *  when the wasm runtime is not built on this host. */
+    geometry?: boolean;
+    /** `--split-merge`: opt in to the split/merge detector. Only produces
+     *  claims together with `--geometry` (issue #4956). */
+    splitMerge?: boolean;
+    /** `--successors`: opt in to the successor-match detector. Only produces
+     *  claims together with `--geometry` (issue #4956). */
+    successors?: boolean;
     json: boolean;
 }
 export declare function contentDiffCommand(options: ContentDiffOptions): Promise<void>;

package/dist/commands/diff-content.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"diff-content.d.ts","sourceRoot":"","sources":["../../src/commands/diff-content.ts"],"names":[],"mappings":"AAmCA,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,OAAO,CAAC;CACf;AAED,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAqFnF"}
+{"version":3,"file":"diff-content.d.ts","sourceRoot":"","sources":["../../src/commands/diff-content.ts"],"names":[],"mappings":"AA6DA,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iFAAiF;IACjF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;2DAGuD;IACvD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;2DACuD;IACvD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;2DACuD;IACvD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,IAAI,EAAE,OAAO,CAAC;CACf;AAED,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CA8LnF"}

package/dist/commands/diff-content.js

@@ -8,37 +8,99 @@
  * The loop this closes: run it once, review the `renamed` matches, keep the
  * sidecar. On the next run the accepted claims come back in as key aliases, the
  * re-GUIDed elements are matched by key, and they never show up as churn again.
- * See `diff-engine.ts` for why this path is data-scope only.
+ * Data scope by default — see `diff-engine.ts`; `--geometry` below opts into
+ * the wasm mesh pass.
+ *
+ * Issue #4955 adds three things on the same loop: `--key-from` keys the
+ * comparison on an authored identifier instead of GlobalId; `--lineage-out` /
+ * `--lineage-in` write and replay the 1:k lineage an external table rekeys on;
+ * and `--accept` folds a reviewed identity map (a human's answer to the
+ * suggestions a geometry-capable run produced) into that lineage as
+ * `replaced` entries.
+ *
+ * Issue #4956 adds `--geometry`: a lazily-loaded `@ifc-lite/wasm` mesh pass
+ * (`diff-geometry.ts`) that attaches world geometry hashes, bounding boxes and
+ * volumes to both files' fingerprints, promoting the scope from `data` to
+ * `both`. `--split-merge` / `--successors` turn on the two geometry-only
+ * detection stages; both are no-ops without `--geometry` (the engine abstains
+ * exactly as it does for a viewer session whose geometry hashing failed).
  */
-import { readFile, stat, writeFile } from 'node:fs/promises';
-import { resolve } from 'node:path';
-import { createIdentityMapSidecar, diffModels, identityMapFromContentMatches, identityMapSidecarMismatches, keyAliasesFromSidecar, parseIdentityMapSidecar, serializeIdentityMapSidecar, } from '@ifc-lite/diff';
+import { readFile, writeFile } from 'node:fs/promises';
+import { createIdentityMapSidecar, createLineageSidecar, diffModels, identityMapFromContentMatches, identityMapSidecarMismatches, keyAliasesFromLineage, keyAliasesFromSidecar, parseIdentityMapSidecar, serializeIdentityMapSidecar, serializeLineageSidecar, } from '@ifc-lite/diff';
+import { parseAuthoredKeySpec } from '@ifc-lite/parser';
 import { loadIfcBytes } from '../loader.js';
 import { fatal, printJson } from '../output.js';
-import { buildFileFingerprints, modelIdentityOf } from './diff-engine.js';
+import { buildFileFingerprints, fallbackPairDuplicateAuthoredKeys, modelIdentityOf, } from './diff-engine.js';
+import { readModel, refuseOverwritingAnInput, unwrapModel } from './diff-content-io.js';
+import { resolveGeometryScope } from './diff-geometry.js';
+import { mergeAliases, mergeLineage, readVerifiedLineage } from './diff-lineage-io.js';
+import { printReport } from './diff-content-report.js';
 export async function contentDiffCommand(options) {
     const { basePath, headPath } = options;
+    const keySpec = options.keyFrom === undefined ? undefined : parseAuthoredKeySpec(options.keyFrom);
+    if (options.keyFrom !== undefined && !keySpec) {
+        fatal(`--key-from must be Tag or <PsetName>.<PropertyName>, got "${options.keyFrom}"`);
+    }
+    // `Tag` is case-insensitive at the CLI boundary, but the persisted sidecar
+    // contract is canonical and shared with the viewer's compare UI.
+    const keyProperty = keySpec?.kind === 'tag' ? 'Tag' : options.keyFrom?.trim();
     // Before anything is read, and long before anything is written.
     await refuseOverwritingAnInput(options);
     const baseBytes = await readModel(basePath);
     const headBytes = await readModel(headPath);
+    // The identity hash is over the file AS IT SITS ON DISK, before any
+    // `.ifcZIP` unwrapping (see `modelIdentityOf`) — so it is taken from the raw
+    // bytes, and the unwrap below is a separate step, not folded into this read.
     const baseIdentity = modelIdentityOf(basePath, baseBytes);
     const headIdentity = modelIdentityOf(headPath, headBytes);
+    const pinned = { base: baseIdentity, head: headIdentity, keyProperty };
     const incoming = options.identityIn
-        ? await readVerifiedSidecar(options.identityIn, baseIdentity, headIdentity)
+        ? await readVerifiedSidecar(options.identityIn, pinned)
         : undefined;
+    const incomingLineage = options.lineageIn
+        ? await readVerifiedLineage(options.lineageIn, pinned)
+        : undefined;
+    const accepted = options.accept ? await readVerifiedSidecar(options.accept, pinned) : undefined;
+    // Unwrapped ONCE and reused by both the parser and (if `--geometry` runs)
+    // the wasm mesh pass — `unwrapIfcZipView` is a cheap magic-byte no-op for an
+    // ordinary `.ifc` file, so a `--geometry` run over a `.ifcZIP` still sees the
+    // real STEP bytes rather than the zip container (issue #4956 review).
+    const baseUnwrapped = await unwrapModel(baseBytes, basePath);
+    const headUnwrapped = await unwrapModel(headBytes, headPath);
     process.stderr.write('Loading files...\n');
-    const baseStore = await loadIfcBytes(baseBytes, basePath);
-    const headStore = await loadIfcBytes(headBytes, headPath);
-    const diff = diffModels(buildFileFingerprints(baseStore), buildFileFingerprints(headStore), {
-        // No meshes in Node: `data` is the honest description of what this path can
-        // compare. See diff-engine.ts.
-        scope: 'data',
+    const baseStore = await loadIfcBytes(baseUnwrapped, basePath);
+    const headStore = await loadIfcBytes(headUnwrapped, headPath);
+    const duplicateAuthoredKeys = new Map();
+    const adapter = { keyProperty, duplicateAuthoredKeys };
+    const baseFingerprints = buildFileFingerprints(baseStore, adapter);
+    const headFingerprints = buildFileFingerprints(headStore, adapter);
+    fallbackPairDuplicateAuthoredKeys([
+        { fingerprints: baseFingerprints, store: baseStore },
+        { fingerprints: headFingerprints, store: headStore },
+    ], duplicateAuthoredKeys);
+    for (const [value, ids] of duplicateAuthoredKeys) {
+        process.stderr.write(`Warning: ${keyProperty} = "${value}" names ${ids.length} entities; they fall back to GlobalId.\n`);
+    }
+    // Both sources of aliases are replayed together. A lineage's 1:1 entries and
+    // an identity map's claims are the same kind of thing under two file formats;
+    // where the two disagree about one head key, neither is applied — that is
+    // `resolveKeyAliases` rule 4, arriving from two files instead of one.
+    const aliases = mergeAliases(incoming ? keyAliasesFromSidecar(incoming) : undefined, incomingLineage ? keyAliasesFromLineage(incomingLineage.entries) : undefined);
+    // `--geometry` (issue #4956): see `diff-geometry.ts` for the wasm pass and
+    // the graceful fall-back to `scope: 'data'` when the runtime is absent.
+    const scope = await resolveGeometryScope(options.geometry ?? false, baseUnwrapped, headUnwrapped, baseFingerprints, headFingerprints, (message) => process.stderr.write(`Warning: ${message}\n`));
+    const diff = diffModels(baseFingerprints, headFingerprints, {
+        scope,
         matchUnpairedByContent: true,
-        keyAliases: incoming ? keyAliasesFromSidecar(incoming) : undefined,
+        keyAliases: aliases,
+        // Both are geometry-only stages (issue #4956): with no geometry pass run,
+        // the engine abstains and `diff.splitMerges` / `diff.successors` stay
+        // undefined, exactly as a viewer session with failed geometry hashing.
+        detectSplitMerge: options.splitMerge,
+        detectSuccessors: options.successors,
     });
     const applied = diff.appliedKeyAliases ?? new Map();
-    const ignored = incoming ? countClaims(incoming) - applied.size : 0;
+    const ignored = aliases ? aliases.size - applied.size : 0;
     let written;
     if (options.identityOut) {
         const entries = mergeIdentityClaims(incoming, applied, diff.contentMatches);
@@ -59,10 +121,25 @@ export async function contentDiffCommand(options) {
             // optional, and `git log` dates a reviewed, committed artifact better
             // than a self-reported timestamp does.
             created: incoming?.created,
+            keyProperty,
         });
         await writeFile(options.identityOut, serializeIdentityMapSidecar(sidecar), 'utf-8');
         written = { path: options.identityOut, entries: sidecar.entries };
     }
+    let lineageWritten;
+    if (options.lineageOut) {
+        const { entries, deleted } = mergeLineage(incomingLineage, incoming, diff, accepted);
+        const sidecar = createLineageSidecar({
+            base: baseIdentity,
+            head: headIdentity,
+            entries,
+            deleted,
+            created: incomingLineage?.created,
+            keyProperty,
+        });
+        await writeFile(options.lineageOut, serializeLineageSidecar(sidecar), 'utf-8');
+        lineageWritten = { path: options.lineageOut, entries: sidecar.entries };
+    }
     if (options.json) {
         printJson({
             base: { path: basePath, hash: baseIdentity.hash, schema: baseStore.schemaVersion },
@@ -74,12 +151,36 @@ export async function contentDiffCommand(options) {
                 base: match.base.map((entity) => entity.key),
                 head: match.head.map((entity) => entity.key),
             })),
+            // Absent (not `[]`) exactly when the stage did not run or the geometry
+            // abstention fired — the engine's own "absent means not proved"
+            // contract, preserved rather than flattened to an empty array.
+            splitMerges: diff.splitMerges?.map((claim) => ({
+                kind: claim.kind,
+                confidence: claim.confidence,
+                whole: claim.whole.key,
+                pieces: claim.pieces.map((piece) => piece.key),
+            })),
+            successors: diff.successors?.map((claim) => ({
+                confidence: claim.confidence,
+                base: claim.base.key,
+                head: claim.head.key,
+                overlap: claim.overlap,
+                distance: claim.distance,
+            })),
             identityMap: {
                 in: options.identityIn
                     ? { path: options.identityIn, applied: applied.size, ignored }
                     : undefined,
                 out: written ? { path: written.path, entries: written.entries.length } : undefined,
             },
+            lineage: {
+                in: options.lineageIn ? { path: options.lineageIn } : undefined,
+                out: lineageWritten
+                    ? { path: lineageWritten.path, entries: lineageWritten.entries.length }
+                    : undefined,
+            },
+            keyProperty: keyProperty ?? null,
+            duplicateAuthoredKeys: [...duplicateAuthoredKeys.keys()],
         });
         return;
     }
@@ -91,75 +192,11 @@ export async function contentDiffCommand(options) {
         ignoredCount: ignored,
         identityIn: options.identityIn,
         written,
+        lineageIn: options.lineageIn,
+        lineageWritten,
+        keyProperty,
     });
 }
-/**
- * Refuse to run at all if `--identity-out` names one of the two input models.
- *
- * The sidecar is a JSON document. Writing it over an IFC file destroys the
- * user's model, and a mistyped or shell-completed path is all it takes — the
- * two arguments right before it are IFC paths. So this is checked first, and
- * the command exits without reading, comparing, or writing anything.
- *
- * Two independent tests, because a path string is not a file:
- *
- * 1. Resolved paths are equal. Catches `./v1.ifc` vs `v1.ifc` vs `sub/../v1.ifc`
- *    with no filesystem access, and is the whole answer on a platform where
- *    `stat` reports no usable inode.
- * 2. The output already exists AND is the same file as an input, by device +
- *    inode. This is the exhaustive test: it catches a symlink, a hard link, a
- *    bind mount, and `V1.IFC` on a case-insensitive filesystem — every way two
- *    different strings can name one file. It is also sufficient on its own for
- *    the destructive case, because a path that does not resolve to an existing
- *    file cannot be overwriting an input: the inputs must exist to be read.
- *
- * `--identity-in` and `--identity-out` naming the SAME sidecar is not checked
- * here, because that is the carry-forward workflow this feature is built around
- * (read the accepted claims, write back the ones that still held).
- */
-async function refuseOverwritingAnInput(options) {
-    const { identityOut } = options;
-    if (identityOut === undefined)
-        return;
-    const out = resolve(identityOut);
-    const outStat = await statOrUndefined(identityOut);
-    for (const [label, input] of [
-        ['base model', options.basePath],
-        ['head model', options.headPath],
-    ]) {
-        if (resolve(input) !== out && !isSameFile(outStat, await statOrUndefined(input)))
-            continue;
-        fatal(`--identity-out ${identityOut} is the ${label} (${input}). ` +
-            'Writing the identity map there would overwrite the input file.');
-    }
-}
-async function statOrUndefined(path) {
-    // A missing or unreadable path cannot be an input file being overwritten;
-    // reading the models is what reports it, with its own message.
-    try {
-        return await stat(path);
-    }
-    catch {
-        return undefined;
-    }
-}
-function isSameFile(a, b) {
-    return a !== undefined && b !== undefined && a.dev === b.dev && a.ino === b.ino;
-}
-/**
- * Read one of the two input models, reporting a missing or unreadable path the
- * way the rest of the command reports problems rather than throwing a raw
- * `ENOENT` stack at the user — the same treatment `readVerifiedSidecar` already
- * gives the sidecar.
- */
-async function readModel(path) {
-    try {
-        return await readFile(path);
-    }
-    catch (error) {
-        return fatal(`Cannot read ${path}: ${error.message}`);
-    }
-}
 /**
  * Read a sidecar and refuse it unless it was verified against exactly these two
  * files.
@@ -171,7 +208,7 @@ async function readModel(path) {
  * deliberately no override flag: the fix for a mismatch is to re-run the
  * comparison that produced the claims, which is one command.
  */
-async function readVerifiedSidecar(path, base, head) {
+async function readVerifiedSidecar(path, models) {
     let text;
     try {
         text = await readFile(path, 'utf-8');
@@ -186,18 +223,12 @@ async function readVerifiedSidecar(path, base, head) {
     catch (error) {
         return fatal(error.message);
     }
-    const problems = identityMapSidecarMismatches(sidecar, { base, head });
+    const problems = identityMapSidecarMismatches(sidecar, models);
     if (problems.length > 0) {
         return fatal(`Identity map ${path} was not verified against these files:\n  ${problems.join('\n  ')}`);
     }
     return sidecar;
 }
-/** Distinct head keys a sidecar actually claims (self-claims and repeats are
- *  no-ops the consumer drops, so counting raw entries would overstate what
- *  could have applied). */
-function countClaims(sidecar) {
-    return keyAliasesFromSidecar(sidecar).size;
-}
 /**
  * The claims the output sidecar should carry: the incoming ones that still
  * applied, plus the ones this run's content matching established.
@@ -227,44 +258,4 @@ function mergeIdentityClaims(incoming, applied, matches) {
     entries.push(...identityMapFromContentMatches(matches));
     return entries;
 }
-function printReport(report) {
-    const { diff } = report;
-    const out = (line) => {
-        process.stdout.write(`${line}\n`);
-    };
-    out('');
-    out(`  Base: ${report.basePath}`);
-    out(`  Head: ${report.headPath}`);
-    out(`  Scope: data (the CLI has no geometry pipeline)`);
-    out('');
-    out(`  Unchanged: ${diff.counts.unchanged}`);
-    out(`  Modified:  ${diff.counts.modified}`);
-    out(`  Added:     ${diff.counts.added}`);
-    out(`  Deleted:   ${diff.counts.deleted}`);
-    const byKind = new Map();
-    for (const match of diff.contentMatches ?? []) {
-        byKind.set(match.kind, (byKind.get(match.kind) ?? 0) + 1);
-    }
-    out('');
-    if (byKind.size === 0) {
-        out('  Content matches: none');
-    }
-    else {
-        out('  Content matches:');
-        for (const [kind, count] of [...byKind].sort()) {
-            out(`    ${kind.padEnd(13)} ${count}`);
-        }
-        out('    (renamed / moved / reshaped are resolved; the rest need a human)');
-    }
-    if (report.identityIn) {
-        out('');
-        out(`  Identity map in:  ${report.identityIn}`);
-        out(`    applied: ${report.appliedCount}, ignored: ${report.ignoredCount}`);
-    }
-    if (report.written) {
-        out('');
-        out(`  Identity map out: ${report.written.path} (${report.written.entries.length} claims)`);
-    }
-    out('');
-}
 //# sourceMappingURL=diff-content.js.map