# Vincio

> Vincio is a Python platform for context-engineered AI applications. It
> compiles prompts, memory, retrieval, tools, schemas, and policies into
> optimized, validated, observable, provider-neutral context packets, then
> validates and evaluates every output.

Package: `pip install vincio` · Python 3.11+ · Apache 2.0 · SemVer.
Main entry point: `from vincio import ContextApp`.

## Quickstart

```python
from vincio import ContextApp

app = ContextApp(name="docs_qa")
app.add_source("docs", path="./docs", retrieval="hybrid")
app.set_policy("answer_only_from_sources", True)
result = app.run("How do I configure SSO?")
result.output; result.citations; result.trace_id; result.cost_usd

# Typed output: pass a Pydantic class; result.output is a validated instance.
from pydantic import BaseModel
class Triage(BaseModel):
    label: str; confidence: float
app = ContextApp(name="triage", output_schema=Triage)
app.run("export button 500s").output.label

# Offline by default: with no provider/key, a deterministic mock emits
# schema-valid output, so the whole pipeline runs in CI without network.
```

## Mental model

- **Pydantic v2 everywhere.** Every public data contract (`RunResult`, `Budget`,
  `EvidenceItem`, `MemoryItem`, `EvalReport`, …) is a Pydantic v2 model.
- **Async-first with sync wrappers.** Every engine has `arun`/async methods; the
  sync `run()` is a thin wrapper and needs no running loop. Stream with
  `async for event in app.astream(...)`.
- **One run pipeline.** `app.run()` executes: normalize → classify → policy →
  memory recall → retrieve → compile context (score/dedupe/conflict/compress/
  budget) → compile prompt (cache-aware) → model (+bounded tool loop) → validate
  (schema/citations/policy, principled repair) → evaluate → trace → memory write.
- **Deterministic where it matters.** Security, permissions, validation, and
  budgets are enforced in code, never gated on model output.
- **One trace, one audit chain.** Every run yields a span tree, a cost, and a
  hash-chained audit entry; metrics, optimization, governance all ride them.
- **Extend via registries.** Providers, metrics, chunkers, rerankers, judges,
  validators, tools, connectors, packs all accept your own implementation;
  third-party packages auto-register on install via the versioned entry-point
  plugin contract (`vincio.{providers,embedders,stores,connectors,chunkers,
  rerankers,metrics,judges,packs}`; `vincio plugins list`, `load_plugins()`).
- **Two surfaces, same impl.** The flat `app.<method>` API and lazy capability
  facades (`app.runs` / `.knowledge` / `.governance` / `.optimization` /
  `.serving` / `.training`) both work.

## Core: ContextApp & the run pipeline

- **Run / stream / submit.** `app.run(input, *, session_id=, tenant_id=, user_id=,
  feature=, config=RunConfig(...))` → `RunResult` (`.output`, `.citations`,
  `.trace_id`, `.cost_usd`, `.raw_text`). `app.astream("...")` yields `stage`,
  `text_delta`, `partial_output` (incremental partial-JSON with `valid_prefix` /
  `validation_errors`), `tool_*`, then `done` with the full `RunResult` (the
  server SSE endpoint emits the same events). `app.submit(...)` → `RunHandle`
  whose `cancel()` propagates cooperative cancellation and still records the run.
- **Budgets are hard caps.** Caps live on a `Budget` (`from vincio import
  Budget`) passed via `RunConfig(budget=Budget(max_cost_usd=, max_input_tokens=,
  max_output_tokens=, max_steps=, max_tool_calls=, max_latency_ms=,
  max_retries=))`; breaches raise `BudgetExceededError` (pre-flight input-token
  check; on the same audit chain as policy/residency).
  `RunConfig(enforce_budget_caps=False)` restores the legacy soft cap. Sub-quadratic
  hot paths (inverted-index BM25, incremental MMR `_select`, memoized
  `count_tokens`, optional numpy vector path); `InMemoryMetadataStore` is
  async-native (`asave`/`aget`/`aquery`/`adelete`/`acount`) and every run path
  (interactive/streaming/batch) persists through the async store contract.
- **Reasoning control.** `RunConfig(reasoning_effort="low|medium|high")` /
  `thinking_budget_tokens` map across OpenAI/Anthropic/Gemini; thinking tokens
  are billed. Optional `OpenAIResponsesProvider` via
  `build_provider("openai_responses")`.
- **Reasoning controller (auto effort).** `app.use_reasoning_controller(policy=ReasoningPolicy(...))`
  installs a `ReasoningController` (`vincio.agents`): a run that does not pin
  `reasoning_effort` gets effort + a thinking-token budget chosen per step from
  the task classification and the live budget, clamped to a hard
  `max_reasoning_tokens` ceiling and a `budget_fraction` of the remaining output
  budget. Low prior confidence escalates one level; a warm thinking prefix in the
  `ReasoningTraceCache` steps it down. `app.reasoning()` builds one to call
  `.decide(...)` directly; the decision is recorded on the trace
  (`reasoning_source`, `reasoning_reason`).
- **Reasoning-trace caching.** `ReasoningTraceCache` (`vincio.caching`) is a
  byte-budgeted LRU of paid thinking prefixes keyed by stable-prefix hash + model
  + effort, so a re-ask that shares a thinking prefix reuses it under the
  resident-memory budget — the reasoning analogue of the prompt render program.
- **Test-time search.** `app.test_time_search(input, *, verifier=, strategy="best_of_n"|"self_consistency", n=)`
  or `TestTimeSearch(generate, verifier=, budget=SearchBudget(...))` in
  `vincio.optimize`: verifier-guided best-of-N, self-consistency, and beam search
  over tool-use trajectories, scored by the existing critics via a `Verifier`
  protocol — `JudgeVerifier` (any `Judge`/`JudgeEnsemble`; disagreement → low
  confidence), `RewardVerifier` (any `VerifiableReward`/`RewardModel`), or a
  callable. Early-exits the moment the verifier clears the bar (best-of-N) or the
  majority is locked (self-consistency); bounded by candidate / cost / deadline.
- **Long-horizon context engineering.** `app.use_context_governor(ContextBudget(max_tokens=, max_resident_bytes=, max_kv_cache_bytes=))`
  installs a per-run `ContextGovernor` (`vincio.context`) that holds a context
  budget across million-token, multi-day, multi-session runs: feed each result
  with `app.govern_packet(result)` and read `app.context_budget_report()`
  (`ContextBudgetReport` — live tokens, residency, KV-cache footprint — the
  residency analogue of `cost_report`). `RelevanceDecay` applies the memory
  decay model within one run so stale `RunSpan`s lose weight (surfaced in the
  excluded-context report); a provenance-preserving `ContextCompactor` folds the
  coldest cold spans into hierarchical summaries written to the memory OS and
  pages their full text back on demand from the content-addressed evidence store
  (`recall(query)` pages a compacted needle back). Held by a horizon-scaling SLO:
  at 10× horizon the governed footprint stays flat (vs ~linear naïve growth) and
  recall is preserved (`families.long_horizon`).
- **World-model / simulation-based planning.** `WorldModel(transitions)`
  (`vincio.agents`) is a deterministic dynamics model fit offline from recorded
  reset/step `Transition`s (`record_transitions(env, action_sequences)`). It learns
  each tool's *parameterized* effect (constant / argument / numeric-step value)
  under a learned *precondition* (the discriminative state field), so
  `model.predict(obs, action)` returns a `PredictedStep` that fails a refund on a
  processing order and succeeds on a cancelled one — and generalizes a cancel seen
  on one order to another; `model.imagine(obs, actions)` rolls a plan forward
  without touching a tool. `model.calibrate(holdout)` returns a `CalibrationReport`
  (`state_accuracy`, `reward_mae`, `trusted`, `weight`) that earns planning weight
  only within tolerance. `ModelPredictivePlanner(model, horizon=, beam_width=).plan(env)`
  searches imagined rollouts with the test-time-search beam, commits the best first
  action, observes, and re-plans, returning an `MPCResult`; it refuses an
  uncalibrated model unless `require_calibrated=False`. At a fixed action budget it
  matches or beats reactive (one-step) planning (`families.world_model`). Reference
  worlds: `make_retail_environment`, `make_vault_environment` (a shortcut trap).
- **Causal record-replay debugger.** `Recorder(app).record(input)`
  (`vincio.observability`) runs an app while capturing every non-deterministic edge
  — model responses (by `ModelRequest.hash`), tool outputs (by name+args), retrieval
  hits, the negotiated `ModelCapabilities`, and clock/seed — into a portable,
  content-addressed `Recording` (`recording.put(store)` / `Recording.from_store`,
  `recording.save`/`load`, `recording.verify()` over a `fidelity_digest`).
  `Replayer(app).replay(recording)` serves each edge back so the run replays
  byte-for-byte (the recording, not the live provider, drives it); the
  `ReplayResult` is `faithful` only when no edge diverged and the output is
  byte-identical, and lists every `Divergence` (the edge live code asked for that
  was not recorded). `Replayer(app).branch(recording, edits=[BranchEdit(...)], input=,
  fallback=)` forks a recording and re-executes only the affected suffix while the
  unchanged prefix is still served from the recording (`served_from_recording` vs
  `reexecuted`). `ReplayProvider` is the underlying replay provider. Held by
  `families.record_replay` (replay byte-identical + divergence detected + verifiable).
  CLI: `vincio trace verify-recording <file>`. Distinct from `ReplayRunner` (which
  re-runs a recorded *input* to diff a candidate app, not byte-faithful replay).
- **Learned semantic cache & near-miss KV reuse.** `LearnedSemanticCache`
  (`vincio.caching`, `app.use_semantic_cache(policy_or_cache=None)`) answers a
  *semantically-equivalent* (not byte-identical) request from cache. A
  `lookup(query, policy_scope=, schema_ref=)` embeds the query, finds the best
  in-scope/in-schema, unexpired entry, and serves it (`SemanticCacheHit.value`,
  `.accepted`) **only at/above a calibrated acceptance threshold** — below the bar
  is a recorded-but-never-served near-miss. The threshold is *learned*:
  `ThresholdCalibrator`/`cache.calibrate(examples)` / `await
  cache.calibrate_from_pairs([(q, q2, equivalent), ...])` fits the lowest bar
  (≥ `min_floor`) whose accepted set clears `target_precision`, returning a
  `CalibrationReport` (`calibrated=False` ⇒ threshold `1.0`, i.e. off, rather than
  guess). Every accepted hit is auditable (`cache.audit()`) and reversible
  (`cache.revoke(key)`); the cache is a bounded LRU under the resident-memory budget
  (`SemanticCachePolicy.max_entries` / `max_resident_bytes`), surfaced by
  `cache.stats()` / `app.semantic_cache_report()` (a served near-miss is a $0-billed
  call in the cost report). `SemanticCacheGate(quality_floor=).evaluate(cache,
  [SemanticGateCase(...)])` is the eval-replay no-regression check (the cache
  analogue of the model-swap `SwapGate`): it passes a faithful cache and blocks a
  drifted one. `KVPrefixPool` (`app.use_kv_prefix_reuse()`) accounts cross-request
  reuse of a shared stable-prefix KV footprint — `observe(prefix_hash=, model=,
  prefix_tokens=)` reports the serving-engine KV a shared head avoids recomputing
  (`app.kv_prefix_report()`), bounded under the resident budget. The runtime
  consults both, opt-in, only when installed. Held by `families.semantic_cache`
  (accepted near-miss at-least-as-good + below-bar never served + gate blocks drift).
- **On-device fine-tuning & continual local adaptation.** `LocalLoRATrainer`
  (`vincio.optimize.local_adaptation`) fits a parameter-efficient, low-rank
  `LocalAdapter` **on-device** from a grounded `TrainingSet` — `await
  trainer.fit(training_set, base_model)` embeds each example's prompt, builds a
  rank-`r` orthonormal subspace (the LoRA-class compression: an `r×d` basis plus
  `n×r` codes), and stores the grounded targets; deterministic and dependency-free,
  with an optional `NativeLoRABackend` to also emit a real GGUF/LoRA file (loaded
  via `GGUFProvider(lora_path=)`). `AdaptedProvider(base, adapter, embedder=)`
  wraps any provider: an in-distribution request (`adapter.apply(query_vec)` clears
  the learned `gate`) is answered the grounded way it was taught, off-distribution
  requests fall through to the base model unchanged (bounded; `scale=0.0`
  neutralizes without unloading). `AdapterRegistry` versions adapters
  (content-addressed `adapter.digest`, `register`/`rollback`/`active`, optional
  on-disk persistence). `ContinualAdaptation`/`app.adapt_locally(dataset,
  runs=|training_set=)` runs the gated loop — fit → gate base-vs-adapted on a
  held-out set with `AdapterGate` (reuses the canary no-regression verdict; the
  adapted model must be at-least-as-good) → promote (register + `app.use_local_adapter`)
  or refuse, every decision on the audit chain and event bus. `app.local_adaptation`
  returns the streaming controller. Held by `families.local_adaptation`
  (at-least-as-good + bounded off-distribution + regression refused/reversible).
- **Federated / cross-org self-improvement.** Sharing what a fleet learned
  *across* trust boundaries without sharing raw traffic (`vincio.optimize.federated`).
  Each member builds a `Contribution` with `ContributionBuilder(embedder=, privacy=)`
  /`app.contribute_federated(member_id=, participants=, training_set=|runs=)`: it
  embeds the member's prompts and forms the `d×d` **scatter** (`Σ wᵢ·(vᵢ⊗vᵢ)`, a
  second-moment sufficient statistic of the local subspace), then **clips** it to
  `PrivacyConfig.clip_norm`, optionally adds the **DP** Gaussian mechanism
  (`dp_epsilon`/`dp_delta` → `noise_sigma()`), and folds in **secure-aggregation**
  masks against `participants` — the wire object carries **no prompt and no
  response**, only numbers, plus a consent attestation (TRAINING purpose, enforced
  when `require_consent`) and a residency tag. `SecureAggregator(privacy=, rank=,
  allowed_regions=).aggregate(contributions)` sums the masked updates (pairwise
  masks cancel across the exact participant set, so no individual update is ever
  observed), refuses a round below `min_contributors` (k-anonymity) or with mixed
  base models/dims/disallowed regions, and extracts the consensus `FederatedSubspace`
  by deterministic federated PCA (top eigenvectors of the aggregate scatter).
  `refit_with_subspace(subspace, training_set, embedder=)` re-fits a member's own
  `LocalAdapter` against the shared geometry (fleet basis, the member's own grounded
  targets). `FederatedImprovement`/`app.adopt_federated(dataset, contributions,
  training_set=|runs=)` runs the gated round — aggregate → refit → gate base-vs-adapted
  with the same `AdapterGate` no-regression verdict → adopt (`AdapterRegistry.register`
  + `app.use_local_adapter`) or refuse/rollback, every decision on the audit chain and
  event bus; `app.federated_improvement` returns the streaming controller. Held by
  `families.federated` (no-raw-traffic + secure-aggregation masks cancel/individual
  hidden + k-anonymity + at-least-as-good + regression refused/reversible).
- **Differential-privacy memory & training.** A federated round bounds one member's
  *per-round* influence; this adds the **end-to-end per-subject privacy budget** that
  composes every memory consolidation and learning round a subject's data touches
  (`vincio.governance.privacy`). `app.use_privacy_accountant(default_budget=PrivacyBudget(
  epsilon=, delta=, on_breach="refuse"|"downweight"), default_mechanism=PrivacyMechanism(
  noise_multiplier=, sample_rate=, steps=))` attaches a Rényi/moments `PrivacyAccountant`:
  `gaussian_rdp(z, sample_rate=, steps=)` is the (sub-sampled) Gaussian RDP curve and
  `rdp_to_epsilon(rdp, delta=)` the RDP→`(ε, δ)` conversion, so composing across rounds is
  far tighter than naively summing each step's `ε`. `check(subject, mechanism)` decides
  whether a release fits the subject's remaining budget; `charge(...)` gates **and** commits,
  raising `PrivacyBudgetError` (code `PRIVACY_BUDGET_EXCEEDED`) on a refusal or down-weighting
  by clipping harder (lower sensitivity → lower cost) to fit. It wires in automatically:
  `app.memory.consolidate(session_id, user_id=)` charges the subject and refuses an
  over-budget consolidation (`ConsolidationReport.privacy_refused`/`privacy_epsilon`), and a
  federated `Contribution` composes the **same** budget when `PrivacyConfig.dp_epsilon` is set.
  `app.set_privacy_budget(subject_id=, epsilon=, delta=, on_breach=)` is the one-liner;
  `app.privacy_report(subject=)` rolls up each subject's spent/remaining `ε` next to the cost
  report; every spend (`privacy_spend`) and refusal (`privacy_refused`) is on the audit chain.
  Held by `families.privacy` (Gaussian-RDP-exact + composes-across-rounds + budget-refused +
  per-subject-isolated + downweight-within-budget + consolidation/federated gated +
  per-subject-report + on-audit-chain).
- **Cross-fleet reputation & weighting.** A federated round merges every member with equal
  weight; this adds a per-member **reputation** that discounts an unreliable or adversarial
  member's pull on the shared consensus — earned only from how each contribution fared against
  the no-regression gate, never from raw traffic (`vincio.optimize.reputation`).
  `app.use_reputation_ledger(config=ReputationConfig(prior_success=, prior_failure=, decay=,
  weight_floor=, weight_ceiling=))` attaches a `ReputationLedger` keeping each member's
  reliability as a Beta-Bernoulli posterior over gate outcomes (a robust generalization of the
  existing reliability scoring): `reputation(member)` is the posterior mean, `weight(member)`
  maps it to an aggregation weight in `[weight_floor, 1]`, `record_outcome(member, passed=)`
  composes one verdict, and `assign(members)` produces the round's weight vector.
  `SecureAggregator(reputation=ledger)` weights a member's contribution by its reputation
  **before** the secure-aggregation masks (so they still cancel exactly); a masked contribution
  must carry the assigned weight (built with `ContributionBuilder.build(..., reputation_weight=)`)
  or the aggregator refuses to re-weight it (`FederatedError`). Wires in automatically: when a
  ledger is bound, `app.federated_improvement`/`app.adopt_federated` weight each contribution and
  record the round's gate verdict back (`FederatedPolicy.record_reputation`). Bounded and
  reversible — a weight only ever lowers pull, and adoption still clears the same no-regression
  and canary gates, so reputation never bypasses the quality bar. `ReputationLedger.from_audit(
  audit)` replays the whole ledger from the chain; `app.reputation_report(member=)` rolls up each
  member's standing next to the cost and privacy reports. Held by `families.reputation`
  (discount-the-regressor + weight-bounded/floored + audit-replayable + adopts-at-least-as-good +
  gate-not-bypassed). `ReputationError` inherits `OPTIMIZATION_ERROR`.
