Migrate a configuration explicitly

The pre-release bonvoyage-config migrate operation applies one explicitly selected, release-shipped configuration-schema migration. It runs offline, does not contact a gateway, and never chooses a target version automatically.

Check a version 1 document

From the repository’s control-plane/ directory:

go run ./cmd/bonvoyage-config migrate \
  --input ../config/examples/local.yaml \
  --from-schema-version 1 \
  --to-schema-version 1

An accepted result identifies the exact input bytes and returns them unchanged:

{
  "operation": "migrate",
  "status": "accepted",
  "result": {
    "kind": "migration",
    "from_schema_version": 1,
    "to_schema_version": 1,
    "changed": false,
    "document": "...",
    "document_sha256": "..."
  }
}

document_sha256 identifies the exact returned bytes. For the current no-change pair it equals the input SHA-256 identity.

Read explicit standard input

Standard input must be selected deliberately and given a bounded source name:

cat ../config/examples/local.yaml | go run ./cmd/bonvoyage-config migrate \
  --stdin \
  --source-id local.yaml \
  --from-schema-version 1 \
  --to-schema-version 1

The source document must declare snapshot.schema_version: 1; the declaration must match --from-schema-version. A mismatch is refused with BV_CFG_VERSION_MISMATCH.

Migrate and validate a working copy

Migration proves only that the selected version pair exists and that the input is safely parseable. It deliberately does not require the old document to pass the current semantic compiler, because a future old schema may contain fields that the current schema no longer accepts.

For a complete first-run sequence, create a disposable working copy, migrate that copy explicitly, and validate the resulting file with the same installed release:

cp ../config/examples/local.yaml /tmp/bonvoyage-migrated.yaml

go run ./cmd/bonvoyage-config migrate \
  --input /tmp/bonvoyage-migrated.yaml \
  --from-schema-version 1 \
  --to-schema-version 1 \
  --in-place

go run ./cmd/bonvoyage-config validate \
  --input /tmp/bonvoyage-migrated.yaml \
  --require-configuration-schema-version 1

The current 1 to 1 pair leaves the working copy unchanged. The sequence is still useful because it demonstrates the required review boundary for a future transforming migration without modifying a tracked example.

An accepted migration is not an accepted configuration, deployment, ACK, activation, or traffic result.

Use in-place mode carefully

--in-place requires --input and rejects symlinks. For the current no-change pair, BonVoyage verifies the regular-file boundary but does not replace or modify the file. Use a working copy as shown above before evaluating this mode.

Prefer separate output and review even after a future transforming migration is shipped. Read-only migration may follow a symlink that resolves to a regular YAML file; mutation may not.

Safety and compatibility

Input is UTF-8, at most 1 MiB, and exactly one YAML document.
YAML aliases and merge keys are rejected.
The source and target versions are mandatory, nonzero 32-bit values.
Known secret-reference fields must contain filenames, not pasted PEM or private-key material; literal key material is rejected without echoing it.
Product, compiler, and configuration-schema requirements may be pinned with the same --require-* flags as validation.
Unsupported pairs never modify the selected input.

Exit	Status	Meaning
`0`	`accepted`	The explicit pair exists and the complete migrated document was returned.
`2`	`rejected`	The input violated parsing, size, encoding, file, or secret-safety rules.
`3`	`refused`	The declared source, requested pair, or exact installed-version requirement did not match.
`4`	`failed`	The selected input could not be read or the result could not be written.
`70`	`failed`	An internal invariant failed.