Repository navigation
id: design+PoC: friendly-name reference resolution, local store — reference representation, index, ranking (from #2047) #2259
Description
From the #2047 investigation (friendly-name references)
Investigation #2047 (queue task 3355, result posted on that issue 2026-10-29) produced the resolution-flow design sketch for @/# friendly-name references: viewer-relative resolution, per-store indexes with query fan-out, ranking rules extending the existing petname.rs/aliases.rs philosophy (petname first, contested never silently picked), stored references as stable ID + surface text + locator hints, and seven worked ambiguity cases. This issue is the design + proof of concept step for the local half. It is not the permanent feature — nothing production is built on the unreviewed sketch (program rule, epic #2056).
Scope
- Spec (doc in
pkgs/id/doc/): reference object representation (target ID, sigil kind, surface, locator hints), the per-store index contents (titles, alias tag claims, tags, petnames, full text), and the candidate/ranking data types. - PoC: resolution over the local store only in the notes/documents surface — type @/# + phrase, get ranked candidates with provenance, insert a stored reference, render it (including renamed-target and cleared-target states from the id: investigate: friendly-name references — @/# phrase resolution via cross-service search (zettelkasten / Mnote model) #2047 sketch).
Out of scope
Cross-store fan-out and locator fetch (v2, its own issue after this PoC), hosted-store search, any change to aliases.rs display rules.
Acceptance criteria
- Spec doc landed in
pkgs/id/doc/and linked from this issue - PoC demonstrates local resolution incl. duplicate-title and contested-alias cases behaving per the id: investigate: friendly-name references — @/# phrase resolution via cross-service search (zettelkasten / Mnote model) #2047 sketch (no silent picks)
- Findings note posted on this issue: what the PoC proved, what fan-out still owes
- No production resolution feature claimed or merged under this issue
Program: ID platform expansion, epic #2056. Parent investigation: #2047. Related: #2048 (Zettelkasten layer design), #2030 (visibility — search must not leak private objects).
Activity
developing-today commentedon Oct 29, 2026
CODE-1122
dezren39 commentedon Oct 30, 2026
Protocol gap — missing agent note
🤖 Agent note · escalated
queue/claimed+work/assigned+status/in-progress(the monitor repaired those labels this run — the issue still carriedqueue/queued+status/needs-triagewhile the task was claimed), but no comment on this issue contains the requiredagent-note:v1footer. The holding agent did not leave the required agent note.Labels added this pass:
user/review,meta/protocol-gap.dezren39 commentedon Oct 30, 2026
Triage result — design+PoC friendly-name reference resolution, local store (#2259, queue task 3415)
🤖 Agent note · picked up + triaged
Verdict — CONFIRMED, scope stands on current main; split to an implementation follow-up
user/review,priority/high,queue/claimed,work/assigned,status/in-progress,app/id,meta/protocol-gap— noheld,user/owned,do-not-merge, ordo-not-auto-edit. Theuser/reviewwas reviewed by this worker first, per protocol: the input design sketch is the completed id: investigate: friendly-name references — @/# phrase resolution via cross-service search (zettelkasten / Mnote model) #2047 investigation result (posted on id: investigate: friendly-name references — @/# phrase resolution via cross-service search (zettelkasten / Mnote model) #2047, 2026-10-29), and proceeding with a local-store PoC under the epic epic: ID platform expansion — apps, comms, currency, hosting, boards (2026-10-28 directive, LIST 6–15) #2056 program rule (nothing production built on the unreviewed sketch) needs no new decision from Drew. Not escalated.gh api contents, 2026-10-30):pkgs/id/src/petname.rsandpkgs/id/src/aliases.rs(the naming philosophy the id: investigate: friendly-name references — @/# phrase resolution via cross-service search (zettelkasten / Mnote model) #2047 sketch extends: petname first, contested never silently picked), pluspkgs/id/src/tag_index.rs,pkgs/id/src/search.rs, andpkgs/id/src/documents.rsas the local index/search/documents surfaces the PoC builds on.pkgs/id/docon main is a symlink to../../doc(repo-rootdoc/, which holds the dated design/feature docs, e.g.2026-10-07T00-20-00Z_feature_petnames_invites). A spec landed "inpkgs/id/doc/" therefore lands in the repo-rootdoc/tree and should follow that dated-name convention; the implementation follow-up must state the resolved path explicitly instead of treatingpkgs/id/doc/as a real directory.Disposition
Triage complete. An implementation follow-up (small_fix, Phase: spec + local PoC) is enqueued from this triage; this issue stays open as the tracking issue for that work, per its own acceptance criteria.
🤖 Agent note · done (triage)
71 remaining items
docs(id): record #2259 reference design
dezren39 commentedon Nov 1, 2026
Design note: local friendly-name reference design.
DocumentRecord.idrevision-level references (recommended for this PoC) or (b) a stable logical note ID that follows later saves.Merge pull request #3829 from developing-today/design/id-2259
Merge pull request #2756 from developing-today/queue/3982-2259-refere…
dezren39 commentedon Nov 3, 2026
RULING (Muse, acting for Drew, 2026-11-03): option (a) — a worker round on PR #2756: address the unresolved Codex findings (verify on the laptop; Codex is usage-walled), land or explicitly close the PoC, and unstick task 3982. A fresh fix task is enqueued for the PR round; task 3415 resumes once #2756 merges/closes.
dezren39 commentedon Nov 3, 2026
agent-note:v1
event: done — findings posted, issue dispositioned (closed as completed)
task: 6830 (repo-health-code-pilot; worker repo-worker-code; lane code-c)
Findings — what the PoC proved
All four acceptance criteria are met:
doc/2026-10-30T13-25-00Z_design_friendly_name_references.md, verified present on main); design record followed in PR design(id): #2259 friendly-name references #3829 (merged 2026-11-02) and was linked from this issue 2026-11-01.4b6d1f93);pkgs/id/src/references.rsverified present on main (39,214 B). It implements the spec'sReference(stable target Hash + sigil + authored surface + locator hints, markdown degradation with parse round-trip),LocalIndex::resolvetier ranking with provenance (petname tier first for@, then exact alias claim, exact title, prefix, token, full-text; boosts never cross tiers), and all four render states (Resolved, Renamed, Cleared, Unresolved-for-viewer). No silent picks: a surface claimed by ≥2 targets isContested,Resolution::single()refuses ties/contested tops,insert_unambiguouserrors instead of guessing. CI tests named in the PR cover: petname-outranks-claim, tier ordering, duplicate-title grouping + no auto-pick, contested-alias no silent pick, insert+render + markdown round-trip, renamed-target, cleared-target, unresolved-for-another-viewer, sigil separation.What fan-out still owes (v2)
Cross-store fan-out, locator fetch, and hosted-store search were out of scope here by design. They are now tracked as issue #5178, which also carries the one still-open Drew decision from the 2026-11-01 design note — Q1, document identity ((a)
DocumentRecord.idrevision-level references vs (b) a stable logical note ID) — since v2's reference representation depends on it.Closing #2259 as completed.