Typed envelope and domain payloads¶
The separate personal result foundation describes the six-kind contract design. It does not activate personal tools or change the legacy responses described below.
P1 introduces canonical-envelope-v1, the normalized closed response contract
kernel for CLI + Skill, MCP, and REST. The implementation is in
argus.contracts.envelope; every model uses Pydantic extra="forbid" and
timezone-aware timestamps.
This is the normalized contract kernel used by generated validation and golden
fixtures. Current business invocations return CliToolEnvelope; discovery
returns AgentToolRegistrySnapshot. Do not decode a live invocation using kernel
field names. Use live OpenAPI/MCP schemas and the Registry's
output_format.schema_name plus binding mappings for the transport contract.
Consumer tools on the OAuth MCP endpoint (/mcp) return
consumer-result-v1 instead.
Envelope fields¶
Every kernel response carries schema_name, schema_version, request_id, audit_id,
as_of, effective_as_of, observed_at, and known_at. A successful response
contains exactly one typed payload; a failed response contains exactly one
error. Evidence, quality, license, and restrictions remain structured arrays.
Pagination and dataset manifests are mutually exclusive.
Errors contain only a stable code, a structured field_path, retryable, and
a details object. They do not contain generated explanations.
Domain payload catalog¶
The first contract kernel defines closed payload families under
argus.contracts.domains:
entity.payloadsecurity.payloadetf.payloadmarket.payloadoption.payloadfiling.payloadmacro.payload
Each payload and nested record rejects unknown fields. Adding an undeclared string field therefore fails validation and the P1 CI contract test.
P3 expands security.payload, etf.payload, and market.payload and adds
option.payload. ETF holdings require effective_date, published_at, and
known_at; adjustment factors require action IDs and a versioned policy; option
greeks require provider/model/input/version metadata. Option schemas contain no
strategy or transaction fields.
Registry-first generation¶
argus.core.tool_registry is the only source for tool input/output versions,
payload family, capability, time semantics, provider coverage, replacement, and
the three transport bindings. Run:
The generator writes checked-in MCP bindings, REST models, the Skill contract,
and the generated interface document. CI runs --check, so a Registry change
without regenerated artifacts fails the build. The CLI binding table is built
in memory by the same code (cli_bindings()) and is not checked in. The shared
JSON Schemas are published in release/schema-catalog.v1.json by
scripts/generate_release_artifacts.py.
The golden fixture at tests/golden/p1_contract.json proves that all three
generated adapters canonicalize successful and coded-error responses to the same
bytes. A live three-interface test separately verifies the existing governed
execution path preserves facts, evidence, effective time, known time, license,
restrictions, and audit linkage.