- **Energy & carbon accounting.** The cost report makes a run's dollar spend an auditable
  number; this adds the sustainability figure beside it — a per-run **energy** (watt-hours) and
  **carbon** (grams CO₂e) estimate on the *same* cost-report surface, never a new plane
  (`vincio.observability.energy` / `vincio.observability.finops`). Opt in with
  `app.use_energy_accounting(region=, pue=, carbon_intensity=)` (off by default; `result.energy_wh`
  / `result.co2e_grams` stay 0 until enabled). Each run then accrues a **deterministic** estimate
  from its own token accounting: an `EnergyIntensityTable` maps the model to an `EnergyProfile`
  (watt-hours per million tokens, seeded by the `ModelRegistry` tier — decode dominates prefill, a
  stronger tier draws more — and overridable via `.set(model, EnergyProfile(...))`), scales by the
  datacenter `pue`, and multiplies by a per-region grid factor (g CO₂e/kWh, from a built-in
  `DEFAULT_CARBON_INTENSITY` table, overridable via `.set_region_intensity(region, g)`); the region
  is the operator's declared `region=` (pinned), else the residency policy's resolved region, else
  the world average. `app.energy_report(by="model"|"tenant"|"feature"|"user"|"provider"|"run")`
  returns an `EnergyReport` rolled up from the same attributed `CostEvent`s the cost report uses
  (each now carries `energy_wh`/`co2e_grams`), and the figures also surface on
  `app.cost_tracker.summary()`. **Budgeted like a dollar:** `app.set_energy_budget(scope=, id=,
  limit_wh=, limit_co2e_grams=, period=)` adds an `EnergyBudget`; when a scope's accrued energy or
  carbon over the period reaches the ceiling, the run is **refused** the way a hard cost cap refuses
  spend (`EnergyBudgetDecision`, an `energy.budget_exceeded` event, an `energy_budget` audit entry).
  **Auditable & offline:** no external service; the per-run estimate and every refusal land on the
  hash-chained audit log (`run` entries carry `energy_wh`/`co2e_grams` when enabled). Held by
  `families.energy` (per-run-estimate + budget-refused + auditable-offline + decode-dominates +
  tier-monotonic + region-intensity-differs + carbon-tracks-energy + off-by-default +
  on-cost-surface). `EnergyBudgetError` inherits `OBSERVABILITY_ERROR`.
- **Performance.** Bounded concurrent fan-out (`vincio.core.concurrency`),
  content-addressed compile/chunk/embedding caches (on by default), request
  coalescing + pooled transport, slim (zero-copy) packets, hard `max_latency_ms`
  deadline + cancellation propagation. The compile hot path is single-pass and
  allocation-light: a vectorized candidate scorer (`ContextScorer.score_batch`,
  NumPy-optional with an identical pure-Python fallback); a compiled-prompt
  render program (`CompilerOptions.use_render_program`, `program_hits`) reusing
  the rendered stable prefix, and a warm candidate arena
  (`performance.reuse_candidate_set`, `arena_hits`) reusing the prepared
  candidate set — both correctness-preserving; streaming-first compilation
  (`ContextCompiler.compile_streaming` → `CompileStreamEvent`, prefix before
  scoring); opt-in speculative retrieval prefetch
  (`performance.speculative_prefetch`, `SpeculativePrefetcher`) warming the
  query embedding; and a per-app resident-memory budget
  (`performance.memory_budget_mb`) held by slim packets + evidence eviction,
  surfaced as `RunResult.memory_bytes`. VincioBench budgets gate CI incl. a
  sub-millisecond warm-compile gate and a footprint regression gate
  (`benchmarks/check_budgets.py`).

## Prompts & context

- **Prompts.** `PromptSpec`, typed AST, cache-aware compiler (stable-prefix
  layout), lint, variant generation, content-hash versioned `PromptRegistry`.
- **Typed signatures (DSPy-style).** `class Sig(Signature)` with `InputField` /
  `OutputField` (docstring = instruction) or `signature("question, context ->
  answer, confidence: float")`; run via `Predict(sig, provider=, model=)` or
  `app.predictor(sig)(**inputs)`; optimize via `sig.to_prompt_spec()`.
- **Context compiler.** Scores every candidate (relevance, novelty, authority,
  freshness, provenance, token cost, leakage risk), dedupes, resolves conflicts,
  compresses, packs to a token budget, and reports excluded context. Opt-in
  semantic scoring (`app.use_semantic_context_scoring()`): embedding-cosine
  relevance + MMR (`mmr_lambda`) + reranker `upstream_relevance` blend +
  value-level (numbers/dates) contradiction as structured conflicts; default is
  lexical.
- **Multimodal-native packet.** `EvidenceItem` / `ContextCandidate` carry a
  `modality` (text/image/table/video) and image/table/video payloads; the
  compiler scores, budgets, orders, and cites them together. Slim packets
  `materialize()` cross-process from a content-addressed `InMemoryEvidenceStore`.
- **Video understanding.** `from vincio.documents import MockVideoAnalyzer,
  video_evidence_items, load_video` (real path: `ProviderVideoAnalyzer` +
  `PyAVFrameExtractor` behind `vincio[video]`). Deterministic `sample_frame_times`
  / `segment_timeline` address a clip without decoding it; a `VideoAnalyzer` yields
  a `VideoAnalysis` (segments + frames) that `video_evidence_items` lowers into
  `modality="video"` `EvidenceItem`s with a `time_range` whose `citation_ref`
  renders `<source>:t<start>-<end>`. `EvidenceItem.time_range` flows from retrieval
  chunking through the `CitedReportBuilder` footnote — temporal grounding at
  sub-clip resolution. `app.load_video(path, analyzer=)`.
- **Learned compression.** `from vincio.context import LLMLinguaCompressor`
  (drop-in `ContextCompiler.compressor`, protects numbers/entities/citations/
  query terms); faithfulness-gated via `app.gate_compression(dataset)` →
  `CompressionTuningResult` (metrics `compression_faithfulness` /
  `faithfulness_preserved`), or `app.use_learned_compression()` (ungated).

## Retrieval (RAG)

- **Index modes** (config `retrieval.mode` / `app.add_source(retrieval=)`):
  `bm25 | dense | sparse` (SPLADE-style) `| late_interaction` (ColBERT MaxSim,
  PLAID compression) `| hybrid | hybrid_full | graph | hybrid_graph`, fused by
  weighted RRF.
- **Query understanding.** `hyde | multi_query | decompose | step_back` via
  `query_strategies=` or `retrieval.query_strategies`.
- **Chunking.** `sentence_window | hierarchical/parent_document` (use
  `AutoMergingIndex`) `| contextual` (+`contextualize_chunks` for LLM prefixes);
  `GraphRAG` (communities + summaries, global/local routing).
- **Live / sharded / quantized.** `LiveIndex.upsert(chunks, *, ttl_seconds=)` /
  `upsert_stream(...)` → `UpsertStats` (content-hash change detection — only
  changed chunks re-embed) + `VectorIndex.migrate`; `ShardedIndex(shards, *,
  router=, max_concurrency=8)` (parallel fan-out, chunks co-locate by
  `document_id`); `TwoStageIndex` + `quantize_scalar` / `quantize_binary` (coarse
  compressed search + full-precision rerank).
- **Structured filters.** `from vincio.retrieval import eq, ne, in_, range_,
  exists, contains, and_, or_, not_, FilterSpec, build_filter_spec`; pass as
  `where=`. Compiles to native backend filters (`to_qdrant`/`to_pinecone`/
  `to_weaviate`/`to_milvus`/`to_elasticsearch`/`to_sql_where`), pushed down
  server-side. `app.tenant_filter` / `build_filter_spec(tenant_id=)` enforce
  shared-or-mine tenant scope in the engine (no fetch-to-filter).
- **Embedders / rerankers / stores.** `build_embedder("local|jina|voyage|cohere|
  voyage-context|voyage-multimodal|cohere-multimodal|<provider>", dimensions=N)`
  (Matryoshka/MRL truncation, contextual + text+image multimodal, query/document
  `input_type` hints); `build_reranker("heuristic|recency|authority|llm|cohere|
  jina|voyage")`; `from vincio.storage import build_vector_index` over `memory |
  qdrant | pgvector | chroma | pinecone | lancedb | weaviate | milvus |
  elasticsearch | opensearch | vespa` (extras `vincio[chroma|pinecone|lancedb|
  weaviate|milvus|elasticsearch|opensearch|vespa]`); embedders expose
  `embed_texts(texts, input_type="query"|"document")`. Local neural models with offline
  fallbacks: `FastEmbedEmbedder`, `SpladeEncoder`, `ColBERTTokenEmbedder`,
  `LocalCrossEncoderReranker`, llama.cpp `GGUFProvider` (each accepts an injected
  `model=`/`tokenizer=`; extras `vincio[fastembed,splade,cross-encoder,gguf]`).
- **Connectors.** `from vincio.connectors import connect` — `web, github, sql,
  s3, gcs, notion, confluence, slack, jira, linear, gdrive, sharepoint,
  salesforce, zendesk, bigquery, snowflake`, custom via `register_connector`;
  `app.add_source("kb", connector=connect("jira", base_url=..., token=...))`. The
  REST connectors ride core `httpx` + an injected `client=` (offline tests);
  `bigquery`/`snowflake` take an injected client/connection (`vincio[bigquery]` /
  `vincio[snowflake]`). All return `Document`s with provenance.

## Memory

- **Recall / remember.** `app.remember(content, user_id=...)` /
  `app.recall(query, user_id=...)`; scopes `session | user | agent | tenant |
  organization | global | team`; scoped handles `app.memory.for_user("u1")` /
  `for_team("eng")`. Hybrid lexical+vector+graph recall (`memory.hybrid_recall`,
  on by default).
- **Lifecycle.** `await app.memory.consolidate(session_id, user_id=...)`
  (episodic→semantic, provenance in `consolidated_from`); hygiene via per-scope
  `memory.ttl_days`, importance-weighted `decay_pass()`, audited
  `edit`/`forget`/`export_owner_data`/`erase_owner_data`. Auto-memory from runs:
  `memory.write_back: [input, evidence, tools, facts]` +
  `memory.fact_min_support` / `memory.max_facts_per_run` — evidence-supported
  claims (`extract_grounded_facts`) become candidates (`origin: run_fact`).
- **Bi-temporal + ACL + consent.** `MemoryItem` carries `valid_from`/`valid_to`/
  `valid_at()`/`acl`/`readable_by()`/`purpose`/`consent_id`, plus
  `MemoryScope.TEAM`; `MemoryEngine.correct(...)` (history-preserving),
  `asearch(..., as_of=, reader=, team_id=)` (as-of recall + ACL + consent
  filtering).
- **Eval.** `vincio.memory.evaluate_memory` (recall precision, contradiction
  rate, staleness, personalization lift), gated in VincioBench.

## Tools, agents & orchestration

- **Tools.** Permissioned registry (RBAC scopes + ABAC rules), schema from type
  hints, resource-limited sandbox, reliability scoring, idempotent approval-gated
  writes. Computer-use & provider-native hosted tools register on the same path.
- **Agents.** `app.agent(tools=, planner="dag|dynamic|react|direct|
  plan_and_execute|hierarchical", max_steps=, domain=, cost_aware_models=)` →
  bounded `AgentState` with `metrics()`; level-parallel DAG over
  `topological_levels`, a real `plan_and_execute` replanning loop
  (`Planner.replan`), in-loop compaction (`LoopCompactor`).
- **Hierarchical (HTN) planning.** `HTNDomain().method(task, [subtasks],
  ordering="sequence|parallel", when=)` + `.operator(name, step_type=,
  tool_name=, fallbacks=)`; `domain.decompose(task, context=)` → `HTNPlanNode`
  sub-goal tree; `dag_from_plan_node(node, available_tools=)` → executable
  `StepDAG`. `planner="hierarchical"` runs it (offline-deterministic with a
  domain, model-driven without; static fallback).
- **Plan repair.** On a tool failure / validation contradiction / budget shock
  the executor edits the *remaining* plan in place (`PlanRepairer`: re-bind to a
  `fallback_tools` / name-overlap tool, substitute to reasoning, reorder a
  corrective step, or drop the optional tail) instead of restarting; each repair
  is an `AgentState.repairs` entry, a `plan.repaired` event, and a trajectory
  step. On by default (`AgentExecutor(repair=False)` to disable).
- **Cost-aware action selection.** `cost_aware_models=[cheap, …, strong]` (or
  `CostAwareSelector(models, registry=)`) picks the cheapest *capable* model per
  step from `ModelRegistry` pricing + capabilities, escalating one tier only when
  the prior step's confidence is low; `SelectionDecision` records the pick.
- **Crews.** `app.crew(members=[{"name","description","goal","keywords",
  "budget_fraction"}], process="sequential|parallel|hierarchical", max_rounds=)`
  → `CrewResult` (output, reports, delegations, blackboard snapshot) — members
  share a versioned `Blackboard`, run under scaled budget shares, always
  terminate.
- **Durable graphs.** `app.graph(name)` → `StateGraph.add_node(name, fn)` (dict
  state → dict updates) / `add_edge` / `add_conditional_edge(source, router,
  targets=)` / `compile(interrupt_before=, interrupt_after=, max_steps=)`;
  checkpoints persist per step; `invoke`/`ainvoke` → `GraphResult(status=
  "done|interrupted|max_steps", state, thread_id)`; `resume(thread_id, value=)`
  (node-level `interrupt(state, payload)`), `update_state` (edit-and-resume),
  `history` + `fork(checkpoint_id)` (time-travel).
- **Compose / workflows.** `compose(a) | b | c` (functions/agents/crews/
  workflows/graphs), `parallel(name=step, ...)`, `branch(router, routes)`,
  streaming via `pipeline.astream(value)`; deterministic `Workflow` DAGs with
  retries/compensation, `Workflow.map_step(name, fn, over=...)` (data-dependent
  fan-out), and approval gates that pause (`status=="paused"`,
  `pending_approvals`) and `workflow.resume(result, approvals={"step": True})`
  without re-running done steps.
- **Distributed execution.** `from vincio.agents import WorkerPoolBackend,
  DistributedCheckpointer, InMemoryGraphCoordinator, Send`.
  `WorkerPoolBackend(workers=N).run(graph, input)` / `run_batch(...)`;
  `DistributedCheckpointer(store, coordinator=)` lease-guards a thread +
  CAS-commits each super-step (lost race → `CheckpointConflictError`);
  `StateGraph.compile(parallel=True)` runs BSP super-steps; a node returning
  `[Send("node", {...})]` fans out map-reduce. `LangGraphBackend().compile(graph)`
  / `OpenAIAgentsBackend().export_crew(crew)` export (lazy, no lock-in).
- **Parallel sub-graph scheduling.** `SubgraphScheduler(workers=N,
  budget=Budget(...), deadline_s=)` work-steals independent sub-graphs across the
  worker pool; `.run([SubgraphTask(graph, input, weight=)])` → `ScheduleResult`
  (`completed`, `partial`, `peak_concurrency`, `speedup`, `shares_usd` summing to
  the budget, `deadline_hit`). The SLA deadline returns completed + durable
  partial results (latest checkpoint) rather than blowing the deadline.
- **Durable timers / scheduled steps.** Inside a graph node: `sleep_until(state,
  when)` / `sleep_for(state, seconds, clock=)` / `wait_for_event(state, name)`
  pause the graph (the wake condition rides the checkpoint, so it survives a
  restart without holding a worker). `TimerService(compiled, clock=)` →
  `.tick(now=)` resumes due sleep timers, `.deliver(thread_id, event_name,
  payload=)` wakes an event wait; `pending_timers` / `due_timers` /
  `resume_due_timers` / `deliver_event` are the module-level forms.
- **Deep research.** `app.research(question, *, budget=ResearchBudget(breadth=,
  depth=, max_sources=, top_k=))` → `ResearchAgent` / `ResearchReport` loops
  search→read→reflect→verify→synthesize, dedups sources, emits a cited report;
  metrics `citation_coverage`/`grounding`/`source_diversity`.
- **Memory OS.** `app.enable_memory_os(scope=, owner_id=, max_core_tokens=)` →
  registers `memory_append`/`replace`/`search`/`archive` as permissioned, audited
  tools over the guarded write pipeline, with a context-pressure pager.
- **Computer-use.** `app.enable_computer_use(backend="mock|playwright|provider",
  require_isolation=)` registers navigate/click/type/screenshot as approval-gated
  tools; pluggable `IsolationBackend` (`Subprocess`/`Container`/`GVisor`/`MicroVM`/
  `WASM`, `require_real_isolation` refuses the subprocess default for adversarial
  code). `app.use_hosted_tools(["web_search","file_search","code_interpreter",
  "computer_use"])` surfaces OpenAI Responses built-ins as namespaced tools.
  Extra `vincio[computer-use]`.
- **Computer-use action plane.** `app.computer_use(screen=, policy=, approve=)`
  returns a `ComputerEnvironment` over a pluggable `ScreenBackend` (deterministic
  `MockScreen` offline; `PlaywrightScreen`/`AccessibilityScreen`/`RemoteDesktopScreen`
  behind `vincio[computer-use]`). It perceives the UI as typed, addressable
  `UIElement`s (`ScreenState`), grounds an intent to a `UIAction` bound by a **stable
  selector** (role+name, not a pixel), then for each action: **pre-gates** it against
  an `ActionPolicy` (a destructive/out-of-scope action gated like a write tool, behind
  an `approve` callback), performs it, **post-verifies** the effect (declarative
  `StateCheck` / `expect_change`), and **undoes** it on divergence — into a typed
  `ActionOutcome`, every step audited. A `ComputerTask` (goal + verifier) drives
  `env.run(policy, task)` → `ComputerRun` (`.success`, `.safe`, `.trajectory`),
  projecting onto the existing trajectory metrics / test-time search. `make_web_checkout`
  is a deterministic WebArena/OSWorld-shaped app gating success-at-budget + safety.
  The flat `enable_computer_use` surface is unchanged.
- **Agent identity, delegation & cryptographic accountability.** `from vincio import
  AgentIdentity, IdentityDocument, Keyring, Delegation, DelegationChain, AgentCredential,
  Grant, did_from_public_key, public_key_from_did` (also `vincio.security.identity`).
  The identity substrate beneath the tool permissions, the agent fabric, and the
  cross-org trust fabric — *who authorized this action, down what chain, within what
  bounds*. `app.identity(name, *, capabilities=, controller=, seed=, use=False)` mints a
  portable, **self-certifying** `AgentIdentity` whose DID is *derived from* its Ed25519
  public key (`did:vincio:ed25519:<hex>`, offline-resolvable with `public_key_from_did`,
  no registry); its content-bound `IdentityDocument` `verify()`s from the bytes, and a
  `Keyring` `rotate()`s keys along a **signed chain** so a signature is validated against
  the key current at signing time — a rotated/revoked key cannot forge new history while
  its past signatures stay valid (`document.verify_signature(msg, sig, at=)`). A signed
  `Delegation` mints a bounded `Grant` (capabilities ⊆, budget ≤, expiry ≤, audience,
  `max_delegations`) from a principal to an agent; `delegation.delegate(...)` sub-delegates,
  and a `DelegationChain` `verify(root_issuer=)`s **offline** where **each link only
  attenuates, never amplifies** — `chain.permits(capability, budget_usd=, at=)` /
  `require_permits(...)` answer authorization, and an over-reaching or tampered link is
  refused from the bytes. A signed `AgentCredential` (`app.issue_credential(subject,
  claims)`) is a verifiable claim that `verify()`s offline and `admits(capability)` folds
  into the admission path. `AgentIdentity` is a drop-in `ChainSigner` (`key_id` is the
  DID): `app.use_identity(id)` binds every audit entry, contract, and settlement to the
  DID. Ed25519 is pure-Python (RFC 8032) by default; the native `cryptography` backend is
  used automatically behind `vincio[crypto]` (byte-identical signatures). Offline,
  deterministic, dependency-free. See the [identity guide](docs/guides/agent-identity.md).
