Skip to content

Adopt Modules + Drivers + Profiles + Packs + Probes as the Core Execution Architecture

Status

Proposed: Standardise HybridOps.Core around a stable module contract and a composable execution model that supports tarball-safe packaging, governed policy, and evidence-first runs.

1. Context

HybridOps.Core is the product runtime. It must provide:

  • A stable module contract that does not change when internal tooling or implementation strategy changes.
  • A consistent execution model that is tarball-safe (no implicit .git or repo-root dependencies).
  • Deterministic evidence paths suitable for support, auditing, and formal technical review.
  • A clean boundary between:
  • intent (what the module declares),
  • policy (how runs are governed),
  • implementation (what tool plan is executed),
  • verification (how success is validated).

The earlier “scenario-first” framing is superseded by a module-first execution contract. Modules are now the primary unit of consumption, selection, and compatibility.

2. Decision

HybridOps.Core adopts five first-class concepts.

2.1 Module

A Module is the smallest consumable unit of intent. A module declares:

  • inputs (schema + defaults)
  • execution selection:
  • execution.driver
  • execution.profile
  • execution.pack_ref.id
  • outputs publication mapping (outputs.publish)
  • probes (verification)
  • constraints and requirements

Modules are tool-agnostic. Modules MUST NOT contain backend/state wiring, workspace naming rules, tool CLI flags, or implementation sources.

2.2 Driver

A Driver is a tool integration adapter that:

  • resolves the referenced pack (execution.pack_ref.id)
  • creates an isolated work directory under the runtime root
  • invokes the required toolchain (Terragrunt/Terraform/etc.)
  • captures evidence (redacted where required)
  • normalises outputs for publishing

Drivers MUST be tarball-safe and MUST NOT assume repository layout beyond release-contained assets and explicit environment variables.

2.3 Profile

A Profile is a versioned policy bundle interpreted by a driver. Profiles define:

  • toolchain policy (binary selection, version constraints, invocation defaults)
  • backend/workspace naming rules (where applicable)
  • templates and hooks owned by the driver
  • execution defaults (timeouts, retries, logging controls)

Profiles are selected by modules but represent operational policy, not module intent.

2.4 Pack

A Pack is a replaceable implementation plan executed by the driver (for example, a Terragrunt stack tree).

Packs are selected by modules and resolved by drivers using a deterministic mapping rule. Packs MUST be runnable without repo-root inference.

2.5 Probes

A Probe is an automated verification step that:

  • validates the outcome using module-defined success criteria
  • produces a concise result summary
  • writes run records into the run evidence directory

3. Rationale

This architecture is adopted to achieve:

  • Stability: modules remain durable even as tooling changes.
  • Governance: profiles centralise operational policy without polluting modules.
  • Replaceability: packs allow implementation swaps without changing module contracts.
  • Verifiability: probes convert claims into repeatable checks with evidence.
  • Packaging: releases can ship a controlled set of drivers + profiles + packs.

4. Consequences

4.1 Positive consequences

  • Clear separation of intent, policy, implementation, and verification.
  • Consistent evidence and support workflow across modules.
  • Enables controlled distribution (ship selected packs without exposing the full source layout).
  • Scales across providers and domains while preserving a stable module contract.

4.2 Negative consequences / risks

  • Requires discipline to keep policy out of modules and business rules out of drivers.
  • Requires CI checks to enforce module/pack/profile boundaries.
  • Pack versioning and migration must be managed deliberately to avoid hidden breaking changes.

5. Alternatives considered

  • Scenario-first bundles: replaced by module contract + pack selection because the module is the stable unit of consumption.
  • Tool-first repository layouts: rejected due to coupling, drift, and weak packaging boundaries.
  • Embedding backend/workspace wiring in packs: rejected; backend/workspace naming is policy and belongs in profiles.

6. Implementation notes

  • Module resolution produces a single request payload: resolved inputs + selected execution refs.
  • Drivers resolve pack stack directories from (driver_ref, pack_ref.id) using a deterministic mapping rule.
  • Drivers run in an isolated workdir under runtime root and capture deterministic evidence.
  • Environment input overrides are supported for operator and CI workflows (explicitly defined and testable).

7. Operational impact and validation

  • Operators run modules through a stable interface and obtain deterministic evidence records.
  • Probes are the primary correctness signal for runs and CI gating.
  • Evidence is treated as a first-class output of every run.

8. References

Maintainer: HybridOps
License: MIT-0 for code, CC-BY-4.0 for documentation unless otherwise stated.