`VIENNA-EXECUTOR.md`

97 lines

# Vienna executor local increment — TK-11300

**Production transport is disabled.** `designer-laboratory-sandbox.myshopify.com`
is the production store despite its name. This code is an actual CLI manifest
consumer and a local, file-backed operational rehearsal. It cannot perform live
inventory recovery. TK-11299 retains authoritative paginated acquisition, actual
shop identity, manifest review, token scope verification and explicit live approval.
No synthetic fixture shop or catalog ID is evidence of a live identity.

`apply-fix.mjs` no longer reads secrets or freshly enumerates products. Historical
`--all`, numeric `--canary`, and restore-map rollback commands fail closed. The
old token wrapper must not be used; live transport is absent, rather than hidden
behind an environment switch. The fixed domain and separate `--expected-store-id`
are validated against the manifest before the adapter is loaded, then against the
adapter's own shop result. There are no catalog or price mutations.

All modes except help require `--manifest FILE --expected-sha256 HASH
--expected-store-id SHOP_GID`. The SHA256 must come from the independent review
of the exact bytes; do not compute a fresh hash of unreviewed input as approval.
`--plan` and its `--enumerate` alias only read the manifest and print JSON. They
refuse adapter/journal options and create no files. Local execution additionally
requires `--offline-state FILE --journal FILE`. Resuming either original mode, or
`--rollback`, requires `--journal-sha256 HASH` from a separately trusted checkpoint.
Never use historical restore maps as journals.

Manifest v1 has exactly `version`, `scope`, `store`, `createdAt`, `expiresAt`,
`records` and `canary`. `scope` is `{vendor:"Phillipe Romano",line:"Vienna"}`.
Every record pins product, variant, inventory item and location GIDs plus the
product/variant preconditions, positive original `onHand` and `target:0`. Every
record must be a non-sample, zero-price, tracked DENY variant in the frozen line.
Expiry and maximum age are 24 hours, with ISO UTC timestamps and no future issue
date. `canary` contains explicit `inventoryItemId@locationId` keys; every frozen
location of each selected product must be included. The test canary deliberately
selects the third record to prove this is not a first-N approximation.

Hashes are operator trust anchors for exact bytes. Neither a manifest hash nor a
journal checkpoint establishes authoritative catalog completeness, arbitrary
journal provenance, or legal operational authorization. Review and transport
adapter integration remain separate. Structurally valid fabricated history with
a newly trusted checkpoint cannot be distinguished from operator-approved input.

Execution compares the full exact record before each compare-and-set write,
fsyncs intent before the adapter call, appends/fsyncs only confirmed successes,
then re-reads the exact identity and quantity before appending verification.
Confirmed rejections are recorded separately and can be retried after another
precondition comparison. Successfully verified mutations are only re-read on
resume; never repeated. Rollback selects confirmed successful records in that
journal, including successful locations from a partially failed product. Rollback
uses the same intent/result/post-read protocol. Once rollback begins, apply
cannot reopen a rolled-back run.

An exception or unrecognized result after intent is ambiguous. Missing success
never proves failure: retry and rollback block before adapter initialization.
There is intentionally no automatic reconciliation or force flag. A confirmed
success with interrupted verification can only advance after an exact read; it
cannot authorize a duplicate mutation. A crashed lock also blocks invocation;
it must be independently reviewed alongside the journal before any later work.
Ordinary completed invocation releases its own lock. Checkpoints are rechecked
under the exclusive journal lock to prevent a concurrent stale replay. A second
lock covers the shared fixture state for the entire CLI journey, so supported
competing CLI writers with different journals cannot race their compare/write.
Both locks release only after their own successful acquisition. Abandoned locks
remain conservative blockers after an actual process crash.

The adapter reloads persisted state for every shop/read/set operation, rechecks
the pinned store each time, and rechecks all record preconditions immediately
before mutation. Reads are nonmutating and never persist an earlier snapshot.
Direct unsynchronized file edits are test-injected drift, not supported writers;
the separate live adapter must supply a real service-side compare-and-set.

Journal parsing validates the chain, sequence, schema, manifest/store binding,
frozen selection, exact quantities and valid per-record state transitions. It
rejects truncated, malformed, unbound or injected histories before the adapter.
All data reads reject symlinks/hardlinks. Fixture state replacement uses fsynced
exclusive temporary files, identity checks, atomic rename and directory fsync.
Failed replacement retains its temporary file and prior durable fixture state.

## Verification and retained evidence

Run `node --test test/cli-preflight.test.mjs test/vienna-executor.test.mjs`.
Set `VIENNA_EVIDENCE_DIR` to an existing local evidence directory to retain each
fixture, manifest, journal, state and child CLI output there. Test time is fixed
by the deny-by-default process preload; the application has no clock override.
The guard denies canonical secrets, network and child processes and permits only
specified fixture files. Calibration deliberately hits real protected entry
points and proves denial. No real credentials, network or inventory are used.

The former 42-check CLI proof remains in git at source commit
`7fb358ca8948290915678dd2c34f83a02d5a0532` and `verification/cli-preflight-e2e-proof-7fb358c.json`.
Legacy write-mode test assertions now require manifest rejection rather than
reaching runtime initialization. The current canonical proof is `verification/e2e-proof.json`, with a detailed
`verification/vienna-e2e-proof.json` sibling. The provisional87-test proof at
commit7645583 predates an independently reproduced adapter stale-cache defect;
the corrected91-test proof includes inter-operation drift and actual competing
CLI subprocesses. That provisional claim is superseded, not accepted as final.
All fixture directories and failed-run logs are retained; no cleanup is required.