Metadata-Version: 2.4
Name: financial-data-protocol
Version: 0.3.1
Summary: Financial Data Protocol Central Registry
Author: Financial Data Protocol contributors
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Requires-Python: <3.15,>=3.13
Description-Content-Type: text/markdown
Requires-Dist: alibabacloud-oss-v2<2,>=1.4
Requires-Dist: boto3==1.43.83
Requires-Dist: fastapi<1,>=0.115
Requires-Dist: httpx>=0.28.1
Requires-Dist: loguru<1,>=0.7
Requires-Dist: psycopg[binary]<4,>=3.2
Requires-Dist: pymongo<5,>=4.10
Requires-Dist: pydantic==2.12.5
Requires-Dist: pytest>=9.1.1
Requires-Dist: pyyaml<7,>=6.0
Requires-Dist: uvicorn[standard]<1,>=0.30
Requires-Dist: trio>=0.34.0
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: jsonschema>=4.23; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: pytest>=8.2; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"

# Financial Data Protocol

Financial Data Protocol (FDP) is infrastructure for registering and tracing exact financial source
materials across business systems.

FDP answers questions such as:

- What exact bytes were registered?
- Which business Artifact refers to those bytes?
- Which immutable Package Revision was used?
- Which system declared a transfer, disclosure, or use?
- Can the retrieved bytes still be verified against their registered identity?

FDP records structure, identity, integrity, provenance, visibility, and immutable history. The
business system that declares a material remains responsible for its business meaning and truth.

## Current deployment profile

The current FDP product provides **Central FDP**: a shared service with Registry Spaces,
PostgreSQL Registry storage, S3-compatible Content custody, authenticated transports, and a typed
client. The previously described Embedded/local warehouse profile is not part of the current
product surface.

The Central capability milestones are incremental:

```text
C0 protocol records and schemas
  -> C1 custody and transaction contract
  -> C2 durable Registry, object custody, and typed client
  -> C3 immutable finance handoffs
  -> C4 disclosure and evidence references
  -> C5 one-writer Space authority cutover
  -> C6 global physical Blob deduplication
```

See [`docs/central-capabilities.md`](docs/central-capabilities.md) for the implementation details
of these milestones. Version history belongs in [`CHANGELOG.md`](CHANGELOG.md).

## Current Central interface

The current packaged command is `fdp-central`. Its commands are:

```bash
fdp-central serve
fdp-central init-db
fdp-central blob-sweep --month 2026-08
```

The Central HTTP service exposes health/readiness/version endpoints, Content staging and
finalization, verified Content retrieval, Artifact and Package Revision registration, declarations,
finance handoffs, disclosure operations, and authority operations.

Start the configured service with:

```bash
uv sync --locked --extra dev
uv run fdp-central init-db
uv run fdp-central serve
```

`init-db` initializes the configured MongoDB Registry and is intentionally limited to a database
without application collections; collections whose names start with `_` are ignored. If
application collections already exist, delete the database manually before initialization.
`blob-sweep` reconciles final Blob objects for one UTC month, for example
`--month 2026-08`; it runs as a dry-run unless `--apply` is supplied.

The service reads the root `config.yaml`. Configure PostgreSQL, S3-compatible storage, HTTP
settings, and machine-token bindings there. Protect this file because it contains deployment
credentials. Deployment prerequisites and examples are documented in
[`docs/central-deployment.md`](docs/central-deployment.md).

## Python client

`CentralClient` sends strict typed requests through a `CentralTransport`. For an in-process test,
use deterministic in-memory custody implementations:

```python
from financial_data_protocol import (
    CentralClient,
    CentralService,
    ContextSpaceAuthorizer,
    InMemoryContentCustody,
    InMemoryRegistryCustody,
    InProcessCentralTransport,
    StaticMachineTokenAuthenticator,
    StaticMachineTokenBinding,
)

transport = InProcessCentralTransport(
    CentralService(
        registry=InMemoryRegistryCustody(),
        content_custody=InMemoryContentCustody(),
        authorizer=ContextSpaceAuthorizer(),
    ),
    StaticMachineTokenAuthenticator((
        StaticMachineTokenBinding(
            "legal-api", "development-token", frozenset({"legal"})
        ),
    )),
)
client = CentralClient(
    transport,
    machine_token="development-token",
    caller_id="legal-api",
    registry_space_id="legal",
)
```

For a deployed service, use the same `CentralClient` API with `HttpCentralTransport`:

```python
from financial_data_protocol import CentralClient, HttpCentralTransport

client = CentralClient(
    HttpCentralTransport("https://central.example", "machine-token", "legal-api"),
    machine_token="machine-token",
    caller_id="legal-api",
    registry_space_id="legal",
)
```

All writes require a stable idempotency key. Repeating the same canonical request replays its
original result; reusing a key for a different request returns a conflict. Content uploads and
retrievals verify the declared size and SHA-256.

Central schema revision 6 separates Space-local Content registration from global physical Blob
custody. `central_contents` keeps each Space's Content identity, while `content_blobs` stores one
physical object for each global `(sha256, size_bytes)` identity and tracks its reference count.
The upload/finalize path performs Blob discovery internally, so clients never need cross-Space
catalog access. Identical bytes registered in different Spaces share one object-store key:

```text
central/<UTC creation date>/<blob_id>
```

Temporary staged objects are removed after successful finalization, and provisional Blob objects
are removed if the Registry transaction rejects the finalize request. PostgreSQL and MongoDB both
support the C6 model. Deployments should initialize a new revision 6 database rather than upgrade
an older database revision.
See the C6 section in [`docs/central-capabilities.md`](docs/central-capabilities.md) for the complete
identity, idempotency, and migration semantics.

## Scope

FDP does not decide whether a contract is approved or compliant, whether a payment is allowed,
whether an invoice is valid, or whether an accounting entry is correct. It does not provide IAM,
Registry federation, a queue, a general RAG system, or downstream workflow and output management.
See [`docs/product-definition.md`](docs/product-definition.md) for the complete product boundary.

## Documentation

- [`docs/central-capabilities.md`](docs/central-capabilities.md): Central C0-C6 capability details
  and historical implementation notes.
- [`docs/api.md`](docs/api.md): Central HTTP API operations.
- [`docs/central-http-contract.md`](docs/central-http-contract.md): frozen HTTP wire contract.
- [`docs/central-deployment.md`](docs/central-deployment.md): deployment and operations.
- [`docs/central-deployment-company-quickstart.md`](docs/central-deployment-company-quickstart.md):
  company deployment quick start.
- [`docs/central-authority-cutover-runbook.md`](docs/central-authority-cutover-runbook.md): C5
  cutover and rollback procedure.
- [`docs/central-e2e-scenario.md`](docs/central-e2e-scenario.md): Central end-to-end scenario.
- [`docs/product-definition.md`](docs/product-definition.md): product role, users, and boundaries.
- [`docs/roadmap.md`](docs/roadmap.md): phased delivery roadmap.
- [`CHANGELOG.md`](CHANGELOG.md): release and version history.

## Development checks

```bash
uv sync --locked --extra dev
uv run python -m pytest -q
uv run python -m ruff check .
uv run python -m mypy
uv run python -m build
```
