From c0ae94b55e84e1e1b936b1d77b69eb7379c222df Mon Sep 17 00:00:00 2001 From: Rafael Richards Date: Tue, 16 Jun 2026 06:55:45 -0400 Subject: [PATCH] =?UTF-8?q?feat(kids):=20VSL=20KIDS=20base=20=E2=80=94=20V?= =?UTF-8?q?SLCFG=20+=20#8989.51=20PARAMETER=20DEFINITION=20+=20Required=20?= =?UTF-8?q?Build=20(T1.3)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Package the VSL layer as an installable KIDS build and prove the lifecycle on both engines (VSL/MSL M1, task T1.3). kids/vsl.build.json declares the VSL base: - routine VSLCFG (the T1.2 config adapter) - a `VPNG GREETING` #8989.51 PARAMETER DEFINITION at the SYS entity (free text) - a Required Build on MSL*0.1*1 (action DON'T INSTALL, LEAVE GLOBAL) The pin stays MSL v0.7.0 (no new tag). The normalized export is committed at dist/kids/VSL.kids as a drift-gated artifact; `make kids`/`make check-kids` re-gate it (deterministic build + golden diff; SKIP-green when v-pkg is absent), added to the `gates` aggregate. `v-pkg roundtrip` clean. install -> verify -> uninstall -> verify-clean GREEN on BOTH engines over the driver (v-pkg standalone): vehu (YDB) and foia-t12 (IRIS). Install reaches #9.7 status 3 with the routine + param present; uninstall backs out to clean (routine + param both absent, verify exit 3). Built on the v-pkg KRN PARAMETER-DEFINITION capability (v-pkg main 2a3f273). Required-build posture (a): the Required Build is emitted into #9.6/MBREQ but not enforced (the direct-populate install bypasses the interactive KIDS prereq check). VSLCFG.m / VSLCFGTST.m untouched. Co-Authored-By: Claude Opus 4.8 (1M context) --- Makefile | 37 ++++++++++- dist/kids/VSL.kids | 116 +++++++++++++++++++++++++++++++++++ docs/memory/MEMORY.md | 1 + docs/memory/t1.3-vsl-kids.md | 75 ++++++++++++++++++++++ kids/vsl.build.json | 19 ++++++ 5 files changed, 245 insertions(+), 3 deletions(-) create mode 100644 dist/kids/VSL.kids create mode 100644 docs/memory/t1.3-vsl-kids.md create mode 100644 kids/vsl.build.json diff --git a/Makefile b/Makefile index e518cd7..29b528a 100644 --- 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 new file mode 100644 index 0000000..5b0b3b4 --- /dev/null +++ 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 index 09b4fdf..cc9e8e2 100644 --- 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 new file mode 100644 index 0000000..18b15ce --- /dev/null +++ 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=''`. +- **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 new file mode 100644 index 0000000..5e76fc1 --- /dev/null +++ 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" } + ] +}