Platform Compiler — Core Object Model¶
Document: 1 of 4 Status: Canonical Depends on: None Required by: Contract Model, Projection Model, Receipt & Provenance Model
Purpose¶
This document defines every first-class object in the Platform Compiler and every relationship between them. It contains no implementation details, no runtime-specific concepts, and no tool references. Everything that follows in the Contract Model, Projection Model, and Receipt Model derives from this object graph.
First-Class Objects¶
Authority¶
An entity that owns and is accountable for one or more Contracts.
An Authority may be Bluefly, Acquia, Google, Apple, Anthropic, or any external organization. The Platform Compiler treats all Authorities identically — it does not distinguish between internal and external Authorities at the object model level. That distinction is a Contract Model concern.
Authority
id: globally unique identity (authority.<name>)
name: human-readable name
type: internal | external | standard-body
trust: owned | partner | vendor | community | unknown
contact: canonical contact or URL for the authority
Capability¶
A business capability owned by exactly one Authority. A Capability is protocol-independent and runtime-independent. It has no hostname, no port, no Docker image, and no Terraform resource. Those are Deployment concerns.
A Capability publishes one or more Contracts. It does not publish implementations.
Capability
id: globally unique identity (capability.<domain>.<name>)
authority: → Authority
name: human-readable name
description: what this capability does
contracts: [ → Contract ] one or more, any contract type
status: active | deprecated | experimental
Examples:
- capability.platform.compliance — owned by Bluefly, publishes an OpenAPI contract
- capability.platform.authentication — owned by Bluefly, publishes an OIDC contract
- capability.platform.agent-ui — owned by Bluefly, publishes an AG-UI contract
- capability.platform.tool-access — owned by Bluefly, publishes an MCP contract
- capability.provider.acquia.content — owned by Acquia, publishes a JSON:API contract
Contract¶
A typed schema published by a Capability. A Contract defines the interface, not the implementation. A Capability may publish multiple Contracts of different types.
Contract
id: globally unique identity (contract.<capability-id>.<type>)
capability: → Capability
type: openapi | graphql | mcp | ag-ui | a2a | json-schema |
cedar | opa | kubernetes-crd | gascity-pack |
terraform-module | asyncapi | grpc-proto
version: semantic version string
source: path within registry to the schema artifact
stability: stable | beta | experimental | deprecated
The Contract type determines which Renderer can consume it. The Planner selects Renderers based on Contract type and Projection target.
Provider¶
An external Authority whose Contracts are imported into the registry. A Provider is not authored — it is imported. Bluefly does not own Provider contracts and does not modify them. The Provider object records the import provenance.
Provider
id: globally unique identity (provider.<name>)
authority: → Authority
trust: partner | vendor | community | unknown
contracts: [ → Contract ] imported contracts from this provider
refresh: cadence at which imports are checked for updates
licensing: license terms governing use
imports:
[ {
name: import name
type: contract type
source_url: canonical upstream URL
imported_at: timestamp
hash: sha256 of imported artifact
status: imported | verified | outdated | deprecated
} ]
Runtime¶
An execution environment that can host Deployments. A Runtime is a fact about infrastructure topology, not a configuration artifact.
Runtime
id: globally unique identity (runtime.<platform>.<name>)
platform: → Platform
type: vm | container | k8s | nas | cloudflare | tailscale |
gascity | gitlab | apple-device
host: resolvable hostname or IP
network: tailscale-id | tailnet-hostname | public
status: active | maintenance | decommissioning | unknown
Examples:
- runtime.oracle.primary — OCI VM, k3s + Docker
- runtime.nas.primary — Synology DS224+
- runtime.cloudflare.global — Cloudflare edge network
- runtime.tailscale.tailnet — Tailscale overlay network
Platform¶
A named grouping of Runtimes that share a deployment boundary and operational ownership.
Platform
id: globally unique identity (platform.<name>)
authority: → Authority
runtimes: [ → Runtime ]
name: human-readable name
description: what this platform is for
Examples:
- platform.oracle — Oracle Cloud VM (k3s, Docker, Gas City)
- platform.nas — Synology DS224+ (DSM, Docker Compose, Tailscale)
- platform.cloudflare — Cloudflare edge (DNS, tunnels, Zero Trust)
- platform.tailscale — Tailscale overlay network
Deployment¶
An instance of a Capability running on a specific Runtime, accessible at a specific address. A Deployment is an object, not a configuration artifact. A single Capability may have many Deployments across many Runtimes.
Deployment
id: globally unique identity (deployment.<capability-id>.<env>)
capability: → Capability
runtime: → Runtime
address:
host: hostname or IP within the runtime
port: integer
path: optional path prefix
exposure:
hostname: public DNS hostname (if externally exposed)
protocol: http | https | grpc | ws | wss
tunnel: → Tunnel (if exposed via tunnel)
environment: production | staging | development | local
state: canonical | legacy | dev | migration | retired
zeroTrust: boolean — whether protected by identity-aware access
The Deployment object is what the Planner reads to produce a Projection. The Planner does not read Docker Compose files, Terraform HCL, or Cloudflare YAML directly.
Tunnel¶
A named network tunnel that bridges a Runtime to a public exposure layer. A Tunnel is not a Deployment — it is infrastructure that enables Deployments to be exposed.
Tunnel
id: globally unique identity (tunnel.<platform>.<name>)
platform: → Platform
type: cloudflare | tailscale | wireguard | ssh
runtime: → Runtime (where the tunnel runs)
token_ref: 1Password reference — never a literal value
routes: [ → Deployment ] deployments routed through this tunnel
Projection¶
A typed artifact emitted by the Compiler for a specific target Runtime or deployment system. A Projection is never authored. It is always generated.
Projection
id: unique within a compilation run
type: cloudflare:tunnel-ingress | cloudflare:dns |
cloudflare:zero-trust | docker:compose |
tailscale:acl | tailscale:tunnel |
gascity:pack | gascity:city |
gitlab:ci-component | security:policy |
terraform:module | kubernetes:manifest
renderer: which Renderer produced this projection
source: → [ Deployment | Capability | Contract ] (inputs)
artifact: path to generated file
hash: sha256 of generated artifact
generated_at: timestamp
The Projection type determines which generated repository receives the artifact. The Renderer determines the tool-specific format (Terraform vs Pulumi vs Crossplane, etc.).
Receipt¶
An immutable record of a compilation or deployment event. Receipts are first-class objects — not logs, not side effects.
Receipt
id: globally unique, immutable
type: compilation | projection | deployment | verification |
import | migration | retirement
authority: execution authority (bounded by role × scope × layer)
inputs: [ → object references ]
outputs: [ → artifact references ]
status: success | failure | partial
claims: [ { claim, evidence, confidence } ]
timestamp: ISO 8601
lineage: [ → Receipt ] parent receipts (composable)
Receipts flow into Beads → Dolt. They are never modified after creation. The Receipt schema is the authority for what a valid receipt looks like.
Relationships¶
Authority ──────────── owns ──────────────► Capability
Authority ──────────── operates ──────────► Runtime
Authority ──────────── publishes ─────────► Provider (external only)
Capability ─────────── publishes ─────────► Contract (1..*)
Capability ─────────── realized_by ───────► Deployment (0..*)
Provider ───────────── imports ───────────► Contract (1..*)
Deployment ─────────── projects ──────────► Capability (1)
Deployment ─────────── runs_on ───────────► Runtime (1)
Deployment ─────────── exposed_via ───────► Tunnel (0..1)
Runtime ────────────── belongs_to ────────► Platform (1)
Tunnel ─────────────── runs_on ───────────► Runtime (1)
Tunnel ─────────────── routes ────────────► Deployment (0..*)
Compiler ───────────── reads ─────────────► Contract (*)
Compiler ───────────── reads ─────────────► Deployment (*)
Compiler ───────────── emits ─────────────► Projection (*)
Compiler ───────────── emits ─────────────► Receipt (*)
Projection ─────────── targets ───────────► Runtime (1)
Projection ─────────── derived_from ──────► Deployment (*)
Receipt ────────────── records ───────────► Projection | Deployment | Compilation
Receipt ────────────── stored_in ─────────► Beads → Dolt
Object Graph (Summary)¶
Engineering Standards
│ governs
▼
Authority ◄──────────────────────────────────────────────┐
│ owns │ is_authority_of
├──► Capability │
│ │ publishes Provider ───┘
│ └──► Contract (typed) │ imports
│ │ └──► Contract (typed)
│ operates │ (both feed the compiler)
▼ ▼
Runtime ◄──── Platform Compiler ────► Projection ────► Generated Repo
│ hosts │ emits (never authored)
▼ ▼
Deployment Receipt ────────────────────────────► Beads → Dolt
│ routes_via
▼
Tunnel
Identifiers¶
Every object has a globally unique, hierarchical identity in the format:
<type>.<domain>.<name>
Examples:
authority.bluefly
authority.acquia
authority.google
capability.platform.compliance
capability.platform.authentication
capability.platform.agent-ui
capability.provider.acquia.content
contract.capability.platform.compliance.openapi
contract.capability.platform.agent-ui.ag-ui
provider.acquia
provider.anthropic
runtime.oracle.primary
runtime.nas.primary
runtime.cloudflare.global
platform.oracle
platform.nas
platform.cloudflare
deployment.compliance.oracle.production
deployment.compliance.drupl.production
tunnel.cloudflare.oracle-platform
tunnel.cloudflare.duadp
Identifiers are permanent. Names may change. Identifiers may not.
Invariants¶
- Every Capability has exactly one Authority.
- Every Deployment has exactly one Capability and exactly one Runtime.
- Every Contract has exactly one Capability.
- Every Provider contract has a complete import manifest (URL, hash, timestamp, status).
- Every Projection is generated — never authored.
- Every Receipt is immutable — never modified after creation.
- No object is both Authored and Generated.
- No runtime state is modified except through a Deployment, which requires a Receipt.