Applying templates to a collection — states gallery
The collection-level half. Applying a project template is always a snapshot copy: the collection gets its own independent instance, and editing the template later never reaches it. That is the point of the model, not a limitation of it — re-apply is explicit, Draft/Review only, and always previews what it will change.
A composition applies at the point a token type is set up — the one moment every axis has somewhere to land. The companion gallery covers the library itself: composition-library-states-gallery-2026-08-19.html.
01Apply a composition · the per-axis previewOne action, but never a blind one. Every axis states what it will do before anything commits. Token-level axes become defaults for definitions created under this type; definitions that already exist are left alone and reported as skipped.
Everything below is a snapshot copy into this collection. Nothing stays linked to the library.
Graded card — TAG · v4
Token type profileCreates type trading_card + 6 assignmentscollectionwill create
Attribute templatesUnions 6 attributes into the master schemacollection4 new · 2 exist
Asset specGraded slab v2 — 3 slots, resolved at compilecontractwill set
Tier set templateabsent — collection rarity untouchedcollectionno change
Variant profileabsenttoken defno change
State policyabsenttoken defno change
i
One delta applies:slot_requirement — dig_report becomes optional for this token type.
02Applied · what changed, and what it is nowThe confirmation states plainly that the collection now owns its copy. Provenance records what it came from so "which collections used Trading card v2?" stays answerable — but provenance is never authority.
Applied
✓
Trading card is set up. 4 attributes added, 2 already existed, 6 assignments written, asset spec resolved.
✓
Token type created
trading_card · assignment matrix written, so the mandatory assignment step is done
✓
Master schema updated
6 attributes now present; each exists exactly once in the collection list
✓
Contract ready to compile
Requirement levels resolved — publish to make it authority
This collection now owns it
i
Editing Trading card v2 in the project library will not change anything here. To pick up a newer version, re-apply — Draft/Review only.
Compiled fromGraded card — TAG v4provenance
Token typeTrading card v2provenance
Asset specGraded slab v2provenance
Runtime never reads any of these. It reads the compiled contract.
03Applying an attribute template alone · assignment is mandatoryA template carries definitions with no requirement levels, and Phase 1 turns auto-assignment off once a collection has more than one token type. So the apply cannot complete without this grid — otherwise a creator applies twelve attributes, sees no effect anywhere, and hunts through the Token types panel for twelve unassigned rows.
Trading card core v3 — every attribute needs a level on at least one token type before this can complete.
Attribute
Kind
Trading card
Promo card
set_name
Category
card_number
Text
foil
Boolean
printer
Text
Showing 4 of 4 incomingBulk: set a column · set a row · dry run
printer is unassigned on every token type. It would land in the collection doing nothing and look like a bug. Give it a level on at least one type to continue.
04Two rejections · key collision and tier set conflictBoth block the apply rather than resolving silently. A key collision is unreconcilable — two different definitions cannot share a key in one master schema. A tier set conflict is structural: rarity is collection-wide, not per token type, so a second composition must not silently re-tier a collection.
Key collision · apply blocked
yearincoming Number · local Textclash
set_nameidentical definitionno change
1 key collides. Rename the local attribute, or use a template version that does not define year. Each attribute exists exactly once in the master schema — that invariant is what validation, scoring, generator mapping and the value lock all depend on.
Tier set conflict · apply rejected
Collection rarity nowTiered · Military ranks v1current
Composition wantsTiered · Card grades v1conflict
Rarity is collection-wide, not per token type. Applying this would re-tier every token in Paper Trail. Two token types needing different tier sets belong in different collections.
i
A composition with the tier set axis absent applies cleanly and never touches collection rarity.
05Provenance in the attribute editorEvery attribute shows whether it arrived from a template — and which version — or was authored locally. Template-derived and local attributes are equal citizens in one master list; templates change where an attribute came from, not where it lives. Provenance drives detach and this display, and nothing else.
One list, one home for every attribute. Six from templates, two authored here.
Attribute
Kind
Source
Trading card
set_name
Category
Trading card core v3
Required
card_number
Text
Trading card core v3
Required
year
Number
Trading card core v3
Optional
foil
Boolean
Trading card core v3
Optional
print_run
Number
Print run v1
Optional
grade_note
Text
authored here
Optional
shop_sku
Text
authored here
Optional
Showing 7 of 7 attributesProvenance is a record, never authority
06Contract list · the compiled artefactThe only thing runtime reads. Immutable once published, one per token type per configuration, and every token pins exactly one version. Moving a token to another version is an explicit validated migration, never an edit.
Readiness reads one artefact. It never walks a graph of templates comparing snapshots — that is what compiling removed.
Showing 3 of 3 contract versionsA published contract never changes silently
07Contract builder · compile and publish a versionWhere the resolved setup is reviewed and requirement levels are set. Requirement level is not a slot or attribute field — a template declares what exists, and required versus optional is decided here, at compile. Publishing makes the version immutable and available to pin; a published contract never changes silently.
Publishing is final. This version becomes immutable and available for tokens to pin. To change it afterwards, compile a new version and migrate.
08Contract assignment · at token creation and importEvery token pins exactly one contract version, chosen explicitly at creation. Invisible where a default exists — with one token type and one published contract there is nothing to ask, so the field does not appear. It surfaces the moment there is a genuine choice.
No picker is shown. The default is the only published contract for this type.
Two contracts · an explicit choice
Token typeTrading card
Contractgraded_card_v1 · 412 tokensselected
graded_card_v2 · dig_report optional
i
Importing 240 tokens? Assign in bulk here, or per row in the import preview.
09Migration · the only way a token changes contractA published contract never changes, so moving a token between versions is an explicit, validated migration — never an edit. Every requirement is checked per token before anything is applied, and tokens that would fail are reported rather than silently skipped or half-migrated.
398 ready · 14 blocked of 412Validation runs before anything is applied
14 tokens cannot migrate yet. Fix their missing values and run again, or migrate the 398 that are ready and leave the rest on v1 — a collection may hold tokens on several contract versions.
10Go-Live checklist · named failuresEvery gate reports a named reason, never a generic invalid flag. The three that come from this system are the asset gate, the policy seam, and the variant topology rules.
Collection · Go-Live readiness
✓
Contract published
graded_card_v1 · every token pins a version
✓
Required attributes present
2 required, both valued on every token
✕
Required asset slots filled
3 tokens are missing the back slot. The spec verifies existence only — content review is separate
✕
Variant policy seam
Token #014 declares transitions, but its attached State Policy does not permit writes to variant. Attach a policy that does, or clear the transitions
✕
Variant reachability
Token #051: variant ascended is unreachable from the default. Orphans and closed cycles fail here
✓
Tier set valid
Military ranks · 4 tiers, no reserved names
11Live · everything from this system is read-onlyAt collection Live the master schema, token types and rarity freeze. At token Live the variant set, topology and attached policy snapshot freeze. Apply and re-apply are gone — the surfaces stay reachable so an author can read what shipped.
Frozen at go-live. This is what every buyer was shown.
!
Locked. The schema, token types and rarity froze when this collection went Live. Editing a project template cannot reach it, and re-apply is unavailable — by design, not as a restriction.
Attribute
Source
Trading card
set_name
Trading card core v3
Required
year
Trading card core v3
Optional
grade_note
authored here
Optional
Showing 3 of 7 attributesRead-only
12Where the apply actions live · almost no new navigationAn apply action hangs off the sub-page that already owns the thing being configured, so a creator applies a template exactly where they would otherwise author it by hand. The four Attributes tabs stay fixed — applying is an action within a tab, never a fifth tab.
A new Contracts sub-page. It cannot go under Attributes (four fixed tabs) and is not an attribute concern — a contract spans the type, its assignments and its slots
13Promote · saving a collection setup back to the libraryThe inverse of apply, and what makes the library populate itself — the first collection is always built by hand, because no templates exist yet. Promotion snapshots in the opposite direction and creates no link: later collection edits never reach the template, exactly as template edits never reach the collection.
Save as template
✕
Promoting Trading card from Paper Trail into the Neon District library.
Token type + matrix6 attributes, levels includedwill create
Asset spec3 resolved slotswill create
Tier setMilitary ranks · 4 tierswill create
Variant profileno variants on this typenothing to save
One compositionBundles all three — "save this whole setup"recommended
Separate templatesThree independent library objects
i
Creates a Draft head. Publish it to make it appliable elsewhere. Paper Trail is unaffected either way — it keeps its own copy.
14Where each axis landsNot a screen — the reference for the apply implementation. A composition applies at the point a token type is set up, and its axes land at three different levels.
Per-axis landing · from token-contract-system-spec.md §4C.2
Axis
Lands on
Notes
Token type profile
Collection
Creates the type and writes its assignment matrix
Attribute templates
Collection master schema
Unioned; each attribute exists exactly once
Asset spec
The compiled contract
Requirement levels resolved at compile
Tier set template
Collection
Collection-wide, not per type — conflicting applies are rejected
Variant profile
Each token definition
Seeds the set; topology stays per token
State policy
Each token definition
Attached and snapshot-copied
Token-level axes become defaults for the type. Definitions created under it inherit the variant profile and state policy, and may diverge locally while Draft. Definitions that already exist are never retro-touched — the apply reports how many were skipped.
15Collection navigation · where Contracts landsA destination list, not a drawn sidebar. Contracts is the only new collection destination the system introduces — everything else applies from the sub-page that already owns the thing.
It sits after everything it compiles from — attributes, rarity, supply — and immediately before what consumes it, since every token pins a contract. The order teaches the dependency.
Alternative considered: a section inside the Token types panel, beside the type it compiles from. Genuinely attractive, but it loses on three counts — go-Live debugging would bury it three levels down; Manage Attributes already carries the master schema, the token types panel and required media; and migration is an operation on a real object, not a detail of a token type.
What stays out: assignment at token creation or import, and per-token exceptions, live in the token flow where the tokens are. Contracts holds the list, the builder, migration and provenance.
i
Honest about the common case. Default contracts are automatic. With one token type, a default contract and nothing unusual, this page says so in a line rather than presenting busywork — a fair trade for a destination that can be found the moment go-Live fails.