# Public Methodology Export Bundle

## Purpose

The production investing repository is private and contains account, broker, execution, infrastructure, correspondence, and other runtime concerns that should not become public merely because methodology transparency is valuable.

The public methodology therefore uses an explicit export boundary instead of changing the production repository's visibility or copying its Git history.

The current staging command is:

```bash
python tools/build_public_methodology_bundle.py \
  --source-commit <immutable-source-commit> \
  --output artifacts/public-methodology-bundle
```

The output is intended to become the reviewed input to a future purpose-built public repository.

## What the builder guarantees

The builder:

- exports only a source-code allowlist reviewed in `tools/build_public_methodology_bundle.py`;
- accepts source files only under `public_methodology/`;
- rejects absolute paths, parent traversal, symlinks, missing required files, duplicate destinations, and non-UTF-8 content;
- refuses to overwrite a nonempty destination;
- requires the destination to remain under this repository's `artifacts/` directory;
- scans content for high-confidence secret formats before writing the bundle;
- validates every source before creating output;
- creates a deterministic `bundle-manifest.json` with the declared source commit, source/output path, SHA-256 checksum, and byte count for each exported file;
- contains no publication or network side effect.

A successful build means the bundle satisfied these mechanical export checks. It is not a legal review, investment-performance verification, or guarantee that every statement in the bundle is correct forever.

## Standalone reproduction

The reviewed bundle contains the complete runtime needed for two disclosed calculation examples.

### Synthetic return and risk metrics

- `examples/reproduce_synthetic_metrics.py` contains fully disclosed invented monthly return inputs;
- `calculations.py` contains the standard-library core return/risk calculations used by that example;
- `generated-policy.json` supplies the versioned policy identity shown in the output;
- no private-repository import path or third-party Python package is required.

From the bundle root:

```bash
python examples/reproduce_synthetic_metrics.py
```

Private-repository parity tests compare the public core metrics against the canonical `backtest.metrics.MetricsCalculator`. The synthetic example remains calculation validation only and is not strategy-performance evidence.

### Official Treasury cash-benchmark calculation

The bundle also includes:

- `data/treasury_bill_2025-06-30.json`, a minimal reviewed subset of an official U.S. Treasury 91-day bill auction result;
- `examples/reproduce_treasury_cash_benchmark.py`, which calculates the holding-period return and simple annualized cash rate from the published price;
- the same `calculations.py` standard-library module.

From the bundle root:

```bash
python examples/reproduce_treasury_cash_benchmark.py
```

The selected Treasury auction published a price of `98.929486` per $100 maturity value and an investment rate of `4.340%`. The bundled calculation reproduces approximately `4.340283%`, agreeing with the published rounded rate within `0.001` percentage point.

This is a real-market cash-benchmark calculation primitive, not an investing-strategy return, recommendation, backtest, paper result, live result, or claim of superiority. The retained input omits CUSIP and unrelated tender/allocation fields.

Both examples are exercised from an isolated bundle in contract tests with `PYTHONPATH` cleared, Python site packages disabled, no private repository imports, and no network dependency.

## What is intentionally excluded

The export boundary does not include:

- brokerage integrations or credentials;
- customer or founder account state;
- balances, holdings, tax lots, or correspondence;
- order execution code;
- database migrations or production schemas;
- deployment configuration or infrastructure topology;
- environment files or secrets;
- production logs and run artifacts;
- the private repository's Git history;
- the full private backtest or strategy implementation.

The public calculation module contains only the reviewed calculations necessary to reproduce the disclosed examples. Adding any new source file to the export requires an explicit allowlist change and the public-methodology contract tests.

## Destination repository

A future public repository should be initialized from a reviewed bundle output, not by:

- changing `Stock-Market-Trading` from private to public;
- mirroring the entire private repository;
- copying private Git history;
- manually selecting files without regenerating the bundle manifest.

This creates a clean provenance chain:

1. private source commit;
2. reviewed export allowlist;
3. deterministic bundle and checksums;
4. standalone reproduction proof;
5. public repository import;
6. public evidence and review links.

That chain is the credibility feature. A public GitHub badge by itself is not.