Skip to content

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.payload
  • security.payload
  • etf.payload
  • market.payload
  • option.payload
  • filing.payload
  • macro.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:

python scripts/generate_interfaces.py
python scripts/generate_interfaces.py --check

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.