Skip to content

operations-catalog: version-bump + mutation metadata for mesh/plugin/approval ops (deferred from PR #98) #101

Open

Description

@brbrainerd

Deferred from CodeRabbit review on #98 — these target the generated SSOT contracts/operations/catalog.v1.yaml, so they must be fixed at the operation-definition/generator source (never hand-edited) and require deliberate policy decisions.

1. Bump x-vox-version (catalog) — #98 thread

PR #98 added operations (mesh.nodes, mesh.dispatch, plugin.install, plugin.remove, approvals.resolve) but the catalog's x-vox-version stayed at 2. Per the contract-versioning guideline, bump it. Note the value isn't a literal in operations_catalog.rs (it's preserved/derived) — determine the version-emission path before changing, so a regeneration carries it forward.

2. Mutation metadata for new ops — #98 thread

mesh.dispatch, plugin.install, plugin.remove, approvals.resolve currently have side_effect_class, scope_kind, reversible = null, leaving the catalog too vague for policy/approval/UX consumers. These fields flow from p.side_effect_class (a policy source) in crates/vox-cli/src/commands/ci/operations_catalog.rs. Populating them needs product/policy decisions:

  • mesh.dispatch: side-effect class? scope (control-plane/system)? reversible (likely false)?
  • plugin.install / plugin.remove: state_change; scope (workspace/repository); reversible?
  • approvals.resolve: state_change; scope (approval); reversible (likely false)?

Also broaden the mesh.dispatch description to mention bundle execution (not just .vox script) — #98 minor thread.

Why deferred

The env-vars contract bump and all code-level review items were fixed in #98. These two require source-level operation-policy definitions on a generated file; guessing the mutation semantics risks shipping wrong policy metadata. The #98 contract change is additive/non-breaking, so it can merge while this is resolved separately.

Activity

  1. brbrainerd commented on Jun 13, 2026

    @brbrainerd
    CollaboratorAuthor

    Partially addressed in #284 (merged): mutation metadata (side_effect_class/scope_kind/reversible) populated for mesh.dispatch, plugin.install, plugin.remove, approvals.resolve; derived artifacts regenerated; ssot-drift clean.

    Remaining (deferred): the x-vox-version header bump is NOT a YAML edit — x-vox-version isn't a field on the OperationsCatalog struct (additionalProperties:false), so operations-sync --target catalog --write would strip it. Needs: (1) add #[serde(rename="x-vox-version")] field + propagate in build_catalog_from_live_registries, (2) reconcile the content-counter (2→3) vs the filename-derived version-header-parity guard (expects 1). Tracking here.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions