financial-data-protocol 0.3.0a3__tar.gz

financial_data_protocol-0.3.0a3/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: financial-data-protocol
+Version: 0.3.0a3
+Summary: Financial Data Protocol Central Registry
+Author: Financial Data Protocol contributors
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Requires-Python: <3.15,>=3.14
+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
+```

financial_data_protocol-0.3.0a3/README.md

@@ -0,0 +1,174 @@
+# 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
+```

financial_data_protocol-0.3.0a3/pyproject.toml

@@ -0,0 +1,75 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "financial-data-protocol"
+version = "0.3.0a3"
+description = "Financial Data Protocol Central Registry"
+readme = "README.md"
+requires-python = ">=3.14,<3.15"
+authors = [{name = "Financial Data Protocol contributors"}]
+classifiers = [
+	"Development Status :: 3 - Alpha",
+	"Programming Language :: Python :: 3.14",
+	"Operating System :: OS Independent",
+]
+dependencies = [
+	"alibabacloud-oss-v2>=1.4,<2",
+	"boto3==1.43.83",
+	"fastapi>=0.115,<1",
+	"httpx>=0.28.1",
+	"loguru>=0.7,<1",
+	"psycopg[binary]>=3.2,<4",
+	"pymongo>=4.10,<5",
+	"pydantic==2.12.5",
+	"pytest>=9.1.1",
+	"pyyaml>=6.0,<7",
+	"uvicorn[standard]>=0.30,<1",
+	"trio>=0.34.0",
+]
+
+[project.scripts]
+fdp-central = "financial_data_protocol.cli:main"
+
+[project.optional-dependencies]
+dev = ["build>=1.2", "jsonschema>=4.23", "mypy>=1.10", "pytest>=8.2", "ruff>=0.5"]
+
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+financial_data_protocol = ["server/db/postgres/migrations/*.sql"]
+
+[tool.pytest.ini_options]
+addopts = "-ra"
+markers = [
+	"integration: disposable PostgreSQL or MongoDB integration coverage",
+]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py314"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.mypy]
+python_version = "3.14"
+strict = true
+packages = ["financial_data_protocol"]
+
+[[tool.uv.index]]
+name = "pypi"
+url = "https://pypi.org/simple"
+explicit = true
+
+[[tool.uv.index]]
+name = "tencent"
+url = "https://mirrors.cloud.tencent.com/pypi/simple"
+default = true

financial_data_protocol-0.3.0a3/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

financial_data_protocol-0.3.0a3/src/financial_data_protocol/__init__.py

