System Architecture and Authority Boundaries
See how external coding clients, native bindings, the ait-native core, Task worktrees, Binary DB, server, and runner connect across local and optional remote authority.
Audience: Developers, integrators, and operators
Read the system as boundaries#
ait-native has one native workflow core and two explicit operating paths. The ordinary path is local: an external coding client or embedded host invokes the native interface, implementation happens in a Task-bound worktree, and a Snapshot records the result into local Binary DB authority. Remote infrastructure is optional and extends only recorded state through explicit operations.
Local authoring is primary. Optional remote infrastructure adds shared authority, offsite preservation, and CI through bounded native interfaces.
Local authoring and recorded authority
Snapshot records mutable work into local authority.
- surfaceExternal coding client or embedded hostInteractive authoring or an in-process caller outside ait-native.
- interfaceait CLI or native bindingCommand or in-process entry surface.
- coreait native coreWorkflow, protocol, and storage semantics.
- executionTask-bound worktreeIsolated mutable implementation workspace.
Remote authority, preservation, and CI
Recorded state enters the server; bounded evidence returns to it.
- queueWorker JobTyped durable request owned by server authority.
- executionait-runnerMaterializes exact Snapshot content and executes Repository CI.
- evidenceCI evidenceBounded result returned to the owning server Repository.
Component and authority map#
| Component boundary | What it owns, and what it does not own |
|---|---|
| External coding client and Python/Node host | Own the interactive or embedded user experience outside ait-native. They call AIT interfaces but do not replace native workflow or storage semantics. |
ait CLI, native bindings, and native core | Own command admission, workflow transitions, protocol behavior, and access to recorded authority. Python and Node enter the same core in process rather than implementing a second workflow. |
| Task-bound worktree and local Binary DB | The worktree is one isolated mutable implementation workspace. Binary DB owns recorded Plan, Task, Change, Snapshot, Line, and related local state. A Snapshot is the boundary between mutable edits and durable AIT history. |
ait-server | Owns the registered remote Repository authority, shared remote workflow state, typed Worker Jobs, evidence, and offsite preservation of recorded state that reached the server. It does not preserve unsnapshotted local edits. |
ait-runner | Claims a compatible Worker Job, materializes exact Snapshot content, executes the Repository-declared CI entrypoint in an isolated attempt, and returns bounded evidence. It never becomes Repository authority. |
Primary local authoring path#
The coding client remains responsible for understanding the request and authoring the implementation. AIT gives that work a stable repository identity and an isolated mutation boundary:
- The client invokes
aitthrough the CLI or a supported native binding. - The native core resolves the exact Repository, Plan item, Task, Change, and Task-bound worktree.
- Code changes remain mutable inside that worktree until a Snapshot is created.
- The Snapshot and workflow records enter local Binary DB authority; the configured closeout path can then evaluate that recorded state.
Multiple agents remain independent because each active Task owns a distinct worktree and command lock. AIT_RAM may accelerate placement, but it does not change the authority boundary: unsnapshotted dirty files are workspace state, while recorded Snapshots remain recoverable AIT state. See Parallel Task Isolation.
Optional remote authority and CI path#
Recorded local state reaches ait-server only through an explicit configured remote operation. Once received, the server owns the remote Repository copy, shared workflow state, evidence, and Worker Job queue. This enables remote management and offsite recovery of the exact state that reached the server.
For CI, the server commits a typed Worker Job. ait-runner claims that job, materializes its referenced Snapshot into isolated attempt storage, runs the Repository-declared entrypoint, and returns bounded results. The server records the resulting evidence; the runner's attempt directory is disposable and is not a second authority.
Remote preservation is not automatic failover and cannot reconstruct dirty or untracked workspace files that were never captured and transferred. See Remote Infrastructure and `ait-runner`: Native CI Execution Plane.
One core through native embeddings#
ait-python and ait-node load the admitted native runtime in process. They provide application-facing entry surfaces without launching a second workflow engine or redefining repository authority. An embedded application must still select the exact Repository context and follow the same Task, Snapshot, remote, and policy boundaries as the CLI.
This diagram is intentionally limited to the current RC.6 product boundary. Release-family components, version evidence, and package composition remain defined by Distribution and Release.