jb/shd.build
1
0
Fork 0
Code Issues 4 Pull Requests Actions Packages Projects Releases Wiki Activity

Specify deferred combat modeling from authored descriptions #1

New Issue
Closed
opened 2026-08-23 13:08:16 -04:00 by jb · 2 comments
jb commented 2026-08-23 13:08:16 -04:00
Owner
Copy Link
Copy Source

Destination

An implementation-ready specification, carried by this map's resolved tickets, for entering and publishing authored fallback descriptions independently of combat models across Talent, OS Protocol Talent, Skill Chip Talent, and Specialization tree-rank effects, then generating valid models through a Modeling Session after entry.

Notes

  • This map plans the change; it does not implement it.
  • Sessions must consult the grilling and domain-modeling skills. Prototype tickets must also consult prototype.
  • Modeled text is the primary public display; exact authored prose is the fallback while modeling is absent or stale.
  • Authored prose follows each owner's existing variant contract and is required for publication.
  • Public users see a binary MODELED / NOT MODELED state. Internal lifecycle detail may remain richer.
  • Editing authored prose makes its prior model stale and restores fallback display until regeneration succeeds.
  • Generation uses only stored authored descriptions as semantic evidence.
  • The required generation workflow is an interactive Modeling Session; ISAC generation controls are not required.
  • A Modeling Session may persist a generated model and its prerequisites only after per-record chat confirmation. Ambiguous behavior must not be invented.
  • Scope is limited to the four existing mechanic owners. Reusable Specialization combat-effect prose may supply a tree-rank effect but does not become a separate public catalog.
  • Relevant precedents: source-owned mechanic programs (4eb754e), captured-only authoring (57068b6), agent-assisted mechanic imports (65a4987), audit-safe bulk mutations (6be31de), and hash-driven staleness/backfills (dc08eef).

Tickets

Decisions so far

  • #2 authored-description and mechanic lifecycle: owner-specific templates and independent authored slots produce materialized fallback prose; immutable model revisions use source fingerprints; public status derives from model currency rather than simulation readiness.
  • #3 autonomous mechanic-capability boundary: generation classifies evidence, assumptions, prerequisites, and capability gaps; Modeling Sessions may implement missing capability through full verification, staged automatic release, and resumable persistence.
  • #4 Modeling Session contract: an interactive coding-agent session enumerates absent or stale owners, generates and validates one mechanic locally, obtains per-record chat confirmation, then submits through the existing owning ISAC action; canonical state supplies resume and duplicate protection.
  • #5 public fallback and model status: Variant A adds a binary badge and one primary behavior block to public cards, quick views, and search; current models use deterministic rendered behavior while absent or stale owners use exact authored fallback. Variant C remains prototype precedent for a future ISAC registry.
  • #6 mutation, audit, and reversal: each confirmed record uses its existing ISAC action and one source-guarded owner transaction; normal audit evidence remains authoritative, and reversal creates a new corrective model revision.
  • #7 migration, backfill, and compatibility: proof-based preflight gates one atomic cutover; proven programs become imported current revisions, empty placeholders become absent, legacy projections are removed, and version 6 is the only supported ISAC snapshot.

Final specification

  • Implementation partition, rollout order, and verification matrix
  • Modeling Sessions persist no run history, checkpoints, receipts, transcripts, or coverage metrics; canonical lifecycle and Audit Events provide durable state.
  • Proof-based preflight blocks every record that cannot backfill losslessly. A Registered Agent must repair or explicitly clear each blocked record before the atomic cutover.

Out of scope

  • Implementing the change during this planning map.
  • ISAC per-record generation buttons, a bulk-generation dashboard, unattended scheduling, or other product UI for generation.
  • External screenshots, guides, or operator notes as generation evidence; those must first update the canonical authored description through normal data entry.
  • Persisting assumption-inventing or best-effort combat behavior.
  • A standalone public registry for reusable Specialization combat-effect catalog entries.
  • Public exposure of internal lifecycle distinctions beyond the binary modeling state.