@@ -0,0 +1,187 @@
+"""Financial Data Protocol public package."""
+
+from .client import FdpClient, FdpConfig
+from .client.protocol_client import CentralClient, CentralClientError
+from .constants import API_SCHEMA_VERSION, CENTRAL_SCHEMA_REVISION, CENTRAL_SCHEMA_VERSION
+from .models import (
+    Artifact,
+    Content,
+    DeclarationProvenance,
+    DisclosurePackageRevision,
+    DisclosureReceipt,
+    DisclosureRevocation,
+    EvidenceReference,
+    LineageDeclaration,
+    LineageRelationType,
+    MaterialTransfer,
+    Package,
+    PackageMember,
+    PackageRevision,
+    RegistrySpace,
+    SpaceAccess,
+    UsageReceipt,
+    WriteConflict,
+    WriteCreated,
+    WriteIdempotent,
+    WriteResult,
+)
+from .server.api import (
+    ApiFailure,
+    ApiRequest,
+    ApiResponse,
+    ApiSuccess,
+    CentralTransport,
+    InProcessCentralTransport,
+    StaticMachineTokenAuthenticator,
+    StaticMachineTokenBinding,
+)
+from .server.authority import (
+    AuthorityCutoverRecord,
+    AuthorityRollbackPointRecord,
+    AuthorityRollbackRecord,
+    DomainAuthorityGate,
+    DomainAuthorityReadback,
+    DomainAuthorityState,
+    ShadowComparison,
+)
+from .server.config import CentralSettings
+from .server.db.mongo.schema import CENTRAL_MONGO_SCHEMA_REVISION
+from .server.errors import (
+    AuthorizationError,
+    ContentIntegrityError,
+    NotFoundError,
+    OperationStateError,
+    ServiceError,
+)
+from .server.http import CentralHttpApp, HttpCentralTransport, create_app
+from .server.object_storage import (
+    AlibabaCloudOssObjectStore,
+    InMemoryObjectStore,
+    ObjectStore,
+    S3ObjectStore,
+    StreamingObjectStore,
+)
+from .server.registries import (
+    CentralOperationState,
+    CleanupUploadRequest,
+    FinalizedUpload,
+    FinalizeUploadRequest,
+    IdempotencyRecord,
+    InMemoryRegistryCustody,
+    RegistryCustody,
+    StagedUpload,
+    StageUploadRequest,
+)
+from .server.registries.mongo_registry import CentralMongoRegistry
+from .server.registries.postgres_registry import (
+    CENTRAL_POSTGRES_SCHEMA_REVISION,
+    CentralPostgresRegistry,
+)
+from .server.schema import export_all_json_schemas, export_json_schema, schema_names
+from .server.services import (
+    ArtifactService,
+    BackupRestoreReadiness,
+    CentralAccessContext,
+    CentralService,
+    ContextSpaceAuthorizer,
+    RecoveryContentCheck,
+    RecoveryRecordCheck,
+    RecoveryRecordState,
+    RecoveryReport,
+    SpaceAuthorizer,
+)
+from .server.services.content_service import (
+    ContentVerificationState,
+    FinalizedContentInspection,
+    OrphanedObject,
+)
+
+__all__ = [
+    "API_SCHEMA_VERSION",
+    "CENTRAL_MONGO_SCHEMA_REVISION",
+    "CENTRAL_POSTGRES_SCHEMA_REVISION",
+    "CENTRAL_SCHEMA_REVISION",
+    "CENTRAL_SCHEMA_VERSION",
+    "AlibabaCloudOssObjectStore",
+    "ApiFailure",
+    "ApiRequest",
+    "ApiResponse",
+    "ApiSuccess",
+    "Artifact",
+    "ArtifactService",
+    "AuthorityCutoverRecord",
+    "AuthorityRollbackPointRecord",
+    "AuthorityRollbackRecord",
+    "AuthorizationError",
+    "BackupRestoreReadiness",
+    "CentralAccessContext",
+    "CentralClient",
+    "CentralClientError",
+    "CentralHttpApp",
+    "CentralMongoRegistry",
+    "CentralOperationState",
+    "CentralPostgresRegistry",
+    "CentralService",
+    "CentralSettings",
+    "CentralTransport",
+    "CleanupUploadRequest",
+    "Content",
+    "ContentIntegrityError",
+    "ContentVerificationState",
+    "ContextSpaceAuthorizer",
+    "DeclarationProvenance",
+    "DisclosurePackageRevision",
+    "DisclosureReceipt",
+    "DisclosureRevocation",
+    "DomainAuthorityGate",
+    "DomainAuthorityReadback",
+    "DomainAuthorityState",
+    "EvidenceReference",
+    "FdpClient",
+    "FdpConfig",
+    "FinalizeUploadRequest",
+    "FinalizedContentInspection",
+    "FinalizedUpload",
+    "HttpCentralTransport",
+    "IdempotencyRecord",
+    "InMemoryObjectStore",
+    "InMemoryRegistryCustody",
+    "InProcessCentralTransport",
+    "LineageDeclaration",
+    "LineageRelationType",
+    "MaterialTransfer",
+    "NotFoundError",
+    "ObjectStore",
+    "OperationStateError",
+    "OrphanedObject",
+    "Package",
+    "PackageMember",
+    "PackageRevision",
+    "RecoveryContentCheck",
+    "RecoveryRecordCheck",
+    "RecoveryRecordState",
+    "RecoveryReport",
+    "RegistryCustody",
+    "RegistrySpace",
+    "S3ObjectStore",
+    "ServiceError",
+    "ShadowComparison",
+    "SpaceAccess",
+    "SpaceAuthorizer",
+    "StageUploadRequest",
+    "StagedUpload",
+    "StaticMachineTokenAuthenticator",
+    "StaticMachineTokenBinding",
+    "StreamingObjectStore",
+    "UsageReceipt",
+    "WriteConflict",
+    "WriteCreated",
+    "WriteIdempotent",
+    "WriteResult",
+    "create_app",
+    "export_all_json_schemas",
+    "export_json_schema",
+    "schema_names",
+]
+
+__version__ = "0.3.0a2"

financial_data_protocol-0.3.0a3/src/financial_data_protocol/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())