feat(#93): IMP-55 u1~u12 frontend manual section swap detection (manual_section_assignment bool axis + drag-only marker gate + dual-axis persistence + backend manual-true gate)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Front/client/tests/user_overrides_write.test.ts

@@ -85,6 +85,22 @@ function sliceHandler(source: string, name: string): string {
   return source.slice(start, end);
 }
 
+/**
+ * IMP-55 #93 u8 — strip JS/TS line + block comments so source-pattern
+ * regex checks assert against LIVE code only. The u5 / u7 docblocks in
+ * Home.tsx intentionally reference removed identifiers (e.g. `defaultByZone`,
+ * `sameAsDefault`, `zoneSectionsDiff`) and the marker axis name in prose to
+ * document the Stage 1 root cause for future readers — those references are
+ * documentation, not behavior, and must not trigger negative-match guards.
+ * Strips `// ...` to EOL and `/* ... *​/` (incl. multi-line) — keeps string
+ * literals intact because we only consume the result for regex-match tests.
+ */
+function stripComments(source: string): string {
+  return source
+    .replace(/\/\*[\s\S]*?\*\//g, "")
+    .replace(/\/\/.*$/gm, "");
+}
+
 describe("Home.tsx write-side wiring (IMP-52 u10) — source pattern", () => {
   it("handleSectionDrop persists zone_sections behind uploadedFile gate", () => {
     const block = sliceHandler(HOME_TSX, "handleSectionDrop");
@@ -567,3 +583,220 @@ describe("restore-on-reopen end-to-end (IMP-52 u10)", () => {
     expect(remapPersistedFramesToZoneFrames(plan, persisted.frames)).toEqual({});
   });
 });
+
+// ─── IMP-55 #93 u8 — manual_section_assignment intent marker contract ─────
+// Verifies four axes of the marker contract introduced in u3 (type) / u5
+// (apply reset) / u6 (drag flip + co-PUT) / u7 (generate gate):
+//   1) Drag dual-axis persistence — handleSectionDrop persists BOTH
+//      `zone_sections` AND `manual_section_assignment: true` in the SAME
+//      PUT body (co-PUT atomicity — disk never sees post-drop zone_sections
+//      without the marker).
+//   2) Apply / cancel reset — handleApplyPendingLayout writes explicit
+//      `manual_section_assignment: false` after the `...overrides` spread,
+//      and handleCancelPendingLayout relies on createInitialUserSelection
+//      (which u3 seeds to `false`) to drop a prior `true`.
+//   3) Marker-gated forwarding — handleGenerate gates `overrides.zoneSections`
+//      forwarding strictly on `manualMarker === true` (NOT truthiness, NOT
+//      `!= null`, NOT presence). u3-seeded `false` and absent values both
+//      skip forwarding.
+//   4) sameAsDefault NOT required — the Stage 1 anti-pattern (defaultByZone
+//      / sameAsDefault / zoneSectionsDiff self-compare loop) is gone from
+//      `handleGenerate` entirely; the marker is the source of intent.
+
+describe("IMP-55 #93 u8 — manual_section_assignment marker contract", () => {
+  it("handleSectionDrop sets marker true in-memory before persistence", () => {
+    const block = sliceHandler(HOME_TSX, "handleSectionDrop");
+    // finalSelection literal (built from zoneSelected, then marker = true)
+    // must occur BEFORE the saveUserOverrides call so the in-memory state
+    // and the PUT body source from the same overrides shape.
+    const markerIdx = block.search(/manual_section_assignment:\s*true/);
+    const saveIdx = block.search(/saveUserOverrides\(/);
+    expect(markerIdx).toBeGreaterThan(-1);
+    expect(saveIdx).toBeGreaterThan(-1);
+    expect(markerIdx).toBeLessThan(saveIdx);
+  });
+
+  it("handleSectionDrop co-PUTs zone_sections + manual_section_assignment:true (single body)", () => {
+    const block = sliceHandler(HOME_TSX, "handleSectionDrop");
+    // Single saveUserOverrides call carrying BOTH axes. The regex spans the
+    // call body to prove the two keys live in the same object literal — a
+    // future split into two PUTs would race the 300ms debounce and re-open
+    // the IMP-55 stale-disk window.
+    expect(block).toMatch(
+      /saveUserOverrides\([\s\S]*?zone_sections:[\s\S]*?manual_section_assignment:\s*true[\s\S]*?\)/,
+    );
+    // Exactly ONE saveUserOverrides call in the handler.
+    const calls = block.match(/saveUserOverrides\(/g) ?? [];
+    expect(calls.length).toBe(1);
+  });
+
+  it("handleApplyPendingLayout resets the marker to false in overrides literal", () => {
+    const block = sliceHandler(HOME_TSX, "handleApplyPendingLayout");
+    // After spreading `...p.userSelection.overrides`, the explicit
+    // `manual_section_assignment: false` overrides any prior-drag `true`.
+    // Without this the layout flip would carry the marker through, and u7
+    // would forward auto-carried assignments as user overrides → the
+    // PARTIAL_COVERAGE regression that motivated IMP-55.
+    expect(block).toMatch(/\.\.\.p\.userSelection\.overrides[\s\S]*?manual_section_assignment:\s*false/);
+  });
+
+  it("handleCancelPendingLayout uses createInitialUserSelection (u3 seeds false)", () => {
+    const block = sliceHandler(HOME_TSX, "handleCancelPendingLayout");
+    // Cancel discards all pending in-memory edits via the fresh-selection
+    // helper — the seed (u3) is the single source of truth for the
+    // in-memory marker on this path. u12 adds a separate disk-side
+    // saveUserOverrides PUT (covered by the u12 describe block below);
+    // the in-memory userSelection literal still has no explicit marker
+    // field — the seed handles it.
+    expect(block).toMatch(/createInitialUserSelection\(p\.slidePlan\)/);
+    // In-memory contract: no `manual_section_assignment` property appears
+    // inside the userSelection assignment. The only marker reference in
+    // live code lives inside the u12 saveUserOverrides(...) call body.
+    const codeOnly = stripComments(block);
+    expect(codeOnly).not.toMatch(
+      /userSelection:[\s\S]*?manual_section_assignment/,
+    );
+  });
+
+  it("handleGenerate gates overrides.zoneSections on manualMarker === true (strict bool)", () => {
+    const block = sliceHandler(HOME_TSX, "handleGenerate");
+    // Marker read AND strict-equality gate. `===` not `==`, not truthiness,
+    // not presence — so `false` / absent both skip forwarding (fail-closed).
+    expect(block).toMatch(/state\.userSelection\.overrides\.manual_section_assignment/);
+    expect(block).toMatch(/manualMarker\s*===\s*true/);
+    // The assignment to `overrides.zoneSections` must live INSIDE the
+    // marker-true branch.
+    const gateIdx = block.search(/if\s*\(\s*manualMarker\s*===\s*true\s*\)/);
+    const assignIdx = block.search(/overrides\.zoneSections\s*=/);
+    expect(gateIdx).toBeGreaterThan(-1);
+    expect(assignIdx).toBeGreaterThan(gateIdx);
+  });
+
+  it("handleGenerate filters forwarded zone_sections to valid zone_ids only (cross-layout safety)", () => {
+    const block = sliceHandler(HOME_TSX, "handleGenerate");
+    // A stale persisted layout could carry zone_ids that do not exist in
+    // the current sourcePlan (e.g. horizontal-2 `top`/`bottom` while the
+    // current layout is vertical-2 `left`/`right`). Those foreign keys
+    // must be dropped before reaching the backend `--override-section-
+    // assignment` so they cannot trigger PARTIAL_COVERAGE.
+    expect(block).toMatch(/validZoneIds\s*=\s*new Set\(\s*sourcePlan\.zones\.map\(\(z\)\s*=>\s*z\.zone_id\)/);
+    expect(block).toMatch(/if\s*\(!validZoneIds\.has\(zoneId\)\)\s*continue/);
+  });
+
+  it("handleGenerate no longer contains the IMP-08 B-3 self-compare anti-pattern", () => {
+    // Strip comments — the u7 docblock intentionally references the removed
+    // identifiers (`defaultByZone` / `sameAsDefault` / `zoneSectionsDiff`)
+    // in prose to explain the Stage 1 root cause for future readers; the
+    // regression we guard against is the LIVE code re-emerging.
+    const block = stripComments(sliceHandler(HOME_TSX, "handleGenerate"));
+    // The Stage 1 root cause: these identifiers compared user input against
+    // itself (sourcePlan === effectiveSlidePlan → zones === pendingZones,
+    // both derived from the same overrides.zone_sections). u7 deleted the
+    // entire block.
+    expect(block).not.toMatch(/\bdefaultByZone\b/);
+    expect(block).not.toMatch(/\bsameAsDefault\b/);
+    expect(block).not.toMatch(/\bzoneSectionsDiff\b/);
+  });
+
+  it("co-PUT payload contract: marker=true + zone_sections land in a single PUT body", async () => {
+    fetchMock.mockResolvedValue(mockResponse({}));
+    // Shape produced by handleSectionDrop after the u6 marker flip.
+    void saveUserOverrides("03_demo", {
+      zone_sections: { left: ["03-2"], right: ["03-1"] },
+      manual_section_assignment: true,
+    });
+    vi.advanceTimersByTime(300);
+    await drainMicrotasks();
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const body = lastPutBody() as Record<string, unknown>;
+    // Both axes in the same PUT body — exact equality, not arrayContaining,
+    // because any extra axis would mean a foreign mutation leaked through.
+    expect(Object.keys(body).sort()).toEqual(
+      ["manual_section_assignment", "zone_sections"].sort(),
+    );
+    expect(body.manual_section_assignment).toBe(true);
+    expect(body.zone_sections).toEqual({ left: ["03-2"], right: ["03-1"] });
+  });
+
+  it("co-PUT payload contract: marker=false carries explicitly through saveUserOverrides", async () => {
+    // u12 will add the apply/cancel explicit `false` PUT; the typed client
+    // must already propagate the literal `false` through the debounce
+    // bucket. A truthiness-based coalesce in the bucket merge would drop
+    // the value and re-open the stale-disk window. This locks the wire
+    // contract independently of the u12 caller-site write.
+    fetchMock.mockResolvedValue(mockResponse({}));
+    void saveUserOverrides("03_demo", { manual_section_assignment: false });
+    vi.advanceTimersByTime(300);
+    await drainMicrotasks();
+    const body = lastPutBody() as Record<string, unknown>;
+    expect(Object.keys(body)).toEqual(["manual_section_assignment"]);
+    expect(body.manual_section_assignment).toBe(false);
+  });
+});
+
+// ─── IMP-55 #93 u12 — stale-disk marker reset on apply / cancel ───────────
+// u5 resets the in-memory marker on layout apply, and u3's seed via
+// `createInitialUserSelection` resets it on cancel. But the disk persists
+// independently — a prior drag wrote `true` via u6's co-PUT, so after a
+// page reload the u3 restore branch would re-seed `true` and the u7 gate
+// would forward auto-carried section assignments → PARTIAL_COVERAGE
+// regression. u12 closes that window by writing `manual_section_assignment:
+// false` to disk via saveUserOverrides on both apply and cancel paths.
+describe("IMP-55 #93 u12 — stale-disk marker reset on layout apply/cancel", () => {
+  it("handleApplyPendingLayout source contains a marker=false saveUserOverrides PUT", () => {
+    const block = sliceHandler(HOME_TSX, "handleApplyPendingLayout");
+    // Stripped-comment source so the u5 docblock prose doesn't satisfy the
+    // assertion — must be a real call expression.
+    const code = stripComments(block);
+    // Uploaded-file gate (mirrors the u6 / other handler pattern — the
+    // demo-mode initial render path must not PUT to an empty key).
+    expect(code).toMatch(
+      /if\s*\(\s*p\.uploadedFile\s*\)[\s\S]*?saveUserOverrides\([\s\S]*?manual_section_assignment:\s*false[\s\S]*?\)/,
+    );
+    expect(code).toMatch(/deriveUserOverridesKey\(p\.uploadedFile\.name\)/);
+  });
+
+  it("handleCancelPendingLayout source contains a marker=false saveUserOverrides PUT", () => {
+    const block = sliceHandler(HOME_TSX, "handleCancelPendingLayout");
+    const code = stripComments(block);
+    // Cancel handler converts from arrow-body to function-body for the
+    // disk PUT; the in-memory reset still comes from createInitialUserSelection.
+    expect(code).toMatch(
+      /if\s*\(\s*p\.uploadedFile\s*\)[\s\S]*?saveUserOverrides\([\s\S]*?manual_section_assignment:\s*false[\s\S]*?\)/,
+    );
+    expect(code).toMatch(/createInitialUserSelection\(p\.slidePlan\)/);
+  });
+
+  it("apply path PUT payload: marker=false carries alone (no auto-carry leakage)", async () => {
+    // The apply handler issues a dedicated PUT for the marker reset that is
+    // independent of the (conditional) zone_geometries PUT and of the
+    // in-memory zone_sections rewrite. The wire contract for this PUT must
+    // contain only the marker — if zone_sections leaked into the same body
+    // it would re-arm the u9 backend fallback gate against u12's intent.
+    fetchMock.mockResolvedValue(mockResponse({}));
+    void saveUserOverrides("03_demo", { manual_section_assignment: false });
+    vi.advanceTimersByTime(300);
+    await drainMicrotasks();
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const body = lastPutBody() as Record<string, unknown>;
+    expect(Object.keys(body)).toEqual(["manual_section_assignment"]);
+    expect(body.manual_section_assignment).toBe(false);
+  });
+
+  it("apply path PUT is unconditional (does NOT gate on hadPriorGeoms)", () => {
+    // The u4 zone_geometries PUT inside handleApplyPendingLayout is
+    // conditional (`p.uploadedFile && hadPriorGeoms`). The u12 marker PUT
+    // must NOT inherit that gate — a stale disk `true` can exist without
+    // any prior zone_geometries, so the reset must always fire.
+    const code = stripComments(sliceHandler(HOME_TSX, "handleApplyPendingLayout"));
+    // Locate the marker PUT and verify its enclosing `if` clause is just
+    // `p.uploadedFile`, not the compound `... && hadPriorGeoms` guard.
+    const markerCallMatch = code.match(
+      /if\s*\(([^)]*)\)\s*\{[^}]*saveUserOverrides\([^)]*manual_section_assignment:\s*false[^)]*\)/,
+    );
+    expect(markerCallMatch).not.toBeNull();
+    if (markerCallMatch) {
+      expect(markerCallMatch[1].trim()).toBe("p.uploadedFile");
+    }
+  });
+});