id: design: client surfaces parity (from #5675)

Summary

Follow-on design ticket from #5675 — its decomposition sketch names this as a separate design, and the parent's acceptance requires these tickets to be filed and linked. Filed in the 2026-11-04 gap pass (WS-F) so the design work exists and can be prioritised on its own merits; implementation timing is a separate decision, possibly months out.

What this design must settle

Scripting/API, agent, and CLI front doors over one query model — parity as a tested property, not a hope.

Context from the parent

The parent design fixes the filtering model, the owner-override boundary, surface parity, and pagination/result rules for querying local and remote ID servers. The parent issue carries the surrounding decisions this ticket must not re-decide; where this ticket's answer would change a parent decision, record that explicitly rather than silently forking it.

Decision record expected

Close this design with a recorded decision (on this issue or in a doc/ record linked from it): the chosen shape, the alternatives rejected and why, and the invariants implementation must hold. If the design splits further, file the splits and link them here rather than growing this issue.

Relations

Parent: #5675. Programme: epic #2056. Filed by WS-F (2026-11-04 ID design gap & expansion pass).

CODE-1503

🤖 Agent note · handed off

Agent: queue worker (repo-worker-code), lane code-j
Session / ID: task 10223
Found via: queue claim
Task: task 10223 (triage for issue id: design: client surfaces parity (from #5675) #5820) is assigned to the opencode execution lane — handing off to the opencode claimant, which launches the bound session. This lane did not work it itself.
Expectation: claimant launches the bound opencode session for task 10223; if unbound by lease/park expiry, task 10223 returns to the queue.
Links: issue id: design: client surfaces parity (from #5675) #5820

🤖 Agent note · handed off

Agent: queue worker (repo-worker-code), lane code-o
Session / ID: task 10223
Found via: queue claim
Task: Triage issue id: design: client surfaces parity (from #5675) #5820 (id: design: client surfaces parity, from issue id: design: Querying local and remote ID servers v1 #5675) — assigned to the opencode execution lane again on re-claim (previously handed off at 2026-11-05T12:45Z, claimant had not launched before the park cycled); handed off to the laptop claimant, not worked by this lane. Issue verified OPEN this shift, no hard-stop labels.
Expectation: claimant launches the bound opencode session for task 10223.
Links: issue id: design: Querying local and remote ID servers v1 #5675 (parent)

🤖 Agent note · handed off

Agent: queue worker (repo-worker-code), lane code-l
Session / ID: task 10223
Found via: queue claim
Task: handing off task 10223 for issue id: design: client surfaces parity (from #5675) #5820 to the opencode claimant (execution lane: opencode)
Expectation: claimant launches the bound opencode session and drives task 10223 to a terminal state
Links: issue id: design: client surfaces parity (from #5675) #5820

🤖 Agent note · parked

Agent: queue worker (repo-worker-code), lane code-e
Session / ID: task 10603
Task: Design id: design: client surfaces parity (from #5675) #5820 (client surfaces parity) — revalidated the packet's ordering gate fresh this shift: issue id: design: server-side filtered remote query execution (from #5675) #5818 is still OPEN with queue/parked, and issue id: design: result shaping & cursor pagination (from #5675) #5821 is still OPEN with queue/parked, so the final surface contract cannot be settled yet. The preliminary surface inventory is already recorded on this issue (2026-11-05T16:18Z note, task 10603): CLI handlers/SearchOptions in pkgs/id/src/commands/find.rs (cmd_find, cmd_search, cmd_find_matches) and MetaRequest::Find at pkgs/id/src/protocol.rs:309. No new work was duplicated.
Resume condition: id: design: server-side filtered remote query execution (from #5675) #5818 and id: design: result shaping & cursor pagination (from #5675) #5821 decisions are both available (issues closed or their decision records posted); then settle the final id: design: client surfaces parity (from #5675) #5820 surface contract against them.
Links: issue id: design: client surfaces parity (from #5675) #5820 · gate issues id: design: server-side filtered remote query execution (from #5675) #5818, id: design: result shaping & cursor pagination (from #5675) #5821 · parent id: design: Querying local and remote ID servers v1 #5675

Agent note — parked on ordering gate (task 10603)

Task: task 10603 — small_fix (design) for issue id: design: client surfaces parity (from #5675) #5820, assigned_lane direct, worked by lane code-m. Resumed from checkpoint stage verified (preliminary surface inventory already posted on issue id: design: client surfaces parity (from #5675) #5820 at 2026-11-05T16:18Z).
Gate revalidated fresh 2026-11-05T17:37:18Z: issue id: design: server-side filtered remote query execution (from #5675) #5818 OPEN (status/parked) and issue id: design: result shaping & cursor pagination (from #5675) #5821 OPEN (status/parked) — both sibling decisions still unavailable. Per the packet's ordering gate, the final surface contract must not be settled until id: design: server-side filtered remote query execution (from #5675) #5818 (filtered remote execution / withheld-result honesty) and id: design: result shaping & cursor pagination (from #5675) #5821 (result shaping / cursors) land.
Action: parked 30 min with resume condition; no code or design record changed this pass.

🤖 Agent note · parked

Agent: repo queue worker, lane code-h (repo-worker-code)
Session / ID: cron repo-queue-worker-shift-h run 2026-11-05; task 10603
Found via: claimed task 10603 this shift; resumed from its verified checkpoint (preliminary inventory already posted 2026-11-05T16:18Z)
Task: task 10603 for issue id: design: client surfaces parity (from #5675) #5820 (small_fix). Fresh revalidation 2026-11-05T18:12Z: issue id: design: client surfaces parity (from #5675) #5820 is OPEN with no hard-stop labels (held / user/owned / do-not-merge / do-not-auto-edit); gate issues id: design: server-side filtered remote query execution (from #5675) #5818 and id: design: result shaping & cursor pagination (from #5675) #5821 are both still OPEN, so the final surface contract remains gated on those decisions, exactly as the checkpoint recorded. No implementation started.
Expectation: resume task 10603 once id: design: server-side filtered remote query execution (from #5675) #5818 and id: design: result shaping & cursor pagination (from #5675) #5821 are merged/closed, then implement the shared query front doors per the verified inventory.
Links: task 10603 · issue id: design: client surfaces parity (from #5675) #5820 · id: design: server-side filtered remote query execution (from #5675) #5818 · id: design: result shaping & cursor pagination (from #5675) #5821

🤖 Agent note · parked

Agent: queue worker (repo-worker-code), lane code-c
Session / ID: task 10603
Found via: queue claim
Task: Preliminary inventory for the id: design: client surfaces parity (from #5675) #5820 surfaces-parity design only — the final contract is NOT settled this pass, per the packet gate: siblings id: design: server-side filtered remote query execution (from #5675) #5818 and id: design: result shaping & cursor pagination (from #5675) #5821 are both still unresolved at fresh check (2026-11-05 18:47Z: id: design: server-side filtered remote query execution (from #5675) #5818 OPEN parked, id: design: result shaping & cursor pagination (from #5675) #5821 OPEN in-progress/claimed).
Expectation: resume when id: design: server-side filtered remote query execution (from #5675) #5818 (filtered execution/honesty/audit) and id: design: result shaping & cursor pagination (from #5675) #5821 (cursor/truncation) are both resolved; then write the decision record cross-checked against id: design: Querying local and remote ID servers v1 #5675, id: design: ID query language/shape v1 (from #5675) #5816, id: design: sensitivity classification model (from #5675) #5817, id: design: owner override mechanics & the encryption boundary (from #5675) #5819, id: design: mutating surface separation (from #5675) #5822.

Preliminary inventory (current main c8a1913, read-only):

Human CLI surface (exists today): pkgs/id/src/main.rs dispatches Command::Find (~line 466), Command::Search (~486), Command::Show (~502), and Command::Peek (~516); all four build the same legacy SearchOptions::new(first, last, count, exclude) and call cmd_find / cmd_search / cmd_show / cmd_peek in pkgs/id/src/commands/find.rs (lines 224 / 360), over the shared core cmd_find_matches (line 914).
Legacy query semantics (the gap vs id: design: ID query language/shape v1 (from #5675) #5816): find.rs implements fuzzy name/hash matching only — Exact / Prefix / Contains match types, --format tag|group|union, --first/--last/--count/--exclude limiting. This is not the id: design: ID query language/shape v1 (from #5675) #5816 canonical structured query object; the design must map these four verbs onto that object without silently dropping the --format / limiting behaviors scripts may already depend on.
Scripting/API surface: the same cmd_* handlers are the library entry points (pub use find::{...} in pkgs/id/src/commands/mod.rs); remote execution goes through serve/client (pkgs/id/src/commands/serve.rs, client.rs) with cmd_find_matches running against a remote node via MetaRequest — so a script/API adapter over the canonical query object has an existing local/remote split to attach to.
Agent surface: no dedicated agent query front door exists yet; the closest surfaces are the REPL (pkgs/id/src/commands/repl.rs, pkgs/id/src/repl/input.rs — the only other mcp mention besides serve.rs) and the web UI (pkgs/id/src/web/). The design must state whether the agent door is the REPL, the web/API layer, or a new adapter — without a privileged query path (packet invariant).
Settled inputs confirmed fresh: id: design: ID query language/shape v1 (from #5675) #5816 CLOSED (canonical query object; names find.rs as the existing CLI surface); id: design: Querying local and remote ID servers v1 #5675 OPEN (parent); id: design: sensitivity classification model (from #5675) #5817, id: design: owner override mechanics & the encryption boundary (from #5675) #5819, id: design: mutating surface separation (from #5675) #5822 OPEN.

🤖 Agent note · preliminary inventory — parked on sibling designs

Agent: repo queue worker, lane code-x (repo-worker-code)
Session / ID: cron repo-queue-worker-shift-x run 2026-11-05 12:39 CST; task 10603 (direct lane, attempt 1/4)
Dependency gate (per this task's own acceptance/tests): the final front-door contract must be cross-checked against id: design: server-side filtered remote query execution (from #5675) #5818 (server-side filtered remote query execution) and id: design: result shaping & cursor pagination (from #5675) #5821 (result shaping & cursor pagination); if either is unresolved, only a preliminary inventory is done and the task parks. Fresh check 2026-11-05: id: design: server-side filtered remote query execution (from #5675) #5818 OPEN, id: design: result shaping & cursor pagination (from #5675) #5821 OPEN → parking after inventory, as specified. (id: design: ID query language/shape v1 (from #5675) #5816, the canonical query shape this design builds on, is CLOSED; id: design: Querying local and remote ID servers v1 #5675 parent and id: design: sensitivity classification model (from #5675) #5817/id: design: owner override mechanics & the encryption boundary (from #5675) #5819/id: design: mutating surface separation (from #5675) #5822 siblings remain OPEN.)
Preliminary inventory (current main aab9b8c, laptop primary clone):
- Human CLI surface: pkgs/id/src/cli.rs — find / search / show / peek commands with documented filtering (cli.rs module docs lines 20–41), plus tag/claim search subcommands. This is the existing find/search behavior the decision record must map onto the id: design: ID query language/shape v1 (from #5675) #5816 canonical query object without silently removing compatibility.
- Local UI / agent-facing surface: pkgs/id/src/directory_view.rs (the local UI that calls directory APIs such as request_friend_as/accept_friend_as — cf. PR fix(id/directory): validate friend-request IDs at admission, preserve legacy removals (#5624) #6239 review evidence), backed by world_session / world_store.
- Scripting/API surface: pkgs/id/src/meta_client.rs and the web layer (pkgs/id/src/web/routes.rs, web/world_ws.rs, web/tags_ws.rs) — the remote/server front door whose filtered execution is exactly what id: design: server-side filtered remote query execution (from #5675) #5818 owns.
- No shared canonical-query-object type is yet consumed by all three surfaces in pkgs/id/src (grep for a shared Query struct hits only web-layer files) — parity is currently per-surface, which is the gap this design closes once id: design: server-side filtered remote query execution (from #5675) #5818/id: design: result shaping & cursor pagination (from #5675) #5821 settle.
Resume condition: task 10603 resumes when id: design: server-side filtered remote query execution (from #5675) #5818 and id: design: result shaping & cursor pagination (from #5675) #5821 are both CLOSED; then the decision record can be settled and cross-checked. Parked 24h per cycle until then.
Links: task 10603 · issue id: design: client surfaces parity (from #5675) #5820 · parent id: design: Querying local and remote ID servers v1 #5675 · siblings id: design: ID query language/shape v1 (from #5675) #5816 (closed) / id: design: server-side filtered remote query execution (from #5675) #5818 / id: design: result shaping & cursor pagination (from #5675) #5821

Navigation Menu

Repository navigation

id: design: client surfaces parity (from #5675) #5820

Summary

What this design must settle

Context from the parent

Decision record expected

Relations

15 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

id: design: client surfaces parity (from #5675) #5820

Description

Summary

What this design must settle

Context from the parent

Decision record expected

Relations

Activity

developing-today commented on Nov 5, 2026

dezren39 commented on Nov 5, 2026

dezren39 commented on Nov 5, 2026

dezren39 commented on Nov 5, 2026

15 remaining items

dezren39 commented on Nov 5, 2026

developing-today commented on Nov 5, 2026

developing-today commented on Nov 5, 2026

dezren39 commented on Nov 5, 2026

developing-today commented on Nov 5, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions