@arnilo/prism 0.0.12 → 0.0.14

package/docs/providers/alibaba.md

@@ -0,0 +1,179 @@
+# Alibaba Cloud provider package
+
+## What it does
+
+`@arnilo/prism-provider-alibaba` is a side-effect-free adapter for Alibaba Cloud
+Model Studio / DashScope (including the Coding Plan) over the **OpenAI-compatible**
+`POST {base}/chat/completions` endpoint.
+
+- **Dynamic model discovery** — `listAlibabaModels()` calls the OpenAI-compatible
+  `GET {base}/models`. No model catalog is hard-coded in the package: available
+  models vary by region, workspace, and billing plan, so discovery is the source of
+  truth. Package setup never fetches.
+- **Context cache** — DashScope implicit prefix caching is automatic. Explicit
+  caching is opt-in via Anthropic-style `cache_control: {"type":"ephemeral"}`
+  markers (at most 4 per request). Cache hits are accounted from
+  `usage.prompt_tokens_details.cached_tokens` (read) and
+  `cache_creation_input_tokens` (write).
+- **Qwen thinking** — `enable_thinking` passthrough toggles reasoning on Qwen models.
+
+The API key is region/plan-scoped: it must match the base URL's billing plan
+(pay-as-you-go regional, workspace-dedicated, or Coding Plan).
+
+## When to use it
+
+Use it when a host app wants Alibaba Cloud Qwen models (Model Studio / DashScope or
+the Coding Plan) through Prism's `AgentSession` runtime with OpenAI-compatible
+serialization, dynamic model discovery, and explicit/implicit cache accounting.
+
+Do not use it for automatic credential discovery, setup-time catalog fetches, or
+real-network tests (live tests stay opt-in).
+
+## Inputs / request
+
+```ts
+import {
+  createAlibabaProviderPackage,
+  createAlibabaProvider,
+  listAlibabaModels,
+  defineAlibabaModel,
+  alibabaBaseUrl,
+} from "@arnilo/prism-provider-alibaba";
+
+createAlibabaProviderPackage(options: AlibabaProviderPackageOptions): ProviderPackage
+createAlibabaProvider(options?: AlibabaProviderOptions): AIProvider
+listAlibabaModels(options?: ListAlibabaModelsOptions): Promise<ModelConfig[]>
+defineAlibabaModel(config: AlibabaModelConfig): ModelConfig
+alibabaBaseUrl(options?: { baseUrl?: string; preset?: AlibabaBasePreset }): string
+```
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `apiKey` | `CredentialValueSource` | DashScope API key (`DASHSCOPE_API_KEY`), region/plan-scoped. |
+| `baseUrl` | `string` | Explicit OpenAI-compatible base URL (wins over `preset`). |
+| `preset` | `AlibabaBasePreset` | `"singapore"` (default) / `"beijing"` / `"us"` / `"coding-plan"`. |
+| `fetch` | `typeof fetch` | Optional fetch implementation for tests/hosts. |
+| `id` | `string` | Provider id (default `alibaba`). |
+| `models` | `readonly ModelConfig[]` | Host-supplied models (from `listAlibabaModels`) to register. |
+
+Base URLs resolved by preset:
+
+| Preset | Base URL |
+| --- | --- |
+| `singapore` | `https://dashscope-intl.aliyuncs.com/compatible-mode/v1` |
+| `beijing` | `https://dashscope.aliyuncs.com/compatible-mode/v1` |
+| `us` | `https://dashscope-us.aliyuncs.com/compatible-mode/v1` |
+| `coding-plan` | `https://coding-intl.dashscope.aliyuncs.com/v1` |
+
+Workspace-dedicated endpoints
+(`https://{workspaceId}.{region}.maas.aliyuncs.com/compatible-mode/v1`) are supplied
+verbatim via `baseUrl`.
+
+## Outputs / response / events
+
+| Surface | Behavior |
+| --- | --- |
+| Stream | Prism text deltas, `delta.reasoning_content` → thinking deltas, tool-call delta/final, `usage`, `done`, redacted `error`. |
+| Usage | `prompt_tokens`/`completion_tokens`/`total_tokens`; `prompt_tokens_details.cached_tokens` → `cacheReadTokens`, `cache_creation_input_tokens` → `cacheWriteTokens`. |
+| Discovery | `listAlibabaModels()` maps `GET {base}/models` entries → `ModelConfig` (reasoning/vision inferred from id). |
+| Auth methods | `api_key` for `alibaba`. |
+
+The stream parser emits `done` only on completion evidence (`[DONE]` plus a terminal
+`finish_reason` with no dangling tool calls). Truncated streams terminate with an
+`error` event instead. Unsupported block placements or unclaimed images fail before
+fetch.
+
+## Request/response example
+
+```bash
+curl 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions' \
+  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "qwen-plus",
+    "messages": [{ "role": "user", "content": "Hello" }],
+    "stream": true,
+    "stream_options": { "include_usage": true }
+  }'
+```
+
+Usage in the final streamed chunk:
+
+```json
+{
+  "usage": {
+    "prompt_tokens": 100,
+    "completion_tokens": 5,
+    "total_tokens": 105,
+    "prompt_tokens_details": { "cached_tokens": 80, "cache_creation_input_tokens": 10 }
+  }
+}
+```
+
+## Implementation example
+
+```ts
+import { createExtensionKernel } from "@arnilo/prism";
+import {
+  createAlibabaProviderPackage,
+  listAlibabaModels,
+} from "@arnilo/prism-provider-alibaba";
+
+const kernel = createExtensionKernel();
+
+// Caller-gated discovery — never runs during setup.
+const models = await listAlibabaModels({ apiKey: process.env.DASHSCOPE_API_KEY });
+
+await kernel.load([
+  createAlibabaProviderPackage({
+    apiKey: process.env.DASHSCOPE_API_KEY,
+    preset: "singapore", // or "coding-plan" with a Coding Plan key
+    models,
+  }),
+]);
+```
+
+## Extension and configuration notes
+
+- Hosts choose base URL/preset, provider id, model list, credential source, and
+  `fetch` impl. Nothing is hard-coded; register discovered models via `models:`.
+- Qwen thinking: `compat.enable_thinking` (request wins over model default) maps to
+  the top-level `enable_thinking` wire field; omitted unless explicitly boolean.
+- Provider-owned compat keys (`route`, `enable_thinking`, `alibaba`) are stripped
+  before the opaque `compat` spread so they never leak into wire bodies.
+
+### Cache behavior
+
+- **Implicit** prefix caching is automatic upstream and sends no markers.
+- **Explicit** caching is opt-in: when `ModelConfig.cache.kind === "cache_control"`
+  (or `cache.mode === "on"`) and the caller supplies
+  `ProviderRequestOptions.cache.breakpoints`, `cache_control: {"type":"ephemeral"}`
+  markers land on the last content block of each selected message, capped at
+  `ALIBABA_MAX_CACHE_BREAKPOINTS` (4). Each cached prefix needs ≥1024 tokens and
+  lives ~5 minutes upstream.
+- Usage accounting: `cached_tokens` → `Usage.cacheReadTokens`,
+  `cache_creation_input_tokens` → `Usage.cacheWriteTokens`.
+
+## Security and performance notes
+
+- SSE streams and HTTP error bodies use bounded `@arnilo/prism/providers/transport`
+  helpers (`readSseData`, `readBoundedResponseText`).
+- No network calls during import, setup, build, or default tests.
+- No automatic environment, file, keychain, or shell credential lookup.
+- The API key is resolved per request via `resolveCredentialValue` and sent only as
+  `Authorization: Bearer`; keys are redacted from all thrown errors (including
+  discovery failures). No local filesystem paths enter request payloads.
+- Caller-supplied `ProviderRequest.options.headers` can add non-owned headers, but
+  provider-owned headers (`content-type`, `authorization`) are applied last and
+  cannot be overridden.
+- Model discovery is caller-gated and never invoked in the provider hot path.
+- Live tests stay opt-in; default tests are network-free.
+
+## Related APIs
+
+- [Provider packages](../provider-packages.md): `defineProviderPackage`,
+  caller-gated discovery, OpenAI-compatible routes.
+- [Provider caching](../provider-caching.md): explicit/implicit matrix.
+- [Credentials and redaction](../credentials-and-redaction.md):
+  `resolveCredentialValue`, `redactSecrets`.
+- [Provider conformance](../provider-conformance.md): network-free adapter tests.

