chore: promote develop — DND-4.2 closure

.changeset/dnd-4-2-automatic-item-order.md

@@ -0,0 +1,5 @@
+---
+'@dndgem/core': minor
+---
+
+Add optional `automaticItemOrder` to `AutoLayoutProposalInput` for advisory automatic-item processing order (DND-4.2). Default Auto-Layout behavior is unchanged when omitted.

benchmarks/core/intelligence-planner.bench.ts

@@ -0,0 +1,155 @@
+/**
+ * DND-4.2 intelligence planner benchmarks — timing evidence only (not CI gates).
+ */
+import { bench, describe } from 'vitest';
+import {
+  createAutoLayoutProposal,
+  createLayoutIntent,
+  createLayoutItem,
+  solveLayout,
+} from '@dndgem/core';
+import {
+  createDeterministicPlanningProposal,
+  normalizePlanningProposal,
+} from '@dndgem/intelligence';
+
+function buildSmallFixture() {
+  return createLayoutIntent({
+    space: { width: 200, height: 100 },
+    items: [
+      createLayoutItem({
+        id: 'blocker',
+        constraints: { preferredWidth: 120, preferredHeight: 100, minWidth: 40 },
+      }),
+      createLayoutItem({
+        id: 'target-a',
+        constraints: { preferredWidth: 90, preferredHeight: 100, minWidth: 40 },
+      }),
+      createLayoutItem({
+        id: 'target-b',
+        constraints: { preferredWidth: 90, preferredHeight: 100, minWidth: 40 },
+      }),
+    ],
+  });
+}
+
+function buildMediumFixture(itemCount = 20) {
+  const items = [];
+  for (let i = 0; i < itemCount; i += 1) {
+    items.push(
+      createLayoutItem({
+        id: `item-${i}`,
+        constraints: {
+          preferredWidth: 60 + (i % 5) * 10,
+          preferredHeight: 40 + (i % 3) * 8,
+          minWidth: 20,
+        },
+      }),
+    );
+  }
+  return createLayoutIntent({
+    space: { width: 800, height: 600 },
+    items,
+  });
+}
+
+function prominenceFor(items: readonly { id: string }[]) {
+  const prominence: Record<string, number> = {};
+  for (let i = 0; i < items.length; i += 1) {
+    prominence[items[i]!.id] = items.length - i;
+  }
+  return prominence;
+}
+
+describe('DND-4.2 intelligence planner benchmarks — timing', () => {
+  const smallIntent = buildSmallFixture();
+  const smallSnapshot = {
+    intent: smallIntent,
+    prominence: { 'target-a': 10, 'target-b': 5, blocker: 0 },
+  };
+
+  bench(
+    'planner-only (small order-sensitive)',
+    () => {
+      createDeterministicPlanningProposal(smallSnapshot);
+    },
+    { warmupIterations: 20, iterations: 200, time: 0 },
+  );
+
+  bench(
+    'planner + normalize + auto-layout (small)',
+    () => {
+      const order = normalizePlanningProposal(
+        smallSnapshot,
+        createDeterministicPlanningProposal(smallSnapshot),
+      ).automaticItemOrder;
+      createAutoLayoutProposal({ intent: smallIntent, automaticItemOrder: order });
+    },
+    { warmupIterations: 20, iterations: 100, time: 0 },
+  );
+
+  bench(
+    'planner + auto-layout + solveLayout (small)',
+    () => {
+      const order = normalizePlanningProposal(
+        smallSnapshot,
+        createDeterministicPlanningProposal(smallSnapshot),
+      ).automaticItemOrder;
+      const proposal = createAutoLayoutProposal({ intent: smallIntent, automaticItemOrder: order });
+      solveLayout({ intent: proposal.effectiveIntent });
+    },
+    { warmupIterations: 20, iterations: 100, time: 0 },
+  );
+
+  const mediumIntent = buildMediumFixture(20);
+  const mediumSnapshot = {
+    intent: mediumIntent,
+    prominence: prominenceFor(mediumIntent.items),
+  };
+
+  bench(
+    'planner-only (medium ~20 items)',
+    () => {
+      createDeterministicPlanningProposal(mediumSnapshot);
+    },
+    { warmupIterations: 10, iterations: 100, time: 0 },
+  );
+
+  bench(
+    'planner + auto-layout + solveLayout (medium ~20 items)',
+    () => {
+      const order = normalizePlanningProposal(
+        mediumSnapshot,
+        createDeterministicPlanningProposal(mediumSnapshot),
+      ).automaticItemOrder;
+      const proposal = createAutoLayoutProposal({
+        intent: mediumIntent,
+        automaticItemOrder: order,
+      });
+      solveLayout({ intent: proposal.effectiveIntent });
+    },
+    { warmupIterations: 10, iterations: 50, time: 0 },
+  );
+
+  const largeIntent = buildMediumFixture(35);
+  const largeSnapshot = {
+    intent: largeIntent,
+    prominence: prominenceFor(largeIntent.items),
+  };
+
+  bench(
+    'planner + auto-layout + solveLayout (~35 items)',
+    () => {
+      const order = normalizePlanningProposal(
+        largeSnapshot,
+        createDeterministicPlanningProposal(largeSnapshot),
+      ).automaticItemOrder;
+      const proposal = createAutoLayoutProposal({
+        intent: largeIntent,
+        automaticItemOrder: order,
+      });
+      solveLayout({ intent: proposal.effectiveIntent });
+    },
+    { warmupIterations: 5, iterations: 30, time: 0 },
+  );
+});

