v0.3.0

v0.3.0 hardens Cayu's durable runtime contracts while extending the
reproducible evidence, knowledge, workspace, task, browser, and evaluation
foundations introduced since v0.2.1.

Upgrade from v0.2.1

Stop all v0.2.1 and older workers, take application-consistent backups, and
upgrade independently deployed servers, dashboards, generated clients, and
workers together. The server contract advances from version 10 to version 16,
and the public application manifest and generator plan advance from schema 7
to schema 9.

The storage schema advances from revision 36 to revision 45. Follow the
revision-specific migration boundaries below: revisions 39 through 45 contain
breaking durable contracts, and populated legacy knowledge or task stores may
require the explicitly documented rebuild or drain procedure. Run cayu storage status followed by cayu storage migrate against every configured SQLite or
PostgreSQL store, and confirm revision 45 with no pending migrations before
starting v0.3.0 workers. Mixed-version deployment and application-only
rollback across these boundaries are unsupported.

Project serving assembles the durable Evals foundation

cayu serve now derives normalized project identity from [project].name,
release identity from CAYU_RELEASE_ID or the public application-manifest
fingerprint, and a durable Evals store from the project's existing SQLite or
PostgreSQL session-store declaration. Explicit loopback --dev may create the
project-local data/cayu.db default; production never invents storage. All
public identity crosses the application's workload-secret redaction boundary,
and Cayu owns and closes the assembled store.

Generated maintained-service factories carry an opaque
ProjectControlPlaneContext into the server assembler. Existing factories
remain source-compatible and receive an actionable cayu check warning plus a
conservative, idempotent cayu generate service-context migration. Explicit
EvalsConfig remains authoritative and is never field-merged with automatic
state. Execution-target assembly is a later slice, so automatically assembled
projects currently report eval_target_not_configured and do not mount Evals
mutation routes or workers.

Control Plane Evals now publishes operation-level readiness

The Evals navigation and direct route now remain discoverable even when a
deployment has not assembled the Evals catalog. The page renders the server's
independent readiness for captured evaluation, catalog reads and writes,
captured-result persistence, scenario conversion, fresh launches,
cancellation, comparison, and reports. Unready pages do not probe absent Evals
endpoints, and planned framework work is distinguished from a genuine
deployment or runtime limitation.

The control-plane contract advances from version 13 to version 14 with the new
required capabilities.evals_readiness projection. Its closed state and reason
codes are discovery metadata rather than authorization: authentication,
mutation policy, and operation preconditions remain authoritative at the
underlying routes. Independently deployed servers, generated clients, and
dashboards must be upgraded together. This first delivery slice does not yet
assemble Evals storage or execution targets automatically and adds no durable
writes or workers.

Tool exposure now governs frozen model-step request profiles

Cayu now provides immutable RegisteredToolCapability summaries, bounded
ToolExposurePolicyRequest and ToolExposureDecision records, deterministic
expose-all and static named-profile policies, and resolve_tool_exposure(...).
Resolution uses detached policy input, accepts names only, rejects policy
mutation and unknown or out-of-ceiling selections, restores canonical
registration order, and binds the resolved profile to exact schema and
definition fingerprints without exposing live tool or environment objects.
Capability summaries are derived once at agent registration and reused by
execution-profile resolution.

CayuApp.register_agent(..., tool_exposure_policy=...) now applies that
contract end to end. Cayu resolves one registration-ordered exposure snapshot
before context pressure and official token counting, sends exactly that subset
through OpenAI, Anthropic, Chat Completions, Bedrock, and Vertex requests, and
reuses the same snapshot for generic retries and context-overflow recovery.
The default remains expose-all, and the runtime-owned structured-output tool is
preserved independently of application exposure.

A provider call for a registered tool absent from the frozen request is blocked
before ToolPolicy, approval, hooks, secret resolution, environment access, or
tool execution. Cayu emits typed not_exposed_in_request evidence without
arguments and appends a provider-valid error result. Compact snapshot authority
survives ordinary tool-round recovery and approval or user-input interruption,
while exposed calls continue through every existing authorization and execution
control.

Bounded fork groups are durable public runtime operations

