matsuri 0.1.0 → 0.3.0

data/docs/design/boot.md

@@ -0,0 +1,131 @@
+# Boot Design
+
+This describes the constraints and properties of the boot design: the
+sequence that takes a process from an invoked binary to a command
+running against an environment, with the repo's vocabulary loaded. This
+is intended to provide both a grammar for how a Matsuri repo boots, and
+for how the boot can be extended.
+
+The promises mentioned in this document are understood as concepts from
+Promise Theory.
+
+## Framing
+
+Boot is where several parties meet: the matsuri gem, the platform repo,
+the shell that invoked the binary, and the operator or agent that typed
+the command. Each party can make promises only about what it owns. The
+design assigns each resolution question of boot to exactly one owner, as
+layers: each layer makes one promise to the layers above it and assumes
+only the layers below.
+
+## Promises
+
+Boot resolves five questions, in order, each with one owner:
+
+1.  Which matsuri runs — promised by the repo's Gemfile.
+2.  Where the repo is — discovered from the working directory.
+3.  What code the repo contributes — loaded by matsuri from the repo's
+    `lib/`.
+4.  Which environment is meant — named by the first positional argument.
+5.  What is activated — declared by the repo's initializer.
+
+Then the command dispatches. Everything below is a constraint on these
+ownerships and the properties each induces.
+
+## Constraint: version binding belongs to the repo's Gemfile
+
+The platform repo locks its matsuri version, and the versions of any
+plugins, in its own Gemfile. Matsuri never resolves its own version, and
+nothing in boot selects among installed versions. A repo that wants the
+binding to be unavoidable ships a `bin/matsuri` wrapper whose whole job
+is to pin `BUNDLE_GEMFILE` and exec `bundle exec matsuri`.
+
+Properties:
+
+- The matsuri a repo runs against is a recorded, reviewable promise.
+  Upgrades are a diff to the lockfile, per repo, on that repo's cadence.
+- Two repos on one machine can promise different matsuri versions
+  without negotiation.
+- The wrapper has no logic to drift. Pin and exec is the entire content;
+  everything else the old wrappers did is owned by a layer below.
+
+## Constraint: discovery anchors at the working directory
+
+Matsuri finds the repo by walking up from the working directory looking
+for `config/matsuri.rb`. The contract of use is to invoke from the repo
+base — where the Gemfile is, in the manner of terraform or chef — and
+the walk-up exists as forgiveness for subdirectory invocation, not as a
+second contract. No environment variable, registry, or wrapper location
+tells matsuri where repos live; standing in the repo is the claim.
+
+Properties:
+
+- Repo identity and version binding coincide. Invoked at the repo base,
+  the repo that discovery finds is the repo whose Gemfile bound the gem;
+  there is no configuration by which they diverge.
+- The invocation is portable. A command that works in one checkout works
+  in another path, another machine, another agent's worktree — nothing
+  about boot is anchored to an absolute location.
+- Failure is immediate and names its cause: no `config/matsuri.rb` on
+  the walk up means no repo, before any command logic runs.
+
+## Constraint: the repo contributes code through matsuri, not through its launcher
+
+Immediately after discovery, matsuri prepends the repo's `lib/` to the
+load path. The repo does not acquire a gemspec to get load-pathing from
+bundler, and the wrapper does not export load paths. A platform repo is
+an application; matsuri is what makes it loadable.
+
+Properties:
+
+- Requiring the repo's own library behaves identically under
+  `bundle exec`, a bare gem install, and a checkout. The repo's
+  extension pattern makes no assumption about who launched the process.
+- The repo never misdeclares itself as a gem. No version, no files list,
+  no packaging promises made solely to obtain a load path.
+- Every repo-authored file in the boot chain — configuration, platform
+  definitions, the initializer — may assume `lib/` is loadable, because
+  the load path precedes all of them.
+
+## Constraint: the environment has exactly one source
+
+The environment is the first positional argument:
+`matsuri <env> <verb> ...`. There is no ambient override and no
+detection from the binary's name. A repo that wants per-environment
+entry points writes them as argument injection — `bin/staging` is
+`exec bin/matsuri staging "$@"` — which keeps the sugar in the repo and
+out of the grammar.
+
+Properties:
+
+- The command is self-describing. What was typed, what `ps` shows, what
+  the CI log recorded, and what matsuri resolved are the same string;
+  during an incident there is no exported variable to go find.
+- One invocation grammar. Every surface that composes a matsuri command
+  — documentation, pipelines, agents, muscle memory — constructs the
+  same shape, and the environment slot cannot be consumed twice.
+- Renaming or symlinking the binary is a non-event. No name is
+  significant, so no name is a trap.
+
+## Constraint: declaration and activation are separate promises
+
+The Gemfile declares what exists; the initializer activates what this
+repo uses. Configuration (`config/matsuri.rb`, `config/platform.rb`) is
+declarative — defaults and environment definitions, no requires. The
+initializer (`config/initializer.rb`) is the one site that requires
+plugins and the repo's own library, and it runs after configuration is
+loaded, before any command logic.
+
+Properties:
+
+- A declared-but-unactivated plugin costs nothing and breaks nothing.
+  Adding a gem to the Gemfile is not yet a decision about boot.
+- Activation order is repo-owned and readable in one file. What this
+  platform loads, and in what order, is the initializer — not a search
+  across configuration.
+- Plugins activate against resolved configuration. By running after the
+  configuration layer, an initializer may branch on environment or
+  settings without ordering hazards.
+- The boot sequence is a fixed spine — bound, discovered, loadable,
+  named, configured, activated, dispatched — and extension happens at
+  the one joint designed for it.

data/docs/design/ssa.md

@@ -0,0 +1,142 @@
+# Server-Side Apply Design
+
+This describes the constraints and properties of matsuri's server-side
+delivery design: how one repo's declaration coexists with other writers
+on the same Kubernetes objects. This is intended to provide both a
+grammar for using server-side delivery and for extending it.
+
+The promises mentioned in this document are understood as concepts from
+Promise Theory.
+
+## Framing
+
+Under server-side apply, the apiserver merges by field ownership: an
+object is a meeting place of managers, each owning the fields it last
+sent. The merge is a fold across parties, but not a defined fold — the
+managers are unordered, and there is no uniform identity element, so the
+structure is not fully monoidal. Each party can promise only its own
+fields.
+
+Matsuri's position in that ensemble is fixed: own exactly what the
+definition declares, cede everything else. Every constraint below exists
+to hold that position. The seeding protocol exists because creation is
+the one moment the position cannot be held by a single apply.
+
+## Constraint: ownership follows declaration, and nothing is read back
+
+The ongoing payload contains exactly the fields the repo manages.
+Matsuri never reads live cluster state to decide a declaration: a field
+another party rolls — an image a deployment operator delivers, a count
+an autoscaler moves — is omitted from the payload, not read back and
+re-sent.
+
+Properties:
+
+- The declaration is the ownership record. What the repo owns on the
+  cluster is what its definitions say, reviewable in the same diff that
+  reviews any other change; there is no second registry of claims.
+- Other writers take their fields uncontested. A controller that scales
+  or a deliverer that rolls an image is never fought, because the repo
+  never speaks about those fields at all — there is no flapping between
+  two sources of truth.
+- A conflict is information. Because the payload never carries a field
+  by accident of read-back, a conflict always marks a field two parties
+  genuinely both claim — never noise from a value that merely drifted.
+
+## Constraint: empty is the identity element, and the identity is never serialized
+
+An empty value in a payload is an ownership claim over nothing — and the
+server does not persist it. Persistence normalizes empties away, and
+inside an atomic struct the normalized persisted value and a serialized
+empty diverge; under field ownership that divergence is a conflict, not
+a merge. So payloads declare in persistence normal form: nil and empty
+collections are pruned at the delivery boundary, and ceding a field and
+saying nothing are structurally the same act.
+
+Because the merge is not fully monoidal, the pruning carries an explicit
+exception list: for some fields an empty value is a genuine assertion —
+a field held empty against other writers — and those are declared by
+path.
+
+Properties:
+
+- The create's echo equals the declaration. What the server persists
+  from the seeded create is value-equal to what the ongoing apply sends,
+  so the equal-values co-ownership the seeding protocol depends on holds
+  — including inside atomic structs, where any divergence is loud.
+- Generation stays unconditional. A definition may render its empty
+  collections unconditionally, the natural shape for a generator; the
+  delivery boundary, not the generator, knows persistence normal form.
+- Emptiness never claims a field. A rendered-but-empty collection cannot
+  quietly make the repo co-owner of something it does not manage.
+- An empty value that reaches the cluster is deliberate. It survives
+  only by appearing in the exception list, so it is named, reviewable,
+  and distinguishable from an accident of rendering.
+
+## Constraint: creation is a protocol, not a verb
+
+A seeded field — the boot image, an initial replica count — must exist
+from the seeded create and end owned by no one, because the ongoing
+declaration never carries it. No single apply can promise both. Creation
+therefore runs as three acts: create the seeded payload under the seed
+owner (a manager named for the ongoing one, with a seed suffix), deliver
+the declared payload with an ordinary server-side apply, then cede —
+remove the seed owner's managedFields entry with an atomic
+test-and-remove. The order is not stylistic: an apply against an object
+with empty managedFields attributes every pre-existing field to a
+synthetic manager that never applies again and so never relinquishes.
+
+Properties:
+
+- Seeds end unowned. The first writer to touch one — a controller
+  scaling, a deliverer rolling the image — takes it without conflict,
+  which is the entire point of seeding.
+- The ongoing manager ends sole owner of exactly the declared fields,
+  and every later delivery is an ordinary apply. The protocol is paid
+  once, at seeding.
+- An interrupted protocol stays attributable. The seed owner's name is
+  derived from the field manager, so a converge that dies mid-protocol
+  strands an object whose managedFields still read as this repo's —
+  failure does not orphan the claim.
+- Re-creation is loud. Creating over an existing object fails rather
+  than silently re-seeding fields that other writers may have moved.
+
+## Constraint: a conflict stops delivery, and forcing is a human judgment
+
+Delivery never forces through a conflict. A conflict marks the frontier
+where another manager owns a field this declaration sends; crossing it
+transfers ownership and overwrites another party's promise. That is an
+incident-time judgment, made by a person with the context in front of
+them — never a delivery default. The escape hatch is raw kubectl, not a
+flag.
+
+Properties:
+
+- Delivery cannot silently take fields. The ownership frontier moves
+  only by an explicit human act, so every transfer has an author.
+- The preview shares the frontier. Diff for a server-side resource
+  dry-runs under the same field manager delivery uses, so the conflict
+  diff surfaces is the conflict apply will hit — not a different one
+  under a different name.
+- Resolution leaves a record. Either the definition stops declaring the
+  field — a reviewed cede — or an operator takes it deliberately, once,
+  outside matsuri. Both are visible acts; neither is a quiet override.
+
+## Constraint: delivery mode and payload content are orthogonal axes
+
+How a payload travels is the resource's delivery policy; what the
+payload says is its presenter pipeline, assembled by intent regime —
+bringing into existence, or delivering declared state. Server-side apply
+is a value of the first axis only. Moving a resource between client-side
+and server-side delivery never changes which presenters run.
+
+Properties:
+
+- Migration is a policy change, not a re-derivation. A resource moves
+  between delivery modes as a one-line change, with its pipeline — and
+  the review that ratified it — intact.
+- One stack can carry both modes. Members migrate individually, so
+  adopting server-side delivery is incremental, not a flag day.
+- The regimes stay about intent. Creation seeds and normal form attach
+  to what the payload means, so they hold identically under either
+  transport.

