PyCharter agent toolkit readiness: requirements and implementation design

Status: proposed for implementation; no requirements in this document are claimed as shipped. Date: 2026-09-27. Audience: PyCharter maintainers and the next implementation session.

Relationship to existing work: This is the productization phase after ai-agent-toolkit.md (AG-1 through AG-17). It preserves that proposal's shipped features and decisions. BACKLOG.md is the only tracker for open work; this document specifies behavior and release gates, not task status. Implementation should remove a backlog item when its PR lands. Read ARCHITECTURE.md, AGENTS.md, and agent-tools-policy.md before coding.

1. Product decision

PyCharter is Optophi's contract and context toolkit for agents. It gives an agent an approved, versioned description of structured data, checks the record the agent produces against the matching executable contract, and records which contract and context were served and checked. It works for any domain expressible through PyCharter contracts and concept schemes.

The primary adoption path is a developer adding a data boundary to an existing agent. The agent framework owns its model, prompt, and loop. PyCharter supplies the data definition, policy-scoped context, deterministic validation, correction feedback, and conformance evidence. The same contract remains usable at API, stream, and pipeline boundaries.

Product promise: “Give agents governed data context. Verify what they produce.” “Verified” means conformance to declared, executable rules. It does not mean that every statement in a record is factually true, that an agent used the context in its reasoning, or that a subsequent action is authorized.

1.1 Why this product shape

Structured model outputs already help models match JSON Schema. Atlan and dbt already serve governed data context through MCP. PyCharter's opportunity is the developer workflow that pairs approved field meaning with the executable contract evaluated where an agent's data enters or leaves a system. This is a product inference from those capabilities, and it matches PyCharter's current runtime enforcement strength.

1.2 Desired first user experience

1. An engineer imports or authors a contract, reviews any concept bindings, and publishes an immutable version.
2. A runtime agent asks PyCharter to prepare that contract. It receives the exact version, a model-usable schema, approved field meanings and usage guidance, a context fingerprint, and a server-issued preparation ID in hosted mode. Preparation reads no record values.
3. The agent proposes a JSON record. Its host calls verify with the pinned contract, fingerprint, and preparation ID. PyCharter returns an accepted/rejected verdict, structured field diagnostics, and concise safe repair feedback.
4. A valid verdict includes a durable verification receipt when a receipt store is configured. The host may pass the receipt identifier to its next system, such as PyActuator. An invalid result can be repaired within the caller's bounded loop or quarantined.
5. The team can inspect conformance by contract version, agent, and failure category without exposing raw records.

The first public demo must show both an invalid output being corrected and a valid output proceeding through an action boundary. A second contract from an unrelated domain must use the same engine and API without code changes.

2. Evidence and starting point

The next session must verify these paths against the branch it starts from; file locations and behavior can change.

Capability	Current evidence	Requirement implication
Runtime enforcement, YAML/Pydantic contracts, ODCS import/export	README.md	Reuse the executable contract and validator.
LLM schema, provider tool schemas, feedback, bounded repair	pycharter-for-ai-agents.md	Preserve current public behavior and adapters.
MCP tool catalog, policy, guarded contract writes	agent-tools-policy.md, src/pycharter/mcp/	Extend existing tools and policy registry; do not create another agent server.
Governed context packs with stable ID, content hash, versions and policy	src/pycharter/semantic/context/_pack.py	Build a prepared view from existing packs. The current hash excludes advisory observed_evidence; describe that accurately.
Local MCP transport	src/pycharter/mcp/__main__.py	Existing stdio remains supported; remote transport is new work.
MCP responses	src/pycharter/mcp/__main__.py	Current calls return JSON inside TextContent; add typed results and output schemas.
Agent conformance	src/pycharter/agent/conformance.py, observability.py	Prometheus counters and bounded DLQ summaries exist; durable per-verification history does not.
Known correctness and privacy defects	BACKLOG.md	Close relevant defects before claiming production readiness.

External compatibility references, checked 2026-09-27: the MCP tool specification defines outputSchema, structuredContent, and authorization-dependent tool lists; the MCP authorization specification defines protected-resource discovery and token audience validation for remote servers; ODCS 3.2 adds agent-facing context, semanticType, synonyms, and other fields. Implement against the SDK's actually supported protocol revisions and test negotiation rather than assuming every client speaks the newest revision.

