vector-mirror 1.0.0

package/src/core/arbitrate.js

@@ -0,0 +1,266 @@
+/**
+ * arbitrate.js — Tri-State Validator (P1-04, VM-LC-001)
+ * Vector Mirror v2.5
+ *
+ * Splits constraint results into three buckets — `passing`, `failing`,
+ * `unchecked` — and passes the scene `diff` through severity-sorted.
+ * No silent cap: max=3 capping has moved to the presentation layer
+ * (`adapters/emitter/prose.js`); structured output ships the full set.
+ *
+ * Tri-state semantics:
+ *   pass === true   → passing[]    (constraint evaluated, satisfied)
+ *   pass === false  → failing[]    (constraint evaluated, violated, with deltas)
+ *   pass === null   → unchecked[]  (could not evaluate, with reasonCode)
+ *
+ * Each `unchecked` entry carries a structured reason so the LLM (or a
+ * downstream emitter) can act on it instead of seeing a phantom "PASS":
+ *   - reasonCategory: "SPECIFICATION" | "MODEL"
+ *   - reasonCode:     enum (see REASON_CODES)
+ *   - hint:           human-readable line
+ *   - suggestedCorrection?: string (only when we can offer one)
+ *
+ * Source-of-truth references:
+ *   - FIX_PLAN_2026-04-18 §1.2 P1-04
+ *   - KATALOG VM-LC-001 (Silent-PASS bei pass:null)
+ *   - KATALOG VM-LC-003 (max=3-Kappung verletzt ADR-024)
+ *   - RB-01 §6.1, RB-03 §6.1
+ *
+ * Core module: NO imports from adapters/ or interface/.
+ */
+
+/**
+ * Severity ordering for diff entries (lower = more important).
+ * `failing` issues are pinned at severity 0; diff types follow.
+ */
+const DIFF_PRIO = {
+  VERSCHOBEN: 1,
+  FARBÄNDERUNG: 2,
+  NEU: 3,
+  ENTFERNT: 4,
+};
+
+/**
+ * Allowed reasonCode values for unchecked entries.
+ * @type {readonly string[]}
+ */
+export const REASON_CODES = Object.freeze([
+  'CONSTRAINT_TYPE_UNKNOWN', // unbekannter / falsch geschriebener Typ
+  'SUBJECT_NOT_FOUND', // subjekt-id existiert nicht im scene
+  'REFERENCE_NOT_FOUND', // referenz-id existiert nicht im scene
+  'REFERENCE_DEGENERATE', // referenz-bbox 0×0 oder ungueltig
+  'MEASUREMENT_AMBIGUOUS', // kein klares messverfahren (z.b. fill auf <g>)
+  'INVALID_MEASUREMENT', // mess-vorgabe selbst ungueltig (z.b. negativer ziel-abstand) (D-003)
+  'SEMANTIC_SUSPICIOUS', // syntaktisch ok, aber semantisch verdaechtig
+  'SCOPE_MISMATCH', // constraint passt nicht zu element-typ
+  // §HEAL-5 Verdikt-Wache (pipeline.js#classifySubjectHonesty, F-AT-2-005):
+  'SUBJECT_NOT_PAINTED', // subjekt malt 0 pixel (paint_visible:false) — pass:true degradiert
+  'SUBJECT_TIME_VARIANT', // subjekt-geometrie zeit-variant (motion_dependent) — geprueft @t0
+  // §H10 R11-07 dritte Wache-Klasse (pipeline.js#classifySubjectHonesty):
+  'SUBJECT_NOT_MEASURABLE', // subjekt-bbox not_measurable (3d/non-smil-motion) — kein gruenes verdikt ueber misstrauter zahl
+  // §H10 R11-21 Parse-Verweigerung (pipeline.js#parseConstraints/checkAllConstraints):
+  'CONSTRAINT_UNPARSEABLE', // constraint-string nicht (vollstaendig) gegen die grammatik parsebar — verweigert statt interpretiert
+  // §H10 R11-01 Existenz-Register (pipeline.js#checkAllConstraints):
+  'SUBJECT_HIDDEN', // subjekt-id existiert im markup, ist aber css-unsichtbar @t0 — nicht gemessen
+  'REFERENCE_HIDDEN', // referenz-id existiert im markup, ist aber css-unsichtbar @t0 — symmetrie zu SUBJECT_HIDDEN (P1)
+]);
+
+/**
+ * Constraint types currently registered in `core/constraints/loader.js`.
+ * Used as the dictionary for typo-suggestions in unchecked entries.
+ * Mirrors ADR-029 Tier-A (11 types). When loader.js gains new types,
+ * extend this list.
+ */
+const KNOWN_CONSTRAINT_TYPES = Object.freeze([
+  'ALIGNED-LEFT',
+  'ALIGNED-TOP',
+  'CENTERED-IN',
+  'COLOR',
+  'DISTANCE-FROM',
+  'FILL',
+  'INSIDE',
+  'NO-OVERLAP',
+  'LEFT-OF',
+  'ABOVE',
+  'SAME-SIZE',
+]);
+
+/**
+ * Levenshtein edit distance — small helper, used for typo suggestions.
+ * O(m·n) time, O(min(m,n)) space.
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+function levenshtein(a, b) {
+  if (a === b) return 0;
+  if (!a) return b.length;
+  if (!b) return a.length;
+  let prev = new Array(b.length + 1);
+  let curr = new Array(b.length + 1);
+  for (let j = 0; j <= b.length; j++) prev[j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[b.length];
+}
+
+/**
+ * Returns the closest known constraint type within Levenshtein ≤ 2,
+ * or `undefined` if no candidate is close enough.
+ *
+ * @param {string} type
+ * @returns {string|undefined}
+ */
+function closestKnownType(type) {
+  if (!type) return undefined;
+  let best;
+  let bestDist = 3; // strictly less than this wins; ≤2 by FIX_PLAN
+  for (const known of KNOWN_CONSTRAINT_TYPES) {
+    const d = levenshtein(type.toUpperCase(), known);
+    if (d < bestDist) {
+      bestDist = d;
+      best = known;
+    }
+  }
+  return best;
+}
+
+/**
+ * Builds an `unchecked` entry. If the constraint result already carries
+ * a reasonCode (provided by registry / P1-08), passes it through; otherwise
+ * applies a heuristic fallback so existing producers keep working.
+ *
+ * @param {object} cr  raw constraint result (`pass: null` shape)
+ * @returns {{
+ *   id?: string,
+ *   constraintType?: string,
+ *   reasonCategory: 'SPECIFICATION'|'MODEL',
+ *   reasonCode: string,
+ *   hint: string,
+ *   suggestedCorrection?: string,
+ *   detail?: string
+ * }}
+ */
+function buildUnchecked(cr) {
+  const entry = {};
+  if (cr.id !== undefined) entry.id = cr.id;
+  if (cr.constraintType !== undefined) entry.constraintType = cr.constraintType;
+  if (cr.detail !== undefined) entry.detail = cr.detail;
+
+  // Honor upstream reasonCode (registry / P1-08) if present and valid.
+  if (cr.reasonCode && REASON_CODES.includes(cr.reasonCode)) {
+    entry.reasonCategory =
+      cr.reasonCategory === 'MODEL' ? 'MODEL' : 'SPECIFICATION';
+    entry.reasonCode = cr.reasonCode;
+    entry.hint = cr.hint || cr.detail || 'Constraint nicht ausgewertet.';
+    if (cr.suggestedCorrection)
+      entry.suggestedCorrection = cr.suggestedCorrection;
+    return entry;
+  }
+
+  // Fallback heuristic: attempt typo-detection on constraintType.
+  if (
+    cr.constraintType &&
+    !KNOWN_CONSTRAINT_TYPES.includes(cr.constraintType)
+  ) {
+    const suggestion = closestKnownType(cr.constraintType);
+    entry.reasonCategory = 'SPECIFICATION';
+    entry.reasonCode = 'CONSTRAINT_TYPE_UNKNOWN';
+    entry.hint = `Constraint-Typ '${cr.constraintType}' ist nicht registriert.`;
+    if (suggestion) entry.suggestedCorrection = suggestion;
+    return entry;
+  }
+
+  // Generic catch-all: known type but check returned pass:null.
+  entry.reasonCategory = 'MODEL';
+  entry.reasonCode = 'MEASUREMENT_AMBIGUOUS';
+  entry.hint = cr.detail || 'Constraint-Auswertung nicht moeglich.';
+  return entry;
+}
+
+/**
+ * Tri-state validation pass over constraint results + scene diff.
+ *
+ * @param {Array<{pass: boolean|null, [k:string]: any}>} constraintResults
+ * @param {Array<{type: string, [k:string]: any}>} diff
+ * @returns {{
+ *   passing:   Array<{id?: string, constraintType?: string}>,
+ *   failing:   Array<{type: 'CONSTRAINT_FAIL', severity: 0, [k:string]: any}>,
+ *   unchecked: Array<{reasonCategory: string, reasonCode: string, hint: string, [k:string]: any}>,
+ *   diff:      Array<{type: string, severity: number, [k:string]: any}>,
+ *   totals:    {
+ *     total: number,
+ *     passing_count: number,
+ *     failing_count: number,
+ *     unchecked_count: number,
+ *     diff_count: number
+ *   }
+ * }}
+ */
+/**
+ * Copies any defined `keys` from `src` onto `dst`. Helper to keep
+ * arbitrate() free of long if-chains.
+ */
+function copyDefined(src, dst, keys) {
+  for (const k of keys) if (src[k] !== undefined) dst[k] = src[k];
+  return dst;
+}
+
+const PASSING_KEYS = ['id', 'constraintType'];
+const FAILING_KEYS = [
+  'detail',
+  'id',
+  'constraintType',
+  'reference',
+  'dx',
+  'dy',
+  'dw',
+  'dh',
+];
+
+export function arbitrate(constraintResults, diff) {
+  const passing = [];
+  const failing = [];
+  const unchecked = [];
+
+  for (const cr of constraintResults) {
+    if (cr.pass === true) {
+      passing.push(copyDefined(cr, {}, PASSING_KEYS));
+    } else if (cr.pass === false) {
+      failing.push(
+        copyDefined(cr, { type: 'CONSTRAINT_FAIL', severity: 0 }, FAILING_KEYS),
+      );
+    } else {
+      unchecked.push(buildUnchecked(cr));
+    }
+  }
+
+  const diffSorted = diff
+    .map((d) => ({ ...d, severity: DIFF_PRIO[d.type] ?? 5 }))
+    .sort((a, b) => a.severity - b.severity);
+
+  const passing_count = passing.length;
+  const failing_count = failing.length;
+  const unchecked_count = unchecked.length;
+  const diff_count = diffSorted.length;
+
+  return {
+    passing,
+    failing,
+    unchecked,
+    diff: diffSorted,
+    totals: {
+      total: failing_count + unchecked_count + diff_count,
+      passing_count,
+      failing_count,
+      unchecked_count,
+      diff_count,
+    },
+  };
+}

package/src/core/constraints/_schema.js

@@ -0,0 +1,89 @@
+/**
+ * _schema.js — Constraint Output Contract (REGEL-3 Caller-Boundary Gate)
+ *
+ *
+ * Zweck:
+ *   REGEL-3 "Spotter-Anti-Luege" (CONSTANTS.md Z.116) maschinen-mässig
+ *   erzwingen. Jeder Constraint, dessen check() ein fail-Verdict liefert,
+ *   MUSS strukturierte Pixel-Korrekturen (dx oder dy) zurueckgeben — nicht
+ *   nur Prosa. Bis Sprint-β3 war REGEL-3 textuelle Konvention; jetzt ist
+ *   sie via Zod-Schema kodiert und durch loader.validatedCheckConstraint
+ *   testbar.
+ *
+ * Vertrag:
+ *   - pass=true   → keine Pixel-Korrektur erwartet (detail darf null sein)
+ *   - pass=false  → MUSS mindestens dx ODER dy enthalten (oder beide)
+ *
+ * REGEL-4 Hexagonal:
+ *   - Modul ist Layer "core/" — darf NUR aus core/ oder Pure-Libraries
+ *     importieren. Hier: ausschliesslich `zod` (Pure-Library, transport-
+ *     agnostisch). KEIN Import aus adapters/ oder interface/.
+ *
+ * Adressiert Audit-Welle-β:
+ *   WELLE-β-004 (DISTANCE-FROM ohne dx/dy — REGEL-3-Asymmetrie zu
+ *               kanonischen Constraints CENTERED-IN/ALIGNED-LEFT).
+ *
+ * DEPENDS: zod
+ */
+import { z } from 'zod';
+
+/**
+ * constraintCheckSchema — Zod-Output-Vertrag fuer alle Constraint .check()-Resultate.
+ *
+ * Aufbau:
+ *   - Basis (z.object): pass:boolean, detail:string|null.
+ *   - .and(z.union(...)): diskriminiert nach pass-Wert.
+ *       Branch 1 (pass=true):  KEINE Pflicht zu dx/dy.
+ *       Branch 2 (pass=false): refine erzwingt dx ODER dy (optional beide,
+ *                              aber mindestens eins).
+ *
+ * REGEL-3-Pflicht bei pass=false (TYP-EHRLICH, maintainer decision S2b
+ * Step-0, D-007):
+ *   - spatial-Constraints (CENTERED-IN, ALIGNED-*, DISTANCE-FROM, …):
+ *     mindestens `dx` ODER `dy`.
+ *   - Resize-Constraints (SAME-SIZE): erfuellen REGEL-3 mit `dw` ODER `dh`
+ *     (Groessen-Delta ist ihre kanonische strukturierte Korrektur).
+ *   - non-spatial-Constraints (COLOR): haben KEINEN Pixel-Delta. Sie tragen
+ *     einen expliziten `non_spatial: true`-Marker und sind damit von der
+ *     Delta-Pflicht ausgenommen. Der Marker ist self-describing (lokal vom
+ *     Constraint deklariert, kein zentraler Typ-Katalog im Schema → keine
+ *     Drift). OHNE Marker bleibt die Delta-Pflicht streng: ein spatial/resize-
+ *     Constraint, der weder Delta noch Marker liefert, wirft weiterhin
+ *     (keine Prosa-only-Antwort fuer mess-bare Constraints).
+ */
+export const constraintCheckSchema = z
+  .object({
+    pass: z.boolean(),
+    detail: z.string().nullable(),
+  })
+  .and(
+    z.union([
+      // pass=true: keine Korrektur-Daten erwartet
+      z.object({ pass: z.literal(true) }),
+      // pass=false: REGEL-3 verlangt strukturierte Korrektur — (dx|dy) ODER
+      // (dw|dh) — ausser der Constraint markiert sich als non_spatial.
+      z
+        .object({
+          pass: z.literal(false),
+          dx: z.number().optional(),
+          dy: z.number().optional(),
+          dw: z.number().optional(),
+          dh: z.number().optional(),
+          // non-spatial-Marker (COLOR): nimmt den Constraint von der
+          // Pixel-Delta-Pflicht aus. Muss explizit `true` sein.
+          non_spatial: z.literal(true).optional(),
+        })
+        .refine(
+          (v) =>
+            v.non_spatial === true ||
+            v.dx !== undefined ||
+            v.dy !== undefined ||
+            v.dw !== undefined ||
+            v.dh !== undefined,
+          {
+            message:
+              'REGEL-3: fail-Verdict MUSS strukturierte Korrektur liefern — dx/dy (spatial) ODER dw/dh (resize) ODER non_spatial:true (z.B. COLOR). Keine Prosa-only-Antwort fuer mess-bare Constraints.',
+          },
+        ),
+    ]),
+  );

