Establish stable face, animation, and semantic spriteset contracts

[zoeyrose]

Architecture amendment — one authored content source (2026-08-13)

Initiative atrinik/atrinik#357 supersedes every future live-branch instruction below. atrinik/content@main is the sole mutable authored source for replacement and Classic targets. Future authored changes land only on main; supported Classic artifacts are deterministically derived from the same immutable main revision. Do not create, restore, author, backport, validate, or publish through a live 1.x branch.

Exact historical 1.x commits, tags, releases, assets, preserved local snapshots, provenance, parity records, and comparisons remain valid immutable evidence. This amendment changes no other feature, balance, lore, compatibility, licensing, validation, or ownership acceptance criterion.

Parent: atrinik/atrinik#314

Coordinates with content#44, content-toolkit#4, and renderer#14.

Outcome

Make faces, animations, and authored visual families first-class stable content identities so compilers can build spritesets and bounded resource packs without deriving semantics from paths, alphabetical order, or runtime face numbers.

This issue owns authored identity, reference, grouping, and attribution facts. It does not own archive layout, protocol messages, client cache behavior, or GPU atlas allocation.

Current gap

At the current content@1.x snapshot, the source contains 9,413 PNG files and 775 animation definitions. Classic collection emits 9,394 runtime faces into one atrinik.0 blob (19 arch/dev images are editor-only and bug.101 is forced to runtime face 0), plus one bmaps table and one animations table.

The authoritative tools/content_catalog currently models gameplay definitions and references but has no face or animation definition domains. The authored schema already identifies face, animation, inv_face, and inv_animation as typed references, so validation and compilation do not yet have the corresponding canonical media graph.

Animation membership is a strong grouping edge, but it is not a safe physical packing rule by itself. Shared faces such as dummy.111 and trans.101 occur in hundreds of animations. Copying every referenced PNG into every animation archive would waste bytes and make attribution/update behavior ambiguous.

Identity and catalog contract

• Define stable domain-qualified identities for encoded faces, animations, and semantic visual families. IDs must not derive from filesystem enumeration, generated runtime table positions, display text, atlas pages, or archive offsets.
• Load every distributable PNG definition and every animation definition, including ordered frames, repeated timing frames, facings, and other supported animation semantics. Preserve the special Classic/editor-only classification without making face 0 a replacement identity rule.
• Resolve every archetype/map/interface field that refers to a face or animation through the catalog. Reject duplicate basenames/IDs, missing or wrong-domain references, malformed animation blocks, unsupported facings, and ambiguous aliases with stable diagnostics and source spans.
• Record immutable encoded-byte digest, media type, dimensions, source path/revision, distribution class, and exact license/author/notice references for each visual resource. Unknown or conflicting licensing blocks distributable output; packing never changes asset terms.
• Define logical spritesets for each animation/facing group and every required multipart/overlay dependency that can be derived from authored semantics.
• Provide an explicit authored visual-family surface for relationships not represented by animation data, such as a monster family, one grass/terrain theme, coordinated building pieces, UI icon family, or effect family. Multiple membership is allowed and ordered roles may be declared where semantically meaningful.
• Keep measured map/region co-occurrence and physical pack assignment out of canonical authored identity. A compiler may consume co-use as a versioned packing input, but it must not rewrite source semantics or create unstable IDs from one corpus traversal.
• Define alias/rename/migration behavior so a source move does not silently create a new durable identity or leave unowned references.

Prefer a small dedicated machine-readable manifest for visual-family relationships if no existing authored field expresses them. Do not overload gameplay ADS fields with transport hints or add a second parser/catalog.

Release-line and ownership rules

main owns forward/replacement authoring and the canonical media identity/grouping contract. 1.x is maintenance-only and declares replacement_toolkit_package: false.

• Do not merge a replacement schema/toolkit wholesale into 1.x.
• Classic may initially derive bounded packs from its existing collected bmaps, animations, and atrinik.0 artifacts in a Classic-owned repackaging step.
• If Classic needs explicit authored family metadata, make a separately reviewed and validated 1.x maintenance change linked to the Classic issue, preserve replacement_ready: false, and forward-port only the shared authored facts through an independent main change.
• Generated catalogs and packs remain under isolated build/output roots; never commit generated runtime collection into authored source or overwrite mutable server data.

Acceptance criteria