data/docs/design/stacks.md

@@ -0,0 +1,153 @@
+# Stacks Design
+
+This describes the constraints and properties of the stack design. This
+is intended to provide both a grammar on how stacks can be used, but
+also extended.
+
+## Framing
+
+A stack is the span of a single management promise: a bundle of
+Kubernetes resources that one operator converges as one act. The noun
+answers "what do we manage together?" — it deliberately does not answer
+"what talks to what?" or "what constitutes the whole system?". Each
+constraint below keeps that promise narrow; the properties follow from
+the narrowness.
+
+## Constraint: membership is decided by co-management only
+
+A resource belongs to a stack because its operator wants to converge it
+together with the others — one owner, one lifecycle, one converge act.
+Runtime topology, architectural wholeness, and system boundaries are not
+membership criteria.
+
+Properties:
+
+- The management partition is orthogonal to the runtime connector graph.
+  Two workloads may communicate heavily and live in different stacks;
+  two may never speak and share one. Runtime coupling does not force
+  co-membership, and co-membership promises nothing about reachability.
+- One noun serves every scale. A stack may be an entire platform or a
+  single service with its sidecars; because the noun claims only
+  co-management, it does not lie at either extreme, and there is no
+  ladder of bigger nouns to invent.
+- Membership is revisable. Moving a workload between stacks reassigns a
+  management promise, nothing more. The cost is confined to the cut: an
+  in-stack neighbor is reached by local name, an out-of-stack neighbor
+  by an address carried in configuration. The change is small, explicit,
+  and visible in the definitions.
+- Wholeness is not required, but filled references are. A stack need not
+  contain everything it depends on; every dependency it does not contain
+  must resolve to an address.
+
+## Constraint: instance data arrives as an argument, not as ambient state
+
+A stack-config binds at the stack definition, as an argument to the
+converge act. It is never folded into the global configuration, which
+remains the environment's ambient state.
+
+Properties:
+
+- Many instances of one stack can exist in one environment. Ambient
+  state is process-global and would quietly promise a single instance;
+  an argument makes the instance count a non-event.
+- No collision surface. Stack-config keys never enter the framework's
+  configuration keyspace, so no key can shadow or be shadowed by
+  framework configuration, and no merge semantics are ever needed.
+- Provenance survives. The configuration that was passed and the
+  manifests that were rendered remain separately readable; nothing is
+  destroyed by merging.
+
+## Constraint: one stack-config per instance, taken whole
+
+The stack-config is a single value. The stack deconstructs it through
+its own definitions; members never receive private variants.
+
+Properties:
+
+- Members cannot disagree. Every resource in the instance derives from
+  the same binding, so consistency across the instance is structural
+  rather than disciplined.
+- Deconstruction is legible. Which fields a stack consumes is read
+  directly from its definitions, not from a merge trace.
+
+## Constraint: instance identity is the (stack, stack-config) pair
+
+A stack name alone names a definition. An instance is the definition
+bound to a stack-config, and every operation on an instance addresses
+the pair.
+
+Properties:
+
+- Instances of the same stack coexist without qualification schemes —
+  the identity that distinguishes them is already in the address.
+- No operation is ambiguous in an environment holding many instances;
+  status, converge, and delete all name the same pair.
+
+## Constraint: parse the grammar, never own the vocabulary
+
+Matsuri validates that a stack-config is well-formed. It makes no claim
+to know every key: definitions lift the fields they consume and are
+silent about the rest.
+
+Properties:
+
+- The stack-config can be shared. One document may serve several
+  consumers (deployment tooling, controllers, humans); a partial
+  consumer that rejected unknown keys would claim the whole vocabulary
+  and break the sharing.
+- The promise is honest. Which keys are consumed is decided by the
+  definitions that read them, which is not enumerable in advance;
+  failing loudly on "unknown" keys would promise an authority matsuri
+  cannot have. Strict vocabulary enforcement belongs to whatever system
+  owns the vocabulary, at its own boundary.
+- Vocabulary can grow without gem changes. The gem ships the mechanism —
+  the flag, the loading, the binding; what any key means is defined
+  entirely by the repository's own definitions.
+
+## Constraint: environment and stack-config vary on different axes
+
+An environment is a committed, closed set naming a tier — where things
+run and under what posture. A stack-config is an open set naming an
+instance — what this particular deployment of a stack is. Neither
+substitutes for the other.
+
+Properties:
+
+- Dynamic environments without environment proliferation. The
+  lifecycle-driven case (a short-lived instance per feature branch) is
+  carried by instance data; the tier set stays small, static, and
+  reviewable.
+- Tier concerns stay in code review; instance concerns stay in data.
+  Changing a cluster mapping is a change to committed definitions;
+  spinning up another instance is a new stack-config file.
+
+## Constraint: cross-stack connections are references with defaults; a pin is the only override
+
+Where a stack depends on something outside itself, the dependency is a
+reference. References resolve to a default — the standing instances of a
+shared tier such as staging — and a stack-config may pin any reference
+to a different address. Pinning is the only override form.
+
+Properties:
+
+- An instance is a sparse override. Instantiating a stack for a feature
+  costs the stack itself plus the pins that differ; everything not
+  mentioned follows the defaults. Cost scales with the diff, not with
+  the size of the platform.
+- Composition is by reference, never co-location. Two stacks owned by
+  different operators compose by one pointing at the other's address —
+  two configs, two lifecycles, one field between them.
+- Coordination is recorded, not minted. When two owners agree to wire
+  their instances together, the pin records the outcome of an agreement
+  made between people; the mechanism imposes no registry, broker, or
+  naming authority of its own.
+
+## Vocabulary note
+
+Names make implied promises, and the flag grammar is part of the name. A
+plural noun with a source suffix (`--values-from=`) promises a document
+folded into a keyspace — overlay and merge semantics. The singular
+`--stack-config=` promises an argument the render is for. Stack-config
+is defined only in matsuri's own terms, as stated above; resemblance to
+concepts in other tools is incidental and carries none of their
+contracts.