package/src/core/constraints/aligned.js

@@ -0,0 +1,42 @@
+/**
+ * aligned.js - ALIGNED-LEFT + ALIGNED-TOP Constraints
+ * Migrated from mirror.js:63-71
+ * Vector Mirror v2.0
+ */
+import { registerConstraint } from './registry.js';
+
+registerConstraint('ALIGNED-LEFT', {
+  // Uniform dispatch signature (registry.js): check(subj, ref, ctx).
+  check(subj, ref, _ctx) {
+    const dx = subj.bbox.x - ref.bbox.x;
+    const pass = Math.abs(dx) <= 2; // Hard 2px spirit level
+    if (pass) return { pass, detail: null };
+    return {
+      pass,
+      detail: `Nicht bündig. Korrektur: dx=${Math.round(-dx)}px`,
+      dx: Math.round(-dx),
+    };
+  },
+  // Uniform dispatch signature (registry.js): arrange(subj, ref, ctx).
+  arrange(_subj, ref, _ctx) {
+    return { x: ref.bbox.x };
+  },
+});
+
+registerConstraint('ALIGNED-TOP', {
+  // Uniform dispatch signature (registry.js): check(subj, ref, ctx).
+  check(subj, ref, _ctx) {
+    const dy = subj.bbox.y - ref.bbox.y;
+    const pass = Math.abs(dy) <= 2;
+    if (pass) return { pass, detail: null };
+    return {
+      pass,
+      detail: `Nicht bündig. Korrektur: dy=${Math.round(-dy)}px`,
+      dy: Math.round(-dy),
+    };
+  },
+  // Uniform dispatch signature (registry.js): arrange(subj, ref, ctx).
+  arrange(_subj, ref, _ctx) {
+    return { y: ref.bbox.y };
+  },
+});

