# GCS-IMPL-005 - Implementation Sequence

Spec ID      : GCS-IMPL-005
Title        : Implementation Sequence
Version      : v1.0
Status       : Settled
Owner        : Phil
Approver     : Phil
Settled      : 2026-07-08
Depends on   : GCS-REGISTER-001, GCS-OVERVIEW-001, GCS-IMPL-004, GCS-AUDIT-001, GCS-NAME-001, GCS-DATA-002, GCS-DATA-003, GCS-RUNTIME-001, GCS-TEST-001
Supersedes   : -

## 1. Purpose

This document defines the exact legal implementation order for Global Control
Structures. It does not start feature implementation. It turns GCS-IMPL-004
into an executable sequence with allowed paths, forbidden paths, input -> output
contracts, positive tests, negative tests, validation commands, exit gates,
dependencies, blockers, and remediation.

## 2. Current Audit

Current repository state after `python3 -m tools.check_contracts --check`:

- Contract gate: passing.
- Current phase: Phase 0D implementation-eligible; implementation not started.
- Runtime state: static research surface plus Phase 0B file-backed
  point-in-time storage skeleton.
- Present implementation surfaces: `index.html`, `build/`, `assets/*.js`,
  `assets/*.svg`, `contracts/*.md`, `conversations/`, `tools/check_contracts.py`,
  `ops/local_variables.example`, `.github/workflows/contract-check.yml`,
  `AGENTS.md`, `CLAUDE.md`, `app/__init__.py`, `app/raw_store/`,
  `app/normalization/`, `app/sources/fixtures/`, `tests/raw_store/`,
  `tests/normalization/`, and `tests/fixtures/`.
- Absent by current checkout: `app/persistence/`, `migrations/`,
  `tests/persistence/`, `api/`, `app/api/`, active Compose files, database
  code, ORM models, SQL files, live ingestion, queues, workers, schedulers,
  Redis, RabbitMQ, Celery, signal package code, entity-resolution code,
  analytics services, production prediction services, API routes, and
  production deployment config.

Primary legal workstream: product surface (`index.html`, `build/`, `assets/`).
Phase 0D physical persistence remains eligible but deferred. No active
database container, Compose file, API, queue, worker, scheduler, live client,
ingestion, entity-resolution, production signal package, analytics service, or
production prediction surface is legal until the matching contract and checker
gate opens that surface. Standalone SQL files remain blocked.

## 3. Non-Negotiable Order

1. Phase -1: contract governance gate.
2. Phase 0A: amend contracts and validator to allow only the point-in-time
   foundation slice.
3. Phase 0B: implement file-backed point-in-time storage skeleton with
   raw -> normalized round-trip tests and no live public data pulls.
4. Phase 0C: design and gate physical Postgres persistence before migrations.
5. Phase 0D: implement physical persistence only after DATA-003 and TEST-001
   name the exact tables, constraints, and migration checks.
6. Phase 1: monetary/fiscal input layer.
7. Phase 2: expenditure/capability input layer.
8. Phase 3: entity-resolution graph and independence audit.
9. Phase 4: corporate behavior and ownership layers.
10. Phase 5: governance layer: DEF 14A, N-PX, vote outcomes.
11. Phase 6: analytics, causality, engagement-channel inference.
12. Phase 7: bounded prediction and validation.
13. Runtime/API/queue/container/deployment activation only after the matching
    contract amendment and gate exists.

## 4. Phase Sequence

### Phase -1 - Contract Governance Gate

