Make Fleet vocabulary parity coverage mechanically complete

Related: #16743 Related: #16747 Related: #16793

Context

PR #16793 established the versioned Fleet client wire contract and was approved at exact head 42fc7a769e. Ada's approval review PRR_kwDODSospM8AAAABI5IFrw demonstrated one future-change hole without finding a defect in the current paired vocabulary: the comparator can execute every registered data/helper pair deeply while remaining blind to a newly exported member that nobody registered.

I independently reproduced the same property without editing the worktree. Adding divergent FLEET_WIRE_PARITY_PROBE properties to in-memory authority/twin wire namespaces and passing them to compareFleetVocabulary() returned []. The live baseline still reports OK, so this is a completeness defect in the guard, not a present divergence in the contract.

Live latest-open sweep: checked the newest 20 open issues and the latest 30 all-state A2A messages at 2026-08-09T15:47:10.732Z; no equivalent ticket or in-flight claim exists. The exact all-state GitHub search returned only unrelated #16787 and #14333; the local issue/discussion sweep found no equivalent.

Memory/KB prior-art retrieval was attempted and was unavailable because both consumers reported EMBEDDING_PROBE_TIMEOUT; the exact-head review, live source, export census, structure map, and executable mutation are the bounded evidence for this ticket.

The Problem

ai/scripts/lint/lint-fleet-vocabulary-parity.mjs hardcodes dataPairs and helperCases (lines 70-176). Those tables verify registered members well, but no mechanism compares their member names with the live ESM namespace exports. A future authority/twin export can therefore diverge while the lint exits zero.

The module header currently says every constant and shared helper is covered and that silent drift cannot exist (lines 6-10). That describes the intended contract, not the implemented coverage mechanism.

The Architectural Reality

Fleet intentionally publishes a dependency-free Brain authority and an operable-cold app twin:

• ai/services/fleet/{mcpServers,harnessTypes,fleetWireMethods,fleetCockpitStatus}.mjs
• apps/agentos/config/{mcpServers,harnessTypes,fleetWireMethods,cockpitSources}.mjs

The realms must not share runtime imports. The lint in ai/scripts/lint/ is the mechanical binding and is consumed by lint-staged, CI, and test/playwright/unit/apps/agentos/config/fleetVocabularyParity.spec.mjs.

Blind Object.keys(authority) === Object.keys(twin) equality is also wrong: the Brain legitimately owns realm-only exports such as credentials/environment handling and cockpit constructors. The missing primitive is an exhaustive disposition census, not naive namespace equality.

Owning-folder structure receipt: npm run --silent ai:structure-map -- --root ai/scripts/lint --files --loc identifies the existing 17-file lint folder and lint-fleet-vocabulary-parity.mjs as the 158-LOC owning sibling. The repository-wide structure-map invocation currently exceeds the Node string limit; the owning-folder run is the usable bounded map.

The Fix

Extend compareFleetVocabulary() with an explicit, mechanically checked export-disposition roster for each authority/twin namespace pair.

Every live export name must be classified as exactly one of:

1. deep-equaled data pair;
2. behavior-compared helper pair;
3. documented authority-only export;
4. documented twin-only export, if any.

Compare the roster with the live namespace keys and fail closed with the namespace and unclassified export name. Preserve the existing deep-equality and drift-sensitive helper fixtures. Correct the module JSDoc so its exhaustive claim is backed by the new census.

Do not move vocabulary into a shared runtime module; zero-import realm isolation remains the contract.

Contract Ledger

Decision Record impact

none — this mechanizes completeness for the already-selected Fleet publication boundary and does not amend the decision-record work tracked by #16747.

Acceptance Criteria

• compareFleetVocabulary() mechanically censuses every export in all four authority/twin namespace pairs.
• Every current asymmetric export is explicitly dispositioned with a reason; adding an unclassified export on either realm fails with its namespace and name.
• Registered constants retain deep-equality comparison and registered helpers retain behavior comparison over the existing fixture matrix.
• Negative witnesses prove that an unregistered authority-only export, twin-only export, and divergent paired export each redden the comparator.
• The module header no longer overclaims coverage; its exhaustive statement matches the implemented census.
• The app twins remain operable-cold and import nothing from ai/services/fleet/.
• npm run --silent ai:lint-fleet-vocabulary-parity passes on the valid roster.
• The focused parity unit spec passes using Neo's unit-test workflow.
• git diff --check origin/dev...HEAD passes.

Out of Scope

• Changing the Fleet wire protocol, capabilities, states, methods, or runtime behavior.
• Moving the authority and twin into one shared runtime module.
• Repairing the seven headed Fleet journeys or packaged Electron validation.
• Modifying PR #16793's already-approved exact head.

Avoided Traps

• Blind namespace equality: rejects legitimate Brain-only exports and erases the trust-boundary rationale.
• Regex/source census: tests spelling rather than the actual ESM export surface.
• More helper fixtures without coverage accounting: deepens registered comparisons but leaves unregistered members invisible.
• Amending the approved PR: would invalidate an exact-head approval for a non-blocking, future-change guard.

Related

• #16743 — source contract ticket.
• #16747 — decision-record carriage for the Fleet boundary.
• #16793 — approved implementation whose reviewer mutation exposed this successor.

Origin Session ID: 64844d03-6d7e-429c-acd7-428cce239367

Retrieval Hint: query "Fleet vocabulary parity completeness"; inspect PR review PRR_kwDODSospM8AAAABI5IFrw; reproduce by passing authority/twin namespace clones with an extra divergent export to compareFleetVocabulary().