# DSH Visual Acceptance V0.1 Architecture

> English companion to [architecture.md](architecture.md). It distinguishes observed mechanisms from target design; see the [spike report](spike-report.md) for evidence.

## 1. Architecture decision

Use a staged hybrid architecture: **core-neutral, thin DSH Adapter, no long-running service**.

```text
DSH Web Client
  conversation.view
        │
        ▼
DSH Host Adapter
  run lifecycle / workspace boundary / artifact access
        │
        ▼
Local Runner ───────── Provider Adapters
  Chrome CDP             ModLens / Vision CLI / optional VLM
        │
        ▼
Acceptance Core
  schema / issue identity / decision / retest
        │
        ▼
Workspace-local Storage
  manifests / evidence / screenshots / reports
```

V0.1 does not start a resident daemon. The DSH Host starts a Runner per Run and releases Chrome, listening ports, and temporary directories at the end. This lowers authentication, port-conflict, and orphan-process costs.

### Current closed-loop Beta implementation

```text
conversation.view UI
  → localhost Host API
  → workspace/session validation
  → Chrome CDP deterministic runner
  → Finding Candidate
  → project-level Issue + append-only Decision
  → local read-only Change Package
  → immutable Matrix Retest + candidate relations
  → human verification
```

Provider inference and automatic Agent session injection are target architecture only. Signals create Candidates; formal Issues, Decisions, and `resolved` require human actions. The handoff boundary is a local Markdown/JSON package and **Copy**, never “sent to Agent”.

### `0.1.2-responsive-acceptance` source candidate

The module boundary stays intact. `coverage-presets.mjs` creates versioned Matrices; `/breakpoints` reads accessible stylesheets and reports completeness; the Runner adds bounded quality facts, screenshot-content validation, and same-Matrix Diff; Checkpoints add controlled `actions`. Run Schema advances to `0.1.2-responsive-acceptance`, while Issue, Decision, and Change Package retain `0.1.1-closed-loop` to avoid an implicit lifecycle migration.

## 2. Module boundaries

### Acceptance Core

Must not depend on DSH, React, Chrome, or any visual Provider. It owns versioned schemas; Target and Matrix; evidence source; Issue fingerprint and lifecycle; human Decision; retest matching; and claim-strength validation.

### Local Runner

Owns deterministic browser facts: Chrome launch/connection, fixed CSS viewport/theme, navigation and Ready condition, console/exception/request/HTTP, image/style/font state, requested/layout/visual viewport, horizontal overflow, basic accessible-name/label and reachability signals, screenshot-content validation, same-Matrix Retest Diff, and environment manifest.

### Provider Adapter

```ts
interface VisualProvider {
  probe(): Promise<ProviderAvailability>
  analyze(input: ProviderInput, signal: AbortSignal): Promise<ProviderEvidence>
}
```

Provider capability claims, availability probe, and this-Run execution result are separate. Do not import non-public implementation from another DSH plugin.

### DSH Adapter

- Host: Run tasks, path fence, artifact index, lifecycle.
- Client: only the formal `conversation.view` slot.
- Maintain a DSH-version compatibility matrix.
- Do not access DSH internal DOM or private CSS classes.

## 3. Data model

```text
AcceptanceProject
 ├─ AcceptanceRun[]
 │   ├─ immutable Target / Matrix snapshot
 │   ├─ CheckpointResult[]
 │   ├─ FindingCandidate[]
 │   └─ RetestRelation[]
 └─ Issue[]
     ├─ stable scope / detector fingerprint
     ├─ lifecycle
     ├─ append-only decisionHistory
     └─ append-only verificationHistory
```

```yaml
lifecycle: active | resolved | unresolved | regressed
decision: pending | approved-fix | accepted-risk | dismissed | deferred
decisionHistory: DecisionEvent[]
verificationHistory: VerificationEvent[]
```

An Issue has current state plus non-overwritable history. No later Run may silently erase a human Decision.

## 4. Execution and state-reproduction contract

