Architecture

Each prepared turn MUST retain requested and effective approval policy, including restricted-session suppression. ACP native mode results MUST remain separate: applied, unsupported, rejected or unreported. Status MUST NOT infer native success from the requested mode. This metadata survives private payload loss and is available in snapshots and the ordered owner journal. Policy metadata MUST NOT mark a turn running or enter the public transcript.

Consumer transcript append and replay allow up to 120 seconds for encrypted durable storage. Cancellation and disconnect still invalidate the endpoint call; an expired append never authorizes provider or tool execution.

Canonical message, tool, interaction, checkpoint and parent/child references are required identities. If scanning changes one, capture emits an omission instead of retaining a misleading association.

The controller is a separate single-writer service. Applications connect through the shared SDK and supply authorized tools, context, evidence and storage ports. The execution library remains ai-host. No core module imports a consuming app. Provider session persistence does not imply recoverable in-flight execution.

The initial implementation records accepted work and committed output in SQLite, captures events before provider acknowledgements, and re-snapshots SDK clients after reconnect. A single workspace identifier serializes execution even across provider instances. Configuration must give each physical workspace one identifier. Native Codex session IDs are bound separately from turn and command identities.

Memory ports expose scoped candidate retrieval and evidence authorization. The controller owns recall timing, budgets, rendering and MCP read-tool registration. Compatibility profiles preserve Lapis skip-over-budget and Nostr truncation behavior; consumer-specific stores and maintenance migration remain separate work. Endpoint disposal revokes tools, context and memory registrations immediately.

Requirements

Private payloads remain volatile where the integration selects metadata-only retention. A durable receipt in that profile covers metadata and external source identity, not recoverability of plaintext. Loss is reported rather than invented. Applications retain encrypted delivery stores and can rehydrate authorized data.

The initial storage uses SQLite WAL and FULL synchronous transactions with an exclusive service instance lock. Distributed writers and a durable host spool are outside the first release. External provider executables remain external.

Lapis memory compatibility is extracted behind structural evidence, database and record-store ports. The schema-1 Markdown representation, revision preimages, source hashes, exclusions, deterministic promotion rules and maintenance leases remain compatible with existing vault data. The application supplies actual vault/database access; the shared module never imports App, Vault or UI code.

The group-memory compatibility profile shares ranking policy with the vault profile and receives scoped evidence/search/mutation ports. It preserves the existing partition and record schema. Embedding providers are injected resources; server consumers may instantiate the exported pinned native provider. Startup rebuilds lexical search documents without warming vector embeddings, and embedding queues run only for new indexed data, explicit rebuilds, or live vector queries. This package does not construct a consumer’s worker, relay client or signer.

The shared runtime facade exposes application-neutral session events over the SDK. It resolves lost turn acknowledgements by command identity and does not retry with a fresh command. Consumers register preparation endpoints instead of injecting memory twice. ACP thought output is normalized to reasoning activity, separate from authored replies. Snapshots include a bounded activity tail and explicitly report truncation; complete retained history remains available through replay. Thread configuration uses optimistic versions and rejects changes during work.

Managed application integrations launch the separate controller executable through an exported process client. Startup credentials travel over the child’s private stdin, never argv. The client writes one newline-delimited request after the child has spawned, leaves stdin open, and does not wait for stdin finish or close; compiled Deno pipes may never emit those events, and readline.close() does not close stdin. The default readiness wait is 60 seconds. Start failures include the readiness cause without credentials. A bare executable name is resolved from PATH or $HOME/.local/bin. The caller supplies an allowlisted environment and a stable database path. The child reads generic provider definitions, reports readiness without credentials, and shares the same service/core as serve. Nostr signing and vault credentials remain outside this interface. Restricted sessions reject application tools and configure the provider’s restricted execution mode.

Runtime facades recognize the stored payloadUnavailable event marker and emit an explicit status gap rather than dropping missing private activity.

The browser runtime accepts a deferred per-turn context port. The SDK registers that port before submission and the service invokes it only when queued work is eligible. Port callbacks are volatile capabilities, never serialized into thread configuration. Resume uses the same endpoint identity and refuses mismatched scope bindings. Compatibility handoff projection and canonical transcript hashes are shared library functions; source transcripts remain application-owned.

External MCP launch descriptions travel through an owner-scoped volatile endpoint. The controller validates them before dispatch and rejects them for restricted execution or providers without MCP support. Only the endpoint identity persists; launch environment values are excluded from receipts, preparations, journals and CLI diagnostics. A disconnected endpoint fails closed. MCP provider activity is observational and never re-invokes an application tool handler.

The runtime preparation port receives the reserved logical thread identity before registration so consumers can reconnect the same authorized context endpoint.

CLI builds produce JavaScript runtime snapshots requiring Deno 2.9.5 or newer. deno task install:cli verifies every file and contained dependency link, smoke-tests the staged release, and atomically replaces a launcher pointing at an immutable ~/.local/lib/lapis-ai-controller/releases/<digest> snapshot. Previous snapshots remain available to running processes. Build metadata never reads the live checkout. Managed readiness MAY include build identity; consumers verify it before activation. Local overrides are materialized only in runtime snapshots. JSR /cli publication uses registry dependencies and explicit imports, with a separate dry-run gate. pnpm local:controller retains its initialization, service reload, and readiness behavior through the runtime installer. Services record the absolute Deno invocation.

