Protocols

Putnami's three pillars — the frameworks (Go and TypeScript), the tooling (CLI, extension SDK, CI), and the platform (Putnami Cloud and other deploy targets) — do not integrate through shared code. They integrate through protocols.

A protocol is a wire contract: a JSON shape with a published schema, a corpus of valid and invalid fixtures, a strict parser in every language that implements it, and at least one real consumer. Nothing in Putnami is allowed to become a shared assumption. It becomes a protocol, or it does not cross a boundary.

This is the layer that turns the principles from statements into things a build can check.

Why this layer exists

Most stacks integrate by convention. The CLI knows what the framework emits because the same person wrote both. That holds until a second language, a second consumer, or an agent arrives — and then the convention lives only in someone's head, and drift is undetectable rather than merely unfixed.

Putnami's principles ask for guarantees a convention cannot carry:

The principle What the protocol layer does about it
Deterministic and reviewable Intent is a JSON document in git, strict-parsed against a published schema, canonically serialized, and addressable by digest. Drift is a test failure, not a surprise.
Observable by construction One versioned JSONL event envelope for every job, and one OTLP/JSON shape exported by every runtime — hand-rolled to the wire, proven byte-identical across languages.
Automation is a first-class user Exit codes, --output modes, and the machine documents are a versioned contract, not an implementation detail that can move under an agent's feet.
Security is foundational Reachability, identity claims, and signing-key lifecycles are declared and fail closed. An ambiguous route pattern fails the build rather than widening an allowlist.
Data ownership is non-negotiable Database, storage, and transaction contracts are declaration-only. They describe what a workload needs and what it was given; they never own the data plane.

The protocol layer is also what makes the polyglot claim honest. TypeScript and Go do not "support the same features" — they are validated against the same fixture corpus, and where they produce artifacts, those artifacts are pinned byte-identical.

From intent to infrastructure

The chain the rest of the documentation describes in pieces is, concretely, this:

You declare The protocol that carries it Who reads it
putnami.workspace.json, putnami.json
workspace and project identity		 workspace, extension the CLI, every extension, every task
An HTTP handler
the HTTP framework		 http-routes your public edge, as a generated default-deny allowlist
A repository, a migration
persistence		 database, migration, transaction Go and TypeScript adapters, the deployer, the test provisioner
An event handler
the events framework		 events clients, Event Servers, the managed Event Plane
An infrastructure need, next to the code that needs it
infra requirements		 infra the build aggregator, then one merged artifact per deploy target
A job
the job runner		 job, runtime the CLI, the language SDKs, your CI
putnami.ci.json
CI intent, reviewable in git		 ci any execution plane — it reads the document, it never widens it
Nothing. It is derived.
your project's own facts		 capabilities, contracts, agentcontext your agent, through putnami context pack and MCP

Read the last row again. Every other row is something a developer writes once, next to the code it describes. The last row is what the system derives from all of them — and it is the row an agent reads.

An agent does not need to be taught your repository. It reads the same contracts your build reads.

putnami context pack aggregates one project's framework-owned facts into an agent-context document: identity and dependency graph, composition roots, capability / contract / infra / migration references, representative source ranges, tests, adjacent docs, and provenance. It aggregates by reference — paths, digests, and ranges, never file content — and runs a fail-closed publish-safety gate before anything leaves the repository. The read-only MCP agent_context tool serves it per request.

The rest of the operational surface is contracted the same way:

  • --output=json / --output=jsonl and the exit-code taxonomy are the cli protocol, versioned and conformance-tested from both the Go and the TypeScript implementation.
  • --impacted gives an agent the blast radius of a change before it acts.
  • The runtime event stream means the agent watching a job and the human reading the log are parsing the same lines.
  • doctor reports production-readiness gaps under a deployment profile, with a frozen check-code taxonomy and a baked remediation per check — so "what is wrong and what do I do about it" is data, not prose.

This is the difference between a project an agent can edit and a system an agent can operate. The second one requires a contract.

The protocol map

Every protocol below owns exactly one boundary. Its Go module name (go.putnami.dev/protocol/<name>) deliberately stands apart from any single consumer rather than belonging to whichever pillar defined it first.

Workspace and intent

Protocol What it carries
workspace putnami.workspace.json and putnami.json: discovery, config layering, extension declarations, predictable resolution across global, workspace, and local scopes.
extension putnami.extension.json: commands, tasks, pipelines, flags, and cache policy — declared, not coded.
template putnami.template.json: project templates stay portable and inspectable instead of hiding metadata in scripts.
ci putnami.ci.json: triggers, branch rules, jobs, runners, publish/deploy clauses — plane-neutral, canonically normalized, digested, and rejecting literal credentials.
features Feature intent, repository evidence, durable specs, and the verification report that connects them. Maturity is an evidence ladder, not an adjective.
support The closed vocabulary behind putnami.support.json — one reviewed authority for what you may depend on.
architecture Architecture Rules as Code and Domain Access contracts. Data may be copied. Authority may not be copied. Opt-in, and free to change its wire format without a migration path.

Execution, diagnostics, and observability

Protocol What it carries
cli One exit-code taxonomy, one --output vocabulary, the reserved global-flag registry, and the machine documents (JSON, JSONL, MCP, session / plan / report files).
runtime The JSONL event envelope: logs, progress, phases, diagnostics, metrics, artifacts, results.
job The --putnamiContext document: workspace / project / extension / job identity, merged params with coercion rules, and the env-var mirror.
config Schema manifests, canonical field types, SHA-256 hashing, remote resolution, and dimension layering — identical in Go and TypeScript.
diagnostic One structured finding format, so no strict parser in the system invents its own error shape.
telemetry OTLP/JSON metrics, traces, and logs — hand-rolled to the wire, byte-identical across languages, pinned by digest.
platform /healthz, /livez, /readyz, /version, opt-in pprof: the same operational surface from every runtime, so operators never special-case a language.

