S3 NEXT dynamic documentation

This tree is independent from the canonical s2 documentation. It has three truth layers:

• current/declared/ — compiled from the checked-in ProductSpec, PageSpec, Data API routes, S3 cron and compose files;
• current/observed/ — an externally captured, read-only S3 runtime manifest;
• current/reconciliation/ — exact set/digest drift between those layers.

Generate declared documentation without contacting any server:

python scripts/docs/generate_next_reconciliation.py

Reconcile an observed manifest and fail on any drift:

python scripts/docs/capture_s3_next_runtime.py \
  --output /tmp/s3-next-runtime.json
python scripts/docs/generate_next_reconciliation.py \
  --observed /tmp/s3-next-runtime.json \
  --require-observed --fail-on-drift

The capture command runs on S3 after deploy and is read-only. It reads the ProductSpec set from next_collector.py --list, PageSpec hashes from the running frontend container, routes from the live Data API OpenAPI document, the installed root crontab and the health of both runtime services.

The observed JSON contract is strict and rejects unknown keys:

{
  "schema_version": 1,
  "source_commit": "40 hexadecimal git characters",
  "bundle_digest": "64 hexadecimal characters",
  "observed_at_utc": "2026-07-13T12:00:00Z",
  "products": [{"code": "wb.stocks", "digest": "64 hexadecimal characters"}],
  "pages": [{"code": "stocks.wb", "digest": "64 hexadecimal characters"}],
  "routes": ["GET /api/v1/status/collection-runs"],
  "cron": ["the exact installed cron entry"],
  "services": ["gwptd-app-new", "gwptd-data-api"]
}

No observed evidence means unverified, never pass. The generator does not SSH, run collectors, write databases, or infer live state from declared files.

On S3, gwptd-next-docs.timer runs this strict reconciliation daily at 16:30 UTC (with up to five minutes of jitter). It writes only in the isolated /opt/gwptd-next-docs-sync worktree and publishes automation/s3-next-live-catalog; the production checkout stays clean and the result is proposed back to next/spec-platform as a draft pull request. The timer uses its own reproducible /opt/gwptd-next-docs-venv; it does not reuse or mutate the collector and Data API Python environments.