From acb19140aefc1c2f06af58fc0b237e1185172ca9 Mon Sep 17 00:00:00 2001 From: Laymer Date: Tue, 10 Nov 2026 14:26:37 +0100 Subject: [PATCH 01/10] V110.1: record guided progression release contract --- TODO.md | 24 +++- docs/STATUS.md | 17 +++ docs/claims/2026-11-10-v110-contract.md | 12 ++ .../decisions/0011-v110-guided-progression.md | 114 ++++++++++++++++++ docs/handoffs/2026-11-10-v110-contract.md | 43 +++++++ docs/releases/V1_RELEASE_PROCESS.md | 19 ++- release/v1/README.md | 15 +++ 7 files changed, 242 insertions(+), 2 deletions(-) create mode 100644 docs/claims/2026-11-10-v110-contract.md create mode 100644 docs/decisions/0011-v110-guided-progression.md create mode 100644 docs/handoffs/2026-11-10-v110-contract.md diff --git a/TODO.md b/TODO.md index e6fe1729..92ad9d28 100644 --- a/TODO.md +++ b/TODO.md @@ -1,4 +1,26 @@ -# 1.0.0 program tracker +# 1.1.0 program tracker + +Governing decision: [ADR 0011](docs/decisions/0011-v110-guided-progression.md). +Owner: Codex `/root`; baseline `aaa73b94`; isolated branch `feat/v1.1-guided-progression`. +This program supersedes unpublished 1.0.0 preparation. Historical completed rows +below do not establish 1.1.0 readiness. + +- [x] V110.1 Record contract, unsigned exception and automated acceptance policy. +- [ ] V110.2 Verify installed tuple/interface and exact-build compatibility. +- [ ] V110.3 Regenerate/review content; version gameplay facts and enforce coverage. +- [ ] V110.4 Progression exchange, explicit addon/manual capture and persistence. +- [ ] V110.5 Trainer spell service, saved plans and rendered workflow. +- [ ] V110.6 Authored editable talents, validation and next-point workflow. +- [ ] V110.7 Profession/crafting quantities, materials and acquisition workflow. +- [ ] V110.8 Equipment enhancement advice and integrations. +- [ ] V110.9 Version-aware release tooling and four-feature acceptance journeys. +- [ ] V110.10 Full checks/reviews, version freeze, inventory and fresh signed closure. +- [ ] V110.11 Protected-main integration, stability, tag and eight-case packaging. +- [ ] V110.12 Independent downloaded-draft UI acceptance, publication and receipt. + +## Superseded 1.0.0 tracker + +### 1.0.0 program tracker Governing decision: [ADR 0006](docs/decisions/0006-v1-program.md) (2026-10-17). Target: the first stable live WoW Forever build after the 4 Nov 2026 launch diff --git a/docs/STATUS.md b/docs/STATUS.md index f400d6e3..01c4b4da 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -1,5 +1,22 @@ # Project status +Updated: 2026-11-10. + +## Current program: 1.1.0 guided progression + +The approved [ADR 0011](decisions/0011-v110-guided-progression.md) supersedes +unpublished 1.0.0 preparation and requires all four usable progression workflows. +Owner and sole implementation writer: Codex `/root`, baseline `aaa73b94`, isolated +worktree `/tmp/navzeroth-v1.1-guided-progression`. Original checkout is preserved. +V110.1 records the contract; runtime implementation, current client/interface +verification, content refresh and all 1.1.0 release evidence remain pending. +See [tracker](../TODO.md), [claim](claims/2026-11-10-v110-contract.md) and +[handoff](handoffs/2026-11-10-v110-contract.md). No 1.1.0 readiness is claimed. + +## Historical 1.0.0 preparation status + +### Project status + Updated: 2026-10-24. **V22 continuation:** Codex independently reviewed PR #286's application-data diff --git a/docs/claims/2026-11-10-v110-contract.md b/docs/claims/2026-11-10-v110-contract.md new file mode 100644 index 00000000..4a758a78 --- /dev/null +++ b/docs/claims/2026-11-10-v110-contract.md @@ -0,0 +1,12 @@ +# V110.1 — release contract + +Owner and sole writer: Codex `/root`. +Baseline: protected origin/main `aaa73b94794f5a32162b430b2314f53bca4e1a7b`, +refreshed 2026-11-10. Branch: `feat/v1.1-guided-progression`. +Worktree: `/tmp/navzeroth-v1.1-guided-progression`. +Original checkout and untracked `data-generators/` remain untouched. + +Scope: ADR 0011, current tracker/status and release-contract entry points. +Acceptance: reconcile the approved 1.1.0 plan against ADRs 0008–0010; +check documentation links and whitespace. No runtime or evidence promotion. +Next task: V110.2 exact installed-client identity and compatibility admission. diff --git a/docs/decisions/0011-v110-guided-progression.md b/docs/decisions/0011-v110-guided-progression.md new file mode 100644 index 00000000..2c760f9e --- /dev/null +++ b/docs/decisions/0011-v110-guided-progression.md @@ -0,0 +1,114 @@ +# ADR 0011: 1.1.0 launch compatibility and guided progression + +Accepted 2026-11-10 by the owner's supplied implementation plan. +Baseline: `aaa73b94794f5a32162b430b2314f53bca4e1a7b`. +Task V110.1; owner and sole writer Codex `/root`. + +## Decision + +Release stable **1.1.0 directly**, superseding unpublished 1.0.0 preparation. +Extend ADR 0008's explicitly unsigned Windows installer exception and ADR 0009's +automated downloaded-draft Windows acceptance to 1.1.0. Signed content receipts +remain mandatory. Automated acceptance does not establish live gameplay, +ordinary-PC performance or human accessibility verification. Preserve historical +records and failed attempts; neither 1.0.0 receipts nor its acceptance satisfy 1.1.0. +ADR 0010's bounded hosted firewall isolation remains applicable. + +Replace the four feature deferrals in ADRs 0008/0009 with required usable workflows: + +| Workflow | Required behavior | +| --- | --- | +| Trainer spells | Prioritize eligible unlearned spells, trainers, prerequisites, known costs and budget shortfalls; unknown knowledge or affordability gives conditional advice. | +| Talents | Editable authored class/role builds and ordered next points; validate ranks, prerequisites, tiers, level budgets and respec implications. | +| Professions/crafting | Rank progression and selected output quantities; materials, known inventory subtraction and acquisition steps; preserve uncertain skill-ups, yields, cooldowns and missing sources. | +| Enhancements | Equipment compatibility, effects, acquisition/materials and permanent/temporary distinctions; numeric ranking only with structured effects and an explicit scoring model. | + +Training, Talents and Professions belong on Progression; enhancement advice belongs +on Gear. Link applicable steps to Planner, Atlas, Today and reminders. Show source origins, confidence, +conflicts and unresolved requirements beside advice. Label talent recommendations +as authored guidance. Manual completion records only +planning progress. No purchasing, talent allocation, crafting or application is +automated. Live auction pricing and combat simulation remain outside scope. + +## Exact client and content + +Recheck installed metadata (plan reports `wowf 1.60.1.70862`) and establish interface +from permitted client evidence before admitting the tuple. Do not infer interface +from a nearby build. Preserve older exact identities; no nearest-build fallback. +Refresh admitted sources and local extraction against the selected tuple, retaining +historical source builds, encryption/unavailability, conflicts and explicit unknowns. +Review later build differences; never silently retarget a candidate. + +Keep world-data v1 reference semantics. Introduce separately versioned typed facts +for spell requirements/costs, talent prerequisite/point rules, profession ranks, +recipe materials/yields and enhancement applicability/effects, each with provenance +and completeness. Empty legacy recipe lists, false cooldown flags, absent talent +prerequisites and prose effects cannot establish gameplay facts. + +Enumerate supported classes, roles, level bands, professions and records from the +refreshed catalog within levels 1–60. Require usable authored guidance across the +declared coverage of all four workflows. Do not imply every game record is known. +Include facts/guidance in inventory validation, source closure, signed bundles and +release review. Missing information never becomes zero, false or no prerequisites. + +## State and application boundaries + +Add `progression_snapshot`, payload version 1, bound to the exact character +snapshot, character, client tuple, dataset context and capture metadata. Preserve +character-snapshot and route-plan v1. Old exports remain accepted; old importers +must explicitly refuse the new kind. Collections distinguish complete, partial and +unavailable; missing companions and absent partial entries mean unknown. + +Where permitted, explicitly capture known spells/ranks and money, talent allocation +and points, profession skills/ranks and recipes, inventory quantities with bag/bank +scope, and equipped enhancements with observable temporary expiry. Capability-gate +addon capture and preserve restricted/unsupported status. Provide separate manual +inputs with manual provenance. Never execute imported Lua or create a live bridge. + +Add additive SQLite migrations for companions and saved plans. Implement pure, +deterministic Rust services, typed application/Tauri commands and generated +TypeScript contracts. Persist snapshot/content/ruleset dependencies. Changing the +selected character snapshot invalidates predecessor advice. + +## Verification and publication + +Version-aware tooling explicitly permits supported release versions and refuses +malformed/unlisted versions. Retain acceptance schema 5 and its nine observations; +extend workloads/evidence checks to all four rendered workflows, including the +independently downloaded draft Windows UI test and restart persistence. + +Required regression families: old snapshot compatibility; exact identity/build +mismatch; partial versus complete-empty; stale/false/zero; learned spells and unknown +versus zero costs; unavailable trainers and insufficient money; talent cycles/ranks/ +prerequisites/overspending/build edits; recipe cycles/overflow/rounding/unknown stock/ +uncertain skill-ups; enhancement restrictions/stacking/missing effects/expiry; +migration/backup/restore/restart/activation rollback/offline operation; Rust/Lua parity. + +Require fresh protected-main checks, per-file 90% coverage, two-platform source +parity, independent read-only review and release stability. Preserve workload limits; +diagnose failures instead of expanding bounds. Finish features/content/docs before +version freeze. Align application/addon declarations and locks to 1.1.0 using existing +generators. Archive superseded evidence, inventory actual coverage, check full packs, +record tested source/production fingerprints, commit public review and prepared +bundle identities, independently reproduce, then sign and verify fresh receipts. + +`release-build-readiness --root . --version 1.1.0` must allow preparation with only +nine pristine pending observations. Run all eight installed-app cases using published +1.0.0-rc.1 as mandatory upgrade baseline, including persistence/downgrade refusal. +Normally merge the reviewed release PR only after checks pass. Run fresh checks and +release stability on resulting main; tag that verified commit `v1.1.0`. + +Require eight passing observations bound to exact packaged installer bytes before +draft readiness. Verify complete assets, checksums, source, unsigned status, signed +content, notices and required sources. Independently download and exercise the +actual draft Windows UI/native workflows, independently review evidence and completed +GitHub provenance, then construct the external overlay without rewriting signed +resources. Relevant product/content changes invalidate affected evidence. + +Publish without another permission request only when +`release-readiness --root . --version 1.1.0 --evidence ` reports +zero blockers, stable readiness and publication allowed. Re-download and verify +public assets before updating the website/download instructions. Record URL, tag, +source, workflow attempts, asset identities, actual checks, measured resources, +limitations and next task in a publication receipt. Missing evidence holds +publication while independent work continues. This ADR itself establishes no pass. diff --git a/docs/handoffs/2026-11-10-v110-contract.md b/docs/handoffs/2026-11-10-v110-contract.md new file mode 100644 index 00000000..3bf63bc4 --- /dev/null +++ b/docs/handoffs/2026-11-10-v110-contract.md @@ -0,0 +1,43 @@ +# V110.1 — 1.1.0 contract and baseline + +Owner and sole writer: Codex `/root`. +Baseline: `aaa73b94794f5a32162b430b2314f53bca4e1a7b`. +Branch/worktree: `feat/v1.1-guided-progression`, `/tmp/navzeroth-v1.1-guided-progression`. +Claim: [V110.1](../claims/2026-11-10-v110-contract.md). + +## Implemented + +ADR 0011 records the approved direct 1.1.0 release, all four required workflows, +exact-build evidence, progression state, source/fact completeness, schema 5, +coverage/review and publication requirements. Current headers in TODO, STATUS and +both release entry points distinguish these requirements from historical 1.0.0 +preparation. Original checkout and untracked data-generators remain untouched. + +## Actual checks and evidence + +- `git fetch origin main` succeeded after sandbox Git-metadata escalation; + origin/main remains `aaa73b94`. +- `git diff --check` passed for the initial documentation changes. +- New current-contract relative links checked with Python; no missing targets + (handoff target created subsequently). +- Read-only installed `.build.info` inspection on 2026-11-10 confirms active + product `wowf`, version `1.60.1.70862`. Only product/version/active were emitted; + no personal exports or installation files were copied into Git. + +## Independent review + +Read-only reviewer `/root/review_v110_contract` found no blocking findings. +Addressed its two omissions: explicit origin/confidence labels and talent advice +labelled authored guidance. Reviewer also verified all eight current relative links +and whitespace; no runtime or release readiness was reviewed. + +## Limitations and next task + +This is contract implementation only. No application changes, new content, +release gates or publication are claimed. Runtime manifests, +versions and receipts retain their existing identities. Interface number is not +established by `.build.info`; requested exact-build permitted addon diagnostic. +Do not admit the tuple or infer its interface from an older client. + +Next: V110.2 exact tuple evidence and metadata/layout compatibility. Progression +contracts and services can proceed independently while interface evidence is pending. diff --git a/docs/releases/V1_RELEASE_PROCESS.md b/docs/releases/V1_RELEASE_PROCESS.md index b87d09d6..cfac73d4 100644 --- a/docs/releases/V1_RELEASE_PROCESS.md +++ b/docs/releases/V1_RELEASE_PROCESS.md @@ -1,4 +1,21 @@ -# Full-content v1.0.0 release process +# Full-content release process + +## Governing stable 1.1.0 contract + +[ADR 0011](../decisions/0011-v110-guided-progression.md) supersedes unpublished +1.0.0 preparation. Use version 1.1.0 only after version-aware tooling and the four +feature journeys are implemented and verified. Keep schema 5 and its nine rows, +unsigned binary disclosure and fresh signed content receipts. RC1 remains the +mandatory upgrade baseline. All protected-main, coverage, source-parity, stability, +independent review and exact downloaded-draft UI/native gates remain required. +Publish without another permission request only after zero blockers, stable readiness +and publication allowed; verify public assets before website updates. +No existing 1.0.0 evidence satisfies the new release. The detailed ADR controls where +the historical procedure below differs. + +## Superseded 1.0.0 process + +### Full-content v1.0.0 release process ## Governing stable 1.0.0 contract diff --git a/release/v1/README.md b/release/v1/README.md index 3d18fbe8..6a187d05 100644 --- a/release/v1/README.md +++ b/release/v1/README.md @@ -1,3 +1,18 @@ +# Release contract + +## Current 1.1.0 requirements + +[ADR 0011](../../docs/decisions/0011-v110-guided-progression.md) supersedes the +unpublished 1.0.0 preparation below. The unsigned installer exception and schema 5 +nine-observation automated acceptance policy apply to 1.1.0. Signed content receipts, +all four usable guided workflows, exact-build compatibility, declared level 1–60 +coverage, independent review, per-file 90% coverage and fresh release evidence are +mandatory. Existing manifests/receipts are historical 1.0.0 inputs until explicitly +regenerated; this documentation does not promote them or change the target tuple. +Follow the ADR's preparation, draft, external-overlay and publication order. + +## Superseded 1.0.0 contract + # Forever release requirements (manifest versions 1–5) ## Governing stable 1.0.0 authority From 6b4dfe51723f21161a32cbead4470539b3b1bf5c Mon Sep 17 00:00:00 2001 From: Laymer Date: Tue, 10 Nov 2026 14:28:13 +0100 Subject: [PATCH 02/10] V110.9a: validate explicit 1.1.0 website release assets --- TODO.md | 1 + docs/claims/2026-11-10-v110-site-version.md | 10 +++++ docs/handoffs/2026-11-10-v110-site-version.md | 18 +++++++++ scripts/site/release-metadata.mjs | 4 +- scripts/site/release-metadata.test.mjs | 38 +++++++++++++++++++ 5 files changed, 69 insertions(+), 2 deletions(-) create mode 100644 docs/claims/2026-11-10-v110-site-version.md create mode 100644 docs/handoffs/2026-11-10-v110-site-version.md diff --git a/TODO.md b/TODO.md index 92ad9d28..8ae8df9e 100644 --- a/TODO.md +++ b/TODO.md @@ -14,6 +14,7 @@ below do not establish 1.1.0 readiness. - [ ] V110.7 Profession/crafting quantities, materials and acquisition workflow. - [ ] V110.8 Equipment enhancement advice and integrations. - [ ] V110.9 Version-aware release tooling and four-feature acceptance journeys. + Website metadata validator supports explicit 1.1.0 (V110.9a); other tooling pending. - [ ] V110.10 Full checks/reviews, version freeze, inventory and fresh signed closure. - [ ] V110.11 Protected-main integration, stability, tag and eight-case packaging. - [ ] V110.12 Independent downloaded-draft UI acceptance, publication and receipt. diff --git a/docs/claims/2026-11-10-v110-site-version.md b/docs/claims/2026-11-10-v110-site-version.md new file mode 100644 index 00000000..281d1712 --- /dev/null +++ b/docs/claims/2026-11-10-v110-site-version.md @@ -0,0 +1,10 @@ +# V110.9a — website release metadata version validation + +Owner and sole writer: Codex `/root`; baseline `acb19140`. +Branch/worktree: `feat/v1.1-guided-progression`, `/tmp/navzeroth-v1.1-guided-progression`. +Scope: scripts/site/release-metadata.mjs and its tests. Explicitly permit 1.1.0 +while requiring the full stable asset set and independently supplied artifact +policy. Do not create a publication receipt or change website release data. +Checks: Node metadata tests, negative malformed/unlisted-version and missing-policy +cases, whitespace, independent read-only review. +Other V110.9 tooling and actual publication remain separate pending work. diff --git a/docs/handoffs/2026-11-10-v110-site-version.md b/docs/handoffs/2026-11-10-v110-site-version.md new file mode 100644 index 00000000..ba9dcd1a --- /dev/null +++ b/docs/handoffs/2026-11-10-v110-site-version.md @@ -0,0 +1,18 @@ +# V110.9a — explicit 1.1.0 website asset validation + +Owner/sole writer Codex `/root`; baseline `acb19140`; branch +`feat/v1.1-guided-progression`. Claim: `docs/claims/2026-11-10-v110-site-version.md`. + +Validator explicitly permits 1.1.0 and requires all eight stable assets plus a +matching artifact policy. Malformed/unlisted versions remain refused even with a +matching policy. Website data, artifact policy and publication receipts are unchanged. + +Actual checks on Node v24.19.0: focused test file passed; experimental Node coverage +reported 100% lines/functions and 90.91% branches for release-metadata.mjs. +`git diff --check` passed. Read-only independent reviewer +`/root/review_v110_contract` reported no blockers and reran tests/whitespace checks. +These are synthetic validator checks, not actual asset or release verification. + +Remaining V110.9 work: Windows acceptance, evidence import, inventory generation, +bundle tooling and all four feature journeys. No 1.1.0 readiness claim. +Next independent task: V110.4a progression observation completeness and bindings. diff --git a/scripts/site/release-metadata.mjs b/scripts/site/release-metadata.mjs index 8c4685f6..635961b2 100644 --- a/scripts/site/release-metadata.mjs +++ b/scripts/site/release-metadata.mjs @@ -4,7 +4,7 @@ import assert from 'node:assert/strict'; // tooling change; publication of the already-supported stable needs only site data. export function validateRelease(release, policy) { assert.equal(release.schema_version, 1); - assert.ok(['1.0.0-rc.1', '1.0.0'].includes(release.version)); + assert.ok(['1.0.0-rc.1', '1.0.0', '1.1.0'].includes(release.version)); const allowed = policy.releases.find(row => row.version === release.version); assert.equal(policy.schema_version, 1); assert.ok(allowed, 'Release needs an explicit source-bound artifact policy'); @@ -17,7 +17,7 @@ export function validateRelease(release, policy) { assert.match(release.application_sha256, /^[a-f0-9]{64}$/); assert.match(release.public_verification_run_id, /^\d+$/); const names = [`AzerothNavigator-${release.version}-x64-setup.exe`, `AzerothNavigator-addon-${release.version}.zip`, 'CANDIDATE_NOTES.md', 'SHA256SUMS.txt', 'SOURCE_COMMIT.txt']; - if (release.version === '1.0.0') names.push(`AzerothNavigator-materials-${release.version}.zip`, 'RELEASE_MATERIALS.json', 'RELEASE_ASSETS.json'); + if (['1.0.0', '1.1.0'].includes(release.version)) names.push(`AzerothNavigator-materials-${release.version}.zip`, 'RELEASE_MATERIALS.json', 'RELEASE_ASSETS.json'); assert.deepEqual(release.assets.map(asset => asset.name).sort(), names.sort()); for (const asset of release.assets) { assert.ok(Number.isSafeInteger(asset.bytes) && asset.bytes > 0); diff --git a/scripts/site/release-metadata.test.mjs b/scripts/site/release-metadata.test.mjs index 0e4f43f8..c615d8fd 100644 --- a/scripts/site/release-metadata.test.mjs +++ b/scripts/site/release-metadata.test.mjs @@ -36,3 +36,41 @@ test('a historical RC capture cannot be relabelled as current stable', async () assert.throws(() => validateCaptureCaption('Actual 1.0.0-rc.1 Windows app, synthetic fixture.', stable, stable)); assert.throws(() => validateCaptureCaption('Historical 1.0.0-rc.1 Windows app.', stable, rc)); }); + +for (const version of ['1.0.0', '1.1.0']) { + test(`${version} requires all stable assets and an explicit matching policy`, () => { + const stable = clone(rc); + stable.version = version; + stable.tag = `v${version}`; + stable.prerelease = false; + stable.assets = rc.assets.map(asset => ({ + ...asset, + name: asset.name.replaceAll(rc.version, version), + url: asset.url.replaceAll(rc.version, version), + })); + for (const name of [`AzerothNavigator-materials-${version}.zip`, 'RELEASE_MATERIALS.json', 'RELEASE_ASSETS.json']) { + stable.assets.push({ name, bytes: 1, sha256: 'a'.repeat(64), url: `https://github.com/Laymer/Navzeroth/releases/download/${stable.tag}/${name}` }); + } + // Synthetic policy authorizes validation only; it is not published evidence. + const permitted = clone(policy); + permitted.releases = [{ ...policy.releases.find(row => row.version === '1.0.0'), version }]; + assert.equal(validateRelease(stable, permitted), stable); + assert.throws(() => validateRelease(stable, { ...permitted, releases: [] }), /explicit source-bound artifact policy/); + for (const asset of stable.assets) { + const missing = clone(stable); + missing.assets = missing.assets.filter(row => row.name !== asset.name); + assert.throws(() => validateRelease(missing, permitted)); + } + const stale = clone(stable); + stale.assets[0].url = rc.assets[0].url; + assert.throws(() => validateRelease(stale, permitted)); + }); +} + +test('even a matching policy cannot admit malformed or unlisted versions', () => { + for (const version of ['1.1.1', '1.2.0', 'v1.1.0', '01.1.0', '1.1.0-rc.1', '1.1.0+build', '1.1.0\n', null]) { + const release = { ...clone(rc), version, tag: `v${version}` }; + const matching = { ...clone(policy), releases: [{ version, prerelease: true, signature: 'unsigned' }] }; + assert.throws(() => validateRelease(release, matching)); + } +}); From bf332bea82aaa4900da0a7f720327badfd510dd8 Mon Sep 17 00:00:00 2001 From: Laymer Date: Tue, 10 Nov 2026 14:31:18 +0100 Subject: [PATCH 03/10] V110.4a: preserve progression observation completeness and binding --- TODO.md | 1 + crates/core/src/lib.rs | 1 + crates/core/src/progression/mod.rs | 109 +++++++++++ crates/core/tests/progression_state.rs | 182 ++++++++++++++++++ docs/STATUS.md | 8 +- .../2026-11-10-v110-progression-state.md | 8 + .../2026-11-10-v110-progression-state.md | 42 ++++ 7 files changed, 349 insertions(+), 2 deletions(-) create mode 100644 crates/core/src/progression/mod.rs create mode 100644 crates/core/tests/progression_state.rs create mode 100644 docs/claims/2026-11-10-v110-progression-state.md create mode 100644 docs/handoffs/2026-11-10-v110-progression-state.md diff --git a/TODO.md b/TODO.md index 8ae8df9e..ec4d0b56 100644 --- a/TODO.md +++ b/TODO.md @@ -9,6 +9,7 @@ below do not establish 1.1.0 readiness. - [ ] V110.2 Verify installed tuple/interface and exact-build compatibility. - [ ] V110.3 Regenerate/review content; version gameplay facts and enforce coverage. - [ ] V110.4 Progression exchange, explicit addon/manual capture and persistence. + V110.4a pure collection/binding foundation implemented and checked; integration pending. - [ ] V110.5 Trainer spell service, saved plans and rendered workflow. - [ ] V110.6 Authored editable talents, validation and next-point workflow. - [ ] V110.7 Profession/crafting quantities, materials and acquisition workflow. diff --git a/crates/core/src/lib.rs b/crates/core/src/lib.rs index b7b686fb..883a840a 100644 --- a/crates/core/src/lib.rs +++ b/crates/core/src/lib.rs @@ -16,6 +16,7 @@ pub mod observation; pub mod origin_policy; pub mod planner; pub mod predicate; +pub mod progression; pub mod release; pub mod reminders; pub mod selection_path; diff --git a/crates/core/src/progression/mod.rs b/crates/core/src/progression/mod.rs new file mode 100644 index 00000000..eebffa4e --- /dev/null +++ b/crates/core/src/progression/mod.rs @@ -0,0 +1,109 @@ +//! Pure progression state primitives. Imported and manual observations retain +//! their own metadata; neither lookup nor binding changes observed game state. +use crate::{ + entities::CharacterSnapshot, + error::{Result, invalid}, + observation::{ + Freshness, FreshnessContext, Observation, ObservationMetadata, ObservationStatus, freshness, + }, + types::{ + CharacterId, DataContext, DatasetRevision, RecordMap, Sha256Hex, SnapshotId, SourceId, + }, +}; +use schemars::JsonSchema; +use serde::{Deserialize, Serialize}; + +#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] +#[serde(rename_all = "snake_case")] +pub enum Completeness { + Complete, + Partial, +} + +/// Availability and capture metadata live on the enclosing Observation. An +/// unavailable enumeration is never represented as an empty complete map. +#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, JsonSchema)] +#[serde(deny_unknown_fields)] +pub struct Enumeration { + pub completeness: Completeness, + pub entries: RecordMap, +} + +#[derive(Clone, Debug, PartialEq)] +pub enum Lookup<'a, T> { + Present(&'a T), + Absent, + Unknown, + Unavailable(ObservationStatus), + NotFresh(Freshness), +} + +/// Missing companions/partial entries cannot prove absence. Even a complete +/// enumeration cannot establish current absence if its time is stale/uncertain. +pub fn lookup<'a, T>( + observation: Option<&'a Observation>>, + key: &SourceId, + time: &FreshnessContext, +) -> Lookup<'a, T> { + let Some(observation) = observation else { + return Lookup::Unknown; + }; + let Some(enumeration) = observation.value() else { + return Lookup::Unavailable(observation.status()); + }; + let age = freshness(observation.metadata(), time); + if !matches!(age, Freshness::Fresh { .. }) { + return Lookup::NotFresh(age); + } + match enumeration.entries.get(key) { + Some(value) => Lookup::Present(value), + None if enumeration.completeness == Completeness::Complete => Lookup::Absent, + None => Lookup::Unknown, + } +} + +/// Exact predecessor identity for progression companions and saved advice. +/// The I/O layer supplies the persisted snapshot hash; this module does not hash +/// or normalize imported bytes and never accepts a nearest-build substitution. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] +#[serde(deny_unknown_fields)] +pub struct SnapshotBinding { + pub snapshot: SnapshotId, + pub character: CharacterId, + pub context: DataContext, + pub source_revision: DatasetRevision, + pub capture: ObservationMetadata, + pub snapshot_sha256: Sha256Hex, +} + +impl SnapshotBinding { + pub fn from_snapshot(snapshot: &CharacterSnapshot, snapshot_sha256: Sha256Hex) -> Self { + Self { + snapshot: snapshot.id.clone(), + character: snapshot.character.clone(), + context: snapshot.context.clone(), + source_revision: snapshot.source_revision.clone(), + capture: snapshot.capture.clone(), + snapshot_sha256, + } + } + + pub fn ensure_matches( + &self, + snapshot: &CharacterSnapshot, + snapshot_sha256: &Sha256Hex, + ) -> Result<()> { + self.context.ensure_compatible(&snapshot.context)?; + if self.snapshot != snapshot.id + || self.character != snapshot.character + || self.source_revision != snapshot.source_revision + || self.capture != snapshot.capture + || &self.snapshot_sha256 != snapshot_sha256 + { + return Err(invalid( + "Progression state belongs to a different character snapshot", + )); + } + Ok(()) + } +} diff --git a/crates/core/tests/progression_state.rs b/crates/core/tests/progression_state.rs new file mode 100644 index 00000000..bd73f7be --- /dev/null +++ b/crates/core/tests/progression_state.rs @@ -0,0 +1,182 @@ +use azeroth_core::{ + entities::CharacterSnapshot, + observation::{ + ClockTrust, Freshness, FreshnessContext, Observation, ObservationMetadata, + ObservationStatus, StateSource, + }, + progression::{Completeness, Enumeration, Lookup, SnapshotBinding, lookup}, + types::{Millis, RecordMap, Sha256Hex, SourceId, UtcMillis}, +}; +use serde_json::json; + +fn time() -> FreshnessContext { + FreshnessContext { + now_utc_ms: Some(UtcMillis::new(100).unwrap()), + clock_trust: ClockTrust::Trusted, + session: None, + max_age_ms: Millis::new(10).unwrap(), + } +} +fn metadata() -> ObservationMetadata { + ObservationMetadata { + observed_at_utc_ms: Some(UtcMillis::new(100).unwrap()), + clock_trust: ClockTrust::Trusted, + source: StateSource::ManualEntry, + ..Default::default() + } +} +fn enumeration( + completeness: Completeness, + entries: &[(&str, u32)], +) -> Observation> { + Observation::known( + Enumeration { + completeness, + entries: RecordMap::new( + entries + .iter() + .map(|(id, value)| (SourceId::new(*id).unwrap(), *value)), + ) + .unwrap(), + }, + metadata(), + ) + .unwrap() +} + +#[test] +fn absence_requires_complete_fresh_enumeration() { + let key = SourceId::new("spell-1").unwrap(); + assert_eq!(lookup::(None, &key, &time()), Lookup::Unknown); + for completeness in [Completeness::Partial, Completeness::Complete] { + let empty = enumeration(completeness, &[]); + assert_eq!( + lookup(Some(&empty), &key, &time()), + if completeness == Completeness::Complete { + Lookup::Absent + } else { + Lookup::Unknown + } + ); + let zero = enumeration(completeness, &[("spell-1", 0)]); + assert_eq!(lookup(Some(&zero), &key, &time()), Lookup::Present(&0)); + let mut stale = time(); + stale.now_utc_ms = Some(UtcMillis::new(111).unwrap()); + assert!(matches!( + lookup(Some(&empty), &key, &stale), + Lookup::NotFresh(Freshness::Stale { .. }) + )); + assert!(matches!( + lookup(Some(&zero), &key, &stale), + Lookup::NotFresh(Freshness::Stale { .. }) + )); + let mut uncertain = time(); + uncertain.clock_trust = ClockTrust::Uncertain; + assert!(matches!( + lookup(Some(&empty), &key, &uncertain), + Lookup::NotFresh(Freshness::Uncertain { .. }) + )); + let mut boundary = time(); + boundary.now_utc_ms = Some(UtcMillis::new(110).unwrap()); + assert_eq!(lookup(Some(&zero), &key, &boundary), Lookup::Present(&0)); + } +} + +#[test] +fn availability_and_false_are_preserved() { + let key = SourceId::new("recipe-1").unwrap(); + for status in [ + ObservationStatus::Unknown, + ObservationStatus::Unsupported, + ObservationStatus::Restricted, + ObservationStatus::NotApplicable, + ] { + let value = Observation::>::unavailable(status, metadata()).unwrap(); + assert_eq!( + lookup(Some(&value), &key, &time()), + Lookup::Unavailable(status) + ); + let roundtrip: Observation> = + serde_json::from_str(&serde_json::to_string(&value).unwrap()).unwrap(); + assert_eq!(roundtrip, value); + } + let value = Observation::known( + Enumeration { + completeness: Completeness::Complete, + entries: RecordMap::new([(key.clone(), false)]).unwrap(), + }, + metadata(), + ) + .unwrap(); + assert_eq!(lookup(Some(&value), &key, &time()), Lookup::Present(&false)); + assert_eq!(value.metadata().source, StateSource::ManualEntry); +} + +#[test] +fn collection_wire_requires_completeness_and_bounded_unique_keys() { + for bad in [ + r#"{"entries":{}}"#, + r#"{"completeness":"unavailable","entries":{}}"#, + r#"{"completeness":"complete","entries":{"s":0,"s":1}}"#, + r#"{"completeness":"complete","entries":{},"assumed":true}"#, + ] { + assert!(serde_json::from_str::>(bad).is_err()); + } + let entries = (0..1025) + .map(|i| (i.to_string(), json!(0))) + .collect::>(); + assert!( + serde_json::from_value::>( + json!({"completeness":"complete","entries":entries}) + ) + .is_err() + ); + assert!( + serde_json::from_value::>>( + json!({"status":"restricted","value":{"completeness":"complete","entries":{}}}) + ) + .is_err() + ); +} + +fn snapshot() -> CharacterSnapshot { + serde_json::from_value(json!({ + "schema_version":1,"id":"snapshot-1","character":"character-1", + "context":{"build":{"edition":"wow_forever","build":"SYNTHETIC","interface":"SYNTHETIC"},"namespace":"demo"}, + "capture":{},"source_revision":"fixture-v1","level":{"status":"unknown"},"role":{"status":"unknown"},"location":{"status":"unknown"},"preferences":{},"equipment":{},"quests":{},"objectives":{} + })).unwrap() +} + +#[test] +fn binding_rejects_every_changed_dependency() { + let snapshot = snapshot(); + let digest = Sha256Hex::new("a".repeat(64)).unwrap(); + let binding = SnapshotBinding::from_snapshot(&snapshot, digest.clone()); + binding.ensure_matches(&snapshot, &digest).unwrap(); + let roundtrip: SnapshotBinding = + serde_json::from_str(&serde_json::to_string(&binding).unwrap()).unwrap(); + assert_eq!(binding, roundtrip); + assert!( + binding + .ensure_matches(&snapshot, &Sha256Hex::new("b".repeat(64)).unwrap()) + .is_err() + ); + for (pointer, value) in [ + ("/id", json!("snapshot-2")), + ("/character", json!("character-2")), + ("/source_revision", json!("fixture-v2")), + ("/capture/source", json!("manual_entry")), + ("/context/build/edition", json!("wow_classic")), + ("/context/build/build", json!("OTHER")), + ("/context/build/interface", json!("OTHER")), + ("/context/namespace", json!("reference")), + ] { + let mut changed = serde_json::to_value(&snapshot).unwrap(); + *changed.pointer_mut(pointer).unwrap() = value; + let changed: CharacterSnapshot = serde_json::from_value(changed).unwrap(); + assert!( + binding.ensure_matches(&changed, &digest).is_err(), + "{pointer}" + ); + } +} diff --git a/docs/STATUS.md b/docs/STATUS.md index 01c4b4da..71c3c75e 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -8,8 +8,12 @@ The approved [ADR 0011](decisions/0011-v110-guided-progression.md) supersedes unpublished 1.0.0 preparation and requires all four usable progression workflows. Owner and sole implementation writer: Codex `/root`, baseline `aaa73b94`, isolated worktree `/tmp/navzeroth-v1.1-guided-progression`. Original checkout is preserved. -V110.1 records the contract; runtime implementation, current client/interface -verification, content refresh and all 1.1.0 release evidence remain pending. +V110.1 records the contract. V110.9a adds explicit 1.1.0 website asset validation; +V110.4a adds tested pure progression collection/binding primitives. See the +[state handoff](handoffs/2026-11-10-v110-progression-state.md) and +[validator handoff](handoffs/2026-11-10-v110-site-version.md). Installed metadata +confirms active wowf 1.60.1.70862; interface evidence is pending. Exchange/storage/UI, +content refresh and all 1.1.0 release evidence remain pending. See [tracker](../TODO.md), [claim](claims/2026-11-10-v110-contract.md) and [handoff](handoffs/2026-11-10-v110-contract.md). No 1.1.0 readiness is claimed. diff --git a/docs/claims/2026-11-10-v110-progression-state.md b/docs/claims/2026-11-10-v110-progression-state.md new file mode 100644 index 00000000..18a2ccf1 --- /dev/null +++ b/docs/claims/2026-11-10-v110-progression-state.md @@ -0,0 +1,8 @@ +# V110.4a — progression observation semantics + +Owner/sole writer Codex `/root`; baseline `6b4dfe51`. +Branch/worktree: `feat/v1.1-guided-progression`, `/tmp/navzeroth-v1.1-guided-progression`. +Scope: pure core progression collection lookup and exact predecessor binding, +with focused tests. Reuse bounded RecordMap, Observation and existing freshness. +No exchange kind, persistence or UI is claimed by this foundational subtask. +Checks: focused Rust tests, formatting, Clippy, independent read-only review. diff --git a/docs/handoffs/2026-11-10-v110-progression-state.md b/docs/handoffs/2026-11-10-v110-progression-state.md new file mode 100644 index 00000000..38419795 --- /dev/null +++ b/docs/handoffs/2026-11-10-v110-progression-state.md @@ -0,0 +1,42 @@ +# V110.4a — progression observation foundation + +Owner/sole writer Codex `/root`; baseline `6b4dfe51`; isolated branch +`feat/v1.1-guided-progression`. Claim: `docs/claims/2026-11-10-v110-progression-state.md`. + +## Implemented + +Pure core collection lookup preserves complete/partial/unavailable, missing companion, +stale/uncertain time, false and zero. Absence is established only by a fresh complete +collection. Existing Observation metadata preserves manual/addon provenance; +RecordMap provides duplicate and 1024-entry refusal. SnapshotBinding checks exact +snapshot/character/context/source revision/capture metadata and supplied persisted +snapshot SHA-256. Old exchange schemas and snapshot types are unchanged. + +## Actual checks + +- `cargo test --locked -p azeroth-core --test progression_state`: 4 passed. +- `cargo test --locked -p azeroth-core`: passed; existing ignored fixture generator + and whole-world LFS workload remain ignored, not verified by this run. +- `cargo clippy --locked -p azeroth-core --all-targets -- -D warnings`: passed. +- `cargo fmt --all --check` and `git diff --check`: passed. +- `cargo llvm-cov --locked -p azeroth-core --test progression_state --json`: + progression/mod.rs 44/45 covered lines (97.78%), 3/3 functions. This is focused + module coverage, not the repository-wide release coverage gate. +- Read-only reviewer `/root/review_v110_contract`: no blockers; independently ran + generated focused executable (4 passed) and whitespace check, did not rebuild. + +Cargo was absent from shell PATH; successful commands used +`/home/laymer/.cargo/bin/cargo`. Initial PATH failures are not test failures. + +## Limitations and next task + +This foundation is not yet consumed by application services. Callers must obtain +SHA-256 from the selected persisted snapshot and enforce binding before lookup; +never trust a companion's self-declared digest as the selected snapshot identity. +No progression exchange, migrations, capture, saved plans, generated frontend +contracts or usable workflows are claimed. No live verification or release gate +promotion. Exact 70862 interface evidence remains pending. + +Next: V110.4b versioned companion payload with bounded decoding and old-import +compatibility, then storage/manual inputs; V110.3 gameplay facts/content can proceed +independently. Complete all tracker items before candidate preparation/publication. From 9e1158e0331562390701669267442bc510f7f6b9 Mon Sep 17 00:00:00 2001 From: Laymer Date: Tue, 10 Nov 2026 14:47:54 +0100 Subject: [PATCH 04/10] V110.4b: add versioned progression snapshot exchange --- TODO.md | 3 +- crates/core/src/contract/mod.rs | 18 +- crates/core/src/contract/progression.rs | 34 + crates/core/src/contract/schema.rs | 3 +- crates/core/src/progression/mod.rs | 3 + crates/core/src/progression/snapshot.rs | 117 + crates/core/tests/progression_exchange.rs | 181 ++ crates/ingest/src/import.rs | 3 + crates/ingest/tests/anav1.rs | 2 +- crates/ingest/tests/import.rs | 39 + docs/STATUS.md | 4 +- .../2026-11-10-v110-progression-exchange.md | 11 + .../2026-11-10-v110-progression-exchange.md | 46 + fixtures/contracts/v1/manifest.json | 6 + .../contracts/v1/progression-snapshot.json | 113 + schemas/v1/README.md | 51 +- schemas/v1/exchange.schema.json | 2028 ++++++++++++++++- schemas/v1/exchange.ts | 1262 +++++++--- tests/contract/check.mts | 6 + 19 files changed, 3505 insertions(+), 425 deletions(-) create mode 100644 crates/core/src/contract/progression.rs create mode 100644 crates/core/src/progression/snapshot.rs create mode 100644 crates/core/tests/progression_exchange.rs create mode 100644 docs/claims/2026-11-10-v110-progression-exchange.md create mode 100644 docs/handoffs/2026-11-10-v110-progression-exchange.md create mode 100644 fixtures/contracts/v1/progression-snapshot.json diff --git a/TODO.md b/TODO.md index ec4d0b56..7434ad51 100644 --- a/TODO.md +++ b/TODO.md @@ -9,7 +9,8 @@ below do not establish 1.1.0 readiness. - [ ] V110.2 Verify installed tuple/interface and exact-build compatibility. - [ ] V110.3 Regenerate/review content; version gameplay facts and enforce coverage. - [ ] V110.4 Progression exchange, explicit addon/manual capture and persistence. - V110.4a pure collection/binding foundation implemented and checked; integration pending. + V110.4a collection/binding and V110.4b versioned exchange implemented and checked; + storage/application/addon integration pending. - [ ] V110.5 Trainer spell service, saved plans and rendered workflow. - [ ] V110.6 Authored editable talents, validation and next-point workflow. - [ ] V110.7 Profession/crafting quantities, materials and acquisition workflow. diff --git a/crates/core/src/contract/mod.rs b/crates/core/src/contract/mod.rs index d03790a5..88992ca2 100644 --- a/crates/core/src/contract/mod.rs +++ b/crates/core/src/contract/mod.rs @@ -14,6 +14,7 @@ mod dataset; mod evidence; mod gear; mod plan; +mod progression; pub mod schema; mod snapshot; pub use dataset::*; @@ -35,6 +36,7 @@ pub const MAX_EXTENSIONS: usize = 64; #[serde(rename_all = "snake_case")] pub enum ContractKind { CharacterSnapshot, + ProgressionSnapshot, PartySnapshot, RoutePlan, EvidenceBundle, @@ -42,8 +44,9 @@ pub enum ContractKind { GearRecommendations, } impl ContractKind { - pub const ALL: [Self; 6] = [ + pub const ALL: [Self; 7] = [ Self::CharacterSnapshot, + Self::ProgressionSnapshot, Self::PartySnapshot, Self::RoutePlan, Self::EvidenceBundle, @@ -53,6 +56,7 @@ impl ContractKind { pub fn as_str(self) -> &'static str { match self { Self::CharacterSnapshot => "character_snapshot", + Self::ProgressionSnapshot => "progression_snapshot", Self::PartySnapshot => "party_snapshot", Self::RoutePlan => "route_plan", Self::EvidenceBundle => "evidence_bundle", @@ -70,9 +74,10 @@ impl ContractKind { /// parser's recursion limit and the rule limits of their records. pub fn max_json_depth(self) -> Option { match self { - Self::CharacterSnapshot | Self::PartySnapshot | Self::RoutePlan => { - Some(MAX_ADDON_JSON_DEPTH) - } + Self::CharacterSnapshot + | Self::ProgressionSnapshot + | Self::PartySnapshot + | Self::RoutePlan => Some(MAX_ADDON_JSON_DEPTH), _ => None, } } @@ -577,6 +582,7 @@ fn decode_checked(input: &str) -> Result> { #[derive(Clone, Debug, PartialEq, Serialize)] #[serde(untagged)] pub enum AnyExchange { + ProgressionSnapshot(Box>), CharacterSnapshot(Box>), PartySnapshot(Box>), RoutePlan(Box>), @@ -587,6 +593,7 @@ pub enum AnyExchange { impl AnyExchange { pub fn kind(&self) -> ContractKind { match self { + Self::ProgressionSnapshot(_) => ContractKind::ProgressionSnapshot, Self::CharacterSnapshot(_) => ContractKind::CharacterSnapshot, Self::PartySnapshot(_) => ContractKind::PartySnapshot, Self::RoutePlan(_) => ContractKind::RoutePlan, @@ -608,6 +615,9 @@ pub fn decode_any(input: &str) -> Result { )); } Ok(match kind { + ContractKind::ProgressionSnapshot => { + AnyExchange::ProgressionSnapshot(Box::new(decode_checked(input)?)) + } ContractKind::CharacterSnapshot => { AnyExchange::CharacterSnapshot(Box::new(decode_checked(input)?)) } diff --git a/crates/core/src/contract/progression.rs b/crates/core/src/contract/progression.rs new file mode 100644 index 00000000..2330e02e --- /dev/null +++ b/crates/core/src/contract/progression.rs @@ -0,0 +1,34 @@ +//! Progression companions retain exact predecessor dependencies. +use super::{ContractKind, EnvelopeHeader, Payload, same_context}; +use crate::{ + error::{Result, invalid}, + progression::ProgressionSnapshot, +}; + +impl Payload for ProgressionSnapshot { + const KIND: ContractKind = ContractKind::ProgressionSnapshot; + fn validate_payload(&self, header: &EnvelopeHeader) -> Result<()> { + same_context(header, &self.binding.context)?; + let deps = header.dependencies; + if deps.dataset_revision.as_ref() != Some(&self.binding.source_revision) + || deps.ruleset_version.is_some() + || deps.score_model_version.is_some() + || deps.snapshots.len() != 1 + || deps.snapshots[0].id != self.binding.snapshot + || deps.snapshots[0].character != self.binding.character + || deps.snapshots[0].context != self.binding.context + { + return Err(invalid( + "Progression dependencies disagree with its snapshot binding", + )); + } + if header.producer.session_id != self.capture.session_id + || header.producer.sequence != self.capture.sequence + { + return Err(invalid( + "Progression producer and capture identity disagree", + )); + } + Ok(()) + } +} diff --git a/crates/core/src/contract/schema.rs b/crates/core/src/contract/schema.rs index 734c8be0..cee91c18 100644 --- a/crates/core/src/contract/schema.rs +++ b/crates/core/src/contract/schema.rs @@ -6,7 +6,7 @@ use serde_json::{Value, json}; pub const SCHEMA_ID: &str = "https://github.com/Laymer/Navzeroth/schemas/v1/exchange.schema.json"; -/// The complete exchange schema: a root `oneOf` over the six envelope kinds +/// The complete exchange schema: a root `oneOf` over the supported envelope kinds /// with shared `$defs`. Output is deterministic (sorted definitions). /// Rust validation remains authoritative for semantic invariants. pub fn exchange_schema() -> Value { @@ -14,6 +14,7 @@ pub fn exchange_schema() -> Value { .for_deserialize() .into_generator(); let roots = [ + generator.subschema_for::>(), generator.subschema_for::>(), generator.subschema_for::>(), generator.subschema_for::>(), diff --git a/crates/core/src/progression/mod.rs b/crates/core/src/progression/mod.rs index eebffa4e..20b2abb5 100644 --- a/crates/core/src/progression/mod.rs +++ b/crates/core/src/progression/mod.rs @@ -107,3 +107,6 @@ impl SnapshotBinding { Ok(()) } } + +mod snapshot; +pub use snapshot::*; diff --git a/crates/core/src/progression/snapshot.rs b/crates/core/src/progression/snapshot.rs new file mode 100644 index 00000000..3fbee383 --- /dev/null +++ b/crates/core/src/progression/snapshot.rs @@ -0,0 +1,117 @@ +//! Companion observations, not gameplay facts or inferred player state. +use super::{Enumeration, SnapshotBinding}; +use crate::{ + error::{Result, Validate, Validated, invalid}, + observation::{Observation, ObservationMetadata}, + types::*, +}; +use schemars::JsonSchema; +use serde::{Deserialize, Serialize}; +use std::collections::BTreeSet; + +#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, JsonSchema)] +#[serde(deny_unknown_fields)] +pub struct ProfessionState { + pub skill: Observation, + pub maximum_skill: Observation, + pub rank: Observation, +} + +#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, JsonSchema)] +#[serde(deny_unknown_fields)] +pub struct InventoryQuantity { + pub item: ItemKey, + /// Aggregated quantity within this one explicit scope. Never a bag index. + pub quantity: Observation, +} + +#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] +#[serde(rename_all = "snake_case")] +pub enum EnhancementDuration { + Permanent, + Temporary, +} + +#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, JsonSchema)] +#[serde(deny_unknown_fields)] +pub struct ObservedEnhancement { + pub duration: Observation, + /// Unreadable expiry remains unknown/restricted; no inferred duration. + pub expires_at_utc_ms: Observation, +} + +#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, JsonSchema)] +#[serde(deny_unknown_fields)] +pub struct EquipmentEnhancements { + pub item: ItemKey, + pub enhancements: Observation>, +} + +#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, JsonSchema)] +#[serde(deny_unknown_fields)] +#[schemars(rename = "ProgressionSnapshot")] +pub struct ProgressionSnapshotData { + pub payload_version: SchemaVersion, + pub id: SnapshotId, + pub binding: SnapshotBinding, + pub capture: ObservationMetadata, + /// Keys identify exact source spell records; unknown rank is not rank zero. + pub spells: Observation>>, + pub money: Observation, + pub talents: Observation>>, + pub available_talent_points: Observation, + pub professions: Observation>, + pub recipes: Observation>>, + /// Bags and bank are separate enumerations and never silently combined. + pub bags: Observation>, + pub bank: Observation>, + pub equipment_enhancements: RecordMap>, +} +pub type ProgressionSnapshot = Validated; + +impl Validate for ProgressionSnapshotData { + fn validate(&self) -> Result<()> { + self.capture.validate()?; + self.binding.capture.validate()?; + if let Some(professions) = self.professions.value() { + for profession in professions.entries.values() { + if let (Some(skill), Some(maximum)) = + (profession.skill.value(), profession.maximum_skill.value()) + && skill > maximum + { + return Err(invalid("Profession skill exceeds its observed maximum")); + } + } + } + for inventory in [&self.bags, &self.bank] { + if let Some(inventory) = inventory.value() { + let mut items = BTreeSet::new(); + for entry in inventory.entries.values() { + self.binding + .context + .ensure_compatible(&entry.item.context)?; + if !items.insert(&entry.item) { + return Err(invalid( + "Inventory scope repeats an aggregated item identity", + )); + } + } + } + } + for slot in self.equipment_enhancements.values() { + if let Some(slot) = slot.value() { + self.binding.context.ensure_compatible(&slot.item.context)?; + if let Some(effects) = slot.enhancements.value() { + for effect in effects.entries.values() { + if effect.duration.value() == Some(&EnhancementDuration::Permanent) + && effect.expires_at_utc_ms.value().is_some() + { + return Err(invalid("Permanent enhancement cannot declare an expiry")); + } + } + } + } + } + Ok(()) + } +} diff --git a/crates/core/tests/progression_exchange.rs b/crates/core/tests/progression_exchange.rs new file mode 100644 index 00000000..fc313508 --- /dev/null +++ b/crates/core/tests/progression_exchange.rs @@ -0,0 +1,181 @@ +use azeroth_core::{ + contract::{AnyExchange, ContractKind, MAX_ENVELOPE_BYTES, decode_any, decode_envelope}, + entities::CharacterSnapshot, + error::ErrorCode, + progression::ProgressionSnapshot, +}; +use serde_json::{Value, json}; +fn fixture() -> Value { + serde_json::from_str(include_str!( + "../../../fixtures/contracts/v1/progression-snapshot.json" + )) + .unwrap() +} +fn decode( + value: &Value, +) -> azeroth_core::error::Result> { + decode_envelope(&value.to_string()) +} +fn item() -> Value { + json!({"context": fixture()["payload"]["binding"]["context"], "item_id":"synthetic-item","variant":"base"}) +} +fn known(value: Value) -> Value { + json!({"status":"known","value":value}) +} +fn entries(value: Value) -> Value { + known(json!({"completeness":"complete","entries":value})) +} + +#[test] +fn companion_roundtrip_and_old_typed_decoder_refusal() { + let original = fixture(); + let parsed = decode(&original).unwrap(); + let encoded = serde_json::to_string(&parsed).unwrap(); + let any = decode_any(&encoded).unwrap(); + assert_eq!(any.kind(), ContractKind::ProgressionSnapshot); + assert!(matches!(any, AnyExchange::ProgressionSnapshot(_))); + assert_eq!( + decode_envelope::(&encoded).unwrap(), + parsed + ); + assert!(decode_envelope::(&encoded).is_err()); + assert_eq!(parsed.payload.money.value().unwrap().get(), 0); + assert_eq!(parsed.payload.available_talent_points.value(), Some(&0)); + assert_eq!( + parsed + .payload + .recipes + .value() + .unwrap() + .entries + .values() + .next() + .unwrap() + .value(), + Some(&false) + ); +} + +#[test] +fn dependencies_and_capture_must_match_exactly() { + for (pointer, value) in [ + ("/dependencies/dataset_revision", json!("other")), + ("/dependencies/snapshots/0/id", json!("other")), + ("/dependencies/snapshots/0/character", json!("other")), + ( + "/dependencies/snapshots/0/context/build/interface", + json!("other"), + ), + ("/dependencies/snapshots", json!([])), + ("/game/build", json!("other")), + ("/producer/session_id", json!("other")), + ("/producer/sequence", json!(999)), + ("/payload/payload_version", json!(2)), + ("/payload/binding/snapshot_sha256", json!("bad")), + ] { + let mut altered = fixture(); + *altered.pointer_mut(pointer).unwrap() = value; + assert!(decode(&altered).is_err(), "{pointer}"); + } + for field in ["ruleset_version", "score_model_version"] { + let mut altered = fixture(); + altered["dependencies"][field] = json!("unexpected"); + assert!(decode(&altered).is_err()); + } + for pointer in ["/payload/capture", "/payload/binding/capture"] { + let mut altered = fixture(); + *altered.pointer_mut(pointer).unwrap() = json!({"sequence":1}); + assert!(decode(&altered).is_err()); + } + let mut changed = fixture(); + changed["payload"]["unexpected"] = json!(true); + assert!(decode(&changed).is_err()); + let mut missing = fixture(); + missing["payload"].as_object_mut().unwrap().remove("spells"); + assert!(decode(&missing).is_err()); +} + +#[test] +fn scoped_inventory_professions_and_effects_preserve_uncertainty() { + let mut value = fixture(); + value["payload"]["professions"] = entries( + json!({"profession": {"skill":known(json!(0)),"maximum_skill":known(json!(0)),"rank":{"status":"unknown"}}}), + ); + let entry = json!({"item":item(),"quantity":known(json!(0))}); + value["payload"]["bags"] = entries(json!({"item":entry})); + value["payload"]["bank"] = value["payload"]["bags"].clone(); + value["payload"]["equipment_enhancements"] = json!({"main_hand": known(json!({"item":item(),"enhancements":entries(json!({"effect":{"duration":known(json!("temporary")),"expires_at_utc_ms":known(json!(0))}}))}))}); + assert!(decode(&value).is_ok()); + let base = value.clone(); + for (pointer, changed) in [ + ( + "/payload/professions/value/entries/profession/skill/value", + json!(1), + ), + ("/payload/bags/value/entries/item/quantity/value", json!(-1)), + ( + "/payload/bags/value/entries/item/quantity/value", + json!(4_294_967_296_u64), + ), + ( + "/payload/bags/value/entries/item/item/context/build/build", + json!("other"), + ), + ( + "/payload/equipment_enhancements/main_hand/value/item/context/namespace", + json!("reference"), + ), + ( + "/payload/equipment_enhancements/main_hand/value/enhancements/value/entries/effect/duration/value", + json!("permanent"), + ), + ] { + let mut value = base.clone(); + *value.pointer_mut(pointer).unwrap() = changed; + assert!(decode(&value).is_err(), "{pointer}"); + } + value["payload"]["bags"]["value"]["entries"]["duplicate"] = entry; + assert!(decode(&value).is_err()); + let mut permanent = base.clone(); + let effect = &mut permanent["payload"]["equipment_enhancements"]["main_hand"]["value"]["enhancements"] + ["value"]["entries"]["effect"]; + effect["duration"] = known(json!("permanent")); + effect["expires_at_utc_ms"] = json!({"status":"not_applicable"}); + assert!(decode(&permanent).is_ok()); + let mut unknown = base; + unknown["payload"]["professions"]["value"]["entries"]["profession"]["maximum_skill"] = + json!({"status":"unknown"}); + unknown["payload"]["equipment_enhancements"]["main_hand"]["value"]["enhancements"] = + json!({"status":"restricted"}); + unknown["payload"]["equipment_enhancements"]["off_hand"] = json!({"status":"unsupported"}); + assert!(decode(&unknown).is_ok()); +} + +#[test] +fn companion_decoding_keeps_byte_depth_and_collection_limits() { + let mut value = fixture(); + value["padding"] = json!("x".repeat(MAX_ENVELOPE_BYTES)); + assert_eq!( + decode_any(&value.to_string()).unwrap_err().code, + ErrorCode::ImportTooLarge + ); + let mut value = fixture(); + let mut nested = json!(0); + for _ in 0..33 { + nested = json!([nested]); + } + value["padding"] = nested; + assert!(decode(&value).is_err()); + let mut value = fixture(); + value["payload"]["spells"] = entries(Value::Object( + (0..1025) + .map(|i| (i.to_string(), known(json!(0)))) + .collect(), + )); + assert!(decode(&value).is_err()); + let text = serde_json::to_string(&fixture()).unwrap().replace( + "\"payload_version\":1", + "\"payload_version\":1,\"payload_version\":1", + ); + assert!(decode_envelope::(&text).is_err()); +} diff --git a/crates/ingest/src/import.rs b/crates/ingest/src/import.rs index 8e853b41..e484e10b 100644 --- a/crates/ingest/src/import.rs +++ b/crates/ingest/src/import.rs @@ -234,6 +234,9 @@ fn summarize(exchange: AnyExchange, options: &ImportOptions) -> ImportResult { } facts(envelope) } + // A companion is not a replacement character snapshot. Do not promote + // it through the legacy character/party freshness summary. + AnyExchange::ProgressionSnapshot(envelope) => facts(&***envelope), AnyExchange::RoutePlan(envelope) => facts(&***envelope), AnyExchange::EvidenceBundle(envelope) => facts(&***envelope), AnyExchange::ReferenceDataset(envelope) => facts(&***envelope), diff --git a/crates/ingest/tests/anav1.rs b/crates/ingest/tests/anav1.rs index 8a897938..9c99de18 100644 --- a/crates/ingest/tests/anav1.rs +++ b/crates/ingest/tests/anav1.rs @@ -34,7 +34,7 @@ fn encode_and_decode_round_trip_every_contract_kind() { assert_eq!(again, exchange); assert_eq!(encode_text(&again).unwrap(), text, "encoding is stable"); } - assert_eq!(kinds.len(), 6); + assert_eq!(kinds.len(), azeroth_core::contract::ContractKind::ALL.len()); } #[test] diff --git a/crates/ingest/tests/import.rs b/crates/ingest/tests/import.rs index afef4d1f..ff77f747 100644 --- a/crates/ingest/tests/import.rs +++ b/crates/ingest/tests/import.rs @@ -391,3 +391,42 @@ fn errors_do_not_echo_imported_content() { &[path_sentinel], ); } + +#[test] +fn progression_requires_explicit_opt_in_and_does_not_replace_character_summary() { + let json = include_str!("../../../fixtures/contracts/v1/progression-snapshot.json"); + let legacy = no_clock(); + assert!(normalize(json, &legacy).is_err()); + let exchange = azeroth_core::contract::decode_any(json).unwrap(); + let text = azeroth_ingest::anav1::encode_text(&exchange).unwrap(); + assert!(import_text(&text, &legacy).is_err()); + let mut companion = legacy; + companion + .accepted_kinds + .insert(ContractKind::ProgressionSnapshot); + let result = import_text(&text, &companion).unwrap(); + assert_eq!(result.kind, ContractKind::ProgressionSnapshot); + assert!(result.snapshots.is_empty()); + assert_eq!(result, normalize(json, &companion).unwrap()); +} + +#[test] +fn progression_fixture_pins_the_actual_predecessor_bytes_and_metadata() { + use azeroth_core::{ + contract::decode_envelope, entities::CharacterSnapshot, progression::ProgressionSnapshot, + types::Sha256Hex, + }; + use sha2::{Digest, Sha256}; + let predecessor = include_str!("../../../fixtures/contracts/v1/character-snapshot.json"); + let character = decode_envelope::(predecessor).unwrap(); + let companion = decode_envelope::(include_str!( + "../../../fixtures/contracts/v1/progression-snapshot.json" + )) + .unwrap(); + let hash = Sha256Hex::new(format!("{:x}", Sha256::digest(predecessor.as_bytes()))).unwrap(); + companion + .payload + .binding + .ensure_matches(&character.payload, &hash) + .unwrap(); +} diff --git a/docs/STATUS.md b/docs/STATUS.md index 71c3c75e..c43f2c17 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -13,7 +13,9 @@ V110.4a adds tested pure progression collection/binding primitives. See the [state handoff](handoffs/2026-11-10-v110-progression-state.md) and [validator handoff](handoffs/2026-11-10-v110-site-version.md). Installed metadata confirms active wowf 1.60.1.70862; interface evidence is pending. Exchange/storage/UI, -content refresh and all 1.1.0 release evidence remain pending. +content refresh and all 1.1.0 release evidence remain pending. V110.4b adds the +[versioned companion exchange](handoffs/2026-11-10-v110-progression-exchange.md), +bounded opt-in decoding and generated contracts; storage/application integration follows. See [tracker](../TODO.md), [claim](claims/2026-11-10-v110-contract.md) and [handoff](handoffs/2026-11-10-v110-contract.md). No 1.1.0 readiness is claimed. diff --git a/docs/claims/2026-11-10-v110-progression-exchange.md b/docs/claims/2026-11-10-v110-progression-exchange.md new file mode 100644 index 00000000..81925608 --- /dev/null +++ b/docs/claims/2026-11-10-v110-progression-exchange.md @@ -0,0 +1,11 @@ +# V110.4b — progression snapshot exchange + +Owner/sole writer Codex `/root`; baseline `bf332bea82aaa4900da0a7f720327badfd510dd8`. +Branch/worktree: `feat/v1.1-guided-progression`, `/tmp/navzeroth-v1.1-guided-progression`. +Scope: versioned pure progression payload, exact envelope dependencies, bounded +core/ingest decoding, generated schema/TypeScript, fixtures and contract docs. +Old character/route v1 semantics and default importer policy remain unchanged. +Checks: core/ingest tests, schema/type generation and corpus checks, Clippy, +formatting, focused coverage, independent read-only review. +Persistence, application commands, addon capture/parity and workflows follow; +no client target admission or release readiness is implied. diff --git a/docs/handoffs/2026-11-10-v110-progression-exchange.md b/docs/handoffs/2026-11-10-v110-progression-exchange.md new file mode 100644 index 00000000..3e7bb417 --- /dev/null +++ b/docs/handoffs/2026-11-10-v110-progression-exchange.md @@ -0,0 +1,46 @@ +# V110.4b — versioned progression companion exchange + +Owner/sole writer Codex `/root`; baseline `bf332bea`; PR #297 isolated worktree. +Claim: `docs/claims/2026-11-10-v110-progression-exchange.md`. + +## Implemented + +New progression_snapshot envelope with payload_version 1, exact predecessor +binding/dependencies and separate companion capture identity. Typed observations +cover spells/ranks, money, talents/points, professions, recipes, scoped bags/bank +and equipment enhancements. Quantities preserve zero; recipes preserve false; +partial/unavailable collections never imply absence. Exact item context and +per-scope aggregate uniqueness, observed skill maxima and permanent expiry rules +are validated. Import uses existing byte/depth/map bounds. Default snapshot import +still refuses companions; explicit opt-in does not populate character summaries. + +Generated Rust schema/TypeScript and a shared synthetic fixture; all old schema +definitions remain unchanged. Old typed importers refuse the new kind. No changes +to character/route v1. Documentation specifies selected persisted hash checks, +nested freshness, equipment matching and separate manual state integration. + +## Actual verification + +- Core tests passed in the combined run (existing ignored fixture/LFS checks remain + ignored). Ingest rerun passed after fixing its historical six-kind assertion. +- Focused progression exchange 4 tests and state 4 tests pass; ingest tests include + explicit opt-in/refusal and actual fixture predecessor SHA-256/binding checks. +- `pnpm contracts:types` and `pnpm contracts:check`: 74 shared fixtures pass. +- Core/ingest all-target Clippy with warnings denied, fmt and whitespace pass. +- Focused llvm-cov: new contract/progression.rs 22/22 lines, progression/snapshot.rs + 37/37 lines, existing progression/mod.rs 44/45 lines. Not a full release gate. +- Read-only review found no blockers, verified unchanged old schema definitions, + fixture binding/hash and focused test executable. Added both recommended tests + (actual predecessor hash and valid permanent/not-applicable expiry). + +Initial new ingest tests failed to compile from passing String instead of &str; +corrected before successful checks. The obsolete six-kind assertion failed after +core tests completed; it now uses ContractKind::ALL. No bounds were enlarged. + +## Remaining + +No migration, application import/UI, addon capture or Lua progression parity yet. +Fixtures establish engineering behavior only, not actual player state. Exact +70862 interface evidence remains pending. Next: V110.4c bounded SQLite companion +storage separated from manual inputs, selected-snapshot invalidation and restart/ +backup/restore tests. Then application commands and saved workflow plans. diff --git a/fixtures/contracts/v1/manifest.json b/fixtures/contracts/v1/manifest.json index 1b4b26de..3ba24893 100644 --- a/fixtures/contracts/v1/manifest.json +++ b/fixtures/contracts/v1/manifest.json @@ -466,6 +466,12 @@ "expect": "semantic_invalid", "error_code": "INVALID_INPUT", "note": "A chain that leads into a two-map cycle is a cycle regardless of record order" + }, + { + "file": "progression-snapshot.json", + "kind": "progression_snapshot", + "expect": "valid", + "note": "Synthetic companion, partial/complete-empty, false and zero; predecessor hash pins character fixture file bytes, not game data." } ] } diff --git a/fixtures/contracts/v1/progression-snapshot.json b/fixtures/contracts/v1/progression-snapshot.json new file mode 100644 index 00000000..f26a6896 --- /dev/null +++ b/fixtures/contracts/v1/progression-snapshot.json @@ -0,0 +1,113 @@ +{ + "format": "azeroth-navigator", + "schema_version": 1, + "fixture": true, + "producer": { + "component": "test_fixture", + "version": "0.1.0", + "session_id": "demo-session-001", + "sequence": 12 + }, + "game": { + "edition": "wow_forever", + "build": "UNVERIFIED_DEMO", + "interface": "UNVERIFIED_DEMO", + "locale": "enGB" + }, + "namespace": "demo", + "provenance": { + "source": "synthetic_fixture", + "clock_trust": "uncertain", + "created_at_utc_ms": 1791792000000 + }, + "kind": "progression_snapshot", + "payload": { + "payload_version": 1, + "id": "demo-progression-001", + "binding": { + "snapshot": "demo-snapshot-001", + "character": "demo-character-paladin", + "context": { + "build": { + "edition": "wow_forever", + "build": "UNVERIFIED_DEMO", + "interface": "UNVERIFIED_DEMO" + }, + "namespace": "demo" + }, + "source_revision": "demo-r1", + "capture": { + "source": "synthetic_fixture", + "clock_trust": "trusted", + "observed_at_utc_ms": 1791791990000, + "session_id": "demo-session-001", + "sequence": 12 + }, + "snapshot_sha256": "d972d7ca3f48cf357cd1afc64794107eee5f397aa6c57d265ffc010fd5b3a29a" + }, + "capture": { + "source": "synthetic_fixture", + "clock_trust": "trusted", + "observed_at_utc_ms": 1791791990000, + "session_id": "demo-session-001", + "sequence": 12 + }, + "spells": { + "status": "unknown" + }, + "money": { + "status": "known", + "value": "0" + }, + "talents": { + "status": "unknown" + }, + "available_talent_points": { + "status": "known", + "value": 0 + }, + "professions": { + "status": "unknown" + }, + "recipes": { + "status": "known", + "value": { + "completeness": "partial", + "entries": { + "synthetic-recipe": { + "status": "known", + "value": false + } + } + } + }, + "bags": { + "status": "known", + "value": { + "completeness": "complete", + "entries": {} + } + }, + "bank": { + "status": "unsupported" + }, + "equipment_enhancements": {} + }, + "dependencies": { + "dataset_revision": "demo-r1", + "snapshots": [ + { + "id": "demo-snapshot-001", + "character": "demo-character-paladin", + "context": { + "build": { + "edition": "wow_forever", + "build": "UNVERIFIED_DEMO", + "interface": "UNVERIFIED_DEMO" + }, + "namespace": "demo" + } + } + ] + } +} diff --git a/schemas/v1/README.md b/schemas/v1/README.md index 4b36e9f0..86ec5d16 100644 --- a/schemas/v1/README.md +++ b/schemas/v1/README.md @@ -2,7 +2,7 @@ These files describe the documents Azeroth Navigator components exchange: character and party snapshots, route plans, evidence bundles, reference datasets -and gear recommendation sets. The Rust definitions in `crates/core/src/contract/` +gear recommendation sets and progression companions. The Rust definitions in `crates/core/src/contract/` are the source of truth. Structural validity never establishes in-game truth. | File | Origin | @@ -27,7 +27,7 @@ Every document is one JSON object with these members: | Member | Required | Meaning | | --- | --- | --- | | `format` | yes | Always `"azeroth-navigator"`. | -| `kind` | yes | `character_snapshot`, `party_snapshot`, `route_plan`, `evidence_bundle`, `reference_dataset` or `gear_recommendations`. Must match the payload. | +| `kind` | yes | `character_snapshot`, `party_snapshot`, `route_plan`, `evidence_bundle`, `reference_dataset` `gear_recommendations` or `progression_snapshot`. Must match the payload. | | `schema_version` | yes | `1`. Any other unsigned integer is rejected as `UNSUPPORTED_SCHEMA` before the payload is read. | | `fixture` | yes | `true` for synthetic engineering data. Production planning must reject fixture documents. | | `producer` | yes | `component` (`addon`, `desktop`, `cli`, `test_fixture`) and `version`, the producer application's version. Optional `session_id`; optional `sequence`, which requires `session_id`. | @@ -38,8 +38,8 @@ Every document is one JSON object with these members: | `payload` | yes | The kind's record (below). | | any other member | no | An **extension**: retained and re-serialized in key order. At most 64; keys are 1–256 bytes without control characters and never a reserved member name; each value at most 16 KiB of JSON text and 64 KiB in total, checked before parsing; numbers within ±(2^53 − 1). | -Unknown members *inside* the payload are accepted and dropped, matching the M1.2 -domain records. Consumers must not rely on them surviving a round trip. +Unknown members *inside* legacy payloads are accepted and dropped, matching the M1.2 +domain records. New progression payload records reject unknown fields. Consumers must not rely on them surviving a round trip. Schema, dataset revision, ruleset, score-model and application versions are independent. Timestamps are integer UTC milliseconds (`*_utc_ms`) everywhere. @@ -253,3 +253,46 @@ and narrows valid fixtures through exhaustive switches. Rust tests check the same manifest, including error codes and round trips. No Lua addon exists yet, so Lua decoding and evaluation parity remain deferred to M2. Shared field names alone do not establish parity. + + +## Progression companion (V110.4b) + +`progression_snapshot` uses envelope schema 1 and required `payload_version: 1`. +This new kind does not change character-snapshot or route-plan v1 semantics. +Older decoders explicitly refuse the unknown kind. Default snapshot import still +accepts only character/party snapshots; a progression caller must explicitly opt in. +A companion never appears as a replacement character in legacy import summaries. + +The required binding names the exact predecessor snapshot, character, build/interface, +namespace, source revision, capture metadata and persisted SHA-256. Envelope +`dependencies` must contain exactly that snapshot reference and source revision, +with no ruleset or score-model dependency. The companion has its own ID/capture; +producer session/sequence must equal that capture, not the predecessor capture. +Application/storage must compare the binding with the actual selected persisted +snapshot and hash before using the companion. A structurally valid self-declared +hash is not proof of identity. Changing the predecessor invalidates advice. + +Required observation fields cover spells/ranks, money, talents/ranks, available +points, profession skills/maxima/ranks, known recipes, bags and bank. Values of +`unknown`, `unsupported`, `restricted` and `not_applicable` carry no value. +Enumeration values contain explicit `complete` or `partial` completeness and a +bounded map of source IDs. Missing partial entries are unknown; complete-empty is +only evidence of absence for that enumeration's exact scope/time. Inner rank, +recipe and quantity observations retain their own status/freshness. Consumers must +check both collection and inner observation freshness before definitive advice. +Money stays a decimal copper string; quantities are integers 0..4294967295. + +Bag and bank quantities are independently aggregated by exact ItemKey, including +variant and context. Duplicate item identities within a scope are refused; the +same item in bags and bank is valid. Neither scope includes equipped items. +Equipment enhancement slots carry exact ItemKey and a separate observed effect +collection. Before advice, compare each item to the bound predecessor slot; +structural validation does not prove the player wore that item. Missing slots mean +unknown. Permanent effects cannot carry a known expiry; temporary unknown expiry +remains unknown and must not be guessed. Manual provenance remains distinct and +will be stored separately by the application, not used to overwrite addon state. + +All maps retain the 1024-entry ceiling; documents retain the 4 MiB byte and 32-level +nesting ceilings. No captured state or live build admission is established by the +synthetic progression fixture. Its predecessor hash pins the character fixture's +file bytes for illustration; runtime bindings use the actual persisted identity. diff --git a/schemas/v1/exchange.schema.json b/schemas/v1/exchange.schema.json index 8c7d6f99..4f713100 100644 --- a/schemas/v1/exchange.schema.json +++ b/schemas/v1/exchange.schema.json @@ -324,6 +324,13 @@ ], "type": "string" }, + "Completeness": { + "enum": [ + "complete", + "partial" + ], + "type": "string" + }, "CompletionSemantics": { "enum": [ "unrepeatable", @@ -595,6 +602,149 @@ "pattern": "^[^\\p{Cc}\\p{White_Space}](?:[^\\p{Cc}]*[^\\p{Cc}\\p{White_Space}])?$", "type": "string" }, + "EnhancementDuration": { + "enum": [ + "permanent", + "temporary" + ], + "type": "string" + }, + "Enumeration": { + "additionalProperties": false, + "description": "Availability and capture metadata live on the enclosing Observation. An\nunavailable enumeration is never represented as an empty complete map.", + "properties": { + "completeness": { + "$ref": "#/$defs/Completeness" + }, + "entries": { + "additionalProperties": { + "$ref": "#/$defs/Observation_uint16" + }, + "maxProperties": 1024, + "propertyNames": { + "$ref": "#/$defs/SourceId" + }, + "type": "object" + } + }, + "required": [ + "completeness", + "entries" + ], + "type": "object" + }, + "Enumeration2": { + "additionalProperties": false, + "description": "Availability and capture metadata live on the enclosing Observation. An\nunavailable enumeration is never represented as an empty complete map.", + "properties": { + "completeness": { + "$ref": "#/$defs/Completeness" + }, + "entries": { + "additionalProperties": { + "$ref": "#/$defs/ProfessionState" + }, + "maxProperties": 1024, + "propertyNames": { + "$ref": "#/$defs/SourceId" + }, + "type": "object" + } + }, + "required": [ + "completeness", + "entries" + ], + "type": "object" + }, + "Enumeration3": { + "additionalProperties": false, + "description": "Availability and capture metadata live on the enclosing Observation. An\nunavailable enumeration is never represented as an empty complete map.", + "properties": { + "completeness": { + "$ref": "#/$defs/Completeness" + }, + "entries": { + "additionalProperties": { + "$ref": "#/$defs/Observation_boolean" + }, + "maxProperties": 1024, + "propertyNames": { + "$ref": "#/$defs/SourceId" + }, + "type": "object" + } + }, + "required": [ + "completeness", + "entries" + ], + "type": "object" + }, + "Enumeration4": { + "additionalProperties": false, + "description": "Availability and capture metadata live on the enclosing Observation. An\nunavailable enumeration is never represented as an empty complete map.", + "properties": { + "completeness": { + "$ref": "#/$defs/Completeness" + }, + "entries": { + "additionalProperties": { + "$ref": "#/$defs/InventoryQuantity" + }, + "maxProperties": 1024, + "propertyNames": { + "$ref": "#/$defs/SourceId" + }, + "type": "object" + } + }, + "required": [ + "completeness", + "entries" + ], + "type": "object" + }, + "Enumeration5": { + "additionalProperties": false, + "description": "Availability and capture metadata live on the enclosing Observation. An\nunavailable enumeration is never represented as an empty complete map.", + "properties": { + "completeness": { + "$ref": "#/$defs/Completeness" + }, + "entries": { + "additionalProperties": { + "$ref": "#/$defs/ObservedEnhancement" + }, + "maxProperties": 1024, + "propertyNames": { + "$ref": "#/$defs/SourceId" + }, + "type": "object" + } + }, + "required": [ + "completeness", + "entries" + ], + "type": "object" + }, + "EquipmentEnhancements": { + "additionalProperties": false, + "properties": { + "enhancements": { + "$ref": "#/$defs/Observation_Enumeration5" + }, + "item": { + "$ref": "#/$defs/ItemKey" + } + }, + "required": [ + "item", + "enhancements" + ], + "type": "object" + }, "EquipmentSlot": { "oneOf": [ { @@ -1240,6 +1390,23 @@ "pattern": "^[^\\p{Cc}\\p{White_Space}](?:[^\\p{Cc}]*[^\\p{Cc}\\p{White_Space}])?$", "type": "string" }, + "InventoryQuantity": { + "additionalProperties": false, + "properties": { + "item": { + "$ref": "#/$defs/ItemKey" + }, + "quantity": { + "$ref": "#/$defs/Observation_uint32", + "description": "Aggregated quantity within this one explicit scope. Never a bag index." + } + }, + "required": [ + "item", + "quantity" + ], + "type": "object" + }, "ItemDefinition": { "properties": { "attributes": { @@ -1688,10 +1855,1539 @@ "$ref": "#/$defs/StateSource", "default": "unrecorded" } - }, - "type": "object" + }, + "type": "object" + }, + "Observation_Array_of_ItemKey": { + "oneOf": [ + { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + }, + "status": { + "const": "known" + }, + "value": { + "items": { + "$ref": "#/$defs/ItemKey" + }, + "type": "array" + } + }, + "required": [ + "status", + "value" + ], + "type": "object" + }, + { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + }, + "status": { + "enum": [ + "unknown", + "unsupported", + "restricted", + "not_applicable" + ] + }, + "value": false + }, + "required": [ + "status" + ], + "type": "object" + } + ] + }, + "Observation_Array_of_Position": { + "oneOf": [ + { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + }, + "status": { + "const": "known" + }, + "value": { + "items": { + "$ref": "#/$defs/Position" + }, + "type": "array" + } + }, + "required": [ + "status", + "value" + ], + "type": "object" + }, + { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + }, + "status": { + "enum": [ + "unknown", + "unsupported", + "restricted", + "not_applicable" + ] + }, + "value": false + }, + "required": [ + "status" + ], + "type": "object" + } + ] + }, + "Observation_Array_of_Text": { + "oneOf": [ + { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + }, + "status": { + "const": "known" + }, + "value": { + "items": { + "$ref": "#/$defs/Text" + }, + "type": "array" + } + }, + "required": [ + "status", + "value" + ], + "type": "object" + }, + { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + }, + "status": { + "enum": [ + "unknown", + "unsupported", + "restricted", + "not_applicable" + ] + }, + "value": false + }, + "required": [ + "status" + ], + "type": "object" + } + ] + }, + "Observation_BuildId": { + "oneOf": [ + { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + }, + "status": { + "const": "known" + }, + "value": { + "$ref": "#/$defs/BuildId" + } + }, + "required": [ + "status", + "value" + ], + "type": "object" + }, + { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + }, + "status": { + "enum": [ + "unknown", + "unsupported", + "restricted", + "not_applicable" + ] + }, + "value": false + }, + "required": [ + "status" + ], + "type": "object" + } + ] + }, + "Observation_CompletionSemantics": { + "oneOf": [ + { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + }, + "status": { + "const": "known" + }, + "value": { + "$ref": "#/$defs/CompletionSemantics" + } + }, + "required": [ + "status", + "value" + ], + "type": "object" + }, + { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + }, + "status": { + "enum": [ + "unknown", + "unsupported", + "restricted", + "not_applicable" + ] + }, + "value": false + }, + "required": [ + "status" + ], + "type": "object" + } + ] + }, + "Observation_CoordinateTransform": { + "oneOf": [ + { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + }, + "status": { + "const": "known" + }, + "value": { + "$ref": "#/$defs/CoordinateTransform" + } + }, + "required": [ + "status", + "value" + ], + "type": "object" + }, + { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + }, + "status": { + "enum": [ + "unknown", + "unsupported", + "restricted", + "not_applicable" + ] + }, + "value": false + }, + "required": [ + "status" + ], + "type": "object" + } + ] + }, + "Observation_Copper": { + "oneOf": [ + { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + }, + "status": { + "const": "known" + }, + "value": { + "$ref": "#/$defs/Copper" + } + }, + "required": [ + "status", + "value" + ], + "type": "object" + }, + { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + }, + "status": { + "enum": [ + "unknown", + "unsupported", + "restricted", + "not_applicable" + ] + }, + "value": false + }, + "required": [ + "status" + ], + "type": "object" + } + ] + }, + "Observation_DurationRange": { + "oneOf": [ + { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + }, + "status": { + "const": "known" + }, + "value": { + "$ref": "#/$defs/DurationRange" + } + }, + "required": [ + "status", + "value" + ], + "type": "object" + }, + { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + }, + "status": { + "enum": [ + "unknown", + "unsupported", + "restricted", + "not_applicable" + ] + }, + "value": false + }, + "required": [ + "status" + ], + "type": "object" + } + ] + }, + "Observation_EnhancementDuration": { + "oneOf": [ + { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + }, + "status": { + "const": "known" + }, + "value": { + "$ref": "#/$defs/EnhancementDuration" + } + }, + "required": [ + "status", + "value" + ], + "type": "object" + }, + { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + }, + "status": { + "enum": [ + "unknown", + "unsupported", + "restricted", + "not_applicable" + ] + }, + "value": false + }, + "required": [ + "status" + ], + "type": "object" + } + ] + }, + "Observation_Enumeration": { + "oneOf": [ + { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + }, + "status": { + "const": "known" + }, + "value": { + "$ref": "#/$defs/Enumeration" + } + }, + "required": [ + "status", + "value" + ], + "type": "object" + }, + { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + }, + "status": { + "enum": [ + "unknown", + "unsupported", + "restricted", + "not_applicable" + ] + }, + "value": false + }, + "required": [ + "status" + ], + "type": "object" + } + ] }, - "Observation_Array_of_ItemKey": { + "Observation_Enumeration2": { "oneOf": [ { "properties": { @@ -1757,10 +3453,7 @@ "const": "known" }, "value": { - "items": { - "$ref": "#/$defs/ItemKey" - }, - "type": "array" + "$ref": "#/$defs/Enumeration2" } }, "required": [ @@ -1846,7 +3539,7 @@ } ] }, - "Observation_Array_of_Position": { + "Observation_Enumeration3": { "oneOf": [ { "properties": { @@ -1912,10 +3605,7 @@ "const": "known" }, "value": { - "items": { - "$ref": "#/$defs/Position" - }, - "type": "array" + "$ref": "#/$defs/Enumeration3" } }, "required": [ @@ -2001,7 +3691,7 @@ } ] }, - "Observation_Array_of_Text": { + "Observation_Enumeration4": { "oneOf": [ { "properties": { @@ -2067,10 +3757,7 @@ "const": "known" }, "value": { - "items": { - "$ref": "#/$defs/Text" - }, - "type": "array" + "$ref": "#/$defs/Enumeration4" } }, "required": [ @@ -2156,7 +3843,7 @@ } ] }, - "Observation_BuildId": { + "Observation_Enumeration5": { "oneOf": [ { "properties": { @@ -2222,7 +3909,7 @@ "const": "known" }, "value": { - "$ref": "#/$defs/BuildId" + "$ref": "#/$defs/Enumeration5" } }, "required": [ @@ -2308,7 +3995,7 @@ } ] }, - "Observation_CompletionSemantics": { + "Observation_EquipmentEnhancements": { "oneOf": [ { "properties": { @@ -2374,7 +4061,7 @@ "const": "known" }, "value": { - "$ref": "#/$defs/CompletionSemantics" + "$ref": "#/$defs/EquipmentEnhancements" } }, "required": [ @@ -2460,7 +4147,7 @@ } ] }, - "Observation_CoordinateTransform": { + "Observation_EquipmentSlot": { "oneOf": [ { "properties": { @@ -2526,7 +4213,7 @@ "const": "known" }, "value": { - "$ref": "#/$defs/CoordinateTransform" + "$ref": "#/$defs/EquipmentSlot" } }, "required": [ @@ -2612,7 +4299,7 @@ } ] }, - "Observation_Copper": { + "Observation_FiniteNumber": { "oneOf": [ { "properties": { @@ -2678,7 +4365,7 @@ "const": "known" }, "value": { - "$ref": "#/$defs/Copper" + "$ref": "#/$defs/FiniteNumber" } }, "required": [ @@ -2764,7 +4451,7 @@ } ] }, - "Observation_DurationRange": { + "Observation_InstanceId": { "oneOf": [ { "properties": { @@ -2830,7 +4517,7 @@ "const": "known" }, "value": { - "$ref": "#/$defs/DurationRange" + "$ref": "#/$defs/InstanceId" } }, "required": [ @@ -2916,7 +4603,7 @@ } ] }, - "Observation_EquipmentSlot": { + "Observation_Level": { "oneOf": [ { "properties": { @@ -2982,7 +4669,7 @@ "const": "known" }, "value": { - "$ref": "#/$defs/EquipmentSlot" + "$ref": "#/$defs/Level" } }, "required": [ @@ -3068,7 +4755,7 @@ } ] }, - "Observation_FiniteNumber": { + "Observation_Millis": { "oneOf": [ { "properties": { @@ -3134,7 +4821,7 @@ "const": "known" }, "value": { - "$ref": "#/$defs/FiniteNumber" + "$ref": "#/$defs/Millis" } }, "required": [ @@ -3220,7 +4907,7 @@ } ] }, - "Observation_InstanceId": { + "Observation_Normalized": { "oneOf": [ { "properties": { @@ -3286,7 +4973,7 @@ "const": "known" }, "value": { - "$ref": "#/$defs/InstanceId" + "$ref": "#/$defs/Normalized" } }, "required": [ @@ -3372,7 +5059,7 @@ } ] }, - "Observation_Level": { + "Observation_Position": { "oneOf": [ { "properties": { @@ -3438,7 +5125,7 @@ "const": "known" }, "value": { - "$ref": "#/$defs/Level" + "$ref": "#/$defs/Position" } }, "required": [ @@ -3524,7 +5211,7 @@ } ] }, - "Observation_Millis": { + "Observation_Predicate": { "oneOf": [ { "properties": { @@ -3590,7 +5277,7 @@ "const": "known" }, "value": { - "$ref": "#/$defs/Millis" + "$ref": "#/$defs/Predicate" } }, "required": [ @@ -3676,7 +5363,7 @@ } ] }, - "Observation_Normalized": { + "Observation_RecordMap_AttributeId_FiniteNumber": { "oneOf": [ { "properties": { @@ -3742,7 +5429,14 @@ "const": "known" }, "value": { - "$ref": "#/$defs/Normalized" + "additionalProperties": { + "$ref": "#/$defs/FiniteNumber" + }, + "maxProperties": 1024, + "propertyNames": { + "$ref": "#/$defs/AttributeId" + }, + "type": "object" } }, "required": [ @@ -3828,7 +5522,7 @@ } ] }, - "Observation_Position": { + "Observation_RecordMap_CapabilityId_CapabilityCheck": { "oneOf": [ { "properties": { @@ -3894,7 +5588,14 @@ "const": "known" }, "value": { - "$ref": "#/$defs/Position" + "additionalProperties": { + "$ref": "#/$defs/CapabilityCheck" + }, + "maxProperties": 1024, + "propertyNames": { + "$ref": "#/$defs/CapabilityId" + }, + "type": "object" } }, "required": [ @@ -3980,7 +5681,7 @@ } ] }, - "Observation_Predicate": { + "Observation_RoleId": { "oneOf": [ { "properties": { @@ -4046,7 +5747,7 @@ "const": "known" }, "value": { - "$ref": "#/$defs/Predicate" + "$ref": "#/$defs/RoleId" } }, "required": [ @@ -4132,7 +5833,7 @@ } ] }, - "Observation_RecordMap_AttributeId_FiniteNumber": { + "Observation_ServiceKind": { "oneOf": [ { "properties": { @@ -4198,14 +5899,7 @@ "const": "known" }, "value": { - "additionalProperties": { - "$ref": "#/$defs/FiniteNumber" - }, - "maxProperties": 1024, - "propertyNames": { - "$ref": "#/$defs/AttributeId" - }, - "type": "object" + "$ref": "#/$defs/ServiceKind" } }, "required": [ @@ -4291,7 +5985,7 @@ } ] }, - "Observation_RecordMap_CapabilityId_CapabilityCheck": { + "Observation_SourceId": { "oneOf": [ { "properties": { @@ -4357,14 +6051,7 @@ "const": "known" }, "value": { - "additionalProperties": { - "$ref": "#/$defs/CapabilityCheck" - }, - "maxProperties": 1024, - "propertyNames": { - "$ref": "#/$defs/CapabilityId" - }, - "type": "object" + "$ref": "#/$defs/SourceId" } }, "required": [ @@ -4450,7 +6137,7 @@ } ] }, - "Observation_RoleId": { + "Observation_Text": { "oneOf": [ { "properties": { @@ -4516,7 +6203,7 @@ "const": "known" }, "value": { - "$ref": "#/$defs/RoleId" + "$ref": "#/$defs/Text" } }, "required": [ @@ -4602,7 +6289,7 @@ } ] }, - "Observation_ServiceKind": { + "Observation_UtcMillis": { "oneOf": [ { "properties": { @@ -4668,7 +6355,7 @@ "const": "known" }, "value": { - "$ref": "#/$defs/ServiceKind" + "$ref": "#/$defs/UtcMillis" } }, "required": [ @@ -4754,7 +6441,7 @@ } ] }, - "Observation_Text": { + "Observation_VariantId": { "oneOf": [ { "properties": { @@ -4820,7 +6507,7 @@ "const": "known" }, "value": { - "$ref": "#/$defs/Text" + "$ref": "#/$defs/VariantId" } }, "required": [ @@ -4906,7 +6593,7 @@ } ] }, - "Observation_UtcMillis": { + "Observation_boolean": { "oneOf": [ { "properties": { @@ -4972,7 +6659,7 @@ "const": "known" }, "value": { - "$ref": "#/$defs/UtcMillis" + "type": "boolean" } }, "required": [ @@ -5058,7 +6745,7 @@ } ] }, - "Observation_VariantId": { + "Observation_uint16": { "oneOf": [ { "properties": { @@ -5124,7 +6811,9 @@ "const": "known" }, "value": { - "$ref": "#/$defs/VariantId" + "maximum": 65535, + "minimum": 0, + "type": "integer" } }, "required": [ @@ -5210,7 +6899,7 @@ } ] }, - "Observation_boolean": { + "Observation_uint32": { "oneOf": [ { "properties": { @@ -5276,7 +6965,8 @@ "const": "known" }, "value": { - "type": "boolean" + "minimum": 0, + "type": "integer" } }, "required": [ @@ -5362,6 +7052,23 @@ } ] }, + "ObservedEnhancement": { + "additionalProperties": false, + "properties": { + "duration": { + "$ref": "#/$defs/Observation_EnhancementDuration" + }, + "expires_at_utc_ms": { + "$ref": "#/$defs/Observation_UtcMillis", + "description": "Unreadable expiry remains unknown/restricted; no inferred duration." + } + }, + "required": [ + "duration", + "expires_at_utc_ms" + ], + "type": "object" + }, "PartyId": { "maxLength": 256, "minLength": 1, @@ -5931,6 +7638,145 @@ ], "type": "string" }, + "ProfessionState": { + "additionalProperties": false, + "properties": { + "maximum_skill": { + "$ref": "#/$defs/Observation_uint16" + }, + "rank": { + "$ref": "#/$defs/Observation_SourceId" + }, + "skill": { + "$ref": "#/$defs/Observation_uint16" + } + }, + "required": [ + "skill", + "maximum_skill", + "rank" + ], + "type": "object" + }, + "ProgressionSnapshot": { + "additionalProperties": false, + "properties": { + "available_talent_points": { + "$ref": "#/$defs/Observation_uint16" + }, + "bags": { + "$ref": "#/$defs/Observation_Enumeration4", + "description": "Bags and bank are separate enumerations and never silently combined." + }, + "bank": { + "$ref": "#/$defs/Observation_Enumeration4" + }, + "binding": { + "$ref": "#/$defs/SnapshotBinding" + }, + "capture": { + "$ref": "#/$defs/ObservationMetadata" + }, + "equipment_enhancements": { + "additionalProperties": { + "$ref": "#/$defs/Observation_EquipmentEnhancements" + }, + "maxProperties": 1024, + "propertyNames": { + "$ref": "#/$defs/SlotId" + }, + "type": "object" + }, + "id": { + "$ref": "#/$defs/SnapshotId" + }, + "money": { + "$ref": "#/$defs/Observation_Copper" + }, + "payload_version": { + "$ref": "#/$defs/SchemaVersion" + }, + "professions": { + "$ref": "#/$defs/Observation_Enumeration2" + }, + "recipes": { + "$ref": "#/$defs/Observation_Enumeration3" + }, + "spells": { + "$ref": "#/$defs/Observation_Enumeration", + "description": "Keys identify exact source spell records; unknown rank is not rank zero." + }, + "talents": { + "$ref": "#/$defs/Observation_Enumeration" + } + }, + "required": [ + "payload_version", + "id", + "binding", + "capture", + "spells", + "money", + "talents", + "available_talent_points", + "professions", + "recipes", + "bags", + "bank", + "equipment_enhancements" + ], + "type": "object" + }, + "ProgressionSnapshotEnvelope": { + "description": "Deserialization is hand-written (see below) so unknown members are size\nchecked as raw text before parsing, instead of buffering the whole envelope.", + "properties": { + "dependencies": { + "$ref": "#/$defs/Dependencies" + }, + "fixture": { + "description": "True for synthetic engineering data. Production planning rejects it.", + "type": "boolean" + }, + "format": { + "const": "azeroth-navigator", + "type": "string" + }, + "game": { + "$ref": "#/$defs/GameContext" + }, + "kind": { + "const": "progression_snapshot", + "type": "string" + }, + "namespace": { + "$ref": "#/$defs/DatasetNamespace" + }, + "payload": { + "$ref": "#/$defs/ProgressionSnapshot" + }, + "producer": { + "$ref": "#/$defs/Producer" + }, + "provenance": { + "$ref": "#/$defs/Provenance" + }, + "schema_version": { + "$ref": "#/$defs/SchemaVersion" + } + }, + "required": [ + "format", + "kind", + "schema_version", + "fixture", + "producer", + "game", + "namespace", + "provenance", + "payload" + ], + "type": "object" + }, "Provenance": { "properties": { "clock_trust": { @@ -6600,6 +8446,39 @@ "pattern": "^[^\\p{Cc}\\p{White_Space}](?:[^\\p{Cc}]*[^\\p{Cc}\\p{White_Space}])?$", "type": "string" }, + "SnapshotBinding": { + "additionalProperties": false, + "description": "Exact predecessor identity for progression companions and saved advice.\nThe I/O layer supplies the persisted snapshot hash; this module does not hash\nor normalize imported bytes and never accepts a nearest-build substitution.", + "properties": { + "capture": { + "$ref": "#/$defs/ObservationMetadata" + }, + "character": { + "$ref": "#/$defs/CharacterId" + }, + "context": { + "$ref": "#/$defs/DataContext" + }, + "snapshot": { + "$ref": "#/$defs/SnapshotId" + }, + "snapshot_sha256": { + "$ref": "#/$defs/Sha256Hex" + }, + "source_revision": { + "$ref": "#/$defs/DatasetRevision" + } + }, + "required": [ + "snapshot", + "character", + "context", + "source_revision", + "capture", + "snapshot_sha256" + ], + "type": "object" + }, "SnapshotId": { "maxLength": 256, "minLength": 1, @@ -6805,6 +8684,9 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "Azeroth Navigator exchange envelopes, schema version 1. Structural only: Rust validation enforces semantic invariants, and structural validity never establishes in-game truth.", "oneOf": [ + { + "$ref": "#/$defs/ProgressionSnapshotEnvelope" + }, { "$ref": "#/$defs/CharacterSnapshotEnvelope" }, diff --git a/schemas/v1/exchange.ts b/schemas/v1/exchange.ts index 5a468fe0..8ce4c743 100644 --- a/schemas/v1/exchange.ts +++ b/schemas/v1/exchange.ts @@ -6,6 +6,7 @@ * Azeroth Navigator exchange envelopes, schema version 1. Structural only: Rust validation enforces semantic invariants, and structural validity never establishes in-game truth. */ export type AzerothNavigatorExchangeV1 = + | ProgressionSnapshotEnvelope | CharacterSnapshotEnvelope | PartySnapshotEnvelope | RoutePlanEnvelope @@ -22,11 +23,7 @@ export type InterfaceId = string; export type DatasetNamespace = "demo" | "reference"; export type SnapshotId = string; export type Locale = string; -export type UtcMillis = number; -export type Sequence = number; -export type Millis = number; -export type SessionId = string; -export type Observation_EquipmentSlot = +export type ObservationUint16 = | { clock_trust?: "trusted" | "uncertain"; observed_at_utc_ms?: UtcMillis | null; @@ -42,7 +39,7 @@ export type Observation_EquipmentSlot = | "reference_data" | "synthetic_fixture"; status: "known"; - value: EquipmentSlot; + value: number; } | { clock_trust?: "trusted" | "uncertain"; @@ -61,15 +58,14 @@ export type Observation_EquipmentSlot = status: "unknown" | "unsupported" | "restricted" | "not_applicable"; value?: never; }; -export type EquipmentSlot = - | { - state: "empty"; - } - | { - item: EquippedItem; - state: "item"; - }; -export type Observation_InstanceId = +export type UtcMillis = number; +export type Sequence = number; +export type Millis = number; +export type SessionId = string; +export type Completeness = "complete" | "partial"; +export type ItemId = string; +export type VariantId = string; +export type Observation_Enumeration4 = | { clock_trust?: "trusted" | "uncertain"; observed_at_utc_ms?: UtcMillis | null; @@ -85,7 +81,7 @@ export type Observation_InstanceId = | "reference_data" | "synthetic_fixture"; status: "known"; - value: InstanceId; + value: Enumeration4; } | { clock_trust?: "trusted" | "uncertain"; @@ -104,9 +100,8 @@ export type Observation_InstanceId = status: "unknown" | "unsupported" | "restricted" | "not_applicable"; value?: never; }; -export type InstanceId = string; -export type ItemId = string; -export type Observation_RecordMap_AttributeId_FiniteNumber = +export type Sha256Hex = string; +export type Observation_EquipmentEnhancements = | { clock_trust?: "trusted" | "uncertain"; observed_at_utc_ms?: UtcMillis | null; @@ -122,9 +117,7 @@ export type Observation_RecordMap_AttributeId_FiniteNumber = | "reference_data" | "synthetic_fixture"; status: "known"; - value: { - [k: string]: FiniteNumber | undefined; - }; + value: EquipmentEnhancements; } | { clock_trust?: "trusted" | "uncertain"; @@ -143,8 +136,7 @@ export type Observation_RecordMap_AttributeId_FiniteNumber = status: "unknown" | "unsupported" | "restricted" | "not_applicable"; value?: never; }; -export type FiniteNumber = number; -export type Observation_VariantId = +export type Observation_Enumeration5 = | { clock_trust?: "trusted" | "uncertain"; observed_at_utc_ms?: UtcMillis | null; @@ -160,7 +152,7 @@ export type Observation_VariantId = | "reference_data" | "synthetic_fixture"; status: "known"; - value: VariantId; + value: Enumeration5; } | { clock_trust?: "trusted" | "uncertain"; @@ -179,8 +171,7 @@ export type Observation_VariantId = status: "unknown" | "unsupported" | "restricted" | "not_applicable"; value?: never; }; -export type VariantId = string; -export type Observation_Level = +export type Observation_EnhancementDuration = | { clock_trust?: "trusted" | "uncertain"; observed_at_utc_ms?: UtcMillis | null; @@ -196,7 +187,7 @@ export type Observation_Level = | "reference_data" | "synthetic_fixture"; status: "known"; - value: Level; + value: EnhancementDuration; } | { clock_trust?: "trusted" | "uncertain"; @@ -215,8 +206,8 @@ export type Observation_Level = status: "unknown" | "unsupported" | "restricted" | "not_applicable"; value?: never; }; -export type Level = number; -export type Observation_Position = +export type EnhancementDuration = "permanent" | "temporary"; +export type Observation_Copper = | { clock_trust?: "trusted" | "uncertain"; observed_at_utc_ms?: UtcMillis | null; @@ -232,7 +223,7 @@ export type Observation_Position = | "reference_data" | "synthetic_fixture"; status: "known"; - value: Position; + value: Copper; } | { clock_trust?: "trusted" | "uncertain"; @@ -251,10 +242,12 @@ export type Observation_Position = status: "unknown" | "unsupported" | "restricted" | "not_applicable"; value?: never; }; -export type FloorId = string; -export type MapId = string; -export type Normalized = number; -export type ObservationBoolean = +/** + * Unsigned integer copper as a canonical base-10 string (Rust also rejects values above u64) + */ +export type Copper = string; +export type SchemaVersion = 1; +export type Observation_Enumeration2 = | { clock_trust?: "trusted" | "uncertain"; observed_at_utc_ms?: UtcMillis | null; @@ -270,7 +263,7 @@ export type ObservationBoolean = | "reference_data" | "synthetic_fixture"; status: "known"; - value: boolean; + value: Enumeration2; } | { clock_trust?: "trusted" | "uncertain"; @@ -289,8 +282,7 @@ export type ObservationBoolean = status: "unknown" | "unsupported" | "restricted" | "not_applicable"; value?: never; }; -export type QuestId = string; -export type Observation_RoleId = +export type Observation_SourceId = | { clock_trust?: "trusted" | "uncertain"; observed_at_utc_ms?: UtcMillis | null; @@ -306,7 +298,7 @@ export type Observation_RoleId = | "reference_data" | "synthetic_fixture"; status: "known"; - value: RoleId; + value: SourceId; } | { clock_trust?: "trusted" | "uncertain"; @@ -325,31 +317,8 @@ export type Observation_RoleId = status: "unknown" | "unsupported" | "restricted" | "not_applicable"; value?: never; }; -export type RoleId = string; -export type SchemaVersion = 1; -export type ProducerComponent = "addon" | "desktop" | "cli" | "test_fixture"; -export type ClockTrust = "trusted" | "uncertain"; -export type StateSource = - | "unrecorded" - | "addon_snapshot" - | "manual_entry" - | "official_api" - | "reference_data" - | "synthetic_fixture"; -export type PartyId = string; -export type CapabilityStatus = - "verified_available" | "verified_unavailable" | "restricted" | "failed" | "untested"; -export type EvidenceId = string; -export type ObjectiveId = string; -export type Text = string; -export type PlanId = string; -/** - * Events after which a plan must be revalidated. Expiry and these triggers - * never prove that the underlying game state changed. - */ -export type RevalidationTrigger = - "dataset_revision_changed" | "build_changed" | "snapshot_superseded" | "ruleset_changed"; -export type Observation_DurationRange = +export type SourceId = string; +export type Observation_Enumeration3 = | { clock_trust?: "trusted" | "uncertain"; observed_at_utc_ms?: UtcMillis | null; @@ -365,7 +334,7 @@ export type Observation_DurationRange = | "reference_data" | "synthetic_fixture"; status: "known"; - value: DurationRange; + value: Enumeration3; } | { clock_trust?: "trusted" | "uncertain"; @@ -384,7 +353,7 @@ export type Observation_DurationRange = status: "unknown" | "unsupported" | "restricted" | "not_applicable"; value?: never; }; -export type Observation_Millis = +export type ObservationBoolean = | { clock_trust?: "trusted" | "uncertain"; observed_at_utc_ms?: UtcMillis | null; @@ -400,7 +369,7 @@ export type Observation_Millis = | "reference_data" | "synthetic_fixture"; status: "known"; - value: Millis; + value: boolean; } | { clock_trust?: "trusted" | "uncertain"; @@ -419,8 +388,7 @@ export type Observation_Millis = status: "unknown" | "unsupported" | "restricted" | "not_applicable"; value?: never; }; -export type StepId = string; -export type Observation_Predicate = +export type Observation_Enumeration = | { clock_trust?: "trusted" | "uncertain"; observed_at_utc_ms?: UtcMillis | null; @@ -436,7 +404,7 @@ export type Observation_Predicate = | "reference_data" | "synthetic_fixture"; status: "known"; - value: Predicate; + value: Enumeration; } | { clock_trust?: "trusted" | "uncertain"; @@ -455,132 +423,16 @@ export type Observation_Predicate = status: "unknown" | "unsupported" | "restricted" | "not_applicable"; value?: never; }; -export type Predicate = - | { - op: "all"; - predicates: Predicate[]; - } - | { - op: "any"; - predicates: Predicate[]; - } - | { - op: "not"; - predicate: Predicate; - } - | { - field: Field; - op: "known"; - } - | { - field: Field; - op: "equals"; - value: Scalar; - } - | { - field: Field; - op: "greater_than_or_equal"; - value: Scalar; - } - | { - op: "quest_state"; - quest: QuestId; - state: QuestState; - value: boolean; - } - | { - completed: boolean; - objective: ObjectiveId; - op: "objective_state"; - } - | { - level: Level; - op: "level_at_least"; - } - | { - item: ItemKey; - modifiers: { - [k: string]: FiniteNumber | undefined; - }; - op: "equipment_matches"; - slot: SlotId; - } - | { - op: "role_is"; - role: RoleId; - } - | { - area: SupportedArea; - op: "location_in_supported_area"; - } - | { - key: PreferenceId; - op: "user_preference"; - value: boolean; - } - | { - op: "participant_state"; - participant: CharacterId; - predicate: Predicate; - }; -export type Field = - | { - field: "level"; - } - | { - field: "role"; - } - | { - field: "preference"; - key: PreferenceId; - } - | { - field: "quest"; - quest: QuestId; - state: QuestState; - } - | { - field: "objective"; - objective: ObjectiveId; - }; -export type PreferenceId = string; -export type QuestState = "accepted" | "completed" | "turned_in"; -export type Scalar = - | { - type: "bool"; - value: boolean; - } - | { - type: "integer"; - value: SafeInteger; - } - | { - type: "number"; - value: FiniteNumber; - } - | { - type: "copper"; - value: Copper; - } - | { - type: "text"; - value: Text; - }; -export type SafeInteger = number; -/** - * Unsigned integer copper as a canonical base-10 string (Rust also rejects values above u64) - */ -export type Copper = string; -export type SlotId = string; -export type NodeId = string; -export type Confidence = - | "verified_on_build" - | "publisher_documented" - | "limited_sample" - | "cross_edition_unverified" - | "inferred" - | "disputed_or_stale"; -export type Observation_Text = +export type ProducerComponent = "addon" | "desktop" | "cli" | "test_fixture"; +export type ClockTrust = "trusted" | "uncertain"; +export type StateSource = + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; +export type Observation_EquipmentSlot = | { clock_trust?: "trusted" | "uncertain"; observed_at_utc_ms?: UtcMillis | null; @@ -596,7 +448,7 @@ export type Observation_Text = | "reference_data" | "synthetic_fixture"; status: "known"; - value: Text; + value: EquipmentSlot; } | { clock_trust?: "trusted" | "uncertain"; @@ -615,7 +467,15 @@ export type Observation_Text = status: "unknown" | "unsupported" | "restricted" | "not_applicable"; value?: never; }; -export type Observation_UtcMillis = +export type EquipmentSlot = + | { + state: "empty"; + } + | { + item: EquippedItem; + state: "item"; + }; +export type Observation_InstanceId = | { clock_trust?: "trusted" | "uncertain"; observed_at_utc_ms?: UtcMillis | null; @@ -631,7 +491,7 @@ export type Observation_UtcMillis = | "reference_data" | "synthetic_fixture"; status: "known"; - value: UtcMillis; + value: InstanceId; } | { clock_trust?: "trusted" | "uncertain"; @@ -650,7 +510,8 @@ export type Observation_UtcMillis = status: "unknown" | "unsupported" | "restricted" | "not_applicable"; value?: never; }; -export type Observation_BuildId = +export type InstanceId = string; +export type Observation_RecordMap_AttributeId_FiniteNumber = | { clock_trust?: "trusted" | "uncertain"; observed_at_utc_ms?: UtcMillis | null; @@ -666,7 +527,9 @@ export type Observation_BuildId = | "reference_data" | "synthetic_fixture"; status: "known"; - value: BuildId; + value: { + [k: string]: FiniteNumber | undefined; + }; } | { clock_trust?: "trusted" | "uncertain"; @@ -685,8 +548,8 @@ export type Observation_BuildId = status: "unknown" | "unsupported" | "restricted" | "not_applicable"; value?: never; }; -export type SourceId = string; -export type Observation_RecordMap_CapabilityId_CapabilityCheck = +export type FiniteNumber = number; +export type Observation_VariantId = | { clock_trust?: "trusted" | "uncertain"; observed_at_utc_ms?: UtcMillis | null; @@ -702,9 +565,7 @@ export type Observation_RecordMap_CapabilityId_CapabilityCheck = | "reference_data" | "synthetic_fixture"; status: "known"; - value: { - [k: string]: CapabilityCheck | undefined; - }; + value: VariantId; } | { clock_trust?: "trusted" | "uncertain"; @@ -723,9 +584,7 @@ export type Observation_RecordMap_CapabilityId_CapabilityCheck = status: "unknown" | "unsupported" | "restricted" | "not_applicable"; value?: never; }; -export type ProviderId = string; -export type ProviderStatus = "available" | "unavailable" | "unverified" | "restricted"; -export type Observation_Copper = +export type Observation_Level = | { clock_trust?: "trusted" | "uncertain"; observed_at_utc_ms?: UtcMillis | null; @@ -741,7 +600,7 @@ export type Observation_Copper = | "reference_data" | "synthetic_fixture"; status: "known"; - value: Copper; + value: Level; } | { clock_trust?: "trusted" | "uncertain"; @@ -760,9 +619,8 @@ export type Observation_Copper = status: "unknown" | "unsupported" | "restricted" | "not_applicable"; value?: never; }; -export type AcquisitionId = string; -export type AcquisitionKind = "quest" | "vendor" | "dungeon" | "crafting" | "other"; -export type Observation_Normalized = +export type Level = number; +export type Observation_Position = | { clock_trust?: "trusted" | "uncertain"; observed_at_utc_ms?: UtcMillis | null; @@ -778,7 +636,7 @@ export type Observation_Normalized = | "reference_data" | "synthetic_fixture"; status: "known"; - value: Normalized; + value: Position; } | { clock_trust?: "trusted" | "uncertain"; @@ -797,10 +655,11 @@ export type Observation_Normalized = status: "unknown" | "unsupported" | "restricted" | "not_applicable"; value?: never; }; -export type EdgeId = string; -export type TravelMode = "walking" | "flight" | "boat" | "tram" | "teleport" | "return"; -export type EdgeStatus = "verified" | "estimated" | "temporarily_unavailable" | "unverified"; -export type Observation_ArrayOf_Text = +export type FloorId = string; +export type MapId = string; +export type Normalized = number; +export type QuestId = string; +export type Observation_RoleId = | { clock_trust?: "trusted" | "uncertain"; observed_at_utc_ms?: UtcMillis | null; @@ -816,7 +675,7 @@ export type Observation_ArrayOf_Text = | "reference_data" | "synthetic_fixture"; status: "known"; - value: Text[]; + value: RoleId; } | { clock_trust?: "trusted" | "uncertain"; @@ -835,26 +694,56 @@ export type Observation_ArrayOf_Text = status: "unknown" | "unsupported" | "restricted" | "not_applicable"; value?: never; }; -export type PinId = string; -export type PixelExtent = number; -export type ImageId = string; -export type LayerId = string; -export type ImageLayerKind = - ("terrain" | "other") | "roads_traced" | "flight_reference" | "overview"; -export type Sha256Hex = string; -export type PinKind = - | { - access: FlightAccess[]; - kind: "flight_master"; - } +export type RoleId = string; +export type PartyId = string; +export type CapabilityStatus = + "verified_available" | "verified_unavailable" | "restricted" | "failed" | "untested"; +export type EvidenceId = string; +export type ObjectiveId = string; +export type Text = string; +export type PlanId = string; +/** + * Events after which a plan must be revalidated. Expiry and these triggers + * never prove that the underlying game state changed. + */ +export type RevalidationTrigger = + "dataset_revision_changed" | "build_changed" | "snapshot_superseded" | "ruleset_changed"; +export type Observation_DurationRange = | { - kind: "settlement"; + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "known"; + value: DurationRange; } | { - kind: "landmark"; + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "unknown" | "unsupported" | "restricted" | "not_applicable"; + value?: never; }; -export type FlightAccess = "alliance" | "horde" | "tower_route"; -export type Observation_CoordinateTransform = +export type Observation_Millis = | { clock_trust?: "trusted" | "uncertain"; observed_at_utc_ms?: UtcMillis | null; @@ -870,7 +759,7 @@ export type Observation_CoordinateTransform = | "reference_data" | "synthetic_fixture"; status: "known"; - value: CoordinateTransform; + value: Millis; } | { clock_trust?: "trusted" | "uncertain"; @@ -889,7 +778,8 @@ export type Observation_CoordinateTransform = status: "unknown" | "unsupported" | "restricted" | "not_applicable"; value?: never; }; -export type Observation_ServiceKind = +export type StepId = string; +export type Observation_Predicate = | { clock_trust?: "trusted" | "uncertain"; observed_at_utc_ms?: UtcMillis | null; @@ -905,7 +795,7 @@ export type Observation_ServiceKind = | "reference_data" | "synthetic_fixture"; status: "known"; - value: ServiceKind; + value: Predicate; } | { clock_trust?: "trusted" | "uncertain"; @@ -924,23 +814,128 @@ export type Observation_ServiceKind = status: "unknown" | "unsupported" | "restricted" | "not_applicable"; value?: never; }; -export type ServiceKind = - "junction" | "vendor" | "repair" | "trainer" | "flight" | "transport" | "dungeon" | "other"; -export type ObjectiveTarget = +export type Predicate = | { - kind: "quest_stage"; + op: "all"; + predicates: Predicate[]; + } + | { + op: "any"; + predicates: Predicate[]; + } + | { + op: "not"; + predicate: Predicate; + } + | { + field: Field; + op: "known"; + } + | { + field: Field; + op: "equals"; + value: Scalar; + } + | { + field: Field; + op: "greater_than_or_equal"; + value: Scalar; + } + | { + op: "quest_state"; quest: QuestId; - stage: ObjectiveId; + state: QuestState; + value: boolean; } | { - kind: "acquisition"; - source: AcquisitionId; + completed: boolean; + objective: ObjectiveId; + op: "objective_state"; } | { - kind: "service"; - node: NodeRef; + level: Level; + op: "level_at_least"; + } + | { + item: ItemKey; + modifiers: { + [k: string]: FiniteNumber | undefined; + }; + op: "equipment_matches"; + slot: SlotId; + } + | { + op: "role_is"; + role: RoleId; + } + | { + area: SupportedArea; + op: "location_in_supported_area"; + } + | { + key: PreferenceId; + op: "user_preference"; + value: boolean; + } + | { + op: "participant_state"; + participant: CharacterId; + predicate: Predicate; }; -export type Observation_CompletionSemantics = +export type Field = + | { + field: "level"; + } + | { + field: "role"; + } + | { + field: "preference"; + key: PreferenceId; + } + | { + field: "quest"; + quest: QuestId; + state: QuestState; + } + | { + field: "objective"; + objective: ObjectiveId; + }; +export type PreferenceId = string; +export type QuestState = "accepted" | "completed" | "turned_in"; +export type Scalar = + | { + type: "bool"; + value: boolean; + } + | { + type: "integer"; + value: SafeInteger; + } + | { + type: "number"; + value: FiniteNumber; + } + | { + type: "copper"; + value: Copper; + } + | { + type: "text"; + value: Text; + }; +export type SafeInteger = number; +export type SlotId = string; +export type NodeId = string; +export type Confidence = + | "verified_on_build" + | "publisher_documented" + | "limited_sample" + | "cross_edition_unverified" + | "inferred" + | "disputed_or_stale"; +export type Observation_Text = | { clock_trust?: "trusted" | "uncertain"; observed_at_utc_ms?: UtcMillis | null; @@ -956,7 +951,7 @@ export type Observation_CompletionSemantics = | "reference_data" | "synthetic_fixture"; status: "known"; - value: CompletionSemantics; + value: Text; } | { clock_trust?: "trusted" | "uncertain"; @@ -975,8 +970,7 @@ export type Observation_CompletionSemantics = status: "unknown" | "unsupported" | "restricted" | "not_applicable"; value?: never; }; -export type CompletionSemantics = "unrepeatable" | "repeatable" | "reset_bound"; -export type Observation_ArrayOf_Position = +export type Observation_UtcMillis = | { clock_trust?: "trusted" | "uncertain"; observed_at_utc_ms?: UtcMillis | null; @@ -992,7 +986,7 @@ export type Observation_ArrayOf_Position = | "reference_data" | "synthetic_fixture"; status: "known"; - value: Position[]; + value: UtcMillis; } | { clock_trust?: "trusted" | "uncertain"; @@ -1011,7 +1005,7 @@ export type Observation_ArrayOf_Position = status: "unknown" | "unsupported" | "restricted" | "not_applicable"; value?: never; }; -export type Observation_ArrayOf_ItemKey = +export type Observation_BuildId = | { clock_trust?: "trusted" | "uncertain"; observed_at_utc_ms?: UtcMillis | null; @@ -1027,7 +1021,7 @@ export type Observation_ArrayOf_ItemKey = | "reference_data" | "synthetic_fixture"; status: "known"; - value: ItemKey[]; + value: BuildId; } | { clock_trust?: "trusted" | "uncertain"; @@ -1046,16 +1040,7 @@ export type Observation_ArrayOf_ItemKey = status: "unknown" | "unsupported" | "restricted" | "not_applicable"; value?: never; }; -export type RuleId = string; -export type DismissalPolicy = "session" | "until_ruleset_changes" | "permanent"; -export type RuleTrigger = - | "snapshot_changed" - | "level_changed" - | "equipment_changed" - | "location_changed" - | "preference_changed" - | "manual"; -export type Observation_FiniteNumber = +export type Observation_RecordMap_CapabilityId_CapabilityCheck = | { clock_trust?: "trusted" | "uncertain"; observed_at_utc_ms?: UtcMillis | null; @@ -1071,7 +1056,9 @@ export type Observation_FiniteNumber = | "reference_data" | "synthetic_fixture"; status: "known"; - value: FiniteNumber; + value: { + [k: string]: CapabilityCheck | undefined; + }; } | { clock_trust?: "trusted" | "uncertain"; @@ -1090,56 +1077,688 @@ export type Observation_FiniteNumber = status: "unknown" | "unsupported" | "restricted" | "not_applicable"; value?: never; }; -export type Ranking = "theoretical" | "obtainable" | "practical"; - -/** - * Deserialization is hand-written (see below) so unknown members are size - * checked as raw text before parsing, instead of buffering the whole envelope. - */ -export interface CharacterSnapshotEnvelope { - dependencies?: Dependencies; - /** - * True for synthetic engineering data. Production planning rejects it. - */ - fixture: boolean; - format: "azeroth-navigator"; - game: GameContext; - kind: "character_snapshot"; - namespace: DatasetNamespace; - payload: CharacterSnapshot; +export type ProviderId = string; +export type ProviderStatus = "available" | "unavailable" | "unverified" | "restricted"; +export type AcquisitionId = string; +export type AcquisitionKind = "quest" | "vendor" | "dungeon" | "crafting" | "other"; +export type Observation_Normalized = + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "known"; + value: Normalized; + } + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "unknown" | "unsupported" | "restricted" | "not_applicable"; + value?: never; + }; +export type EdgeId = string; +export type TravelMode = "walking" | "flight" | "boat" | "tram" | "teleport" | "return"; +export type EdgeStatus = "verified" | "estimated" | "temporarily_unavailable" | "unverified"; +export type Observation_ArrayOf_Text = + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "known"; + value: Text[]; + } + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "unknown" | "unsupported" | "restricted" | "not_applicable"; + value?: never; + }; +export type PinId = string; +export type PixelExtent = number; +export type ImageId = string; +export type LayerId = string; +export type ImageLayerKind = + ("terrain" | "other") | "roads_traced" | "flight_reference" | "overview"; +export type PinKind = + | { + access: FlightAccess[]; + kind: "flight_master"; + } + | { + kind: "settlement"; + } + | { + kind: "landmark"; + }; +export type FlightAccess = "alliance" | "horde" | "tower_route"; +export type Observation_CoordinateTransform = + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "known"; + value: CoordinateTransform; + } + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "unknown" | "unsupported" | "restricted" | "not_applicable"; + value?: never; + }; +export type Observation_ServiceKind = + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "known"; + value: ServiceKind; + } + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "unknown" | "unsupported" | "restricted" | "not_applicable"; + value?: never; + }; +export type ServiceKind = + "junction" | "vendor" | "repair" | "trainer" | "flight" | "transport" | "dungeon" | "other"; +export type ObjectiveTarget = + | { + kind: "quest_stage"; + quest: QuestId; + stage: ObjectiveId; + } + | { + kind: "acquisition"; + source: AcquisitionId; + } + | { + kind: "service"; + node: NodeRef; + }; +export type Observation_CompletionSemantics = + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "known"; + value: CompletionSemantics; + } + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "unknown" | "unsupported" | "restricted" | "not_applicable"; + value?: never; + }; +export type CompletionSemantics = "unrepeatable" | "repeatable" | "reset_bound"; +export type Observation_ArrayOf_Position = + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "known"; + value: Position[]; + } + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "unknown" | "unsupported" | "restricted" | "not_applicable"; + value?: never; + }; +export type Observation_ArrayOf_ItemKey = + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "known"; + value: ItemKey[]; + } + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "unknown" | "unsupported" | "restricted" | "not_applicable"; + value?: never; + }; +export type RuleId = string; +export type DismissalPolicy = "session" | "until_ruleset_changes" | "permanent"; +export type RuleTrigger = + | "snapshot_changed" + | "level_changed" + | "equipment_changed" + | "location_changed" + | "preference_changed" + | "manual"; +export type Observation_FiniteNumber = + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "known"; + value: FiniteNumber; + } + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "unknown" | "unsupported" | "restricted" | "not_applicable"; + value?: never; + }; +export type Ranking = "theoretical" | "obtainable" | "practical"; + +/** + * Deserialization is hand-written (see below) so unknown members are size + * checked as raw text before parsing, instead of buffering the whole envelope. + */ +export interface ProgressionSnapshotEnvelope { + dependencies?: Dependencies; + /** + * True for synthetic engineering data. Production planning rejects it. + */ + fixture: boolean; + format: "azeroth-navigator"; + game: GameContext; + kind: "progression_snapshot"; + namespace: DatasetNamespace; + payload: ProgressionSnapshot; producer: Producer; provenance: Provenance; schema_version: SchemaVersion; } /** - * Versions and inputs the payload was produced from. Absent fields and an - * empty snapshot list mean "no such dependency"; each kind fixes which apply. + * Versions and inputs the payload was produced from. Absent fields and an + * empty snapshot list mean "no such dependency"; each kind fixes which apply. + */ +export interface Dependencies { + dataset_revision?: DatasetRevision | null; + ruleset_version?: RulesetVersion | null; + score_model_version?: ScoreModelVersion | null; + snapshots?: SnapshotRef[]; +} +export interface SnapshotRef { + character: CharacterId; + context: DataContext; + id: SnapshotId; +} +export interface DataContext { + build: BuildKey; + namespace: DatasetNamespace; +} +export interface BuildKey { + build: BuildId; + edition: EditionId; + interface: InterfaceId; +} +export interface GameContext { + build: BuildId; + edition: EditionId; + interface: InterfaceId; + locale: Locale; +} +export interface ProgressionSnapshot { + available_talent_points: ObservationUint16; + /** + * Bags and bank are separate enumerations and never silently combined. + */ + bags: + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "known"; + value: Enumeration4; + } + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "unknown" | "unsupported" | "restricted" | "not_applicable"; + value?: never; + }; + bank: Observation_Enumeration4; + binding: SnapshotBinding; + capture: ObservationMetadata; + equipment_enhancements: { + [k: string]: Observation_EquipmentEnhancements | undefined; + }; + id: SnapshotId; + money: Observation_Copper; + payload_version: SchemaVersion; + professions: Observation_Enumeration2; + recipes: Observation_Enumeration3; + /** + * Keys identify exact source spell records; unknown rank is not rank zero. + */ + spells: + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "known"; + value: Enumeration; + } + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "unknown" | "unsupported" | "restricted" | "not_applicable"; + value?: never; + }; + talents: Observation_Enumeration; +} +/** + * Availability and capture metadata live on the enclosing Observation. An + * unavailable enumeration is never represented as an empty complete map. */ -export interface Dependencies { - dataset_revision?: DatasetRevision | null; - ruleset_version?: RulesetVersion | null; - score_model_version?: ScoreModelVersion | null; - snapshots?: SnapshotRef[]; +export interface Enumeration4 { + completeness: Completeness; + entries: { + [k: string]: InventoryQuantity | undefined; + }; } -export interface SnapshotRef { +export interface InventoryQuantity { + item: ItemKey; + /** + * Aggregated quantity within this one explicit scope. Never a bag index. + */ + quantity: + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "known"; + value: number; + } + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "unknown" | "unsupported" | "restricted" | "not_applicable"; + value?: never; + }; +} +export interface ItemKey { + context: DataContext; + item_id: ItemId; + variant: VariantId; +} +/** + * Exact predecessor identity for progression companions and saved advice. + * The I/O layer supplies the persisted snapshot hash; this module does not hash + * or normalize imported bytes and never accepts a nearest-build substitution. + */ +export interface SnapshotBinding { + capture: ObservationMetadata; character: CharacterId; context: DataContext; - id: SnapshotId; + snapshot: SnapshotId; + snapshot_sha256: Sha256Hex; + source_revision: DatasetRevision; } -export interface DataContext { - build: BuildKey; - namespace: DatasetNamespace; +export interface ObservationMetadata { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; } -export interface BuildKey { - build: BuildId; - edition: EditionId; - interface: InterfaceId; +export interface EquipmentEnhancements { + enhancements: Observation_Enumeration5; + item: ItemKey; } -export interface GameContext { - build: BuildId; - edition: EditionId; - interface: InterfaceId; - locale: Locale; +/** + * Availability and capture metadata live on the enclosing Observation. An + * unavailable enumeration is never represented as an empty complete map. + */ +export interface Enumeration5 { + completeness: Completeness; + entries: { + [k: string]: ObservedEnhancement | undefined; + }; +} +export interface ObservedEnhancement { + duration: Observation_EnhancementDuration; + /** + * Unreadable expiry remains unknown/restricted; no inferred duration. + */ + expires_at_utc_ms: + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "known"; + value: UtcMillis; + } + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "unknown" | "unsupported" | "restricted" | "not_applicable"; + value?: never; + }; +} +/** + * Availability and capture metadata live on the enclosing Observation. An + * unavailable enumeration is never represented as an empty complete map. + */ +export interface Enumeration2 { + completeness: Completeness; + entries: { + [k: string]: ProfessionState | undefined; + }; +} +export interface ProfessionState { + maximum_skill: ObservationUint16; + rank: Observation_SourceId; + skill: ObservationUint16; +} +/** + * Availability and capture metadata live on the enclosing Observation. An + * unavailable enumeration is never represented as an empty complete map. + */ +export interface Enumeration3 { + completeness: Completeness; + entries: { + [k: string]: ObservationBoolean | undefined; + }; +} +/** + * Availability and capture metadata live on the enclosing Observation. An + * unavailable enumeration is never represented as an empty complete map. + */ +export interface Enumeration { + completeness: Completeness; + entries: { + [k: string]: ObservationUint16 | undefined; + }; +} +export interface Producer { + component: ProducerComponent; + sequence?: Sequence | null; + session_id?: SessionId | null; + /** + * Producer application version; independent of schema and dataset versions. + */ + version: string; +} +export interface Provenance { + clock_trust: ClockTrust; + /** + * Absent means the producer recorded no creation time. + */ + created_at_utc_ms?: UtcMillis | null; + source: StateSource; +} +/** + * Deserialization is hand-written (see below) so unknown members are size + * checked as raw text before parsing, instead of buffering the whole envelope. + */ +export interface CharacterSnapshotEnvelope { + dependencies?: Dependencies; + /** + * True for synthetic engineering data. Production planning rejects it. + */ + fixture: boolean; + format: "azeroth-navigator"; + game: GameContext; + kind: "character_snapshot"; + namespace: DatasetNamespace; + payload: CharacterSnapshot; + producer: Producer; + provenance: Provenance; + schema_version: SchemaVersion; } export interface CharacterSnapshot { capture: ObservationMetadata; @@ -1164,21 +1783,6 @@ export interface CharacterSnapshot { schema_version: SchemaVersion; source_revision: DatasetRevision; } -export interface ObservationMetadata { - clock_trust?: "trusted" | "uncertain"; - observed_at_utc_ms?: UtcMillis | null; - received_at_utc_ms?: UtcMillis | null; - sequence?: Sequence | null; - session_elapsed_ms?: Millis | null; - session_id?: SessionId | null; - source?: - | "unrecorded" - | "addon_snapshot" - | "manual_entry" - | "official_api" - | "reference_data" - | "synthetic_fixture"; -} export interface EquippedItem { context: DataContext; instance: Observation_InstanceId; @@ -1215,23 +1819,6 @@ export interface QuestProgress { quest: QuestId; turned_in: ObservationBoolean; } -export interface Producer { - component: ProducerComponent; - sequence?: Sequence | null; - session_id?: SessionId | null; - /** - * Producer application version; independent of schema and dataset versions. - */ - version: string; -} -export interface Provenance { - clock_trust: ClockTrust; - /** - * Absent means the producer recorded no creation time. - */ - created_at_utc_ms?: UtcMillis | null; - source: StateSource; -} /** * Deserialization is hand-written (see below) so unknown members are size * checked as raw text before parsing, instead of buffering the whole envelope. @@ -1314,11 +1901,6 @@ export interface DurationRange { max_ms: Millis; min_ms: Millis; } -export interface ItemKey { - context: DataContext; - item_id: ItemId; - variant: VariantId; -} export interface SupportedArea { bounds?: Bounds | null; map: MapKey; diff --git a/tests/contract/check.mts b/tests/contract/check.mts index f0e0d70b..ad50057d 100644 --- a/tests/contract/check.mts +++ b/tests/contract/check.mts @@ -38,6 +38,7 @@ const manifest = readJson("fixtures/contracts/v1/manifest.json") as { fixtures: const envelopeDefs: Record = { character_snapshot: "CharacterSnapshotEnvelope", + progression_snapshot: "ProgressionSnapshotEnvelope", party_snapshot: "PartySnapshotEnvelope", route_plan: "RoutePlanEnvelope", evidence_bundle: "EvidenceBundleEnvelope", @@ -146,6 +147,11 @@ function summarize(doc: Exchange): string { const categories = new Set(snapshotCategories(doc.payload)); return `${label} snapshot: ${[...categories].sort().join(",")}`; } + case "progression_snapshot": { + check(doc.payload.payload_version === 1, "progression payload version"); + if (doc.payload.money.status === "known") check(copperIsCanonical(doc.payload.money.value), "progression copper stays a canonical string"); + return `${label} progression for ${doc.payload.binding.snapshot}: bags ${category(doc.payload.bags)}, bank ${category(doc.payload.bank)}`; + } case "party_snapshot": { const times = doc.payload.participants.map((p) => p.capture.observed_at_utc_ms ?? null); check(new Set(times).size === times.length, "participants keep individual capture times"); From 0bed7f4e598c17da8b77e880f5a3d0f8387cc0c8 Mon Sep 17 00:00:00 2001 From: Laymer Date: Tue, 10 Nov 2026 15:00:04 +0100 Subject: [PATCH 05/10] V110.4c: persist snapshot-bound progression companions --- TODO.md | 3 +- crates/storage/src/lib.rs | 2 + crates/storage/src/migrations.rs | 5 + crates/storage/src/progression.rs | 220 ++++++++++ crates/storage/src/recovery.rs | 2 + crates/storage/src/schema_v14.sql | 12 + crates/storage/tests/catalog_v2.rs | 2 +- .../storage/tests/local_state_foundation.rs | 2 +- crates/storage/tests/migrations.rs | 4 +- crates/storage/tests/progression.rs | 395 ++++++++++++++++++ crates/storage/tests/sessions.rs | 2 +- .../tests/source_identity_migration.rs | 4 +- docs/STATUS.md | 5 +- .../2026-11-10-v110-progression-storage.md | 8 + .../2026-11-10-v110-progression-storage.md | 61 +++ 15 files changed, 718 insertions(+), 9 deletions(-) create mode 100644 crates/storage/src/progression.rs create mode 100644 crates/storage/src/schema_v14.sql create mode 100644 crates/storage/tests/progression.rs create mode 100644 docs/claims/2026-11-10-v110-progression-storage.md create mode 100644 docs/handoffs/2026-11-10-v110-progression-storage.md diff --git a/TODO.md b/TODO.md index 7434ad51..a4a60268 100644 --- a/TODO.md +++ b/TODO.md @@ -10,7 +10,8 @@ below do not establish 1.1.0 readiness. - [ ] V110.3 Regenerate/review content; version gameplay facts and enforce coverage. - [ ] V110.4 Progression exchange, explicit addon/manual capture and persistence. V110.4a collection/binding and V110.4b versioned exchange implemented and checked; - storage/application/addon integration pending. + V110.4c companion persistence implemented and checked; + application/addon integration and saved workflow plans pending. - [ ] V110.5 Trainer spell service, saved plans and rendered workflow. - [ ] V110.6 Authored editable talents, validation and next-point workflow. - [ ] V110.7 Profession/crafting quantities, materials and acquisition workflow. diff --git a/crates/storage/src/lib.rs b/crates/storage/src/lib.rs index 7e1651bd..2c585cbf 100644 --- a/crates/storage/src/lib.rs +++ b/crates/storage/src/lib.rs @@ -56,3 +56,5 @@ pub mod local_submissions; pub mod today; pub mod local_data; + +pub mod progression; diff --git a/crates/storage/src/migrations.rs b/crates/storage/src/migrations.rs index 75c15f3c..6c151579 100644 --- a/crates/storage/src/migrations.rs +++ b/crates/storage/src/migrations.rs @@ -91,6 +91,11 @@ pub const MIGRATIONS: &[Migration] = &[ name: "durable content travel choices and versioned bundle defaults", sql: include_str!("schema_v13.sql"), }, + Migration { + version: 14, + name: "snapshot-bound progression companions", + sql: include_str!("schema_v14.sql"), + }, ]; /// The newest version in `MIGRATIONS`. diff --git a/crates/storage/src/progression.rs b/crates/storage/src/progression.rs new file mode 100644 index 00000000..6fa5d4b8 --- /dev/null +++ b/crates/storage/src/progression.rs @@ -0,0 +1,220 @@ +//! Immutable companion persistence. Selection is always tied to a validated +//! persisted character snapshot; manual records occupy a separate origin. +use crate::{ + ProfileKey, SqliteStore, + error::{SqliteResult, invalid, storage}, + hash::snapshot_content_hash, + sqlite::find_profile, +}; +use azeroth_core::{ + contract::{Envelope, MAX_ENVELOPE_BYTES, decode_envelope}, + entities::CharacterSnapshot, + error::Result, + observation::StateSource, + progression::ProgressionSnapshot, +}; +use rusqlite::{OptionalExtension, Transaction, TransactionBehavior, params}; +use serde::{Deserialize, Serialize}; +use sha2::{Digest, Sha256}; + +pub const MAX_PROGRESSION_RECORDS: usize = 128; +pub const MAX_PROGRESSION_BYTES: usize = 16 * 1024 * 1024; + +#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum ProgressionOrigin { + Imported, + Manual, +} +impl ProgressionOrigin { + fn name(self) -> &'static str { + match self { + Self::Imported => "imported", + Self::Manual => "manual", + } + } +} + +fn verify_origin( + envelope: &Envelope, + origin: ProgressionOrigin, +) -> Result<()> { + let source = if envelope.fixture { + StateSource::SyntheticFixture + } else { + match origin { + ProgressionOrigin::Imported => StateSource::AddonSnapshot, + ProgressionOrigin::Manual => StateSource::ManualEntry, + } + }; + if envelope.provenance.source != source || envelope.payload.capture.source != source { + return Err(invalid( + "Progression origin disagrees with capture provenance", + )); + } + // Predecessor capture is not a manual edit and retains its original source. + let mut payload = serde_json::to_value(&envelope.payload) + .map_err(|_| invalid("Invalid progression payload"))?; + payload + .as_object_mut() + .ok_or_else(|| invalid("Invalid progression payload"))? + .remove("binding"); + let source = serde_json::to_value(source).map_err(|_| invalid("Invalid progression source"))?; + fn sources(value: &serde_json::Value, expected: &serde_json::Value) -> bool { + match value { + serde_json::Value::Object(map) => { + let source = map.get("source"); + let known = map.get("status").and_then(|v| v.as_str()) == Some("known"); + (!map.contains_key("clock_trust") + || source == Some(expected) + || (!known && source.and_then(|v| v.as_str()) == Some("unrecorded"))) + && map.values().all(|v| sources(v, expected)) + } + serde_json::Value::Array(values) => values.iter().all(|v| sources(v, expected)), + _ => true, + } + } + if !sources(&payload, &source) { + return Err(invalid("Progression observations mix capture origins")); + } + Ok(()) +} + +fn validate_binding( + envelope: &Envelope, + parent: &str, + key: &ProfileKey, +) -> Result<()> { + let parent = decode_envelope::(parent)?; + if &ProfileKey::of(&parent) != key || envelope.fixture != key.fixture { + return Err(invalid("Progression profile differs from predecessor")); + } + envelope + .payload + .binding + .ensure_matches(&parent.payload, &snapshot_content_hash(&parent)?) +} + +impl SqliteStore { + /// Returns false for identical re-import, refuses same-ID replacement. + /// The immediate transaction excludes a concurrent predecessor selection. + pub fn save_progression( + &mut self, + key: &ProfileKey, + envelope: &Envelope, + origin: ProgressionOrigin, + ) -> Result { + let document = serde_json::to_string(envelope) + .map_err(|_| invalid("Progression cannot be serialized"))?; + if document.len() > MAX_ENVELOPE_BYTES { + return Err(invalid("Progression exceeds document capacity")); + } + let envelope = decode_envelope::(&document)?; + verify_origin(&envelope, origin)?; + let hash = format!("{:x}", Sha256::digest(document.as_bytes())); + let tx = self + .conn + .transaction_with_behavior(TransactionBehavior::Immediate) + .db()?; + let Some((profile, Some(parent))) = find_profile(&tx, key)? else { + return Err(invalid( + "Progression requires a selected character snapshot", + )); + }; + let predecessor: String = tx + .query_row( + "SELECT document FROM snapshots WHERE id=?1 AND profile_id=?2", + params![parent, profile], + |r| r.get(0), + ) + .db()?; + validate_binding(&envelope, &predecessor, key)?; + let previous: Option<(String,String)> = tx.query_row("SELECT content_sha256,document FROM progression_snapshots WHERE profile_id=?1 AND origin=?2 AND companion_id=?3", params![profile,origin.name(),envelope.payload.id.as_str()], |r|Ok((r.get(0)?,r.get(1)?))).optional().db()?; + if let Some((old_hash, old_document)) = previous { + if old_hash != hash || old_document != document { + return Err(invalid( + "Progression identity already has different content", + )); + } + return Ok(false); + } + let (count, bytes): (i64,i64) = tx.query_row("SELECT count(*),coalesce(sum(length(CAST(document AS BLOB))),0) FROM progression_snapshots WHERE profile_id=?1", [profile], |r|Ok((r.get(0)?,r.get(1)?))).db()?; + if count >= MAX_PROGRESSION_RECORDS as i64 + || bytes + document.len() as i64 > MAX_PROGRESSION_BYTES as i64 + { + return Err(invalid("Progression profile capacity exceeded")); + } + tx.execute("INSERT INTO progression_snapshots(profile_id,snapshot_row_id,origin,companion_id,content_sha256,document) VALUES(?1,?2,?3,?4,?5,?6)",params![profile,parent,origin.name(),envelope.payload.id.as_str(),hash,document]).db()?; + tx.commit().db()?; + Ok(true) + } + + /// All captures for the current predecessor, ordered by ID, not presumed + /// recency. Callers must evaluate freshness before selecting observations. + pub fn current_progression( + &self, + key: &ProfileKey, + origin: ProgressionOrigin, + ) -> Result>> { + // Reuse a caller-owned consistent read (for example with_immediate_read) + // so snapshot and companion queries can share one database view. + if !self.conn.is_autocommit() { + return self.read_progression(key, Some(origin)); + } + let tx = Transaction::new_unchecked(&self.conn, TransactionBehavior::Deferred).db()?; + let result = self.read_progression(key, Some(origin)); + tx.commit().db()?; + result + } + + /// With no origin filter, validate ALL history for recovery, not just current. + pub(crate) fn read_progression( + &self, + key: &ProfileKey, + origin: Option, + ) -> Result>> { + let Some((profile, current)) = find_profile(&self.conn, key)? else { + return Ok(Vec::new()); + }; + let mut statement = self.conn.prepare("SELECT p.origin,p.companion_id,p.content_sha256,p.document,s.document FROM progression_snapshots p JOIN snapshots s ON s.id=p.snapshot_row_id WHERE p.profile_id=?1 AND (?2 IS NULL OR (p.origin=?2 AND p.snapshot_row_id=?3)) ORDER BY p.origin,p.companion_id LIMIT ?4").db()?; + let mut rows = statement + .query(params![ + profile, + origin.map(ProgressionOrigin::name), + current, + MAX_PROGRESSION_RECORDS as i64 + 1 + ]) + .db()?; + let mut result = Vec::new(); + let mut bytes = 0; + while let Some(row) = rows.next().db()? { + let name: String = row.get(0).db()?; + let stored_origin = match name.as_str() { + "manual" => ProgressionOrigin::Manual, + "imported" => ProgressionOrigin::Imported, + _ => return Err(storage("Invalid stored progression origin")), + }; + let id: String = row.get(1).db()?; + let hash: String = row.get(2).db()?; + let document: String = row.get(3).db()?; + bytes += document.len(); + if result.len() >= MAX_PROGRESSION_RECORDS + || bytes > MAX_PROGRESSION_BYTES + || document.len() > MAX_ENVELOPE_BYTES + { + return Err(storage("Stored progression exceeds capacity")); + } + if format!("{:x}", Sha256::digest(document.as_bytes())) != hash { + return Err(storage("Stored progression hash disagrees")); + } + let envelope = decode_envelope::(&document)?; + if envelope.payload.id.as_str() != id { + return Err(storage("Stored progression identity disagrees")); + } + verify_origin(&envelope, stored_origin)?; + validate_binding(&envelope, &row.get::<_, String>(4).db()?, key)?; + result.push(envelope); + } + Ok(result) + } +} diff --git a/crates/storage/src/recovery.rs b/crates/storage/src/recovery.rs index 0bdc8ce1..80798200 100644 --- a/crates/storage/src/recovery.rs +++ b/crates/storage/src/recovery.rs @@ -24,6 +24,7 @@ fn row_limit(table: &str) -> usize { const TABLES: &[&str] = &[ "profiles", "snapshots", + "progression_snapshots", "snapshot_observations", "profile_preferences", "imports", @@ -450,6 +451,7 @@ fn validate_snapshot(store: &SqliteStore) -> Result<()> { } } for key in keys.values() { + store.read_progression(key, None)?; store.preferences(key)?; store.reminder_state(key)?; for id in store.session_ids(key)? { diff --git a/crates/storage/src/schema_v14.sql b/crates/storage/src/schema_v14.sql new file mode 100644 index 00000000..ea6d2efb --- /dev/null +++ b/crates/storage/src/schema_v14.sql @@ -0,0 +1,12 @@ +-- Immutable companions; manual state never replaces an imported observation. +-- Parent snapshot deletion/pruning also removes its now-unusable companions. +CREATE TABLE progression_snapshots ( + profile_id INTEGER NOT NULL REFERENCES profiles(id) ON DELETE CASCADE, + snapshot_row_id INTEGER NOT NULL REFERENCES snapshots(id) ON DELETE CASCADE, + origin TEXT NOT NULL CHECK (origin IN ('imported', 'manual')), + companion_id TEXT NOT NULL, + content_sha256 TEXT NOT NULL CHECK (length(content_sha256) = 64), + document TEXT NOT NULL CHECK (length(CAST(document AS BLOB)) <= 4194304), + PRIMARY KEY (profile_id, origin, companion_id) +) WITHOUT ROWID; +CREATE INDEX progression_parent ON progression_snapshots(snapshot_row_id, origin); diff --git a/crates/storage/tests/catalog_v2.rs b/crates/storage/tests/catalog_v2.rs index 5dab6023..84b817c2 100644 --- a/crates/storage/tests/catalog_v2.rs +++ b/crates/storage/tests/catalog_v2.rs @@ -50,7 +50,7 @@ fn migration_preserves_v1_bytes_hashes_and_pointer_then_rolls_between_versions() drop(store); let conn = raw(&db.path); let before:(String,String)=conn.query_row("SELECT document,content_sha256 FROM dataset_revisions JOIN dataset_manifests ON revision_id=id",[],|r|Ok((r.get(0)?,r.get(1)?))).unwrap(); - conn.execute_batch("DROP TABLE bundled_content_defaults; DROP TABLE content_travel_choices; DROP TABLE catalog_asset_layers; DROP TABLE catalog_asset_blobs; ALTER TABLE dataset_revisions DROP COLUMN content_version; DELETE FROM schema_migrations WHERE version>=11").unwrap(); + conn.execute_batch("DROP TABLE progression_snapshots; DROP TABLE bundled_content_defaults; DROP TABLE content_travel_choices; DROP TABLE catalog_asset_layers; DROP TABLE catalog_asset_blobs; ALTER TABLE dataset_revisions DROP COLUMN content_version; DELETE FROM schema_migrations WHERE version>=11").unwrap(); drop(conn); let mut store = SqliteStore::open(&db.path).unwrap(); let after:(String,String)=raw(&db.path).query_row("SELECT document,content_sha256 FROM dataset_revisions JOIN dataset_manifests ON revision_id=id",[],|r|Ok((r.get(0)?,r.get(1)?))).unwrap(); diff --git a/crates/storage/tests/local_state_foundation.rs b/crates/storage/tests/local_state_foundation.rs index edf1b9fa..c7896549 100644 --- a/crates/storage/tests/local_state_foundation.rs +++ b/crates/storage/tests/local_state_foundation.rs @@ -37,7 +37,7 @@ fn populated_v8_backfills_only_recorded_activations_and_preserves_immutable_byte .unwrap() .map(Result::unwrap) .collect(); - conn.execute_batch("DROP TABLE bundled_content_defaults; DROP TABLE content_travel_choices; DROP TABLE catalog_asset_layers; DROP TABLE catalog_asset_blobs; ALTER TABLE dataset_revisions DROP COLUMN content_version; DROP TABLE local_submissions; DROP TABLE current_plan; DROP TABLE app_settings; DROP TABLE content_dispositions; DELETE FROM schema_migrations WHERE version>=9").unwrap(); + conn.execute_batch("DROP TABLE progression_snapshots; DROP TABLE bundled_content_defaults; DROP TABLE content_travel_choices; DROP TABLE catalog_asset_layers; DROP TABLE catalog_asset_blobs; ALTER TABLE dataset_revisions DROP COLUMN content_version; DROP TABLE local_submissions; DROP TABLE current_plan; DROP TABLE app_settings; DROP TABLE content_dispositions; DELETE FROM schema_migrations WHERE version>=9").unwrap(); drop(conn); let store = SqliteStore::open(&db.path).unwrap(); assert_eq!( diff --git a/crates/storage/tests/migrations.rs b/crates/storage/tests/migrations.rs index da2a4ed5..6609022e 100644 --- a/crates/storage/tests/migrations.rs +++ b/crates/storage/tests/migrations.rs @@ -39,7 +39,7 @@ fn seed_profile(path: &std::path::Path) { fn fresh_in_memory_database_migrates_to_latest() { let store = SqliteStore::open_in_memory().unwrap(); assert_eq!(store.schema_version().unwrap(), latest_version()); - assert_eq!(latest_version(), 13); + assert_eq!(latest_version(), 14); } #[test] @@ -276,7 +276,7 @@ fn populated_v3_upgrades_preserving_content_parties_and_snapshot_documents() { // Reconstruct the exact v3 schema; v4 only adds this empty audit table. raw(&db.path) .execute_batch( - "DROP TABLE bundled_content_defaults; DROP TABLE content_travel_choices; DROP TABLE catalog_asset_layers; DROP TABLE catalog_asset_blobs; ALTER TABLE dataset_revisions DROP COLUMN content_version; DROP TABLE local_submissions; DROP TABLE current_plan; DROP TABLE app_settings; DROP TABLE content_dispositions; DROP TABLE party_plan_proposals; DROP TABLE session_calibration_annotations; DROP TABLE reminder_state; DROP TABLE sessions; DROP TABLE snapshot_promotions; DELETE FROM schema_migrations WHERE version >= 4;", + "DROP TABLE progression_snapshots; DROP TABLE bundled_content_defaults; DROP TABLE content_travel_choices; DROP TABLE catalog_asset_layers; DROP TABLE catalog_asset_blobs; ALTER TABLE dataset_revisions DROP COLUMN content_version; DROP TABLE local_submissions; DROP TABLE current_plan; DROP TABLE app_settings; DROP TABLE content_dispositions; DROP TABLE party_plan_proposals; DROP TABLE session_calibration_annotations; DROP TABLE reminder_state; DROP TABLE sessions; DROP TABLE snapshot_promotions; DELETE FROM schema_migrations WHERE version >= 4;", ) .unwrap(); let before = common::dump_state(&db.path); diff --git a/crates/storage/tests/progression.rs b/crates/storage/tests/progression.rs new file mode 100644 index 00000000..b450c057 --- /dev/null +++ b/crates/storage/tests/progression.rs @@ -0,0 +1,395 @@ +mod common; +use azeroth_core::{ + contract::{Envelope, decode_envelope}, + entities::CharacterSnapshot, + progression::{ProgressionSnapshot, SnapshotBinding}, +}; +use azeroth_storage::{ + ImportSource, ProfileKey, SnapshotStore, SqliteStore, + progression::{MAX_PROGRESSION_RECORDS, ProgressionOrigin}, + snapshot_content_hash, +}; +use common::{Doc, TempDb, raw}; +use serde_json::{Value, json}; + +fn companion(parent: &Envelope, id: &str) -> Envelope { + let mut value: Value = serde_json::from_str(include_str!( + "../../../fixtures/contracts/v1/progression-snapshot.json" + )) + .unwrap(); + value["payload"]["id"] = json!(id); + value["payload"]["binding"] = serde_json::to_value(SnapshotBinding::from_snapshot( + &parent.payload, + snapshot_content_hash(parent).unwrap(), + )) + .unwrap(); + value["dependencies"]["snapshots"][0] = json!({"id":parent.payload.id,"character":parent.payload.character,"context":parent.payload.context}); + value["dependencies"]["dataset_revision"] = json!(parent.payload.source_revision); + value["game"] = serde_json::to_value(&parent.game).unwrap(); + value["namespace"] = json!(parent.namespace); + value["payload"]["capture"]["source"] = json!("synthetic_fixture"); + fn mark(value: &mut Value) { + if let Value::Object(map) = value { + if map.contains_key("status") { + map.insert("source".into(), json!("synthetic_fixture")); + } + for item in map.values_mut() { + mark(item); + } + } + } + mark(&mut value["payload"]); + decode_envelope(&value.to_string()).unwrap() +} +fn seed(store: &mut SqliteStore) -> (Envelope, ProfileKey) { + let parent = Doc::base().decode(); + let key = ProfileKey::of(&parent); + store + .import_character_snapshot(&parent, ImportSource::Fixture, None) + .unwrap(); + (parent, key) +} + +#[test] +fn immutable_separate_origins_restart_and_snapshot_invalidation() { + let db = TempDb::new("progression"); + let mut store = SqliteStore::open(&db.path).unwrap(); + let (parent, key) = seed(&mut store); + let value = companion(&parent, "one"); + assert!( + store + .save_progression(&key, &value, ProgressionOrigin::Imported) + .unwrap() + ); + assert!( + !store + .save_progression(&key, &value, ProgressionOrigin::Imported) + .unwrap() + ); + assert!( + store + .current_progression(&key, ProgressionOrigin::Manual) + .unwrap() + .is_empty() + ); + assert!( + store + .save_progression(&key, &value, ProgressionOrigin::Manual) + .unwrap() + ); + let mut changed = serde_json::to_value(&value).unwrap(); + changed["payload"]["money"]["value"] = json!("1"); + let changed = decode_envelope(&changed.to_string()).unwrap(); + assert!( + store + .save_progression(&key, &changed, ProgressionOrigin::Imported) + .is_err() + ); + drop(store); + let mut store = SqliteStore::open(&db.path).unwrap(); + assert_eq!( + store + .current_progression(&key, ProgressionOrigin::Imported) + .unwrap(), + vec![value.clone()] + ); + assert_eq!( + store + .current_progression(&key, ProgressionOrigin::Manual) + .unwrap(), + vec![value.clone()] + ); + let combined = store + .with_immediate_read(|store| store.current_progression(&key, ProgressionOrigin::Imported)) + .unwrap(); + assert_eq!(combined, vec![value.clone()]); + let newer = Doc::base() + .snapshot_id("newer") + .session("demo-session-001", 13) + .elapsed(999999) + .decode(); + store + .import_character_snapshot(&newer, ImportSource::Fixture, None) + .unwrap(); + assert!( + store + .current_progression(&key, ProgressionOrigin::Imported) + .unwrap() + .is_empty() + ); + assert!( + store + .current_progression(&key, ProgressionOrigin::Manual) + .unwrap() + .is_empty() + ); + assert!( + store + .save_progression(&key, &value, ProgressionOrigin::Imported) + .is_err() + ); + assert!( + store + .save_progression(&key, &companion(&newer, "two"), ProgressionOrigin::Imported) + .unwrap() + ); + store.delete_profile(&key).unwrap(); + assert!( + store + .current_progression(&key, ProgressionOrigin::Imported) + .unwrap() + .is_empty() + ); + assert_eq!( + common::count(&db.path, "SELECT count(*) FROM progression_snapshots"), + 0 + ); +} + +#[test] +fn mismatch_missing_profile_and_provenance_fail_atomically() { + let mut store = SqliteStore::open_in_memory().unwrap(); + let parent = Doc::base().decode(); + let key = ProfileKey::of(&parent); + let value = companion(&parent, "one"); + assert!( + store + .save_progression(&key, &value, ProgressionOrigin::Imported) + .is_err() + ); + seed(&mut store); + for pointer in [ + "/payload/binding/snapshot_sha256", + "/payload/capture/source", + "/provenance/source", + "/payload/money/source", + ] { + let mut bad = serde_json::to_value(&value).unwrap(); + *bad.pointer_mut(pointer).unwrap() = if pointer.ends_with("sha256") { + json!("a".repeat(64)) + } else { + json!("unrecorded") + }; + if let Ok(bad) = decode_envelope::(&bad.to_string()) { + assert!( + store + .save_progression(&key, &bad, ProgressionOrigin::Imported) + .is_err(), + "{pointer}" + ); + } + } + let foreign = Doc::base().character("other").decode(); + assert!( + store + .save_progression( + &key, + &companion(&foreign, "two"), + ProgressionOrigin::Imported + ) + .is_err() + ); + assert!( + store + .current_progression(&key, ProgressionOrigin::Imported) + .unwrap() + .is_empty() + ); +} + +#[test] +fn capacity_is_bounded_and_duplicate_still_succeeds_at_limit() { + let mut store = SqliteStore::open_in_memory().unwrap(); + let (parent, key) = seed(&mut store); + for id in 0..MAX_PROGRESSION_RECORDS { + store + .save_progression( + &key, + &companion(&parent, &id.to_string()), + ProgressionOrigin::Imported, + ) + .unwrap(); + } + assert!( + !store + .save_progression(&key, &companion(&parent, "0"), ProgressionOrigin::Imported) + .unwrap() + ); + assert!( + store + .save_progression( + &key, + &companion(&parent, "overflow"), + ProgressionOrigin::Manual + ) + .is_err() + ); + assert_eq!( + store + .current_progression(&key, ProgressionOrigin::Imported) + .unwrap() + .len(), + MAX_PROGRESSION_RECORDS + ); +} + +#[test] +fn migration_backup_restore_and_corruption_checks() { + let db = TempDb::new("progression-migrate"); + let mut conn = raw(&db.path); + azeroth_storage::migrations::migrate_with( + &mut conn, + &azeroth_storage::migrations::MIGRATIONS[..13], + ) + .unwrap(); + conn.execute("INSERT INTO profiles(character_id,edition,build,interface,namespace,is_fixture) VALUES('kept','wow_forever','SYNTHETIC','SYNTHETIC','demo',1)",[]).unwrap(); + drop(conn); + let mut store = SqliteStore::open(&db.path).unwrap(); + assert_eq!(store.schema_version().unwrap(), 14); + assert_eq!(store.list_profiles().unwrap().len(), 1); + let (parent, key) = seed(&mut store); + let value = companion(&parent, "one"); + store + .save_progression(&key, &value, ProgressionOrigin::Imported) + .unwrap(); + let backup = TempDb::new("progression-backup"); + store.backup_to(&backup.path).unwrap(); + let restored = TempDb::new("progression-restore"); + azeroth_storage::recovery::reconstruct_backup(&backup.path, &restored.path).unwrap(); + let restored = SqliteStore::open(&restored.path).unwrap(); + assert_eq!( + restored + .current_progression(&key, ProgressionOrigin::Imported) + .unwrap(), + vec![value] + ); + raw(&db.path) + .execute( + "UPDATE progression_snapshots SET content_sha256=?1", + ["a".repeat(64)], + ) + .unwrap(); + assert!( + store + .current_progression(&key, ProgressionOrigin::Imported) + .is_err() + ); + let refused = TempDb::new("progression-bad-restore"); + assert!(azeroth_storage::recovery::reconstruct_backup(&db.path, &refused.path).is_err()); +} + +#[test] +fn production_manual_provenance_cannot_be_imported_or_mix_known_sources() { + let reference = Doc::reference().decode(); + let mut parent = serde_json::to_value(&reference).unwrap(); + parent["fixture"] = json!(false); + parent["producer"]["component"] = json!("addon"); + let parent: Envelope = decode_envelope( + &parent + .to_string() + .replace("synthetic_fixture", "addon_snapshot"), + ) + .unwrap(); + let mut store = SqliteStore::open_in_memory().unwrap(); + let key = ProfileKey::of(&parent); + store + .import_character_snapshot(&parent, ImportSource::Clipboard, None) + .unwrap(); + // Build from a synthetic reference, then explicitly switch only companion + // observations to manual; predecessor metadata remains original addon data. + let fixture = companion(&reference, "manual"); + let mut value = serde_json::to_value(&fixture).unwrap(); + value["fixture"] = json!(false); + value["producer"]["component"] = json!("desktop"); + let mut value: Value = serde_json::from_str( + &value + .to_string() + .replace("synthetic_fixture", "manual_entry"), + ) + .unwrap(); + value["payload"]["binding"] = serde_json::to_value(SnapshotBinding::from_snapshot( + &parent.payload, + snapshot_content_hash(&parent).unwrap(), + )) + .unwrap(); + let manual: Envelope = decode_envelope(&value.to_string()).unwrap(); + assert!( + store + .save_progression(&key, &manual, ProgressionOrigin::Imported) + .is_err() + ); + assert!( + store + .save_progression(&key, &manual, ProgressionOrigin::Manual) + .unwrap() + ); + value["payload"]["id"] = json!("mixed"); + value["payload"]["money"]["source"] = json!("addon_snapshot"); + let mixed = decode_envelope(&value.to_string()).unwrap(); + assert!( + store + .save_progression(&key, &mixed, ProgressionOrigin::Manual) + .is_err() + ); + value["payload"]["money"]["source"] = json!("unrecorded"); + let unrecorded = decode_envelope(&value.to_string()).unwrap(); + assert!( + store + .save_progression(&key, &unrecorded, ProgressionOrigin::Manual) + .is_err() + ); + assert_eq!( + store + .current_progression(&key, ProgressionOrigin::Manual) + .unwrap(), + vec![manual] + ); +} + +#[test] +fn recovery_validates_corrupt_noncurrent_companions_and_parent_profile() { + for corruption in ["companion_id", "parent_profile"] { + let db = TempDb::new(corruption); + let mut store = SqliteStore::open(&db.path).unwrap(); + let (parent, key) = seed(&mut store); + store + .save_progression( + &key, + &companion(&parent, "old"), + ProgressionOrigin::Imported, + ) + .unwrap(); + let newer = Doc::base() + .snapshot_id("newer") + .session("demo-session-001", 13) + .elapsed(999999) + .decode(); + store + .import_character_snapshot(&newer, ImportSource::Fixture, None) + .unwrap(); + let other = Doc::base().character("other").decode(); + store + .import_character_snapshot(&other, ImportSource::Fixture, None) + .unwrap(); + if corruption == "companion_id" { + raw(&db.path) + .execute( + "UPDATE progression_snapshots SET companion_id='altered'", + [], + ) + .unwrap(); + } else { + raw(&db.path).execute("UPDATE progression_snapshots SET snapshot_row_id=(SELECT s.id FROM snapshots s JOIN profiles p ON p.id=s.profile_id WHERE p.character_id='other')",[]).unwrap(); + } + // The active predecessor has no companion. Restore must still validate + // the entire retained history rather than checking only this view. + assert!( + store + .current_progression(&key, ProgressionOrigin::Imported) + .unwrap() + .is_empty() + ); + let dest = TempDb::new("refused-history"); + assert!(azeroth_storage::recovery::reconstruct_backup(&db.path, &dest.path).is_err()); + } +} diff --git a/crates/storage/tests/sessions.rs b/crates/storage/tests/sessions.rs index bb4b51ea..64b60954 100644 --- a/crates/storage/tests/sessions.rs +++ b/crates/storage/tests/sessions.rs @@ -119,7 +119,7 @@ fn populated_v4_upgrade_preserves_other_domains() { // Remove only the new empty table and migration marker to reconstruct the // exact previous schema with real populated domain records. let conn = common::raw(&db.path); - conn.execute_batch("DROP TABLE bundled_content_defaults; DROP TABLE content_travel_choices; DROP TABLE catalog_asset_layers; DROP TABLE catalog_asset_blobs; ALTER TABLE dataset_revisions DROP COLUMN content_version; DROP TABLE local_submissions; DROP TABLE current_plan; DROP TABLE app_settings; DROP TABLE content_dispositions; DROP TABLE party_plan_proposals; DROP TABLE session_calibration_annotations; DROP TABLE reminder_state; DROP TABLE sessions; DELETE FROM schema_migrations WHERE version>=5") + conn.execute_batch("DROP TABLE progression_snapshots; DROP TABLE bundled_content_defaults; DROP TABLE content_travel_choices; DROP TABLE catalog_asset_layers; DROP TABLE catalog_asset_blobs; ALTER TABLE dataset_revisions DROP COLUMN content_version; DROP TABLE local_submissions; DROP TABLE current_plan; DROP TABLE app_settings; DROP TABLE content_dispositions; DROP TABLE party_plan_proposals; DROP TABLE session_calibration_annotations; DROP TABLE reminder_state; DROP TABLE sessions; DELETE FROM schema_migrations WHERE version>=5") .unwrap(); let before = common::dump_state(&db.path); drop(conn); diff --git a/crates/storage/tests/source_identity_migration.rs b/crates/storage/tests/source_identity_migration.rs index dff585e7..ad2f9d8d 100644 --- a/crates/storage/tests/source_identity_migration.rs +++ b/crates/storage/tests/source_identity_migration.rs @@ -35,7 +35,7 @@ fn widen_source_bytes_preserves_every_row_tombstone_counter_and_foreign_key() { let mut conn = raw(&db.path); // Reconstruct the exact trusted old table rather than rewriting its migration. conn.execute_batch( - "DROP TABLE bundled_content_defaults; DROP TABLE content_travel_choices; DROP TABLE catalog_asset_layers; DROP TABLE catalog_asset_blobs; ALTER TABLE dataset_revisions DROP COLUMN content_version; DROP TABLE local_submissions; DELETE FROM schema_migrations WHERE version>=10", + "DROP TABLE progression_snapshots; DROP TABLE bundled_content_defaults; DROP TABLE content_travel_choices; DROP TABLE catalog_asset_layers; DROP TABLE catalog_asset_blobs; ALTER TABLE dataset_revisions DROP COLUMN content_version; DROP TABLE local_submissions; DELETE FROM schema_migrations WHERE version>=10", ) .unwrap(); let old = include_str!("../src/schema_v9.sql"); @@ -105,7 +105,7 @@ fn widen_source_bytes_preserves_every_row_tombstone_counter_and_foreign_key() { .is_err() ); migrate(&mut conn).unwrap(); - assert_eq!(latest_version(), 13); + assert_eq!(latest_version(), 14); assert_eq!(rows(&conn), before); conn.execute( insert, diff --git a/docs/STATUS.md b/docs/STATUS.md index c43f2c17..d0082841 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -15,7 +15,10 @@ V110.4a adds tested pure progression collection/binding primitives. See the confirms active wowf 1.60.1.70862; interface evidence is pending. Exchange/storage/UI, content refresh and all 1.1.0 release evidence remain pending. V110.4b adds the [versioned companion exchange](handoffs/2026-11-10-v110-progression-exchange.md), -bounded opt-in decoding and generated contracts; storage/application integration follows. +bounded opt-in decoding and generated contracts. V110.4c adds +[immutable companion storage](handoffs/2026-11-10-v110-progression-storage.md) with +manual/import separation and full-history recovery validation (190 storage tests pass). +Application/UI integration and saved workflow plans follow. See [tracker](../TODO.md), [claim](claims/2026-11-10-v110-contract.md) and [handoff](handoffs/2026-11-10-v110-contract.md). No 1.1.0 readiness is claimed. diff --git a/docs/claims/2026-11-10-v110-progression-storage.md b/docs/claims/2026-11-10-v110-progression-storage.md new file mode 100644 index 00000000..c8ba413f --- /dev/null +++ b/docs/claims/2026-11-10-v110-progression-storage.md @@ -0,0 +1,8 @@ +# V110.4c — bounded progression companion persistence + +Owner/sole writer Codex `/root`; baseline `9e1158e0`, isolated PR #297 branch. +Scope: additive SQLite migration 14, immutable snapshot-bound companions with +separate imported/manual provenance, current-snapshot filtering, deletion/backup/ +restore integration and focused regression tests. Plans and application UI follow. +Checks: migration/storage/recovery suites, Clippy, formatting, focused per-file +coverage and independent read-only review. No actual client or release claim. diff --git a/docs/handoffs/2026-11-10-v110-progression-storage.md b/docs/handoffs/2026-11-10-v110-progression-storage.md new file mode 100644 index 00000000..6250e725 --- /dev/null +++ b/docs/handoffs/2026-11-10-v110-progression-storage.md @@ -0,0 +1,61 @@ +# V110.4c — immutable companion persistence + +Owner/sole writer Codex `/root`; baseline `9e1158e0`; isolated PR #297 branch. +Claim: `docs/claims/2026-11-10-v110-progression-storage.md`. + +## Implemented + +Additive migration 14 stores immutable progression companions separately by imported +or manual origin. Saving validates exact selected predecessor metadata and the +existing canonical persisted snapshot hash inside an immediate transaction. Imported +captures require addon provenance; manual captures require manual provenance; +known nested observations cannot mix sources or lose provenance. Synthetic fixture +records remain explicitly synthetic. Same-ID changes refuse; exact repeats are no-ops. + +Reads revalidate documents, digests, identity, origins and predecessor binding. +Queries reuse a caller-owned transaction when present, allowing parent and +companion to share one consistent read. Current queries return only records for the current character snapshot, ordered +by ID without assuming recency. Changing the selected snapshot hides predecessor +companions. Profile deletion and snapshot pruning cascade. Limits: 128 records +and 16 MiB per profile, existing 4 MiB per document; capacity refusal is atomic. + +Recovery recognizes the new table and validates all retained companions, including +noncurrent history. Backup/restore, restart, schema13 upgrade, stale-parent refusal, +manual/import separation, capacity, identity conflicts and corruption are tested. +Historical downgrade-test setup removes the new table when reconstructing older +schemas; migration expectations now name 14. No historical schema was rewritten. + +## Actual verification + +- Full `cargo test --locked -p azeroth-storage`: 190 tests passed, including migration/recovery. + Final consistent-read integration then passed the six focused tests and Clippy. +- Six focused progression tests passed; new storage module llvm-cov line coverage + 159/169 = 94.08%. Coverage is focused engineering evidence, not full release proof. +- Storage all-target Clippy with warnings denied, fmt and whitespace passed. +- Application snapshot_workflow and local_state_recovery tests: 10 passed. +- Desktop `pnpm --dir apps/desktop typecheck` passed with expanded exchange types. +- Earlier failures: new test passed a table name to a SQL-count helper; fixed. + Historical downgrade fixtures initially retained migration14's table, and one + schema-version assertion still expected13; corrected before passing full rerun. + +## Independent review + +Read-only `/root/progression_review` inspected progression persistence, origin +checks and transaction reuse: no blockers; no independent test/coverage run. +Read-only `/root/recovery_review` separately inspected migration registration, +recovery copy/foreign-key/full-history validation and corruption/downgrade tests: +no blockers; whitespace passed, no independent test/coverage run. Combined review +covers both subsystems; neither review establishes live or release acceptance. + +## Remaining and next task + +Storage methods are not yet exposed by application/Tauri commands or UI. Companion +records do not yet include saved plans. Consumers still need field freshness, +equipment identity and authored fact/ruleset checks. Manual inputs do not mutate +addon observations; completion must never assert game-state changes. No live +capture, Lua parity, Windows acceptance or release readiness is established. + +Next: V110.4d application import/manual-input services and generated DTOs, then +saved plan dependencies and progression screen; continue V110.3 typed facts/content +and exact-build interface evidence independently. Existing 1.0.0 receipts do not +bind this changed product source. No merge/tag/publication in this task. From b656db00671b691286ff8eba058e211633775a16 Mon Sep 17 00:00:00 2001 From: Laymer Date: Tue, 10 Nov 2026 15:26:47 +0100 Subject: [PATCH 06/10] V110.4d: expose guarded progression import and manual capture commands --- Cargo.lock | 1 + TODO.md | 3 +- apps/desktop/src-tauri/src/command_tests.rs | 3 + apps/desktop/src-tauri/src/lib.rs | 34 + apps/desktop/src/commands/client.ts | 3 + apps/desktop/src/commands/contract.ts | 3 + apps/desktop/src/commands/demoAdapter.ts | 3 + apps/desktop/src/commands/progression.test.ts | 35 + crates/app/Cargo.toml | 1 + .../app/examples/export_progression_schema.rs | 4 + crates/app/src/lib.rs | 2 + crates/app/src/progression/dto.rs | 91 + crates/app/src/progression/manual.rs | 107 + crates/app/src/progression/mod.rs | 208 ++ crates/app/tests/progression.rs | 235 ++ crates/core/src/contract/schema.rs | 2 +- crates/core/src/observation.rs | 4 +- docs/STATUS.md | 3 +- ...2026-11-10-v110-progression-application.md | 8 + ...2026-11-10-v110-progression-application.md | 52 + .../desktop/native-boundaries/requests.json | 22 +- schemas/v1/README.md | 19 + schemas/v1/progression-api.schema.json | 3262 +++++++++++++++++ schemas/v1/progression-api.ts | 1258 +++++++ scripts/coverage/collect-rust.mjs | 1 + scripts/generate-contract-types.mjs | 12 +- tests/contract/check.mts | 15 + 27 files changed, 5380 insertions(+), 11 deletions(-) create mode 100644 apps/desktop/src/commands/progression.test.ts create mode 100644 crates/app/examples/export_progression_schema.rs create mode 100644 crates/app/src/progression/dto.rs create mode 100644 crates/app/src/progression/manual.rs create mode 100644 crates/app/src/progression/mod.rs create mode 100644 crates/app/tests/progression.rs create mode 100644 docs/claims/2026-11-10-v110-progression-application.md create mode 100644 docs/handoffs/2026-11-10-v110-progression-application.md create mode 100644 schemas/v1/progression-api.schema.json create mode 100644 schemas/v1/progression-api.ts diff --git a/Cargo.lock b/Cargo.lock index d93a2a11..4709c95e 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -90,6 +90,7 @@ dependencies = [ "azeroth-ingest", "azeroth-local-data", "azeroth-storage", + "schemars 1.2.2", "serde", "serde_json", "sha2", diff --git a/TODO.md b/TODO.md index a4a60268..ceba56a1 100644 --- a/TODO.md +++ b/TODO.md @@ -11,7 +11,8 @@ below do not establish 1.1.0 readiness. - [ ] V110.4 Progression exchange, explicit addon/manual capture and persistence. V110.4a collection/binding and V110.4b versioned exchange implemented and checked; V110.4c companion persistence implemented and checked; - application/addon integration and saved workflow plans pending. + V110.4d application/native commands implemented and checked; + UI/addon integration and saved workflow plans pending. - [ ] V110.5 Trainer spell service, saved plans and rendered workflow. - [ ] V110.6 Authored editable talents, validation and next-point workflow. - [ ] V110.7 Profession/crafting quantities, materials and acquisition workflow. diff --git a/apps/desktop/src-tauri/src/command_tests.rs b/apps/desktop/src-tauri/src/command_tests.rs index c0d1f4e9..d3abd5c2 100644 --- a/apps/desktop/src-tauri/src/command_tests.rs +++ b/apps/desktop/src-tauri/src/command_tests.rs @@ -27,6 +27,9 @@ fn command_handler() -> fn(tauri::ipc::Invoke) -> bool get_calibration, get_joint_planning_catalog, project_positions, + get_progression_view, + import_progression_text, + save_manual_progression, reminder_view, review_selected_local_guide, set_session_calibration, diff --git a/apps/desktop/src-tauri/src/lib.rs b/apps/desktop/src-tauri/src/lib.rs index ee0ca9d1..2411c264 100644 --- a/apps/desktop/src-tauri/src/lib.rs +++ b/apps/desktop/src-tauri/src/lib.rs @@ -659,6 +659,37 @@ async fn get_calibration( ) -> Result { blocking(state, move |app| app.get_calibration(&profile_id, &request)).await } +#[tauri::command(rename_all = "snake_case")] +async fn get_progression_view( + state: State<'_, Application>, + profile_id: String, +) -> Result { + blocking(state, move |app| { + app.progression_view(&profile_id, system_now()) + }) + .await +} +#[tauri::command] +async fn import_progression_text( + state: State<'_, Application>, + text: String, +) -> Result { + blocking(state, move |app| { + app.import_progression_text(&text, system_now()) + }) + .await +} +#[tauri::command] +async fn save_manual_progression( + state: State<'_, Application>, + text: String, +) -> Result { + blocking(state, move |app| { + app.save_manual_progression(&text, system_now()) + }) + .await +} + #[tauri::command(rename_all = "snake_case")] async fn reminder_view( state: State<'_, Application>, @@ -1293,6 +1324,9 @@ pub fn run() -> i32 { plan_joint_session, set_session_calibration, get_calibration, + get_progression_view, + import_progression_text, + save_manual_progression, reminder_view, mutate_reminders, inspect_plan_route, diff --git a/apps/desktop/src/commands/client.ts b/apps/desktop/src/commands/client.ts index 7299f198..ae8ed7a4 100644 --- a/apps/desktop/src/commands/client.ts +++ b/apps/desktop/src/commands/client.ts @@ -48,6 +48,9 @@ async function run(call: () => Promise): Promise> { /** Typed command wrappers: the only way UI code reaches the backend. */ export function createClient(adapter: CommandAdapter) { return { + getProgressionView: (profileId: string) => run(() => adapter.invoke("get_progression_view", { profile_id: profileId })), + importProgression: (request: import("../../../../schemas/v1/progression-api").ImportProgressionRequest) => run(() => adapter.invoke("import_progression_text", { text: JSON.stringify(request) })), + saveManualProgression: (request: import("../../../../schemas/v1/progression-api").ManualProgressionRequest) => run(() => adapter.invoke("save_manual_progression", { text: JSON.stringify(request) })), prepareResearchDelivery:(catalog:string,locale:string,bindings?:import("./localData").LocalDeliveryChoices)=>run(()=>adapter.invoke("prepare_research_delivery",{catalog,locale,...(bindings===undefined?{}:{bindings})})), getResearchDeliveryPage:(revision:string,domain:string,offset:number)=>run(()=>adapter.invoke("get_research_delivery_page",{revision,domain,offset,limit:200})), getResearchDeliveryActivation:(revision:string)=>run(()=>adapter.invoke("get_research_delivery_activation",{revision})), diff --git a/apps/desktop/src/commands/contract.ts b/apps/desktop/src/commands/contract.ts index dd40b5d3..cc42be98 100644 --- a/apps/desktop/src/commands/contract.ts +++ b/apps/desktop/src/commands/contract.ts @@ -275,6 +275,9 @@ export interface PlanningReport { /** Every command the UI may call. Each maps to one narrowly scoped Rust command. */ export interface CommandMap { + get_progression_view: { input: { profile_id: string }; output: import("../../../../schemas/v1/progression-api").ProgressionView }; + import_progression_text: { input: { text: string }; output: import("../../../../schemas/v1/progression-api").ProgressionReceipt }; + save_manual_progression: { input: { text: string }; output: import("../../../../schemas/v1/progression-api").ProgressionReceipt }; prepare_research_delivery:{input:{catalog:string;locale:string;bindings?:import("./localData").LocalDeliveryChoices};output:string}; get_research_delivery_page:{input:{revision:string;domain:string;offset:number;limit:number};output:import("./localData").ResearchDeliveryPage}; get_research_delivery_activation:{input:{revision:string};output:import("./localData").ResearchDeliveryActivation}; diff --git a/apps/desktop/src/commands/demoAdapter.ts b/apps/desktop/src/commands/demoAdapter.ts index f0a1efb8..23c09317 100644 --- a/apps/desktop/src/commands/demoAdapter.ts +++ b/apps/desktop/src/commands/demoAdapter.ts @@ -186,6 +186,9 @@ export const demoAdapter: CommandAdapter = { case "accept_party_plan": case "set_session_calibration": case "get_calibration": + case "get_progression_view": + case "import_progression_text": + case "save_manual_progression": case "reminder_view": case "mutate_reminders": case "get_gear_catalog": diff --git a/apps/desktop/src/commands/progression.test.ts b/apps/desktop/src/commands/progression.test.ts new file mode 100644 index 00000000..b9a3e520 --- /dev/null +++ b/apps/desktop/src/commands/progression.test.ts @@ -0,0 +1,35 @@ +import { createClient } from "./client"; +import { demoAdapter } from "./demoAdapter"; +import type { CommandAdapter } from "./contract"; +import type { ManualProgressionRequest } from "../../../../schemas/v1/progression-api"; +import fixture from "../../../../fixtures/contracts/v1/progression-snapshot.json"; + +const request: ManualProgressionRequest = { + profile_id: "selected-profile", + expected: fixture.payload.binding as ManualProgressionRequest["expected"], + id: "manual-one", + spells: {status:"unknown"}, money: {status:"known", value:"0"}, + talents: {status:"unknown"}, available_talent_points:{status:"known",value:0}, + professions: {status:"unknown"}, recipes:{status:"known",value:{completeness:"partial",entries:{recipe:false}}}, + bags:{status:"unknown"}, bank:{status:"unknown"}, equipment_enhancements:{}, +}; +it("transports expected binding and manual false/zero without inventing provenance", async () => { + const calls: {command:string;input:unknown}[] = []; + const adapter:CommandAdapter = {invoke(command,input) {calls.push({command,input}); return Promise.reject({code:"SNAPSHOT_OUTDATED",message:"Reload inputs",retryable:false});}}; + const client=createClient(adapter); + expect(await client.getProgressionView("selected-profile")).toEqual({ok:false,error:{code:"SNAPSHOT_OUTDATED",message:"Reload inputs",retryable:false}}); + await client.saveManualProgression(request); + const imported={profile_id:request.profile_id,expected:request.expected,text:"ANAV1:explicit-copied-input"}; + await client.importProgression(imported); + expect(calls).toEqual([ + {command:"get_progression_view",input:{profile_id:"selected-profile"}}, + {command:"save_manual_progression",input:{text:JSON.stringify(request)}}, + {command:"import_progression_text",input:{text:JSON.stringify(imported)}}, + ]); +}); +it("browser demo explicitly refuses persistent progression actions", async () => { + const client=createClient(demoAdapter); + for (const result of [await client.getProgressionView("demo"),await client.saveManualProgression(request),await client.importProgression({profile_id:request.profile_id,expected:request.expected,text:"ANAV1:input"})]) { + expect(result.ok).toBe(false); + } +}); diff --git a/crates/app/Cargo.toml b/crates/app/Cargo.toml index 9f37574a..0262b6ca 100644 --- a/crates/app/Cargo.toml +++ b/crates/app/Cargo.toml @@ -9,6 +9,7 @@ authors.workspace = true publish.workspace = true [dependencies] +schemars = "1" azeroth-core = { path = "../core" } azeroth-ingest = { path = "../ingest" } azeroth-storage = { path = "../storage" } diff --git a/crates/app/examples/export_progression_schema.rs b/crates/app/examples/export_progression_schema.rs new file mode 100644 index 00000000..51827f81 --- /dev/null +++ b/crates/app/examples/export_progression_schema.rs @@ -0,0 +1,4 @@ +//! Regenerate with cargo run --locked -p azeroth-app --example export_progression_schema. +fn main() { + print!("{}", azeroth_app::progression::api_schema_text()); +} diff --git a/crates/app/src/lib.rs b/crates/app/src/lib.rs index 47b583d9..5461b028 100644 --- a/crates/app/src/lib.rs +++ b/crates/app/src/lib.rs @@ -165,3 +165,5 @@ pub mod local_submissions; pub mod today; mod local_changes; + +pub mod progression; diff --git a/crates/app/src/progression/dto.rs b/crates/app/src/progression/dto.rs new file mode 100644 index 00000000..99ab8f45 --- /dev/null +++ b/crates/app/src/progression/dto.rs @@ -0,0 +1,91 @@ +use azeroth_core::{observation::Freshness, progression::*, types::*}; +use schemars::JsonSchema; +use serde::{Deserialize, Serialize}; + +/// Manual input has no caller-controlled provenance or observation metadata. +#[derive(Clone, Debug, Default, Serialize, Deserialize, JsonSchema)] +#[serde(tag = "status", rename_all = "snake_case", deny_unknown_fields)] +pub enum ManualValue { + #[default] + Unknown, + Known { + value: T, + }, +} +#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)] +#[serde(deny_unknown_fields)] +pub struct ManualProfession { + pub skill: Option, + pub maximum_skill: Option, + pub rank: Option, +} +#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)] +#[serde(deny_unknown_fields)] +pub struct ManualInventory { + pub item: ItemKey, + pub quantity: u32, +} +#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)] +#[serde(deny_unknown_fields)] +pub struct ManualEnhancement { + pub duration: Option, + pub expires_at_utc_ms: Option, +} +#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)] +#[serde(deny_unknown_fields)] +pub struct ManualEquipment { + pub item: ItemKey, + pub enhancements: ManualValue>, +} +#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)] +#[serde(deny_unknown_fields)] +pub struct ManualProgressionRequest { + pub profile_id: String, + pub expected: SnapshotBinding, + pub id: SnapshotId, + pub spells: ManualValue>, + pub money: ManualValue, + pub talents: ManualValue>, + pub available_talent_points: ManualValue, + pub professions: ManualValue>, + pub recipes: ManualValue>, + pub bags: ManualValue>, + pub bank: ManualValue>, + pub equipment_enhancements: RecordMap>, +} +#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)] +#[serde(deny_unknown_fields)] +pub struct ImportProgressionRequest { + pub profile_id: String, + pub expected: SnapshotBinding, + pub text: String, +} +#[derive(Clone, Debug, Serialize, JsonSchema)] +pub struct ProgressionRecord { + pub snapshot: ProgressionSnapshot, + pub freshness: Freshness, +} +#[derive(Clone, Debug, Serialize, JsonSchema)] +pub struct ProgressionView { + pub profile_id: String, + pub fixture: bool, + pub binding: SnapshotBinding, + pub imported: Vec, + pub manual: Vec, +} +#[derive(Clone, Debug, Serialize, JsonSchema)] +pub struct ProgressionReceipt { + pub profile_id: String, + pub snapshot_id: SnapshotId, + pub companion_id: SnapshotId, + pub stored: bool, + pub fixture: bool, +} +/// Schema generation root; this is not an executable command dispatcher. +#[derive(JsonSchema)] +pub struct ProgressionApi { + pub manual_request: ManualProgressionRequest, + pub import_request: ImportProgressionRequest, + pub view: ProgressionView, + pub receipt: ProgressionReceipt, +} diff --git a/crates/app/src/progression/manual.rs b/crates/app/src/progression/manual.rs new file mode 100644 index 00000000..26f6e3bc --- /dev/null +++ b/crates/app/src/progression/manual.rs @@ -0,0 +1,107 @@ +use super::dto::*; +use azeroth_core::{ + error::Result, + observation::{Observation, ObservationMetadata}, + progression::*, + types::*, +}; +use serde::Serialize; + +fn observed( + value: Option, + capture: &ObservationMetadata, +) -> Result> { + match value { + Some(value) => Observation::known(value, capture.clone()), + None => Observation::unavailable( + azeroth_core::observation::ObservationStatus::Unknown, + capture.clone(), + ), + } +} +fn value( + input: &ManualValue, + capture: &ObservationMetadata, + map: impl FnOnce(&T) -> Result, +) -> Result> { + observed( + match input { + ManualValue::Unknown => None, + ManualValue::Known { value } => Some(map(value)?), + }, + capture, + ) +} +fn enumeration( + input: &ManualValue>, + capture: &ObservationMetadata, + map: impl Fn(&T) -> Result, +) -> Result>> { + value(input, capture, |e| { + Ok(Enumeration { + completeness: e.completeness, + entries: RecordMap::new( + e.entries + .iter() + .map(|(k, v)| Ok((k.clone(), map(v)?))) + .collect::>>()?, + )?, + }) + }) +} +pub(super) fn payload( + input: &ManualProgressionRequest, + capture: ObservationMetadata, +) -> Result { + let c = &capture; + let inventory = |input: &ManualValue>| { + enumeration(input, c, |v| { + Ok(InventoryQuantity { + item: v.item.clone(), + quantity: observed(Some(v.quantity), c)?, + }) + }) + }; + ProgressionSnapshot::try_new(ProgressionSnapshotData { + payload_version: SchemaVersion, + id: input.id.clone(), + binding: input.expected.clone(), + capture: capture.clone(), + spells: enumeration(&input.spells, c, |v| observed(Some(*v), c))?, + money: value(&input.money, c, |v| Ok(*v))?, + talents: enumeration(&input.talents, c, |v| observed(Some(*v), c))?, + available_talent_points: value(&input.available_talent_points, c, |v| Ok(*v))?, + professions: enumeration(&input.professions, c, |v| { + Ok(ProfessionState { + skill: observed(v.skill, c)?, + maximum_skill: observed(v.maximum_skill, c)?, + rank: observed(v.rank.clone(), c)?, + }) + })?, + recipes: enumeration(&input.recipes, c, |v| observed(Some(*v), c))?, + bags: inventory(&input.bags)?, + bank: inventory(&input.bank)?, + equipment_enhancements: RecordMap::new( + input + .equipment_enhancements + .iter() + .map(|(slot, v)| { + Ok(( + slot.clone(), + value(v, c, |v| { + Ok(EquipmentEnhancements { + item: v.item.clone(), + enhancements: enumeration(&v.enhancements, c, |e| { + Ok(ObservedEnhancement { + duration: observed(e.duration, c)?, + expires_at_utc_ms: observed(e.expires_at_utc_ms, c)?, + }) + })?, + }) + })?, + )) + }) + .collect::>>()?, + )?, + }) +} diff --git a/crates/app/src/progression/mod.rs b/crates/app/src/progression/mod.rs new file mode 100644 index 00000000..361d208a --- /dev/null +++ b/crates/app/src/progression/mod.rs @@ -0,0 +1,208 @@ +//! Explicit profile-bound companion actions. No game I/O or state automation. +mod dto; +mod manual; +use crate::snapshots::{SnapshotApplication, context}; +use azeroth_core::{ + contract::*, + entities::{CharacterSnapshot, SnapshotRef}, + error::{AppError, ErrorCode, Result}, + observation::{ClockTrust, ObservationMetadata, StateSource, freshness}, + progression::SnapshotBinding, + types::*, +}; +use azeroth_ingest::import::{ImportOptions, import_text}; +use azeroth_storage::{ + ProfileKey, SnapshotStore, SqliteStore, progression::ProgressionOrigin, snapshot_content_hash, +}; +pub use dto::*; +use serde::de::DeserializeOwned; +use std::collections::BTreeSet; + +pub const MAX_PROGRESSION_REQUEST: usize = 8 * 1024 * 1024; +fn invalid(message: &'static str) -> AppError { + AppError::new(ErrorCode::InvalidInput, message, false) +} +fn parse(text: &str) -> Result { + if text.len() > MAX_PROGRESSION_REQUEST { + return Err(AppError::new( + ErrorCode::ImportTooLarge, + "Progression request exceeds capacity", + false, + )); + } + if !azeroth_ingest::anav1::json_depth_within(text, 32) { + return Err(invalid("Progression request exceeds nesting limit")); + } + let value = azeroth_core::strict_json::value(text.as_bytes(), MAX_PROGRESSION_REQUEST) + .map_err(|_| invalid("Invalid progression request"))?; + serde_json::from_value(value).map_err(|_| invalid("Invalid progression request")) +} +fn parent(store: &SqliteStore, key: &ProfileKey) -> Result> { + store + .current_snapshot(key)? + .ok_or_else(|| invalid("Progression requires a current character snapshot")) +} +fn expected(parent: &Envelope, expected: &SnapshotBinding) -> Result<()> { + expected + .ensure_matches(&parent.payload, &snapshot_content_hash(parent)?) + .map_err(|_| { + AppError::new( + ErrorCode::SnapshotOutdated, + "Selected character snapshot changed; reload progression inputs", + false, + ) + }) +} +fn receipt( + profile_id: &str, + parent: &Envelope, + id: SnapshotId, + stored: bool, +) -> ProgressionReceipt { + ProgressionReceipt { + profile_id: profile_id.into(), + snapshot_id: parent.payload.id.clone(), + companion_id: id, + stored, + fixture: parent.fixture, + } +} +impl SnapshotApplication { + pub fn progression_view(&self, id: &str, now: Option) -> Result { + self.with_profile_store_mut(id, |store, key| { + store.with_immediate_read(|store| { + let parent = parent(store, key)?; + let records = |origin| { + store + .current_progression(key, origin)? + .into_iter() + .map(|e| { + Ok(ProgressionRecord { + freshness: freshness(&e.payload.capture, &context(now)), + snapshot: e.payload.clone(), + }) + }) + .collect::>>() + }; + Ok(ProgressionView { + profile_id: id.into(), + fixture: key.fixture, + binding: SnapshotBinding::from_snapshot( + &parent.payload, + snapshot_content_hash(&parent)?, + ), + imported: records(ProgressionOrigin::Imported)?, + manual: records(ProgressionOrigin::Manual)?, + }) + }) + }) + } + pub fn import_progression_text( + &self, + text: &str, + now: Option, + ) -> Result { + let request: ImportProgressionRequest = parse(text)?; + let imported = import_text( + &request.text, + &ImportOptions { + accepted_kinds: BTreeSet::from([ContractKind::ProgressionSnapshot]), + freshness: context(now), + }, + )?; + let AnyExchange::ProgressionSnapshot(envelope) = imported.exchange else { + return Err(invalid("Expected a progression companion")); + }; + self.with_profile_store_mut(&request.profile_id, |store, key| { + let parent = parent(store, key)?; + expected(&parent, &request.expected)?; + // Require both UI expectation and companion binding to select the same predecessor. + expected(&parent, &envelope.payload.binding)?; + let stored = store.save_progression(key, &envelope, ProgressionOrigin::Imported)?; + Ok(receipt( + &request.profile_id, + &parent, + envelope.payload.id.clone(), + stored, + )) + }) + } + pub fn save_manual_progression( + &self, + text: &str, + now: Option, + ) -> Result { + let request: ManualProgressionRequest = parse(text)?; + self.with_profile_store_mut(&request.profile_id, |store, key| { + let parent = parent(store, key)?; + expected(&parent, &request.expected)?; + let source = if parent.fixture { + StateSource::SyntheticFixture + } else { + StateSource::ManualEntry + }; + let capture = ObservationMetadata { + source, + clock_trust: if now.is_some() { + ClockTrust::Trusted + } else { + ClockTrust::Uncertain + }, + observed_at_utc_ms: now, + ..Default::default() + }; + let payload = manual::payload(&request, capture.clone())?; + let envelope = Envelope::try_new(EnvelopeData { + format: FormatTag, + kind: KindTag::new(), + schema_version: SchemaVersion, + fixture: parent.fixture, + producer: Producer { + component: ProducerComponent::Desktop, + version: Text::new(env!("CARGO_PKG_VERSION"))?, + session_id: None, + sequence: None, + }, + game: parent.game.clone(), + namespace: parent.namespace, + provenance: Provenance { + source, + clock_trust: capture.clock_trust, + created_at_utc_ms: now, + }, + dependencies: Dependencies { + dataset_revision: Some(parent.payload.source_revision.clone()), + snapshots: vec![SnapshotRef { + id: parent.payload.id.clone(), + character: parent.payload.character.clone(), + context: parent.payload.context.clone(), + }], + ..Default::default() + }, + payload, + extensions: Default::default(), + })?; + let stored = store.save_progression(key, &envelope, ProgressionOrigin::Manual)?; + Ok(receipt( + &request.profile_id, + &parent, + request.id.clone(), + stored, + )) + }) + } +} +pub fn api_schema_text() -> String { + let schema = schemars::generate::SchemaSettings::draft2020_12() + .into_generator() + .into_root_schema_for::(); + let mut value = serde_json::to_value(schema).expect("schema serializes"); + value["$id"] = serde_json::json!( + "https://github.com/Laymer/Navzeroth/schemas/v1/progression-api.schema.json" + ); + azeroth_core::contract::schema::strip_numeric_formats(&mut value); + format!( + "{}\n", + serde_json::to_string_pretty(&value).expect("schema serializes") + ) +} diff --git a/crates/app/tests/progression.rs b/crates/app/tests/progression.rs new file mode 100644 index 00000000..31fbe49b --- /dev/null +++ b/crates/app/tests/progression.rs @@ -0,0 +1,235 @@ +use azeroth_app::{progression::*, snapshots::SnapshotApplication}; +use azeroth_core::{ + error::ErrorCode, + observation::{Freshness, StateSource}, + types::UtcMillis, +}; +use serde_json::{Value, json}; +fn parent(id: &str, sequence: u64) -> Value { + let mut v: Value = serde_json::from_str(include_str!( + "../../../fixtures/contracts/v1/character-snapshot.json" + )) + .unwrap(); + v["payload"]["id"] = json!(id); + v["payload"]["capture"]["sequence"] = json!(sequence); + v["producer"]["sequence"] = json!(sequence); + v +} +fn seed(app: &SnapshotApplication) -> String { + app.import_text(&format!("ANAV1:{}", parent("one", 12)), None) + .unwrap() + .profile_id +} +fn request(app: &SnapshotApplication, id: &str) -> Value { + let view = app.progression_view(id, None).unwrap(); + let u = json!({"status":"unknown"}); + json!({"profile_id":id,"expected":view.binding,"id":"manual-one","spells":u,"money":u,"talents":u,"available_talent_points":u,"professions":u,"recipes":u,"bags":u,"bank":u,"equipment_enhancements":{}}) +} +fn known(v: Value) -> Value { + json!({"status":"known","value":v}) +} +fn enumeration(entries: Value) -> Value { + known(json!({"completeness":"partial","entries":entries})) +} + +#[test] +fn manual_full_capture_preserves_zero_false_partial_and_stamps_provenance() { + let app = SnapshotApplication::in_memory().unwrap(); + let id = seed(&app); + let mut r = request(&app, &id); + let item = json!({"context":r["expected"]["context"],"item_id":"item","variant":"base"}); + r["money"] = known(json!("0")); + r["available_talent_points"] = known(json!(0)); + r["spells"] = enumeration(json!({"spell":0})); + r["talents"] = enumeration(json!({"talent":0})); + r["recipes"] = enumeration(json!({"recipe":false})); + r["professions"] = enumeration(json!({"profession":{"skill":0,"maximum_skill":0,"rank":null}})); + r["bags"] = enumeration(json!({"stack":{"item":item,"quantity":0}})); + r["bank"] = known(json!({"completeness":"complete","entries":{}})); + r["equipment_enhancements"] = json!({"main_hand":known(json!({"item":item,"enhancements":enumeration(json!({"effect":{"duration":"temporary","expires_at_utc_ms":0},"unknown":{"duration":null,"expires_at_utc_ms":null}}))})),"off_hand":{"status":"unknown"}}); + let now = Some(UtcMillis::new(1000).unwrap()); + assert!( + app.save_manual_progression(&r.to_string(), now) + .unwrap() + .stored + ); + assert!( + !app.save_manual_progression(&r.to_string(), now) + .unwrap() + .stored + ); + let view = app.progression_view(&id, now).unwrap(); + assert!(view.imported.is_empty()); + assert_eq!(view.manual.len(), 1); + assert!(matches!(view.manual[0].freshness, Freshness::Fresh { .. })); + let s = &view.manual[0].snapshot; + assert_eq!(s.money.value().unwrap().get(), 0); + assert_eq!(s.money.metadata().source, StateSource::SyntheticFixture); + assert_eq!( + s.recipes + .value() + .unwrap() + .entries + .values() + .next() + .unwrap() + .value(), + Some(&false) + ); + assert_eq!(s.bank.value().unwrap().entries.len(), 0); + assert!(matches!( + app.progression_view(&id, None).unwrap().manual[0].freshness, + Freshness::Uncertain { .. } + )); + assert!(matches!( + app.progression_view(&id, Some(UtcMillis::new(2_000_000).unwrap())) + .unwrap() + .manual[0] + .freshness, + Freshness::Stale { .. } + )); +} + +#[test] +fn request_validation_and_stale_guards_leave_prior_records_unchanged() { + let app = SnapshotApplication::in_memory().unwrap(); + let id = seed(&app); + let r = request(&app, &id); + app.save_manual_progression(&r.to_string(), None).unwrap(); + for (field, value) in [ + ("profile_id", json!("missing")), + ( + "money", + json!({"status":"known","value":"1","source":"addon_snapshot"}), + ), + ("spells", enumeration(json!({"spell":-1}))), + ] { + let mut bad = r.clone(); + bad[field] = value; + assert!(app.save_manual_progression(&bad.to_string(), None).is_err()); + } + assert!(app.save_manual_progression("{}", None).is_err()); + assert!( + app.save_manual_progression("{\"id\":1,\"id\":2}", None) + .is_err() + ); + assert!(app.save_manual_progression(&"[".repeat(33), None).is_err()); + assert_eq!( + app.save_manual_progression(&"x".repeat(MAX_PROGRESSION_REQUEST + 1), None) + .unwrap_err() + .code, + ErrorCode::ImportTooLarge + ); + let mut bad = r.clone(); + bad["professions"] = enumeration(json!({"p":{"skill":2,"maximum_skill":1,"rank":null}})); + assert!(app.save_manual_progression(&bad.to_string(), None).is_err()); + assert_eq!(app.progression_view(&id, None).unwrap().manual.len(), 1); + app.import_text(&format!("ANAV1:{}", parent("two", 13)), None) + .unwrap(); + assert_eq!( + app.save_manual_progression(&r.to_string(), None) + .unwrap_err() + .code, + ErrorCode::SnapshotOutdated + ); + assert!(app.progression_view(&id, None).unwrap().manual.is_empty()); +} + +#[test] +fn imported_companion_requires_opt_in_identity_and_stays_separate() { + let app = SnapshotApplication::in_memory().unwrap(); + let id = seed(&app); + let r = request(&app, &id); + app.save_manual_progression(&r.to_string(), None).unwrap(); + let view = app.progression_view(&id, None).unwrap(); + let mut envelope: Value = serde_json::from_str(include_str!( + "../../../fixtures/contracts/v1/progression-snapshot.json" + )) + .unwrap(); + envelope["payload"] = serde_json::to_value(&view.manual[0].snapshot).unwrap(); + envelope["producer"] + .as_object_mut() + .unwrap() + .remove("session_id"); + envelope["producer"] + .as_object_mut() + .unwrap() + .remove("sequence"); + envelope["dependencies"]["snapshots"][0]["id"] = json!("one"); + let input = json!({"profile_id":id,"expected":view.binding,"text":format!("ANAV1:{envelope}")}); + let first = app + .import_progression_text(&input.to_string(), None) + .unwrap(); + assert!(first.stored); + assert!( + !app.import_progression_text(&input.to_string(), None) + .unwrap() + .stored + ); + let view = app.progression_view(&id, None).unwrap(); + assert_eq!(view.manual.len(), 1); + assert_eq!(view.imported.len(), 1); + let mut bad = input.clone(); + bad["text"] = json!(format!("ANAV1:{}", parent("one", 12))); + assert!(app.import_progression_text(&bad.to_string(), None).is_err()); + let mut bad = input.clone(); + bad["expected"]["snapshot_sha256"] = json!("a".repeat(64)); + assert_eq!( + app.import_progression_text(&bad.to_string(), None) + .unwrap_err() + .code, + ErrorCode::SnapshotOutdated + ); + envelope["payload"]["binding"]["snapshot_sha256"] = json!("b".repeat(64)); + bad = input; + bad["text"] = json!(format!("ANAV1:{envelope}")); + assert_eq!( + app.import_progression_text(&bad.to_string(), None) + .unwrap_err() + .code, + ErrorCode::SnapshotOutdated + ); +} + +#[test] +fn production_manual_source_is_assigned_by_service_and_survives_restart() { + let path = std::env::temp_dir().join(format!( + "navzeroth-progression-app-{}.sqlite", + std::process::id() + )); + let app = SnapshotApplication::open(&path).unwrap(); + let mut p = parent("production", 12); + p["fixture"] = json!(false); + p["namespace"] = json!("reference"); + p["payload"]["context"]["namespace"] = json!("reference"); + p["producer"]["component"] = json!("addon"); + let text = format!("ANAV1:{p}") + .replace("synthetic_fixture", "addon_snapshot") + .replace("\"namespace\":\"demo\"", "\"namespace\":\"reference\""); + let id = app.import_text(&text, None).unwrap().profile_id; + let mut r = request(&app, &id); + r["money"] = known(json!("0")); + app.save_manual_progression(&r.to_string(), None).unwrap(); + drop(app); + let app = SnapshotApplication::open(&path).unwrap(); + let view = app.progression_view(&id, None).unwrap(); + assert!(!view.fixture); + assert_eq!( + view.manual[0].snapshot.money.metadata().source, + StateSource::ManualEntry + ); + assert_eq!( + view.manual[0].snapshot.capture.source, + StateSource::ManualEntry + ); + drop(app); + std::fs::remove_file(path).unwrap(); +} + +#[test] +fn generated_progression_api_schema_matches_committed() { + assert_eq!( + api_schema_text(), + include_str!("../../../schemas/v1/progression-api.schema.json") + ); +} diff --git a/crates/core/src/contract/schema.rs b/crates/core/src/contract/schema.rs index cee91c18..d49407c3 100644 --- a/crates/core/src/contract/schema.rs +++ b/crates/core/src/contract/schema.rs @@ -39,7 +39,7 @@ pub fn exchange_schema() -> Value { /// schemars annotates primitive integers with non-standard formats such as /// "int16"; their ranges are already explicit, and default JSON Schema /// validators reject unknown formats, so they are removed. -fn strip_numeric_formats(value: &mut Value) { +pub fn strip_numeric_formats(value: &mut Value) { match value { Value::Object(o) => { if o.get("format").and_then(Value::as_str).is_some_and(|f| { diff --git a/crates/core/src/observation.rs b/crates/core/src/observation.rs index ae2bd48b..610dbba1 100644 --- a/crates/core/src/observation.rs +++ b/crates/core/src/observation.rs @@ -213,14 +213,14 @@ pub struct FreshnessContext { pub session: Option<(SessionId, Millis)>, pub max_age_ms: Millis, } -#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] #[serde(rename_all = "snake_case")] pub enum ClockUncertainty { MissingOrUntrustedTime, ClockReversed, AgeOutOfRange, } -#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] #[serde(tag = "status", rename_all = "snake_case")] pub enum Freshness { Fresh { age_ms: Millis }, diff --git a/docs/STATUS.md b/docs/STATUS.md index d0082841..db14ec56 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -18,7 +18,8 @@ content refresh and all 1.1.0 release evidence remain pending. V110.4b adds the bounded opt-in decoding and generated contracts. V110.4c adds [immutable companion storage](handoffs/2026-11-10-v110-progression-storage.md) with manual/import separation and full-history recovery validation (190 storage tests pass). -Application/UI integration and saved workflow plans follow. +V110.4d adds [application commands and generated DTOs](handoffs/2026-11-10-v110-progression-application.md). +UI integration and saved workflow plans follow. See [tracker](../TODO.md), [claim](claims/2026-11-10-v110-contract.md) and [handoff](handoffs/2026-11-10-v110-contract.md). No 1.1.0 readiness is claimed. diff --git a/docs/claims/2026-11-10-v110-progression-application.md b/docs/claims/2026-11-10-v110-progression-application.md new file mode 100644 index 00000000..516cc6d3 --- /dev/null +++ b/docs/claims/2026-11-10-v110-progression-application.md @@ -0,0 +1,8 @@ +# V110.4d — progression application commands and manual inputs + +Owner/sole writer Codex `/root`; baseline `0bed7f4e`, isolated PR #297 branch. +Scope: bounded application input DTOs, generated progression API types/schema, +consistent profile-bound views, explicit import/manual capture commands, native +registration and frontend typed wrappers. UI integration follows after commands. +Checks: app tests, schema drift/typecheck, native command fixture registration, +focused coverage, Clippy/fmt and independent read-only review. No live claims. diff --git a/docs/handoffs/2026-11-10-v110-progression-application.md b/docs/handoffs/2026-11-10-v110-progression-application.md new file mode 100644 index 00000000..78802bf6 --- /dev/null +++ b/docs/handoffs/2026-11-10-v110-progression-application.md @@ -0,0 +1,52 @@ +# V110.4d — application progression commands + +Owner/sole writer Codex `/root`; baseline `0bed7f4e`; isolated PR #297 branch. +Claim: `docs/claims/2026-11-10-v110-progression-application.md`. + +## Implemented + +Three application/native commands: get_progression_view, import_progression_text, +save_manual_progression. Views obtain predecessor and both origins in one consistent +read. Both mutations check the expected exact binding; storage rechecks selected +predecessor atomically. Wrong-profile/stale UI/companion identities refuse. + +Manual DTOs contain values and completeness, never caller-supplied provenance. +The service assigns manual source/capture metadata (synthetic for fixture profiles), +preserves unknown/zero/false and separate bags/bank/equipment scopes, and validates +all resulting domain invariants. Missing trusted boundary time stays uncertain. +Records remain immutable; refreshing a manual capture requires a new companion ID. +No imported observation is overwritten or promoted by manual input. + +New progression-api schema/TypeScript are generated from Rust. The existing TS +generator now regenerates both artifacts. Rust tests enforce schema drift; AJV +checks manual provenance refusal and unknown/complete semantics. Native handlers +use blocking database-host dispatch; command-map wrappers preserve safe errors. +Browser demo explicitly refuses persistent progression commands. + +## Actual checks + +- Five progression app tests plus ten snapshot/recovery regression tests passed. +- Desktop: 557 unit tests, typecheck and lint passed. +- 74 exchange fixtures and new progression API schema constraints passed. +- Existing core contract-schema tests passed; exchange v1 output unchanged. +- App all-target Clippy, formatting and whitespace passed. +- Focused llvm-cov: manual.rs 92/97 lines (94.85%), mod.rs 173/176 (98.30%). + Schema exporter explicitly executed with instrumentation and added to the hosted + coverage collector. Full release coverage/Windows acceptance is not claimed. +- Read-only reviewer app_progression_review found no blocking logic issue and + identified missing schema-exporter coverage execution; repaired in collector. + Reviewer inspected native registration/wrappers and whitespace, did not run tests. +- Coverage tooling tests: five passed after sandbox EPERM spawning Node was rerun + with escalation. An initial regression command named nonexistent test `boundary`; + corrected to the actual progression/snapshot_workflow/local_state_recovery targets. + +Initial compile corrected wrong depth-helper module and SchemaVersion constructor +before passing checks. New schemars dependency uses already-pinned version1.2.2; +no dependency version changed. Native Windows new handlers remain pending hosted +verification; no interactive/live-game verification. + +## Next + +Expose these commands in progression/manual-input UI, then implement saved plan +binding and the four guidance services with versioned gameplay facts. Exact70862 +interface evidence/content refresh remain pending. No merge/tag/publication. diff --git a/fixtures/desktop/native-boundaries/requests.json b/fixtures/desktop/native-boundaries/requests.json index 6aa38b3d..88c500c3 100644 --- a/fixtures/desktop/native-boundaries/requests.json +++ b/fixtures/desktop/native-boundaries/requests.json @@ -104,7 +104,9 @@ "command": "activate_content_set", "args": { "profile_id": "invalid", - "revisions": ["synthetic-missing-revision"], + "revisions": [ + "synthetic-missing-revision" + ], "accept_inferred_travel": true } }, @@ -765,5 +767,23 @@ "mode": "later", "completed": true } + }, + { + "command": "get_progression_view", + "args": { + "profile_id": "invalid" + } + }, + { + "command": "import_progression_text", + "args": { + "text": "{}" + } + }, + { + "command": "save_manual_progression", + "args": { + "text": "{}" + } } ] diff --git a/schemas/v1/README.md b/schemas/v1/README.md index 86ec5d16..8a8235f6 100644 --- a/schemas/v1/README.md +++ b/schemas/v1/README.md @@ -296,3 +296,22 @@ All maps retain the 1024-entry ceiling; documents retain the 4 MiB byte and 32-l nesting ceilings. No captured state or live build admission is established by the synthetic progression fixture. Its predecessor hash pins the character fixture's file bytes for illustration; runtime bindings use the actual persisted identity. + +## Progression application DTOs + +`progression-api.schema.json` and `progression-api.ts` describe desktop application +requests/views, not a new addon exchange format. Regenerate with: + +```sh +cargo run --locked -p azeroth-app --example export_progression_schema > schemas/v1/progression-api.schema.json +pnpm contracts:types +``` + +Rust app tests compare the schema artifact; `pnpm contracts:check` checks representative +input rules. Manual requests carry exact expected SnapshotBinding, a new immutable +companion ID, and explicit known/unknown values. They cannot provide provenance or +timestamps: the app supplies those at explicit capture. Imports accept only ANAV1 +progression companions and require the same expected binding. Requests are limited +to 8 MiB (including escaped ANAV1 text) and 32 JSON levels; inner exchange keeps +its existing 4 MiB ceiling. Duplicate/unknown request members are refused. Views +keep imported and manual records separate and expose capture freshness. diff --git a/schemas/v1/progression-api.schema.json b/schemas/v1/progression-api.schema.json new file mode 100644 index 00000000..63fabf50 --- /dev/null +++ b/schemas/v1/progression-api.schema.json @@ -0,0 +1,3262 @@ +{ + "$defs": { + "BuildId": { + "maxLength": 256, + "minLength": 1, + "pattern": "^[^\\p{Cc}\\p{White_Space}](?:[^\\p{Cc}]*[^\\p{Cc}\\p{White_Space}])?$", + "type": "string" + }, + "BuildKey": { + "properties": { + "build": { + "$ref": "#/$defs/BuildId" + }, + "edition": { + "$ref": "#/$defs/EditionId" + }, + "interface": { + "$ref": "#/$defs/InterfaceId" + } + }, + "required": [ + "edition", + "build", + "interface" + ], + "type": "object" + }, + "CharacterId": { + "maxLength": 256, + "minLength": 1, + "pattern": "^[^\\p{Cc}\\p{White_Space}](?:[^\\p{Cc}]*[^\\p{Cc}\\p{White_Space}])?$", + "type": "string" + }, + "ClockTrust": { + "enum": [ + "trusted", + "uncertain" + ], + "type": "string" + }, + "ClockUncertainty": { + "enum": [ + "missing_or_untrusted_time", + "clock_reversed", + "age_out_of_range" + ], + "type": "string" + }, + "Completeness": { + "enum": [ + "complete", + "partial" + ], + "type": "string" + }, + "Copper": { + "description": "Unsigned integer copper as a canonical base-10 string (Rust also rejects values above u64)", + "pattern": "^(?:0|[1-9][0-9]{0,19})$", + "type": "string" + }, + "DataContext": { + "properties": { + "build": { + "$ref": "#/$defs/BuildKey" + }, + "namespace": { + "$ref": "#/$defs/DatasetNamespace" + } + }, + "required": [ + "build", + "namespace" + ], + "type": "object" + }, + "DatasetNamespace": { + "enum": [ + "demo", + "reference" + ], + "type": "string" + }, + "DatasetRevision": { + "maxLength": 256, + "minLength": 1, + "pattern": "^[^\\p{Cc}\\p{White_Space}](?:[^\\p{Cc}]*[^\\p{Cc}\\p{White_Space}])?$", + "type": "string" + }, + "EditionId": { + "maxLength": 256, + "minLength": 1, + "pattern": "^[^\\p{Cc}\\p{White_Space}](?:[^\\p{Cc}]*[^\\p{Cc}\\p{White_Space}])?$", + "type": "string" + }, + "EnhancementDuration": { + "enum": [ + "permanent", + "temporary" + ], + "type": "string" + }, + "Enumeration": { + "additionalProperties": false, + "description": "Availability and capture metadata live on the enclosing Observation. An\nunavailable enumeration is never represented as an empty complete map.", + "properties": { + "completeness": { + "$ref": "#/$defs/Completeness" + }, + "entries": { + "additionalProperties": { + "maximum": 65535, + "minimum": 0, + "type": "integer" + }, + "maxProperties": 1024, + "propertyNames": { + "$ref": "#/$defs/SourceId" + }, + "type": "object" + } + }, + "required": [ + "completeness", + "entries" + ], + "type": "object" + }, + "Enumeration10": { + "additionalProperties": false, + "description": "Availability and capture metadata live on the enclosing Observation. An\nunavailable enumeration is never represented as an empty complete map.", + "properties": { + "completeness": { + "$ref": "#/$defs/Completeness" + }, + "entries": { + "additionalProperties": { + "$ref": "#/$defs/ObservedEnhancement" + }, + "maxProperties": 1024, + "propertyNames": { + "$ref": "#/$defs/SourceId" + }, + "type": "object" + } + }, + "required": [ + "completeness", + "entries" + ], + "type": "object" + }, + "Enumeration2": { + "additionalProperties": false, + "description": "Availability and capture metadata live on the enclosing Observation. An\nunavailable enumeration is never represented as an empty complete map.", + "properties": { + "completeness": { + "$ref": "#/$defs/Completeness" + }, + "entries": { + "additionalProperties": { + "$ref": "#/$defs/ManualProfession" + }, + "maxProperties": 1024, + "propertyNames": { + "$ref": "#/$defs/SourceId" + }, + "type": "object" + } + }, + "required": [ + "completeness", + "entries" + ], + "type": "object" + }, + "Enumeration3": { + "additionalProperties": false, + "description": "Availability and capture metadata live on the enclosing Observation. An\nunavailable enumeration is never represented as an empty complete map.", + "properties": { + "completeness": { + "$ref": "#/$defs/Completeness" + }, + "entries": { + "additionalProperties": { + "type": "boolean" + }, + "maxProperties": 1024, + "propertyNames": { + "$ref": "#/$defs/SourceId" + }, + "type": "object" + } + }, + "required": [ + "completeness", + "entries" + ], + "type": "object" + }, + "Enumeration4": { + "additionalProperties": false, + "description": "Availability and capture metadata live on the enclosing Observation. An\nunavailable enumeration is never represented as an empty complete map.", + "properties": { + "completeness": { + "$ref": "#/$defs/Completeness" + }, + "entries": { + "additionalProperties": { + "$ref": "#/$defs/ManualInventory" + }, + "maxProperties": 1024, + "propertyNames": { + "$ref": "#/$defs/SourceId" + }, + "type": "object" + } + }, + "required": [ + "completeness", + "entries" + ], + "type": "object" + }, + "Enumeration5": { + "additionalProperties": false, + "description": "Availability and capture metadata live on the enclosing Observation. An\nunavailable enumeration is never represented as an empty complete map.", + "properties": { + "completeness": { + "$ref": "#/$defs/Completeness" + }, + "entries": { + "additionalProperties": { + "$ref": "#/$defs/ManualEnhancement" + }, + "maxProperties": 1024, + "propertyNames": { + "$ref": "#/$defs/SourceId" + }, + "type": "object" + } + }, + "required": [ + "completeness", + "entries" + ], + "type": "object" + }, + "Enumeration6": { + "additionalProperties": false, + "description": "Availability and capture metadata live on the enclosing Observation. An\nunavailable enumeration is never represented as an empty complete map.", + "properties": { + "completeness": { + "$ref": "#/$defs/Completeness" + }, + "entries": { + "additionalProperties": { + "$ref": "#/$defs/Observation_uint16" + }, + "maxProperties": 1024, + "propertyNames": { + "$ref": "#/$defs/SourceId" + }, + "type": "object" + } + }, + "required": [ + "completeness", + "entries" + ], + "type": "object" + }, + "Enumeration7": { + "additionalProperties": false, + "description": "Availability and capture metadata live on the enclosing Observation. An\nunavailable enumeration is never represented as an empty complete map.", + "properties": { + "completeness": { + "$ref": "#/$defs/Completeness" + }, + "entries": { + "additionalProperties": { + "$ref": "#/$defs/ProfessionState" + }, + "maxProperties": 1024, + "propertyNames": { + "$ref": "#/$defs/SourceId" + }, + "type": "object" + } + }, + "required": [ + "completeness", + "entries" + ], + "type": "object" + }, + "Enumeration8": { + "additionalProperties": false, + "description": "Availability and capture metadata live on the enclosing Observation. An\nunavailable enumeration is never represented as an empty complete map.", + "properties": { + "completeness": { + "$ref": "#/$defs/Completeness" + }, + "entries": { + "additionalProperties": { + "$ref": "#/$defs/Observation_boolean" + }, + "maxProperties": 1024, + "propertyNames": { + "$ref": "#/$defs/SourceId" + }, + "type": "object" + } + }, + "required": [ + "completeness", + "entries" + ], + "type": "object" + }, + "Enumeration9": { + "additionalProperties": false, + "description": "Availability and capture metadata live on the enclosing Observation. An\nunavailable enumeration is never represented as an empty complete map.", + "properties": { + "completeness": { + "$ref": "#/$defs/Completeness" + }, + "entries": { + "additionalProperties": { + "$ref": "#/$defs/InventoryQuantity" + }, + "maxProperties": 1024, + "propertyNames": { + "$ref": "#/$defs/SourceId" + }, + "type": "object" + } + }, + "required": [ + "completeness", + "entries" + ], + "type": "object" + }, + "EquipmentEnhancements": { + "additionalProperties": false, + "properties": { + "enhancements": { + "$ref": "#/$defs/Observation_Enumeration5" + }, + "item": { + "$ref": "#/$defs/ItemKey" + } + }, + "required": [ + "item", + "enhancements" + ], + "type": "object" + }, + "Freshness": { + "oneOf": [ + { + "properties": { + "age_ms": { + "$ref": "#/$defs/Millis" + }, + "status": { + "const": "fresh", + "type": "string" + } + }, + "required": [ + "status", + "age_ms" + ], + "type": "object" + }, + { + "properties": { + "age_ms": { + "$ref": "#/$defs/Millis" + }, + "status": { + "const": "stale", + "type": "string" + } + }, + "required": [ + "status", + "age_ms" + ], + "type": "object" + }, + { + "properties": { + "reason": { + "$ref": "#/$defs/ClockUncertainty" + }, + "status": { + "const": "uncertain", + "type": "string" + } + }, + "required": [ + "status", + "reason" + ], + "type": "object" + } + ] + }, + "ImportProgressionRequest": { + "additionalProperties": false, + "properties": { + "expected": { + "$ref": "#/$defs/SnapshotBinding" + }, + "profile_id": { + "type": "string" + }, + "text": { + "type": "string" + } + }, + "required": [ + "profile_id", + "expected", + "text" + ], + "type": "object" + }, + "InterfaceId": { + "maxLength": 256, + "minLength": 1, + "pattern": "^[^\\p{Cc}\\p{White_Space}](?:[^\\p{Cc}]*[^\\p{Cc}\\p{White_Space}])?$", + "type": "string" + }, + "InventoryQuantity": { + "additionalProperties": false, + "properties": { + "item": { + "$ref": "#/$defs/ItemKey" + }, + "quantity": { + "$ref": "#/$defs/Observation_uint32", + "description": "Aggregated quantity within this one explicit scope. Never a bag index." + } + }, + "required": [ + "item", + "quantity" + ], + "type": "object" + }, + "ItemId": { + "maxLength": 256, + "minLength": 1, + "pattern": "^[^\\p{Cc}\\p{White_Space}](?:[^\\p{Cc}]*[^\\p{Cc}\\p{White_Space}])?$", + "type": "string" + }, + "ItemKey": { + "properties": { + "context": { + "$ref": "#/$defs/DataContext" + }, + "item_id": { + "$ref": "#/$defs/ItemId" + }, + "variant": { + "$ref": "#/$defs/VariantId" + } + }, + "required": [ + "context", + "item_id", + "variant" + ], + "type": "object" + }, + "ManualEnhancement": { + "additionalProperties": false, + "properties": { + "duration": { + "anyOf": [ + { + "$ref": "#/$defs/EnhancementDuration" + }, + { + "type": "null" + } + ] + }, + "expires_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + } + }, + "type": "object" + }, + "ManualEquipment": { + "additionalProperties": false, + "properties": { + "enhancements": { + "$ref": "#/$defs/ManualValue8" + }, + "item": { + "$ref": "#/$defs/ItemKey" + } + }, + "required": [ + "item", + "enhancements" + ], + "type": "object" + }, + "ManualInventory": { + "additionalProperties": false, + "properties": { + "item": { + "$ref": "#/$defs/ItemKey" + }, + "quantity": { + "minimum": 0, + "type": "integer" + } + }, + "required": [ + "item", + "quantity" + ], + "type": "object" + }, + "ManualProfession": { + "additionalProperties": false, + "properties": { + "maximum_skill": { + "maximum": 65535, + "minimum": 0, + "type": [ + "integer", + "null" + ] + }, + "rank": { + "anyOf": [ + { + "$ref": "#/$defs/SourceId" + }, + { + "type": "null" + } + ] + }, + "skill": { + "maximum": 65535, + "minimum": 0, + "type": [ + "integer", + "null" + ] + } + }, + "type": "object" + }, + "ManualProgressionRequest": { + "additionalProperties": false, + "properties": { + "available_talent_points": { + "$ref": "#/$defs/ManualValue3" + }, + "bags": { + "$ref": "#/$defs/ManualValue6" + }, + "bank": { + "$ref": "#/$defs/ManualValue6" + }, + "equipment_enhancements": { + "additionalProperties": { + "$ref": "#/$defs/ManualValue7" + }, + "maxProperties": 1024, + "propertyNames": { + "$ref": "#/$defs/SlotId" + }, + "type": "object" + }, + "expected": { + "$ref": "#/$defs/SnapshotBinding" + }, + "id": { + "$ref": "#/$defs/SnapshotId" + }, + "money": { + "$ref": "#/$defs/ManualValue2" + }, + "professions": { + "$ref": "#/$defs/ManualValue4" + }, + "profile_id": { + "type": "string" + }, + "recipes": { + "$ref": "#/$defs/ManualValue5" + }, + "spells": { + "$ref": "#/$defs/ManualValue" + }, + "talents": { + "$ref": "#/$defs/ManualValue" + } + }, + "required": [ + "profile_id", + "expected", + "id", + "spells", + "money", + "talents", + "available_talent_points", + "professions", + "recipes", + "bags", + "bank", + "equipment_enhancements" + ], + "type": "object" + }, + "ManualValue": { + "description": "Manual input has no caller-controlled provenance or observation metadata.", + "oneOf": [ + { + "additionalProperties": false, + "properties": { + "status": { + "const": "unknown", + "type": "string" + } + }, + "required": [ + "status" + ], + "type": "object" + }, + { + "additionalProperties": false, + "properties": { + "status": { + "const": "known", + "type": "string" + }, + "value": { + "$ref": "#/$defs/Enumeration" + } + }, + "required": [ + "status", + "value" + ], + "type": "object" + } + ] + }, + "ManualValue2": { + "description": "Manual input has no caller-controlled provenance or observation metadata.", + "oneOf": [ + { + "additionalProperties": false, + "properties": { + "status": { + "const": "unknown", + "type": "string" + } + }, + "required": [ + "status" + ], + "type": "object" + }, + { + "additionalProperties": false, + "properties": { + "status": { + "const": "known", + "type": "string" + }, + "value": { + "$ref": "#/$defs/Copper" + } + }, + "required": [ + "status", + "value" + ], + "type": "object" + } + ] + }, + "ManualValue3": { + "description": "Manual input has no caller-controlled provenance or observation metadata.", + "oneOf": [ + { + "additionalProperties": false, + "properties": { + "status": { + "const": "unknown", + "type": "string" + } + }, + "required": [ + "status" + ], + "type": "object" + }, + { + "additionalProperties": false, + "properties": { + "status": { + "const": "known", + "type": "string" + }, + "value": { + "maximum": 65535, + "minimum": 0, + "type": "integer" + } + }, + "required": [ + "status", + "value" + ], + "type": "object" + } + ] + }, + "ManualValue4": { + "description": "Manual input has no caller-controlled provenance or observation metadata.", + "oneOf": [ + { + "additionalProperties": false, + "properties": { + "status": { + "const": "unknown", + "type": "string" + } + }, + "required": [ + "status" + ], + "type": "object" + }, + { + "additionalProperties": false, + "properties": { + "status": { + "const": "known", + "type": "string" + }, + "value": { + "$ref": "#/$defs/Enumeration2" + } + }, + "required": [ + "status", + "value" + ], + "type": "object" + } + ] + }, + "ManualValue5": { + "description": "Manual input has no caller-controlled provenance or observation metadata.", + "oneOf": [ + { + "additionalProperties": false, + "properties": { + "status": { + "const": "unknown", + "type": "string" + } + }, + "required": [ + "status" + ], + "type": "object" + }, + { + "additionalProperties": false, + "properties": { + "status": { + "const": "known", + "type": "string" + }, + "value": { + "$ref": "#/$defs/Enumeration3" + } + }, + "required": [ + "status", + "value" + ], + "type": "object" + } + ] + }, + "ManualValue6": { + "description": "Manual input has no caller-controlled provenance or observation metadata.", + "oneOf": [ + { + "additionalProperties": false, + "properties": { + "status": { + "const": "unknown", + "type": "string" + } + }, + "required": [ + "status" + ], + "type": "object" + }, + { + "additionalProperties": false, + "properties": { + "status": { + "const": "known", + "type": "string" + }, + "value": { + "$ref": "#/$defs/Enumeration4" + } + }, + "required": [ + "status", + "value" + ], + "type": "object" + } + ] + }, + "ManualValue7": { + "description": "Manual input has no caller-controlled provenance or observation metadata.", + "oneOf": [ + { + "additionalProperties": false, + "properties": { + "status": { + "const": "unknown", + "type": "string" + } + }, + "required": [ + "status" + ], + "type": "object" + }, + { + "additionalProperties": false, + "properties": { + "status": { + "const": "known", + "type": "string" + }, + "value": { + "$ref": "#/$defs/ManualEquipment" + } + }, + "required": [ + "status", + "value" + ], + "type": "object" + } + ] + }, + "ManualValue8": { + "description": "Manual input has no caller-controlled provenance or observation metadata.", + "oneOf": [ + { + "additionalProperties": false, + "properties": { + "status": { + "const": "unknown", + "type": "string" + } + }, + "required": [ + "status" + ], + "type": "object" + }, + { + "additionalProperties": false, + "properties": { + "status": { + "const": "known", + "type": "string" + }, + "value": { + "$ref": "#/$defs/Enumeration5" + } + }, + "required": [ + "status", + "value" + ], + "type": "object" + } + ] + }, + "Millis": { + "maximum": 9007199254740991, + "minimum": 0, + "type": "integer" + }, + "ObservationMetadata": { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + } + }, + "type": "object" + }, + "Observation_Copper": { + "oneOf": [ + { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + }, + "status": { + "const": "known" + }, + "value": { + "$ref": "#/$defs/Copper" + } + }, + "required": [ + "status", + "value" + ], + "type": "object" + }, + { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + }, + "status": { + "enum": [ + "unknown", + "unsupported", + "restricted", + "not_applicable" + ] + }, + "value": false + }, + "required": [ + "status" + ], + "type": "object" + } + ] + }, + "Observation_EnhancementDuration": { + "oneOf": [ + { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + }, + "status": { + "const": "known" + }, + "value": { + "$ref": "#/$defs/EnhancementDuration" + } + }, + "required": [ + "status", + "value" + ], + "type": "object" + }, + { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + }, + "status": { + "enum": [ + "unknown", + "unsupported", + "restricted", + "not_applicable" + ] + }, + "value": false + }, + "required": [ + "status" + ], + "type": "object" + } + ] + }, + "Observation_Enumeration": { + "oneOf": [ + { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + }, + "status": { + "const": "known" + }, + "value": { + "$ref": "#/$defs/Enumeration6" + } + }, + "required": [ + "status", + "value" + ], + "type": "object" + }, + { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + }, + "status": { + "enum": [ + "unknown", + "unsupported", + "restricted", + "not_applicable" + ] + }, + "value": false + }, + "required": [ + "status" + ], + "type": "object" + } + ] + }, + "Observation_Enumeration2": { + "oneOf": [ + { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + }, + "status": { + "const": "known" + }, + "value": { + "$ref": "#/$defs/Enumeration7" + } + }, + "required": [ + "status", + "value" + ], + "type": "object" + }, + { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + }, + "status": { + "enum": [ + "unknown", + "unsupported", + "restricted", + "not_applicable" + ] + }, + "value": false + }, + "required": [ + "status" + ], + "type": "object" + } + ] + }, + "Observation_Enumeration3": { + "oneOf": [ + { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + }, + "status": { + "const": "known" + }, + "value": { + "$ref": "#/$defs/Enumeration8" + } + }, + "required": [ + "status", + "value" + ], + "type": "object" + }, + { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + }, + "status": { + "enum": [ + "unknown", + "unsupported", + "restricted", + "not_applicable" + ] + }, + "value": false + }, + "required": [ + "status" + ], + "type": "object" + } + ] + }, + "Observation_Enumeration4": { + "oneOf": [ + { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + }, + "status": { + "const": "known" + }, + "value": { + "$ref": "#/$defs/Enumeration9" + } + }, + "required": [ + "status", + "value" + ], + "type": "object" + }, + { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + }, + "status": { + "enum": [ + "unknown", + "unsupported", + "restricted", + "not_applicable" + ] + }, + "value": false + }, + "required": [ + "status" + ], + "type": "object" + } + ] + }, + "Observation_Enumeration5": { + "oneOf": [ + { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + }, + "status": { + "const": "known" + }, + "value": { + "$ref": "#/$defs/Enumeration10" + } + }, + "required": [ + "status", + "value" + ], + "type": "object" + }, + { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + }, + "status": { + "enum": [ + "unknown", + "unsupported", + "restricted", + "not_applicable" + ] + }, + "value": false + }, + "required": [ + "status" + ], + "type": "object" + } + ] + }, + "Observation_EquipmentEnhancements": { + "oneOf": [ + { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + }, + "status": { + "const": "known" + }, + "value": { + "$ref": "#/$defs/EquipmentEnhancements" + } + }, + "required": [ + "status", + "value" + ], + "type": "object" + }, + { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + }, + "status": { + "enum": [ + "unknown", + "unsupported", + "restricted", + "not_applicable" + ] + }, + "value": false + }, + "required": [ + "status" + ], + "type": "object" + } + ] + }, + "Observation_SourceId": { + "oneOf": [ + { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + }, + "status": { + "const": "known" + }, + "value": { + "$ref": "#/$defs/SourceId" + } + }, + "required": [ + "status", + "value" + ], + "type": "object" + }, + { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + }, + "status": { + "enum": [ + "unknown", + "unsupported", + "restricted", + "not_applicable" + ] + }, + "value": false + }, + "required": [ + "status" + ], + "type": "object" + } + ] + }, + "Observation_UtcMillis": { + "oneOf": [ + { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + }, + "status": { + "const": "known" + }, + "value": { + "$ref": "#/$defs/UtcMillis" + } + }, + "required": [ + "status", + "value" + ], + "type": "object" + }, + { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + }, + "status": { + "enum": [ + "unknown", + "unsupported", + "restricted", + "not_applicable" + ] + }, + "value": false + }, + "required": [ + "status" + ], + "type": "object" + } + ] + }, + "Observation_boolean": { + "oneOf": [ + { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + }, + "status": { + "const": "known" + }, + "value": { + "type": "boolean" + } + }, + "required": [ + "status", + "value" + ], + "type": "object" + }, + { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + }, + "status": { + "enum": [ + "unknown", + "unsupported", + "restricted", + "not_applicable" + ] + }, + "value": false + }, + "required": [ + "status" + ], + "type": "object" + } + ] + }, + "Observation_uint16": { + "oneOf": [ + { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + }, + "status": { + "const": "known" + }, + "value": { + "maximum": 65535, + "minimum": 0, + "type": "integer" + } + }, + "required": [ + "status", + "value" + ], + "type": "object" + }, + { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + }, + "status": { + "enum": [ + "unknown", + "unsupported", + "restricted", + "not_applicable" + ] + }, + "value": false + }, + "required": [ + "status" + ], + "type": "object" + } + ] + }, + "Observation_uint32": { + "oneOf": [ + { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + }, + "status": { + "const": "known" + }, + "value": { + "minimum": 0, + "type": "integer" + } + }, + "required": [ + "status", + "value" + ], + "type": "object" + }, + { + "properties": { + "clock_trust": { + "$ref": "#/$defs/ClockTrust", + "default": "uncertain" + }, + "observed_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "received_at_utc_ms": { + "anyOf": [ + { + "$ref": "#/$defs/UtcMillis" + }, + { + "type": "null" + } + ] + }, + "sequence": { + "anyOf": [ + { + "$ref": "#/$defs/Sequence" + }, + { + "type": "null" + } + ] + }, + "session_elapsed_ms": { + "anyOf": [ + { + "$ref": "#/$defs/Millis" + }, + { + "type": "null" + } + ] + }, + "session_id": { + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ] + }, + "source": { + "$ref": "#/$defs/StateSource", + "default": "unrecorded" + }, + "status": { + "enum": [ + "unknown", + "unsupported", + "restricted", + "not_applicable" + ] + }, + "value": false + }, + "required": [ + "status" + ], + "type": "object" + } + ] + }, + "ObservedEnhancement": { + "additionalProperties": false, + "properties": { + "duration": { + "$ref": "#/$defs/Observation_EnhancementDuration" + }, + "expires_at_utc_ms": { + "$ref": "#/$defs/Observation_UtcMillis", + "description": "Unreadable expiry remains unknown/restricted; no inferred duration." + } + }, + "required": [ + "duration", + "expires_at_utc_ms" + ], + "type": "object" + }, + "ProfessionState": { + "additionalProperties": false, + "properties": { + "maximum_skill": { + "$ref": "#/$defs/Observation_uint16" + }, + "rank": { + "$ref": "#/$defs/Observation_SourceId" + }, + "skill": { + "$ref": "#/$defs/Observation_uint16" + } + }, + "required": [ + "skill", + "maximum_skill", + "rank" + ], + "type": "object" + }, + "ProgressionReceipt": { + "properties": { + "companion_id": { + "$ref": "#/$defs/SnapshotId" + }, + "fixture": { + "type": "boolean" + }, + "profile_id": { + "type": "string" + }, + "snapshot_id": { + "$ref": "#/$defs/SnapshotId" + }, + "stored": { + "type": "boolean" + } + }, + "required": [ + "profile_id", + "snapshot_id", + "companion_id", + "stored", + "fixture" + ], + "type": "object" + }, + "ProgressionRecord": { + "properties": { + "freshness": { + "$ref": "#/$defs/Freshness" + }, + "snapshot": { + "$ref": "#/$defs/ProgressionSnapshot" + } + }, + "required": [ + "snapshot", + "freshness" + ], + "type": "object" + }, + "ProgressionSnapshot": { + "additionalProperties": false, + "properties": { + "available_talent_points": { + "$ref": "#/$defs/Observation_uint16" + }, + "bags": { + "$ref": "#/$defs/Observation_Enumeration4", + "description": "Bags and bank are separate enumerations and never silently combined." + }, + "bank": { + "$ref": "#/$defs/Observation_Enumeration4" + }, + "binding": { + "$ref": "#/$defs/SnapshotBinding" + }, + "capture": { + "$ref": "#/$defs/ObservationMetadata" + }, + "equipment_enhancements": { + "additionalProperties": { + "$ref": "#/$defs/Observation_EquipmentEnhancements" + }, + "maxProperties": 1024, + "propertyNames": { + "$ref": "#/$defs/SlotId" + }, + "type": "object" + }, + "id": { + "$ref": "#/$defs/SnapshotId" + }, + "money": { + "$ref": "#/$defs/Observation_Copper" + }, + "payload_version": { + "$ref": "#/$defs/SchemaVersion" + }, + "professions": { + "$ref": "#/$defs/Observation_Enumeration2" + }, + "recipes": { + "$ref": "#/$defs/Observation_Enumeration3" + }, + "spells": { + "$ref": "#/$defs/Observation_Enumeration", + "description": "Keys identify exact source spell records; unknown rank is not rank zero." + }, + "talents": { + "$ref": "#/$defs/Observation_Enumeration" + } + }, + "required": [ + "payload_version", + "id", + "binding", + "capture", + "spells", + "money", + "talents", + "available_talent_points", + "professions", + "recipes", + "bags", + "bank", + "equipment_enhancements" + ], + "type": "object" + }, + "ProgressionView": { + "properties": { + "binding": { + "$ref": "#/$defs/SnapshotBinding" + }, + "fixture": { + "type": "boolean" + }, + "imported": { + "items": { + "$ref": "#/$defs/ProgressionRecord" + }, + "type": "array" + }, + "manual": { + "items": { + "$ref": "#/$defs/ProgressionRecord" + }, + "type": "array" + }, + "profile_id": { + "type": "string" + } + }, + "required": [ + "profile_id", + "fixture", + "binding", + "imported", + "manual" + ], + "type": "object" + }, + "SchemaVersion": { + "const": 1, + "type": "integer" + }, + "Sequence": { + "maximum": 9007199254740991, + "minimum": 0, + "type": "integer" + }, + "SessionId": { + "maxLength": 256, + "minLength": 1, + "pattern": "^[^\\p{Cc}\\p{White_Space}](?:[^\\p{Cc}]*[^\\p{Cc}\\p{White_Space}])?$", + "type": "string" + }, + "Sha256Hex": { + "pattern": "^[0-9a-f]{64}$", + "type": "string" + }, + "SlotId": { + "maxLength": 256, + "minLength": 1, + "pattern": "^[^\\p{Cc}\\p{White_Space}](?:[^\\p{Cc}]*[^\\p{Cc}\\p{White_Space}])?$", + "type": "string" + }, + "SnapshotBinding": { + "additionalProperties": false, + "description": "Exact predecessor identity for progression companions and saved advice.\nThe I/O layer supplies the persisted snapshot hash; this module does not hash\nor normalize imported bytes and never accepts a nearest-build substitution.", + "properties": { + "capture": { + "$ref": "#/$defs/ObservationMetadata" + }, + "character": { + "$ref": "#/$defs/CharacterId" + }, + "context": { + "$ref": "#/$defs/DataContext" + }, + "snapshot": { + "$ref": "#/$defs/SnapshotId" + }, + "snapshot_sha256": { + "$ref": "#/$defs/Sha256Hex" + }, + "source_revision": { + "$ref": "#/$defs/DatasetRevision" + } + }, + "required": [ + "snapshot", + "character", + "context", + "source_revision", + "capture", + "snapshot_sha256" + ], + "type": "object" + }, + "SnapshotId": { + "maxLength": 256, + "minLength": 1, + "pattern": "^[^\\p{Cc}\\p{White_Space}](?:[^\\p{Cc}]*[^\\p{Cc}\\p{White_Space}])?$", + "type": "string" + }, + "SourceId": { + "maxLength": 256, + "minLength": 1, + "pattern": "^[^\\p{Cc}\\p{White_Space}](?:[^\\p{Cc}]*[^\\p{Cc}\\p{White_Space}])?$", + "type": "string" + }, + "StateSource": { + "enum": [ + "unrecorded", + "addon_snapshot", + "manual_entry", + "official_api", + "reference_data", + "synthetic_fixture" + ], + "type": "string" + }, + "UtcMillis": { + "maximum": 9007199254740991, + "minimum": -9007199254740991, + "type": "integer" + }, + "VariantId": { + "maxLength": 256, + "minLength": 1, + "pattern": "^[^\\p{Cc}\\p{White_Space}](?:[^\\p{Cc}]*[^\\p{Cc}\\p{White_Space}])?$", + "type": "string" + } + }, + "$id": "https://github.com/Laymer/Navzeroth/schemas/v1/progression-api.schema.json", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "description": "Schema generation root; this is not an executable command dispatcher.", + "properties": { + "import_request": { + "$ref": "#/$defs/ImportProgressionRequest" + }, + "manual_request": { + "$ref": "#/$defs/ManualProgressionRequest" + }, + "receipt": { + "$ref": "#/$defs/ProgressionReceipt" + }, + "view": { + "$ref": "#/$defs/ProgressionView" + } + }, + "required": [ + "manual_request", + "import_request", + "view", + "receipt" + ], + "title": "ProgressionApi", + "type": "object" +} diff --git a/schemas/v1/progression-api.ts b/schemas/v1/progression-api.ts new file mode 100644 index 00000000..b114e142 --- /dev/null +++ b/schemas/v1/progression-api.ts @@ -0,0 +1,1258 @@ +/* Generated from progression-api.schema.json by scripts/generate-contract-types.mjs. + * Do not edit. Structural types only: Rust validation enforces semantic + * invariants, and unknown members are omitted from these types. */ + +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "UtcMillis". + */ +export type UtcMillis = number; +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "Sequence". + */ +export type Sequence = number; +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "Millis". + */ +export type Millis = number; +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "SessionId". + */ +export type SessionId = string; +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "CharacterId". + */ +export type CharacterId = string; +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "BuildId". + */ +export type BuildId = string; +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "EditionId". + */ +export type EditionId = string; +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "InterfaceId". + */ +export type InterfaceId = string; +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "DatasetNamespace". + */ +export type DatasetNamespace = "demo" | "reference"; +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "SnapshotId". + */ +export type SnapshotId = string; +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "Sha256Hex". + */ +export type Sha256Hex = string; +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "DatasetRevision". + */ +export type DatasetRevision = string; +/** + * Manual input has no caller-controlled provenance or observation metadata. + * + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "ManualValue3". + */ +export type ManualValue3 = + | { + status: "unknown"; + } + | { + status: "known"; + value: number; + }; +/** + * Manual input has no caller-controlled provenance or observation metadata. + * + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "ManualValue6". + */ +export type ManualValue6 = + | { + status: "unknown"; + } + | { + status: "known"; + value: Enumeration4; + }; +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "Completeness". + */ +export type Completeness = "complete" | "partial"; +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "ItemId". + */ +export type ItemId = string; +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "VariantId". + */ +export type VariantId = string; +/** + * Manual input has no caller-controlled provenance or observation metadata. + * + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "ManualValue7". + */ +export type ManualValue7 = + | { + status: "unknown"; + } + | { + status: "known"; + value: ManualEquipment; + }; +/** + * Manual input has no caller-controlled provenance or observation metadata. + * + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "ManualValue8". + */ +export type ManualValue8 = + | { + status: "unknown"; + } + | { + status: "known"; + value: Enumeration5; + }; +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "EnhancementDuration". + */ +export type EnhancementDuration = "permanent" | "temporary"; +/** + * Manual input has no caller-controlled provenance or observation metadata. + * + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "ManualValue2". + */ +export type ManualValue2 = + | { + status: "unknown"; + } + | { + status: "known"; + value: Copper; + }; +/** + * Unsigned integer copper as a canonical base-10 string (Rust also rejects values above u64) + * + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "Copper". + */ +export type Copper = string; +/** + * Manual input has no caller-controlled provenance or observation metadata. + * + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "ManualValue4". + */ +export type ManualValue4 = + | { + status: "unknown"; + } + | { + status: "known"; + value: Enumeration2; + }; +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "SourceId". + */ +export type SourceId = string; +/** + * Manual input has no caller-controlled provenance or observation metadata. + * + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "ManualValue5". + */ +export type ManualValue5 = + | { + status: "unknown"; + } + | { + status: "known"; + value: Enumeration3; + }; +/** + * Manual input has no caller-controlled provenance or observation metadata. + * + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "ManualValue". + */ +export type ManualValue = + | { + status: "unknown"; + } + | { + status: "known"; + value: Enumeration; + }; +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "Freshness". + */ +export type Freshness = + | { + age_ms: Millis; + status: "fresh"; + } + | { + age_ms: Millis; + status: "stale"; + } + | { + reason: ClockUncertainty; + status: "uncertain"; + }; +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "ClockUncertainty". + */ +export type ClockUncertainty = "missing_or_untrusted_time" | "clock_reversed" | "age_out_of_range"; +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "Observation_uint16". + */ +export type ObservationUint16 = + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "known"; + value: number; + } + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "unknown" | "unsupported" | "restricted" | "not_applicable"; + value?: never; + }; +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "Observation_Enumeration4". + */ +export type Observation_Enumeration4 = + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "known"; + value: Enumeration9; + } + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "unknown" | "unsupported" | "restricted" | "not_applicable"; + value?: never; + }; +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "Observation_EquipmentEnhancements". + */ +export type Observation_EquipmentEnhancements = + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "known"; + value: EquipmentEnhancements; + } + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "unknown" | "unsupported" | "restricted" | "not_applicable"; + value?: never; + }; +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "Observation_Enumeration5". + */ +export type Observation_Enumeration5 = + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "known"; + value: Enumeration10; + } + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "unknown" | "unsupported" | "restricted" | "not_applicable"; + value?: never; + }; +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "Observation_EnhancementDuration". + */ +export type Observation_EnhancementDuration = + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "known"; + value: EnhancementDuration; + } + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "unknown" | "unsupported" | "restricted" | "not_applicable"; + value?: never; + }; +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "Observation_Copper". + */ +export type Observation_Copper = + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "known"; + value: Copper; + } + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "unknown" | "unsupported" | "restricted" | "not_applicable"; + value?: never; + }; +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "SchemaVersion". + */ +export type SchemaVersion = 1; +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "Observation_Enumeration2". + */ +export type Observation_Enumeration2 = + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "known"; + value: Enumeration7; + } + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "unknown" | "unsupported" | "restricted" | "not_applicable"; + value?: never; + }; +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "Observation_SourceId". + */ +export type Observation_SourceId = + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "known"; + value: SourceId; + } + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "unknown" | "unsupported" | "restricted" | "not_applicable"; + value?: never; + }; +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "Observation_Enumeration3". + */ +export type Observation_Enumeration3 = + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "known"; + value: Enumeration8; + } + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "unknown" | "unsupported" | "restricted" | "not_applicable"; + value?: never; + }; +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "Observation_boolean". + */ +export type ObservationBoolean = + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "known"; + value: boolean; + } + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "unknown" | "unsupported" | "restricted" | "not_applicable"; + value?: never; + }; +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "Observation_Enumeration". + */ +export type Observation_Enumeration = + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "known"; + value: Enumeration6; + } + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "unknown" | "unsupported" | "restricted" | "not_applicable"; + value?: never; + }; +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "ClockTrust". + */ +export type ClockTrust = "trusted" | "uncertain"; +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "Observation_UtcMillis". + */ +export type Observation_UtcMillis = + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "known"; + value: UtcMillis; + } + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "unknown" | "unsupported" | "restricted" | "not_applicable"; + value?: never; + }; +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "Observation_uint32". + */ +export type ObservationUint32 = + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "known"; + value: number; + } + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "unknown" | "unsupported" | "restricted" | "not_applicable"; + value?: never; + }; +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "SlotId". + */ +export type SlotId = string; +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "StateSource". + */ +export type StateSource = + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + +/** + * Schema generation root; this is not an executable command dispatcher. + */ +export interface ProgressionApi { + import_request: ImportProgressionRequest; + manual_request: ManualProgressionRequest; + receipt: ProgressionReceipt; + view: ProgressionView; +} +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "ImportProgressionRequest". + */ +export interface ImportProgressionRequest { + expected: SnapshotBinding; + profile_id: string; + text: string; +} +/** + * Exact predecessor identity for progression companions and saved advice. + * The I/O layer supplies the persisted snapshot hash; this module does not hash + * or normalize imported bytes and never accepts a nearest-build substitution. + * + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "SnapshotBinding". + */ +export interface SnapshotBinding { + capture: ObservationMetadata; + character: CharacterId; + context: DataContext; + snapshot: SnapshotId; + snapshot_sha256: Sha256Hex; + source_revision: DatasetRevision; +} +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "ObservationMetadata". + */ +export interface ObservationMetadata { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; +} +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "DataContext". + */ +export interface DataContext { + build: BuildKey; + namespace: DatasetNamespace; +} +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "BuildKey". + */ +export interface BuildKey { + build: BuildId; + edition: EditionId; + interface: InterfaceId; +} +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "ManualProgressionRequest". + */ +export interface ManualProgressionRequest { + available_talent_points: ManualValue3; + bags: ManualValue6; + bank: ManualValue6; + equipment_enhancements: { + [k: string]: ManualValue7 | undefined; + }; + expected: SnapshotBinding; + id: SnapshotId; + money: ManualValue2; + professions: ManualValue4; + profile_id: string; + recipes: ManualValue5; + spells: ManualValue; + talents: ManualValue; +} +/** + * Availability and capture metadata live on the enclosing Observation. An + * unavailable enumeration is never represented as an empty complete map. + * + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "Enumeration4". + */ +export interface Enumeration4 { + completeness: Completeness; + entries: { + [k: string]: ManualInventory | undefined; + }; +} +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "ManualInventory". + */ +export interface ManualInventory { + item: ItemKey; + quantity: number; +} +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "ItemKey". + */ +export interface ItemKey { + context: DataContext; + item_id: ItemId; + variant: VariantId; +} +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "ManualEquipment". + */ +export interface ManualEquipment { + enhancements: ManualValue8; + item: ItemKey; +} +/** + * Availability and capture metadata live on the enclosing Observation. An + * unavailable enumeration is never represented as an empty complete map. + * + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "Enumeration5". + */ +export interface Enumeration5 { + completeness: Completeness; + entries: { + [k: string]: ManualEnhancement | undefined; + }; +} +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "ManualEnhancement". + */ +export interface ManualEnhancement { + duration?: EnhancementDuration | null; + expires_at_utc_ms?: UtcMillis | null; +} +/** + * Availability and capture metadata live on the enclosing Observation. An + * unavailable enumeration is never represented as an empty complete map. + * + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "Enumeration2". + */ +export interface Enumeration2 { + completeness: Completeness; + entries: { + [k: string]: ManualProfession | undefined; + }; +} +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "ManualProfession". + */ +export interface ManualProfession { + maximum_skill?: number | null; + rank?: SourceId | null; + skill?: number | null; +} +/** + * Availability and capture metadata live on the enclosing Observation. An + * unavailable enumeration is never represented as an empty complete map. + * + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "Enumeration3". + */ +export interface Enumeration3 { + completeness: Completeness; + entries: { + [k: string]: boolean | undefined; + }; +} +/** + * Availability and capture metadata live on the enclosing Observation. An + * unavailable enumeration is never represented as an empty complete map. + * + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "Enumeration". + */ +export interface Enumeration { + completeness: Completeness; + entries: { + [k: string]: number | undefined; + }; +} +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "ProgressionReceipt". + */ +export interface ProgressionReceipt { + companion_id: SnapshotId; + fixture: boolean; + profile_id: string; + snapshot_id: SnapshotId; + stored: boolean; +} +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "ProgressionView". + */ +export interface ProgressionView { + binding: SnapshotBinding; + fixture: boolean; + imported: ProgressionRecord[]; + manual: ProgressionRecord[]; + profile_id: string; +} +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "ProgressionRecord". + */ +export interface ProgressionRecord { + freshness: Freshness; + snapshot: ProgressionSnapshot; +} +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "ProgressionSnapshot". + */ +export interface ProgressionSnapshot { + available_talent_points: ObservationUint16; + /** + * Bags and bank are separate enumerations and never silently combined. + */ + bags: + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "known"; + value: Enumeration9; + } + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "unknown" | "unsupported" | "restricted" | "not_applicable"; + value?: never; + }; + bank: Observation_Enumeration4; + binding: SnapshotBinding; + capture: ObservationMetadata; + equipment_enhancements: { + [k: string]: Observation_EquipmentEnhancements | undefined; + }; + id: SnapshotId; + money: Observation_Copper; + payload_version: SchemaVersion; + professions: Observation_Enumeration2; + recipes: Observation_Enumeration3; + /** + * Keys identify exact source spell records; unknown rank is not rank zero. + */ + spells: + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "known"; + value: Enumeration6; + } + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "unknown" | "unsupported" | "restricted" | "not_applicable"; + value?: never; + }; + talents: Observation_Enumeration; +} +/** + * Availability and capture metadata live on the enclosing Observation. An + * unavailable enumeration is never represented as an empty complete map. + * + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "Enumeration9". + */ +export interface Enumeration9 { + completeness: Completeness; + entries: { + [k: string]: InventoryQuantity | undefined; + }; +} +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "InventoryQuantity". + */ +export interface InventoryQuantity { + item: ItemKey; + /** + * Aggregated quantity within this one explicit scope. Never a bag index. + */ + quantity: + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "known"; + value: number; + } + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "unknown" | "unsupported" | "restricted" | "not_applicable"; + value?: never; + }; +} +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "EquipmentEnhancements". + */ +export interface EquipmentEnhancements { + enhancements: Observation_Enumeration5; + item: ItemKey; +} +/** + * Availability and capture metadata live on the enclosing Observation. An + * unavailable enumeration is never represented as an empty complete map. + * + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "Enumeration10". + */ +export interface Enumeration10 { + completeness: Completeness; + entries: { + [k: string]: ObservedEnhancement | undefined; + }; +} +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "ObservedEnhancement". + */ +export interface ObservedEnhancement { + duration: Observation_EnhancementDuration; + /** + * Unreadable expiry remains unknown/restricted; no inferred duration. + */ + expires_at_utc_ms: + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "known"; + value: UtcMillis; + } + | { + clock_trust?: "trusted" | "uncertain"; + observed_at_utc_ms?: UtcMillis | null; + received_at_utc_ms?: UtcMillis | null; + sequence?: Sequence | null; + session_elapsed_ms?: Millis | null; + session_id?: SessionId | null; + source?: + | "unrecorded" + | "addon_snapshot" + | "manual_entry" + | "official_api" + | "reference_data" + | "synthetic_fixture"; + status: "unknown" | "unsupported" | "restricted" | "not_applicable"; + value?: never; + }; +} +/** + * Availability and capture metadata live on the enclosing Observation. An + * unavailable enumeration is never represented as an empty complete map. + * + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "Enumeration7". + */ +export interface Enumeration7 { + completeness: Completeness; + entries: { + [k: string]: ProfessionState | undefined; + }; +} +/** + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "ProfessionState". + */ +export interface ProfessionState { + maximum_skill: ObservationUint16; + rank: Observation_SourceId; + skill: ObservationUint16; +} +/** + * Availability and capture metadata live on the enclosing Observation. An + * unavailable enumeration is never represented as an empty complete map. + * + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "Enumeration8". + */ +export interface Enumeration8 { + completeness: Completeness; + entries: { + [k: string]: ObservationBoolean | undefined; + }; +} +/** + * Availability and capture metadata live on the enclosing Observation. An + * unavailable enumeration is never represented as an empty complete map. + * + * This interface was referenced by `ProgressionApi`'s JSON-Schema + * via the `definition` "Enumeration6". + */ +export interface Enumeration6 { + completeness: Completeness; + entries: { + [k: string]: ObservationUint16 | undefined; + }; +} diff --git a/scripts/coverage/collect-rust.mjs b/scripts/coverage/collect-rust.mjs index 7978f5a8..000a099f 100644 --- a/scripts/coverage/collect-rust.mjs +++ b/scripts/coverage/collect-rust.mjs @@ -59,6 +59,7 @@ export function collectRust(destination){ run('workspace-tests','cargo',['llvm-cov','test','--locked','--workspace','--all-targets','--no-report']); instrumented={...environment,...coverageEnvironment(run('instrumentation-environment','cargo',['llvm-cov','show-env','--sh'],{stdoutOnly:true}))}; if(path.resolve(instrumented.CARGO_LLVM_COV_TARGET_DIR)!==target||path.resolve(instrumented.CARGO_LLVM_COV_BUILD_DIR)!==target)throw new Error('Instrumentation escaped its owned build directory'); + cargoExample('progression-api-schema-export','azeroth-app','export_progression_schema'); cargoExample('schema-export','azeroth-core','export_content_schema'); cargoExample('world-data-schema-export','azeroth-core','export_world_data_schema'); cargoExample('release-inventory-schema-export','azeroth-core','export_release_schema',['inventory']); diff --git a/scripts/generate-contract-types.mjs b/scripts/generate-contract-types.mjs index e3dc5216..d20351fb 100644 --- a/scripts/generate-contract-types.mjs +++ b/scripts/generate-contract-types.mjs @@ -4,11 +4,12 @@ import { readFile, writeFile } from "node:fs/promises"; import { compile } from "json-schema-to-typescript"; const root = new URL("../schemas/v1/", import.meta.url); -const schema = JSON.parse(await readFile(new URL("exchange.schema.json", root), "utf8")); -const banner = `/* Generated from exchange.schema.json by scripts/generate-contract-types.mjs. +for (const [file, type] of [["exchange", "AzerothNavigatorExchangeV1"], ["progression-api", "ProgressionApi"]]) { +const schema = JSON.parse(await readFile(new URL(`${file}.schema.json`, root), "utf8")); +const banner = `/* Generated from ${file}.schema.json by scripts/generate-contract-types.mjs. * Do not edit. Structural types only: Rust validation enforces semantic * invariants, and unknown members are omitted from these types. */`; -const ts = await compile(schema, "AzerothNavigatorExchangeV1", { +const ts = await compile(schema, type, { bannerComment: banner, additionalProperties: false, unreachableDefinitions: true, @@ -16,5 +17,6 @@ const ts = await compile(schema, "AzerothNavigatorExchangeV1", { format: true, style: { endOfLine: "lf", printWidth: 100 }, }); -await writeFile(new URL("exchange.ts", root), ts.replace(/\r\n/g, "\n")); -console.log("Wrote schemas/v1/exchange.ts"); +await writeFile(new URL(`${file}.ts`, root), ts.replace(/\r\n/g, "\n")); +console.log(`Wrote schemas/v1/${file}.ts`); +} diff --git a/tests/contract/check.mts b/tests/contract/check.mts index ad50057d..590b7b17 100644 --- a/tests/contract/check.mts +++ b/tests/contract/check.mts @@ -254,3 +254,18 @@ if (failures > 0) { process.exit(1); } console.log(`OK: ${manifest.fixtures.length} fixtures checked against schema and TypeScript handling`); + + +// Application progression DTOs are generated from Rust independently of exchange v1. +const progressionSchema = readJson("schemas/v1/progression-api.schema.json") as object; +const progressionAjv = new Ajv2020({ allErrors: true }); +progressionAjv.addSchema(progressionSchema, "progression-api"); +const manualValidator = progressionAjv.compile({ $ref: "progression-api#/$defs/ManualProgressionRequest" }); +const companion = readJson("fixtures/contracts/v1/progression-snapshot.json") as {payload:{binding:unknown}}; +const unknown = { status:"unknown" }; +const manualInput = { profile_id:"synthetic-profile", expected:companion.payload.binding, id:"manual-one", spells:unknown, money:{status:"known",value:"0"}, talents:unknown, available_talent_points:{status:"known",value:0}, professions:unknown, recipes:{status:"known",value:{completeness:"partial",entries:{recipe:false}}}, bags:unknown, bank:unknown, equipment_enhancements:{} }; +check(manualValidator(manualInput), "generated manual progression schema accepts zero/false/unknown"); +check(!manualValidator({...manualInput,money:{status:"known",value:"0",source:"addon_snapshot"}}), "manual provenance cannot be supplied"); +check(!manualValidator({...manualInput,money:{status:"unknown",value:"0"}}), "unknown manual value cannot carry a value"); +check(!manualValidator({...manualInput,spells:{status:"known",value:{entries:{}}}}), "manual enumeration needs completeness"); +console.log("OK: generated progression API input constraints checked"); From d823b0df2ec012530daf57827f94fb16f08817a7 Mon Sep 17 00:00:00 2001 From: Laymer Date: Tue, 10 Nov 2026 15:38:36 +0100 Subject: [PATCH 07/10] V110.4e: add guarded desktop progression inputs --- TODO.md | 3 +- apps/desktop/e2e/progression-inputs.spec.ts | 66 +++++++ apps/desktop/src/screens/ImportScreen.tsx | 3 +- .../progression/ProgressionInputs.test.tsx | 171 ++++++++++++++++++ .../screens/progression/ProgressionInputs.tsx | 101 +++++++++++ .../progression/ProgressionRecords.tsx | 29 +++ .../desktop/src/screens/progression/inputs.ts | 28 +++ docs/STATUS.md | 4 +- .../2026-11-10-v110-progression-inputs.md | 15 ++ .../2026-11-10-v110-progression-inputs.md | 50 +++++ 10 files changed, 467 insertions(+), 3 deletions(-) create mode 100644 apps/desktop/e2e/progression-inputs.spec.ts create mode 100644 apps/desktop/src/screens/progression/ProgressionInputs.test.tsx create mode 100644 apps/desktop/src/screens/progression/ProgressionInputs.tsx create mode 100644 apps/desktop/src/screens/progression/ProgressionRecords.tsx create mode 100644 apps/desktop/src/screens/progression/inputs.ts create mode 100644 docs/claims/2026-11-10-v110-progression-inputs.md create mode 100644 docs/handoffs/2026-11-10-v110-progression-inputs.md diff --git a/TODO.md b/TODO.md index ceba56a1..3ea27c9d 100644 --- a/TODO.md +++ b/TODO.md @@ -12,7 +12,8 @@ below do not establish 1.1.0 readiness. V110.4a collection/binding and V110.4b versioned exchange implemented and checked; V110.4c companion persistence implemented and checked; V110.4d application/native commands implemented and checked; - UI/addon integration and saved workflow plans pending. + V110.4e Imports companion/manual money and point inputs implemented and checked; + catalog-backed manual editors, addon capture and saved workflow plans pending. - [ ] V110.5 Trainer spell service, saved plans and rendered workflow. - [ ] V110.6 Authored editable talents, validation and next-point workflow. - [ ] V110.7 Profession/crafting quantities, materials and acquisition workflow. diff --git a/apps/desktop/e2e/progression-inputs.spec.ts b/apps/desktop/e2e/progression-inputs.spec.ts new file mode 100644 index 00000000..314e4d76 --- /dev/null +++ b/apps/desktop/e2e/progression-inputs.spec.ts @@ -0,0 +1,66 @@ +import { expect, test } from "@playwright/test"; +import { fail, installMock } from "./support/mockInvoke"; +import type { CharacterSnapshotEnvelope } from "../../../schemas/v1/exchange"; +import type { ManualProgressionRequest, ProgressionRecord, ProgressionView } from "../../../schemas/v1/progression-api"; +import snapshot from "../../../fixtures/contracts/v1/character-snapshot.json" with { type: "json" }; +import companion from "../../../fixtures/contracts/v1/progression-snapshot.json" with { type: "json" }; + +// Browser journey across the real React/typed command boundary; mock storage only. +test("companion import and manual input preserve origins and survive UI reload", async ({ page }) => { + const profile = "synthetic-profile"; + const freshness = { status: "uncertain", reason: "missing_or_untrusted_time" } as const; + const imported: ProgressionRecord[] = []; const manual: ProgressionRecord[] = []; + const binding = companion.payload.binding as ProgressionView["binding"]; + let saved: ManualProgressionRequest | null = null; + const { calls } = await installMock(page, { + get_app_status: () => ({ version: "synthetic-test", data_mode: "stored", active_profile: profile, capabilities: {} }), + list_profiles: () => [{ id: profile, display_name: "Synthetic character", context: binding.context, fixture: true, data_mode: "stored", snapshot_count: 1 }], + get_stored_snapshot: () => ({ envelope: snapshot as CharacterSnapshotEnvelope, profile_id: profile, freshness, data_mode: "stored" }), + get_snapshot_history: () => [], + get_snapshot_watch: () => ({ active: false, status: null, last_import: null, error: null }), + get_progression_view: () => ({ profile_id: profile, fixture: true, binding, imported, manual }), + import_progression_text: ({ text }) => { + const request = JSON.parse(text) as { text: string; expected: unknown }; + if (request.text !== "ANAV1:synthetic-companion") throw fail("INVALID_INPUT", "Invalid progression export"); + expect(request.expected).toEqual(binding); + imported.push({ snapshot: companion.payload as ProgressionRecord["snapshot"], freshness }); + return { profile_id: profile, snapshot_id: binding.snapshot, companion_id: companion.payload.id, stored: true, fixture: true }; + }, + save_manual_progression: ({ text }) => { + saved = JSON.parse(text) as ManualProgressionRequest; + expect(saved.expected).toEqual(binding); + manual.push({ snapshot: { ...companion.payload as ProgressionRecord["snapshot"], id: saved.id, money: saved.money, available_talent_points: saved.available_talent_points, + recipes: { status: "unknown" }, bags: { status: "unknown" }, bank: { status: "unknown" } }, freshness }); + return { profile_id: profile, snapshot_id: binding.snapshot, companion_id: saved.id, stored: true, fixture: true }; + }, + }); + await page.goto("/"); + await page.getByRole("button", { name: "Imports", exact: true }).click(); + const panel = page.getByRole("region", { name: "Progression inputs", exact: true }); + await expect(panel.getByRole("button", { name: "Open progression inputs" })).toBeEnabled(); + expect(calls.filter((v) => v === "get_progression_view")).toEqual([]); + await panel.getByRole("button", { name: "Open progression inputs" }).click(); + await expect(panel.getByText(/No imported progression observations/)).toBeVisible(); + await panel.getByLabel("Progression export text", { exact: true }).fill("invalid-companion"); + await panel.getByRole("button", { name: "Import progression companion", exact: true }).click(); + await expect(panel.getByRole("alert")).toContainText("Invalid progression export"); + await panel.getByLabel("Progression export text", { exact: true }).fill("ANAV1:synthetic-companion"); + await panel.getByRole("button", { name: "Import progression companion", exact: true }).click(); + await expect(panel.getByRole("alert")).toHaveCount(0); + await panel.getByText(/Imported capture/).click(); + await expect(panel.getByText("0 recorded entries; complete enumeration")).toBeVisible(); + await expect(panel.getByText(/partial enumeration, other entries unknown/)).toBeVisible(); + await panel.getByLabel("Money (copper)", { exact: true }).fill("0"); + await panel.getByRole("button", { name: "Save manual entry" }).click(); + await expect(panel.getByText(/Saved progression capture: manual-/)).toBeVisible(); + expect(saved).toMatchObject({ money: { status: "known", value: "0" }, available_talent_points: { status: "unknown" }, recipes: { status: "unknown" } }); + await page.reload(); + await page.getByRole("button", { name: "Imports", exact: true }).click(); + await panel.getByRole("button", { name: "Open progression inputs" }).click(); + const records = panel.getByRole("region", { name: "Manual progression observations" }); + await records.getByText(/Manual capture/).click(); + await expect(records.getByText("0 copper")).toBeVisible(); + await expect(records.getByText("Source: Synthetic fixture.")).toBeVisible(); + await expect(records.getByText("Unknown (not observed)").first()).toBeVisible(); + await expect(panel.getByText(/Imported capture/)).toBeVisible(); +}); diff --git a/apps/desktop/src/screens/ImportScreen.tsx b/apps/desktop/src/screens/ImportScreen.tsx index 929148ee..e53cca20 100644 --- a/apps/desktop/src/screens/ImportScreen.tsx +++ b/apps/desktop/src/screens/ImportScreen.tsx @@ -5,6 +5,7 @@ import type { FileInputFormat, HistoryEntry, ImportReceipt, StoredSnapshot, Watc import { describeAge } from "../atlas/describe"; import { describeObservation } from "../observation"; import { Button, Field, Panel } from "../ui"; +import { ProgressionInputs } from "./progression/ProgressionInputs"; const WATCH_LABELS: Record = { waiting_for_stable_file: "Waiting for a complete, stable save.", imported: "The saved snapshot was imported.", @@ -192,5 +193,5 @@ export function ImportScreen({ client, onChanged }: { client: CommandClient; onC } {history.length === 0 ?

