Architecture

Context

Engineers provide local files. DeploySutra reads them, computes evidence, writes reports and stops. A human, using an independent CI/GitOps system, decides and acts.

 before.yaml  after.yaml  plan.json
        \         |         /
         v        v        v
   +------------------------------+
   |       deploysutra CLI        |   no apply / deploy / destroy / rollback
   +--------------+---------------+
                  v
   +------------------------------+      +---------------------------+
   | core: parse -> diff -> rules |----->| reporting: JSON, MD, HTML |
   |  -> blast map -> gate -> seal|      +-------------+-------------+
   +------------------------------+                    v
        ^            ^                          human reviewer
     MCP (stdio)   loopback API              (decides outside the tool)

Modules

ModuleResponsibility
util.mjsSHA-256, canonical JSON, seal/verify, safeFile, text cleaning
yaml.mjsStrict YAML subset with exact line maps and multi-document streams
manifest.mjsIngestion, JSON line maps, semantic diff and redaction
rules.mjsRule registry, profiles, per-document checks
blast.mjsDependency edges from supplied manifests
assess.mjsSnapshot comparison, gate, rollback model, plan summary
corpus.mjs50 labelled rule cases
audit.mjsIndependent self-audit
reporting/index.mjsRenderers and saveReports
server/index.mjs, server/mcp.mjsLoopback API and MCP server
cli/index.mjs, cli/install.mjsCommand line and skill installer

Design decisions (short ADRs)

DecisionAlternativesWhyTrade-offReversibility
Zero dependencies, hand-written YAML subsetAdd a YAML libraryNo supply-chain surface; fails loudly on anything unsupportedNot full YAML; Helm output must be rendered firstA parser adapter can replace yaml.mjs behind the same function
Gate has two statesAdd READYStatic checks can never prove safetyUsers may want a green lightAdding a state is a breaking, visible change
Block on persistent findings tooBlock only new onesOld HIGH risk is still riskMore noisy for legacy manifestsUse development profile or fix the manifest
Desired-state only, no clusterLive diffNo credentials, reproducibleCannot see driftA future adapter would be separately gated
Unkeyed SHA-256 sealSignaturesWorks offline with no key managementNot authenticitySigned provenance planned with an explicit trust root
Audit kept out of the core indexExport from coreCore stays free of subprocess APIsOne extra import pathNone needed

Data model (report v2.0)

schemaVersion, productVersion, rulesVersion, scope, profile, source.before/after (path, sha256, bytes), resources, diffs (id, resource, path, change, before, after, redacted, source, line, lineConfidence), policyFindings (id, severity, status new/persistent, resource, field, source, line, requirement), blastMap, impactedByChange, blastRadius, rollback, gate, gateReasons, checks, limitations, integrity.

Deterministic output

The analysis path contains no clocks or randomness. Objects are canonicalised before hashing, so equal inputs give equal digests on every platform.

Extension points

New rules go in the registry with an ID, severity, remediation and a corpus case; skills reference rule IDs and commands and a test fails if either is invented. Future adapters (OPA, Helm, live read-only collectors) must be separate, opt-in and sandboxed.