3. Scope and boundaries

In scope

• A coherent prepare → verify → record experience over Python, MCP, CLI, and the existing HTTP/UI shells, with consistent semantics.
• Exact contract and concept version pinning across preparation and verification; explicit policy decisions and stale-context handling.
• Safe, machine-readable tool outputs and validation feedback.
• Durable, privacy-conscious verification receipts and conformance summaries.
• Authenticated remote MCP as an Optophi deployment surface.
• Interoperability with existing contracts, including reviewed ODCS 3.2 support.
• Documentation and examples that make an agent integration reproducible.

Out of scope

• An agent persona, model, prompt, reasoning loop, model provider dependency in the core, or a new kind: Agent or kind: Toolset artifact. The existing optional repair_loop remains a caller-invoked helper.
• Document ingestion, embeddings, vector search, or RAG; PyIntake owns that work and exchanges data through the documented integration seam.
• Executing external side effects. PyActuator owns operation policy, delivery, idempotency, and action audit. PyCharter verifies data passed to an action.
• Automatic promotion of imported semantics, generated constraints, or agent authored contract changes. Existing review and approval remain mandatory.
• Proving the factual truth of model output with schema checks alone.
• A new store backend, general workflow engine, or universal data catalog.

Architectural constraints

1. The validator and context projection remain deterministic and stateless. Transport, authentication, persistence, and telemetry stay in shells and stores. No per-record model call or semantic-store lookup on the validator hot path.
2. Contracts, rules, field bindings, and vocabulary remain configuration or versioned domain artifacts. Tool exposure remains the existing strict agent-tools.yaml configuration; there is no new artifact kind.
3. New persistent models expose the same behavior on supported SQLite, Postgres, and MongoDB implementations where the store abstraction declares parity. Do not hide a backend gap behind a successful API response.
4. New HTTP and UI routes compose public services; they contain no policy, validation, or version-resolution business logic.
5. Cross-package integration uses a named, documented wire seam. PyCharter must not import PyActuator or PyIntake internals.
6. New behavior is additive to shipped Validator, MCP tools, CLI, adapters, and approval semantics. Any unavoidable break needs an explicit migration plan and major-version review.

4. Terms and behavioral model

Term	Meaning
Contract ref	Namespace, name, and immutable version of one executable contract. A name-only request may resolve at preparation time; verification uses the resolved version.
Context pack	The existing governed semantic projection with context_pack_id and content_hash. Its hash does not cover advisory observed_evidence.
Prepared context	A read-only response combining one contract's model schema, permitted semantic context, policy status, exact refs, and fingerprints. It is a projection, not a new stored domain artifact.
Preparation event	A hosted metadata record that a particular authenticated host was served a particular prepared projection. It does not prove the model consumed it.
Verification	One deterministic evaluation of a candidate JSON record under an exact executable contract and an authenticated requester context.
Receipt	A durable, metadata-only record of a verification attempt and its verdict. It documents a check; it grants no permission to execute an action.
Enforced rule	A rule actually evaluated by the runtime validator.
Advisory context	Reviewed description or guidance supplied to the agent, with no claim of runtime enforcement unless mapped to an executable rule.

The following invariant must hold at every surface:

prepared.preparation_id == verified.preparation_id   # hosted mode
prepared.contract_version == verified.contract_version
prepared.context_fingerprint == verified.context_fingerprint
verified.verdict == accepted  =>  executable contract rules passed

The fingerprint must identify the governed context the verifier relies on, including the effective policy projection. The current pack's advisory observed_evidence is excluded from its hash; either give that evidence a separate fingerprint and explicit freshness semantics or omit it from the pinned prepared view. Never imply it is covered by the governed fingerprint. A change to pinned context between prepare and verify yields a named stale_context result; the caller prepares again. A revoked permission is a denial, even when the old fingerprint still matches an old snapshot.

5. Functional requirements

Requirement IDs in this document are stable references for PRs and tests. “Must” is a release gate. “Should” is expected before the hosted product is called complete, but may follow the first local integration slice.

R0. Correctness and safety baseline — must precede hosted release

R0.1 Close the existing ODCS round-trip defect, and reject or explicitly select an object when importing a multi-object foreign ODCS document. Never silently discard schema objects or rules.

