Land v-pkg: m-kids→v-pkg refile + KIDS lifecycle + waterline (Phase A)

.github/workflows/ci.yml

@@ -8,3 +8,5 @@ on:
 jobs:
   ci:
     uses: vista-cloud-dev/.github/.github/workflows/go-ci.yml@main
+  arch:
+    uses: vista-cloud-dev/.github/.github/workflows/arch-waterline.yml@main

.gitignore

@@ -1,5 +1,7 @@
-# Build output
-/dist/
+# Build output — ignore everything in dist/ EXCEPT the generated, committed
+# contract artifact (drift-gated *.json).
+/dist/*
+!/dist/*.json
 /bin/
 *.test
 # coverage report artifacts — specific/anchored so they never match a source

Makefile

@@ -1,9 +1,9 @@
-# m-kids — KIDS round-trip CLI. Build conventions inherited from
+# v-pkg — the `v pkg` KIDS domain. Build conventions inherited from
 # go-cli-template: static (CGO_ENABLED=0), -trimpath, version stamped via
-# -ldflags, cross-compile matrix, lint, test, schema.
+# -ldflags, cross-compile matrix, lint, test, schema, contract.
 
-BIN     ?= m-kids                     # KIDS round-trip CLI
-PKG     := github.com/vista-cloud-dev/m-kids
+BIN     ?= v-pkg                     # the v pkg domain CLI (standalone)
+PKG     := github.com/vista-cloud-dev/v-pkg
 LDPKG   := $(PKG)/clikit
 VERSION ?= $(shell git describe --tags --always --dirty 2>/dev/null || echo dev)
 COMMIT  ?= $(shell git rev-parse --short HEAD 2>/dev/null || echo none)
@@ -16,7 +16,7 @@ export CGO_ENABLED := 0
 
 PLATFORMS := linux/amd64 linux/arm64 darwin/arm64 windows/amd64
 
-.PHONY: all build run lint test tidy schema dist clean
+.PHONY: all build run lint test tidy schema contract check-contract dist clean
 
 all: lint test build
 
@@ -39,6 +39,14 @@ tidy:
 schema: build
 	./dist/$(BIN) schema
 
+# Regenerate the v-cli domain contract (v-cli-platform.md §4) → dist/v-contract.json.
+contract:
+	UPDATE_GOLDEN=1 go test ./pkgcli/ -run Contract
+
+# Drift gate: fail if dist/v-contract.json is stale vs the live command tree.
+check-contract:
+	go test ./pkgcli/ -run Contract
+
 # Cross-compile the pinned matrix into dist/.
 dist:
 	@mkdir -p dist
@@ -50,4 +58,5 @@ dist:
 	done
 
 clean:
-	rm -rf dist
+	rm -f dist/$(BIN) dist/$(BIN)-* *.test
+	@# keep dist/*.json — committed, drift-gated contract artifacts

clikit/version.go

@@ -4,7 +4,7 @@ import "runtime"
 
 // Build metadata, injected at link time:
 //
-//	go build -ldflags "-X github.com/vista-cloud-dev/m-kids/clikit.Version=$VER \
+//	go build -ldflags "-X github.com/vista-cloud-dev/v-pkg/clikit.Version=$VER \
 //	                    -X …/clikit.Commit=$SHA -X …/clikit.Date=$DATE"
 var (
 	Version = "dev"

dist/v-contract.json

@@ -0,0 +1,275 @@
+{
+  "domain": "pkg",
+  "version": "0.1.0",
+  "contractVersion": "1.0",
+  "exits": [
+    {
+      "code": 0,
+      "meaning": "ok"
+    },
+    {
+      "code": 1,
+      "meaning": "runtime error"
+    },
+    {
+      "code": 2,
+      "meaning": "usage error"
+    },
+    {
+      "code": 3,
+      "meaning": "check / gate failed"
+    },
+    {
+      "code": 4,
+      "meaning": "refused / substrate unavailable"
+    }
+  ],
+  "commands": [
+    {
+      "path": [
+        "parse"
+      ],
+      "help": "Parse a .KID file and summarize its builds and sections.",
+      "args": [
+        {
+          "name": "kid-file",
+          "type": "string",
+          "required": true,
+          "help": "Path to the .KID file."
+        }
+      ]
+    },
+    {
+      "path": [
+        "decompose"
+      ],
+      "help": "Split a .KID into a per-component KIDComponents/ tree.",
+      "args": [
+        {
+          "name": "kid-file",
+          "type": "string",
+          "required": true,
+          "help": "Path to the .KID file."
+        },
+        {
+          "name": "output-dir",
+          "type": "string",
+          "required": true,
+          "help": "Output directory for the component tree (replaced if it exists)."
+        }
+      ]
+    },
+    {
+      "path": [
+        "assemble"
+      ],
+      "help": "Reassemble a component tree back into a .KID.",
+      "args": [
+        {
+          "name": "input-dir",
+          "type": "string",
+          "required": true,
+          "help": "Component tree (a directory of \u003cbuild\u003e/KIDComponents/)."
+        },
+        {
+          "name": "output-kid",
+          "type": "string",
+          "required": true,
+          "help": "Output .KID path."
+        }
+      ]
+    },
+    {
+      "path": [
+        "roundtrip"
+      ],
+      "help": "Verify decompose→assemble reproduces the build (exit 3 on drift).",
+      "args": [
+        {
+          "name": "kid-file",
+          "type": "string",
+          "required": true,
+          "help": "Path to the .KID file."
+        }
+      ]
+    },
+    {
+      "path": [
+        "canonicalize"
+      ],
+      "help": "Substitute install-time IENs with \"IEN\" in a tree (LOSSY; review-only).",
+      "args": [
+        {
+          "name": "decomp-dir",
+          "type": "string",
+          "required": true,
+          "help": "A decomposed component tree to rewrite in place (LOSSY)."
+        }
+      ]
+    },
+    {
+      "path": [
+        "lint"
+      ],
+      "help": "Run the PIKS data-class gate over a .KID (exit 3 on a blocked file).",
+      "flags": [
+        {
+          "name": "piks",
+          "type": "string",
+          "help": "Path to an authoritative PIKS classification table (TSV: filenumber\u003cTAB\u003eclass)."
+        },
+        {
+          "name": "strict",
+          "type": "bool",
+          "help": "Treat unclassified data files as gate failures (fail-closed)."
+        }
+      ],
+      "args": [
+        {
+          "name": "kid-file",
+          "type": "string",
+          "required": true,
+          "help": "Path to the .KID file."
+        }
+      ]
+    },
+    {
+      "path": [
+        "build"
+      ],
+      "help": "Build a KIDS transport global from a declarative build spec (deterministic, normalized export).",
+      "flags": [
+        {
+          "name": "src",
+          "type": "string",
+          "default": "src",
+          "help": "Directory holding the routine source (\u003croutine\u003e.m)."
+        },
+        {
+          "name": "out",
+          "type": "string",
+          "help": "Output .KID path (default: dist/kids/\u003cpkg\u003e.kids)."
+        }
+      ],
+      "args": [
+        {
+          "name": "spec",
+          "type": "string",
+          "required": true,
+          "help": "Path to the kids/\u003cpkg\u003e.build.json build spec."
+        }
+      ]
+    },
+    {
+      "path": [
+        "install"
+      ],
+      "help": "Install a built .KID on a live engine over the driver (non-interactive KIDS load+install).",
+      "flags": [
+        {
+          "name": "engine",
+          "type": "enum",
+          "enum": [
+            "ydb",
+            "iris"
+          ],
+          "required": true,
+          "help": "Engine to reach: ydb or iris."
+        },
+        {
+          "name": "transport",
+          "type": "enum",
+          "enum": [
+            "local",
+            "docker",
+            "remote"
+          ],
+          "default": "remote",
+          "help": "Driver transport: local | docker | remote."
+        }
+      ],
+      "args": [
+        {
+          "name": "kid-file",
+          "type": "string",
+          "required": true,
+          "help": "Path to the built .KID transport file to install on the live engine."
+        }
+      ]
+    },
+    {
+      "path": [
+        "verify"
+      ],
+      "help": "Verify a .KID's install on a live engine (#9.7 status + per-routine presence).",
+      "flags": [
+        {
+          "name": "engine",
+          "type": "enum",
+          "enum": [
+            "ydb",
+            "iris"
+          ],
+          "required": true,
+          "help": "Engine to reach: ydb or iris."
+        },
+        {
+          "name": "transport",
+          "type": "enum",
+          "enum": [
+            "local",
+            "docker",
+            "remote"
+          ],
+          "default": "remote",
+          "help": "Driver transport: local | docker | remote."
+        }
+      ],
+      "args": [
+        {
+          "name": "kid-file",
+          "type": "string",
+          "required": true,
+          "help": "Path to the .KID whose install to verify (its name + routines)."
+        }
+      ]
+    },
+    {
+      "path": [
+        "uninstall"
+      ],
+      "help": "Uninstall a .KID from a live engine (routine-only back-out: routines + #9.7/#9.6).",
+      "flags": [
+        {
+          "name": "engine",
+          "type": "enum",
+          "enum": [
+            "ydb",
+            "iris"
+          ],
+          "required": true,
+          "help": "Engine to reach: ydb or iris."
+        },
+        {
+          "name": "transport",
+          "type": "enum",
+          "enum": [
+            "local",
+            "docker",
+            "remote"
+          ],
+          "default": "remote",
+          "help": "Driver transport: local | docker | remote."
+        }
+      ],
+      "args": [
+        {
+          "name": "kid-file",
+          "type": "string",
+          "required": true,
+          "help": "Path to the .KID whose install to reverse (routine-only back-out)."
+        }
+      ]
+    }
+  ]
+}

docs/implementation-plan.md

@@ -23,7 +23,7 @@ append any new `§ Lessons learned`, and log directional decisions in `§ Q&A`.
 | P4.1 | — Phase 1: inventory only (`#9.4`/`#9.6`/`#9.7` → `inventory.json`, zero writes, no PHI) | ☐ | — | [§P4](#p4) |
 | P4.2 | — Phase 2: definition extraction (S2/S3) behind the PIKS airlock | ☐ | — | [§P4](#p4) |
 | P4.3 | — Phase 3: S1 re-export → real `.KID` for `m-kids` round-trip | 🔒 | needs gold doc (P6) | [§P4](#p4) |
-| **P5** | KIDS install automation (silent/non-interactive install of a `.KID`) | ☐ design only | `docs/kids-installation-automation.md` | [§P5](#p5) |
+| **P5** | KIDS install automation (silent/non-interactive install of a `.KID`) | ◑ built — `v pkg install/verify/uninstall` over the driver; **install now streams the transport global in size-bounded chunks → staging global → MERGE + `EN^XPDIJ`** (2026-06-12), fixing a silent partial-install of large packages (one-mega-routine staging truncated). YDB live-proven incl. the full 15-routine MSL base (test-in-place 15/15 suites); IRIS live-validation of the chunked path owed (T0b.2 IRIS leg) | `pkgcli/lifecycle.go`, `internal/installspec/*`, `docs/kids-installation-automation.md §7` | [§P5](#p5) |
 | **P6** | Gold-doc gap — *Kernel 8.0 Developer's Guide: KIDS Developer Tools User Guide* (silent-install APIs + `XPD*` answer vars + re-export entry points) | ☐ | VDL fetch pending | [§P6](#p6) |
 | **P7** | Engine parity for extraction + install (`^XTMP`/`XINDEX`/KIDS identical under YottaDB & IRIS) | 🔒 | depends on `m-ydb`/`m-iris` real-engine spikes | [§P7](#p7) |
 
@@ -122,7 +122,7 @@ definition walk / S3 component dump); recommended architecture runs over the
 engine-neutral driver contract (P7). **Phase 1 (inventory-only) is zero-write,
 no-PHI — ship first.** Open items tracked in `§ Q&A` (Q2, Q5).
 
-### P5 — KIDS install automation (design only) {#p5}
+### P5 — KIDS install automation (built; IRIS-live pending) {#p5}
 Per `docs/kids-installation-automation.md`: drive the authoritative 3-phase KIDS
 install (load distribution → install build → post-install) non-interactively.
 Two tiers: **Tier A** = native silent-install APIs + `XPD*` answer variables
@@ -131,6 +131,21 @@ interactive menus (the safe interim default). Transport globals live in `^XTMP`;
 menus `[XPD MAIN]`/`[XPD INSTALLATION MENU]`; keys `XUPROG`/`XUPROGMODE`. Runs
 over the driver contract (P7). Open items in `§ Q&A` (Q3, Q4).
 
+**Built (2026-06-12):** the chosen automation route is the **direct-`^XTMP`
+populate** path (§7.1) — `internal/installspec` generates the proven M (create the
+`#9.7` entry via `$$INST^XPDIL1` → populate `^XTMP("XPDI",XPDA,…)` from the parsed
+`.KID` pairs → synchronous `EN^XPDIJ`; `<<VPKG>>key=value` result markers), and
+`pkgcli/lifecycle.go` mounts **`v pkg install` / `verify` / `uninstall`** on it.
+The waterline split holds: the KIDS knowledge stays here, while reaching a live
+engine goes through the shared `mdriver.Client` (m-driver-sdk v0.3.0) — each verb
+stages its script as a scratch routine (`ZVPKG*`) via `exec load` and runs `EN^…`
+via `exec run` (one process = one symbol table, so `XPDA` survives the SETs).
+Markers are read off captured device output. **Live-proven on the YDB FOIA engine
+(T0a.3/T0a.4).** Remaining: **T0a.5** — the same lifecycle live on the **IRIS
+FOIA** engine (`foia` container) is the M0a exit gate (three invariants green on
+both engines). `v pkg <verb>` takes the built `.KID` + `--engine ydb|iris`
+`--transport local|docker|remote`.
+
 ### P6 — Gold-doc gap {#p6}
 The *Kernel 8.0 Developer's Guide: KIDS Developer Tools User Guide* is **not** in
 the `~/data/vdocs` gold corpus and is required for the exact silent-install APIs,