[Enrique Saurez (esaurez)]

Stacked on #876; this PR retargets to dev when the pull requests below it merge. The chain on dev is #866 → #882 → #883 → #876 → #871 → #873 → #874, after #863, #864, #865, #867, #868, #869, #870, #872, #875, and #878, which have merged.

A clone that the host restores from a template keeps the template's captured configuration, so nothing tells its guest the image, upper, export, network, and workload view of its own launch, and nothing identifies the settings that a guest applied. This adds nvx::activation, the record of those settings and its limits, without features, beside nvx::protocol, so that the host, the guest, and every adapter's framing check it by the same rules. It changes no behavior: nothing builds, carries, or applies the record yet.

Part of #838: the first of its three pull requests. The second, #873, encodes the record canonically, and the third, #874, adds the encoding of Ready's activation and the conformance vectors, and removes the configuration identity, so that Ready reports only that the activation applied, and a clone's transaction ID.

What changed

The record (nvx-rs/src/activation/mod.rs). An ActivationRecord holds the schema's VERSION, a clone's RestoreSection, and the Configuration:

• the Image: EROFS or GPT, the Identity of the image's binding, the EROFS UUID or GPT disk GUID that the guest expects, if any, and a GPT disk's first-partition bound;
• the Upper: a tmpfs, or the scratch, with its binding's Identity and its Journal policy;
• the OverlayMode;
• an Export, a directory or an aggregate, with its plan's Identity, which covers the export's whole shape, and its 1 to 4,096 mappings;
• the Network: its policy's Identity, an optional DNS address, the listeners' Publication, in the vocabulary of nvx::guest::entry, and an optional proxy endpoint;
• the WorkloadView: the hostname, the MachineIdMode, the image's own machine ID or a generated one, and an optional WorkloadIdentity, a UID and a GID, neither 0 nor u32::MAX;
• the ExpectedResources: the CPU count and the memory size that the guest must have.

A clone's RestoreSection holds the restore's 16-byte TransactionId and the TemplateReference: the template's StoreGeneration, the nonzero publication ID that its store assigns in the order of publication and never reuses, and the Identity of the template's key. An Identity is 32 bytes that the host computes, such as the SHA-256 digest of an object's canonical form; the record never holds the objects that identities name. ReadyActivation is what Ready reports: the ConfigurationIdentity, which #874 removes so that nothing hashes the record, and a clone's transaction ID.

The other inputs of the root's assembly are invariants of the template, as the module documents: the runtime directory, the block devices' MMIO windows and sizes, the GPT partitions that the guest expects, of which there are none, and how long the guest waits for its devices. Secrets, per-execution environments, and host mapping tables never enter the record.

The limits are public constants: MAX_RECORD_BYTES (1,024), MAX_MAPPINGS (4,096, protocol::MAX_HOST_MAPPINGS), MAX_HOSTNAME_BYTES (64), and MAX_PROXY_ENDPOINT_BYTES (255). ActivationRecord::new admits a configuration only once Configuration::check finds that it keeps them, and otherwise reports the first one broken, in the order of the fields. Besides each limit, an export without mappings, mappings without an export, and a zero UID or GID, it refuses:

• a UID or GID of u32::MAX, which the kernel reads as an unchanged ID, and which the guest's entry and the managed agent refuse;
• a hostname with a NUL, as the guest's entry does;
• a proxy endpoint with anything other than visible ASCII characters, or with an @, which would start credentials;
• a zero CPU count, memory size, or first-partition bound, which no guest matches.

Documentation. The module documentation describes the configuration, the template's invariants, and the limits, with an example. The crate's README and doc/project-structure.md list the module.

Tests (nvx-rs/src/activation/tests.rs): each limit at and past its edge; an export without mappings and mappings without an export, refused; a UID or GID of 0 or u32::MAX, refused, each alone; a configuration with every part at its limit, admitted; cold-boot and clone records; the order in which limits are reported; the errors' messages; the opaque values' bytes and hexadecimal forms; and store generations, nonzero numbers that compare in the order of publication and display in decimal.

Validation

At 3032e6d, the head, rebased onto #876 without changes to the contents of its commits, on Windows and on Linux x86_64:

• cargo fmt --check; cargo clippy with --all-targets --all-features, --lib, and --lib --no-default-features, -D warnings; cargo test with all, default, and no features; cargo doc with -D warnings; cargo +1.89 check;
• the runtime adapter's protocol-only and host-only configurations, and, on Linux, its guest-only configuration;
• aci_edge_sandboxes' checks;
• on Linux, also the bundled artifacts test, the macOS check of both crates, the guest binaries' lint, tests, build, and check, and the Markdown link check.

At each of the three commits, cargo clippy with --all-targets --all-features, --lib, --lib --no-default-features, and --lib --no-default-features --features guest, -D warnings, passed on both systems.

Before the rebase, on dev, the same checks passed at the first and the third commits, and at the heads of #873 and #874 that contained the second, which answers the review, and CI passed at the third, in run 40121956945. At the first commit, one test outside this change failed once on Linux, in the all-features run on a busy host: guest::cgroup::tests::settlement_collects_statuses_between_its_checks_until_the_deadline, whose collections.get() > 1 assertion races a 50 ms deadline. At the same head, it passed 50 of 50 runs alone, and the all-features suite passed 3 of 3 runs. While this pull request targets #876's branch, dev's CI doesn't run on it.

The third commit makes the StoreGeneration the nonzero number that the template store of #839 assigns to each publication, in place of 16 opaque bytes, so that a record names a template's generation in the store's own terms.

The guide sections that #838 names follow the numbering of #591, which isn't on dev, so the record is documented in the module and the crate's README.

[Copilot]

🟡 Changes recommended

Workload identity validation accepts u32::MAX, which the existing guest entry rejects.

1 open issue

• Reject u32::MAX workload IDs in ActivationRecord::new · New

What changed in this PR

Introduces feature-independent nvx::activation types and limits for layered-root configuration, the first step of #838. Encoding, identity calculation, transport, and application remain outside this PR.

Changes:

• Defines activation records, restore references, configuration settings, and Ready metadata.
• Adds validation and tests for limits, invalid combinations, and opaque identifiers.
• Documents the module in the crate and repository guides.

File	Description
nvx-rs/​src/​lib.rs	Exposes and documents the activation module without feature gates.
nvx-rs/​src/​activation/​tests.rs	Tests boundaries, validation errors, record variants, and identifiers.
nvx-rs/​src/​activation/​mod.rs	Defines activation types, public limits, and validation.
nvx-rs/​README.md	Documents the activation API and feature-independent availability.
doc/​project-structure.md	Adds activation to the repository layout.

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

The additive data model has focused validation and boundary coverage, with no unresolved findings or runtime behavior changes.

No open issues 🎉

1 resolved since last review

• Reject u32::MAX workload IDs in ActivationRecord::new

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

The additive contract and boundary tests have no unresolved findings, and the prior workload-ID validation issue is fixed.

No open issues 🎉

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

The additive model matches the stated scope, has thorough boundary tests, and has no unresolved blocking findings.

No open issues 🎉

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

The additive types and validation match the stated scope, cover boundary conditions, and resolve the prior workload-ID issue without changing runtime behavior.

No open issues 🎉

_{Review effort: Balanced}