Update docs for current upstream drift by JimCollinson · Pull Request #2 · WithAutonomi/autonomi-developer-docs

JimCollinson · 2026-04-03T17:39:41Z

Summary

update docs affected by recent upstream drift in ant-client, ant-node, saorsa-core, and saorsa-transport
refresh verification blocks and add missing ant-node coverage on local-network-related pages
tighten payment, node embedding, native Rust, and transport/NAT wording to match current merged truth

Verification

re-audited current upstream SHAs for the affected repos
compile-checked the updated ant-node embed example against current ant-node main
compile-checked the updated native Rust external-payment example against current ant-core main
carried forward the previously validated SDK, CLI, and MCP smoke-test findings where unchanged by this pass

Notes

this PR is intentionally limited to the drifted surfaces identified in the latest audit
unchanged docs areas were repinned only where needed, without broad rewrites

Re-audit the latest ant-client, ant-node, saorsa-core, and saorsa-transport changes, update the affected docs, refresh verification blocks, and adjust the native Rust and node guidance to match current merged truth.

JimCollinson · 2026-04-03T17:40:49Z

@claude use WebFetch to verify whether this PR correctly updates docs affected by upstream drift in ant-client, ant-node, saorsa-core, and saorsa-transport. Focus on the changed pages in this PR only. Identify anything still stale, misleading, or missing. Do not make changes yet.

claude · 2026-04-03T17:41:01Z

PR Verification: Upstream Drift Check

Work in progress...

Tasks:

Read changed files in this PR
Fetch upstream ant-client sources
Fetch upstream ant-node sources
Fetch upstream saorsa-core sources
Fetch upstream saorsa-transport sources
Cross-reference key changed pages against upstream
Report findings

View job run

JimCollinson · 2026-04-03T17:48:46Z

@claude use WebFetch to verify only these changed pages in this PR: docs/core-concepts/payment-model.md, docs/how-to-guides/embed-a-node.md, docs/cli-reference/ant-core-library.md, docs/how-to-guides/use-external-signers.md, docs/architecture/system-overview.md, docs/glossary.md, docs/how-to-guides/setup-local-network.md. Check them against current upstream ant-client, ant-node, saorsa-core, and saorsa-transport, identify anything still stale, misleading, or missing, and keep the response concise. Do not make changes yet.

claude · 2026-04-03T17:49:00Z

Claude encountered an error —— View job

PR Verification: Upstream Drift Check

Work in progress...

Tasks:

Read changed files in this PR
Fetch upstream ant-client sources
Fetch upstream ant-node sources
Fetch upstream saorsa-core sources
Fetch upstream saorsa-transport sources
Cross-reference key changed pages against upstream
Report findings

JimCollinson · 2026-04-03T17:52:11Z

@claude use WebFetch to review only these pages in this PR: docs/core-concepts/payment-model.md, docs/how-to-guides/embed-a-node.md, docs/cli-reference/ant-core-library.md, docs/how-to-guides/use-external-signers.md, docs/how-to-guides/setup-local-network.md. Check them against current upstream ant-client and ant-node, identify anything still stale, misleading, or missing, and keep the response concise. Do not make changes yet.

claude · 2026-04-03T17:52:27Z

Claude encountered an error —— View job

PR Verification: Upstream Drift Check

Work in progress...

Tasks:

JimCollinson · 2026-04-03T17:52:28Z

@claude use WebFetch to review only these pages in this PR: docs/architecture/system-overview.md and docs/glossary.md. Check them against current upstream saorsa-core and saorsa-transport, identify anything still stale, misleading, or missing, and keep the response concise. Do not make changes yet.

claude · 2026-04-03T17:52:41Z

Claude encountered an error —— View job

PR Verification: saorsa-core and saorsa-transport drift check

Work in progress...

Tasks:

Read changed pages (system-overview.md, glossary.md)
Fetch upstream saorsa-core sources
Fetch upstream saorsa-transport sources
Cross-reference pages against upstream
Report findings

Tighten the repo writing rules to avoid time-relative, repo-first, and awkward route-language phrasing in rendered docs, then apply the same cleanup across the key onboarding, concept, reference, and glossary pages.

