73 lines
4.5 KiB
Markdown
73 lines
4.5 KiB
Markdown
# Plugin Delivery Rehearsal Run Design
|
|
|
|
## Context
|
|
|
|
P2-D8e2h introduced a server-authoritative delivery acceptance report, but that report was transient. Operators could not prove which routing, environment, target ledger state, or approval policy they had reviewed before a deployment rehearsal. The next step must preserve that evidence without implying that a real target mutation already happened.
|
|
|
|
P2-D8e2i therefore adds an append-only `PLAN_ONLY` rehearsal Run. It freezes the non-secret acceptance response and an ordered scenario contract in the control database. It does not publish a Plugin, create an approval, enqueue an Outbox command, or execute target DML.
|
|
|
|
## Run Contract
|
|
|
|
Each `factory_plugin_delivery_rehearsal_run` row records:
|
|
|
|
- a unique SHA-256 Run key and schema version `1.0`;
|
|
- mode `PLAN_ONLY`;
|
|
- status `READY` when all acceptance checks pass, otherwise `BLOCKED`;
|
|
- frozen control and target environment codes, target catalog, and routing fingerprint;
|
|
- canonical acceptance JSON plus its SHA-256 fingerprint;
|
|
- an ordered scenario fingerprint;
|
|
- frozen passed/total check counts and scenario count;
|
|
- authenticated creator and creation time.
|
|
|
|
`READY` means the captured prerequisites permit a future isolated rehearsal. It does not mean that any rehearsal scenario has executed or succeeded. `BLOCKED` Runs are still persisted so configuration changes and failed readiness reviews remain auditable.
|
|
|
|
The Mapper intentionally exposes inserts and reads only. There is no application update or delete operation for either table.
|
|
|
|
## Scenario Contract
|
|
|
|
Every Run freezes the same six ordered scenarios in `factory_plugin_delivery_rehearsal_scenario`:
|
|
|
|
1. create and approve a separation-of-duties request;
|
|
2. expire pending or approved evidence;
|
|
3. revoke pending or approved evidence;
|
|
4. execute mixed SQL, permission, and menu apply routes;
|
|
5. preserve a failure and perform an idempotent retry;
|
|
6. compensate in reverse order while verifying ownership and receipts.
|
|
|
|
When the acceptance snapshot is ready, scenarios are `PLANNED`. Otherwise they are `BLOCKED`. No `PASSED`, `FAILED`, or execution receipt state exists in this phase because the service does not run those scenarios.
|
|
|
|
Each scenario stores the evidence required for eventual completion. Its fingerprint projection excludes database IDs and includes sequence, stable code, name, state, evidence, and planning result, so the same projection can be verified after reloading generated keys.
|
|
|
|
## Integrity Verification
|
|
|
|
Creation uses the existing canonical JSON codec and SHA-256 service. The acceptance fingerprint hashes the exact persisted canonical JSON. The scenario fingerprint hashes a canonical ordered projection of all six rows.
|
|
|
|
Detail reads fail closed unless all of the following match:
|
|
|
|
- acceptance JSON fingerprint;
|
|
- schema version and `PLAN_ONLY` mode;
|
|
- status derived from the frozen acceptance snapshot;
|
|
- control environment, target environment, target catalog, and routing fingerprint;
|
|
- passed/total check counts;
|
|
- scenario row count and scenario fingerprint.
|
|
|
|
The raw snapshot JSON is ignored by the REST serializer. Detail responses expose the parsed non-secret acceptance object only after integrity verification.
|
|
|
|
## API And UI
|
|
|
|
All endpoints reuse `generator:delivery:verify`:
|
|
|
|
- `POST /generator/plugin/delivery-rehearsals` creates a local plan snapshot;
|
|
- `GET /generator/plugin/delivery-rehearsals` returns the 50 most recent summaries;
|
|
- `GET /generator/plugin/delivery-rehearsals/{rehearsalId}` verifies and returns one full report.
|
|
|
|
The delivery page can create a snapshot, inspect recent Runs, and open a report containing the two integrity fingerprints, frozen checks, and ordered scenarios. It deliberately exposes no rehearsal execution command.
|
|
|
|
## Boundaries
|
|
|
|
- Creating a Run writes only the control database rehearsal tables. The existing acceptance service may perform its configured read-only readiness probe, but no target DML is issued.
|
|
- The snapshot contains no JDBC URL, username, password, SQLState, or raw target exception.
|
|
- This phase does not reserve an environment, lock a Transition, or grant future execution authority. A later execution must repeat preflight and approval validation.
|
|
- Switching from `PLAN_ONLY` to an isolated MySQL rehearsal requires an explicit target authorization and a separate execution-state design with per-scenario receipts.
|
|
- No external MySQL instance was connected or modified while implementing this stage. Plaintext development credentials and TLS verification remain deferred by explicit user decision.
|