- **Verified reasoning & neuro-symbolic certificates.** `from vincio import VerifiedAnswer,
  Certificate, Check, CompositeVerifier, ArithmeticVerifier, UnitVerifier, TemporalVerifier,
  ConstraintVerifier, SchemaVerifier, CitationVerifier, default_verifiers, BehaviorSpec,
  EventPattern, RuntimeMonitor, Shield, ToolContract, ProgramSpec, ProgramOp,
  ProgramProperty, SynthesizedProgram, synthesize` (also `vincio.verify`; `Constraint` and
  `VerificationContext` live in `vincio.verify`). The certifiable frontier above
  probabilistic grading: for the classes of question where it is possible, an answer carries
  a checkable certificate a deterministic verifier confirms independently of the model.
  `app.verify_reasoning(answer, *, verifiers=, evidence=, schema=, constraints=, facts=,
  now=, regenerate=, max_cycles=2, raise_on_refute=False)` runs offline kernels (arithmetic,
  units, temporal, schema, constraint satisfaction, citation entailment) into a content-bound
  `Certificate` that is `verified` only when a kernel **recomputed** a claim and it held,
  `refuted` when a recomputation disagreed (a proof the answer is wrong), or `inapplicable`;
  it **re-derives its verdict from the bytes** (`certificate.verify()`), so a flipped status
  is caught. A refuted answer **refuses to emit**, and a `regenerate(answer, critique)`
  callback drives the existing bounded self-correction loop. A `BehaviorSpec` (`forbid` /
  `require_before` / `invariant`) states a temporal-logic property over an agent's
  trajectory, a `RuntimeMonitor` (`app.behavior_monitor`) checks it step-by-step, and a
  `Shield` (`app.shield(specs, *, mode="block"|"repair"|"monitor", use=False)` /
  `app.use_shield`) **blocks or repairs a violating action before it executes** — wired into
  the tool runtime so a policy-violating tool call (an unapproved write) is structurally
  refused. A `ToolContract` (`requires_that` / `ensures_that`) enforces pre/post-conditions
  against the actual call (`app.add_tool(..., contract=)`, `ToolContractError` on breach),
  and `synthesize` (`app.synthesize_program(spec, examples)`) emits a `SynthesizedProgram`
  whose declared properties are proven into a `Certificate` before it runs. Errors:
  `ReasoningVerificationError` / `CertificateRefutedError` / `BehaviorViolationError` /
  `ProgramSynthesisError` / `ToolContractError`. Deterministic kernels are dependency-free;
  optional SMT / CAS (`SmtConstraintVerifier` / `CasArithmeticVerifier`, `vincio.verify.smt`)
  behind `vincio[verify]`. Offline, deterministic. See the
  [verified-reasoning guide](docs/guides/verified-reasoning.md).

- **Autonomous skill acquisition & open-ended curriculum.** `from vincio import LearnedSkill,
  LearnedSkillLibrary, SkillProvenance, SkillStep, CurriculumTask, FrontierEstimate,
  CurriculumProposal, AutoCurriculum, SkillSearch, Solution, library_capability, Cultivator,
  CultivationResult, CycleReport` (also `vincio.cultivate`, plus a free `cultivate(...)`). The
  apex of the self-improvement arc: an agent that **grows its own capability** safely. This is
  distinct from `vincio.skills.SkillLibrary` (human-authored `SKILL.md` knowledge); a
  `LearnedSkill` is *acquired* by the agent and `to_skill()`-projects onto the same retrieval
  path. `app.cultivate(curriculum, *, library=None, held_out=None, cycles=3, rails=None,
  governance=None, min_capability_gain=0.0, prune=True, record=True)` runs propose → attempt →
  verify → distill → promote across cycles. An `AutoCurriculum(tasks, *, rails=, governance=,
  world_model=, search=, max_tasks=4)` proposes the next task at the **frontier of current
  competence** (solvable by a bounded, library-composing `SkillSearch`, not yet by retrieving a
  known skill) and **gates every objective before it is attempted** — the rails screen the
  instruction and the `GovernanceVerifier` must prove the app's controls hold, else the
  objective (or the whole round) is refused; a `CurriculumProposal.verify()` catches a refused
  objective relabelled as proposed (`stayed_in_policy`). A winning, oracle-verified trajectory
  is distilled into a `LearnedSkill` (objective, precondition, ordered `SkillStep`s — each a
  primitive `EnvAction` **or** a sub-skill call, so skills **compose** via `compose()`),
  verifier, `SkillProvenance`. A `LearnedSkillLibrary` is content-addressed (`add` dedups a
  byte-identical procedure, versions a changed one), retrieved like memory/tools (`relevant` /
  `evidence_for`), and offline-verifiable (`verify()` / `library_hash`; a tampered procedure is
  caught). A skill is promoted **only through the same `no_regression_gate`** a deploy clears
  (capability — `library_capability` over a held-out frontier set — must not fall, a
  `CanaryVerdict`), and a dead-weight skill is demoted. `CultivationResult.verify()` re-derives
  the monotonicity and stay-in-policy verdicts from the bytes; every run lands on the audit
  chain (`skill_cultivation`) and event bus (`cultivation.completed`). Error: `CultivationError`.
  No new dependency; offline, deterministic against the reference environments. See the
  [skill-acquisition guide](docs/guides/skill-acquisition.md).

## Use-case coverage: verticals, Assistant, voice

- **Vertical packs.** `app.use_pack("healthcare|ediscovery|kyc|customer_support|
  code_review")` — full-stack bundles that preconfigure retrieval knobs, scoped
  memory (`add_memory`), deterministic rails, domain metrics, a data-residency
  posture (`set_residency`, fail-open on unknown so the offline path runs), and a
  golden eval set, on top of the domain-pack contract. The `Pack` model gains
  `retrieval`/`memory`/`residency`/`purpose`; `Pack.is_vertical`,
  `Pack.retrieval_mode()`, `pack.dataset()` (golden set). Residency is
  fail-closed (`deny_on_unknown=True`); the offline path still runs because a
  passed provider instance reports its real name (mock/local → `on_prem`). A
  `redact` rail masks PII/PHI in *structured* output fields, not just free text.
- **Assistant.** `chat = app.assistant(user_id=, session_id=, memory_writeback=True,
  auto_approve=[...], on_approval=fn)` — a session-aware multi-turn layer; each
  `chat.send(text)`/`asend` is a full `run` threaded under one session, returns an
  `AssistantTurn` (`text`/`output`/`citations`/`approvals`/`memory_writes`/`trace_id`).
  Multi-turn state is session-scoped memory write-back. Write tools are denied and
  surfaced as `chat.pending_approvals` until `chat.approve(tool)`; `chat.history()`,
  `chat.reset()`. Drives as a `Simulator` agent for multi-turn evals.
- **Voice agent.** `agent = app.voice_agent(backend="inprocess|openai|gemini",
  research=True, memory_os=True, rails=True)` → a `VoiceAgent` (async context
  manager: `send_text`/`send_audio`/`commit`/`interrupt`, rail-screened `events()`).
  Wires the realtime session to the deep-research agent (in-session cited `research`
  tool), the memory OS, and the app's input/output rails; tool calls route through
  the permissioned runtime. Extra `vincio[realtime]` for hosted backends.

## Structured output & reliability

- **Output schema.** Pass a Pydantic class as `output_schema=`; `result.output`
  is a validated instance.
- **Constrained decoding.** Negotiated per run (`to_strict_json_schema`
  strict-sanitizes for the decoder; validation runs on the original; mode lands
  on the trace as `decoding=native|prompt`); `choice_schema(options)` /
  `regex_schema(pattern)`.
- **Streaming validation.** `partial_output` events carry `valid_prefix` /
  `validation_errors` — abort early when `valid_prefix is False`.
- **Rails.** `app.add_rail(name=, kind="topic|format|safety|custom",
  direction="input|output|both", action="block|warn|redact", blocked_topics=/
  allowed_topics=/max_chars=/require_pattern=/forbid_pattern=/detectors=
  ["pii","secrets","injection"]/predicate=)` + `app.register_rail_predicate`;
  deterministic, enforced before/after every generation, violations audited as
  `rail:<name>`.
- **Self-correction.** `app.enable_self_correction(max_cycles=2,
  max_cost_usd=0.05)` (bounded validate→critique→repair, structure-only — facts
  never invented) or `vincio.output.SelfCorrector`.
- **Multi-schema routing.** `app.add_output_schema(schema, keywords=,
  task_types=, when=)` picks the contract per run; `SchemaRouter.classify/
  validate_any` for content-side validation.

## Evaluation & continuous quality

- **Datasets & gates.** `Dataset.load("golden.jsonl")`, `app.evaluate(...)`,
  gates like `{"groundedness": ">= 0.95"}`; CLI `vincio eval run`.
- **Metrics.** Task/grounding/quality/safety/conversational: `faithfulness |
  answer_relevance | hallucination` (strict number checks) `| toxicity | bias |
  summarization_quality | knowledge_retention | conversation_relevance |
  conversation_outcome | intent_resolution | lexical_overlap` (lexical) `|
  semantic_similarity` (embedding-backed). Conversation metrics read turns from
  `case.context['messages']`. Unscoreable cases return `MetricResult(skipped=True)`
  and are excluded from gates.
- **Trajectory & tool-use.** `tool_call_accuracy | tool_call_f1 | goal_accuracy |
  plan_adherence | plan_quality | step_efficiency | topic_adherence` score the
  `trajectory` on a `RunOutput` — build it with `RunOutput.from_agent_state` /
  `from_crew_result` / `from_trace` (no re-instrumentation); refs in
  `rubric['expected_tools'|'plan'|'optimal_steps'|'topic']`;
  `report.metric_families()` shows output-only vs trajectory.
- **Judges & data.** `GEvalJudge(provider, model=, criteria=, samples=N)` (LLM-
  backed, deterministic template fallback) + `judge.calibrate(pairs)` (returns
  `cohens_kappa`, `gating_weight(threshold=)`; `queue.judge_trusted()` gates a
  judge on agreement); `SyntheticGenerator(seed=).generate(docs, n=)` (offline
  templates + LLM hook, provenance in `metadata.source_ids` + `rubric.facts`);
  `RedTeamSuite().run(app)` (jailbreak/injection/leak/bias/toxicity,
  `attack_success_rate`, `detector_coverage`).
- **Experiments & testing.** `app.experiment(name, variants=, dataset=,
  metrics=)` → `.compare()`/`.cost()`/`.significance(metric)`; `ab_test(a, b,
  metric)` (paired/Welch t-test, p-value + CI + effect size, pure-Python);
  `EvalRunner(..., repeats=N, repeat_aggregate="mean", flake_quarantine=True,
  flake_threshold=0.15)`; `ExperimentTracker(path).log/compare/ablation`.
  `vincio.testing` —
  `assert_eval`/`assert_grounded`/`assert_metric`/`assert_safe` + a pytest plugin
  with the `vincio_snapshot` fixture (`--vincio-update-snapshots`).
- **Multi-turn & online.** `Simulator(seed=).simulate(agent, Persona(goal=))` →
  `SimulatedConversation.to_eval_case()`; `dataset_from_traces(traces,
  group_by_session=True)`. `app.add_online_evaluator(metric, sample_rate=)` scores
  live runs off the hot path (`OnlineEvaluator.series()`, `app.aflush_online()`
  in tests). Drift: `DriftMonitor(...).set_score_baseline/check_scores/
  set_embedding_baseline/check_embeddings/observe_score/check_distribution` +
  `ks_statistic`/`psi`/`rbf_mmd2`/`CUSUMDetector` raise `drift.detected`; CLI
  `vincio eval drift baseline.json current.json`. Annotation: `AnnotationQueue` +
  `cohens_kappa`; CLI `vincio eval annotate labels.jsonl`.
- **Environment & benchmark harness.** `from vincio.evals import Environment,
  ToolEnvironment, EnvAction, StateCheck, make_retail_environment, scripted_policy,
  task_success`. `Environment` is `reset()/step(action)/observe()/verify()`;
  `verify()` runs `StateCheck`s over the world end state (the task-success
  oracle); `EnvironmentSimulator().run(env, policy)` → `Trajectory`. Nine adapters
  `SWEBenchAdapter | TauBenchAdapter | GAIAAdapter | WebArenaAdapter |
  BFCLAdapter | AgentBenchAdapter | ToolBenchAdapter | LiveCodeBenchAdapter |
  MMLUProAdapter` (+ `BenchmarkTask`, `load_benchmark`, `available_benchmarks`)
  pin a `task_set_hash()`, score a verifiable end state (AgentBench: per-env
  exact/contains/set/numeric match; ToolBench: solvable pass-rate over a call
  path; LiveCodeBench: all-tests-pass; MMLU-Pro: option-letter extraction),
  replay offline (`adapter.replay()`, fixtures in `benchmarks/fixtures/`) or solve
  live (`adapter.run(make_agent_solver(app, mode="text"|"calls"))` /
  `make_env_solver(policy)`; `tasks_from_jsonl`, `gaia_tasks_from_export`,
  `agentbench_tasks_from_export`, `toolbench_tasks_from_export`,
  `livecodebench_tasks_from_export`, `mmlu_pro_tasks_from_export`);
  `report.to_eval_report()` feeds the optimizer. Retrieval eval:
  `RetrievalEvaluator` / `retrieval_regression(search_fn,
  RetrievalGoldenSet([RetrievalQuery(...)]), RetrievalConfig, store=
  IndexRegressionStore())` gates recall/nDCG deltas with the swap significance
  test.
- **Quality frontier: ensembles, attribution, adaptive sampling.** Judge panel:
  `JudgeEnsemble([j1, j2, j3], aggregate="mean"|"median"|"trimmed_mean",
  disagreement_threshold=0.2)` → `await .averdict(case, out)` returns an
  `EnsembleVerdict` (`.value`, `.scores`, `.disagreement`, `.uncertain`,
  `.spread`); `judge_disagreement(scores)` quantifies spread; `.calibrate([(panel,
  human), ...])` fits a linear correction + records panel-vs-human κ, and
  `.gating_weight(threshold=0.6)` is `1.0` only once that κ clears the bar.
  Causal attribution: `await attribute_regression(app, dataset, [
  AttributionFactor.model("model", baseline=, candidate=),
  AttributionFactor.prompt("prompt", baseline=, candidate=),
  AttributionFactor.attr("retrieval", "retriever", baseline=, candidate=)],
  metric="lexical_overlap")` (or `CausalAttributor(...).attribute()`) runs `2**k`
  counterfactual coalitions and returns an `AttributionReport` with exact Shapley
  `.contributions` (sum to `.total_delta`), `.dominant_factor`, `.concentration`,
  `.explained`. Adaptive sampling: `await AdaptiveSampler(cases, sample_fn,
  gate=">= 0.9", budget=, seed_samples=2, confidence=0.95).run()` seeds every
  case then allocates by variance reduction, stopping when the CI clears the
  threshold → `AdaptiveSamplingResult` (`.verdict` pass|fail|uncertain,
  `.decided`, `.samples_used`, `.savings`, `.allocations`).
- **Metric = guardrail = fitness.** Every metric is reusable as a runtime
  guardrail (`app.add_metric_rail(metric, threshold=)` / `metric_guardrail(metric,
  threshold=)`) and as optimizer fitness (`AGENTIC_OBJECTIVES`); per-language eval
  slicing `EvalReport.slice_by_tag("lang:")` / `tag_gap`.

## Optimization & self-improvement

- **The closed loop.** `loop = app.improvement_loop(metrics=, gates=
  {"groundedness": ">= 0.8"})`; `loop.run(min_feedback_score=0.5)` — capture
  traces → `dataset_from_traces` → baseline eval → gated optimization → promote
  (registry push + tag "production" + `link_eval` + applied + `loop_promotion`
  audit + `loop.promoted` event); `dry_run=True` decides without acting. CLI
  `vincio loop run`.
- **Reflective optimizer & flywheel.** `app.reflective_optimize(dataset,
  strategy="reflective|mipro", budget=, minibatch_size=, gates=, apply=)` →
  `ReflectiveResult` (reads failures, proposes targeted edits via
  `HeuristicReflector`/`LLMReflector` + `cluster_failures`, evolves a
  `ParetoFrontier` under a rollout budget, deterministic under seed). Distillation:
  `app.export_training_set(runs=, require_grounding=True, format="openai|anthropic")`
  (or standalone `export_training_set_from_runs(runs, ...)` / `export_training_set(
  traces, ...)`) → grounded/deduped (`semantic_dedupe`) `TrainingSet` (trace path
  needs `app.enable_training_capture()`); gate a student `app.distill(ts, held_out,
  teacher=, student=, min_quality_ratio=)` → `DistillationResult` (promotes a
  `ModelCascade` only on quality-hold + cost cut; `BootstrapFinetune(trainer=
  provider_trainer(make_finetune_backend(...) | OpenAIFineTuneBackend(...)),
  swap_gate=)` runs a real fine-tune job). `vincio distill`.
- **Pareto / learned budgets / retrieval feedback / search.** `pareto_loop(
  candidates, evaluate_fn, dataset, objectives=[ObjectiveSpec(...)],
  constraints={"cost":0.01}, prefer="accuracy")` → `ParetoResult`
  (`frontier.front`/`knee()`); `BudgetLearner(...).learn(dataset)` →
  `LearnedAllocations` installed via `app.use_learned_budgets(...)`;
  `RetrievalFeedback(app.retrieval, records_from_dataset(ds)).tune()` (gated RRF/
  reranker tuning) + `recommend_chunking(reports_by_config, baseline=)`;
  `ContextOptimizer(...).optimize(dataset, strategy="hill_climb|anneal")` /
  `guided_search(space, evaluate, strategy=, budget=, seed=)` — deterministic,
  gate-respecting.
- **Optimizer-judge calibration.** `app.calibrate_judge(geval, samples)` (samples
  `(case, output, human_score)`) reflectively tunes the judge's *steps* to
  maximize Cohen's κ, adopting only on a strict gain → `JudgeCalibrationResult`
  (vs. `judge.calibrate(pairs)` in Evaluation, which calibrates the *threshold* /
  gating weight).
- **Significance-gated promotion.** `ab_test` returns p-value + CI + effect size;
  `evolution_loop` blocks significant regressions / warns under-powered runs.
  Trace-replay: `ReplayRunner(app).replay(traces, pin_tools=)` diffs output/
  trajectory/cost; `vincio trace replay --against <app>`.
- **Unified self-improvement contract.** `from vincio.optimize import
  SelfImprovementPolicy, SelfImprovementController, MetaSpec, CanarySpec,
  DeployResult, SelfImprovementEvent, successive_halving, learn_fitness_weights,
  select_for_labeling, deploy_candidate`. One `SelfImprovementPolicy` composes
  scheduling/proposal/online/canary/active-learning/meta; `app.self_improvement(
  policy, dataset=)` returns a controller whose `astream()`/`step()`/`run()` emit
  `observe → proposal → meta → label → reeval → canary → promote/rollback` (typed
  events `SelfImprovementPhaseEvent` / `DeployCompleted`). Meta =
  `successive_halving` over the strategy/budget grid + `learn_fitness_weights`.
- **Canary-gated deploy (prompt/policy).** `app.deploy(candidate, dataset=...)`
  (offline gated comparison) or `app.deploy(candidate, live_inputs=[...],
  score_fn=...)` (live-traffic canary via `LiveCanary`: ramps `CanarySpec.percent`,
  scores each arm, auto-rolls-back) — promotes live only on a no-regression
  `CanaryVerdict`. This is the **prompt/policy** canary; for live **model**
  rotation see `app.canary` / `CanaryRouter` under Providers & models.
- **On-policy reinforcement from verifiable rewards (RLVR).** `from
  vincio.optimize import RewardModel, VerifiableReward, OracleReward,
  BenchmarkReward, JudgeEnsembleReward, RewardSample, TrajectoryAdvantage,
  environment_step_value, TrajectoryOptimizer, SoftmaxPolicy, LearningTask,
  CandidateOutcome, LearningResult, compute_group_advantages, no_regression_gate,
  kl_divergence`. `RewardModel([reward, ...])` composes verifiable rewards into a
  dense signal — `OracleReward` (stateful-environment task-success oracle),
  `BenchmarkReward(adapter)` (the nine benchmark scorers), `JudgeEnsembleReward(
  ensemble)` (a split panel **down-weights itself**, leaning on what is
  checkable). `TrajectoryAdvantage(value_fn).credit(trajectory)` assigns
  step-level credit by Shapley counterfactual replay (shared
  `vincio.core.shapley` kernel; `environment_step_value(env_factory)` re-verifies
  the end state with kept tool steps). `app.learn(tasks, reward=, kl_max=,
  iterations=, learning_rate=, min_reward_improvement=, flywheel=, held_out=,
  teacher=, student=)` runs a GRPO group-relative update (`compute_group_advantages`)
  with a KL-to-reference clamp and a monotonic `no_regression_gate` →
  `LearningResult` (`.promoted/.reward_delta/.kl_to_reference/.kl_within_bound/
  .reward_monotonic/.verdict` (a `CanaryVerdict`)/`.recommended/.training_set/
  .distillation`). The served policy never regresses the baseline reward; a
  promotion emits a fine-tune job through the existing flywheel from the on-policy
  winners and is audited (`learn.promoted`/`learn.rejected`). Offline path uses a
  deterministic mock `SoftmaxPolicy`.
- **Building blocks (also usable directly).** `ContinuousImprovementController(
  app, metrics=, golden=, sustain=, cooldown_s=, eval_budget=, quality_floor=,
  reoptimize=)` → `ControllerDecision` (`.set_baseline(...).attach()` turns
  sustained debounced drift into one gated, audited, restart-safe action);
  `ExperimentProposer(app, ...)`
  (`.rank/propose/run_next`); `GuardedBanditRouter(entries,
  bandit="epsilon_greedy|ucb1|linucb")` (safety floor — no exploration on
  high-risk traffic, per-arm regret, auto-freeze/rollback; `app.use_bandit_router`);
  `GoldenRegressionSuite(path)` (`gate(report)` blocks a regressing candidate;
  `ImprovementLoop(golden_suite=)`).

## Observability

- **Traces.** Carry `session_id`/`thread_id`; `trace.add_score`/`span.add_score`
  (runtime evaluators attach automatically), `trace.add_feedback(score=,
  comment=)`. `sessions_from_traces` → `Session`; `dataset_from_traces(traces,
  min_feedback_score=)` → eval dataset; `record_feedback(..., exporter=)`. Viewer:
  `render_trace_text`, `trace_to_html`/`session_to_html` (self-contained),
  `trace_diff_html`. OTel exporter emits GenAI semantic conventions
  (`chat {model}`, `gen_ai.*`, `gen_ai.conversation.id`, agentic `invoke_agent`).
- **Prompt registry.** `PromptRegistry(dir).push(spec, tags=)` — content-hash
  versions, moving tags, `diff(name, a, b, rendered=True)`, `rollback(name)`,
  `link_eval(name, version, report)`.
- **Causal record-replay.** `Recorder`/`Replayer`/`Recording`/`ReplayProvider`/
  `ReplayResult`/`Divergence`/`BranchEdit`/`BranchResult` (`from vincio.observability
  import ...`) record a whole run's non-deterministic edges and replay it
  byte-for-byte; see the dedicated bullet above and `vincio trace verify-recording`.
- **Served plane (opt-in, self-hosted).** `from vincio.observability import
  IndexedTraceStore, ViewerApp, serve_viewer, AlertManager,
  AlertRule(kind="threshold"|"ewma"|"burn_rate"), TailSamplingExporter,
  WebhookAlertSink/SlackAlertSink/PagerDutyAlertSink, PrometheusExporter,
  ContentCapturePolicy`. Prompt/completion content capture is **off by default**
  at the export boundary (OTel exporter + tool runtime); opt in via
  `ContentCapturePolicy(capture=True)` (PII-redacted + truncated). Cross-worker
  shared state: `from vincio.storage.shared_state import InMemoryRateLimiter,
  TenantQuotaManager`; `RedisRateLimiter` / `RedisIdempotencyStore` in
  `vincio.storage.redis` (set `server.redis_url` so a multi-worker fleet enforces
  one coherent limit).

## Providers & models

- **Providers.** `openai, anthropic, google, mistral, local` (OpenAI-compatible),
  `mock` (deterministic, offline, schema-valid output); presets `groq | together
  | fireworks | openrouter | deepseek | perplexity | xai | nvidia` via
  `openai_compatible(name)` / `build_provider(name)` (`<NAME>_API_KEY`), or any
  endpoint with `openai_compatible(base_url=, api_key=)`. Enterprise endpoints
  `bedrock | vertex | azure` via `build_provider(...)` behind a pluggable
  `AuthStrategy`. All async-first, pooled transport, retries, request coalescing.
- **ModelRegistry.** `from vincio import default_model_registry, ModelRegistry` —
  a versioned, config-overridable (`VINCIO_MODEL_REGISTRY` JSON/YAML) catalog
  keyed by exact model id binding `ModelProfile` (capabilities + standard/batch
  pricing + context window + modalities + GA/deprecation/retirement). The cost
  table (`PriceTable`) and capability guards derive from it; an unknown model
  warns + emits `model.unknown` instead of billing $0. Token counters register
  behind the `TokenCounter` Protocol (`register_token_counter`).
- **Capability-aware failover.** `requirements_for` / `capability_check`
  intersect a request's needs (vision/tools/structured-output/reasoning/context)
  with `ModelCapabilities`. `FailoverChain` / `HealthAwareFailover` guard by
  default (`guard_capabilities=False` opts out): skip a mismatched substitution,
  classify a terminal lifecycle error (`is_lifecycle_error`), raise
  `ModelRetiredError` / `CapabilityMismatchError`.
- **Router.** `app.use_router(models, *, strategy="cheapest|fastest|least_busy",
  budget_usd=)` / `Router.from_models(provider, models)` picks the cheapest/
  fastest/least-busy *capable* model, downgrades to a per-request budget, emits a
  `model.routed` `RoutingDecision`.
- **Swap regression.** `app.gate_swap(candidate_model, *, baseline_model=,
  dataset=, traces=, gates=, repeats=, flake_quarantine=)` → `SwapVerdict`
  (replay + `evaluate_gates` + `DriftMonitor` + `ab_test` + behavioral shape
  diff); `app.swap_regression(dataset, *, candidate_model=, baseline_model=,
  repeats=)` / standalone `model_swap_regression(...)` → `SwapRegressionReport`
  (`.regressions`, `.worst_slices`, `.metric_tests`). `EvalRunner(..., repeats=N,
  flake_quarantine=True)` excludes flaky cases from gates.
- **Shadow & canary (model-level).** `app.shadow(candidate_model, *,
  candidate_provider=, block=)` → `ShadowProvider` (returns primary,
  dual-dispatches candidate, `.observations`/`.diff()`); `app.canary(
  candidate_model, *, percent=, score_fn=, min_samples=, regression_threshold=,
  prompt_name=)` → `CanaryRouter` (ramps %, online scoring, auto-rollback to
  primary + prompt-registry head, emits `canary.rollback`). The **prompt/policy**
  analog is `app.deploy` under Optimization & self-improvement.
- **Lifecycle & discovery.** `app.watch_lifecycle(models=, as_of=)` /
  `LifecycleWatcher(...)` emit sunset alerts + `MigrationProposal`
  (`apply_to_cascade`/`apply_to_policy`/`apply_to_config`);
  `ModelProvider.list_models()` + `ModelRegistry.reconcile(profiles)` /
  `discover_models(provider)` (offline-safe).

## Cost & reliability (FinOps)

- **Batch (~50% cost).** `app.batch(inputs, *, discount=0.5)` / `app.abatch(...)`
  → `list[RunResult]`, or `BatchRunner(backend, *, discount=0.5).run(requests)` →
  `BatchRunResult` (`.by_id()`, `.succeeded`, `.failed`; reconcile by
  `BatchRequest(custom_id, request)` → `BatchResult.custom_id`); backends
  `InProcessBatchBackend` (offline) `| OpenAIBatchBackend(completion_window="24h")
  | AnthropicBatchBackend | GoogleBatchBackend`. CLI `vincio batch`.
- **Resilience (inner→outer).** `CircuitBreaker(RetryingProvider(provider), *,
  failure_threshold=0.5, cooldown_s=30.0)` (`CircuitState` CLOSED/OPEN/HALF_OPEN,
  `circuit.*` events); `HealthAwareFailover([(provider, label), ...])` (open
  breakers raise non-retryable `CircuitOpenError`); `KeyPool(providers, *, rpm=,
  tpm=, breaker=True)` (round-robin, dual RPM+TPM limiter, full-jitter backoff
  honoring `retry_after`).
- **Cascade.** `app.use_cascade(models, *, min_confidence=0.5,
  max_escalations=None, confidence=)` (cheap→strong, escalate on low confidence) /
  `ModelCascade.from_models([...])` / `ModelCascade([CascadeRung(model, provider=,
  min_confidence=)])`; `response_confidence(resp)` = 1.0 clean stop / 0.0
  length|filter|error / 0.2 schema-expected-but-unparsed.
- **Budgets & attribution.** `app.set_cost_budget(limit_usd=, scope="tenant|
  feature|user|global", id=, period="run|hour|day|month|total",
  on_breach="cap|degrade|queue_to_batch", degrade_model=, anomaly_factor=)`;
  `app.cost_report(by="tenant|feature|user|model|provider|run", since=)` →
  `CostReport` (`.total_usd`, `.rows`, `.print_summary()`); `app.cost_ledger` /
  `app.budget_manager` (`CostLedger` / `BudgetManager` / `CostBudget`) always
  present; `arun`/`astream` accept `feature=` (cost dimension); events
  `cost.anomaly`/`cost.budget_exceeded`, audit `cost_budget`. CLI `vincio cost
  report`.
- **Prompt caching.** `app.enable_prompt_caching(ttl="5m|1h",
  min_prefix_tokens=1024)` (on by default via `provider_cache` /
  `provider_cache_ttl` / `provider_cache_min_prefix_tokens` config;
  `Message.cache_ttl`; model spans gain `cache_hit_rate`/`cached_input_tokens`).
- **Learned semantic cache & KV reuse.** `app.use_semantic_cache()` installs a
  `LearnedSemanticCache` the runtime consults before a live call, serving a
  near-miss above a trace-calibrated threshold (`cache.calibrate_from_pairs(...)`,
  `SemanticCacheGate`); `app.use_kv_prefix_reuse()` installs a `KVPrefixPool` for
  cross-request stable-prefix KV reuse. Config: `cache.semantic_cache` /
  `cache.semantic_threshold` / `cache.kv_prefix_reuse`; reports via
  `app.semantic_cache_report()` / `app.kv_prefix_report()`; model spans gain
  `semantic_cached` / `kv_prefix_reused` / `kv_bytes_reused`. See the full entry
  above (`families.semantic_cache`).
- **On-device local adaptation.** `app.adapt_locally(dataset, runs=|training_set=,
  policy=LocalAdaptationPolicy(), registry=)` fits a `LocalAdapter` on-device, gates
  it against the base on the held-out `dataset` (at-least-as-good), and on a pass
  registers + applies it (`AdaptationResult`); `app.local_adaptation(...)` returns
  the streaming `ContinualAdaptation` controller; `app.use_local_adapter(adapter)`
  applies one live and `app.use_local_adapter(None)` unloads it. See the full entry
  above (`families.local_adaptation`).
- **Federated / cross-org self-improvement.** `app.contribute_federated(member_id=,
  participants=, training_set=|runs=, policy=FederatedPolicy(), consent_subject=)`
  builds this member's numeric, raw-text-free `Contribution` (behind the consent
  ledger + residency posture); `app.adopt_federated(dataset, contributions,
  training_set=|runs=, policy=, registry=)` securely aggregates the fleet's
  contributions into a shared subspace, re-fits this member's own adapter against it,
  gates it against the base on the held-out `dataset` (at-least-as-good), and on a
  pass registers + applies it (`FederatedRoundResult`); `app.federated_improvement(...)`
  returns the streaming `FederatedImprovement` controller. Only numeric, masked,
  bounded-sensitivity aggregates cross a trust boundary. See the full entry above
  (`families.federated`).
- **Cross-fleet reputation & weighting.** `app.use_reputation_ledger()` attaches a
  `ReputationLedger` that earns a per-member reliability score from each federated
  round's no-regression gate verdict and reliability-weights the `SecureAggregator`,
  so a repeatedly-regressing or adversarial member is discounted without being singled
  out. Bounded (a weight never leaves `[floor, 1]`) and reversible (adoption still
  clears the same gate); `app.reputation_report()` rolls up each member's standing;
  `ReputationLedger.from_audit(audit)` replays it from the chain. See the full entry
  above (`families.reputation`).
- **Energy & carbon accounting.** `app.use_energy_accounting(region=)` turns on a per-run
  energy (Wh) and carbon (gCO₂e) estimate on the same cost-report surface; every run then carries
  `result.energy_wh` / `result.co2e_grams`, and `app.energy_report(by=...)` rolls them up like
  `app.cost_report`. `app.set_energy_budget(limit_wh=, limit_co2e_grams=, scope=, period=)` refuses
  a run that would exceed its sustainability envelope, the way a hard cost cap refuses spend.
  Deterministic and offline; the estimate and every refusal are on the audit chain. See the full
  entry above (`families.energy`).
- **Formal verification of governance invariants.** `app.verify_governance()` proves containment,
  residency, the budget hard cap, and the erasure-proof binding hold across their whole bounded,
  typed state space ahead of any run (a `held=True` verdict checks every point of each invariant's
  domain — a proof, not a sample), yields a delta-minimized `Counterexample` on violation, and lands
  a content-hashed verdict on the audit chain offline with no external prover. See the full entry
  below (`families.verification`).

## Security & governance

- **Detectors.** Deterministic PII / secret / prompt-injection detection with a
  normalization + recursive base64/hex/rot13 decode pre-pass (catches obfuscated
  attacks); non-English PII via `PIIDetector(locales=["fr","de","es","in","sg",
  "br","uk"])`; authority/provenance RAG-poisoning via
  `from vincio.security import PoisoningDetector` (FP/FN via
  `PoisoningReport.telemetry` + classifier hook). All accept a pluggable
  `DetectorBackend` (an ML model merges with, never replaces, the rules).
- **Provable injection containment.** Detection is best-effort, so containment
  separates the control plane from the data plane. `from vincio import TrustLabel,
  TaintedValue` — provenance becomes a `trusted`/`untrusted`/`quarantined` lattice
  that propagates through derivations and `ContextPacket.materialize()`, never
  laundering taint. `DualPlaneExecutor(tool_runtime, broker=CapabilityBroker(...))`
  ingests untrusted bytes into a quarantine, exposes only typed, schema-validated
  `extract(...)`ions to the privileged planner (`control_messages` never contain
  the bytes), and gates every side-effecting `call(...)` on an unforgeable
  `CapabilityToken` minted from the user's request (`executor.mint(tool,
  constraints=...)`) — an untrusted-tainted argument is refused without a
  capability or approval (`ContainmentError`). `verify_containment(monitor.events)`
  proves `untrusted ⇒ no unapproved capability` over a run (escalation rate 0).
  Capability-scoped tools are also available at the permission layer via
  `ToolPermissionChecker(broker=...)`.
- **Access & egress.** RBAC/ABAC via `AccessController`
  (`require_explicit_tenant=True` fails closed on untagged tenants); mandatory
  egress DLP `PolicyEngine.scan_egress` (`security.egress_dlp`: off/warn/block) on
  the fully-assembled request — `block` raises `EgressBlockedError`.
- **Audit chain.** Append-only, hash-chained, offline-verifiable
  (`verify_audit_file` / `AuditLog.verify_file()` / `vincio audit verify`); sign
  with `security.audit_signing_key` (HMAC) or an `Ed25519Signer` over `entry_hash`;
  Merkle-root checkpoints (`AuditLog.checkpoint`) for external witnessing.
- **Residency.** `app.set_residency(["eu"], provider_regions={...})` /
  `governance.allowed_regions` refuse egress as a blocking `ResidencyViolationError`;
  region inferred from a pinned endpoint via `infer_region_from_url`
  (AWS/GCP/Vertex/sovereign) with jurisdiction-aware matching.
- **Lineage, provable erasure & consent.** `app.trace_lineage(source)`;
  `app.erase_source(source)` → `ErasureResult` with `.proof` (`ErasureProof` from
  `build_erasure_proof`, signed by `app.content_signer`, content-bound by SHA-256
  over the removed-id set across chunks/documents/memories/artifacts, anchored to
  the audit Merkle root; `verify_erasure_proof`; emits a `SourceErased` event).
  `from vincio.governance import ConsentLedger, ConsentRecord, ConsentDecision,
  Purpose, LawfulBasis`; `app.use_consent_ledger()`,
  `AccessController.check_purpose(...)`; recall drops items whose purpose lost
  consent.
- **Formal verification of governance invariants.** `app.verify_governance()` →
  `VerificationReport` *proves* — by exhaustive bounded model checking, ahead of any
  run — that four governance invariants hold across their whole bounded, typed state
  space: containment (`untrusted ⇒ no unapproved capability`), in-jurisdiction
  residency (reflecting the app's `deny_on_unknown` posture), the budget hard cap,
  and the erasure-proof content binding. Each `Invariant` binds to the *same*
  decision function the runtime uses (the containment gate is `requires_authority`;
  the erasure binding is `verify_erasure_proof`), so a `held=True` verdict is a proof
  about the shipped machinery (`states_checked == domain_size`), not a sample. A
  violation yields a delta-minimized `Counterexample` (`.render()`); the
  content-hashed verdict (`report.content_sha256`, `report.verify()`) lands on the
  audit chain as a `governance_verification` decision (`allow`/`deny`), offline with
  no external prover. `from vincio import GovernanceVerifier, VerificationReport,
  Counterexample, Invariant`; `from vincio.governance import default_invariants,
  containment_invariant, residency_invariant, budget_invariant, erasure_invariant,
  within_budget`; `raise_on_violation=True` raises `GovernanceVerificationError`.
  VincioBench `verification` family + 3 SLOs.
- **Verified reasoning (output-side, per-answer).** `app.verify_reasoning(answer, ...)`
  → `VerifiedAnswer` attaches a deterministic, content-bound `Certificate` (offline
  kernels: arithmetic / units / temporal / schema / constraint satisfaction / citation
  entailment) that `verified` only on a recomputed-and-matched claim, `refuted` on a
  disagreement; a refuted answer **refuses to emit** and a `regenerate=` callback drives
  self-correction. A `Shield` (`app.shield(..., use=True)`) wired into the tool runtime
  **blocks a policy-violating action before it executes**; a `ToolContract` enforces
  tool pre/post-conditions (`ToolContractError`). VincioBench `verified_reasoning` family
  + 2 SLOs (certificate-soundness, shield-prevents-violation); optional SMT/CAS behind
  `vincio[verify]`. See the [verified-reasoning guide](docs/guides/verified-reasoning.md).
- **Autonomous skill acquisition (gated open-ended growth).** `app.cultivate(curriculum, ...)`
  → `CultivationResult` runs an `AutoCurriculum` through propose → attempt → verify → distill →
  promote: it proposes only frontier tasks, **gates every objective through the rails + the
  `GovernanceVerifier` before attempting** (an unsafe/out-of-policy task is refused, never run —
  `stayed_in_policy`), distills oracle-verified trajectories into a content-addressed, composable
  `LearnedSkillLibrary`, and **promotes a skill only through the same `no_regression_gate`** a
  deploy clears (capability never falls; dead weight is demoted). `CultivationResult.verify()`
  re-derives monotonicity and stay-in-policy from the bytes; audited as `skill_cultivation`.
  VincioBench `skill_acquisition` family + 2 SLOs (capability-monotonicity, stay-in-policy-safety);
  no new dependency. See the [skill-acquisition guide](docs/guides/skill-acquisition.md).
- **Compliance evidence (generated, no hosted dependency).** `app.model_card()` /
  `system_card()` (`CardFormat` vincio|open_model_card|ai_card);
  `app.compliance_report()` / `ComplianceMapper().map(redteam=, eval_report=,
  target=app)` over OWASP LLM Top 10 (2025) / OWASP Agentic / NIST AI RMF / MITRE
  ATLAS / ISO IEC 42001 → `ComplianceReport` (`.coverage_rate`, `.to_markdown()`;
  a control is `covered` only with measured evidence, else `partial`);
  `app.aibom()` (CycloneDX 1.6, `AIComponent.verify` / `sha256_file`); content
  marking `from vincio.governance import mark_synthetic_content, ai_disclosure,
  data_summary` + `verify_manifest(..., signer=HmacSigner(secret))`
  (`governance.content_marking` marks every run); non-English PII via
  `governance.locales`; per-language token tax `app.fertility.token_tax(lang)`.
  CLI `vincio governance card|report --red-team --markdown|aibom|lineage|erase`.
- **Supply chain.** Releases ship a CycloneDX SBOM + SLSA provenance attestations
  (`gh attestation verify <artifact> --repo Ohswedd/vincio`).

## Documents & media out (generation)

- **Documents.** `app.build_document(source, *, format="markdown|html|docx|pdf|
  pptx", contract=DocumentContract(required_sections=, table_specs=[TableSpec(
  ...)], min_words=, citations_per_section=))` (the `DocumentBuilder`) turns a
  *validated* result into a structurally-validated, provenance-audited
  `DocumentArtifact` (`document_generate` event; repair is formatting-only,
  deficient output raises `DocumentContractError`). Markdown/HTML are
  dependency-free; DOCX/PDF/PPTX need `vincio[gen-docx|gen-pdf|gen-pptx]`. Plus
  `fill_text_template`/`fill_docx_form`/`fill_pdf_form` (typed citation-aware
  `Slot`s) and `generate_redline`.
- **Cited reports.** `app.cited_report(answer, evidence, *, format=,
  contract=CitationContract(min_coverage=, require_entailment=,
  min_entailment_rate=))` / async `acited_report` (the `CitedReportBuilder`)
  resolves `[E1]` markers to footnotes + bibliography, computes sentence-level
  coverage and per-claim entailment.
- **Image / TTS.** `app.generate_image(prompt, *, provider=ImageProvider,
  model=)` / `agenerate_image` (`ImageGenRequest`) and `app.synthesize_speech(
  text, *, provider=SpeechProvider, voice=, format=)` / `asynthesize_speech`
  (`SpeechRequest`); providers `Mock`/`OpenAI`/`Google`/`HTTP`Image and
  `Mock`/`OpenAI`/`Google`/`ElevenLabs`Speech; every asset C2PA-stamped (SHA-256
  via `mark_synthetic_content` + `embed_provenance` (PNG) / `write_sidecar_manifest`),
  budget-metered (`meter_media_cost`), audited (`image_generate`/
  `speech_synthesize`).
- **Video.** `app.generate_video(prompt, *, provider=VideoProvider, model=,
  seconds=)` / `agenerate_video` (`VideoGenRequest`) and `app.edit_video(video,
  prompt, *, provider=)` / `aedit_video`; providers `Mock`/`OpenAI`(Sora)/
  `Google`(Veo)/`HTTP`Video; every clip C2PA-stamped (manifest `media_type`
  `video/mp4`, bound to its bytes), priced by `video_cost`/`VideoPrice`,
  budget-metered, audited (`video_generate`/`video_edit`). Real frame decode
  behind `vincio[video]`.
- **Richer inputs.** `load_pdf(path, ocr_engine=)` OCR fallback (`vincio[ocr]`),
  layout-aware `load_document(path, layout=True)` / `extract_pdf_layout`
  (`vincio[pdf-layout]`), `load_media(path, transcriber=MockTranscriber()|
  WhisperTranscriber())` → timestamped transcript, `figure_evidence`,
  `parse_html`/`structure_data`; audio chat input via `ContentPart.audio` +
  `core.media.encode_audio_bytes`; loaders PPTX/EPUB/RTF/ODT (dep-free), Parquet
  (`vincio[parquet]`), mbox/`.msg` (`vincio[msg]`) via a `ParserRegistry`
  (`register_loader`). Forms/KYC: `HeuristicFormExtractor().extract(text)` →
  `FormField`s + `form_fields_to_evidence`; `DocumentAI` adapters
  (Textract/Azure/Google).
- **EU AI Act pack.** `app.risk_tier(purpose=, domains=)` → `RiskAssessment`
  (advisory; `RiskTierClassifier`), `app.annex_iv(...)` (`AnnexIVBuilder`),
  `app.fria(..., affected_groups=)` (`FRIAGenerator`) rendered through the
  document engine, grounded by the live config/cards/matrix, recorded as
  `conformity_doc`.

## Protocols & interoperability

- **MCP.** `vincio.mcp`: `app.add_mcp_server(name, command=/url=/server=)`,
  `app.serve_mcp()` (stdio / Streamable HTTP / in-process); consumed tools run
  through the permissioned/sandboxed/audited runtime, resources become evidence
  (`origin: mcp:<server>`), sampling routes to the provider; OAuth 2.1 seams.
  `MCPUIResource` served via `app.serve_mcp(ui_resources=[...])`. Protocol-version
  negotiation (`negotiate_version`, `SUPPORTED_PROTOCOL_VERSIONS`) honours an
  older-pinned peer; `StreamableHTTPTransport(stateless=True)` is the stateless-core
  transport mode (no `Mcp-Session-Id`).
- **MCP Apps (server-rendered UI).** `app.mcp_app(name, max_render_tokens=)` →
  `MCPAppBridge` reads a consumed server's `ui://` resources and lowers each into an
  AG-UI `CUSTOM` `mcp.ui` event (`from vincio.server.agui import mcp_ui_event`):
  untrusted-external provenance, token-metered against the run (an oversized render
  is `refused`), audited (`mcp_ui_render`). `bridge.to_agui_events()` /
  `bridge.stream(base)` (splice before `RUN_FINISHED`); a tool result may embed a
  UI resource (`client.call_tool_ui` → text + `[MCPUIResource]`); `is_ui_resource`.
