docs: document resource snapshot workflow
This commit is contained in:
+21
-5
@@ -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,
|
||||
|
||||
@@ -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"
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user