R0.2 Fix SQLite semantic context/export lookups that receive UUID strings. The same context ref must resolve on SQLite and Postgres.

R0.3 Prevent binding edits from being lost across canvas and workbench views. The previewed field meaning must match the saved version.

R0.4 Reject unknown pipeline connector keys with an actionable diagnostic; correct shipped examples that rely on ignored keys. An agent-facing config validator must never approve a configuration whose setting has no effect.

R0.5 Correct quality-report identity and SLA comparison direction before quality scores are shown as agent-readiness or conformance evidence.

R0.6 Define and enforce restricted-profile suppression for small populations, including ranges and exact counts. Test every agent and API read path that can expose those profiles.

R0.7 Resolve the documented bare-Postgres-URL DLQ driver failure so the quarantine path works with the supported deployment configuration.

Existing reproductions and file references are in BACKLOG.md. Do these as focused defect PRs. Completion means the reproductions fail before the fix, pass after it, and relevant backend/transport parity checks pass.

R1. Prepare an exact, governed contract view

R1.1 Provide one compositional prepare_contract_context operation over the existing fetch_contract_schema and semantic context services. It must return: exact namespace/name/version; a canonical contract fingerprint; a model-usable JSON Schema; visible approved field definitions/bindings and provenance references; concept scheme version; effective policy status; context fingerprint; and any warnings about advisory or unavailable context. Use the existing contract/version and context-pack formats internally.

R1.2 A name-only request may resolve to a version for convenience. The response must echo that exact version, and downstream examples must verify against it. Define and test what “latest usable” means when the numerically latest version is deprecated or retired; do not silently select a deprecated version. Preserve legacy name-only tool behavior until a migration is documented.

R1.3 Every field in the prepared view must distinguish enforced constraints, reviewed advisory meaning, and unavailable/unreviewed meaning. The response must never label a descriptive ODCS constraint or an imported instruction as enforced unless a corresponding executable rule exists.

R1.4 Apply requester identity, namespace/workspace scope, field classification, approval state, and ai_usage_policy before serialization. An empty or invalid workspace must never return workspace-scoped semantic content; protected hosted preparation must refuse when contract scope cannot be established. Local contract-only preparation may explicitly return no semantic pack. A caller-supplied namespace or workspace string cannot broaden an authenticated caller's rights. Test schema, concept, profile, and provenance fields separately.

R1.5 Keep the result compact: accept a documented token budget or profile, prioritize required fields and executable constraints, report omissions, and never prune a required field into an invalid schema. Full and compact views must share the same contract identity and policy rules; fingerprint the actual governed projection supplied to the caller.

R1.6 Expose the same prepared projection through a Python service and the existing MCP catalog. HTTP may expose it through a thin route when the service is stable. The CLI must support a dry-run preview of exactly what a specified requester would see.

R1.7 Hosted preparation must mint an opaque preparation ID and durably record minimal metadata: authenticated principal/workspace, exact contract and context fingerprints, policy projection, and time. It stores no full schema, context pack, prompt, or record values. Local/offline preparation can return recorded: false. The ID names an event and is never a bearer permission. Its verification lifetime defaults to one hour and may be configured up to 24 hours; expired preparations require another prepare call.

R2. Verify a record under the prepared version

R2.1 Extend validate_record and the corresponding Python service to accept an exact contract ref, candidate record, context fingerprint, preparation ID in hosted mode, and optional caller correlation and attempt IDs. Verification must load the server-side preparation metadata, match its principal/workspace and fingerprints, and recheck current authorization. A caller-supplied fingerprint alone is never proof of preparation or permission. The authenticated principal comes from the transport, never from an untrusted argument. Preserve the existing return fields for older callers.

R2.2 The safe agent workflow must evaluate the exact prepared contract version and all executable rules. It must report whether the submitted record was accepted unchanged, accepted after declared coercion, or rejected. It must not report success for an unknown contract, stale context, missing permission, unsupported rule, or an unresolved version. Define error codes for each.

R2.3 Verification returns structured diagnostics with field paths, rule codes, and safe expected-value descriptions. agent_feedback remains concise and deterministic. Restricted/PII values, undeclared-field values, secrets, and internal exception text must not appear in model-facing feedback or logs.

