feat(dashboard): single-window perspective capture + shape-only fingerprint (#14652) (#14697)

* feat(dashboard): single-window perspective capture + shape-only fingerprint (#14652)

* fix(dashboard): fingerprint coherence + cycle guards — persisted-tree fingerprints, fail-closed cyclic walks (#14652)

Author: neo-fable-clio

src/dashboard/DockZoneModel.mjs

@@ -722,6 +722,128 @@ class DockZoneModel extends Base {
         return errors
     }
 
+    /**
+     * @summary Computes the shape-only fingerprint of a dock-zone document.
+     *
+     * The fingerprint describes topology SHAPE — node types, nesting, child arity, zone
+     * occupancy — and deliberately contains no node ids, item ids, sizes, titles or window
+     * identity, so two structurally identical layouts fingerprint identically regardless of
+     * where or when they were captured (the persistence guardrail for `windowFingerprint`).
+     * Deterministic by construction: child arrays keep document order, edge zones walk in the
+     * fixed {@link #dockZoneEdgeKeys} order.
+     * @param {Object} document The committed dock-zone document.
+     * @returns {{fingerprint:(Object|null), errors:String[]}}
+     * @static
+     */
+    static computeShapeFingerprint(document) {
+        let errors = [];
+
+        if (!DockZoneModel.isJsonRecord(document) || !DockZoneModel.isJsonRecord(document.nodes)) {
+            return {fingerprint: null, errors: ['fingerprint requires a document with a nodes record']}
+        }
+
+        const counts  = {'edge-zone': 0, split: 0, tabs: 0},
+              visited = new Set();
+
+        const walk = nodeId => {
+            const node = document.nodes[nodeId];
+
+            if (!node) {
+                errors.push(`fingerprint walk found no node for id "${nodeId}"`);
+                return '?'
+            }
+
+            // cycle guard: a node graph that references an ancestor would recurse forever —
+            // fail closed through the errors path, never a RangeError out of the public API
+            if (visited.has(nodeId)) {
+                errors.push(`fingerprint walk detected a cycle at node "${nodeId}"`);
+                return '?'
+            }
+
+            visited.add(nodeId);
+
+            counts[node.type] = (counts[node.type] || 0) + 1;
+
+            switch (node.type) {
+                case 'split':
+                    return `${node.orientation === 'horizontal' ? 'h' : 'v'}(${(node.children || []).map(walk).join(',')})`;
+                case 'tabs':
+                    return `t${node.items?.length || 0}`;
+                case 'edge-zone':
+                    return `e{${[...DockZoneModel.dockZoneEdgeKeys]
+                        .map(zone => node.zones?.[zone] ? `${zone}:${walk(node.zones[zone])}` : '')
+                        .filter(Boolean).join(',')}}`;
+                default:
+                    errors.push(`fingerprint walk found unsupported node type "${node.type}"`);
+                    return '?'
+            }
+        };
+
+        const shape = walk(document.root);
+
+        if (errors.length) {
+            return {fingerprint: null, errors}
+        }
+
+        return {
+            fingerprint: {
+                schema    : 'neo.harness.dockShape.v1',
+                shape,
+                nodeCounts: counts,
+                itemCount : Object.keys(document.items || {}).length
+            },
+            errors
+        }
+    }
+
+    /**
+     * @summary Captures the current window's dock document as a v2 saved-layout perspective.
+     *
+     * The single-window capture scope: layout truth only enters the record — the committed
+     * document tree — never render projections, runtime handles or pane-internal state (panes
+     * are layout-blind, so their internals are not the layout's to save).
+     *
+     * Fingerprint-coherence by construction: the wrapper is written FIRST (validate + normalize
+     * through the one writer path), and the fingerprint is computed from the PERSISTED
+     * `layout.dockZone` — never the raw input — so the stored fingerprint cannot describe a
+     * tree the record does not contain (normalization collapses e.g. a single-child split to
+     * its child; a pre-normalization fingerprint would immortalize the collapsed wrapper).
+     * @param {Object} document The committed dock-zone document to capture.
+     * @param {Object} [metadata={}] {layoutId, title, revision, metadata, perspectiveName}
+     * @returns {{layout:(Object|null), errors:String[]}}
+     * @static
+     */
+    static capturePerspective(document, metadata={}) {
+        // pre-probe the RAW input purely as the cycle/shape gate: the writer's normalize pass
+        // recurses and must never see a cyclic graph; the probe's fingerprint is DISCARDED so
+        // coherence with the persisted tree is never at risk
+        const probe = DockZoneModel.computeShapeFingerprint(document);
+
+        if (probe.errors.length) {
+            return {layout: null, errors: probe.errors}
+        }
+
+        const written = DockZoneModel.createSavedLayout(document, {
+            ...metadata,
+            captureScope     : 'window',
+            windowFingerprint: null
+        });
+
+        if (written.errors.length) {
+            return written
+        }
+
+        const {fingerprint, errors} = DockZoneModel.computeShapeFingerprint(written.layout.dockZone);
+
+        if (errors.length) {
+            return {layout: null, errors}
+        }
+
+        written.layout.windowFingerprint = fingerprint;
+
+        return written
+    }
+
     /**
      * @summary Wraps a valid committed dock-zone document in a JSON-only saved-layout envelope.
      *

test/playwright/unit/dashboard/DockZoneModel.spec.mjs

@@ -217,6 +217,84 @@ test.describe('Neo.dashboard.DockZoneModel', () => {
             expect(DockZoneModel.restoreSavedLayout(layout).errors).toEqual([])
         });
 
+        test('capturePerspective emits a v2 window-scope record with a shape-only fingerprint', () => {
+            const {layout, errors} = DockZoneModel.capturePerspective(doc(), {
+                layoutId       : 'capture-1',
+                title          : 'Capture One',
+                perspectiveName: 'Morning Focus'
+            });
+
+            expect(errors).toEqual([]);
+            expect(layout.schema).toBe(DockZoneModel.LAYOUT_SCHEMA);
+            expect(layout.captureScope).toBe('window');
+            expect(layout.perspectiveName).toBe('Morning Focus');
+            expect(layout.windowFingerprint.schema).toBe('neo.harness.dockShape.v1');
+            expect(typeof layout.windowFingerprint.shape).toBe('string');
+            expect(layout.windowFingerprint.itemCount).toBeGreaterThan(0);
+            expect(DockZoneModel.restoreSavedLayout(layout).errors).toEqual([])
+        });
+
+        test('stored fingerprint matches the PERSISTED document, not the pre-normalized input (single-child split collapse)', () => {
+            // a split with one child normalizes away — the persisted root becomes the child tabs
+            const d = splitDoc();
+            d.nodes['main-split'].children = ['main-tabs'];
+            d.nodes['main-split'].sizes    = [1];
+            delete d.nodes['side-tabs'];
+            delete d.items.terminal;
+
+            const {layout, errors} = DockZoneModel.capturePerspective(d, {layoutId: 'c', title: 'C'});
+
+            expect(errors).toEqual([]);
+            // the stored fingerprint must equal the persisted tree's fingerprint by construction…
+            expect(layout.windowFingerprint)
+                .toEqual(DockZoneModel.computeShapeFingerprint(layout.dockZone).fingerprint);
+            // …and must NOT carry the collapsed split wrapper the raw input had
+            expect(layout.windowFingerprint.shape)
+                .not.toBe(DockZoneModel.computeShapeFingerprint(d).fingerprint.shape);
+            expect(layout.windowFingerprint.shape).not.toContain('h(')
+        });
+
+        test('cyclic node graphs fail closed through the public return shapes, never a throw', () => {
+            const cyclic = doc();
+            cyclic.nodes['loop-split'] = {type: 'split', orientation: 'horizontal', children: ['main-tabs', 'loop-split'], sizes: [0.5, 0.5]};
+            cyclic.nodes.root.zones.center = 'loop-split';
+
+            const direct = DockZoneModel.computeShapeFingerprint(cyclic);
+            expect(direct.fingerprint).toBe(null);
+            expect(direct.errors.join(' ')).toContain('cycle');
+
+            const captured = DockZoneModel.capturePerspective(cyclic, {layoutId: 'x', title: 'X'});
+            expect(captured.layout).toBe(null);
+            expect(captured.errors.length).toBeGreaterThan(0)
+        });
+
+        test('shape fingerprints are deterministic, id-free and shape-sensitive', () => {
+            const a = DockZoneModel.computeShapeFingerprint(doc()),
+                  b = DockZoneModel.computeShapeFingerprint(doc());
+
+            expect(a.errors).toEqual([]);
+            expect(a.fingerprint).toEqual(b.fingerprint);
+
+            // rename every node id — the shape must not change (id-freedom)
+            const renamed = JSON.parse(JSON.stringify(doc()).replaceAll('main-tabs', 'renamed-tabs'));
+            expect(DockZoneModel.computeShapeFingerprint(renamed).fingerprint.shape).toBe(a.fingerprint.shape);
+
+            // structural change → different shape term
+            const mutated = doc();
+            mutated.nodes['main-tabs'].items.push('extra-item');
+            expect(DockZoneModel.computeShapeFingerprint(mutated).fingerprint.shape).not.toBe(a.fingerprint.shape)
+        });
+
+        test('fingerprint walk fails closed on dangling node refs', () => {
+            const broken = doc();
+            broken.root = 'missing-node';
+
+            const {fingerprint, errors} = DockZoneModel.computeShapeFingerprint(broken);
+
+            expect(fingerprint).toBe(null);
+            expect(errors.join(' ')).toContain('missing-node')
+        });
+
         test('fails closed on perspective-field contract violations', () => {
             const badScope = DockZoneModel.createSavedLayout(doc(), {layoutId: 'x', title: 'X', captureScope: 'galaxy'});
             expect(badScope.layout).toBe(null);