Metadata-Version: 2.4
Name: fbsde-system
Version: 0.2.0.dev10
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.dev8; 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.dev8; 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 application baseline is:

```text
fbsde-system==0.2.0.dev9
worker-learner-core==0.2.0.dev7
minimal-linear-fbsde-app==0.1.0.dev4
```

Install the published pair from PyPI:

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

The current source tree is the coordinated release candidate:

```text
fbsde-system==0.2.0.dev10
worker-learner-core==0.2.0.dev8
minimal-linear-fbsde-app==0.1.0.dev5
```

Dev10 adds bounded replay-admission timing while preserving the dev9 admission,
durability, recovery, compiler, and numerical behavior. It binds the dev8
Plane-1 compact-result, lifecycle, shutdown, and progress contract. The example
version changes because its exact dependency metadata is part of its artifact
identity.

This candidate is not a published baseline until both exact package commits are
tagged, their wheels are published and verified, and the coordinated pair is
qualified. Until then, use exact locally built wheels for candidate testing;
do not permit an index to substitute older packages 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 immutable published baseline.

## 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.
