---
title: "ACP boundary"
description: "Phase 3 foundation: bounded framing/RPC, permissions, prompt translation and lifecycle effects, plus Unix SQLite admission, durable intents, resolved retention, fenced prompt-write pumps, bounded egress, a durable pre-session connection owner, live direction-policy fencing, pinned SDK method/reply decoding, owned wire initialization, pending session reservation and partial observed-effect corpus replay. Exhaustive fault qualification and runtime interpreter/provider integration remain pending; no gateway linkage."
type: "living"
source: "crates/acp_boundary/README.md"
verified: "2026-11-14"
group: "Contracts"
---

> **Living doc**, checked against the code 2026-11-14

`vulpine-acp` is an inactive workspace library: the deterministic boundary and session executor of
ADR 0070. The gateway does not
link it, and it makes neither ACP role available or active. Private, uninstalled process-owner and exec-gate binaries
exercise native custody, experimental macOS denial and durable native effect tombstones
(ADR 0071). They are not an installed
managed backend, provider or model.

Dependencies: serde/serde_json (MIT OR Apache-2.0), rusqlite (MIT), the exact ACP SDK 5.0.0 / schema 1.15.1 packages
(Apache-2.0) for typed methods and owned wire initialization, and rustix 1.1.4 (Apache-2.0 / MIT) for the Unix scoped
reads' descriptor-relative filesystem I/O. On macOS and Linux it also takes exact pins of tokio, nix, command-fds,
listenfd and ring for the native custody code, and sha2 for digests. The Unix admission store does local filesystem and SQLite I/O. A UTF-8
record is **not** a validated ACP message.

The private process owner's controls (`release_receipt`, `NativeOwnerChannel`, TERM and KILL records) serve those
custody tests only.


## Streamed SDK submission input

The host-supplied SDK owner submits a bounded prompt array through the native channel. Begin, chunk and commit
records keep the 256-byte record and 64-byte reply-body limits, one 30 s whole-call deadline and one exchange at a
time. The session runtime charges incomplete assembly and validation or rewrite payloads against its data budget.
Complete validation precedes the sole provider writer. Commit is consumed once. Canceling or expiring assembly does
not release durable capacity. See
ADR 0071.

The return path moves one charged event through bounded replies to the SDK owner. Permission descriptions keep their
original callback attribution and confer no grant.


## Line framing

`FrameDecoder` allocates a fixed byte buffer after its caller's connection admission. Each byte advances the
decoder. LF returns one borrowed UTF-8 record. There is no internal record queue, callback, task or timer. A caller
must stop reading while downstream is blocked, and must bound any copies it keeps. Fixed framing storage does not
bound the whole adapter's memory.

The frame limit includes LF, is at most 1 MiB and must fit a nonempty record. CR stays payload, including CR before
LF; JSON validation decides whether it is legal. UTF-8 is validated only at the delimiter, so a multibyte character
split across chunks is valid. An oversize, empty or invalid-UTF-8 record closes the decoder for good: it never
resynchronizes past untrusted bytes. EOF never emits a partial record and is not prompt settlement or execution
quiescence. Debug and error messages hold no record bytes.


## Bounded JSON-RPC envelopes

`decode_message` validates one record before any method dispatch. It limits decoding to 32 levels and 65,536 nodes
(object keys count), rejects duplicate decoded keys at any depth, and never preallocates from peer size hints. The
frame cap applies when it is called directly too.

Requests, notifications and result/error responses keep their distinct shapes. Stable-v1 IDs are null, signed 64-bit
integers or strings. An absent ID means a notification; an explicit null is a request or response ID. A response needs
an ID and exactly one of result or error. An error needs a signed 32-bit code and a string message. Unknown optional
fields and numeric spellings survive, because the original borrowed JSON is kept instead of a reserialized tree.
Debug and error output never shows peer-controlled strings. Parsing uses serde_json's ordinary numeric range.

This validates envelopes only. A well-formed `initialize` envelope may still have invalid parameters: it **must not
dispatch** until method-specific validation passes. Unknown methods are kept for a dispatcher to answer
method-not-found; they are not implicitly supported.


## Permission decisions

`decode_permission_outcome` validates the nested stable-v1 permission success result. It rejects malformed known tags
instead of treating them as extensions. The caller must correlate its RPC ID and authenticate the human route:
parsing is not authorization.

`PermissionInteraction` is a pure single-interaction reducer:

- It binds principal and interface, direction, machine, session, prompt, callback, resource scope, nonce and
  generations.
