# GCS-STACK-001 - Stack Architecture Contract

Spec ID      : GCS-STACK-001
Title        : Stack Architecture
Version      : v1.0
Status       : Settled
Owner        : Phil
Approver     : Phil
Settled      : 2026-07-08
Depends on   : GCS-SYS-001, GCS-NAME-001, GCS-NAME-002
Supersedes   : -

## 1. Current Stack

The current stack is intentionally small and **product-first**:

- Static HTML study page (`index.html`).
- Flagship interactive instrument (`build/`).
- Browser-only JavaScript figures (`assets/*.js`).
- Static SVG assets (`assets/*.svg`).
- Product charter and provenance notes (`conversations/`).
- Markdown contracts (method rails + engineering rails).
- Python static validator.
- CI workflow that runs the validator.
- Phase 0B file-backed storage skeleton (present; not the product surface).

Before Phase 0D there is no app server, API server, database, migration
system, active container runtime, worker, scheduler, broker, or queue. Phase 0A
opened only the file-backed Phase 0B storage-skeleton paths named below.
Phase 0D may open only Postgres-ready persistence implementation code,
Python migration files, persistence tests, and optional persistence validation
tooling after the GCS-DATA-003 physical inventory and GCS-TEST-001 checker
gate are amended. Phase 0D still does not open an app server, API server,
active database container, worker, scheduler, broker, queue, live source
client, analytics module, or prediction module.

## 2. Future Stack Boundary

When implementation begins, the first allowed runtime stack is:

| Layer | Contract-owned shape |
| --- | --- |
| Language | Python 3 for validation and Phase 0B storage-skeleton code |
| Data store | No database in Phase 0B; Postgres remains deferred until DATA-003 physical design and migration gates are amended |
| Raw payloads | Filesystem-backed raw store with immutable digests in Phase 0B; object storage may be introduced only by later amendment |
| Static/public surface | HTML/CSS/JS study + `build/` instrument; future web shell governed by GCS-API-001 only if a server transport is introduced |
| Graph model | Relational graph tables first; no separate graph database until DATA amendment |
| Async | None until GCS-RUNTIME-001 is amended |

## 3. Module Boundaries

Phase 0B may introduce only these application and test paths:

| Path | Owner | Permitted responsibility |
| --- | --- | --- |
| `app/__init__.py` | GCS-STACK-001 | Importable package marker with contract header only |
| `app/raw_store/` | GCS-DATA-003 | File-backed raw payload digest and immutable local fixture storage |
| `app/normalization/` | GCS-DATA-002 | Fixture-only normalized metadata records |
| `app/sources/fixtures/` | GCS-DATA-002 / GCS-SEC-001 | Fixed local fixture payloads and metadata only; no live clients |
| `tests/raw_store/` | GCS-TEST-001 | Raw-store boundary tests |
| `tests/normalization/` | GCS-TEST-001 | Normalization boundary tests |
| `tests/fixtures/` | GCS-TEST-001 | Test-only fixed payload fixtures |
| `app/persistence/` | GCS-DATA-003 | Phase 0D Postgres-ready persistence adapters, schema inspection helpers, raw/source-record write paths, and point-in-time query helpers |
| `migrations/NNNN_<snake_case>.py` | GCS-DATA-003 | Phase 0D Python migration files creating only the contracted physical persistence inventory |
| `tests/persistence/` | GCS-TEST-001 | Phase 0D persistence boundary tests for schema, fixture round trip, point-in-time queries, and idempotency |
| `tools/check_persistence_schema.py` | GCS-TEST-001 / GCS-DATA-003 | Optional Phase 0D persistence schema validator |

Later application modules must live under contract-owned package paths:

| Path | Owner | Permitted responsibility |
| --- | --- | --- |
| `app/sources/` | GCS-DATA-002 | Public source clients and fetch scheduling |
| `app/raw_store/` | GCS-DATA-003 | Raw payload storage and digesting |
| `app/normalization/` | GCS-DATA-002 | Re-runnable source normalization |
| `app/entity_resolution/` | GCS-DATA-002 | Identifier crosswalk and independence audit |
| `app/signals/` | GCS-SIG-003 | Concentration, causality, and engagement inference |
| `app/api/` | GCS-API-001 | Future transport only, no business truth |
| `app/security/` | GCS-SEC-001 | Secret/source/egress controls |

No future module is complete until it has a contract header and a mirrored
test path.

## 4. External Boundaries

External public data services are boundaries. Tests may use fakes for public
data services, but GCS code must not mock its own modules to make tests pass.

Current external boundary (browser-only; no `app/` live clients):

- `assets/scale-figure.js` may fetch World Bank public indicator data in the
  browser and falls back to embedded stamped data if fetch fails.
- `assets/live_public_sources.js` may fetch, in the browser only:
  - Treasury FiscalData Debt to the Penny
  - FRED public `fredgraph.csv` for WALCL (Fed total assets; H.4.1 proxy)
  - FRED public `fredgraph.csv` for RRPONTSYD (overnight reverse repo)
  - FiscalData Monthly Treasury Statement Table 9 line 320 (Net Interest)
  - FiscalData `auctions_query` primary-dealer accepted/tendered fields
  - USASpending search endpoints for F-35 and CHIPS keyword obligations
  - SEC EDGAR 13F-HR information tables for named managers’ LMT CUSIP rows
    (browser CORS often fails; stamped EDGAR extracts are required fallbacks)
  and must fall back to embedded stamped values if fetch or CORS fails.
  It may stamp GAO F-35 lifecycle figures from cited GAO reports (no GAO API)
  and assemble hero verticals (F-35 debt→lifecycle→13F; CHIPS debt→awards).
- `assets/flow_regime.js` may implement a browser-only Flow Regime Markov
  model (discrete plumbing states, embedded transition matrix estimated from
  public RRP history, 7/14-day occupancy forecasts with entropy and decay).
  It may read `window.gcsLivePublic` and tag deals with regime favorability.
  This is pedagogical short-horizon forecasting under GCS-SIG-003, not a
  production `app/signals/` package and not an oracle.
- `build/index.html` may consume those browser fetches and the regime model via
  `window.gcsLivePublic` / `window.gcsFlowRegime` / `window.gcsDealFixturePack`
  patches. This is not Phase-1 ingestion, not an `app/sources/` client, and not
  a concordance claim by itself.

Future external boundaries (server/app clients still require phase opening):

- SEC EDGAR as an application source client.
- Broader FRED / Federal Reserve application ingestion.
- Broader Treasury Fiscal Data / TreasuryDirect application ingestion.
- Broader USASpending application ingestion.
- ISS / Glass Lewis published policy documents where legally available.

## 5. Validation

Positive verification: `python3 -m tools.check_contracts --check` confirms
that only Phase 0B allowlisted implementation paths exist.

Negative verification: adding `api/`, `app/api/`, invalid migration names,
standalone SQL files, `app/signals/`, `app/entity_resolution/`,
`app/prediction/`, active Compose, live HTTP clients, or queue tokens without
the matching contract amendment fails the gate.