ai-capability-framework 1.0.0-rc.3 → 1.0.0

package/docs/action-lifecycle.md

@@ -1,23 +1,22 @@
 # Action Lifecycle
 
-AICF runtime separates model-facing tool use from host-controlled side effects.
-Models may receive read and prepare capabilities. Commit stays behind
-application code.
+AICF runtime separates model-facing tool use from host-controlled side effects. Models
+may receive read and prepare capabilities. Commit stays behind application code.
 
 ## Flow
 
 The runtime lifecycle is:
 
 ```text
-route -> read or prepare -> approval pending -> approved or rejected -> commit -> audit
+route -> read or prepare -> approval pending -> approved or rejected -> commit -> optional verify -> audit
 ```
 
-`AicfToolExecutor` accepts only `read` and `prepare` execution requests. A
-malformed model tool call that attempts `commit` is denied safely.
+`AicfToolExecutor` accepts only `read` and `prepare` execution requests. A malformed
+model tool call that attempts `commit` is denied safely.
 
-`AicfActionLifecycleManager` is the commit entrypoint. It commits only from a
-stored prepared action plus a matching approval when required and an idempotency
-key when required by the capability manifest.
+`AicfActionLifecycleManager` is the commit entrypoint. It commits only from a stored
+prepared action plus a matching approval when required and an idempotency key when
+required by the capability manifest.
 
 ## Prepare
 
@@ -29,18 +28,17 @@ Prepare validates:
 - registered prepare handler;
 - output schema for the prepared-action preview.
 
-Successful prepare stores an `AicfPreparedAction`. Prepare capabilities that
-can later be committed should declare `lifecycle.commit_capability_id`, and the
-prepared action records that linked commit capability. If policy requires
-approval, the returned model-safe envelope includes
-`status: "approval_required"` and a prepared-action reference.
+Successful prepare stores an `AicfPreparedAction`. Prepare capabilities that can later
+be committed should declare `lifecycle.commit_capability_id`, and the prepared action
+records that linked commit capability. If policy requires approval, the returned
+model-safe envelope includes `status: "approval_required"` and a prepared-action
+reference.
 
 ## Approval
 
-`recordApproval()` records an approval decision for a prepared action and updates
-the prepared-action state. It does not build approval UI, verify approvers, or
-own identity. Host applications must perform those checks before recording the
-decision.
+`recordApproval()` records an approval decision for a prepared action and updates the
+prepared-action state. It does not build approval UI, verify approvers, or own identity.
+Host applications must perform those checks before recording the decision.
 
 ## Commit
 
@@ -48,28 +46,36 @@ Commit validates:
 
 - stored prepared action exists and is not expired, rejected, or cancelled;
 - requested commit capability matches the prepared action's declared
-  `commitCapabilityId`, or the prepared action capability itself supports
-  commit;
+  `commitCapabilityId`, or the prepared action capability itself supports commit;
 - commit capability exists and supports `lifecycle.commit`;
 - commit handler exists;
 - approval exists, is approved, matches the prepared action, and is not expired;
 - idempotency is present when required;
 - policy allows commit for the runtime context.
 
-Commit uses the stored prepared action and approval. It does not accept
-model-provided raw business arguments. Duplicate idempotency keys return the
-safe existing result rather than invoking the handler again.
+Commit uses the stored prepared action and approval. It does not accept model-provided
+raw business arguments. Duplicate idempotency keys return the safe existing result
+rather than invoking the handler again.
 
-Failed commit handlers, thrown commit handlers, and invalid commit output move
-the prepared action to `failed`. Terminal actions such as committed, verified,
-failed, expired, cancelled, and rejected cannot be moved back to approved.
+Failed commit handlers, thrown commit handlers, and invalid commit output move the
+prepared action to `failed`. Terminal actions such as committed, failed, expired,
+cancelled, and rejected cannot be moved back to approved.
 
 ## Verify
 
-`verify()` checks a committed action through the committed capability's optional
-verify handler. It returns model-safe `verified`, `failed`, `unavailable`, or
-`denied` envelopes and never exposes thrown handler error details directly.
+`verify()` checks a stored committed action through the committed capability's optional
+verify handler. It requires the committed-action reference to match the stored prepared
+action, tenant, account, subject, and committed capability.
 
