# tipoc-tv Critical Path Map

This map binds critical implementation paths to the repo-contained design
capsule. A future change that touches one of these paths must first load
`AGENTS.md`, `docs/DESIGN-CAPSULE.md`, this file, and the local path-scoped
`AGENTS.md`.

## Pre-Action Gate

Before editing a critical path, state:

1. the critical path entry being modified
2. the design-capsule sections loaded
3. the local `AGENTS.md` files loaded
4. the invariant the change is allowed to modify
5. the already validated behavior that must remain unchanged
6. the tests and guards that will prove alignment

If the intended change contradicts this map or the design capsule, stop and
reopen the owning design or update the capsule and map through an accepted
design-change path. Code is not allowed to silently become the new design.

## core/execution

Owned files:

1. `core/execution/executor.go`
2. `core/execution/live_prepare.go`
3. `core/execution/live_run.go`
4. `core/execution/live.go`
5. `core/execution/executor_test.go`

Design sections:

1. Public Workflow
2. Prepare Data Generation
3. Source Publication And Import
4. Runtime And Closeout
5. Workload Profiles And Hotspots
6. Forbidden Shortcuts

Invariants:

1. Public stages remain exactly `init -> prepare -> run -> cleanup`.
2. Formal S3 prepare publishes generated source objects directly to object
   storage without complete local CSV staging.
3. Prepare operation splitting is shared trunk behavior. Explicit generate-only
   prepare materializes source artifacts without TiDB side effects, and later
   import/add-index prepare reuses existing current-attempt source artifacts
   instead of regenerating data.
4. Workload adapters provide workload-specific catalog, source identity, source
   generation, schema projection, runtime semantics, and proof; schema
   execution, import, ADD INDEX, statistics validation, completion validation,
   checkpointing, receipts, and manifest transitions stay in shared execution
   helpers.
5. Source-object layout is owned by the shared objectstore/import planner. The
   current accepted layout is a TiDB-readable wildcard source location per
   table; future flat-root or table-directory layouts must be added there and
   recorded in receipts rather than implemented inside workload adapters.
6. Runtime executes a duration-based pressure window with real statement
   execution evidence, not a single synthetic pass.
7. The CE deck maps one token to one CE transaction family. Trade-Result and
   Market-Feed are byproducts of Trade-Order only.
8. Run evidence includes 33-table prepare-load summary, throughput, temporal
   closeout, worker summaries, and zero blocked statements for a pass.
9. Workload profile selection must bias runtime lineage before SQL generation;
   SQL builders must not hardcode hotspot literals.
10. Workload profile evidence must flow from manifest into live runtime receipt,
   run receipt, and global closeout so a hotspot run is reproducible.

Forbidden bypasses:

1. readiness, smoke, fixed small counts, or customer-count override pass paths
2. review SQL or `SELECT COUNT(*)` runtime fallbacks
3. fixed all-family bundle execution per pressure iteration
4. old attempt evidence as a current pass after guards change
5. hotspot simulation implemented as SQL literal patching
6. workload-specific prepare drivers that bind import or add-index execution
   back to source generation after TPC-E has already established split
   prepare stages
7. workload-specific source layout rules that bypass the shared objectstore and
   import planner

Required verification:

1. `go test ./core/execution`
2. `python3 tools/critical_path_guard.py`
3. `python3 tools/go_lint_guard.py`
4. `python3 ../tools/tiforge_execution_guard.py --skip-all-go-tests` from the
   outer project when only governance or focused execution code changed

## industries/securities

Owned files:

1. `industries/securities/tpce/*.go`
2. `industries/securities/schema/*.go`
3. `industries/securities/transactions/*.go`
4. `industries/securities/queries/*.go`
5. `industries/securities/validators/*.go`
6. package-level tests under `industries/securities/**`

Design sections:

1. TPC-E Securities Model
2. CE Transaction Mix
3. Runtime And Closeout
4. Workload Profiles And Hotspots

Invariants:

1. The TPC-E catalog remains 33 tables.
2. `trade_request` remains the explicit empty prepare table until the frozen
   design changes.
3. The transaction catalog remains the statement source for all 126 runtime
   statement ids.
4. Validators and query evidence must check securities semantics, not generic
   row-count substitutes.
5. Canonical and hotspot workload profiles must remain explainable through
   lineage inputs, manifest parameters, and observed distribution evidence.

Forbidden bypasses:

1. shrinking back to an old reduced table projection
2. hiding unimplemented statement families behind generic SQL
3. changing transaction family ownership without updating actor routing and
   tests
4. embedding hotspot constants inside query, validator, or SQL-builder code

Required verification:

1. `go test ./industries/securities/...`
2. `go test ./projections/tidb/runtime`
3. `python3 tools/critical_path_guard.py`