benchmarks/core/intelligence-planner.semantic.test.ts

@@ -0,0 +1,95 @@
+/**
+ * DND-4.2 intelligence planner semantic benchmarks — CI-safe checks only.
+ */
+import { describe, expect, it } from 'vitest';
+import { createAutoLayoutProposal, createLayoutIntent, createLayoutItem } from '@dndgem/core';
+import {
+  createDeterministicPlanningProposal,
+  normalizePlanningProposal,
+} from '@dndgem/intelligence';
+
+function orderSensitiveIntent() {
+  return createLayoutIntent({
+    space: { width: 200, height: 100 },
+    items: [
+      createLayoutItem({
+        id: 'blocker',
+        constraints: {
+          preferredWidth: 120,
+          preferredHeight: 100,
+          minWidth: 40,
+        },
+      }),
+      createLayoutItem({
+        id: 'target-a',
+        constraints: {
+          preferredWidth: 90,
+          preferredHeight: 100,
+          minWidth: 40,
+        },
+      }),
+      createLayoutItem({
+        id: 'target-b',
+        constraints: {
+          preferredWidth: 90,
+          preferredHeight: 100,
+          minWidth: 40,
+        },
+      }),
+    ],
+  });
+}
+
+describe('DND-4.2 intelligence planner — semantic gates', () => {
+  it('planner guidance reduces unplaced automatic items on order-sensitive fixture', () => {
+    const intent = orderSensitiveIntent();
+    const snapshot = {
+      intent,
+      prominence: { 'target-a': 10, 'target-b': 5, blocker: 0 },
+    };
+    const baseline = createAutoLayoutProposal({ intent });
+    const guided = createAutoLayoutProposal({
+      intent,
+      automaticItemOrder: normalizePlanningProposal(
+        snapshot,
+        createDeterministicPlanningProposal(snapshot),
+      ).automaticItemOrder,
+    });
+
+    expect(baseline.unplacedItemIds.length).toBeGreaterThan(guided.unplacedItemIds.length);
+    expect(guided.unplacedItemIds).toEqual(['blocker']);
+  });
+
+  it('planner-only output is deterministic across repeated runs (50×)', () => {
+    const intent = orderSensitiveIntent();
+    const snapshot = {
+      intent,
+      prominence: { 'target-a': 10, 'target-b': 5, blocker: 0 },
+    };
+    const first = createDeterministicPlanningProposal(snapshot);
+    for (let i = 0; i < 50; i += 1) {
+      expect(createDeterministicPlanningProposal(snapshot)).toEqual(first);
+    }
+  });
+
+  it('end-to-end planner + auto-layout proposal order stays stable (50×)', () => {
+    const intent = orderSensitiveIntent();
+    const snapshot = {
+      intent,
+      prominence: { 'target-a': 10, 'target-b': 5, blocker: 0 },
+    };
+
+    const run = () => {
+      const order = normalizePlanningProposal(
+        snapshot,
+        createDeterministicPlanningProposal(snapshot),
+      ).automaticItemOrder;
+      return createAutoLayoutProposal({ intent, automaticItemOrder: order });
+    };
+
+    const first = run();
+    for (let i = 0; i < 50; i += 1) {
+      expect(run()).toEqual(first);
+    }
+  });
+});

benchmarks/vitest.bench.config.ts

@@ -15,6 +15,7 @@ export default defineConfig({
   resolve: {
     alias: {
       '@dndgem/core': path.resolve(root, '../packages/core/dist/index.js'),
+      '@dndgem/intelligence': path.resolve(root, '../packages/intelligence/dist/index.js'),
     },
   },
 });

benchmarks/vitest.config.ts

@@ -18,6 +18,7 @@ export default defineConfig({
   resolve: {
     alias: {
       '@dndgem/core': path.resolve(root, '../packages/core/dist/index.js'),
+      '@dndgem/intelligence': path.resolve(root, '../packages/intelligence/dist/index.js'),
     },
   },
 });

docs/architecture/alpha-api-contract.md

@@ -139,10 +139,12 @@ Core remains framework-agnostic, renderer-agnostic, and deterministic.
 #### Auto-Layout compose (opt-in)
 
 ```ts
-const proposal = createAutoLayoutProposal({ intent, previous? });
+const proposal = createAutoLayoutProposal({ intent, previous?, automaticItemOrder? });
 const result = solveLayout({ intent: proposal.effectiveIntent, previous? });
 ```
 
+`automaticItemOrder` (optional, DND-4.2) — advisory processing order for automatic items only. When omitted, Stage B/C use declaration order (Phase 3 default). Core normalizes defensively; unknown, duplicate, and source ids are ignored.
+
 Auto-Layout is **opt-in**. Calling `solveLayout` alone is unchanged. Available on published npm `@alpha` (`0.1.0-alpha.1`). Alpha breaking-change policy above is unchanged.
 
 ### Internal to Core (not public)