[dezren39]

Second slice of queue task 3982 / issue #2259. The spec slice merged as #2742 (doc/2026-10-30T13-25-00Z_design_friendly_name_references.md, resolved path repo-root doc/ via the pkgs/id/doc symlink, stated there and in #2742). This PR is the local-store PoC the spec defines.

What lands: pkgs/id/src/references.rs — a self-contained, production-isolated PoC module over one local index (notes/documents surface):

• Reference per spec §1: stable target Hash + sigil kind + author-chosen surface + locator hints + author context, with the markdown degradation [surface](id://<hash>) and its parse round-trip.
• LocalIndex::resolve per spec §3: ranked candidates with provenance (store, claim author, claim_state) — petname tier first (@ only, viewer-local), then exact alias claim, exact title, prefix, token, full-text; boosts never cross tiers.
• No silent picks: a surface claimed by ≥2 targets is Contested; Resolution::single() refuses ties and contested tops; insert_unambiguous errors Ambiguous/NoMatch; the author picks a candidate explicitly via insert, and the stored ID makes the choice permanent.
• render per spec §4: all four states — Resolved, Renamed (stored surface kept, current label reported), Cleared (degrades to label + cleared marker), Unresolved for a viewer whose store lacks the target (inert text revealing only the stored surface).

Tests (run in CI, pkgs/id cargo tests): petname-outranks-claim, tier ordering, duplicate-title grouping + no auto-pick, contested-alias no silent pick, insert+render resolved + markdown round-trip, renamed-target, cleared-target, unresolved-for-another-viewer, sigil separation.

Out of scope (per packet/spec): cross-store fan-out and locator fetch, hosted-store search, any change to aliases.rs display rules, any production resolution feature. The findings note goes on #2259 when this merges.

Refs #2259.

---

^{Need help on this PR? Tag @codesmith-bot with what you need.}

[coderabbitai]

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 11 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: ef9b8fed-27b4-4c33-873c-a240ab926765

Commits

Reviewing files that changed from the base of the PR and between 58635f8 and c161f0e.

Files selected for processing: 2

• pkgs/id/src/lib.rs
• pkgs/id/src/references.rs

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-30T14:08:53.731514Z	c161f0e	New commits

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c51557349d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[dezren39]

🤖 Agent note · parked

• Agent: queue worker (repo-worker-code), lane B shift
• Session / ID: queue task 3982
• Found via: queue claim (resumed parked task)
• Task: id: design+PoC: friendly-name reference resolution, local store — reference representation, index, ranking (from #2047) #2259 spec merged via id: spec for friendly-name reference resolution, local store (#2259) #2742 (58635f8). This PoC PR id: local-store PoC for friendly-name reference resolution (#2259) #2756 is the remaining slice. Parked because CI has not started: the id workflow has no pull_request trigger, so it was dispatched manually — run 41068036058 on head c161f0e — and has sat pending with 0 jobs for ~40 min (Actions queue stall, not a code failure). The queue backend (PostgREST) is also returning 503s, so the park verb itself may land late; this note is the resume record.
• Codex gate: round 1 produced 3 P2 findings (sigil-scoped contested check, markdown escaping, prefix provenance) — all fixed in c161f0e with regression tests, replies posted on each thread, threads resolved. Round 2 on c161f0e posted no new findings.
• Expectation: resume = read run 41068036058 (re-dispatch gh workflow run id-check.yml --ref queue/3982-2259-reference-poc if it died queued); on green, merge this PR, post the findings note on id: design+PoC: friendly-name reference resolution, local store — reference representation, index, ranking (from #2047) #2259 (what the PoC proved / what cross-store fan-out still owes), strip the queue/work/status labels from id: design+PoC: friendly-name reference resolution, local store — reference representation, index, ranking (from #2047) #2259, and complete task 3982 (outcome pr_opened→fixed_merged).
• Links: PR id: local-store PoC for friendly-name reference resolution (#2259) #2756 · CI run https://github.com/developing-today/code/actions/runs/41068036058 · branch queue/3982-2259-reference-poc · laptop worktree ~/git/fleet/3982-2259-reference-poc