# Migrating from Makoto v0.2 to v0.3

Makoto v0.3 is a separate protocol family. Existing v0.2 statements, bundles, policies, schemas, media types, and reports remain v0.2. Do not relabel them as v0.3.

The reference verifier supports both versions. It selects one family from the consumer policy and bundle, then rejects identifiers from the other family. A v0.3 graph cannot cite a v0.2 predecessor.

## Identifier changes

For new evidence, replace each Makoto-owned `/v0.2/` schema or predicate identifier with its `/v0.3/` counterpart. Use `0.3` for `version`, `schemaVersion`, and `reportVersion`. The v0.3 handoff media type is `application/vnd.makoto.handoff.v0.3+json`. The dataset-manifest media type is `application/vnd.makoto.dataset-manifest.v0.3+json`.

Authoring commands default to v0.2 for compatibility. Select v0.3 explicitly:

```bash
makoto attest origin \
--protocol-version 0.3 \
...
```

Use the same option with `attest transform` and `handoff create`.

## Standard licence claims

Generate the immutable standard profile reference:

```bash
makoto profile standard-license \
--out licence-profile.json
```

Attach that reference with `--profile`. The statement extension must contain one claim for each subject:

```json
{
  "https://usemakoto.dev/claim/v0.3/license": {
    "claims": [
      {
        "subjectName": "part-00000.parquet",
        "spdxExpression": "CC-BY-4.0",
        "evidenceUrl": "https://example.test/evidence.json"
      }
    ]
  }
}
```

Claims are sorted by `subjectName` and cover every statement subject exactly once. Add the profile's exact ID, digest, closure digest, and `target: "statement"` to a trust-policy rule's `profileConstraints` when the receiver requires it.

The signed claim records who vouched for the declaration. It does not prove that the licence is correct or that the data is legally usable.

## Record commitments

A v0.3 dataset-manifest entry may add `recordMerkle` with algorithm `rfc6962-sha256-record-digest-v1`, a positive `recordCount`, and a SHA-256 root.

Prepare a record declaration using sorted, non-overlapping byte ranges or an ordered record-hash list. Compute the manifest value with:

```bash
makoto record root \
--declaration records.json \
--entry shard.bin \
--json
```

After the signed bundle verifies under receiver policy, create a proof with `makoto record prove`. Verify it with `makoto record verify`. Supplying exact record bytes checks their digest. Supplying exact entry bytes checks the entry digest and extracts the proof's declared byte range.

Makoto treats record boundaries as producer declarations. It does not parse Parquet, CSV, or another data format.

## Keyless signing

v0.3 accepts Sigstore keyless identities beside pinned Ed25519 keys. Existing
Ed25519 policies and envelopes keep their meaning.

A receiver that authorizes keyless signatures must:

1. Add the exact identity constraint under `keylessIdentities`. GitHub Actions
   constraints include exact issuer, subject, repository, workflow ref, and
   event values.
2. Add that identity ID to `authorizedIdentityIds` in the applicable rule.
3. Pin the exact trusted-root bytes in `sigstoreTrustRoot.digest.sha256`.
4. Supply those bytes separately with `makoto verify bundle
   --sigstore-trust-root`. Verification never fetches a trust root or uses one
   from producer bundle contents.

`minimumSignatures` counts distinct passing IDs across `authorizedKeyIds` and
`authorizedIdentityIds`. A policy can therefore require one pinned key plus one
keyless workflow identity.

Producers can add a keyless signature to an in-toto statement envelope with
`makoto envelope keyless-sign`. The command uses an ambient OIDC credential and
may contact the configured Sigstore services. See
[`examples/github-actions/`](../examples/github-actions/) for a pull-request
workflow. The handoff envelope may still use pinned Ed25519 even when statement
rules authorize keyless identities.

The v0.3 identifier family was unreleased when this change landed: no v0.3 tag
or GitHub release existed. The envelope and trust-policy shapes were therefore
extended in place. A post-release change to accepted bytes or decisions needs
a new complete identifier family under the protocol versioning rule.

## Unchanged boundaries

v0.3 does not add index hierarchy, language fields, sharding, scheduling, or
AI-specific semantics. Those remain application or extension concerns.