From 2c8b598bbbeb0348be1eb5c93ea516d553ee8a08 Mon Sep 17 00:00:00 2001 From: Rafael Richards Date: Sat, 13 Jun 2026 21:29:44 -0400 Subject: [PATCH 1/7] chore(arch): declare m-stdlib layer m for the waterline G1 gate MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Tag dist/repo.meta.json with "layer": "m" (bump verified_on) so `m arch check` reads m-stdlib's side of the m/v waterline directly. The gate's M-source arm scans src/*.m for ^VSL* references; m-stdlib gates clean (no v-layer routine exists yet). Records loose ends B (v-cli registry regen) + C (G1 gate built) as closed in the VSL tracker (§ s12) and adds the waterline-g1-gate memory (the layer-tag heterogeneity + registry-regen gotchas). Gate: `~/vista-cloud-dev/m-cli/dist/m arch check .` → clean, exit 0. Co-Authored-By: Claude Opus 4.8 (1M context) --- dist/repo.meta.json | 3 +- docs/memory/MEMORY.md | 1 + docs/memory/waterline-g1-gate.md | 42 +++++++++++++++++++++ docs/tracking/vsl-implementation-tracker.md | 3 +- 4 files changed, 47 insertions(+), 2 deletions(-) create mode 100644 docs/memory/waterline-g1-gate.md diff --git a/dist/repo.meta.json b/dist/repo.meta.json index a77caaa..9d9d23e 100644 --- a/dist/repo.meta.json +++ b/dist/repo.meta.json @@ -4,9 +4,10 @@ "repo": "https://github.com/m-dev-tools/m-stdlib", "role": "Pure-M runtime standard library — STD* modules", "language": ["m"], + "layer": "m", "license": "AGPL-3.0", "agent_instructions": "AGENTS.md", - "verified_on": "2026-05-10", + "verified_on": "2026-06-13", "exposes": { "modules": "dist/stdlib-manifest.json", "errors": "dist/errors.json" diff --git a/docs/memory/MEMORY.md b/docs/memory/MEMORY.md index 98b0b6a..8c5580c 100644 --- a/docs/memory/MEMORY.md +++ b/docs/memory/MEMORY.md @@ -2,6 +2,7 @@ One line per memory file. Content lives in the files, not here. +- [waterline-g1-gate](waterline-g1-gate.md) — the m/v waterline **G1 gate** (`m arch check` in m-cli) — dependency-direction (v→m only); how `layer` is declared (dist/ meta vs root `repo.meta.json` for m-cli's gitignored dist/), check-manifest doesn't schema-validate the meta, and the v-cli registry-regen `go mod tidy` dep. Built s12 (loose end C). - [t0b2-msl-kids-base](t0b2-msl-kids-base.md) — VSL T0b.2 (MSL KIDS-install-as-green): **YDB leg GREEN — 15/15 test-in-place** after the m-ydb gbldir (`e5dcf85`) + v-pkg streamed-install (`aa1991f`) fixes. **IRIS leg (s9):** `raises^STDASSERT` **now ported to IRIS** (try/catch `irisRaises` branch; YDB byte-identical) → STDFMT/STDARGS clean + STDASSERTTST 40/40 both engines + STDUUID P2 gone; remaining IRIS crashes are **non-raises**. **(s10):** file I/O made dual-engine — STDFS portable facade (`$$openRead/Write/Append`+`readLn`) + STDOS.env IRIS arm + 5 consumers migrated; **STDFSTST 50/50 both engines, YDB full 2098/0**. **But the consumer SUITES still don't go green on IRIS** — separate non-file blockers (STDJSON **byte-mode** parser, STDCSV **`@cb@` indirection**, **wide-char** descriptions). file-I/O ≠ green suites; see §s10. Full 15/15 needs byte-mode + callback-idiom + wide-char work (out of file-I/O scope). ≤8-char-name decision keeps STDASSERT/STDSEMVER as a rename follow-up. - [vsl-doc-gaps-v0.2](vsl-doc-gaps-v0.2.md) — how the VistA Standard Library architecture doc's §12 VDL gaps resolved at v0.2; the vdocs `XU:XU:UG` over-collapse defect that blocks gold-promotion of the Kernel feature guides. - [msl-vsl-coordination-plan](msl-vsl-coordination-plan.md) — the MSL↔VSL coordination model (contract-as-coupling, serialize-contract/parallelize-adapters, milestones M0–M5); VSL repo doesn't exist yet (M0 pending); future-modules-plan now organized around two demos (A inbound FHIR / B outbound S3) with a STD+VSL dependency-ordered master table. diff --git a/docs/memory/waterline-g1-gate.md b/docs/memory/waterline-g1-gate.md new file mode 100644 index 0000000..fd5165b --- /dev/null +++ b/docs/memory/waterline-g1-gate.md @@ -0,0 +1,42 @@ +--- +name: waterline-g1-gate +description: The m/v waterline G1 dependency-direction gate (`m arch check`) — how layer is declared, the dist/-gitignore gotcha, and the v-cli registry-regen dependency. +metadata: + type: project +--- + +The m/v waterline **G1 gate** (ADR `docs/background/m-v-waterline-adr.md` §3.2, +the "land first" gate) was built 2026-06-13 (s12): `m arch check` in m-cli +(`internal/arch`, branch `arch-waterline-g1`). G1 = dependency-direction: +`v → m` allowed, `m → v` forbidden. For an `m`-layer repo it runs two arms — +Go dep closure (`go list -deps -json` → fail on any `vista-cloud-dev/v-*` +module) and an M-source scan (`.m` files for `^VSL*` references). A `v`-layer +repo passes trivially. Exit 3 + violation list on any m → v edge. + +**Non-obvious — where the `layer` tag lives differs per repo (heterogeneous).** +`ResolveLayer` looks in priority order: `dist/repo.meta.json`, +`dist/v-contract.json`, then **root `repo.meta.json`**, then a `--layer` +override. +- m-stdlib + v-pkg **commit `dist/`** (drift-gated artifacts) → tag lives in + `dist/repo.meta.json` / `dist/v-contract.json`. +- **m-cli's `dist/` is gitignored** (`/dist/`), so its layer tag had to live in + a NEW **root** `repo.meta.json` (m-cli had no committed meta artifact at all + before this). Any future Go tool repo with a gitignored `dist/` needs the same + root-level meta. + +**m-stdlib `make check-manifest` does NOT schema-validate `repo.meta.json`** — it +only asserts the file is tracked + clean. So adding `"layer": "m"` was safe; +remember to bump `verified_on` (guardrail). + +**v-cli registry regen has a hidden dep.** `dist/v-registry.json` aggregates +v-pkg's contract via a dev `replace => ../v-pkg`. When v-pkg's `pkgcli` gained +the lifecycle verbs (install/verify/uninstall) it started importing +`mdriver.Client` from `m-driver-sdk` — so regenerating the registry in v-cli +first needs `go mod tidy` (airgapped: `GOPROXY=file://…`) to pull +`m-driver-sdk v0.3.0` into v-cli's module graph, else `make registry` fails +`missing go.sum entry`. + +Resume: tag the rest (`m-driver-sdk`/`m-ydb`/`m-iris` = m; `v-pkg`/`v-cli` = v) ++ adopt `m arch check` in each repo's CI; then T0b.1 scaffold v-stdlib +(`layer: v`). See [[msl-vsl-coordination-plan]] and the VSL tracker +(`docs/tracking/vsl-implementation-tracker.md` § s12). diff --git a/docs/tracking/vsl-implementation-tracker.md b/docs/tracking/vsl-implementation-tracker.md index 7bfa822..7338a55 100644 --- a/docs/tracking/vsl-implementation-tracker.md +++ b/docs/tracking/vsl-implementation-tracker.md @@ -14,7 +14,7 @@ doc_type: [TRACKING] > One row per task; update the row in the **same increment** as the code. Design > context: front door [`../plans/vsl-overview.md`](../plans/vsl-overview.md). -**Status (2026-06-12 s4): M0a CLOSED — the install/verify/uninstall lifecycle is proven on BOTH engines over the driver path. YDB: `v pkg … --engine ydb` on vehu (T0a.3/T0a.4). IRIS: `v pkg … --engine iris --transport remote` on foia (2026-06-12 s4) — install → #9.7 status=3 + `$$PING^ZZSKEL`→"pong"; verify → installed=1; uninstall → reversible (routine + #9.7/#9.6 gone). The dual-engine exit gate (T0a.5) is GREEN; v-pkg unchanged. Resume (in order): (B) regen v-cli's stale registry (3 pkg verbs); (C) wire the m/v waterline G1 gate.** +**Status (2026-06-12 s4): M0a CLOSED — the install/verify/uninstall lifecycle is proven on BOTH engines over the driver path. YDB: `v pkg … --engine ydb` on vehu (T0a.3/T0a.4). IRIS: `v pkg … --engine iris --transport remote` on foia (2026-06-12 s4) — install → #9.7 status=3 + `$$PING^ZZSKEL`→"pong"; verify → installed=1; uninstall → reversible (routine + #9.7/#9.6 gone). The dual-engine exit gate (T0a.5) is GREEN; v-pkg unchanged. **Loose ends B + C CLOSED (2026-06-13 s12):** (B) v-cli registry regenerated with the 3 lifecycle verbs (install/verify/uninstall) — v-cli `chore/registry-regen-lifecycle-verbs`; (C) the m/v waterline **G1 dependency-direction gate is built** — `m arch check` in m-cli (`arch-waterline-g1`), m-cli + m-stdlib self-declare `layer` and gate clean. Resume: (D) tag the remaining repos' `layer` (m-driver-sdk/m-ydb/m-iris = m; v-pkg/v-cli = v) + adopt `m arch check` in each CI; (E) **T0b.1 — scaffold v-stdlib (layer v).**** The `VistaEngine` substrate is built on the **m engine-driver contract** (the chosen integration is **subprocess + JSON envelope**, not in-process import — driver-contract §2/§11). Foundational driver work landed this session: m-ydb @@ -75,6 +75,7 @@ _(Append one dated line per increment as tasks move. Newest last.)_ - 2026-06-12 (s9) — **`raises^STDASSERT` PORTED to IRIS (discoveries P1 closed).** `raises` gets a `$ZVERSION["IRIS"` branch → new `irisRaises(captured,code)`: runs the XECUTE'd code in an ObjectScript `try { xecute code } catch ex { set captured=$ecode }`, then `use $principal` + clear `$ecode` and `goto raisesUnwound` — the shared substring-match against `errno` is engine-identical; **YDB path byte-identical** (the `if` is false on YDB). **Empirically validated through the *real* test runner (`m test --docker=m-test-iris --engine=iris`), after discovering ad-hoc `irissession` heredocs mislead — IRIS rejects `.m`/`.mac` hand-loads, so my early "`,M13,`/``" results were undefined-label artifacts, not error-clobbering.** On IRIS, try/catch leaves `$ECODE` engine-identical: `,M9,` for ``, and the full user code `,U-STDFMT-UNCLOSED-BRACE,` for a `set $ECODE` raise deep in an extrinsic chain — so no module's `raise()` needed changes. (Caveat learned: IRIS `try{}` fully suppresses even a deeper `$ETRAP`, so try/catch is the only viable unwind — an `$ETRAP`+arg-less-`quit` port faults `` on the extrinsic return, the IRIS analog of the YDB M17 that forced the ZGOTO trick.) TDD: RED = STDASSERTTST 0/0 crash on IRIS; added `tRaisesCapturesDeepUserEcode` (rqDeep→rqMid→rqRaise `set $ECODE` chain) to lock the user-code path on both engines. **GREEN: STDASSERTTST 40/40 on YDB AND IRIS; STDFMTTST 62/62 + STDARGSTST 37/37 clean on IRIS (were raises-crashes); STDUUIDTST 131/131 (discoveries P2 cleared — the "1 fail" was a raises-abort side-effect, not a STDUUID bug); YDB full suite 2096/0 (no regression); STDASSERT coverage 85.5% ≥85; fmt/lint clean; dist/ manifest regenerated.** Remaining IRIS 0/0 suites are **non-raises** (discoveries P2 2026-06-12): STDJSON/XML/CSV (zero `raises` calls) → m-iris GetOut wide-char lane; STDSEEDTST → crashes at its *first* test on `open path:(newversion):0` (IRIS file-OPEN portability), before its raises test. Branch `t0b2-msl-kids-base`. Engines restored (vehu up, foia stopped — IRIS validated via m-test-iris this session, not foia). - 2026-06-13 (s11) — **RE-BASELINE on foia → 10/15 (MEASURE-FIRST overturned the s10 byte-mode scope).** Rebuilt `m-iris/dist/m-iris` from `m-iris-driver@49a5b00` (the GetOut wide-char fix; the prior binary predated it), brought up foia, ran `kids-test-in-place.sh iris`. **10/15** (was 6/15). **The m-iris GetOut wide-char fix WORKS on remote** — STDURL 150/0, STDREGEX 102/0, STDFMT 62/0 all green (Phase-3 wide-char DONE on the foia path). **STDB64 55/0 + STDHEX 49/0 — the byte family — PASS, so there is NO byte-mode blocker** (the s10 "STDJSON byte-mode" claim was a misdiagnosis). The 5 reds have **5 distinct causes**, diagnosed via the real driver (docker m-test-iris for compile/assert detail, foia/remote as ground truth): **(1) STDJSON** crash ` parse+12` for ALL inputs = the **unguarded `zgoto`-`$etrap`** idiom (parse+encode) — the only base module that didn't guard it like STDFS/STDHARN/STDASSERT.raises do; **(2) STDXML** crash ` myNs("")` = **null subscripts** (IRIS rejects, YDB allows); **(3) STDCSV** won't COMPILE on IRIS (`#5475` on `@callback@(curRow,.fields)` — IRIS has **no argument indirection**); **(4) STDDATE** 1 fail = `now()` reads `$ZHOROLOG` as YDB 4-comma but IRIS `$ZHOROLOG` is elapsed-seconds → year 3567; **(5) STDUUID** 2 fails were **collateral** from the crashers (source+installed both 131/131 in isolation — no fix). **Real work = 4 code fixes** (STDJSON IRIS try/catch arm · STDXML null-subscript fix [user fork] · STDCSV `xecute` dispatch · STDDATE `$ZTIMESTAMP` arm), all YDB-byte-identical, following established in-repo idioms. discoveries.md s11 rows. Engines: foia up (this session), vehu stopped — restore at close. - 2026-06-13 (s11 close) — **T0b.2 ☑ — 17/17 test-in-place on BOTH engines.** The s11 measure-first re-baseline (10/15) understated per-suite work: each crashing suite stacked several IRIS issues exposed only as the prior one cleared. Landed, each its own commit, YDB-byte-identical: **STDJSON** — zgoto-$etrap IRIS arm; **two latent UTF-8 operator-precedence bugs** in emitUtf8 + the surrogate combine (M has no precedence; wrong on *both* engines, never caught because the old tests used literal-byte passthrough — the `\u`-escape test rewrite exposed them); empty object key → graceful `U-STDJSON-PARSE` on IRIS (user decision: IRIS prohibits null local subscripts; documented in stdjson.md + users-guide); irisParse `$ECODE`-on-failure clear; file smoke tests migrated to the STDFS facade. **STDXML** — `$$dfltNsKey()` space-sentinel for the default-namespace null subscript (user-chosen). **STDCSV** — `@callback@` arg-indirection → `xecute`-built dispatch; **+ latent STDFS `readLn` bug** (IRIS try/catch left `$ECODE` set after the EOF ``, poisoning the post-read check). **STDDATE** — `now()` `$ZTIMESTAMP` IRIS arm. **STDUUID** — `unixMs()` `$ZTIMESTAMP` IRIS arm (v7 time-prefix was loosely-monotonic on IRIS via the YDB `$zhorolog` assumption → same-second misorder). **STDOS** — full IRIS port (cwd/user/hostname via `$system.*`, cmdline/argc/arg/argv graceful-empty), and cwd switched to **`$ZDIRECTORY`** (YDB's authoritative cwd; `$PWD` was unset in vehu's `docker exec`). **STDFS+STDOS added to the base** (15→17); `v pkg build` accepts STDFS's `$ZF`; deterministic gate ✓. Re-runs: foia + vehu both `suites=17 pass=1483 fail=0`. YDB per-suite green on m-test-engine (2028/0; STDCSPRNG byte-mode suite needs the `.so`, untouched). Coverage exception: STDFS 69.3% (dual-engine, documented). Engines restored: vehu up, foia stopped. +- 2026-06-13 (s12) — **Loose ends B + C closed; G1 waterline gate built.** (B) Regenerated v-cli's stale `dist/v-registry.json` — it carried only 7 pkg verbs; v-pkg's contract gained `install`/`verify`/`uninstall` in the M0a lifecycle work (T0a.3–T0a.5), so the aggregated registry was 3 verbs behind. `make registry` (which also `go mod tidy`'d `m-driver-sdk v0.3.0` into v-cli's graph — v-pkg's `pkgcli` now imports `mdriver.Client`); full `make check` green; v-cli `chore/registry-regen-lifecycle-verbs` pushed. (C) Built the **m/v waterline G1 gate** (`m-v-waterline-adr.md` §3.2 G1, the ADR's "land first" gate): new `internal/arch` + `m arch check` in m-cli (`arch-waterline-g1`). `ResolveLayer` reads `layer` from a committed meta artifact (`dist/repo.meta.json` · `dist/v-contract.json` · root `repo.meta.json`) or `--layer`. For an `m`-layer repo it runs two arms — Go dep closure (`go list -deps -json` → fail on any `vista-cloud-dev/v-*`) + M source scan (`.m` for `^VSL*` refs); a `v`-layer repo passes trivially. Exit 3 + violation list on any m → v edge. TDD, `internal/arch` 85.7% cover, wired into m-cli's `make all`. **Proven:** m-cli self-gates clean; m-stdlib (now tagged `layer: m` here) gates clean on the M arm; v-cli falsely checked as `--layer m` flags v-pkg + v-cli (exit 3). **Resume:** tag the rest (m-driver-sdk/m-ydb/m-iris = m; v-pkg/v-cli = v) + adopt the gate in each CI; then **T0b.1 scaffold v-stdlib (layer v).** - 2026-06-13 (s10) — **File I/O made dual-engine: STDFS portable facade + 5-consumer migration (Variant B "full refactor").** STDFS (was YDB-only by design) now has public `$$openRead/$$openWrite/$$openAppend` + private `readLn`/`closeDelete`/`sizeIris`, engine-branched (`readonly→"R"`, `newversion:stream:nowrap→"WNS"`, `append→"WA"`, `close:(delete)→close:"D"`, `$ZEOF`↔``-catch), with off-engine syntax `xecute`-hidden so each compiler parses only its own arm. **STDFSTST 50/50 BOTH engines** (was 0/0 IRIS). STDOS.env got a `$system.Util.GetEnviron` IRIS arm (was `$ztrnlnm`). STDJSON/STDCSV/STDSEED/STDLOG routed through STDFS; STDSEEDTST/STDCSVTST fixtures ported. **YDB full 2098/0 — no regression**; fmt clean, lint errors=0, KIDS drift-gate ✓, dist regenerated. **KEY OUTCOME:** the file-I/O refactor makes the file layer portable but does **NOT** turn the consumer SUITES green on IRIS — they have separate non-file blockers (discoveries P2 2026-06-13): **STDJSON byte-mode parser** (`$$parse` crashes on IRIS, no file involved), **STDCSV `@callback@(args)` indirection** (crashes on IRIS even ASCII), and **wide-char descriptions** (STDCSV/STDSEED/STDLOG/STDXML → m-iris GetOut/session-capture lane). Only **STDFS** goes green on IRIS this session. Coverage note: STDFS 69.3% / STDOS 83.7% per-file (dual-engine IRIS arms unreachable on the YDB coverage tier — same documented situation as STDHARN 76.7%). **To actually green the IRIS consumer suites still needs: byte-mode portability + a portable `parseFile` callback idiom + the wide-char capture path** — all separate from file I/O. Engines restored (vehu up, foia stopped). ## Per-milestone notes From 925093505a20128b628e9df66d8ddff48f949953 Mon Sep 17 00:00:00 2001 From: Rafael Richards Date: Sat, 13 Jun 2026 22:07:47 -0400 Subject: [PATCH 2/7] =?UTF-8?q?docs(tracker):=20T0b.1=20done=20=E2=80=94?= =?UTF-8?q?=20v-stdlib=20scaffolded=20+=20pushed?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Mark T0b.1 ☑ (VSL effort): v-stdlib repo stood up at github.com/vista-cloud-dev/v-stdlib (public, layer v), smoke suite 2/2 green on both YDB and IRIS. Next M0b step is T0b.3 (the four drift gates + seams block). Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/tracking/vsl-implementation-tracker.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/tracking/vsl-implementation-tracker.md b/docs/tracking/vsl-implementation-tracker.md index 7338a55..a49f8e3 100644 --- a/docs/tracking/vsl-implementation-tracker.md +++ b/docs/tracking/vsl-implementation-tracker.md @@ -14,7 +14,7 @@ doc_type: [TRACKING] > One row per task; update the row in the **same increment** as the code. Design > context: front door [`../plans/vsl-overview.md`](../plans/vsl-overview.md). -**Status (2026-06-12 s4): M0a CLOSED — the install/verify/uninstall lifecycle is proven on BOTH engines over the driver path. YDB: `v pkg … --engine ydb` on vehu (T0a.3/T0a.4). IRIS: `v pkg … --engine iris --transport remote` on foia (2026-06-12 s4) — install → #9.7 status=3 + `$$PING^ZZSKEL`→"pong"; verify → installed=1; uninstall → reversible (routine + #9.7/#9.6 gone). The dual-engine exit gate (T0a.5) is GREEN; v-pkg unchanged. **Loose ends B + C CLOSED (2026-06-13 s12):** (B) v-cli registry regenerated with the 3 lifecycle verbs (install/verify/uninstall) — v-cli `chore/registry-regen-lifecycle-verbs`; (C) the m/v waterline **G1 dependency-direction gate is built** — `m arch check` in m-cli (`arch-waterline-g1`), m-cli + m-stdlib self-declare `layer` and gate clean. Resume: (D) tag the remaining repos' `layer` (m-driver-sdk/m-ydb/m-iris = m; v-pkg/v-cli = v) + adopt `m arch check` in each CI; (E) **T0b.1 — scaffold v-stdlib (layer v).**** +**Status (2026-06-12 s4): M0a CLOSED — the install/verify/uninstall lifecycle is proven on BOTH engines over the driver path. YDB: `v pkg … --engine ydb` on vehu (T0a.3/T0a.4). IRIS: `v pkg … --engine iris --transport remote` on foia (2026-06-12 s4) — install → #9.7 status=3 + `$$PING^ZZSKEL`→"pong"; verify → installed=1; uninstall → reversible (routine + #9.7/#9.6 gone). The dual-engine exit gate (T0a.5) is GREEN; v-pkg unchanged. **Loose ends B + C CLOSED (2026-06-13 s12):** (B) v-cli registry regenerated with the 3 lifecycle verbs (install/verify/uninstall) — v-cli `chore/registry-regen-lifecycle-verbs`; (C) the m/v waterline **G1 dependency-direction gate is built** — `m arch check` in m-cli (`arch-waterline-g1`), m-cli + m-stdlib self-declare `layer` and gate clean. **T0b.1 DONE (s12):** v-stdlib scaffolded + pushed (public, layer v, smoke 2/2 both engines). Resume: (D) tag the remaining repos' `layer` (m-driver-sdk/m-ydb/m-iris = m; v-pkg/v-cli = v) + adopt `m arch check` in each CI; (E) **T0b.3 — the four drift gates + `seams` block** (next M0b step).** The `VistaEngine` substrate is built on the **m engine-driver contract** (the chosen integration is **subprocess + JSON envelope**, not in-process import — driver-contract §2/§11). Foundational driver work landed this session: m-ydb @@ -36,7 +36,7 @@ repo still do not exist; `v-pkg` is today's `m-kids` (offline verbs only). | T0a.3 | M0a | v-pkg | ☑ | **Install→verify LIVE-PROVEN on YDB FOIA (2026-06-12).** Drove the full sequence on `worldvista/vehu` (GT.M V7.0-005): `v pkg build` → `EN1^XPDIL` load (2 stdin answers; the `v pkg build` layout matches `GI`'s parser exactly) → `EN^XPDIJ` synchronous install (no prompt — `$$ANSWER^XPDIQ`→`""` default-NO for routine-only; needs `DUZ(0)="@"`) → **#9.7 status piece 9 = 3 "Install Completed"**, routine installed AND executes (`$$PING^ZZSKEL()`→`"pong"`), #9.6 BUILD created. Exact sequence + gotchas captured in `v-pkg/docs/kids-installation-automation.md §7.1`; §11 Q1 CLOSED. **Go script generators DONE + live-validated (2026-06-12):** `installspec.InstallScript`/`VerifyScript`/`UninstallScript` emit the direct-populate M (create #9.7 via `$$INST^XPDIL1` → populate `^XTMP` from parsed `.KID` pairs → `EN^XPDIJ`; `<>key=val` result lines; already-installed guard) — TDD-green (91.4% cover) and run end-to-end on vehu (install→status=3+pong, verify, reversible uninstall). **Remaining:** mount as `v pkg install/verify/uninstall` verbs over the m-ydb/m-iris driver `Exec` (transport-architecture decision: v-pkg imports m-driver-sdk + runs the driver binary, vs shells to `m vista exec`) + repeat on IRIS (T0a.5). **DONE:** mounted as `v pkg install/verify/uninstall` over the shared `mdriver.Client` (`pkgcli/lifecycle.go`); driver-path proven on both YDB (vehu) and IRIS (foia) — see T0a.5. | T0a.2 | | T0a.4 | M0a | v-pkg | ☑ | **Reversibility LIVE-PROVEN on YDB FOIA (2026-06-12).** Routine-only uninstall = `^%ZOSF("DEL")` (routine) + `DIK` on #9.7 INSTALL + #9.6 BUILD. A snapshot→install→uninstall→diff cycle returned the engine to the pre-install snapshot (routine absent, .m/.o gone from disk, both B-xrefs empty); only divergence is the monotonic IEN counters (inherent, not a leak). KIDS ships no generic uninstall — back-out is the tool's job. **DONE:** `v pkg uninstall` wired over `mdriver.Client`; reversible back-out proven on both YDB (vehu) and IRIS (foia) over the driver path — see T0a.5. | T0a.3 | | T0a.5 | M0a | v-pkg | ☑ | **3 invariants green on BOTH engines over the DRIVER path — M0a exit gate CLOSED.** YDB: full driver-path proven (T0a.3 install/verify · T0a.4 reversible, via `v pkg … --engine ydb` on vehu). **⚠ Correction (2026-06-12 T0b.2):** the YDB *driver-path* claim does **not** hold — `v pkg … --engine ydb --transport docker` against vehu fails `%YDB-E-ZGBLDIRUNDEF` (m-ydb docker transport omits `ydb_gbldir`; discoveries P1). The YDB KIDS lifecycle was genuinely proven, but via the **raw-M-over-`docker exec`** path (sourcing `/home/vehu/etc/env`), not `v pkg --engine ydb`. The IRIS driver-path proof below stands. **Update (2026-06-12 s6):** the m-ydb gbldir gap is now FIXED (m-ydb `e5dcf85`) and `v pkg install/verify/uninstall /tmp/ZZSKEL.kids --engine ydb --transport docker` runs the full ZZSKEL lifecycle on vehu (install #9.7 status 3 → verify → reversible uninstall) — so the **M0a YDB driver-path is now genuinely real** for ZZSKEL. (Multi-routine packages hit a separate v-pkg partial-install bug — see T0b.2 / discoveries P1 — but M0a's single-routine ZZSKEL gate is unaffected.) **IRIS driver-path CLOSED (2026-06-12 s4):** ran `v pkg install/verify/uninstall /tmp/ZZSKEL.kids --engine iris --transport remote` against **foia** (IRIS 2026.1, namespace VISTA) over `mdriver.Client` → m-iris `exec`: **install** → `installed:true status:3`; `$$PING^ZZSKEL()`→"pong" (via `m-iris exec eval`); **verify** → `installed:true status:3 ZZSKEL:true`; **uninstall** → `uninstalled:true`, post-verify `installed:false status:0 ZZSKEL:false` (reversible — routine + #9.7/#9.6 gone). m-iris binary built from `m-iris-driver` (HEAD `31fa0f6`, incl. exec commit `33019b7`); `meta caps` now lists `exec`. Infra recipe: stop vehu→start foia→kill VistA-TaskMan tree (license)→`_SYSTEM`/`vista123`→`meta doctor` all-green. v-pkg unchanged (the wiring was contract-correct). Detail → docs/memory `t0a3-live-install-handoff` §T0a.5. | T0a.4 | -| T0b.1 | M0b | v-stdlib (new) | ☐ | repo scaffolded; empty suite green | T0a.5 | +| T0b.1 | M0b | v-stdlib (new) | ☑ | **DONE 2026-06-13 (s12).** v-stdlib repo scaffolded + pushed (github.com/vista-cloud-dev/v-stdlib, public, `main` `f5bbb64`). No `m new` exists (Go m-cli has no `new`; `m-project` template empty) → modeled on m-stdlib: `.m-cli.toml` (modern/pythonic-lower), Makefile (`check-fast` = fmt-check+lint+arch engine-free; engine-bound `test` stages STDASSERT from m-stdlib via `--routines`), `dist/repo.meta.json` **`layer: v`**, `tests/VSLSMOKETST.m` (trivial `^STDASSERT` smoke). Verified green: fmt-check+lint(0)+arch(layer v, clean); **VSLSMOKETST 2/2 on YDB + 2/2 on IRIS**. No `VSL*` modules yet (VSLCFG first at M1/T1.2). | T0a.5 | | T0b.2 | M0b | m-stdlib | ☑ | **CLOSED 2026-06-13 (s11): MSL base test-in-place 17/17 GREEN on BOTH engines.** foia (IRIS 2026.1, remote/Atelier): `suites=17 pass=1483 fail=0`; vehu (GT.M V7.0-005, docker): `suites=17 pass=1483 fail=0`; both with reversible uninstall + verify-clean. Base grew 15→**17** (added STDFS+STDOS — a real dependency of STDCSV/STDJSON since the s10 STDFS migration). Closed via the s11 IRIS-portability fixes (all YDB-byte-identical): STDJSON (zgoto-$etrap arm + 2 latent UTF-8 precedence bugs + empty-key graceful-reject + irisParse $ecode), STDXML (null-subscript sentinel), STDCSV (xecute callback) + STDFS (readLn $ecode-on-EOF), STDDATE/STDUUID ($ZTIMESTAMP clock), STDOS (full IRIS port + $ZDIRECTORY cwd). Coverage: STDFS 69.3% per-file (dual-engine xecute-hidden arms unreachable on the YDB tier — documented exception like STDHARN 76.7%; aggregate gate unaffected); STDOS 85.1%. **(history below)** **Offline deliverables done; live loop blocked on m-ydb.** Build spec `kids/std.build.json` (MSL base = 15 ≤8-char pure modules: STDSTR/STDMATH/STDB64/STDHEX/STDFMT/STDCOLL/STDDATE/STDURL/STDARGS/STDJSON/STDTOML/STDXML/STDCSV/STDUUID/STDREGEX); `v pkg build` → **byte-identical** `dist/kids/MSL.kids` (`MSL*0.1*1`), drift-gated by `make kids`/`check-kids`. Test-in-place orchestrator `scripts/kids-test-in-place.sh` (v pkg install → load STDASSERT+STDHARN+*TST as never-shipped harness sidecar → `do run^STDHARN()` against the **installed** routines → uninstall → verify clean); harness primitives validated piecemeal on vehu (durable `exec load`; STDHARN frame contract). **m-ydb `$ydb_gbldir` blocker FIXED** (m-ydb `e5dcf85`) → the YDB driver path now reaches globals; the loop runs install→harness→… and the **harness mechanism is proven** (STDSTRTST/STDMATHTST/STDB64TST passed **in place** against KIDS-installed routines: 154 assertions, 0 failures). **YDB leg GREEN (2026-06-12 s8):** after the v-pkg streamed-install fix (`aa1991f` — install was silently installing only the first ~3 routines of a multi-routine KID; now streams the transport global in size-bounded chunks → staging global → MERGE + `EN^XPDIJ`), the full loop is green on vehu: all 15 routines install, **15/15 suites pass test-in-place (1403 assertions, 0 fail)**, reversible uninstall, verify-clean. Orchestrator now runs the harness **per suite** (a single 15-suite frame overflows the IRIS runner's output capture) and tolerates runner errors. **IRIS leg PARTIAL:** the chunked install **fully works on IRIS** (all 15 installed on foia), but test-in-place is **6/15** — blocked by (1) **discoveries P1 m-stdlib: `raises^STDASSERT` is YDB-only** (`$ETRAP`/`ZGOTO` → `` on IRIS) crashing the 6 error-path suites (STDFMT/STDDATE/STDARGS/STDJSON/STDXML/STDCSV); (2) **discoveries P1 m-iris: runner `GetOut` faults on wide-char output** (STDURL/STDREGEX); (3) **discoveries P2: STDUUIDTST 1 IRIS-only failure**. This is the first time m-stdlib suites have run on IRIS (YDB-first project). STDASSERT(9)/STDSEMVER(9) sidecar'd per the ≤8-char decision. **Update (2026-06-12 s9): `raises^STDASSERT` PORTED to IRIS** (discoveries P1 closed) — `$ZVERSION["IRIS"`→`irisRaises` try/catch, YDB byte-identical; STDASSERTTST 40/40 both engines, STDFMT 62/62 + STDARGS 37/37 clean on IRIS, STDUUID now 131/131 (P2 cleared as a raises side-effect), YDB full 2096/0. Remaining IRIS crashes are **non-raises** (discoveries P2 2026-06-12): STDJSON/XML/CSV → m-iris GetOut wide-char lane; STDSEED → IRIS file-OPEN portability. **To close 15/15: m-iris GetOut wide-char fix + STDSEED/STDCSV file-open portability**, then re-run `kids-test-in-place.sh iris` on foia and flip ☑. **Update (2026-06-13 s11): RE-BASELINE → 10/15.** The m-iris GetOut wide-char fix (`m-iris-driver@49a5b00`) WORKS on remote (STDURL/STDREGEX/STDFMT green). **No byte-mode blocker** (STDB64/STDHEX pass). 4 real m-stdlib code fixes remain — STDJSON unguarded `zgoto`-`$etrap`, STDXML null subscripts, STDCSV `@callback@` arg-indirection (won't compile on IRIS), STDDATE `now()` `$ZHOROLOG`-format — all YDB-byte-identical; STDUUID's 2 fails were collateral (no fix). See s11 log + discoveries. | T0a.5 | | T0b.3 | M0b | m-stdlib + v-stdlib | ☐ | 4 drift gates exist + red-on-violation | T0b.2 | | T0b.4 | M0b | m-stdlib | ☐ | seam contract v1 tagged + pinned | T0b.3 | @@ -76,6 +76,7 @@ _(Append one dated line per increment as tasks move. Newest last.)_ - 2026-06-13 (s11) — **RE-BASELINE on foia → 10/15 (MEASURE-FIRST overturned the s10 byte-mode scope).** Rebuilt `m-iris/dist/m-iris` from `m-iris-driver@49a5b00` (the GetOut wide-char fix; the prior binary predated it), brought up foia, ran `kids-test-in-place.sh iris`. **10/15** (was 6/15). **The m-iris GetOut wide-char fix WORKS on remote** — STDURL 150/0, STDREGEX 102/0, STDFMT 62/0 all green (Phase-3 wide-char DONE on the foia path). **STDB64 55/0 + STDHEX 49/0 — the byte family — PASS, so there is NO byte-mode blocker** (the s10 "STDJSON byte-mode" claim was a misdiagnosis). The 5 reds have **5 distinct causes**, diagnosed via the real driver (docker m-test-iris for compile/assert detail, foia/remote as ground truth): **(1) STDJSON** crash ` parse+12` for ALL inputs = the **unguarded `zgoto`-`$etrap`** idiom (parse+encode) — the only base module that didn't guard it like STDFS/STDHARN/STDASSERT.raises do; **(2) STDXML** crash ` myNs("")` = **null subscripts** (IRIS rejects, YDB allows); **(3) STDCSV** won't COMPILE on IRIS (`#5475` on `@callback@(curRow,.fields)` — IRIS has **no argument indirection**); **(4) STDDATE** 1 fail = `now()` reads `$ZHOROLOG` as YDB 4-comma but IRIS `$ZHOROLOG` is elapsed-seconds → year 3567; **(5) STDUUID** 2 fails were **collateral** from the crashers (source+installed both 131/131 in isolation — no fix). **Real work = 4 code fixes** (STDJSON IRIS try/catch arm · STDXML null-subscript fix [user fork] · STDCSV `xecute` dispatch · STDDATE `$ZTIMESTAMP` arm), all YDB-byte-identical, following established in-repo idioms. discoveries.md s11 rows. Engines: foia up (this session), vehu stopped — restore at close. - 2026-06-13 (s11 close) — **T0b.2 ☑ — 17/17 test-in-place on BOTH engines.** The s11 measure-first re-baseline (10/15) understated per-suite work: each crashing suite stacked several IRIS issues exposed only as the prior one cleared. Landed, each its own commit, YDB-byte-identical: **STDJSON** — zgoto-$etrap IRIS arm; **two latent UTF-8 operator-precedence bugs** in emitUtf8 + the surrogate combine (M has no precedence; wrong on *both* engines, never caught because the old tests used literal-byte passthrough — the `\u`-escape test rewrite exposed them); empty object key → graceful `U-STDJSON-PARSE` on IRIS (user decision: IRIS prohibits null local subscripts; documented in stdjson.md + users-guide); irisParse `$ECODE`-on-failure clear; file smoke tests migrated to the STDFS facade. **STDXML** — `$$dfltNsKey()` space-sentinel for the default-namespace null subscript (user-chosen). **STDCSV** — `@callback@` arg-indirection → `xecute`-built dispatch; **+ latent STDFS `readLn` bug** (IRIS try/catch left `$ECODE` set after the EOF ``, poisoning the post-read check). **STDDATE** — `now()` `$ZTIMESTAMP` IRIS arm. **STDUUID** — `unixMs()` `$ZTIMESTAMP` IRIS arm (v7 time-prefix was loosely-monotonic on IRIS via the YDB `$zhorolog` assumption → same-second misorder). **STDOS** — full IRIS port (cwd/user/hostname via `$system.*`, cmdline/argc/arg/argv graceful-empty), and cwd switched to **`$ZDIRECTORY`** (YDB's authoritative cwd; `$PWD` was unset in vehu's `docker exec`). **STDFS+STDOS added to the base** (15→17); `v pkg build` accepts STDFS's `$ZF`; deterministic gate ✓. Re-runs: foia + vehu both `suites=17 pass=1483 fail=0`. YDB per-suite green on m-test-engine (2028/0; STDCSPRNG byte-mode suite needs the `.so`, untouched). Coverage exception: STDFS 69.3% (dual-engine, documented). Engines restored: vehu up, foia stopped. - 2026-06-13 (s12) — **Loose ends B + C closed; G1 waterline gate built.** (B) Regenerated v-cli's stale `dist/v-registry.json` — it carried only 7 pkg verbs; v-pkg's contract gained `install`/`verify`/`uninstall` in the M0a lifecycle work (T0a.3–T0a.5), so the aggregated registry was 3 verbs behind. `make registry` (which also `go mod tidy`'d `m-driver-sdk v0.3.0` into v-cli's graph — v-pkg's `pkgcli` now imports `mdriver.Client`); full `make check` green; v-cli `chore/registry-regen-lifecycle-verbs` pushed. (C) Built the **m/v waterline G1 gate** (`m-v-waterline-adr.md` §3.2 G1, the ADR's "land first" gate): new `internal/arch` + `m arch check` in m-cli (`arch-waterline-g1`). `ResolveLayer` reads `layer` from a committed meta artifact (`dist/repo.meta.json` · `dist/v-contract.json` · root `repo.meta.json`) or `--layer`. For an `m`-layer repo it runs two arms — Go dep closure (`go list -deps -json` → fail on any `vista-cloud-dev/v-*`) + M source scan (`.m` for `^VSL*` refs); a `v`-layer repo passes trivially. Exit 3 + violation list on any m → v edge. TDD, `internal/arch` 85.7% cover, wired into m-cli's `make all`. **Proven:** m-cli self-gates clean; m-stdlib (now tagged `layer: m` here) gates clean on the M arm; v-cli falsely checked as `--layer m` flags v-pkg + v-cli (exit 3). **Resume:** tag the rest (m-driver-sdk/m-ydb/m-iris = m; v-pkg/v-cli = v) + adopt the gate in each CI; then **T0b.1 scaffold v-stdlib (layer v).** +- 2026-06-13 (s12) — **T0b.1 DONE — v-stdlib scaffolded + pushed.** Created github.com/vista-cloud-dev/v-stdlib (public, matching the m-stdlib/v-pkg/v-cli siblings; `main` `f5bbb64`). No automated scaffolder exists (the Go m-cli has no `new` verb, the legacy Python `m` is gone, `~/claude/templates/m-project/` is empty), so modeled the skeleton on m-stdlib, adapted to layer v / VSL*: `.m-cli.toml` (modern, pythonic-lower, target-engine any), `Makefile` (`check-fast` = fmt-check+lint+arch engine-free; engine-bound `test`/`coverage` stage STDASSERT from m-stdlib via `--routines`, with `ENGINE`/`DOCKER` vars), `dist/repo.meta.json` with **`layer: v`** (gated by `m arch check` → passes trivially, v→m allowed), `tests/VSLSMOKETST.m` (trivial `^STDASSERT` smoke), README + CLAUDE.md (waterline rules, TDD, dual-engine). Gotcha: `m fmt --rules` only accepts `identity|canonical`; the `pythonic-lower` style comes from `.m-cli.toml` `[fmt]` when no `--rules` is passed (mirror m-stdlib's bare `m fmt`). **Verified green:** fmt-check + lint (0 findings) + arch (layer v, clean); **VSLSMOKETST 2/2 on YDB (m-test-engine) AND 2/2 on IRIS (m-test-iris)** — empty-suite-green exit criterion met dual-engine. No `VSL*` modules yet; VSLCFG (XPAR config, binds STDENV) is first at M1/T1.2. **Next M0b step: T0b.3** (the four drift gates + `seams` block). - 2026-06-13 (s10) — **File I/O made dual-engine: STDFS portable facade + 5-consumer migration (Variant B "full refactor").** STDFS (was YDB-only by design) now has public `$$openRead/$$openWrite/$$openAppend` + private `readLn`/`closeDelete`/`sizeIris`, engine-branched (`readonly→"R"`, `newversion:stream:nowrap→"WNS"`, `append→"WA"`, `close:(delete)→close:"D"`, `$ZEOF`↔``-catch), with off-engine syntax `xecute`-hidden so each compiler parses only its own arm. **STDFSTST 50/50 BOTH engines** (was 0/0 IRIS). STDOS.env got a `$system.Util.GetEnviron` IRIS arm (was `$ztrnlnm`). STDJSON/STDCSV/STDSEED/STDLOG routed through STDFS; STDSEEDTST/STDCSVTST fixtures ported. **YDB full 2098/0 — no regression**; fmt clean, lint errors=0, KIDS drift-gate ✓, dist regenerated. **KEY OUTCOME:** the file-I/O refactor makes the file layer portable but does **NOT** turn the consumer SUITES green on IRIS — they have separate non-file blockers (discoveries P2 2026-06-13): **STDJSON byte-mode parser** (`$$parse` crashes on IRIS, no file involved), **STDCSV `@callback@(args)` indirection** (crashes on IRIS even ASCII), and **wide-char descriptions** (STDCSV/STDSEED/STDLOG/STDXML → m-iris GetOut/session-capture lane). Only **STDFS** goes green on IRIS this session. Coverage note: STDFS 69.3% / STDOS 83.7% per-file (dual-engine IRIS arms unreachable on the YDB coverage tier — same documented situation as STDHARN 76.7%). **To actually green the IRIS consumer suites still needs: byte-mode portability + a portable `parseFile` callback idiom + the wide-char capture path** — all separate from file I/O. Engines restored (vehu up, foia stopped). ## Per-milestone notes From a565a7711466cbf21e278ea9d7f75543d1d5b785 Mon Sep 17 00:00:00 2001 From: Rafael Richards Date: Sat, 13 Jun 2026 23:15:59 -0400 Subject: [PATCH 3/7] docs(tracker): (D) layer tags landed across all 8 ecosystem repos Record that the m/v waterline `layer` tag is now declared in every repo: m-cli/m-stdlib/m-driver-sdk/m-ydb/m-iris = m; v-pkg/v-cli/v-stdlib = v. The 5 newly-tagged repos use a root repo.meta.json (layer is a repo property, not a per-domain/generated-contract field); the 3 m repos gate clean on the Go dep arm, the v repos pass G1 trivially. Residual: the reusable org CI workflow isn't wired yet, so enforcement is local-only. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/memory/waterline-g1-gate.md | 13 ++++++++++--- docs/tracking/vsl-implementation-tracker.md | 3 ++- 2 files changed, 12 insertions(+), 4 deletions(-) diff --git a/docs/memory/waterline-g1-gate.md b/docs/memory/waterline-g1-gate.md index fd5165b..7f6195f 100644 --- a/docs/memory/waterline-g1-gate.md +++ b/docs/memory/waterline-g1-gate.md @@ -36,7 +36,14 @@ first needs `go mod tidy` (airgapped: `GOPROXY=file://…`) to pull `m-driver-sdk v0.3.0` into v-cli's module graph, else `make registry` fails `missing go.sum entry`. -Resume: tag the rest (`m-driver-sdk`/`m-ydb`/`m-iris` = m; `v-pkg`/`v-cli` = v) -+ adopt `m arch check` in each repo's CI; then T0b.1 scaffold v-stdlib -(`layer: v`). See [[msl-vsl-coordination-plan]] and the VSL tracker +**All 8 ecosystem repos are now tagged (s12):** m-cli/m-stdlib/m-driver-sdk/ +m-ydb/m-iris = `m`; v-pkg/v-cli/v-stdlib = `v`. The 5 later ones each got a +**root `repo.meta.json`** (the layer is a repo property — deliberately NOT in +v-pkg's generated `dist/v-contract.json` or v-cli's aggregate +`dist/v-registry.json`; `ResolveLayer` falls through to root). The 3 `m` repos +gate clean on the Go arm; the `v` repos pass trivially. **Residual:** the gate +runs locally / in each `make` only — the reusable org CI workflow (ADR §3.3.2, +`.github/workflows/arch-waterline.yml`) is NOT wired yet, so CI doesn't enforce +it on push. v-stdlib scaffold (T0b.1) is done. See +[[msl-vsl-coordination-plan]] and the VSL tracker (`docs/tracking/vsl-implementation-tracker.md` § s12). diff --git a/docs/tracking/vsl-implementation-tracker.md b/docs/tracking/vsl-implementation-tracker.md index a49f8e3..4f67418 100644 --- a/docs/tracking/vsl-implementation-tracker.md +++ b/docs/tracking/vsl-implementation-tracker.md @@ -14,7 +14,7 @@ doc_type: [TRACKING] > One row per task; update the row in the **same increment** as the code. Design > context: front door [`../plans/vsl-overview.md`](../plans/vsl-overview.md). -**Status (2026-06-12 s4): M0a CLOSED — the install/verify/uninstall lifecycle is proven on BOTH engines over the driver path. YDB: `v pkg … --engine ydb` on vehu (T0a.3/T0a.4). IRIS: `v pkg … --engine iris --transport remote` on foia (2026-06-12 s4) — install → #9.7 status=3 + `$$PING^ZZSKEL`→"pong"; verify → installed=1; uninstall → reversible (routine + #9.7/#9.6 gone). The dual-engine exit gate (T0a.5) is GREEN; v-pkg unchanged. **Loose ends B + C CLOSED (2026-06-13 s12):** (B) v-cli registry regenerated with the 3 lifecycle verbs (install/verify/uninstall) — v-cli `chore/registry-regen-lifecycle-verbs`; (C) the m/v waterline **G1 dependency-direction gate is built** — `m arch check` in m-cli (`arch-waterline-g1`), m-cli + m-stdlib self-declare `layer` and gate clean. **T0b.1 DONE (s12):** v-stdlib scaffolded + pushed (public, layer v, smoke 2/2 both engines). Resume: (D) tag the remaining repos' `layer` (m-driver-sdk/m-ydb/m-iris = m; v-pkg/v-cli = v) + adopt `m arch check` in each CI; (E) **T0b.3 — the four drift gates + `seams` block** (next M0b step).** +**Status (2026-06-12 s4): M0a CLOSED — the install/verify/uninstall lifecycle is proven on BOTH engines over the driver path. YDB: `v pkg … --engine ydb` on vehu (T0a.3/T0a.4). IRIS: `v pkg … --engine iris --transport remote` on foia (2026-06-12 s4) — install → #9.7 status=3 + `$$PING^ZZSKEL`→"pong"; verify → installed=1; uninstall → reversible (routine + #9.7/#9.6 gone). The dual-engine exit gate (T0a.5) is GREEN; v-pkg unchanged. **Loose ends B + C CLOSED (2026-06-13 s12):** (B) v-cli registry regenerated with the 3 lifecycle verbs (install/verify/uninstall) — v-cli `chore/registry-regen-lifecycle-verbs`; (C) the m/v waterline **G1 dependency-direction gate is built** — `m arch check` in m-cli (`arch-waterline-g1`), m-cli + m-stdlib self-declare `layer` and gate clean. **T0b.1 DONE (s12):** v-stdlib scaffolded + pushed (public, layer v, smoke 2/2 both engines). **(D) layer tags DONE (s12):** all 8 ecosystem repos now declare `layer` and gate clean via `m arch check` — m-cli/m-stdlib/m-driver-sdk/m-ydb/m-iris = **m** (Go+M arms clean); v-pkg/v-cli/v-stdlib = **v** (pass trivially). Each tag is a root `repo.meta.json` (layer is a repo property, not a per-domain/generated-contract field). Resume: (D-residual) adopt `m arch check` as a reusable org CI workflow (`.github` repo) so the gate runs on every push, not just locally; (E) **T0b.3 — the four drift gates + `seams` block** (next M0b step).** The `VistaEngine` substrate is built on the **m engine-driver contract** (the chosen integration is **subprocess + JSON envelope**, not in-process import — driver-contract §2/§11). Foundational driver work landed this session: m-ydb @@ -77,6 +77,7 @@ _(Append one dated line per increment as tasks move. Newest last.)_ - 2026-06-13 (s11 close) — **T0b.2 ☑ — 17/17 test-in-place on BOTH engines.** The s11 measure-first re-baseline (10/15) understated per-suite work: each crashing suite stacked several IRIS issues exposed only as the prior one cleared. Landed, each its own commit, YDB-byte-identical: **STDJSON** — zgoto-$etrap IRIS arm; **two latent UTF-8 operator-precedence bugs** in emitUtf8 + the surrogate combine (M has no precedence; wrong on *both* engines, never caught because the old tests used literal-byte passthrough — the `\u`-escape test rewrite exposed them); empty object key → graceful `U-STDJSON-PARSE` on IRIS (user decision: IRIS prohibits null local subscripts; documented in stdjson.md + users-guide); irisParse `$ECODE`-on-failure clear; file smoke tests migrated to the STDFS facade. **STDXML** — `$$dfltNsKey()` space-sentinel for the default-namespace null subscript (user-chosen). **STDCSV** — `@callback@` arg-indirection → `xecute`-built dispatch; **+ latent STDFS `readLn` bug** (IRIS try/catch left `$ECODE` set after the EOF ``, poisoning the post-read check). **STDDATE** — `now()` `$ZTIMESTAMP` IRIS arm. **STDUUID** — `unixMs()` `$ZTIMESTAMP` IRIS arm (v7 time-prefix was loosely-monotonic on IRIS via the YDB `$zhorolog` assumption → same-second misorder). **STDOS** — full IRIS port (cwd/user/hostname via `$system.*`, cmdline/argc/arg/argv graceful-empty), and cwd switched to **`$ZDIRECTORY`** (YDB's authoritative cwd; `$PWD` was unset in vehu's `docker exec`). **STDFS+STDOS added to the base** (15→17); `v pkg build` accepts STDFS's `$ZF`; deterministic gate ✓. Re-runs: foia + vehu both `suites=17 pass=1483 fail=0`. YDB per-suite green on m-test-engine (2028/0; STDCSPRNG byte-mode suite needs the `.so`, untouched). Coverage exception: STDFS 69.3% (dual-engine, documented). Engines restored: vehu up, foia stopped. - 2026-06-13 (s12) — **Loose ends B + C closed; G1 waterline gate built.** (B) Regenerated v-cli's stale `dist/v-registry.json` — it carried only 7 pkg verbs; v-pkg's contract gained `install`/`verify`/`uninstall` in the M0a lifecycle work (T0a.3–T0a.5), so the aggregated registry was 3 verbs behind. `make registry` (which also `go mod tidy`'d `m-driver-sdk v0.3.0` into v-cli's graph — v-pkg's `pkgcli` now imports `mdriver.Client`); full `make check` green; v-cli `chore/registry-regen-lifecycle-verbs` pushed. (C) Built the **m/v waterline G1 gate** (`m-v-waterline-adr.md` §3.2 G1, the ADR's "land first" gate): new `internal/arch` + `m arch check` in m-cli (`arch-waterline-g1`). `ResolveLayer` reads `layer` from a committed meta artifact (`dist/repo.meta.json` · `dist/v-contract.json` · root `repo.meta.json`) or `--layer`. For an `m`-layer repo it runs two arms — Go dep closure (`go list -deps -json` → fail on any `vista-cloud-dev/v-*`) + M source scan (`.m` for `^VSL*` refs); a `v`-layer repo passes trivially. Exit 3 + violation list on any m → v edge. TDD, `internal/arch` 85.7% cover, wired into m-cli's `make all`. **Proven:** m-cli self-gates clean; m-stdlib (now tagged `layer: m` here) gates clean on the M arm; v-cli falsely checked as `--layer m` flags v-pkg + v-cli (exit 3). **Resume:** tag the rest (m-driver-sdk/m-ydb/m-iris = m; v-pkg/v-cli = v) + adopt the gate in each CI; then **T0b.1 scaffold v-stdlib (layer v).** - 2026-06-13 (s12) — **T0b.1 DONE — v-stdlib scaffolded + pushed.** Created github.com/vista-cloud-dev/v-stdlib (public, matching the m-stdlib/v-pkg/v-cli siblings; `main` `f5bbb64`). No automated scaffolder exists (the Go m-cli has no `new` verb, the legacy Python `m` is gone, `~/claude/templates/m-project/` is empty), so modeled the skeleton on m-stdlib, adapted to layer v / VSL*: `.m-cli.toml` (modern, pythonic-lower, target-engine any), `Makefile` (`check-fast` = fmt-check+lint+arch engine-free; engine-bound `test`/`coverage` stage STDASSERT from m-stdlib via `--routines`, with `ENGINE`/`DOCKER` vars), `dist/repo.meta.json` with **`layer: v`** (gated by `m arch check` → passes trivially, v→m allowed), `tests/VSLSMOKETST.m` (trivial `^STDASSERT` smoke), README + CLAUDE.md (waterline rules, TDD, dual-engine). Gotcha: `m fmt --rules` only accepts `identity|canonical`; the `pythonic-lower` style comes from `.m-cli.toml` `[fmt]` when no `--rules` is passed (mirror m-stdlib's bare `m fmt`). **Verified green:** fmt-check + lint (0 findings) + arch (layer v, clean); **VSLSMOKETST 2/2 on YDB (m-test-engine) AND 2/2 on IRIS (m-test-iris)** — empty-suite-green exit criterion met dual-engine. No `VSL*` modules yet; VSLCFG (XPAR config, binds STDENV) is first at M1/T1.2. **Next M0b step: T0b.3** (the four drift gates + `seams` block). +- 2026-06-13 (s12) — **(D) layer tags landed across all 8 ecosystem repos.** Tagged the 5 remaining repos (m-cli + m-stdlib were tagged when G1 was built; v-stdlib at scaffold): **m** = m-driver-sdk (`coordination`), m-ydb (`m-ydb-driver`), m-iris (`m-iris-driver`); **v** = v-pkg (`refile-v-pkg`), v-cli (`chore/registry-regen-lifecycle-verbs`). Each via a root `repo.meta.json` — the layer is a **repo** property, so it does NOT belong in the per-domain generated `dist/v-contract.json` (v-pkg) or aggregate `dist/v-registry.json` (v-cli); `ResolveLayer` reads root `repo.meta.json` (falling through past those generated artifacts, which carry no `layer` key). All 3 `m` repos gate **clean on the Go arm** (`go list -deps` → no `vista-cloud-dev/v-*` in closure) + M arm; the 2 `v` repos pass G1 trivially. Each committed on its current working branch + pushed. **Residual:** the gate runs locally / in each repo's `make` only — the reusable org CI workflow (ADR §3.3.2, `.github/workflows/arch-waterline.yml`) is not yet wired, so CI doesn't enforce it on push yet. Next M0b: T0b.3. - 2026-06-13 (s10) — **File I/O made dual-engine: STDFS portable facade + 5-consumer migration (Variant B "full refactor").** STDFS (was YDB-only by design) now has public `$$openRead/$$openWrite/$$openAppend` + private `readLn`/`closeDelete`/`sizeIris`, engine-branched (`readonly→"R"`, `newversion:stream:nowrap→"WNS"`, `append→"WA"`, `close:(delete)→close:"D"`, `$ZEOF`↔``-catch), with off-engine syntax `xecute`-hidden so each compiler parses only its own arm. **STDFSTST 50/50 BOTH engines** (was 0/0 IRIS). STDOS.env got a `$system.Util.GetEnviron` IRIS arm (was `$ztrnlnm`). STDJSON/STDCSV/STDSEED/STDLOG routed through STDFS; STDSEEDTST/STDCSVTST fixtures ported. **YDB full 2098/0 — no regression**; fmt clean, lint errors=0, KIDS drift-gate ✓, dist regenerated. **KEY OUTCOME:** the file-I/O refactor makes the file layer portable but does **NOT** turn the consumer SUITES green on IRIS — they have separate non-file blockers (discoveries P2 2026-06-13): **STDJSON byte-mode parser** (`$$parse` crashes on IRIS, no file involved), **STDCSV `@callback@(args)` indirection** (crashes on IRIS even ASCII), and **wide-char descriptions** (STDCSV/STDSEED/STDLOG/STDXML → m-iris GetOut/session-capture lane). Only **STDFS** goes green on IRIS this session. Coverage note: STDFS 69.3% / STDOS 83.7% per-file (dual-engine IRIS arms unreachable on the YDB coverage tier — same documented situation as STDHARN 76.7%). **To actually green the IRIS consumer suites still needs: byte-mode portability + a portable `parseFile` callback idiom + the wide-char capture path** — all separate from file I/O. Engines restored (vehu up, foia stopped). ## Per-milestone notes From 0c601446f86b4c111265a1888fc812ef2056cc09 Mon Sep 17 00:00:00 2001 From: Rafael Richards Date: Sun, 14 Jun 2026 07:10:30 -0400 Subject: [PATCH 4/7] docs(tracker): reusable arch-waterline CI workflow created Record the .github reusable workflow (arch-waterline.yml) that runs `m arch check` in any repo. Validated via go install of the m-cli arch branch. Activation pending two main-merges + per-repo caller adoption. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/tracking/vsl-implementation-tracker.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tracking/vsl-implementation-tracker.md b/docs/tracking/vsl-implementation-tracker.md index 4f67418..c0e6fb1 100644 --- a/docs/tracking/vsl-implementation-tracker.md +++ b/docs/tracking/vsl-implementation-tracker.md @@ -14,7 +14,7 @@ doc_type: [TRACKING] > One row per task; update the row in the **same increment** as the code. Design > context: front door [`../plans/vsl-overview.md`](../plans/vsl-overview.md). -**Status (2026-06-12 s4): M0a CLOSED — the install/verify/uninstall lifecycle is proven on BOTH engines over the driver path. YDB: `v pkg … --engine ydb` on vehu (T0a.3/T0a.4). IRIS: `v pkg … --engine iris --transport remote` on foia (2026-06-12 s4) — install → #9.7 status=3 + `$$PING^ZZSKEL`→"pong"; verify → installed=1; uninstall → reversible (routine + #9.7/#9.6 gone). The dual-engine exit gate (T0a.5) is GREEN; v-pkg unchanged. **Loose ends B + C CLOSED (2026-06-13 s12):** (B) v-cli registry regenerated with the 3 lifecycle verbs (install/verify/uninstall) — v-cli `chore/registry-regen-lifecycle-verbs`; (C) the m/v waterline **G1 dependency-direction gate is built** — `m arch check` in m-cli (`arch-waterline-g1`), m-cli + m-stdlib self-declare `layer` and gate clean. **T0b.1 DONE (s12):** v-stdlib scaffolded + pushed (public, layer v, smoke 2/2 both engines). **(D) layer tags DONE (s12):** all 8 ecosystem repos now declare `layer` and gate clean via `m arch check` — m-cli/m-stdlib/m-driver-sdk/m-ydb/m-iris = **m** (Go+M arms clean); v-pkg/v-cli/v-stdlib = **v** (pass trivially). Each tag is a root `repo.meta.json` (layer is a repo property, not a per-domain/generated-contract field). Resume: (D-residual) adopt `m arch check` as a reusable org CI workflow (`.github` repo) so the gate runs on every push, not just locally; (E) **T0b.3 — the four drift gates + `seams` block** (next M0b step).** +**Status (2026-06-12 s4): M0a CLOSED — the install/verify/uninstall lifecycle is proven on BOTH engines over the driver path. YDB: `v pkg … --engine ydb` on vehu (T0a.3/T0a.4). IRIS: `v pkg … --engine iris --transport remote` on foia (2026-06-12 s4) — install → #9.7 status=3 + `$$PING^ZZSKEL`→"pong"; verify → installed=1; uninstall → reversible (routine + #9.7/#9.6 gone). The dual-engine exit gate (T0a.5) is GREEN; v-pkg unchanged. **Loose ends B + C CLOSED (2026-06-13 s12):** (B) v-cli registry regenerated with the 3 lifecycle verbs (install/verify/uninstall) — v-cli `chore/registry-regen-lifecycle-verbs`; (C) the m/v waterline **G1 dependency-direction gate is built** — `m arch check` in m-cli (`arch-waterline-g1`), m-cli + m-stdlib self-declare `layer` and gate clean. **T0b.1 DONE (s12):** v-stdlib scaffolded + pushed (public, layer v, smoke 2/2 both engines). **(D) layer tags DONE (s12):** all 8 ecosystem repos now declare `layer` and gate clean via `m arch check` — m-cli/m-stdlib/m-driver-sdk/m-ydb/m-iris = **m** (Go+M arms clean); v-pkg/v-cli/v-stdlib = **v** (pass trivially). Each tag is a root `repo.meta.json` (layer is a repo property, not a per-domain/generated-contract field). **(D-residual) reusable org CI workflow CREATED (s12):** `.github/.github/workflows/arch-waterline.yml` (branch `arch-waterline-workflow`) — go-installs `m` from m-cli (`m-cli-ref` input, default `main`) and runs `m arch check .`; exit 3 fails the job. Validated: `go install …@arch-waterline-g1` + `m-cli arch check .` gates m-stdlib clean. **Activation (3 steps, all user-gated merges/adoption):** (1) merge m-cli `arch-waterline-g1`→main (so `m arch check` is on m-cli main); (2) merge `.github` `arch-waterline-workflow`→main (so callers can `uses: …@main`); (3) add the one-line `arch:` caller job to each repo's `ci.yml`. Resume: finish activation; (E) **T0b.3 — the four drift gates + `seams` block** (next M0b step).** The `VistaEngine` substrate is built on the **m engine-driver contract** (the chosen integration is **subprocess + JSON envelope**, not in-process import — driver-contract §2/§11). Foundational driver work landed this session: m-ydb From f81cf1bac5055afbc086511a4ee4565f5759fb06 Mon Sep 17 00:00:00 2001 From: Rafael Richards Date: Sun, 14 Jun 2026 07:28:16 -0400 Subject: [PATCH 5/7] ci(arch): adopt the reusable m/v waterline G1 gate MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add the arch job calling vista-cloud-dev/.github arch-waterline.yml@main, so `m arch check` (the G1 dependency-direction gate) runs in CI on every push/PR — the ADR §3.3 'no exception' enforcement, not just the local make gate. Co-Authored-By: Claude Opus 4.8 (1M context) --- .github/workflows/ci.yml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index d7c28e0..2dd1137 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -16,6 +16,11 @@ on: pull_request: jobs: + # m/v waterline G1 gate (engine-free) — m-stdlib is layer m; the gate + # scans src/*.m for any ^VSL* (v-layer) reference. + arch: + uses: vista-cloud-dev/.github/.github/workflows/arch-waterline.yml@main + m-stdlib: runs-on: ubuntu-latest container: From a7bb57195dafd5b6a674d87ccc872edb7258aa7a Mon Sep 17 00:00:00 2001 From: Rafael Richards Date: Sun, 14 Jun 2026 07:36:22 -0400 Subject: [PATCH 6/7] docs(tracker): org CI waterline gate wired + verified live Record that the reusable arch-waterline workflow is fully activated: m-cli arch + the .github workflow merged to main, the arch caller added to all 8 repos, and the gate proven green on real CI (v-stdlib v-layer + m-cli Go-arm). Notes the two CI gotchas: the go-install @main proxy lag (fixed with git clone --branch) and v-cli's local replace vs the Go arm. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/memory/waterline-g1-gate.md | 14 ++++++++++---- docs/tracking/vsl-implementation-tracker.md | 3 ++- 2 files changed, 12 insertions(+), 5 deletions(-) diff --git a/docs/memory/waterline-g1-gate.md b/docs/memory/waterline-g1-gate.md index 7f6195f..b96fddc 100644 --- a/docs/memory/waterline-g1-gate.md +++ b/docs/memory/waterline-g1-gate.md @@ -41,9 +41,15 @@ m-ydb/m-iris = `m`; v-pkg/v-cli/v-stdlib = `v`. The 5 later ones each got a **root `repo.meta.json`** (the layer is a repo property — deliberately NOT in v-pkg's generated `dist/v-contract.json` or v-cli's aggregate `dist/v-registry.json`; `ResolveLayer` falls through to root). The 3 `m` repos -gate clean on the Go arm; the `v` repos pass trivially. **Residual:** the gate -runs locally / in each `make` only — the reusable org CI workflow (ADR §3.3.2, -`.github/workflows/arch-waterline.yml`) is NOT wired yet, so CI doesn't enforce -it on push. v-stdlib scaffold (T0b.1) is done. See +gate clean on the Go arm; the `v` repos pass trivially. **CI enforcement WIRED (s12):** the reusable +`.github/.github/workflows/arch-waterline.yml` (ADR §3.3.2) runs `m arch check` +in any repo (one-line `arch:` caller). All 8 repos call it; verified green on +real CI (v-stdlib v-layer + m-cli Go-arm). **Two CI gotchas:** the workflow +must build `m` via `git clone --branch ${ref}` + `go build` — NOT +`go install …@main`, because the Go proxy caches the `@main` branch→commit +resolution and lags a fresh m-cli merge ~30 min (would build a stale `m` +without `arch check`). And v-cli's dev `replace => ../v-pkg` would break the +Go-arm's `go list` in CI — harmless only because v-cli is layer v (arch skips +the Go arm). v-stdlib scaffold (T0b.1) is done. See [[msl-vsl-coordination-plan]] and the VSL tracker (`docs/tracking/vsl-implementation-tracker.md` § s12). diff --git a/docs/tracking/vsl-implementation-tracker.md b/docs/tracking/vsl-implementation-tracker.md index c0e6fb1..6d19bd2 100644 --- a/docs/tracking/vsl-implementation-tracker.md +++ b/docs/tracking/vsl-implementation-tracker.md @@ -14,7 +14,7 @@ doc_type: [TRACKING] > One row per task; update the row in the **same increment** as the code. Design > context: front door [`../plans/vsl-overview.md`](../plans/vsl-overview.md). -**Status (2026-06-12 s4): M0a CLOSED — the install/verify/uninstall lifecycle is proven on BOTH engines over the driver path. YDB: `v pkg … --engine ydb` on vehu (T0a.3/T0a.4). IRIS: `v pkg … --engine iris --transport remote` on foia (2026-06-12 s4) — install → #9.7 status=3 + `$$PING^ZZSKEL`→"pong"; verify → installed=1; uninstall → reversible (routine + #9.7/#9.6 gone). The dual-engine exit gate (T0a.5) is GREEN; v-pkg unchanged. **Loose ends B + C CLOSED (2026-06-13 s12):** (B) v-cli registry regenerated with the 3 lifecycle verbs (install/verify/uninstall) — v-cli `chore/registry-regen-lifecycle-verbs`; (C) the m/v waterline **G1 dependency-direction gate is built** — `m arch check` in m-cli (`arch-waterline-g1`), m-cli + m-stdlib self-declare `layer` and gate clean. **T0b.1 DONE (s12):** v-stdlib scaffolded + pushed (public, layer v, smoke 2/2 both engines). **(D) layer tags DONE (s12):** all 8 ecosystem repos now declare `layer` and gate clean via `m arch check` — m-cli/m-stdlib/m-driver-sdk/m-ydb/m-iris = **m** (Go+M arms clean); v-pkg/v-cli/v-stdlib = **v** (pass trivially). Each tag is a root `repo.meta.json` (layer is a repo property, not a per-domain/generated-contract field). **(D-residual) reusable org CI workflow CREATED (s12):** `.github/.github/workflows/arch-waterline.yml` (branch `arch-waterline-workflow`) — go-installs `m` from m-cli (`m-cli-ref` input, default `main`) and runs `m arch check .`; exit 3 fails the job. Validated: `go install …@arch-waterline-g1` + `m-cli arch check .` gates m-stdlib clean. **Activation (3 steps, all user-gated merges/adoption):** (1) merge m-cli `arch-waterline-g1`→main (so `m arch check` is on m-cli main); (2) merge `.github` `arch-waterline-workflow`→main (so callers can `uses: …@main`); (3) add the one-line `arch:` caller job to each repo's `ci.yml`. Resume: finish activation; (E) **T0b.3 — the four drift gates + `seams` block** (next M0b step).** +**Status (2026-06-12 s4): M0a CLOSED — the install/verify/uninstall lifecycle is proven on BOTH engines over the driver path. YDB: `v pkg … --engine ydb` on vehu (T0a.3/T0a.4). IRIS: `v pkg … --engine iris --transport remote` on foia (2026-06-12 s4) — install → #9.7 status=3 + `$$PING^ZZSKEL`→"pong"; verify → installed=1; uninstall → reversible (routine + #9.7/#9.6 gone). The dual-engine exit gate (T0a.5) is GREEN; v-pkg unchanged. **Loose ends B + C CLOSED (2026-06-13 s12):** (B) v-cli registry regenerated with the 3 lifecycle verbs (install/verify/uninstall) — v-cli `chore/registry-regen-lifecycle-verbs`; (C) the m/v waterline **G1 dependency-direction gate is built** — `m arch check` in m-cli (`arch-waterline-g1`), m-cli + m-stdlib self-declare `layer` and gate clean. **T0b.1 DONE (s12):** v-stdlib scaffolded + pushed (public, layer v, smoke 2/2 both engines). **(D) layer tags DONE (s12):** all 8 ecosystem repos now declare `layer` and gate clean via `m arch check` — m-cli/m-stdlib/m-driver-sdk/m-ydb/m-iris = **m** (Go+M arms clean); v-pkg/v-cli/v-stdlib = **v** (pass trivially). Each tag is a root `repo.meta.json` (layer is a repo property, not a per-domain/generated-contract field). **(D-residual) org CI workflow WIRED + VERIFIED LIVE (s12):** `.github/.github/workflows/arch-waterline.yml` runs `m arch check` in any repo. **All 3 activation steps done:** (1) m-cli `arch-waterline-g1`→main merged (PR#5, `m arch check` on m-cli main); (2) `.github` workflow→main merged (PR#1) + a follow-up fix→main (PR#2: build `m` via `git clone --branch`, not `go install …@main` — the module proxy's branch cache lags a fresh merge ~30 min → would build a stale `m` without `arch check`); (3) the one-line `arch:` caller added to all 8 repos' `ci.yml` (v-cli + v-stdlib got their first `ci.yml`). **Verified GREEN on real CI:** v-stdlib PR#1 `arch/arch SUCCESS` (v-layer trivial) + m-cli PR#6 `arch/arch SUCCESS` (m-layer **Go-arm** — `go list` closure clean). m-cli + v-stdlib callers merged to main (gate live there); the other 6 callers ride on their repos' current feature branches and activate as those branches merge. No local-path `replace` in the m Go repos (Go-arm safe in CI). Resume: (E) **T0b.3 — the four drift gates + `seams` block** (next M0b step).** The `VistaEngine` substrate is built on the **m engine-driver contract** (the chosen integration is **subprocess + JSON envelope**, not in-process import — driver-contract §2/§11). Foundational driver work landed this session: m-ydb @@ -78,6 +78,7 @@ _(Append one dated line per increment as tasks move. Newest last.)_ - 2026-06-13 (s12) — **Loose ends B + C closed; G1 waterline gate built.** (B) Regenerated v-cli's stale `dist/v-registry.json` — it carried only 7 pkg verbs; v-pkg's contract gained `install`/`verify`/`uninstall` in the M0a lifecycle work (T0a.3–T0a.5), so the aggregated registry was 3 verbs behind. `make registry` (which also `go mod tidy`'d `m-driver-sdk v0.3.0` into v-cli's graph — v-pkg's `pkgcli` now imports `mdriver.Client`); full `make check` green; v-cli `chore/registry-regen-lifecycle-verbs` pushed. (C) Built the **m/v waterline G1 gate** (`m-v-waterline-adr.md` §3.2 G1, the ADR's "land first" gate): new `internal/arch` + `m arch check` in m-cli (`arch-waterline-g1`). `ResolveLayer` reads `layer` from a committed meta artifact (`dist/repo.meta.json` · `dist/v-contract.json` · root `repo.meta.json`) or `--layer`. For an `m`-layer repo it runs two arms — Go dep closure (`go list -deps -json` → fail on any `vista-cloud-dev/v-*`) + M source scan (`.m` for `^VSL*` refs); a `v`-layer repo passes trivially. Exit 3 + violation list on any m → v edge. TDD, `internal/arch` 85.7% cover, wired into m-cli's `make all`. **Proven:** m-cli self-gates clean; m-stdlib (now tagged `layer: m` here) gates clean on the M arm; v-cli falsely checked as `--layer m` flags v-pkg + v-cli (exit 3). **Resume:** tag the rest (m-driver-sdk/m-ydb/m-iris = m; v-pkg/v-cli = v) + adopt the gate in each CI; then **T0b.1 scaffold v-stdlib (layer v).** - 2026-06-13 (s12) — **T0b.1 DONE — v-stdlib scaffolded + pushed.** Created github.com/vista-cloud-dev/v-stdlib (public, matching the m-stdlib/v-pkg/v-cli siblings; `main` `f5bbb64`). No automated scaffolder exists (the Go m-cli has no `new` verb, the legacy Python `m` is gone, `~/claude/templates/m-project/` is empty), so modeled the skeleton on m-stdlib, adapted to layer v / VSL*: `.m-cli.toml` (modern, pythonic-lower, target-engine any), `Makefile` (`check-fast` = fmt-check+lint+arch engine-free; engine-bound `test`/`coverage` stage STDASSERT from m-stdlib via `--routines`, with `ENGINE`/`DOCKER` vars), `dist/repo.meta.json` with **`layer: v`** (gated by `m arch check` → passes trivially, v→m allowed), `tests/VSLSMOKETST.m` (trivial `^STDASSERT` smoke), README + CLAUDE.md (waterline rules, TDD, dual-engine). Gotcha: `m fmt --rules` only accepts `identity|canonical`; the `pythonic-lower` style comes from `.m-cli.toml` `[fmt]` when no `--rules` is passed (mirror m-stdlib's bare `m fmt`). **Verified green:** fmt-check + lint (0 findings) + arch (layer v, clean); **VSLSMOKETST 2/2 on YDB (m-test-engine) AND 2/2 on IRIS (m-test-iris)** — empty-suite-green exit criterion met dual-engine. No `VSL*` modules yet; VSLCFG (XPAR config, binds STDENV) is first at M1/T1.2. **Next M0b step: T0b.3** (the four drift gates + `seams` block). - 2026-06-13 (s12) — **(D) layer tags landed across all 8 ecosystem repos.** Tagged the 5 remaining repos (m-cli + m-stdlib were tagged when G1 was built; v-stdlib at scaffold): **m** = m-driver-sdk (`coordination`), m-ydb (`m-ydb-driver`), m-iris (`m-iris-driver`); **v** = v-pkg (`refile-v-pkg`), v-cli (`chore/registry-regen-lifecycle-verbs`). Each via a root `repo.meta.json` — the layer is a **repo** property, so it does NOT belong in the per-domain generated `dist/v-contract.json` (v-pkg) or aggregate `dist/v-registry.json` (v-cli); `ResolveLayer` reads root `repo.meta.json` (falling through past those generated artifacts, which carry no `layer` key). All 3 `m` repos gate **clean on the Go arm** (`go list -deps` → no `vista-cloud-dev/v-*` in closure) + M arm; the 2 `v` repos pass G1 trivially. Each committed on its current working branch + pushed. **Residual:** the gate runs locally / in each repo's `make` only — the reusable org CI workflow (ADR §3.3.2, `.github/workflows/arch-waterline.yml`) is not yet wired, so CI doesn't enforce it on push yet. Next M0b: T0b.3. +- 2026-06-14 (s12) — **Org CI workflow wired + verified live; G1 now enforced in CI.** Created the reusable `.github/.github/workflows/arch-waterline.yml` (ADR §3.3.2) and completed all activation: merged m-cli arch→main (PR#5, a merge commit that also landed the stacked T0.1 VistaEngine + SDK-dedupe — both already verified), merged the workflow→`.github` main (PR#1), and added the `arch:` caller to all 8 repos. **Two non-obvious CI findings:** (1) the workflow first used `go install github.com/vista-cloud-dev/m-cli@main`, but the **Go module proxy caches the `@main` branch→commit resolution** and lagged the fresh merge ~30 min (kept resolving the pre-merge `856065b` with no `arch check`) → switched to `git clone --depth 1 --branch ${ref}` + `go build` (exact HEAD immediately; m-cli's deps still via proxy) — PR#2, validated locally vs m-cli main `47c4e49`. (2) v-cli has a dev `replace => ../v-pkg`, which would break the Go-arm's `go list` in CI — but v-cli is layer v, so arch **skips** the Go arm (trivial pass); the m-layer Go repos have no local-path replace, so their Go-arm is CI-safe. **Verified GREEN on GitHub Actions:** v-stdlib `arch/arch SUCCESS` (chain proof: caller→reusable@main→clone+build m→`m arch check`) and m-cli `arch/arch SUCCESS` (real m-layer Go-arm). m-cli + v-stdlib callers merged to main (each also got its first/updated `ci.yml`); the other 6 callers sit on their repos' current feature branches and activate when those merge. - 2026-06-13 (s10) — **File I/O made dual-engine: STDFS portable facade + 5-consumer migration (Variant B "full refactor").** STDFS (was YDB-only by design) now has public `$$openRead/$$openWrite/$$openAppend` + private `readLn`/`closeDelete`/`sizeIris`, engine-branched (`readonly→"R"`, `newversion:stream:nowrap→"WNS"`, `append→"WA"`, `close:(delete)→close:"D"`, `$ZEOF`↔``-catch), with off-engine syntax `xecute`-hidden so each compiler parses only its own arm. **STDFSTST 50/50 BOTH engines** (was 0/0 IRIS). STDOS.env got a `$system.Util.GetEnviron` IRIS arm (was `$ztrnlnm`). STDJSON/STDCSV/STDSEED/STDLOG routed through STDFS; STDSEEDTST/STDCSVTST fixtures ported. **YDB full 2098/0 — no regression**; fmt clean, lint errors=0, KIDS drift-gate ✓, dist regenerated. **KEY OUTCOME:** the file-I/O refactor makes the file layer portable but does **NOT** turn the consumer SUITES green on IRIS — they have separate non-file blockers (discoveries P2 2026-06-13): **STDJSON byte-mode parser** (`$$parse` crashes on IRIS, no file involved), **STDCSV `@callback@(args)` indirection** (crashes on IRIS even ASCII), and **wide-char descriptions** (STDCSV/STDSEED/STDLOG/STDXML → m-iris GetOut/session-capture lane). Only **STDFS** goes green on IRIS this session. Coverage note: STDFS 69.3% / STDOS 83.7% per-file (dual-engine IRIS arms unreachable on the YDB coverage tier — same documented situation as STDHARN 76.7%). **To actually green the IRIS consumer suites still needs: byte-mode portability + a portable `parseFile` callback idiom + the wide-char capture path** — all separate from file I/O. Engines restored (vehu up, foia stopped). ## Per-milestone notes From 2963801da692d4f83367c3f42278591609f10195 Mon Sep 17 00:00:00 2001 From: Rafael Richards Date: Sun, 14 Jun 2026 08:11:33 -0400 Subject: [PATCH 7/7] =?UTF-8?q?docs(plan):=20MSL=E2=9F=B7VSL=20orchestrati?= =?UTF-8?q?on=20&=20kickoff=20runbook?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The durable runbook for running the multi-repo MSL⟷VSL effort (analog of the driver coordination-model): the stabilize→standardize→implement phasing, the one-session↔one-repo↔one-branch model, the seam contract as the sole coupling (serialize-the-seam/parallelize-consumers), the increment-protocol handoff + seam-tag boundaries, the new-session recipe and session-boundary rules, and the standardized/enforced "one way" target (uniform repo.meta.json + reusable CI + meta-gate). Point new sessions here. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/plans/msl-vsl-orchestration-kickoff.md | 170 ++++++++++++++++++++ 1 file changed, 170 insertions(+) create mode 100644 docs/plans/msl-vsl-orchestration-kickoff.md diff --git a/docs/plans/msl-vsl-orchestration-kickoff.md b/docs/plans/msl-vsl-orchestration-kickoff.md new file mode 100644 index 0000000..861f415 --- /dev/null +++ b/docs/plans/msl-vsl-orchestration-kickoff.md @@ -0,0 +1,170 @@ +--- +title: MSL ⟷ VSL Orchestration & Kickoff Runbook +status: active +created: 2026-06-14 +plan: docs/plans/vsl-implementation-plan.md +tracker: docs/tracking/vsl-implementation-tracker.md +doc_type: [PLANNING] +--- + +# MSL ⟷ VSL Orchestration & Kickoff Runbook + +> The durable "how we run the multi-repo MSL⟷VSL effort" doc — the analog of +> the driver effort's `coordination-model.md`. Point every new session at this +> file. It answers: which repo am I in, how do repos hand off, where do clean +> session boundaries fall, and how the gatekeeping/CI standard is kept +> unambiguous and enforced across all repos. +> +> Companion docs: the milestone plan +> [`vsl-implementation-plan.md`](vsl-implementation-plan.md), the live +> [`vsl-implementation-tracker.md`](../tracking/vsl-implementation-tracker.md), +> the waterline rule `docs/background/m-v-waterline-adr.md` (org `docs` repo), +> and per-repo memory under each repo's `docs/memory/`. + +--- + +## 0. The one-paragraph model + +The ecosystem is layered by the **m/v waterline**: engine-neutral `m-*` below, +VistA-specific `v-*` above, dependency flowing **one way, `v → m`**. The MSL⟷VSL +build follows that spine — **m-stdlib (`STD*`) → v-stdlib (`VSL*`) → consumer +(`VPNG`/`VWEB`)** — and the *only* coupling between layers is a single tagged +artifact, the **seam contract** (m-stdlib's `seams` block, pinned by v-stdlib). +So the discipline is: **serialize the seam, parallelize the consumers**, one +**session ↔ one repo ↔ one branch**, and every stop is a clean, pushed, +documented increment. + +--- + +## 1. Phasing — stabilize → standardize → implement + +Do **not** start feature work on a stale baseline. The phases are ordered. + +### Phase A — Stabilize (get `main` canonical everywhere) +The prerequisite. Most repos' real work currently lives on long-lived feature +branches; `main` is behind. Until `main` is the source of truth, the gates +(`@main` workflow refs, `go install …@`, CI) enforce against code that +isn't really there. Per repo, **leaf-first** (`m` before `v`): +1. Land the active feature branch → `main` via PR (CI green) — or consciously abandon it. +2. Clear dependabot PRs. +3. Prune merged/dead local branches (one `main` + at most one active work branch). +4. **Exit gate:** every repo's `main` builds, gates green, and its `layer` tag + + `arch:` CI caller are *on main* (so the gate actually enforces). + +**Landing order & dependencies:** +| # | Repo | Branch | Note | +|---|------|--------|------| +| 1 | m-driver-sdk | `coordination` | leaf (the seam); land + tag a release | +| 2 | m-ydb | `m-ydb-driver` | pins SDK *tag* → independent of SDK main | +| 3 | m-iris | `m-iris-driver` | pins SDK *tag* → independent of SDK main | +| 4 | m-cli | (already on main) | prune leftover local branches only | +| 5 | v-pkg | `refile-v-pkg` | the m-kids→v-pkg refile; land **then tag** (e.g. v0.1.0) | +| 6 | v-cli | `chore/registry-…` | **blocked**: drop dev `replace => ../v-pkg`, pin v-pkg's new tag, then land (else go-ci is red in CI) | +| 7 | m-stdlib | `arch-waterline-g1-mstdlib` | waterline + this runbook | +| 8 | v-stdlib | (caller already on main) | prune local | + +### Phase B — Standardize the substrate (one unambiguous, enforced way) +Make the org discipline `source-tag → generate → registry → red-gate` concrete +and self-enforcing: +1. **One meta artifact, one location.** Standardize on **root `repo.meta.json`** + (language-agnostic, not buried in generated `dist/`) with a tiny schema + (`id, layer, language, verification_commands, consumes, exposes`). `m arch + check` validates its presence/shape. (Migrate m-stdlib/v-pkg off + `dist/…` once tooling reads root first.) +2. **Finish the gate suite** in the same `m arch check` + same reusable + workflow: **G2** (no VistA symbols below the waterline), **G3** + (transport-monopoly — only m-driver-sdk runs a driver/builds the envelope), + **G4** (seam-pin — tagged SDK, no `replace`). G1 (dependency-direction) is + done. +3. **The meta-gate (keystone).** A scheduled org job (ADR §3.3.4) that walks + every repo and asserts each declares a valid `layer`, calls + `arch-waterline.yml`, and is in an ecosystem registry. **This is what makes + the standard enforced rather than conventional** — drift goes red + automatically. +4. **One reusable CI per language.** `go-ci.yml` + `arch-waterline.yml` exist; + add **`m-ci.yml`** (fmt/lint/test/coverage + arch, modeled on m-stdlib's CI) + so every M repo gets an identical pipeline from one line. +5. **Pin the seam deterministically.** Tag an m-cli release; set the workflow's + `m-cli-ref` to the tag (not floating `main`) so CI stops drifting under + m-cli's main. + +### Phase C — Implement MSL⟷VSL (T0b.3 onward) +Only on a clean, standardized substrate. Follow the tracker's `Repo` column in +dependency order: T0b.3 (four drift gates + `seams` block) → T0b.4 (freeze seam +v1, tag MSL, v-stdlib pins) → T1.1 STDENV seam → T1.2 VSLCFG → T1.3 VSL KIDS +base → T1.4/T1.5 VPNG consumer + determinism ledger → M2–M6 (parallel-safe once +M1 is green). + +--- + +## 2. Which repo am I in? + +The repo that **owns the current tracker task** (the tracker's `Repo` column). +The dependency spine is **m-stdlib → v-stdlib → consumer**, always lower-first. + +- **m-stdlib is the anchor** for the MSL side: it holds the canonical tracker, + the milestone plan, and the **seam contract** everything pins. Cross-cutting + planning/tracking edits happen here. +- A task that names `v-stdlib` / a consumer / a driver / m-cli is done in *that* + repo, in its own session. + +## 3. Orchestration & handoffs + +- **One session ↔ one repo ↔ one branch.** Never edit two repos in one session. + `cd` into the sub-repo before starting. +- **The coupling is exactly one artifact: the seam contract.** m-stdlib emits a + `seams` block in its manifest and **tags** a seam version; v-stdlib **pins** + that tag and a drift gate asserts it. Serialize the seam, parallelize the + consumers (same shape as the driver effort's "serialize the SDK"). +- **Cross-repo features go sequentially, leaf repo first.** Lower layer + implemented + verified + (for a seam change) tagged, *then* the upper layer + consumes the tag. +- **Frozen-seam window:** when the upper layer needs a new shape, it records + `needs seam: X` in its tracker and does **not** bump the seam itself; the + m-stdlib (anchor) session batches it into the next tagged seam. + +### Clean git handoffs +The **Increment Protocol is the handoff mechanism**. Every increment ends at a +*verified* state with: memory updated (`/docs/memory/`), tracker row + +Status/Resume line updated, and a commit pushed to the working branch. That +leaves every repo at a clean, pushed, documented point — which *is* the handoff. +Add a **tag at each seam boundary** (m-stdlib tags `seams-vN`; the v-stdlib +session pins it). Never switch repos mid-change. + +The cross-session state lives in two places, never in your head: +1. the tracker's **Status / Resume line** (cross-repo "where we are / what's next"), and +2. each repo's **`docs/memory/`** (per-repo non-obvious facts). + +## 4. When to start a new session + +- **Repo boundary** — the next task is in a different repo (the cleanest cut). +- **Seam freeze** — lower repo tagged → start a fresh upper-repo session to consume it. +- **~50% context** — *finish the current increment first* (verified + pushed + + Resume line updated), then start fresh. Never hand off mid-change. +- **Per increment** — each verified increment is a valid boundary. + +### New-session recipe +1. `cd` into the repo that owns the next task. +2. Read its `CLAUDE.md` + `docs/memory/MEMORY.md` + the tracker's Status/Resume line. +3. Confirm the branch (`git branch --show-current`); branch off `main` if landing a new increment. +4. Run the repo's gate to confirm a clean baseline (`make check` / `make check-fast` / `m arch check .`). +5. Begin — TDD-first, one increment, then run the Increment Protocol. + +## 5. The standardized, enforced "one way" (target end-state) + +Every repo, with no exception, has: +- a root **`repo.meta.json`** declaring `layer` (+ `verification_commands`, `consumes`, `exposes`); +- a **`ci.yml`** that calls the **reusable workflows** — `arch-waterline.yml` + (universal G1–G4) + the language CI (`go-ci.yml` / `m-ci.yml`); +- the **Increment Protocol** as its commit/push/memory/tracker rhythm; +- and is covered by the **meta-gate** (declares a layer, calls the workflow, is + in the ecosystem registry) — the backstop that turns the standard from a + convention into a gate. + +Compliance is a **build artifact, not a review habit**: a new repo earns trust +by adding its `tag → registry → gate` triple, not by being watched. + +--- + +*Keep this runbook in lockstep with `vsl-implementation-plan.md` and the +tracker. Update it when the orchestration model itself changes.*