-In-memory stores are examples and test utilities. Production applications should
-use durable stores, such as the optional AWS reference stores or host-owned
-storage.
+Verification does not rewrite committed side-effect history. A successful verification
+keeps the prepared action state as `committed` and records
+`verification.status: "verified"`. A verification failure also keeps state as
+`committed` and records `verification.status: "verification_failed"`. Runtime envelopes
+mirror this split with `action.state: "committed"` plus `action.verificationStatus`.
+
+If an action is already verified, `verify()` returns the stored verification result
+without calling the handler again. Thrown handler errors are redacted in the envelope,
+audit event, and optional audit ledger.
+
+In-memory stores are examples and test utilities. Production applications should use
+durable stores, such as the optional AWS reference stores or host-owned storage.

package/docs/adapter-roadmap.md

@@ -22,29 +22,29 @@ Every adapter should expose the same high-level contract:
 - `bindings`, `excluded`, and `diagnostics`;
 - selection gated by `decideCapability(..., operation: "select")`;
 - restricted side-effect tools excluded by default;
-- schema normalization that fails closed when the target cannot represent an
-  AICF input schema safely.
+- schema normalization that fails closed when the target cannot represent an AICF input
+  schema safely.
 
 ## Priority Order
 
-| Priority | Adapter | Why It Comes Here | Primary Output |
-| --- | --- | --- | --- |
-| Priority | Adapter | Status | Primary Output |
-| --- | --- | --- | --- |
-| P1 | Anthropic Claude Messages tools | Implemented | Claude client tool definitions plus parser for `tool_use` blocks. |
-| P2 | Google Gemini function calling | Implemented | Gemini `functionDeclarations` plus parser for `functionCall` objects. |
-| P3 | Vercel AI SDK tools | Implemented | AI SDK tool map with `inputSchema`, `description`, `strict`, and no `execute`. |
-| P4 | Model Context Protocol tool descriptors | Implemented | MCP `Tool` descriptors and parser for `tools/call` requests. |
-| P5 | LangChain/LangGraph tools | Implemented | Structured tool parameter specs and bindings for host-supplied functions. |
-| P6 | Semantic Kernel functions | Implemented | Function/plugin metadata and parser guidance for manual invocation flows. |
+| Priority | Adapter                                 | Why It Comes Here | Primary Output                                                                 |
+| -------- | --------------------------------------- | ----------------- | ------------------------------------------------------------------------------ |
+| Priority | Adapter                                 | Status            | Primary Output                                                                 |
+| ---      | ---                                     | ---               | ---                                                                            |
+| P1       | Anthropic Claude Messages tools         | Implemented       | Claude client tool definitions plus parser for `tool_use` blocks.              |
+| P2       | Google Gemini function calling          | Implemented       | Gemini `functionDeclarations` plus parser for `functionCall` objects.          |
+| P3       | Vercel AI SDK tools                     | Implemented       | AI SDK tool map with `inputSchema`, `description`, `strict`, and no `execute`. |
+| P4       | Model Context Protocol tool descriptors | Implemented       | MCP `Tool` descriptors and parser for `tools/call` requests.                   |
+| P5       | LangChain/LangGraph tools               | Implemented       | Structured tool parameter specs and bindings for host-supplied functions.      |
+| P6       | Semantic Kernel functions               | Implemented       | Function/plugin metadata and parser guidance for manual invocation flows.      |
 
 ## P1: Anthropic Claude Messages Tools
 
 Target a no-model-call adapter that exports Claude client tool definitions:
 
 - `name`: sanitized AICF capability ID, capped at the provider limit.
-- `description`: composed from `model_description`, use guidance, risk,
-  autonomy, lifecycle, and side-effect metadata.
+- `description`: composed from `model_description`, use guidance, risk, autonomy,
+  lifecycle, and side-effect metadata.
 - `input_schema`: normalized AICF `input_schema`.
 - `strict: true` when the schema can be represented safely.
 - optional `input_examples` only when public examples are available and validated.
@@ -54,12 +54,10 @@ Parser target:
 - map Claude `tool_use.name` to capability ID;
 - read `tool_use.id` as call ID;
 - validate `tool_use.input` against the original AICF input schema;