R2.4 If the contract uses coercion, include the accepted normalized record or a reference to it only when the requester is allowed to see it. If the host cannot receive the normalized record and has no authorized reference-based handoff, this workflow must reject normalization. The host must know which bytes are being accepted. A verdict that validated a coerced record cannot silently authorize use of the original candidate.

R2.5 Existing bounded repair_loop and arepair_loop continue to work. Document and test max attempts, exhausted/quarantined outcomes, and validation under one pinned version. A repair attempt cannot change the governing contract or bypass a failed rule.

R2.6 The same verification service should also accept structured records returned to an agent by a tool. A declared direction (agent_output or tool_output) changes reporting only, never rule semantics. This allows the same published contract to govern both sides of an agent's data boundary.

R3. Durable verification receipts

R3.1 Define a versioned receipt DTO and storage interface. At minimum a receipt records: receipt ID, time, authenticated principal and workspace, preparation ID, caller correlation ID, contract ref and fingerprint, context fingerprint, verdict, normalization status, stable diagnostic codes/field paths, attempt number, and the validator build/version. It must distinguish “verification completed” from “result persisted.”

R3.2 Preparation and receipt storage contain no raw candidate, accepted record, prompt, full context pack, secret, or unrestricted error text. Avoid plain hashes of small sensitive values. For idempotency, store only a server-keyed request digest; it is internal and is not exposed as a payload hash. Document key rotation and replay behavior. Define retention, deletion, and export behavior as deployment settings with a 90-day default retention for hosted metadata. Shorter tenant policy may override it.

R3.3 Hosted require_receipt mode must fail closed when persistence is unavailable: no accepted response is returned without a persisted receipt. Local/offline validation may return recorded: false with an explicit reason. Receipts are idempotent within the authenticated principal and workspace for the same caller-supplied correlation/attempt key and identical verification request; conflicting reuse returns a conflict. A missing key creates a fresh receipt for each attempt.

R3.4 Receipt reads are policy-scoped and auditable. A receipt ID is an opaque identifier, never a bearer authorization to perform an action. A consumer can verify receipt status and contract identity through a documented read interface; it must still make its own authorization decision.

R3.5 Implement preparation and receipt store behavior consistently across declared backends. Test concurrent writes, retries, crash/restart recovery, retention cleanup, and migrations. If the architecture chooses an existing event store rather than a new table, document why it satisfies these semantics.

R4. Agent and coding-agent tool behavior

R4.1 Reuse the capability registry as the authoritative tool catalog and the current agent-tools.yaml allowlists. Add new read tools there and enforce tool visibility at both discovery and dispatch. Unknown policy keys remain startup errors.

R4.2 Publish stable outputSchema and structuredContent for the focused agent tools, beginning with prepare, validate, explain, proposal, and conformance. Keep serialized JSON text as a compatibility representation where the negotiated MCP revision calls for it. Tool errors carry a stable code, retryability, and safe message; private exception text stays server-side.

R4.3 Preserve the current guarded-write lifecycle. A coding agent may sketch, diff, lint, and propose a contract; a separate approved commit writes an immutable version. Proposal tokens, stale-base checks, role checks, and audit events stay enforced. Imported ODCS agent guidance and new concept bindings use the same review path before becoming approved context.

R4.4 Read tools must avoid unnecessary tool proliferation. One prepare operation should serve the common runtime path; existing granular tools remain for exploration and coding agents. Tool descriptions must state what is enforced and what is advisory.

R5. Authenticated remote MCP and policy parity

R5.1 Keep stdio MCP for local use. Add an independently deployable remote Streamable HTTP MCP shell using the same service layer and tool catalog. Do not share mutable requester state across requests or infer identity from a connection. Remote requests derive principal, role, workspace, and scopes from a validated token and apply policy at discovery and dispatch.

R5.2 Implement the applicable MCP authorization requirements for the supported protocol revision, including protected-resource metadata, intended audience validation, and correct 401/403 behavior. Reuse Optophi's identity provider where possible; do not add a second user database to PyCharter. Document service-to-service and user-delegated access separately.

R5.3 The authenticated scope may narrow tool access and data scope but cannot override contract privacy flags or guarded-write approval. Tool-list ordering is deterministic for a given identity and policy. A revoked token or changed role affects the next request; cached tool lists must expire or be invalidated appropriately.

