Skip to content

session-relay Rust port (steps 1-6) + knowledge-format lint & citations#4

Merged
DocksDocks merged 18 commits into
mainfrom
explore/rust-port-and-okf
Jul 1, 2026
Merged

session-relay Rust port (steps 1-6) + knowledge-format lint & citations#4
DocksDocks merged 18 commits into
mainfrom
explore/rust-port-and-okf

Conversation

@DocksDocks

@DocksDocks DocksDocks commented Jul 1, 2026

Copy link
Copy Markdown
Owner

What's in here

Three plans on one exploration branch, two of them executed:

session-relay Rust port — steps 1–6 of 8 (plan: docs/plans/active/session-relay-rust-port.md)

  • Crate at plugins/session-relay/rust/: full behavioral port of the five Node store-touchers into one multi-call relay binary (bus/hook/CLI), kernel flock replacing the mkdir-mutex, pinned toolchain 1.85.0, min-size release profile. 10 cargo tests incl. an 8×10 cross-process lock race and a black-box MCP lifecycle smoke.
  • CI: tag glob broadened to *--v*; guarded Rust provisioning in the validate job; new build-binaries.yml (workflow_dispatch only, 2 runners → 4 arches).
  • Author tooling: registry-driven rust capability — ci.mjs gates fmt/clippy + a --locked musl host-leg build + committed-checksum verify; release.mjs refuses to tag without all 4 committed binaries.
  • Tests/docs on the binary: selftest.mjs rewritten black-box (39 checks, every store touch through the binary), new read-only relay peek, SKILL.md paths flipped to <plugin>/bin/relay.
  • NOT yet flipped: consumer manifests still point at the Node files — that is step 7, which needs build-binaries.yml dispatched from main (workflow_dispatch only lists default-branch workflows). Binaries land in a follow-up PR; the Node payload is deleted there too (step 8).

knowledge-format lint & citations — executed + review passed (plan being shipped on this branch)

Karpathy LLM-Wiki Lint checks folded into context-tree audit + skill-maintenance drift tables; OKF/Karpathy cited as convergent prior art. No vendoring.

okf-knowledge-bundle — parked stub plan (status: planned), untouched until picked up.

Verification

  • node scripts/ci.mjs green locally (2 plugins + repo-wide, incl. the new Rust leg: fmt/clippy clean, musl host build, 39-check selftest).
  • cargo test 10/10; cargo clippy --all-targets -- -D warnings clean.
  • release.mjs --dry-run --plugin session-relay correctly REFUSES to tag while binaries are uncommitted.

🤖 Generated with Claude Code

https://claude.ai/code/session_01UyDDEDsq6yGeJKzNAwW3ZQ

DocksDocks and others added 18 commits July 1, 2026 16:15
@DocksDocks @claude
plan(knowledge-format-lint-and-citations): draft — OKF citations + Li…
239a52e 
…nt checklist

Fold a maintenance Lint checklist into the context-tree audit and
skill-maintenance skills, and cite OKF (Apache-2.0) + Karpathy LLM-Wiki
as prior art — citation-not-adoption (license + architecture mismatch).
No vendoring, no OKF schema, no new skill.

Self-reviewed 89/100 (draft red-team, all 10 holes fixed).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UyDDEDsq6yGeJKzNAwW3ZQ
@DocksDocks @claude
plan(session-relay-rust-port): draft — zero-runtime single Rust binary
91f2f3e 
Replace session-relay's five store-touching Node .mjs with one static
Rust `relay` binary (4 committed arches + sh launcher) so a Codex-only
host needs no Node, and upgrade the store lock mkdir-mutex → kernel flock.
Full port, commit binaries in-tree (maintainer scope choice).

Darwin binaries produced by a native-runner build matrix (build-binaries.yml),
committed before the tag; ci.yml gains Rust provisioning so ci.mjs builds the
host leg. 7 steps, planned against main 7ee6a0d.

Self-reviewed 66 → 88/100 (fresh-context draft red-team; its 9 findings —
3 blocking build/CI/delete gaps + a false-passing grep + a step/goal
conflict — applied pre-start).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UyDDEDsq6yGeJKzNAwW3ZQ
@DocksDocks @claude
plan(session-relay-rust-port): pin build/delivery model — CI canonica…
5810e79 
…l + Mac fallback

