`verification/filemaker-graph-repair-runbook.md`

96 lines

# TK-10922 — FileMaker graph runbook (Steve's 10 minutes)

Everything up to step 4 is **read-only and changes nothing.** Stop after step 3 and hand me
the file if you'd rather I do the analysis — that's the whole point of the parser.

---

## Step 1 — open the file (read-only)

FileMaker Pro is already installed and this host is in your recent-files list:

```
fmnet:/designerwallcoverings.account.filemaker-cloud.com/WALLPAPER
```

Open it with an account that has **[Full Access]** — the Database Design Report is greyed
out for any lesser privilege set. That's why I can't do this over the API: the Data API
account has no schema rights, and DDR isn't exposed to it at all.

## Step 2 — export the Database Design Report (read-only)

**Tools ▸ Database Design Report…**

- Available files: tick **WALLPAPER only** (untick everything else — the other files make it
slow and add noise)
- Include fields for: leave all ticked
- Report format: **XML** ← not HTML; the parser reads XML
- Save to: `~/Desktop/ddr/`

This writes a file and modifies nothing in the database.

## Step 3 — hand it to me

```
node scripts/diagnostics/parse-ddr-cascade-map.mjs ~/Desktop/ddr/WALLPAPER.xml --base WALLPAPER
```

That prints three sections:

1. **Dangling table occurrences** — any TO whose base table no longer resolves
2. **The cascade-delete impact map** — every relationship that deletes related records, i.e.
exactly what would start happening on every delete once the graph works again
3. **Culprit candidates** — the intersection: a cascade-delete relationship pointing at a
dangling TO. That is the thing throwing `[110]`.

The parser is smoke-tested against a fixture (`scripts/diagnostics/fixtures/sample-ddr.xml`).
If your real DDR parses as 0 occurrences, the tag names differ in your FileMaker version —
tell me and I'll adapt it, don't hand-read 251 layouts' worth of XML.

## Step 4 — the repair (only after reading section 2) ⚠️ GATED

**File ▸ Manage ▸ Database… ▸ Relationships**

A dangling table occurrence renders distinctively — the TO box shows a missing-table
indicator instead of a normal field list. Find the one section 3 named.

**Disarm it. Do not repoint it.**

| Action | Effect |
|---|---|
| Untick *"Delete related records in this table when a record is deleted in the other table"* | **DISARMS** a cascade that is currently inert-by-error. Safe. |
| Delete the dangling TO / its relationship outright | **DISARMS**, and removes the dead weight. Safe if nothing else uses it. |
| Repoint it at a real table ("fixing" it properly) | **ARMS** the cascade across every future delete in a 470,000-record file. This is the dangerous one. |

Those last two rows are opposite outcomes reached by the same "fix the error" instinct. The
panel's contrarian is why this table exists — section 2 tells you what you'd be arming.

Also check **File ▸ Manage ▸ External Data Sources…** for an entry pointing at a file that
no longer exists. That's the other well-known source of `[110]` on delete.

## Step 5 — tell me, and I finish it

The three deletes take about ten seconds once the graph is clean:

```
node scripts/execute-sweep.mjs \
--plan data/plans/HSW-corrected-3record-2026-08-28T14-32-26-000Z.json \
--ticket TK-10922-execute-corrected-mfr-repair-3-record-de --apply
```

Snapshot-first, sku-match guard, keep-worthiness guard, never-delete-to-zero guard, and a
reversible-ledger entry per delete — all already wired and dry-run-clean as of today.

---

## If you'd rather not touch the graph at all

The panel's dissent (2 of 7 votes, and the contrarian's pick) is a legitimate alternative:
stamp the three placeholders' existing free-text `Mfr Pattern` field with
`SUPERSEDED - see master <keep-id>`. No schema change, no cascade walk, works through the API
I already have, reversible from the snapshots I'm holding, and it immediately stops the record
masquerading as a real manufacturer code. The duplicates stay in the file.

It's a canonical write, so it needs your explicit go — but it's the one path that doesn't
require you to open FileMaker Pro at all.