-- return structured diagnostics for unknown names, malformed input, and schema
-  failures.
+- return structured diagnostics for unknown names, malformed input, and schema failures.
 
-Reference basis: Claude client tools include `name`, `description`, and
-`input_schema`, can use `strict: true`, and return `tool_use` blocks that the
-host application executes.
+Reference basis: Claude client tools include `name`, `description`, and `input_schema`,
+can use `strict: true`, and return `tool_use` blocks that the host application executes.
 
 ## P2: Google Gemini Function Calling
 
@@ -67,8 +65,8 @@ Target a no-model-call adapter that exports Gemini function declarations:
 
 - `name`: sanitized capability ID using underscores or camelCase-safe names.
 - `description`: composed from AICF model-facing and governance metadata.
-- `parameters`: AICF input schema converted to Gemini's OpenAPI-compatible
-  schema subset.
+- `parameters`: AICF input schema converted to Gemini's OpenAPI-compatible schema
+  subset.
 
 Parser target:
 
@@ -78,13 +76,13 @@ Parser target:
 - report schema keywords that cannot be represented safely in Gemini parameters.
 
 The hard part is schema normalization. Gemini function declarations use an
-OpenAPI-compatible subset, so this adapter should fail closed for unsupported
-JSON Schema 2020-12 features rather than silently weakening validation.
+OpenAPI-compatible subset, so this adapter should fail closed for unsupported JSON
+Schema 2020-12 features rather than silently weakening validation.
 
 ## P3: Vercel AI SDK Tools
 
-Target a TypeScript-first adapter that exports an AI SDK-compatible tool map
-without execution functions:
+Target a TypeScript-first adapter that exports an AI SDK-compatible tool map without
+execution functions:
 
 - object keys are deterministic tool names;
 - values include `description`, `inputSchema`, and `strict` when supported;
@@ -97,9 +95,9 @@ Parser target:
 - validate tool call input against the original AICF input schema;
 - leave tool result production and execution to the host app.
 
-This adapter is attractive because the AI SDK accepts JSON schemas and `execute`
-is optional, allowing host apps to forward calls to a queue, client, or approval
-path instead of executing in the same process.
+This adapter is attractive because the AI SDK accepts JSON schemas and `execute` is
+optional, allowing host apps to forward calls to a queue, client, or approval path
+instead of executing in the same process.
 
 ## P4: Model Context Protocol Tool Descriptors
 
@@ -110,18 +108,18 @@ Target MCP descriptor export, not an AICF-owned executable MCP server:
 - `description`: AICF model description plus lifecycle/risk guidance;
 - `inputSchema`: AICF input schema, preserving JSON Schema 2020-12 where valid;
 - `outputSchema`: AICF output schema when representable;
-- `annotations`: conservative hints derived from side effects, such as read-only
-  and idempotent hints.
+- `annotations`: conservative hints derived from side effects, such as read-only and
+  idempotent hints.
 
 Parser target:
 
 - map `tools/call.params.name` to capability ID;
 - validate `tools/call.params.arguments`;
-- return an AICF capability request object for the host MCP server or runtime to
-  decide and execute.
+- return an AICF capability request object for the host MCP server or runtime to decide
+  and execute.
 
-Do not add an MCP server that executes capabilities inside AICF. Host apps may
-use AICF descriptors inside their own MCP server implementation.
+Do not add an MCP server that executes capabilities inside AICF. Host apps may use AICF
+descriptors inside their own MCP server implementation.
 
 ## P5: LangChain And LangGraph Tools
 
@@ -132,12 +130,12 @@ Target descriptor export for host-created tools:
 - schema suitable for LangChain structured tools;
 - binding metadata for capability ID, risk, autonomy, and restriction status.
 
-Do not generate callable implementations. LangChain and LangGraph tools are
-runtime functions that can update state or return commands, so the host must
-supply execution, approval, and state handling.
+Do not generate callable implementations. LangChain and LangGraph tools are runtime
+functions that can update state or return commands, so the host must supply execution,
+approval, and state handling.
 
