docs(protocol): specify the remote node protocol (B-01) - #101
Open
gustavobertoi wants to merge 5 commits into
Open
gustavobertoi wants to merge 5 commits into
gustavobertoi wants to merge 5 commits into
Conversation
…owledge packs
BACKLOG_V2 tasks are derived from a capability report about the code, not from
the code ("The report describes the code; it is not the code"), so an agent that
treats it as ground truth will confidently implement around bugs that do not
exist. This adds a pipeline that separates verification, planning, building and
review into distinct agents with explicit boundaries.
Agents under .agents/agents/ (per ADR-0009, .claude/agents symlinks into it):
premise-verifier, engine-researcher, implementation-planner, protocol-spec-author,
go-implementer, e2e-harness-engineer, code-reviewer.
Knowledge packs under .agents/skills/: backlog-task (the orchestrating pipeline,
with a routing table for every task id), plus durable-execution-internals,
crash-resume-testing, persistence-and-migrations, observability-tracing,
function-package-authoring, remote-node-protocol, capability-registry-and-agents.
Two boundaries are drawn explicitly because dispatch gets them wrong: process-death
tests belong to the harness engineer and involve no production Go, and the spec
author is the first call for B-01 or any wire-surface change.
Recorded as ADR-0034.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…ed findings
One document per task at docs/backlog/<ID>.md — filenames are the bare id so the
pipeline can open a task by id, deliberately unlike docs/adr/'s NNNN-slug.md.
Each carries the backlog text verbatim, premise status distinguishing EXECUTED
from READ from UNVERIFIED, the code area, the agent route, "Done when" as
checkboxes, out-of-scope, the ADR/spec call, and a dated log.
45 documents: F x3, A x11, B x10, C x12, D x6, plus V-a/V-b/V-c. Tier B, Tier C
proposed work and all of Tier D are marked unmistakably as net-new — presenting a
proposal as shipped behaviour is the failure mode these files exist to prevent.
BACKLOG_V2.md gains a "Found during verification — unfiled" section with the three
bugs F-01 turned up, recorded rather than fixed per the backlog's own rule:
V-a agent tool calls bypass workflow_func.go, so they emit no node.execute span
and no duration metric — evidence against B-03's node/tool parity requirement
V-b resume appends a second subworkflow:started for one exec id; no DB constraint
catches it (sub_workflow_refs is UNIQUE on child_workflow_id only)
V-c Workflow.Next discards the FindNode error and derefs nil, crashing the actor
Ids and tiers are left unassigned on purpose — that is the maintainer's call.
BACKLOG.md is marked superseded rather than deleted; every id in it was renumbered.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
F-01's deliverable: each finding is a checked-in test that fails on the current
tree. All three REPRODUCED. No production code is modified — the point is to
demonstrate the defects against the tree as it stands.
.1 the node span context is discarded (workflow_func.go:96), so function code
cannot inject traceparent. Scope correction: `_ = nodeCtx` is a symptom, not
the defect — nothing downstream can accept a context (ExecuteFunction,
FunctionTransport.Execute and type Function are all context-free), so A-04
is a public pkg/ API change with design tension against ADR-0027.
.2 a restart with a pending system/subworkflow spawns a second child. All four
links verified. Scope correction: synchronous sub-workflows only — the async
branch journals step:completed at workflow_handler.go:936 and is immune.
.3 the memory graph repo returns the live pointer, so an Upsert rewrites a
running run's topology. Driver parity executed against a real Postgres 17:
the postgres driver is immune. This is also A-06's premise.
Each test asserts the DEFECT, not a fix: verified empirically by applying candidate
fixes and confirming each test flips green under every shape tried, and stays red
under a paper-over. An earlier revision asserted source text, a row count a correct
fix would not change, and clone-on-read specifically; all three were rewritten.
These stay on this branch. They cannot go green until A-04, A-02 and A-06 land, so
each merges as the first commit of the PR that fixes its defect rather than turning
main red for two sprints. See docs/backlog/F-01.md for the mapping.
Verified: build ok, lint 0 issues, go test -race reports no data race, and the only
reds in the tree are these six.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The 45 per-task documents now live as draft items on https://github.com/orgs/open-source-cloud/projects/2 — one per task, each carrying its full dossier as the item body (premise status distinguishing EXECUTED from READ from UNVERIFIED, code area with file:symbol, dependencies, agent route, done-when, ADR notes, dated log). Keeping both would have meant two sources of task state drifting apart on the first edit. BACKLOG_V2.md remains the narrative and the rationale; the board owns status, size, priority and assignment. Board fields were derived from the backlog only: Status Done = F-01 (verified and closed); Ready = Sprint 1 remainder (F-02, F-03, A-06, A-07); Backlog = everything else Size the backlog's declared S/M/L; Tier D left unset (no declared size) Priority P0 = Sprint 1 plus B-01 (gates all of Tier B, "before writing any Go") P1 = Sprint 2/3 remainder and the rest of Tier A; P2 = everything else The documents remain in this branch's history at commit 4225bb4 if a file-based copy is ever wanted again. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Add the versioned remote-node protocol spec (v1.0.0-draft) that settles all eight open questions an SDK author needs before implementing a worker: push-vs-pull, the invocation envelope, ack semantics, the success/business-error/infrastructure-error taxonomy, the delivery guarantee and idempotency key, worker<->engine auth, capability declaration/schema, and protocol/capability versioning. Record the dispatch-direction decision as ADR-0035 and index it in docs/adr/README.md. This is Markdown only -- no engine Go changes. It unblocks B-02, B-03, B-05, B-08 and C-10, all of which were blocked on this spec per BACKLOG_V2.md. Co-Authored-By: Claude Sonnet 5 <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.
Summary
docs/protocol/remote-node-protocol-v1.md(v1.0.0-draft) — the versioned wire spec for FUSE's remote-node / extension protocol, precise enough for an SDK author (Laravel, NestJS, any HTTP-capable worker) to implement without reading Go. Settles all eight B-01 decisions, none left TBD: push-vs-pull, the invocation envelope, ack semantics, the completion taxonomy, the delivery guarantee + idempotency key, auth (both directions), capability declaration/schema, and protocol/capability versioning. Every clause is tagged§ TODAY(shipped, file:symbol-cited) or§ PROTOCOL(a requirement the engine/worker must grow), with stableRNP-*clause ids a future B-05 conformance suite can cite.docs/adr/0035-remote-node-protocol-push-transport.md(MADR 3.0, Proposed) recording the why behind the hardest-to-reverse decision — push over pull — and cross-links ADR-0024, ADR-0022, ADR-0023, ADR-0017, ADR-0027.docs/adr/README.md.This is Markdown only — no engine Go was touched. Per
BACKLOG_V2.md, B-01 "blocks every other B task"; this PR unblocks B-02, B-03, B-05, B-08 and C-10 to be planned and implemented against a real clause instead of a guess.Test plan
make swagger(fresh-clone requirement, gitignoreddocs/docs.go/swagger.*regenerated, not committed)make lint— 0 issuesmake build— OKmake test— 731/738 pass; the 7 failures are pre-existing, unrelated RED tests from commitacfb8e6(tests/functional/f01_3_verification_test.go, the F-01.3 live-schema-edit-isolation findings that A-06 will fix) — confirmed bygit diff --statshowing onlydocs/files changed in this branchgit status/git diff --stattouches onlydocs/adr/README.md,docs/adr/0035-remote-node-protocol-push-transport.md,docs/protocol/remote-node-protocol-v1.md🤖 Generated with Claude Code