Answer the "how do binaries ship for multiple plugins" question in the plan:
- Binaries committed in-tree (git-clone delivery), NOT Release assets — the
  reason "every consumer just installs it" works; make the rationale explicit.
- Chicken-and-egg: build pre-tag → commit → release.mjs asserts + tags.
- Producer decision: GitHub Actions native matrix canonical (decouples release
  from having a Mac) + rust/build-all.sh local Apple-Silicon fallback.
  Linux host can only make the 2 musl arches — darwin needs Apple.
- build-binaries.yml is workflow_dispatch-only (fixed the tag-trigger
  contradiction); validate is the tag gate. Windows-native marked out of scope.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UyDDEDsq6yGeJKzNAwW3ZQ
@DocksDocks @claude
plan(both): web-verify every external claim + add cited Sources
f6f866c 
Research pass (2026-07-01) grounding both plans in fetched sources, not memory:

session-relay-rust-port:
- GitHub runner labels were STALE — macos-13 (Intel) is retired; switch to one
  arm64 macos-latest runner cross-building both darwin arches + one ubuntu for
  musl (4 binaries, 2 free runners). Source: GitHub-hosted runners reference.
- Drop the build-all.sh Mac "fallback" — speculative second build path; CI makes
  all four, Mac dev needs only the host leg. (Answers "why the Mac fallback?".)
- Codex substitution clarified: native ${PLUGIN_ROOT} + ${CLAUDE_PLUGIN_ROOT}
  compat; issue #19372 = residual risk; STOP retained. Claude binary-command
  flip confirmed documented-supported. Rust 1.85/edition-2024, rustix::fs::flock,
  cross-can't-ship-darwin all confirmed. Added a cited External-research block.

knowledge-format-lint-and-citations:
- Fixed a MIS-SOURCED claim: OKF Apache-2.0 was cited to the Google Cloud blog,
  which doesn't state a license — real source is the knowledge-catalog repo
  LICENSE (claim itself true). Format + Karpathy Lint items verified verbatim.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UyDDEDsq6yGeJKzNAwW3ZQ
@DocksDocks @claude
plan(both): apply second red-team + engineering/plugin best-practice …
221404d 
…pass

Fresh-context re-review (rust 75/100, knowledge 87/100) merged with a
practices research pass (MCP spec, Claude hooks/plugins docs, min-sized-rust,
Cargo book, git-lfs):

session-relay-rust-port:
- BLOCKING: the "Codex uses native ${PLUGIN_ROOT}" decision had not propagated
  to Goal/Interfaces/Step 6 — added a per-manifest flip table (Claude MCP +
  exec-form hooks on ${CLAUDE_PLUGIN_ROOT}; Codex bus.mcp.json on native
  ${PLUGIN_ROOT}) + a dedicated Codex-var acceptance grep.
- Practices: forbid Git LFS for bin/ (pointer files = broken consumer clone);
  concrete [profile.release] block; rust-toolchain.toml exact pin (makes the
  reproducible-rebuild criterion achievable); fmt/clippy/--locked gating;
  exec-bit 100755 + .gitattributes for committed binaries; bus.rs stdout
  purity as a normative MCP-stdio MUST; state never under the plugin root.
- Structure: ci.mjs checksum-verify now skips-with-notice until binaries land;
  split overloaded step 6 into 6 (tests+docs) / 7 (atomic flip) — 8 steps;
  enumerated all 8 SKILL.md path strings + residual grep; fixed step-3 dep,
  selftest ~L390 source imprecision; named the register seeding path.

knowledge-format-lint-and-citations:
- Lint acceptance was gameable (summed >=5) and silently omitted the
  "missing cross-references" check — now five per-check greps, each required.
- Step 2 over-declared dependency corrected; capability-tuning :24/:181
  anchors re-verified.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UyDDEDsq6yGeJKzNAwW3ZQ
@DocksDocks @claude
plan(knowledge-format-lint-and-citations): start — planned → ongoing
b5f8ce8 
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UyDDEDsq6yGeJKzNAwW3ZQ
@DocksDocks @claude
feat(skills): LLM-Wiki graph Lint in context-tree audit + OKF/Karpath…
4303561 
…y prior-art citations