| Field | Requirement |
| --- | --- |
| Implementation objective | Prove the repository is contract-governed before implementation starts. |
| Governing contracts | GCS-REGISTER-001, GCS-OVERVIEW-001, GCS-NAME-001, GCS-NAME-002, GCS-TEST-001, GCS-AUDIT-001 |
| Allowed files/directories | `contracts/`, `tools/`, `.github/workflows/`, `ops/local_variables.example`, static source headers |
| Forbidden files/directories | `app/`, `api/`, `migrations/`, `ops/docker/compose.gcs_project.yml`, queue/broker/worker code |
| Input -> output contract | Current repo checkout -> passing contract gate and audit table. |
| Positive verification test | `python3 -m tools.check_contracts --check` prints `GCS_CONTRACT_CHECK_OK`. |
| Negative verification test | Add unregistered `contracts/GCS-*.md`; gate fails as unregistered. |
| Validation command | `python3 -m tools.check_contracts --check`; `git diff --check`. |
| Exit gate | Contract gate and whitespace gate pass. |
| Dependencies | None. |
| Blocker/remediation | If the gate fails, remediate the named contract/header/env/register violation before any implementation planning. |

### Phase 0A - Open the Point-In-Time Foundation Slice

| Field | Requirement |
| --- | --- |
| Implementation objective | Amend contracts and validator so Phase 0B may add only a minimal point-in-time storage skeleton. |
| Governing contracts | GCS-REGISTER-001, GCS-OVERVIEW-001, GCS-STACK-001, GCS-DATA-002, GCS-DATA-003, GCS-TEST-001, GCS-AUDIT-001 |
| Allowed files/directories | `contracts/GCS-OVERVIEW-001_Specification_Overview.md`, `contracts/GCS-STACK-001_Stack_Architecture_Contract.md`, `contracts/GCS-DATA-003_Persistence_Contract.md`, `contracts/GCS-TEST-001_Test_and_CI_Contract.md`, `contracts/GCS-AUDIT-001_Contract_Implementation_Audit.md`, `tools/check_contracts.py` |
| Forbidden files/directories | Feature code under `app/`; `api/`; `migrations/`; active Compose; queue/broker/runtime service code; live public data fetchers |
| Input -> output contract | Settled Phase 0 contracts -> amended Phase 0B allowlist for file-backed raw store, normalized record metadata, and tests. |
| Positive verification test | Gate allows only explicitly named Phase 0B paths after the amendment. |
| Negative verification test | Adding `app/signals/`, `api/`, `migrations/`, `queue_name`, or `container_name` still fails. |
| Validation command | `python3 -m tools.check_contracts --check`; `python3 -m tools.check_contracts --self-test`; `git diff --check`. |
| Exit gate | Audit table marks Phase 0B as implementation-eligible and the checker enforces the new allowlist. |
| Dependencies | Phase -1 exit. |
| Blocker/remediation | Current contracts block app/database code; remediate by amending only the narrow Phase 0B storage-skeleton allowance. |

### Phase 0B - File-Backed Point-In-Time Storage Skeleton

| Field | Requirement |
| --- | --- |
| Implementation objective | Build the smallest storage kernel that proves raw payload retention, normalized metadata, as-of discipline, idempotent re-run, and no lookahead leakage using fixed local fixtures only. |
| Governing contracts | GCS-DATA-002, GCS-DATA-003, GCS-STACK-001, GCS-SEC-001, GCS-TEST-001 |
| Allowed files/directories | `app/__init__.py`, `app/raw_store/`, `app/normalization/`, `app/sources/fixtures/`, `tests/raw_store/`, `tests/normalization/`, `tests/fixtures/`, validator updates needed to recognize those paths |
| Forbidden files/directories | `api/`, `app/api/`, `migrations/`, `app/signals/`, `app/entity_resolution/`, active containers, live HTTP clients, schedulers, queues, workers, Redis, RabbitMQ, Celery |
| Input -> output contract | Fixed local payload fixture + source metadata -> immutable raw payload digest + normalized record with `as_of_timestamp`, `fetch_timestamp`, `source_authority_tier`, source identifier, and normalization version. |
| Positive verification test | Same fixture ingested twice produces one raw payload identity and one deterministic normalized record. |
| Negative verification test | Missing `as_of_timestamp`, missing source authority tier, changed payload under same digest, or future-known timestamp is rejected. |
| Validation command | `python3 -m tools.check_contracts --check`; focused tests such as `python3 -m unittest discover -s tests/raw_store -v` and `python3 -m unittest discover -s tests/normalization -v`; `git diff --check`. |
| Exit gate | Raw -> normalized round trip passes; duplicate re-run writes no duplicate; no network calls; no DB/migration/API/queue surfaces exist. |
| Dependencies | Phase 0A exit. |
| Blocker/remediation | If tests need a DB, stop and move to Phase 0C design first; do not smuggle database behavior into file-backed storage. |

