Named by convention so a coding agent finds it without being told. Written to
get someone productive from a cold start without having to reconstruct the
reasoning from the diff.
Four sections carry the weight. The architecture rules that must not be broken,
each of which fails silently rather than loudly — intelligence never lives in
the API, authentication is not authorization, cost is charged against the full
commitment, sold and held are different things. The traps that have already
cost time here, with the specific symptom each produces: onConflictDoNothing
being a no-op without a constraint, z.coerce.boolean turning "false" into true,
grid children needing min-w-0, Drizzle emitting a cast Postgres rejects, the
CSP allowing exactly one inline script by hash, and the Prime Intellect API
quoting node totals rather than per-GPU prices. The conventions, including that
comments explain why rather than what. And an explicit start order.
The last section says what not to do, which is the part most easily lost: do
not copy component files from the MIT project we borrowed ideas from, do not
open self-registration on a shared identity provider, do not put a production
key on the CI runner, do not weaken the guard that refuses to serve the CRM
unauthenticated, and do not invent email addresses for real people.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
PIG is an agent-native CRM for two-sided AI-compute companies: businesses
that buy GPU capacity from providers and resell it. Their business is the
spread between two pipelines, which is precisely what a generic CRM cannot
represent.
The load-bearing decision is the `allocations` table, joining a
capacity_commitment (what we bought, at a known cost) to a demand_deal
(what we sold, at a known price). Margin, utilisation and idle capacity all
fall out of that one join. Cost is charged against the full commitment
rather than only the hours that sold, because unsold hours are already paid
for and any other treatment flatters a block that is losing money.
Domain decisions worth noting, each grounded in how this market operates:
- Demand stages put `legal` second, not last. Customers do not hand
workloads to an infrastructure provider before paper is executed.
- Supply qualification splits technical from financial diligence, recorded
attributably. Accepting capacity is a two-key decision.
- Capacity carries a time SHAPE (intervals + quantities), not a window.
Commitments ramp and step down; a rectangle reports availability that
does not exist in the month someone wants it.
- SLAs model three distinct shapes: none, a reliability tier plus credits
policy, and a negotiated agreement. Aggregators generally cannot promise
uptime on resold capacity, but negotiate heavyweight paper upstream.
Remedies include fee abatement, which is materially better than a capped
credit and is not expressible as one.
- Export control is a predicate on the allocation edge, evaluated against
the ULTIMATE parent's jurisdiction. Country of incorporation is not a
valid key, so this cannot live as a flag on an account.
- Agent-derived claims land in `facts` with a confidence band and evidence.
Only verified claims self-apply; weaker ones await review.
- The API never calls the agent. It writes to a leased queue, guarded by a
partial unique index on unfinished work.
Verified: typechecks clean, migration generates and applies to Postgres 16
(31 tables, 24 enums, 117 indexes).
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
karti