Executes plan knowledge-format-lint-and-citations (4/4 steps):
- context-tree audit gains the cross-node graph Lint (contradictions between
  nodes, orphan nodes with no inbound link, concepts lacking a node, missing
  cross-references, web-fillable data gaps) — op row, workflow bullet, and a
  Graph Lint procedure table in references/conflict-resolution.md (+ Contents
  TOC, required once the file crossed 100 lines). Audit stays read-only.
- skill-maintenance Drift Detection gains the two per-skill checks:
  intra-skill contradiction and claim-superseded-by-newer-source.
- Prior-art citations: Google OKF (Apache-2.0, markdown+YAML frontmatter) and
  Karpathy's LLM-Wiki (Ingest-Query-Lint) in write-skill attribution +
  context-tree framing. Citation only — no vendoring, no schema adoption.
- metadata.updated bumped + content_hash backfilled on all three skills.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UyDDEDsq6yGeJKzNAwW3ZQ
@DocksDocks @claude
plan(knowledge-format-lint-and-citations): steps 4/4 done — ongoing →…
d9d297a 
… in_review

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UyDDEDsq6yGeJKzNAwW3ZQ
@DocksDocks @claude
plan(knowledge-format-lint-and-citations): completion review — passed
7faa53f 
Goal met: yes. All 5 acceptance criteria re-run green by fresh-context
plan-review; scope clean (work commit 4303561 touches only the three named
skills); descriptions untouched; nothing vendored; CI green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UyDDEDsq6yGeJKzNAwW3ZQ
@DocksDocks @claude
plan(okf-knowledge-bundle): parked stub — OKF knowledge bundles for c…
adfb579 
…onsumer projects

Preserves the OKF evaluation idea (knowledge/ bundles wired into context-tree,
NOT a skills/AGENTS.md retrofit — already decided against) with sources and
the untrusted-third-party note on okf-skills. Parked; rust port takes priority.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UyDDEDsq6yGeJKzNAwW3ZQ
@DocksDocks @claude
plan(session-relay-rust-port): start — planned → ongoing
c54b386 
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UyDDEDsq6yGeJKzNAwW3ZQ
@DocksDocks @claude
fix(ci): gate ALL plugin release tags — broaden tag glob docks--v* → …
755a91d 
…*--v*

session-relay tags (session-relay--v*) never triggered the validate workflow,
so release.mjs's tag-CI wait found no run and session-relay releases were
un-gated. One general glob replaces the plugin-specific one; trigger-model
doc updated in the same change. (rust-port plan, step 1/8)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UyDDEDsq6yGeJKzNAwW3ZQ
@DocksDocks @claude
ci(session-relay): binary-producer workflow + Rust provisioning in th…
5cdc688 
…e gate

build-binaries.yml: 2-runner matrix (macos-latest arm64 → both darwin arches;
ubuntu-latest → both musl arches, aarch64 via gcc-aarch64-linux-gnu),
--locked builds, per-runner checksum parts, workflow_dispatch ONLY (binaries
are committed pre-tag; the tag push is the gate and can only verify in-tree
content). No third-party toolchain action — both runner images preinstall
rustup (verified against runner-images readmes); the one new pin is
upload-artifact@043fb46d # v7.0.1.

ci.yml validate job gains a guarded Rust step (musl-tools + host musl target),
a no-op until rust-toolchain.toml lands. .github/AGENTS.md documents both.
(rust-port plan, step 2/8)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UyDDEDsq6yGeJKzNAwW3ZQ
@DocksDocks @claude
feat(session-relay): Rust crate scaffold + store.rs port with kernel …
20c2ee8 
…flock

Port of lib/store.mjs, every semantic preserved: field-preserving register
upsert + renamed-alias drop, atomic tmp+rename writes, sanitize/encodeDir
traversal defense, drain-under-lock, JS-spread override in enqueue, ISO-ms
timestamps (hand-rolled civil-date math — no chrono). The mkdir-mutex becomes
a kernel flock(2) on a .lock FILE (rustix, auto-released on crash; 3s
fail-fast contract kept) with a first-run migration that removes the v1
mkdir-mutex .lock DIRECTORY.

Deps stay lean per plan budget: tinyjson 2.5 + rustix 1.1 (fs only —
rustix::rand is Linux-only, so UUIDs come from /dev/urandom via std).
Toolchain pinned via rust-toolchain.toml (1.85.0 + rustfmt/clippy).