package/docs/providers/azure.md

@@ -0,0 +1,74 @@
+# Azure OpenAI / Foundry
+
+## What it does
+
+`@arnilo/prism-provider-azure` registers an Azure OpenAI / Foundry Chat Completions provider that uses host-supplied Entra workload identity (Bearer) or Azure resource keys (`api-key`). Deployment URLs keep the configured endpoint host (custom subdomain, private endpoint, or VNet FQDN).
+
+## When to use it
+
+Use it for enterprise Azure OpenAI / Foundry deployments with Managed Identity or host token providers. Do not fold this into consumer OpenAI packages. Do not embed static keys in fixtures.
+
+## Inputs / request
+
+```ts
+import { createAzureOpenAIProviderPackage } from "@arnilo/prism-provider-azure";
+
+createAzureOpenAIProviderPackage({
+  endpoint: "https://my-resource.openai.azure.com",
+  deployment: "gpt-4o",
+  apiVersion: "2024-10-21",
+  credential: hostEntraToken, // late-bound
+  authStyle: "bearer",
+  models: [{ provider: "azure", model: "gpt-4o" }],
+});
+```
+
+| Field | Meaning |
+| --- | --- |
+| `endpoint` | Absolute https resource URL; host preserved |
+| `deployment` | Deployment name (defaults to `model.model`) |
+| `apiVersion` | Query `api-version` (default `2024-10-21`) |
+| `credential` | `CredentialValueSource` — Entra token or resource key |
+| `authStyle` | `bearer` (default) or `api-key` |
+
+## Outputs / response / events
+
+Reuses `@arnilo/prism/providers/openai-compatible` streaming events (text, tool deltas, usage, done, redacted errors). Missing credentials fail closed before `fetch`.
+
+## Request/response example
+
+```http
+POST https://my-resource.privatelink.openai.azure.com/openai/deployments/gpt-4o/chat/completions?api-version=2024-10-21
+Authorization: Bearer <entra-token>
+```
+
+## Implementation example
+
+```ts
+const provider = createAzureOpenAIProvider({
+  endpoint: process.env.AZURE_OPENAI_ENDPOINT!,
+  deployment: "gpt-4o",
+  credential: () => entra.getToken("https://cognitiveservices.azure.com/.default").then((t) => t.token),
+});
+```
+
+Opt-in live canaries: inject real `fetch` + host credential behind host CI secrets — no secrets in repo.
+
+## Extension and configuration notes
+
+Register via `createExtensionKernel().load([createAzureOpenAIProviderPackage(...)])`. Pair with `@arnilo/prism-model-router` for residency allow-lists on Azure regions/endpoints.
+
+## Security and performance notes
+
+- No credential prefetch at import; resolve per request.
+- Endpoint host is never rewritten to public DNS.
+- Errors redact credential values via shared transport helpers.
+- No Azure SDK dependency.
+
+## Related APIs
+
+- [OpenAI-compatible provider](openai-compatible.md)
+- [Provider packages](../provider-packages.md)
+- [Model routing](../model-routing.md)
+- [Credential storage](../credential-storage.md)
+- Package README: [`@arnilo/prism-provider-azure`](../../packages/provider-azure/README.md)

