Release Notes: v0.1.0

Release Date: 2026-09-07

Highlights

Initial release of Systems Architecture Spec (SAS): a statically-typed-friendly, Go-first semantic model for describing software systems as typed graphs — nodes, relationships, boundaries, identities, and entitlements — with diagrams, launch readiness, and threat modeling as views over that one model rather than separately maintained artifacts. Dogfooded end to end on real PlexusOne portfolio systems: sas validate --profile security gates internet-facing launches, sas view replaces hand-drawn architecture diagrams, and sas bind / sas export threat-model are verified against the real external tools they integrate with (PIDL, Threat Model Spec) rather than internal assumptions about their shape.

What's New

Core semantic graph

sas.Architecture is the canonical document: Node, Relationship, Boundary, Identity, Entitlement, View, ProtocolBinding, Assurance, and namespaced typed Extensions. See SPEC.md for the full normative model.

import "github.com/plexusone/systemspec-architecture/sas"

arch := sas.Architecture{
    Version: "0.1",
    Nodes: []sas.Node{
        {ID: "web", Kind: sas.NodeKindService, Name: "Storefront"},
        {ID: "db", Kind: sas.NodeKindDataDatabase, Name: "Orders Database"},
    },
    Relationships: []sas.Relationship{
        {ID: "web-to-db", From: "web", To: "db", Kind: sas.RelationKindDataAccess},
    },
}

Go structs are the source of truth. JSON Schema is generated (invopop/jsonschema, lint-clean under schemakit --property-case camelCase) and stays within the static-type profile — no oneOf/anyOf/allOf. Zod and TypeScript types generate from that same schema and conform to the same fixture corpus as the Go model.

CLI

sas validate <architecture.json> [--profile development,deployment,security,threat-model,sre] [--format console|json]
sas view <architecture.json> [--view <id> | --group-by --include-kinds --include-relations --include-boundaries] --format mermaid|d2|dot
sas bind <architecture.json> --pidl <protocol.json> [--format console|json]
sas export threat-model <architecture.json>
sas assure <architecture.json> [--format console|json]

sas validate --profile security is the launch-readiness gate: every internet-facing relationship must declare transport encryption, identity, and data classification, and its target node must declare an owner — one command a launch checklist runs before a system ships to production.

Renderers and catalogs

render/mermaid, render/d2, and render/dot each render a View's selection, verified against the real d2 and dot CLIs compiling to SVG, not just internally-consistent Go string output. catalog supplies AWS/GCP/ Kubernetes display names and icon hints, plus HTTP/SQL/MCP operation mappings — vendor detail stays out of the core NodeKind vocabulary.

PIDL bindings and the Threat Model Spec bridge

ProtocolBinding instantiates a PIDL protocol's abstract entities as concrete SAS nodes; sas bind verifies a binding against a real PIDL protocol document. bridge/threatmodel exports an Architecture as the system-under-analysis (DiagramIR) for Threat Model Spec, verified against its real published JSON Schema — SAS never re-describes threat reasoning, which stays in Threat Model Spec.

Assurance coverage

sas assure reports, per node and relationship, whether each of the four Assurance evidence categories (tests, metrics, detections, deployment) has at least one reference — a concrete gap list, not just a summary percentage.

Non-Goals (v1)

Runtime reconciliation, semantic diff / change-impact analysis, and CALM (FINOS) interop are explicitly deferred — see SPEC.md §12 for the full list and rationale. Semantic diff is the leading v0.2 candidate.

Getting Started

go get github.com/plexusone/systemspec-architecture@v0.1.0
go run ./cmd/sas validate examples/dogfood/acme-widgets.json --profile security
go run ./cmd/sas view examples/dogfood/acme-widgets.json --view context --format d2

Requirements

• Go 1.26+
• d2 and Graphviz dot on PATH for D2/DOT renderer output (optional — the renderers themselves have no external dependency; only compiling their output to an image does)

Full Changelog

See CHANGELOG.md for the complete list of changes.