04 — The spec system: what makes it a platform

This is the page that justifies the rename. One abstraction, sixteen implementations, three generalisation mechanisms, and a documented path for specs that live outside the repo. Full data in specs__catalogue.json.

1. The catalogue

Seventeen directories; sixteen registered (sg_edge has no manifest.py and is therefore invisible to the registry — see §5).

Nine stable, seven experimental. Boot times span 15 seconds (mitmproxy) to 600 seconds (docker, content_proxy) — a 40× range, which is itself a good argument for the manifest carrying boot_seconds_typical as a field rather than a footnote.

These are not documents. Each is a working package with manifest.py, api/routes/, cli/, service/, schemas/, tests/, and often ui/.

2. Three mechanisms, and none of them is capabilities.json

(a) manifest.py — the registry

Every spec exposes a typed MANIFEST of Schema__Spec__Manifest__Entry:

spec_id · display_name · icon · version · stability · boot_seconds_typical
capabilities · nav_group · extends · soon · create_endpoint_path

"Single source of truth. Every spec's manifest.py exposes MANIFEST."

This is where the 30 April brief's criterion 5 was deliberately improved on — it asked for specs stored as JSON with a spec.json; what shipped is typed Python with a schema. Better, and the site should say so rather than scoring it as a miss.

(b) Spec__Routes__Loader — convention-based discovery

spec_id 'docker' resolves to sg_compute_specs.docker.api.routes.Routes__Docker__Stack. No registration list, no import graph to maintain.

And a design note worth publishing because it cuts both ways: "Specs without a route class are silently skipped." Convenient during development; a silent-failure mode in production. A spec that loses its route class disappears from the API with no error.

(c) Spec__CLI__Builder — generated CLIs

Per-spec CLIs are generated, not written. The builder registers a uniform verb set for every spec:

list · info · create · wait · health · connect · exec · delete · ami list|bake · cert

Sixteen specs, one CLI surface, written once. This is the strongest single argument that the thing is a platform: adding a spec costs a manifest, a route class and a service — the CLI comes free.

(d) Entry points — specs outside the repo

Spec__Loader already supports PEP 621 entry-point discovery under the group sg_compute.specs, alongside the in-repo walk. The 30 April "Spec Standard: External Repos" brief specified it.

Third-party specs are architecturally supported and untested in the wild. That is a genuinely interesting claim and it should be published as a claim, not a feature — with an invitation to try it.

⚠️ What is not the mechanism

capabilities.json:

{ "app": "sg-playwright", "version": "v0.1.29",
  "axioms": ["statelessness", "least-privilege-by-declaration", "self-description"],
  "declared_narrowing": [] }

Frozen at v0.1.29 while the repo is at v0.2.71 — 42 minor versions. It is COPY'd into the image and served verbatim at GET /admin/capabilities, and the repo's own documentation says not to read it:

"The UI reads GET /health/capabilities (the live Schema__Service__Capabilities, populated by Capability__Detector) — never the stale capabilities.json."

The live mechanism is Capability__Detector, which detects the deployment target from environment variables (laptop | ci | claude_web | container | lambda) and builds capabilities at runtime. Present that as the self-description story; mention capabilities.json only as a known-stale artefact, or delete it.

The three axioms it names — statelessness, least-privilege-by-declaration, self-description — are good, and they are actually implemented (01__ §1, the JS allowlist, /health/capabilities). Rescue the axioms from the stale file and put them on the front page.

3. What this makes possible — and what it does not yet

Possible today. Sixteen ready-to-launch environments, each with a typed manifest, a stability rating, a measured boot time, a generated CLI and auto-discovered routes. The 30 April brief's own framing:

"This is the simulated AWS Marketplace: a catalogue of pre-configured, ready-to-launch environments."

That is exactly what /specs/ should be, and it is real.

Not yet, and the site must say so:

• create_node covers 3 of 16 specs. EC2__Platform._service_for raises NotImplementedError for anything but docker, podman, vnc. The other thirteen create nodes through their own CLI and service paths, not the control-plane API. The uniform CLI is real; the uniform API is not.
• One platform. Platform.name is documented as 'ec2' | 'k8s' | 'gcp' | 'local'. Only EC2 exists.
• No multi-node stacks. Routes__Compute__Stacks returns a list; Cli__Compute__Stack is unwired.
• sg_edge is unregistered — 9,108 lines, the second-largest spec directory, and invisible to the registry because it has no manifest.py. Either register it or move it out of sg_compute_specs/; leaving the largest unregistered thing inside the spec tree is confusing for anyone reading the catalogue.

4. Why the family view matters more than the list

Grouped by what they actually do:

Vault specs are within 300 lines of browser specs. That single row is the clearest possible statement that this is not a browser service — and it points at the integration the rest of the estate wants: vault-writes as a first-class capability, already implemented twice.

It also explains why the artefact-sink gap (01__ §6) matters more than it looks. Two specs exist whose capability is literally vault-writes, and the generic artefact writer's vault path raises NotImplementedError. The capability exists at the spec layer and not at the platform layer. That is 08__ Q4.

5. How to write /specs/

1. One page per spec, generated from manifest.py — the manifest already carries everything a page needs. Do not hand-write sixteen pages that will drift.
2. Lead with the family view, not the alphabetical list.
3. Show stability and boot time in the header, because they are what a reader is actually choosing on.
4. State the create_node gap per spec — three of sixteen is a real limitation and hiding it produces support questions.
5. Publish the entry-point contract as an invitation: here is how a spec that lives in your repo joins this catalogue.
6. Generate the page from the tree, at build time. Every stale artefact in this repo became stale because it was written once by hand.

This document is released under the Creative Commons Attribution 4.0 International licence (CC BY 4.0).

Published on sg-compute.sgit.ai under CC BY 4.0. Source: the sg-compute.sgit.ai brief pack v0.33.62, 24 August 2026, by Dinis Cruz via the SG/Send Librarian, with AI co-authorship (Claude, Anthropic).

source: /briefs/05__the-serverless-argument.md