- It permits only an option offered exactly once, under both the immutable and the current authority.
- It expires at the earlier of the human and parent deadlines. An explicit timer tick expires a silent interaction.
- Persistent allow or reject choices are not offered in this profile, and never remapped.
- Cancel, and a late or duplicate response after completion, produce no second completion effect.
- One completion object supplies both the audit selection and the escaped wire result bytes.

It accepts at most 16 unique options, with IDs of at most 4096 bytes. These are local profile bounds, not protocol
limits. It does not authenticate bindings, generate secure nonces, acquire writer fences, deliver callbacks, impose
installation quotas or durably commit outcomes. The services that do must serialize live authority checks with effect
consumption. Recreating an interaction after a crash is not safe replay. UI failure, disconnect and disable must
cancel it explicitly. Dropping it proves nothing remotely.

## Baseline prompt translation

`validate_prompt` validates every text and resource-link block before returning a value. Required session and
content fields and known tags are strict. Image, audio and embedded-resource blocks are held back and reject the whole
mixed prompt. Optional metadata follows the pinned v1 schema's tolerant rules: raw fields stay inert, neither dropped
nor turned into authority.

Outbound uses the original validated ACP JSON unchanged. `prepare_prompt` wraps the exact raw block array in a
labeled untrusted user-data record and serializes one Pi `prompt` command with a caller-supplied ID. Text and link
order, optional-field presence, unknown fields and numeric spellings all survive. No URI is fetched, opened,
resolved, probed or sent to a handler. The label does not prevent prompt injection, and a later provider or tool may
still request access.

The final Pi bytes, including the command ID, escaping and LF, must fit 1 MiB. Serialization uses a bounded memory
sink, and a failure returns no partial frame. This inbound ceiling does not constrain valid outbound ACP frames.
Prepared bytes still need authenticated session ownership, admission, journal-before-write and transport readiness;
nothing is dispatched here. The command does not request steering or queueing.

## Negotiation, correlation and lifecycle effects

`Negotiation` applies the role-specific stable-v1 version rule and a fixed handshake expiry. An inbound agent falls
back to 1; an outbound client refuses unsupported responses. A silent handshake expires on a timer tick. A repeated
initialization closes instead of resetting the deadline. It consumes typed version data only: wire initialize and
capability schema validation, authentication, session admission and readiness are separate.

`RequestBook` reserves one of 16 pending slots before queueing. It issues IDs that are never reused within an
externally fenced generation, and keeps up to 256 resolved tombstones. A timeout returns locally once but keeps the
unresolved correlation and its slot, so a late matching response can still record settlement. Replies to
never-dispatched IDs, stale generations, numeric/string mismatches and duplicates have no effect. Deadlines include
queue wait and come from the request class. The ordinary RPC budget does not cut permission waits short. The book is
neither a durable journal nor permission to release a prompt slot.

`PromptLifecycle` emits bounded effects against a captured connection, allocation and prompt key. Cancel, timeout,
EOF, Pi acknowledgement and `agent_end` do not release the prompt slot. Settlement releases it once, without
inferring subprocess quiescence. Only trusted proof of managed teardown establishes quiescence; an attached agent
cannot gain cleanup authority through that event. A stale key cannot affect a successor. Local return and cancel
requests are one-shot. These primitives perform no writes, signals, detach or permit release.

The caller must serialize authenticated observations and live admission checks with durable effect commits.
Rebuilding these objects after a crash with reused generations is unsafe. They are state-machine building blocks, not
an installed supervisor or cross-process authority.

## Durable admission store (Unix)

`AuthorityStore` provisions a new private operator-bound root, or opens existing state it expects, with no create,
reset or migration. SQLite immediate transactions serialize cross-process accounting. Contention returns Busy; there
is no waiting admission queue. The installation identity must match. Explicit fencing changes the durable authority
generation: older handles become invalid, and their unresolved records stay.

Defaults are 8 connections, 4 sessions, 2 managed children, 2 global prompts and 1 prompt per session. A parent
reservation must exist and stay unresolved. Resolving a parent with live dependents refuses. Committed launch and
write intents precede external effects. Unknown dispatch and cleanup keep their capacity across reopen. Bounded
enumeration recovers tokens and parents without in-memory state. Prompt settlement cannot release child capacity.
Proof enums are trusted orchestrator inputs, never authenticated evidence on their own.

The journal and its SQLite file:

