zyr/FT546MWS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: clarify shadow warehouse authority

Browse Source
This commit is contained in:
zgw
2026-09-03 10:28:43 +08:00
parent e0eb507d7e
commit 8f5dea31ed
1 changed files with 4 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/superpowers/specs/2026-09-03-ft546wms-shadow-v3-design.md
View File

@@ -65,7 +65,7 @@ The Legacy completion wait is bounded by `FORTUCKY_SHADOW_TIMEOUT_SECONDS`, whic
### Common admission flow
1. At the existing pre-Legacy integration point, atomically enter Legacy activity, advance the epoch, and attempt to lease the current snapshot.
2. If shadow is disabled, the snapshot is not `READY`, it is stale, the warehouse is wrong, or another observation owns it, return a no-op token immediately. Skip counts are updated in fixed-size in-memory counters and flushed by the worker; the caller performs no database or synchronous log write.
2. If shadow is disabled, the snapshot is not `READY`, it is stale, the published snapshot warehouse is wrong, or another observation owns it, return a no-op token immediately. Skip counts are updated in fixed-size in-memory counters and flushed by the worker; the caller performs no database or synchronous log write.
3. If admitted, copy only the immutable request identifiers already in memory and submit the worker task.
4. Execute the original Legacy procedure immediately, regardless of the shadow admission result.
5. In a `finally` block, complete the token with either the Legacy outcome or failure marker and exit Legacy activity. Completion never waits for the worker.
@@ -105,7 +105,7 @@ The default maximum age is 60 seconds and accepts values from 5 through 300 seco
## Warehouse normalization
`FORTUCKY_ALGORITHM_WAREHOUSE_ID=01` is authoritative for this field test. A raw request value such as `W02` is retained in diagnostics but cannot override the configured algorithm warehouse.
`FORTUCKY_ALGORITHM_WAREHOUSE_ID=01` is authoritative for this field test. A raw request value such as `W02` is retained in diagnostics but cannot override the configured algorithm warehouse and does not by itself skip the observation. Planning still uses the published `01` snapshot. An observation is skipped only when the published snapshot warehouse does not match the configured warehouse after normalization.
Purely numeric warehouse identifiers are compared after removing leading zeroes, so `1` and `01` are equivalent. Non-numeric identifiers are compared as exact trimmed values; `W02` is not equal to `01`.
@@ -116,7 +116,7 @@ Every shadow-only failure has one of these outcomes:
- `SKIP_NOT_READY`: startup or recovery has no published snapshot.
- `SKIP_BUSY`: another observation or refresh owns the coordinator.
- `SKIP_STALE`: the published snapshot exceeded its maximum age.
- `SKIP_WAREHOUSE`: request diagnostics do not match the configured warehouse; Legacy still runs normally.
- `SKIP_WAREHOUSE`: the published snapshot warehouse does not match the configured warehouse; Legacy still runs normally.
- `SKIP_CONCURRENT`: Legacy activity changed during refresh or invalidated the sample window.
- `ERROR_PLAN` or `ERROR_COMPARE`: the current observation is invalid, its consumed generation cannot return to `READY`, the lease is released in `finally`, and asynchronous refresh begins.
- `ERROR_REFRESH`: the candidate generation is rolled back; after bounded retries the coordinator becomes `UNAVAILABLE` and retains the previous generation for diagnosis only.
@@ -167,7 +167,7 @@ Shadow v3 is not sufficient by itself to authorize formal cutover. A new field r
- inventory parity has zero missing/extra warehouse `01` rows and exact equality for space, product, project, quantity, lock/reservation, availability, lane, and occupancy fields included by the export;
- at least 100 valid inbound and 100 valid outbound comparisons, excluding explicitly skipped requests;
- every valid comparison has snapshot generation/time, immutable input diagnostics, candidate counts, and both outcomes;
- zero valid sample has a post-Legacy snapshot, unexplained stock-not-found, unexplained waiting-channel result, or cross-warehouse input;
- zero valid sample has a post-Legacy snapshot, unexplained stock-not-found, unexplained waiting-channel result, or uses a published snapshot from a warehouse other than configured `01`;
- the export records zero Legacy request blocked by an `alg.*` session; compared with the approved Legacy-only baseline under the same shift/load class, Legacy p95 latency increases by no more than 5% and p99 by no more than 10%; caller-side shadow admission p99 remains at or below one millisecond;
- differing recommended locations are reviewed as algorithm choices rather than treated as automatic failures.