id: friendly-name reference resolution v2 — cross-store fan-out and locator fetch (follow-on to #2259)

Follow-on to #2259 (design + local-store PoC, completed 2026-11-03)

The local half of friendly-name reference resolution is done and merged: spec (doc/2026-10-30T13-25-00Z_design_friendly_name_references.md, PR #2742; design record PR #3829) and the local-store PoC (pkgs/id/src/references.rs, PR #2756, merge 4b6d1f93). Findings are posted on #2259.

This issue is the v2 half that #2259 explicitly left out of scope:

Scope

Cross-store fan-out: resolution queries across stores (not just the local notes/documents index), merging per-store ranked candidates under the spec's tier rules — boosts never cross tiers, contested surfaces are never silently picked.
Locator fetch: following a stored reference's locator hints to fetch/render a target that lives in another store, including the renamed/cleared/unresolved-for-viewer render states across the store boundary.
Hosted-store search: the hosted counterpart of the local index (was out of scope for the PoC).

Carried decision (Drew)

From the 2026-11-01 design note on #2259 — Q1, document identity: choose (a) DocumentRecord.id revision-level references (recommended for the PoC) or (b) a stable logical note ID that follows later saves. The PoC landed without this ruling; v2's reference representation depends on it, so this issue stays design-first until Q1 is answered.

Acceptance criteria

Q1 answered and recorded here
Design for fan-out ordering/provenance across stores (how per-store tiers merge without silent picks)
PoC or implementation per the design, with duplicate-title and contested-alias cases covered across stores

Program: ID platform expansion, epic #2056. Origin: #2047 investigation → #2259 local design+PoC → this v2.

Intake review

Related: Origin: #2259 (closed/completed). Spec: doc/2026-10-30T13-25-00Z_design_friendly_name_references.md.

Notes: Follow-on to #2259 (design + local-store PoC, completed 2026-11-03; PR #2742/#3829/#2756). Body already carries acceptance criteria and the carried Q1 decision, so no body edit this pass. Scope is the v2 half: cross-store fan-out, locator fetch, hosted-store search. Risks: tier-rule violations across store boundaries (boosts crossing tiers) are the spec's hard constraint — acceptance tests should include a contested-surface case. Effort l (multi-day, three sub-scopes; may split). Suggested approach: slice per scope item, fan-out first since locator fetch depends on its result shape.

— fleet monitor intake (protocol §5), 2026-11-03. Verified still live this run: no merged PR resolves this issue.

🤖 Agent note · handed off

Agent: queue worker (repo-worker-code), lane code-h
Session / ID: task 9464
Found via: queue claim
Task: Handed off to the opencode execution lane per §1b — the laptop claimant launches the bound opencode session for task 9464 (issue id: friendly-name reference resolution v2 — cross-store fan-out and locator fetch (follow-on to #2259) #5178).
Expectation: claimant session drives task 9464 to its terminal state under this queue's worker id
Links: n/a

🤖 Agent note · picked up

Agent: queue worker (repo-worker-code), lane code-a
Session / ID: task 9464
Found via: queue claim
Task: triage for id: friendly-name reference resolution v2 — cross-store fan-out and locator fetch (follow-on to #2259) #5178 — claimed by lane code-a; execution-lane assignment: opencode
Expectation: handed to the opencode claimant, which launches the bound session
Links: queue task 9464

🤖 Agent note · handed off

Agent: queue worker (repo-worker-code), lane code-h
Session / ID: task 9464
Found via: queue claim
Task: triage of issue id: friendly-name reference resolution v2 — cross-store fan-out and locator fetch (follow-on to #2259) #5178 (id: friendly-name reference resolution v2 — cross-store fan-out and locator fetch) — claimed by lane code-h and assigned to the opencode execution lane
Expectation: the opencode-claimant launches a bound opencode session for task 9464, which drives the triage to its terminal state
Links: issue id: friendly-name reference resolution v2 — cross-store fan-out and locator fetch (follow-on to #2259) #5178

🤖 Agent note · handed off

Agent: queue worker (repo-worker-code), lane code-n
Session / ID: task 9464
Found via: queue claim
Task: task 9464 (triage for issue id: friendly-name reference resolution v2 — cross-store fan-out and locator fetch (follow-on to #2259) #5178) assigned to the opencode execution lane; handed off to the laptop opencode-claimant, which launches a bound session to drive task 9464 to a terminal state.
Expectation: done = issue id: friendly-name reference resolution v2 — cross-store fan-out and locator fetch (follow-on to #2259) #5178 resolved or dispositioned per its packet acceptance criteria.
Links: issue id: friendly-name reference resolution v2 — cross-store fan-out and locator fetch (follow-on to #2259) #5178

agent-note:v1
state: picked-up
task: 9464 — triage #5178
agent: repo-worker-code, OpenChamber scheduled lane 335a5d1f-bfc1-4831-99ea-850c8939a727
found via: atomic queue claim
revalidating: issue #5178 remains open; checking the prior triage disposition and merged PR #5553 against current issue/PR state before closing this task or routing remaining scope.

agent-note:v1
state: triaged
task: 9464 — triage #5178
agent: repo-worker-code, OpenChamber scheduled lane 335a5d1f-bfc1-4831-99ea-850c8939a727
found via: atomic queue claim

Disposition: keep #5178 OPEN. Q1 is answered: references target stable logical note IDs with an optional exact-revision pin; current main 83f78ed2347ec039a1a029f4a29e88c45382a70e contains Reference.pinned_revision and the merged FanOut implementation. PR #5553 is MERGED, and its design record explicitly says locator fetch/render and hosted-store search remain later slices; no open PR currently references #5178. The prior follow-up task 9579 delivered the fan-out slice.

Next steps: locator-hint fetch/render across stores first, preserving viewer-specific access filtering and explicit renamed/cleared/unresolved states; hosted-store search second as a separately scoped adapter. No Drew decision blocker remains. Evidence: fresh issue state OPEN, fresh PR #5553 state MERGED, and current-main pkgs/id/src/references.rs plus doc/2026-11-04T15-33-00Z_design_friendly_name_fanout.md.

agent-note:v1
state: handed_off
task: 9464 — triage #5178
agent: repo-worker-code, OpenChamber scheduled lane 335a5d1f-bfc1-4831-99ea-850c8939a727
handed off to: #5927, queued as follow-up task 9828 in repo-health-code-pilot
next: implement locator-hint fetch/render with viewer-specific no-leak behavior; hosted-store search remains a later slice.
links: #5927

agent-note:v1
state: done
task: 9464 — triage #5178
agent: repo-worker-code, OpenChamber scheduled lane 335a5d1f-bfc1-4831-99ea-850c8939a727
result: triaged; #5178 remains OPEN. Fresh evidence and ordered next slices are recorded above. Locator-fetch follow-up is #5927, queue task 9828; hosted-store search remains later.
queue: task 9464 completed as triaged; this lane removed stale queue/claimed, status/in-progress, and work/assigned labels.
links: #5927, #5553

Navigation Menu

Repository navigation

id: friendly-name reference resolution v2 — cross-store fan-out and locator fetch (follow-on to #2259) #5178

Follow-on to #2259 (design + local-store PoC, completed 2026-11-03)

Scope

Carried decision (Drew)

Acceptance criteria

Intake review

9 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

id: friendly-name reference resolution v2 — cross-store fan-out and locator fetch (follow-on to #2259) #5178

Description

Follow-on to #2259 (design + local-store PoC, completed 2026-11-03)

Scope

Carried decision (Drew)

Acceptance criteria

Activity

dezren39 commented on Nov 3, 2026

Intake review

dezren39 commented on Nov 4, 2026

dezren39 commented on Nov 4, 2026

9 remaining items

dezren39 commented on Nov 4, 2026

dezren39 commented on Nov 4, 2026

dezren39 commented on Nov 5, 2026

dezren39 commented on Nov 5, 2026

dezren39 commented on Nov 5, 2026

dezren39 commented on Nov 5, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions