OrcaSlicer/filament_id_plan_v3.md

# filament_id plan v3: OFL as the catalog, content-addressed product ids

Supersedes §5 of `filament_id_plan_v2.md` (whose P+md5 verdict stands unchanged) and
revises the mint rule of `filament_id_plan.md` (v1, implemented on `feature/filament_id`).
Decision driver: v1's mint key scoped families to the *profile bundle* (printer brand), so
one commercial product tuned in N bundles carries N ids — e.g. PolyLite PLA ships in five
bundles (`BBL`, `OrcaFilamentLibrary`, `OrcaArena`, `Qidi`, `Snapmaker`), all with
`filament_vendor: "Polymaker"`, under up to five different ids (`GFL00`, `OFceJcLf`, …).
That contradicts what `filament_id` means: one id per commercial product line.

## 0. The architecture

Three tiers, two frozen islands:

1. **BBL island — untouched.** Bambu profiles keep their `GF*` catalog ids byte-for-byte
   (device/RFID/cloud contract). No convergence between GF and OFL ids is attempted: the
   same product may permanently carry `GFL00` on the BBL side and an `OF*` id everywhere
   else. This is a deliberate trade for simplicity; v2's curated-GF-adoption (old W4) is
   dropped.
2. **`QD_*` island — untouched.** Qidi's box builds `QD_<series>_<vendor>_<type>` from
   device enums and requires exactly-matching presets (`QidiPrinterAgent.cpp:146-152`).
   Qidi presets carrying `QD_*` are exempt from re-minting, forever.
3. **Everything else converges on OrcaFilamentLibrary.** OFL is the product catalog: a
   material family's id is declared once, on its OFL family root. Vendor bundles carry
   only per-printer *specializations* of OFL families — same base name, non-empty
   `compatible_printers`, **no `filament_id` key** — which (a) alias-shadow the OFL preset
   on the printers they claim (`Preset.cpp:3684-3714`: "Generic PLA @Qidi Q2 0.4mm nozzle"
   hides "Generic PLA @System" on that machine) and (b) resolve the OFL family's id
   through the loader's inherits/base-bundle walk (`PresetBundle.cpp:4842-5080`). Products
   OFL does not (yet) carry mint their id in the vendor bundle **with the same rule**;
   because the key is bundle-independent (§1), later hoisting the family into OFL never
   changes its id.

Convergence therefore happens by *single declaration point*, not by copying ids across
bundles — no adoption registry, no cross-bundle id claims to curate.

## 1. The mint rule

```
triple = (filament_vendor, filament_type, family_name)      # from the family ROOT's flattened config
key    = "filament_product/<filament_vendor>/<filament_type>/<family_name>"
id     = "OF" + base62_6( uuid5( FILAMENT_ID_NAMESPACE, key ) )     # namespace unchanged:
                                                                    # c4d3ff49-4c32-5534-a3e3-00894157ab97
```

