fix: stop the templates and samples teaching the wrong key

[liam-machine]

Prompted by Joakim Dalby's comment on a LinkedIn post showing the demo GIF:

I wish your customer dimension has a dimension key called Customer_key, because I think the business key is Customer_Id, and hopefully not the name of customer since name of persons is not unique. Date_key can be a date.

They were being polite. It was the name.

What was actually wrong

# dim_customer.yml, before
- name: customer_id
  description: Surrogate key for customer    # a surrogate, named like a business key
  isPrimaryKey: true
- name: customer_name
  isNaturalKey: true                         # the name IS marked as the business key

dim_location did the same with site_name. But the sample was the symptom, not the disease — FALLBACK_TEMPLATES in src/services/templateService.ts has it too, and that's what every user without custom templates inherits.

Two things are being conflated:

{name}_key	surrogate	meaningless, unique per row, the column facts point at
{name}_id	business key	as the source system spells it, unique per entity

Those are not the same, and SCD2 is where it bites: one entity owns a row per version, so the business key repeats by design. The scd2 template therefore shipped a dimension whose declared primary key is provably not unique — and ERD Studio derives cardinality from uniqueness tests, so that isn't only cosmetic.

The AI harness already had this right. SCHEMA_CONTENT documents email as the natural key and full_name as a tracked attribute. So HARNESS_VERSION is deliberately not bumped: the guidance was correct, the defaults contradicted it.

What changed

Templates (FALLBACK_TEMPLATES + the fixture copies)

• dimension / scd2 split {name}_key and {name}_id, the latter flagged isNaturalKey
• scd2 marks its tracked attributes scdType: 2, so it finally demonstrates the feature it's named after
• dimension (Type 1) drops the Type 2 effective dating it was shipping; scd2 drops its duplicate set (it carried both valid_from/valid_to and scd_valid_from/scd_valid_to)
• bridge flags its two sides isForeignKey instead of only claiming so in the description text

Sample models — every dimension gets a _key surrogate and a real business key (customer_id, project_code, location_code, task_id); names become ordinary tracked attributes; facts join to dimension surrogates. Carried through the domain relationships, the dbt schema yml, manifest.json and catalog.json — the catalog keeps its deliberate UPPERCASE spelling for dim_task, which is what proves the declared spelling wins for display.

dim_date is untouched. A YYYYMMDD key is the one conventional exception — exactly the concession Joakim made — and it's now documented as such, with calendar_date as its business key.

showcase gains dim_customer and dim_date. Both sat in the model library referenced by nothing, so the dimension that best demonstrates the split was never on the canvas.

The demo GIF

Every frame of media/demo.gif — the marketplace README hero — showed dim_customer with an NK badge on customer_name. Regenerated:

The canvas is real; the window around it is drawn. The editor area in each frame is the actual dist/webview.js bundle, driven by payloads a real SemanticEditorProvider produced over the real fixture project — the logical domainLoaded, the physical stageData, and the discrepancyReport from an actual toggleDiscrepancy. Every caption is asserted against the live DOM while capturing, so a mismatch aborts the run.

The VS Code window (title bar, activity bar, explorer, tabs, status bar) is CSS, not a screen capture — there's no display or VS Code in the environment this was built in. Because it's drawn, I held it to being true rather than merely plausible:

• the file tree lists exactly what test/fixtures/dbt-project contains
• the tab and breadcrumb name the file that's actually open
• the activity bar carries the real ERD Studio icon from media/icon-sidebar.svg
• the language indicator reads JSON, because a domain file is JSON

Nothing on screen names a file the repo doesn't have or implies a feature that doesn't ship. The README alt text opens with "ERD Studio open in VS Code" and the CHANGELOG states the chrome is rendered, so this can't later be mistaken for a screenshot. If you'd rather have a genuine capture, the fixture state is committed — recapturing in the dev host is a couple of minutes.

One honest detail in frame 4: the overlay reports customer_id Only in Logical. That's correct — the new business key is in the design and not yet in the warehouse, which is precisely what the discrepancy view is for.

467 KB, 1400×929, four frames.

Tests

1560 pass (1527 before), 33 new in test/unit/dimensionalModelling.test.ts, asserting the rules rather than the current strings:

• a dimension has exactly one primary key, and its PK and NK are different columns
• no template or sample ever flags a label-shaped column (*_name, *_label, *_title) as the natural key
• scd2 tracks history on attributes and on neither key, and carries the columns that make versions addressable
• the Type 1 template ships no Type 2 dating, and scd2 ships only one set
• fact foreign keys end _key; a fact keys itself on a degenerate business identifier
• dim_date is the documented exception

Verified they fail against the previous fixtures — reverting dim_customer.yml alone trips two of them with the exact complaint Joakim made.

npm run compile, npm run build, npm test green; vsce ls --no-dependencies still 12 files.

Worth pushing back on

• {name}_key is a convention, not a law. Plenty of dbt practice skips integer surrogates for a hash (dbt_utils.generate_surrogate_key) or uses the business key directly. I picked the explicit split because it's the one a template can teach, and a template that stays silent teaches the conflation by default — but it is a choice. The part with no other side is that a name is not a key, and that's enforced generically rather than by naming specific columns.
• The fact PK. Facts keep {name}_id as both PK and NK — a degenerate dimension — rather than gaining a surrogate that buys nothing. If you'd rather facts carried {name}_key too, it's a small change to the templates and the generic tests still hold.

🤖 Generated with Claude Code

https://claude.ai/code/session_0137crR8usmNLiUke7NeYpBY