Metadata-Version: 2.4
Name: fbsde-system
Version: 0.2.0.dev7
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 dev7 candidate:

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

The candidate adds the smallest durable restart binding needed by the Plane-1
generation protocol: an adapter/store implementation identity remains stable
when only the fenced application attempt changes, while exact per-attempt
manifest registration and live fence validation remain mandatory. Run,
payload, barrier, compiler, contract, persistence-graph, and numerical
substitutions remain rejected. FBSDE numerical kernels are unchanged from
dev6. It is not accepted or published merely because these version strings
appear in source. The worker commit and deterministic wheel hash must be
frozen, all package lanes must pass against that exact artifact, and the owner
must accept the resulting tuple.

Until dev7 is published, install it from the exact locally built wheels or
exact sibling sources. Do not permit an index to satisfy either exact dev7
requirement implicitly.

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