Building alone still does not install or start a service.

Production source already lives under auth, capture, cli, domain, execution, memory, persistence, and transport. Domain turn execution, transcript capture, and endpoint registration live as named modules under src/domain/. Persistence, transport dispatch, and client snapshot helpers are also named modules beside those facades. Lapis memory episode documents, search ranking, ingest, inspect, forget, and consolidation live as named modules under src/memory/lapis/. Group memory search, claims, and lifecycle live as named modules under src/memory/group/. Residual root files are public facades (client, runtime, managed, contracts) or composition roots (index, main, service). For AIC-ARCH-001 and AIC-ARCH-002, scripts/check-architecture.mjs enforces counted-line budgets and that import matrix. New production and script files must stay at or under 300 counted lines; new tests at or under 500. Existing files must not grow counted lines without updating scripts/architecture-baseline.json in the same change. A recorded budget fails when the current counted size plus twenty is still below that budget. Organisation plans under docs/plans/ are not canonical requirements.

AIC-CLI-002 acceptance details

Local controller installation verifies:

• Default install, config, and workspace paths are ~/.local/bin/lapis-ai-controller, ~/.config/lapis-ai-controller/config.json, and ~/.lapis/ai-controller, with --config, --workspace, --instance, and --install-path overrides.
• The executable is copied to a temporary sibling and renamed into place.
• A missing config initializes ~/.lapis/ai-controller unless --workspace or LAPIS_AI_CONTROLLER_WORKSPACE is supplied; an existing config is reused without rewriting tokens.
• After service reload, status --json reports lapis-ai-controller/1 and command output never includes token bytes or private payloads.

Session reattachment validates application reference, context sources, tool and memory endpoints, restricted mode and payload policy against the stored thread. A mismatched attachment fails before it can submit another turn.

Native cancellation retains the workspace lease until the provider confirms a terminal turn or the confirmation deadline expires. An interrupt request alone is not proof of completion; an expired confirmation remains interrupted.

Provider setup precedes the persisted dispatch boundary. Setup failures are failed turns; a lost outcome after dispatch remains submission-unknown or interrupted. Such a turn fences its workspace across restart. An owner may resolve it as failed or cancelled only with explicit confirmation that external work stopped. Resolution records an audit event and releases queued work without retrying the original command. The CLI exposes this through turns resolve. An owner cancel of that inactive turn is the same confirmation: resolve it as cancelled and release queued work without retrying the command.

Provider launch defaults come from the installed ai-host/acpx registry. The controller resolves external executable paths for Deno without replacing adapter selection or requiring additional global agent binaries.

Startup validates all retained record shapes before recovery starts external work. Unsupported database versions and malformed records fail closed with payload-free errors. Metadata-only preparation markers have their own retained schema. Metadata-only turns persist only short error codes, never exception text.

A handshake with an unsupported protocol version fails as protocol_unsupported before token comparison. Hello then binds a revocable AuthSession from a bootstrap credential or session bearer. Handshake success grants no extra authority: every later method has a declared scope, then principal, application, provider and workspace checks. Missing configuration scopes default to the full initial set. Existing file and managed tokens remain bootstrap credentials. Replay and subscriptions are threads:read. Mutations stay explicit and idempotent on command identity. Application tools and memory ports are keyed by principal and application. Memory adapters receive a server access envelope; client identity fields are stripped. ai-host stays an in-process executor and MUST NOT receive controller-user scopes. A later host service would use a controller-owned credential, not an application session. WebSocket tickets remain an unissued seam so long-lived secrets can stay out of socket URLs later.

Two configured identities for one physical workspace fail as workspace_alias. Restricted-mode, endpoint and retention mismatches fail reattachment as binding_mismatch.

AIC-API-003 acceptance details

Session authorization verifies:

• Hello with a bootstrap token issues or resumes one AuthSession per credential and may return a session bearer only when newly issued.
• Hello with a revoked or expired session bearer fails closed.
• A method without a scope-map entry fails in tests; a session missing a required scope fails as forbidden.
• Reconnect keeps the same AuthSession identity and does not resubmit mutations.

AIC-API-004 acceptance details

Resource isolation verifies:

• Thread application is stamped from the session and defaults to owner for retained rows.
• Another principal or application cannot read the thread, its replay, or its private memory.
• Memory input cannot override server-derived access fields.
• Application tools cannot be invoked from an unauthorized thread or application.

CLI CliError codes keep their exit class. Service-manager unavailability uses exit 3; usage and request failures use exit 2. Secrets still require an explicit token show command.

Native external MCP processes receive explicit environment-name allowlists and required startup. Values remain in the native process environment, not argv. Because these servers share one native parent environment, conflicting values for the same name and reserved application-bridge names fail before launch; ACP retains server-specific environments.

