Skip to content

Declarative binding upgrades and retained chains

Changing YAML, replacing plugin JARs, and activating a new profile are different operations. None is an implicit migration of retained state. This guide concerns the experimental declarative-composite provider; start with the binding guide and authoring CLI.

Keep the exact Yano Maven version and matching ordinary JVM ZIP, the Yano X distribution and manifested plugin bundles, the authored document, canonical IR, canonical profile bytes and digest, and the sealed <app>.chain file. Preserve the chain’s genesis identity and retained stores independently of these artifacts. The composite, stdlib and role-workflow bundles declare minLevel: 12: they need plugin API level 12 with the ADR-031.3 and ADR-031.4 host contract (stateless kernel admission, kernel-declared rule facts, value views and write views). No Yano release contains that contract yet, and level 12 alone does not identify it, because the typed-view API was added to level 12 without a new level. API compatibility alone does not promise consensus-profile compatibility.

Admission rules make kernel facts consensus inputs. A bundle that changes which facts a kernel declares, or how it computes them, changes the outcome of rules that read them, even when the profile still reconstructs; treat it as a consensus change and qualify it with replay, not only profile-check.

The profile is not determined by YAML text or IR bytes alone:

InputConsequence of changing it
Omitted authoring limitsRecompilation selects the compiler’s current defaults; IR and profile identity can change
Kernel configuration descriptorDefaults are materialized before hashing; newly required defaults can make old IR fail construction
Machine applicationVersionIncluded in the component descriptor and therefore the profile commitment
Machine query subjectsCollected into the component descriptor; even an added query can change the profile commitment
Workflow execution versionPins the binding execution semantics, independently of the IR wire layout
Component/workflow generation heights, routes and quotasCommitted parts of the executable profile, not local tuning settings

Decoding existing IR does not substitute new limits. Conversely, recompiling the same YAML with a different tool or bundle set is not evidence of identical IR, descriptors or execution. Compare the actual canonical artifacts. The sealed <app>.chain file carries the chain’s composite settings and the digest of every plugin bundle it runs on; appchain join and appchain start refuse a node whose bundles differ instead of accepting replaced bundles silently.

The current provider constructs workflow and profile version 1.2.0. ADR-031.3 (admission rules) amended the version-one binding IR, expression dialect and receipt layouts in place: every amended structure changed its array arity, so IR and receipts written by the 1.1.0 or 1.0.0 runtimes fail decode with an explicit “predates ADR-031.3” error instead of being misread. Lazy baseline materialization, source-versus-derived work accounting, and pre-kernel reservation rules also differ from the earlier experimental 1.0.0 runtime.

ADR-031.4 (typed views) then amended the rule layout in place again, without changing the version: each rule gained its reads, and a receipt’s rule failure gained the index of the deciding write. IR whose admission rules were written before ADR-031.4, and receipts that record a rule failure in the earlier layout, fail decode with an explicit “predates ADR-031.4” error. Documents without rules and receipts without a rule failure are unaffected. Because the version still reads 1.2.0, the version alone does not tell you which layout a retained chain wrote; run profile-check against the candidate bundles.

The stock provider does not select an old workflow implementation from a version field in IR, and it cannot decode pre-ADR-031.3 IR at all: supplying an earlier deployment’s original IR in machines.composite.binding-ir-catalog[...] fails construction. No ADR-015 epoch from pre-ADR bytes is supported. Likewise, one currently selected machine provider cannot automatically supply both its old and new descriptor/implementation merely because both IR documents are present.

Declarative composition is experimental. Re-create a 1.1.0 or 1.0.0 chain, or a 1.2.0 chain whose rules predate ADR-031.4, from its YAML with this release; do not upgrade it in place. Keep a retained chain on its exact qualified runtime, or design and independently qualify a migration. A fresh chain with a new identity is a separate deployment, not preservation of the old history. Do not delete state, rewrite profile markers, regenerate a retained genesis identity, or change fixed to governed to bypass validation.

Compatible evolution within an executable catalog

Section titled “Compatible evolution within an executable catalog”

The provider supports a bounded catalog: the genesis IR in machines.composite.binding-ir plus contiguous indexed dormant entries in machines.composite.binding-ir-catalog[0], [1], and so on, with at most 64 profiles including genesis. This can support compatible binding changes when the installed runtime can reproduce every required historical profile exactly. It is not arbitrary plugin hot reload.

