docs: document resource snapshot workflow

This commit is contained in:
morluto
2026-07-29 17:37:00 +00:00
parent ba098f24e5
commit 2a45d8de7d
9 changed files with 38 additions and 19 deletions
+21 -5
View File
@@ -60,8 +60,10 @@ shutdown rules still apply; REA never kills a process it cannot prove it owns.
## Evidence resources
Evidence remains inline for compatibility and successful Evidence-producing
tools also return `resource_link` content. Session resources are connection-local:
Evidence-producing tools return compact summaries plus `resource_link` content.
Every link is accompanied by an ordinary instruction to copy its opaque URI
unchanged and call MCP `resources/read` (Codex: `read_mcp_resource`). Session
resources are connection-local:
- `rea://evidence/{evidenceId}` returns the complete immutable Evidence v2 record.
- `rea://evidence/{evidenceId}/section/{section}` returns a bounded result section.
@@ -69,9 +71,10 @@ tools also return `resource_link` content. Session resources are connection-loca
`protocol`, `nodes`, `occurrences`, and `edges` when present.
- `rea://unknown/{unknownId}` returns the current residual-unknown head and its
immutable revision history.
- `rea://unknowns/active` returns current unresolved heads.
- `rea://snapshot/{snapshotDigest}` returns the current immutable analysis
snapshot when its canonical content digest matches.
- `rea://evidence-bundle/{bundleDigest}` returns immutable canonical bytes
retained by `snapshot_evidence_bundle`.
- `rea://snapshot/current` returns the mutable native analysis cache as an
`available` or `unavailable` state.
- `rea://artifact/{manifestId}/{collection}` returns a canonical artifact
`nodes`, `occurrences`, or `edges` page with Evidence provenance.
- `rea://function/{targetSha256}/{address}` returns a retained function dossier
@@ -84,11 +87,24 @@ workspace `resource_link` blocks. Workspace resources preserve revision and
`previous_revision_digest` commitments; persistent workspace files remain
subject to configured read/write roots.
`export_evidence_bundle` is file-only and requires `path`; existing files
require `overwrite: true`. Use `snapshot_evidence_bundle` and then
`resources/read` when the complete bundle is needed within the current session.
An Evidence URI is discoverability, not authorization. It cannot authorize file
access, extraction, mounting, execution, or networking. IDs disappear when the
session ends unless the existing Evidence bundle or workspace persistence flow
explicitly retains them.
## Aggregate native context
`get_navigation_context` combines the selected document, current address, and
current/containing procedure. A cursor outside a procedure is represented as
`procedure: null`. `inspect_address_context` requires an explicit address and
returns bounded name, procedure, comment, inline-comment, and bookmark facets;
unsupported facets are local `unavailable` outcomes. The scalar getters remain
available while the aggregate contracts are evaluated.
## Permission policy
All local side effects use one scope vocabulary: capability, canonical roots,
+9 -6
View File
@@ -11,7 +11,7 @@
"skill_version": "23"
},
"tools": {
"total": 111,
"total": 114,
"families": [
{
"id": "direct",
@@ -167,7 +167,7 @@
{
"id": "session",
"surface": "session",
"count": 19,
"count": 22,
"tools": [
"binary_session",
"build_call_path",
@@ -180,11 +180,14 @@
"correlate_static_and_runtime",
"export_evidence_bundle",
"find_changed_behavior",
"get_navigation_context",
"import_evidence_bundle",
"inspect_address_context",
"list_unknowns",
"open_binary",
"record_unknown",
"run_replay_machine",
"snapshot_evidence_bundle",
"update_unknown",
"verify_reconstruction",
"verify_unknown_resolution"
@@ -662,16 +665,16 @@
"runtime_catalog": {
"counts": {
"cli_commands": 67,
"mcp_tools": 111,
"mcp_tools": 114,
"mcp_prompts": 6,
"mcp_resources": 2,
"mcp_resource_templates": 11
},
"digests": {
"tools_sha256": "092dd59990f61b1011ac0cd4f5b8d6a3e4a2cf7ade49c86892963c87b71dc65b",
"tools_sha256": "ea2b9be5eb6230a65e25e6b52a9df9b60812aeb43dd08612ac96458cfb5a7f9a",
"prompts_sha256": "2dd61fd4e29657e7faf739ef67be7b1f637ddf446e7d73acc0d2fd1d9f06b43e",
"resources_sha256": "339a984ea8cd8be5f234adf24395bf0295258d990492005cf6fe1f293d12cd46",
"combined_sha256": "461b4dbea03ef60d637f4b74debca4dbea0e1dd423d7d9c9a631e62204528c05",
"resources_sha256": "e0e872276ebf6f88e916ef24930a99eed27ce4c93e494e60820e9bd8cc8497c3",
"combined_sha256": "2c55a0742cca841ba58200cf87d851fdaeae24cfaadcd356d3642c67fd70a2a2",
"providers_sha256": "918ccd6b8ae442cd5844dcfde55086f458176241c8d166c1e9dd0f242ccd2bb0"
}
}