Metadata-Version: 2.4
Name: fbsde-system
Version: 0.2.0.dev14
Summary: Framework-neutral contracts and runtime primitives for FBSDE systems.
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
Requires-Dist: numpy>=2.0
Provides-Extra: jax
Requires-Dist: jax>=0.4.38; extra == "jax"
Requires-Dist: optax>=0.2.4; extra == "jax"
Provides-Extra: worker-core
Requires-Dist: worker-learner-core==0.2.0.dev11; extra == "worker-core"
Provides-Extra: full
Requires-Dist: jax>=0.4.38; extra == "full"
Requires-Dist: optax>=0.2.4; extra == "full"
Requires-Dist: worker-learner-core==0.2.0.dev11; extra == "full"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.8; extra == "dev"

# fbsde-system

`fbsde-system` is the independently installable Plane 2 package for reusable
FBSDE contracts, model IR, compilation, semantic identities, StateBank,
replay, lifecycle, checkpoint, commit, and recovery machinery. Model equations
and numerical kernels belong to the consuming Plane 3 application.

The distribution name is `fbsde-system`; the import name is `fbsde_system`.
The base installation depends only on NumPy and imports neither JAX nor
`worker_learner_core`. Optional integrations are explicit.

## Package status

The current published package pair is:

```text
fbsde-system==0.2.0.dev13
worker-learner-core==0.2.0.dev11
```

Install the exact pair from PyPI:

```bash
python -m pip install \
  'worker-learner-core==0.2.0.dev11' \
  'fbsde-system==0.2.0.dev13'
```

The separately packageable example source shipped with that pair is:

```text
minimal-linear-fbsde-app==0.1.0.dev8
```

It pins the published pair above and is included as source in this repository
on `main` immediately after the `v0.2.0.dev13` release (the tag itself
carries example dev7 with the previous pair's pins — a release-prep omission
caught by package CI). The example is source-only and is not published on
PyPI; install it from `examples/minimal_linear_fbsde_app/` when needed.

Dev13 changes the exact Plane-1 dependency and package/example identities; it
does not change FBSDE contracts, persistence, compiler behavior, or numerical
kernels. Worker dev11 adds the application-free concurrency framework
subpackage (`worker_learner_core.concurrency`) extracted from macro_finance —
schedule laws with content-addressed identities, a snapshot channel with
pointer and file transports, and ordinal evaluator partitions — with every
existing facade surface unchanged. The example version changes because its
exact dependency metadata is part of its artifact identity.

The superseded dev12/dev10 pair and its source-only dev7 example remain
available at the FBSDE `v0.2.0.dev12` tag for historical reproduction; that
pair has no known behavioral defect. The earlier dev11/dev9 pair and its dev6
example remain at the FBSDE `v0.2.0.dev11` tag; do not adopt dev11/dev9 for a
new multi-evaluator run: a stalled or dead snapshot consumer can leave worker
dev9 waiting without a bound.

The exact tags, source commits, and verified wheel hashes for the published
pair are recorded in `docs/interfaces/compatibility.md`. Do not substitute an
unbounded preview range or expose sibling source through `PYTHONPATH`.
Importing the worker integration without its exact optional dependency raises
a focused `MissingOptionalDependencyError`.

See `docs/interfaces/compatibility.md` for the current and retained historical
baselines.

## Primary cross-project path

A new project should own its formulation, contracts, bindings, work, packets,
snapshots, and application factory. The intended public path is:

```text
model formulation
  -> application-owned FBSDEModelIR and FBSDEKernelBindings
  -> compile_fbsde_model(...)
  -> CompiledFBSDEApplication
  -> ApplicationFactory.from_payload(...)
  -> worker_learner_core.run_application(...)
```

`FBSDEEvaluatorWorkerFactory` uses the authoritative
`worker_learner_core.evaluator.worker.EvaluatorWorker` by default. Do not
provide a custom worker builder unless the application genuinely needs a
different worker implementation.

The separately packageable example in
`examples/minimal_linear_fbsde_app/` implements the scalar formulation
`dX=0, Y_T=X_T` without importing any reference application. After installing
the two exact wheels:

```bash
python -m pip install ./examples/minimal_linear_fbsde_app
python -m minimal_linear_fbsde_app.smoke --mode cooperative
python -m minimal_linear_fbsde_app.smoke --mode spawn
```

Each mode performs one evaluator transaction and one learner update through
the public application facade.

## Authority boundary

The example uses `InMemoryFBSDECommitAuthority` and reports:

```text
authority_status = nonauthorizing
authority_mode = development-in-memory
```

That mode is suitable for development and nonauthorizing personal
verification. It does not grant durable admission, publication, pointer,
checkpoint, recovery, or production authority. Applications that require
those powers must bind the appropriate verified durable authorities
explicitly.

The exact tuple named in the current owner acceptance is personal-stable only
within its nonauthorizing, single-owner research boundary. Any later source or
tuple requires its own exact verification and acceptance.
Neither package status nor a successful run is a production ApprovalRecord,
ReleaseRecord, or AuthorityTransferRecord.

## Verification lanes

Install the dependencies for the lane being exercised, then run:

```bash
# Base: NumPy only; no JAX or worker-core integration tests
python -m pytest -q -m 'not worker_core_integration and not jax_integration'

# Worker-core integration
python -m pytest -q -m worker_core_integration

# JAX integration
python -m pytest -q -m jax_integration

# Full installed environment
python -m pytest -q

python -m ruff check .
python -m build
python scripts/audit_base_import.py
python -m compileall -q src tests scripts examples/minimal_linear_fbsde_app
```

The base audit rejects imports of JAX, worker core, and reference-application
namespaces from the base package.

## Standalone external-application verifier

The FBSDE repository owns a package-local installed-wheel verifier for its
minimal external application:

```bash
python scripts/verify_minimal_external_application.py \
  --worker-core-repo ../worker_learner_core \
  --external-app ./examples/minimal_linear_fbsde_app \
  --output-dir ../artifacts/fbsde-minimal-external-application
```

It observes the actual evaluator object and worker-builder setting, checks the
exact cooperative and spawn close-marker sets, compares smoke diagnostics with
independent observations, and rejects reference-application imports. Package
tests and this verifier require no `correlated_default` checkout.

## Independent consumer verifier

The owner repository `correlated_default` separately provides the
cross-project consumer verification entrypoint. From a checkout containing
the three sibling repositories, run:

```bash
python ../correlated_default/scripts/verify_personal_three_plane_pair.py \
  --worker-core-repo ../worker_learner_core \
  --fbsde-system-repo . \
  --external-app ./examples/minimal_linear_fbsde_app \
  --output-dir ../correlated_default/artifacts/personal_three_plane_pair
```

The verifier builds clean wheels, installs them without repository-source
leakage, checks the package lanes, and runs the external application's default
evaluator, cooperative, and spawn modes. Retain its manifest and exact wheel
hashes when selecting a pair for another project.

## Compiler and contract surface

`compile_fbsde_model(...)` compiles a validated `FBSDEModelIR` and a closed
`FBSDEKernelBindings` collection into eight immutable plans and a
`CompiledFBSDEModel`. Callable source and behavior-visible static state are
authenticated, and deserialized plans are reconstructed from the IR and
binding manifest before use.

Compilation emits an `ExecutionIdentityRecipe`; execution and exact-replay
identities are resolved only after route, artifact, and numerical-ABI facts are
available. Route-specific lifecycle projections remain authority-gate inputs,
not compiler inputs, so compilation stays reusable across applications.