Refresh all ant-client verification blocks to the latest merged SHA after the recent bootstrap-peer and version bump commits, and keep the drift-pass branch aligned with the newest merged truth used in weekend verification.

Remove the last time-relative and scope-reporting phrases from the remaining concept and onboarding pages, and make the native Rust getting-started page more user-outcome-first.

Replace the last ordinary-prose uses of upstream-style provenance language, add an explicit CLAUDE.md rule for it, and include the lingering core concepts payment-summary fix on the drift pass branch.

Add a CLAUDE.md rule against narrating evidence in rendered prose and replace the remaining README/provenance-style statements in the docs with direct user-facing instructions and facts.

Replace the last README-narration sentence in the Java binding page with a direct statement about the SDK surface so it matches the updated documentation style rules.

JimCollinson · 2026-04-04T09:09:30Z

@claude use WebFetch to review only the changed files in this PR and identify any remaining stale technical claims, misleading wording, or missing verification coverage. Keep the response concise and prioritize only real issues. Do not make changes.

claude · 2026-04-04T09:09:44Z

Claude finished @JimCollinson's task in 8m 29s —— View job

PR Verification: Upstream Drift Check

Tasks:

Read changed files in this PR
Check repo-registry for upstream URLs
Fetch upstream ant-client sources
Fetch upstream ant-node sources
Fetch upstream saorsa-core/saorsa-transport sources
Cross-reference key changed pages against upstream
Report findings

Findings

Most technical claims in the changed pages are accurate against the current upstream SHAs. The following specific issues remain.

1. Relay claim overstated — `system-overview.md` and `glossary.md`

docs/architecture/system-overview.md (transport story bullet):

relay-assisted connectivity for difficult NAT cases, including symmetric NAT

docs/glossary.md (NAT traversal entry):

Observed-address discovery, hole punching, and relay-assisted connectivity used by the transport layer to keep peers reachable across NAT boundaries, including harder cases such as symmetric NAT.

The saorsa-transport README describes relay only in a NAT-type success-rate table footnote for CGNAT (50–70%): "Relay fallback may be needed." No relay server type, relay discovery protocol, or relay connectivity mechanism is documented. Symmetric NAT is handled via direct traversal at 60–80% success — relay is not tied to symmetric NAT in the source. The current wording implies relay is an active, implemented mechanism for symmetric NAT specifically, which the source does not support.

Suggested correction: drop "relay-assisted" from both locations, or constrain it to CGNAT with a qualifier like "relay fallback may apply for CGNAT cases". Fix this →

2. Missing ant-client verification block — `docs/how-to-guides/use-external-signers.md`

The page references data_prepare_upload, file_prepare_upload, prepare_merkle_batch_external, and finalize_merkle_batch from ant-core (step 5), but only carries an ant-sdk verification block. The ant-client commit 796d0df (same as used in payment-model.md and ant-core-library.md on this PR) covers those methods. A second verification block citing that commit would make coverage complete.

Everything else confirmed accurate

Claim	Status
All 13 `NodeConfig` fields in `embed-a-node.md`	✅ All present in ant-node `src/config.rs`
`NodeConfig::development()` and `NodeConfig::default()`	✅ Confirmed
`RunningNode::run()` and `subscribe_events()`	✅ Both confirmed on `RunningNode`
ant-node version `"0.10.0-rc.1"`	✅ Matches `Cargo.toml` at verified commit
`ant_core::data` module paths (Client, Wallet, PaymentMode, etc.)	✅ All confirmed
Merkle threshold 64 chunks (`DEFAULT_MERKLE_THRESHOLD`)	✅ Confirmed in `ant-core/src/data/client/merkle.rs`
ML-KEM-768 and ML-DSA-65 in QUIC transport	✅ Confirmed in saorsa-transport
ant-node wraps `saorsa-core::P2PNode`	✅ Confirmed
`ExternalPaymentInfo` enum variants `WaveBatch` / `Merkle`	✅ Confirmed as enum with those variants
Payment modes `Auto`, `Merkle`, `Single`	✅ Confirmed
`setup-local-network.md` ant-node verification block added	✅ Appropriate, ant-node commit present
`payment-model.md` Merkle threshold statement	✅ Accurate

Add the missing ant-client verification block to the external signers guide and soften the relay/NAT wording in the system overview and glossary so it matches the transport sources more precisely.

