# Makoto v0.2 integration boundary

v0.2 ships a protocol, reference CLI/library, and runnable handoff proof. Production adapters for
Airflow, Databricks, dbt, Kafka, Prefect, Spark, Dagster, and similar tools are intentionally not a
September milestone. The stable integration boundary is small enough for each tool to adopt
without embedding the verifier.

## Producer integration

At a pipeline boundary, an integration should:

1. snapshot the exact output bytes without following links or allowing them to change mid-read;
2. create one origin statement for newly observed data, or one transformation statement that
   binds every predecessor statement, predecessor subject, and exact input digest;
3. attach any organization-owned statement, predicate, or artifact profile references;
4. sign the statement with a key appropriate for that operation; and
5. persist the DSSE envelope beside the data or in the platform's provenance store.

At an organizational handoff, collect the exact reachable statements and final artifacts, create
an authorized signed handoff manifest, and package only the evidence and artifact bytes the
recipient needs. Private profile schemas may remain outside the bundle.

For partitioned datasets, author a canonical dataset-manifest JSON artifact, attest it with the
mandatory core dataset-manifest profile, and supply that manifest plus any transferred partitions
when creating the handoff:

```json
{
  "name": "selected-partition",
  "path": "part-000.json",
  "predecessor": "attestations/origin.dsse.json",
  "subjectName": "customers.dataset-manifest.json",
  "entryName": "year=2026/part-000.json",
  "predecessorMaterial": "customers.dataset-manifest.json"
}
```

`entryName` and `predecessorMaterial` are an inseparable pair. Before signing, the producer checks
that the predecessor attests the exact manifest bytes with the mandatory core profile and that the
named entry's digest and optional size match the input partition.

```bash
uv run makoto handoff create \
  --head attestations/final.dsse.json \
  --attestations attestations \
  --artifact-binding bindings/final.json \
  --artifact-material bindings/dataset-manifest-material.json \
  --dataset-entry-binding bindings/partition-000.json \
  --key keys/handoff.private.pem \
  --out handoff.bundle
```

Producer `--artifact-material` binding files contain exactly `statement`, `subjectName`, and
`path`; dataset-entry bindings contain exactly `manifestStatement`, `manifestSubjectName`,
`entryName`, and `path`. All paths inside a binding resolve relative to that binding file. The
producer verifies the manifest's signed subject digest, mandatory profile identity, entry digest,
and optional size before publishing the bundle.

`--artifact-material` is not dataset-specific. If the selected signed subject does not carry the
exact mandatory dataset-manifest profile, the producer packages it as ordinary historical
material. A receiver hashes and reports every authorized manifest-listed historical mapping,
including one from a statement that later proves unreachable; graph completeness denies that
unreachable statement independently. Reachable historical bytes targeted by a critical signed
artifact profile are required even when no transformation needs their content.

Dataset-entry files use
`artifacts/dataset-entries/<sha256(JCS(logical-identity))>.bin`. The logical identity contains
exactly `manifestStatementDigest`, `manifestSubjectName`, and `entryName`; it deliberately excludes
the member digest so a digest disagreement cannot create a second logical record or alternate
path.

## Consumer integration

A consumer should call the reference verifier with:

- the received bundle;
- receiver-owned trust policy and public keys;
- receiver-owned digest-pinned schema catalogs; and
- independent expected manifest, head, artifact, recipient, nonce, or age inputs required by
  policy.

Automate on the JSON report and process exit code. Do not scrape human wording. `ALLOW` means all
required checks passed under that exact policy and expectation set. Optional unavailable evidence
appears explicitly as warning, `indeterminate`, `not_checked`, or `skipped` detail rather than a
fabricated guarantee.

Expected heads alone do not select the complete final-artifact set: an authorized handoff signer
may add another terminal subject of an expected head. Consumers of sensitive pipelines should
require an independently obtained expected manifest digest or the complete expected-artifact
tuple set. The example demo supplies all three anchors so its `ALLOW` covers both graph and final
artifact selection.

Key validity is evaluated at the report's consumer-controlled evaluation time. Preserve the exact
trust-policy snapshot and its digest with every accepted report; otherwise routine key retirement
can make historical evidence unverifiable, while leaving retired keys authorized indefinitely
weakens compromise response. Use dedicated keys per Makoto claim role rather than reusing a broad
general-purpose signing key.

## Persistence guidance

An integration can store envelopes as sidecars, catalog records, object metadata pointers, or
rows in a provenance service. Storage location is not identity: statement and artifact digests
are. Preserve exact bytes. Never rewrite an earlier signed payload to append a step.

Statement and handoff identity deliberately hash decoded payload bytes, not the outer envelope.
Adding or removing a co-signature therefore does not change graph or manifest identity; signature
thresholds and the report expose whether the remaining envelope still satisfies receiver policy.

## Current support statement

The website integration pages are current lifecycle field notes, not installable adapters.
They identify stable artifact boundaries and platform context without claiming automatic hooks,
packages, or platform-native verification. PyPI `makoto` is unrelated and npm `@makoto/sdk` is
unpublished. Use the checked-out repository with `uv sync --locked --dev` and
`uv run makoto ...` until a future release explicitly publishes a supported distribution.

Any document processor can act as a complementary producer by emitting Makoto statements and
artifact profiles for its outputs. No named document tool is a Makoto protocol dependency.