Design Principles & Invariants

These principles are inviolable and MUST be reflected in all code, UI, documentation, and audit artifacts.

Core Principles

Principle 1: Release Identity via Digest

INVARIANT: A release is a set of OCI image digests (component → digest mapping), never tags.

Implementation Requirements:

Principle 2: Determinism and Evidence

INVARIANT: Every deployment/promotion produces an immutable evidence record.

Evidence record contains:

Evidence enables:

Implementation Requirements:

Principle 3: Pluggable Everything, Stable Core

INVARIANT: Integrations are plugins; the core orchestration engine is stable.

Plugins contribute:

Core engine provides:

Implementation Requirements:

Principle 4: No Feature Gating

INVARIANT: All plans include all features. Limits are only:
- Number of environments
- Number of new digests analyzed per day
- Fair use on deployments

This prevents:

Implementation Requirements:

Principle 5: Offline-First Operation

INVARIANT: All core operations MUST work in air-gapped environments.

Implications:

Implementation Requirements:

Principle 6: Immutable Generated Artifacts

INVARIANT: Every deployment generates and stores immutable artifacts.

Generated artifacts:

Version sticker enables:

Implementation Requirements:

Architectural Invariants (Enforced by Design)

These invariants are enforced through database constraints, code architecture, and operational controls.

InvariantEnforcement Mechanism
Digests are immutableDatabase constraint: digest column is unique, no updates
Evidence packets are append-onlyEvidence table has no UPDATE/DELETE permissions
Secrets never in databaseVault integration; only references stored
Plugins cannot bypass policyPolicy evaluation in core, not plugin
Multi-tenant isolationtenant_id FK on all tables; row-level security
Workflow state is auditableState transitions logged; no direct state manipulation
Approvals are tamper-evidentApproval records are signed and append-only

Database Enforcement

-- Example: Evidence table with no UPDATE/DELETE
CREATE TABLE release.evidence_packets (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id UUID NOT NULL REFERENCES tenants(id),
    promotion_id UUID NOT NULL REFERENCES release.promotions(id),
    content_hash TEXT NOT NULL,
    content JSONB NOT NULL,
    signature TEXT NOT NULL,
    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
    -- No updated_at column; immutable by design
);

-- Revoke UPDATE/DELETE from application role
REVOKE UPDATE, DELETE ON release.evidence_packets FROM app_role;

Code Architecture Enforcement

// Policy evaluation is ALWAYS in core, never delegated to plugins
public sealed class PromotionDecisionEngine
{
    // Plugins provide gate implementations, but core orchestrates evaluation
    public async Task<DecisionResult> EvaluateAsync(
        Promotion promotion,
        IReadOnlyList<IGateProvider> gates,
        CancellationToken ct)
    {
        // Core controls evaluation order and aggregation
        var results = new List<GateResult>();
        foreach (var gate in gates)
        {
            // Plugin provides evaluation logic
            var result = await gate.EvaluateAsync(promotion, ct);
            results.Add(result);

            // Core decides how to aggregate (plugins cannot override)
            if (result.IsBlocking && _policy.FailFast)
                break;
        }

        // Core makes final decision
        return _decisionAggregator.Aggregate(results);
    }
}

Document Conventions

Throughout the Release Orchestrator documentation:

References