-This adapter should probably be implemented after the AI SDK adapter, because
-both are TypeScript-oriented but AI SDK has a cleaner descriptor-only path.
+This adapter should probably be implemented after the AI SDK adapter, because both are
+TypeScript-oriented but AI SDK has a cleaner descriptor-only path.
 
 ## P6: Semantic Kernel Functions
 
@@ -148,8 +146,8 @@ Target metadata and manual-invocation compatibility:
 - parser support for chosen function name and arguments;
 - guidance for `autoInvoke: false` style host workflows.
 
-Semantic Kernel is useful for enterprise users, but its strongest value is in
-runtime orchestration. AICF should stay on the metadata and validation side.
+Semantic Kernel is useful for enterprise users, but its strongest value is in runtime
+orchestration. AICF should stay on the metadata and validation side.
 
 ## Common Tests For Future Adapter Implementations
 
@@ -157,10 +155,10 @@ Each adapter should add tests for:
 
 - allowed read and prepare capabilities exported for a matching context;
 - restricted commit/send capabilities excluded by default;
-- restricted export only with an explicit option and deterministic selection
-  still applied;
-- deterministic safe name generation, truncation, collision handling, and
-  reverse bindings;
+- restricted export only with an explicit option and deterministic selection still
+  applied;
+- deterministic safe name generation, truncation, collision handling, and reverse
+  bindings;
 - schema normalization success and unsupported-schema exclusion;
 - valid tool-call parsing;
 - invalid JSON or malformed input handling;
@@ -170,10 +168,14 @@ Each adapter should add tests for:
 
 ## Reference Links
 
-- Anthropic Claude tool use: https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview
-- Anthropic define tools: https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools
+- Anthropic Claude tool use:
+  https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview
+- Anthropic define tools:
+  https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools
 - Google Gemini function calling: https://ai.google.dev/gemini-api/docs/function-calling
 - Vercel AI SDK tool calling: https://ai-sdk.dev/docs/ai-sdk-core/tools-and-tool-calling
-- Model Context Protocol tools: https://modelcontextprotocol.io/specification/2025-06-18/server/tools
+- Model Context Protocol tools:
+  https://modelcontextprotocol.io/specification/2025-06-18/server/tools
 - LangChain JavaScript tools: https://docs.langchain.com/oss/javascript/langchain/tools
-- Semantic Kernel manual function invocation: https://learn.microsoft.com/en-us/semantic-kernel/concepts/ai-services/chat-completion/function-calling/function-invocation
+- Semantic Kernel manual function invocation:
+  https://learn.microsoft.com/en-us/semantic-kernel/concepts/ai-services/chat-completion/function-calling/function-invocation

package/docs/adapters.md

@@ -1,21 +1,20 @@
 # Adapters
 
-AICF adapters export validated capability manifests into provider or runtime
-tool descriptor shapes. They do not call models, execute handlers, persist
-actions, collect approvals, or perform side effects.
+AICF adapters export validated capability manifests into provider or runtime tool
+descriptor shapes. They do not call models, execute handlers, persist actions, collect
+approvals, or perform side effects.
 
 Every adapter follows the same boundary:
 
 - require a decision context with permissions and autonomy tier;
 - include only capabilities whose `select` decision is `allowed`;
-- exclude restricted commit, send, money-moving, permission-changing, workflow,
-  and irreversible capabilities by default;
-- allow restricted export only with `includeRestricted: true`, while still
-  applying deterministic selection;
+- exclude restricted commit, send, money-moving, permission-changing, workflow, and
+  irreversible capabilities by default;
+- allow restricted export only with `includeRestricted: true`, while still applying
+  deterministic selection;
 - bind exported names back to AICF capability IDs;
 - validate parsed tool-call arguments against the original AICF input schema;
-- fail closed with diagnostics when schemas or names cannot be represented
-  safely.
+- fail closed with diagnostics when schemas or names cannot be represented safely.
 
 ## TypeScript APIs
 