• The catalog contains one stable definition for every supported distributable face and animation plus typed references from every supported authored consumer.
• Animation entries preserve definition order, facings, repeated frames, and ordered face membership exactly; shared faces remain one resource identity referenced by many sets.
• Explicit visual families can represent at least one multi-animation monster family, one grass/terrain theme, one multipart object, one effect family, and one UI/icon family without encoding archive or UV positions.
• Clean and incremental catalog runs are deterministic and produce the same identity/reference graph independent of filesystem order, locale, cache warmth, and source moves covered by declared aliases.
• Duplicate, missing, ambiguous, unsafe, malformed, editor-only/distribution-confused, and unlicensed media cases fail with stable source-located diagnostics.
• Every distributable visual resolves to exact per-source attribution/license/notice metadata; the existing unlicensed-media backlog remains excluded or is explicitly resolved rather than flattened into a pack-level blanket license.
• Versioned JSON/schema fixtures cover animation/facing sets, multiple family membership, shared placeholders, oversized families, aliases, and negative references for the replacement toolkit.
• python3 tools/validate.py and git diff --check pass on each affected release line, with separate linked PRs if both main and 1.x change.

Dependencies and consumers

This work extends the content identity contract and feeds the new toolkit spriteset/pack compiler. Publication remains in content#44; Classic consumption remains in its dedicated follow-up to classic#46; renderer geometry/UV semantics remain in renderer#14.

The content and visual assets retain their actual licenses. Replacement implementation code and schemas are MIT. Under the canonical historical-grant policy, an exact independently separable Classic contribution may be inspected as implementation reference, copied, migrated or ported, translated or adapted, and relicensed for an MIT destination only when it fits one grant row's temporal and sole-original-authorship scope. Distinct contributions may cite different rows only if each independently qualifies; rows cannot be combined for joint, generated, or inseparable work. Later material needs contemporaneous compatible permission. The grants do not relicense content or visual assets, which retain their exact terms, notices, and provenance requirements.

Priority, blockers, and parallel delivery

Priority: P0 critical-path contract. This is one of the first two replacement producer foundations, alongside content-toolkit#4. It should start immediately and does not wait for Classic, GP1, a pack format, or GPU atlas work.

Execution order

Phase	Work	Can run in parallel	Exit/handoff
C0 — freeze identity rules	Approve exact-case stable face/animation/family IDs, alias/rename rules, runtime/editor distribution roles, limits, and the bug.101 Classic projection boundary.	Corpus baseline/count checks, PNG metadata reader, schema documentation, and negative fixture design	Versioned ID/reference proposal reviewed by content-toolkit#4/#16 consumers
C1 — catalog faces and animations	Add definitions and typed archetype/map/interface references; preserve ordered/repeated frames and facings; emit dimensions/digests/source locations.	Face loader, animation loader, authored-reference integration, shuffled-enumeration determinism, and diagnostics can be implemented independently behind C0 types	Whole supported corpus resolves or produces owned stable diagnostics
C2 — attribution and distribution	Attach exact source/author/license/notice identity and explicit distributable/editor-only/excluded status to every media entry.	Existing attribution inventory and parser/schema work can proceed concurrently	Every fixture/member has an admission state; unknowns are explicitly excluded, not silently licensed
C3 — logical spritesets	Derive animation/multipart sets and add explicit semantic visual-family metadata, multiple membership, aliases, and validation.	Family syntax/schema, catalog graph validation, and co-occurrence evidence tooling can proceed in parallel	One versioned positive/negative fixture covers animation, monster, terrain, multipart, effect, UI, shared-member, and oversized-family cases
C4 — freeze and release the contract	Generate schemas/docs/fixtures and obtain consumer sign-off from content-toolkit#4/#16 and content#44.	Linux/Windows determinism and release-line validation	Immutable contract version/digest is ready for content-toolkit#16; later changes require a migration/feature decision

Blockers and dependencies

• No hard blocker to starting C0–C2. The current authored schema and catalog are sufficient to implement the missing media domains.
• C4 completion requires a consumer handshake, not consumer implementation: content-toolkit#4/Content schema: prototype and select the authored syntax #16 must confirm the stable IDs, bounds, and fixtures are sufficient before version 1 freezes.
• Replacement-ready publication is member-scoped: unresolved provenance/license entries block those members from content#44 and pack publication, but they do not block the schema, catalog, diagnostics, approved subset, or Classic's explicitly non-replacement-ready artifacts.
• content@1.x is not on this critical path. Classic#66 should first use a Classic-owned repackaging projection. A 1.x change is allowed only if explicit authored family facts prove necessary and then needs its own linked maintenance review.
• Filesystem/map co-occurrence evidence may inform content-toolkit#16's soft affinity, but it cannot block or mutate canonical identity/group membership.

Parallel handoffs

• Publish an early synthetic fixture as soon as C0 types freeze so content-toolkit#16, protocol#10, client#32, and server#76 can develop without the full corpus.
• Give content-toolkit#16 the complete C4 catalog/schema fixture for whole-corpus integration.
• Give content#44 per-member admission and notice references; packaging must never infer a blanket license from a family or pack.
• Keep renderer-specific UVs/pages/residency in renderer#14. This issue may own authored anchors or semantic render metadata only where content#61/renderer#14 explicitly agree on ownership.

This issue blocks content-toolkit#16's whole-corpus completion and the spriteset portion of content#44, but not their synthetic-fixture, release-plumbing, or format-design work.