Skip to content

Bluefly Work Record Profile Specification

1. Overview and Authority

The bluefly.work-record.v1 profile establishes the canonical structure for tracking governed work lifecycle in the Bluefly platform. It builds upon JSON Schema 2020-12 and introduces four primary record types: request, decision, progress, and receipt.

  • Canonical Schema ID: https://bluefly.io/schemas/bluefly.work-record.v1.json
  • Owning Repository: blueflyio/agent-platform/tools/api-schema-registry
  • Governing Standard: Engineering-Standard/architecture/bluefly-work-record-profile.md
  • Execution Engine: Gas City (Formula V2 & Orders)
  • Durable Store: Dolt (127.0.0.1:3308/hq, table/bead records)

2. Canonical JSON Schema (2020-12)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://bluefly.io/schemas/bluefly.work-record.v1.json",
  "title": "Bluefly Work Record",
  "type": "object",
  "properties": {
    "record_type": {
      "type": "string",
      "enum": [
        "request",
        "decision",
        "progress",
        "receipt"
      ]
    },
    "state": {
      "type": "object",
      "properties": {
        "work": {
          "type": "string",
          "enum": [
            "open",
            "in-progress",
            "blocked",
            "completed",
            "cancelled"
          ]
        }
      }
    },
    "delivery": {
      "type": "object",
      "properties": {
        "merge_request": {
          "type": "object",
          "properties": {
            "state": {
              "type": "string",
              "enum": [
                "opened",
                "closed",
                "merged"
              ]
            }
          }
        },
        "pipeline": {
          "type": "object",
          "properties": {
            "status": {
              "type": "string",
              "enum": [
                "pending",
                "running",
                "success",
                "failed",
                "canceled",
                "skipped"
              ]
            }
          }
        }
      }
    },
    "evidence": {
      "type": "object",
      "properties": {
        "wasGeneratedBy": {
          "type": "string"
        },
        "wasDerivedFrom": {
          "type": "string"
        },
        "wasAttributedTo": {
          "type": "string"
        }
      }
    },
    "tenancy": {
      "type": "object",
      "description": "Optional tenancy scoping for multi-tenant or group-isolated work records",
      "properties": {
        "tenant_id": {
          "type": "string",
          "description": "Unique identifier for the tenant, group, or organization"
        },
        "scope": {
          "type": "string",
          "enum": [
            "city-wide",
            "tenant-private"
          ],
          "default": "city-wide",
          "description": "Visibility scope of the work record"
        }
      }
    }
  },
  "required": [
    "record_type"
  ]
}

3. Four Canonical Record Types

Record Type Purpose Primary Fields Lifecycle Trigger
request Captures initial intent, caller identity, and constraints for new work record_type, state.work (open), tenancy, evidence.wasAttributedTo Intake order, user dispatch, or inbound event
decision Records architectural, security, policy, and governance approvals record_type, decision, policy_id, evidence.wasAttributedTo, evidence.wasDerivedFrom Human or autonomous policy gate
progress Records state transitions, execution progress, dependencies, blockers record_type, state.work (in-progress/blocked), delivery Agent execution step, pipeline event
receipt Final, immutable delivery confirmation with verification proof record_type, state.work (completed), delivery.merge_request, evidence Bead close, MR merge, post-verification

4. Ownership Model and Field Mapping

4.1 System of Record Boundaries

Component Responsibility Governed Fields
Gas City / Beads (Dolt) Durable work graph, lifecycle states, parent/child relationships record_type, state.work, tenancy
GitLab / SCM Source control, review lifecycle, CI pipeline verification delivery.merge_request, delivery.pipeline
W3C PROV Ledger Lineage, agent attribution, cryptographic provenance evidence.wasGeneratedBy, evidence.wasDerivedFrom, evidence.wasAttributedTo
ContextControl Customer projection, visualization, UI audit surface Read-only projection of work records filtered by tenancy

4.2 Legacy Field Replacement Mapping

To eliminate divergent schema representations across legacy agents and ad-hoc scripts:

Legacy / Ad-hoc Field Canonical Field in bluefly.work-record.v1 Transformation Rule
status state.work Normalize to open, in-progress, blocked, completed, cancelled
mr_state, gitlab_mr.status delivery.merge_request.state Normalize to opened, closed, merged
ci_status, pipeline_state delivery.pipeline.status Normalize to pending, running, success, failed, canceled, skipped
author, agent_id, actor evidence.wasAttributedTo Canonical agent or user URI/URN
parent_bead, derived_from evidence.wasDerivedFrom URN to parent Bead or source artifact
tool_call, script_id evidence.wasGeneratedBy URN to tool, generator, or command execution
group_id, org_id tenancy.tenant_id Tenant string identifier
visibility, privacy tenancy.scope Normalize to city-wide or tenant-private

5. Tenancy and Group Scoping (bc-7vv4)

The work record and evidence system supports multi-tenant scoping for operations that span customer organizations, such as ContextControl's Drupal Governed Update.

  • Declaration: A work record declares its tenant/scope via the tenancy object in the schema:
  • tenant_id: Unique identifier for the tenant, group, or organization.
  • scope: Either city-wide (accessible across the entire installation) or tenant-private (strictly isolated to the owning tenant).
  • ContextControl Rendering: When ContextControl renders work records, it filters by the tenant_id field. Only records where scope is city-wide or where tenant_id matches the authenticated context's tenant are rendered in that tenant's view.
  • Gas City Enforcement: Gas City enforces tenant boundaries on bead visibility by requiring tenant_id matching during Bead queries (via Dolt read-access views or application-level enforcement). Cross-tenant queries are rejected unless run by a city-wide authorized system agent.

6. Gas City Lifecycle Integration

The execution lifecycle of work records is automated using Gas City constructs:

6.1 Formula V2: governed-work-lifecycle

Materializes the 9-step canonical lifecycle: 1. validate-request: Validates inbound work request against bluefly.work-record.v1. 2. resolve-authority: Resolves rig, owning agent identity, and policy standard. 3. create-bead: Materializes durable Bead in Dolt store. 4. prepare-worktree: Creates isolated Gas City-managed worktree. 5. execute-change: Executes code modification and local verification. 6. deliver-gitlab: Pushes commits, opens/updates MR targeting release/v0.1.x. 7. verify-delivery: Verifies CI pipeline passes and MR converges. 8. generate-receipt: Generates receipt work record with PROV attribution. 9. cleanup-session: Deregisters worktree, closes Bead, records completion event.

6.2 Six Canonical Orders

  1. work-request-intake: Triggers governed-work-lifecycle upon new work dispatch.
  2. delivery-reconcile: Periodically audits MR and pipeline status to update delivery object in active beads.
  3. blocked-work-route: Detects state.work == blocked and routes handoff via gc sling and gc mail.
  4. receipt-on-close: Enforces that a Bead cannot transition to completed without an authoritative receipt record.
  5. evidence-integrity-patrol: Patrols beads and commits to verify PROV-O completeness (wasGeneratedBy, wasDerivedFrom, wasAttributedTo).
  6. stale-work-patrol: Flags or reclaims abandoned in-progress beads exceeding inactivity thresholds.

7. Standards and Normative Citations