Metadata-Version: 2.5
Name: axiom-data-pipeline-orchestrator
Version: 3.0.4
Summary: Meridian-only durable execution authority for the Axiom runtime
Project-URL: Homepage, https://github.com/zephytiju/AxiomDataPipelineOrchestrator
Project-URL: Repository, https://github.com/zephytiju/AxiomDataPipelineOrchestrator.git
Author-email: Juntai Team <dev@juntai.com>
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: axiom-data-pipeline-topology==3.0.0
Requires-Dist: axiom-data-workflow==2.1.0
Requires-Dist: fastapi==0.141.1
Requires-Dist: juntai-usage==2.0.0
Requires-Dist: meridian-storage-core==1.0.0
Requires-Dist: meridian-storage-evidence==1.0.0
Requires-Dist: meridian-storage-object-common==1.0.0
Requires-Dist: meridian-storage-semantics==1.0.0
Requires-Dist: meridian-storage-streaming==1.0.0
Requires-Dist: pydantic==2.13.4
Requires-Dist: uvicorn==0.52.1
Description-Content-Type: text/markdown

# Axiom Data Pipeline Orchestrator

[简体中文](README_zh.md) · [Development](DEVELOPMENT.md)

This repository is the sole durable execution authority for Axiom Runtime. Version
3 accepts workload-authorized internal commands and progress events, binds every
execution to exact immutable Definition, topology, Driver, language, runtime, and
applicable query-schema references, and records all state through logical Meridian
Resources.

## Authority boundaries

The package owns execution identity and transitions, attempts, raw-ingress identity,
checkpoint epochs and forward heads, coverage receipts, sparse gaps, redrive and
waiver intent, cancellation, projections, and replay-safe evidence.

It does not own public Definition or Operations APIs, worker execution, physical
storage, provider clients, Engines, Adapters, credentials, or infrastructure. The
application deployment package supplies a configured Meridian composition and a
workload authorizer.

## Meridian Resources

- `structured` is authoritative for commands, executions, runtime events, raw
  ingress, checkpoint epochs, coverage, gaps, projections, and the outbox.
- `object` verifies exact immutable raw payload references before a raw ledger row
  is committed.
- `streaming` carries idempotent dispatch, cancellation, progress, raw-availability,
  checkpoint, redrive, and waiver events.
- `evidence` receives append-only audit records from the same durable outbox.

Outbox delivery is intentionally at least once. A stable outbox identity is reused
after a crash between publication and delivery marking, so conforming Meridian
Bindings deduplicate the replay. Read-facing snapshots come from projections rather
than the command-side execution row.

Every initial and retry dispatch carries an execution-scoped `usageContext` built
from the durable application, workflow, execution, attempt, exact topology, and
exact Driver identities. Worker hosts pass that context to the Driver; neither a
resource request nor a Usage/exporter endpoint is used as actual-use evidence.

## Checkpoint semantics

Checkpoint authority is scoped by source binding, source fingerprint, logical
partition, and epoch. `RECORDS_ONLY` input can land and dispatch raw records but
never moves a forward head or closes a gap. `COMPLETE_WINDOW` receipts advance the
head monotonically; a disjoint jump creates an explicit bridge gap in the same
transaction. Later complete overlap closes a gap without rewinding the head.

Raw records from remote acquisition and supplied-raw import use the portable
`canonical_raw_identity` from `axiom-data-workflow==2.1.0`, so equal content and
source identity converge on one ledger record while conflicting bytes fail closed.

## Internal service

The service exposes only `/internal/v1/*` routes, including:

- `POST /internal/v1/executions`
- `POST /internal/v1/executions:snapshots`
- `POST /internal/v1/execution-events`
- `POST /internal/v1/raw-ingress`
- checkpoint, coverage, gap search, redrive, waiver, and cancellation operations

The production image exports the stable zero-argument factory
`juntai.axiom.data_pipeline.orchestrator.composition:create`. The deployment sets
`AXIOM_COMPOSITION_FACTORY` to that release-owned path and provides
`AXIOM_RUNTIME_DEPENDENCIES_FACTORY=module.path:factory`. The dependency factory
returns the typed, credential-opaque workload identity, authorizer, Configuration
and Artifact clients, and logical Runtime Resources supplied by Vangu. The
production factory starts the injected `MERIDIAN_CONFIG`, verifies every required
logical binding before readiness, and returns the existing
`(AxiomRuntime, WorkloadAuthorizer)` tuple.

Physical Meridian Engine selection, provisioning, target state, and credential
material remain exclusively outside this repository and outside both factory
paths.

## Verification

```bash
python -m pytest
ruff check src tests acceptance scripts
python scripts/check_dependency_boundaries.py
python scripts/verify_contracts.py
python -m build
```

The acceptance fixtures run the same crash, retry, overlap, disjoint-window,
deduplication, cancellation, and recovery scenarios against multiple conforming
logical Binding implementations.
