Metadata-Version: 2.4
Name: fbsde-system
Version: 0.2.0.dev8
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.dev7; 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.dev7; 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 source is the coordinated, nonauthorizing dev8/dev7 candidate:

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

The dev8 FBSDE candidate preserves the dev7 durable restart binding and makes
one Linux portability repair: the internal admission journal lock file is
opened read/write before requesting an exclusive `flock`. Exact per-attempt
manifest registration, live fence validation, and all stable run, payload,
barrier, compiler, contract, persistence-graph, and numerical bindings remain
unchanged. FBSDE numerical kernels are unchanged from dev6. It is not accepted
merely because these version strings appear in source. The exact FBSDE and
worker commits and deterministic wheel hashes must be frozen, all package
lanes must pass against those artifacts, and the owner must accept the
resulting tuple.

Before dev8 registry publication, install the FBSDE package from the exact
locally built wheel or exact source and install worker core dev7 from its exact
published artifact. Do not permit an index to substitute a different version
for either exact requirement.

The previous exact tuple remains the retained personal-stable acceptance for
nonauthorizing single-owner research:

The retained owner acceptance names this exact tuple:

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

Install that retained accepted package pair from PyPI:

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

The `worker-core` and `full` extras also require that exact worker-core
version:

```bash
python -m pip install 'fbsde-system[worker-core]==0.2.0.dev6'
python -m pip install 'fbsde-system[jax]==0.2.0.dev6'
python -m pip install 'fbsde-system[full]==0.2.0.dev6'
```

Importing the worker integration without its optional dependency raises a
focused `MissingOptionalDependencyError`.

The immutable release tags `v0.2.0.dev6` in the worker and FBSDE repositories
identify the accepted sources. Exact commits, wheel hashes, hosted runs, and
independent reproduction evidence are retained outside this package source so
that changing this README cannot recursively change the identity it names.
See `docs/interfaces/compatibility.md`.

The dev6/dev3 versions above identify immutable retained acceptance. They do
not assign an identity or status to the dev8/dev7/dev4 candidate.

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