- At most 1024 fixed-shape records, resolved ones included. Terminal space is reserved at admission, and phase
  updates are fixed-width. A full journal refuses; it never evicts.
- 4096-byte pages, a 1000-page database ceiling, DELETE rollback journaling, EXTRA sync/fullfsync, a bounded cache,
  no mmap.
- Resource and operation records hold no prompt bodies or credentials. Separate bounded permission rows keep exact
  interaction outcomes and queued question and result frames, opaque IDs and options included. Session rows keep
  bounded backend identities.
- `resolve_at` takes a trusted whole-second Unix time, stored in the reserved terminal space. Fractional,
  overflowing and regressed times refuse.
- `prune_resolved` deletes only resolved leaves at least seven days old, without resetting allocation IDs. A
  duplicate resolution keeps the age. An untimed `resolve` keeps its record forever, and kept children protect their
  parents. Pruning is explicit, never automatic at admission.

The schema is 10. Older schemas refuse, with no migration or reset. It keeps durable direction policy and generations,
writer claims, session identities, operation uncertainty and managed-launch metadata, durable session routing,
permission and prompt effects and captured drains. It keeps bounded per-session operator-policy metadata and separate
decision provenance. Revoking a policy fences selection, execution and physical delivery, without enlarging
authority or adding a quota pool. Unattended operator policy stays disabled by default. Reopen validates metadata,
capacities and parent relationships in one read snapshot.


Roots must be absolute, private and operator-trusted, on a local filesystem that honors SQLite locks and fsync.
Root or database symlinks, database hardlinks, oversized database files and detected replacement are refused. These
checks do not confine a hostile same-user path race. A storage or corruption error poisons a mutating handle, and
reopen must validate the existing state. Partial provisioning is left in place for investigation, never deleted
automatically.

The one native managed-child implementation, `NativeProviderHost`, is not installed. The deterministic supervisor below orders gated launch, birth and
containment through a trusted host interface; it does not permit a real provider launch.

## Fenced prompt writes and bounded egress (Unix)

`PromptWrite` validates a frame and its captured connection and prompt binding. It then commits a one-shot
`dispatch_unknown` claim before copying or offering bytes to a sink. A private, non-cloneable permit and cursor keep
partial-write progress. Each bounded nonblocking sink call runs under an immediate authority transaction. A takeover
during the call refuses Busy. A takeover between calls stops the old permit from emitting more bytes, even with a
successor store handle. Reopen cannot recreate a writer for the unknown record. A write's success never releases
prompt capacity or proves remote settlement.

`FrameQueue` has separate budgets: 128 entries / 4 MiB for data, 16 entries / 64 KiB for control. Active frames stay
fully charged. Control takes priority only between frames, never inside a partial JSON line. A full data queue
backpressures without a copy; a full control queue closes explicitly. The five-second absolute stall deadline
includes creation and queue wait and respects the parent deadline. A retry after backpressure cannot reset it, and
younger control traffic cannot hide an expired data frame. Sink failure, invalid counts, clock regression or
unwinding make the writer and queue unusable; nothing is replayed.

The pre-session owner below joins the queue, decoder and typed negotiation, and prompt-write claims go through that
owned queue. Integration rules:

- The sink must be trusted, bounded and nonblocking. These primitives cannot preempt callback latency.
- One exclusive connection owner serializes whole frames across prompt writers and routes the captured binding to the
  right transport. Never run several schedulers or writers on a shared stream, or duplicate their buffers.
- The producer pauses on Backpressure with at most one bounded pending frame.
- Queue classes are trusted protocol classification, not peer or model choices.

No real sink, callback route or provider is registered.

## Pre-session connection owner (Unix)

`ConnectionOwner` checks independent, default-off `RoleFlags` before reserving a connection. It commits a one-time
writer claim before allocating the decoder and queue. Drop, close, restart or a second handle cannot reclaim that
stream. Claims survive until record retention can remove the resolved connection. Standalone `PromptWrite` streams and
owned-queue streams have distinct durable claim classes and cannot be mixed. All claim codes share one SQLite integer
width, with space allocated at reservation.

One owner holds one decoder and one output queue and drives input and output under the captured authority fence.
Input chunks are capped at 1 MiB and at 16 borrowed-record callbacks per call. The caller keeps any unconsumed suffix,
uncopied. A callback unwind closes ownership. Typed negotiation uses the role-specific version logic, a fixed 10 s
handshake and a 30 s sessionless deadline; traffic cannot extend them. `initialize` needs data already
schema-validated and correlated, and emits no capability advertisement or wire reply.

Caller flags can only narrow admission. The durable default-off policy is checked atomically with connection admission
and writer effects. Disabling fences that direction; re-enabling advances its generation, so an old owner cannot
revive. A complete operator snapshot rejects malformed configuration with no partial update. These policy APIs must
never become model tools. Callbacks still need authenticated routing and bounded, nonblocking implementations.
`close` releases local buffers only. It does not close an external file descriptor, release durable capacity, claim
settlement or prove quiescence. No provider session or real transport is enabled.

## SDK-backed wire decoding

`decode_call` validates initialize, session/new, baseline prompts, cancellation, permission requests and session and
tool updates with the pinned SDK's stable-v1 method implementations. It enforces direction and request or
notification shape, rejects extra workspace roots and MCP configuration, and bounds and de-duplicates permission
options. The original borrowed JSON keeps unknown fields, metadata and numeric spelling. Paths and IDs stay untrusted.
Unknown requests refuse; unknown notifications are inert. SDK optional-field fallbacks grant no authority. Decoding
touches no URI and no filesystem.

The native SDK actor/session/transport loop is not instantiated: its internal unbounded channels are not qualified
against the installation budgets. The SDK's published archives omit LICENSE, so a distribution must carry the
retained Apache license notices.


## Owned wire initialization and pending session admission

`ProtocolConnection` owns the decoder and queue; it adds no scheduler. It consumes one record per call and leaves the
suffix with its caller.

- Inbound initialization returns stable v1 with empty optional capabilities and keeps the request ID's wire type and
  precision. Wire readiness waits until the initialization reply has finished writing.
- Outbound initialization needs its own fully written request and a matching, schema-valid v1 reply. Guessed, stale
  and duplicate IDs do not promote readiness.
- Internal tags live on queue entries, so completing an unrelated error response cannot complete initialization.
- Unknown requests get bounded -32601 responses.
- A sink unwind poisons both the protocol state and its owner.

`decode_reply` validates initialize, new-session, prompt and nested permission results against the captured method.
Decoding alone does not correlate a response, authenticate a human or prove execution quiescence.

After wire initialization, `reserve_session` checks a schema-valid inbound request against the trusted invocation
workspace scope. It refuses duplicate pending request IDs and reserves under the captured writer and live policy
transaction. Both local and installation session limits apply. This is a **pending reservation only**: it produces no
session-success response, provider readiness, process launch or prompt dispatch. Workspace equality is not
filesystem confinement. Close and timeout do not release a pending reservation.

## Captured identity, queued claims and Pi command outcomes

`reserve_session_for` captures a `SessionIdentity` atomically with the pending reservation. These must match exactly:
the provider registration, executable, model and configuration, loadout, principal, initiating interface, machine,
workspace and allocation digests, the allocation generation and the ownership class. The trusted host supplies
canonical identities; peer metadata cannot supply its own authority. `check_session_binding` rechecks the durable
identity and the live writer and policy fence. A matching identity alone grants no provider readiness, human authority
or confinement.

The schema stores one fixed 304-byte identity per bound session, with a foreign key to its reservation. Recovery
validates encoding and resource class and never adopts old writers. Retention keeps a resolved identity until its
reservation is eligible for explicit pruning, then removes both. An unbound reservation cannot pass a bound-session
check or claim the owned prompt path.

`ConnectionOwner::enqueue_prompt` preflights the queue, then atomically claims the captured prompt as
dispatch-unknown. The committed, noncloneable claim enters the data queue. There is no second payload buffer and no
standalone-writer bypass. Every sink call checks that entry's session, identity and unresolved prompt inside the
writer transaction. Control priority and partial-frame noninterleaving hold. Backpressure before the claim leaves the
prompt reserved. A failure after the claim keeps the uncertainty and never authorizes replay. This is a trusted writer
primitive: before calling it, the interpreter validates the complete prompt, binds the actual wire session and
destination, and establishes provider readiness.

`PromptLifecycle::new_pi` captures the Pi command ID and allocation key before dispatch. `apply_pi_reply` accepts at
most one matching, bounded command response. Started, queued and `agent_end` do not settle the prompt.
Handled-without-a-run and rejected-before-acceptance settle it, with rejection distinct from success. Neither proves
child quiescence: an extension may start independent work. The interpreter still applies the returned lifecycle
effects durably and in order. This helper does not release a store reservation or authenticate stdout.

## Deterministic executor integration

