Skip to content

feat: fleet comms wire schemas (event envelope, channel metadata, message metadata) v1#15

Merged
andrei-hasna merged 2 commits into
mainfrom
feat/fleet-comms-contracts
Jul 7, 2026
Merged

feat: fleet comms wire schemas (event envelope, channel metadata, message metadata) v1#15
andrei-hasna merged 2 commits into
mainfrom
feat/fleet-comms-contracts

Conversation

@andrei-hasna

Copy link
Copy Markdown
Contributor

Summary

Registers three machine-validatable fleet comms wire schemas + validators per fleet comms workflow v1.1. Todos task: 41ea5a6e (parent tracking task 843cfb62). Wire schemas belong in open-contracts, not knowledge (v1.1 amendment 2; knowledge item hasna-knowledge-taxonomy).

Schemas (all .strict(), registry-integrated, hasna.*.v1 ids minted in contracts per governance decision #2, k_mr6fvzgm_wrcb2t)

  • hasna.comms_event_envelope.v1 — namespaced <source>.<entity>.<action> type (2-4 lowercase segments), severities info|notice|breaking|critical, scope fleet|package|machine, affected_packages/affected_machines, action_required, ack_by, mandatory dedupe_key. Cross-field rules: package scope requires affected_packages; machine scope requires affected_machines; ack_by requires action_required; fleet.freeze/fleet.unfreeze pinned critical + fleet-scoped + action-required.
  • hasna.comms_channel_metadata.v1 — the metadata.channel_schema object: class enum fleet|package|product|loop-lane|initiative|personal, noise quiet|work|firehose, initiative channels require owner + machine-evaluatable until horizon (ISO date, UTC timestamp, or gate:<todos-id>), archived-channel successor pointer.
  • hasna.comms_message_metadata.v1 — severity-tag metadata for [FREEZE]/[UNFREEZE]/[BREAKING]/[CUTOVER]/[POLICY]/[RELEASE] exact-case first-token posts; tag + full envelope ride in --metadata, never parsed from text; per-tag severity bounds; FREEZE/UNFREEZE pinned to fleet.freeze/fleet.unfreeze both directions.

Validators exported for hooks/loops/publishers (validate before emit/post)

  • One severity mapping table: COMMS_EVENT_TYPES / COMMS_SEVERITY_TAG_INFO (+ bijection consistency tests), defaultSeverityForCommsEventType.
  • extractCommsSeverityTag (exact-case first token), commsSeverityTagToken, validateCommsTaggedMessage (text token + metadata schema + tag/text match).
  • Generic registry paths work too: validateContract/parseContract/validateEmbeddedContract, CLI contracts validate --schema hasna.comms_event_envelope.v1 ....

Version: 0.4.1 -> 0.5.0 (additive minor). Human-facing rules live in knowledge items hasna-agent-comms-protocol / hasna-agent-comms-envelope; these schemas are the machine-validatable source of truth those items cross-reference.

Verification

  • bun run verify:release green: typecheck, 169 pass / 7 skip / 0 fail (baseline 142), conformance over all fixtures incl. the 6 new comms valid/invalid fixtures, build, dist smoke, pack dry-run.
  • Adversarial review (high effort, 8 angles) run on the diff: 2 findings surfaced and fixed in this PR (tag<->event-type bijection consistency tests; until horizon tightened from free-form string to date/timestamp/gate-id). Refuted candidates documented in the task log.
  • Note: bun test with a stale dist/ present fails pre-existing no-cloud-scan tests (repo-known; verify:release rm-rfs dist first). Not introduced by this PR.

Fixtures

6 new examples: comms-{event-envelope,channel-metadata,message-metadata}.{valid,invalid}.json wired into the examples + conformance suites with exact expected issue paths.

…sage metadata) v1

Registers three machine-validatable comms schemas per fleet comms
workflow v1.1 (todos task 41ea5a6e, parent 843cfb62):

- hasna.comms_event_envelope.v1: namespaced <source>.<entity>.<action>
  type, severities info/notice/breaking/critical, scope
  fleet/package/machine, affected_packages/affected_machines,
  action_required, ack_by, mandatory dedupe_key. fleet.freeze and
  fleet.unfreeze pinned critical + fleet-scoped + action-required.
- hasna.comms_channel_metadata.v1: channel_schema class enum
  (fleet/package/product/loop-lane/initiative/personal), noise class,
  initiative owner + machine-evaluatable until horizon (date or
  gate:<todos-id>), archived-channel successor pointer.
- hasna.comms_message_metadata.v1: severity-tag metadata for
  [FREEZE]/[UNFREEZE]/[BREAKING]/[CUTOVER]/[POLICY]/[RELEASE]
  exact-case first-token posts; envelope rides in --metadata, never
  parsed from text.

Ships the one severity mapping table (COMMS_EVENT_TYPES /
COMMS_SEVERITY_TAG_INFO with bijection tests), tag helpers
(extractCommsSeverityTag, commsSeverityTagToken), and
validateCommsTaggedMessage so hooks/loops/publishers validate before
emit/post. Valid/invalid fixtures + conformance + unit tests; README
catalog updated. @hasna/contracts 0.4.1 -> 0.5.0.
@andrei-hasna
andrei-hasna merged commit db60950 into main Jul 7, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant