Skip to content

Upstream Convergence Engineering Reference & Blueprint

Reference ID: REF-UPSTREAM

This document defines the canonical engineering reference and implementation blueprint for converging Bluefly onto upstream platform primitives, ledgers, and tools.

1. The Core Invariants

  • Every authority layer must have a corresponding executable doctor check. The architecture document serves as the specification; the diagnostic suite is the enforcement.
  • A document is not authoritative because it exists. It is authoritative because it can be traced to verified runtime evidence or an upstream authoritative source. This prevents standards from becoming speculative or decoupled from reality.
  • Canonical knowledge is a consequence of verified execution. Documentation does not merely happen later—it is derived from evidence.
  • An engineering standard is a runtime artifact, not a planning artifact. A standard may only change when upstream behavior, runtime behavior, capability ownership, or verification requirements change. It may not change solely to restructure or rephrase the document.
  • Reality produces knowledge; knowledge never produces reality. Knowledge Receipts may reference Runtime Receipts, but Runtime Receipts must never reference Knowledge Receipts. This prevents circular authority loops.

2. Authority vs. Causal Flow

To maintain clear abstractions, we separate the static hierarchy of platform authorities from the dynamic causal loop of execution.

2.1. The Authority Hierarchy

The authority hierarchy dictates the boundaries and constraints of platform configuration. Higher layers define, compile, and validate the constraints of lower layers.

Repository Authority (Git History / Branches / Hooks / Topology)
        │
        ▼
Capability Authority (Catalog / Lifecycle / Scope / Dependencies)
        │
        ▼
Execution Authority (Intentional Work Graph / Beads)
        │
        ▼
Runtime Authority (Transient State / Host / Containers)
        │
        ▼
Knowledge Authority (Memory & Understanding / BluCity-Docs)
1. Repository defines available assets. 2. Capability defines available operations. 3. Execution chooses operations. 4. Runtime realizes them. 5. Knowledge documents them.

2.2. The Cross-Cutting Planes

  • The Observability Plane: Measures, monitors, and records telemetry across every level of the hierarchy simultaneously. Telemetry does not dictate policy or own execution; it records reality.
  • The Contract Plane: Constrains every layer of the hierarchy using active policy, rules, schemas, and specifications (e.g. Cedar policies, push rules, OpenAPI schemas, JSON schemas, SPDX/SBOM/AIBOM constraints). Contracts do not create capabilities; they restrict and validate them.

2.3. The Causal Feedback Loop

The operational lifecycle operates as a closed loop where reality remains the ultimate ground truth:

Reality (Ground Truth) ──► Knowledge (Memory) ──► Humans (Authorizers) ──► Execution (Work Graph) ──► Runtime ──► Reality
* Reality produces knowledge. * Knowledge informs humans. * Humans authorize execution. * Execution schedules runtime changes. * Runtime mutates reality.

3. Executable Verification Mapping

The six authority layers are enforced by a matching suite of automated diagnostic commands. Every invariant declared in this blueprint is verified programmatically:

Authority Layer Executable Verification Scope
Repository doctor repository Asserts clean working tree, remote branch tracking, submodule synchronization, installed hooks, and absence of forbidden deletions/OS junk.
Capability doctor capability Validates pack syntax, dependencies, lock files, variables, and composition imports.
Execution doctor work Verifies active Bead claims, work graph status, and database consistency.
Runtime doctor runtime Verifies host connectivity, tailnet access, and Docker containers.
Contract doctor contract Validates Cedar policy syntax, schema conformances, and push rules.
Knowledge doctor knowledge Checks for tool cache pollution and verifies QMD index health.

4. Platform Ledgers & Receipts

Platform state is tracked across six distinct ledgers. To avoid duplicating execution DAGs, all receipts are stored as structured files committed directly into Git, leveraging Git's native commit parent-graphs, timestamps, signatures, and immutability.

Repository Ledger ──► Work Ledger ──► Capability Ledger ──► Runtime Ledger ──► Contract Ledger ──► Knowledge Ledger

4.1. The Six Ledgers

  1. Repository Ledger (Git): Tracks revision history, branches, hooks, worktrees, and repository topology.
  2. Work Ledger (Beads / Dolt): Tracks intentional task states and dependency DAGs.
  3. Capability Ledger (Packs / city.toml): Tracks the catalog of capabilities, their canonical owner, lifecycle, and dependencies.
  4. Runtime Ledger (Gas Town / Docker / Oracle): Tracks transient execution and machine states.
  5. Contract Ledger (OSSA / Cedar / push rules / OpenAPI): Tracks active constraints, policies, schemas, and bills-of-materials (SPDX, SBOM, AIBOM).
  6. Knowledge Ledger (BluCity-Docs / QMD): Tracks long-term architectural understanding and memory.