No stored snapshot history.

:
    {history.map((entry) =>
  • {entry.snapshot_id}{entry.is_current ? " (current)" : " (history only)"}: {describeAge(entry.freshness)} {!entry.is_current && }
  • )}
} - ; + {current !== null && current.profile_id === selected && }; } diff --git a/apps/desktop/src/screens/progression/ProgressionInputs.test.tsx b/apps/desktop/src/screens/progression/ProgressionInputs.test.tsx new file mode 100644 index 00000000..2644f7aa --- /dev/null +++ b/apps/desktop/src/screens/progression/ProgressionInputs.test.tsx @@ -0,0 +1,171 @@ +import { act, fireEvent, render, screen, waitFor, within } from "@testing-library/react"; +import { vi } from "vitest"; +import { createClient, type CommandAdapter } from "../../commands"; +import type { CommandMap, CommandName } from "../../commands/contract"; +import type { ManualProgressionRequest, ProgressionReceipt, ProgressionView } from "../../../../../schemas/v1/progression-api"; +import fixture from "../../../../../fixtures/contracts/v1/progression-snapshot.json"; +import { ProgressionInputs } from "./ProgressionInputs"; +import { ProgressionRecords } from "./ProgressionRecords"; +import { inputError, manualRequest } from "./inputs"; + +const view: ProgressionView = { profile_id: "profile-one", fixture: true, binding: fixture.payload.binding, imported: [], manual: [] } as ProgressionView; +const receipt: ProgressionReceipt = { profile_id: view.profile_id, snapshot_id: view.binding.snapshot, companion_id: "saved-companion", stored: true, fixture: true }; +const unavailable = { code: "PROVIDER_UNAVAILABLE", message: "Storage unavailable", retryable: true }; +function deferred() { let resolve!: (value: T) => void; let reject!: (reason: unknown) => void; const promise = new Promise((yes, no) => { resolve = yes; reject = no; }); return { promise, resolve, reject }; } +function harness() { + const calls: { command: CommandName; input: unknown }[] = []; + const get = vi.fn<() => Promise>().mockResolvedValue(view); + const save = vi.fn<() => Promise>().mockResolvedValue(receipt); + const adapter: CommandAdapter = { invoke(command: C, input: CommandMap[C]["input"]): Promise { + calls.push({ command, input }); + return (command === "get_progression_view" ? get() : save()) as Promise; + } }; + return { client: createClient(adapter), calls, get, save }; +} +async function open() { + fireEvent.click(screen.getByRole("button", { name: "Open progression inputs" })); + await waitFor(() => expect(screen.queryByText("Loading progression observations…")).not.toBeInTheDocument()); +} +function props(h: ReturnType) { return { client: h.client, profileId: view.profile_id, snapshotId: view.binding.snapshot, disabled: false }; } + +it("loads only on explicit open and saves zero with exact binding and other observations unknown", async () => { + const h = harness(); render(); + expect(h.calls).toEqual([]); await open(); + expect(screen.getByText(/No imported progression/)).toBeInTheDocument(); + expect(screen.getByText(/No manual progression/)).toBeInTheDocument(); + expect(screen.getByRole("button", { name: "Save manual entry" })).toBeDisabled(); + fireEvent.change(screen.getByLabelText("Money (copper)"), { target: { value: "0" } }); + fireEvent.change(screen.getByLabelText("Available talent points"), { target: { value: "0" } }); + fireEvent.click(screen.getByRole("button", { name: "Save manual entry" })); + expect(await screen.findByText(/Saved progression capture: saved-companion \(synthetic fixture\)/)).toBeInTheDocument(); + const call = h.calls.find((v) => v.command === "save_manual_progression"); + if (call === undefined) throw new Error("Manual save was not invoked"); + const request = JSON.parse((call.input as { text: string }).text) as ManualProgressionRequest; + expect(request).toMatchObject({ profile_id: view.profile_id, expected: view.binding, id: expect.stringMatching(/^manual-/), money: { status: "known", value: "0" }, available_talent_points: { status: "known", value: 0 }, spells: { status: "unknown" }, talents: { status: "unknown" }, professions: { status: "unknown" }, recipes: { status: "unknown" }, bags: { status: "unknown" }, bank: { status: "unknown" }, equipment_enhancements: {} }); + expect(screen.getByLabelText("Money (copper)")).toHaveValue(""); + expect(screen.getByLabelText("Available talent points")).toHaveValue(""); + expect(h.get).toHaveBeenCalledTimes(2); +}); + +it("rejects invalid numbers without rounding currency and preserves unknown separately from zero", () => { + for (const value of ["-1", "1.1", "1e3", "01", " ", "18446744073709551616", "999999999999999999999"]) expect(inputError(value, "")).toMatch(/Money must/); + for (const value of ["-1", "1.1", "1e3", "01", "65536", "100000"]) expect(inputError("", value)).toMatch(/talent points must/); + expect(inputError("18446744073709551615", "65535")).toBeNull(); + expect(manualRequest(view, "18446744073709551615", "").money).toEqual({ status: "known", value: "18446744073709551615" }); + expect(manualRequest(view, "", "0").money).toEqual({ status: "unknown" }); + expect(manualRequest(view, "0", "").available_talent_points).toEqual({ status: "unknown" }); + expect(manualRequest(view, "0", "").id).not.toEqual(manualRequest(view, "0", "").id); +}); + +it("imports a companion explicitly and explains duplicate receipts", async () => { + const h = harness(); h.save.mockResolvedValue({ ...receipt, stored: false, fixture: false }); + render(); await open(); + fireEvent.change(screen.getByLabelText("Progression export text"), { target: { value: "ANAV1:companion" } }); + fireEvent.click(screen.getByRole("button", { name: "Import progression companion" })); + expect(await screen.findByText(/Progression capture was already stored: saved-companion/)).toBeInTheDocument(); + expect(h.calls).toContainEqual({ command: "import_progression_text", input: { text: JSON.stringify({ profile_id: view.profile_id, expected: view.binding, text: "ANAV1:companion" }) } }); + expect(screen.getByLabelText("Progression export text")).toHaveValue(""); +}); + +it("shows capture origins, stale/uncertain age, empty/partial collections and unavailable fields", () => { + const base = fixture.payload as ProgressionView["imported"][number]["snapshot"]; + const { rerender } = render(); + expect(screen.getByText(/Imported capture.*stale/)).toBeInTheDocument(); + fireEvent.click(screen.getByText(/Imported capture/)); + expect(screen.getByText("Source: Synthetic fixture.")).toBeInTheDocument(); + expect(screen.getByText("0 copper")).toBeInTheDocument(); + expect(screen.getByText("0 recorded entries; complete enumeration")).toBeInTheDocument(); + expect(screen.getByText("1 recorded entries; partial enumeration, other entries unknown")).toBeInTheDocument(); + expect(screen.getByText("Unsupported by this client")).toBeInTheDocument(); + const manual = { ...base, capture: { ...base.capture, source: "manual_entry" as const }, money: { status: "restricted" as const }, recipes: { status: "not_applicable" as const }, bank: { status: "known" as const, value: { completeness: "partial" as const, entries: {} } } }; + rerender(); + expect(screen.getByText(/Manual capture.*age uncertain/)).toBeInTheDocument(); + expect(screen.getByText("Source: Manual entry.")).toBeInTheDocument(); + expect(screen.getByText("Restricted (hidden by the game)")).toBeInTheDocument(); + expect(screen.getByText("Not applicable")).toBeInTheDocument(); + expect(screen.getByText("0 recorded entries; partial enumeration, other entries unknown")).toBeInTheDocument(); + rerender(); + expect(screen.getByText("Source: Addon observation.")).toBeInTheDocument(); +}); + +it.each(["profile", "snapshot"])("refuses a loaded view for a different %s", async (mismatch) => { + const h = harness(); h.get.mockResolvedValue(mismatch === "profile" ? { ...view, profile_id: "other" } : { ...view, binding: { ...view.binding, snapshot: "other" } }); + render(); await open(); + expect(screen.getByRole("alert")).toHaveTextContent("SNAPSHOT_OUTDATED"); + expect(screen.getByLabelText("Money (copper)")).toBeDisabled(); + expect(screen.queryByRole("region", { name: "Manual progression observations" })).not.toBeInTheDocument(); +}); + +it("recovers read failures and preserves manual inputs through save failures", async () => { + const h = harness(); h.get.mockRejectedValueOnce(unavailable); + h.save.mockRejectedValueOnce({ code: "INVALID_INPUT", message: "Capture rejected", retryable: false }); + render(); await open(); + expect(screen.getByRole("alert")).toHaveTextContent("PROVIDER_UNAVAILABLE"); + fireEvent.click(screen.getByRole("button", { name: "Refresh progression observations" })); + await waitFor(() => expect(screen.getByLabelText("Money (copper)")).toBeEnabled()); + fireEvent.change(screen.getByLabelText("Money (copper)"), { target: { value: "-1" } }); + expect(screen.getByRole("button", { name: "Save manual entry" })).toBeDisabled(); + fireEvent.change(screen.getByLabelText("Money (copper)"), { target: { value: "250" } }); + fireEvent.click(screen.getByRole("button", { name: "Save manual entry" })); + expect(await screen.findByRole("alert")).toHaveTextContent("Capture rejected"); + expect(screen.getByLabelText("Money (copper)")).toHaveValue("250"); + fireEvent.click(screen.getByRole("button", { name: "Save manual entry" })); + expect(await screen.findByText(/Saved progression capture/)).toBeInTheDocument(); +}); + +it.each(["stale", "wrong receipt"])("invalidates the binding on %s during a write", async (kind) => { + const h = harness(); + if (kind === "stale") h.save.mockRejectedValue({ code: "SNAPSHOT_OUTDATED", message: "Changed snapshot", retryable: false }); + else h.save.mockResolvedValue({ ...receipt, snapshot_id: "different" }); + render(); await open(); + fireEvent.change(screen.getByLabelText("Available talent points"), { target: { value: "1" } }); + fireEvent.click(screen.getByRole("button", { name: "Save manual entry" })); + expect(await screen.findByRole("alert")).toHaveTextContent("SNAPSHOT_OUTDATED"); + expect(screen.getByLabelText("Available talent points")).toBeDisabled(); +}); + +it.each(["client", "profile", "snapshot"])("resets entered data and ignores delayed reads when %s changes", async (kind) => { + const h = harness(); const late = deferred(); h.get.mockReturnValueOnce(late.promise); + const original = props(h); const { rerender } = render(); + fireEvent.click(screen.getByRole("button", { name: "Open progression inputs" })); + const next = kind === "client" ? { ...original, client: harness().client } : kind === "profile" ? { ...original, profileId: "other" } : { ...original, snapshotId: "other" }; + rerender(); + await act(async () => { late.resolve(view); }); + expect(screen.getByRole("button", { name: "Open progression inputs" })).toBeInTheDocument(); + expect(screen.queryByLabelText("Money (copper)")).not.toBeInTheDocument(); + expect(screen.queryByRole("alert")).not.toBeInTheDocument(); +}); + +it("ignores delayed write failures after closing and resets drafts when reopening", async () => { + const h = harness(); const late = deferred(); h.save.mockReturnValueOnce(late.promise); + render(); await open(); + fireEvent.change(screen.getByLabelText("Money (copper)"), { target: { value: "10" } }); + fireEvent.click(screen.getByRole("button", { name: "Save manual entry" })); + expect(screen.getByLabelText("Money (copper)")).toBeDisabled(); + fireEvent.click(screen.getByRole("button", { name: "Close progression inputs" })); + await act(async () => { late.reject(unavailable); }); + expect(screen.queryByRole("alert")).not.toBeInTheDocument(); + await open(); expect(screen.getByLabelText("Money (copper)")).toHaveValue(""); +}); + +it("disables mutations during parent changes and refreshes ages without replacing drafts", async () => { + vi.useFakeTimers({ toFake: ["setInterval", "clearInterval"] }); + try { + const h = harness(); const original = props(h); const { rerender, unmount } = render(); await open(); + fireEvent.change(screen.getByLabelText("Money (copper)"), { target: { value: "10" } }); + rerender(); + expect(screen.getByLabelText("Money (copper)")).toBeDisabled(); + rerender(); + h.get.mockResolvedValue({ ...view, manual: [{ snapshot: fixture.payload as ProgressionView["manual"][number]["snapshot"], freshness: { status: "stale", age_ms: 3600000 } }] }); + await act(async () => { await vi.advanceTimersByTimeAsync(60000); }); + expect(screen.getByLabelText("Money (copper)")).toHaveValue("10"); + expect(within(screen.getByRole("region", { name: "Manual progression observations" })).getByText(/stale/)).toBeInTheDocument(); + const pending = deferred(); h.save.mockReturnValueOnce(pending.promise); + fireEvent.click(screen.getByRole("button", { name: "Save manual entry" })); + const reads = h.get.mock.calls.length; + await act(async () => { await vi.advanceTimersByTimeAsync(60000); }); + expect(h.get).toHaveBeenCalledTimes(reads); + unmount(); await act(async () => { pending.resolve(receipt); }); + await vi.advanceTimersByTimeAsync(60000); expect(h.get).toHaveBeenCalledTimes(reads); + } finally { vi.useRealTimers(); } +}); diff --git a/apps/desktop/src/screens/progression/ProgressionInputs.tsx b/apps/desktop/src/screens/progression/ProgressionInputs.tsx new file mode 100644 index 00000000..7f7f20c4 --- /dev/null +++ b/apps/desktop/src/screens/progression/ProgressionInputs.tsx @@ -0,0 +1,101 @@ +import { useCallback, useEffect, useRef, useState } from "react"; +import type { AppError, CommandClient } from "../../commands"; +import type { ProgressionReceipt, ProgressionView } from "../../../../../schemas/v1/progression-api"; +import { Button, Field, Panel } from "../../ui"; +import { inputError, manualRequest } from "./inputs"; +import { ProgressionRecords } from "./ProgressionRecords"; + +interface Props { client: CommandClient; profileId: string; snapshotId: string; disabled: boolean } +const OUTDATED: AppError = { code: "SNAPSHOT_OUTDATED", message: "The selected snapshot changed. Refresh stored state before opening progression inputs again.", retryable: false }; + +/** Remount all input and request state when its owning client or predecessor changes. */ +export function ProgressionInputs(props: Props) { + const owner = useRef({ client: props.client, profileId: props.profileId, snapshotId: props.snapshotId, key: 0 }); + if (owner.current.client !== props.client || owner.current.profileId !== props.profileId || owner.current.snapshotId !== props.snapshotId) { + owner.current = { client: props.client, profileId: props.profileId, snapshotId: props.snapshotId, key: owner.current.key + 1 }; + } + return ; +} + +function InputToggle(props: Props) { + const [open, setOpen] = useState(false); + return +

Record information for the selected character snapshot. Manual entries describe what you entered; saving does not change the game.

+ {open ? <> + + + : } +
; +} + +function InputEditor({ client, profileId, snapshotId, disabled }: Props) { + const [view, setView] = useState(null); + const [error, setError] = useState(null); + const [receipt, setReceipt] = useState(null); + const [loading, setLoading] = useState(true); + const [busy, setBusy] = useState(false); + const [text, setText] = useState(""); + const [money, setMoney] = useState(""); + const [points, setPoints] = useState(""); + const generation = useRef(0); + const active = useRef(true); + const mutating = useRef(false); + const refresh = useCallback(async () => { + const ticket = ++generation.current; + setLoading(true); + const result = await client.getProgressionView(profileId); + if (!active.current || generation.current !== ticket) return; + setLoading(false); + if (!result.ok) { setView(null); setError(result.error); } + else if (result.value.profile_id !== profileId || result.value.binding.snapshot !== snapshotId) { setView(null); setError(OUTDATED); } + else { setView(result.value); setError(null); } + }, [client, profileId, snapshotId]); + useEffect(() => { + active.current = true; + void refresh(); + const timer = window.setInterval(() => { if (!mutating.current) void refresh(); }, 60000); + return () => { active.current = false; generation.current++; window.clearInterval(timer); }; + }, [refresh]); + + const invalid = inputError(money, points); + const blocked = disabled || busy || loading || view === null; + async function save(kind: "manual" | "import") { + if (blocked || mutating.current || view === null || (kind === "manual" && invalid !== null) || (kind === "import" && text.trim() === "")) return; + mutating.current = true; setBusy(true); setError(null); setReceipt(null); + const ticket = ++generation.current; + const result = kind === "manual" ? await client.saveManualProgression(manualRequest(view, money, points)) + : await client.importProgression({ profile_id: profileId, expected: view.binding, text }); + if (!active.current || ticket !== generation.current) return; + mutating.current = false; setBusy(false); + if (!result.ok) { setError(result.error); if (result.error.code === "SNAPSHOT_OUTDATED") setView(null); return; } + if (result.value.profile_id !== profileId || result.value.snapshot_id !== snapshotId) { setView(null); setError(OUTDATED); return; } + setReceipt(result.value); + if (kind === "manual") { setMoney(""); setPoints(""); } else setText(""); + await refresh(); + } + + return
+ {loading &&

Loading progression observations…

} + {error !== null &&

Error {error.code}: {error.message}

} + {receipt !== null &&

{receipt.stored ? "Saved progression capture" : "Progression capture was already stored"}: {receipt.companion_id}{receipt.fixture ? " (synthetic fixture)" : ""}.

} + +
+ Import progression companion + {(c) =>