## industries/securities/bootstrap

Owned files:

1. `industries/securities/bootstrap/materializer.go`
2. `industries/securities/bootstrap/materializer_test.go`

Design sections:

1. Prepare Data Generation
2. Source Publication And Import

Invariants:

1. LCG64-based generation remains deterministic by ownership range and stream
   coordinates.
2. CSV source objects roll by configured target bytes while preserving complete
   CSV rows.
3. S3-configured formal prepare streams source objects directly to the object
   store through the object sink.
4. The materializer never pads files with meaningless rows just to meet an
   object target.

Forbidden bypasses:

1. complete local CSV staging before S3 upload for formal object-store prepare
2. large complete-object in-memory single PUT behavior for formal S3 objects
3. row identity that depends on worker scheduling order

Required verification:

1. `go test ./industries/securities/bootstrap`
2. `go test ./internal/csvpipe`
3. `go test ./projections/tidb/objectstore`
4. `python3 tools/critical_path_guard.py`

## industries/securities/runtime

Owned files:

1. `industries/securities/runtime/runtime.go`
2. `industries/securities/runtime/routing.go`
3. `industries/securities/runtime/state_machine.go`
4. `industries/securities/runtime/timeline.go`
5. `industries/securities/runtime/*_test.go`

Design sections:

1. TPC-E Securities Model
2. CE Transaction Mix
3. Runtime And Closeout
4. Workload Profiles And Hotspots

Invariants:

1. Runtime actor ownership remains CE, BrokerageHouse/SUT, MEE, DM, and
   TradeCleanup over one global securities world.
2. MEE, DM, cleanup, deck ranges, and trade id leases remain horizontally
   partitionable.
3. Timeline validation keeps causal ordering for CE, Trade-Order, SendToMarket,
   MEE, Market-Feed, DM, and TradeCleanup.
4. TradeCleanup remains a closeout boundary after a full DM rotation.
5. Hotspot profiles may bias entity selection, but they must not bypass CE deck,
   MEE, DM, cleanup, timeline validation, or horizontal ownership.

Forbidden bypasses:

1. random SQL execution
2. full family bundle execution for every CE token
3. per-worker independent securities worlds
4. accepting missing timeline evidence as pass
5. hotspot behavior that changes SQL literals without workload-profile lineage

Required verification:

1. `go test ./industries/securities/runtime`
2. `go test ./core/runtime`
3. `go test ./core/execution -run Runtime`
4. `python3 tools/critical_path_guard.py`

## projections/tidb

Owned files:

1. `projections/tidb/schema/*.go`
2. `projections/tidb/importer/*.go`
3. `projections/tidb/ddl/*.go`
4. `projections/tidb/stats/*.go`
5. `projections/tidb/br/*.go`
6. `projections/tidb/objectstore/*.go`
7. `projections/tidb/runtime/*.go`
8. `projections/tidb/live/*.go`

Design sections:

1. Source Publication And Import
2. Index, Statistics, And BR
3. Runtime And Closeout
4. Workload Profiles And Hotspots

Invariants:

1. TiDB remains the system under test and the source of runtime truth.
2. Imports use `IMPORT INTO` file sources and Global Sort when configured.
3. Inline runtime indexes stay in `CREATE TABLE`; prepare-end supplemental
   `ADD INDEX` remains limited to the frozen three indexes.
4. The base Global Sort workspace URI is an internal import-executor binding;
   table import plans derive one table-scoped `global_sort_uri` and use it in
   `CLOUD_STORAGE_URI` and table plan digests.
5. Statistics validation and BR boundary evidence remain mandatory prepare-end
   artifacts for live TiDB prepare, and BR backup/restore commands must carry
   the selected TiUP component when the target cluster requires a version-bound
   BR binary.
6. Runtime SQL builders must either produce the exact securities statement or
   block explicitly. They must not substitute review SQL.
7. Runtime SQL builders must consume lineage inputs from the workload profile
   and must not own hotspot-selection policy.
8. SQL context helpers may render explicit lineage fields, but they must not
   choose hot sets, skew functions, or profile seeds.

Forbidden bypasses:

1. `LOAD DATA`, `INSERT`, `INSERT ... SELECT`, stage-table merge, or
   `CREATE TABLE AS SELECT` prepare loading
2. `IMPORT INTO ... FROM SELECT`
3. generic table-count or placeholder runtime SQL
4. weakening stats or BR evidence to optional pass evidence
5. hardcoded hotspot literal values inside SQL builders

Required verification:

1. `go test ./projections/tidb/...`
2. `go test ./core/execution`
3. `python3 tools/critical_path_guard.py`
4. `python3 tools/go_lint_guard.py`