115 lines
7.2 KiB
Markdown
115 lines
7.2 KiB
Markdown
# Architecture
|
|
|
|
AIE is a local engineering memory with two cycles: investigation/refinement and
|
|
implementation, connected by DEC and Plan. OODA is adaptive; gates constrain delivery.
|
|
The CLI records external observations and applies deterministic checks. It does not
|
|
execute repository commands, operate a server or provide distributed collaboration.
|
|
|
|
## Runtime and modules
|
|
|
|
Java 25, Gradle 9.3.1, Spring Boot 4.0.9, Modulith 2.0.9, Picocli 4.7.7 and Jackson 3
|
|
remain pinned by the build. JUnit 5.13.4, AssertJ and Modulith/ArchUnit verify behavior.
|
|
GraalVM CE 25.5.5.0+3 is pinned in .sdkmanrc. Spring supplies process lifecycle and AOT;
|
|
services are ordinary Java classes with explicit project paths and no retained Work
|
|
cache. Infrastructure stays outside immutable domain records.
|
|
|
|
| Module | Owns | May depend on |
|
|
|---|---|---|
|
|
| filesystem | Codecs, paths, SQLite sessions/typed storage, atomic external files and locks | none |
|
|
| project | Bootstrap, discovery, native/entry contracts and repository policy | filesystem |
|
|
| work | Work identity/guidance/lifecycle, source snapshots and EPIC graph/policy | project, filesystem |
|
|
| discussion | Entries, topics, surveys, answer history and dispositions | work, project, artifact, filesystem |
|
|
| decision | Drafts, approvals, revision and supersession | work, filesystem |
|
|
| planning | Plans, dependencies, results, experiments and scope exclusions | work, decision, discussion, artifact, filesystem |
|
|
| artifact | Temporary payloads, lifecycle, publication recovery and typed receipts | work, filesystem |
|
|
| agent | Proposal adapters, bounded local transport, validation and application | project, work, discussion, decision, planning, artifact, filesystem |
|
|
| legacyimport | Explicit DF preview/import, preserved originals and provenance | filesystem, project, work, discussion, artifact |
|
|
| verification | Integrity/readiness, gates, snapshots, coordination, migration and context | protocol modules |
|
|
| cli | Picocli commands and presentation | public module APIs |
|
|
|
|
ArchitectureTest enforces these boundaries. Work does not import Decision, Artifact
|
|
or Verification. Verification coordinates across independently owned domains.
|
|
|
|
## Storage boundary
|
|
|
|
New projects use `.ai-engineering/aie.db`, selected explicitly in the bootstrap.
|
|
Small configuration and entry files remain outside the database. File existence alone
|
|
never selects SQLite. Contract 4 and the database application/schema versions are
|
|
validated before use. Legacy decoding remains explicit and never converts on read.
|
|
|
|
SQLite JDBC 3.54.1.0 provides the embedded engine. SqliteDatabase owns connection
|
|
lifecycle, foreign keys, WAL/FULL durability, IMMEDIATE writes, snapshot reads and
|
|
bounded busy waits. Nested services share a transaction; failed nested mutations
|
|
cannot be accidentally committed after an exception is caught. File-publication
|
|
callbacks run after commit or rollback, after the connection closes.
|
|
|
|
SqliteRecords maps trusted record components to typed scalar columns and ordered
|
|
child rows. Composite operational values have a domain codec, not serialized file
|
|
content. List presence preserves null versus empty, necessary for historical hashes.
|
|
Identity/current-revision/format/reference tables retain ownership and revisions;
|
|
EPIC links have a unique child-parent index and foreign keys. Selected Work reads
|
|
use direct keys. Global integrity checks still inspect the whole project.
|
|
|
|
A project publication lock fences storage migration/rollback from writers. SQLite
|
|
commands wait a bounded interval and reject a backend transition observed while
|
|
waiting. Ordinary related reads need no file lock and use one database snapshot.
|
|
|
|
## Quality and temporary files
|
|
|
|
QualityGates stores required project definitions and cumulative Work additions.
|
|
Observed results bind procedures, actual invocation, inputs, Work scope/guidance,
|
|
DEC revisions, outcome and a short summary. Missing, failed or stale gates block
|
|
manual, Plan and EPIC delivery. Delivery snapshots bind the exact passed results.
|
|
Human approval remains a different record and responsibility.
|
|
|
|
Artifact bytes remain outside SQLite. Inputs stay available while the Work needs
|
|
checks. Completion atomically records validated retirement intent; after commit,
|
|
eligible payloads are unlinked and acknowledged. Pending retirement is repeatable
|
|
when deletion or acknowledgement was interrupted. New checks refuse retired inputs.
|
|
Structured Plan/EPIC receipts need no payload file. Legacy originals are preserved.
|
|
Requested outputs stay in their delivery destinations, outside the cleanup scope.
|
|
|
|
ArtifactPublication journals only owned publication intent. Rollback/recovery removes
|
|
its own orphan payload, never an unrelated file. Unknown residue is reported for
|
|
inspection. Local provider workspaces are bounded temporary directories; raw transport,
|
|
credentials, environment and complete logs do not become engineering memory.
|
|
|
|
## Authority, coordination and migration
|
|
|
|
Guidance preserves explicit human choices, DEC requests and approval policy.
|
|
Decision/Plan revisions enforce accepted authority, dependency completion, experiment
|
|
reconsideration and unresolved concerns. SQL promotion/supersession and related
|
|
references commit together. RUN failure rolls back its proposal and separately
|
|
records a short diagnostic without references to reverted records. Request replay
|
|
remains idempotent. No adapter can approve a DEC or answer on behalf of a human.
|
|
|
|
PlanCoordinator and EpicCoordinator retain SYSTEM_PLANS/SYSTEM_EPIC provenance,
|
|
RESULTS/DECOMPOSITION policy and explicit scope-bound delegation. Related SQL
|
|
mutations/propagation are transactional. Historical legacy semantics and hashes
|
|
remain readable; only the legacy backend retains per-file recovery boundaries.
|
|
|
|
StorageMigration previews canonical hashes, retains safety originals, imports typed
|
|
records in a separate database, compares content/authority/history and validates
|
|
before activation. Exact legacy bytes stay external for revision-chain verification;
|
|
readers also compare them with typed rows. Contract 4 and a visible legacy-reader
|
|
marker prevent incompatible writers. Recovery is repeatable; rollback refuses to
|
|
lose engineering memory written after activation. Existing tracked originals are
|
|
not removed. Details: [migration](storage-migration.md).
|
|
|
|
## Native package
|
|
|
|
`nativePackage` builds AIE and the pinned SQLite diagnostic CLI with companion native
|
|
libraries and a checksum manifest. Native hints cover operational records/resources.
|
|
The candidate verifier creates a disposable database with native AIE and reads it
|
|
with packaged sqlite3. Install preparation is distinct from activation: versioned
|
|
releases, a current symlink and shortcuts are switched only after verification.
|
|
Installer tests use fake tools and disposable destinations. This Work did not run
|
|
an actual installer or modify the active distribution or consumer projects.
|
|
|
|
Primary references: [SQLite JDBC native support](https://github.com/xerial/sqlite-jdbc#graalvm-native-image-support),
|
|
[SQLite transactions](https://sqlite.org/lang_transaction.html),
|
|
[foreign keys](https://sqlite.org/foreignkeys.html),
|
|
[official source releases/checksums](https://sqlite.org/download.html),
|
|
[Boot requirements](https://docs.spring.io/spring-boot/4.0/system-requirements.html),
|
|
[Gradle Java compatibility](https://docs.gradle.org/9.3.1/userguide/compatibility.html).
|