STD-ARCH-002: Bluefly Factory Gateway & Interface Contract Standard¶

Status: Canonical & Binding
Standard ID: STD-ARCH-002
Owner: Blu (kingstown-core.blu) — Director
Target Environments: blutown.ai (Factory / Customer Surface), Gas City (Runtime), bluefly.io (Marketing)

1. Prime Directive & Zero Custom Code Law¶

ContextControl is the governed human interface and read model; Gas City is the sole execution orchestrator; Beads carries durable work; Formulas materialize repeatable operations; Events synchronize state; Drupal ECA and API Normalization compose the interface without custom glue. All custom controllers, custom API clients, custom event daemons, and custom orchestration modules are strictly REJECTED.

Immutable Factory Laws¶

BEADS != EVENTS
EVENTS != COMMANDS
MAIL != WORK AUTHORITY
CONTEXTCONTROL != ORCHESTRATOR
RAW BD = scope-local authority
GC = Factory-wide operational view
MAIL_SENT != WORK_ACCEPTED
CUSTOM_CODE_ADDED = 0  (Composition over custom code)

2. The Four Communication Planes & Semantics¶

Plane	Semantics	Authority	Purpose & Boundaries
Work Plane	`WORK TRANSFER`	Beads (`bd`)	Stores what work exists, ownership, dependencies, readiness, status, and evidence. Bead updates and slinging transfer work.
Execution Plane	`EXECUTION`	Agents + Formulas + Sessions	Performs bounded execution. Sessions are disposable containers; Formulas are workflow compilers; Agents are configured roles.
Observation Plane	`OBSERVATION`	Gas City Events	Immutable, append-only, typed, cursor-based state transition proof. Emits SSE streams used by ContextControl.
Human / Control Plane	`CONTEXT MESSAGE` / Governance	ContextControl (Drupal)	Governs who can request, approve, inspect, govern, and understand work. Mail provides context only (`MAIL_SENT != WORK_ACCEPTED`).

3. High-Level Architecture: Bluefly Factory Gateway¶

CUSTOMER / OPERATOR (blutown.ai)
  │
  ▼
CONTEXTCONTROL (Drupal identity / Group scope policy / approval / evidence)
  │
  │ Governed Async Request (202 ACCEPTED + request_id)
  ▼
PRIVATE FACTORY EDGE (Tailscale Service Identity -> factory-api.blutown.ai -> 127.0.0.1:8372)
  │
  ▼
GAS CITY RUNTIME (127.0.0.1:8372 Loopback)
  │
  ├─ Beads (Durable Work Graph)
  ├─ Events (Typed SSE Stream)
  ├─ Services (/svc/{name})
  └─ Webhooks (/hook/{name} via hooks.blutown.ai)
  │
  ├─ Formula V2 ──► Agent ──► Session
  │
  ▼
CONTEXTCONTROL READ MODEL (Drupal ECA + API Normalization + Group + Views + Canvas + SDC)
  │
  ▼
CUSTOMER UI / OPERATIONS CONSOLE / EVIDENCE RECEIPT

4. Architectural Rules & System Boundaries¶

1. Bluefly Factory Gateway Boundary¶

Gas City Supervisor REST API (127.0.0.1:8372) remains loopback-bound.
Raw 0.0.0.0 exposure, iptables NAT redirects, Host header spoofing, or public Cloudflare Supervisor exposure are STRICTLY PROHIBITED.
Trusted access routes through factory-api.blutown.ai via Tailscale service identity.

2. Declared Webhooks (`/hook/{name}`) & Services (`/svc/{name}`)¶

Inbound external platform events (e.g. GitLab SaaS) route through a dedicated narrow edge (hooks.blutown.ai).
Webhook routes must be explicitly declared in root city.toml. Imported packs CANNOT grant themselves public exposure.
Workspace HTTP services mount under /svc/{name} through the controller edge.

3. ContextControl Never Talks Directly to an Agent¶

ContextControl does NOT address individual agent sessions or tmux panes.
Flow: ContextControl ──► Governed Gas City Request ──► Bead / Formula V2 ──► Gas City selects & starts Agent session.

4. Drupal Implementation = Pure Configuration (`CUSTOM_CODE_ADDED = 0`)¶

