From 2917acc3d01d6e8901416570dc8fac7f1b93fa3f Mon Sep 17 00:00:00 2001 From: Rafael Richards Date: Tue, 16 Jun 2026 17:36:01 -0400 Subject: [PATCH] =?UTF-8?q?prompts:=20add=20M4=20(VSLSEC=20+=20VSLLOG=20?= =?UTF-8?q?=E2=80=94=20security/audit=20seams)=20kickoff=20for=20the=20nex?= =?UTF-8?q?t=20session?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Next-steps kickoff after M3: bind the identity/crypto seam to Kernel (^XUSHSH, DUZ/#200, ^XUSEC, OPTION #19) as VSLSEC, and the observability sink to a FileMan audit file as VSLLOG (reusing VSLFS for the DBS writes; v->v composition). Flags the design questions (the security seam splits at the waterline — VSLSEC authz is VistA-only; VSLLOG reuses VSLFS; existing-entry probe fixtures) and the notional-@icr rule. Leaf-first, dual-engine exit. Models m3-vslfs-kickoff.md. Co-Authored-By: Claude Opus 4.8 (1M context) --- prompts/m4-vslsec-vsllog-kickoff.md | 219 ++++++++++++++++++++++++++++ 1 file changed, 219 insertions(+) create mode 100644 prompts/m4-vslsec-vsllog-kickoff.md diff --git a/prompts/m4-vslsec-vsllog-kickoff.md b/prompts/m4-vslsec-vsllog-kickoff.md new file mode 100644 index 0000000..1dded5c --- /dev/null +++ b/prompts/m4-vslsec-vsllog-kickoff.md @@ -0,0 +1,219 @@ +--- +title: "VSL/MSL M4 — VSLSEC + VSLLOG: the security (S5) and audit (S3) seams" +status: ready +created: 2026-06-16 +doc_type: [PROMPT] +for: a fresh implementation session (cross-repo, leaf-first; MSL seam leaf(s) → VSLSEC + VSLLOG in v-stdlib) +plan: docs/vsl-msl/vsl-implementation-plan.md +tracker: docs/vsl-msl/vsl-implementation-tracker.md +--- + +# VSL/MSL M4 — `VSLSEC` (security, S5) + `VSLLOG` (audit, S3) + +The next milestone in the horizontal seam build-out (§12.2): **security + +audit**. `VSLSEC` binds the identity/crypto seam to Kernel +(`^XUSHSH`/`$$ENCRYP^XUSHSH`, `DUZ`/#200, `^XUSEC`, OPTION #19 context); +`VSLLOG` binds the observability sink to a **FileMan audit file** (and, +optionally, a MailMan alert). Risk **R3 — Kernel auth impedance** (VSLSEC) and +the audit-sink durability problem the §6.2 log-egress example motivates (VSLLOG). + +M4 is **parallel-safe** with the owed M2 tail and the deferred v-pkg DD-install +track; it does not wait on them. + +## Where we are (snapshot, 2026-06-16) + +- **M1 COMPLETE** (`STDENV→VSLCFG→VPNG`) · **M2 functionally complete** (`STDNET` + + `VSLIO`, socket seam) · **M3 COMPLETE + MERGED** (`STDKV` + `VSLFS`, the + storage seam S1 — dual-engine 7/7, DIERR→`,U-VSL-FS-DIERR,`). +- **MSL is at `v0.9.0`** (STDENV + STDNET + STDKV seams); v-stdlib `main` pins + `msl_ref: v0.9.0` and has **VSLCFG + VSLIO + VSLFS** (all merged). +- **The seam machinery is well-worn**: `@seam`→snapshot + bump-forcer; v-stdlib + `check-msl-pin` fetches MSL's contract at the pinned tag; the four drift gates. +- **`check-icr` now accepts a notional `@icr DBS`/`notional` marker** (the DBIA + registry is a human-curated FORUM list, not enforced — see the HARD RULE in + shared memory `notional-dbia-not-a-blocker.md` + plan §5.4). Kernel ICRs + (`^XUSHSH`, `^XUSEC`, `XUS…`) ARE usually numbered — but **ground every one via + `corpus-researcher`** and fall back to the notional marker if the corpus has no + number. Never re-open a missing number as a blocker. +- **`VSLFS` is the reusable FileMan-DBS record writer** — `$$set`/`$$get`/ + `$$exists`/`$$kill` over `(file,iens,field)` with the DIERR→`$ECODE` contract. +- Both engines up: `vehu` (YDB), `foia-t12` (IRIS), driver stack only. + +## The open design questions to resolve FIRST (then don't re-litigate) + +1. **The security seam splits AT the waterline — most of `VSLSEC` has NO MSL + counterpart.** Portable token/credential crypto (HMAC, constant-time compare, + digests) already lives in `STDCRYPTO`. The **authorization decision** — *does + `DUZ` hold this `^XUSEC` key / this OPTION #19 context?*, and the principal→ + `DUZ`/#200 binding — is **inherently VistA** (it cannot run on a bare engine), + so it has **no portable MSL seam**: `VSLSEC` is a *VistA-only* adapter for + that part (like `VSLIO`'s server side staying out of the seam). **Decide + early:** does `VSLSEC` ALSO bind `^XUSHSH`/`$$ENCRYP^XUSHSH` as a back end for + an `STDCRYPTO` *hash/compare* seam (→ tag a minimal `@seam` on STDCRYPTO), + **or** is `VSLSEC` purely the authz layer (`$$hasKey`/`$$inContext`/`$$duz`) + with NO MSL seam at all? **Recommendation:** keep the seam **minimal** — bind + only what a real consumer needs. The §12.2 VSLSEC row + architecture §3.4 are + the ground truth; read them before naming entry points. Portable crypto stays + in `STD*`; the VistA authorization decision lives in `VSLSEC` (architecture + §3.4, verbatim). +2. **Where is the `STDLOG` sink seam, and does `VSLLOG` reuse `VSLFS`?** `STDLOG` + is the portable structured logger; the **sink** is the seam `VSLLOG` backs + (a FileMan audit file). **Decide:** (a) does `STDLOG` already expose a + pluggable sink to tag `@seam`, or does the seam need a small new entry point; + and (b) **`VSLLOG` should REUSE `VSLFS`** for the FileMan record writes + (v→v composition is allowed — both are layer `v`; only `v→m` is one-way), not + re-bind `UPDATE^DIE` itself — `VSLLOG` adds only the log-record→FileMan-fields + mapping (+ optional MailMan alert). **Recommendation:** reuse `VSLFS`; do NOT + duplicate the DBS binding (waterline §9 no-dup applies within `v` too). +3. **How are the test fixtures provided (live, safe)?** Mirror M3's resolution: + use **EXISTING low-risk entries via the probe pattern**, deferring any + data-DD install to the v-pkg track. + - **VSLSEC:** an existing `DUZ`/#200 user (e.g. `DUZ=1`), an existing + `^XUSEC(KEY,DUZ)` key, and an existing OPTION #19 context the test user + holds — probe for one that's present (read-only), assert the authz decision; + do NOT grant/revoke real keys. For `^XUSHSH` hashing, hash a throwaway + string and assert determinism (no persisted state). + - **VSLLOG:** an **existing low-risk FileMan file** for the audit records + (the #8989.51-style throwaway-record pattern VSLFS used), or a dedicated + audit file via the deferred v-pkg DD-install enabler. **Recommendation:** + existing file first (do NOT block VSLLOG-green on the DD installer). + +## Decisions already made (do not re-litigate) + +1. **Leaf-first, cross-repo, one writer per repo** (as M1–M3): any **new/changed + MSL seam** is authored + **tagged** (`v0.10.0`) in m-stdlib FIRST; only then + does v-stdlib re-pin `msl_ref` → `v0.10.0` and bind it. If M4 needs NO MSL + seam change (VSLSEC authz is VistA-only; STDLOG's sink already exists), the + MSL leg may be a no-op and no new tag is cut — decide per Q1/Q2. Never edit + two repos in one session. Cutting the MSL tag is an explicit user action. +2. **`VSLSEC` + `VSLLOG` live in v-stdlib** (beside VSLCFG/VSLIO/VSLFS), layer + `v`. They contain ONLY the VistA binding; portable logic stays in `STD*` + (called up). `VSLLOG` reuses `VSLFS` for FileMan writes (no DBS re-bind). +3. **Every L4 call is `@icr`-tagged + grounded via `corpus-researcher`.** Kernel + (`^XUSHSH`, `^XUSEC`, `XUS…` context, `$$ENCRYP^XUSHSH`), MailMan, and the + FileMan DBS (reused via VSLFS). Do NOT trust the plan's prose — verify each ICR + number + `@source` anchor; use the **notional `@icr DBS`/`notional` marker** + for any documented-Supported call the corpus has no number for (the gate + accepts it; see `notional-dbia-not-a-blocker.md`). +4. **Error contract:** loud failures map to clean `,U-VSL-SEC-…,` / `,U-VSL-LOG-…,` + `$ECODE` (with `$$lastError^VSLSEC()` / `$$lastError^VSLLOG()` carrying detail) + — the same loud-failure posture as VSLFS's DIERR mapping and VSLIO/STDNET's + TLS guards. An authz DENY is a normal `0`/false return, NOT an error; a + malformed call or a FileMan/Kernel fault is the loud `$ECODE`. +5. **Dual-engine is the exit criterion** (single-engine first). Kernel auth + + FileMan are VistA-portable — verify on both `vehu` and `foia-t12`; add a + `$ZVERSION` arm only if a primitive genuinely diverges (VSLFS needed none). + +## Resume prompt + +``` +Start VSL/MSL M4 — VSLSEC (security seam, S5) + VSLLOG (audit seam, S3). Bind the +identity/crypto seam to Kernel (^XUSHSH / $$ENCRYP^XUSHSH, DUZ/#200, ^XUSEC, +OPTION #19 context) as VSLSEC, and the observability sink to a FileMan audit file +(+ optional MailMan alert) as VSLLOG — VSLLOG REUSING VSLFS for the FileMan record +writes (v->v composition; no DBS re-bind). Prove GREEN on BOTH engines (vehu YDB, +foia-t12 IRIS) over the driver stack. Single-engine first; dual-engine is the exit. + +RESOLVE THE DESIGN QUESTIONS FIRST (see the kickoff): (Q1) the security seam splits +at the waterline — VSLSEC's authz (hasKey/inContext/DUZ bind) is VistA-only with NO +MSL seam; portable crypto stays in STDCRYPTO; decide whether to also bind ^XUSHSH as +an STDCRYPTO hash/compare back end. (Q2) STDLOG sink seam home + VSLLOG reuses VSLFS. +(Q3) test fixtures = EXISTING low-risk entries via the probe pattern (an existing +DUZ/#200 user + ^XUSEC key + context option for VSLSEC; an existing low-risk file +for VSLLOG audit records), deferring any data-DD install to a v-pkg track. + +CROSS-REPO, LEAF-FIRST, ONE WRITER PER REPO: if a new/changed MSL seam is needed, +author + TAG it in m-stdlib FIRST (new tag v0.10.0), THEN bind it in v-stdlib +(re-pin msl_ref v0.9.0 -> v0.10.0). If M4 needs no MSL seam change, no new tag. +Never edit two repos in one session. + +START BY READING (in order): + 1. docs/vsl-msl/msl-vsl-architecture.md §3.4 (Kernel identity/authz) + §3.6/§3 + (MailMan/audit) + docs/vsl-msl/msl-vsl-coordination-implementation-plan.md + §5.1 (S5 + S3 rows), §5.4 (the @icr gate — now notional-aware), §5.5 + (@source), §12.2 (the VSLSEC + VSLLOG acceptance rows). + 2. v-stdlib/src/VSLFS.m + VSLIO.m + VSLCFG.m + their tests + docs/memory/ + {m3-vslfs,m2-vslio,t1.2-vslcfg}.md — the adapter pattern, the @icr/@source/ + pin gate wiring, the live-driver recipe, the DIERR/loud-error posture, and + how VSLFS exposes set/get/exists/kill (VSLLOG reuses it). + 3. m-stdlib/src/STDCRYPTO.m + STDLOG.m (+ docs/modules/) — confirm what portable + surface already exists (crypto hash/compare; the log sink), and whether a new + @seam tag is needed; m-stdlib/docs/memory/m3-stdkv-storage-seam.md (the + leaf-first + @seam + tag-and-repin rhythm to copy). + 4. docs/memory/notional-dbia-not-a-blocker.md (shared) — the @icr notional rule + + how gen-icr.py's NOTIONAL_MARKERS works; v-stdlib/tools/gen-icr.py. + 5. ~/vista-cloud-dev/CLAUDE.md + v-stdlib/CLAUDE.md — the m/v waterline, the + ENGINE-ACCESS HARD RULE (driver stack only), and the Increment Protocol. + +THE WORK (TDD red-first, hard rule; like M3): + LANE A (m-stdlib, only IF a seam change is needed): tag/extend the @seam + (STDCRYPTO hash/compare and/or STDLOG sink), tests green both engines, the 4 + drift gates + bump-forcer green, increment + (user) tag MSL v0.10.0. + LANE B (v-stdlib, after any v0.10.0): VSLSEC + VSLLOG. Re-pin if Lane A ran. + tests/VSLSECTST.m + VSLLOGTST.m FIRST (red, safe defaults): VSLSEC hash + determinism + hasKey/inContext over existing safe entries + a loud + ,U-VSL-SEC-..., on a Kernel fault; VSLLOG writes an audit record (via VSLFS), + reads it back, and maps a failure to ,U-VSL-LOG-.... src/VSLSEC.m + VSLLOG.m: + the VistA binding ONLY, each L4 call @icr/@source-tagged (grounded via + corpus-researcher; notional marker where the corpus has no number). + +ENGINE RECIPES (from m3/t1.2 memory): + m test --engine ydb --docker vehu --chset m --routines src --routines /src tests/VSLSECTST.m + m test --engine iris --docker foia-t12 --namespace VISTA --routines src --routines /src tests/VSLSECTST.m + m vista exec --engine ydb|iris --transport docker '' (+ M_YDB_*/M_IRIS_* env for ad-hoc DD probes) + (Driver stack ONLY — never raw docker exec / iris session.) + +VERIFICATION (M4 "done"): + • VSLSECTST + VSLLOGTST green on BOTH engines: VSLSEC hash/compare + authz + decision over existing safe entries, loud ,U-VSL-SEC-...,; VSLLOG audit + write+read via VSLFS, loud ,U-VSL-LOG-.... + • Boundaries green: check-msl-pin (@v0.10.0 if Lane A ran, else @v0.9.0) / + check-icr (every Kernel/FileMan/MailMan call Supported-or-notional + declared, + no direct VistA-global access) / check-citations. make check-fast clean. + • No regression: m-stdlib + v-stdlib's VSLCFG/VSLIO/VSLFS + vpng unchanged. + +DO NOT (scope guards): + • Do NOT edit two repos in one session; tag any MSL leaf first, then the VSL. + • Do NOT re-bind FileMan DBS in VSLLOG — reuse VSLFS (no duplication). + • Do NOT reimplement portable crypto in VSLSEC — STDCRYPTO owns it; VSLSEC is + the VistA authz decision + the Kernel hash back end only. + • Do NOT grant/revoke real ^XUSEC keys or alter real users — probe existing + safe entries read-only; do NOT block green on a data-DD install (deferred). + • Do NOT re-open a missing ICR number as a blocker (notional marker is fine). + • Merges + any MSL re-tag stay user actions. + +INCREMENT PROTOCOL (per repo, when green): + Lane A (if run): memory + module-tracker + docs/modules/.md; commit/push; + (user) tag v0.10.0. + Lane B: memory v-stdlib/docs/memory/m4-vslsec-vsllog.md; flip the M4 row in + docs/vsl-msl/vsl-implementation-tracker.md (docs repo — SEPARATE commit); + commit/push the v-stdlib branch (e.g. m4-vslsec-vsllog). Co-Authored-By trailer. + +GOAL: the security + audit seams proven — VSLSEC binds identity/crypto to Kernel +(hash + the VistA authz decision) and VSLLOG durably writes audit records through +VSLFS to FileMan, both loud-on-failure and dual-engine green, all determinism +boundaries green. Then M5 (VSLBLD/VSLTASK — KIDS build + listener, §12.2) and the +§6.2 worked examples (S3 log egress, FHIR façade). +``` + +## Notes for the operator (not part of the resume prompt) + +- **VSLSEC is mostly NOT a seam adapter.** Unlike VSLCFG/VSLIO/VSLFS (each backs a + portable MSL seam), the *authorization decision* has no bare-engine analog, so + VSLSEC is largely a pure-VistA module. That's expected per the architecture + (§3.4): "Portable token crypto stays in STD*; the VistA authorization decision + lives in VSL." Only the `^XUSHSH` hash back end (if pursued) mirrors a portable + STDCRYPTO seam. Don't force a seam where the capability is inherently VistA. +- **VSLLOG is the first v→v composition.** It reuses VSLFS rather than re-binding + FileMan DBS — the in-`v` analog of the waterline no-duplication rule. Confirm + `m arch check` is happy with a `VSL*`→`VSL*` call (it should be — the gate + forbids `v→` only below the line, and `m→v`; within `v` is fine). +- **Ground every Kernel ICR.** `^XUSHSH`/`$$ENCRYP^XUSHSH`, `^XUSEC`, the `XUS` + context APIs, and MailMan are documented in the Kernel guides — but the corpus + has been wrong before (XPAR at T1.2, CALL^%ZISTCP at M2). Verify each via + `corpus-researcher`; use the notional marker where no number exists. +- **The owed/parallel tracks** (non-blocking): the v-pkg FileMan-DD-install + enabler (would give VSLLOG a dedicated audit file + re-test VSLFS), STDNET's + IRIS leg, and tier-3 TLS. None gate M4. +- **If `foia-t12` is down**, recreate per the IRIS recipe in the t1.2/t1.3 + memories; confirm `docker ps` healthy before the IRIS run.