arch

Documentation

Overview

Package arch implements the m/v waterline gates — the machine-checkable boundary between the engine-neutral `m` layer and the VistA-specific `v` layer (see docs/background/m-v-waterline-adr.md in the org `docs` repo).

It ships four gates:

• G1 — dependency-direction — the core invariant: dependency flows one way, v → m, never the reverse. An `m`-layer repo's Go dependency closure must contain no `vista-cloud-dev/v-*` module, and its M source must reference no `VSL*` (v-layer) routine.
• G2 — forbidden-symbol (no VistA below the waterline): an `m`-layer `.m` file's code must not reference a VistA-only symbol (FileMan/Kernel/KIDS: ^DIC/^DIE/^DIK/^DIQ, ^DD(, ^DPT(, ^VA(, ^XUS*, ^XPD*). Comment-aware — a symbol named only in a ';' comment (e.g. an STDMOCK doc example) is not a reference.
• G3 — transport-monopoly: only m-driver-sdk may run a driver binary / build the engine envelope. Any other repo's Go code naming a driver binary ("m-ydb"/"m-iris") other than its own is hand-rolling transport — reach the engine through mdriver.Client instead.
• G4 — seam-pin: a repo requiring m-driver-sdk must pin a tagged release in go.mod — no `replace` to it, no pseudo-version (untagged commit).

It also validates the repo's standardized meta artifact (Phase B item 1): root repo.meta.json (preferred, then dist/repo.meta.json) must carry id, layer, language, and verification_commands; layer must be "m" or "v".

G1 and G2 apply to the m layer; G3, G4, and meta-validation are layer-agnostic (a v consumer also must not hand-roll transport and must seam-pin). A repo declares its layer in a committed meta artifact ("layer": "m"|"v"); a `v`-layer repo passes G1/G2 trivially.

Index

• type Layer
  • func ResolveLayer(root, override string) (Layer, error)
• type Meta
  • func LoadMeta(root string) (meta Meta, path string, found bool, err error)
• type MetaProblem
  • func ValidateMeta(meta Meta) []MetaProblem
• type Report
  • func Check(root, override string) (Report, error)
• type Violation
  • func CheckDriverMonopoly(root, selfName string) ([]Violation, error)
  • func CheckMRefs(root string) ([]Violation, error)
  • func CheckSeamPin(root string) ([]Violation, error)
  • func CheckVistaSymbols(root string) ([]Violation, error)

Types

type Layer

type Layer string

Layer is a repo's side of the waterline.

const (
	// LayerM is the engine-neutral layer (runs on a bare M engine, no VistA).
	LayerM Layer = "m"
	// LayerV is the VistA-specific layer (needs Kernel/FileMan/KIDS).
	LayerV Layer = "v"
)

func ResolveLayer

func ResolveLayer(root, override string) (Layer, error)

ResolveLayer determines the repo's declared layer. An explicit override ("m"/"v") wins; otherwise the top-level "layer" field of a known committed meta artifact is read (dist/repo.meta.json, then dist/v-contract.json).

type Meta

type Meta struct {
	ID                   string   `json:"id"`
	Layer                string   `json:"layer"`
	Language             []string `json:"language"`
	VerificationCommands []string `json:"verification_commands"`
}

Meta is the standardized repo meta artifact (the schema item 1 validates). Required: id, layer, language, verification_commands. Optional fields (consumes, exposes — repo-defined object shapes) and descriptive fields (repo, role, license, …) are allowed and ignored here.

func LoadMeta

func LoadMeta(root string) (meta Meta, path string, found bool, err error)

LoadMeta reads the repo's standardized meta artifact — root repo.meta.json preferred, then dist/repo.meta.json. found is false when neither exists (a repo that declares its layer only via dist/v-contract.json, or via --layer). A malformed JSON meta returns an error.

type MetaProblem

type MetaProblem struct {
	Field  string `json:"field"`
	Detail string `json:"detail"`
}

MetaProblem is one meta-shape finding (a missing or malformed field).

func ValidateMeta

func ValidateMeta(meta Meta) []MetaProblem

ValidateMeta checks the meta against the standardized schema (Phase B item 1): id, layer, language, and verification_commands are required; layer must be "m" or "v"; consumes and exposes are optional. Returns one MetaProblem per violation (empty when clean).

type Report

type Report struct {
	Layer       Layer       `json:"layer"`
	CheckedGo   bool        `json:"checkedGo"`   // G1 Go dependency closure
	CheckedM    bool        `json:"checkedM"`    // G1 m-ref + G2 forbidden-symbol
	CheckedG3   bool        `json:"checkedG3"`   // G3 transport-monopoly (driver refs)
	CheckedG4   bool        `json:"checkedG4"`   // G4 seam-pin (go.mod)
	CheckedMeta bool        `json:"checkedMeta"` // meta-artifact shape
	Violations  []Violation `json:"violations"`
}

Report is the full waterline-gate result for one repo.

func Check

func Check(root, override string) (Report, error)

Check resolves the repo layer and runs the applicable G1 checks. A v-layer repo passes trivially (v → m is allowed); an m-layer repo is checked on both the Go dependency closure (when a go.mod is present) and its M source.

type Violation

type Violation struct {
	Gate   string `json:"gate"`   // "G1" | "G2" | "G3" | "G4" | "META"
	Kind   string `json:"kind"`   // "go-dep" | "m-ref" | "vista-symbol" | "driver-ref" | "seam-replace" | "seam-untagged" | "meta-shape"
	Source string `json:"source"` // offending module path or file:line
	Detail string `json:"detail"` // human-readable explanation
}

Violation is one gate finding — a waterline breach (G1–G4) or a meta-shape problem (META).

func CheckDriverMonopoly

func CheckDriverMonopoly(root, selfName string) ([]Violation, error)

CheckDriverMonopoly scans the Go source under root for an exec of a driver binary other than the repo's own (selfName) — the G3 transport-monopoly violation (ADR §3.2: no `exec.Command(…, "m-ydb"/"m-iris", …)` outside the SDK). The driver literal must co-occur with an exec.Command/CommandContext call on the same code line, so the gate's own deny-list and string fixtures (which name the binaries but never exec them) do not trip it. Only m-driver-sdk may run a driver / build the envelope; every other consumer reaches the engine through mdriver.Client (engine name "ydb"/"iris", never the binary). Comment text is ignored (goCodePortion); generated/vendored trees are skipped. The SDK is exempt and is not scanned (the caller skips it).

func CheckMRefs

func CheckMRefs(root string) ([]Violation, error)

CheckMRefs scans the .m source under root for references to v-layer (VSL*) routines — the M-side m → v G1 violation.

func CheckSeamPin

func CheckSeamPin(root string) ([]Violation, error)

CheckSeamPin inspects root/go.mod for the seam-pin invariant (G4): a repo that requires m-driver-sdk must pin a *tagged* release — no `replace` directive to it and no pseudo-version (untagged commit) require. A repo with no go.mod, or one not depending on the SDK, passes trivially.

func CheckVistaSymbols

func CheckVistaSymbols(root string) ([]Violation, error)

CheckVistaSymbols scans the code portion of the .m source under root for VistA-only symbols (the G2 violation — no VistA below the waterline). Comment text is ignored via codePortion.