4.2. Authority Debt Integration

Authority Debt is represented directly as READY Beads in the Work Ledger with type=authority-transfer. This consolidates all tasks under a single system of record.

4.3. Receipt Specification

Receipts are validated, structured YAML files committed to Git:

1. Repository Receipt

Generated upon commit verification: 

repository_receipt:
  receipt_id: rep-20260712-00051
  parent_receipts:
    - rep-20260712-00049
  branch: release/v0.1.x
  commit: a9f81c9a8...
  tag: v0.1.0
  signature: gpg-key-id-9381c...
  dirty_state: false
  timestamp: 2026-07-12T02:28:00Z

2. Runtime Receipt

Generated upon execution verification: 

runtime_receipt:
  receipt_id: rt-20260712-00184
  parent_receipts:
    - rt-20260712-00171
  repository_receipt: rep-20260712-00051
  runtime:
    host: blueflynas
    rig: oracle-town
    city: portland
    deployment: /home/ubuntu/gt/portland
  verification:
    doctor: PASS
    health: OK
    pipeline: https://gitlab.com/blueflyio/.../pipelines/1837482
  timestamp: 2026-07-12T02:30:00Z

3. Capability Receipt

Generated when updating pack definitions or composition layouts: 

capability_receipt:
  receipt_id: cap-20260712-00042
  pack_name: amcs
  action: register_capability
  dependencies:
    - [email protected]
  hash: sha256-f83b19a2...

4. Knowledge Receipt

Generated when documenting proven behavior, referencing the underlying runtime receipts and generating a strict evidence_hash: 

knowledge_receipt:
  receipt_id: kn-20260712-00012
  bead_id: B-482
  runtime_receipts:
    - rt-20260712-00184
  evidence_hash: sha256(runtime_receipt + pipeline_id + git_commit + doctor_output)
  documentation_delta:
    updated:
      - upstream-architectural-reference.md
  architectural_change:
    type: platform_hierarchy_realignment
    reason: "Runtime behavior differed from previous documentation."

5. Knowledge Curation & Execution Standard

5.1. Startup and Verification Protocol

Before any observation or action, the agent must verify platform authorities: 1. Verify Repository Authority: Confirm repository health and layout. 2. Verify Capability Authority: Confirm imported packs match execution scope. 3. Verify Work Authority: Claim active bead and verify ownership: 

No READY bead claimed ──► Claim bead ──► Verify bead ownership ──► Proceed to Observation
4. Verify Runtime Authority: Confirm host connection and daemon state.

[!NOTE] Non-Normative Implementation details: Current Gas Town runtime integration implements these gates via gt up ──► gt doctor ──► bd ready.

5.2. Operational Modes

Planning is not an execution mode. Planning only exists if explicitly requested by a human. Otherwise, the agent operates in a closed loop:

Observe ──► Execute ──► Curate

MODE: OBSERVATION

  • Purpose: Measure reality.
  • Allowed Operations: qmd retrieval, upstream verification, runtime prechecks, work graph audits, git inspection.
  • Exit: Evidence collected. No planning or documentation changes.

MODE: EXECUTION

  • Purpose: Produce a runtime change.
  • Allowed Operations: Code edits, commits, pushes, deployment, verification checks.
  • Universal No Narrative Rule: During Execution Mode, agents shall not produce conversational narrative. Output must strictly contain only the following fields: 
    STATE: <state>
BEAD: <bead_id>
STEP: <step_name>
RESULT: <pass/fail>
NEXT: <next_action>
  • Exit: Running system verified. No documentation changes.

MODE: CURATION

  • Purpose: Reconcile knowledge after execution.
  • Prerequisite: Verified runtime receipt exists.
  • Allowed Operations: Update BluCity-Docs, retire duplicate guides, update indexes, sign Knowledge Receipt.
  • Forbidden: New engineering plans, new architecture proposals.

5.3. The Ownership Ladder

Before authoring custom code, decisions must traverse the Ownership Ladder from the highest tier downwards. Custom development is reserved only for gaps that cannot be satisfied configurationally or declaratively.

6. Next Major Enforcement Milestones

Future work must transition the platform from a well-documented architecture to a self-validating one by executing against these milestones:

  1. Doctor as Executable Specification: Every rule declared in this standard must be verified by an automated blu doctor check.
  2. Automated Receipts: Receipts must be programmatically generated as an output of successful execution or deployment runs rather than compiled manually by agents.
  3. Exclusive Work Graph: All development tasks—including refactoring, compliance, and authority-transfers—must flow exclusively through Beads as the single work ledger.
  4. Measurable Capability Convergence: Standardize reporting on the net negative ownership status:
  5. Capabilities transferred.
  6. Remaining custom capabilities.
  7. Maintenance obligations eliminated.
  8. Duplicate implementations remaining.