## Destination An implementation-ready specification, carried by this map's resolved tickets, for entering and publishing authored fallback descriptions independently of combat models across Talent, OS Protocol Talent, Skill Chip Talent, and Specialization tree-rank effects, then generating valid models through a Modeling Session after entry. ## Notes - This map plans the change; it does not implement it. - Sessions must consult the `grilling` and `domain-modeling` skills. Prototype tickets must also consult `prototype`. - Modeled text is the primary public display; exact authored prose is the fallback while modeling is absent or stale. - Authored prose follows each owner's existing variant contract and is required for publication. - Public users see a binary `MODELED` / `NOT MODELED` state. Internal lifecycle detail may remain richer. - Editing authored prose makes its prior model stale and restores fallback display until regeneration succeeds. - Generation uses only stored authored descriptions as semantic evidence. - The required generation workflow is an interactive Modeling Session; ISAC generation controls are not required. - A Modeling Session may persist a generated model and its prerequisites only after per-record chat confirmation. Ambiguous behavior must not be invented. - Scope is limited to the four existing mechanic owners. Reusable Specialization combat-effect prose may supply a tree-rank effect but does not become a separate public catalog. - Relevant precedents: source-owned mechanic programs (`4eb754e`), captured-only authoring (`57068b6`), agent-assisted mechanic imports (`65a4987`), audit-safe bulk mutations (`6be31de`), and hash-driven staleness/backfills (`dc08eef`). ## Tickets - [x] [Define the authored-description and mechanic lifecycle](https://git.jb.codes/jb/shd.build/issues/2) - [x] [Define the autonomous mechanic-capability boundary](https://git.jb.codes/jb/shd.build/issues/3) - [x] [Define the Modeling Session contract](https://git.jb.codes/jb/shd.build/issues/4) - [x] [Prototype public fallback and modeling status](https://git.jb.codes/jb/shd.build/issues/5) - [x] [Define canonical mutation, moderation, audit, and reversal semantics](https://git.jb.codes/jb/shd.build/issues/6) - [x] [Define migration, backfill, and compatibility policy](https://git.jb.codes/jb/shd.build/issues/7) ## Decisions so far - [#2 authored-description and mechanic lifecycle](https://git.jb.codes/jb/shd.build/issues/2#issuecomment-125): owner-specific templates and independent authored slots produce materialized fallback prose; immutable model revisions use source fingerprints; public status derives from model currency rather than simulation readiness. - [#3 autonomous mechanic-capability boundary](https://git.jb.codes/jb/shd.build/issues/3#issuecomment-126): generation classifies evidence, assumptions, prerequisites, and capability gaps; Modeling Sessions may implement missing capability through full verification, staged automatic release, and resumable persistence. - [#4 Modeling Session contract](https://git.jb.codes/jb/shd.build/issues/4#issuecomment-133): an interactive coding-agent session enumerates absent or stale owners, generates and validates one mechanic locally, obtains per-record chat confirmation, then submits through the existing owning ISAC action; canonical state supplies resume and duplicate protection. - [#5 public fallback and model status](https://git.jb.codes/jb/shd.build/issues/5#issuecomment-150): Variant A adds a binary badge and one primary behavior block to public cards, quick views, and search; current models use deterministic rendered behavior while absent or stale owners use exact authored fallback. Variant C remains prototype precedent for a future ISAC registry. - [#6 mutation, audit, and reversal](https://git.jb.codes/jb/shd.build/issues/6#issuecomment-143): each confirmed record uses its existing ISAC action and one source-guarded owner transaction; normal audit evidence remains authoritative, and reversal creates a new corrective model revision. - [#7 migration, backfill, and compatibility](https://git.jb.codes/jb/shd.build/issues/7#issuecomment-146): proof-based preflight gates one atomic cutover; proven programs become imported current revisions, empty placeholders become absent, legacy projections are removed, and version 6 is the only supported ISAC snapshot. ## Final specification - [Implementation partition, rollout order, and verification matrix](https://git.jb.codes/jb/shd.build/issues/1#issuecomment-153) - Modeling Sessions persist no run history, checkpoints, receipts, transcripts, or coverage metrics; canonical lifecycle and Audit Events provide durable state. - Proof-based preflight blocks every record that cannot backfill losslessly. A Registered Agent must repair or explicitly clear each blocked record before the atomic cutover. ## Out of scope - Implementing the change during this planning map. - ISAC per-record generation buttons, a bulk-generation dashboard, unattended scheduling, or other product UI for generation. - External screenshots, guides, or operator notes as generation evidence; those must first update the canonical authored description through normal data entry. - Persisting assumption-inventing or best-effort combat behavior. - A standalone public registry for reusable Specialization combat-effect catalog entries. - Public exposure of internal lifecycle distinctions beyond the binary modeling state.
jb added the wayfinder:map label 2026-08-23 13:08:16 -04:00
jb commented 2026-08-23 21:12:28 -04:00
Author
Owner
Copy Link
Copy Source

Deferred combat modeling implementation specification

Outcome

SHD.build will publish exact authored mechanic descriptions before a structured Mechanic Program exists. Talent, OS Protocol Talent, Skill Chip Talent, and Specialization tree-rank effects will share one authored-source lifecycle, immutable model revisions, deterministic public rendering, and binary public status.

An interactive Modeling Session will model one Canonical Record at a time. The session uses stored authored descriptions as its only semantic evidence, validates the draft locally, shows the complete mechanic in chat, obtains confirmation for that record, and submits the existing authenticated ISAC action through browser-harness.

SHD.build will not add a Modeling Client API, bearer token, bulk job, generation receipt, checkpoint, dashboard, persisted chat approval, or contribution proposal path for Modeling Sessions.

Locked contracts

Authored sources

Add a shared authored-description module with these owner contracts:

Owner Required variants
Standard Talent I, II
Exotic Talent I, plus II only when the owner defines Tier II
OS Protocol Talent base
Skill Chip Talent minimum, maximum
Specialization tree-rank effect base

Each owner stores a template, independent authored slot values, ordered variants, and exact materialized prose. Numbered slots, duration, and stack values no longer come from Mechanic Program outcomes. Canonical owner saves and Contribution Proposal approval reject unknown tokens, unresolved slots, missing variants, or a stored materialization that differs from a fresh render. Incomplete Contribution Proposals may persist before approval.

Specialization source identity includes rank description, reusable effect identity and template, and rank-specific authored values. The reusable effect remains an internal authoring input.

The server computes SHA-256 source fingerprint version 1 over versioned canonical JSON containing owner type and ID, template, ordered variants and slots, Specialization inputs when applicable, and authored-contract version. Timestamps, editor state, display-only ordering, and model data are excluded.

Model revisions and lifecycle

Every model save creates an append-only revision containing source fingerprint, mechanic contract version, program hash, readiness, Scenario Inputs, and the normalized graph. The owner selects one revision. Application services never update or delete revision data; the database adds no immutability triggers.

Lifecycle derives from canonical state:

  • absent: no selected non-empty valid revision;
  • stale: a selected revision has a different source fingerprint or unsupported mechanic contract;
  • current: the selected non-empty revision matches and validates.

A current ready, requires_assumptions, or valid non-empty captured_only revision is publicly MODELED. Empty capture placeholders are absent. Absent and stale owners are publicly NOT MODELED. Stale revisions remain stored but never render publicly or execute in Builder calculations.

Modeling Session

The session discovers absent or stale owners through authenticated ISAC registry reads and filters. It reloads one owner, reads the materialized descriptions and current fingerprint, and constructs ConditionalMechanicDraftV1 without calling /api/isac/mechanic-assistant.

Missing source evidence produces a chat clarification and no write. Explicit encounter variables become typed Scenario Inputs. A fully determined prerequisite may be created through its existing audited ISAC action. Unsupported grammar, persistence, editor, Builder value production, or runtime behavior produces a capability gap rather than an approximation.

Before each owner submission, the session shows exact variant prose, readiness, Scenario Inputs, conditions, pools, outcomes, variant values, prerequisites, warnings, pseudo-script, fingerprint, and target action. The Registered Agent confirms that record in chat. Any semantic edit or source-fingerprint change expires confirmation.