### Phase 0C - Physical Persistence Design Gate

| Field | Requirement |
| --- | --- |
| Implementation objective | Convert DATA-003 from high-level table families into an exact physical persistence inventory before migrations exist. |
| Governing contracts | GCS-DATA-003, GCS-NAME-001, GCS-SEC-001, GCS-TEST-001 |
| Allowed files/directories | `contracts/GCS-DATA-003_Persistence_Contract.md`, `contracts/GCS-AUDIT-001_Contract_Implementation_Audit.md`, `tools/check_contracts.py`, future design-only docs under `contracts/` |
| Forbidden files/directories | `migrations/`, ORM models, active database URLs, active Compose, live source ingestion |
| Input -> output contract | File-backed Phase 0B record model -> physical table/field/enum/constraint/index inventory with deterministic names. |
| Positive verification test | Checker proves every required table family has named fields, source authority, timestamp, digest, constraints, and planned test coverage. |
| Negative verification test | Anonymous constraint, ad-hoc enum text, missing `as_of_timestamp`, or missing raw payload digest fails. |
| Validation command | `python3 -m tools.check_contracts --check`; `git diff --check`. |
| Exit gate | DATA-003 names every table, enum, constraint pattern, migration safety class, and persistence test file required for Phase 0D. |
| Dependencies | Phase 0B exit. |
| Blocker/remediation | If physical persistence cannot be fully named, keep using file-backed skeleton and do not add migrations. |

### Phase 0D - Physical Persistence Implementation

| Field | Requirement |
| --- | --- |
| Implementation objective | Implement the Postgres-ready physical persistence layer after DATA-003 names it exactly. |
| Governing contracts | GCS-DATA-003, GCS-DEPLOY-002, GCS-TEST-001, GCS-SEC-001 |
| Allowed files/directories | `app/persistence/`, `migrations/NNNN_<snake_case>.py`, `tests/persistence/`, `tools/check_persistence_schema.py`, and `ops/local_variables.example` only if a future database URL variable is introduced |
| Forbidden files/directories | `api/`, `app/api/`, live source clients, queues/workers/schedulers, active Compose, database containers, standalone SQL files, production deployment config, entity-resolution modules, signal modules, analytics modules, prediction modules |
| Input -> output contract | Phase 0B fixture payload and normalized metadata record plus a contract-approved database connection -> persisted raw and normalized rows with deterministic constraints and point-in-time query behavior. |
| Positive verification test | Migrated schema accepts a valid raw + normalized round trip and point-in-time query. |
| Negative verification test | Migration drift, anonymous constraints, wrong enum storage, missing digest, missing timestamp, duplicate idempotency key, or lookahead query fails. |
| Validation command | `python3 -m tools.check_contracts --check`; `python3 -m tools.check_contracts --self-test`; `python3 -m unittest discover -s tests/persistence -v`; future persistence checker if added; `git diff --check`. |
| Exit gate | Persistence tests pass against the contracted database strategy and raw/normalized rows rebuild from fixtures. |
| Dependencies | Phase 0C exit; Phase 0D frame/checker amendment; local DB strategy either contract-approved without containers or GCS-DEPLOY-002 amended for container activation. |
| Blocker/remediation | Current DEPLOY-002 has no active Compose runtime; if Postgres requires containers, amend DEPLOY-002 before introducing Compose. |