1. A human confirms Target and Matrix.
2. The client creates a Run through the Host.
3. The Runner executes deterministic checks and returns browser evidence and screenshots.
4. The Host returns Finding Candidates.
5. A human creates Issues and adds Decisions.
6. Only an `approved-fix` Issue can create a local package for copying.
7. After the user changes the target, a Retest replays the same immutable Matrix.
8. The system displays six candidate relations; a human confirms, rejects, merges, or splits them.

V0.1 accepts three deterministic state mechanisms: URL/query, a user-provided fixture, or limited deterministic browser actions. Natural-language requests such as “enter the error state” are not a contract. Every Checkpoint needs a Ready condition; timeout becomes `unreached`.

`Target` is the exact page selected, not only an origin. With a `/` checkpoint path, the Runner retains the Target pathname and existing query. Only a non-root path such as `/reports.html` may switch page within that origin. `state` and `theme` query parameters are a reproduction attempt, not proof that a state was reached.

## 5. Storage and security

```text
.dsh-visual-acceptance/
├── project.json
├── schema.json
├── runs/<run-id>/manifest.json
├── runs/<run-id>/screenshots/
├── issues.json
└── change-packages/
    ├── <package-id>.md
    └── <package-id>.json
```

Schemas are versioned. Writes use a temporary file and atomic replace. Artifact paths are relative and should remain outside Git. The system does not record cookies, authorization headers, existing page form values, or full network bodies. Explicit `fill/select` recipe values are stored in the local Run Matrix but omitted from public action evidence and Change Packages, so credentials are forbidden. Directories use `0700`; manifests, PNGs, JSON, and Markdown use `0600`.

Issue changes are serialized inside one Host process. Cross-process file locking is not implemented, so two DSH processes must not modify the same workspace/project concurrently. Old `0.1.0-slice` Runs stay readable; first Issue creation initializes the project files without deleting old Runs.

## 6. Current Host API

| Method | Path | Purpose |
|---|---|---|
| GET | `/visual-acceptance/context` | Session workspace and capability boundary |
| POST | `/visual-acceptance/breakpoints` | Read accessible CSS media queries and report breakpoint completeness |
| GET | `/visual-acceptance/runs` | List workspace Runs |
| POST | `/visual-acceptance/runs` | Validate input; create and execute a Run |
| GET | `/visual-acceptance/runs/:runId` | Run detail and progress |
| POST | `/visual-acceptance/runs/:runId/cancel` | Cancel active Run |
| POST | `/visual-acceptance/runs/:runId/retest` | Retest from a completed baseline's immutable Matrix |
| GET | `/visual-acceptance/runs/:runId/screenshots/:name` | Read local screenshot evidence |
| GET / POST | `/visual-acceptance/issues` | List project Issues / create from Candidate or screenshot |
| GET | `/visual-acceptance/issues/:issueId` | Read Issue and history |
| POST | `/visual-acceptance/issues/:issueId/decision` | Append human Decision event |
| POST | `/visual-acceptance/issues/:issueId/relations` | Save human retest, rejection, merge, or split |
| POST | `/visual-acceptance/issues/:issueId/change-package` | Create local package only for `approved-fix` |

The Host distrusts any client-provided `cwd`; it resolves the actual workspace from `sessionQuery`. Remote URLs, workspace-external HTML, out-of-bounds Run IDs, and invalid screenshot names are rejected. A session allows only one active Run, preventing concurrent Chrome launches.

## 7. Compatibility and remaining engineering gates

| Scope | Current evidence | Release gate |
|---|---|---|
| DSH Host `0.1.1-rc.2` | E3 | Automated lifecycle test |
| `conversation.view` | E3 | Mounted in real DSH Web session and completed a Run |
| DSH Web UI | E3 | 1440px and 390px, console, Run/cancel checks |
| DSH Desktop shell | Tab observed by user; automation absent | Light/dark and close/reopen |
| Chrome CDP 151 | E3 | One run on minimum and current version |
| ModLens 3.23.1 | Probe only | Fixed-sample adapter test |

Still required after `0.1.2`: explicit destructive schema migration tooling, cross-process lock/recovery, reference-design identity and comparison (the current Diff is Retest-only), actual Provider execution with minimized evidence, automatic Agent injection, Desktop compatibility, and a five-real-project modification/retest pilot.