# substrate-sdk-python

Build shellbound applications. Any Python framework. Any deployment. Trust rooted in hardware.

## Install

```bash
pip install substrate-sdk[django]
```

## Django (2 lines)

```python
# settings.py
INSTALLED_APPS = [
    ...
    'substrate_sdk.django',
]
MIDDLEWARE = [
    ...
    'substrate_sdk.django.ShellboundMiddleware',
]
```

Every request is Chronicle-attributed. Every model save is Chronicle-recorded.
If a bascule shell is present: fully governed. If not: development mode, works normally.

## Direct usage

```python
from substrate_sdk import ShellApp

app = ShellApp(shard_name="my-app", capabilities={"network": True})
context = app.register()
print(context.is_governed)  # True if shell present
print(context.shard_did)     # DID assigned by shell
```

## What this does

When running inside a Substrate FFC:
- Your process gets a DID + SPIFFE SVID
- Your process gets a governed accord
- Every request is Chronicle-attributed
- Every operation is audit-verifiable
- You participate in the governance fabric

When running locally (no shell):
- Development mode — everything works normally
- Chronicle events go to stdout
- No governance enforcement
- Zero impact on application behavior

## Phase B: HFL Direct Binding (planned)

When the HFL kernel module is present, `substrate_sdk` will route Chronicle
events through `substrate-hfl-python` (PyO3) instead of stdout. This upgrades
a Tier 4 deployment to Tier 1/2 with **zero application code changes**.

```
Phase A (current):  SDK → stdout → bascule-filter → Chronicle
Phase B (planned):  SDK → substrate-hfl-python (PyO3) → HFL → Chronicle
```

`substrate-hfl-python` is a new crate in the substrate workspace:
- Depends on `hfl-types`
- Exposes: `chronicle_write()`, `accord_check()`, `session_get()`
- `substrate_sdk/chronicle.py` detects HFL availability and routes automatically