### Phase 1 - Monetary/Fiscal Input Layer

| Field | Requirement |
| --- | --- |
| Implementation objective | Ingest the fast input clock: Fed/FRED, Treasury fiscal data, TreasuryDirect, and FOMC calendar data. |
| Governing contracts | GCS-DATA-002, GCS-DATA-003, GCS-SEC-001, GCS-TEST-001 |
| Allowed files/directories | `app/sources/monetary_fiscal/`, `app/normalization/monetary_fiscal/`, `tests/sources/monetary_fiscal/`, `tests/fixtures/monetary_fiscal/` |
| Forbidden files/directories | Governance/corporate source clients, analytics, predictions, API routes, queues, schedulers |
| Input -> output contract | Public Tier 1 monetary/fiscal fixture or fetched response -> point-in-time normalized monetary/fiscal record. |
| Positive verification test | Reconstruct aggregate balance sheet/TGA sample from fixtures and match source totals. |
| Negative verification test | Missing source authority tier, duplicate re-pull, unsupported clock, or live network call in unit tests fails. |
| Validation command | Contract check, source tests, no-network unit-test mode, `git diff --check`. |
| Exit gate | Historical monetary/fiscal fixture set round trips with native clock, as-of stamp, and no duplicates. |
| Dependencies | Phase 0D exit for durable persistence or an explicit Phase 1 file-backed allowance if persistence remains file-backed. |
| Blocker/remediation | Do not pull live APIs until rate-limit, user-agent, raw retention, and fixture-first tests are present. |

### Phase 2 - Expenditure/Capability Input Layer

| Field | Requirement |
| --- | --- |
| Implementation objective | Ingest USASpending obligations/assistance and capability-relevant recipient identifiers. |
| Governing contracts | GCS-DATA-002, GCS-DATA-003, GCS-SEC-001, GCS-TEST-001 |
| Allowed files/directories | `app/sources/expenditure_capability/`, `app/normalization/expenditure_capability/`, `tests/sources/expenditure_capability/`, `tests/fixtures/expenditure_capability/` |
| Forbidden files/directories | Ownership/governance ingestion, analytics, predictions, API routes, queues |
| Input -> output contract | USASpending fixture -> normalized obligation/assistance record with recipient identifiers and obligation date. |
| Positive verification test | Reproduce known annual obligation total from fixture subset and attach stable recipient IDs. |
| Negative verification test | Missing UEI/recipient ID, missing obligation date, Tier 3-only source, or duplicate pull fails. |
| Validation command | Contract check, expenditure source tests, `git diff --check`. |
| Exit gate | Expenditure records are point-in-time and ready to feed the identifier crosswalk. |
| Dependencies | Phase 1 exit. |
| Blocker/remediation | If recipient identity cannot be stabilized, stop before Phase 3 and improve normalization/crosswalk prep. |

### Phase 3 - Entity-Resolution Graph and Independence Audit

| Field | Requirement |
| --- | --- |
| Implementation objective | Bind sources into one graph and prove independence-adjusted holder collapse. |
| Governing contracts | GCS-DATA-002, GCS-DATA-003, GCS-NAME-002, GCS-TEST-001 |
| Allowed files/directories | `app/entity_resolution/`, `tests/entity_resolution/`, fixtures for CIK/ticker/CUSIP/LEI/UEI and manages/sub-advises edges |
| Forbidden files/directories | Signal inference, predictions, public API, queues |
| Input -> output contract | Effective-dated identifiers + ownership/manager/fund edges -> entity nodes, edges, identifier crosswalk, adjusted holder blocs. |
| Positive verification test | Known issuer resolves parent, holders, sub-advisor collapse, and government disbursement edge. |
| Negative verification test | Counting a sub-advised fund and advisor as two independent bearings fails. |
| Validation command | Contract check, entity-resolution tests, `git diff --check`. |
| Exit gate | Independence audit produces adjusted holder count and bloc size for fixture issuers. |
| Dependencies | Phase 1 and Phase 2 exits. |
| Blocker/remediation | Do not proceed to ownership analytics until crosswalk effective dates and non-independence collapse are proven. |