R5.4 Enforce request size, response size, time, rate, and concurrency limits at the remote boundary. Validate HTTP origin/host and transport configuration according to the supported MCP revision. Log request IDs and safe operation names, never bearer tokens or payloads.

R5.5 Test at least one real MCP client against local stdio and remote HTTP, including protocol negotiation, structured results, read-only default, authorization failure, cross-workspace refusal, proposal/commit approval, and reconnection. Do not mark remote ready based solely on direct function tests.

R6. Interoperability and configuration-driven authoring

R6.1 Support ODCS 3.2 import and export through a reviewed mapping. Preserve known fields, report fields PyCharter cannot execute or represent, and avoid silent loss on round trip. In particular map or preserve context, semanticType, synonyms, enum descriptions, and authoritative definitions where applicable. Test multi-object imports and existing 3.0/3.1 fixtures.

R6.2 Imported context is source material, not automatically trusted instructions to an agent. Show provenance and import status, require review before publication, and distinguish executable rules from descriptive text. Present reviewed guidance as lower-trust task data, never as host/system instructions. Sanitize presentation, but do not rely on string filtering as a prompt injection defense; the approval and trust-tier boundaries are the defense.

R6.3 Keep YAML/Pydantic authoring as first-class paths. The smallest successful setup must work locally with no model and no hosted account. One existing contract can be prepared and verified without authoring a concept scheme; absent semantics are clearly reported. Concept bindings enrich the workflow after approval.

R6.4 Supply contract lints for agent readiness: ambiguous or missing field descriptions, unreviewed bindings, advisory-only constraints that appear enforceable, unsupported rules, exposed sensitive fields, and stale concepts. Lints are configuration diagnostics, not generated domain truth. Assign severity and allow a team to choose a publication gate in configuration.

R7. Conformance and operator experience

R7.1 Build durable conformance summaries from receipt events, grouped by contract/version, agent principal, outcome, field/rule category, and time window. The current bounded DLQ scan and Prometheus counters remain useful, but cannot be the sole source for historical acceptance rates. Do not store raw payloads to power charts.

R7.2 Show coverage and denominators: first-pass acceptance, repaired acceptance, rejection/quarantine, top failure categories, and receipt-write failure. A truncated or incomplete source must be labeled as such. Separate contract quality scores from agent-output conformance.

R7.3 Extend the existing Contracts → Agents UI with: a policy-aware prepared-context preview, a verify/repair example using the current Try it surface, a receipt detail view, and versioned conformance trends. Reuse the existing editor, typed hooks, components, and design tokens. A reviewer must see what an agent would receive before approving context changes.

R7.4 Operators need documented configuration for storage, retention, metrics, tracing, limits, remote authentication, and local-only mode. Health and readiness checks must distinguish a working validator from unavailable receipt storage or semantic context. Never silently degrade a required gate.

R8. Cross-package integration seam

R8.1 Define a small versioned verification-reference DTO for consumers: receipt ID, contract namespace/name/version, verdict, context fingerprint, and timestamp. It is passed as metadata or looked up through an authenticated read API. Do not pass raw records or import sibling package types into the PyCharter core. Extend the existing integration-dtos.linkml.yaml source and integration seam rather than creating a second cross-package schema authority.

R8.2 Document the Optophi composition pattern: PyIntake may propose candidate meanings through its existing integration DTOs; PyCharter reviews and serves approved meanings and verifies structured records; PyActuator decides whether and how to execute an action. Integration must preserve each package's policy and audit boundaries.

R8.3 Produce a small integration example with a mock action adapter. It must prove that invalid or stale verification cannot be treated as a valid input by the example host. PyActuator integration itself is a separate cross-repository change and should follow its public operation contract.

6. Proposed public shapes

These are target wire examples, not a claim about current API names. Final fields should be specified with Pydantic models, JSON Schema, and migration notes before implementation. They must be consistent across Python, MCP, and HTTP where exposed.