For a chain created in governed mode, the existing profile-governance runbook supplies the proposal, chunk/seal, approval, all-member readiness and exact-height activation protocol. Before using it for a declarative profile:

  1. Reconstruct the retained active and historical profiles with the candidate bundle set and compare their canonical bytes and digests. Stop on a mismatch.
  2. Include the target alongside all profiles required for replay and late effect results. Export and independently review its canonical profile bytes.
  3. Use a new workflow generation height for changed binding IR. Changed component configuration requires a new component generation. A generation height does not migrate incompatible state or replace a leaf’s stored genesis; such changes may need a new component instance and an explicit migration.
  4. Qualify replay, restart, historical proofs, activation-height cutover and outstanding effect/result handling with the complete catalog.
  5. Deploy the qualified catalog everywhere before proposing its exact target digest. Follow the existing approval/readiness protocol; do not infer readiness from a successful local compile.

Historical executable profiles must remain available. An on-chain approval does not manufacture a missing implementation or authorize an unimplemented state migration. In particular, this protocol alone cannot bridge any of the stock provider’s earlier boundaries: versions 1.0.0 and 1.1.0, or rules written before ADR-031.4.

Check a candidate bundle set without touching retained state

Section titled “Check a candidate bundle set without touching retained state”

The read-only profile-check command now tests exact reconstruction through the installed candidate plugin catalog:

Terminal window
./yano.sh appchain bindings profile-check \
--profiles retained-profiles.json --context context.json \
--plugins-directory /absolute/path/to/candidate/plugins

retained-profiles.json is a JSON array of canonical profile hex strings, genesis first, followed by every distinct historical or target profile being checked. Supply 1-64 entries, each at most 65,536 decoded bytes. Empty, duplicate, noncanonical, schema-v1, or non-declarative profiles are rejected. Export these artifacts from your independently trusted deployment records or qualified profile query/proof tooling; this command does not authenticate their origin.

Use the explicit chain identity, consensus profile and membership context described in the CLI guide. More than one profile requires settings["membership.mode"] to be "governed". The checker selects governed catalog construction itself; arbitrary machines.* overrides remain rejected. This does not change any deployed chain’s mode.

The checker extracts each profile’s explicit IR, constructs the catalog through the actual selected provider, and queries each expected profile using a synthetic read-only profile marker. It reports expected digests and per-profile results. Exit 0 and reproducesProfiles: true mean all supplied profiles are byte-for-byte reconstructible. Exit 2 means invalid or incompatible input; construction and missing-profile diagnostics identify failed checks. Step through a passing check and the ways it fails:

What profile-check provesIllustrative data

What you're seeing: a read-only preflight before you change plugin bundles for a retained chain. Step through a passing check, then the ways it fails.

  1. Gather the profiles Export the retained chain’s canonical composite profiles from records you trust: genesis first, then every historical or target profile you need. That is 1 to 64 hex strings. The checker does not authenticate where they came from, and it opens no retained store.
    ./yano.sh appchain bindings profile-check --profiles retained-profiles.json --context context.json --plugins-directory /absolute/path/to/candidate/plugins
  2. Decode each profile Each entry must be a declarative schema-v2 profile with explicit binding IR, and that IR must decode with this build. Duplicates are refused.
    • passes: Declarative schema-v2 profile with explicit IR
    • passes: IR decodes with this build
    • passes: No duplicate profile
  3. Check the context Use the chain’s original explicit context. More than one profile needs membership.mode set to governed in its settings; the checker then builds a governed catalog itself. It changes no deployed chain’s mode.
    • passes: Several profiles: membership.mode is governed
  4. Build the candidate catalog The checker opens the candidate plugin directory through the real host catalog and constructs the declarative-composite provider with every profile’s IR. This runs the installed plugins’ code, unsandboxed: check only bundles you trust.
  5. Compare byte for byte For each profile, a synthetic read-only marker holds that profile, and the candidate answers the query composite/active-profile-v1. Its bytes must equal the bytes you supplied. They do.
    • passes: Candidate returns the same canonical profile bytes
  6. Read the verdict Exit 0 and reproducesProfiles: true: every supplied profile is reconstructible byte for byte. That is all it proves. It is not replay, migration, proof verification or semantic equivalence.

What if: Rules from before ADR-031.4

