Define the authored-description and mechanic lifecycle #2

Closed
opened 2026-08-23 13:08:35 -04:00 by jb · 2 comments
Owner

Part of #1

Question

How should the four mechanic-owner profiles store exact authored fallback prose across their Tier I/Tier II, base, minimum/maximum, and tree-rank variant contracts; represent absent, stale, assumption-dependent, captured-only, and executable models; handle placeholders; enforce publication completeness; invalidate prior models after prose edits; and remove the current Exotic Talent and Skill Chip Talent exceptions without conflating public binary status with simulation readiness?

Part of #1 ## Question How should the four mechanic-owner profiles store exact authored fallback prose across their Tier I/Tier II, base, minimum/maximum, and tree-rank variant contracts; represent absent, stale, assumption-dependent, captured-only, and executable models; handle placeholders; enforce publication completeness; invalidate prior models after prose edits; and remove the current Exotic Talent and Skill Chip Talent exceptions without conflating public binary status with simulation readiness?
jb added the wayfinder:grilling label 2026-08-23 13:08:35 -04:00
jb self-assigned this 2026-08-23 13:59:11 -04:00
Author
Owner

Authored descriptions and mechanic lifecycle

Canonical authored descriptions

Each mechanic owner stores an authored template, independent authored slot values, and materialized prose for every required variant. Mechanic outcomes do not supply fallback text.

Owner Required authored variants
Talent Tier I and Tier II for a standard Talent; Tier I plus Tier II only when an Exotic Talent defines Tier II
OS Protocol Talent base
Skill Chip Talent minimum and maximum
Specialization tree-rank effect base

The Specialization source includes the rank description, selected reusable combat-effect template, and rank-specific authored values. The reusable effect remains an internal authoring input and does not gain a public catalog.

Editors render materialized prose from the template and authored slots. Canonical validation rejects unknown tokens, missing required slots, unresolved tokens, missing variants, and disagreement between a stored projection and a fresh render. Canonical saves and contribution approvals enforce this rule. A contribution proposal may retain incomplete prose while Oversight works on it, but approval must fail until the proposal is complete.

Source identity

The server computes a deterministic SHA-256 fingerprint from a versioned canonical serialization of all semantic inputs:

  • owner type and stable owner ID;
  • template text;
  • ordered variant identifiers and authored slot values;
  • Specialization rank description, reusable effect identity and template, and rank values when applicable;
  • authored-description contract version.

The fingerprint excludes timestamps, display ordering unrelated to meaning, editor state, and Mechanic Program data. Generation receives materialized authored descriptions and variant identity as its only semantic evidence.

Immutable model revisions

Every generated or manually saved Mechanic Program creates an immutable model revision containing its source fingerprint, mechanic contract version, readiness, scenario inputs, and normalized program graph. The owner points to the selected revision. Saving another model never rewrites an older revision.

A selected revision is current when its source fingerprint matches the owner's current fingerprint and the installed mechanic contract validates the stored graph. A mismatch makes the revision stale. An authored edit therefore makes the selected model stale without deleting it. Reverting the authored inputs to an earlier fingerprint may reactivate the selected matching revision; selecting or generating another matching revision supersedes it without removing history.

The internal lifecycle is:

  • absent: no non-empty valid model revision is selected;
  • stale: a selected revision exists but its fingerprint or contract no longer matches;
  • current: a selected non-empty revision matches and validates.

current retains the existing readiness values ready, requires_assumptions, and captured_only. An empty capture placeholder counts as absent, not as a model.

Public surfaces derive one binary state. Every current valid revision displays MODELED, including requires_assumptions and captured_only. absent and stale display NOT MODELED. Public pages do not expose readiness. They must neither display nor execute stale models.

Exception removal

All four owners may publish complete authored prose without a Mechanic Program. Exotic Talents no longer require a Tier I branch or outcome to save. Skill Chip Talents no longer require branches or outcomes when prose is complete. Exotic Tier II remains optional because the owner contract, rather than the modeling profile, determines required variants.

The mechanic-authoring profile must derive its variant list from the owner record. It must not assume that every Exotic has Tier II.

