v6.x slot rename + migrate alias map (Mk4 canonical names)

[Wolfe-Jam]

Gap

The pre-v6 cli (March 2026) renamed 6 slots to Mk4 canonical names with bi-directional aliases (read either, write Mk4). v6 ground-up rewrite reverted all of it — src/core/slots.ts still uses pre-Mk4 names.

Memory entry faf-cli-slot-rename.md documents the v5 implementation as "completed" — the claim is stale relative to v6.

Renames

Current (v6)	Mk4 canonical
stack.frontend	stack.framework
stack.css_framework	stack.css
stack.state_management	stack.state
stack.api_type	stack.api
stack.database	stack.db
stack.package_manager	stack.pkg_manager

Scope

1. Rename the 6 slot paths in src/core/slots.ts to Mk4 canonical.
2. Read path — accept both old + new names (backward compat for existing .faf files; 36k+ downloads in the wild).
3. Write path — emit Mk4 names only on next save.
4. faf migrate — add the alias map so an explicit faf migrate run rewrites old → new in place.
5. Tests cover both old-name-on-disk and new-name-on-disk cases.
6. Slot descriptions / display labels updated.
7. Parity gate (tests/parity-brake.test.ts) — confirm xai-faf-rust ref impl uses the same Mk4 names; if not, coordinate in lockstep.

Why now

• v6.6.0 = The Trophy Edition; the v5 era promised this rename was already done. v6 should honour the canonical vocabulary, not the legacy.
• Pairs naturally with Trophy-only recommendation — clean vocabulary, clean threshold, same release line.
• Closes the memory↔code drift on faf-cli-slot-rename.md.

Out of scope

• Renaming any human_context.* or monorepo.* paths (Mk4 doesn't touch those).
• Renaming the category labels (frontend, backend, etc. as category names) — only slot paths inside stack.*.

[Wolfe-Jam]

Phase A landed: commit fda6d0b on main.

What shipped (cli-side prep, no on-wire changes):

• SlotDef gains optional canonical?: string (src/core/types.ts)
• 6 affected slots get canonical alias:
  • stack.frontend → stack.framework
  • stack.css_framework → stack.css
  • stack.state_management → stack.state
  • stack.api_type → stack.api
  • stack.database → stack.db
  • stack.package_manager → stack.pkg_manager
• SLOT_BY_PATH is now dual-keyed — both legacy AND canonical paths resolve to the same SlotDef
• CANONICAL_TO_CURRENT / CURRENT_TO_CANONICAL bidirectional alias maps
• getSlotByAnyPath() + readSlotValue() helpers for dual-name reads
• 11 new tests covering alias resolution + fallback reads + index stability
• 685/685 tests green

slot.path (on-wire identifier) stays LEGACY for now. kernel + xai-faf-rust both still on legacy names — verified empirically (WASM strings output + score_faf test against canonical-named .faf returned lower score, confirming kernel does not yet accept Mk4 names). No scoring regression.

Deferred to Phase B (separate lockstep PRs):

1. faf-scoring-kernel WASM accepts canonical names → separate npm publish
2. xai-faf-rust/src/scoring/mk4.rs uses canonical (parity ref impl)
3. Regenerate tests/fixtures/parity/parity-expected.fafb
4. Then in faf-cli: flip slot.path = canonical, activate faf migrate rewrite, update write commands (go / ai / auto / init)

Phase A removes the cli-side blocker; the on-wire rename ships once kernel + xai-faf-rust agree.

Leaving issue open until Phase B lands.

[Wolfe-Jam]

Phase B Stages 1 + 2 source-complete and pushed. Stage 3 (cli flip) awaits kernel npm publish.

Stage 1 — faf-wasm-sdk (kernel source)

Commit: Wolfe-Jam/faf-wasm-sdk@759f2d1

• get_universal_slots() renamed to canonical (framework/css/state/api/db/pkg_manager)
• legacy_alias_for(&str) helper added
• get_slot_state() now tries canonical → falls back to legacy alias on Empty
• walk_path_state() extracted as path-walk helper
• 7 new tests covering canonical scoring, legacy fallback, "canonical wins when both present", all-6-renames, enterprise pkg_manager fallback, direct alias map unit test
• 97/97 tests pass (was 90)
• Version: 2.0.0 → 2.1.0 (Cargo.toml + npm-package/package.json + sdk_version())

Stage 2 — xai-faf-rust (parity ref impl)

Commit: 9aceeff on private xai-faf-rust/main

• Identical slot rename + alias fallback applied to src/scoring/mk4.rs
• src/commands/gold.rs:25 updated to detect both framework: and frontend: in gap-report
• 118/118 tests pass — including the FAFB parity suite (parity-input.faf only contains project.name, so the renamed slots aren't exercised; bytes unchanged)

Stage 3 — faf-cli (pending kernel npm publish)

Blocked on: faf-scoring-kernel npm publish at 2.1.0.

The npm package faf-scoring-kernel publishes from faf-wasm-sdk/pkg-node/ (currently shows v2.0.3). To unblock Stage 3:

1. In faf-wasm-sdk repo: wasm-pack build --target nodejs --out-dir pkg-node
2. Bump pkg-node/package.json version: 2.0.3 → 2.1.0
3. cd pkg-node && npm publish (per NPM PUBLISH PROTOCOL — explicit GO required)

Once published, Stage 3 in faf-cli is a small follow-up:

• Bump faf-scoring-kernel dep to ^2.1.0
• Flip slot.path → canonical in src/core/slots.ts (rename Phase A's canonical? field to legacy?)
• Update 4 test files referencing legacy slot strings
• Activate faf migrate to rewrite legacy keys → canonical in-place
• Regenerate tests/fixtures/parity/parity-expected.fafb from updated xai-faf-rust (the fixture's current input only has project.name, so bytes likely unchanged — verify anyway)

Lockstep status

Layer	Source	Publish status
faf-wasm-sdk (Rust)	✅ 759f2d1 on main	pending wasm-pack rebuild + npm publish
xai-faf-rust (private)	✅ 9aceeff on main	private — no public publish
faf-cli Phase A	✅ fda6d0b on main	shipped
faf-cli Phase B	⏳ pending kernel	needs kernel 2.1.0 in node_modules

Backward compatibility receipt

Both Stage 1 and Stage 2 ship with the legacy fallback in get_slot_state. After publish, existing .faf files containing legacy keys (stack.frontend, stack.css_framework, etc.) continue scoring identically. New .faf files written by faf-cli (post-Stage-3) will use canonical names natively. The transition is silent for existing users.

[Wolfe-Jam]

Closing — surpassed by the shipped read-both approach. slots.ts carries the canonical aliases + dual-key lookup, so every .faf scores correctly regardless of legacy-vs-Mk4 names — the functional goal is met. The remaining on-wire write-flip is optional vocabulary-alignment, gated on a coordinated canonical kernel publish (source is live in faf-wasm-sdk 2.1.0). Reopen if a kernel release ever makes it worthwhile.