@parity/product-lab 0.0.1-placeholder → 0.1.0

package/core/domain/README.md

@@ -0,0 +1,197 @@
+# @product-lab/domain
+
+The domain model of product-lab: entities, value objects and domain services, with no dependencies and no I/O. It is
+the innermost layer of the hexagon:
+`core/ports`, `core/lab`, `core/application`, the host, environment and chain contract kits, most adapters and the entry
+points depend on it; it depends on nothing. Refactor step 4 created it by moving and unifying concepts that were
+declared several times across core, the adapters and the entry points.
+
+## Folders and exports
+
+Each folder is a subpath export (`@product-lab/domain/<folder>`); `@product-lab/domain` exports everything.
+
+| Folder | Exports | What it replaced (paths as they were then) |
+| --- | --- | --- |
+| `lab/` | `CAPABILITIES`, `Capability`, `isCapability`; `Offer` (with the `EnvironmentOffer` data shape); `Requirements` (`AppRequirements`); `RequirementCheck` (domain service: requirements against an offer, optionally explaining a missing capability); the function exports `checkRequirements`, `mergeRequirements`, `requirementErrors`; `CapabilityPolicy` (facts to capabilities, with reasons; no development authority off-machine); `IntegrationReadiness` (ready, available, idle, unavailable, failed, blocked); `Topology`, `TopologyOptions`, `TopologyIssue`, `TopologyIssues`, `Retention`, `RetentionView`, `TopologyPresentation`, `TopologyOffer`, `TopologyEndpoints` and their helpers (`isTopology`, `orderedChains`, `sameChains`, `stateKind`, `describeState`, `topologyLabel`, `localEndpoints`), added in refactor step 5. Since 3 October 2026 (backlog A6, `public-target.ts`): `PublicTarget` (`PublicTargetData`, `PublicAccess`: the marker an environment on a public network carries as `EnvironmentOffer.public`, with its reason, and optionally its network and access (`read-only` by default, `read-write` for writes through pre-onboarded identities); `timeouts()` (`PublicTimeouts`) sized from its finality, at least 12 s; `refusal(what, { capabilities, writes })` naming work that needs `devAuthority` or writes on a read-only target; `notice()`), `runScoped` and `isRunScoped` (the run id in a value a run writes); `Offer` validates the marker (`local: false`, no `devAuthority`); `waitsNotice()` names the waits sized for its finality; `RequirementCheck` explains a missing `devAuthority` on a public offer in its own words (so a block that needs it is refused naming it); `withholdCapabilities(topology, capabilities, reason)` (`topology-functions.ts`) rehearses a target that lacks a capability on a local topology (offer, reasons, a `withheld` customization and a note). Since 6 October 2026 (`chain-pace.ts`, also the subpath `@product-lab/domain/lab/chain-pace`, which imports nothing and the panel serves as `/chain-pace.js`): `ChainPace` (`fast` or `real-time`), `CHAIN_PACES`, `REAL_TIME_PACE_LINE`, `KEEP_FOR_DAYS`, `keptChainAheadWords`, `REPLACE_KEPT_QUESTION`, `REPLACE_KEPT_ACTION`: every surface's words for the pace and a stale kept chain. Since 3 October 2026 (`rpc-selection.ts`, the lab's own RPC per chain): `RpcDeclaration` (`RpcRole`: `endpoint` or `upstream`), `RpcSelection` (per chain the URL and where it came from, `RpcSource`: default, lab.config, remembered, request, a later source winning; `problems(environment, declaration, { publicTarget })` refuses a chain the provider does not list and an `endpoint` RPC off this machine without a reason unless the environment is a public target; `view()`, `RpcChoiceView`, never a secret or a token), `rpcLiteralErrors`, `rpcUrlProblem` (a literal URL with a user, password or query is refused, naming the field, never the value) and `shownRpcUrl` (scheme and host for a secret's URL or one that may carry a token) | `core/application/src/orchestration/capabilities.ts`; `offerErrors`; `checkRequirements`, `topologyAvailability` and `withTopologyReasons`; the capability decisions in `env-attached` and `env-chopsticks`; the status decision in `integrationAvailability`; `core/lab/src/topology.ts`'s per-adapter policy (defaults, ports, capability reasons), which stayed in `core/lab` while the shared shape moved here |
+| `lab/` (config) | Config redesign (6 October 2026; `resolved-config.ts`, also the subpath `@product-lab/domain/lab/resolved-config`, which imports nothing and the panel serves as `/resolved-config.js`): `CONFIG_GROUPS`, `configGroupOf`, `CONFIG_SOURCE_WORDS` (`ResolvedConfigSource`: yours, default, detected, advanced), `configValueText` (a value in one line, a secret by its name only), `offConfigItems`/`configEntryOff` (what a config leaves off or unset, each with the loader's line: the window greys them, never hides them) and `TOPOLOGY_PROFILE_WORDS`/`profileWords` (the relay-less profile is the "Local dev chain (Omni Node)"; `topologyLabel` uses them): how `product-lab config`, the window's Config view and MCP group and word the resolved config. Tests: `tests/resolved-config.test.ts`. | New |
+| `actors/` | `ActorId`, `ActorAlias`, `Actor` (with the `ActorSession` data shape; its optional `host`, an `ActorHost` of the host adapter's id, short label and colour, from `actorHost(provider)`, and since backlog 185 the options on for it; since 6 October 2026 `limits` (C6, `HostLimit`: what the host cannot do yet, in its adapter's words), the lab's `description` of the host, and `network` (C4, `HostNetworkNote`: the session's network where it opened, when the options do not say it; `withNetworkNote(host, note)` puts it in place of the option it qualifies, so a row and a tile cannot disagree); `host-options.ts`: `HostOptionDeclaration`, `HostOptionSetting`, `hostReference`, `parseHostReference`, `resolveHostChoice`, `hostOptionsOn`, the host reference a person, a scenario or a saved identity names a host with; `isHostColor` and `HOST_COLOR_FALLBACK`, slate, in `host-color.ts`), `ActorRoster` (distinct ids, isolated origins, keep one usable identity), `Session` (host, actor, app), `Principal` (29 September 2026: who a run or step acts as, the setup principal or one identity; `stepPrincipal`, `runOwner`, `describePrincipal`, `SETUP_RESOURCE`); since 3 October 2026 `ActorKind` and `ActorSession.kind` (`preOnboarded`: an account that existed before the run, backlog A3); the panel serves these files to the browser | the controller's two actor checks, `actors.ts`, `appOrigin`, the alias regex in `actor-binding.ts`, the `\u0000` key in `HostSessionRegistry` |
+| `identity/` | `Identity`, `ProvisionedIdentity`, `BIP39_ENTROPY_LENGTHS`, `assertBip39Entropy`; since 3 October 2026 (backlog A3, `pre-onboarded-actor.ts`) `PreOnboardedActor`, `preOnboarded(secret, { liteUsername, account })`, `PreOnboardedActorData` and `ActorDeclarationData` (an existing account declared by its secret's name, never a value); server-only, never served to the browser | entropy assertion from `core/application/src/orchestration/identity/port.ts` |
+| `runs/` | `Run` (aggregate: `RunStatus`, `StepStatus`, guarded transitions), `RunTransitionError`, `Checkpoint`, `Evidence` (typed union: `receipt`, `transaction` (tx-landed: a `{ txHash }` with what the evidence says about its signer, signing block, nonce, mortality and receipt), `block`, `navigation`, `observation`); since tx-landed `SubmittedTransaction` (the transaction "did this transaction land" asks about: its hash, a receipt position or both; `earliestBlock`, `expiredAt`; backlog 190: `Mortality.birthHash`, `withBirthHash`) and `TransactionLanding` (the four answers `succeeded`, `failed`, `not-included`, `unknown`, each with its reason; `outcome` for reconciliation and `outcomeOf` for several; `retractedBirth`); since step 8 `NegativeControl` (the judging rule itself: `judge`, with `ControlStep`, `ControlOutcome`, `ControlVerdict`, `ControlVerdictReason`; `ControlExpectation`: a bundle rerun's step and marker); since 6 October 2026 tag-only controls (`controlSpec`, `taggedControls`, `runTagSelection`, `failsWithProblem`, `JudgedFailure`; step 8: `removedControlDeclaration`, `NEGATIVE_CONTROL_TAG`) and `step-failure.ts` (`stepFailure`: a step's reason; `tests/control-tags.test.ts`); since step 6 `describeFailure` (`failure-description.ts`: a structured provider error as a short label; imports nothing, the panel serves it to the browser as `/errors.js`); since backlog item 63 `attributeSubmissions` (`step-submissions.ts`: which transactions a failed step sent, from three readings of its identity's account and the host's signing record: `attributed`, `nothing-sent` or `ambiguous` with the reason; `ChainWindow`, `SigningWindow`, `SubmissionAttribution`; `tests/step-submissions.test.ts`); since backlog 20 (3 October 2026) run bundles: `RunBundle` (the index, read with every problem named: `RunBundleFormatError`), `RunBundleData` and its parts (`RUN_BUNDLE_KIND`, `RUN_BUNDLE_INDEX`, `RunBundleAttempt`, `RunBundleFailure`, `RunBundleState`, `SourceRevisionData`, `WithheldIdentity`), `bundleVerdict` (flaky never passes), `bundleReproducibility`, `isBundlePath`, `failureMarker` (the stable part of an error a rerun must repeat: hashes, ids, durations, long numbers and chain positions such as `block 7` cut out), `RunBundleReproduction` (`problems`: every refusal at once; `judge`: a rerun by `NegativeControl.judge` with the bundled failure as the expectation), `sameSource`, `RunBundleRefusedError` (`tests/run-bundle.test.ts`); since backlog 34 (3 October 2026) parallel workers (`workers.ts`): `planWorkers` (feature files shared out, recorded durations longest first, the rest by count), `WorkersDeclaration` and `workersDeclarationProblems` (a lab's `workers`), `workerEnvProblems` (no two workers given the same variables), `sharedWorkerEndpoints` (an address two workers' environments reported), `workersOverlapMs` (`tests/workers.test.ts`); since backlog 32 race hunting: `RaceSeed`, `RaceJitter`, `RaceDelay` ([below](#race-hunting)) | the controller's and the scheduler's separate run state machines; the MCP server's evidence walkers; `JudgeNegativeControl` in `@product-lab/application`, which now delegates to `NegativeControl.judge` |
+| `runs/` (stored content) | Backlog 99 (`stored-content.ts`): `storedContent(events)`, the content a landed store transaction stored, from its `TransactionStorage.Stored` event (the event's `cid` bytes, else the id built from `content_hash`), as `StoredContent` (`cid` in base32, `contentHash`); `rawBlake2bCidOfDigest(digest)`, the CIDv1 (raw, blake2b-256 multihash) whose digest is the one given, nothing hashed again. `tests/stored-content.test.ts` (the ids read on Notes' fast environment) | `CheckStores` in `@product-lab/application` |
+| `resources/` | `Resource` (names, `Resource.account`, collisions), `Generation`, and function exports `accountResource`, `assertResources`, `collisions` | `core/application/src/orchestration/run/resources.ts` helpers; the container's generation counter |
+| `network/` | `workerHoldPolicy`, `WorkerHold`, `WorkerHoldSetting`, `WORKER_HOLD_SWITCH` (lane wasm, 6 October 2026: a lab's browsers hold each new worker until it is observed, through a debugging port on 127.0.0.1 that every local process of every user can reach, only for a local environment with only lab-made identities and no dot.li host, unless `workerHold: false`; off, the reason); `LoopbackUrl`, `EnvironmentEndpoints` (with `ChainEndpoint`, `EndpointMap`); `NetworkPolicy` (Phase 3: deny-by-default as a domain service; `NetworkPolicy.from({ routes, appOrigins, exceptions, hostOnlyRoutes? })` (backlog 42: `hostOnlyRoutes` denies the routes to a context that holds the app but not the host), `decide(url, kind)` → allow with its rule (`chain`, `service`, `app`, `exception`, `inline`) and target, or deny with the reason; `resolvableHosts()`, `hostResolverRules()` (the resolver backstop in Chromium's rule syntax) and `NetworkPolicy.BACKSTOP_CANARY`; with `NetworkDecision`, `NetworkException`, `NetworkPolicyData`, `NetworkRequestKind`); `observedEndpoints` (7 October 2026, from examples/notes: a host session's observed traffic judged as its policy log would be, the host's People socket, undeclared endpoints, and the coverage gaps that hide traffic, for `{actor}'s host reached only declared endpoints`); `HostNetworkRoutes` (refactor step 7 part b: the one routing model hosts use to reach an environment's chains and services, with `HostNetworkRoutesData`, `ChainRoute`, `PublicRoutesOptIn`, `HOST_NETWORKS`, `HostNetwork`, `ROUTE_IDS`; validated when built: a known network and its namespace, a People route, loopback WebSocket and HTTP routes without credentials or query unless an explicit recorded `publicRoutes` opt-in, 32-byte distinct genesis hashes). Since 3 October 2026 (backlog A4, `endpoint-locality.ts`): `EndpointLocality` (`of(endpoints)`: loopback and public endpoints, `kind` `loopback`, `public`, `mixed` or `empty`, `assertNotMixed(owner)`), `MixedEndpointsError` (`mixed-endpoints-error.ts`: names both sides and why), `HostNetworkRoutes.locality()`; `NetworkPolicy.from` refuses a mixed routing and `closeExtras` adds no closed loopback route to a public one | dot.li's private allow/deny decisions (`adapters/host/dotli/src/routing.ts`, now asking `NetworkPolicy`); fifteen loopback predicates with different host sets (core, the platform package, five adapters, the conformance probe, the MCP server, the notes example); `TopologyEndpoints` plus the `environmentAccess()` object literal; step 7 part b: the three host routing contracts (the truAPI CLI's `HostNetworkSession`/`HostRoutes`, the WASM host's `LocalChain[]`, dot.li's `LocalEndpoints` options) and env-engine's `NETWORKS` |
+| `navigation/` | `NavigationRequested`, `navigationRequest`, `parseProductUrl`, `resolveNavigation`, `NavigationTarget`, `DOTNS_TLDS`, `NavigationEvidence`; since step 9 an app's route catalogue (`app-routes.ts`: `AppNavigation`, `AppRoute`, `RouteField`, `routeFields`, `validateNavigation`, `buildRouteUrl`; imports nothing, the panel serves it to the browser as `/navigation.js`); since Phase 4 `ExpectedNavigation`, `describeDestination`, `findNavigations`, `describeNavigationRecords` (`navigation-expectation.ts`: what the generic navigation sentences match) | `core/application/src/orchestration/host/destinations.ts`, the navigation types in `host/port.ts` and `host/bridge.ts`; step 9: core's former `navigation.ts` and the route types in `core/ports` (which re-export them); Phase 4: the matching in the testing kit's `navigation.ts` |
+| `navigation/` (phase2-nav) | `destinationName`, `resolveNamedDestination`, `discoveredAppId`, `NameRecord`, `DeployedApp`, `PendingDestination`, `DestinationSource`: destinations resolved through the environment's name service in `deployed-local` (what a name points at decides; an unregistered name, or a name pointing at other content than the lab deployed, is refused; content no lab app declares is `discovered`). `NavigationTarget`'s `app` gains `cid`, `resolvedAt`, `source`, `discovered`, and `unregistered` a `reason` | new |
+| `sentences/` | Phase 4: `SentencePattern` (`{actor}`, `{string}`, `{int}`, `{count}`, `{word}`, `{app}`, `{route}`; an `{int}` or `{string}` may be an output reference; optional text `(…)` as in Cucumber, a `(s)` after a number's word its plural: `render` and `wording`, backlog 120), `TableShape` (strict DataTables: `TableSpec` columns as kinds `text`/`integer`/`boolean`/`actor`, choice lists or specs, `rows: "one" \| "many"`; `TableError` lists every problem), `OutputReference` (`$Ada.note`, `$note`), `ScenarioOutputs`, `outputValue`, `SentenceBook` (the registry: atomic kinds `action`, `assertion`, `identity`, `navigation` and, since backlog 16, `time` (`TimeAdvance`: what `the chain advances {int} blocks` and `time advances by {int} minutes` ask for, their limits, and `shortfall`, whether a chain observed before and after shows the advance); `repeatable` plurals expanded `count` times; data-only `step-group`s with `{kind}`/`{n}` placeholders, and since Phase 4 increment 2 table step groups (`RowExpansion`: each row expands to the sentences its `by` cell names, `<column>` filled, then `then` with the row as a one-row table; call origin `row`); `expand(step)` to `AtomicCall`s with their origin; duplicate, dangling-repeat, function-in-group and cycle errors), `planScenario` (the static plan: missing or ambiguous sentences, malformed tables, actors not introduced, dangling references; `PlanIssue`), `SentenceError`, `MissingSentenceError`, `AmbiguousSentenceError`, `UnresolvedReferenceError`; since backlog 38 `assertionMutants` (test the tests: one mutant per positive assertion step, its first literal `{string}` given `MUTATION_SUFFIX` or `{int}` plus 1, rendered through the sentence's own pattern; every step not changed has its reason: an absence check, found by `ABSENCE_WORDS` in the sentence's own words with `absenceWord`, since it still passes when its value changes; an earlier step's output; a step group or repeat; a custom step; and whole outlines and negative controls; a scenario with nothing to change says so plainly), `mutantSource` (the feature text with only that line's step changed) and `mutationVerdict` (killed, survived or inconclusive from the negative-control rule); framework `GENERIC_SENTENCES`, their patterns and `isGenericOwner`. Since together-steps the inline run-together sentence `{steps} at the same time` (`AT_THE_SAME_TIME_SENTENCE`, owner `lab.atTheSameTime`; `{steps}` is accepted only there): `SentenceBook.splitTogether` splits it at the " and "s outside quoted text into parts that are each one registered sentence (at most `MAX_TOGETHER_JOINS`); no reading or a part no sentence matches is a `SentenceError`, two readings an `AmbiguousSplitError` | `core/lab`'s `sentencePattern` (core/lab re-exports it) and the registry's step-group check; `core/application/src/orchestration/integrations/generic-sentences.ts` |
+| `sentences/` (characters) | Backlog 35: `CharacterDeclaration` (`defineLab({ characters })`: `steps` over `{actor}` only, `description`), `charactersDeclarationProblems`, `characterSentence` (`{actor} is <name>`), `characterOwner` (`lab.characters["<name>"]`), `isCharacterOwner`; `isGenericOwner` leaves a character out (it is the lab's own vocabulary). Tests: `core/lab/tests/characters.test.ts`. | New |
+| `sentences/` (prepared characters, no funds) | Backlog 35b and 35c: `charactersUsed` (the characters steps use, through other characters too, with their steps), `preparedCharacters` (the identities steps make one character each and nothing more), `characterActor`; `PlannedStep.prepared` / `PlanOptions.prepared` (`PreparedCharacterStep`: a step a fixture's identity meets, which introduces its actor and runs nothing); `FixtureKey.characters` (each used character's steps; a change, an addition or a removal is named); `FixtureRecord.prepared`; `FixtureBundle.checkoutDifferences` and `FixtureCatalog.match` compare it. `NEW_UNFUNDED_ACTOR_SENTENCE` (`{actor} is a new actor with no funds`, owner `lab.newUnfundedActor`). Tests: `tests/prepared-characters.test.ts`. | New |
+| `builder/` | Phase 5: the visual builder's model, no UI. `BuilderPalette` (every atomic sentence of a `SentenceBook` as a `PaletteBlock`: group, title, `via`, app, resources, availability, one `BlockField` per parameter from `ParameterHint`s, the table shape, the declared plural; `BlockInfo` is what the application adds); the document (`BuilderFeature`, `BuilderScenario`, `BuilderBlock` = `SentenceBlock`, `RepeatBlock`, `TogetherBlock`, `TextBlock`); `renderFeature` (the saved `.feature`: plurals for a Repeat whose body declares one, else `# repeat N times` … `# end repeat`, `these steps run together:` for a group (a doc string when a block has a table, backlog 113), or `<A> and <B> at the same time` for one with `form: "inline"` (a loaded inline step keeps it; the `together` edit takes `form`), `# checkpoint`), `readFeature` (a file back into blocks; `NotRepresentable` items: steps kept as text blocks (a doc-string group with a composed part with its `docString`), structures (Background, outline, rule, other doc strings, comment) make the load lossy), `checkScenario` / `checkFeature` (the static plan mapped to blocks, scopes, actors, checkpoints, `togetherSchedule`), `roundTripDifferences` and `saveFeature` (`RoundTripError` when the saved form does not load back into the same blocks), `applyEdit` with `BuilderEdit` (add, move, remove, repeat, together (the gate: `togetherProblems`), ungroup, count, values, table, checkpoint, actors, rename), `newBlock`, `bindingProblems`, `BuilderError`. Since panel-builder (28 September 2026): `PaletteBlock.introduces` (the parameter or column that names new actors); `ACTOR_ROSTER` and `nextActorName` (a new actor's name: the first roster name not in the cast, then Actor1, Actor2…), used by `newBlock` and `defaultTable` (a table whose columns are all optional starts with the first; `renderFeature` refuses a table with no columns); the `actors` edit refuses a name already in the cast and extends the first `these actors exist:` table; `checkScenario(scenario, palette, bound, options)` reports a name introduced twice ("Ada is already in the cast"; `bound` actors, such as a Background's, are in scope) and, with `CheckOptions.custom`, lists the text blocks a custom step runs (`ScenarioCheck.custom`) and warns only for undefined ones; `readFeature` returns a Background's steps as `LoadedFeature.background` (still a structure that makes the load lossy). `tests/builder-cast.test.ts`. The `sentences/` book gains the kind `together` (a table of step texts, each one action or assertion; `CallOrigin` kind `together`). Backlog 113: doc-string parts with their own tables and composed parts (`SentenceBook.docStringParts`, `SentenceError.docLine`, `PlanIssue.docLine`; `tests/together-doc-string.test.ts`) | new |
+| `products/` (phase2-nav) | `ProductConfig` (a product's manifest grants, `trustedProducts`, in the publisher's `LocalProductConfig` shape, validated as the truAPI host reads it; `grants(caller, scope)`), `GRANT_SCOPES`, `bareProductLabel`, `decideProductConfig` with `ProductConfigDecision` and `ProductConfigRefused` (a product config goes only to a host routed to this machine and naming no endpoint off it, unless an opt-in with its reason is recorded) | new; `productConfigFor` in deploy-bulletin writes the same shape |
+| `versions/` | Phase 6: `VersionSelector` (parses and validates `locked`, `deployed`, `latest-release`, explicit versions, `release:owner/repo@tag` / `{ release }`, `git:<repo>@<ref>` / `{ git, ref }`; `moving`, `isCommit`; refuses `latest`, `deployed-ios`/`-android` and invalid refs with what to write instead), `gitRefProblem`, `ComponentId` (`runtime:people`, `host:truapi-cli`; kinds runtime, binary, host, app, tool), `Digest` (`sha256`, `sha512` (an npm tarball's integrity, backlog 27), `blake2-256`, `git-sha1`), `ReleaseVersion` (ordering, pre-releases first), `VersionPolicy` (the lab's selectors; `override` for candidates), `LockedComponent` (one lock entry: version, `ComponentSource` (github-release, git, npm with its package, network with its block), named digests, the selector it came from, never `locked`, no secret-looking attributes), `LabLock` (`lab.lock.json`, schema 1, strict parse, `with`/`without`, `changesTo`), `VersionResolution` (what a run resolved: origin per component, candidates, every `FetchRecord`, `writesLock` always false; `recordedTarget` strips queries and credentials), `VersionDrift` (upgrade, downgrade, changed), `VersionWorkspaceKey` (one workspace per combination), `RecoveryPolicy` (resume only the same combination; refuse a downgrade or version change; never a reset), `SnapshotFreshness` (a fork snapshot against a `deployed` resolution), `VersionError`; G2 (29 September 2026): `LockPromotion` (the exact candidate entries replace the lock's, judged against a control that ran the current lock; refuses a stale lock, a control that is not the lock, a candidate that differs elsewhere, an uncovered or unchanged candidate; never resolves) and `LockProposalRefusal` with `LockProposalRefusalCode` / `LOCK_PROPOSAL_REFUSALS`; for environments (`wip/versions-env`): `ResolvedRuntime` (a resolution's runtime entry: chain, network, resolved block, code and genesis digests, spec; `compare(observed)` against what an environment runs, never `ok` without a code digest), `EnvironmentVersions` (split a resolution for one environment: runtimes of its chains, refusals for other networks and resolved binaries, the rest not applicable), `decideHostRoute` (backlog 27, `host-route.ts`: how a suite row runs a newer host release, official when the published release shows every needed capability, patched when the patches for what it lacks and those they apply after apply, otherwise unsupported naming the patch and its files; blocked or untested probes are no proof), `VersionedWorkspace` (`select(name, resolution)` → `<name>.versions-<key>`, `resume({ name, recorded, current })`: the recovery policy, and refusals when versions are known on one side only or the name carries another key) | nothing (new in Phase 6; the truAPI CLI's interim `host.lock.json` stays in its adapter) |
+| `suites/` | Phase 7: `SuitesData` (`defineLab({ suites })`: `scopes`, `pr`, `merge`, `nightly`; `SuiteData`, `MatrixRowData`, `ChangeScopeData`, `SUITE_NAMES`), `SuiteConfig` (validated once: known suites, a matrix only in nightly, pr/merge locked, affected selection needs scopes, budgets; config redesign: `ModeData` (`defineLab({ modes })`), each mode translated onto a declared suite of its name, `SuiteConfig.from(suites, modes)`, `mode(name)`, `modeNames()`: rows are environments × hosts × versions × devices named by what varies, `latest` is every policy component and the row's host when its source is declared, at `latest-release` (`EVERY_COMPONENT`; the lab's `unsupported["*"]` says why there is nothing to resolve), a device the browser does not name is unsupported, `onlyAffected` selects changed feature files (`ChangeScopes.affected(…, { byFeatureFile })`, selection `features`), `workers` shares one combination out by feature file (`SuitePlanRow.paths`, `SuitePlan.workers`); `tests/modes.test.ts`), `parseBudget`, `globMatcher`, `ChangeScopes` (changed paths → touched scopes; documentation touches nothing, a path outside the lab or in no scope runs the whole suite), `planSuite` (rows with tags, environment, host, candidates, previewed scenarios; `unsupported` and `empty` rows with the reason; `@manual` and `@negative-control` never run: `SUITE_EXCLUDED_TAGS`; a mode's `runtime-latest` and `hosts-latest` rows move only `EVERY_RUNTIME` (`runtime:*`) or `ROW_HOST` (`host:*`, the row's host), and its own `scopes` (`ChangeScopes.byGlob`) replace `suites.scopes`, since 7 October 2026; given the lab's `scenarioEnvironments`, a row previews only the scenarios whose `@environment:`, `@live-network` and `@root-calls` tags fit its environment, by the rule its run applies, `selectsOnEnvironment`, since 7 October 2026), `judgeSuite` (passes only when a row ran and every row that ran passed within budget; unsupported and empty never pass; a suite that selects nothing fails), `SuiteConfigError`; G2: `SuiteEvidenceError` (`code` and `evidence`: what the suite evidence store refused and in which file) | new; generalizes `entrypoints/cucumber/src/ci/change-scope.ts` |
+| `recordings/` | Phase 9: `RunRecordingData` and its parts (since 3 October 2026, backlog 20: `RecordedFeature`, where a feature scenario was written, and `RunnerFailure`, a failure its runner reported outside the lab's runs; `RecordedStep`, `RecordedFrame` with `phase`, `status`, `overlapping` and `media`, `ChainObservation`, `RecordedTransaction` (with `submittedAt` and `includedAt` since 29 September 2026, for the replay's run timeline), `RecordingCapture`, `RecordingSummary`; `RECORDING_SCHEMA_VERSION`), `RunRecording` (validates a stored recording, `summary`, `lanes`, and `framePair(step, actor)`: which frame shows an identity's app before and after a step, settled frames first, with a note on how each frame relates to the step, never another identity's frame), `RecordingRetention` (count, age and size limits applied on write, oldest first, never the recording just written; `DEFAULT` 50 recordings, 30 days, 500 MB), `StepSpeedLimits` (backlog 29), `StepChainWindows`, `RecordedChainChanges` (backlog 22), `StepConsoleErrors`, `RecordedConsole` (backlog 23), `RecordingHealth`, `RecordedHealth`, `HealthSample` (backlog 25), `RecordedHostRequests` (backlog 41), `RecordedFeatureStep` and `RunRecordingData.featureSteps` (backlog 110: a feature scenario's Gherkin steps with their times, those that ran no lab run included), `RecordedUiCalls` and `RecordedUiCall` (backlog 110: what each step did on screen in the lab window, each call's identity, call, target as a person names it, start, duration and outcome; `RunRecordingData.uiCalls`, absent for a run with no visible surface), `RecordingSettings` (`fromVariables`: `PRODUCT_LAB_RECORDINGS` frames/steps/off, the retention variables in `RECORDING_VARIABLES`, and since backlog 18b `PRODUCT_LAB_RECORDINGS_VIDEO` on/off, `video`), `RecordedVideo` and `RecordingCapture.videos` (backlog 18b, headless half; 52: each video's source, identity, `videos/<name>` file and wall-clock `openedAt`; `RunRecording.videoSpans()` gives where the recording starts and ends in each), `RecordedRace` (backlog 32: the run's and the scenario's seeds, the longest wait and every wait; field `runSeed`, since the redactor hides any field named `seed`), `RecordingFormatError`; since hot reload a step's optional `appBuilds` (the app builds it ran against); since backlog 20 (3 October 2026) the optional `feature` (`RecordedFeature`: the scenario's file, line, tags and the fixture it started from with what was done with it; a recording without it reads as before) | new |
+| `recordings/recording-health.ts`, `recordings/step-machine.ts` | Backlog 241: a health sample's optional CPU idle share, loop delay and utilization and memory pressure. Where measured, the idle share (under 10 %) and the pressure (warn, critical) decide whether the machine was the limit instead of the load and free memory, and a loop busy 0.9 or more, or over 1 s late, names the lab's own loop (`StepHealth.limits`). `describeStepMachine` (`@product-lab/domain/recordings/step-machine`) imports nothing, so the lab window loads it |
+| `checks/` | Backlog 40: the checks a feature step can run after it passes. `scenarioChecks(tags, declared)`: off by default; `@visual` or `@accessibility` (or the lab's `checks.<kind>.all`) turns one on, with the lab's settings (`StepChecksDeclaration`: `visual.threshold`, default `DEFAULT_VISUAL_THRESHOLD` 0.1% of the pixels, `visual.mask`, `visual.settled` and `visual.settleTimeoutMs` (default `DEFAULT_SETTLE_TIMEOUT_MS`, 120 s; since isolation-92b: selectors of the app's own elements whose presence means its screen is at rest, waited for before each screenshot; `unsettledReason` names the selector and the wait when one never shows), `accessibility.failOn`, default serious and critical, `accessibility.rules`, `accessibility.ignore`: rule ids whose findings never fail a step, never also in `rules`); `stepChecksProblems` names each wrong field; `baselinePath(feature, scenario, step, actor, { host, device })` puts a baseline beside the feature (`<feature dir>/__baselines__/<feature>/<scenario>/<host kind>/<step>-<actor>.png`, keyed by the scenario's own actor name, one folder per host kind: a host shapes what the app shows; on a device profile, backlog 31c, a `<device>/` folder inside it; `DEVICE_VARIABLE`, `PRODUCT_LAB_DEVICE`); `CONTROL_RUN_VARIABLE` (`PRODUCT_LAB_CONTROL_RUN=1` in a negative control's run, lane speed 7 October 2026: a lab may bound a check the control fails more tightly where its positives are measured fast, and says which bound it used); `baselineMode` (`PRODUCT_LAB_BASELINES`: `write-missing` by default, `update`, `strict`); `visualVerdict` (a count against the threshold; a size change always fails); `accessibilityFailures` (the findings at a failing impact, each with its elements, and apart the ignored rules' findings); `StepCheckError`. Tests: `tests/step-checks.test.ts`. Backlog 110: `SideReading`, `SIDE_READINGS_KEY`, `sideReadings(attached)` and `readingRecorder(attach)`: what one side of a check read (a screen, or a chain or store), with what was expected and found, kept on the step (`AssertionContext.reading`). | New |
+| `recordings/` (demos) | Backlog 36: `demoSteps` (a recording's steps with their times in one of its videos and their Gherkin text), `planDemo` (the cut: each action at real speed, its result held, waits sped up and labelled, `×8 waiting for finality`; over `maxSeconds` the waits speed up first; `DEMO_DEFAULTS`), `demoVtt` (the captions as WebVTT), `DemoStep`, `DemoSegment`, `DemoCaption`, `DemoPlan`; `DemoRefusedError` (`missing-tools` or `refused`). Tests: `tests/demo-cut.test.ts` (with a 200-round property test: every real-speed moment is kept, the cut is never longer than asked when it can fit). | New |
+| `recordings/` (journeys) | Backlog 47: `JourneyDocument.of(recording, scenario?)`, a walkthrough (`Journey`) of a feature scenario from its recording: each Gherkin step (Background first) with the acting identity's screenshot (after the step, else before, with its timing note; else why none), names by role, and captions that state only what the recording proves (a transaction finalized only with that status, a block final only when its window followed the finalized head, otherwise "included, not yet final"; a gap is named, never left out; unrecorded steps marked); `JourneyMarkdown` (`page`, `index`, given the caller's `JourneyTime` formatter: the same document renders the same bytes); `JourneysDeclaration`, `journeysDeclarationProblems`, `JOURNEY_TAG`, `JOURNEYS_OUT` (`defineLab({ journeys })`). Tests: `tests/journey-document.test.ts`. | New |
+| `conditions/` | Backlog 31 (3 October 2026): per-actor conditions as values. `NetworkCondition` (`online`, `offline`, or `throttled` with latency and optional throughput; offline is phone semantics: the app keeps its local link to its host, and neither reaches the chain), `networkConditionProblems`, `describeNetwork`; `CpuSlowdown` (1, 2, 4, 6) and `cpuSlowdown`; `ConditionProfiles` (the built-in `slow-3g`, `fast-3g`, `slow-wifi`, and a lab's own, resolved by name; a built-in one is never redefined); `ConditionStep` and the four generic condition sentences (`{actor}'s network is {string}`, `{actor} goes offline`, `{actor} comes back online`, `{actor}'s device is {int} times slower`, sentence kind `condition`); `trafficDecision` and `isLocalLink` (what a network condition does to one request or socket message, the identity's local link to its host exempt: every surface routes through it); `ConditionedWire` (one direction of a stream under a condition: a piece's arrival time, a burst carried at its speed, never out of order, lost while offline; it queues what is in flight and the surface hands on what is `due`); `ConditionError`. `HostCapabilities.conditions` (and the requirement `conditions`) says a host's sessions carry them; `RecordedStep.conditions` notes them per step (`tests/conditions.test.ts`) |
+| `load/` | Backlog 43 (load), subpath `@product-lab/domain/load`: `loadPlan` (a load as generic sentences: `these actors exist:` with `Load1`…, then `these steps run together:` with the action for every identity, `each` times, round by round; `LOAD_LIMITS` 64 identities, 20 calls each; every bad request named at once), `loadGuardTrip` and `DEFAULT_LOAD_GUARD` (stop above 1.5 load per CPU, above load 64 or below 2 GB of free memory, with why), `loadReport` (from a recording only: finalized per second, submission to inclusion and to finality as p50/p95/max with unknowns counted, failed steps by `failureMarker`, peak concurrency, best-to-finalized lag, machine load) (`tests/load.test.ts`) |
+| `apps/` | Hot reload of app code (backlog item 5): `AppWatchDeclaration` (what `apps.<id>.watch` declares: `paths`, `ignore`, `restart`, `rebuild`, `debounceMs`), `AppWatch` (`parse` validates it naming the field; `classify` splits changed paths into restart and reload, a restart path inside a reloading directory winning; `ignores`, `inBuild`, `watched`), `AppChange`, `APP_WATCH_ALWAYS_IGNORED` (`node_modules`, `.product-lab`, `.git`), `APP_WATCH_DEBOUNCE_MS`, `APP_REBUILD_TIMEOUT_MS`; `appBuildMessage` and `AppBuildOutcome` (the one line a build shows: "<app label> reloaded (build 3, 1.2 s)"). `tests/app-watch.test.ts`. Backlog item 62: `AppReadiness` (`parse` validates `apps.<id>.ready` naming the field; `steps`, `signal`, `failed`, `timeoutMs`, `describe()`), `AppReadyDeclaration`, `ReadySignalDeclaration`, `ReadyStepDeclaration`, `ElementDeclaration`, `ElementTarget`, `describeElement`, `APP_READY_TIMEOUT_MS`; `AppAccountSource` (`apps.<id>.account`: `"host"` or a page reader, the fallback for a host that cannot tell), `AppAccountDeclaration`. `tests/app-readiness.test.ts` | new |
+| `apps/` (continued) | Backlog items 64 to 66: `AppDevServerDeclaration` and `AppDevServer` (what `apps.<id>.devServer` declares: `command`, `args` with `{port}`, `cwd`, `env`, `port`, `settings` names for the product id, the chains' genesis hashes and the endpoints, `readyPath`, `startTimeoutMs`, `updates`; `parse` validates it naming the field, `vite` is the default, `plan` turns it into the process to start and refuses a setting that names a chain or an endpoint the environment does not have), `settingsHint` (what "not ready" adds: the setting names the lab gave); `injectScriptTag` and `isHtmlContentType` (`html-script.ts`: one script tag after `<head>`, shared by the gateway over deployed bytes and the lab's proxy); `FramingHeaders`, `FramingRefusal`, `framingRefusal` (as a browser decides: `frame-ancestors` alone when a policy has one, else `X-Frame-Options`), `framingRefusalAnywhere` (before the framing page is known), `framingHeaders`, `framingRefusalMessage` (the one sentence shown everywhere; the header is never removed); `AppBuildOutcome` gained `following`, `updated`, `dev-server-error`, `dev-server-gone` and `not-held`. `tests/app-dev-server.test.ts`, `tests/app-framing.test.ts`. Backlog A5 (second half): `AppDeployedDeclaration` and `AppDeployedSource` (`app-deployed-source.ts`: `apps.<id>.deployed`, a DotNS `name` or the web gateway's `url` translated to it, a `cid` pin, `ipfsGateway`: on by default only for a public network, `resolveOn`: an Asset Hub RPC origin to resolve the name on instead of the environment's, read-only, absent by default (27 October 2026), `networkProblem` for a name of another network) and `DEPLOY_NETWORKS` (each public network's TLD, web gateway and IPFS gateway, from bulletin-deploy 0.21.0's `environments.json`); `tests/app-deployed-source.test.ts` |
+| `releases/` | product-lab's own versions (`./releases`; 2 October 2026): `parseChangelog` (a changesets `CHANGELOG.md` into `ReleaseEntry` per version: `breaking` from "Major Changes", `changes` from the rest, commit prefixes dropped), `compareVersions` (semantic version precedence, prereleases first), `isVersion`, `releaseChannel` (the dist-tag a version follows: `latest`, `next`, `canary` or `dev`), `entriesBetween` (after one version up to another, newest first), `headline` (a change's first sentence), `ReleaseNotice` (what is new since a repository's last used version, a newer published version, the fix) and `releaseNoticeLines` (the terminal text, breaking changes first). Pure: the CLI reads the files and the registry. `tests/release-notes.test.ts` | new |
+| `devices/` | Backlogs 31a, 31b and 31d (3 October 2026): `DeviceProfile` (the device an identity's app is shown as: `name`, CSS `viewport`, `deviceScaleFactor` (at most 5: Playwright names a 4.5 phone), `mobile`, `touch`, optional `userAgent`; chosen when a surface opens, never changed during a scenario; network and CPU are backlog 31's `ConditionControl`), `DeviceChoice` (a name or a written-out profile), `DESKTOP_DEVICE`, `DEVICE_LIMITS`, `deviceProfileProblems` (each problem named by its field), `resolveDevice` (against a catalogue the caller supplies: exact name, then ignoring case; an unknown name is refused with the nearest names, never replaced), `nearestDeviceNames`. Named devices such as "Pixel 7" come from the browser adapter's registry, not from here. `tests/device-profile.test.ts`. 22 October 2026: `SYNTHETIC_MEDIA_ARGS` (Chromium's synthetic camera and microphone, prompts accepted) and `withSyntheticMedia(options)` (those arguments first, once, then the caller's): every lab browser runs them, so no lab run can prompt for or take the machine's camera or microphone (`tests/synthetic-media.test.ts`; the repository-wide scan is `tools/architecture/tests/synthetic-media.test.ts`) | new |
+| `root-calls/` | 4 October 2026: `RootCallPolicyData` (`defineLab({ rootCalls })`: `key`, `allow`, `signing`), `rootCallPolicyProblems`, `parseRootCallName`, `CALL_CARRYING_PALLETS`, `rootCallDecision` (in order: a policy, never a mainnet, a chain the lab started or a public testnet known by genesis and declared writable, a call that carries no other call and is on the allow-list, the session's confirmation), `KNOWN_CHAINS` and `knownChain` (Polkadot and Kusama mainnets and their system chains, next-v2 and previewnet People and Asset Hub, by genesis hash) | new |
+| `lab/` (new identities, 4 October 2026) | `NewIdentitiesData` and `newIdentitiesProblems`: `PublicTargetData.newIdentities` (`funder`, `usernamePrefix`, `fund` by chain in planck, `maxPerRun` 1 to 10), only on a `read-write` target; `PublicTarget.newIdentities` and its notice | new |
+| `lab/` (environment options, backlog 184) | `EnvironmentOption`, `MachineNeeds`, `MachineSize`, `OptionPick`; `pickEnvironmentOption(options, machine, chosen?)`: the person's choice wins; else the first option (the default) when the machine meets its needs; else the first that fits; else the last; always with why in words. `machineSize`, `fitsMachine`, `needsSentence` (`tests/environment-options.test.ts`) | new |
+| `lab/` (the running lab, B1 step a) | `besideRunningLab(running)`: what a start beside a lab another process runs in the same folder says, naming its window, its process and what to do; MCP `env_start` and a second `bun run lab` say it word for word (their tests pin it); `runtime-wire.ts` (B1): `ATTACHED_RUNTIME_CALLS`, `toWire`/`fromWire` (bigints) and `encodeRuntimeError`/`decodeRuntimeError` (typed errors across the window's runtime API) | new |
+| `accounts/` (subpath `@product-lab/domain/accounts`) | Backlog item 62: `AccountAddress` (`parse`, `tryParse`, `fromPublicKey`; `kind` `account` or `h160`, `prefix`, `publicKey`, `hex`, `ss58(prefix)`, `h160(mapping)`, `same(other, comparison)`), `AccountComparison` and `H160Mapping` (`"revive"` only), `AccountFormatError`, `AmbiguousAccountError` (a 20-byte address against a 32-byte account with no mapping named), `ExpectedAccount` (an expected value matched as an account in any form), and the functions `sameAccount`, `expectedAccount`, `accountPublicKey`, `accountSs58`. `hashes.ts` holds the pure BLAKE2b and Keccak-256 it needs (the domain has no dependency; cross-checked against `@noble/hashes`). `tests/accounts.test.ts` | exact string comparison of addresses in the default session and `chainEventAssertion` |
+| `features/` | Backlog 17 (30 September 2026): `StepBreakpoints` and `StepBreakpoint` (`step-breakpoints.ts`: parse and validate the saved document, `stale` when a step changed, `with`, `without`, `of`). Step 8: `parseFeature`, (Phase 5: `gherkinCells`), `FeatureFile`, `FeatureScenario`, `FeatureStep`, `StepSentence`; `matchesTags`; `relativeFeaturePath`; since scenario conditions (28 September 2026, `scenario-conditions.ts`) `TagCondition` (`{ tag, fits, reason }`, what an integration's `scenarioConditions` returns), `UnmetCondition`, `validateTagConditions`, `mergeTagConditions` (a tag fits only when every condition on it fits), `unmetConditions(tags, conditions)`, `describeUnmet` ("Not for this chain: <reason> (@tag)"), `excludingTags(expression, tags)` and `selectsWithConditions` (`tests/scenario-conditions.test.ts`). Phase 4 (for `product-lab lint`): a step's DataTable (`FeatureStep.table`), the Background in effect (`FeatureScenario.background`, a Rule's adding to the feature's) and an outline's `examples` (each Examples block's own header is read, its rows mapped onto the first block's columns: Phase 4 increment 2); `FeatureScenario.actors` (the names its identity steps introduce; the runtime's listing fills it). Since panel-gherkin (28 September 2026, so the panel can show any Gherkin) the model keeps, additively: `FeatureStep.docString` (`FeatureDocString`: both fences, media type, the fence's indentation removed, the first escaped fence of a line unescaped); `FeatureScenario.kind` (`outline` for Scenario Outline / Template and a Scenario with Examples), `description`, `ownTags`, `featureTags` (`tags` is the effective union: feature, Rule, own, as Cucumber tags a pickle), `rule` (`FeatureRule`), `backgroundName`, `examplesBlocks` (`FeatureExamplesBlock`: each block's name, line, tags, description and table), `markers` (`FeatureMarker`: comment lines inside the scenario, such as the builder's `checkpoint`, `repeat N times`, `end repeat`) and `variants` (`FeatureVariant`: one per Examples row, named exactly as Cucumber names the pickle, with its 1-based `example`, `block`, row `line` and `values`); `FeatureFile.line` and `description`. `gherkinCells` reads cells as Gherkin does (an unknown escape keeps its backslash). English keywords; other languages are left alone. `tests/feature-gherkin.test.ts` (fixtures in `tests/fixtures/gherkin/`). Since 2 October 2026 (`cleanup-report.ts`): `CLEANUP_REPORT_ENV`, `CLEANUP_REPORT_FILE`, `CLEANUP_RESULT_NAME`, `CleanupFailure`, `CleanupReport`, `describeCleanupFailure` (an `AggregateError`'s errors and an `Error`'s cause as a bounded tree), `cleanupFailureLines` and `cleanupReport`: the environment cleanup failure the Cucumber hooks record and the runner reports as its own result; the features-cucumber adapter's `tests/gherkin-parity.test.ts` compares it with Cucumber's own plan | the MCP server's former `gherkin.ts` |
+| `shared/` | `SecretUri`, `DEVELOPMENT_PHRASE`, `MissingCapabilityError`, `MissingRouteError` (step 7 part b: a host needs a route the routing lacks), `DEVELOPMENT_AUTHORITY` (refactor step 7: `//Alice` and its public key, the development authority account env-attached probes for and env-chopsticks installs (the `devAuthority` capability); pinned against `Sr25519KeyDerivation` in keys-sr25519's tests); `parseAdapterOptions` and its structural `ParsingSchema` (L1: one error naming every problem of an adapter's options, for any `safeParse` schema) | the keys adapter's former `secret-uri.ts` (it re-exports `SecretUri` and keeps derivation); the error and `parseAdapterOptions` in `core/lab/src/topology.ts` |
+| `lab/` (L1) | `HostCapabilities`, `HostRequirement`, `ApprovalPolicy` (what a host declares; `@product-lab/ports/host` re-exports them) and `hostSupports` | `core/ports/src/driven/host/host-provider.ts`; `hostSupports` from `core/application/src/orchestration/host/port.ts` |
+| `navigation/` (L1) | `appUrl` (structural `AddressableApp`: the ports' `HostApp` satisfies it) and `appUrlAt` | `core/application/src/orchestration/host/port.ts` |
+| `shared/` (L1) | `UnsupportedHostOperation` (a host cannot perform an operation; names what is missing); since 21 October 2026 `siblingModule(specifier, base)` (`sibling-module.ts`): a module loaded by path rather than imported, in the form its referrer runs as, `.ts` from the sources and `.js` in the compiled package (tools/eval/src/build.ts); `tests/sibling-module.test.ts` | `core/application/src/orchestration/host/port.ts` |
+| `lab/`, `shared/` (q10-errors) | Typed errors callers branch on instead of the message: `LabConfigurationError` (`problems`), `EnvironmentRequestError` (a request refused before anything starts), `ConfirmationRequiredError` (`action: "reset"`), `JsonRpcError` (`method`, `rpcMessage`, `rpcCode`: a JSON-RPC `error` reply), `BlockUnavailableError` (`block`: a read at a block whose state the node or client does not hold), `MissingHostToolsError` (`file`); since q10-errors-runs `ScenarioInputError` in `runs/` (`code`: `not-an-object`,
+| `fixtures/` (29 September 2026) | `FixtureDeclaration` and `fixtureDeclarationProblems` (`defineLab({ fixtures })`: `setup`, `environment`, `inputs`, `description`); `FixtureKey` (`from`, `differences(current)`: one sentence per changed part: the setup file, lab.lock.json, the declared inputs, each chain's runtime, the state's lineage); `FixtureRecord` (`create`, `parse`, `bindings()`, `toJSON`; `FixtureEnvironmentSnapshot`); `FixtureRefusedError` (`reasons`; nothing was changed); since 30 September 2026 (backlogs 1b and 1c) `scenarioFixture(tags)` (the fixture a scenario's `@fixture:<name>` tag names, whether it carries `@fixture-shared`, and every problem: an empty or invalid name, two fixtures), `FIXTURE_TAG`, `SHARED_FIXTURE_TAG`; `ISOLATED_TAG`, `isolatedScenario(tags)` and `ISOLATED_START_FIXTURE` (backlog 17h, 3 October 2026: `@isolated` asks for the state back; the reserved fixture name it is saved under, refused in a declaration); `FixtureRecord.expires` and `expired(now)` (state that follows the chain's clock, backlog 1a) and an optional `FixtureKey.setup` (a fixture saved from the running state, backlog 1h); fixtures built on fixtures (backlog 1f, 3 October 2026): `FixtureDeclaration.from` (a declared fixture on the same environment, no cycles, else a problem), `fixtureBases(declared, name)` (nearest first) and an optional `FixtureKey.base` (one digest of every base's setup and inputs, so a changed base makes it stale) | nothing: new. An example's checkpoint and template mechanism was specific to its fork; this is the generic form |
+| `fixtures/` (fixture sharing, 30 September 2026) | `FixtureBundle` (`create`, `parse`, `withParts`, `checkoutDifferences`: the setup, lock and declared inputs against the key; `platformDifferences`; `relocate`/`unrelocatable`: session directories from the exporting lab to the importing one; `compressedBytes`; always `containsTestKeys` with `TEST_KEYS_NOTICE`), `FixtureBundleFile`, `FixtureBundlePart`, `FixturePlatform`; `FixtureRecord.history` (`FixtureHistoryEntry`: `imported`, `upgraded`, `rebuilt`); `FixtureCatalog` (a source's `manifest.json`: `parse`, `entryOf` a written bundle, `with` an entry replacing the same fixture, platform and checkout, `match`: the newest entry that fits the checkout and platform, or each entry's reason), `FixtureCatalogEntry`, `FIXTURE_CATALOG_KIND`; `FixtureSourceDeclaration` (`GithubReleaseFixtureSource`: repository, tag, attestation policy, signer workflow; `DirectoryFixtureSource`: path) and `fixtureSourceProblems` | nothing: new Since backlog 77: `FixtureImportIncompleteError`, an import that failed after it began replacing the environment's state (a caller must not run a setup on what it left); `unrelocatable()` is informative only, since an importer places session state kept outside the exporting lab on its own session's directories. Since backlog 242 the bundle's environment may name `workspace`, the directory the state was saved in (absolute; absent in older bundles) |
+| `lab/` (value tones, 29 September 2026) | `ValueTones` (`key`, `errors`, `merge`, `toneOf`, `toJSON`), `VALUE_TONES`, `ValueTone`, `ValueToneDeclaration`: an integration's `valueTones` validated (a plain object; tones `success`, `warning`, `danger`, `neutral`; one value never given two tones), normalised (trimmed, lower-cased) and merged across a lab's integrations (a value two integrations tone differently is an error) | the product words hard-coded in `entrypoints/panel/src/client/gherkin-view.ts` `cellTone` |
+| `statements/` (config redesign, 6 October 2026) | Beside `decodeStatement` and the statement encoding: `statementTopic(name)` (blake2b-256 of a name's UTF-8 bytes, or of bytes: a 32-byte topic) and `checkContent(cid, bytes)` (`ContentCheck`: a raw blake2b-256 CIDv1 in base32 is hashed again, `hashed` or `mismatch`; any other CID, or more than `CONTENT_REHASH_LIMIT` bytes, is `blocks`: left to the Bulletin reader's block check, with why), for the lab's `statementReader` (`tests/content-check.test.ts`) | `examples/notes/lab/store.ts` (its topics hashed with @noble/hashes) |
+| `agreement/` (30 September 2026, backlog 61) | UI and chain agreement, the rule behind `checkUiAgainstChain`: `AgreementMode` (`pinned`, `eventual`, `optimistic`), `AGREEMENT_MODES`, `AGREEMENT_MODE_USE` (when each applies, one line each) and `AGREEMENT_PROVES` (what a pass proves); `AgreementSettings` (`of`, `problems`: the bound `withinMs`, the stability period `stableMs`, `pollMs`, `blockWithinMs`, `subject`, `finality`; a mode that is not one is refused naming the three); `AgreementSample` and its readings (`ScreenReading`, `ChainReading`, `PinnedReading`, `PendingTransaction`, `ShownBlock`, `AgreementBlock`: one round of readings, with its time as a value); `AgreementJudge` (`observe(sample)`: waiting, agreed or failed; `backingBlock`: the best block that last backed an optimistic claim), a pure rule with no clock; the record `UiChainAgreement` (`mode`, `proves`, `reached`, the screen and chain readings with their blocks, `agreedAt`, `timing`, `readings`, `lost`, `backing`, `pendingSource`, `timeline`) with `AgreementState`, `AgreementFailure`, `AgreementBacking`, `AgreementStep`; `UiChainDisagreementError` (`reason`, `agreement`); `agreementSummaries` and `AGREEMENTS_KEY` (a step's attached records in short, for its trace); claims: `sameClaim` (structural equality), `sameFields(...)` (a field match), `claimText` | new: each example compared its screen with the chain in its own way (`examples/notes` `readShownNote`, another example's reader waiting two seconds for a stable screen) |
+`unknown-input`, `missing-value`, `invalid-value`; `input`: the input's key). Each keeps the message people read. `NegativeControl.judge`'s `wrong-reason` verdict also says what mismatched (`mismatch`: `step` or `marker`); the marker itself is text by design | `EnvironmentRequestError` from `core/application/src/environment/` (which re-exports it); the others replace plain `Error`s whose message callers matched |
+
+`features/plain-output.ts` (backlog 186, `tests/plain-output.test.ts`): the plain output of `product-lab test`. It holds
+`PLAIN_OUTPUT_ENV`, `plainOutput` and `PLAIN_MARK`/`plainLine` (the mark that tells the run's lines from the lab's), plus
+`shortIds` (a hash, account or content id of 32 or more letters and digits, with a digit, keeps its ends) and
+`plainDuration`. `stepSidesWords` (`StepSidesCall`) gives a step's screen and chain checks in the lab window's words,
+from its readings, completed chain waits and host-signed transactions, never from the lab's own or the chain's own entries.
+
+`@product-lab/core` re-exports what its callers used (`checkRequirements`, `EnvironmentAccess`, `ProvisionedIdentity`,
+`resolveNavigation`, `Resource`, …), so examples and entry points did not change their imports.
+
+L1 also moved pure topology decisions into `lab/topology-functions.ts`: default capability reasons,
+offers and requirement availability, issue validation, sensitive-value redaction, guarded endpoint access and
+the text description. `TopologyError` lives in `lab/topology-error.ts`. The lab package keeps its Zod
+adapter-option schemas. `runManifest(topology, { now, … })` (q10-arch) joined `createRunManifest` in
+`lab/run-manifest.ts`: the same manifest from a caller's `Date`, which is required. `ForkSnapshot` is now a versions data type,
+and `RunManifest` is a lab data type; core re-exports both.
+The network folder also owns `absentGenesis` and `closeExtras`: deterministic closed routes for ids
+that a running environment does not offer. `hostRoutesFor`, which checks ports through `PortAllocator`,
+remains in the application's orchestration (`core/application/src/orchestration/host/host-routes.ts`).
+`lab/run-manifest.ts` owns `createRunManifest(topology, createdAt, options)`: it redacts sensitive
+topology values and takes its timestamp from the caller, so the domain does not read a clock.
+`shared/` also exports `UnsupportedCapabilityError` from `@product-lab/domain/shared` and the root export. It
+identifies an optional runtime capability that is absent, with a stable code and a capability name.
+
+A `Run` is `idle` → `running` ⇄ `pausing`/`paused` → `cancelling` → one of `complete`, `failed`, `cancelled`.
+The scheduler uses the whole machine; the `Execution.status` a run reports (`@product-lab/ports/driving`) never
+shows `idle` and shows `pausing` as `running` (`ScenarioRun` in `core/application`). Since step 4 the lab controller
+(removed in step 9) and the scheduler both reported `complete` (the scheduler said `completed`, and `succeeded` for
+a step).
+
+## Race hunting
+
+Backlog 32 (4 October 2026), in `runs/`: `RaceSeed`
+(`race-seed.ts`: 8 hex digits; `run(index)`, run 0 being the seed itself, and `scenario(where)`, each scenario's own)
+and `RaceJitter` (`race-jitter.ts`, mulberry32: a wait up to `maxMs` before an identity's step that follows another
+identity's and before every identity's step in a run-together group, never before the environment's or setup work;
+`delays()`, `RaceDelay`). `tests/race-jitter.test.ts`.
+
+## Exploration
+
+Backlog 39 (4 October 2026), in `explore/` (also
+`@product-lab/domain/explore`): `SeededRandom` (mulberry32, shared with `RaceJitter`: `next`, `int`, `pick`; a seed is a
+whole number from 0 to 4294967295); `ExplorationAlphabet` (`from(palette blocks)`: the block that introduces a new actor
+and every available action that does not opt out with `explore: false`, takes no table and whose every parameter can
+be filled; `sample(random, { steps, actors })`, `introduce`, `actorsOf`, `simpler`) and `ExploreStep`; `shrinkSteps`
+(delta debugging over the steps, then simpler values, keeping a candidate only while the caller's predicate says it
+still fails; `limit` tries, default 200); `ExploreFailure`, `errorShape` (numbers, hex and quoted text left out) and
+`failureSignature` (kind, invariant, step sentence, error shape). No product words, nothing that runs a step.
+`tests/explore.test.ts`. Backlog 21, `what-if-branches.ts`:
+`whatIfPlan(feature, only?)` (the Background as the trunk, each scenario or Examples row as a `WhatIfBranch` with its
+row's values and its steps as written; the trunk keeps the feature's `@fixture:<name>`, a branch's isolation and
+fixture tags are dropped; `WhatIfPlanError` (`what-if-plan-error.ts`) with every reason: fewer than two branches, an unknown scenario, Backgrounds
+that differ, a branch naming its own fixture) and `whatIfDifferences` (the results and checks that are not the same in
+every branch, each with every branch's value; `WhatIfOutcome`). `tests/what-if.test.ts`.
+
+## Tools
+
+`src/tools/` (5 October 2026, the lab window's Tools page): `toolCommand(tool, options)`, the CLI command of a tool run
+(`product-lab test --race`, `explore`, `what-if`, `test --mutate`, `load`, `host verify`, `test --suite`, `bisect`),
+its words quoted only when needed (`shellWord`), and `counted(count, one, many?)` ("1 note", "2 notes"). Pure. Tests:
+`tests/tool-command.test.ts`.
+
+## Who may depend on it
+
+Everything in the workspace may (`scope:core`, `layer:core`). It may depend on nothing: the Nx `type:domain`
+constraint allows only `type:domain`, and `tests/independence.test.ts` checks that `package.json` declares no
+dependencies, that sources import only each other, and that no ambient I/O, time or randomness is used. The
+architecture lint rules for `core/*/src` (no Node built-ins, polkadot-api, Playwright; no `process`, timers,
+`Date.now`) apply here too.
+
+It implements no port and uses none; ports (`core/ports`) and adapters use its types.
+
+## Not here yet
+
+The feature `Step`, `Action` and `Assertion` still live in `core/lab`'s definitions (`defineAction`, `defineAssertion`); only their sentences moved here in Phase 4.
+
+`Step`, `Action` and `Assertion` remain flattened into scenarios in `core/lab`, left open past step 7. `HostNetworkRoutes` arrived with
+`LabSession`'s replacement in step 7 part b; `NetworkPolicy`
+moved here from dot.li in Phase 3 and is applied by the truAPI CLI host, the truAPI WASM host and dot.li.
+The domain-model
+record lists each with its file and step.
+
+## Testing
+
+```sh
+bunx nx run domain:test        # node --test, no chain, no browser
+bunx nx run domain:lint
+bunx nx run domain:typecheck
+```
+
+## References
+
+
+Private, workspace-only package. Consumers will install the single umbrella package `@parity/product-lab` once it is
+published.
+
+## Locked setup artifacts
+
+`ReleaseArtifact` (`/versions`) validates a locked release asset and selects its SHA-256/asset name for a target. `Topology.fromLock` names the artifacts an environment uses; concrete path overrides are excluded.
+
+## Suite compatibility
+
+`@product-lab/domain/suites` exports `compareSuiteRuns`, `compatibilityMarkdown`, `compatibilityNotifications`, `reproductionCommand`, `errorSummary`, and the suite-summary, component, comparison and notification types. Pure functions compare recorded combinations and scenario outcomes, identify regressions/recoveries/lost coverage, and group scenarios skipped after an earlier failure. Attribution follows recorded evidence and is not proof of causality: a component observed in the previous run and not observed now (the run stopped before it started) is named as not observed and never blamed. `planSuite` takes `unsupportedVersions` (the lab's `versions.unsupported`): a row asking for a candidate of such a component or kind is unsupported with the lab's reason. It takes `rowSelection` (what each row's run selects: feature files, the configuration's tags, fail-fast) so a row plans what its run runs, and `versionSources` (backlog 27): a row may name a component the lab declares a version source for as a candidate though the policy does not select it. `judgeSuite` takes a row outcome `unsupported` found only once the row resolved (a host release that cannot run), never passing. Test with `bunx nx run domain:test`.
+
+Automatic bisect (backlog 37, `src/suites/bisection.ts`, `src/suites/bisect-plan.ts`): `bisectPlan(change)` turns one `CompatibilityChange` into its axes (each changed app, runtime or host component, the blamed first, with the regression's failing step) or refuses it by name (a recovery, an infrastructure failure, no recorded cause, a change only the combination carries, a binary, an added or removed component). `judgeProbe(runs, expectedStep?)` gives a probe's verdict: every run passed `good`, every run failed at the regression's step `bad`, runs that disagree `flaky`, a run that could not test the scenario `skip`. `Bisection` probes the ends first (when they do not pass and fail, `ends-disagree`, nothing is halved), then the middle of what is open, stepping past untestable values, within `defaultProbeBudget`; its `BisectOutcome` is `found`, `skipped`, `flaky`, `ends-disagree` or `budget`. `bisectSummary(report)` leads with the verdict in plain words, then the probes. `CombinationComponent.commit` records the lab's commit beside its tree. Test: `tests/bisect.test.ts`.
+
+Host bypass evidence is public run data: every finalized ledger entry, direct connection, per-app policy and explicit coverage gap. `HostBypassPolicy` rejects an allowance without a written reason. Since backlog 110 a direct connection may name its `chain` (the chain whose route its endpoint is: the host names it, else the lab from the environment's declared node endpoints).
+
+A direct connection may name its `document` (C7, 6 October 2026): the document the traffic belongs to, a worker's the one that started it, when the browser names its frame. `purpose: "host"` marks an embedding host's own traffic (its page, its workers), told by that document; like the other purposes it is retained and never a finding.
+
+`HostRequestLimits` (backlog 41) is the permission audit's maximum: what an app may ask its host for and how many times (the host's wording, literal and case-insensitive; a request no limit names is a violation; approved and denied both count), and `parse` reads the host's `approved|denied <request>` decision lines.
+
+`mergeHostBypassEvidence` combines report and recording evidence without omitting direct connections, finalized ledger entries, unknown decoding, policy reasons or coverage gaps. Conflicting scopes, policies and observations remain visible as gaps.
+
+`hostBypassVerdict` computes the aggregate run or step verdict, including unexplained foreign extrinsics without app attribution. Coverage gaps and partial decoding remain incomplete; stricter stored verdicts survive merges. `appIncompleteReason` gives an app marked incomplete without a gap of its own the line saying why (the run's gap, the entries not fully decoded, or an unknown scope), and `observedAppGaps` drops that derived line before a recomputation (HostBypassMonitor's evidence and reconcile). The `@product-lab/domain/runs/host-bypass-verdict` subpath exports this pure helper for browser consumers.
+
+App proxy announcements (item82): `apps` exports pure Vite message interpretation, canonical announcement input and a bounded recent decision window. Fingerprints preserve protocol revisions and do not include recipient history; the Node adapter computes SHA256. No socket, clock or I/O lives here.
+
+
+Framing inspection (item82): `FramingDocument`, `AppFramingInspectionRequest`, `AppFramingInspection` and `inspectFramingDocument` provide a pure serializable allowed/refused/unknown decision over observed headers. The existing CSP precedence, final document origin, ancestor matching and refusal sentences stay in this domain helper. Missing evidence cannot produce allowed. No fetching or adapter imports enter the domain.
+
+## Declared Next App Router updates (1 October 2026)
+
+`apps/next-webpack-announcement.ts` reads the qualified Next16.3.1 webpack text messages as pure announcements. The explicit declaration is `next-webpack-app-router`; shared socket frames do not establish whether an app uses App Router or Pages Router. The first App Router sync initializes socket state, changed later syncs reload, successful builds and router changes update, and diagnostics pass. Turbopack messages refuse this declared profile. Tests: `bunx nx run domain:test`.
+
+## More dev servers (1 October 2026)
+
+`apps/next-turbopack-announcement.ts` reads stock Next 16.3.1 Turbopack messages (chunk-list updates in place,
+`restart`/`reloadPage`/another session id/a changed sync reload; `built` applies nothing; webpack's messages before
+`turbopack-connected` are refused). `apps/webpack-dev-server-announcement.ts` reads webpack-dev-server 6.0.0 and
+Rspack dev server 2.2.1 messages as their shared page client applies them (`hash` then `ok`/`warnings`; the first hash
+is the page's build). `AppDevServer.parse` accepts `"next-turbopack"`, `"webpack-dev-server"` and `{ hold: "<path>" }`;
+`appDevServerProtocol` names the protocol the lab follows (`"hold"` for a hold). Tests: `bunx nx run domain:test`.
+
+`apps/dev-server-socket.ts` (pure): which CLI a declared command runs (`webpackFamily`), the config file its
+arguments name (`configArgument`) or the CLI would find (`DEFAULT_CONFIG_FILES`), the arguments that add the dev
+servers' own proxy setting (`proxySocketArgs`), the content of the lab's files (`webpackSocketOverlay`,
+`rspackSocketWrapper`) and the notice when the lab cannot tell (`proxySocketNotice`). Tests: `tests/dev-server-socket.test.ts`.

package/core/domain/src/accounts/account-address.d.ts

@@ -0,0 +1,48 @@
+/**
+ * How a chain relates a 32-byte account to a 20-byte address. One mapping is supported:
+ *
+ * `revive`: pallet-revive's `AccountId32Mapper` (Asset Hub and every chain using pallet-revive). A 32-byte account
+ * whose last 12 bytes are `0xEE` is a 20-byte address padded, and maps back to its first 20 bytes; any other account
+ * maps to the last 20 bytes of its Keccak-256. The mapping is a function of the account alone, so the comparison
+ * needs no chain read.
+ *
+ * Not supported (compare the 20-byte forms yourself, from the chain's own state): Frontier's hashed mapping
+ * (`blake2_256("evm:" ++ address)`), truncation, and chains whose native account is 20 bytes.
+ */
+export type H160Mapping = "revive";
+export interface AccountComparison {
+    /** The chain's mapping between 32-byte accounts and 20-byte addresses; without it such a pair is refused. */
+    readonly h160?: H160Mapping;
+}
+export declare class AccountAddress {
+    /** The text it was read from, trimmed. */
+    readonly text: string;
+    /** `account`: a 32-byte account (SS58 or public key); `h160`: a 20-byte address. */
+    readonly kind: "account" | "h160";
+    private readonly bytes;
+    /** The SS58 network prefix it was written with; undefined for hex. */
+    readonly prefix: number | undefined;
+    private constructor();
+    /** Read an address; throws `AccountFormatError` naming why the text is not one. */
+    static parse(value: unknown): AccountAddress;
+    /** `parse`, or undefined when the text is not an address. */
+    static tryParse(value: unknown): AccountAddress | undefined;
+    /** A 32-byte account from its bytes (a public key as chains and hosts give it). */
+    static fromPublicKey(publicKey: Uint8Array): AccountAddress;
+    /** The 32-byte public key as lower-case 0x hex; throws for a 20-byte address (no public key can be recovered from it). */
+    get publicKey(): string;
+    /** Lower-case 0x hex of what it is: 32 bytes for an account, 20 for an address. */
+    get hex(): string;
+    /** The account in SS58 with `prefix` (default 42, the generic Substrate prefix). Only a 32-byte account has one. */
+    ss58(prefix?: number): string;
+    /** The 20-byte address under `mapping` (itself for a 20-byte address), lower-case 0x hex. */
+    h160(mapping: H160Mapping): string;
+    /**
+     * Whether both are the same account. Two 32-byte accounts: the same public key, whatever the SS58 prefix or hex.
+     * Two 20-byte addresses: the same bytes. One of each: only with the chain's mapping (`comparison.h160`); without
+     * it the comparison throws `AmbiguousAccountError`.
+     */
+    same(other: AccountAddress, comparison?: AccountComparison): boolean;
+    toString(): string;
+    toJSON(): string;
+}

package/core/domain/src/accounts/account-address.js

@@ -0,0 +1,153 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { AccountFormatError } from "./account-format-error.js";
+import { AmbiguousAccountError } from "./ambiguous-account-error.js";
+import { blake2b, keccak256 } from "./hashes.js";
+const ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+const SS58_CONTEXT = [0x53, 0x53, 0x35, 0x38, 0x50, 0x52, 0x45];
+const FORMS = "an SS58 address, a 0x-prefixed 32-byte public key or a 0x-prefixed 20-byte address";
+const toHex = (bytes) => `0x${Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+const fromHex = (hex) => Uint8Array.from(hex.slice(2).match(/../g) ?? [], (pair) => parseInt(pair, 16));
+const equal = (a, b) => a.length === b.length && a.every((byte, index) => byte === b[index]);
+function base58Decode(text) {
+    let value = 0n;
+    for (const character of text) {
+        const digit = ALPHABET.indexOf(character);
+        if (digit < 0)
+            return undefined;
+        value = value * 58n + BigInt(digit);
+    }
+    const bytes = [];
+    for (; value > 0n; value >>= 8n)
+        bytes.unshift(Number(value & 0xffn));
+    for (const character of text) {
+        if (character !== "1")
+            break;
+        bytes.unshift(0);
+    }
+    return Uint8Array.from(bytes);
+}
+function base58Encode(bytes) {
+    let value = 0n;
+    for (const byte of bytes)
+        value = (value << 8n) | BigInt(byte);
+    let text = "";
+    for (; value > 0n; value /= 58n)
+        text = ALPHABET[Number(value % 58n)] + text;
+    for (const byte of bytes) {
+        if (byte !== 0)
+            break;
+        text = `1${text}`;
+    }
+    return text;
+}
+function prefixBytes(prefix) {
+    if (!Number.isInteger(prefix) || prefix < 0 || prefix > 16383)
+        throw new Error(`An SS58 network prefix is 0 to 16383, not ${String(prefix)}`);
+    if (prefix < 64)
+        return [prefix];
+    return [((prefix & 0b1111_1100) >> 2) | 0b0100_0000, (prefix >> 8) | ((prefix & 0b11) << 6)];
+}
+function checksum(payload) {
+    return blake2b(Uint8Array.from([...SS58_CONTEXT, ...payload]), 64).slice(0, 2);
+}
+function reviveAddress(account) {
+    if (account.slice(20).every((byte) => byte === 0xee))
+        return account.slice(0, 20);
+    return keccak256(account).slice(12);
+}
+export class AccountAddress {
+    text;
+    kind;
+    bytes;
+    prefix;
+    constructor(
+    text, 
+    kind, bytes, 
+    prefix) {
+        this.text = text;
+        this.kind = kind;
+        this.bytes = bytes;
+        this.prefix = prefix;
+        Object.freeze(this);
+    }
+    static parse(value) {
+        if (typeof value !== "string")
+            throw new AccountFormatError(String(value), `an account is text: ${FORMS}`);
+        const text = value.trim();
+        if (!text)
+            throw new AccountFormatError(value, "it is empty");
+        if (/…|\.\.\./.test(text))
+            throw new AccountFormatError(text, "it is shortened, and a shortened address matches many accounts; compare the full address (an app may keep it in an attribute or a title)");
+        if (/^0x/i.test(text)) {
+            if (/^0x[0-9a-f]{64}$/i.test(text))
+                return new AccountAddress(text, "account", fromHex(text.toLowerCase()), undefined);
+            if (/^0x[0-9a-f]{40}$/i.test(text))
+                return new AccountAddress(text, "h160", fromHex(text.toLowerCase()), undefined);
+            throw new AccountFormatError(text, `hex must be 32 bytes (a public key) or 20 bytes (an address); expected ${FORMS}`);
+        }
+        const decoded = base58Decode(text);
+        if (!decoded)
+            throw new AccountFormatError(text, `expected ${FORMS}`);
+        const first = decoded[0];
+        if (first === undefined || first > 127)
+            throw new AccountFormatError(text, "its SS58 network prefix is not valid");
+        const prefixLength = first < 64 ? 1 : 2;
+        if (decoded.length !== prefixLength + 32 + 2)
+            throw new AccountFormatError(text, `it is SS58 of ${Math.max(0, decoded.length - prefixLength - 2)} bytes, not of a 32-byte account`);
+        const payload = decoded.slice(0, prefixLength + 32);
+        if (!equal(checksum(payload), decoded.slice(prefixLength + 32)))
+            throw new AccountFormatError(text, "its SS58 checksum is wrong (a mistyped or cut address)");
+        const prefix = prefixLength === 1 ? first : ((first & 0b0011_1111) << 2) | (decoded[1] >> 6) | ((decoded[1] & 0b0011_1111) << 8);
+        return new AccountAddress(text, "account", payload.slice(prefixLength), prefix);
+    }
+    static tryParse(value) {
+        try {
+            return AccountAddress.parse(value);
+        }
+        catch (error) {
+            if (error instanceof AccountFormatError)
+                return undefined;
+            throw error;
+        }
+    }
+    static fromPublicKey(publicKey) {
+        if (!(publicKey instanceof Uint8Array) || publicKey.length !== 32)
+            throw new Error("An account public key is 32 bytes");
+        return new AccountAddress(toHex(publicKey), "account", Uint8Array.from(publicKey), undefined);
+    }
+    get publicKey() {
+        if (this.kind !== "account")
+            throw new Error(`${this.text} is a 20-byte address; its 32-byte account cannot be derived from it`);
+        return toHex(this.bytes);
+    }
+    get hex() {
+        return toHex(this.bytes);
+    }
+    ss58(prefix = 42) {
+        if (this.kind !== "account")
+            throw new Error(`${this.text} is a 20-byte address; it has no SS58 form`);
+        const payload = Uint8Array.from([...prefixBytes(prefix), ...this.bytes]);
+        return base58Encode(Uint8Array.from([...payload, ...checksum(payload)]));
+    }
+    h160(mapping) {
+        if (this.kind === "h160")
+            return toHex(this.bytes);
+        if (mapping !== "revive")
+            throw new Error(`Unknown address mapping ${String(mapping)} (supported: revive)`);
+        return toHex(reviveAddress(this.bytes));
+    }
+    same(other, comparison = {}) {
+        if (this.kind === other.kind)
+            return equal(this.bytes, other.bytes);
+        if (!comparison.h160)
+            throw new AmbiguousAccountError(this.text, other.text);
+        return this.h160(comparison.h160) === other.h160(comparison.h160);
+    }
+    toString() {
+        return this.text;
+    }
+    toJSON() {
+        return this.text;
+    }
+}

package/core/domain/src/accounts/account-format-error.d.ts

@@ -0,0 +1,12 @@
+/** A text that is not an account address the lab can compare; says which forms are. */
+export declare class AccountFormatError extends Error {
+    /** The text as given (an address is public; nothing secret is echoed). */
+    readonly value: string;
+    /** Why it is not an address. */
+    readonly problem: string;
+    constructor(
+    /** The text as given (an address is public; nothing secret is echoed). */
+    value: string, 
+    /** Why it is not an address. */
+    problem: string);
+}

package/core/domain/src/accounts/account-format-error.js

@@ -0,0 +1,14 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export class AccountFormatError extends Error {
+    value;
+    problem;
+    constructor(
+    value, 
+    problem) {
+        super(`${JSON.stringify(value.length > 80 ? `${value.slice(0, 79)}…` : value)} is not an account the lab can compare: ${problem}`);
+        this.value = value;
+        this.problem = problem;
+        this.name = "AccountFormatError";
+    }
+}

package/core/domain/src/accounts/account-functions.d.ts

@@ -0,0 +1,15 @@
+import { type AccountComparison } from "./account-address.js";
+import { ExpectedAccount } from "./expected-account.js";
+/**
+ * Whether two addresses are the same account: the same 32-byte public key in any SS58 prefix or as hex, or the same
+ * 20-byte address. A 20-byte address against a 32-byte account is compared only with the chain's mapping
+ * (`{ h160: "revive" }`) and otherwise refused (`AmbiguousAccountError`). A text that is not an address throws
+ * `AccountFormatError`: a comparison never passes or fails on a value it could not read.
+ */
+export declare function sameAccount(left: string, right: string, comparison?: AccountComparison): boolean;
+/** Mark a value a check expects as an account, so it is matched in any form (`ExpectedAccount`). */
+export declare function expectedAccount(account: string, comparison?: AccountComparison): ExpectedAccount;
+/** The account's 32-byte public key as lower-case 0x hex: one spelling per account, for keys and lookups. */
+export declare function accountPublicKey(account: string): string;
+/** The account in SS58 with `prefix` (default 42). */
+export declare function accountSs58(account: string, prefix?: number): string;

package/core/domain/src/accounts/account-functions.js

@@ -0,0 +1,16 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { AccountAddress } from "./account-address.js";
+import { ExpectedAccount } from "./expected-account.js";
+export function sameAccount(left, right, comparison = {}) {
+    return AccountAddress.parse(left).same(AccountAddress.parse(right), comparison);
+}
+export function expectedAccount(account, comparison = {}) {
+    return new ExpectedAccount(account, comparison);
+}
+export function accountPublicKey(account) {
+    return AccountAddress.parse(account).publicKey;
+}
+export function accountSs58(account, prefix = 42) {
+    return AccountAddress.parse(account).ss58(prefix);
+}

package/core/domain/src/accounts/ambiguous-account-error.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Two addresses of different kinds (a 20-byte address and a 32-byte account) that only a chain's own mapping can
+ * relate, asked to be compared without naming that mapping. The lab refuses instead of guessing.
+ */
+export declare class AmbiguousAccountError extends Error {
+    readonly left: string;
+    readonly right: string;
+    constructor(left: string, right: string);
+}

package/core/domain/src/accounts/ambiguous-account-error.js

@@ -0,0 +1,13 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export class AmbiguousAccountError extends Error {
+    left;
+    right;
+    constructor(left, right) {
+        super(`Cannot tell whether ${left} and ${right} are the same account: one is a 20-byte address and the other a 32-byte account, and chains map one to the other differently. ` +
+            `Name the chain's mapping (h160: "revive" for pallet-revive chains such as Asset Hub), or compare two addresses of the same kind.`);
+        this.left = left;
+        this.right = right;
+        this.name = "AmbiguousAccountError";
+    }
+}

package/core/domain/src/accounts/expected-account.d.ts

@@ -0,0 +1,19 @@
+import { AccountAddress, type AccountComparison } from "./account-address.js";
+/**
+ * An account a check expects to find in a value read from a chain or an app (an event field, a storage value, an
+ * attribute): matched as an account, in whatever form the value is written. A comparison names a field as an account
+ * with this; a field that is not marked so keeps its exact comparison.
+ */
+export declare class ExpectedAccount {
+    readonly account: AccountAddress;
+    readonly comparison: AccountComparison;
+    constructor(account: string | AccountAddress, comparison?: AccountComparison);
+    /**
+     * Whether `value` is this account: an address as text, raw bytes (32 or 20), or an object exposing `asHex()`.
+     * A value that is no address at all does not match; a 20-byte value against a 32-byte account (or the reverse)
+     * without a declared mapping throws `AmbiguousAccountError`.
+     */
+    matches(value: unknown): boolean;
+    toString(): string;
+    toJSON(): string;
+}