The operation journal shares the **1024 total records** ceiling with resource reservations. It can keep many
unresolved operation intents without inventing live connections or children. Intents hold fixed-size digests, not
payloads or credentials, and commit before effects. Tokens are reconciliation identities, never replay permits. An
unknown record protects its parent session. Only explicitly resolved, timed records can age out.

Outbound `reserve_backend_session` reserves capacity before provider startup and handshake. It claims no readiness and
allows no early prompt. `ProtocolConnection` keeps at most one untrusted post-initialize packet for the executor;
further input pauses unconsumed. Unknown notifications and unmatched responses stay inert. `SessionRuntime` composes
these APIs into inbound and outbound session routing:

- Exact written backend responses precede readiness.
- Opaque public and backend IDs stay distinct.
- An immutable invocation identity cannot be warm-rebound.
- Inbound semantic updates carry their exact queue tag, so an unrelated control completion cannot release
  backpressure or let a final prompt response overtake them.

Standard Pi 1.5 RPC `agent_settled` has no prompt command ID. `SessionRuntime` treats that bare event as an
observation, never as proof that the current prompt settled. `observe_pi_settlement` needs an original command ID that
the backend producer or SDK correlated at invocation creation, not a current-prompt label a stream consumer attached.
Stale IDs have no effect, and earlier semantic output must drain first. This is a trusted integration seam, not a new
Pi wire field. Bare RPC cannot release reusable-session prompts. Verified owned teardown is a separate proof.

The managed supervisor separates intent, single-use gated spawn, durable birth and containment binding, and gate
release:

- All metadata space is reserved before spawn.
- A callback panic or ambiguity keeps the uncertainty. Recovery never recreates a provider writer or relaunches.
- Lookup-only reconciliation can poll, and it permanently fences the original launch handle.
- Cleanup signals only a captured birth and containment target. Starting cleanup fences provider writes. Release
  needs a verified reap plus descendant accounting.
- The native host implementation (`NativeProviderHost`) is not installed. The parent host owns timer driving and physical transport
  authentication.
- Inbound Pi RPC uses the **separate `PiStreamOwner` child stream**, never the ACP client's output queue. A command
  keeps one durable claim across partial writes.
- Releasing a never-launched child needs a host-attested irreversible seal and accounted-for descendants. A negative
  lookup is not proof.

`LaunchDriver` owns the original unused attempt and host across Pending exchanges. Its bounded progress callbacks run
under fresh fences, never resubmit spawn or release, and never extend the preparation deadline. Failure and unwind
keep custody, never a recovered writer. `OutboundBootstrap::into_resumable` composes this with the session executor
and the sole ACP queue. Initialize is queued once, after binding and release. A partial or failed handoff keeps the
original host and executor. This path is not a production native backend or installed SDK launcher.

`EffectSession`, `DurablePrompt` and `PendingPermission` commit state before effects. The runtime routes outbound
reverse requests through the initiating authenticated human interface. It routes inbound typed backend requests
through ACP to the restricted Pi stream. The inbound `permission_result` is an explicit backend-adapter seam; ordinary
Pi RPC does not implement it. Model text cannot authorize escalation. Queue admission means unknown delivery, not
success. Exact full-frame completion records delivery atomically. Partial writes recheck the captured identity,
direction, deadline and narrowed authority on the original queue.

`DirectionalDrain` captures one fixed 10 s budget and a 2 s TERM grace. The runtime's noncloneable control permit
allows only captured cancellation through its own streams. A partial revoked data or approval frame cannot be spliced
or completed under cancellation authority. Re-enabling never revives old permits. Admitted but unsent prompts stay held
until verified settlement, reconciliation or owned teardown; removing a queued frame does not prove release. The host
drives the permission-expiry and drain timers. There is no background scheduler here.

`AttachedGuard` consumes an initialized owner and an already authenticated exclusive bridge writer. Discovery, local
hooks, missing machine callbacks, voice and changed allocation facts refuse. Each send rechecks the captured facts
inside the local write transaction. The trusted sink must still authenticate its actual remote destination. No remote
writer acquisition or hc transport is supplied. External close or kill is always refused. Detach never proves the
remote side idle.

Scoped reads consume a trusted preopened directory object. They resolve bounded ancestors without following symlinks
and revalidate the captured ancestry before data access. Delegated denial has no local fallback path. Filesystem and
terminal capabilities stay unadvertised. Scoped reads are not atomic against arbitrary concurrent filesystem mutation,
cannot bound syscall wall time, and do not confine a native child.

