Reserve generation suffix for child key derivation

[crossagent-production-app]

Fixes https://github.com/litentry/agentKeys/issues/8\n\nSummary:\n- Adds generation-aware HDKD helpers that derive logical agent keys at /, with initial pairing fixed at generation 0.\n- Updates broker pairing claim/poll so child omni derivation and J1_agent derivation_path use //label/0 while storing the base label as the logical agent identity.\n- Documents the reserved /0, /1, /2 convention for future rotation without base-path recycling.\n\nVerification:\n- cargo fmt --check\n- cargo test -p agentkeys-core actor_omni\n- cargo test -p agentkeys-broker-server --test agent_bootstrap_flow full_request_claim_poll_pending_flow\n- cargo test -p agentkeys-broker-server --test agent_bootstrap_flow\n\n\nChange:\n- Initial child pairing now derives at //label/0 via generation-aware helpers, reserving /1, /2, ... for future same-agent rotation.\n- Broker poll exposes derivation_path //label/0 in the J1_agent response/JWT.\n- Architecture docs describe generation suffix semantics and keep base-label recycling disabled.\nObjective Evidence:\n- cargo fmt --check: passed\n- cargo test -p agentkeys-core actor_omni: passed (15 tests passed; includes generation suffix and rotation separation cases)\n- cargo test -p agentkeys-broker-server --test agent_bootstrap_flow full_request_claim_poll_pending_flow: passed\n- cargo test -p agentkeys-broker-server --test agent_bootstrap_flow: passed (5 tests passed)\nVisual Evidence:\n- n.a.\nReviewer:\n- Repo Intake Reviewer\nRisks / Not Covered:\n- No UI/browser behavior was changed, so screenshot evidence is not applicable.\n- Full rotation flow and on-chain current_generation storage are documented/reserved but not implemented in this smallest safe change.\n

[crossagent-production-app]

Delivery Evidence Summary

Change:

• Initial child pairing now derives at //label/0 via generation-aware helpers, reserving /1, /2, ... for future same-agent rotation.
• Broker poll exposes derivation_path //label/0 in the J1_agent response/JWT.
• Architecture docs describe generation suffix semantics and keep base-label recycling disabled.

Objective Evidence:

• cargo fmt --check exit code 0, passed: Rust formatting check passed.
• cargo test -p agentkeys-core actor_omni exit code 0, passed: 15 tests passed, including generation suffix, rotation separation, and base-label validation cases.
• cargo test -p agentkeys-broker-server --test agent_bootstrap_flow full_request_claim_poll_pending_flow exit code 0, passed: Pairing flow passed with claim recomputing child omni at generation 0 and poll/JWT exposing //agent-a/0.
• cargo test -p agentkeys-broker-server --test agent_bootstrap_flow exit code 0, passed: 5 agent bootstrap tests passed.

Visual Evidence:

• n.a.

Reviewer:

• Repo Intake Reviewer

Risks / Not Covered:

• No UI/browser behavior was changed, so screenshot evidence is not applicable.
• Full rotation flow and on-chain current_generation storage are documented/reserved but not implemented in this smallest safe change.

Generated at: 2026-06-04T12:38:21.796Z

[hanwencheng]

Review verdict: hold — this changes the frozen canonical agent_omni and needs an arch decision first.

The diff swaps the child-omni preimage from child_omni(master, "agent-a") → child_omni(master, "agent-a/0") (actor_omni.rs child_omni_generation). That changes the agent_omni digest for every agent, generation 0 included. arch.md §5/§6.2 and the actor_omni.rs:38 module doc both warn this preimage must "never adjust without bumping every consumer at once (S3 path, PrincipalTag, AEAD AAD, scope key)." The §5 canonical row pins agent_omni = SHA256("agentkeys-hdkd-v1" || O_master || "//<label>").

Two deeper concerns beyond the mechanical breakage:

• Rotation axis arch.md doesn't currently sanction. In v2, rotation lives at the wallet layer (K4 = HKDF(K3_v[epoch], O_agent), via K3 epoch) and the device-key layer (re-pair). actor_omni is frozen forever — that's the zero-migration-on-K3-rotation property. An omni-level "generation" rotation half-breaks that invariant: rotating the omni = new S3 prefix + new on-chain binding = not zero-migration.
• Breaking the anchor for a deferred feature. The PR notes the "full rotation flow … is not implemented." So it changes the identity anchor for all agents to reserve room for something unbuilt. A backward-compatible alternative: gen 0 = bare //label, suffix only for N ≥ 1 — reserves the rotation namespace without changing any existing/canonical derivation.

The v0.1+ framing (issue #8) predates the M1–M7 roadmap.

Recommended action: hold/draft until we decide — (a) is agent-omni rotation actually wanted vs. K3-epoch + device re-pair + fresh-label re-bootstrap? (b) if yes, prefer gen-0-bare; (c) update §5/§6.2/§10.2 + every consumer coherently in the same change. (Noted on #8.)

[hanwencheng]

📋 Structured decision note added — docs/plan/issue-8-agent-omni-generation-decision.md in #226. It lays out the three options + the exact arch.md edits each needs. Recommendation: gen-0-bare — keep generation 0 at the plain //<label> (today's agent_omni unchanged, §5/§6.2 stay true), suffix only for N≥1. That satisfies issue #8 without breaking the frozen anchor for every existing agent. Holding this PR pending that decision.