# ADR-0001: v0.4 Application, transaction, and Automation architecture

- Status: accepted for implementation after independent adversarial review
- Date: 2026-08-03
- Scope: v0.4.0

## Context

PR #70 establishes a UI-independent controller seam but leaves restore, prune,
settings, dialogs, and execution orchestration in MainForm. Issue #69 shows
that the current Node and .NET rollback coordinators learn about applied files
only after a batch returns, so a mid-batch exception can conceal partial
writes. v0.4 also requires scriptable business operations and complete real
WinForms entry automation without exposing production control surfaces.

## Decision

1. Core remains the exclusive data-operation layer and gains a durable,
   backup-bound file transaction journal with crash detection and compensating
   rollback.
2. Application becomes the exclusive use-case layer for all GUI and Business
   operations. Requests are immutable; plans bind normalized input, targets,
   fingerprints, digest, expiry, and single-use execution state.
3. Business Automation is a one-shot console host using experimental JSON
   protocol 0.4. stdout is machine JSON only; writes require explicit
   `--apply` plus an exact fresh plan and digest.
4. GUI Automation runs only in an explicit isolated test launch. It uses a
   current-user-only random named pipe and one-time credential from a protected
   bootstrap descriptor. The bridge only invokes registered control actions on
   the UI thread.
5. A versioned static manifest plus runtime enumeration and causal traces form
   a 100% entry/action coverage gate. Native shell-dialog internals are narrow
   exemptions, but their application-owned launch buttons remain real GUI
   actions.
6. The release package contains the GUI, Automation host, schema, and manifest.
   Protocol 0.4 and manifest versions explicitly permit pre-1.0 evolution.

## Safety invariants

- No Automation path reads, copies, logs, or modifies `auth.json` or
  credentials.
- Test roots require a sentinel and canonical path containment before any
  process starts or write occurs.
- Normal GUI mode creates no Automation listener.
- The named pipe is local/current-user only; arbitrary reflection and arbitrary
  file access are absent.
- A transaction cannot disappear while non-terminal. Recovery is explicit and
  diagnostic; rollback failure preserves both original and rollback errors.
- The current agent never writes remote `main`, merges a PR based on `main`,
  enables auto-merge, or creates a formal tag/Release.

## Alternatives rejected

- Continuing separate MainForm workflows: duplicates behavior and makes
  Business/GUI equivalence unverifiable.
- Direct Application calls from the GUI bridge: does not prove the real control
  event path.
- Public HTTP/TCP listener: unnecessary attack surface for a local release
  tool.
- Hidden WinForms probe as the release gate: cannot prove visible desktop,
  focus, dialog, keyboard, or obstruction behavior.
- Stable JSONL v1 now: commits to compatibility before the real use cases and
  safety model have release evidence.
- In-memory applied-file tracking only: cannot recover after process death and
  repeats Issue #69's fundamental visibility gap.

## Consequences

The implementation adds projects, release artifacts, schema/manifest checks,
and Windows-only E2E infrastructure. Normal operation remains local and
backup-first. Tests become more expensive but produce repeatable evidence and
remove the manual full-entry regression burden. The macOS UI continues to use
Core and must keep building, but full macOS Application migration is outside
the v0.4 Windows release gate.

## Independent review reconciliation

A local Claude Opus consultation completed on 2026-08-03 after 687 seconds
(`fea38f91-b679-405f-bb25-da26bba8fdeb`). Codex compared its threat model with
the repository and accepted these release-gating corrections:

- read-only status/describe remains available during an unfinished
  transaction and reports the bound backup; only mutations are blocked;
- pruning must never delete a backup referenced by a non-terminal journal;
- modal GUI actions are operated by the external Headful desktop driver while
  the pending bridge invocation observes the real GUI event and Application
  lifecycle; no synthetic bridge shortcut substitutes for the dialog;
- the GUI coverage denominator comes from runtime interactive-control
  enumeration, not from the static manifest alone;
- causal proof includes an architecture rule preventing bridge-to-Application
  shortcuts, an observed GUI event/message leg, and independent filesystem or
  SQLite effects; a bypass negative-control test must fail the gate;
- the Headful harness rejects real-home aliases/reparse points and only cleans
  a sentinel-bearing disposable root beneath its owned evidence directory.

The review's proposed Node-to-C# thin-wrapper conversion was not adopted:
the npm CLI is an existing cross-platform product surface, while the Business
host is a Windows release companion. Instead, a shared declarative transaction
corpus will keep Node and C# failure semantics aligned. Suggestions involving
`auth.json` replacement and credential backup were inapplicable: this tool
does not read, copy, or modify `auth.json`. Full two-participant crash
forward-recovery is not promised by v0.4; a post-crash journal deliberately
blocks later mutations and exposes the exact backup for explicit restore,
which matches the Issue #69 acceptance boundary.