Skip to content
Vulpine
Esc
↑↓navigate↵open⌘Jpreview
On this page

ACP boundary

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.

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.

Was this page helpful?