cursedbelt 2.7.0 → 3.0.0

package/src/studio/studio.spec.ts

@@ -1,886 +0,0 @@
-/**
- * The engine-model studio's contract (03 §3).
- *
- * The two gates the spec names are `describe`d verbatim at the bottom:
- *   - a studio-authored design serializes to an AppConfig that passes the FULL
- *     pipeline with zero errors, and reloads to an identical canvas;
- *   - an edit adding `privateMedia` without `guard` blocks save with the
- *     `engine-dependency-missing` diagnostic, inline on the field that caused it.
- *
- * Everything above them is the behavior those two depend on, tested where it
- * can fail rather than only through the gate.
- */
-import { describe, expect, it } from 'bun:test';
-import {
-  autoLayout,
-  canWire,
-  compatibleInputs,
-  createStudioDesign,
-  createStudioSession,
-  DEFAULT_NODE_HEIGHT,
-  DEFAULT_NODE_WIDTH,
-  edit,
-  enginePalette,
-  findWirePoint,
-  fromAppConfig,
-  inputs,
-  inspectorPanel,
-  MIN_NODE_HEIGHT,
-  MIN_NODE_WIDTH,
-  outputs,
-  previewFeatures,
-  resolvedPositions,
-  resolvedSizes,
-  saveDisposition,
-  type StudioDesign,
-  type StudioVerification,
-  toAppConfigJson,
-  unwiredRequiredInputs,
-  verifyStudioDesign,
-} from './index';
-
-const errorsOf = (v: StudioVerification) => v.diagnostics.filter((d) => d.severity === 'error');
-const codesOf = (v: StudioVerification) => errorsOf(v).map((d) => d.code);
-
-/* ------------------------------------------------------------- document */
-
-describe('the document', () => {
-  it('opens on a design that compiles clean — a blank canvas is never red', async () => {
-    const verification = await verifyStudioDesign(createStudioDesign({ appId: 'blank' }));
-    expect(verification.ok).toBe(true);
-    expect(verification.errorCount).toBe(0);
-    expect(verification.warningCount).toBe(0);
-  });
-
-  it('opens a saas design with guard and rbac, because V0 requires both', async () => {
-    const design = createStudioDesign({ appId: 'tenant', engines: ['knowledge'], profile: 'saas' });
-    expect(design.config.engines).toContain('guard');
-    const verification = await verifyStudioDesign(design);
-    expect(codesOf(verification)).toEqual([]);
-  });
-
-  it('lays out deterministically — one column per engine, in canonical order', () => {
-    const design = edit.addInstance(createStudioDesign({ appId: 'a', engines: ['asset'] }), 'asset');
-    const positions = autoLayout(design.config);
-    expect(positions.asset).toEqual({ x: 0, y: 0 });
-    // Second asset instance stacks under the first, same column.
-    expect(positions['asset-2']).toEqual({ x: 0, y: 180 });
-    // `system` is the fifth engine id, so it always gets the fifth column.
-    expect(autoLayout(createStudioDesign({ appId: 'a' }).config).system).toEqual({ x: 4 * 320, y: 0 });
-  });
-
-  it('mints non-colliding instance ids', () => {
-    let design = createStudioDesign({ appId: 'a', engines: ['asset'] });
-    design = edit.addInstance(design, 'asset');
-    design = edit.addInstance(design, 'asset');
-    expect((design.config.instances ?? []).map((i) => i.id)).toEqual(['asset', 'asset-2', 'asset-3']);
-  });
-});
-
-/* ----------------------------------------------------------- operations */
-
-describe('edit operations keep the document coherent', () => {
-  const wired = (): StudioDesign => {
-    let design = createStudioDesign({ appId: 'a', engines: ['asset'] });
-    design = edit.addInstance(design, 'asset');
-    design = edit.moveNode(design, 'asset-2', { x: 999, y: 42 });
-    return edit.addConnection(design, 'asset:videos-out', 'asset-2:videos-in');
-  };
-
-  it('deleting an instance drops the wires that touched it, and its position', () => {
-    const design = edit.removeInstance(wired(), 'asset-2');
-    expect(design.config.connections).toEqual([]);
-    expect(design.layout.nodes['asset-2']).toBeUndefined();
-    expect((design.config.instances ?? []).map((i) => i.id)).toEqual(['asset']);
-  });
-
-  it('deleting keeps the engine active — a delete/re-add round trip is lossless', () => {
-    const design = edit.removeInstance(wired(), 'asset-2');
-    expect(design.config.engines).toContain('asset');
-  });
-
-  it('renaming rewrites every wire endpoint and carries the canvas position', () => {
-    const design = edit.renameInstance(wired(), 'asset-2', 'vault');
-    expect(design.config.connections).toEqual([{ from: 'asset:videos-out', to: 'vault:videos-in' }]);
-    expect(design.layout.nodes.vault).toEqual({ x: 999, y: 42 });
-    expect(design.layout.nodes['asset-2']).toBeUndefined();
-  });
-
-  it('refuses a rename onto an existing id rather than merging two instances', () => {
-    const design = wired();
-    expect(edit.renameInstance(design, 'asset-2', 'asset')).toBe(design);
-  });
-
-  it('dropping a node activates its engine', () => {
-    const design = edit.addInstance(createStudioDesign({ appId: 'a' }), 'knowledge');
-    expect(design.config.engines).toEqual(['system', 'knowledge']);
-  });
-
-  it('deactivating an engine takes its instances with it', () => {
-    const design = edit.deactivateEngine(wired(), 'asset');
-    expect(design.config.engines).not.toContain('asset');
-    expect(design.config.instances).toEqual([]);
-    expect(design.config.connections).toEqual([]);
-  });
-
-  it('setting a feature to undefined removes the key rather than storing undefined', () => {
-    let design = edit.setFeature(createStudioDesign({ appId: 'a', engines: ['asset'] }), 'asset', 'ocr', true);
-    expect((design.config.instances ?? [])[0]?.features).toEqual({ ocr: true });
-    design = edit.setFeature(design, 'asset', 'ocr', undefined);
-    // JSON has no `undefined`; storing one would make the document and the file
-    // on disk disagree, which the round-trip gate would read as drift.
-    expect(Object.hasOwn((design.config.instances ?? [])[0]?.features ?? {}, 'ocr')).toBe(false);
-  });
-
-  it('refuses a duplicate wire', () => {
-    const design = wired();
-    expect(edit.addConnection(design, 'asset:videos-out', 'asset-2:videos-in')).toBe(design);
-  });
-
-  it('an edit against a missing instance is a no-op, not a crash', () => {
-    const design = wired();
-    expect(edit.setFeature(design, 'ghost', 'ocr', true)).toBe(design);
-    expect(edit.removeInstance(design, 'ghost')).toBe(design);
-  });
-
-  it('switching to saas brings guard and rbac with it', async () => {
-    const design = edit.setProfile(createStudioDesign({ appId: 'a', engines: ['knowledge'] }), 'saas');
-    expect(design.config.engines).toContain('guard');
-    expect(codesOf(await verifyStudioDesign(design))).toEqual([]);
-  });
-
-  it('moving a node changes no config byte', () => {
-    const design = wired();
-    const moved = edit.moveNode(design, 'asset', { x: 5, y: 5 });
-    expect(moved.config).toBe(design.config);
-  });
-});
-
-describe('node sizing lives in the layout, not the config', () => {
-  const twoAssets = (): StudioDesign => {
-    let design = createStudioDesign({ appId: 'a', engines: ['asset'] });
-    design = edit.addInstance(design, 'asset');
-    return design;
-  };
-
-  it('resizeNode stores a box and changes no config byte', () => {
-    const design = twoAssets();
-    const sized = edit.resizeNode(design, 'asset', { width: 300, height: 200 });
-    expect(sized.layout.sizes.asset).toEqual({ width: 300, height: 200 });
-    expect(sized.config).toBe(design.config);
-  });
-
-  it('clamps a resize to the minimum box — a node too small to read is not representable', () => {
-    const sized = edit.resizeNode(twoAssets(), 'asset', { width: 10, height: 10 });
-    expect(sized.layout.sizes.asset).toEqual({ width: MIN_NODE_WIDTH, height: MIN_NODE_HEIGHT });
-  });
-
-  it('rounds fractional pointer sizes to whole canvas units', () => {
-    const sized = edit.resizeNode(twoAssets(), 'asset', { width: 300.6, height: 199.2 });
-    expect(sized.layout.sizes.asset).toEqual({ width: 301, height: 199 });
-  });
-
-  it('a resize to the same box is a no-op — no wasted undo step or compile', () => {
-    const sized = edit.resizeNode(twoAssets(), 'asset', { width: 300, height: 200 });
-    expect(edit.resizeNode(sized, 'asset', { width: 300, height: 200 })).toBe(sized);
-  });
-
-  it('resolvedSizes falls back to the auto-size default for an unsized node', () => {
-    const sizes = resolvedSizes(edit.resizeNode(twoAssets(), 'asset', { width: 300, height: 200 }));
-    expect(sizes.asset).toEqual({ width: 300, height: 200 });
-    expect(sizes['asset-2']).toEqual({ width: DEFAULT_NODE_WIDTH, height: DEFAULT_NODE_HEIGHT });
-  });
-
-  it('a taller stored node pushes the auto-stacked node below it down, no overlap', () => {
-    const design = edit.resizeNode(twoAssets(), 'asset', { width: 220, height: 400 });
-    const positions = resolvedPositions(design);
-    // asset-2 has no stored position, so it auto-stacks BELOW the resized asset.
-    expect(positions.asset).toEqual({ x: 0, y: 0 });
-    expect(positions['asset-2'].y).toBeGreaterThanOrEqual(400);
-  });
-
-  it('deleting a node drops its stored size', () => {
-    const design = edit.resizeNode(twoAssets(), 'asset-2', { width: 300, height: 200 });
-    const pruned = edit.removeInstance(design, 'asset-2');
-    expect(pruned.layout.sizes['asset-2']).toBeUndefined();
-  });
-
-  it('renaming a node carries its stored size across', () => {
-    let design = edit.resizeNode(twoAssets(), 'asset-2', { width: 300, height: 200 });
-    design = edit.renameInstance(design, 'asset-2', 'vault');
-    expect(design.layout.sizes.vault).toEqual({ width: 300, height: 200 });
-    expect(design.layout.sizes['asset-2']).toBeUndefined();
-  });
-
-  it('resetLayout forgets stored sizes as well as positions', () => {
-    let design = edit.resizeNode(twoAssets(), 'asset', { width: 300, height: 200 });
-    design = edit.moveNode(design, 'asset', { x: 5, y: 5 });
-    const reset = edit.resetLayout(design);
-    expect(reset.layout.sizes).toEqual({});
-    expect(reset.layout.nodes).toEqual({});
-  });
-});
-
-describe('replaceInstance swaps a node in place (View / tinker mode)', () => {
-  const wired = (): StudioDesign => {
-    let design = createStudioDesign({ appId: 'a', engines: ['asset'] });
-    design = edit.addInstance(design, 'asset');
-    design = edit.moveNode(design, 'asset-2', { x: 999, y: 42 });
-    return edit.addConnection(design, 'asset:videos-out', 'asset-2:videos-in');
-  };
-
-  it('preserves the outgoing node position, on its stored spot or its auto slot', () => {
-    // `asset-2` was dragged to a bespoke position; `asset` sits at its auto slot.
-    const dragged = edit.replaceInstance(wired(), 'asset-2', 'knowledge');
-    const newId = (dragged.config.instances ?? []).find((i) => i.engine === 'knowledge')!.id;
-    expect(resolvedPositions(dragged)[newId]).toEqual({ x: 999, y: 42 });
-
-    // A node with no stored position inherits its auto-layout slot, pinned so the
-    // swap does not teleport it to the new engine's column.
-    const auto = edit.replaceInstance(wired(), 'asset', 'knowledge');
-    const autoId = (auto.config.instances ?? []).find((i) => i.engine === 'knowledge')!.id;
-    expect(resolvedPositions(auto)[autoId]).toEqual({ x: 0, y: 0 });
-  });
-
-  it('drops every wire that touched the replaced node — never a dangling ref', () => {
-    const swapped = edit.replaceInstance(wired(), 'asset-2', 'knowledge');
-    expect(swapped.config.connections).toEqual([]);
-    // The result compiles clean: the wire policy leaves nothing for V1/V3 to trip on.
-    expect(swapped.config.instances?.map((i) => i.id).includes('asset-2')).toBe(false);
-  });
-
-  it('leaves wires that did NOT touch the replaced node untouched', () => {
-    let design = createStudioDesign({ appId: 'a', engines: ['asset'] });
-    design = edit.addInstance(design, 'asset'); // asset-2, the node we will replace
-    design = edit.addInstance(design, 'asset'); // asset-3
-    design = edit.addConnection(design, 'asset:videos-out', 'asset-3:videos-in');
-    const swapped = edit.replaceInstance(design, 'asset-2', 'knowledge');
-    expect(swapped.config.connections).toEqual([{ from: 'asset:videos-out', to: 'asset-3:videos-in' }]);
-  });
-
-  it('retires the old engine when the swapped node was its last instance, and adds the new one', () => {
-    // A single asset on the canvas → swapping it away leaves no asset instance,
-    // so `asset` is deactivated and `knowledge` becomes active in its place.
-    const design = createStudioDesign({ appId: 'a', engines: ['asset'] });
-    const swapped = edit.replaceInstance(design, 'asset', 'knowledge');
-    expect(swapped.config.engines).not.toContain('asset');
-    expect(swapped.config.engines).toContain('knowledge');
-    expect((swapped.config.instances ?? []).map((i) => i.engine)).toEqual(['knowledge']);
-  });
-
-  it('keeps the old engine active when another of its instances remains', () => {
-    const swapped = edit.replaceInstance(wired(), 'asset-2', 'knowledge'); // asset still has `asset`
-    expect(swapped.config.engines).toContain('asset');
-    expect(swapped.config.engines).toContain('knowledge');
-  });
-
-  it('replacing a stale / missing id is just an add — the mode is never a dead end', () => {
-    const design = createStudioDesign({ appId: 'a', engines: ['asset'] });
-    const added = edit.replaceInstance(design, 'ghost', 'knowledge');
-    expect((added.config.instances ?? []).map((i) => i.id)).toEqual(['asset', 'knowledge']);
-    // Nothing was removed, so the original engine is untouched.
-    expect(added.config.engines).toContain('asset');
-  });
-
-  it('a swapped design still compiles clean', async () => {
-    const swapped = edit.replaceInstance(createStudioDesign({ appId: 'a', engines: ['asset'] }), 'asset', 'knowledge');
-    expect(codesOf(await verifyStudioDesign(swapped))).toEqual([]);
-  });
-});
-
-/* --------------------------------------------------------------- wiring */
-
-describe('wiring is offered from the post-V2 truth, not the declared catalog', () => {
-  const manifestOf = async (design: StudioDesign) => {
-    const verification = await verifyStudioDesign(design);
-    if (!verification.manifest) throw new Error(`no manifest: ${codesOf(verification).join(', ')}`);
-    return verification;
-  };
-
-  it('a port switched off by enabledWhen stops being offered', async () => {
-    const design = createStudioDesign({ appId: 'a', engines: ['asset'] });
-    const on = await manifestOf(design);
-    expect(outputs(on.manifest!).map((p) => p.endpoint)).toContain('asset:videos-out');
-
-    const off = await manifestOf(edit.setFeature(design, 'asset', 'video', false));
-    // Fail-closed (04 §3): the port does not EXIST, so the canvas cannot draw
-    // the wire — rather than drawing it and reporting it later.
-    expect(outputs(off.manifest!).map((p) => p.endpoint)).not.toContain('asset:videos-out');
-    expect(inputs(off.manifest!).map((p) => p.endpoint)).not.toContain('asset:videos-in');
-  });
-
-  it('accepts a token-compatible wire and refuses a mode mismatch, in V3s own words', async () => {
-    let design = createStudioDesign({ appId: 'a', engines: ['asset'] });
-    design = edit.addInstance(design, 'asset');
-    const { manifest } = await manifestOf(design);
-    const videosOut = findWirePoint(manifest!, 'asset:videos-out')!;
-    const videosIn = findWirePoint(manifest!, 'asset-2:videos-in')!;
-    const refreshIn = findWirePoint(manifest!, 'asset-2:refresh-in')!;
-
-    expect(canWire(manifest!, videosOut, videosIn).ok).toBe(true);
-    const refused = canWire(manifest!, videosOut, refreshIn);
-    expect(refused.ok).toBe(false);
-    expect(refused.reason).toBe('mode-mismatch');
-    expect(refused.message).toContain('signal');
-  });
-
-  it('refuses a wire that leaves and re-enters one instance', async () => {
-    const { manifest } = await manifestOf(createStudioDesign({ appId: 'a', engines: ['asset'] }));
-    const verdict = canWire(
-      manifest!,
-      findWirePoint(manifest!, 'asset:videos-out')!,
-      findWirePoint(manifest!, 'asset:videos-in')!,
-    );
-    expect(verdict).toMatchObject({ ok: false, reason: 'self' });
-  });
-
-  it('only offers compatible landing points for a drag', async () => {
-    let design = createStudioDesign({ appId: 'a', engines: ['asset', 'knowledge'] });
-    design = edit.addInstance(design, 'asset');
-    const { manifest } = await manifestOf(design);
-    const landings = compatibleInputs(manifest!, findWirePoint(manifest!, 'asset:videos-out')!);
-    // Both landings are the LATTICE, not a coincidence: `media:videos` is a
-    // subtype of `media:items`, so a videos producer legally feeds an items
-    // consumer — and nothing on `knowledge`, whose tokens are unrelated.
-    expect(landings.map((p) => p.endpoint).sort()).toEqual(['asset-2:items-in', 'asset-2:videos-in']);
-    expect(landings.map((p) => p.tokenId).sort()).toEqual(['media:items', 'media:videos']);
-  });
-
-  it('a wire the canvas offered is a wire the compiler accepts', async () => {
-    let design = createStudioDesign({ appId: 'a', engines: ['asset'] });
-    design = edit.addInstance(design, 'asset');
-    const { manifest } = await manifestOf(design);
-    const from = findWirePoint(manifest!, 'asset:videos-out')!;
-    for (const landing of compatibleInputs(manifest!, from)) {
-      const verification = await verifyStudioDesign(edit.addConnection(design, from.endpoint, landing.endpoint));
-      expect(codesOf(verification), `${from.endpoint} → ${landing.endpoint}`).toEqual([]);
-    }
-  });
-
-  it('reports required inputs with nothing wired into them', async () => {
-    // `asset.editor` declares a required clips input — an editor with no source
-    // of clips is a dead pane. `editor` depends on the `wasm` capability, so the
-    // probe must supply it; that is the point of the next test.
-    const design = edit.setFeature(createStudioDesign({ appId: 'a', engines: ['asset'] }), 'asset', 'editor', true);
-    const verification = await verifyStudioDesign(design, { capabilities: { wasm: true } });
-    expect(codesOf(verification)).toContain('required-port-unwired');
-    expect(unwiredRequiredInputs(verification.manifest!).map((p) => p.endpoint)).toEqual(['asset:video-in']);
-  });
-
-  it('a feature the HOST cannot run is not effective, so its required port never appears', async () => {
-    // The same design on a machine with no `wasm`: `effective(editor) = false`,
-    // the required port does not exist, and there is nothing to wire. A studio
-    // that demanded the wire anyway would be demanding it for a pane that will
-    // not render — this is `enabledWhen` fail-closed doing its job at the studio
-    // moment, against the LIVE host (04 §1's capability-source rule).
-    const design = edit.setFeature(createStudioDesign({ appId: 'a', engines: ['asset'] }), 'asset', 'editor', true);
-    const verification = await verifyStudioDesign(design, { capabilities: { wasm: false } });
-    expect(codesOf(verification)).toEqual([]);
-    expect(unwiredRequiredInputs(verification.manifest!)).toEqual([]);
-    expect(verification.diagnostics.map((d) => d.code)).toContain('capability-downgrade');
-  });
-});
-
-/* ------------------------------------------------------ diagnostic targets */
-
-describe('diagnostics are placed from structured fields, never from their prose', () => {
-  it('puts a feature-level error on the field that caused it', async () => {
-    const design = edit.setFeature(
-      createStudioDesign({ appId: 'a', engines: ['asset'] }),
-      'asset',
-      'privateMedia',
-      true,
-    );
-    const verification = await verifyStudioDesign(design);
-    expect(errorsOf(verification)[0]?.target).toEqual({
-      kind: 'feature',
-      instanceId: 'asset',
-      feature: 'privateMedia',
-    });
-    expect(verification.byInstance.get('asset')).toHaveLength(1);
-  });
-
-  it('puts a broken wire on the wire, even though its instance half names nothing', async () => {
-    const design = edit.addConnection(
-      createStudioDesign({ appId: 'a', engines: ['asset'] }),
-      'ghost:videos-out',
-      'asset:videos-in',
-    );
-    const verification = await verifyStudioDesign(design);
-    expect(codesOf(verification)).toContain('unknown-connection-endpoint');
-    expect(verification.byConnection.get(0)?.length).toBeGreaterThan(0);
-    // The missing node is not on the canvas; the wire is what the author fixes.
-    expect(verification.byInstance.get('ghost')).toBeUndefined();
-  });
-
-  it('places a V3 connection error, whose path is a from→to PAIR and carries no instanceId', async () => {
-    let design = createStudioDesign({ appId: 'a', engines: ['asset'] });
-    design = edit.addInstance(design, 'asset');
-    // value → signal: V3 refuses it, and reports it as
-    // `path: 'asset:videos-out → asset-2:refresh-in'` with no instanceId at all.
-    design = edit.addConnection(design, 'asset:videos-out', 'asset-2:refresh-in');
-    const verification = await verifyStudioDesign(design);
-    expect(codesOf(verification)).toContain('port-mode-mismatch');
-    expect(verification.byConnection.get(0)?.map((d) => d.code)).toContain('port-mode-mismatch');
-    // Not on a node, and above all not silently on the app.
-    expect(verification.appLevel.map((d) => d.code)).not.toContain('port-mode-mismatch');
-  });
-
-  it('never drops a diagnostic it cannot place — it lands on the app', async () => {
-    const design = createStudioDesign({ appId: 'a' });
-    // An unknown top-level key has no instance and no wire to belong to.
-    (design.config as Record<string, unknown>).nonsense = true;
-    const verification = await verifyStudioDesign(design);
-    expect(codesOf(verification)).toContain('unknown-config-key');
-    expect(verification.appLevel.length).toBeGreaterThan(0);
-    expect(verification.diagnostics.length).toBe(
-      verification.appLevel.length +
-        [...verification.byInstance.values()].flat().length +
-        [...verification.byConnection.values()].flat().length,
-    );
-  });
-});
-
-/* ------------------------------------------------------------- inspector */
-
-describe('the inspector reflects the schema V0 validates against', () => {
-  it('renders a control for every feature key, with the schema default as the effective value', async () => {
-    const design = createStudioDesign({ appId: 'a', engines: ['asset'] });
-    const panel = inspectorPanel(design, 'asset', await verifyStudioDesign(design))!;
-    const gallery = panel.fields.find((f) => f.descriptor.name === 'gallery')!;
-    expect(gallery.overridden).toBe(false);
-    expect(gallery.effective).toBe(true); // the schema's default, not an arbitrary off
-    expect(panel.fields.map((f) => f.descriptor.name)).toContain('ocr');
-  });
-
-  it('marks a field the author has set, and attaches its diagnostics to it', async () => {
-    const design = edit.setFeature(
-      createStudioDesign({ appId: 'a', engines: ['asset'] }),
-      'asset',
-      'privateMedia',
-      true,
-    );
-    const panel = inspectorPanel(design, 'asset', await verifyStudioDesign(design))!;
-    const field = panel.fields.find((f) => f.descriptor.name === 'privateMedia')!;
-    expect(field).toMatchObject({ overridden: true, declared: true, effective: true });
-    expect(field.diagnostics.map((d) => d.code)).toEqual(['engine-dependency-missing']);
-    expect(panel.diagnostics).toEqual([]);
-  });
-
-  it('keeps rendering through a document that does not parse', () => {
-    const design = edit.setFeature(
-      createStudioDesign({ appId: 'a', engines: ['asset'] }),
-      'asset',
-      'galleryLayouts',
-      'not-an-array',
-    );
-    // The inspector's job is to be usable while the config is broken.
-    expect(inspectorPanel(design, 'asset', null)?.fields.length).toBeGreaterThan(0);
-    expect(previewFeatures((design.config.instances ?? [])[0]!)).toBeNull();
-  });
-
-  it('reports the palette without gating a second instance of an active engine', () => {
-    const design = edit.addInstance(createStudioDesign({ appId: 'a', engines: ['asset'] }), 'asset');
-    expect(enginePalette(design)).toContainEqual({ engine: 'asset', active: true, instances: 2 });
-    expect(enginePalette(design)).toContainEqual({ engine: 'dev', active: false, instances: 0 });
-  });
-});
-
-/* --------------------------------------------------------------- session */
-
-describe('the live session', () => {
-  /** A verify whose completion the test controls, so ordering is deterministic. */
-  const deferred = () => {
-    let resolve!: (v: StudioVerification) => void;
-    const promise = new Promise<StudioVerification>((r) => {
-      resolve = r;
-    });
-    return { promise, resolve };
-  };
-
-  it('discards a result whose design is no longer current', async () => {
-    const gates = [deferred(), deferred()];
-    const seen: string[] = [];
-    let call = 0;
-    const session = createStudioSession({
-      design: createStudioDesign({ appId: 'a' }),
-      verify: async (design) => {
-        seen.push(design.config.app.title ?? '');
-        return gates[call++ === 0 ? 0 : 1]!.promise;
-      },
-    });
-
-    // First compile is in flight; edit again before it lands.
-    const first = await verifyStudioDesign(createStudioDesign({ appId: 'a' }));
-    session.apply((d) => edit.setAppMeta(d, { title: 'second' }));
-    gates[0]!.resolve({ ...first, errorCount: 99 }); // the STALE answer
-    await Bun.sleep(0);
-    gates[1]!.resolve(first);
-
-    const settled = await session.settled();
-    // The stale result must never be painted.
-    expect(settled.errorCount).toBe(0);
-    expect(session.getState().design.config.app.title).toBe('second');
-    session.dispose();
-  });
-
-  it('coalesces a burst of edits into one follow-up compile', async () => {
-    let calls = 0;
-    const clean = await verifyStudioDesign(createStudioDesign({ appId: 'a' }));
-    const session = createStudioSession({
-      design: createStudioDesign({ appId: 'a' }),
-      verify: async () => {
-        calls++;
-        await Bun.sleep(1);
-        return clean;
-      },
-    });
-    for (const title of ['a', 'b', 'c', 'd']) session.apply((d) => edit.setAppMeta(d, { title }));
-    await session.settled();
-    // One initial compile plus one for the whole burst — not one per keystroke.
-    expect(calls).toBeLessThanOrEqual(2);
-    session.dispose();
-  });
-
-  it('keeps the last good manifest when an edit stops compiling', async () => {
-    const session = createStudioSession({ design: createStudioDesign({ appId: 'a', engines: ['asset'] }) });
-    const good = await session.settled();
-    expect(good.manifest).not.toBeNull();
-
-    session.apply((d) => edit.setFeature(d, 'asset', 'galleryLayouts', 'not-an-array'));
-    const broken = await session.settled();
-    expect(broken.ok).toBe(false);
-    expect(broken.manifest).toBeNull();
-    // The canvas still has ports to draw while the author fixes the typo.
-    expect(session.getState().lastGoodManifest).not.toBeNull();
-    session.dispose();
-  });
-
-  it('refuses to save while unverified, and refuses when the compiler itself failed', async () => {
-    const session = createStudioSession({
-      design: createStudioDesign({ appId: 'a' }),
-      verify: async () => {
-        throw new Error('harvester exploded');
-      },
-    });
-    expect(session.disposition().allowed).toBe(false);
-    const verification = await session.settled();
-    expect(verification.ok).toBe(false);
-    expect(verification.failure).toContain('harvester exploded');
-    // A compiler we could not run has approved nothing.
-    expect(session.disposition().allowed).toBe(false);
-    expect(session.disposition().reason).toContain('harvester exploded');
-    session.dispose();
-  });
-
-  it('does not compile a no-op edit', async () => {
-    let calls = 0;
-    const clean = await verifyStudioDesign(createStudioDesign({ appId: 'a' }));
-    const session = createStudioSession({
-      design: createStudioDesign({ appId: 'a' }),
-      verify: async () => {
-        calls++;
-        return clean;
-      },
-    });
-    await session.settled();
-    const before = calls;
-    session.apply((d) => edit.renameInstance(d, 'nope', 'also-nope'));
-    await session.settled();
-    expect(calls).toBe(before);
-    session.dispose();
-  });
-});
-
-describe('the session undo/redo history', () => {
-  it('undo restores the prior design and redo reapplies it', async () => {
-    const session = createStudioSession({ design: createStudioDesign({ appId: 'a' }) });
-    const base = session.getState().design;
-    await session.settled();
-    expect(session.canUndo()).toBe(false);
-    expect(session.getState().canUndo).toBe(false);
-
-    session.apply((d) => edit.setAppMeta(d, { title: 'one' }));
-    await session.settled();
-    session.apply((d) => edit.setAppMeta(d, { title: 'two' }));
-    await session.settled();
-    expect(session.getState().design.config.app.title).toBe('two');
-    expect(session.canUndo()).toBe(true);
-    expect(session.getState().canRedo).toBe(false);
-
-    session.undo();
-    await session.settled();
-    expect(session.getState().design.config.app.title).toBe('one');
-    expect(session.getState().canRedo).toBe(true);
-
-    session.undo();
-    await session.settled();
-    // Back to the exact snapshot the session opened with.
-    expect(session.getState().design).toBe(base);
-    expect(session.canUndo()).toBe(false);
-
-    session.redo();
-    await session.settled();
-    expect(session.getState().design.config.app.title).toBe('one');
-    session.dispose();
-  });
-
-  it('coalesces same-tag edits into ONE undo step', async () => {
-    const session = createStudioSession({ design: createStudioDesign({ appId: 'a' }) });
-    const base = session.getState().design;
-    await session.settled();
-
-    // A drag gesture / a burst on one control: same tag collapses to one step.
-    for (const title of ['x1', 'x2', 'x3']) {
-      session.apply((d) => edit.setAppMeta(d, { title }), 'meta');
-      await session.settled();
-    }
-    expect(session.getState().design.config.app.title).toBe('x3');
-
-    session.undo();
-    await session.settled();
-    expect(session.getState().design).toBe(base);
-    expect(session.canUndo()).toBe(false);
-    session.dispose();
-  });
-
-  it('coalesces a resize gesture into ONE undo step, restoring the prior box', async () => {
-    let design = createStudioDesign({ appId: 'a', engines: ['asset'] });
-    design = edit.resizeNode(design, 'asset', { width: 240, height: 140 });
-    const session = createStudioSession({ design });
-    await session.settled();
-
-    // A pointer resize fires many size updates; the same tag collapses the whole
-    // gesture into one undo step (mirrors `move:<id>` for drags).
-    for (const height of [180, 220, 260]) {
-      session.apply((d) => edit.resizeNode(d, 'asset', { width: 300, height }), 'resize:asset');
-      await session.settled();
-    }
-    expect(session.getState().design.layout.sizes.asset).toEqual({ width: 300, height: 260 });
-
-    session.undo();
-    await session.settled();
-    // One undo returns to the box the gesture started from, not through each frame.
-    expect(session.getState().design.layout.sizes.asset).toEqual({ width: 240, height: 140 });
-    expect(session.canUndo()).toBe(false);
-    session.dispose();
-  });
-
-  it('untagged edits are discrete undo steps', async () => {
-    const session = createStudioSession({ design: createStudioDesign({ appId: 'a' }) });
-    await session.settled();
-    session.apply((d) => edit.setAppMeta(d, { title: 'a1' }));
-    await session.settled();
-    session.apply((d) => edit.setAppMeta(d, { title: 'a2' }));
-    await session.settled();
-
-    session.undo();
-    await session.settled();
-    expect(session.getState().design.config.app.title).toBe('a1');
-    session.undo();
-    await session.settled();
-    expect(session.canUndo()).toBe(false);
-    session.dispose();
-  });
-
-  it('a fresh edit after undo discards the redo future', async () => {
-    const session = createStudioSession({ design: createStudioDesign({ appId: 'a' }) });
-    await session.settled();
-    session.apply((d) => edit.setAppMeta(d, { title: 'a1' }));
-    await session.settled();
-    session.undo();
-    await session.settled();
-    expect(session.getState().canRedo).toBe(true);
-
-    session.apply((d) => edit.setAppMeta(d, { title: 'b1' }));
-    await session.settled();
-    expect(session.getState().canRedo).toBe(false);
-    session.dispose();
-  });
-
-  it('reset clears the history — no undo across a document swap', async () => {
-    const session = createStudioSession({ design: createStudioDesign({ appId: 'a' }) });
-    await session.settled();
-    session.apply((d) => edit.setAppMeta(d, { title: 'a1' }));
-    await session.settled();
-    expect(session.canUndo()).toBe(true);
-
-    session.reset(createStudioDesign({ appId: 'b' }));
-    await session.settled();
-    expect(session.canUndo()).toBe(false);
-    expect(session.canRedo()).toBe(false);
-    session.dispose();
-  });
-
-  it('undo/redo at the boundary schedule no wasted compile', async () => {
-    let calls = 0;
-    const clean = await verifyStudioDesign(createStudioDesign({ appId: 'a' }));
-    const session = createStudioSession({
-      design: createStudioDesign({ appId: 'a' }),
-      verify: async () => {
-        calls++;
-        return clean;
-      },
-    });
-    await session.settled();
-    const before = calls;
-    session.undo(); // nothing to undo
-    session.redo(); // nothing to redo
-    await session.settled();
-    expect(calls).toBe(before);
-    session.dispose();
-  });
-
-  it('a replaceInstance swap is ONE undo step', async () => {
-    const session = createStudioSession({ design: createStudioDesign({ appId: 'a', engines: ['asset'] }) });
-    const base = session.getState().design;
-    await session.settled();
-
-    session.apply((d) => edit.replaceInstance(d, 'asset', 'knowledge'));
-    await session.settled();
-    expect((session.getState().design.config.instances ?? []).map((i) => i.engine)).toEqual(['knowledge']);
-
-    // A single press restores the whole swap — not one press for the delete half
-    // and another for the add half.
-    session.undo();
-    await session.settled();
-    expect(session.getState().design).toBe(base);
-    expect(session.canUndo()).toBe(false);
-    session.dispose();
-  });
-
-  it('undo re-verifies the restored design', async () => {
-    let calls = 0;
-    const clean = await verifyStudioDesign(createStudioDesign({ appId: 'a' }));
-    const session = createStudioSession({
-      design: createStudioDesign({ appId: 'a' }),
-      verify: async () => {
-        calls++;
-        return clean;
-      },
-    });
-    await session.settled();
-    session.apply((d) => edit.setAppMeta(d, { title: 'one' }));
-    await session.settled();
-    const before = calls;
-    session.undo();
-    await session.settled();
-    // A restored design is compiled exactly as a fresh edit would be.
-    expect(calls).toBe(before + 1);
-    session.dispose();
-  });
-});
-
-/* ------------------------------------------------------- THE §3 GATES */
-
-describe('GATE — a studio-authored design round-trips through the full pipeline', () => {
-  const authored = (): StudioDesign => {
-    // Everything a real authoring session does: drop nodes, rename one, set
-    // features, draw a wire, move things around.
-    let design = createStudioDesign({ appId: 'round-trip', title: 'Round Trip', engines: ['asset', 'knowledge'] });
-    design = edit.addInstance(design, 'asset');
-    design = edit.renameInstance(design, 'asset-2', 'clips');
-    design = edit.setFeature(design, 'asset', 'gallery', true);
-    design = edit.setFeature(design, 'knowledge', 'kanban', true);
-    design = edit.setInstanceTitle(design, 'asset', 'Media');
-    design = edit.addConnection(design, 'asset:videos-out', 'clips:videos-in');
-    design = edit.moveNode(design, 'clips', { x: 640, y: 240 });
-    design = edit.resizeNode(design, 'clips', { width: 320, height: 220 });
-    return design;
-  };
-
-  it('serializes to an AppConfig the pipeline accepts with ZERO errors', async () => {
-    const verification = await verifyStudioDesign(authored());
-    expect(codesOf(verification)).toEqual([]);
-    expect(verification.ok).toBe(true);
-    expect(verification.lastStage).toBe('V6');
-    expect(verification.manifest?.appId).toBe('round-trip');
-  });
-
-  it('reloads to an identical canvas', async () => {
-    const design = authored();
-    // The exact bytes that become `app-config.json` — layout is NOT among them.
-    const onDisk = toAppConfigJson(design);
-    expect(Object.hasOwn(onDisk, 'layout')).toBe(false);
-
-    const reloaded = fromAppConfig(onDisk, design.layout);
-    expect(reloaded.config).toEqual(design.config);
-    expect(resolvedPositions(reloaded)).toEqual(resolvedPositions(design));
-    // A manual resize is layout too — it must survive the trip beside positions.
-    expect(reloaded.layout.sizes.clips).toEqual({ width: 320, height: 220 });
-    // …and it still compiles identically after the trip.
-    expect(codesOf(await verifyStudioDesign(reloaded))).toEqual([]);
-  });
-
-  it('reloads to an identical canvas even with NO stored layout — the auto-layout is deterministic', () => {
-    const design = authored();
-    const reloaded = fromAppConfig(toAppConfigJson(design));
-    expect(reloaded.config).toEqual(design.config);
-    // Only the dragged node differs; every other position is reproduced exactly.
-    const before = resolvedPositions(design);
-    const after = resolvedPositions(reloaded);
-    for (const id of ['asset', 'knowledge']) expect(after[id]).toEqual(before[id]!);
-    expect(after.clips).toEqual(autoLayout(design.config).clips!);
-  });
-
-  it('drops a layout entry for an instance the config no longer has', () => {
-    const design = authored();
-    const pruned = edit.removeInstance(design, 'clips');
-    const reloaded = fromAppConfig(toAppConfigJson(pruned), design.layout);
-    expect(reloaded.layout.nodes.clips).toBeUndefined();
-    // A stale SIZE is dropped for the same reason a stale position is — it would
-    // otherwise resurrect the day someone re-adds an instance with that id.
-    expect(reloaded.layout.sizes.clips).toBeUndefined();
-  });
-});
-
-describe('GATE — privateMedia without guard blocks save, inline', () => {
-  const offending = () =>
-    edit.setFeature(createStudioDesign({ appId: 'leaky', engines: ['asset'] }), 'asset', 'privateMedia', true);
-
-  it('refuses the save with engine-dependency-missing', async () => {
-    const verification = await verifyStudioDesign(offending());
-    const disposition = saveDisposition(verification);
-    expect(disposition.allowed).toBe(false);
-    expect(disposition.blockers.map((d) => d.code)).toEqual(['engine-dependency-missing']);
-    expect(disposition.reason).toContain('engine-dependency-missing');
-    // An error must carry a machine-actionable fix (the pipeline's own law).
-    expect(disposition.blockers[0]?.fix).toBeTruthy();
-  });
-
-  it('renders the diagnostic ON the switch that caused it', async () => {
-    const design = offending();
-    const panel = inspectorPanel(design, 'asset', await verifyStudioDesign(design))!;
-    const field = panel.fields.find((f) => f.descriptor.name === 'privateMedia')!;
-    expect(field.diagnostics.map((d) => d.code)).toEqual(['engine-dependency-missing']);
-  });
-
-  it('clears the moment the guard engine is added — and the save is allowed again', async () => {
-    const fixed = edit.addInstance(offending(), 'guard');
-    const verification = await verifyStudioDesign(fixed);
-    expect(codesOf(verification)).toEqual([]);
-    expect(saveDisposition(verification).allowed).toBe(true);
-  });
-
-  it('blocks through the SESSION too — the save button reads the same gate', async () => {
-    const session = createStudioSession({ design: createStudioDesign({ appId: 'leaky', engines: ['asset'] }) });
-    await session.settled();
-    expect(session.disposition().allowed).toBe(true);
-
-    session.apply((d) => edit.setFeature(d, 'asset', 'privateMedia', true));
-    await session.settled();
-    expect(session.disposition().allowed).toBe(false);
-
-    session.apply((d) => edit.addInstance(d, 'guard'));
-    await session.settled();
-    expect(session.disposition().allowed).toBe(true);
-    session.dispose();
-  });
-
-  it('a WARNING never blocks a save — the hardware you drew it on is not a defect', async () => {
-    // `asset` warns `capability-downgrade` with no ffmpeg probed on this host.
-    const verification = await verifyStudioDesign(createStudioDesign({ appId: 'a', engines: ['asset'] }));
-    expect(verification.warningCount).toBeGreaterThan(0);
-    expect(saveDisposition(verification).allowed).toBe(true);
-  });
-});