@@ -89,9 +88,9 @@ node dist/cli.js langchain-tools examples --context examples/support/openai/cont
 node dist/cli.js semantic-kernel-functions examples --context examples/support/openai/context.support_agent.json
 ```
 
-Use `--include-restricted` only when the host has deliberately narrowed context
-and still intends to run deterministic approval, idempotency, auth, and commit
-checks before any side effect.
+Use `--include-restricted` only when the host has deliberately narrowed context and
+still intends to run deterministic approval, idempotency, auth, and commit checks before
+any side effect.
 
 ## Output Shapes
 
@@ -107,6 +106,6 @@ All outputs include `bindings`, `excluded`, and `diagnostics`.
 
 ## Host Responsibilities
 
-Adapters only produce descriptors and parse calls. Host applications remain
-responsible for model requests, real authorization, facts, approvals, execution,
-storage, idempotency, verification, and durable audit logs.
+Adapters only produce descriptors and parse calls. Host applications remain responsible
+for model requests, real authorization, facts, approvals, execution, storage,
+idempotency, verification, and durable audit logs.

package/docs/ai-sdk-runtime.md

@@ -1,18 +1,18 @@
 # Vercel AI SDK Bridge
 
-The AI SDK bridge is an optional provider adapter for applications that already
-use Vercel AI SDK Core. It translates a routed AICF capability slice into AI SDK
-tools, executes tool calls through `AicfToolExecutor`, and returns model-safe
-AICF runtime envelopes.
+The AI SDK bridge is an optional provider adapter for applications that already use
+Vercel AI SDK Core. It translates a routed AICF capability slice into AI SDK tools,
+executes tool calls through `AicfToolExecutor`, and returns model-safe AICF runtime
+envelopes.
 
-It does not install provider packages, choose a model provider, expose commit
-tools, persist state, log raw provider payloads, or make root/runtime imports
-depend on the `ai` package.
+It does not install provider packages, choose a model provider, expose commit tools,
+persist state, log raw provider payloads, or make root/runtime imports depend on the
+`ai` package.
 
 ## Import
 
-Install AICF plus AI SDK Core only in applications that use this bridge. Model
-provider packages remain host application dependencies.
+Install AICF plus AI SDK Core only in applications that use this bridge. Model provider
+packages remain host application dependencies.
 
 ```bash
 npm install ai-capability-framework ai