Data

Protocol What it carries
database Requirement manifests, bindings, and test bindings: logical datasources, exactly-one-transport connections, schema semantics, test provisioning policy.
transaction The unit-of-work descriptor and result envelope, with a closed outcome taxonomy and a retryable advisory that must agree with it.
migration Startup, locking, state tracking, and rollback guarantees — plus bundle digest equivalence across runners.
storage Object storage declared provider-neutrally: access levels, isolation scopes, signed-URL capability, lifecycle. Declaration only; the data plane stays out.

Reachability, events, and infrastructure

Protocol What it carries
http-routes A provider-neutral reachability inventory with explicit public-edge visibility, provenance, canonical ordering, and a stable digest. Ambiguous patterns fail closed.
events Envelopes, stream frames, discovery, endpoint profiles, and a conformance runner that can be pointed at a deployed Event Server.
infra Requirements committed next to the code, workload runtime intent, overrides, and the aggregated manifest with deterministic merge rules and provenance.

Build, publish, and distribution

Protocol What it carries
cache The remote build cache wire: negotiate, store/commit, batched writes, Action Cache and CAS shapes, capabilities, presigned transfers — plus the provider RPC.
oci Optional registry fast paths layered on the OCI distribution spec, always degrading to the standard API elsewhere.
gomod Authenticated private Go module uploads with channel routing a plain VCS tag cannot express.
registry Publisher authentication without the framework owning a host list, a recipe model, or a stored credential. Absence of a credential is a supported answer.
sitecontent Content produced in one repository, mounted into a site in another as one content-addressed, self-verifying bundle. This page's neighbours arrive that way.

Security

Protocol What it carries
identity The consumer-side identity vocabulary — well-known claims, principal kinds, the typed claims shape — authored once and generated into every language.
keyring The signing-key state machine with a legal-transition table, the private keyring and its public JWKS projection, and a versioned credential-digest grammar. Vocabulary and validation only; no cryptography.

Agents and assurance

Protocol What it carries
agentcontext The deterministic, redaction-safe per-project orientation document agents read instead of rescanning your repository.
capabilities Everything one project contributes — config, schemas, discoverers, migrations, infra, health, lifecycle, versions — with provenance per entry.
contracts The canonical IR of a project's vocabulary, lowered by one compiler into Go and TypeScript types, JSON Schema, OpenAPI inputs, discovery metadata, and docs.
doctor Production-readiness findings under a deployment profile, a frozen check-code taxonomy, and waivers you commit deliberately rather than forget silently.
doccov No wire shape of its own: a ratchet that fails the build when too many wire fields cannot be explained from the types and schemas alone.

The reviewed support status of every protocol is published on Support status, which is generated from the workspace catalog. This page deliberately does not restate it — a status has exactly one home.

What earns the name

A package in protocols/ is not a protocol because of where it lives. It meets a bar:

  1. An index entry — it is declared in the map, not discovered by accident.
  2. A JSON schema for every wire shape.
  3. A fixture corpus with valid/ and invalid/ cases. This is the cross-language test surface.
  4. Strict parsing and a conformance test that runs the corpus through the parser and the validator.
  5. At least one real consumer, or an explicit defined, not yet adopted marker. A protocol without consumers is a spec, not a contract.
  6. A versioning guard when the contract is versioned: the protocol version is pinned by test, and committed artifacts enforce an acceptance window.
  7. Cross-language equivalence fixtures when more than one language implements it.

Point 5 is the one that keeps this directory honest. Point 3 is the one that makes "polyglot" mean something: the fixtures are shared, so a Go implementation and a TypeScript implementation cannot quietly disagree.

Conformance is the proof

The repository publishes a conformance matrix — who implements or consumes each protocol today, across the CLI, the extension SDK, the Go framework, the TypeScript framework, and the platform. It distinguishes three states:

  • conformant — tested against the protocol package or its fixtures;
  • aligned by hand — mirrored deliberately, drift possible, and marked as such;
  • not a consumer.

That middle state is published on purpose. A matrix that only showed green would be marketing; the value of this one is that it names exactly where the guarantee is a test and where it is still a promise.

Where two languages both produce an artifact, equivalence is pinned rather than assumed: config hashes, migration bundle digests, infra manifests, capability and contract serializations, and the telemetry wire are all compared byte-for-byte against shared goldens.

Where protocols land: dev, cloud, intelligence

The same contracts carry across all three Putnami surfaces. That is the point of having them.

putnami.dev — the frameworks and the tooling — is where intent is declared and derived. Protocols make that declaration precise: what a project is, what it exposes, what it needs, and what it emits.

Putnami Cloud adds operational depth on top of the same documents: release provenance, runtime correlation, incident context, rollout protection. It reads http-routes to build an allowlist, infra to provision, ci to execute, telemetry to observe. It does not get a private dialect.

Putnami Intelligence makes the workspace queryable: agent orientation over MCP, a versioned workspace index, and spec-driven development — features, specs and architecture recorded next to the code. The review-and-audit loop — findings over versioned evidence, with freshness and receipts — is where this is going. It is a standalone product: it delivers value with neither Putnami frameworks nor Putnami Cloud, through provider adapters that normalize external systems into the same evidence model. Adopting putnami.dev improves its structural precision; adopting Putnami Cloud improves its operational depth.

And Cloud is held to the same rule as anyone else: it integrates through the same published contracts available to third-party adapters. Its advantage is zero-configuration correlation across workspace, environment, revision, deployment, and telemetry — not a private semantic backchannel.