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

package/docs/mcp-server-runtime.md

@@ -1,8 +1,7 @@
 # MCP Server Runtime
 
-AICF MCP server runtime is an optional interoperability subpath for host
-applications that want to expose routed AICF capabilities through a Model
-Context Protocol server.
+AICF MCP server runtime is an optional interoperability subpath for host applications
+that want to expose routed AICF capabilities through a Model Context Protocol server.
 
 Import it from:
 
@@ -20,55 +19,52 @@ Descriptor-only MCP provider helpers are available separately:
 import { buildMcpProviderToolDescriptors } from "ai-capability-framework/providers/mcp";
 ```
 
-The package root and `ai-capability-framework/runtime` do not import the MCP SDK.
-The MCP SDK is optional unless a host uses SDK registration helpers.
+The package root and `ai-capability-framework/runtime` do not import the MCP SDK. The
+MCP SDK is optional unless a host uses SDK registration helpers.
 
 ## Runtime Boundary
 
-`AicfMcpServer` is an in-process server core. It does not start an HTTP, SSE,
-Streamable HTTP, or stdio process by itself. Host applications own transport,
-authentication, session handling, network policy, and deployment.
+`AicfMcpServer` is an in-process server core. It does not start an HTTP, SSE, Streamable
+HTTP, or stdio process by itself. Host applications own transport, authentication,
+session handling, network policy, and deployment.
 
 The server lists and executes only routed read and prepare capabilities. Commit
-capabilities are not listed and are not executable through MCP tool calls.
-Commit remains host-controlled through the AICF action lifecycle manager.
+capabilities are not listed and are not executable through MCP tool calls. Commit
+remains host-controlled through the AICF action lifecycle manager.
 
 ## Tool Listing
 
-Minimal usage is: validate manifests, build runtime context through a trusted
-host factory, route a read/prepare capability slice, instantiate
-`AicfMcpServer`, then bind it to a host-owned MCP transport or SDK server.
+Minimal usage is: validate manifests, build runtime context through a trusted host
+factory, route a read/prepare capability slice, instantiate `AicfMcpServer`, then bind
+it to a host-owned MCP transport or SDK server.
 
 `listTools(request)` resolves runtime context through a host-provided
-`runtimeContextFactory`, builds model context through `AicfContextBuilder`,
-routes capabilities through `AicfCapabilityRouter`, and returns MCP tool
-descriptors generated from the validated AICF manifests through the MCP provider
-descriptor layer.
+`runtimeContextFactory`, builds model context through `AicfContextBuilder`, routes
+capabilities through `AicfCapabilityRouter`, and returns MCP tool descriptors generated
+from the validated AICF manifests through the MCP provider descriptor layer.
 
-The context factory must validate user, tenant, account, and permission context.
-The MCP client request is not a trusted identity source.
+The context factory must validate user, tenant, account, and permission context. The MCP
+client request is not a trusted identity source.
 
 ## Tool Calling
 
-`callTool(request)` parses an MCP `tools/call`-style request, validates
-arguments against the original AICF capability schema, and executes through
-`AicfToolExecutor`.
+`callTool(request)` parses an MCP `tools/call`-style request, validates arguments
+against the original AICF capability schema, and executes through `AicfToolExecutor`.
 
-Tool output is a model-safe AICF runtime envelope serialized as text content.
-Denied, unavailable, validation-error, and failed paths return safe MCP error
-results without stack traces, raw prompts, provider payloads, or private
-diagnostics.
+Tool output is a model-safe AICF runtime envelope serialized as text content. Denied,
+unavailable, validation-error, and failed paths return safe MCP error results without
+stack traces, raw prompts, provider payloads, or private diagnostics.
 
-Descriptor metadata includes MCP annotations and `_meta.aicf` summaries for
-capability ID, type, risk, lifecycle operation, approval requirement, security
-boundary, and side effects. These are hints for MCP-compatible clients; AICF
-runtime validation and policy remain authoritative.
+Descriptor metadata includes MCP annotations and `_meta.aicf` summaries for capability
+ID, type, risk, lifecycle operation, approval requirement, security boundary, and side
+effects. These are hints for MCP-compatible clients; AICF runtime validation and policy
+remain authoritative.
 
 ## SDK Registration Helper
 
 `registerAicfMcpTools()` can register the current routed tool set against a
-caller-provided MCP SDK server object that exposes `registerTool()` or `tool()`.
-It does not import MCP transports or create a long-running process.
+caller-provided MCP SDK server object that exposes `registerTool()` or `tool()`. It does
+not import MCP transports or create a long-running process.
 
 ```ts
 await registerAicfMcpTools({
@@ -78,12 +74,12 @@ await registerAicfMcpTools({
 });
 ```
 
-For production MCP deployments, host applications should pin SDK versions,
-validate transport auth, enforce tenant/account context on the server side, and
-apply the same audit and approval controls used by other AICF runtime paths.
+For production MCP deployments, host applications should pin SDK versions, validate
+transport auth, enforce tenant/account context on the server side, and apply the same
+audit and approval controls used by other AICF runtime paths.
 
-The public runtime support/billing example shows the executor and lifecycle
-objects that an MCP host can reuse behind `AicfMcpServer.callTool()`.
+The public runtime support/billing example shows the executor and lifecycle objects that
+an MCP host can reuse behind `AicfMcpServer.callTool()`.
 
 ## Checks
 
@@ -93,6 +89,6 @@ npm run test:mcp-provider
 npm run test:mcp-server
 ```
 
-Known limitations: no standalone HTTP, SSE, Streamable HTTP, or stdio server;
-no full MCP transport matrix; no production auth; no raw MCP payload logging;
-and no model-exposed commit path.
+Known limitations: no standalone HTTP, SSE, Streamable HTTP, or stdio server; no full
+MCP transport matrix; no production auth; no raw MCP payload logging; and no
+model-exposed commit path.

package/docs/memory.md

@@ -1,8 +1,8 @@
 # Governed Memory And Preferences
 
-AICF memory governance is an optional contract for host-owned memory and
-preferences. It helps a host decide whether a summarized memory record may be
-shown to a model as context.
+AICF memory governance is an optional contract for host-owned memory and preferences. It
+helps a host decide whether a summarized memory record may be shown to a model as
+context.
 
 Import it from:
 
@@ -13,57 +13,56 @@ import {
 } from "ai-capability-framework/memory";
 ```
 
-The memory subpath does not store memory, recall memory, infer preferences,
-embed text, search vectors, call models, or update user profiles. Host
-applications own memory storage, consent, deletion, identity resolution, tenant
-scoping, and user-facing preference controls.
+The memory subpath does not store memory, recall memory, infer preferences, embed text,
+search vectors, call models, or update user profiles. Host applications own memory
+storage, consent, deletion, identity resolution, tenant scoping, and user-facing
+preference controls.
 
 ## Records
 
-`GovernedMemoryRecord` stores a public-safe summary, not raw transcripts or raw
-profile data. Each record includes:
+`GovernedMemoryRecord` stores a public-safe summary, not raw transcripts or raw profile
+data. Each record includes:
 
 - redacted subject/account/tenant refs where relevant;
 - a scope such as `user`, `account`, `tenant`, `workflow`, or `session`;
 - a purpose and `contentSummary`;
-- source provenance, confidence, sensitivity labels, consent basis, allowed use
-  cases, disallowed use cases, timestamps, and optional retention policy.
+- source provenance, confidence, sensitivity labels, consent basis, allowed use cases,
+  disallowed use cases, timestamps, and optional retention policy.
 
-Preferences use the same record shape. For example, a support user preference
-can allow `support_refund_preparation` while disallowing cross-tenant support.
+Preferences use the same record shape. For example, a support user preference can allow
+`support_refund_preparation` while disallowing cross-tenant support.
 
 ## Exposure
 
-`evaluateMemoryExposure(record, context)` fails closed when a record is expired,
-out of scope, missing a matching use case, explicitly disallowed, credential
-classified, or sensitive without consent.
+`evaluateMemoryExposure(record, context)` fails closed when a record is expired, out of
+scope, missing a matching use case, explicitly disallowed, credential classified, or
+sensitive without consent.
 
-`selectGovernedMemory(records, context)` evaluates every record, keeps only
-allowed records, sorts them by record ID, and applies a default maximum of 20.
+`selectGovernedMemory(records, context)` evaluates every record, keeps only allowed
+records, sorts them by record ID, and applies a default maximum of 20.
 
-Allowed use cases are exact string matches in F12. There is no wildcard or
-semantic matching.
+Allowed use cases are exact string matches in F12. There is no wildcard or semantic
+matching.
 
 ## Context Conversion
 
 `memoryRecordToContextSegment()` converts a selected record into a security
-`ContextSegment` with `instructionsAllowed: false`. Memory is data, not a
-system or developer instruction.
+`ContextSegment` with `instructionsAllowed: false`. Memory is data, not a system or
+developer instruction.
 
-`memoryRecordToRuntimeContextItem()` converts a selected record into a runtime
-context item for host-controlled context building. It includes purpose,
-confidence, scope, sensitivity labels, and the summary without exposing raw
-subject IDs or private diagnostics.
+`memoryRecordToRuntimeContextItem()` converts a selected record into a runtime context
+item for host-controlled context building. It includes purpose, confidence, scope,
+sensitivity labels, and the summary without exposing raw subject IDs or private
+diagnostics.
 
-Sensitive or credential-classified records still go through the existing
-security redaction helpers before crossing provider or trace boundaries.
+Sensitive or credential-classified records still go through the existing security
+redaction helpers before crossing provider or trace boundaries.
 
 ## Example
 
-The public fixture at
-`examples/support/memory/support.agent.preferences.json` is synthetic. It shows
-a support preference summary with redacted refs and an explicit use-case allow
-list. It is validated by `npm run validate`.
+The public fixture at `examples/support/memory/support.agent.preferences.json` is
+synthetic. It shows a support preference summary with redacted refs and an explicit
+use-case allow list. It is validated by `npm run validate`.
 
 ```bash
 npm run validate
@@ -72,8 +71,8 @@ npm run test:memory
 
 ## Boundaries
 
-AICF does not decide what should be remembered. It only helps a host govern
-whether a host-supplied memory summary may be used for a specific request.
+AICF does not decide what should be remembered. It only helps a host govern whether a
+host-supplied memory summary may be used for a specific request.
 
-Do not put raw prompts, raw provider payloads, raw transcripts, credentials,
-tenant IDs, account IDs, user IDs, or customer data in public memory fixtures.
+Do not put raw prompts, raw provider payloads, raw transcripts, credentials, tenant IDs,
+account IDs, user IDs, or customer data in public memory fixtures.

package/docs/migration-0.1-to-1.0.md

@@ -1,7 +1,7 @@
 # Migration From 0.1 To 1.0
 
-AICF 1.0 is a clean public contract cut from the pre-release 0.1 work. The
-validator intentionally does not support both schema versions side by side.
+AICF 1.0 is a clean public contract cut from the pre-release 0.1 work. The validator
+intentionally does not support both schema versions side by side.
 
 ## Required Changes
 
@@ -9,14 +9,19 @@ validator intentionally does not support both schema versions side by side.
   `schema_version: "1.0"`.
 - Regenerate TypeScript manifest types with `npm run generate:types`.
 - Re-run `npm run validate` and `npm run check`.
-- Update docs, changelog entries, and release notes that refer to the manifest
-  contract version.
+- Update docs, changelog entries, and release notes that refer to the manifest contract
+  version.
+- If test tooling imported `runCli` from `ai-capability-framework`, update that import
+  to `ai-capability-framework/cli`.
 
 ## Compatibility Notes
 
-The 1.0 contract preserves the v0.1 public shape and no-execution boundary. The
-main compatibility change is the schema version literal. Treat v0.1 examples as
-pre-release material and update them before using the 1.0 validator.
+The 1.0 contract preserves the v0.1 public shape and no-execution boundary. The main
+compatibility change is the schema version literal. Treat v0.1 examples as pre-release
+material and update them before using the 1.0 validator.
 
-Host applications remain responsible for model calls, auth, facts, approvals,
-side effects, storage, and durable audit logs.
+Release-candidate CLI runner imports moved out of the root package before v1. The `aicf`
+binary did not change; only programmatic imports should switch to the `./cli` subpath.
+
+Host applications remain responsible for model calls, auth, facts, approvals, side
+effects, storage, and durable audit logs.

package/docs/observability/overview.md

@@ -1,8 +1,7 @@
 # Observability Overview
 
-AICF observability emits sanitized metadata events and spans. It does not store
-raw prompts, raw provider payloads, traces, secrets, or sensitive tool output by
-default.
+AICF observability emits sanitized metadata events and spans. It does not store raw
+prompts, raw provider payloads, traces, secrets, or sensitive tool output by default.
 
 Read:
 

package/docs/observability-runtime.md

@@ -1,7 +1,7 @@
 # Observability Runtime
 
-AICF observability is an optional set of trace sinks and redaction helpers for
-runtime behavior. Import it from:
+AICF observability is an optional set of trace sinks and redaction helpers for runtime
+behavior. Import it from:
 
 ```ts
 import {
@@ -12,23 +12,21 @@ import {
 } from "ai-capability-framework/observability";
 ```
 
-The package root and runtime subpath do not require OpenTelemetry, Langfuse, or
-any provider SDK.
+The package root and runtime subpath do not require OpenTelemetry, Langfuse, or any
+provider SDK.
 
 Sanitized runtime traces can be replayed or converted into draft evals through
-`ai-capability-framework/replay`. Replay fixtures should contain metadata,
-hashes, model-safe envelopes, and redaction summaries, not raw prompts or raw
-provider payloads.
+`ai-capability-framework/replay`. Replay fixtures should contain metadata, hashes,
+model-safe envelopes, and redaction summaries, not raw prompts or raw provider payloads.
 
 ## Trace Events
 
-Trace events are structured summaries with run ID, request ID, timestamp, event
-type, and JSON-safe attributes. They are intended for runtime inspection and
-external observability sinks, not raw transcript storage.
+Trace events are structured summaries with run ID, request ID, timestamp, event type,
+and JSON-safe attributes. They are intended for runtime inspection and external
+observability sinks, not raw transcript storage.
 
-Default event capture is metadata-only. Raw prompts, user text, tool outputs,
-provider payloads, secrets, session tokens, cookies, and payment data are not
-emitted by default.
+Default event capture is metadata-only. Raw prompts, user text, tool outputs, provider
+payloads, secrets, session tokens, cookies, and payment data are not emitted by default.
 
 Content capture modes:
 
@@ -36,48 +34,46 @@ Content capture modes:
 - `metadata`: keep size/key summaries only.
 - `redacted_content`: include redacted content after sensitive-value scrubbing.
 
-When trace attributes include AICF security classification metadata, the
-optional `ai-capability-framework/security` redaction defaults are applied
-before collection. This preserves existing capture modes while adding
-fail-closed handling for credentials and sensitive data classes.
+When trace attributes include AICF security classification metadata, the optional
+`ai-capability-framework/security` redaction defaults are applied before collection.
+This preserves existing capture modes while adding fail-closed handling for credentials
+and sensitive data classes.
 
 ## Trace Sinks
 
 - `NoopTraceSink` discards events.
 - `CollectingTraceSink` stores sanitized events in memory for tests.
 - `CompositeTraceSink` fans out to multiple sinks and isolates sink failures.
-- `NoopTracer`, `InMemoryTracer`, `TraceSinkTracer`, and
-  `OpenTelemetryTracerAdapter` provide a run/span-style API over the same
-  sanitized event model.
-- `OpenTelemetryTraceSink` accepts a tracer-like API object and maps useful
-  `gen_ai.*` attributes plus stable `aicf.*` attributes.
+- `NoopTracer`, `InMemoryTracer`, `TraceSinkTracer`, and `OpenTelemetryTracerAdapter`
+  provide a run/span-style API over the same sanitized event model.
+- `OpenTelemetryTraceSink` accepts a tracer-like API object and maps useful `gen_ai.*`
+  attributes plus stable `aicf.*` attributes.
 
-OpenTelemetry GenAI conventions are still evolving, so AICF keeps its own
-namespaced attributes for framework-specific data such as capability ID,
-policy status, action state, run ID, and request ID.
+OpenTelemetry GenAI conventions are still evolving, so AICF keeps its own namespaced
+attributes for framework-specific data such as capability ID, policy status, action
+state, run ID, and request ID.
 
 ## OpenAI Runtime Integration
 
-`runOpenAIResponses()` accepts optional `traceSink` and `contentCapture`
-options. It emits events for context building, routing, model calls, tool call
-parsing, tool execution, runtime errors, and completion.
+`runOpenAIResponses()` accepts optional `traceSink` and `contentCapture` options. It
+emits events for context building, routing, model calls, tool call parsing, tool
+execution, runtime errors, and completion.
 
 Trace sink failures do not fail the runtime request. They produce safe internal
 diagnostics only.
 
 ## Langfuse
 
-Langfuse support is available from `ai-capability-framework/langfuse`. The
-adapter accepts a client-like object and probes methods at runtime, so the SDK
-is optional and version drift does not affect Core imports.
+Langfuse support is available from `ai-capability-framework/langfuse`. The adapter
+accepts a client-like object and probes methods at runtime, so the SDK is optional and
+version drift does not affect Core imports.
 
-Langfuse dataset helpers convert AICF eval cases into public-safe dataset items
-and back. They do not upload data by themselves.
+Langfuse dataset helpers convert AICF eval cases into public-safe dataset items and
+back. They do not upload data by themselves.
 
-`LangfuseTracerAdapter` wraps the same sink behavior with the run/span-style
-tracer API. It still accepts a client-like object and does not require the
-Langfuse SDK.
+`LangfuseTracerAdapter` wraps the same sink behavior with the run/span-style tracer API.
+It still accepts a client-like object and does not require the Langfuse SDK.
 
-The runtime support/billing example is intentionally no-model and no-trace by
-default. Hosts can add `CollectingTraceSink` or another sink around the same
-runtime path when they need sanitized runtime inspection.
+The runtime support/billing example is intentionally no-model and no-trace by default.
+Hosts can add `CollectingTraceSink` or another sink around the same runtime path when
+they need sanitized runtime inspection.

package/docs/openai-responses.md

@@ -1,12 +1,12 @@
 # OpenAI Responses Adapter
 
-The OpenAI Responses adapter exports AICF capabilities as no-model-call function
-tool definitions. It converts validated manifests into tool definitions and maps
-model tool calls back to capability IDs and validated arguments.
+The OpenAI Responses adapter exports AICF capabilities as no-model-call function tool
+definitions. It converts validated manifests into tool definitions and maps model tool
+calls back to capability IDs and validated arguments.
 
-The adapter does not call OpenAI, execute handlers, persist action state, verify
-real authorization, collect approvals, commit side effects, or write audit logs.
-Host applications own those runtime responsibilities.
+The adapter does not call OpenAI, execute handlers, persist action state, verify real
+authorization, collect approvals, commit side effects, or write audit logs. Host
+applications own those runtime responsibilities.
 
 For the optional live Responses tool loop, see
 [OpenAI Responses runtime](openai-runtime.md). The adapter on this page exports
@@ -14,8 +14,8 @@ descriptor JSON only.
 
 ## Tool Export
 
-Use `buildOpenAIResponsesTools(registry, options)` with a validated registry and
-a request context:
+Use `buildOpenAIResponsesTools(registry, options)` with a validated registry and a
+request context:
 
 ```ts
 const toolset = buildOpenAIResponsesTools(registry, {
@@ -33,16 +33,16 @@ The result contains:
 - `excluded`: capabilities not exported and the reason.
 - `diagnostics`: export warnings or fatal name-collision errors.
 
-By default the adapter exports only capabilities whose `select` decision is
-allowed. For export, the context autonomy tier is treated as the toolset ceiling
-and capped at each capability's own autonomy tier before the select decision is
-evaluated. This lets an `A2` toolset include an `A1` read capability while still
-preserving capability-level autonomy limits.
+By default the adapter exports only capabilities whose `select` decision is allowed. For
+export, the context autonomy tier is treated as the toolset ceiling and capped at each
+capability's own autonomy tier before the select decision is evaluated. This lets an
+`A2` toolset include an `A1` read capability while still preserving capability-level
+autonomy limits.
 
-The adapter also excludes restricted side-effect capabilities, including commit,
-send, irreversible, money-moving, permission-changing, and workflow-triggering
-capabilities. Use `includeRestricted: true` only when the host application has
-already narrowed context and is deliberately constructing a restricted toolset.
+The adapter also excludes restricted side-effect capabilities, including commit, send,
+irreversible, money-moving, permission-changing, and workflow-triggering capabilities.
+Use `includeRestricted: true` only when the host application has already narrowed
+context and is deliberately constructing a restricted toolset.
 
 ## OpenAI Shape
 
@@ -63,29 +63,28 @@ Exported tools use the Responses function tool shape:
 }
 ```
 
-Tool names use `aicf_` plus a sanitized capability ID. Long names are capped at
-64 characters with a deterministic hash suffix. Tool descriptions include the
-manifest model description, capability type, risk tier, autonomy tier, lifecycle
-flags, and use guidance.
+Tool names use `aicf_` plus a sanitized capability ID. Long names are capped at 64
+characters with a deterministic hash suffix. Tool descriptions include the manifest
+model description, capability type, risk tier, autonomy tier, lifecycle flags, and use
+guidance.
 
-The adapter normalizes input schemas for OpenAI strict mode by making object
-properties required, representing optional fields as nullable where possible,
-and setting `additionalProperties: false`. Schemas that cannot be represented
-safely are excluded with diagnostics.
+The adapter normalizes input schemas for OpenAI strict mode by making object properties
+required, representing optional fields as nullable where possible, and setting
+`additionalProperties: false`. Schemas that cannot be represented safely are excluded
+with diagnostics.
 
 ## Tool Call Parsing
 
-Use `parseOpenAIResponsesToolCall(toolset, call)` after a model returns a
-Responses `function_call` item. The parser:
+Use `parseOpenAIResponsesToolCall(toolset, call)` after a model returns a Responses
+`function_call` item. The parser:
 
 - resolves the OpenAI tool name to an AICF capability ID;
 - parses the JSON argument string;
 - validates arguments against the capability input schema;
-- returns structured diagnostics for unknown tools, invalid JSON, and schema
-  failures.
+- returns structured diagnostics for unknown tools, invalid JSON, and schema failures.
 
-The parser does not execute the capability. The host application should run a
-fresh deterministic decision before prepare or commit execution.
+The parser does not execute the capability. The host application should run a fresh
+deterministic decision before prepare or commit execution.
 
 ## CLI
 
@@ -96,12 +95,12 @@ npm run build
 node dist/cli.js openai-tools examples --context examples/support/openai/context.support_agent.json
 ```
 
-The command prints JSON containing `tools`, `bindings`, `excluded`, and
-`diagnostics`. It exits nonzero for invalid manifests, missing or invalid
-context JSON, tool-name collisions, or when no tools are exportable.
+The command prints JSON containing `tools`, `bindings`, `excluded`, and `diagnostics`.
+It exits nonzero for invalid manifests, missing or invalid context JSON, tool-name
+collisions, or when no tools are exportable.
 
 ## Reference Basis
 
-OpenAI Responses accepts function tools in the request `tools` array. Function
-tools use JSON Schema parameters, and strict schema adherence is recommended for
-reliable function calling.
+OpenAI Responses accepts function tools in the request `tools` array. Function tools use
+JSON Schema parameters, and strict schema adherence is recommended for reliable function
+calling.