CayuApp.run_fork_group(...) now freezes one terminal source checkpoint and
execution profile, runs 2-16 caller-named sibling sessions under bounded
parallelism and one causal budget, applies registered deterministic gates, and
admits only bounded allow-listed evidence to a tool-free evaluator. Lifecycle,
branch evidence, one validated selection, failures, and exact-request replay
are durable across in-memory, SQLite, and PostgreSQL session stores. Version 1
fails the group if any sibling or gate fails while preserving every branch for
inspection.
Atomic source digests prevent same-epoch source drift while siblings are being
created. Revision-fenced lifecycle publication prevents stale coordinators from
replacing a terminal result, reconciles lost commit acknowledgements, and sends
nonterminal child sessions through ordinary Cayu recovery after process loss.
One renewable store-backed execution claim prevents applications sharing a
store from concurrently resuming the same group. The tool-free evaluator's
exact execution profile is frozen before durable admission, and extension
failures are recorded only through bounded, secret-redacted diagnostics.

Workspace mutation attribution is explicit and fail-closed

Workspace revision deltas no longer imply per-tool causality. Mutation receipts
now distinguish exclusive tool attribution, concurrent ambiguity, and
external/unknown changes; exact attribution requires stable resource identity
plus matching adapter-provided writer-isolation evidence at both ends of the
window. Overlapping in-process windows taint every participant, edits between
windows remain separate gap evidence, and direct workspace operations are
reconciled against independently observed endpoints with bounded content-free
projections. Private-argument and dynamic multi-call quarantine uses a fixed
projection with no direct-operation hashes, metadata, counts, or gap evidence,
cannot claim exact attribution, and clears the process-local gap baseline so a
later receipt cannot resurrect quarantined evidence. Built-in bindings default
to unknown isolation.

Terminal binding finalization records an unattributed delta from the last
durable after-window observation, and session forks explicitly report shared or
unproven workspace lineage without claiming an isolated derived revision. The
new evidence is additive JSON in existing events and round-trips through all
built-in session stores; no storage migration is required.

Derived knowledge indexes publish exact identity and readiness

KnowledgeEmbeddingIdentity now binds every comparable derived embedding to
its exact entry revision, optional chunk, projection content, embedding space,
preprocessing, generator, and index representation. Independent
KnowledgeIndexReadiness events use compare-and-swap sequence fencing,
attempt fencing, idempotent operation replay, bounded authorized high-water
pages, and durable restart behavior across in-memory, SQLite, and PostgreSQL.
Lexical-only custom stores keep optional extension hooks instead of pretending
to support embeddings.

InMemoryEmbeddingKnowledgeStore and PostgresEmbeddingKnowledgeStore now keep
canonical publication provider-free and consume committed changes through
bounded process_embedding_changes(...) workers with independent change and
projection-record budgets plus deterministic continuation. The crash-safe order is
pending readiness, vector commit, ready readiness, then outbox acknowledgement.
Semantic/hybrid search is read-only, rejects non-ready or incompatible rows,
and returns machine-readable KnowledgeIndexCoverage; explicit bounded
backfill retries failed or missing projections.

Breaking storage revision 44 preserves canonical revision-43 knowledge and
adds the readiness event/current tables. PostgreSQL drops pre-identity
cayu_knowledge_embeddings rows during migration because vectors are derived
and cannot be safely assigned the missing identity. Stop older workers, migrate
once, and rebuild semantic projections; Cayu does not add a legacy read path or
fabricate readiness.

Knowledge-store conformance is adversarial and explicit

The shared KnowledgeStore suite now registers each in-memory, SQLite, and
PostgreSQL backend with explicit lifecycle, durability, and optional-capability
claims. Reusable scenarios cover compare-and-swap revisions, owned immutable
results, authorization, atomic failure, exact change publication and page
metadata, portable ordering, lifecycle guards, projection readiness, and
embedding-space isolation. Ten deliberately broken adapters prove that each
scenario detects its intended defect instead of merely replaying happy paths.

Structured knowledge query terms and phrases that normalize to no searchable
tokens now fail at KnowledgeQuery construction consistently across backends.
PostgreSQL embedding startup also validates the revision-bound table's primary
key, checks, composite cascading foreign key, and required ready B-tree indexes;
a same-named but structurally incompatible index no longer survives CREATE,
MIGRATE, or VALIDATE startup. These checks harden the rebuildable revision-44
derived table and require no new storage revision.

Knowledge revisions carry evidence and publish atomic changes

Knowledge create, append, and owned-publication operations now accept immutable
KnowledgeEvidence bound to an exact entry revision and optional exact chunk.
Lifecycle-only successors inherit and rebind evidence; content-changing
successors require callers to supply it explicitly. Evidence participates in
publication idempotency, bounded authorized reads, defensive copying, and
global collision protection across the in-memory, SQLite, and PostgreSQL
backends. Revision-42 publication receipts remain replayable after migration
when the retry carries no evidence; evidence-bearing requests never use the
older entry-and-chunks-only digest.

