Agent toolkit readiness: technical decisions

Status: implementation decisions, including the maintainer-approved checkpoint recommendations 1–7. Updated: 2026-10-10. These decisions implement the constraints in agent toolkit readiness requirements while preserving existing offline tools and programmatic host injection.

ODCS import safety (R0.1)

An ODCS library metric imports as the matching PyCharter rule name; the runtime still applies its normal executable-rule validation. rowCount maps to the supported row_count aggregate. The other ODCS 3.1 library metrics retain their names but require an executor before they can become loadable quality rules. An export always carries a PyCharter marker, even when all identity fields live in metadata, so an authored contract does not gain foreign-document header fields on re-import. Because one PyCharter contract has one JSON Schema object, importing an ODCS document with several schema objects fails with an actionable error rather than choosing the first object silently.

An imported ODCS 3.2 contract adds these optional metadata fields:

Field	Meaning
odcs_passthrough	Original foreign sections and schema, including apiVersion, retained as source data.
odcs_import_review	required for unreviewed imports; legacy contract_reviewed grants no guidance access; guidance_reviewed identifies a reviewed version bundle.
odcs_import_review_by	Verified reviewer principal, distinct from the proposer.
odcs_import_review_at	Approval time as an ISO 8601 timestamp.
odcs_guidance_review	Validated proposal_id, event_id, bundle_fingerprint, and proposer referencing independent review evidence.

The maintainer approved one bundle per exact (namespace, name, version) on 2026-10-10. Approval covers the retained ODCS context, authoritative definitions, source schema guidance, and imported contract/schema descriptions. Its canonical SHA-256 fingerprint binds that bundle and identity. A changed bundle or version requires new review. Proposal staging discards every candidate-supplied review claim. The authenticated HTTP reviewer route supplies the existing verified JWT workspace scope; local CLI --as labels and anonymous development access cannot approve imported guidance. Imported bundles always require a distinct reviewer, regardless of the native-contract segregation setting.

Direct store and API publication remain available without this review gate. Agent-facing model/tool schemas continue withholding imported descriptions. Authenticated full preparation can expose a reviewed bundle only as import_guidance with trust: imported_reviewed_advisory, after checking the independent durable approval event and exact identity/content fingerprint. Metadata claims alone grant no access. The bundle is source data, never host/system instructions or executable rules; it does not confer approved semantic bindings. Offline preparation, compact/budgeted views, missing evidence, and bundles containing any private field withhold it. The effective context fingerprint includes guidance only when it is visible.

These metadata fields are additive. This is an approved review-policy semantics change: earlier contract_reviewed versions remain withheld and must be proposed as a new version for authenticated bundle review; no legacy approval is silently upgraded.

Contract identity and fingerprint

An agent preparation resolves one (namespace, name, version) before it projects a schema. The canonical fingerprint is sha256: plus SHA-256 of UTF-8 JSON with sorted keys, compact separators, ensure_ascii=False, and non-finite numbers rejected. The hashed object is {"namespace": ..., "name": ..., "version": ..., "document": ...}, where document is the normalized full contract returned by the store for that exact identity. The global namespace is represented by JSON null. Store row IDs, lifecycle status, authors, and timestamps are excluded. ODCS input is first imported into the same normalized contract shape; raw source formatting cannot change the fingerprint. A change to executable contract content must change the fingerprint. The prepare slice will add canonical test vectors and cross-backend equality tests before exposing this value.

Effective context fingerprint

The prepared view omits observed_evidence: the existing context pack hash explicitly excludes this changing advisory data. The effective fingerprint uses the same canonical JSON and sha256: convention over the contract fingerprint, exact concept scheme version, the visible approved context projection, policy role/workspace and classification decisions, and an explicit list of omitted fields. It is computed after all policy filtering and any token-budget reduction. The existing pack content_hash is an input or provenance reference, never a substitute for this effective fingerprint: the response filter can remove content while leaving the pack hash intact. Verification rebuilds the effective projection under current permission and rejects a mismatch as stale_context. Revoked permission is a denial.

Version resolution and legacy callers

The new preparation path selects the highest semantic version whose stored status is active within the authenticated namespace. If no active version exists, it refuses preparation. An explicit deprecated or retired version is refused for agent preparation and verification, even if a reviewer can still inspect it elsewhere. Unknown lifecycle states are ineligible. Verification never resolves latest: it uses the prepared exact version. Existing name-only Validator and MCP validate_record calls keep their current latest_version behavior during migration; callers move by preparing once and passing the returned exact identity to verification. No existing default or signature changes in this defect slice.

Preparation and receipt storage

The review-event log is unsuitable as a verification ledger: it is keyed to suggestions, allows free-text comments, and lacks the principal/workspace, idempotency, expiration, and retention constraints needed for receipts. Use a dedicated metadata-only preparation and receipt store, implemented with equivalent operations on SQLite, Postgres, and MongoDB. Hosted metadata retention defaults to 90 days, with a shorter tenant setting permitted. Preparation IDs are opaque, scoped to principal and workspace, and valid for one hour by default, at most 24 hours. Receipt idempotency is scoped to principal, workspace, correlation ID, and attempt ID; the stored request digest is server-keyed and remains internal. Reusing that key with an identical verification request returns the original receipt; conflicting reuse fails. During key rotation, retain old verification keys until the replay window closes; a missing old key makes replay unverifiable and must fail closed. The dedicated SQL ledger has managed migrations; all three backends cover retries, concurrency, and restart recovery. Authenticated tenant deletion/export remains follow-up work.

The approved host settings are PYCHARTER_AGENT_VERIFICATION_URL, PYCHARTER_AGENT_RECEIPT_KEYS (a JSON key-ID to base64 HMAC key map), and PYCHARTER_AGENT_RECEIPT_ACTIVE_KEY. They are required by hosted receipt providers and the remote MCP command, with no auth-secret, contract-database, or in-memory fallback. Optional PYCHARTER_AGENT_RECEIPT_RETENTION_DAYS narrows the default to 1–90 days. Receipt reads commit metadata-only events in the same store before querying. pycharter agent receipts sweep cleans up preparations, receipts, and read events; the operator schedules it. See verification store provisioning.

Binding approval persistence

The API lifecycle always uses SQL mapping projections, independent of PYCHARTER_MAPPING_PROJECTION_BACKEND; the standalone factory retains its memory default. This approved API default change makes editor approvals visible to agents reading the SQL projection. Projection-backed lineage also reads SQL regardless of that backend setting; its separate feature flag continues to select projection or JSON-scan reads.

Forks inherit current approval and source event provenance only for identical normalized bindings, including roles, tags, privacy, and annotations. Bakes inherit the exact approved primary overlay while preserving privacy flags. Changed or withdrawn bindings require review. Ambiguous namespace identities continue withholding approval; namespace-qualified mapping identity remains separate work. No existing contract or projection is silently rewritten.

MCP compatibility

The shipped server uses stdio and supports the installed MCP 1.x decorator API plus an MCP 2.x handler adapter. The current tested local SDK is MCP 1.23.3, whose latest protocol revision is 2025-11-25; its Tool and CallToolResult types expose outputSchema and structuredContent. Keep stdio compatibility and serialized JSON text for clients that negotiate the existing representation. The first typed-result slice targets protocol 2025-11-25 with real-client negotiation tests. A newer revision, including 2026-07-28, becomes supported only after the installed SDK and both stdio and remote client tests demonstrate it. Remote MCP will use per-request token identity and protocol-appropriate authorization; the stdio startup binding remains local-only.