The session submits the existing owner action with expectedSourceFingerprint. The action requires the authenticated Agent's normal data.manage permission. It recomputes the fingerprint in the owner transaction, rejects drift without side effects, inserts and selects the model revision, updates public projections, and appends the existing owner Audit Event. An uncertain retry first reloads canonical state and skips an identical current graph.

Capability changes run on a branch, pass focused and repository verification plus independent code and security review, deploy to staging, verify health and representative generation, then merge and deploy to production through the existing deployment workflows before the session resumes.

Public presentation

Adopt prototype Variant A from prototype/issue-5-model-status at 904cb07. Variant C remains prototype precedent for a possible future ISAC registry.

Public cards, quick views, and global search show one textual badge and one primary behavior block. MODELED uses the established model surface and blue treatment. NOT MODELED is neutral. Orange remains action-only.

A deterministic renderer converts the selected structured program into public behavior text. It never exposes raw JSON or pseudo-script. If no current renderable model exists, the same block shows exact materialized authored prose. Labels read MODELED BEHAVIOR or AUTHORED DESCRIPTION; public pages never reveal readiness, source hashes, revision IDs, or stale-versus-absent distinctions.

Talent preserves tier hierarchy, OS Protocol retains level and upgrade controls, Skill Chip shows minimum and maximum, and Specialization adds Focus/node/rank effect detail. Each Specialization rank-effect attachment is a separate mechanic owner with its own badge and behavior block; a rank containing mixed-status attachments does not receive an aggregate status. Cards, quick views, and search read one public projection so status and text cannot disagree.

Target persistence

Add these structures to database/schema.sql and the migration tooling:

  • mechanic_authored_sources: stable source identity, owner type and ID, template, authored-contract version, current source fingerprint;
  • mechanic_authored_variants: ordered variant key and exact materialized prose;
  • mechanic_authored_slots: source, variant, slot key, exact display value, ordering, and optional unit/Attribute metadata;
  • mechanic_model_revisions: source, revision number, source fingerprint, mechanic contract, program hash, readiness, Scenario Inputs, origin, actor, and timestamp;
  • revision child tables for pools, clauses, and outcomes;
  • mechanic_model_selections: one selected revision per authored source;
  • mechanic_public_variants: source and variant, selected revision, fingerprint and contract versions, binary status, rendered behavior, and display source;
  • a simplified Specialization rank-effect owner association that retains stable attachment identity but moves trigger, state, and outcome behavior into model revisions.

The atomic cutover removes the mutable conditional_effect_rules graph and its children; template, tier-description, and protocol/chip effect projections replaced by authored tables; program-derived Talent summary columns; and Specialization combat projections replaced by the new owner association and revisions. Before implementation locks the drop list, a dependency scan must prove that every named table and column has a new authoritative reader. The release retains no dual writes or compatibility reader.

Implementation phases

These phases are development slices for one coordinated release. No phase deploys to production until the complete cutover package and proof-based migration pass.

Phase 1: Pure authored, lifecycle, and rendering contracts

Create:

  • src/lib/calculations/mechanic-authored-description.ts
  • src/lib/calculations/mechanic-lifecycle.ts
  • src/lib/calculations/mechanic-public-renderer.ts
  • adjacent tests.

Update src/lib/calculations/mechanic-editor.ts and src/lib/calculations/mechanic.ts to remove descriptionSlot as authored authority while retaining structured outcome meaning.

Implement owner variant derivation, strict slot grammar, materialization, canonical serialization, hashing, lifecycle classification, stable program hashing, and deterministic public rendering. The renderer must cover every registered Event, condition, state, Outcome, duration, Cooldown, stack, Attribute, and variant label or reject the model as unrenderable.

Success criteria

  • Every owner materializes complete prose without a Mechanic Program.
  • Fingerprint and public-render snapshots are deterministic.
  • Empty capture, current readiness states, stale hashes, unsupported contracts, and unrenderable graphs classify exactly as specified.
  • Unresolved source values never become guessed numbers or Scenario Inputs.

Phase 2: Revision persistence and shared owner mutation seam

Create:

  • src/lib/server/mechanic-authored-sources.ts
  • src/lib/server/mechanic-model-revisions.ts
  • src/lib/server/mechanic-public-projection.ts
  • src/lib/components/isac/AuthoredDescriptionEditor.svelte.

Replace src/lib/server/conditional-effects.ts with append-only revision persistence and selected-revision reads. Refactor owner route actions and editors:

  • src/routes/isac/talents/+page.server.ts and +page.svelte
  • src/routes/isac/protocols/+page.server.ts and +page.svelte
  • src/routes/isac/skillchips/+page.server.ts and +page.svelte
  • src/routes/isac/specializations/+page.server.ts and +page.svelte
  • src/routes/isac/data-moderation/+page.server.ts and +page.svelte.

Migrate Data Oversight snapshots and previews from conditionalRuleSnapshot to authored-source and immutable-revision snapshots. Approval replay must enter the same shared owner service as a direct save.

Each form carries expectedSourceFingerprint and explicit selection intent: preserve, save a new revision, or clear selection. The transaction compares the fingerprint, validates authored state, inserts any revision, selects it, refreshes public variants, updates relationships, and appends the complete owner Audit Event. A prose-only edit preserves the selected pointer and makes it stale through hash mismatch.

Remove forced-model validation for Exotic and Skill Chip Talents. Refactor owner actions into shared server functions so ISAC form submission, Data Oversight replay, audit reversion, and tests use one validation and transaction path.

Saving a reusable specialization_combat_effects template must enumerate every attached tree-rank effect in the same transaction, recompute each authored fingerprint and materialization, preserve each selected revision pointer so changed attachments become stale, and refresh every affected public projection.

Success criteria

  • All four owners save complete prose with no model.
  • Fingerprint conflicts produce no partial owner, revision, projection, relationship, or audit write.
  • Every model save creates a new revision; identical uncertain retries create none.
  • Owner Audit Events capture source, selected revision, readiness, Scenario Inputs, graph, and relationship evidence without secrets or chat text.