@@ -26,52 +26,49 @@ import {
 } from "ai-capability-framework/providers/ai-sdk";
 ```
 
-`createDefaultAiSdkToolFactories()` dynamically imports the optional `ai`
-package. Host applications may instead pass compatible `tool`, `jsonSchema`,
-and optional `stepCountIs` factories.
+`createDefaultAiSdkToolFactories()` dynamically imports the optional `ai` package. Host
+applications may instead pass compatible `tool`, `jsonSchema`, and optional
+`stepCountIs` factories.
 
 ## Tool Bridge
 
-`buildAiSdkTools()` builds an AI SDK tool set from an already-routed AICF
-capability slice. Each generated tool uses a provider-safe name, a cloned JSON
-Schema input, and an `execute` callback that delegates to
-`executeProviderToolCall()`.
+`buildAiSdkTools()` builds an AI SDK tool set from an already-routed AICF capability
+slice. Each generated tool uses a provider-safe name, a cloned JSON Schema input, and an
+`execute` callback that delegates to `executeProviderToolCall()`.
 
 AI SDK validation and `needsApproval` metadata are advisory. AICF still performs
-canonical input validation, policy checks, lifecycle checks, approval handling,
-and model-safe envelope formatting.
+canonical input validation, policy checks, lifecycle checks, approval handling, and
+model-safe envelope formatting.
 
 Minimal usage is: validate manifests, build a routed runtime slice, register
-read/prepare handlers, create AI SDK tool factories, then pass the generated
-tools to a host-owned `generateText` or `streamText` call.
+read/prepare handlers, create AI SDK tool factories, then pass the generated tools to a
+host-owned `generateText` or `streamText` call.
 
 ## Generate And Stream Wrappers
 
-`runAiSdkGenerateText()` is a convenience wrapper around a host-supplied
-`generateText` function. It passes the host model, prompt or messages, system
-text, tools, `stopWhen`, and provider options, then returns a safe summary with
-text, tool-call summaries, model-safe tool envelopes, usage, warnings, and trace
-events.
+`runAiSdkGenerateText()` is a convenience wrapper around a host-supplied `generateText`
+function. It passes the host model, prompt or messages, system text, tools, `stopWhen`,
+and provider options, then returns a safe summary with text, tool-call summaries,
+model-safe tool envelopes, usage, warnings, and trace events.
 
-`runAiSdkStreamText()` is a thin wrapper around a host-supplied `streamText`
-function. It passes AICF-backed tools and trace hooks, sets `includeRawChunks:
-false`, and does not consume, transform, log, or store raw stream chunks.
+`runAiSdkStreamText()` is a thin wrapper around a host-supplied `streamText` function.
+It passes AICF-backed tools and trace hooks, sets `includeRawChunks: false`, and does
+not consume, transform, log, or store raw stream chunks.
 
 ## Boundary
 
-- AICF capability manifests, policy, lifecycle, and runtime envelopes remain the
-  source of truth.
-- Commit, destructive, money-moving, and external-send capabilities are not
-  exported by default and are not executable through AI SDK tool calls.
-- Provider packages such as `@ai-sdk/openai`, `@ai-sdk/anthropic`, and
-  `@ai-sdk/google` are host application dependencies, not AICF dependencies.
-- Raw prompts, provider request/response payloads, traces, credentials, and
-  private diagnostics are not captured by default.
+- AICF capability manifests, policy, lifecycle, and runtime envelopes remain the source
+  of truth.
+- Commit, destructive, money-moving, and external-send capabilities are not exported by
+  default and are not executable through AI SDK tool calls.
+- Provider packages such as `@ai-sdk/openai`, `@ai-sdk/anthropic`, and `@ai-sdk/google`
+  are host application dependencies, not AICF dependencies.
+- Raw prompts, provider request/response payloads, traces, credentials, and private
+  diagnostics are not captured by default.
 - Live tests are opt-in with `RUN_LIVE_AI_SDK=1` and host-provided model setup.
 
-Known limitations: no AI SDK provider packages, no provider selection, no UI
-components, no raw stream chunk capture, no production storage, and no
-model-exposed commit path.
+Known limitations: no AI SDK provider packages, no provider selection, no UI components,
+no raw stream chunk capture, no production storage, and no model-exposed commit path.
 
 ## Checks
 

package/docs/anthropic-runtime.md

@@ -1,17 +1,16 @@
 # Anthropic Claude Runtime
 
-The Anthropic runtime is an optional provider adapter for Claude Messages tool
-use. It translates a routed AICF capability slice into Claude client tools,
-runs a bounded Messages loop with a caller-provided client, executes tool calls
-through `AicfToolExecutor`, and returns Claude-compatible `tool_result` blocks.
+The Anthropic runtime is an optional provider adapter for Claude Messages tool use. It
+translates a routed AICF capability slice into Claude client tools, runs a bounded
+Messages loop with a caller-provided client, executes tool calls through
+`AicfToolExecutor`, and returns Claude-compatible `tool_result` blocks.
 
-It does not expose commit tools, use Anthropic Tool Runner, persist state, log
-raw provider payloads, or make root/runtime imports depend on the Anthropic SDK.
+It does not expose commit tools, use Anthropic Tool Runner, persist state, log raw
+provider payloads, or make root/runtime imports depend on the Anthropic SDK.
 
 ## Import
 
-Install AICF plus the optional Anthropic SDK only in applications that use this
-subpath:
+Install AICF plus the optional Anthropic SDK only in applications that use this subpath:
 
 ```bash
 npm install ai-capability-framework @anthropic-ai/sdk