Custom modules (e.g. context_control_operations) are REJECTED.
Compose upstream modules: api_normalization + ECA + Group + Views + Canvas + SDC + Drupal AI / Tool API.

5. Formula V2 Technical Steps vs. Customer Lifecycle Projection¶

Technical Formula steps (e.g. inventory core, check advisories, inspect composer) are distinct from higher-level customer lifecycle stages (DETECT, UNDERSTAND, MATCH, AUTHORIZE, ACT, VERIFY, PROVE).
ContextControl projects technical step Beads into customer lifecycle stages in the UI.

6. Trust Class Transparency in ContextControl UI¶

Every operation displays its trust boundary:

CAPABILITY: Drupal Core Security Update
AUTHORITY: Bluefly Drupal Service Identity
CUSTOMER SCOPE: Corporate Website (Group: Acme Corp)
POLICY: SEC-UPDATE-02 (Minor updates auto-approved)
INPUTS TRUST CLASS: External Untrusted (Composer metadata, Advisories)
EXECUTOR: DrupalWorks Agent
EXECUTION INTERFACE: Composer / Drush via approved capability
VERIFIER: Independent Witness Agent
RECOVERY: Git revert + deployment rollback
EVIDENCE RETENTION: 365 Days

5. Phased Implementation Roadmap (Phases A–J)¶

Phase A: Factory Connectivity: Loopback supervisor (127.0.0.1:8372), Tailscale private edge (factory-api.blutown.ai), declared root webhooks (hooks.blutown.ai).
Phase B: API Normalization: Ingest Gas City OpenAPI spec via api_normalization. Expose read capabilities (CITY_STATUS, READY_WORK, OPERATIONS, AGENTS, SESSIONS, EVENTS, EVIDENCE, USAGE) and single command (REQUEST_OPERATION).
Phase C: Drupal Workflow: Button/AG-UI ──► Drupal Form/Action ──► Group scope ──► Cedar Policy ──► api_normalization action ──► Gas City API (202 ACCEPTED + request_id).
Phase D: Event Read Model: Consume Gas City SSE event stream. Map native events to ContextControl projection state (requested, authorized, queued, claimed, running, waiting, blocked, verification, completed, failed).
Phase E: Group Isolation: Configure Organization ──► Team ──► Estate isolation using Drupal Group module.
Phase F: Operations Console UI: Build /operations, /operations/{id}, /agents, /evidence, /approvals using Views, Canvas, SDC, and AG-UI. Display real progress, executing agent, evidence checks, estimated human time saved, and model cost.
Phase G: Agent Handoff Enforcement: Enforce BEAD = WORK TRANSFER, MAIL = CONTEXT, EVENT = OBSERVATION, SESSION = EXECUTION.
Phase H: Formula V2 Operation: Deliver drupal-estate-audit.formula.toml as read-heavy vertical slice.
Phase I: Trust Transparency: Display full trust class matrix on operation detail pages.
Phase J: Demo Acceptance: Second developer logs in, views Group-scoped estate, clicks "Run Drupal Estate Audit", and observes real operation progress and evidence without CLI.

6. Required Completion Receipt (STD-ECON-001)¶

CUSTOM_CODE_ADDED=0
CUSTOM_CODE_REMOVED=YES
GAS_CITY_API_REAL=YES
OPENAPI_IMPORTED=YES
API_NORMALIZATION_USED=YES
ECA_USED=YES
GROUP_USED=YES
VIEWS_USED=YES
CANVAS_USED=YES
SDC_USED=YES
OPERATION_REQUEST_REAL=YES
BEADS_REAL=YES
AGENT_REAL=YES
EVENTS_REAL=YES
EVIDENCE_REAL=YES
COST_REAL=YES
CUSTOMER_ISOLATION_PROVEN=YES
SECOND_DEVELOPER_DEMO_PROVEN=YES
IS_THE_NEXT_RUN_GETTING_CHEAPER_AND_MORE_REUSABLE=YES
WHY=Eliminated custom modules by composing api_normalization, ECA, Group, Views, Canvas, and SDC over Gas City loopback behind private edge factory-api.blutown.ai.