### Phase 4 - Corporate Behavior and Ownership Layers

| Field | Requirement |
| --- | --- |
| Implementation objective | Ingest SEC 13F, 13D/13G, Form 4, and 8-K records and bind them to the graph. |
| Governing contracts | GCS-DATA-002, GCS-DATA-003, GCS-SEC-001, GCS-TEST-001 |
| Allowed files/directories | `app/sources/sec_behavior_ownership/`, `app/normalization/sec_behavior_ownership/`, `tests/sources/sec_behavior_ownership/` |
| Forbidden files/directories | Governance-vote parsing, engagement inference, predictions, queues |
| Input -> output contract | SEC fixture payload -> point-in-time holder/transaction/material-event records linked to entity graph. |
| Positive verification test | Reproduce top-holder percentages for fixture issuers and split adjusted bloc vs tail. |
| Negative verification test | Treating 13F as event tempo, missing filing latency/as-of, or unlinked CIK fails. |
| Validation command | Contract check, SEC ownership tests, `git diff --check`. |
| Exit gate | Ownership topology is point-in-time and independence-adjusted across FIC/MIC/TIC fixture issuers. |
| Dependencies | Phase 3 exit. |
| Blocker/remediation | If CIK/corporate events are unresolved, return to Phase 3 instead of patching ownership logic locally. |

### Phase 5 - Governance Layer

| Field | Requirement |
| --- | --- |
| Implementation objective | Ingest DEF 14A, DEFA14A proposal lifecycle, N-PX fund votes, vote outcomes, and proxy advisor policy metadata. |
| Governing contracts | GCS-DATA-002, GCS-DATA-003, GCS-SEC-001, GCS-TEST-001 |
| Allowed files/directories | `app/sources/governance/`, `app/normalization/governance/`, `tests/sources/governance/`, governance fixtures |
| Forbidden files/directories | Engagement-channel inference, predictions, public API, queues |
| Input -> output contract | Governance fixtures -> ballot, proposal lifecycle, fund vote, vote outcome, record date, and advisor-policy records joined to graph. |
| Positive verification test | Reconstruct full ballot and fund-by-fund vote for a fixture proxy season. |
| Negative verification test | N-PX vote not joined to ballot item, missing record date, or pooled with-management rate without baseline context fails. |
| Validation command | Contract check, governance tests, `git diff --check`. |
| Exit gate | Governance layer can answer how named funds voted on fixture ballot items. |
| Dependencies | Phase 4 exit. |
| Blocker/remediation | Do not implement engagement inference until ballot/vote/outcome alignment is proven. |

### Phase 6 - Analytics and Engagement-Channel Inference

| Field | Requirement |
| --- | --- |
| Implementation objective | Produce concentration, flow-causality, and engagement-channel estimates from validated point-in-time records. |
| Governing contracts | GCS-SIG-003, GCS-SYS-001, GCS-DATA-002, GCS-TEST-001 |
| Allowed files/directories | `app/signals/`, `tests/signals/`, fixture analytical datasets derived from prior phases |
| Forbidden files/directories | Prediction service, public API, queues, unvalidated live data outputs |
| Input -> output contract | Point-in-time records + graph + governance baseline -> redistribution vectors, concentration outputs, causal edge reports, engagement-channel estimates. |
| Positive verification test | Fixture signal reports adjusted bloc/dispersed tail/inert retail separately and computes residual signatures against baseline. |
| Negative verification test | Correlation-only causal claim, in-sample-only signal, non-independent bearing, or manufactured engagement content fails. |
| Validation command | Contract check, signal tests, out-of-sample validation tests where applicable, `git diff --check`. |
| Exit gate | Every analytical output cites primary-record bearings and named assumptions; no prediction ships yet. |
| Dependencies | Phase 5 exit. |
| Blocker/remediation | If point-in-time or independence metadata is missing, return to data/entity phases. |

