[STRAWMAN] docs(grid): MULTI-PEER-COMMANDS.md — multi-author seed (companion to #1439)#1440
Draft
joelteply wants to merge 7 commits into
Draft
[STRAWMAN] docs(grid): MULTI-PEER-COMMANDS.md — multi-author seed (companion to #1439)#1440joelteply wants to merge 7 commits into
joelteply wants to merge 7 commits into
Conversation
Companion to continuum#1439 GRID-BUS-ARCHITECTURE. Defines which Continuum commands distribute across grid + how distributed resources are addressed (handles) + concrete shapes for multi-peer commands. **This is a STRAWMAN, not a finished doc.** Per Joel's direction (2026-05-25 'you are not alone, divide up research and planning'), the 8 sections are intended for multi-author ownership: - §1 existing primitives inventory → research baseline (any reviewer) - §2 command classification table → claude-tab-2 (16279c3f) — needs bus-architecture-author depth - §3 quorum model + §4.1 genome paging + §4.4 multi-peer RAG → claude-tab-1 (55c30b28) — Lane C2 consumer-side context - §4.2/4.3 federated inference + distributed training → dba950ce or whoever takes adapter-integration depth - §4.5 multi-peer forge runs → codex (543c0bf7) — forge substrate - §5 handle distribution model → codex Rust side + claude-tab-1 TS side, paired - §6 hosting/payment + §7 forge-alloy as universal contract substrate → claude-tab-2 (per Joel's vision clarification + tab-2's own forge-alloy correction) - §8 migration sequencing → claude-tab-2 (owns #1439 bus migration) Reviewers should REPLACE their owned sections wholesale if my strawman framing doesn't fit — this is starting material, not finished design. Sections I'll commit to keeping mine: §3, §4.1, §4.4, and TS half of §5. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Per the work-division on #cambriantech 2026-05-25: claude-tab-1 (55c30b28) wrote first-pass draft of all sections including §2/§6/§7/§8. This commit refines those four sections per the wholesale-handoff invitation. §2 — added 2.1 with rows the first-pass missed (ping for #1439 grid-routable example, inbox/persona-turn-execute migration trajectory, cognition/* per-persona binding, presence:peer-manifest + contract:* event classes, grid/show-* introspection commands). Sharpened axis-rationale prose. §6 — added 6.1 per-circle pricing defaults table (local/household/trusted-orgs/extended/public-mesh × cost model × sentinel scrutiny × contract artifact). Added 6.2 capability liveness + withdrawal mechanics. Added 6.3 three worked hosting examples (ai/generate household, genome/train federated mixed-tier, data/vector-search any-quorum household). §7 — substantial rewrite incorporating canonical-doc references I missed on #1439's first pass (logged in #1439 appendix correction). 7.1 quotes FORGE-ALLOY-DOMAIN-EXTENSIBILITY.md TL;DR + FORGE-ALLOY-PROOF-CONTRACTS.md proof-contract object shape. 7.2 names the Continuum-side drift + the 6-work-item refactor as prerequisite. 7.3 computation-kind → alloy-domain mapping table (model forging 0x01, delivery 0x05, evaluation 0x06, custom 0xFF). 7.4 conditional claim: refactor lands before first non-ML multi-peer command. Resolves #1439 Q11 — not Path A/B (both were my reinvention), but the already-designed Domain Extensibility refactor. §8 — added 8.1 worked example: ping opts into multi-peer in 2 lines (smallest opt-in). Added 8.2 phased opt-in order (Phase A proof-of-life → Phase G distributed forge), each phase separately shippable. Added 8.3 revert path. Added 8.4 explicit out-of-scope (persona migration, sentinel arbitration protocol, LP wallet on-chain settlement, recipe-as-grid-contract semantics). Kanban cards claimed (CambrianTech/continuum repo, P1): §2 0525edc6-6411-4d00-99fe-9d86de1af1bb §6 38848f04-563e-4929-931f-a9cb3d911f76 §7 e5c65d27-4620-4655-a74a-c2487434ef90 §8 ca374e43-4399-42fe-82b5-0415929b058a Co-Authored-By: claude-tab-1 <55c30b28-f01d-4a33-bb71-dc0279bbe7ef> Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…dge cases
Card fbf8912e-eb3a-4bf9-9f75-53b07f59f110 (claude-tab-1 / 55c30b28).
Revises §3 from strawman framing to decisive spec:
- Default quorum for naturalScope='grid' commands is 'single' (lowest-cost,
matches today's GridInterceptor behavior); 'multi'/'any' are explicit
opt-ins per call site.
- §3.2 'single' quorum: explicit failure modes (no-matching-peer,
peer-unreachable, no-accepting-peer), retry-budget defaults (3 retries
with exp backoff capped 5s), no-auto-retry for mutating commands —
command class declares idempotent: true to opt into retry.
- §3.3 'multi' quorum: concrete defaults table (min: 2, max: 8, slow_peer_
timeout_ms reducer-specific, result_freshness_ms 30s), 6 reducer types
(fedavg/majority-vote/weighted-average/best-of-N/union/custom) with
specific defaults each, if_under_min triple option (fail / proceed-
degraded / wait-up-to-Ns) with rationale per command-class, contract
attribution rule (per-peer chain, only successful peers paid).
- §3.4 'any' quorum: fan_out_to ('all-matching' default), reducer choices
(first-good-enough / merge-top-k / union), adaptive max_wait_ms (p95 of
recent latency * 1.5, capped 5s), early_return_on_first opt-in, privacy
filter at SOURCE not reducer.
- §3.5 cross-cutting: ordering (reducer's responsibility), idempotency
contract (multi/any dispatchers must dedupe), backpressure via
presence:resource-pressure (router-side, not scope), observability
(grid:quorum:dispatched + :resolved as broadcast events).
- §3.6 explicit non-quorum concerns: routing target hints, trust circle,
backpressure, reservation TTL — these live elsewhere on scope.
Strawman framing was vague on defaults; spec needs decisive values so
per-call scope.quorum overrides are meaningful. All defaults rationalized
in-table.
No code change. Reviewers: claude-tab-2 (for consistency with §2 command
classification + §8 migration), codex (for substrate-side dispatch logic),
joel (for default rationale).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…-tab2-sections docs(grid): MULTI-PEER-COMMANDS §2/§6/§7/§8 refinements + §7 canonical-doc corrections
…chemas + FETCH/DELEGATE decision tree
Card cdc37197-dc18-4030-81ce-5655004abc2e (claude-tab-1).
Refines §4.1 from strawman framing to implementation-spec:
- §4.1.1 explicit inventory of single-machine primitives (AdapterStore,
LayerLoader, GenomeRegistry, PagedResourcePool, GenomeDaemon) —
confirms grid extension preserves all of them unchanged.
- §4.1.2 typed event schemas for the two new event classes:
AdapterAvailableEvent (per-peer inventory broadcast on join+heartbeat,
deduped by monotonic sequence) and AdapterPressureEvent (hysteresis
threshold-crossings only, lists eviction candidates so other peers
can pre-fetch). Plus GridAdapterIndex API surface.
- §4.1.3 FETCH vs DELEGATE decision tree as operator policy: depends on
local-GPU-can-run-inference + estimated-use-count + vram-budget.
Per-circle defaults (household FETCH-leaning, trusted-orgs DELEGATE-
leaning).
- §4.1.4 ASCII flow diagram for cross-peer paging-activate (both
FETCH and DELEGATE paths).
- §4.1.5 hot-path inference through a remote adapter (DELEGATE): A
dispatches ai/generate via grid router with scope.peer_id=B; B's
standard local inference path with adapter pinned; token stream
back via airc bus on inference handle's scoped channel. Calling
code unchanged.
- §4.1.6 multi-peer paging pressure model: peers react to broadcast
pressure events (pre-fetch / voluntary release / dispatch elsewhere)
— self-regulating mesh, no central scheduler.
- §4.1.7 version-pinning sharp edge: content-stable manifest_id makes
DELEGATE safe across same versions; cross-version requires explicit
adapter_version_policy. Plus federated-training implication —
eager-fan-out within contributing peer set, lazy DELEGATE for
others.
- §4.1.8 explicit non-goals: sharded loading (model-parallel out of
scope), runtime adapter merging, weights_sha256 verification gap
(TODO follow-up card).
Composes existing primitives, adds 2 event classes + 1 new TS file
(GridAdapterIndex). No daemon changes. No protocol changes. Per the
no-shim rule: extends primitives via metadata broadcast + per-policy
decision, not via a wrapping adapter layer.
Reviewers: codex (substrate side — confirm the event classes can ride
existing airc-lib subscribe primitives), joel (FETCH/DELEGATE policy
defaults match grid-economy intent).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ce + re-rank math + namespace contract
Card fc1e3262-7ad4-4f92-9f4b-f322e004f387 (claude-tab-1).
Refines §4.4 from strawman framing to implementation-spec:
- §4.4.1 explicit inventory of single-machine primitives (data/vector-
search, engram store, cognition/recall-engrams).
- §4.4.2 new event classes (GridRagRequest + GridRagResponse) with
full typed schemas. Single new flag (scope.fan_out) is the API
delta from caller's perspective.
- §4.4.3 ASCII flow diagram for cross-peer fan-out.
- §4.4.4 re-ranking math: dedup-by-content-hash, cosine score
commensurable across peers IFF same embedding model (enforced via
namespace contract), min-alloy filter for index recall quality
control, score-zero handling.
- §4.4.5 privacy filter HARD RULE: applied at source peer per its own
policy, never re-asked by reducer. Three sharing levels (full /
signal-only / denied) per-circle in grid-policy.json. Worked example
(Joel's household + Toby's grid).
- §4.4.6 namespace distinction: engrams:* (per-persona, privacy-
filtered) vs published:* (opt-in shared, no filter). Cross-peer
fan-out covers both; semantics differ.
- §4.4.7 hot-path perf: embedding-gen latency depends on local model
avail, wait deadline tuning (LAN vs cross-internet), result volume
is trivial (~80 items at K=10, N=8), filter cost negligible.
- §4.4.8 non-goals: cross-model embedding alignment (future research),
persistent cross-peer subscription (different shape), cross-peer
engram WRITE (separate spec with contract chain), federated learning
over engrams (hybrid of §4.3 + §4.4).
The privacy-at-source rule is the key invariant: each receiving peer
decides what to return based on its OWN policy. Reducer never re-asks
for withheld content. Per-engram metadata flags (e.g. private: true on
a journal entry) override per-circle defaults.
Reviewers: codex (event-class registration), joel (privacy defaults +
namespace contract), dba950ce (engram-tier interactions if their
sections touch this).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Card 54dc3648-ae0a-49e2-8608-ceca9a84a3c1 (claude-tab-1, TS side).
Rust-side spec open for codex to pair.
Refines §5 from strawman to TS-implementation-spec:
- §5.1 RemoteResourceHandle<T> typed interface extending existing
Handle<T>. 8 fields total (5 inherited from Handle, 3 grid-specific:
peer_id, remote_handle_id, resource_kind, resource_hint, fetch_
strategy, reservation_id?, trust_circle).
- §5.1.1 8 resource kinds with default fetch_strategy each (lora_
adapter delegate, kv_cache always delegate, inference_session always
delegate, embedding_index delegate, render_buffer pull-on-use,
model_weights pull-immediately, media_blob pull-on-use, custom).
- §5.2 4 caller-facing methods (.value() / .unpin() / .status() /
.heartbeat()) with explicit semantics + throws conditions. Async
proxy caching for delegate strategy, byte caching for pull-on-use.
- §5.3 pin lifecycle ASCII sequence covering REQUEST → PIN-RESPONSE
→ DISPATCH → UNPIN with both A (caller) and B (holder) perspectives.
Safety section explains why no orphan pins survive crashes
(heartbeat-driven timeout on holder side, 2× TTL).
- §5.4 lease + reservation with concrete defaults table (10s reservation,
5min TTL, 1min heartbeat, 10min orphan timeout) and 3 reservation
policies (first-come / priority-circle / bid) per holder policy.
- §5.5 content-addressed FETCH path for the FETCH-side of the §4.1.3
decision tree. Hash verification on receive, dedup by content hash,
multi-source fetch deferred.
- §5.6 cross-cutting: handle id disambiguation (local .id vs remote_
handle_id), status events ride airc bus on scoped channel (no
polling), JSON serialization clean, TS/Rust boundary explicit.
- §5.7 non-goals: Rust-side substrate (codex owns), streaming-handle
semantics (follow-up), multi-hop dispatch handle propagation
(deferred until use case), cross-grid handle sharing (separate spec).
Per the no-shim rule: TS doesn't reimplement pin lifecycle logic — it
dispatches through IPC to Rust which owns the truth. RemoteResource
Handle is a typed wrapper class around the existing Handle pattern,
not a new abstraction layer.
All 4 my-owned sections (§3, §4.1, §4.4, §5 TS) now done. Codex on §5
Rust spec when they pick up the card; dba950ce on §4.2/§4.3 if they
take it; codex/anyone on §4.5 if they take it.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Status: DRAFT / strawman / multi-author seed. Do NOT merge as-is.
Per Joel's direction (2026-05-25 'you are not alone, divide up research and planning — that's what airc is for'), this PR is a seed doc multiple agents will own different sections of.
Ownership (announced on #cambriantech)
How to contribute
What this doc is
Sits below #1439 (the bus + transport layer) and above per-command implementation work (§5.3 of #1439). Answers: 'OK we have a grid bus — what RUNS on it, what stays local, and how do peers actually share things?'
What this doc is NOT
Verification
Coordination
Reply on #cambriantech over airc with section claims / acks / counterproposals. Doc does not gate anything from landing — opt-in is per-command; legacy paths keep working.