Update docs for client and node drift

4a42b0d

Re-audit the latest ant-client, ant-node, saorsa-core, and saorsa-transport changes, update the affected docs, refresh verification blocks, and adjust the native Rust and node guidance to match current merged truth.

JimCollinson added 6 commits April 3, 2026 21:01

Refine docs wording and style rules

2b1bc3e

Tighten the repo writing rules to avoid time-relative, repo-first, and awkward route-language phrasing in rendered docs, then apply the same cleanup across the key onboarding, concept, reference, and glossary pages.

Repin ant-client to latest merged commit

9e9753c

Refresh all ant-client verification blocks to the latest merged SHA after the recent bootstrap-peer and version bump commits, and keep the drift-pass branch aligned with the newest merged truth used in weekend verification.

Tighten final docs wording

ca5c262

Remove the last time-relative and scope-reporting phrases from the remaining concept and onboarding pages, and make the native Rust getting-started page more user-outcome-first.

Remove remaining provenance wording

fd2ebad

Replace the last ordinary-prose uses of upstream-style provenance language, add an explicit CLAUDE.md rule for it, and include the lingering core concepts payment-summary fix on the drift pass branch.

State docs facts directly

d6a48d4

Add a CLAUDE.md rule against narrating evidence in rendered prose and replace the remaining README/provenance-style statements in the docs with direct user-facing instructions and facts.

Clean up Java binding wording

bbd1635

Replace the last README-narration sentence in the Java binding page with a direct statement about the SDK surface so it matches the updated documentation style rules.

Fix final drift review findings

248bc8d

Add the missing ant-client verification block to the external signers guide and soften the relay/NAT wording in the system overview and glossary so it matches the transport sources more precisely.

JimCollinson merged commit 0625606 into main Apr 4, 2026
1 check passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update docs for current upstream drift#2

Update docs for current upstream drift#2
JimCollinson merged 8 commits intomainfrom
update/drift-pass-2026-04-03

JimCollinson commented Apr 3, 2026 •

edited

Loading

Uh oh!

JimCollinson commented Apr 3, 2026

Uh oh!

claude bot commented Apr 3, 2026 •

edited

Loading

Uh oh!

JimCollinson commented Apr 3, 2026

Uh oh!

claude bot commented Apr 3, 2026 •

edited

Loading

Uh oh!

JimCollinson commented Apr 3, 2026

Uh oh!

claude bot commented Apr 3, 2026 •

edited

Loading

Uh oh!

JimCollinson commented Apr 3, 2026

Uh oh!

claude bot commented Apr 3, 2026 •

edited

Loading

Uh oh!

JimCollinson commented Apr 4, 2026

Uh oh!

claude bot commented Apr 4, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

JimCollinson commented Apr 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Verification

Notes

Uh oh!

JimCollinson commented Apr 3, 2026

Uh oh!

claude bot commented Apr 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Verification: Upstream Drift Check

Uh oh!

JimCollinson commented Apr 3, 2026

Uh oh!

claude bot commented Apr 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Verification: Upstream Drift Check

Uh oh!

JimCollinson commented Apr 3, 2026

Uh oh!

claude bot commented Apr 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Verification: Upstream Drift Check

Uh oh!

JimCollinson commented Apr 3, 2026

Uh oh!

claude bot commented Apr 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Verification: saorsa-core and saorsa-transport drift check

Uh oh!

JimCollinson commented Apr 4, 2026

Uh oh!

claude bot commented Apr 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Verification: Upstream Drift Check

Findings

1. Relay claim overstated — system-overview.md and glossary.md

2. Missing ant-client verification block — docs/how-to-guides/use-external-signers.md

Everything else confirmed accurate

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

JimCollinson commented Apr 3, 2026 •

edited

Loading

claude bot commented Apr 3, 2026 •

edited

Loading

claude bot commented Apr 3, 2026 •

edited

Loading

claude bot commented Apr 3, 2026 •

edited

Loading

claude bot commented Apr 3, 2026 •

edited

Loading

claude bot commented Apr 4, 2026 •

edited

Loading

1. Relay claim overstated — `system-overview.md` and `glossary.md`

2. Missing ant-client verification block — `docs/how-to-guides/use-external-signers.md`