Every successful canonical knowledge mutation now emits one metadata-only,
before/after-audience-bound KnowledgeChange in the same transaction. A scope
that loses access still receives the removal/update signal needed to clear stale
derived state; expiration cannot make already-published work disappear. Bounded
change pages accept at most MAX_KNOWLEDGE_CHANGE_LIMIT records, expose an
honest store-owned accessible high-water mark, and reject
cursors beyond the current store sequence, while scope-bound leased consumers
can initialize from a full-scan baseline and provide fenced at-least-once
delivery with durable SQLite/PostgreSQL cursors. Failed writes, exact
publication replays, authorization denials, and rolled-back transactions emit
no change.

Change-consumer leases now use store-authoritative time (the database clock on
PostgreSQL), and durable acknowledgement receipts keep exact retries
idempotent even after the consumer advances again.

Evidence prefixes and multi-entry expiration changes now use portable scalar
identity ordering across the in-memory, SQLite, and PostgreSQL backends, so
bounded results and cleanup publication do not depend on database locale or
insertion order.

Owned PostgreSQL publication now acquires the global change-sequence lock only
after entry, chunk, and evidence payloads are written. Unrelated canonical
writes can proceed while a large payload is staged without weakening atomic
receipt and outbox publication.

Entry IDs and chunk IDs now have explicit portable UTF-8 byte limits shared by
canonical models, referenced evidence/receipts/changes, and every built-in
backend. Revision-43 migration rejects out-of-contract revision-42 identities
before applying DDL, avoiding backend-specific index failures. The revision-43
migration timestamp also preserves cleanup delivery for migrated entries that
expire after the outbox baseline without widening access to entries that were
already expired.

Breaking schema revision 43 adds evidence, ordered-change, and consumer-state
tables without rewriting revision-42 knowledge or fabricating historical
events. Stop pre-43 knowledge writers, run cayu storage migrate, and confirm
revision 43 before starting this build. Mixed revision-42/revision-43 knowledge
writers are unsupported.

Model execution is attributable to complete immutable profiles

Execution-profile schema version 3 now binds provider-adapter behavior,
provider-visible request controls, context selection, knowledge injection,
compaction, live-state projection, application and invocation budgets,
structured output, and finalization semantics in addition to the existing
runtime, model, instruction, tool, policy, hook, environment, and effect
authority. Model dispatch, retries, recovery, explicit compaction, budget
evidence, structured-output repair, and model completion retain the frozen
governing profile instead of resolving mutable registrations again.

Governed request footprints advance to schema version 2 and reference that
profile without replacing their separate concrete-request evidence role.
Paired cost-quality comparison reports and bounded runtime-evidence reports
also advance to schema version 2 so attempt-level cost and runtime evidence can
identify the governing profile. These records remain content-free: they do not
retain raw prompts, knowledge, credentials, secrets, or unbounded schemas.

OpenAI providers support native hosted web search

Applications can grant one registered agent immutable, typed
OpenAIWebSearch authority separately from Cayu-executed tools. Both the API-key
and experimental subscription providers send the native Responses API tool,
retain completed search actions, complete returned source lists, and URL
citations, and publish bounded provider-owned lifecycle evidence. Search calls
and unknown outcomes are accounted independently from tokens; current published
OpenAI call pricing is represented with source provenance, while unavailable
pricing remains explicitly unpriced. Strict budgets reject hosted search when a
hard per-response call ceiling cannot be established.

The public application manifest and generator plan advance from schema version
8 to version 9 because hosted-tool authority participates in registration and
execution identity. Regenerate committed manifests and generated plans; older
schema documents are not interpreted as granting hosted search. The server
contract advances from version 15 to version 16 because usage and cost
projections add hosted-search resource fields. Upgrade independently deployed
servers, packaged dashboards, and generated clients together. This change does
not require a storage migration. Paired cost-quality reports advance from schema
version 2 to version 3 so Compound and other comparison consumers retain hosted
search calls, unknown outcomes, and their separately priced resource cost.

Fork and workspace branch authority fails closed

CURRENT_CHILD session forks now require an attributable application authority
decision even when their structural profile fingerprints are equal. Provider
changes always project and preflight portable history, including same-model
transitions. Local workspace branches now reject source/private per-directory
path-semantics mismatches and revalidate those semantics before publication.

