FIBONACCI RING — FINITE-FACE COSMOLOGICAL OBSERVATORY v2.0.0
================================================================

PURPOSE
-------
This implementation runs the supplied Fibonacci Ring progression while
avoiding exhaustive materialization of every simplex generated by repeated
barycentric subdivision.

The primary progression remains:
    Ω, A, B

K is recovered from (A,B) using fast-doubling Fibonacci arithmetic. The
subdivision depth used by the observatory is derived from K as max(0,K-3).
It is not stored as an independent ring counter.

The topology is represented by:
    * the base complete simplex (1 through 4 vertices during initialization)
    * its exact f-vector
    * the exact barycentric-subdivision recurrence

A finite set of faces is manifested at each transition. Each sampled face is
identified by a global rank and a compact ancestry witness. The witness stores
one parent-rank/ordered-partition step per derived subdivision level. It does
not expand all faces or all vertices of the latent complex.

REQUIREMENTS
------------
Python 3.10 or newer. Standard library only. No pip installs required.

WINDOWS QUICK START
-------------------
1. Extract the ZIP.
2. Open PowerShell in the extracted directory.
3. Run:

   py -3.13 fibonacci_ring_finite_observatory.py --steps 128 --samples 64 --mutations --log-dir fibonacci_ring_finite_run

The command performs 128 transitions, manifests at most 64 faces per
transition, runs the shadow mutation campaign, verifies the trace, and
reconstructs the history.

SMALL-SCALE EXHAUSTIVE CROSS-CHECK
----------------------------------
Run the explicit abstract-complex oracle through subdivision depth 3:

   py -3.13 fibonacci_ring_finite_observatory.py --steps 7 --samples 64 --oracle-levels 3 --log-dir fibonacci_ring_oracle_check

This explicitly materializes only the small reference complexes. At depth 3
the oracle checks the exact f-vector and every sampled face witness against
the materialized complex. It is not used for later large-depth progression.

RESUME A LONG-RUN EXPERIMENT
----------------------------
A fresh run writes an append-only observations.jsonl trace and an atomic
checkpoint.json. To continue the same experiment:

   py -3.13 fibonacci_ring_finite_observatory.py --steps 128 --samples 64 --mutations --resume --log-dir fibonacci_ring_finite_run

--steps is the number of additional transitions in that invocation; it is
an external experiment stopping budget, not a ring progression counter.
Resume verifies the trace hash chain and reconstructs the current ring state
from TRACE. The trace is authoritative if a checkpoint is stale.
Use the same --seed, --radius, and --axial-scale as the original run.
A fresh run without --resume starts a new trace in the selected log directory.

USEFUL OPTIONS
--------------
--steps N             Number of additional transitions (default 12)
--samples N           Maximum finite face manifestations per transition
                      (default 64; allowed 1..4096)
--seed N              Deterministic sampling seed (default 20261109)
--mutations           Run shadow-only mutation tests
--oracle-levels N     Exhaustive oracle depth, 0..3 (default 2)
--resume              Continue an existing verified experiment
--log-dir PATH        Output directory
--radius FLOAT        Strand radius (default 1)
--axial-scale FLOAT   Strand axial scale (default 1)

MATHEMATICAL REPRESENTATION
---------------------------
For a d-dimensional complex with f-vector f_j, barycentric subdivision has

  f'_d = sum_{j=d..D} (d+1)! S(j+1,d+1) f_j

where S(n,k) is a Stirling number of the second kind. The coefficient counts
ordered partitions of the vertices of a parent simplex into nonempty blocks,
which correspond to strict chains of nonempty faces.

The transform is inverted exactly to unrank a face ancestry from its global
rank. The implementation batches unranking so the previous f-vector is
recovered once per level, not once per sampled face.

For the initial tetrahedron:
  initial f-vector: [4, 6, 4, 1]
  after one subdivision: [15, 50, 60, 24]
  after two subdivisions: [149, 796, 1224, 576]
  after three subdivisions: [2745,  ...]

The f-vector, dimension, Euler characteristic, and face counts are exact
arbitrary-precision integers. Since the initialized complex is a simplex and
barycentric subdivision preserves its homeomorphism type, its Betti numbers
over F2 remain (1,0,...,0).

WHAT IS AND IS NOT CERTIFIED
----------------------------
Exact:
  * Fibonacci pair/address recovery
  * f-vector recurrence and total latent face count
  * dimension and Euler characteristic
  * contractible homology class inherited from the simplex
  * sampled face ancestry and rank reconstruction
  * append-only trace hash chain
  * full historical replay from the initial state

Cross-checked exhaustively at small depths:
  * explicit f-vector agreement
  * sampled ancestry witnesses resolve to actual simplices

Not claimed:
  * that a finite sample detects every possible mutation in the latent complex
  * that a sampled local neighborhood proves global adjacency integrity
  * that the f-vector alone uniquely determines a simplicial complex

The mutation campaign deliberately includes an unsampled latent-face mutation.
It is expected to remain undetected by a finite sample. This is an explicit
measurement boundary, not a successful global integrity claim.

OUTPUT FILES
------------
baseline.json             Experiment seed and initial conditions
observations.jsonl         Append-only transition trace with hash chain
checkpoint.json            Atomic latest committed ring state
mutation_results.jsonl     Shadow mutation results (when --mutations)
tomography.json            Summary of observational windows
tomography.jsonl           Window hashes
final_report.json          Final verification and reconstruction report

The primary ring is never mutated by the shadow mutation campaign.
================================================================