A profile written by an earlier experimental runtime.

  1. Gather the profiles Export the retained chain’s canonical composite profiles from records you trust: genesis first, then every historical or target profile you need. That is 1 to 64 hex strings. The checker does not authenticate where they came from, and it opens no retained store.
    ./yano.sh appchain bindings profile-check --profiles retained-profiles.json --context context.json --plugins-directory /absolute/path/to/candidate/plugins
  2. Decode each profile This IR has admission rules written before ADR-031.4 changed the rule layout in place. It fails to decode with “binding IR predates ADR-031.4”. The execution version still reads 1.2.0, so the version number gives no warning.
    • passes: Declarative schema-v2 profile with explicit IR
    • fails: IR decodes with this build predates ADR-031.4
    • not reached: No duplicate profile
  3. Exit 2 The tool reports “Profile input is invalid” and exits 2. This build cannot run that chain. Re-create an experimental chain from its YAML, or keep it on its exact qualified runtime.

What if: The candidate builds different bytes

The new bundles construct, but not the same profile.

  1. Gather the profiles Export the retained chain’s canonical composite profiles from records you trust: genesis first, then every historical or target profile you need. That is 1 to 64 hex strings. The checker does not authenticate where they came from, and it opens no retained store.
    ./yano.sh appchain bindings profile-check --profiles retained-profiles.json --context context.json --plugins-directory /absolute/path/to/candidate/plugins
  2. Decode each profile Each entry must be a declarative schema-v2 profile with explicit binding IR, and that IR must decode with this build. Duplicates are refused.
    • passes: Declarative schema-v2 profile with explicit IR
    • passes: IR decodes with this build
    • passes: No duplicate profile
  3. Check the context Use the chain’s original explicit context. More than one profile needs membership.mode set to governed in its settings; the checker then builds a governed catalog itself. It changes no deployed chain’s mode.
    • passes: Several profiles: membership.mode is governed
  4. Build the candidate catalog The checker opens the candidate plugin directory through the real host catalog and constructs the declarative-composite provider with every profile’s IR. This runs the installed plugins’ code, unsandboxed: check only bundles you trust.
  5. Compare byte for byte For each profile, a synthetic read-only marker holds that profile, and the candidate answers the query composite/active-profile-v1. Its bytes must equal the bytes you supplied. Here they differ: for example, a machine’s applicationVersion or its query subjects changed, and both are part of the component descriptor.
    • fails: Candidate returns the same canonical profile bytes
  6. Exit 2 That profile reports reproducesProfile: false with “candidate returned different canonical profile bytes”, and the tool exits 2. Do not deploy these bundles to the retained chain.

What if: Two profiles, fixed membership

The context still describes a fixed-membership chain.

  1. Gather the profiles Export the retained chain’s canonical composite profiles from records you trust: genesis first, then every historical or target profile you need. That is 1 to 64 hex strings. The checker does not authenticate where they came from, and it opens no retained store.
    ./yano.sh appchain bindings profile-check --profiles retained-profiles.json --context context.json --plugins-directory /absolute/path/to/candidate/plugins
  2. Decode each profile Each entry must be a declarative schema-v2 profile with explicit binding IR, and that IR must decode with this build. Duplicates are refused.
    • passes: Declarative schema-v2 profile with explicit IR
    • passes: IR decodes with this build
    • passes: No duplicate profile
  3. Check the context Use the chain’s original explicit context. More than one profile needs membership.mode set to governed in its settings; the checker then builds a governed catalog itself. It changes no deployed chain’s mode.
    • fails: Several profiles: membership.mode is governed
  4. Exit 2 Every profile reports “candidate catalog construction failed”, and the tool exits 2. Supply the governed context the chain actually uses.
  • operator
  • offline tool
  • candidate plugins
  • passes
  • fails

No retained stores are opened, no machine initialization or block application is performed, and no submission, network access or signing is requested. As with other catalog tools, installed Java plugins are trusted executable code, not sandboxed data. A successful check is not state migration, replay qualification, proof verification, or proof of binary semantic equivalence. Omitting a historical profile cannot establish that it is safe to remove.

The current bindings compile, validate, graph, and dry-run commands construct a fixed genesis profile. They are useful for command and cascade rehearsal, but do not qualify a governed epoch transition or migrate a retained chain. The sealed bundle digests detect changes: appchain join and appchain start refuse a changed plugin bundle until the operator accepts it with join --accept-bundles. Detecting a change does not make it compatible.

profile-check supplies a fail-closed reconstruction preflight, not an installer or migration planner. There is no general declarative command that installs old and new workflow implementations side by side, exports a complete historical migration catalog, or proves arbitrary plugin upgrades compatible. Those capabilities require explicit version-addressable implementations and additional tooling and tests. Until then, treat bundle or execution-version changes as a compatibility review, not a routine YAML edit.