Specify PackRebindEvent structured fields, rebind/validation-failure metrics, and diagnostic payloads (ADR 005)

[coderabbitai]

Background

ADR 005 (PR #9, branch 1-1-4-record-seeded-prng-choice) specifies that a PackRebindEvent is logged on PATCH-only silent rebind (Table 2, behaviour-on-load matrix) but does not define:

• The structured fields of PackRebindEvent (e.g. runId, fromContentHash, toContentHash, packId, fromVersion, toVersion, timestamp, rebindReason)
• Metrics for rebind rate and validation-failure rate (e.g. counters or gauges surfaced through the observability port)
• Diagnostic payloads for contentHash mismatch failures and PRNG contract violations (sufficient context for a developer to reconstruct what went wrong without a debugger)

A review check flagged this gap: the PR specifies operational behaviour (pack rebinding, validation) without the logging and diagnostic contracts needed to debug failures in production or in self-play pipelines.

Required work

When roadmap items 1.3.2 and 1.4.x implement the migration machinery, extend the observability specification to include:

1. PackRebindEvent schema — define all required fields; emit through the existing structured-logging/observability port (see issue Wire concrete observability implementations for appMachine named actions #8 for the port wiring).
2. PackValidationFailureEvent schema — emitted when contentHash differs and rebind is refused; include expected, actual, packId, version, and runId.
3. PrngContractViolationEvent schema — emitted when a saved run's prngContract field does not match the engine's compiled PRNG identity; include savedContract, engineContract, and runId.
4. Metrics — rebind success rate, validation-failure count per session, and PRNG contract violation count; expose through the metrics interface ratified in ADR 005 / the observability layer.

References

• PR Plan seeded PRNG choice and pack migration policy (1.1.4) #9 — Plan seeded PRNG choice and pack migration policy (1.1.4)
• Issue Wire concrete observability implementations for appMachine named actions #8 — Wire concrete observability implementations for appMachine named actions
• ADR 005: docs/adr-005-use-deterministic-simulation-and-parameter-packs.md, lines 254 and 279
• Roadmap items 1.3.2 and 1.4.x in docs/roadmap.md

Raised by @leynos via code-review check on PR #9.

[coderabbitai]

🔗 Related PRs

leynos/netsuke#302 - Overhaul Netsuke CLI documentation contract [merged]
leynos/beatcue#7 - Record BeatCue JSON schema decision (1.1.1) [merged]
leynos/beatcue#9 - Record object-tracking boundary (1.1.2) [merged]
#7 - Record XState machine collocation strategy (1.1.3) [closed]
leynos/weaver#141 - Add observability RFC roadmap tasks (#122) [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!