{
  "tool": "prepare_contract_context",
  "arguments": {"contract_ref": "orders@2.1.0", "namespace": "sales"},
  "result": {
    "preparation_id": "...",
    "contract": {"namespace": "sales", "name": "orders", "version": "2.1.0", "fingerprint": "sha256:..."},
    "schema": {"type": "object", "properties": {}},
    "context": {"context_pack_id": "...", "fingerprint": "sha256:...", "concept_version": "3.0.0", "fields": []},
    "policy": {"status": "approved", "projection": "viewer"},
    "warnings": []
  }
}

{
  "tool": "validate_record",
  "arguments": {
    "contract_ref": "orders@2.1.0",
    "namespace": "sales",
    "preparation_id": "...",
    "context_fingerprint": "sha256:...",
    "record": {"order_id": "abc"},
    "correlation_id": "run-123",
    "attempt_id": "1"
  },
  "result": {
    "is_valid": false,
    "verdict": "rejected",
    "contract": {"namespace": "sales", "name": "orders", "version": "2.1.0"},
    "diagnostics": [{"path": "order_id", "code": "invalid_format", "message": "Expected a UUID"}],
    "agent_feedback": "order_id must be a UUID",
    "receipt": {"id": "...", "recorded": true}
  }
}

Wire rules:

• contract_ref and context_fingerprint in the new safe path are exact; preparation IDs are bound server-side to identity and scope; correlation IDs are untrusted labels and cannot select an identity or workspace. Existing callers may omit these additions under documented legacy behavior.
• A missing/unavailable semantic pack is explicit. Pure contract validation can continue if policy permits; it must not imply semantic approval.
• is_valid is reserved for contract conformance. Auth, stale context, persistence, and transport errors have distinct codes and no valid verdict.
• Use stable codes and field paths for programs, safe natural language for models, and redacted internal logs for operators.
• A receipt may include recorded: false only in a mode explicitly configured to allow that outcome.

7. Security, privacy, and failure model

Situation	Required behavior
No identity or workspace on a protected deployment	Refuse protected content and verification; do not use a superuser fallback.
Requester asks for another namespace/workspace	Refuse or narrow to authenticated scope; do not trust the argument.
Unapproved/deprecated context	Apply existing role visibility; indicate omitted context without leaking its contents.
Sensitive field or low-cardinality profile	Apply classification and profile suppression before schema/context/feedback/receipt serialization.
Imported instructions or sample text contain prompt injection	Treat as untrusted source until reviewed; never promote through an import alone.
Candidate violates a rule	Return a rejected verdict and safe, precise feedback; never coerce silently.
Context changes after prepare	Return stale_context; require a new prepare step.
Preparation ID is absent, foreign, expired, or replayed across scope	Refuse the hosted verification; do not trust a client-supplied fingerprint alone.
Contract disappears or version is unsupported	Return a stable refusal, no successful verdict.
Receipt store unavailable in required mode	Fail closed and report a service error; do not issue an unrecorded accepted result.
Model exhausts repair attempts	Return rejected/quarantined state and preserve existing DLQ behavior.
Private exception in MCP or HTTP shell	Log server-side; return a generic, stable public error code.

The implementation threat review must cover token substitution, cross-tenant reads, tool-list/dispatch mismatch, output-schema confusion, prompt injection through imported metadata, low-cardinality disclosure, replayed verification requests, stale context, and receipt misuse as an action authorization token.

8. Architecture and implementation sequence

Layer placement

Layer	Target responsibility
Pure core	Contract/schema projection; deterministic context composition from supplied approved inputs; validator and safe diagnostic rendering; receipt DTO construction from a verdict.
Store	Immutable contract resolution and new receipt/event persistence with backend parity. No policy decisions in storage adapters.
Agent/MCP shell	Tool registration, exposure policy, structured result envelopes, local stdio and remote transport adapters.
HTTP shell	Authenticated thin API for prepared views, verification, receipts, and trends where needed.
Worker	Retention and summary jobs only if needed; restart-safe and idempotent.
UI	Preview, Try it, receipt and conformance views over HTTP; no duplicated domain logic.

PR-sized slices and dependencies