data/docs/diff.md

@@ -0,0 +1,85 @@
+# Diff
+
+Matsuri carries two diffs because there are two different questions to
+ask before a converge, and no single comparison answers both.
+
+**The server-side diff** (the default) answers: *what will the cluster
+actually do with this manifest?* The payload — the exact payload `apply`
+would send — is dry-run through the apiserver, where defaulting and
+admission controllers run, and kubectl prints live-vs-admitted. If an
+admission controller injects a sidecar, a default, or a label, it shows
+here.
+
+**The hash diff** (`--hash-diff`) answers: *how has the live object
+drifted from my declaration?* The comparison runs locally against the
+rendered manifest, and everything the cluster owns — `status`, the
+last-applied annotation, server-populated defaults, equivalent
+quantities like `1024Mi` vs `1Gi` — is filtered out, so what remains is
+your drift, not the cluster's bookkeeping.
+
+Use the default to preview a converge; use `--hash-diff` when the
+admitted view drowns your one-line change in injected fields.
+
+## Usage
+
+```console
+$ matsuri staging diff deployment web            # server-side: live vs admitted
+$ matsuri staging diff deployment web --hash-diff # client-side: drift vs declaration
+$ matsuri staging diff stack my-stack            # every member, same flags
+```
+
+Workload resource verbs accept an image tag positional, same as apply:
+
+```console
+$ matsuri staging diff deployment web v1.2.3
+```
+
+## Primary container focus
+
+`-p` / `--primary-container` narrows the comparison to the first
+container of the pod template — the usual question being "did anything
+but my image change?":
+
+```console
+$ matsuri staging diff deployment web v1.2.3 -p
+```
+
+The projection is a hash-diff affordance (kubectl has no equivalent), so
+`-p` implies `--hash-diff`.
+
+Every built-in workload with a pod template declares where its primary
+container lives via `let(:primary_container_path)`; a custom resource
+that wants `-p` declares the path into its own manifest shape:
+
+```ruby
+let(:primary_container_path) { ['spec', 'template', 'spec', 'containers', 0] }
+```
+
+## Exit codes
+
+The server-side diff inherits kubectl's convention:
+
+- `0` — no differences (and no output; silence means clean)
+- `1` — differences found (not an error)
+- above `1` — an actual failure
+
+## Tuning the hash diff filters
+
+The noise filters live on the resource (`Matsuri::Concerns::Diffable`),
+so a definition that knows about additional cluster-owned paths can
+override them:
+
+```ruby
+Matsuri.define :deployment, 'web' do
+  # a controller rewrites this annotation on every sync; never report it
+  def always_changed_path?(path)
+    super || path == 'metadata.annotations.example.com/sync-stamp'
+  end
+end
+```
+
+The filter surface: `readonly_path?` (paths the apiserver owns),
+`always_changed_path?` (values rewritten on every apply),
+`default_value_assigned_nothing?` (declaring a default the server
+already holds), and `unit_comparison_is_equal?` (quantity-aware
+equality). Each returning `true` suppresses that comparison.

data/docs/known-issues.md

@@ -0,0 +1,19 @@
+# Known Issues
+
+## CronJob templates inherit Pod's restartPolicy default
+
+Pod defaults `restart_policy` to `Always`, and nothing in the CronJob
+chain overrides it. Kubernetes rejects `Always` in Job pod templates
+(`OnFailure` or `Never` are the lawful values), so a cron job built
+through the pod template emits a template the API server refuses unless
+the pod definition declares its own policy:
+
+```ruby
+Matsuri.define :pod, 'report' do
+  let(:restart_policy) { 'OnFailure' }
+end
+```
+
+The fixture pod `report` models this. Whether CronJob should own a
+Job-lawful default for its template, rather than inheriting Pod's, is an
+open design question — deferred.