### Phase 7 - Bounded Prediction and Validation

| Field | Requirement |
| --- | --- |
| Implementation objective | Produce short-term recorded-layer forecasts with confidence intervals, decay clauses, regime tags, and out-of-sample records. |
| Governing contracts | GCS-SIG-003, GCS-SYS-001, GCS-DATA-002, GCS-TEST-001 |
| Allowed files/directories | `app/prediction/`, `tests/prediction/`, prediction validation fixtures |
| Forbidden files/directories | Public prediction API, queues, unmanaged deployment, unvalidated model outputs |
| Input -> output contract | Point-in-time training window + held-out validation window -> prediction record with CI, decay clause, regime tag, and observed outcome. |
| Positive verification test | Held-out governance or flow-rotation fixture demonstrates out-of-sample skill using only knowable-as-of records. |
| Negative verification test | In-sample-only fit, missing confidence interval, missing decay clause, missing regime tag, or lookahead leakage fails. |
| Validation command | Contract check, prediction tests, point-in-time leakage tests, `git diff --check`. |
| Exit gate | Prediction output has passing OOS record and any decayed/failed signal is removed or demoted. |
| Dependencies | Phase 6 exit. |
| Blocker/remediation | If no signal survives OOS validation, ship no prediction and report the failed signal as rejected. |

## 5. Deferred Runtime Activation

These implementation surfaces remain blocked until their own amendments exist:

| Surface | Current status | Required amendment before implementation |
| --- | --- | --- |
| API routes | Blocked | GCS-API-001 endpoint inventory, DTOs, idempotency, positive/negative route tests |
| Queues/workers/schedulers | Blocked | Replace or amend GCS-RUNTIME-001 with logical queues, broker decision, durable outbox/inbox, retry/dead-letter tests |
| Redis/RabbitMQ/Celery | Blocked | Runtime + deployment + container amendments; source-of-truth remains durable store |
| Active Docker Compose | Blocked | GCS-DEPLOY-002 active compose path, service set, native-arch rule, static and runtime container checks |
| Production deployment | Blocked | GCS-DEPLOY-001 managed runtime tuple, secrets, healthcheck, rollback, CI conformance report |
| Public UI/API for data outputs | Blocked | API and security contracts plus output leakage gates |

## 6. Immediate Next Task

The next task is **product surface deepening** (primary workstream):

```text
Deepen index.html + build/ immersive instrument
(topology, lineage, concentration/φ math, bounded next moves with decay).
Keep fixture pedagogy honest; stamp provenance; do not invent off-record content.
```

Allowed product paths without further phase gates: `index.html`, `build/`,
`assets/`, and product notes under `conversations/`. Method-rail contracts
(SYS, SIG, SEC) govern claim language on that surface.

Phase 0D physical persistence is **deferred**. When deliberately resumed:

```text
Implement only the physical persistence surface opened by GCS-DATA-003,
GCS-TEST-001, GCS-STACK-001, and tools/check_contracts.py.
```

Phase 0D may use only `app/persistence/`,
`migrations/NNNN_<snake_case>.py`, `tests/persistence/`, optional
`tools/check_persistence_schema.py`, and `ops/local_variables.example` only if
a future database URL variable is introduced and documented.

If Phase 0D requires a database container or active Compose runtime, stop and
derive a GCS-DEPLOY-002 boundary frame before introducing those files.

No API route, queue, worker, scheduler, live source client, ingestion path,
entity-resolution module, production prediction service, production deployment
config, active Compose file, database container, or standalone SQL file may be
introduced without the matching contract amendment.