feat: adopt local SQLite engineering memory and quality gates

This commit is contained in:
2026-11-22 14:39:00 +00:00
parent f5d5db73c2
commit 218c060b94
228 changed files with 28728 additions and 1161 deletions
+421
View File
@@ -0,0 +1,421 @@
# SQLite persistence: legacy mapping and migration cases
This is the implementation map for WRK-000D / DEC-0001 / PLN-0001, starting with
TSK-0001. It describes the inspected file backend and the invariants the SQLite
implementation must preserve. The implementation sections below record the completed SQLite integration; the
source inventory also documents the supported legacy backend.
The active CLI and this repository's canonical `.ai-engineering` remain on the file
backend. Native installation, replacement of active binaries/libraries/shortcuts,
and migration of consumer projects are deferred by explicit human instruction.
Implementation and verification use fixtures, disposable copies and build outputs.
## Persistence boundary
One SQLite database, `.ai-engineering/aie.db`, will own a local project's Work
memory. Keep discovery/configuration/agent entry files small and explicit where
bootstrap needs them. A file named `aie.db` alone does not establish that migration
completed or that the installed CLI can read its schema.
Store domain fields and relationships, not files encoded as BLOB, base64 or a large
TEXT document. Ordered child data belongs to typed dependent rows; constrained
operational structures may use an explicit codec when they are not independently
queried. Do not put every aggregate into a serialized `work.md` column.
Generated contexts, readiness/evaluation reports, suggested actions and freshness
flags are projections, not additional authorities. Rebuild them from the applicable
records in a consistent read transaction. File payloads remain outside SQLite.
## Source-to-target inventory
Table names below identify logical groups for the schema step, not a final SQL
migration. Preserve ordered lists and nullable/omitted historical values where they
affect interpretation or digests. Do not change externally visible identities.
| Source and owner | Domain data to preserve | Target groups and invariants |
|---|---|---|
| `ai-engineering.yaml`; `ProjectService`, `ProjectConfig` | Project identity/name; repositories, paths/type/language/access/validation commands; general/activity adapters, profile/model/timeout and archive policy | Bootstrap configuration and typed configuration records; one authority per field. Empty repositories are valid. Repository access defaults to read-only. A source repository is optional. |
| `protocol.json`, entry README/AGENTS; `ProtocolGuide`, `ProtocolContract` | Contract/schema versions, capabilities, startup and managed instruction boundaries | Explicit storage/schema discovery and compatibility. Preserve external project rules. Unsupported contracts fail before writes. `onboard` is not data migration. |
| `works/.sequence.yaml`; `WorkService.Sequence` | Highest reserved Work number, including gaps | Transactional project-local allocation. Preserve legacy high-water interpretation; never recompute solely from surviving Works or rename decimal-looking historical IDs. |
| `work.md`; `Work` | ID, title, description, goal, motivation, ordered constraints/acceptance criteria, status, timestamps, author, repository revisions and all child references | `works`, ordered scope/revision rows and owned references. A Work ID is project-wide; `(work_id, child_id)` identifies a Work-local child. Preserve terminal/editability/archive/reopen semantics. |
| Work guidance; `WorkGuidance` | Mode, approval policy, explicit choice history and decision requests, with actor/reason/time/human attestation | Guidance/choice/request rows. Absence in a historical Work differs from newly UNSPECIFIED guidance. Only recorded human instructions change authority. |
| Work completion/events; `Work.Completion` | Criterion texts and evidence references; scope hash, integrations, summary, origin, delegation/aggregation, actor/time and lifecycle events | Completion/criterion/integration/event rows. Preserve HUMAN, SYSTEM_EPIC and SYSTEM_PLANS provenance, not just COMPLETED status. Do not invent approval during migration. |
| `discussions/DSC-*.md`; `DiscussionEntry` | Work/thread/topic, kind, author/time, exact narrative, optional earlier response target | Discussion entries and response edges in source order. QUESTION/ISSUE remains pending until an explicit linked RESPONSE/CONCLUSION. Preserve UTF-8, Markdown and whitespace. |
| `topics/TOP-*.md`, `.history`; `TopicService` | Title/description, ordered source discussion IDs, revision/hash/editor/reason/time | Topic/current revision/source rows. Legacy threads remain implicit topic views, without fabricated formal topic history. |
| `surveys/SVY-*.md`, `.history`; `SurveyService` | Questions/options/recommendation/multiple flag/topic/sources; every answer, selected choices, author/time and supersedes link | Survey/question/option/answer/choice rows and revision provenance. Recommendations are not answers. Superseded answers remain available; latest answer determines pending state. |
| `dispositions/DSP-*.md`; `DispositionService` | Target entry, ARCHIVE/RESTORE, reason/evidence, author/time | Owned disposition/evidence references. Archive remains subject to the configured policy; restore does not delete the original proposal. |
| `decisions/DEC-*.md`, `.history`; `DecisionService` | Narrative/context/approach/rationale, alternatives/risks/criteria/evidence, approval status/history, revisions and revises/supersededBy | Decision/revision/approval/list/reference rows. DIRECT and SYSTEM_PLAN approval provenance stay distinct; preserve causal Plan IDs and no-human-attestation semantics of permitted system promotion. |
| `plans/PLN-*.md`, `.history`; `PlanService` | Narrative, decisions, steps and ordered criteria/dependencies/results/evidence; status/revisions; scope exclusions; experiments | Plan/revision/step/dependency/exclusion/experiment rows. Excluding cancelled scope does not satisfy a dependency; completed steps still require results and applicable checks. |
| Plan experiments; `Experiment` | Hypothesis, criterion, invocation, step, author/time; observed outcome, interpretation/next action/evidence, retry/reconsideration, questioned DEC | Experiment/result/reference rows. Criteria precede results; failed retries require reconsideration. Open experiments and unresolved DEC concerns continue to block affected execution. |
| `epic/WRK-*.md`, `.history`; `EpicService` | RESULTS/DECOMPOSITION, ordered children/importance, revision/hash, explicit scope-bound authorization | EPIC policy/revision/link/authorization rows. Enforce existing forest topology, one parent, no cycles and no authorization inferred from status. |
| `agent-runs/RUN-*.md`; `AgentService`, `AgentRun` | Request identity/task/activity/requester/executor/source hash; APPLYING/COMPLETED/FAILED, typed proposal, applied references, diagnostic and invocation provenance | Run/proposal/applied-reference/invocation rows. Preserve idempotency and interrupted publication diagnostics; do not retain raw transport, environment or credentials. |
| `artifacts/evidence/ART-*/artifact.yaml`; `ArtifactService` | Work-local identity, origin/purpose/path, SHA-256, size, author/time | Artifact metadata and references. New temporary evidence needs explicit lifecycle state. Payload bytes are external; their absence is not success unless legitimate post-check disposal is recorded. |
| Plan/EPIC completion and DF-import receipt payloads | Typed receipt identity, inputs, referenced source revisions/hashes and producer provenance | Typed internal receipt/source rows. These are protocol state; parse only recognized owned receipts, not arbitrary user payloads. Preserve legacy payload/representation provenance when required. |
| `runs/`, `artifacts/outputs`, references and experiment files | Temporary execution files, requested deliverables and external references | Filesystem lifecycle/paths only when needed. A RUN record differs from the ignored `runs/` folder. Do not promote every generated file into permanent evidence. |
### Current gate boundary
`ProjectConfig.Repository.validationCommands` describes repository validation
commands. The legacy baseline did not expose a complete project-level and
per-Work gate-result catalog; QualityGates now supplies that contract in SQLite. Completion enforces mechanical protocol checks,
recorded results and owned evidence; it does not itself execute those commands.
TSK-0007 adds the project gate baseline and Work additions while preserving this
execution boundary. A historical COMPLETED label or an ART reference is not proof
that a newly introduced gate was executed. Imported approvals retain their original
meaning; new gate results must record actual observations of the applicable state.
## Hashes and historical representations
There are several distinct digests, with different source material:
1. **Revision chain:** `Revisions.chain` hashes the preceding file's exact UTF-8
content. Parsing and reserializing YAML can change bytes without changing the
domain object. Keep the original source representation/provenance available
for legacy chain checks; never replace a historical hash with a new one merely
to make import pass. Retained migration originals stay outside database TEXT.
2. **Work completion scope:** `VerificationService.scopeHash` hashes deterministic
JSON of selected domain fields and ordered child records. Optional legacy
fields are conditionally omitted. Do not normalize missing guidance to a new
choice, add optional empty collections to old digest inputs, or reorder lists.
3. **Plan/EPIC receipt sources:** source Plan revisions and child completions bind
to their semantic digests and producer/authority metadata. Importing a receipt
does not authorize re-completion, reevaluation or a new human approval.
4. **Artifact integrity:** SHA-256 is over exact payload bytes; retain size/path
ownership checks and the distinction between a user file and a protocol receipt.
5. **Adapter and import fingerprints:** preserve source fingerprints, request IDs
and import source identities. An identical retry is not a new Work or RUN;
changed input with the same identity requires existing rejection/review rules.
Storage schema, manifest schema, protocol contract and Markdown document versions
are separate. Existing record schema is 1, Work sequence reads versions 1/2,
narrative Markdown reads document versions 1/2 and protocol contracts read 1/2/3.
A new SQLite schema does not mean historical documents were rewritten.
## Unit-of-work and file lifecycle map
| Operation | Records that must publish coherently | External boundary |
|---|---|---|
| Create Work | Reserved high-water and initial identity/guidance | Bootstrap and legacy source discovery; no ID reuse on retry |
| Add discussion/answer | Entry or revised survey, source links and Work references/timestamp | No implicit evidence attachment or human answer |
| Accept/revise/supersede DEC | Approval and revision, replacement links and affected references | Preserve immutable accepted content and causal authority |
| Create/update Plan or finish step | Eligible decision promotion, Plan revision, step/result/evidence references | Evidence must be available and valid during dependent checks |
| Apply agent proposal | RUN state, typed proposals/applied references and resulting records | Provider call stays outside a write lock; recheck source state before application; preserve idempotent retry |
| Complete Plan/Work or coordinate EPIC | Source revisions, internal receipt, completion and applicable propagation | No automatic completion from an empty set; retain reopen/authorization rules |
| Retire temporary evidence | Completed dependent checks, minimal result and legitimate disposal state | File deletion follows committed result/disposal intent; interruption is recoverable; requested outputs are protected |
| Migrate file backend | Imported rows, mapping/provenance and activation state | Stable source snapshot, migration safety copy and staged database; never switch before verification |
Keep local write transactions short; provider calls and external quality commands
must not hold the database write lock. A read of related context uses one coherent
view. Waits have a duration limit and an actionable diagnostic.
File publication and removal are not SQLite transactions. Define interruption
cases explicitly: unreferenced staged file; committed reference with missing input;
committed checked result pending cleanup; process interrupted before completion.
Only the third case is eligible for post-check disposal. Removing one evidence
file must consider every dependent check, including other Plans or Work completion.
## Representative corpus and expected outcomes
Use the existing resource bytes and workflow builders. All mutations below are
against temporary copies/projects. Do not regenerate frozen resources with the new
writer to obtain expected values.
| Corpus/case | Existing source | Required result of future migration/SQLite checks |
|---|---|---|
| Frozen pre-contract delivered Work | `src/test/resources/compatibility/baseline-v1/.ai-engineering`; `CompatibilityTest` | Keep 9 original files unchanged, implicit contract 1 and sequence schema 1 readable, accepted DEC plus draft history, legacy defaults and exact frozen scope hash. SQLite import yields equivalent meaning without rewriting or reopening the source. |
| Missing optional refinement/guidance | `CompatibilityTest`, `RefinementSafetyTest`, `WorkGuidanceTest` | Interpret defaults in memory; no invented mode, waiver, answer or approval. New guided Works still require human choices. |
| Current refinement/history | `DiscussionRefinementTest`, `RefinementSafetyTest`, `DiscussionMarkdownTest` | Preserve UTF-8/body text, response links, implicit/formal topics, all survey answers and latest-answer semantics, reversible dispositions. |
| DEC and Plan authority | `WorkGuidanceTest`, `PlanDecisionPromotionTest`, `OperationalSafetyTest` | Preserve direct versus system approvals, exact causal links, accepted-content immutability, revised decision blocking and Plan authority. |
| Plan consolidation/recovery | `PlanConsolidationTest`, `PlanConsolidationSafetyTest` | Preserve actual completed Plan sources, exclusions, incomplete scopes, existing receipt reuse, reopen semantics and pending questions. Tampered evidence fails before the step write. |
| EPIC delegation/history | `EpicWorkflowTest`, `EpicSafetyTest` | Keep important/optional children, authorization invalidation, nested forest and historical hashes; reproduce recovery without duplicating completions. |
| Import receipts and colliding source-local IDs | `src/test/resources/discussion-import/alpha`, `beta`; `DiscussionImportTest`, `legacyimport/DiscussionImportRecoveryTest` | Preserve stable source identity and original evidence; distinguish sources that reused DSC IDs; identical reimport/recovery does not duplicate Works or overwrite changed inputs. |
| Fresh processes without Git | `ProcessContinuityTest`, `scripts/native-smoke.sh` | Reconstruct the same memory in a new process without Git installed; preserve source files and avoid a server dependency. |
| Evidence missing/tampered before check | `IntegrityTest`, `PlanConsolidationSafetyTest` | Reject size/hash/path/ownership failures and do not publish successful checks. |
| Explicitly retired temporary evidence | New scenario in TSK-0008/0009 | Check while present, persist minimal result, retire only after all consumers finish; historical queries remain valid; pending consumers prevent deletion. This behavior is not implemented in the current backend. |
| Unsupported versions/unknown fields | `CompatibilityTest`, `OperationalSafetyTest` | Reject malformed, future or inconsistent records before activation; a current manifest cannot hide unsupported history; preview does not modify source. |
| Traversal, symlink, foreign ownership | `IntegrityTest`, `RefinementSafetyTest`, `EpicSafetyTest` | Refuse unsafe paths/identities without reading a symlink target, leaking its contents or publishing partial records. Apply the same boundary to database and sidecar paths. |
| Interrupted conversion/retry | New scenario in TSK-0010; existing import recovery pattern | Fail before activation, retain usable legacy state, expose recovery state and retry without duplicate IDs/approvals/completions. Two usable writers must not become independent authorities. |
| Local concurrent writers/rollback | New scenario in TSK-0003 | Enforce ownership/foreign keys and whole-operation rollback; no duplicate allocated identity; bounded lock contention. Multi-machine reconciliation is out of scope. |
### Frozen anchors
The frozen baseline's expected completed Work scope hash is
`72d5803add0b8714d7dc4bf7e63ad55cc3259df910aa8b03790657eac4c2bd02`.
Its accepted DEC is revision 2; `previousHash` and the original draft's byte digest
are `545dc8e36da222fdeaf9458f77880bf2d1842738b82bac5296cddf62452a7e01`.
The ART-0001 payload digest is
`98545564d0747210b91b933bf8554c4b7e36ba878e6662cb48156b08ff74e1ee`.
These anchors were inspected from existing resources, not generated by SQLite.
## Mapping to implementation steps
- TSK-0002/0003 establish the driver, native loading, schema and unit of work.
- TSK-0004/0005 map investigation and implementation records while retaining authority.
- TSK-0006 maps RUNs, source fingerprints and deterministic coordination/receipts.
- TSK-0007/0008 add gate records and temporary evidence lifecycle.
- TSK-0009 builds projections without repeated unrelated reads.
- TSK-0010 exercises the corpus before any activation and implements public migration.
- TSK-0011 declares storage compatibility and initializes local ignored state.
- TSK-0012 prepares the distribution with disposable installer fixtures only.
- TSK-0013 updates public operational documentation once the commands exist.
- TSK-0014 verifies the integrated result and hands a reproducible workload to WRK-000C.
This mapping does not change DEC authority, weaken a gate or authorize installation.
Successful legacy tests characterize the source backend; they do not yet prove
equivalence of a SQLite importer. Future steps must exercise these same expectations
through the implemented database path.
## Driver and Native Image proof (TSK-0002)
The selected candidate is `org.xerial:sqlite-jdbc:3.54.1.0` (SQLite 3.54.1).
`src/sqliteProbe` is a build-only entry point, separate from the installed CLI and
project discovery. `sqliteProbe` exercises create/read/write/rollback/reopen in a
JVM; `nativeSqliteProbeCompile` builds the same entry point with its JNI library
exported beside the executable. The native binary explicitly selects a GraalVM
Java 25 toolchain; selecting the Gradle JVM alone did not select the correct
Native Image launcher in the first local build attempt.
Example disposable verification, using the repository's pinned GraalVM:
```sh
mkdir -p build/sqlite-probe/disposable
./gradlew sqliteProbe -PprobeDatabase=build/sqlite-probe/disposable/proof.db
./gradlew sqliteProbe -PprobeDatabase=build/sqlite-probe/disposable/proof.db
./gradlew nativeSqliteProbeCompile
bash scripts/sqlite-probe.sh /absolute/path/to/build/native/nativeSqliteProbeCompile/aie-sqlite-probe
```
The shell proof creates its own temporary database and starts separate native
processes, checks a UTF-8 value and rollback, disables temporary-library extraction
and verifies that an isolated executable fails when its companion library is absent.
These are build/driver checks; they do not install the native application, activate
the database backend or establish the end-to-end latency of the AIE CLI.
## Transaction foundation (TSK-0003)
`SqliteDatabase` now provides explicit initialization and command-scoped read/write
transactions. Opening a missing database does not create files. Its application ID,
`user_version` and schema metadata must agree before domain operations proceed.
Initialization uses WAL with FULL synchronization; connection foreign keys are
enabled explicitly, and writer transactions begin IMMEDIATE with a bounded busy
timeout (2 seconds by default).
Nested operations share their connection. A nested failure makes the enclosing
write rollback-only even if its caller catches the exception. Read transactions
use a read-only SQLite connection and cannot be upgraded implicitly to writes.
Related reads retain a stable snapshot while another local writer commits.
`sqlite/schema-v1.sql` establishes the ownership/revision/reference keys and local
identity high-water marks. Domain field tables will be integrated in TSK-0004
through TSK-0007; the foundation does not yet route the CLI's Works to SQLite.
References are deferred until commit so related revisions can publish together.
Missing target ownership aborts the transaction. Database and sidecar symlinks,
nonregular paths and orphan sidecars during initialization require inspection.
`SqliteDatabaseTest` covers initialization, path encoding, rollback, foreign keys,
nested failures, read-only access, snapshot consistency, writer contention,
unsupported schemas and filesystem boundaries. The build-only native probe also
creates and reopens the foundation schema, verifying its resource loading and
transaction entry points in Native Image without installing the application.
## Investigation record integration (TSK-0004)
`ProjectService.initializeSqlite` is the explicit backend entry point used by
disposable integration projects. The public `init` default is still the legacy
backend until the storage-contract/initialization step. Existing projects are not
converted by the presence of an arbitrary database file: the bootstrap configuration
must explicitly select SQLite.
`SqliteRecords` maps record scalar fields to typed columns in domain-specific
tables. Ordered fields use dependent tables and ordinals; structured operational
items (such as an answer or completion) have an explicit JSON representation per
item, not a serialized source document or entire Work. Work-owned references also
bind to the shared revision identity keys. Tables/columns come from trusted domain
record definitions, while identities and values use bound SQL parameters.
`RecordStorage` adapts the existing record codec and revision operations without
placing canonical Markdown files in SQLite projects. New revision hashes bind to
deterministic materializations of the typed record; migration can retain original
source paths/digests for legacy representations. `WorkService` loads a selected
Work by identity, allocates IDs transactionally and preserves its folder location
when the title changes. Discussions, topic revisions, survey/answer history and
dispositions use the same transaction as their Work references.
Integration checks cover rejected publication rollback, missing owned references,
concurrent local allocation, selecting one Work without parsing an unrelated broken
record, UTF-8 and explicit guidance/decision requests. A fresh JVM reconstructs
discussion/survey context, and the native probe creates and reopens a Work and its
discussion in separate processes using the application's AOT metadata. These checks
do not yet migrate DECs, Plans or the active workspace to the new backend.
## Decision and Plan integration (TSK-0005)
Decisions, approvals, supersession and Plan/experiment revisions now use the typed
record adapter. SQLite Plan creation publishes permitted draft promotions, the
Plan and its Work reference in one transaction. The legacy backend retains its
file-publication recovery path; SQL publication does not compensate by writing
Markdown files. A requested rollback of a prepared SQL promotion marks the whole
unit of work rollback-only.
The existing domain checks still enforce pending discussion, approval policy,
accepted decision references, step dependencies, experiment outcomes and required
owned evidence. Artifact metadata is mapped into SQLite as foundational support
for these checks; payloads remain files and are still retained at this step. The
temporary-artifact lifecycle and disposal policy belong to TSK-0008.
`SqliteImplementationTest` covers human acceptance and immutability, atomic system
promotion rollback/retry under an explicit fixture waiver, supersession and Plan
reconsideration, dependencies, owned evidence and the OODA experiment/retry loop.
Existing file-backend authority, promotion and experiment tests remain applicable.
### TSK-0006 — RUNs e coordenação
RUNs e políticas de EPIC usam registros tipados no SQLite. Idempotência e
fingerprints continuam derivados do contexto; a aplicação de propostas é uma
transação. Uma falha reverte todo o bundle e publica, em transação posterior,
somente o RUN falho com diagnóstico e referências aplicadas vazias. Não há
transporte bruto ou logs no banco. A coordenação conserva os recibos existentes
até a integração de seu ciclo de vida no TSK-0008.
Verificação: 30 cenários distintos de SqliteCoordinationTest, EpicWorkflowTest,
EpicSafetyTest, RefinementSafetyTest e ArchitectureTest passaram, incluindo
idempotência, falha intermediária via trigger SQL, RESULTS/DECOMPOSITION,
aprovação explícita, revisão de política, propagação e reabertura.
### TSK-0007 — gates obrigatórios
Definições de gates do projeto e adicionais por Work são cumulativas. Cada gate
declara procedimento e caminhos avaliados; não executa comandos. O registro exige
atestado de observação, fingerprint prévio, resultado, invocação e resumo curto.
Arquivos, escopo/guidance do Work e revisões das DECs compõem o fingerprint;
mudanças relevantes ou na definição exigem nova avaliação. Bookkeeping do Plan
não invalida um resultado. Anexos obrigatórios passam pela integridade existente.
Conclusões humanas, por Plans e por EPICs verificam os gates e congelam referências
e hashes dos resultados entregues na mesma transação. A consulta histórica não
reaplica regras configuradas depois da entrega. Testes focados de gates,
coordenação, infraestrutura e arquitetura: 23 cenários passaram. Instalação e
workspace canônico permanecem no formato legado.
### TSK-0008 — anexos temporários e recuperação
O Work aberto conserva seus anexos porque outros checks ainda podem precisar
deles. A conclusão valida os anexos e registra DISCARD_PENDING na transação;
somente após commit remove os payloads e reconhece DISCARDED. Interrupções entre
essas fases são repetíveis por `artifact recover WRK`. Ausência sem validação
prévia continua inválida. Novas avaliações exigem entradas disponíveis, inclusive
após reabrir um Work; o histórico usa o resultado mínimo persistido.
Recibos de Plans/EPICs novos são fatos tipados, sem arquivos JSON. As origens
legadas de importação permanecem preservadas, assim como futuras cópias de
migração. Publicações temporárias usam um pequeno journal operacional, removido
após commit/rollback; recuperação distingue órfão próprio de payload já publicado.
Rollback de preparação remove diretórios vazios próprios e preserva resíduos
desconhecidos. Outputs solicitados fora do estado AIE não são alvos da limpeza.
EXP-0002: 32 cenários distintos focados passaram em duas rodadas. Cobertura inclui
arquivo perdido antes de check, recusa de reuso após descarte, rollback da
conclusão, interrupção após commit e após unlink, publicação interrompida,
repetição, preservação de output e originais legados, recibos e coordenação.
### TSK-0009 — consultas e diagnóstico
Contexto, status, next-actions e validação usam snapshots SQLite para leituras
relacionadas. Parent/links de EPIC têm índice relacional com unicidade de pai e
FKs. Consultar um Work selecionado não carrega outros Works por conveniência:
um registro alheio inválido não bloqueia seu contexto. Validação global continua
inspecionando o projeto, contador, grafo, FK e integridade SQLite.
Compatibilidade inspeciona registros tipados e revisões no banco, sem procurar
Markdown inexistente nem converter arquivos. Contexto expõe gates e disponibilidade
dos anexos. Next-actions sinaliza descarte interrompido sem fazê-lo durante leitura.
15 testes focados passaram, incluindo contexto em JVM separado, snapshot com outro
escritor, isolamento de Work inválido, histórico com formato não suportado e leitura
sem limpeza. A regressão legada de compatibilidade também passou na rodada anterior.
### TSK-0010 — migração explícita
`storage migrate` apresenta prévia sem escrita; `--apply --expect HASH` prepara
uma base separada, importa registros tipados e compara DTOs, revisões, autoridade
e integridade antes de selecionar SQLite. `--recover` e `--rollback` usam o
fingerprint da operação. A cópia de segurança conserva originais e fontes exatas
dos hashes; o staging é removido após êxito. Os arquivos legados existentes
permanecem em seus destinos, sem alteração ou remoção de arquivos rastreados.
Contrato 4 e um marcador visível em `works/` impedem escrita por CLI antiga,
inclusive comandos que já aguardavam o lock. Escritores modernos compartilham
uma fronteira de publicação com espera limitada e recusam mudança de backend
durante a espera. Leituras não precisam desse lock. A recuperação recusa ativação
se o legado mudou; rollback preserva essas alterações e exige nova prévia. Depois
de novas gravações SQLite, rollback é recusado para não perder memória.
A prova encontrou e corrigiu a distinção entre lista nula e vazia (especialmente
exclusions de Plan). Essa presença é tipada no esquema e os hashes originais
continuam ancorados em bytes externos, com comparação contra o registro tipado.
EXP-0003: 34 testes na rodada final passaram, incluindo cinco pontos de falha,
corpus congelado, Plan/survey ativo, EPIC/RUN, IDs reservados e compatibilidade.
Nenhum consumidor nem este workspace foi migrado.
### TSK-0011 — inicialização local
`init` prepara SQLite e bootstrap antes de publicar o workspace. Acrescenta
`/.ai-engineering/` ao .gitignore sem exigir Git, preservando instruções externas
e regras anteriores. `--version-state` deixa essa política ao desenvolvedor;
`--storage legacy` é explícito para compatibilidade. Nenhum comando remove arquivos
rastreados ou converte projetos existentes durante onboard/leitura.
Bootstrap SQLite exige contrato 4 antes de acessar a base; esquemas/contratos
incompatíveis são diagnosticados. As instruções distribuídas exigem CLI compatível
para ler SQLite e proíbem interpretar memória ilegível como projeto vazio. Testes
de continuidade passaram em seis cenários JVM separados, inclusive sem Git no PATH.
A rodada consolidada de init, migração, compatibilidade, protocolo e arquitetura
também passou após explicitar o backend das fixtures legadas.
### TSK-0012 — pacote preparado, instalação adiada
`nativePackage` reúne AIE nativo, bibliotecas companheiras e CLI sqlite3 em
`build/native/package`; distribuições usam esse diretório completo. SQLite 3.54.1
é compilado de fonte oficial com SHA3-256 fixado em scripts/sqlite-version.json.
O verificador confere componentes/hashes/versões, inicializa um projeto descartável
com AIE nativo e lê sua base com o sqlite3 do pacote.
O instalador preparado aceita bin-dir/lib-dir, verifica uma release completa antes
de alternar current e publicar atalhos aie/ai-engineering/aie-sqlite3. Uma falha na
troca dos atalhos restaura a release e os atalhos anteriores. 17 testes com
ferramentas simuladas passaram, inclusive falha parcial de ativação. O pacote real
de build foi verificado em macOS arm64; Linux está coberto pelas fixtures de
instalação, sem prova nativa física nesta máquina.
Nenhuma instalação real foi executada: binários/bibliotecas/atalhos ativos e
projetos consumidores permanecem intactos.
### TSK-0013 — contrato documentado
README, arquitetura, protocolo, compatibilidade e recursos de entrada agora
descrevem memória local SQLite, gates e anexos temporários. O procedimento público
está em docs/storage-migration.md. A referência detalhada do backend de arquivos
foi mantida separadamente como legado explícito. Os dois ciclos, OODA e autoridade
humana permanecem; instalação/migração reais continuam adiadas. Links locais foram
verificados e os testes de init, compatibilidade e Work guidance passaram.
### TSK-0014 — regressão integrada e handoff
`./gradlew check` passou com 230 testes JVM, zero falhas/erros/skips, além dos 11
cenários do fixture Jenkins. O ajuste final do importador SQLite passou em rodada
focada de 17 testes (importação/recuperação e arquitetura). As 17 fixtures finais do
instalador passaram com ferramentas simuladas; nenhuma instalação real ocorreu.
O pacote final e arquivos ZIP/TAR foram gerados com GraalVM e tiveram componentes,
hashes, versões e permissões verificados. O smoke nativo completo passou, incluindo
legado, continuidade, guidance/OODA e os novos cenários SQLite de gate pendente,
conclusão, descarte, recusa de reuso e migração do corpus congelado. O diagnóstico de
processos do macOS exigiu execução fora do sandbox; a repetição autorizada passou.
Uma cópia isolada do pacote abriu SQLite com extração temporária sem escrita; uma
cópia sem a biblioteca JDBC foi corretamente recusada.
O gerador de latência foi verificado com um Work/uma nota sintéticos, sem medição.
docs/latency-scenario.md e scripts/latency-fixture.py foram encaminhados por Discussion
ao WRK-000C, que permanece OPEN. Adoção do banco não foi declarada prova de melhora.
A verificação física foi macOS arm64; Linux/Windows permanecem dependentes da matriz
CI para confirmação nativa. Instalação ativa, workspace canônico e consumidores
continuam no estado anterior, sem migração real.