---
id: 12418
title: Ticket B — Boot bootstrap-envelope → wake overrideMetadata
state: CLOSED
labels:
  - ai
  - architecture
assignees:
  - neo-opus-ada
createdAt: '2026-06-03T03:49:30Z'
updatedAt: '2026-06-03T13:29:23Z'
githubUrl: 'https://github.com/neomjs/neo/issues/12418'
author: neo-opus-ada
commentsCount: 0
parentIssue: 12416
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking:
  - '[ ] 12422 Ticket B2 — volatile HarnessPresence registry (state∪address) + addressType dispatch + staleness'
closedAt: '2026-06-03T13:29:23Z'
---
# Ticket B — Boot bootstrap-envelope → wake overrideMetadata

Part of Epic #12416 (graduated from Discussion #12412). The runtime self-registration core's boot-envelope mechanism.

> **Scope note (re-scoped during implementation):** Originally bundled the boot envelope **and** the volatile HarnessPresence registry. The registry half (HarnessPresence record, `addressType` dispatch, staleness/TTL) was carved into **#12422** because it gates on PR #12411 (state vocab) and is a separable concern. This ticket now covers the boot-envelope → `overrideMetadata` mechanism only — delivered by **PR #12421**. The graduated design (#12412) is unchanged; only the implementation tracking was split for clean PR↔ticket mapping.

## Scope
- **Typed boot bootstrap-envelope** (env): `{instanceAddress, addressType ∈ userDataDir|pid|tmuxSession|webhookUrl}` + `appName`/adapter. Transport ⟂ instance-address kept separate. `NEO_AI_DATA_ROOT` resolution is #12417's surface (out of scope here).
- memory-core **boot derives wake-route `overrideMetadata`** from the envelope (the existing `WakeSubscriptionService.bootstrap()` `overrideMetadata` parameter is the seam). The durable `subscriptionTemplate` in `identityRoots` stays **machine-agnostic** (NO operator path — per the #11822 `[hold-before-PR]` catch).
- **Fail-closed** on a misconfigured envelope (partial config, unknown type, recognized-but-not-yet-dispatchable type) — a non-default instance must never silently fall back to the default route and misroute its wakes. The default instance (no envelope) is routed by the *absence* of an address (#12407).

## Acceptance Criteria
- [ ] AC1: boot derives `overrideMetadata` from the env-envelope; no operator path enters shared `identityRoots`.
- [ ] AC2: default instance (no envelope) → no override → routed by absence; misconfigured envelope → fail-closed (no subscription).
- [ ] AC3: `userDataDir` dispatchable today via the existing daemon; reserved types (`pid`/`tmuxSession`/`webhookUrl`) fail closed until their dispatch lands in #12422.
- [ ] AC4: unit coverage of the full `resolveOverrideMetadata` matrix; live 2-instance proof folds with #12402.

## Contract Ledger
| Surface | Source of Authority | Behavior | Fallback | Evidence |
|---|---|---|---|---|
| `NEO_HARNESS_INSTANCE_ADDRESS` + `_TYPE` (boot env) | Epic #12416 / Discussion #12412 address-dim | typed envelope → `overrideMetadata` | both omitted = default instance (route by absence) | unit |
| `BootEnvelopeResolver.resolveOverrideMetadata` | this ticket | pure env → override map; fail-closed on degenerate shapes | throw → boot IIFE logs + skips (no subscription) | unit |
| memory-core boot wiring | `WakeSubscriptionService.bootstrap({overrideMetadata})` seam | inject per-instance address at boot | `bootstrap()` with no override (default) | static + unit; live → #12402 |

## Carved out (now #12422)
The volatile HarnessPresence registry (state∪address union), `bootId`+pid-dead staleness/TTL, generic `addressType` delivery dispatch, and `immediate`-requires-fresh-presence — all gating on PR #12411's state vocab.

## Related
Epic #12416; Discussion #12412; **PR #12421** (delivers this); **#12422** (carved-out HarnessPresence registry); #12402 (L3 validation); #11822/#12399/#12407 (wake-routing precedents); #12417 (NEO_AI_DATA_ROOT boundary).

## Timeline

- 2026-06-03T03:49:32Z @neo-opus-ada added the `ai` label
- 2026-06-03T03:49:32Z @neo-opus-ada added the `architecture` label
- 2026-06-03T03:50:29Z @neo-opus-ada added parent issue #12416
- 2026-06-03T04:03:01Z @neo-gpt cross-referenced by #12416
- 2026-06-03T04:21:25Z @neo-opus-ada assigned to @neo-opus-ada
- 2026-06-03T04:31:05Z @neo-opus-ada cross-referenced by PR #12421
- 2026-06-03T04:42:51Z @neo-opus-ada cross-referenced by #12422
- 2026-06-03T04:43:51Z @neo-opus-ada changed title from **Ticket B — Boot bootstrap-envelope → wake overrideMetadata + volatile HarnessPresence registry** to **Ticket B — Boot bootstrap-envelope → wake overrideMetadata**
- 2026-06-03T10:41:41Z @neo-opus-ada cross-referenced by #12434
- 2026-06-03T11:36:31Z @neo-gpt marked this issue as blocking #12422
- 2026-06-03T13:29:24Z @tobiu closed this issue

