vista-cloud-dev · rafael5 · Jun 17, 2026 · Jun 16, 2026
diff --git a/Makefile b/Makefile
@@ -8,6 +8,10 @@ SRC     := src
 TESTS   := tests
 # STDASSERT/STDHARN live in m-stdlib and are staged for engine-bound tests.
 MSTDLIB ?= $(HOME)/vista-cloud-dev/m-stdlib
+# v-pkg — the host tool that builds the VSL KIDS base from kids/vsl.build.json
+# (VSL T1.3). Defaults to the sibling checkout's standalone binary; override
+# with `make kids VPKG=/path/to/v-pkg`.
+VPKG ?= $(HOME)/vista-cloud-dev/v-pkg/dist/v-pkg
 
 # Engine selection for the engine-bound targets (test/coverage):
 #   make test ENGINE=ydb  DOCKER=m-test-engine
@@ -18,7 +22,7 @@ ENGINE_FLAGS := $(if $(ENGINE),--engine $(ENGINE)) $(if $(DOCKER),--docker $(DOC
 
 .PHONY: all check fmt fmt-check lint arch test coverage clean \
         seams check-seams icr check-icr check-citations namespaces check-namespaces \
-        pin check-msl-pin check-engine-access gates
+        pin check-msl-pin check-engine-access kids check-kids gates
 
 all: check
 
@@ -97,9 +101,36 @@ check-msl-pin:
 check-engine-access:
 	@python3 tools/check_engine_access.py --check
 
+# ── VSL T1.3: the VSL KIDS base build (drift-gated artifact) ──────────
+# kids/vsl.build.json declares the VSL layer as an installable KIDS build:
+# the VSLCFG routine + the VPNG GREETING #8989.51 PARAMETER DEFINITION (SYS)
+# + a Required Build on the MSL base (MSL*0.1*1). `make kids` builds the
+# deterministic, normalized .KID via v-pkg; `make check-kids` re-gates it —
+# a fresh rebuild must be byte-identical (deterministic-build invariant) AND
+# match the committed dist/kids/VSL.kids (drift gate), same discipline as
+# m-stdlib's check-kids. Engine-free — needs only the v-pkg binary. SKIP-green
+# when v-pkg is absent (mirrors check-citations) so CI without it stays green.
+kids:
+	$(VPKG) build kids/vsl.build.json --src $(SRC) --out dist/kids/VSL.kids
+
+check-kids:
+	@if [ ! -x "$(VPKG)" ]; then \
+	  echo "check-kids: v-pkg not found at $(VPKG) — SKIP (build it in v-pkg or set VPKG=…)"; \
+	  exit 0; \
+	fi
+	@tmp=$$(mktemp); \
+	$(VPKG) build kids/vsl.build.json --src $(SRC) --out $$tmp >/dev/null; \
+	if diff -q $$tmp dist/kids/VSL.kids >/dev/null 2>&1; then \
+	  echo "check-kids: dist/kids/VSL.kids matches a fresh deterministic build ✓"; \
+	  rm -f $$tmp; \
+	else \
+	  echo "ERROR: dist/kids/VSL.kids drifted from kids/vsl.build.json + src/ — run 'make kids' and commit" >&2; \
+	  rm -f $$tmp; exit 1; \
+	fi
+
 # Aggregate of the engine-free drift gates (the four own-tier gates + the
-# upward MSL pin + the transport-monopoly gate).
-gates: check-seams check-icr check-citations check-namespaces check-msl-pin check-engine-access
+# upward MSL pin + the transport-monopoly gate + the KIDS-build drift gate).
+gates: check-seams check-icr check-citations check-namespaces check-msl-pin check-engine-access check-kids
 
 # Engine-free gates (fmt/lint/arch + drift gates) + the engine-bound suite. CI
 # runs the full set; `make check-fast` needs no engine.

diff --git a/dist/kids/VSL.kids b/dist/kids/VSL.kids
@@ -0,0 +1,116 @@
+KIDS Distribution saved by v-pkg
+m-kids reassembled output
+**KIDS**:VSL*1.0*1^
+
+**INSTALL NAME**
+VSL*1.0*1
+"BLD",1,0)
+VSL*1.0*1^VSL^0^0
+"BLD",1,"KRN",0)
+^9.67PA^8989.51^1
+"BLD",1,"KRN",8989.51,0)
+8989.51
+"BLD",1,"KRN",8989.51,"NM",0)
+^9.68A^1^1
+"BLD",1,"KRN",8989.51,"NM",1,0)
+VPNG GREETING^^0
+"BLD",1,"KRN",8989.51,"NM","B","VPNG GREETING",1)
+
+"BLD",1,"KRN","B",8989.51,8989.51)
+
+"BLD",1,"REQB",0)
+^9.611^1^1
+"BLD",1,"REQB",1,0)
+MSL*0.1*1^2
+"BLD",1,"REQB","B","MSL*0.1*1",1)
+
+"RTN")
+1
+"RTN","VSLCFG")
+0^32^0^0
+"RTN","VSLCFG",1,0)
+VSLCFG	; v-stdlib — VistA configuration adapter over XPAR (Parameter Tools).
+"RTN","VSLCFG",2,0)
+	;
+"RTN","VSLCFG",3,0)
+	; Binds the MSL config-read seam ($$get^STDENV) to VistA's XPAR parameter
+"RTN","VSLCFG",4,0)
+	; store at the SYS (system) entity — the faithful analog of STDENV's flat
+"RTN","VSLCFG",5,0)
+	; key->value config read. The adapter contains ONLY the VistA binding; no
+"RTN","VSLCFG",6,0)
+	; parsing or formatting (that stays in STD*, called up; m/v waterline).
+"RTN","VSLCFG",7,0)
+	;
+"RTN","VSLCFG",8,0)
+	; Public extrinsics:
+"RTN","VSLCFG",9,0)
+	;   $$get^VSLCFG(key,default)   — read a SYS-level parameter value, else default
+"RTN","VSLCFG",10,0)
+	;   $$set^VSLCFG(key,value)     — set a parameter value at the SYS entity
+"RTN","VSLCFG",11,0)
+	;
+"RTN","VSLCFG",12,0)
+	; XPAR is a Supported API (Kernel Toolkit, ICR #2263).
+"RTN","VSLCFG",13,0)
+	;
+"RTN","VSLCFG",14,0)
+	quit
+"RTN","VSLCFG",15,0)
+	;
+"RTN","VSLCFG",16,0)
+get(key,default)	; Read parameter `key` at the SYS entity; return `default` when unset.
+"RTN","VSLCFG",17,0)
+	; doc: @param key      string  XPAR parameter name (PARAMETER DEFINITION #8989.51)
+"RTN","VSLCFG",18,0)
+	; doc: @param default  string  value returned when the parameter is unset
+"RTN","VSLCFG",19,0)
+	; doc: @returns        string  the SYS-level value, or `default` when unset
+"RTN","VSLCFG",20,0)
+	; doc: @example        set greeting=$$get^VSLCFG("VPNG GREETING","hello")
+"RTN","VSLCFG",21,0)
+	; doc: @icr 2263 @call $$GET^XPAR @status Supported @custodian XU @source XU/krn_8_0_dg_toolkit_ug#getxpar-return-an-instance-of-a-parameter
+"RTN","VSLCFG",22,0)
+	new v
+"RTN","VSLCFG",23,0)
+	set v=$$GET^XPAR("SYS",key,1)
+"RTN","VSLCFG",24,0)
+	quit $select(v="":default,1:v)
+"RTN","VSLCFG",25,0)
+	;
+"RTN","VSLCFG",26,0)
+set(key,value)	; Set parameter `key` to `value` at the SYS entity.
+"RTN","VSLCFG",27,0)
+	; doc: @param key    string  XPAR parameter name (#8989.51)
+"RTN","VSLCFG",28,0)
+	; doc: @param value  string  value to store at the SYS level
+"RTN","VSLCFG",29,0)
+	; doc: @returns      void    side-effecting; no return value
+"RTN","VSLCFG",30,0)
+	; doc: @icr 2263 @call EN^XPAR @status Supported @custodian XU @source XU/krn_8_0_dg_toolkit_ug#enxpar-add-change-delete-parameters
+"RTN","VSLCFG",31,0)
+	do EN^XPAR("SYS",key,1,value)
+"RTN","VSLCFG",32,0)
+	quit
+"ORD",1,8989.51)
+8989.51;1;1;;;;;;;
+"ORD",1,8989.51,0)
+PARAMETER DEFINITION
+"KRN",8989.51,1,-1)
+0
+"KRN",8989.51,1,0)
+VPNG GREETING^VPNG greeting (read by VPNG via $$get^VSLCFG at SYS)^
+"KRN",8989.51,1,1)
+F^^
+"KRN",8989.51,1,30,0)
+^8989.513I^1^1
+"KRN",8989.51,1,30,1,0)
+1^4.2
+"KRN",8989.51,1,30,"B",1,1)
+
+"MBREQ")
+1
+"VER")
+8.0^22.2
+**END**
+**END**
diff --git a/docs/memory/MEMORY.md b/docs/memory/MEMORY.md
@@ -4,6 +4,7 @@ One line per memory file. Content lives in the files, not here.
 
 - [m4-vslsec-vsllog](m4-vslsec-vsllog.md) — VSL/MSL **M4 DONE** (2026-06-16): **VSLSEC** (security/authz seam S5) + **VSLLOG** (audit sink S3). **Dual-engine GREEN 11/11** (vehu YDB + foia-t12 IRIS); suite 33/33 no regression. **VSLSEC = authz-only** — GROUNDED that there is **no portable Kernel generic-hash** (`$$SHAHASH^XUSHSH` absent on vehu; classic `^XUSHSH` returns a constant on both) so crypto stays in **STDCRYPTO**; binds `$$hasKey` over **`^XUSEC`** (Supported reference, notional ICR; a DENY is a normal `0`), `$$duz` (#200 IEN), `$$user` (#200 NAME via **VSLFS reuse**); loud **`,U-VSL-SEC-ARG,`** on a malformed call. **VSLLOG = first v→v composition** — reuses VSLFS (no DBS re-bind), audit line via `$$now^STDDATE` (v→m), maps VSLFS DIERR → **`,U-VSL-LOG-WRITE,`**; no `@icr` (no direct L4 call). **Lane A NO-OP** (no MSL seam change; pin stays **v0.9.0**). GOTCHA: `zgoto`-`$ETRAP` aborts the resident harness 0/0 → use the flag-based `$ETRAP` (clear OUR trap before re-raising). Gates: check-icr 9 / check-citations 9 / check-namespaces 5. MailMan alert + `$$inContext` (CRCONTXT) deferred. Branch `m4-vslsec-vsllog`. Next: M5 (VSLBLD/VSLTASK).
 - [m3-vslfs](m3-vslfs.md) — VSL/MSL **M3 Lane B DONE** (2026-06-16): **VSLFS** binds the `STDKV` storage seam (MSL **v0.9.0**) to VistA's FileMan DBS — `$$set`=`UPDATE^DIE` (returns resolved IENS; `"+1,"` adds), `$$get`/`$$exists`=`$$GET1^DIQ`, `$$kill`=`FILE^DIE` with FDA **`.01="@"`** (**no `DELETE^DIE` exists**; `^DIK`/direct KILL forbidden). Re-pinned `msl_ref` v0.8.0→v0.9.0. **Dual-engine GREEN 7/7** (vehu + foia-t12) over **#8989.51** (free-text `.01`, no other required fields → safe ZZ throwaway record; no DD install). DIERR→**`,U-VSL-FS-DIERR,`** `$ECODE` + `$$lastError`; MSG_ROOT="ERR" keeps errors private. **No `$ZVERSION` arm** (FileMan DBS portable). ICR **notional** (`@icr DBS` marker — gen-icr.py taught NOTIONAL_MARKERS; see [[notional-dbia-not-a-blocker]]). 3 boundaries green; suite **22/22** no regression. Branch `m3-vslfs` **stacked on `m2-vslio`** (unmerged). Next: M4 (VSLSEC+VSLLOG).
+- [t1.3-vsl-kids](t1.3-vsl-kids.md) — VSL T1.3 (2026-06-16): **the VSL layer packaged as a KIDS build**. `kids/vsl.build.json` = VSLCFG routine + **`VPNG GREETING` #8989.51 PARAMETER DEFINITION** (SYS, free text) + **Required Build on `MSL*0.1*1`** (action LEAVE GLOBAL; pin stays MSL v0.7.0). **install→verify→uninstall→verify-clean GREEN on BOTH engines** over the driver (`v-pkg`; vehu YDB + foia-t12 IRIS). Normalized export committed at **`dist/kids/VSL.kids`** + **`make check-kids`** deterministic/golden drift gate (in `gates`; SKIP-green w/o v-pkg). Param named for the **consumer** (VPNG), matching VSLCFG.m's doc default `"hello"`. **Required-build posture (a)**: emitted into #9.6/MBREQ (faithful) but NOT enforced (direct-populate install bypasses the interactive KIDS prereq check). Sits on the v-pkg KRN capability (v-pkg main `2a3f273`). Next: T1.4 VPNG consumer.
 - [t1.2-vslcfg](t1.2-vslcfg.md) — VSL T1.2 (2026-06-16): **VSLCFG**, the first VSL* module — binds the STDENV config seam to XPAR at the **SYS entity** (`$$get`=`$$GET^XPAR("SYS",…)`, `$$set`=`EN^XPAR("SYS",…)`), validated live on vehu. **All 3 determinism boundaries GREEN** (① re-pin `msl_ref`→v0.7.0 carrying real STDENV; ② check-icr ICR #2263; ③ check-citations vs gold corpus). Citation reconciled: **XU/krn_8_0_dg_toolkit_ug / ICR #2263**, not the plan's XT guess. **Keystone unblock:** driver→live XPAR via `M_YDB_GBLDIR`/`M_YDB_ROUTINES`. **Remaining blocker:** `m test --docker` honors gbldir but NOT M_YDB_ROUTINES → VSLCFGTST aborts 0/0 (XPAR routines unresolved); fix = layer the resident routine base in the m test/m-ydb path (m-cli/m-ydb session) or test-in-place `--resident`.
 - [meta-root + owed VSLSEED filer](meta-root-and-owed.md) — layer declared in **root `repo.meta.json`** (migrated off `dist/` 2026-06-15, Phase B item 1); the owed `fileViaDie^VSLSEED` FileMan filer (re-homed from m-stdlib STDSEED per the G2 waterline decision) lands here when a v-layer seeding consumer needs it.
 - [t0b4-msl-seam-pin](t0b4-msl-seam-pin.md) — VSL T0b.4 (v-stdlib leg, 2026-06-15): the **cross-repo MSL seam-contract pin** — `dist/msl-seam-pin.json` (pins MSL `v0.6.0` + frozen `seams` copy) + `tools/msl_seam_pin.py` drift gate (`make check-msl-pin`). Reads the sibling MSL @ tag via `git show`; **SKIP-green when unreachable** (so it SKIPs in CI today, asserts at dev-time); fetch-at-tag path deferred to T1.1. Don't conflate with v-stdlib's own (VSL*) `dist/seam-snapshot.json`.

diff --git a/docs/memory/t1.3-vsl-kids.md b/docs/memory/t1.3-vsl-kids.md
@@ -0,0 +1,75 @@
+---
+name: t1.3-vsl-kids
+description: VSL T1.3 DONE — the VSL layer packaged as a KIDS build (kids/vsl.build.json = VSLCFG routine + VPNG GREETING #8989.51 PARAMETER DEFINITION at SYS + Required Build on MSL*0.1*1); install→verify→uninstall→verify-clean GREEN on both engines over the driver; deterministic+golden drift gate wired.
+metadata:
+  type: project
+---
+
+# VSL T1.3 — VSL KIDS base (v-stdlib, 2026-06-16)
+
+Packages the VSL layer as an installable KIDS build and proves the
+install/uninstall lifecycle on both engines. Branch `t1.3-vsl-kids`. Third M1
+task (after T1.1 MSL `seams.STDENV`@v0.7.0 and T1.2 VSLCFG). Sits on top of the
+**v-pkg KRN capability** (merged to v-pkg `main` `2a3f273`, 2026-06-16) — see
+v-pkg `docs/memory/krn-param-def-component.md` for the build/run cheat-sheet.
+
+## The build spec — `kids/vsl.build.json`
+```json
+{ "package": "VSL", "version": "1.0", "patch": "1",
+  "components": {
+    "routines": ["VSLCFG"],
+    "parameterDefinitions": [
+      { "name": "VPNG GREETING", "displayText": "VPNG greeting (read by VPNG via $$get^VSLCFG at SYS)",
+        "dataType": "free text", "entities": [ { "entity": "SYS", "precedence": 1 } ] } ] },
+  "requiredBuilds": [ { "name": "MSL*0.1*1", "action": "DON'T INSTALL, LEAVE GLOBAL" } ] }
+```
+→ `v-pkg build` reports `routines:1 paramDefs:1 requiredBuilds:1`, installName `VSL*1.0*1`.
+
+- **Param NAME = `VPNG GREETING`** (NOT the kickoff's illustrative "VSL GREETING").
+  Decision: match the **consumer** — VSLCFG.m's committed doc example (T1.2) already
+  uses `$$get^VSLCFG("VPNG GREETING","hello")`, and the default `"hello"` lines up with
+  T1.4's golden `{"greeting":"hello"}` (unseeded read returns the default). The VSL base
+  *ships* the definition; the VPNG consumer (T1.4) seeds/reads the value. T1.3 installs
+  the **empty DEFINITION only** — no value.
+- **Required Build name = `MSL*0.1*1`** — read from m-stdlib `kids/std.build.json`
+  (package MSL, version 0.1, patch 1). Pin stays MSL **v0.7.0** (no new tag cut).
+- **Required-build action codes** (v-pkg `internal/buildspec`): `"DON'T INSTALL, LEAVE
+  GLOBAL"`→2, `"…REMOVE GLOBAL"`→1, `"WARN…"`/unset→0.
+
+## Required-build posture chosen = (a), enforcement deferred
+v-pkg's **direct-populate install bypasses the interactive KIDS LOAD** where the
+required-build prerequisite check normally fires. So the Required Build is faithfully
+**EMITTED** into the #9.6 manifest (`"BLD",1,"REQB",1,0)="MSL*0.1*1^2"` + `"MBREQ")`) —
+a drift-gated artifact — but is **NOT ENFORCED** at install in this path (the VSL base
+installs even if the MSL base is absent). This satisfies the §12.1 ledger row ("Required
+Build DECLARED"). The faithful "install-once base ordering" posture (b) — build the MSL
+base KID and install it first — is deferred (relevant to T1.4/T1.5's test-in-place).
+
+## Lifecycle — GREEN on BOTH engines over the driver (`v-pkg`, NOT `m test`)
+install→verify→uninstall→verify-clean, all exit-0 path; verify-clean reports
+`installed:false` + exit 3 (the clean signal). Recipes (env exactly as T1.2 used):
+- **YDB (vehu):** `--engine ydb --transport docker` + `M_YDB_CONTAINER=vehu
+  M_YDB_GBLDIR=/home/vehu/g/vehu.gld M_YDB_ROUTINES='<vehu gtmroutines>'`.
+- **IRIS (foia-t12):** `--engine iris --transport docker` + `M_IRIS_TRANSPORT=docker
+  M_IRIS_CONTAINER=foia-t12 M_IRIS_NAMESPACE=VISTA M_IRIS_IRIS_INSTANCE=IRIS`.
+Verify = #9.7 status 3 + `routines.VSLCFG:true` + `params."VPNG GREETING":true`.
+Clean = all three false. (Engine work via the driver stack ONLY — see shared
+[[engine-access-through-driver-stack]].)
+
+## Drift gate (registry discipline)
+The normalized export is committed at **`dist/kids/VSL.kids`** (mirrors m-stdlib's
+`dist/kids/MSL.kids`). `make kids` rebuilds it; **`make check-kids`** re-gates:
+deterministic (build twice → byte-identical) + golden (diff vs committed) +
+SKIP-green when the v-pkg binary is absent (so CI without it stays green). Added to
+the `gates` aggregate (so `make check-fast` covers it). `v-pkg roundtrip` clean (54
+pairs). Build the binary from v-pkg main: `cd v-pkg && go build -o dist/v-pkg .`
+(use the **standalone** v-pkg, not the `v` umbrella, which may pin an older v-pkg).
+
+## Gates
+`make check-fast` (fmt/lint/arch + all 7 drift gates incl. check-kids) GREEN; T1.2's
+three determinism boundaries unregressed; `m arch check .` layer `v` clean. VSLCFG.m /
+VSLCFGTST.m untouched.
+
+**Next: T1.4** (VPNG consumer — `$$ping^VPNG()`==`{"greeting":"hello"}`, KIDS Requires
+the VSL base) then **T1.5** (M1 exit gate: full determinism ledger, byte-identical both
+engines). Full plan: `docs/vsl-msl/vsl-implementation-plan.md` (T1.3 row) + §12.1.
diff --git a/kids/vsl.build.json b/kids/vsl.build.json
@@ -0,0 +1,19 @@
+{
+  "package": "VSL",
+  "version": "1.0",
+  "patch": "1",
+  "components": {
+    "routines": ["VSLCFG"],
+    "parameterDefinitions": [
+      {
+        "name": "VPNG GREETING",
+        "displayText": "VPNG greeting (read by VPNG via $$get^VSLCFG at SYS)",
+        "dataType": "free text",
+        "entities": [ { "entity": "SYS", "precedence": 1 } ]
+      }
+    ]
+  },
+  "requiredBuilds": [
+    { "name": "MSL*0.1*1", "action": "DON'T INSTALL, LEAVE GLOBAL" }
+  ]
+}