Skip to content

Version 1.1.8 ยท Last updated

Typed envelope and domain payloads

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.

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 CLI bindings, MCP bindings, REST models, shared JSON Schemas, the Skill contract, and the generated interface document. CI runs --check, so a Registry change without regenerated artifacts fails the build.

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.