package/src/core/constraints/centered-in.js

@@ -0,0 +1,29 @@
+/**
+ * centered-in.js - CENTERED-IN Constraint
+ * Migrated from mirror.js:36-41
+ * Vector Mirror v2.0
+ */
+
+import { getTolX, getTolY } from '../tolerance.js';
+import { registerConstraint } from './registry.js';
+
+registerConstraint('CENTERED-IN', {
+  check(subj, ref, { grid }) {
+    const dx = subj.bbox.x + subj.bbox.w / 2 - (ref.bbox.x + ref.bbox.w / 2);
+    const dy = subj.bbox.y + subj.bbox.h / 2 - (ref.bbox.y + ref.bbox.h / 2);
+    const pass =
+      Math.abs(dx) <= getTolX(ref.bbox.w, grid) &&
+      Math.abs(dy) <= getTolY(ref.bbox.h, grid);
+    if (pass) return { pass, detail: null };
+    return {
+      pass,
+      detail: `Verfehlt Zentrum. Korrektur: dx=${Math.round(-dx)}px, dy=${Math.round(-dy)}px`,
+      dx: Math.round(-dx),
+      dy: Math.round(-dy),
+    };
+  },
+  // Uniform dispatch signature (registry.js): arrange(subj, ref, ctx).
+  arrange(_subj, ref, _ctx) {
+    return { cx: ref.bbox.x + ref.bbox.w / 2, cy: ref.bbox.y + ref.bbox.h / 2 };
+  },
+});