package/docs/providers/bedrock.md

@@ -0,0 +1,72 @@
+# Amazon Bedrock
+
+## What it does
+
+`@arnilo/prism-provider-bedrock` registers an Amazon Bedrock Runtime OpenAI-compatible Chat Completions provider. Hosts supply IAM/IRSA/assumed-role credentials; the package signs requests with SigV4 (no AWS SDK). Region and optional PrivateLink endpoint URLs are preserved.
+
+## When to use it
+
+Use it for enterprise Bedrock access under workload identity. Do not embed long-lived keys in fixtures. Use model-router residency policy to deny disallowed regions.
+
+## Inputs / request
+
+```ts
+import { createBedrockProviderPackage } from "@arnilo/prism-provider-bedrock";
+
+createBedrockProviderPackage({
+  region: "eu-west-1",
+  // endpoint: "https://vpce-….bedrock-runtime.eu-west-1.vpce.amazonaws.com",
+  credential: () => hostAwsCredentials(),
+  models: [{ provider: "bedrock", model: "anthropic.claude-3-haiku-20240307-v1:0" }],
+});
+```
+
+| Field | Meaning |
+| --- | --- |
+| `region` | AWS region for signing + default endpoint |
+| `endpoint` | Optional https PrivateLink / VPC interface base URL |
+| `credential` | `{ accessKeyId, secretAccessKey, sessionToken? }` or async callback |
+| `signRequest` | Optional host SigV4 override |
+
+Default public base: `https://bedrock-runtime.{region}.amazonaws.com` → `/openai/v1/chat/completions`.
+
+## Outputs / response / events
+
+OpenAI-compatible SSE mapped to Prism provider events. Missing credentials fail closed before network I/O.
+
+## Request/response example
+
+```http
+POST https://bedrock-runtime.eu-west-1.amazonaws.com/openai/v1/chat/completions
+Authorization: AWS4-HMAC-SHA256 Credential=…/eu-west-1/bedrock/aws4_request, …
+X-Amz-Security-Token: …
+```
+
+## Implementation example
+
+```ts
+const provider = createBedrockProvider({
+  region: "us-east-1",
+  credential: async () => fromNodeProviderChain()(),
+});
+```
+
+Live canaries stay opt-in behind host credentials; default tests are network-free.
+
+## Extension and configuration notes
+
+Uses Bedrock’s OpenAI-compatible runtime route (not Converse eventstream). Hosts needing Converse-only models should supply a custom provider or AI SDK bridge.
+
+## Security and performance notes
+
+- No AWS SDK; package-local SigV4 only for `bedrock` service.
+- Private endpoint hosts are not rewritten to public DNS.
+- Credential secrets are redacted from provider errors.
+- No credential prefetch at import.
+
+## Related APIs
+
+- [OpenAI-compatible provider](openai-compatible.md)
+- [Model routing](../model-routing.md)
+- [Provider packages](../provider-packages.md)
+- Package README: [`@arnilo/prism-provider-bedrock`](../../packages/provider-bedrock/README.md)

package/docs/providers/google.md

@@ -82,6 +82,7 @@ api.registerProviderPackage(createGoogleProviderPackage({ apiKey: hostKey, model
 
 ## Related APIs
 
+- [Google Vertex AI](vertex.md): enterprise ADC/workload-identity package (separate from this consumer API-key package).
 - [Provider packages](../provider-packages.md): package setup + discovery contract.
 - [Thinking and reasoning](../thinking-and-reasoning.md): portable thinking helpers.
 - [Provider conformance](../provider-conformance.md): network-free assertions.

package/docs/providers/ollama.md

@@ -0,0 +1,166 @@
+# Ollama Cloud provider package
+
+## What it does
+
+`@arnilo/prism-provider-ollama` is a side-effect-free adapter for Ollama — both
+**Ollama Cloud** (`https://ollama.com`) and a **local** `ollama serve`
+(`http://localhost:11434`) — over the OpenAI-compatible
+`POST {base}/chat/completions` endpoint.
+
+- **Dynamic model discovery** — `listOllamaModels()` calls the OpenAI-compatible
+  `GET {base}/models`. No model catalog is hard-coded: available models vary by cloud
+  account or local pull, so discovery is the source of truth. Package setup never
+  fetches. (The native `GET {base}/api/tags` endpoint is an alternate catalog source;
+  Prism uses the OpenAI-compatible route for a uniform shape.)
+- **Implicit cache only** — Ollama reuses its KV/prompt cache automatically. There is
+  no request knob and no cached-token count in usage, so `Usage.cacheReadTokens` is
+  intentionally left undefined (documented ceiling below).
+- **Reasoning** — `reasoning_effort` passthrough (e.g. gpt-oss models).
+
+Cloud auth is an ollama.com API key sent as `Authorization: Bearer`; local instances
+are typically unauthenticated (omit the key).
+
+## When to use it
+
+Use it when a host app wants Ollama Cloud or local Ollama models through Prism's
+`AgentSession` runtime with OpenAI-compatible serialization and dynamic model
+discovery.
+
+Do not use it for automatic credential discovery, setup-time catalog fetches, explicit
+cache control (Ollama has none), or real-network tests (live tests stay opt-in).
+
+## Inputs / request
+
+```ts
+import {
+  createOllamaProviderPackage,
+  createOllamaProvider,
+  listOllamaModels,
+  defineOllamaModel,
+  ollamaBaseUrl,
+} from "@arnilo/prism-provider-ollama";
+
+createOllamaProviderPackage(options: OllamaProviderPackageOptions): ProviderPackage
+createOllamaProvider(options?: OllamaProviderOptions): AIProvider
+listOllamaModels(options?: ListOllamaModelsOptions): Promise<ModelConfig[]>
+defineOllamaModel(config: OllamaModelConfig): ModelConfig
+ollamaBaseUrl(options?: { baseUrl?: string; preset?: OllamaBasePreset }): string
+```
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `apiKey` | `CredentialValueSource` | Ollama Cloud API key; omit for unauthenticated local. |
+| `baseUrl` | `string` | Explicit OpenAI-compatible base URL (wins over `preset`). |
+| `preset` | `OllamaBasePreset` | `"cloud"` (default) / `"local"`. |
+| `fetch` | `typeof fetch` | Optional fetch implementation for tests/hosts. |
+| `id` | `string` | Provider id (default `ollama`). |
+| `models` | `readonly ModelConfig[]` | Host-supplied models (from `listOllamaModels`) to register. |
+
+Base URLs resolved by preset (each includes the `/v1` segment):
+
+| Preset | Base URL |
+| --- | --- |
+| `cloud` | `https://ollama.com/v1` |
+| `local` | `http://localhost:11434/v1` |
+
+## Outputs / response / events
+
+| Surface | Behavior |
+| --- | --- |
+| Stream | Prism text deltas, `delta.reasoning_content` → thinking deltas, tool-call delta/final, `usage`, `done`, redacted `error`. |
+| Usage | `prompt_tokens` → `inputTokens`, `completion_tokens` → `outputTokens` (native `prompt_eval_count`/`eval_count` are the equivalent). `cacheReadTokens` stays undefined. |
+| Discovery | `listOllamaModels()` maps `GET {base}/models` entries → `ModelConfig` (reasoning/vision inferred from id). |
+| Auth methods | `api_key` for `ollama`. |
+
+The stream parser emits `done` only on completion evidence (`[DONE]` plus a terminal
+`finish_reason` with no dangling tool calls). Truncated streams terminate with an
+`error` event instead. Unsupported block placements or unclaimed images fail before
+fetch.
+
+## Request/response example
+
+```bash
+curl 'https://ollama.com/v1/chat/completions' \
+  -H "Authorization: Bearer $OLLAMA_API_KEY" \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "gpt-oss:20b",
+    "messages": [{ "role": "user", "content": "Hello" }],
+    "stream": true,
+    "stream_options": { "include_usage": true }
+  }'
+
+curl 'https://ollama.com/v1/models' -H "Authorization: Bearer $OLLAMA_API_KEY"
+```
+
+Usage in the final streamed chunk:
+
+```json
+{ "usage": { "prompt_tokens": 100, "completion_tokens": 5, "total_tokens": 105 } }
+```
+
+## Implementation example
+
+```ts
+import { createExtensionKernel } from "@arnilo/prism";
+import {
+  createOllamaProviderPackage,
+  listOllamaModels,
+} from "@arnilo/prism-provider-ollama";
+
+const kernel = createExtensionKernel();
+
+// Caller-gated discovery — never runs during setup.
+const models = await listOllamaModels({ apiKey: process.env.OLLAMA_API_KEY });
+
+await kernel.load([
+  createOllamaProviderPackage({
+    apiKey: process.env.OLLAMA_API_KEY, // omit for local
+    preset: "cloud", // or "local"
+    models,
+  }),
+]);
+```
+
+## Extension and configuration notes
+
+- Hosts choose base URL/preset, provider id, model list, credential source, and
+  `fetch` impl. Nothing is hard-coded; register discovered models via `models:`.
+- Reasoning: `compat.reasoning_effort` (request wins over model default) maps to the
+  top-level `reasoning_effort` wire field; omitted unless explicitly a string.
+- Provider-owned compat keys (`route`, `reasoning_effort`, `ollama`) are stripped
+  before the opaque `compat` spread so they never leak into wire bodies.
+
+### Cache behavior
+
+- **Implicit only.** Ollama reuses its KV/prompt cache automatically; there is no
+  request knob and no wire marker. Prism never emits `cache_control` for Ollama.
+- **Documented ceiling:** Ollama exposes no cached-token count, so
+  `Usage.cacheReadTokens` is intentionally left `undefined` (not `0`). If a future
+  Ollama release reports cached tokens, map them in `mapOllamaModel`/usage handling.
+
+## Security and performance notes
+
+- SSE streams and HTTP error bodies use bounded `@arnilo/prism/providers/transport`
+  helpers (`readSseData`, `readBoundedResponseText`).
+- No network calls during import, setup, build, or default tests.
+- No automatic environment, file, keychain, or shell credential lookup.
+- The cloud API key is resolved per request via `resolveCredentialValue` and sent only
+  as `Authorization: Bearer`; keys are redacted from all thrown errors (including
+  discovery failures). Local presets send no auth header when no key is configured.
+  No local filesystem paths enter request payloads.
+- Caller-supplied `ProviderRequest.options.headers` can add non-owned headers, but
+  provider-owned headers (`content-type`, `authorization`) are applied last and
+  cannot be overridden.
+- Model discovery is caller-gated and never invoked in the provider hot path.
+- Live tests stay opt-in; default tests are network-free.
+
+## Related APIs
+
+- [Provider packages](../provider-packages.md): `defineProviderPackage`,
+  caller-gated discovery, OpenAI-compatible routes.
+- [Provider caching](../provider-caching.md): explicit/implicit matrix (Ollama =
+  implicit only).
+- [Credentials and redaction](../credentials-and-redaction.md):
+  `resolveCredentialValue`, `redactSecrets`.
+- [Provider conformance](../provider-conformance.md): network-free adapter tests.

package/docs/providers/openai-compatible.md

@@ -27,9 +27,11 @@ Options:
 | Field | Type | Purpose |
 | --- | --- | --- |
 | `id` | `string` | Optional provider id. Defaults to `openai-compatible`. |
-| `baseUrl` | `string` | Base API URL; `/chat/completions` is appended. |
+| `baseUrl` | `string` | Base API URL; `/chat/completions` is appended unless `chatCompletionsUrl` is set. |
 | `apiKey` | `CredentialValueSource` | Optional direct/callback/resolver credential source. |
 | `fetch` | `typeof fetch` | Optional fetch implementation for tests or custom hosts. |
+| `chatCompletionsUrl` | `string \| ((request) => string)` | Optional full chat-completions URL override (Azure deployment paths). |
+| `authStyle` | `"bearer" \| "api-key" \| "none"` | Auth header style. Default `bearer`. |
 
 Provider requests use the standard `ProviderRequest` shape: `model`, `messages`, optional `tools`, `metadata`, and `signal`.
 

package/docs/providers/openrouter.md

@@ -188,9 +188,11 @@ cache-read pricing exists), and seeds `compat.reasoning.effort` from
   hidden app identity.
 - Live tests stay opt-in behind `PRISM_LIVE_PROVIDER_TESTS=1` plus fake-safe
   provider-specific env names; default tests are network-free.
+- Enterprise hosts that must gate `compat.openRouterRouting` should wrap selection with `@arnilo/prism-model-router` (`allowOpenRouterRouting`); the OpenRouter adapter itself still passthroughs routing when present on the request.
 
 ## Related APIs
 
+- [Model routing](../model-routing.md): optional allow-list/residency/budget/circuit facade and OpenRouter routing gate.
 - [Provider packages](../provider-packages.md): `defineProviderPackage`,
   `ModelConfig`/`compat`, cache policy, caller-gated discovery.
 - [Thinking and reasoning](../thinking-and-reasoning.md): `applyThinkingLevel`

package/docs/providers/vertex.md

@@ -0,0 +1,71 @@
+# Google Vertex AI
+
+## What it does
+
+`@arnilo/prism-provider-vertex` registers a Vertex AI OpenAPI-compatible Chat Completions provider authenticated with host ADC / workload identity tokens. It is intentionally separate from `@arnilo/prism-provider-google` (consumer Gemini API keys).
+
+## When to use it
+
+Use it for GCP enterprise Vertex deployments with Application Default Credentials or workload identity federation. Do not use the consumer Google package for Vertex auth semantics.
+
+## Inputs / request
+
+```ts
+import { createVertexProviderPackage } from "@arnilo/prism-provider-vertex";
+
+createVertexProviderPackage({
+  projectId: "my-gcp-project",
+  location: "europe-west1",
+  credential: () => hostAdcAccessToken(),
+  models: [{ provider: "vertex", model: "google/gemini-2.0-flash-001" }],
+});
+```
+
+| Field | Meaning |
+| --- | --- |
+| `projectId` | GCP project |
+| `location` | Vertex location / region |
+| `endpoint` | Optional full https OpenAPI base (private/custom); otherwise location-scoped default |
+| `credential` | Bearer access token source (ADC / WIF) |
+
+Default base: `https://{location}-aiplatform.googleapis.com/v1/projects/{project}/locations/{location}/endpoints/openapi`.
+
+## Outputs / response / events
+
+OpenAI-compatible SSE → Prism provider events. Missing ADC token fails closed before `fetch`.
+
+## Request/response example
+
+```http
+POST https://europe-west1-aiplatform.googleapis.com/v1/projects/my-gcp-project/locations/europe-west1/endpoints/openapi/chat/completions
+Authorization: Bearer <adc-token>
+```
+
+## Implementation example
+
+```ts
+const provider = createVertexProvider({
+  projectId: "my-gcp-project",
+  location: "us-central1",
+  credential: async () => (await GoogleAuth.getAccessToken()),
+});
+```
+
+## Extension and configuration notes
+
+`@arnilo/prism-provider-google` remains API-key Gemini (`generativelanguage.googleapis.com`) and must not register Vertex OAuth/ADC. Load this package explicitly for Vertex.
+
+## Security and performance notes
+
+- No Google Cloud SDK dependency in the package.
+- Custom/private endpoint hosts are preserved.
+- Tokens redacted from errors; no import-time credential prefetch.
+- Pair with model-router residency allow-lists on `location`.
+
+## Related APIs
+
+- [Google Gemini (consumer)](google.md)
+- [OpenAI-compatible provider](openai-compatible.md)
+- [Provider packages](../provider-packages.md)
+- [Model routing](../model-routing.md)
+- Package README: [`@arnilo/prism-provider-vertex`](../../packages/provider-vertex/README.md)

package/docs/public-contracts.md

@@ -15,7 +15,8 @@ Current contract groups:
 - Extensions/middleware: `ExtensionLifecycleEventName`, `ExtensionEvent`, `Extension`, `ExtensionAPI`, `MiddlewareHookName`, `Middleware`, `MiddlewareNext`, `MiddlewareRegistry`
 - Configuration/manifests: `ConfigProvider`, `ConfigLayer`, `ConfigLoadContext`, `PrismManifest`, `ManifestContributionDeclaration`, `ManifestResourceDeclaration`, `ManifestContributionKind`
 - Stores/resources/settings/credentials/compaction/retry/cache helpers: `SessionEntry`, `SessionStore`, `StoreFactory`, `Resource`, `ResourceLoader`, `ResourceLoadContext`, `SettingsProvider`, `CredentialRequest`, `Credential`, `CredentialResolver`, `CompactionStrategy`, `CompactionContext`, `CompactionResult`, `CompactionOptions`, `CompactionMiddlewarePayload`, `CompactionEntryData`, `DefaultCompactionStrategyOptions`, `RetryPolicy`, `RetryContext`, `RetryDecision`, `RetryOptions`, `RetryMiddlewarePayload`, `DefaultRetryPolicyOptions`, `CacheUsageReport`, `sanitizeCacheKey`, `mapCacheRetention`, `applyCacheControl`, `cacheHitRate`, `cacheSavings`, `cacheUsageReport`
-- Production persistence (adapter-facing): `ProductionPersistenceStore`, `CheckpointStore`, `CheckpointKey`, `CheckpointSaveInput`, `CheckpointRecord`, `CheckpointQuery`, `LeaseStore`, `LeaseKey`, `LeaseAcquireInput`, `LeaseClaimInput`, `LeaseRecord`, `PersistencePage`, `PersistenceQuery`, `OwnershipScope`, `SessionRecord`, `SessionQuery`, `BranchRecord`, `BranchQuery`, `SessionEntryQuery`, `RunRecord`, `RunQuery`, `RunFeedbackRecord`, `RunFeedbackStore`, `RunFeedbackQuery`, `AgentEventRecord`, `AgentEventQuery`, `ToolCallRecord`, `ToolCallQuery`, `UsageRecord`, `UsageQuery`, `AgentDefinitionRecord`, `AgentDefinitionQuery`, `RetentionPolicy`, `RetentionPolicyQuery`, `MigrationRecord`, `MigrationQuery`
+- Production persistence (adapter-facing): `ProductionPersistenceStore` (optional `lifecycle`), `CheckpointStore`, `CheckpointKey`, `CheckpointSaveInput`, `CheckpointRecord`, `CheckpointQuery`, `LeaseStore`, `LeaseKey`, `LeaseAcquireInput`, `LeaseClaimInput`, `LeaseRecord`, `PersistencePage`, `PersistenceQuery`, `OwnershipScope`, `SessionRecord`, `SessionQuery`, `BranchRecord`, `BranchQuery`, `SessionEntryQuery`, `RunRecord`, `RunQuery`, `RunFeedbackRecord`, `RunFeedbackStore`, `RunFeedbackQuery`, `AgentEventRecord`, `AgentEventQuery`, `ToolCallRecord`, `ToolCallQuery`, `UsageRecord`, `UsageQuery`, `AgentDefinitionRecord`, `AgentDefinitionQuery`, `RetentionPolicy`, `RetentionPolicyQuery`, `MigrationRecord`, `MigrationQuery`, `PersistenceLifecycleStore`, `LegalHoldRecord`, `TenantQuota`
+- Identity: `Principal`, `AgentIdentity`, `IdentityVerifier`, `assertIdentityActive`, `narrowIdentity`, `ownershipFromIdentity`, `assertIdentityMatchesOwnership`, `assertIdentityPropagation`, `identityTelemetryAttributes`, `resolveRunIdentity`, `IdentityError`, identity limit constants
 
 ## When to use it
 
@@ -165,6 +166,7 @@ Important request shapes:
 | `CacheUsageReport` | Numeric cache diagnostics from normalized `Usage`: read/write tokens, hit rate, estimated savings, and optional currency. |
 | `AgentDefinitionRecord` / `AgentDefinitionQuery` | Versioned agent-definition snapshot and filters. Does not store credentials or provider instances. |
 | `RetentionPolicy` / `RetentionPolicyQuery` | Retention policy and filters: age, entry count, byte limits, archive store, applied kinds. |
+| `PersistenceLifecycleStore` / `LegalHoldRecord` / `TenantQuota` | Optional hold/retention apply/export/quota capability on `ProductionPersistenceStore.lifecycle`. |
 | `MigrationRecord` / `MigrationQuery` | Applied migration record and filters. |
 
 ## Outputs / response / events