Metadata-Version: 2.4
Name: fbsde-system
Version: 0.2.0.dev11
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.dev9; 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.dev9; 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 most recent published package pair is:

```text
fbsde-system==0.2.0.dev10
worker-learner-core==0.2.0.dev8
```

That immutable pair remains available for reproducing its published interface:

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

The example source shipped with that pair is:

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

It pins the published pair above and is included as source in this repository
and the FBSDE dev10 tag. The example is not published on PyPI; install it from
`examples/minimal_linear_fbsde_app/` when needed.

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.

Do not adopt dev10/dev8 for a new multiprocess run: worker dev8 can exit after
a finite packet budget before its queue feeder flushes an accepted packet. The
current coordinated release candidate is:

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

Dev11 changes the exact Plane-1 dependency and package/example identities; it
does not change FBSDE contracts, persistence, compiler behavior, or numerical
kernels. Worker dev9 fixes finite-budget packet delivery while retaining
bounded coordinated shutdown. Use exact candidate wheels until both packages
are published and independently verified.

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 immutable historical 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.
