deploy-kit

Everything needed to get an application deployed: the model an application author writes, the decision record that justifies every rule in it, and, as it lands, the compiler that turns that model into deployable artifacts.

Status: pre-implementation. The model and its decision surface are here and enforced by CI. The compiler is being brought over from deploy-config-schema, which stays alive and authoritative until this repository can render the estate. Nothing here deploys anything yet.

What is in here

Path	What it holds
CONTEXT.md	The vocabulary. One term, one meaning; also the naming authority for code.
docs/architecture.md	Normative for code structure, the way spec/v1 is normative for the model.
docs/adr/	The decision surface, one directory per decision domain. Machine-checked.
docs/adr/model/	The v1 model: premises carrying falsifiable claims, decisions resting on them. The register counts both.
docs/adr/architecture/	The compiler's own structure. Pointers resolve against docs/architecture.md, not spec/v1.
docs/adr/deferred/	Co-testing, still parked, and the retired push-delivery design, each record with its fate. Not v1.
spec/v1/	The normative specification. Chapters 00–60, delivery (55) among them, including the two authored documents: Project Intent (10) and Platform Intent (14).
spec/v1/diagrams/	One drawn diagram per chapter, as an SVG with the editable draw.io diagram embedded. One palette; colour carries the layer.
spec/v1/examples/minimal/	The smallest complete Application: one project, one Application, one Process, 26 authored lines reaching 10 objects.
spec/v1/examples/	Worked examples: real Applications from this estate, written in the model.
emf/	The model-driven implementation: a Java build on Ecore, Xtext, OCL, QVT-Operational and Acceleo, held to parity with the production implementation and deleted after the course.
scripts/	The gates: the ADR contract, links, manifests and layer boundaries. TypeScript that Node runs directly (tooling).

The shape of the model

The three-model pipeline: three models, each joined to the next by a transformation, with the middle one as a contract (0003). They are stages of a pipeline, not metalevels, which is why "metamodel" here means a language definition and nothing else (CONTEXT.md):

1. Project Intent: hand-authored, requirements only. What an application owner knows and nobody else does: its cold-start budget, what its data is worth, which paths answer readiness.
2. Resolved Deployment: derived. Every platform decision, assigned from pinned, digested inputs (0006) and reviewable as a diff.
3. Deliverable Set: serialization only. No decisions.

Two rules do most of the work. Contention decides authority (0004): a value is platform-assigned exactly when it must be unique estate-wide or draws on a shared finite resource; everything else belongs to the Application. And derivation is total (0005): every hand-tuned value in the live estate must be reachable from something only the Application could have declared.

Reading it

Start at spec/v1/00-overview.md for the model, or docs/adr/README.md for why each rule is what it is.

ADRs justify; the spec is normative. Where an ADR and its normative: pointer disagree, the spec wins and the ADR is what gets fixed: CI resolves every pointer against a real heading, so the two cannot drift silently.

A premise carrying claim: open is decided in direction but not yet tested. It names its owner and the exact command or measurement that would settle it. Three of the eight are currently false as built, and say so.

What is deliberately not here

How one unit's tests gate another's deploy (co-testing) stays parked. How the estate deploys is part of the model since 2026-09-24 (0050): Flux pulls a signed, pinned render per Project and Flagger switches it, as chapter 55 specifies. The model's three demands on delivery are what that chapter meets:

Demand	Decided in
Release Unit atomicity: no member switches until every member is healthy	0052
Destructive operations gated by Durability Class	0018
Rendering only from pinned, digested inputs	0006, 0034

The parked co-testing work, and the push design delivery retired, are in docs/adr/deferred/.

Local checks

nvm use             # Node 24.21.0, pinned in .nvmrc
npm ci
npm run verify      # lint, format, typecheck, ADR contract, tests + coverage

npm run lint:adrs alone runs the decision-record contract, and npm test runs the suite without enforcing coverage. npm run test:coverage (part of npm run verify) enforces the ratchet in vitest.config.ts: statements 99.51%, branches 97.95%, functions 100%, lines 99.46%.

The command

deploy-kit is the compiler's command line, in src/cli/. The package ships it as a bin, built to JavaScript before the package is packed, so a repository that pins the package runs npx --no-install deploy-kit; from a clone it runs as below, with no build. It has three commands. Each reads and writes directories and never the registry: a workflow pulls fragments into a directory, runs the command, and pushes what it wrote.

# Check a set of authored files read together: a Platform document, project files, env files.
node src/cli/index.ts validate spec/v1/examples/platform/platform.intent.yml \
  spec/v1/examples/minimal/notes.project.yml ...

# Pack one release of a project file, or of the Platform document, as an Intent Fragment.
node src/cli/index.ts publish spec/v1/examples/minimal/notes.project.yml \
  --repository JorisJonkers-dev/notes --source-sha <commit> --version 1.4.0 --out fragment/ \
  [--images-lock images.lock.yml]   # packs the project's share of the lock its build wrote

# Compose the estate from pulled fragments, each directory holding a fragment and the
# `ref` its pull resolved, and write the artifacts, the lock and what to report.
node src/cli/index.ts compose --platform platform/ --fragments fragments/ \
  --cluster-state cluster-state.yml --schema-package-integrity <sha256:...> --out composed/ \
  [--held held/] [--pins pins.json] [--lock lock.json --lock-commit <commit>]

• Exit status. A command exits 0 when the inputs are accepted, 1 when they are refused, and 2 when it was called wrongly.
• Diagnostics. They go to stderr for a human. Under --json they go to stdout as an array.
• What compose writes. Under its output directory, artifacts/<name>/ holds one directory per delivered Project, and _estate once no Project is legacy. Beside it, the lock.json file holds the composition lock, and the composition.json file holds each artifact's content hash and whether its pin moves, plus the commit statuses and the Project conditions the workflow reports.

Conventions

• CONTRIBUTING.md: Conventional Commits, PR flow
• VERSIONING.md: the versioning contract
• SECURITY.md: reporting
• AGENTS.md: the one agent contract every tool reads; CLAUDE.md imports it and adds Claude-specific notes only