# Licensed bundle provider port

`LicensedBundleProvider` consumes a customer-owned normalized data drop from
the absolute canonical directory named by `MOONFISH_LICENSED_BUNDLE`. It makes
no network calls and contains no vendor-specific API code.

Current status: version `0.21.0` includes a native MoonBit preflight/loader and
durable snapshot receipt. It remains disabled until
`MOONFISH_LICENSED_BUNDLE` names a canonical customer-owned directory. The
loader never falls back to a fixture or public source. Commercial use still
requires the customer’s actual data contract and license approval.

The directory contains `manifest.json`, `snapshot.json`, and exactly twelve
normalized dataset JSON files. The manifest contract is
`moonfish.licensed-data-bundle.v1` version `1.0.0`. Each dataset file uses
`moonfish.licensed-dataset.v1` and contains only `contract_id`,
`contract_version`, `dataset_id`, and `records`. `snapshot.json` uses
`moonfish.licensed-systematic-snapshot.v1` and binds the bundle ID, the exact
dataset digest map, and a `systematic_snapshot` implementing the same v2
interface returned by the development fixture provider.

All paths are bundle-relative, unique, regular files, and may not traverse or
resolve through symbolic links. SHA-256 digests bind raw bytes. Commercial
acquisition fails closed on any contract, schema, path, digest, timestamp,
freshness, coverage, point-in-time, adjustment, license, or contract-reference
failure. A validated bundle grants research-data availability only; it grants
no broker, order, execution, publication, resale, or investment-advice
authority.

## Operator contract

Copy `moonpack/examples/licensed-data-bundle.manifest.example.json` as a shape
template only. Its zero digests and placeholder references are intentionally
non-runnable. Normalize the licensed inputs into the twelve dataset envelopes,
compute SHA-256 over each file's exact bytes, and put those twelve digests in
both `manifest.json` and `snapshot.json`. Compute the snapshot digest last and
put it in the manifest.

The snapshot's `systematic_snapshot` contains the already normalized v2 market
snapshot: cutoff-aware provider metadata, an ordered exchange-session calendar,
regime inputs, and the multi-security universe used by the deterministic
screening and scoring workflow. At least 67 ordered exchange sessions are
required so every recommendation can carry the installed
`quarterly-extreme-upside` policy's 40–65-session plan.

Portfolio daily operation is a separately readiness-gated extension. A bundle
used after market close may add `portfolio_daily_observation` to
`systematic_snapshot`. It must implement
`moonfish-portfolio-daily-observation@1.0.0`: exact next valid session, one
close/accessibility row per open position, CSI All Share and industry return
series, effective corporate actions, source/effective/retrieval/cutoff times,
commercial license class, adjustment method, nested record digests and exact
run calendar/data/policy/plan/prior-portfolio bindings. The service reloads and
validates the local bundle for the operation. If the extension is absent,
commercial portfolio observation fails with
`commercial_portfolio_daily_observation_missing`; it never substitutes fixture
or caller-authored prices.

The long-lived cross-run paper account accepts licensed daily observations only
when every open symbol has a point-in-time, commercially licensed,
digest-bound, adjustment-consistent row. Fixture shadow observations must
explicitly declare fixture mode and cannot be relabeled as commercial.

Setting `MOONFISH_LICENSED_BUNDLE` selects the only commercial ingress. It does
not itself approve the license or prove an investable edge.