Phase 3: Runtime and Public Database cutover

Update current model consumers:

  • src/lib/calculations/mechanic-persistence.ts
  • src/lib/builder/loadout-combat.ts
  • src/lib/builder/loadout-summary.ts
  • src/routes/builder/+page.server.ts
  • src/lib/server/shared-build-summary.ts
  • related Builder and shared-Build components.

Only adapt a selected revision when fingerprint, contract, and graph validation all pass.

Extend src/lib/database/items.ts with shared behavior groups. Update:

  • src/routes/database/[category]/+page.server.ts
  • src/routes/database/+page.server.ts and +page.svelte
  • src/lib/components/DatabaseItemCard.svelte
  • src/lib/components/ItemIconRail.svelte
  • src/app.css.

Port only Variant A production structure. Add Specialization tree-rank projection and search coverage. Search and cards use mechanic_public_variants, with exact authored fallback already selected in that projection.

Success criteria

  • Stale models never execute or appear in public text, search, Builder summaries, or shared Builds.
  • Every public owner shows exactly one binary textual state.
  • Card, quick-view, and search status/text agree across all variants and owner types; each Specialization attachment reports independently without a misleading rank aggregate.
  • Compact behavior text truncates visually while its full value remains available to assistive technology and the linked detail.
  • Keyboard, focus restoration, screen-reader, responsive, contrast, loading/error, and reduced-motion checks pass.

Phase 4: Proof-based preflight and atomic database cutover

Create:

  • scripts/mechanic-cutover-preflight.mjs
  • scripts/mechanic-cutover-verify.mjs
  • adjacent tests and fixtures.

Integrate the repeatable cutover into scripts/db-migrate.mjs. Preflight classifies every owner as lossless, absent, or blocked and writes a machine-readable report with a digest of relevant rows. Owner-specific checks require exact round trips among template, outcome display values, required variants, existing projections, and rendered prose. Populated captured-only graphs may migrate when they validate and round-trip; empty captures become absent.

A Registered Agent repairs or explicitly clears every blocked record through normal audited owner actions before cutover. Preflight also blocks on every pending legacy Contribution Proposal whose serialized owner payload lacks the new authored fields and expected fingerprint; Data Oversight must approve, correct into the new contract, reject, or otherwise resolve each proposal before migration. The cutover never silently discards a pending proposal.

Migration recomputes the reviewed digest, backfills authored state and imported revision 1, validates counts, hashes, foreign keys, programs, and selections, switches every reader, drops all proven legacy projections, and commits only when every assertion passes.

Success criteria

  • Preflight is deterministic and read-only.
  • Unsupported actions, missing variants, unresolved placeholders, lossy projections, and source drift block migration.
  • No historical revisions, stale periods, or provenance are fabricated.
  • Repeated migration is safe, and any failed assertion leaves the legacy database intact.
  • The post-cutover verifier compares row counts, critical entity identities, rendered descriptions, source hashes, and selected-program validation with the verified backup and preflight before writers restart.
  • The completed release passes npm run check, then npm run build, then npm test in that order.

Phase 5: Modeling Session skill and capability workflow

Create .agents/skills/model-authored-mechanics/SKILL.md and focused references. Apply the writing-for-agents and stop-slop skills to the full documents.

The skill uses authenticated ISAC registry reads for candidate discovery, repository validators for local draft checks, one-record chat confirmation, browser-harness for the existing owner action, and canonical read-back for revision and Audit Event verification. It must not call the application AI assistant or write database tables directly.

Update the existing Talent and weapon screenshot skills to delegate stored-description modeling to this shared workflow instead of duplicating rules.

Capability-gap instructions enumerate required grammar, persistence, editor, public renderer, Builder value pipeline, AI assistant contract where still relevant to manual ISAC use, tests, documentation, review, staging deployment, production deployment, and resume checks.

Success criteria

  • A fresh session can stop and resume from canonical absent/stale state.
  • Every mutation has one visible chat confirmation and a successful post-save read-back.
  • Prerequisites use their owning actions and remain separately audited; an uncertain retry reloads and reuses an exact canonical prerequisite without a duplicate write.
  • Unsupported semantics produce a capability gap with no model revision and no empty captured placeholder.
  • A failed capability check, review, merge, migration, or deployment leaves canonical models and the prior deployment unchanged while affected owners remain pending.
  • No application-side session, token, receipt, or bulk history infrastructure exists.

Phase 6: Corrective revision, snapshots, docs, and release

Create src/lib/server/mechanic-reversal.ts and extend src/routes/isac/audit/+page.server.ts. Reversal requires audit.revert, explicit confirmation, current-state comparison, matching authored fingerprint, dependency validation, and a compatible prior graph. It copies that graph into a new corrective revision, selects it, refreshes public projections, and appends audit.reverted; it never deletes or rewrites history.

Update scripts/isac-data-tables.mjs, export/import/restore validation, and tests for ISAC snapshot version 6. Version 5 imports fail with an explicit unsupported-version error. The generic full backup format may remain unchanged only if tests prove that it enumerates all new tables and counts.

Update docs/architecture.md, docs/DESIGN_SYSTEM.md, docs/DEPLOYMENT.md, docs/TALENT_MECHANIC_RULES.md where conventions change, and CONTEXT.md. Apply stop-slop to every complete affected document.

Success criteria

  • Corrective reversal preserves all model revisions and blocks on newer state or incompatible source.
  • Version 6 export/import round-trips the complete authored, revision, selection, and public projection graph.
  • No version 5 reader, dual write, or legacy fallback remains.
  • Architecture, domain, deployment, mechanic, and design-system documentation match production behavior.
  • The tracked development server is restarted after the completed source change, logs show one successful server, and an HTTP request succeeds while that verified server remains running.