7. Cities (Deployments) vs. Packs (Capabilities)

To scale the engineering model, we separate Cities (customer deployments) from Packs (reusable capabilities). We organize capabilities by business domain under simple names without company branding prefixes, treating them similarly to Drupal contrib modules.

Drupal Architecture Model:         Gas City Architecture Model:
  Drupal Site                        City (Customer Deployment via city.toml)
    ├── Core                           ├── System Packs (gc core)
    ├── Contrib                        ├── Community Packs
    └── Custom                         └── Bluefly Packs (amcs, governance, oracle, etc.)

7.1. Declarative Cities

A City's city.toml file contains composition rules and deployment variables with minimal custom logic:

# city.toml - Portland Deployment
name = "Portland"
region = "us-east"

imports = [
  "amcs",
  "governance",
  "oracle",
  "knowledge"
]

[variables]
customer = "Portland DOT"
backup_frequency = "daily"

7.2. Packs Library (blucity-packs/)

The library of packs is organized under blucity-packs/: * amcs — Canonical Drupal control-plane capabilities. * governance — Cedar policies and verification receipts. * oracle — Host mounting and workspace transport controls. * compliance — Security audit protocols and checks. * contractplane — Signed authorization and registry compliance. * drupal-ai — AI-specific content optimization and grounding. * ossa — Open System Steering Agent hooks. * duadp — Drupal Upstream Application Deployment Protocol. * knowledge — Canonical engineering standards, references, runbooks, and architecture. Treating documentation as a pack ensures it is imported and versioned alongside capabilities.

8. Default Mapping Decision Tree

Consult this matrix before writing any code. If a capability exists upstream, Bluefly must adopt or configure it, rather than building custom TypeScript/Go binaries.

Need Upstream Owner Bluefly Action Description
Multi-agent work Gas Town Configure Set up session roles (Mayor, Deacon, Witness).
Runtime Gas City Configure Run workflows using standard execution engines.
Work graph Beads Adopt Track task states and dependency DAGs.
Formula execution Gas City Author Write declarative TOML steps (formulas/).
Orders Gas City Author Define trigger-driven events (orders/).
Telemetry gascity-otel Configure Feed performance metrics to GC_OTEL_ENDPOINT.
Dashboard gascity-dashboard Extend Render custom views for operator inspection.
Federation Wasteland Adopt Query signature checks and wanted boards.
Session persistence tmux-adapter / OpenClaw Configure Use tmux/subprocess profiles in city.toml.
Data Dolt Adopt Ground truth versioned SQL server tables.
Governance Bluefly Build Custom authorization enforcements.
Receipts Bluefly Build Cryptographic transaction logging.
Cedar policy Bluefly Build Write evaluation rules in anti-slop.cedar.
Drupal knowledge amcs Author Define specific update and sync behaviors.

9. PackV2 Extension Taxonomy

Under the PackV2 paradigm, the pack is the product. Rather than organizing code by repository boundaries, capabilities are grouped into declarative packs containing no custom runtime logic. Custom command files are classified into standard extension surfaces.

Pack Layout Specification

<pack-name>/
  ├── pack.toml     # Pack declaration and imports
  ├── city.toml     # Rig and deployment maps
  ├── agents/       # Agent prompts/templates (Mayor, Deacon, Witness)
  ├── commands/     # CLI commands configuration
  ├── orders/       # Cron, event-driven, or cooldown triggers
  ├── formulas/     # Declarative state resolution graphs (TOML)
  ├── doctor/       # Diagnosic scripts for blu doctor
  ├── overlay/      # Dynamic CLI command overrides/adjustments
  ├── skills/       # Prompts and reference schemas
  ├── mcp/          # Model Context Protocol tools
  └── assets/       # Static templates, files, and resources

The "Never Build This Again" Classification

Custom Subsystem Target Upstream Primitive Classification Action
blu-remote Gas City SSH session provider Move into Pack Configure session = "ssh" in city.toml
blu-sync Dolt remotes + Beads sync Move into Formula Execute dolt push inside a sync formula
blu buddy Headless subprocess/tmux sessions Move into Pack Define session profiles in pack.toml
sweep command blu repos health + converge Move into Command Implement as a commands/ overlay in a pack

10. The Ralph Loop (Executor-Only Model)

The Ralph Loop is a pure executor. It does not perform discovery, scheduling, or policy decision-making. It merely drives state changes in response to verified receipts.

Observe (Audit)
    ↓
Receipt (Observe Receipt)
    ↓
Policy (Authorize via Cedar/OSSA)
    ↓
Execute (Ralph Loop mutations)
    ↓
Verify (Doctor diagnostics)
    ↓
Receipt (Verification Receipt)