- **Elicitation (governed mid-call input).** `from vincio.mcp import ElicitationGate,
  ElicitationRequest, ElicitationResponse, ElicitationPolicy, ElicitationAction`.
  `app.add_mcp_server(..., elicitation=collector, elicitation_approval=fn,
  elicitation_policy=ElicitationPolicy(require_approval=, screen_rails=,
  forbid_quarantined=))` builds an `ElicitationGate`: a server's `elicitation/create`
  is gated like a write tool — an approver may deny it, the collected value is
  screened through the input `RailEngine` (a secret/injection value is declined), and
  an accepted value is wrapped `TaintedValue.untrusted(...)` (`mcp:<server>:elicitation`)
  so it is contained like any untrusted input; every decision audited (`mcp_elicit`).
  A served app initiates one with `MCPServer.elicit(message, schema=)`.
- **MCP marketplace bridge.** `app.add_mcp_from_registry(name, registry=,
  allow=/deny=/directory=)` — one call: discover via `MCPRegistryClient`, govern
  reachability through a governed `AgentDirectory` (`AllowListGate`, audited
  `agent_resolve`), then land the server's tools in the permissioned runtime;
  `server=`/`transport=` for offline/in-process. Unlisted → `AccessDeniedError`.
- **A2A.** `vincio.a2a`: `app.serve_a2a(crew|graph)` (Agent Card + JSON-RPC task
  lifecycle), `RemoteA2AAgent` as a bounded crew delegate.
- **Agent Skills.** `vincio.skills`: `app.add_skill(path)` (`SKILL.md` progressive
  disclosure, bundled scripts as sandboxed tools).
- **Agent fabric.** `from vincio.registry import AgentDirectory, ACPClient,
  ACPAgentManifest, MCPRegistryClient, MCPServerRecord`;
  `app.agent_directory(allow=[...], deny=[...])` (governed + audited);
  `directory.find(capability=|tag=|query=)`, `directory.resolve(name)` passes an
  `AllowListGate` (fail-closed) and records an `agent_resolve` decision. AGNTCY/ACP
  + MCP-registry discover into the same directory.