package/src/core/constraints/color.js

@@ -0,0 +1,63 @@
+/**
+ * color.js - COLOR Constraint
+ * Migrated from mirror.js:104-107
+ * Vector Mirror v2.0
+ * Uses ctx.value (target color name)
+ */
+import { registerConstraint } from './registry.js';
+import { parseColor } from '../../lib/palette.js';
+
+registerConstraint('COLOR', {
+  // COLOR braucht keine Referenz (non-spatial, Ziel-Farbe steckt in ctx.value).
+  // Ohne diesen Marker wuerde die pipeline-Wache (fail-closed-Default) COLOR
+  // faelschlich als referenz-pflichtig behandeln.
+  requiresReference: false,
+  // Uniform dispatch signature (registry.js): check(subj, ref, ctx).
+  check(subj, _ref, { value }) {
+    // COLOR ist non-spatial (D-007): kein Pixel-Delta. Der non_spatial-Marker
+    // nimmt fail-Verdicts von der REGEL-3-Delta-Pflicht aus (_schema.js).
+    // Der spaetere COLOR-attribute_fix ist C-04/L-003-Arbeit, NICHT hier.
+    if (value === undefined || value === null) {
+      return {
+        pass: false,
+        detail: `Kein Farbwert angegeben fuer #${subj.id}.`,
+        non_spatial: true,
+      };
+    }
+    // §HEAL3b: eine nicht messbare Farbe (use-Instanz → 'indeterminate', §HEAL3b
+    // im Renderer) kann nicht GEGEN ein Ziel geprüft werden. Ein pass:false meldete
+    // eine FALSCHE Verletzung und triggerte eine SCHÄDLICHE Korrektur auf eine
+    // womöglich schon korrekte Farbe (Blind-Trust-Gesetz). Unmessbar → UNCHECKED.
+    if (subj.color === 'indeterminate') {
+      return {
+        pass: null,
+        reasonCode: 'MEASUREMENT_AMBIGUOUS',
+        reasonCategory: 'MODEL',
+        detail: `Farbe von #${subj.id} ist nicht messbar (use-Instanz) — COLOR ${value} nicht prüfbar.`,
+      };
+    }
+    // §H9 K-08a: subj.color ist IMMER der quantisierte Name (grid.js →
+    // parseColor/CIELAB). Der Soll-Token MUSS durch DENSELBEN Quantisierer,
+    // sonst vergleicht der Check zwei Repräsentationen derselben Farbe
+    // (#ff0000 vs red = False Negative). Unbekannte Token fallen in
+    // parseColor unverändert durch → ehrlicher FAIL bleibt.
+    //
+    // §H9 P3 MESS-GRANULARITÄT (ausgesprochen, bewusst): `COLOR <hex>`
+    // bedeutet nearest-named-color im Mess-Farbraum (140 W3C-Namen, CIELAB —
+    // parseColor/rgbToColorName). Zwei Hexes, die in DIESELBE Palette-Zelle
+    // quantisieren (z.B. #ff0000 und #ff0001 → beide 'red'), gelten als
+    // GLEICH — das ist die Granularität der Messung, kein Bug. Hexes mit
+    // VERSCHIEDENEM quantisierten Namen (#ff0000 'red' vs #ff6347 'tomato')
+    // bleiben verschieden → FAIL (Pin: tests/h9_red/test_h9_k08a.mjs).
+    // Feinere Unterscheidung (Hex-exakter Kanal) wäre eine Design-Runde,
+    // keine stille Verfeinerung hier.
+    const pass = subj.color === parseColor(value);
+    if (pass) return { pass, detail: null };
+    return {
+      pass,
+      detail: `Farbe ist ${subj.color}, soll ${value} sein.`,
+      non_spatial: true,
+    };
+  },
+  // No arrange — color cannot be spatially computed
+});