11. Drupal: The Proof (amcs Pack Blueprint)

Instead of maintaining generic repository utilities, the proof of PackV2 composition is demonstrated through a vertical slice implementing the Drupal operational domain. Our authoritative Drupal pack is amcs (Agent Managed Content System).

Layout: blucity-packs/amcs

Located at: Applications/blucity-packs/amcs

amcs/
  ├── pack.toml     # Imports and dependencies (pinned Core/Beads)
  ├── packs.lock    # Resolved pack dependency tree
  ├── ENABLEMENT.md # Setup guide and credentials bootstrap
  ├── README.md     # Pack overview and architecture
  ├── agents/
  │     ├── content-author/         # Writes content drafts and updates
  │     ├── content-maintenance/    # Applies patches and minor core upgrades
  │     ├── editorial-qa/           # Runs validation, checking link rot / alt tags
  │     ├── governance-compliance/  # Enforces OSSA and database sanity checks
  │     ├── migration-ingestion/    # Orchestrates database imports
  │     ├── personalization/        # Manages taxonomy-suggest overlays
  │     └── search-rag/             # Grounds RAG databases
  ├── orders/
  │     ├── amcs-addon-surface-patrol.toml    # Weekly check of external addons
  │     ├── amcs-config-drift-patrol.toml     # Daily database configuration audit
  │     ├── amcs-custom-modules-sweep.toml    # Scans for obsolete codebase hooks
  │     ├── amcs-ddev-health-patrol.toml      # Hourly local server liveness check
  │     ├── amcs-editorial-qa-weekly.toml     # Runs link and tag checks
  │     ├── amcs-factory-bootstrap-manual.toml# Manual developer environment setup
  │     ├── amcs-governance-audit-manual.toml # Manual security compliance run
  │     ├── amcs-jsonapi-health-patrol.toml   # API liveness check
  │     ├── amcs-rag-grounding-patrol.toml    # Re-indexes vector embeddings
  │     ├── amcs-recipe-surface-patrol.toml   # Validates applied system recipes
  │     ├── amcs-release-validation-manual.toml# Manual validation prior to push
  │     ├── amcs-runtime-verify-patrol.toml   # Verifies Tailscale and DB access
  │     ├── amcs-site-maintain-daily.toml     # Installs nightly security patches
  │     ├── amcs-stale-content-weekly.toml    # Highlights unmaintained content
  │     └── amcs-workflow-guard-patrol.toml   # Verifies active workspace states
  ├── formulas/
  │     ├── drupal-module-governance-audit.toml  # Audits custom hooks/security
  │     ├── drupal-mr-validation.toml            # Automated git merge request validation
  │     ├── drupal-recipe-apply.toml             # Applies core site recipes
  │     ├── drupal-site-maintain.toml            # Updates Drupal core and schemas
  │     ├── drupal-site-template-factory.toml    # Creates a fresh local ddev harness
  │     ├── mol-amcs-accessibility-review-readonly.toml
  │     ├── mol-amcs-content-author-draft.toml
  │     ├── mol-amcs-custom-modules-sweep-readonly.toml
  │     ├── mol-amcs-draft-from-brief.toml
  │     ├── mol-amcs-editorial-qa-review.toml
  │     ├── mol-amcs-factory-bootstrap.toml
  │     ├── mol-amcs-human-approval-handoff.toml
  │     ├── mol-amcs-migration-plan-readonly.toml
  │     ├── mol-amcs-rag-grounding-audit.toml
  │     ├── mol-amcs-runtime-verify.toml
  │     ├── mol-amcs-site-template-extraction.toml
  │     ├── mol-amcs-taxonomy-suggest-readonly.toml
  │     ├── mol-drupal-addon-surface-readonly.toml
  │     ├── mol-drupal-config-drift-readonly.toml
  │     ├── mol-drupal-ddev-health-readonly.toml
  │     ├── mol-drupal-jsonapi-health-readonly.toml
  │     ├── mol-drupal-recipe-surface-readonly.toml
  │     ├── mol-drupal-stale-content-readonly.toml
  │     └── mol-drupal-workflow-guard-readonly.toml
  ├── skills/
  │     ├── amcs-drupal-rig/        # Custom guidelines for drush and config
  │     └── amcs-gas-city-primitives/ # Prompt references for formula/bead usage
  └── mcp/                          # Exposes composer/drush control to LLMs

12. What Bluefly Owes and Maintains

Bluefly's code footprint is limited to: * Cedar/OSSA Policies: Enforcing authorization rules. * Receipt Verification: Generating and checking execution audit envelopes. * ContractPlane Integration: Checking organizational compliance. * Doctor Extensions: Custom diagnostic checks. * Pack Composition: Declarative Packs mapping workspace domains (e.g. oracle, governance, compliance, amcs).