Rollout order

  1. Finish all six implementation phases and independent review on one release branch.
  2. Stop the development server before database maintenance.
  3. Run and review cutover preflight; repair or explicitly clear every blocked development record through audited actions.
  4. Run npm run check, npm run build, and npm test.
  5. Create and verify a timestamped npm run db:backup; record affected-table counts and critical owner identities.
  6. Run the migration and post-cutover verifier; restart the development server and verify HTTP health and representative owner/editor/public flows.
  7. Deploy to staging through the existing skill. Verify migration, counts, owner round trips, stale fallback, public search, Builder exclusion, corrective reversal, version 6 snapshot round trip, and one non-production Modeling Session submission.
  8. Preserve a production backup and counts, deploy through the existing production workflow, verify installed contracts and health, then resume any paused Modeling Session from canonical state.

Any migration assertion rolls back. A post-commit verification failure keeps writers stopped, preserves the failed database and logs, and restores the verified backup through the documented empty-target restore process before the previous release resumes.

Verification Notes

  • Unit tests: owner variant contracts, token grammar, exact slot formatting, canonical JSON, SHA-256 fixtures, lifecycle, public renderer, and program hashes.
  • Persistence tests: append-only revisions, selected pointers, identical retry skip, source conflict rollback, stale exclusion, public projection refresh, and complete compound Audit Event evidence.
  • Owner action tests: all four families, standard and optional Exotic variants, no-model saves, incomplete canonical rejection, incomplete proposal persistence and approval rejection, prerequisite relationships, and one-transaction rollback.
  • Runtime tests: stale/invalid/captured-only handling in persistence, Builder, shared Builds, and public projection.
  • Public tests: card, quick view, global search, Specialization ranks, Tier I/II, minimum/maximum, base, accessibility, truncation, and responsive states.
  • Migration tests: every owner, empty/populated capture, executable models, mismatched projections, unsupported legacy actions, digest drift, repeatability, rollback, counts, hashes, foreign keys, and critical identities.
  • Snapshot tests: version 6 dependency order and round trip, empty-target enforcement, explicit version 5 rejection, and full-backup coverage of new tables.
  • Reversal tests: permission, confirmation, current-state comparison, compatible copy, source mismatch, dependency conflict, newer selection, and audit.reverted evidence.
  • Required repository commands run in order: npm run check, npm run build, npm test.
  • After source, style, configuration, dependency, or route changes, restart the tracked development server, verify logs, and confirm an HTTP request while leaving one verified server running.

Precedents & Lessons

  • 4eb754e: source-owned mechanics crossed schema, runtime, persistence, ISAC, Builder, public reads, tests, docs, and snapshots. Follow-up 11406e3 shows that migration completion must inspect the structure being transformed rather than the presence of a legacy table.
  • 65a4987: authored placeholders coupled to outcomes created lossy projections and owner exceptions. Unresolved values must remain unresolved; independent authored slots and exact proof checks prevent invention.
  • 57068b6: successful ISAC reshaping validated manifests, cardinality, ranges, and relationships in one transaction and rejected old snapshot formats. Schema, restore, import, export, and consumers move together.
  • 6be31de and 99fe604: compound Audit Events need explicit child snapshots, and reversal must compare current state and append compensation rather than rewrite history.
  • dc08eef, 92e1f58, and 9089f4a: append-only revisions and content hashes work, but schema presence did not prove backfill completion. Preflight, execution, and post-state verification must all be tested.
  • Prototype 904cb07: Variant A matches current public card hierarchy; Variant C remains useful only as future ISAC precedent. Prototype files and switcher never merge into production.

Explicit exclusions

  • Per-record or bulk generation buttons in ISAC.
  • Application-side Modeling Client authentication or APIs.
  • Stored Modeling Session manifests, transcripts, approvals, checkpoints, receipts, dashboards, or coverage metrics.
  • Best-effort or assumption-inventing mechanics.
  • A public reusable Specialization effect catalog.
  • Legacy snapshot readers, dual writes, compatibility projections, or fallback parsing after cutover.