cargo test: 7/7 — incl. an 8-worker x 10-op cross-process race (80 untorn
unique mailbox lines, 88 registry entries = zero lost RMW) and the .lock
dir->file migration test. fmt --check clean; clippy -D warnings clean.
(rust-port plan, step 3/8)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UyDDEDsq6yGeJKzNAwW3ZQ
@DocksDocks @claude
feat(session-relay): port discover/cli/hook/bus to Rust — full behavi…
08c400e 
…or parity

Every tested invariant carried over:
- discover.rs: stat-then-content (READ_CAP=65536 bounded head-read), UUID
  gate, Claude cwd-from-content + Codex session_meta parsing, newest-first
  dedupe, cwd tie-break, root env resolution (RELAY_* overrides +
  CLAUDE_CONFIG_DIR/CODEX_HOME). Read-only.
- cli.rs: the doorbell with BOTH UUID gates (--id and resolved-name), `--`
  end-of-options fencing on parse AND spawn sides (claude -p --resume ... --
  <msg> / codex exec resume ... -- <msg>), refuse-if-dir-missing, --dry.
- hook.rs: <session-relay-mail> fence + defuse() — rewritten byte-wise
  eq_ignore_ascii_case after catching a to_lowercase() offset-misalignment
  panic risk on untrusted non-ASCII input (self-caught pre-compile).
- bus.rs: 6 tool schemas embedded as a verbatim JSON literal (wire-identical
  surface), JSON-RPC lifecycle w/ client protocolVersion echo, stdout purity
  (spec MUST — logs only via stderr), RELAY_PROJECT_DIR ${...}-unsubstituted
  fallback, hint strings now point at <plugin>/bin/relay wake.

New black-box bus_smoke test drives the real stdio lifecycle (initialize
echo, unanswered notification, 6 tools, whoami, -32602). cargo test 10/10;
fmt + clippy -D warnings clean; repo gate green. (rust-port plan, step 4/8)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UyDDEDsq6yGeJKzNAwW3ZQ
@DocksDocks @claude
feat(scripts): rust binary capability — ci.mjs host-leg gate + releas…
4495b29 
…e.mjs 4-target assert (rust-port plan, step 5/8)

session-relay descriptor gains rust: { dir, bin, binName, targets }.
ci.mjs gateRust: cargo fmt --check + clippy -D warnings + --locked musl
host-leg build into bin/, committed-SHA256SUMS verify before the
self-test (warn-skip until step 7 lands binaries; cargo-absent machines
warn-skip — tag-CI enforces). release.mjs refuses to tag unless all 4
target binaries + launcher are committed executable with verifying
checksums (proven: dry-run errs listing the 3 non-host legs + launcher).
Shared helpers in scripts/lib/rust-bin.mjs; Linux host maps to the
static musl leg (builds with rustup target add alone — no musl-gcc).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UyDDEDsq6yGeJKzNAwW3ZQ
@DocksDocks @claude
test(session-relay): black-box selftest against bin/relay + peek subc…
f1795c7 
…ommand + SKILL.md paths (rust-port plan, step 6/8)

selftest.mjs no longer imports store.mjs — every store touch goes
through the binary (flock is all-or-nothing): markers seeded by piping
synthesized SessionStart events into 'relay hook', names via 'relay
register', read-only assertions via new 'relay peek <who>'. 39 checks
pass; skip-with-notice when bin/ holds no binary (cargo-less machine
pre-step-7). 8x10 stress + lock liveness + fence-defuse matrix stay in
cargo tests. SKILL.md: every relay.mjs / mcp/bus.mjs mention flips to
<plugin>/bin/relay (incl. codex mcp add example; list awk field $3->$4
for the [tool] column); content_hash backfilled. Manifests still on
Node — consumer-facing flip is step 7.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UyDDEDsq6yGeJKzNAwW3ZQ
@DocksDocks @claude
plan(session-relay-rust-port): steps 1-6 done — blocked on merge-to-m…
9e7a732 
…ain for build-binaries dispatch

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UyDDEDsq6yGeJKzNAwW3ZQ
@DocksDocks DocksDocks merged commit 2ef6976 into main Jul 1, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@DocksDocks