Knowledge updates are immutable, revision-addressed publications

Knowledge entries now retain immutable revisions and a transactional current
revision pointer. Every chunk belongs to an exact entry revision; compare-and-
swap publication permits only the successor of the caller's expected current
revision, and concurrent stale writers receive a typed conflict. Current and
historical reads are explicit, lifecycle changes append revisions, current-only
search and list operations cannot surface stale material, and hard deletion
removes the complete revision history. In-memory, SQLite, and PostgreSQL stores
share the same revision, access-control, publication-receipt, and defensive-copy
contract. Runtime context candidates and knowledge-facing APIs carry the exact
revision they expose.

Historical entry and chunk reads now require authorization for both the exact
snapshot and the logical entry's current revision, so an older active revision
cannot bypass a later tombstone or access restriction. Authorized principals can
still retire current material to archived or deleted without being granted
read access to the retired state; promotion and reactivation continue to require
destination access. Revision exhaustion is rejected before mutation with the
same error across all built-in backends.

The server contract advances from version 11 to version 12 because knowledge
entry and chunk representations now require their exact revision. Upgrade
independently deployed servers, packaged dashboards, and generated clients
together.

Breaking schema revision 42 replaces the mutable knowledge layout. Fresh stores
and stores whose legacy knowledge tables are all empty migrate normally. A
populated pre-42 knowledge store is refused before Cayu changes its schema,
data, or migration ledger: stop older writers, take an application-consistent
backup, and explicitly replace/reset that database rather than fabricating
revision history. Run cayu storage status followed by cayu storage migrate,
then confirm revision 42 before starting current workers. Mixed pre-42 and
revision-42 knowledge writers are unsupported. Revision-42 startup also verifies
the complete knowledge table, constraint, current-view, search-structure, and
required-index contract and refuses a damaged or conflicting schema before
serving reads.

New runs use one atomic model target

RunRequest.target now accepts an optional exact
ModelTarget(provider_name=..., model=...). It replaces the independent
RunRequest.provider_name and RunRequest.model fields, and the server run
body likewise replaces model with target. Update Python callers and
generated server clients together; the removed fields are rejected rather than
silently combined. When target is absent, Cayu continues to use the agent's
model and its configured provider or normal model-pattern/default routing.
The server contract advances from version 10 to version 11 for this breaking
request-body change.

Local workspaces support bounded speculative branches

An exact LocalWorkspace can now create an isolated, process-local branch from
a complete observed workspace revision. Branches expose the ordinary workspace
API, deterministic content-free net changes, explicit rollback, and
conflict-checked all-or-none publication. Source snapshots, overlays, evidence,
lifetime, and active branch count are bounded; unsafe paths, symlinks, special
files, stale baselines, and publication conflicts fail closed. Other workspace
backends remain explicitly unsupported, and durable reconstruction after
process loss is not part of this first slice.

Queued dispatch is bound to durable execution profiles

Queued tasks now retain the target session instance, source and required
execution-profile fingerprints, and deterministic terminal handoff identity.
Workers validate that authority before provider, tool, verifier, environment,
or other governed work begins, and restart reconciliation settles the exact
session/task outcome without redispatching completed work.

Breaking schema revision 40 installs the queued-dispatch handoff indexes and
marks the new profiled dispatch envelope as the only supported queued payload.
Before migrating a shared session or task store, stop every revision-39-or-
older dispatch producer and worker, take an application-consistent backup, and
drain or explicitly settle every legacy task type configured on any
TaskStoreDispatcher. This includes the default cayu.dispatch type and every
application-defined custom task type. After all older processes are quiescent,
run cayu storage status followed by cayu storage migrate, then confirm
revision 40 before starting current workers. Mixed revision-39/revision-40
operation and application-only rollback across this boundary are unsupported.

Knowledge access is explicit and retrieval foundations are reproducible

Every built-in knowledge store operation now requires a principal-derived
KnowledgeAccessScope, supplied per operation or bound to the store. The scope
is enforced inside memory, SQLite, and PostgreSQL reads, searches, mutations,
chunk access, embedding paths, and publication-receipt replay. Runtime context
injection, knowledge tools, indexing, and review carry the same scope; callers
cannot widen a store-bound scope. Trusted maintenance must opt into the explicit
privileged scope. Global chunk-identity occupancy is authorized before it is
reported: foreign-scope collisions fail with KnowledgeAccessDenied, authorized
collisions use KnowledgeChunkConflict, and PostgreSQL serializes entry, chunk,
and publication identities in one server-side ordered lock batch. The remember
tool preserves those deterministic outcomes as access denial or publication
conflict instead of misreporting them as an outcome-ambiguous write, but only
after an authoritative receipt lookup proves publication absent. An unavailable
receipt lookup preserves the ambiguous outcome of post-commit extension work.