- **Triple resolution.** All three values come from the family root preset's *flattened
  effective config* (`filament_vendor` and `filament_type` are inheritable list options —
  take the first element; family_name = the root's base name, `\s?@.*` stripped once).
  For own-key-layout families (no root), each declaring preset's flattened config is used
  and CI requires all declarers of one family to agree on the triple. A root that resolves
  an empty `filament_vendor` or `filament_type` is a CI error (generics use `"Generic"`).
  Values enter the key verbatim (UTF-8, no case folding).
- **Bundle-independent by design.** The key contains no bundle name, so the same product
  yields the same id whether minted in OFL or in a vendor bundle; migrating a family into
  OFL (§0.3) is id-stable. Two bundles independently adding the same triple converge
  automatically — and that is correct, because equal (vendor, type, name) *is* the
  definition of "same product" here. The known look-alike hazards stay separated by the
  type component: the 4 same-name-different-type groups (Flashforge `Generic PLA Silk` as
  SILK, OFL `Generic PETG-CF` as PETG, `Generic PA6-CF`, `Generic PE-CF`) hash apart until
  their type bugs are fixed (§5, W3) and converge automatically after — self-healing that
  pure name-keying (rejected in v2) could not provide.
- **Format and salt unchanged from v1**: 8 chars, `OF` + 6 base62; deterministic `/1`,
  `/2`… salt past any taken or retired id (the O+7 widening was evaluated and rejected:
  62⁶ expects 1.9×10⁻⁵ collisions at today's 1,455 families, and `^O.{7}$` would sweep 35
  legacy ids into the conformance gate vs. one today).
- **Content-addressed, deliberately.** If any triple component changes — a family rename,
  a `filament_vendor` correction, a `filament_type` fix — the id changes with it. This
  *replaces* v1's "ids are immutable once shipped" with "ids are derivable from the
  product identity, and identity changes are migrations" — made safe by the succession
  ledger (§2). `renamed_from` still gates preset-name compatibility as before.
- CLI: `--mint "Polymaker/PLA/PolyLite PLA"` prints without touching the tree; running
  the script plain inserts missing ids; CI errors print the expected id.

## 2. The succession ledger (the amendment that makes this safe)

Shipped ids are referenced outside the tree: AFC/Klipper lane data, Bambu AMS trays
holding OFL-only materials, on-device PA-calibration records, user-root preset copies,
3mf `slice_info`. Retiring an id without a forwarding pointer downgrades all of those to
`Generic <type>` fallbacks. Therefore:

- **Schema.** `scripts/retired_filament_ids.json` entries become objects:
  `{"retired": {"OGFL99": {"claims": [...], "successor": "OFxxxxxx"}}}`. Append-only as
  before; a successor may itself be retired later (chains allowed, cycle-checked, and
  followed to the live end). A retired id may never be minted again (check 4 unchanged).
  Cross-island *hint* entries are permitted for ids Orca cannot retire because another
  island owns them (e.g. `GFL99 → <OFL Generic PLA id>`): consulted only when no live
  preset matches, so BBL installs still resolve `GFL99` natively first. By the same
  principle, an id in a foreign island's space (`GF*`/`QD_*`) that vanishes from the tree
  is **released with a hint, never retired** — the island's catalog owns it and may
  legitimately (re)ship it later, which check 4 must never block. (Implementation
  amendment, v3.0: `--update-snapshot` routes such ids to `hints` automatically; hint
  keys may be absent from the tree.)
- **Shipped and consulted at runtime.** The ledger ships in `resources/`; a small helper
  (`resolve_filament_id_succession(id)`) follows the chain and is consulted **only on
  resolution miss**, before the `Generic <type>` name fallback, in:
  `PresetBundle::get_filament_by_filament_id` (covers `DevFilaBlackList`, `SelectMachine`
  warnings, `Plater` tray configs in one place), the AMS sync match predicates
  (`PresetBundle.cpp:3151`, `:3252-3254` miss paths at `:3157-3169`/`:3260-3305`),
  `PresetComboBoxes::add_ams_filaments`, `MachineObject::setting_id_to_type`
  (`DeviceManager.cpp:2545` miss branch), calibration-history name lookup
  (`CaliHistoryDialog.cpp:62`), and the #14423 Moonraker lane matching when it lands.
  With this in place the OFL re-mint is near-residue-free and every future
  content-addressed rename stays safe.
- **Kill the hardcoded generic map.** `MoonrakerPrinterAgent::map_filament_type_to_generic_id`
  (`MoonrakerPrinterAgent.cpp:608-658`) hardcodes 23 OFL ids (`OGFL99`… `OFLSBS99`).
  Replace it with a runtime lookup of the OFL generic preset by name ("Generic PLA
  @System" → its current id), removing the code↔profile lockstep permanently. (This also
  releases `OFLSBS99`, v2's one frozen OF-shaped legacy id, for normal re-minting.)

## 3. Validation rule changes

- **Check 3 (mint conformance)** becomes a pure function of the root's triple: a non-BBL,
  non-`QD_*` id must equal `mint(triple)` ± salt, or be snapshot-grandfathered (the
  grandfather set shrinks to ≈ nothing for non-BBL once migration completes).
- **Check 5 (alias hygiene) generalizes and becomes load-bearing.** For *every*
  OFL-carried family (not just `Generic * @System`): a vendor specialization must keep the
  OFL base name (else the OFL preset un-shadows and creates a live per-printer duplicate —
  v1's P7 pattern) and non-empty `compatible_printers`, and must not declare an id. The
  C++ validator's OFL-aware `-f` (`PresetBundle.cpp:5674-5753`) already enforces the
  runtime consequence; the script check names the rename as the cause.
- **New check 8 (triple integrity):** every id-declaring family resolves a complete,
  family-consistent triple; roots missing `filament_vendor`/`filament_type` error.
- **New check 9 (succession integrity):** every retired entry's successor chain ends at a
  live tree id (or a documented cross-island hint target); no cycles; retired ids absent
  from the tree.
- Snapshot mechanism, reserved spaces (`GF*`→BBL, `QD_*`→Qidi, `P`-hex/`null`→user-custom;
  v2's do-not-reserve-`OF*` note stands), and check 1/2/4/7 are unchanged.

## 4. Migration phases

**v3.0 — tooling + prerequisites (no profile changes).** New mint + triple resolver
(reuse the flatten machinery), succession schema migration + C++ lookup helper wired into
the §2 miss paths, Moonraker map → runtime lookup, checks 3/5/8/9, tests. Carry v2's W1
client hardening (skip tray-wipe/temp-rewrite when a system preset holds the id; relax
the `DeviceManager.cpp:5252` assert; guard the `PresetBundle.cpp:3717` deref) — it ships
first regardless. **W3 type fixes land here**, *before* any re-mint: type is now a key
component, so minting before fixing OFL `Generic PETG-CF`/`Generic PE-CF` would re-id
those families twice.

**v3.1 — OFL re-mint.** Every OFL-declared id re-derives from its triple (mirrors like
`OGFA00`, generics like `OGFL99`, blocks like `OEPLAB00` — all of it); each old shipped id
gains a succession entry pointing at its replacement; the 26 GF-shaped ids OFL declares
(measured at v3.0: only one of them, `GFOT001`, is also declared by BBL) are released to
the BBL island space with hints at the re-minted families — two-island purity. Snapshot
regenerated; full gate battery + fixture overlays (this phase touches preset-visibility
machinery only via ids, but the fixtures are cheap insurance). Implementation notes
(v3.1, executed): OFL generic ids relocate from the fdm_filament_* template bases onto
the product-named "Generic X @System" presets first, so their triples carry the product
name; `fdm_filament_pc` keeps a (transitional) declaration because 7 Prusa presets
inherit it directly — the v3.2 Prusa worksheet re-homes them and deletes it.

**v3.2 — vendor bundles, worksheet-per-vendor (v1 machinery).** Three sub-cases:
  (a) the **391 unshipped v1 `OF*` mints** re-derive under the triple key — no succession
  entries (they never shipped; a documented one-time `--forget-never-shipped <list>` drops
  them from the ledger lineage instead of retiring them, since the ledger's rationale —
  ids live on in user presets and 3mfs — cannot apply to unreleased ids);
  (b) **true generic tunings** riding copied legacy ids (`GFL99`-class) drop their own id
  and re-point to the OFL generic family (the v1 Sovol pattern) — their old ids get
  cross-island hints where BBL owns them, succession entries otherwise;
  (c) remaining **shipped legacy ids** (numeric, name-shaped, pseudo-GF, the 57
  multi-vendor GF residue, the 10 P-hex — everything non-BBL/non-`QD_*`, ~800 ids)
  re-mint with succession entries. Retiring the 10 P-hex system ids also removes the last
  system ids from `check_ams_filament_valid`'s destructive P-gate.

**v3.3 — ongoing consolidation (optional, per-vendor, id-stable).** Hoist vendor-unique
products into OFL where a family is genuinely multi-vendor material; thanks to the
bundle-independent key this never changes ids, so it can proceed opportunistically.

## 5. Gates (every phase)

`python scripts/orca_extra_profile_check.py` exit 0; `assign_filament_ids.py --check`
exit 0; unit tests green (existing 46 + new triple/succession/adoption tests); validator
`-l 2` exit 0, `-f` tree-wide exit 0, `-r` BBL+Qidi exit 0; custom-preset fixture
archives; config-equivalence — flattened effective configs differ only in `filament_id`
(re-mints), `inherits`/`compatible_printers` (re-points, as prescribed per worksheet), and
the W3 `filament_type` corrections. New for v3: a C++ test that a retired id resolves
through the succession chain in the sync miss path, and a Moonraker test that the generic
map lookup matches the shipped OFL presets. Manual AMS smoke test (tray set → old-id
resolve → clear) stays a release-checklist item.

## 6. Accepted costs (explicit)

- **GF ↔ OFL divergence is permanent** for products in both catalogs (PolyLite PLA ≠
  `GFL00` outside BBL). The forward-looking fix is PR #12724-style filament-database
  upload, where Orca ids become first-class device artifacts.
- **Renames/type-fixes re-id families** (by design); the succession ledger absorbs the
  device/user residue, but each one is still a ledger entry and a snapshot diff to review.
- **User roots** keep whatever id they copied at creation; with succession lookup in
  `get_filament_by_filament_id` they now *resolve* instead of dangling — strictly better
  than v1's accepted residue.
- **One-time field transition**: devices holding pre-v3 ids (AFC lanes, AMS trays, cali
  records) resolve via succession on updated clients; *older* Orca versions and
  BambuStudio never resolved OFL-only ids anyway (`?`/generic fallback — unchanged for
  them).

## 7. Open decisions

1. Whether v3.2(b)'s cross-island hints (`GFL99` → OFL generic) are wanted at launch or
   deferred (pure-miss-path feature; zero risk to BBL installs, small review surface).
2. v3.3 pacing: per-vendor PRs opportunistically vs. a dedicated consolidation train.
3. Whether to fold v2's W5 (P+md5 ids for inherited *user* presets, PR #13315) into v3.0's
   C++ work or keep it a separate PR (recommended: separate; W1 is its only prerequisite).

## 8. Evidence

Carried from v2 §8 (all re-verified this session), plus: `filament_vendor` audit — 49
distinct strings tree-wide, `"Polymaker"` byte-consistent across all five PolyLite-PLA
bundles; multi-vendor different-family GF residue = 57 ids; `MoonrakerPrinterAgent.cpp:
608-658` = 23 hardcoded OFL ids; mint examples verified live (`Qidi/PolyLite PLA` →
`OFceJcLf` under the v1 key — the fragmentation this plan removes; salt determinism
`OF8afiMO`). Alias shadowing and the OFL id fallback verified at `Preset.cpp:3684-3714`
and `PresetBundle.cpp:4842-5080` during the v1 audit; per-printer `-f` semantics at
`PresetBundle.cpp:5674-5753`.