The structural fix for the generation-2 "72% of context window on
tool schemas" pathology Michael Kerduchi flagged. A JouleClaw tool
surface (MCP server, the out-of-process policy daemon, an HTTP
endpoint) now emits a Hydra Core Vocabulary
hydra:ApiDocumentation document a generic third-generation agent
client reads ONCE — and is then free to call every operation
without ever loading a tool-by-tool schema into its context window.
Composes directly on wave-22 #1: every operation's input / output
class IRI references the JouleClaw vocabulary at /vocab/v1#, so
the Hydra doc and the receipt stream share one term space. A
client that knows our vocabulary AND Hydra Core Vocabulary needs
zero JouleClaw-specific code beyond standard W3C semantics.
Surface:
- Hydra type vocabulary: ApiDocumentation, Class, Operation,
Status, SupportedProperty.
- ToolDescription — neutral input type any tool source can
populate (MCP, policy IPC, HTTP services).
- ApiDocumentationBuilder — fluent, deterministic emitter.
- to_pretty() helper for the JSON-LD wire form.
- mcp-adapter feature: From<&McpToolSchema> for ToolDescription
so an existing jouleclaw-graph-mcp server emits a Hydra doc
in one chained call.
Defaults a Hydra client expects:
- method = GET for read-only operations (mutating: false)
- method = POST for mutating operations (mutating: true)
- expects = owl:Nothing for parameterless operations
- returns = jc:ToolResponse from the JouleClaw vocabulary
- statusCodes = 200, 400, 500
- jc_tool_id and jc_mutating extension fields cross-link the
operation back to the receipt-stream vocabulary
Constraints upheld:
- #![forbid(unsafe_code)], no FFI, no model invocation.
- Deterministic: identical input → identical JSON-LD output.
- Picojoule cost.
17 tests + a worked example (gen_graph_mcp_api_doc) that emits
conformance/graph-mcp-api.jsonld from the live jouleclaw-graph-mcp
tool set. The committed sample doc lets a third party verify the
emitter byte-equal against the canonical output without running
Cargo.
SPEC.md §14 documents the contract a conforming JouleClaw tool
surface meets; prior §§14-16 (Does-not-say / Adjacent /
References) renumber to §§15-17.
Workspace: 105 crates (+1), 2,591 lib tests (+17), 0 failures.
Next wave-22 steps remain: #3 SHACL shapes for actions + tool
inputs (local validation, no model-side guessing), and #4 the
generic Rust + WASM Hydra client crate (agent-side counterpart;
demoable on /playground).
50b234f2d7