Acceptance checks

  • Each owner can publish complete authored prose with no model.
  • Placeholder rendering works without reading conditional_effect_rules or model outcomes.
  • Incomplete proposals persist, but approval rejects unresolved prose.
  • Editing any semantic source input makes the selected model stale immediately.
  • Stale programs cannot reach public modeled text or combat evaluation.
  • Every model save creates a revision and preserves previous revisions.
  • Public status depends on currency and validity, not simulation readiness.
  • Standard, Exotic, OS Protocol, Skill Chip, and Specialization variant contracts have focused validation and lifecycle tests.
# Authored descriptions and mechanic lifecycle ## Canonical authored descriptions Each mechanic owner stores an authored template, independent authored slot values, and materialized prose for every required variant. Mechanic outcomes do not supply fallback text. | Owner | Required authored variants | | --- | --- | | Talent | Tier I and Tier II for a standard Talent; Tier I plus Tier II only when an Exotic Talent defines Tier II | | OS Protocol Talent | `base` | | Skill Chip Talent | `minimum` and `maximum` | | Specialization tree-rank effect | `base` | The Specialization source includes the rank description, selected reusable combat-effect template, and rank-specific authored values. The reusable effect remains an internal authoring input and does not gain a public catalog. Editors render materialized prose from the template and authored slots. Canonical validation rejects unknown tokens, missing required slots, unresolved tokens, missing variants, and disagreement between a stored projection and a fresh render. Canonical saves and contribution approvals enforce this rule. A contribution proposal may retain incomplete prose while Oversight works on it, but approval must fail until the proposal is complete. ## Source identity The server computes a deterministic SHA-256 fingerprint from a versioned canonical serialization of all semantic inputs: - owner type and stable owner ID; - template text; - ordered variant identifiers and authored slot values; - Specialization rank description, reusable effect identity and template, and rank values when applicable; - authored-description contract version. The fingerprint excludes timestamps, display ordering unrelated to meaning, editor state, and Mechanic Program data. Generation receives materialized authored descriptions and variant identity as its only semantic evidence. ## Immutable model revisions Every generated or manually saved Mechanic Program creates an immutable model revision containing its source fingerprint, mechanic contract version, readiness, scenario inputs, and normalized program graph. The owner points to the selected revision. Saving another model never rewrites an older revision. A selected revision is current when its source fingerprint matches the owner's current fingerprint and the installed mechanic contract validates the stored graph. A mismatch makes the revision stale. An authored edit therefore makes the selected model stale without deleting it. Reverting the authored inputs to an earlier fingerprint may reactivate the selected matching revision; selecting or generating another matching revision supersedes it without removing history. The internal lifecycle is: - `absent`: no non-empty valid model revision is selected; - `stale`: a selected revision exists but its fingerprint or contract no longer matches; - `current`: a selected non-empty revision matches and validates. `current` retains the existing readiness values `ready`, `requires_assumptions`, and `captured_only`. An empty capture placeholder counts as `absent`, not as a model. Public surfaces derive one binary state. Every current valid revision displays `MODELED`, including `requires_assumptions` and `captured_only`. `absent` and `stale` display `NOT MODELED`. Public pages do not expose readiness. They must neither display nor execute stale models. ## Exception removal All four owners may publish complete authored prose without a Mechanic Program. Exotic Talents no longer require a Tier I branch or outcome to save. Skill Chip Talents no longer require branches or outcomes when prose is complete. Exotic Tier II remains optional because the owner contract, rather than the modeling profile, determines required variants. The mechanic-authoring profile must derive its variant list from the owner record. It must not assume that every Exotic has Tier II. ## Acceptance checks - Each owner can publish complete authored prose with no model. - Placeholder rendering works without reading `conditional_effect_rules` or model outcomes. - Incomplete proposals persist, but approval rejects unresolved prose. - Editing any semantic source input makes the selected model stale immediately. - Stale programs cannot reach public modeled text or combat evaluation. - Every model save creates a revision and preserves previous revisions. - Public status depends on currency and validity, not simulation readiness. - Standard, Exotic, OS Protocol, Skill Chip, and Specialization variant contracts have focused validation and lifecycle tests.
Author
Owner

Decision specification recorded above. The contract covers owner variants, independent authored slots, immutable hash-linked model revisions, public status, publication completeness, and exception removal. Closing as resolved.

Decision specification recorded above. The contract covers owner variants, independent authored slots, immutable hash-linked model revisions, public status, publication completeness, and exception removal. Closing as resolved.
jb closed this issue 2026-08-23 14:25:57 -04:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: jb/shd.build#2