Native MCP environment regressions run alongside the existing session, context, approval, structured-input, configuration and resume contract tests.

Native empty-form MCP elicitations are one-time approval interactions. Forms with fields or URL actions are not treated as approval and receive an unsupported request error; the adapter never invents required user input. Unknown server requests receive a JSON-RPC error instead of silently leaving a turn waiting.

Provider configuration MAY include a validated non-secret vcsIdentity name and email. ACP sessions MUST bind that identity and replace the native session when it changes. Runtime text events MUST preserve optional logical message IDs and completion markers through the output journal; transport frame IDs remain independent.

Authenticated consumer tool endpoints MAY register a generic capture port. Mutating application tools MUST await its begin acknowledgement before execution and its finish after the result. Read observations remain advisory. Endpoint ownership and disconnect fencing apply to capture callbacks; native ACP effects are observed through the journal and MUST NOT be replayed. Observed ACP tool calls merge start and update frames into one invocation envelope before a durable pair. Command, kind, and locations stay on that envelope; file, command, and patch rows remain forbidden.

The redaction adapter runs pinned credential detectors in an isolated worker. Synchronous SQLite writes use the same policy through a bounded worker result buffer; event preparation uses whole logical blocks. Workspace roots are granted from service configuration. Explicit environment and dotenv grants are private runtime inputs, never thread configuration or transcript metadata. External ACP provider traffic and native agent journals remain outside managed coverage.

The new agent-redaction package is initially validated through an explicitly documented local package archive. Publishing it and upgrading registry lockfiles remain separate operator gates; publishable manifests keep semver dependencies.

Compiled staging resolves ESM-only dependencies through public import exports and explicitly includes the isolated scanner worker modules.

Derived memory candidates containing reserved redaction or omission markers are rejected rather than promoted as factual memories.

The public contracts export assertTranscript for consumer-owned encrypted persistence; validation is shared without exposing storage internals.

Lapis memory ports scan DTOs before indexing and durable writes and scan legacy reads before derivation. Browser defaults expose portable detector coverage; consumers can inject an explicit enforcement adapter. Raw authorized evidence read arguments stay in the execution path. Transformed evidence locations fail closed instead of becoming file capabilities. Redacted candidates are rejected.

Generic approval policy is ask (the default for omitted values) or allow-all, independent of provider-specific permission modes. Allow all resolves only offered execution approvals, preserving their exact IDs and recording an automatic decision. Structured task input and restricted sessions never inherit automatic approval. Each turn uses its durable prepared configuration; changes apply to later turns. ACP permissions preserve the host deadline rather than extending its lifetime. Permission resolution must not move a completed, cancelled or failed turn back to running, and concurrent requests leave the turn waiting until all are resolved.

Host permission settlement is a typed execution event bound to the exact native interaction and turn. Expired or cancelled host requests remain terminal even when capture is awaiting durable acknowledgement; replay never opens another approval. Turn completion cannot be changed by late interaction registration. The ACP adapter drains settlement handlers without retrying a decision already settled by the host.

Continuation uses turns.continue with the exact prior turn and a new idempotent command identity. It creates a linked attempt in the same thread with newly authored instructions, verified sanitized transcript evidence and current configuration. It MUST reject running, interrupted or submission-unknown work, pending interactions, unknown tool effects and unavailable metadata-only history. It MUST NOT cancel, release execution fences, replay the original prompt or rerun tools. Scope authorization applies to the prior turn; repeated identical commands return the same receipt and differing input conflicts. Preparation rechecks the prior outcome and evidence before dispatch.

Metadata-only transcript rows retain the non-content sequence number needed for ordered replay. Live replay resolves payloads from volatile capture. After loss of volatile payloads, replay MUST report transcript_unavailable; it MUST NOT return a falsely complete empty history or authorize continuation from it.

Approval-policy provider acceptance is recorded in local policy validation. It distinguishes provider decisions and independently verified file effects from inconclusive redacted-path probes, browser acceptance and production deployment.

Background group-memory embedding failures MUST be contained before the next event-loop turn. If capture or durable error recording fails, the in-memory drain halts and leaves unembedded documents in durable pending state for a later explicit recovery. It MUST NOT retry against a failed scanner, write raw input, or crash the consuming service with an unhandled rejection. Closing memory stops queued work before disposing its capture boundary.

The initial 0.1.0 npm release is prepared in GitHub from the frozen registry lockfile. Release automation carries one immutable checksum-verified tarball through the protected npm-production OIDC publisher, then proves registry integrity, signatures, and a clean public-export consumer. Initial package creation remains an interactive npm bootstrap gate. The controller consumes AI Host 0.3.0 and Agent Redaction 0.1.0 through registry semver ranges after their releases. No installed service is restarted.

The full Node test lane serializes test files to avoid competing SQLite replay and process-lifecycle fixtures. Every test and existing deadline remains in the lane, followed by Deno runtime acceptance; no assertion or timeout is relaxed.

The README documents public client installation and authenticated usage. The separate specification workflow publishes canonical contracts to GitHub Pages without starting a service or invoking an external provider.