Breaking schema revision 41 stores the immutable authorization projection beside
each knowledge publication receipt so exact replay remains safe after an entry is
hard-deleted. Stop pre-41 workers and take an application-consistent backup before
migrating. Existing receipt authorization is deliberately not inferred or
backfilled: databases with populated pre-41 knowledge publication receipts must be
recreated. Empty receipt tables migrate normally. Run cayu storage status
followed by cayu storage migrate, then confirm revision 41 before starting
current workers. Mixed pre-41 and current knowledge writers are unsupported.

The memory foundation also adds a deterministic weighted reciprocal-rank fusion
primitive with bounded channel diagnostics, an explicit revision-reset/refusal
contract, and a versioned hermetic retrieval corpus and baseline runner. These are
foundation primitives; automatic curation and context placement remain separate
future layers. WRRF configuration construction now rejects values outside its
canonical durable fingerprint domain rather than accepting a configuration that
can fail only after fusion work. Its weight maps are deeply immutable, and
model_copy(update=...) revalidates updated values before returning a new
configuration.

Durable tasks retain immutable invocation provenance

Tasks now carry a Cayu-minted invocation identity and their immediate execution
source through claims, worker replacement, scheduling, session attachment, and
terminal settlement. Server-created work also retains its verified product
subject, so replacement workers can reconstruct the exact task provenance
without trusting caller-authored identifiers.

Breaking schema revision 39 applies this immutable origin contract to tasks and
durable dispatch. Stop pre-39 workers and take an application-consistent backup
before migrating. Populated prerelease task stores cannot be assigned truthful
origins and must be recreated; empty task stores migrate normally. Run
cayu storage status followed by cayu storage migrate; migration passes
through revision 39 before the breaking revision-40 queued-dispatch boundary
described above. Confirm revision 40 before starting current workers. Generated
product-operation stores also add a required originating-subject column;
recreate populated prerelease product databases rather than fabricating that
authority.

Worker task terminalization survives lost acknowledgements

Worker-claimed task completion and failure now commit a deterministic terminal
receipt atomically with task state. Exact retries return the original terminal
task after lease clearance, while changed worker, kind, payload, or digest
intent fails closed. CayuApp and run_task_worker(...) use a bounded,
observable retry helper for acknowledgement-ambiguous store failures; claim
loss, deterministic operating-system failures, validation, conflicts, and
cancellation are not retried. Success and uncertainty expose elapsed time and
applied backoff, and worker/dispatcher loops preserve an independently won
terminal outcome without masking same-key changed intent. This is durable task
state idempotency, not an exactly-once guarantee for external effects.

Additive schema revision 38 installs the receipt table in SQLite and PostgreSQL.
Revision-37 binaries remain compatible with the new table, but new built-in
task stores require revision 38. Current workers also require the breaking
revision-39 task-provenance boundary and the breaking revision-40 queued-dispatch
boundary described above; migrate the shared database through revision 40 before
deploying them.

SQLite knowledge updates no longer scan the global FTS corpus

SQLite knowledge chunks now share a stable integer identity with their FTS5 rows.
Updating, replacing, pruning, or deleting one entry addresses only that entry's
chunks, avoiding corpus-sized work while the shared SQLite writer lock is held.
Search behavior and BM25 ranking are unchanged.

The knowledge migration advances the storage schema from revision 36 to
breaking revision 37 before the additive revision-38 task receipt migration and
breaking revision-39 task-provenance boundary, followed by the breaking
revision-40 queued-dispatch boundary. Stop older workers, drain every configured
legacy dispatcher task type as described above, take an application-consistent
backup, run cayu storage status followed by cayu storage migrate, and confirm
revision 40 before restarting current workers. The SQLite migration rebuilds
legacy knowledge FTS rows in one transaction. After an ambiguous interruption,
run cayu storage status: retry when revision 36 remains, or continue through
the later migrations when the complete revision 37 commit is already visible.
PostgreSQL records revision 37 without changing its knowledge schema, then adds
the shared terminalization receipt table at revision 38 before continuing
through revisions 39 and 40.