ES-0001: Bluefly Engineering Standard¶
| Field | Value |
|---|---|
| Status | Active |
| Date | 2026-09-09 |
| Author | Thomas Scola |
| Scope | Platform-wide — all Bluefly code, docs, and ops |
Purpose¶
This document codifies the architectural decisions and terminology rules into a single, enforceable engineering standard. All Bluefly engineering work — code, documentation, automation, runbooks, and operational procedures — must conform to this standard.
1. Runtime Architecture¶
Authority: Bluefly Deployment Architecture
1.1 Layering¶
The Bluefly runtime stack is strictly layered. Every layer depends only on the layer below it.
Bluefly Governance Plane (Business Intent) → Release Bundle (Desired State) → Gas City Execution Plane (Reconciliation) → Oracle Runtime Plane (Immutable)
Gas Town is upstream's predecessor project. It may exist as an imported Pack. It is not a peer orchestration platform, not an intermediary, and not a layer in this stack.
1.2 Domain Compilation¶
Bluefly overlay terms compile onto Gas City primitives. They do not add primitives. Source: How Gas City Works.
| Bluefly Concept | Maps onto |
|---|---|
| Mission | Pack |
| Factory | Gas City + Pack-configured Agents + Orders |
| Capability | Formula |
| Deployment | Bluefly Operations / GitLab release — not a Session, not a primitive |
| Worker | Agent |
1.3 Immutable Deployment Rule¶
Deployment across the platform relies on immutable, artifact-first deployments.
- No manual runtime mutations.
- No SSH deployments or manual docker-compose.
- All environments are managed via Governance Plane approvals releasing versioned Release Bundles.
2. Repository Authority Model¶
2.1 The Four Authorities¶
Every repository defines four distinct authorities. They must never be conflated.
| Authority | Definition | Default |
|---|---|---|
| Development Authority | Where active development occurs | Mac |
| Source Authority | Single source of truth for version history; CI/CD reads here | GitLab |
| Deployment Authority | Where production workloads run | Oracle |
| Recovery Authority | Disaster recovery clone; not authoritative for dev/source/deploy | NAS |
3. Terminology Standard¶
3.1 Required Terminology¶
| Use This | Instead Of |
|---|---|
| Source Authority (GitLab) | "canonical" (unqualified) |
| Recovery Authority (NAS) | "NAS canonical," "NAS source" |
| Development Authority (Mac) | "Mac canonical," "local canonical" |
| Deployment Authority (Oracle) | "production copy" |
| Release Bundle | "Deployment package" |
4. Prohibited Patterns¶
The following patterns are explicitly prohibited in all Bluefly engineering artifacts:
| Pattern | Why |
|---|---|
git pull on production |
Runtime plane is immutable |
| Manual SSH deployments | Deployments flow through Gas City reconciliation |
"NAS is canonical" |
NAS is Recovery Authority, not Source Authority |
| Mutable production config | Violates IaC and Desired State principles |
| Archive without proving all 9 points | Violates the Execution Rule |
5. Open Source Integration¶
When integrating Open Source Software, engineers SHALL first determine whether the requested capability already exists as native functionality, configuration, plugin, provider, middleware, extension point, or officially supported integration. Bluefly code may only implement domain-specific behavior after all upstream ownership has been exhausted and documented with evidence.
Binding factory placement: Bluefly Factory Operating Contract (Preferred extension order; Decision gate).
References¶
- Bluefly Deployment Architecture
- Terminology Migration List (companion document)
- Bluefly Constitution (Factory Operating Model)
- Bluefly Factory Operating Contract