- **Agent negotiation & contracting.** `from vincio.negotiation import
  buyer_position, seller_position, Negotiation, NegotiationBudget, Contract,
  ContractTerms, select_offer, A2ANegotiator` (also top-level `vincio.__all__`).
  `app.negotiate(scope, *, buyer=, seller=, budget=NegotiationBudget(max_rounds=,
  deadline_s=), buyer_id=, seller_id=)` / `anegotiate` runs a typed alternating-offers
  bargain between a buyer and a seller `NegotiationPosition` (or a `Party`) → a
  `NegotiationResult` (`.status` agreement|no_agreement|walk_away, `.agreed`,
  `.contract`, `.rounds`, `.offers`, `.deadline_hit`). **Termination guaranteed**:
  a deal when the parties' acceptable regions overlap (time-dependent concession +
  `AC_next` acceptance), a clean no-deal when they do not, a partial result on a
  deadline. On agreement a `Contract` (price/SLA/scope/quality) is **signed by both
  parties** (`app.contract_signer`, audit-chain signer, or per-app key) and recorded
  (`negotiation` / `contract_signed` audit actions); `contract.verify(signer)`
  validates **offline** (hash recomputes + signatures check; tamper → invalid),
  `contract.to_budget()` lowers price→`max_cost_usd` / SLA→`max_latency_ms`, and
  `contract.check(cost_usd=, latency_ms=, quality=)` / `app.enforce_contract(...)`
  detect a breach (and debit the seller's reputation). When a `ReputationLedger` is
  attached (`app.use_reputation_ledger()`), a local party discounts a counterparty's
  offers by its reputation weight (`[floor, 1]`, bounded/reversible — discounted, not
  singled out); `select_offer(results, buyer_position, reputation=)` picks the
  reputation-weighted best deal. Over the A2A fabric: `app.serve_negotiation(party)`
  exposes a `Party` as an A2A agent (a `negotiate` skill), `A2ANegotiator(client,
  member_id=, role=)` drives a remote counterparty (member identity pinned, not
  self-asserted). `NegotiationError`/`ContractError` (codes `NEGOTIATION_ERROR` /
  `CONTRACT_VIOLATION`).
- **Cross-org workflow choreography.** `from vincio.choreography import Saga,
  Choreography, SagaResult, SagaJournal, StepRequest, StepOutcome, RemoteParticipant,
  choreography_a2a_server` (also top-level `vincio.__all__`; `Participant`,
  `LocalParticipant`, `SagaContext` are subpackage-only). A `Saga(name=).step(name, *,
  action=, participant=|capability=, compensation=, payload=, build=, contract=, retries=)`
  is an ordered, compensating cross-org workflow (the choreography analogue of the in-process
  durable graph); a step names its participant statically (`participant=`) **xor** declares a
  `capability=` resolved at run time (run-time discovery, below). `app.choreograph(saga, *,
  participants=, input=, saga_id=, directory=, binder=, binding_weights=, interrupt_after=)`
  / `achoreograph` drives it → a `SagaResult` (`.status`
  completed|compensated|failed|interrupted, `.completed_steps`, `.compensated_steps`,
  `.failed_step`, `.output`/`.output_of(step)`, `.journal`). `participants` maps an org
  id to a `Participant` (or, as a convenience, a dict of `{action: handler(payload)}`
  callables, wrapped in a `LocalParticipant`); a handler returns a dict (output) or a
  `StepOutcome(ok=, output=, cost_usd=, latency_ms=, quality=)`. **Per-org governance**:
  the coordinator audits each dispatched handoff on its own chain (`choreography_step`
  action) while each participant audits its execution on its own — no shared control
  plane. **Compensation**: a forward step that returns `ok=False`, raises, or **breaches
  its step `contract`** (`contract.check` on the delivered metrics) triggers
  deterministic compensation of completed steps in **reverse order** (a compensation
  handler gets the forward output under `payload["forward_output"]`); a clean unwind is
  `status="compensated"`, an incomplete one `"failed"` (or `CompensationError` with
  `raise_on_compensation_failure=True`). **Durable**: the `SagaJournal` is checkpointed
  to `app.store` after every step (kind `choreography_sagas`), so `app.resume_choreography(
  saga, saga_id, *, participants=)` resumes after a restart on a fresh engine and never
  re-runs a completed step; the journal is **hash-chained** so `journal.verify(verifier=)`
  recomputes it **offline** (tamper → `intact=False`, `broken_at=seq`). Over the A2A
  fabric: `app.serve_choreography(handlers, *, org_id=)` exposes an org's handlers as an
  A2A agent (a `choreograph` skill), `RemoteParticipant(client, org_id=)` dispatches a
  step to a remote org (same `perform`/`compensate` protocol as a local one).
  `ChoreographyError`/`CompensationError` (codes `CHOREOGRAPHY_ERROR` /
  `COMPENSATION_FAILED`).
- **Cross-org workflow discovery & dynamic choreography.** `from vincio.choreography import
  CapabilityBinder, BindingWeights, BindingCandidate, StepBinding` (also top-level
  `vincio.__all__`). A step declaring `capability=` is resolved to a participant **at dispatch
  time** from a governed `AgentDirectory` (`app.agent_directory(allow=)`), passed as
  `app.choreograph(..., directory=)` — discovery changes *who* runs a step, never *how*. A
  `CapabilityBinder(directory, *, reputation=, settlement_book=, weights=BindingWeights(
  reputation=, settlement=, contract_fit=, unknown_settlement_score=))` `.rank(capability, *,
  contract=, available=)` / `.bind(step, *, available=)` finds the directory records advertising
  the capability, governs each through the allow-list (audited `agent_resolve`), keeps the
  allowed **and** reachable ones (an org present in both the directory and `participants`), and
  ranks them by a weighted mean of reputation weight (`ReputationLedger.weight`), settlement
  reliability (share honoured, from `SettlementBook.report`), and contract fit (prior delivered
  cost vs the step contract's price) — best first, ties broken by org id (deterministic). The
  chosen `StepBinding` (`.org`, `.score`, `.candidates`, `.considered`, `.eligible`) is recorded
  on the journal (`result.bindings[step]` / `journal.bindings()`) and audited on the
  coordinator's chain (`choreography_bind`). A capability no allowed, reachable candidate
  advertises raises `ChoreographyError`. A discovered step is contract-enforced, **compensated at
  the org it was bound to** (recorded `org`, not re-resolved), durable across a restart (a
  resume re-binds only steps not yet run), and dispatched over the A2A fabric identically.
  Build the binder automatically from `directory=` + the app's reputation ledger + settlement
  book, or pass a prepared `binder=`. Held by `families.discovery` (binding-correctness +
  governance-preservation).
- **Agent-to-agent settlement & metering.** `from vincio import Meter, MeterReading,
  UsageEvent, SettlementRecord, SettlementBook, SettlementReport, Reconciliation,
  reconcile, settle_contract, settle_saga` (also `vincio.settlement.__all__`;
  `SettlementLine`, `SettlementSignature`, `SettlementVerification`, `SettlementStatus`,
  `SettlementRow`, `BookVerification` are subpackage-only). **Closing the books** on work
  delivered under a negotiated `Contract` — never a payment rail, only a verifiable ledger
  of what was owed and delivered. **Meter**: `app.meter(contract, *, run_id=)` →
  `Meter(contract_id)`; `.accrue(*, units=, cost_usd=, latency_ms=, quality=, step=)` adds a
  `UsageEvent`, `.reading()` → a **total-preserving** `MeterReading` (cost/latency summed,
  quality the **minimum** = weakest link held against a floor, totals exactly the sum of the
  events — the metering-accuracy invariant); `Meter.from_saga(result)` builds a meter per
  contract from a saga's journal. **Settle**: `app.settle(contract, *, reading=|cost_usd=,
  latency_ms=, quality=, run_id=, party=, sign=True, record_reputation=True)` → a
  `SettlementRecord` (`.status` settled|breached, `.amount_owed_usd` = agreed price,
  `.balance_usd` = price − delivered cost [+credit/−overrun], `.overrun_usd`/`.credit_usd`,
  `.lines` per dimension, `.breaches`) — reconciles delivery via `contract.check`. A breach
  is **not** an error (it reconciles to `status="breached"`). `settle_contract(contract, *,
  reading=|cost_usd=,…)` is the pure builder; `app.settle_saga(result, *, contracts={id:
  Contract})` / `settle_saga` settles every contract a saga ran under from its journal.
  **Signed & offline-verifiable**: both parties sign one reconciliation hash over the
  economic facts (run-id/timestamp-independent, so two sides co-sign the *same* hash);
  `record.sign(signer, party=)` (party must be buyer/seller), `record.verify(verifier=,
  require=)` → `SettlementVerification` (a tampered figure → `hash_ok=False`). **Reconcile
  across the boundary**: `reconcile(a, b)` → `Reconciliation(.agrees, .hashes_match,
  .discrepancies)` ties two orgs' records out (a disagreement is a dispute); raises
  `SettlementError` only for different contracts. **Book**: `app.use_settlement_book(*,
  owner=)` → `SettlementBook(owner, *, signer=, audit=, store=, reputation=, book_id=)`, a
  **hash-chained** ledger (`book_id` defaults unique; pass a stable one to resume across
  restarts via `store`); `.settle(...)` reconciles+signs+links+audits+reputation-closes,
  `.verify(verifier=)` → `BookVerification` (tamper → `intact=False`, `broken_at=seq`),
  `.report(counterparty=)` / `app.settlement_report(counterparty=)` → `SettlementReport`
  (per-counterparty owed/delivered/net balance, settled/breached). **Reputation-closing**: a
  settled overrun/shortfall debits the seller (via an attached `ReputationLedger`), so
  delivery weights the next negotiation. Audit action `settlement`. `SettlementError` (code
  `SETTLEMENT_ERROR`).
- **Cross-org settlement netting & multilateral clearing.** `from vincio import NettingSet,
  net_settlements, net_books` (also `vincio.settlement.__all__`: `NetPosition`,
  `NetObligation`, `BilateralNet`, `GrossObligation`, `NettingDispute`, `NettingVerification`
  are subpackage-only). **Netting** folds a fleet's many bilateral `SettlementBook` balances
  into a single minimal set of net obligations — a library-side clearing *calculation*, never
  a hosted clearing house or a payment rail. Each settled contract is a directed payable
  (buyer owes seller `amount_owed_usd`, the agreed price; a breach is surfaced by the
  settlement's own status/reputation, not by altering what is owed). `net_settlements(records,
  *, owner=, fleet=, verify_with=)` and `net_books(books, *, owner=, verify_with=,
  require_intact=)` → a `NettingSet`: the same settlement seen from both books is **deduped
  not double-counted** (by reconciliation hash), the directed payables aggregate per pair into
  `GrossObligation`s, collapse to one `BilateralNet` per counterparty, and the per-org
  `NetPosition`s (`owed_usd`/`due_usd`/`net_usd`; sum to zero) **clear** to the minimal set of
  `NetObligation` transfers — at most `N − 1`, net-debtors paying net-creditors,
  deterministically (ties by org id). **Content-bound & offline-verifiable**: the netting hash
  binds the fleet, the exact source records read, the positions, and the cleared obligations;
  `netting.sign(signer, party=)`, `netting.verify(verifier=, require=)` → `NettingVerification`
  (`.hash_ok`, `.positions_balanced`, `.conserves` — the cleared transfers reproduce every
  position), `.require_valid()`. **Same discipline**: a tampered source record (its
  reconciliation hash no longer recomputes) is **refused** (`SettlementError`), and two books
  that disagree on a contract are pinpointed as a `NettingDispute` (excluded; `.clean`,
  `.require_clean()`). `app.clear_settlements(*, books=, records=, sign=True, verify_with=,
  record_audit=True)` nets a fleet, signs as the app, and audits (action `netting`);
  `book.net(*, sign=True)` nets one org's own book. `.print_summary()`, `.to_wire`/`.from_wire`.
- **Cross-org dispute resolution & arbitration.** `from vincio import Resolution, arbitrate`
  (also `vincio.settlement.__all__`: `ResolutionStatus`, `ResolutionVerification`, `ClaimVerdict`
  are subpackage-only). **Arbitration** resolves a pinpointed disagreement (a `NettingDispute`,
  or two records that do not reconcile) — a library-side protocol, never a hosted arbitration
  service or a court of record. `arbitrate(records, *, contract_id=None, arbiter="",
  verify_with=None)` → a `Resolution`: each party submits its signed `SettlementRecord`s for one
  contract and the decision rests on nothing it cannot recompute — a reconciliation hash **both**
  the buyer and the seller signed (each on their own record, co-signing one figure) is mutually
  corroborated and **upheld**; a unilateral claim contradicting it is **rejected** and pinpointed
  (`ClaimVerdict.reason`); a single uncontested figure stands on its own; neither corroborated →
  **unresolved** (`status` is `"upheld"`|`"unresolved"`). Unlike netting, a tampered/forged claim
  is marked **inadmissible** and pinpointed (`.inadmissible_claims`), never raised — arbitration
  is the venue that adjudicates a bad claim. **Content-bound & offline-verifiable**: the
  resolution hash binds the contract, parties, outcome (`upheld_hash`/`upheld_balance_usd`), and
  every claim verdict (by reconciliation hash + signers + admissible + stands, NOT record id, so
  the same claim from both sides binds once; arbiter/id/timestamp excluded → two arbiters
  co-sign one hash); `resolution.sign(signer, party=)`, `resolution.verify(verifier=, require=)`
  → `ResolutionVerification` (`.hash_ok`, `.decision_sound` — the recorded outcome re-derives
  from the recorded claims, so a flipped verdict is caught even after re-sealing), `.require_valid()`,
  `.require_resolved()`. `.standing_claims`/`.rejected_claims`/`.inadmissible_claims`/`.dissenters`.
  `app.arbitrate(records, *, contract_id=None, sign=True, verify_with=None, record_audit=True,
  record_reputation=True)` adjudicates, signs as the app, audits (action `arbitration`), and
  **closes the reputation loop** by debiting each dissenter (the party whose admissible claim did
  not stand; unresolved debits nobody); `book.arbitrate(*counterparty_records, contract_id=None,
  sign=True, verify_with=None)` resolves one org's own record against submitted claims.
  `.print_summary()`, `.to_wire`/`.from_wire`.
- **Cross-org reputation attestation & portability.** `from vincio import ReputationAttestation,
  AttestationRevocation, PortableReputation, attest_reputation, revoke_attestation, combine_attestations`
  (also `vincio.settlement.__all__`: `AttestationConfig`, `AttestationVerification`,
  `AttestationVerdict`, `RevocationVerification`, `SubjectStanding` are subpackage-only). Makes earned
  standing **portable** — reputation that travels the fabric, never a hosted reputation bureau.
  `attest_reputation(records, subject, *, issuer="", resolutions=None, config=None, verify_with=None,
  horizon_days=None, note="")` → a `ReputationAttestation`: reads an issuer's own signed
  `SettlementRecord`s where `subject` is the **seller** (a fulfilled settlement a success, a breach a
  failure) and arbitration `Resolution`s where `subject` is a dissenter (a failure), counting only
  what it can recompute (a tampered own record is skipped; the exact `source_hashes` bound). Raises
  `SettlementError` on no admissible history. **Content-bound & offline-verifiable**: the attestation
  hash binds issuer/subject/`settled`/`breached`/`dissents`/prior/`reputation`/`source_hashes` (plus
  `horizon_days` when set; id + timestamp excluded; issuer **is** bound — one issuer's signed claim);
  `att.sign(signer, party=None)` (defaults to issuer), `att.verify(verifier=, require=None)` →
  `AttestationVerification` (`.hash_ok`, `.evidence_sound` — the attested reputation re-derives from the
  evidence counts, so a tampered score is caught even after re-sealing), `.require_valid()`,
  `.to_wire`/`.from_wire`. `combine_attestations(attestations, *, subject=None, config=None,
  verify_with=None, base=None, allow_self=False, revocations=None, as_of=None)` → a `PortableReputation`:
  verifies each (a tampered/forged one refused and pinpointed in `.refused`), refuses a self-attestation
  (`issuer==subject`) and a stacked one (only an issuer's largest counts, `.excluded`), and pools the
  admissible evidence per subject into one Beta-Bernoulli posterior under the importer's prior (conjugate
  → combining is summing evidence, never one self-asserted number; `AttestationConfig.per_issuer_cap`
  bounds any one issuer's mass). `.weight(member_id)` → `[floor, 1]` (a `base` local `ReputationLedger`'s
  earned standing wins for a known counterparty; an unknown one falls back to the prior),
  `.reputation`/`.standing`/`.subjects`/`.counted`/`.refused`/`.excluded`/`.revoked`/`.stale`. Drops into
  the existing negotiation/discovery path unchanged (`LocalParty`/`select_offer` accept any
  `weight(member_id)`). **Freshness & revocation** (standing changes → the prior is time-aware and
  revocable, reading only existing signed artifacts): with an `as_of` clock a stale attestation (past its
  issuer `horizon_days` window) is excluded and pinpointed (`.stale`), and `AttestationConfig.half_life_days`
  decays an older one's evidence mass (`0.5 ** (age/half_life)`, ratio preserved) out of the prior;
  `revoke_attestation(attestation_or_hash, *, subject="", issuer="", replacement=None, reason="")` → an
  `AttestationRevocation` (binds issuer/subject/`attestation_hash`/`replacement_hash`; `.sign`/`.verify` →
  `RevocationVerification`, `.revokes(att)`, `.is_supersession`, `.to_wire`/`.from_wire`) withdraws/supersedes
  an attestation **by its hash** — a `combine_attestations(..., revocations=[rev])` excludes it (`.revoked`),
  honored only when it verifies and is issued by the **same party** (a forged or cross-issuer revocation
  cannot cancel a claim). `app.attest_reputation(subject, *, book=None, resolutions=None, config=None,
  horizon_days=None, sign=True, record_audit=True)` issues from the app's settlement book, signs as the
  app, audits (action `reputation_attestation`); `app.revoke_attestation(attestation, *, book=None,
  replacement=None, reason="", sign=True, record_audit=True)` signs + audits a revocation (action
  `attestation_revocation`); `app.import_reputation(attestations, *, subject=None, config=None,
  verify_with=None, allow_self=False, revocations=None, as_of=None, weight=True)` combines and (with
  `weight`) attaches the prior so the next `app.negotiate` weights an unknown counterparty by what its
  past counterparties attest; `book.attest(subject, *, resolutions=None, config=None, sign=True,
  verify_with=None, horizon_days=None, note="")` / `book.revoke(attestation, *, replacement=None,
  reason="", sign=True)` issue signed as the book owner.
- **Cross-org reputation gossip & attestation exchange.** `from vincio import AttestationExchange,
  ReputationBundle, PeerVisit, GatheredReputation, attestation_a2a_server, gather_reputation` (all also in
  `vincio.settlement.__all__`). A bounded, **pull-based** exchange of the existing signed attestations and
  revocations over the A2A fabric — the discovery analogue for reputation, never a hosted registry or a
  push-based bus. **Peer (server):** `attestation_a2a_server(book, *, revocations=None, attestations=None,
  config=None, name=None, url="", description="", tracer=None, token_validator=None, audit=None)` → an
  `A2AServer` whose Agent Card advertises an `attestation-exchange` skill; answering a subject query it
  returns a `ReputationBundle` of its **own** signed artifacts (the current attestation it can issue from
  `book.attest(subject)` plus held `revocations` for that subject; pass explicit `attestations=` to serve a
  fixed snapshot) — *pull, never push*, a no-history subject yields an attestation-free bundle, never an
  error. `app.serve_attestations(*, book=None, revocations=None, attestations=None, config=None, name=None,
  url="", description="", token_validator=None)` wires it from the app's book and its retained revocations.
  **Importer (client):** `AttestationExchange(client, *, peer_id="")` wraps an `A2AClient`; `.fetch(subject)`
  → a `ReputationBundle`. `gather_reputation(subject, *, peers, directory=None, principal=None, config=None,
  verify_with=None, base=None, allow_self=False, held_attestations=None, held_revocations=None, as_of=None,
  max_peers=None, audit=None, record_audit=True)` → a `GatheredReputation`: visits peers (a dict
  `id→connection` or `(id, conn)` pairs; a connection is an `AttestationExchange`, an in-process `A2AServer`,
  or an `A2AClient`) in deterministic order, **governs** each through `directory` (an `AgentDirectory`
  allow-list, audited — a denied peer skipped and pinpointed), **bounds** the fan-out to `max_peers`,
  **verifies** every fetched artifact from the bytes (a forged/tampered one refused), **dedupes** by content
  hash, and folds the gathered (plus any `held_*`) artifacts into the **same** `combine_attestations` under the
  same freshness/revocation/`[floor, 1]` discipline. `.weight(member_id)` / `.standing(id)` delegate to the
  assembled `PortableReputation` (`.reputation`); `.visits` (a `PeerVisit` each: `.peer`/`.allowed`/`.reachable`/
  `.attestations`/`.revocations`/`.duplicates`/`.reason`/`.contributed`), `.attestations`/`.revocations`
  (deduped), `.peers_visited`/`.peers_reachable`/`.peers_contributing`/`.attestations_gathered`/
  `.revocations_gathered`/`.duplicates`/`.visit_for(peer)`. Every peer visited (`reputation_peer`) and artifact
  fetched (`reputation_fetch`) lands on the audit chain. `app.gather_reputation(subject, **kwargs)` /
  `app.agather_reputation(...)` delegate with `base=self.reputation_ledger`, `audit=self.audit`, and (with
  `weight=True`, the default) attach the assembled prior so the next `app.negotiate` weights an unknown
  counterparty by what its peers attest. Runs byte-for-byte the same against in-process peers
  (`connect_a2a_in_process`) as over the live fabric.
- **Cross-org transitive trust & Sybil-resistant weighting.** `from vincio import TrustConfig, TrustModel,
  IssuerTrust, build_trust_model` (all also in `vincio.settlement.__all__`). Pooling every counted issuer's
  evidence with equal pull lets a clutch of unknown peers out-evidence a few you've lived through, and a Sybil
  cluster manufacture standing by all vouching the same way. **Opt-in** issuer-trust weighting closes that:
  `combine_attestations(attestations, *, ..., trust=None, trust_config=None)` scales each issuer's contributed
  evidence *mass* by the importer's own trust in that issuer (successes and failures together, so it changes how
  much an issuer *pulls*, never the reputation it attests), bounded `[trust_floor, 1]`. With neither `trust` nor
  `trust_config`, pooling is byte-for-byte the pre-trust behavior (every issuer at full pull). `TrustConfig(
  max_depth=1, hop_decay=0.5, trust_floor=0.1, trust_ceiling=1.0)`: `.trust_of(reputation)` maps a standing into
  the band, `.clamp_trust(v)` holds it, `.validate_coherent()`. `build_trust_model(attestations, *, base=None,
  config=None, attestation_config=None, verify_with=None)` → a `TrustModel` by a bounded web-of-trust: **hop 0**
  an issuer the importer has first-hand evidence for in its `base` `ReputationLedger` is trusted as much as that
  ledger weights it; **hops 1..max_depth** an already-trusted issuer that *attests another issuer* (vouches for
  it as a counterparty) lends it trust derived from that pooled standing, attenuated by `hop_decay` per hop;
  **unreached** issuers fall back to `trust_floor` (counted, never zeroed). Only admissible (verified)
  attestations vouch, and an issuer never bootstraps its own trust. **Sybil-resistant** because trust is lent
  only *outward from a trusted root* — a ring of mutually-vouching unknown issuers is never reached and stays at
  the floor, so pull follows earned trust, not issuer count. `TrustModel.trust_in(issuer)` / `.weight(issuer)`
  (alias, so it drops in as a `trust=` source or wherever a ledger is), `.assessment(issuer)`→`IssuerTrust`
  (`.issuer`/`.trust`/`.depth`[0 direct, k transitive, None unreached]/`.direct`/`.vouched_by`/`.reputation`/
  `.transitive`), `.issuers()`/`.direct_issuers()`/`.transitive_issuers()`/`.assessments()`. Pass a `trust=` (a
  `TrustModel`, anything with `trust_in`/`weight`, or an `issuer→float` callable; clamped to `[0,1]`) or a
  `trust_config=` (builds the model from `base` + the *full* attestation set, so a trusted issuer can vouch even
  when `subject` is set). The applied multiplier is pinpointed on `AttestationVerdict.trust` (counted) and
  `SubjectStanding.issuer_trust` (`{issuer: multiplier}`); `PortableReputation.trust` holds the model and
  `.trust_in(issuer)` reads it. `app.import_reputation(..., trust=None, trust_config=None)` /
  `app.gather_reputation(..., trust=None, trust_config=None)` thread it through, rooted in
  `self.reputation_ledger`. Deterministic and offline — never a central trust authority.
- **Cross-org reputation-gated admission & progressive exposure.** `from vincio import AdmissionConfig,
  AdmissionDecision, AdmissionPolicy, AdmissionVerification, admit` (all also in `vincio.settlement.__all__`;
  `Standing` is subpackage-only). A weighted standing was still only *consulted* as a soft negotiation weight;
  nothing **acted** on a thin or low standing to bound up-front exposure. An `AdmissionPolicy` maps the standing
  the fabric earns — an imported `PortableReputation` or a local `ReputationLedger` — to a bounded
  `AdmissionDecision`. `AdmissionConfig(parity_exposure_usd=1000.0, floor_fraction=0.1, full_trust_evidence=10.0,
  ramp_floor=0.2, max_escrow_fraction=0.5, min_sla_factor=0.5)`: exposure is `floor_fraction + (1−floor_fraction)·
  reputation·ramp_progress(evidence)` (`.ramp_progress` climbs `[ramp_floor,1]` to parity at `full_trust_evidence`
  settled deliveries), `.terms_for(reputation, evidence)` → the four terms, `.validate_coherent()`.
  `AdmissionPolicy(config=None).admit(subject, *, reputation=None, ledger=None, standing=None)` →
  `AdmissionDecision`; `.read_standing(source, subject)` gives **local first-hand evidence precedence** (a portable
  prior whose `base` ledger has earned evidence for the subject is read from the ledger, exactly as
  `PortableReputation.weight` resolves it). Module-level `admit(subject, *, reputation=None, ledger=None,
  standing=None, config=None)` is the convenience. `AdmissionDecision` (`.subject`, `.standing` →
  `Standing(weight, reputation, evidence, issuers)`, `.config`, `.exposure_fraction`, `.max_contract_value_usd`,
  `.escrow_fraction`, `.sla_factor`, `.at_parity`, `.issuers`, `.content_hash`, `.audit_id`): **content-bound &
  offline-verifiable** — `.compute_hash`/`.seal`, `.verify()` → `AdmissionVerification(valid, hash_ok, terms_sound,
  reason)` re-derives the terms from the bound standing so a tampered ceiling is caught even after re-sealing,
  `.require_valid()` raises `SettlementError`, `.to_wire`/`.from_wire`. **Folds into the existing path**:
  `.bound_position(position)` clamps a buyer's `NegotiationPosition` price reserve to the ceiling and tightens the
  SLA reserve (a copy; the original is untouched), `.apply_to_terms(terms)` caps a `ContractTerms` price/SLA and
  stamps the escrow posture into `.metadata` (excluded from the contract hash, so the contract stays
  offline-verifiable). A thin or low-trust standing is admitted on conservative terms — discounted exposure, never
  refused — the ceiling ramping toward parity as settled history accrues and a regression walking it back, bounded
  and reversible. `app.admit(subject, *, reputation=None, policy=None, config=None, record_audit=True)` reads the
  same source the negotiation path weights by (`imported_reputation` else `reputation_ledger`) and records the
  decision on the audit chain (action `reputation_admission`, decision `parity`|`graduated`). Deterministic and
  offline — never a hosted underwriting service.
- **Cross-org collateralized settlement & escrow.** `from vincio import Escrow, EscrowConfig, EscrowVerification,
  post_escrow, settle_escrow` (all also in `vincio.settlement.__all__`; `EscrowState`, `EscrowSignature` are
  subpackage-only). The admission-required escrow fraction was still only a *number stamped on the terms*; nothing
  **held** it, released it, or forfeited a slice. `post_escrow(contract, *, decision=None, fraction=None,
  amount=None, poster=None, beneficiary=None, config=None)` → a sealed, unsigned `Escrow` binding the collateral to
  a specific contract: the amount comes from an explicit `amount` (flat), a `fraction` of the price, an
  `AdmissionDecision.escrow_fraction` (`decision=`), or the admission posture `apply_to_terms` stamped onto the
  contract's terms; `poster` defaults to the seller (the admitted counterparty backing its delivery), `beneficiary`
  to the buyer. `Escrow` (`.contract_id`/`.contract_hash`, `.buyer`/`.seller`/`.poster`/`.beneficiary`,
  `.price_usd`/`.escrow_fraction`/`.amount_usd`, `.decision_hash`, `.config`, `.state` (`posted`|`released`|
  `forfeited`), `.shortfall_fraction`/`.forfeited_usd`/`.released_usd`/`.breaches`, `.settlement_hash`,
  `.content_hash`/`.audit_id`, `.is_posted`/`.is_released`/`.is_forfeited`/`.is_resolved`): **content-bound &
  offline-verifiable** — `.compute_hash`/`.seal`, `.sign(signer, party)` (buyer/seller only), `.verify(verifier=None,
  *, require=None)` → `EscrowVerification(valid, hash_ok, terms_sound, signatures_ok, signed_by, reason)` re-derives
  the amount from the fraction and the release/forfeit split from the shortfall so a tampered amount or forfeiture is
  caught even after re-sealing, `.require_valid()`, `.to_wire`/`.from_wire`. `.resolve(record, *, config=None)` /
  `settle_escrow(escrow, record, *, config=None)` settles it against a `SettlementRecord`: a fulfilled delivery
  releases the whole stake, a breach forfeits `min(shortfall, max_forfeit_fraction)·amount` (the per-dimension
  shortfall is how far delivery missed the worst breached term, pinpointed in `.breaches`) and releases the
  remainder — driven by the same record verdict, never the whole stake. `EscrowConfig(max_forfeit_fraction=1.0)`
  caps a single breach's forfeiture (set `<1` for a guaranteed residual). `app.post_escrow(contract, *, decision=,
  fraction=, amount=, poster=, beneficiary=, config=, party=, sign=True)`, `app.settle_escrow(escrow, record, *,
  config=, party=, sign=True)`, and `app.settle(contract, ..., escrow=None, escrow_config=None)` resolve it in the
  same call — every transition signed and on the audit chain (action `escrow`, decision = the state). Deterministic
  and offline — never a hosted escrow custodian or a payment rail.
- **Cross-org collateral pooling & cross-contract margin.** `from vincio import CollateralPool,
  CollateralPoolVerification, PooledContract, post_collateral_pool, draw_pool` (all also in
  `vincio.settlement.__all__`; `PooledContractState`, `PoolStatus` are subpackage-only). An `Escrow` backs *one*
  contract; a counterparty running many concurrent contracts had to lock **separate** collateral per deal even
  though its breaches and clean deliveries net out (capital stranded contract-by-contract the way bilateral
  settlements were before netting). A `CollateralPool` is a **bounded margin account** posted once that backs many
  contracts — the collateral analogue of a `NettingSet`. `post_collateral_pool(contracts, *, poster=None,
  posted=None, decisions=None, fraction=None, config=None)` → a sealed, unsigned `CollateralPool`: each contract's
  `required_usd` re-derives via the same source resolver as `post_escrow` (a matching `AdmissionDecision` in
  `decisions` — a dict keyed by contract id or one decision for all — a uniform `fraction`, or the posture stamped
  onto each contract's terms); `poster` defaults to the common seller; `posted` defaults to the total required (so
  the pool starts exactly collateralized). Each open contract is **allocated** `required_usd × coverage`
  (`coverage = min(1, balance/required_open)`), proportional to its requirement. `CollateralPool`
  (`.poster`/`.contracts` (`PooledContract`: `.contract_id`/`.contract_hash`, `.buyer`/`.seller`/`.beneficiary`,
  `.required_usd`/`.allocated_usd`, `.state` (`open`|`released`|`forfeited`), `.shortfall_fraction`/
  `.forfeited_usd`/`.released_usd`/`.breaches`, `.settlement_hash`), `.posted_usd`/`.drawn_usd`/`.balance_usd`/
  `.required_open_usd`/`.available_usd`/`.topup_usd`/`.coverage`, `.status` (`posted`|`active`|`settled`),
  `.needs_topup`/`.residual_usd`/`.parties`/`.beneficiaries`/`.open_contracts`, `.contract(id)`): **content-bound &
  offline-verifiable** — `.compute_hash`/`.seal` (contracts sorted by id so add-order is irrelevant), `.sign(signer,
  party)` (poster or a counterparty only), `.verify(verifier=None, *, require=None)` →
  `CollateralPoolVerification(valid, hash_ok, terms_sound, signatures_ok, signed_by, reason)` re-derives every
  allocation and reconciles the balance (`balance == posted − drawn`, top-up == `max(0, required_open − balance)`,
  each forfeiture == `min(shortfall, max_forfeit_fraction)·required`) so a tampered allocation/balance/forfeiture is
  caught even after re-sealing, `.require_valid()`, `.to_wire`/`.from_wire`. `.draw(record, *, config=None)` /
  `draw_pool(pool, record, *, config=None)` settles one backed contract against its `SettlementRecord`: a clean
  delivery releases its requirement back to the available balance (frees capital for the next deal), a breach draws
  a bounded slice from the shared stake and releases the rest — driven by the same record verdict, never the whole
  stake. `.back(contract, *, decision=/fraction=/amount=, beneficiary=)` adds a contract to the open pool (may
  surface a top-up); `.top_up(amount)` adds capital to clear a top-up obligation. Reuses `EscrowConfig`
  (`max_forfeit_fraction`) for the forfeiture policy. `app.post_collateral_pool(contracts, *, poster=, posted=,
  decisions=, fraction=, config=, party=, sign=True)`, `app.draw_pool(pool, record, *, config=, party=, sign=True)`,
  and `app.settle(contract, ..., pool=None)` draw it in the same call — every transition signed and on the audit
  chain (action `collateral_pool`, decision = the status). Deterministic and offline — never a hosted clearing
  house, a margin custodian, or a payment rail.
- **Cross-org collateral rehypothecation guards & re-use bounds.** `from vincio import CollateralLedger,
  CollateralLedgerVerification, ReuseBreach, BeneficiaryClaim, guard_collateral` (all also in
  `vincio.settlement.__all__`; `LedgerPool`, `LedgerContract` are subpackage-only). A `CollateralPool` only ever
  re-allocates capital *within itself*, so nothing bounded a counterparty that pledged the **same** stake across more
  than one pool — the same capital double-counted, over-stating what backs each deal (the collateral analogue of a
  `SettlementRecord` double-counted before netting deduplicated it). A `CollateralLedger` is the **rehypothecation
  guard**. `guard_collateral(pools, *, poster=None, held=None, custody=None, verify_with=None)` → a sealed, unsigned
  `CollateralLedger`: reads a counterparty's pools (refusing one whose content hash no longer recomputes; a forged
  pool signature too, with `verify_with`), reconciles what they collectively pledge (`pledged_usd` = Σ live
  `balance_usd`) against the capital it actually holds (`held_usd`; from a `custody` proof-of-reserves, an asserted
  `held=`, or — by default — the gross pledge minus the provably double-pledged capital; `held` and `custody` are
  mutually exclusive). `CollateralLedger` (`.poster`/`.pools` (`LedgerPool`)/`.pool_hashes`, `.posted_usd`/
  `.pledged_usd`/`.held_usd`/`.available_usd`/`.reuse_usd`/`.duplicate_pledge_usd`, `.reserves_proven`/`.custodian`/
  `.custody_hash`/`.reserves_usd`, `.breaches` (`ReuseBreach`:
  `.contract_id`/`.beneficiary`/`.pools`/`.secured_usd`/`.pledged_usd`/`.excess_usd`), `.claims` (`BeneficiaryClaim`:
  `.beneficiary`/`.claim_usd`/`.secured_usd`/`.unsecured_usd`/`.share`/`.is_secured`), `.reserve_breach`
  (`UnderReservedBreach`: `.custodian`/`.attestation_hash`/`.reserves_usd`/`.pledged_usd`/`.shortfall_usd`),
  `.over_committed`/`.within_bounds`/`.under_reserved`/`.status` (`over_committed`|`within_bounds`),
  `.breach(id)`/`.claim(beneficiary)`): a contract
  pledged across more than one pool is a pinpointed `ReuseBreach` (its collateral honorable once, the excess provably
  double-pledged), and when a stake backs deals for more than one beneficiary each claim is bounded to its
  deterministic **pari-passu** share of the held capital (proportional to its claim) so a forfeiture cannot pay one
  beneficiary out of capital another has first claim on. **Content-bound & offline-verifiable** —
  `.compute_hash`/`.seal` (pools/breaches/claims sorted so fold-order is irrelevant), `.sign(signer, party)`,
  `.verify(verifier=None, *, require=None)` → `CollateralLedgerVerification(valid, hash_ok, terms_sound,
  signatures_ok, signed_by, reason)` re-derives the pledged total, the re-use breaches, the beneficiary
  apportionment, and the under-reserved breach so a tampered figure is caught even after re-sealing, `.require_valid()`,
  `.require_within_bounds()` (raises if over-committed), `.require_reserved()` (raises if under-reserved),
  `.to_wire`/`.from_wire`.
  `app.guard_collateral(pools, *, poster=, held=, custody=, sign=True, verify_with=, record_audit=True)` and
  `book.guard_collateral(...)` sign it and record the guard on the audit chain (action `rehypothecation`, decision =
  the status). Deterministic and offline — never a hosted custodian, a clearing house, or a payment rail.
- **Cross-org collateral custody attestation & proof-of-reserves.** `from vincio import CustodyAttestation,
  CustodyAttestationVerification, ReserveLine, attest_custody` (all also in `vincio.settlement.__all__`). The
  rehypothecation guard's `held` figure was *asserted*, not proven — a counterparty over-stating its reserves still
  passed. A `CustodyAttestation` makes it **evidence-backed**: a signed, content-bound **proof-of-reserves**.
  `attest_custody(poster, reserves, *, custodian=None, as_of=None)` → a sealed, unsigned `CustodyAttestation`:
  `reserves` is a number, a `{account: amount}` mapping, or `ReserveLine`/`(account, amount)` items (a negative
  holding is refused); `custodian` defaults to `poster` (self-custody). `CustodyAttestation` (`.custodian`/`.poster`/
  `.reserves` (`ReserveLine`: `.account`/`.amount_usd`/`.note`)/`.reserves_usd`/`.as_of`, `.self_custody`/`.accounts`,
  `.compute_hash`/`.seal`, `.sign(signer, *, party=None)` (only the custodian signs), `.verify(verifier=None, *,
  require=None)` → `CustodyAttestationVerification(valid, hash_ok, reserves_sound, signatures_ok, signed_by, reason)`
  re-derives the reserve total from the line items so a tampered figure is caught even after re-sealing,
  `.require_valid()`, `.audit_details`/`.to_wire`/`.from_wire`). `guard_collateral(..., custody=)` reads
  `.reserves_usd` as the `held` figure (`.reserves_proven` on the ledger), surfacing an `UnderReservedBreach` when the
  proven reserves fall below the pledges — refusing a tampered figure, a forged custodian (with `verify_with`), or an
  attestation for a different poster. `app.attest_custody(poster, reserves, *, custodian=, as_of=, sign=True,
  record_audit=True)` / `book.attest_custody(...)` sign it as the custodian and record it on the audit chain (action
  `custody_attestation`, decision = `self_custody`|`custodied`). Offline — never a hosted custodian or a
  proof-of-reserves auditor.
- **Cross-org custody liability attestation & proof-of-solvency.** `from vincio import LiabilityAttestation,
  LiabilityAttestationVerification, LiabilityLine, InsolvencyBreach, SolvencyProof, SolvencyProofVerification,
  attest_liabilities, prove_solvency` (all also in `vincio.settlement.__all__`). Proof-of-reserves proves the capital a
  counterparty *holds*, but reserves are one side of the ledger — a counterparty solvent against one buyer may be
  under-water once *every* obligation it owes is counted. A `LiabilityAttestation` makes the liability side
  evidence-backed: `attest_liabilities(poster, liabilities, *, attestor=None, as_of=None)` → a sealed, unsigned
  `LiabilityAttestation` over the total obligations owed (`liabilities` is a number, a `{creditor: amount}` mapping, or
  `LiabilityLine`/`(creditor, amount)` items; a negative obligation is refused; `attestor` defaults to `poster` —
  self-attested). `LiabilityAttestation` (`.attestor`/`.poster`/`.liabilities` (`LiabilityLine`:
  `.creditor`/`.amount_usd`/`.note`)/`.liabilities_usd`/`.as_of`, `.self_attested`/`.creditors`, `.compute_hash()`/
  `.seal()`/`.sign(signer, *, party=None)` (only the attestor signs), `.verify(verifier=None, *, require=None)` →
  `LiabilityAttestationVerification(valid, hash_ok, liabilities_sound, signatures_ok, signed_by, reason)` re-derives the
  total from the line items so a tampered figure is caught even after re-sealing, `.require_valid()`,
  `.audit_details`/`.to_wire`/`.from_wire`). `prove_solvency(custody, liabilities, *, poster=None, completeness=None,
  as_of=None, verifier=None)` folds a proven `CustodyAttestation` against a proven `LiabilityAttestation` for the same
  poster (refusing a tampered, forged, or wrong-poster attestation; pass `completeness=` a `CompletenessProof` to bound
  the margin by the completed total) → a sealed, unsigned `SolvencyProof` (`.poster`/`.custodian`/
  `.attestor`/`.custody_hash`/`.liability_hash`/`.reserves_usd`/`.liabilities_usd`/`.margin_usd` (reserves − liabilities),
  `.solvent`/`.insolvent`/`.status` (`solvent`|`insolvent`), `.solvency_adjusted_held` (`max(0, margin)` — the
  unencumbered capital), `.breach` (`InsolvencyBreach`: `.poster`/`.custodian`/`.attestor`/`.custody_hash`/
  `.liability_hash`/`.reserves_usd`/`.liabilities_usd`/`.shortfall_usd`), `.verify(verifier=None, *, require=None)` →
  `SolvencyProofVerification(valid, hash_ok, margin_sound, signatures_ok, signed_by, reason)` re-derives the margin and
  breach so a flipped verdict is caught even after re-sealing, `.require_valid()`, `.require_solvent()` (raises if
  insolvent), `.sign(signer, *, party)`, `.audit_details`/`.to_wire`/`.from_wire`). `guard_collateral(..., solvency=)`
  reads `.solvency_adjusted_held` as the `held` figure (`.solvency_adjusted` on the ledger, with `.attestor`/
  `.liability_hash`/`.liabilities_usd`/`.solvency_margin_usd`/`.gross_reserves_usd`/`.insolvent`/`.require_solvent()`),
  bounding pledges against capital not already owed elsewhere — refusing a tampered proof, a forged signature (with
  `verify_with`), or a proof for a different poster. `app.attest_liabilities(poster, liabilities, *, attestor=,
  as_of=, sign=True, record_audit=True)` / `book.attest_liabilities(...)` sign it as the attestor (action
  `liability_attestation`, decision = `self_attested`|`attested`), and `app.prove_solvency(custody, liabilities, *,
  poster=, as_of=, verify_with=, sign=True, record_audit=True)` / `book.prove_solvency(...)` sign and record the proof
  (action `solvency_proof`, decision = `solvent`|`insolvent`). When a completeness check is folded the proof carries
  `.attested_liabilities_usd` (the attestor's figure), `.completeness_hash`, `.completeness_adjusted`, and
  `.understated_usd`. Offline — never a hosted solvency auditor.
- **Cross-org liability inclusion proofs & completeness.** `from vincio import MerkleStep, InclusionProof,
  InclusionProofVerification, OmissionBreach, CompletenessProof, CompletenessVerification, check_completeness` (all also
  in `vincio.settlement.__all__`). A `LiabilityAttestation`'s total is still one number — a counterparty could
  under-state what it owes by omitting a creditor. The attestation now commits its line items into a Merkle root
  (`.liabilities_root`, bound in the signed hash; the total *and* root re-derive on every verify), so each creditor gets
  an `InclusionProof`: `attestation.inclusion_proof(creditor)` / `app.inclusion_proof(liabilities, creditor)` /
  `book.inclusion_proof(...)` → `InclusionProof` (`.creditor`/`.amount_usd`/`.leaf_index`/`.leaf_count`/`.path`
  (`MerkleStep`: `.sibling`/`.sibling_on_right`)/`.liabilities_root`/`.liability_hash`, `.verify(attestation=None,
  verifier=None)` → `InclusionProofVerification(valid, path_ok, bound_ok, signed_by, reason)` reconstructs the root from
  the leaf+path and, with the attestation, checks the leaf is really one it commits to; `.require_valid()`,
  `.to_wire`/`.from_wire`); `attestation.inclusion_proofs()` lists one per line; an unknown or ambiguous creditor is
  refused. `check_completeness(liabilities, claims, *, verifier=None, as_of=None)` / `app.check_completeness(...)` /
  `book.check_completeness(liabilities, claims=None, ...)` (claims default to the book's own settled records against the
  poster) folds creditor claims (a `{creditor: amount}` mapping, `LiabilityLine` / `SettlementRecord` /
  `(creditor, amount)` items) against the attestation (refusing a tampered/forged attestation) → a sealed
  `CompletenessProof` (`.poster`/`.attestor`/`.liability_hash`/`.liabilities_root`/`.attested_usd`/`.claimed_usd`/
  `.completed_usd` (attested + proven understatements)/`.breaches` (`OmissionBreach`: `.creditor`/`.attested_usd`/
  `.claimed_usd`/`.understatement_usd`/`.omitted`)/`.complete`/`.status`/`.understated_usd`/`.omitted_creditors`,
  `.verify(verifier=None, *, require=None)` → `CompletenessVerification(valid, hash_ok, completeness_sound,
  signatures_ok, signed_by, reason)` re-derives the completed total and breaches (a dropped omission caught by
  `completed ≥ claimed`), `.require_valid()`, `.require_complete()` (raises on any omission), `.sign(signer, *, party)`,
  `.audit_details`/`.to_wire`/`.from_wire`). `prove_solvency(..., completeness=)` reads `.completed_usd` instead of the
  attestor's figure (refusing a check for a different poster/attestation), so the solvency margin is bounded by the
  obligations creditors can prove. App/book sign and record the check (action `liability_completeness`, decision =
  `complete`|`incomplete`). Offline — never a hosted attestation registry.
- **Cross-org liability non-equivocation & root consistency.** `from vincio import RootCommitment,
  RootCommitmentVerification, EquivocationProof, EquivocationProofVerification, RootConsistencyReport,
  prove_equivocation, check_root_consistency` (all also in `vincio.settlement.__all__`). Completeness catches an omission
  only when the omitted creditor folds its own claim, but a counterparty issues its attestation per relationship — so it
  can **equivocate**, signing a smaller `liabilities_root` for one creditor and a different one for another, each
  creditor's `InclusionProof` verifying against the root *it* was shown. `attestation.root_commitment()` →
  `RootCommitment` (`.poster`/`.attestor`/`.as_of`/`.liabilities_root`/`.liabilities_usd`/`.liability_hash`/`.signature`,
  `.consistency_key` (`(poster, attestor, as_of)`), `.conflicts_with(other)`, `.verify(verifier=None)` →
  `RootCommitmentVerification(valid, committed, signed_ok, signed_by, reason)`, `.to_wire`/`.from_wire`) — a signed,
  privacy-preserving digest of the root and `as_of` the attestor signed, **without** the line items, that creditors
  compare over the attestation exchange. `prove_equivocation(first, second, *, verifier=None, first_creditor="",
  second_creditor="")` folds two attestations a poster signed for the same `(poster, attestor, as_of)` with different
  roots → an `EquivocationProof` (`.poster`/`.attestor`/`.as_of`/`.first`/`.second` (whole attestations, canonical
  content-hash order)/`.first_root`/`.second_root`/`.first_creditor`/`.second_creditor`/`.roots`/`.creditors`/
  `.liabilities_gap_usd`, `.verify(verifier=None, *, require=None)` → `EquivocationProofVerification(valid, hash_ok,
  attestations_ok, conflict_ok, attestor_signed, signatures_ok, signed_by, reason)` re-derives each embedded root from
  the bytes and (with the verifier) checks the attestor signed each so a forged conflicting root is refused,
  `.require_valid()`, `.sign(signer, *, party)`, `.audit_details`/`.to_wire`/`.from_wire`); refuses different
  posters/instants (distinct snapshots) or identical roots (no conflict). `check_root_consistency(attestations, *,
  verifier=None)` groups a set of held attestations (bare or `(creditor, attestation)`) by their key and folds every
  conflicting pair → a `RootConsistencyReport` (`.consistent`/`.checked`/`.keys`/`.equivocations`/`.equivocating_posters`,
  `.require_consistent()`, `.to_wire`/`.from_wire`); a tampered or (with a verifier) forged/unsigned root is excluded as
  inadmissible, so it cannot manufacture a false accusation. `app.check_root_consistency(attestations, *, verify_with=,
  record_reputation=True, record_audit=True)` / `book.check_root_consistency(...)` record each equivocation (action
  `liability_equivocation`, decision `equivocation`) on the audit log and ding the equivocating poster on the bound
  reputation ledger. Offline — never a hosted transparency log.
- **Cross-org liability history consistency & snapshot monotonicity.** `from vincio import Discharge,
  DischargeVerification, discharge_liability, MonotonicityBreach, HistoryConsistencyProof,
  HistoryConsistencyProofVerification, HistoryConsistencyReport, check_history_consistency` (all also in
  `vincio.settlement.__all__`). Non-equivocation is scoped to one `as_of`; a counterparty can still issue a *later*
  snapshot that quietly drops a past obligation. A `LiabilityAttestation` now carries an optional commitment to the prior
  snapshot (`.prior_hash`/`.prior_root`/`.prior_as_of`, `.has_prior`), bound into its signed hash, set via
  `attest_liabilities(poster, liabilities, *, attestor=None, as_of=None, prior=None)` or `attestation.link_to(prior)`
  (same `(poster, attestor)`, strictly later `as_of` — a back-dated link is refused and caught from the bytes). A
  `Discharge` (`discharge_liability(poster, creditor, amount_usd, *, as_of=None, note="")`: `.poster`/`.creditor`/
  `.amount_usd`/`.as_of`/`.status` (`partial`|`empty`), `.sign(signer, *, party=None)` — signed by the **creditor** only,
  `.verify(verifier=None, *, require=None)` → `DischargeVerification(valid, hash_ok, sound, signatures_ok, signed_by,
  reason)`, `.audit_details`/`.to_wire`/`.from_wire`) is the creditor's signed release that legitimizes a drop.
  `check_history_consistency(attestations, *, discharges=None, verifier=None)` groups snapshots by `(poster, attestor)`,
  walks each chain in `as_of` order, and folds it into a `HistoryConsistencyProof` (`.poster`/`.attestor`/`.snapshots`/
  `.discharges`/`.breaches`/`.chain_linked`/`.head_hash`/`.span_from`/`.span_to`, `.monotone`/`.consistent`/`.linked`/
  `.snapshot_count`/`.status`/`.breaching_creditors`/`.unexplained_usd`, `.verify(verifier=None, *, require=None)` →
  `HistoryConsistencyProofVerification(valid, hash_ok, snapshots_ok, chain_ok, monotone_sound, attestor_signed,
  signatures_ok, signed_by, reason)`, `.require_valid`/`.require_monotone`/`.require_linked`, `.sign(signer, *, party)`,
  `.audit_details`/`.to_wire`/`.from_wire`). A creditor obligation that shrinks between snapshots without a signed,
  in-window discharge is a `MonotonicityBreach` (`.poster`/`.attestor`/`.creditor`/`.prior_hash`/`.next_hash`/
  `.prior_usd`/`.next_usd`/`.dropped_usd`/`.discharged_usd`/`.unexplained_usd`). The check returns a
  `HistoryConsistencyReport` (`.consistent`/`.checked`/`.chains`/`.proofs`/`.breaching_posters`, `.require_consistent()`,
  `.to_wire`/`.from_wire`); a tampered or (with a verifier) unsigned snapshot is excluded as inadmissible, and a forged or
  poster-signed discharge does not explain a drop. `app.check_history_consistency(attestations, *, discharges=None,
  verify_with=None, record_reputation=True, record_audit=True)` / `book.check_history_consistency(...)` record each
  inconsistent history (action `liability_history`, decision `consistent`|`inconsistent`) and ding the breaching poster;
  `app.discharge_liability(poster, amount_usd, *, creditor=None, as_of=None, note="")` / `book.discharge_liability(...)`
  sign and record a discharge (action `liability_discharge`). Offline — never a hosted transparency log.
- **Cross-org insolvency resolution & liability seniority waterfall.** `from vincio import SeniorityTranche,
  SeniorityVerification, SenioritySchedule, build_seniority_schedule, CreditorRecovery, WaterfallTranche,
  InsolvencyResolution, InsolvencyResolutionVerification, resolve_insolvency` (all also in `vincio.settlement.__all__`). A
  `SolvencyProof` *flags* an insolvency but says nothing about which creditors the scarce reserves pay, or in what order.
  `build_seniority_schedule(poster, tranches, *, as_of=None)` ranks the obligations into a sealed, unsigned
  `SenioritySchedule` — `tranches` is an ordered spec: a list of creditor-name lists (position = priority, rank 0 most
  senior, e.g. `[["bank"], ["acme", "globex"]]`), `SeniorityTranche(rank, creditors, label)` items, or `{rank, creditors,
  label}` dicts. `SenioritySchedule` (`.poster`/`.tranches`/`.as_of`, `.ranks`/`.residual_rank` (one below the most-junior
  listed tranche — an unlisted creditor falls here)/`.creditors`, `.ranking()` → `{creditor: rank}`, `.rank_of(creditor)`,
  `.compute_hash()`/`.seal()`, `.sign(signer, *, party)` — signed by the poster or its creditors, `.verify(verifier=None,
  *, require=None)` → `SeniorityVerification(valid, hash_ok, well_formed, signatures_ok, signed_by, reason)` (a duplicate
  rank or a creditor in two tranches is not `well_formed`), `.require_valid`, `.audit_details`/`.to_wire`/`.from_wire`).
  `resolve_insolvency(custody, liabilities, schedule=None, *, poster=None, completeness=None, solvency=None, set_off=None,
  as_of=None, verifier=None)` reuses `prove_solvency` (so a tampered/forged/wrong-poster attestation is refused) and
  distributes the proven reserves across the obligations **by seniority then pari-passu within a tranche** into an
  `InsolvencyResolution` (`.poster`/`.custodian`/`.attestor`/`.custody_hash`/`.liability_hash`/`.completeness_hash`/
  `.solvency_hash`/`.schedule_hash`/`.set_off_hashes`, `.reserves_usd`/`.liabilities_usd` (net of set-off)/
  `.gross_liabilities_usd`/`.attested_liabilities_usd`/`.set_off_usd`/`.distributed_usd`/`.shortfall_usd`/
  `.surplus_usd`/`.residual_rank`, `.tranches` (`WaterfallTranche`: `.rank`/`.label`/`.claim_usd`/`.paid_usd`/`.coverage`/
  `.creditors`), `.recoveries` (`CreditorRecovery`: `.creditor`/`.rank`/`.label`/`.claim_usd`/`.recovery_usd`/
  `.shortfall_usd`/`.recovery_rate`/`.gross_claim_usd`/`.set_off_usd`/`.made_whole`/`.set_off`), `.solvent`/`.insolvent`/
  `.status` (`solvent`|`resolved`)/`.fully_recovered`/`.shortfall_bearers` (ordered by seniority)/`.recovery_rate`/
  `.set_off`, `.recovery_of(creditor)`,
  `.verify(verifier=None, schedule=None, set_off=None, *, require=None)` → `InsolvencyResolutionVerification(valid, hash_ok,
  distribution_sound, schedule_bound, set_off_bound, signatures_ok, signed_by, reason)` — re-derives the **entire** waterfall from the
  recorded per-creditor claims/ranks/reserves (an over-stated recovery, a re-ordered tranche, or a junior creditor paid
  ahead of a senior one is refused even after re-sealing) and, with `schedule`, binds each creditor's rank to the signed
  schedule, `.require_valid`/`.require_fully_recovered`, `.sign(signer, *, party)`, `.audit_details`/`.to_wire`/
  `.from_wire`). With no `schedule` the whole set is one pari-passu tranche (the rehypothecation guard's apportionment);
  pass `completeness` (a `CompletenessProof`) to distribute against the *completed* liability set. `app.build_seniority_schedule(poster,
  tranches, *, as_of=None, sign=True, record_audit=True)` / `book.build_seniority_schedule(...)` sign and record the
  schedule (action `seniority_schedule`, decision `self_ranked`|`ranked`); `app.resolve_insolvency(custody, liabilities,
  schedule=None, *, poster=None, completeness=None, solvency=None, set_off=None, as_of=None, verify_with=None, sign=True,
  record_reputation=True, record_audit=True)` / `book.resolve_insolvency(...)` sign and record the resolution (action
  `insolvency_resolution`, decision `solvent`|`resolved`) and ding a poster that could not make its creditors whole on the
  reputation path. Offline — never a hosted receiver or a bankruptcy court.
- **Cross-org insolvency set-off & close-out netting.** `from vincio import SetOffStatement, build_set_off_statement,
  set_off_from_records`. A creditor of an insolvent estate is often *also* a debtor of it, paid on its **gross** claim
  while it still owes the other side; close-out netting collapses the mutual obligations to a single net claim *before*
  the waterfall. `build_set_off_statement(poster, creditor, owed_usd, owing_usd, *, references=None, as_of=None)` states
  the obligations running both ways — `owed_usd` the poster owes, `owing_usd` the creditor owes back — into a sealed
  `SetOffStatement` (`.poster`/`.creditor`/`.owed_usd`/`.owing_usd`/`.net_debtor`/`.net_creditor`/`.net_usd`/`.references`,
  `.poster_net_claim_usd` (`max(0, owed − owing)`)/`.set_off_usd` (`min(owed, owing)`)/`.creditor_in_debit`/`.eliminated`/
  `.direction` (`poster_owes`|`creditor_in_debit`|`eliminated`)/`.mutual`, `.compute_hash()`/`.seal()`, `.sign(signer, *,
  party)` — signed by **both** parties, `.verify(verifier=None, *, require=None, require_mutual=False)` →
  `SetOffVerification(valid, hash_ok, well_formed, net_sound, signatures_ok, signed_by, reason)` (the net re-derives from
  the gross; `require_mutual` refuses a one-sided claim), `.require_valid`, `.audit_details`/`.to_wire`/`.from_wire`).
  `set_off_from_records(poster, creditor, liabilities, records, *, as_of=None, verifier=None)` derives a statement straight
  from the existing `LiabilityAttestation` (the `owed_usd`) and `SettlementRecord`s (the `owing_usd`, deduped by hash) — a
  tampered artifact refused, a forged signature too with a verifier. Pass `set_off=[...]` to `resolve_insolvency` to net
  each creditor to its net claim before distributing (a creditor in debit recovers nothing; an over-stated set-off claiming
  a different gross than the attestation, or a one-sided statement, is refused), reconciled against the *completed* gross
  and bound into the resolution by hash. `app.build_set_off_statement(poster, creditor, owed_usd, owing_usd, *,
  references=None, as_of=None, sign=True, record_audit=True)` / `book.build_set_off_statement(poster, creditor,
  owed_usd=None, owing_usd=None, *, liabilities=None, references=None, as_of=None, verify_with=None, sign=True)` sign and
  record the statement (action `liability_set_off`, decision = the net direction). Offline — never a hosted clearing house
  or a bankruptcy court.
- **Cross-org engagement lifecycle (capstone — fabric feature-complete & frozen).** `from vincio import
  CrossOrgEngagement, EngagementNarrative, EngagementStage, EngagementSignature, EngagementVerification`. The capstone that
  unifies the twenty cross-org rungs into one coherent, conformance-proven system. `app.cross_org_engagement(*, buyer="",
  seller="", scope="", coordinator=None)` → a `CrossOrgEngagement` facade that threads the whole pipeline behind one
  governed, audited call-path: `negotiate(*, buyer, seller, require_agreement=True, **kw)` →contract, `admit(subject=None,
  **kw)`, `choreograph(saga, *, participants, **kw)` (pass `directory=` to discover), `settle(contract=None, **kw)` /
  `settle_saga(result=None, *, contracts, **kw)`, `net(**kw)`, `arbitrate(records, **kw)`, `attest_reputation(subject=None,
  **kw)` / `import_reputation(attestations, **kw)`, `post_escrow` / `post_collateral_pool` / `guard_collateral`,
  `attest_custody` / `attest_liabilities` / `prove_solvency` / `check_completeness` / `check_root_consistency` /
  `check_history_consistency`, and `resolve_insolvency(custody, liabilities, schedule=None, **kw)`. **Purely
  compositional:** each method delegates to the *same* `app.*` primitive (unchanged and usable directly), captures the
  artifact (exposed as `eng.contract`/`.delivery`/`.netting`/`.insolvency`/…), and records it as an `EngagementStage`.
  `eng.record_stage(stage, artifact, **summary)` is an escape hatch for any other artifact. `eng.seal(*, sign=True,
  record_audit=True)` → a content-bound, signed `EngagementNarrative` on the audit log (action `cross_org_engagement`);
  each stage binds the verb, the artifact's own content hash, and a digest of its bytes into a hash-chained link.
  `narrative.verify(verifier=None, *, require=None, artifacts=None)` recomputes the whole chain from the bytes alone
  (`intact`/`head_ok`/`hash_ok`/`digests_ok`/`signatures_ok`/`broken_at`); `eng.verify(verifier=None, *, require=None)`
  re-digests every captured live artifact too, so a re-ordered stage, an edited digest, an edited underlying artifact, or a
  forged signature is caught. `narrative.to_wire`/`from_wire`, `require_valid`, `stage_names`, `print_summary`. With this
  capstone the cross-org settlement & credit surface is **feature-complete and frozen** under the stability policy — no
  further cross-org *primitive* is scheduled. Offline — never a hosted orchestration service or a managed control plane.
- **Community pack & skill registry.** `from vincio import CommunityRegistry,
  BundleRecord`; a signed, content-bound (SHA-256 + `HMACSigner`/`Ed25519Signer`)
  index of opt-in packs and `SKILL.md` bundles. `registry.publish_pack/skill(...)`,
  `registry.load_pack/load_skill(name)` — resolution passes the same `AllowListGate`
  the fabric uses, verifies the signature, and records an audited `bundle_resolve`
  decision; tamper/unlisted/unsigned are denied. `sign_index()`/`verify_index()`.
- **Plugins.** `from vincio import installed_plugins, load_plugins,
  discover_plugins`; `from vincio.plugins import PLUGIN_API_VERSION`. Entry-point
  groups `vincio.{providers,embedders,stores,connectors,chunkers,rerankers,metrics,
  judges,packs}` register third-party extensions on install; a distribution may
  declare its targeted API major via `vincio.plugins:api_version` (major mismatch →
  reported + skipped). `connect()`/`load_pack()` auto-load on a name miss; `vincio
  plugins list` (CLI).
- **Generative UI.** `from vincio.server.agui import AGUIEvent,
  run_stream_to_agui, agent_stream_to_agui`; SSE `POST /v1/apps/{id}/agui`;
  `AgentExecutor.astream` /
  `Crew.astream` yield `AgentEvent`/`CrewEvent` (lifecycle, genuine provider token
  deltas, tool events) — inherits the run's provenance/budget/audit.
- **Framework interop & DX.** `from vincio.interop import add_langchain_tool,
  from_langchain_loader/retriever/embeddings, from_llamaindex_reader/retriever/
  embedding, add_llamaindex_tool, from_haystack_retriever/document/embedder,
  add_haystack_component, from_dspy_module/retriever/signature, add_dspy_module,
  to_dspy_lm` (duck-typed `from_*`) + `to_langchain_*`/`to_llamaindex_*`/
  `to_haystack_*` (extras `vincio[langchain|llamaindex|haystack|dspy]`); packs
  `app.use_pack(name)` (`load_pack`, `available_packs`, `register_pack`) — domain
  packs `support|engineering|finance|legal` and full-stack vertical packs
  `healthcare|ediscovery|kyc|customer_support|code_review` (the `Pack` contract's
  `retrieval`/`memory`/`residency`/`purpose` fields also preconfigure retrieval,
  scoped memory, rails, metrics, and a residency posture); `enable_rich_reprs`
  (notebook), `vincio tui`, `config_json_schema()`; voice/realtime `from
  vincio.realtime import RealtimeSession, connect_realtime` /
  `app.realtime_session(...)` (backends inprocess|openai|gemini; extra
  `vincio[realtime]`).

## Stability

- SemVer on the frozen public surface (`vincio.__all__` /
  `vincio.stability.public_api()`, `API_VERSION == "3.0"`); `from vincio import
  deprecated, experimental, stability_of` (`@deprecated(since=, removed_in=,
  alternative=)` / `@experimental(since=)` emit warnings, escalatable to errors).
  Nothing public is removed in a minor/patch — only deprecated then removed at the
  next major. `vincio doctor [path]` reports a project's deprecated-API usage
  (replacement + removal version from `stability_of`) and config schema drift.
- Typing: the package ships `py.typed` (PEP 561) and is type-checked end to end; a
  graduated, CI-enforced `mypy --strict` set (`stability`, `core.errors`,
  `core.error_catalog`, `core.config`, `core.config_migrations`, `_apiref`,
  `cli.doctor`) grows over time (`docs/reference/typing.md`).
- Errors: every `VincioError` carries a stable `.code`, a `.remediation` hint, and
  a `.docs_url` from a completeness-gated, internationalizable catalog
  (`vincio.core.error_catalog`: `ERROR_CATALOG`, `remediation_for`, `docs_url_for`,
  `register_error_locale`; `docs/reference/errors.md`). Catch the family with one
  `except VincioError`; branch on `.code`; surface `.remediation`. Message strings
  are not stable; codes and the catalog are.
- Config migrations: `VincioConfig.schema_version` + `vincio.core.config_migrations`
  (`CONFIG_SCHEMA_VERSION`, `migrate`, `needs_migration`); `load_config` upgrades
  stale files in memory, `vincio config migrate` persists the upgrade.
- Docstring coverage is gated (`vincio._apiref.undocumented_symbols()` is empty);
  the exhaustive API index is generated (`docs/reference/api-generated.md`).
- Published SLOs (`benchmarks/slos.json`, `docs/reference/slo.md`) each enforced
  by an at-least-as-strict VincioBench budget (`tests/test_slos.py`). Tool sandbox
  `setrlimit` CPU/memory/fd limits (`run_subprocess_sandboxed` /
  `SandboxedPython(max_cpu_seconds=, max_memory_bytes=, max_open_files=)`;
  `SandboxError`). Threat model in
  `docs/security/threat-model.md`.

## Edge / WASM runtime

- `vincio.edge` runs the dependency-free compile → score → rail → pack core at
  the edge / in the browser (Pyodide/WASM), behind a thin in-process boundary.
  `EdgeRuntime(profile=EdgeProfile.browser()).run(EdgeRequest(task=..., evidence=[...]))`
  → `EdgeResult` (`.packet` slim `ContextPacket`, `.prompt` rendered model-ready
  text, `.resident_bytes`, `.within_profile`, `.allowed`, `.rail_check`). No
  provider, network, filesystem, or caller-owned event loop. `.run` is sync
  (works under a WASM host loop); `.arun` is async. Accepts a plain string too.
- `EdgeProfile` bounds the compiled packet — `max_resident_bytes` /
  `max_input_tokens` / `max_evidence_items` — and lowers to the *same*
  `ContextCompilerOptions` the server reads (`.to_compiler_options()`). Presets:
  `EdgeProfile.browser()` (256 KiB / 4096 tok), `.worker()` (the default), and
  `.server_like()` (for parity testing). The footprint stays under the cap as the
  corpus grows 10×, held by slimming + eviction; `run(..., strict=True)` raises
  `EdgeError` instead of `within_profile=False` on a breach.
- Parity, not a fork: `verify_edge_parity()` → `EdgeParityReport` proves the edge
  packet is byte-identical (same `spec_hash`) to a direct server compile and that
  the runtime delegates to the canonical `ContextCompiler` / `RailEngine`.
  `edge_manifest()` → `EdgeManifest` statically certifies the core path imports
  nothing native (`.clean` / `.offending`), so it is WASM-buildable.
- `edge_environment()` / `is_wasm_runtime()` detect a Pyodide/WASI host (reads
  `sys.platform`, executes nothing). `app.edge_runtime(profile=None)` builds a
  runtime seeded with the app's rails. Rails run at the edge: input rails screen
  the task, output rails screen the *rendered context* (a secret leaking from
  evidence is refused before the prompt is emitted).

## CLI & server

- `vincio init (--template minimal|rag|agent|eval, --provider) · run · config
  schema/validate/show/migrate (--check/--dry-run/--output) · doctor (--json) ·
  packs list/show · tui · eval run/report/dataset
  (--group-by-session)/drift/annotate/regress (--baseline-model X
  --candidate-model Y) · prompt lint/compile/push/versions/diff/rollback · trace
  show/view/replay/diff/export/sessions/feedback · optimize run/reflective · loop
  run (--app/--dataset/--min-feedback/--gate/--tag/--dry-run/--reflective) ·
  distill (--traces-dir/--output/--format) · index build · memory
  inspect/remember/recall/forget/export/consolidate/decay · audit verify ·
  governance card/report (--red-team --markdown)/aibom/lineage/erase · mcp
  tools/add/serve · providers list/lifecycle/discover/regress · batch
  (--input/--input-file/--discount/--output) · cost report (--by/--db/--json)`.
- Server: `vincio serve --app app.py` (uvicorn; `/v1/health/ready`, `/v1/metrics`,
  graceful shutdown) or `from vincio.server import create_app` (FastAPI; API key +
  JWT; real-token SSE). For scale, set `server.redis_url` so rate-limit/idempotency
  state stays coherent across workers.

## Gotchas for generated code

- **Don't hand-parse model output** — pass `output_schema=` (or a `Signature`) and
  read `result.output`; repair fixes structure only, never invents facts.
- **Security/permissions/budgets are code, not prompts** — use rails, the access
  controller, and `RunConfig` budgets; never ask the model to self-police.
- **Offline by default** — omit a provider/key (or use `provider="mock"`) and the
  full pipeline runs deterministically in CI.
- **Async methods are `arun`/`astream`/`a*`** — the sync wrappers need no running
  loop; don't `asyncio.run` inside an existing loop.
- **`continuous_improvement` / `experiment_proposer` are removed** — use
  `app.self_improvement(policy)`, or construct `ContinuousImprovementController(
  app, ...)` / `ExperimentProposer(app, ...)` directly.
- **Metrics are one object** — the same metric is an eval, a runtime guardrail
  (`add_metric_rail`), and optimizer fitness.
- **`lexical_overlap` is lexical; `semantic_similarity` is embedding-backed** —
  unscoreable cases are skipped (`MetricResult(skipped=True)`), not scored 0 or 1.
- **Budgets raise** `BudgetExceededError`; unknown models warn (no silent $0).
- **Everything lands on one trace + audit chain** — read `result.trace_id` and
  `vincio audit verify` rather than adding side-channel logging.