@@ -26,8 +25,8 @@ import {
 ```
 
 `createDefaultAnthropicMessagesClient()` dynamically imports the optional
-`@anthropic-ai/sdk` package. Host applications may instead pass any compatible
-client with `messages.create(input)`.
+`@anthropic-ai/sdk` package. Host applications may instead pass any compatible client
+with `messages.create(input)`.
 
 ## Runtime Shape
 
@@ -35,38 +34,36 @@ Minimal usage is: validate manifests, build a routed runtime slice, register
 read/prepare handlers, create or pass a Claude-compatible client, then call
 `runAnthropicMessages()` with synthetic-safe messages and host context.
 
-The host application is responsible for building runtime context, routing
-capabilities, registering handlers, and providing initial Claude messages.
+The host application is responsible for building runtime context, routing capabilities,
+registering handlers, and providing initial Claude messages.
 
-`runAnthropicMessages()` sends `model`, `max_tokens`, `system`, `messages`,
-`tools`, and optional `tool_choice` to `client.messages.create()`. If Claude
-returns `tool_use` blocks, AICF parses them through the generated binding map,
-validates arguments against the original AICF schema, executes only read or
-prepare through the runtime executor, and appends one user message whose content
-starts with matching `tool_result` blocks.
+`runAnthropicMessages()` sends `model`, `max_tokens`, `system`, `messages`, `tools`, and
+optional `tool_choice` to `client.messages.create()`. If Claude returns `tool_use`
+blocks, AICF parses them through the generated binding map, validates arguments against
+the original AICF schema, executes only read or prepare through the runtime executor,
+and appends one user message whose content starts with matching `tool_result` blocks.
 
-`tool_result.tool_use_id` always comes from Claude's `tool_use.id`. Safe error
-envelopes set `is_error: true`; approval-required prepare results are returned
-as model-safe envelopes without committing the action.
+`tool_result.tool_use_id` always comes from Claude's `tool_use.id`. Safe error envelopes
+set `is_error: true`; approval-required prepare results are returned as model-safe
+envelopes without committing the action.
 
 ## Boundary
 
-The Anthropic runtime follows the same provider-neutral boundary as the OpenAI
-runtime:
+The Anthropic runtime follows the same provider-neutral boundary as the OpenAI runtime:
 
-- AICF capability manifests, policy, lifecycle, and runtime envelopes remain the
-  source of truth.
+- AICF capability manifests, policy, lifecycle, and runtime envelopes remain the source
+  of truth.
 - Claude tool schemas are provider descriptors, not trusted execution policy.
-- Commit, destructive, money-moving, and external-send capabilities are not
-  exported by default and are not executable through provider tool calls.
-- Raw prompts, provider request/response payloads, traces, credentials, and
-  private diagnostics are not captured by default.
+- Commit, destructive, money-moving, and external-send capabilities are not exported by
+  default and are not executable through provider tool calls.
+- Raw prompts, provider request/response payloads, traces, credentials, and private
+  diagnostics are not captured by default.
 - Live tests are opt-in with `RUN_LIVE_ANTHROPIC=1`, `ANTHROPIC_API_KEY`, and
   `AICF_ANTHROPIC_MODEL`.
 
-Known limitations: no streaming, no Anthropic Tool Runner, no server-side
-Anthropic tools, no provider-managed automatic tool execution, no production
-storage, and no model-exposed commit path.
+Known limitations: no streaming, no Anthropic Tool Runner, no server-side Anthropic
+tools, no provider-managed automatic tool execution, no production storage, and no
+model-exposed commit path.
 
 ## Checks
 

package/docs/api/public-api-policy.md

@@ -0,0 +1,59 @@
+# Public API Policy
+
+AICF treats published package exports as public contracts. The root package is the
+stable Core and descriptor API. Runtime, provider, governance, security, storage,
+control-plane, eval, and CLI utilities live behind explicit subpaths so applications can
+import only the surface they use.
+
+## Root API Policy
+
+The root import is reserved for stable Core and descriptor APIs. It should stay small
+enough that applications can import it without pulling optional runtime, provider,
+cloud, tracing, or CLI implementation dependencies.
+
+## Import Policy
+
+- Use `ai-capability-framework` for Core contracts, manifest loading, validation,
+  deterministic decisions, eval helpers, descriptor adapters, and model-safe tool
+  results.
+- Use subpaths for optional runtime or integration surfaces, such as
+  `ai-capability-framework/runtime`, `ai-capability-framework/openai`, and
+  `ai-capability-framework/providers/anthropic`.
+- Use `ai-capability-framework/cli` only for programmatic CLI tests or tooling. The
+  `runCli` helper is intentionally not exported from the root package.
+- The `aicf` binary remains the supported command-line entrypoint for normal CLI use.
+- Optional provider, AWS, OpenTelemetry, Langfuse, MCP, LangChain, AI SDK, and Agents
+  SDK packages must not be required by the root import.
+
+## Export Classifications
+
+| Surface                                                                                                                                                                                                                                                     | Classification                      | Notes                                                                                                                                                       |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ai-capability-framework`                                                                                                                                                                                                                                   | stable public                       | Core manifests, loading, validation, deterministic decisions, eval helpers, descriptor-only adapters, registry helpers, and model-safe tool-result helpers. |
+| `ai-capability-framework/runtime`                                                                                                                                                                                                                           | release-candidate public            | No-model runtime context, routing, policy, handler registry, executor, lifecycle, stores, audit events, and envelopes.                                      |
+| `ai-capability-framework/openai`                                                                                                                                                                                                                            | adapter public                      | Optional OpenAI Responses runtime and OpenAI Agents SDK bridge.                                                                                             |
+| `ai-capability-framework/providers`                                                                                                                                                                                                                         | adapter public                      | Shared provider foundation for names, schemas, calls, results, optional dependencies, and provider execution helpers.                                       |
+| `ai-capability-framework/providers/*`                                                                                                                                                                                                                       | adapter public                      | Provider-specific or framework-bridge adapter surfaces for Anthropic, Gemini, AI SDK, LangChain, MCP, Semantic Kernel, and conformance helpers.             |
+| `ai-capability-framework/mcp-server`                                                                                                                                                                                                                        | adapter public                      | Optional MCP server runtime surface backed by AICF routing and execution.                                                                                   |
+| `ai-capability-framework/aws`                                                                                                                                                                                                                               | adapter public                      | Optional AWS reference adapters. AWS SDK imports stay isolated to this subpath.                                                                             |
+| `ai-capability-framework/observability`, `ai-capability-framework/langfuse`                                                                                                                                                                                 | release-candidate public            | Optional metadata/redacted-content tracing and Langfuse adapters.                                                                                           |
+| `ai-capability-framework/evals-live`, `ai-capability-framework/evalops`, `ai-capability-framework/promptfoo`                                                                                                                                                | release-candidate public            | Optional eval and EvalOps export/import helpers. Live paths are opt-in.                                                                                     |
+| `ai-capability-framework/governance`, `ai-capability-framework/controls`, `ai-capability-framework/conformance`                                                                                                                                             | release-candidate public            | Governance, runtime controls, and deterministic conformance gates.                                                                                          |
+| `ai-capability-framework/audit`, `ai-capability-framework/security`, `ai-capability-framework/security-packs`, `ai-capability-framework/replay`, `ai-capability-framework/evidence`, `ai-capability-framework/memory`, `ai-capability-framework/provenance` | release-candidate public            | Public-safe evidence, security, replay, memory, and provenance utility contracts.                                                                           |
+| `ai-capability-framework/control-plane`                                                                                                                                                                                                                     | release-candidate public            | Framework-neutral request router and reference service helpers; production auth and storage remain host-owned.                                              |
+| `ai-capability-framework/cli`                                                                                                                                                                                                                               | release-candidate public            | Programmatic CLI runner for tests and tooling. Exposes `runCli` and `CliRunOptions`; not exported from the root package.                                    |
+| `src/cli.ts` direct imports in repository tests                                                                                                                                                                                                             | internal but exported for CLI/tests | Source-level test convenience only. External users should import `ai-capability-framework/cli` or run the `aicf` binary.                                    |
+| Root `runCli` export                                                                                                                                                                                                                                        | should be removed before v1         | Removed from root in P7. Use `ai-capability-framework/cli`.                                                                                                 |
+| CLI implementation helpers other than `runCli` and `CliRunOptions`                                                                                                                                                                                          | should move to subpath              | Keep private to the CLI module unless a future release documents a narrow public contract.                                                                  |
+| Undocumented source files, generated internals, and private helper functions                                                                                                                                                                                | should be removed before v1         | Do not expose through package exports.                                                                                                                      |
+
+## Migration Note For Release-Candidate Users
+
+If a release-candidate app imported `runCli` from the package root, change it to:
+
+```ts
+import { runCli } from "ai-capability-framework/cli";
+```
+
+This keeps root imports focused on the stable Core API while preserving a supported
+programmatic CLI entrypoint for tests and local automation.