# Deferred combat modeling implementation specification ## Outcome SHD.build will publish exact authored mechanic descriptions before a structured Mechanic Program exists. Talent, OS Protocol Talent, Skill Chip Talent, and Specialization tree-rank effects will share one authored-source lifecycle, immutable model revisions, deterministic public rendering, and binary public status. An interactive **Modeling Session** will model one Canonical Record at a time. The session uses stored authored descriptions as its only semantic evidence, validates the draft locally, shows the complete mechanic in chat, obtains confirmation for that record, and submits the existing authenticated ISAC action through browser-harness. SHD.build will not add a Modeling Client API, bearer token, bulk job, generation receipt, checkpoint, dashboard, persisted chat approval, or contribution proposal path for Modeling Sessions. ## Locked contracts ### Authored sources Add a shared authored-description module with these owner contracts: | Owner | Required variants | | --- | --- | | Standard Talent | `I`, `II` | | Exotic Talent | `I`, plus `II` only when the owner defines Tier II | | OS Protocol Talent | `base` | | Skill Chip Talent | `minimum`, `maximum` | | Specialization tree-rank effect | `base` | Each owner stores a template, independent authored slot values, ordered variants, and exact materialized prose. Numbered slots, duration, and stack values no longer come from Mechanic Program outcomes. Canonical owner saves and Contribution Proposal approval reject unknown tokens, unresolved slots, missing variants, or a stored materialization that differs from a fresh render. Incomplete Contribution Proposals may persist before approval. Specialization source identity includes rank description, reusable effect identity and template, and rank-specific authored values. The reusable effect remains an internal authoring input. The server computes SHA-256 source fingerprint version 1 over versioned canonical JSON containing owner type and ID, template, ordered variants and slots, Specialization inputs when applicable, and authored-contract version. Timestamps, editor state, display-only ordering, and model data are excluded. ### Model revisions and lifecycle Every model save creates an append-only revision containing source fingerprint, mechanic contract version, program hash, readiness, Scenario Inputs, and the normalized graph. The owner selects one revision. Application services never update or delete revision data; the database adds no immutability triggers. Lifecycle derives from canonical state: - `absent`: no selected non-empty valid revision; - `stale`: a selected revision has a different source fingerprint or unsupported mechanic contract; - `current`: the selected non-empty revision matches and validates. A current `ready`, `requires_assumptions`, or valid non-empty `captured_only` revision is publicly `MODELED`. Empty capture placeholders are absent. Absent and stale owners are publicly `NOT MODELED`. Stale revisions remain stored but never render publicly or execute in Builder calculations. ### Modeling Session The session discovers absent or stale owners through authenticated ISAC registry reads and filters. It reloads one owner, reads the materialized descriptions and current fingerprint, and constructs `ConditionalMechanicDraftV1` without calling `/api/isac/mechanic-assistant`. Missing source evidence produces a chat clarification and no write. Explicit encounter variables become typed Scenario Inputs. A fully determined prerequisite may be created through its existing audited ISAC action. Unsupported grammar, persistence, editor, Builder value production, or runtime behavior produces a capability gap rather than an approximation. Before each owner submission, the session shows exact variant prose, readiness, Scenario Inputs, conditions, pools, outcomes, variant values, prerequisites, warnings, pseudo-script, fingerprint, and target action. The Registered Agent confirms that record in chat. Any semantic edit or source-fingerprint change expires confirmation. The session submits the existing owner action with `expectedSourceFingerprint`. The action requires the authenticated Agent's normal `data.manage` permission. It recomputes the fingerprint in the owner transaction, rejects drift without side effects, inserts and selects the model revision, updates public projections, and appends the existing owner Audit Event. An uncertain retry first reloads canonical state and skips an identical current graph. Capability changes run on a branch, pass focused and repository verification plus independent code and security review, deploy to staging, verify health and representative generation, then merge and deploy to production through the existing deployment workflows before the session resumes. ### Public presentation Adopt prototype Variant A from [`prototype/issue-5-model-status` at `904cb07`](https://git.jb.codes/jb/shd.build/src/commit/904cb07). Variant C remains prototype precedent for a possible future ISAC registry. Public cards, quick views, and global search show one textual badge and one primary behavior block. `MODELED` uses the established model surface and blue treatment. `NOT MODELED` is neutral. Orange remains action-only. A deterministic renderer converts the selected structured program into public behavior text. It never exposes raw JSON or pseudo-script. If no current renderable model exists, the same block shows exact materialized authored prose. Labels read `MODELED BEHAVIOR` or `AUTHORED DESCRIPTION`; public pages never reveal readiness, source hashes, revision IDs, or stale-versus-absent distinctions. Talent preserves tier hierarchy, OS Protocol retains level and upgrade controls, Skill Chip shows minimum and maximum, and Specialization adds Focus/node/rank effect detail. Each Specialization rank-effect attachment is a separate mechanic owner with its own badge and behavior block; a rank containing mixed-status attachments does not receive an aggregate status. Cards, quick views, and search read one public projection so status and text cannot disagree. ## Target persistence Add these structures to `database/schema.sql` and the migration tooling: - `mechanic_authored_sources`: stable source identity, owner type and ID, template, authored-contract version, current source fingerprint; - `mechanic_authored_variants`: ordered variant key and exact materialized prose; - `mechanic_authored_slots`: source, variant, slot key, exact display value, ordering, and optional unit/Attribute metadata; - `mechanic_model_revisions`: source, revision number, source fingerprint, mechanic contract, program hash, readiness, Scenario Inputs, origin, actor, and timestamp; - revision child tables for pools, clauses, and outcomes; - `mechanic_model_selections`: one selected revision per authored source; - `mechanic_public_variants`: source and variant, selected revision, fingerprint and contract versions, binary status, rendered behavior, and display source; - a simplified Specialization rank-effect owner association that retains stable attachment identity but moves trigger, state, and outcome behavior into model revisions. The atomic cutover removes the mutable `conditional_effect_rules` graph and its children; template, tier-description, and protocol/chip effect projections replaced by authored tables; program-derived Talent summary columns; and Specialization combat projections replaced by the new owner association and revisions. Before implementation locks the drop list, a dependency scan must prove that every named table and column has a new authoritative reader. The release retains no dual writes or compatibility reader. ## Implementation phases These phases are development slices for one coordinated release. No phase deploys to production until the complete cutover package and proof-based migration pass. ### Phase 1: Pure authored, lifecycle, and rendering contracts Create: - `src/lib/calculations/mechanic-authored-description.ts` - `src/lib/calculations/mechanic-lifecycle.ts` - `src/lib/calculations/mechanic-public-renderer.ts` - adjacent tests. Update `src/lib/calculations/mechanic-editor.ts` and `src/lib/calculations/mechanic.ts` to remove `descriptionSlot` as authored authority while retaining structured outcome meaning. Implement owner variant derivation, strict slot grammar, materialization, canonical serialization, hashing, lifecycle classification, stable program hashing, and deterministic public rendering. The renderer must cover every registered Event, condition, state, Outcome, duration, Cooldown, stack, Attribute, and variant label or reject the model as unrenderable. #### Success criteria - Every owner materializes complete prose without a Mechanic Program. - Fingerprint and public-render snapshots are deterministic. - Empty capture, current readiness states, stale hashes, unsupported contracts, and unrenderable graphs classify exactly as specified. - Unresolved source values never become guessed numbers or Scenario Inputs. ### Phase 2: Revision persistence and shared owner mutation seam Create: - `src/lib/server/mechanic-authored-sources.ts` - `src/lib/server/mechanic-model-revisions.ts` - `src/lib/server/mechanic-public-projection.ts` - `src/lib/components/isac/AuthoredDescriptionEditor.svelte`. Replace `src/lib/server/conditional-effects.ts` with append-only revision persistence and selected-revision reads. Refactor owner route actions and editors: - `src/routes/isac/talents/+page.server.ts` and `+page.svelte` - `src/routes/isac/protocols/+page.server.ts` and `+page.svelte` - `src/routes/isac/skillchips/+page.server.ts` and `+page.svelte` - `src/routes/isac/specializations/+page.server.ts` and `+page.svelte` - `src/routes/isac/data-moderation/+page.server.ts` and `+page.svelte`. Migrate Data Oversight snapshots and previews from `conditionalRuleSnapshot` to authored-source and immutable-revision snapshots. Approval replay must enter the same shared owner service as a direct save. Each form carries `expectedSourceFingerprint` and explicit selection intent: preserve, save a new revision, or clear selection. The transaction compares the fingerprint, validates authored state, inserts any revision, selects it, refreshes public variants, updates relationships, and appends the complete owner Audit Event. A prose-only edit preserves the selected pointer and makes it stale through hash mismatch. Remove forced-model validation for Exotic and Skill Chip Talents. Refactor owner actions into shared server functions so ISAC form submission, Data Oversight replay, audit reversion, and tests use one validation and transaction path. Saving a reusable `specialization_combat_effects` template must enumerate every attached tree-rank effect in the same transaction, recompute each authored fingerprint and materialization, preserve each selected revision pointer so changed attachments become stale, and refresh every affected public projection. #### Success criteria - All four owners save complete prose with no model. - Fingerprint conflicts produce no partial owner, revision, projection, relationship, or audit write. - Every model save creates a new revision; identical uncertain retries create none. - Owner Audit Events capture source, selected revision, readiness, Scenario Inputs, graph, and relationship evidence without secrets or chat text. ### Phase 3: Runtime and Public Database cutover Update current model consumers: - `src/lib/calculations/mechanic-persistence.ts` - `src/lib/builder/loadout-combat.ts` - `src/lib/builder/loadout-summary.ts` - `src/routes/builder/+page.server.ts` - `src/lib/server/shared-build-summary.ts` - related Builder and shared-Build components. Only adapt a selected revision when fingerprint, contract, and graph validation all pass. Extend `src/lib/database/items.ts` with shared behavior groups. Update: - `src/routes/database/[category]/+page.server.ts` - `src/routes/database/+page.server.ts` and `+page.svelte` - `src/lib/components/DatabaseItemCard.svelte` - `src/lib/components/ItemIconRail.svelte` - `src/app.css`. Port only Variant A production structure. Add Specialization tree-rank projection and search coverage. Search and cards use `mechanic_public_variants`, with exact authored fallback already selected in that projection. #### Success criteria - Stale models never execute or appear in public text, search, Builder summaries, or shared Builds. - Every public owner shows exactly one binary textual state. - Card, quick-view, and search status/text agree across all variants and owner types; each Specialization attachment reports independently without a misleading rank aggregate. - Compact behavior text truncates visually while its full value remains available to assistive technology and the linked detail. - Keyboard, focus restoration, screen-reader, responsive, contrast, loading/error, and reduced-motion checks pass. ### Phase 4: Proof-based preflight and atomic database cutover Create: - `scripts/mechanic-cutover-preflight.mjs` - `scripts/mechanic-cutover-verify.mjs` - adjacent tests and fixtures. Integrate the repeatable cutover into `scripts/db-migrate.mjs`. Preflight classifies every owner as `lossless`, `absent`, or `blocked` and writes a machine-readable report with a digest of relevant rows. Owner-specific checks require exact round trips among template, outcome display values, required variants, existing projections, and rendered prose. Populated captured-only graphs may migrate when they validate and round-trip; empty captures become absent. A Registered Agent repairs or explicitly clears every blocked record through normal audited owner actions before cutover. Preflight also blocks on every pending legacy Contribution Proposal whose serialized owner payload lacks the new authored fields and expected fingerprint; Data Oversight must approve, correct into the new contract, reject, or otherwise resolve each proposal before migration. The cutover never silently discards a pending proposal. Migration recomputes the reviewed digest, backfills authored state and imported revision 1, validates counts, hashes, foreign keys, programs, and selections, switches every reader, drops all proven legacy projections, and commits only when every assertion passes. #### Success criteria - Preflight is deterministic and read-only. - Unsupported actions, missing variants, unresolved placeholders, lossy projections, and source drift block migration. - No historical revisions, stale periods, or provenance are fabricated. - Repeated migration is safe, and any failed assertion leaves the legacy database intact. - The post-cutover verifier compares row counts, critical entity identities, rendered descriptions, source hashes, and selected-program validation with the verified backup and preflight before writers restart. - The completed release passes `npm run check`, then `npm run build`, then `npm test` in that order. ### Phase 5: Modeling Session skill and capability workflow Create `.agents/skills/model-authored-mechanics/SKILL.md` and focused references. Apply the `writing-for-agents` and `stop-slop` skills to the full documents. The skill uses authenticated ISAC registry reads for candidate discovery, repository validators for local draft checks, one-record chat confirmation, browser-harness for the existing owner action, and canonical read-back for revision and Audit Event verification. It must not call the application AI assistant or write database tables directly. Update the existing Talent and weapon screenshot skills to delegate stored-description modeling to this shared workflow instead of duplicating rules. Capability-gap instructions enumerate required grammar, persistence, editor, public renderer, Builder value pipeline, AI assistant contract where still relevant to manual ISAC use, tests, documentation, review, staging deployment, production deployment, and resume checks. #### Success criteria - A fresh session can stop and resume from canonical absent/stale state. - Every mutation has one visible chat confirmation and a successful post-save read-back. - Prerequisites use their owning actions and remain separately audited; an uncertain retry reloads and reuses an exact canonical prerequisite without a duplicate write. - Unsupported semantics produce a capability gap with no model revision and no empty captured placeholder. - A failed capability check, review, merge, migration, or deployment leaves canonical models and the prior deployment unchanged while affected owners remain pending. - No application-side session, token, receipt, or bulk history infrastructure exists. ### Phase 6: Corrective revision, snapshots, docs, and release Create `src/lib/server/mechanic-reversal.ts` and extend `src/routes/isac/audit/+page.server.ts`. Reversal requires `audit.revert`, explicit confirmation, current-state comparison, matching authored fingerprint, dependency validation, and a compatible prior graph. It copies that graph into a new corrective revision, selects it, refreshes public projections, and appends `audit.reverted`; it never deletes or rewrites history. Update `scripts/isac-data-tables.mjs`, export/import/restore validation, and tests for ISAC snapshot version 6. Version 5 imports fail with an explicit unsupported-version error. The generic full backup format may remain unchanged only if tests prove that it enumerates all new tables and counts. Update `docs/architecture.md`, `docs/DESIGN_SYSTEM.md`, `docs/DEPLOYMENT.md`, `docs/TALENT_MECHANIC_RULES.md` where conventions change, and `CONTEXT.md`. Apply `stop-slop` to every complete affected document. #### Success criteria - Corrective reversal preserves all model revisions and blocks on newer state or incompatible source. - Version 6 export/import round-trips the complete authored, revision, selection, and public projection graph. - No version 5 reader, dual write, or legacy fallback remains. - Architecture, domain, deployment, mechanic, and design-system documentation match production behavior. - The tracked development server is restarted after the completed source change, logs show one successful server, and an HTTP request succeeds while that verified server remains running. ## Rollout order 1. Finish all six implementation phases and independent review on one release branch. 2. Stop the development server before database maintenance. 3. Run and review cutover preflight; repair or explicitly clear every blocked development record through audited actions. 4. Run `npm run check`, `npm run build`, and `npm test`. 5. Create and verify a timestamped `npm run db:backup`; record affected-table counts and critical owner identities. 6. Run the migration and post-cutover verifier; restart the development server and verify HTTP health and representative owner/editor/public flows. 7. Deploy to staging through the existing skill. Verify migration, counts, owner round trips, stale fallback, public search, Builder exclusion, corrective reversal, version 6 snapshot round trip, and one non-production Modeling Session submission. 8. Preserve a production backup and counts, deploy through the existing production workflow, verify installed contracts and health, then resume any paused Modeling Session from canonical state. Any migration assertion rolls back. A post-commit verification failure keeps writers stopped, preserves the failed database and logs, and restores the verified backup through the documented empty-target restore process before the previous release resumes. ## Verification Notes - Unit tests: owner variant contracts, token grammar, exact slot formatting, canonical JSON, SHA-256 fixtures, lifecycle, public renderer, and program hashes. - Persistence tests: append-only revisions, selected pointers, identical retry skip, source conflict rollback, stale exclusion, public projection refresh, and complete compound Audit Event evidence. - Owner action tests: all four families, standard and optional Exotic variants, no-model saves, incomplete canonical rejection, incomplete proposal persistence and approval rejection, prerequisite relationships, and one-transaction rollback. - Runtime tests: stale/invalid/captured-only handling in persistence, Builder, shared Builds, and public projection. - Public tests: card, quick view, global search, Specialization ranks, Tier I/II, minimum/maximum, base, accessibility, truncation, and responsive states. - Migration tests: every owner, empty/populated capture, executable models, mismatched projections, unsupported legacy actions, digest drift, repeatability, rollback, counts, hashes, foreign keys, and critical identities. - Snapshot tests: version 6 dependency order and round trip, empty-target enforcement, explicit version 5 rejection, and full-backup coverage of new tables. - Reversal tests: permission, confirmation, current-state comparison, compatible copy, source mismatch, dependency conflict, newer selection, and `audit.reverted` evidence. - Required repository commands run in order: `npm run check`, `npm run build`, `npm test`. - After source, style, configuration, dependency, or route changes, restart the tracked development server, verify logs, and confirm an HTTP request while leaving one verified server running. ## Precedents & Lessons - `4eb754e`: source-owned mechanics crossed schema, runtime, persistence, ISAC, Builder, public reads, tests, docs, and snapshots. Follow-up `11406e3` shows that migration completion must inspect the structure being transformed rather than the presence of a legacy table. - `65a4987`: authored placeholders coupled to outcomes created lossy projections and owner exceptions. Unresolved values must remain unresolved; independent authored slots and exact proof checks prevent invention. - `57068b6`: successful ISAC reshaping validated manifests, cardinality, ranges, and relationships in one transaction and rejected old snapshot formats. Schema, restore, import, export, and consumers move together. - `6be31de` and `99fe604`: compound Audit Events need explicit child snapshots, and reversal must compare current state and append compensation rather than rewrite history. - `dc08eef`, `92e1f58`, and `9089f4a`: append-only revisions and content hashes work, but schema presence did not prove backfill completion. Preflight, execution, and post-state verification must all be tested. - Prototype `904cb07`: Variant A matches current public card hierarchy; Variant C remains useful only as future ISAC precedent. Prototype files and switcher never merge into production. ## Explicit exclusions - Per-record or bulk generation buttons in ISAC. - Application-side Modeling Client authentication or APIs. - Stored Modeling Session manifests, transcripts, approvals, checkpoints, receipts, dashboards, or coverage metrics. - Best-effort or assumption-inventing mechanics. - A public reusable Specialization effect catalog. - Legacy snapshot readers, dual writes, compatibility projections, or fallback parsing after cutover.
jb commented 2026-08-23 21:12:59 -04:00
Author
Owner
Copy Link
Copy Source

All six decision tickets are resolved. The reviewed implementation specification above defines the target data model, six implementation phases, atomic migration and rollout, Modeling Session workflow, Variant A public presentation, corrective reversal, verification matrix, database safeguards, and precedent lessons. Closing the planning map; implementation remains a separate change.

All six decision tickets are resolved. The reviewed implementation specification above defines the target data model, six implementation phases, atomic migration and rollout, Modeling Session workflow, Variant A public presentation, corrective reversal, verification matrix, database safeguards, and precedent lessons. Closing the planning map; implementation remains a separate change.
jb closed this issue 2026-08-23 21:13:00 -04:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
needs-triage
A maintainer must evaluate the issue
 wayfinder:grilling
Wayfinder HITL decision conversation
 wayfinder:map
Canonical Wayfinder planning map
 wayfinder:prototype
Wayfinder HITL prototype decision ticket
 wayfinder:research
Wayfinder AFK research decision ticket
 wayfinder:task
Wayfinder prerequisite task ticket
No labels wayfinder:map
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
jb
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: jb/shd.build#1