pig/docs/ontology.md

The ontology

Why PIG is shaped the way it is. Read packages/core/src/ontology.ts alongside this — the code carries the same reasoning in comments, and it is the version that cannot go stale.

The one table that matters

capacity_commitment  ──┐
   (what we bought,    │
    at a known cost)   │
                       ├──▶  allocation  ──▶  margin, utilisation, idle
                       │     (what we sold,
demand_deal          ──┘      at a known price)
   (what we sold)

Margin, utilisation and idle capacity all fall out of that single join. No generic CRM can compute any of them, because none has a concept of a cost-bearing commitment sitting behind the pipeline.

Cost is charged against the full commitment, not only the hours that sold. Unsold hours are already paid for. Charging only the allocated share would report a healthy margin on a block that is losing money — precisely the failure this system exists to prevent.

Three teams

Supply, demand, and research. Research is first-class rather than an afterthought: internal research burn is real capacity consumption competing with revenue for the same GPUs, and margin math that cannot see it is wrong.

Pipelines

Demand — qualification → legal → scoping → proposal → procurement → POC → deployment → expansion. Note that legal sits second. Customers do not hand workloads to an infrastructure provider before paper is executed. Most CRMs put contracting at the end of the funnel and are simply wrong about it here.

Supply — sourced → qualifying → technical diligence → financial diligence → pricing → contracting → onboarding → live → renewal. Qualification is split in two because accepting capacity is a two-key decision: engineering judges whether the cluster can do the work, finance judges whether the economics clear. Both verdicts are recorded attributably.

Capacity is a shape, not a rectangle

A commitment carries shape: {intervals[], quantities[]} — how many GPUs are held during each interval. Real contracts ramp across tranches and step down at checkpoints. A single start/end/total flattens that and then reports availability that does not exist in the month someone wants it.

Availability at any instant is therefore:

available(t) = shapeQuantityAt(t) − Σ overlapping allocations(t)

Holds reserve; they do not sell

A live hold removes capacity from everyone else's availability — otherwise two sellers promise the same GPUs — but does not count toward utilisation or revenue, because it has not sold. Conflating the two is how a pipeline of optimistic holds comes to look like a full book. Holds expire on a timer so a stalled deal releases inventory automatically.

Security tiers are ranked, not labelled

community_cloud < secure_cloud < government. A requirement is satisfied only by capacity at or above the tier it asked for, which is why SECURITY_TIER_RANK exists and why the matcher compares ranks rather than equality. A government (sovereign) requirement served from community capacity is not a near miss; it is the wrong answer, and an equality check would have made it invisible rather than merely wrong.

Service levels come in three shapes

A compute aggregator generally cannot offer a conventional uptime guarantee on capacity it resells and does not control, and says so publicly. So slaKind distinguishes:

• none — self-serve, no commitment at all
• credits_policy — a reliability tier plus service credits. Not an uptime guarantee, and must never be displayed as one
• negotiated — a real signed SLA with committed, measurable metrics

Remedies matter as much as targets. remedyType includes fee_abatement, where payment obligations are cancelled for affected capacity until service is restored — uncapped in duration and materially better than a capped credit. It cannot be expressed as a credit percentage, so it gets its own representation.

Export control is a predicate, not a flag

US controls on advanced computing apply an ultimate parent test that reaches through the corporate tree: an entity can be restricted because of where its parent is headquartered, even when the entity itself sits somewhere unrestricted. Country of incorporation is therefore not a valid key.

Compliance is evaluated on the allocation edge — this buyer, this beneficial owner, this physical jurisdiction — recorded with its reasoning and rule version, and re-evaluated on resale or migration. See packages/db/src/schema/compliance.ts. PIG records and surfaces; it does not make the legal determination for you.

Evidence

Agent-derived claims land in facts with a confidence score, a band, evidence and a source URL. Only verified claims self-apply; anything weaker waits for a human. An agent permitted to write unattributed claims will eventually write a wrong one, and nobody will be able to tell which.

The same principle governs seed data about real people: every record carries a grade and a citation, authorship is never promoted to employment, and no email address is ever inferred.