# GCS-OVERVIEW-001 - Specification Overview

Spec ID      : GCS-OVERVIEW-001
Title        : Specification Overview
Version      : v1.0
Status       : Settled
Owner        : Phil
Approver     : Phil
Settled      : 2026-07-08
Depends on   : GCS-REGISTER-001, GCS-SYS-001, GCS-NAME-001, GCS-TEST-001
Supersedes   : -

## 1. Purpose

This overview explains the contract stack in build order. It is not a looser
version of the contracts. If it conflicts with a contract artifact, the
registered contract artifact wins.

## 2. Current Runtime Truth

The current repository is a **product-first** static research surface with
contract rails:

- `index.html` renders the immersive GCS public study page.
- `build/` hosts the flagship interactive instrument (topology, lineage, math
  lab, bounded next-move modes).
- `assets/*.js` renders browser-only figures (scale series, round-trip circuit).
- `assets/*.svg` stores static visual evidence and equations.
- `conversations/03-product-charter.md` records the product-first priority.
- `contracts/*.md` stores the binding contract stack (method rails + engineering
  rails).
- `tools/check_contracts.py` enforces static conformance.
- Phase 0B added the file-backed point-in-time storage skeleton under the
  paths named in GCS-IMPL-005 and enforced by `tools/check_contracts.py`.
- Phase 0C completed the physical persistence design gate.
- Phase 0D is implementation-eligible but **deferred** behind product-surface
  work until multi-year point-in-time queries beyond fixtures are required.
- There is no API server, active Compose file, database container, worker,
  scheduler, broker, queue, live source client, ingestion path, entity
  resolution module, signal module, analytics module, or production prediction
  service in the current checkout. The instrument may show fixture-backed
  pedagogical forecasts with explicit decay; that is not a production
  prediction module.

That absence for server/runtime surfaces is contractual. Phase 0D may introduce
only the persistence surface named below when deliberately resumed. Any other
future implementation surface must first amend the matching contract.

## 3. Build Order

| Build rank | Contract | Why it comes here |
| --- | --- | --- |
| 1 | GCS-SYS-001 | Fixes what GCS may claim and the proof standard |
| 2 | GCS-NAME-001, GCS-NAME-002 | Prevents naming drift before code appears |
| 3 | GCS-STACK-001 | Defines the allowed runtime and module boundaries |
| 4 | GCS-DATA-002, GCS-DATA-003 | Makes point-in-time data and persistence auditable |
| 5 | GCS-API-001 | Defines the transport boundary before any endpoint exists |
| 6 | GCS-RUNTIME-001 | Explicitly forbids queues in the current phase |
| 7 | GCS-DEPLOY-001, GCS-DEPLOY-002 | Prevents port, service, and environment ambiguity |
| 8 | GCS-SEC-001 | Applies source authority and lawful-data controls everywhere |
| 9 | GCS-TEST-001 | Converts the contracts into gates |
| 10 | GCS-IMPL-004 | Executes the build in phase order |

## 4. Phase-0 Implementation Eligibility

Phase 0A may only add or update:

- Contract documents.
- Static site and static figure code with contract headers.
- Validator tools.
- CI wiring for validator tools.
- Documentation for inactive future runtime surfaces.

Phase 0B may add only:

- `app/__init__.py`
- `app/raw_store/`
- `app/normalization/`
- `app/sources/fixtures/`
- `tests/raw_store/`
- `tests/normalization/`
- `tests/fixtures/`

Phase 0B input -> output contract:

```text
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
```

Phase 0B may not add:

- Live ingestion against public APIs.
- Database models or migrations.
- API endpoints.
- Workers, queues, schedulers, Redis, RabbitMQ, or Celery.
- Active container orchestration.
- Predictions or inference services.
- Live HTTP source clients.
- `app/api/`, `app/signals/`, or `app/entity_resolution/`.

Phase 0C is complete. It named the physical persistence inventory, migration
ordering, rollback policy, point-in-time query rules, and future Phase 0D
proof tests in GCS-DATA-003.

Phase 0D may add only:

- `app/persistence/`
- `migrations/NNNN_<snake_case>.py`
- `tests/persistence/`
- `tools/check_persistence_schema.py`
- `ops/local_variables.example` only if a future database URL variable is
  introduced and documented

Phase 0D may not add:

- `api/`
- `app/api/`
- active Compose files
- database containers
- standalone `.sql` files
- queues, workers, schedulers, Redis, RabbitMQ, or Celery
- live source clients or ingestion
- entity resolution
- signals
- analytics
- prediction

## 5. Implementation Gate

Every phase exits only when the audit table in GCS-AUDIT-001 names:

- The governing contract.
- The implementation files governed.
- Positive verification.
- Negative verification.
- Validation command.
- Status.
- Exact remediation for every gap.

## 6. Immediate Next Task

The next task is **product surface deepening**, not Phase 0D:

```text
Deepen the immersive instrument and study:
  build/ topology · lineage · math lab · bounded next-move modes
  index.html narrative and figure binding
  fixture honesty, provenance stamps, decay on forecasts
```

Phase 0D physical persistence remains eligible but deferred. Resume it only
when the instrument needs multi-year point-in-time queries beyond fixtures, and
only inside the Phase 0D allowance in GCS-DATA-003, GCS-TEST-001,
GCS-STACK-001, GCS-IMPL-005, and `tools/check_contracts.py`.

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