LearnNewsExamplesServices
Frontmatter
id16189
titleRemove the one-shot Fleet MCP target migration
stateClosed
labels
enhancementairefactoringtestingarchitecture
assigneesneo-gpt-emmy
createdAtJul 30, 2026, 10:17 PM
updatedAtJul 31, 2026, 1:25 AM
githubUrlhttps://github.com/neomjs/neo/issues/16189
authorneo-gpt-emmy
commentsCount0
parentIssuenull
subIssues[]
subIssuesCompleted0
subIssuesTotal0
contentTrust
projected
quarantined0
signals[]
blockedBy[x] 16184 Separate Fleet MCP target selection from wire transport
blocking[]
closedAtJul 31, 2026, 1:25 AM

Remove the one-shot Fleet MCP target migration

Closed Backlog/active-chunk-11 enhancementairefactoringtestingarchitecture
neo-gpt-emmy
neo-gpt-emmy commented on Jul 30, 2026, 10:17 PM

Context

Issue #16184 and PR #16190 hard-cut Fleet's public target selection to canonical mcpTarget intent. The first landing included a deliberately temporary read-path translator in FleetRegistryService.mjs for a hypothetical persisted mcpTransport row.

The runtime census after merge changes the cleanup authority:

  • A bounded sweep across the known Neo clones and local harness-instance roots found exactly one Fleet registry.json.
  • That file is exactly 18 bytes and parses completely as {"agents":{}}.
  • No persisted Fleet agent row—legacy or canonical—exists on this installation.

The migration therefore never traversed a row. Deletion is safe immediately by proven absence, not by claiming that a rewrite occurred.

The Problem

The current ticket originally required a “successful rewrite” receipt. Against an empty registry, that receipt is trivially satisfiable and cannot distinguish:

  1. a legacy row that traversed the migration and was rewritten, from
  2. no row existing to traverse.

Claiming the first would be false. Keeping the migration after proving the second would turn a one-installation precaution into permanent compatibility debt, while the positive unit fixture would continue manufacturing a historical state that never existed at runtime.

The Architectural Reality

  • FleetRegistryService.readRegistry() owns persisted agent hydration.
  • The marked migrateLegacyMcpTransport() / migrateStoredAgentDefinition() block is read-path compatibility only.
  • Public defineAgent() and the Body↔Brain control path independently reject retired target-as-transport input; removing stored-row translation must not weaken those guards.
  • FleetRegistryService.spec.mjs owns both the synthetic hydration fixture and the mechanical retired-vocabulary sweep.
  • This is a source deletion for one empirically empty installation, not a generic schema-version or multi-installation migration product.

The Fix

  1. Record the negative runtime receipt: the sole Fleet registry exists but contains zero agent rows, so no legacy row can be stranded.
  2. Delete the marked legacy target migration helpers and make readRegistry() hydrate the persisted definitions directly.
  3. Delete the positive legacy hydration fixture.
  4. Remove the production migration-region exception from the retired-vocabulary guard.
  5. Preserve direct-registry and real Body↔Brain rejection of retired target-as-transport input.
  6. Run the focused Fleet Registry / Control Bridge tests and vocabulary sweep.

Contract Ledger

Target Surface Source of Authority Proposed Behavior Fallback Docs Evidence
Runtime Fleet registry set Bounded installation census Zero persisted agent rows; no migration traversal or rewrite is claimed Any newly discovered legacy row reopens the premise before deletion This ticket's receipt Exactly one 18-byte registry whose complete parsed shape is {"agents":{}}
FleetRegistryService.readRegistry() Canonical persisted definition shape from #16184 Hydrate current definitions directly; no retired-row translator or rewrite branch Existing missing/corrupt-file behavior remains unchanged Existing source JSDoc Focused registry hydration tests
Public define/configure boundary Registry + Control Bridge Retired target-as-transport input remains rejected Controlled domain rejection; no silent resident degradation #16184 Direct registry + real-wire tests
Retired-vocabulary guard Fleet Registry unit spec No production migration exception remains Any retired target vocabulary in the owned Fleet surface fails the suite N/A Negative source/test sweep

Acceptance Criteria

  • The ticket records that the sole installation's registry contains zero agent rows and the migration path was never exercised.
  • The marked persisted-row migration helpers and rewrite branch are deleted from FleetRegistryService.mjs.
  • readRegistry() retains its existing missing/corrupt-file behavior while hydrating canonical definitions directly.
  • The positive legacy hydration fixture is deleted.
  • The vocabulary guard no longer strips a production migration region, and no retired target-as-transport token remains in the owned production Fleet surface.
  • Direct registry input and the real Body↔Brain define path still reject retired target-as-transport input instead of degrading it to resident.
  • Focused Fleet Registry / Control Bridge tests and the vocabulary sweep pass after deletion.
  • No generic schema-version framework, dual-read alias, migration script, or compatibility timer is introduced.

Out of Scope

  • Supporting hypothetical external installations with persisted pre-cut rows; the verified runtime authority contains none.
  • Reworking the mcpTarget shape, resolved plan, harness adapters, or AgentOS UI delivered by #16184.
  • Changing tenant credentials, MCP authentication, or server protocols.
  • Creating migration infrastructure for a state that did not exist.

Avoided Traps

  • Claiming a rewrite receipt from an empty registry: identical output would falsely imply traversal.
  • Keeping the migration “just in case”: converts a bounded cutover into permanent compatibility debt.
  • Retaining a synthetic historical fixture as runtime authority: tests should protect live contracts, not fictional installation history.
  • Building migration infrastructure: negative ROI for one verified-empty installation.
  • Weakening wire rejection: rejecting retired input prevents silent semantic drift; accepting and translating it would recreate compatibility.

Decision Record impact

None. This completes the deletion boundary already prescribed by #16184 and remains aligned with the canonical stdio / streamable-http vocabulary established by #15188 and PR #15191.

Related

Successor to #16184

Related: #16190, #15188, #15191

Origin Session ID: b1ebc46a-5a83-496c-aa8b-385af785e9cb

Retrieval Hint: Fleet empty registry no migration traversal delete mcpTransport read path

tobiu referenced in commit becde3c - "fix(fleet): remove unexercised target migration (#16189) (#16198)" on Jul 31, 2026, 1:25 AM
tobiu closed this issue on Jul 31, 2026, 1:25 AM