1. Baseline defect PRs: close R0 items that undermine context, validation, privacy, or quarantine. Each PR owns one defect or tightly related cluster.
2. Identity and exact refs: define canonical contract ref resolution, policy mapping, and deprecated-version behavior. Add cross-backend and cross-workspace tests. This unblocks every later API.
3. Prepared projection: implement R1 in the service layer and Python API; add the focused MCP tool and CLI preview. Prove context fingerprint and version consistency. Persist minimal preparation metadata in hosted mode.
4. Verification contract: extend the existing validation path with exact version, fingerprint, verdict states, safe diagnostics, and normalization semantics. Preserve existing callers. Add bounded-repair examples.
5. Receipts: extend the preparation event store with receipt semantics, migrations, idempotency, required/optional modes, and read API. Test all declared backends before using receipts as a hosted product claim.
6. MCP wire quality and remote transport: add output schemas and structured results, then authenticated Streamable HTTP with per-request policy. Test actual clients and protocol negotiation.
7. ODCS 3.2 and readiness lint: map/import/review agent context and preserve round trips. Keep import logic separate from publication.
8. Conformance and UI: aggregate receipt events, add scoped views and operator controls. Reuse the existing Agents UI.
9. Optophi integration example and release: document the bridge to PyActuator, publish two cross-domain examples, perform security and performance review, and update package/website claims only after gates below pass.

The new session should begin at slice 1 or 2, choose one coherent PR, and record any newly discovered work in BACKLOG.md. It should not implement all slices in one branch.

9. Acceptance and release gates

Per-slice definition of done

• Public behavior is specified in reference docs with migration notes.
• Unit tests prove valid, invalid, unauthorized, stale, and persistence-failure behavior relevant to that slice. Integration tests exercise supported stores/transports, including negative policy cases.
• New domain/config keys are strict Pydantic-validated YAML/JSON with example configs and a fail-fast unknown-key test.
• No new cross-layer import, hidden core I/O, model SDK in the core, or cross-package internal dependency.
• The repo's required checks pass (./scripts/ci.sh and applicable integration checks) before a PR; docs and examples build.
• The corresponding backlog entry is removed in the completing PR.

Agent-toolkit release gate

All of the following must pass before PyCharter or Optophi claims a production-ready hosted agent toolkit:

1. A new developer can run one local no-model example and one MCP example from published docs, then see an invalid output repaired and a valid one accepted under an exact version.
2. Two unrelated sample domains use the same prepare/verify API and policy configuration without Python engine changes.
3. Contract, concept, policy projection, and validator versions in the prepared view and receipt are inspectable and consistent. Stale or revoked context cannot produce an accepted hosted verdict.
4. Auth and privacy tests show no cross-workspace content or restricted raw values in schemas, context, errors, logs, receipts, or dashboards.
5. A required receipt survives restart and retry; storage outage prevents an accepted hosted result. Conformance totals agree with durable receipts, and missing/truncated data is labeled.
6. Stdio and remote MCP pass client integration tests for read, validate, denial, and approved write paths. Output schemas match real results.
7. ODCS 3.2 fixtures round-trip with explicit reports for unmapped fields; imported guidance cannot bypass review.
8. The R0 trust defects relevant to advertised workflows are closed, CI is green, and a short threat review and benchmark report are attached to the release PR. Benchmark the prepare and verify paths separately and compare validator performance with the pre-change baseline; investigate material regression before release.

Product measures after launch

Track onboarding time from an existing contract, share of agent calls using an exact version, first-pass and post-repair acceptance, rejected records stopped before downstream use, receipt availability, and the percentage of agent-visible fields with reviewed meaning. These are product measures, not claims that every accepted record is factually correct.

10. Decisions carried forward and decisions to make in the first PR

Carried forward: the shipped AG tool catalog and CLI, plain exposure policy, fail-closed two-phase contract writes, no Agent/Toolset artifact, caller-owned model/loop, and PyIntake separation are established decisions.

The first implementation PR must record these remaining technical decisions in an ADR or the relevant reference document before changing public behavior:

1. The canonical contract fingerprint and how it is computed across stored versions and imported formats.
2. The effective context fingerprint, including requester-specific policy projection and the current context pack's excluded advisory evidence.
3. The exact deprecated/retired version resolution rule and migration for legacy name-only callers.
4. Receipt storage location, idempotency key scope, retention default, and parity plan. Prefer an existing event facility if it genuinely meets R3.
5. The supported MCP protocol revision(s) and SDK behavior for structured output and remote authorization. Preserve stdio compatibility.

These are engineering choices bounded by the requirements above. They do not require inventing an agent platform inside PyCharter.