fix(app-facts): open the catalog through an escaped read-only URI

CHANGELOG.md

@@ -19,6 +19,7 @@ Sections dated before 2026-09-19 predate the cycle and stay as they are. Named m
 
 ## Unreleased
 
+- fix(app-facts): **the catalog is opened through an escaped read-only URI, so a model folder with `#` or `?` in its name no longer breaks step 2 or leaves a stray file beside the project.** Step 2 built `"file:%s?mode=ro" % DB` from the raw path; `#` and `?` end the path in a URI, so `mode=ro` was dropped and SQLite created an empty database at the truncated path (a zero-byte `a ` beside `a #2/`) and opened that. On master that ends in a Python traceback (`no such table: modules_data`, exit 2) after the shell's catalog check had passed. The URI now comes from new `mxtk_sqlite_ro_uri` in `_common.sh`, the `pathname2url` escaping `mxtk_model_version` already did, which now calls the same helper. Step 2 also refuses with a FAULT line when the catalog it opened has 0 tables, rather than writing facts from it, and with a `_common.sh` that predates the helper (or none) app-facts builds the same `pathname2url` URI inline, as its `require_py`/`find_mpr` fallbacks already do, passing the path through `native_path` when that exists. Fixture `tests/wave2/test-app-facts-db-uri.sh` (10 cases: folders `a #2`, `b?c` and a plain control, the URI shape, the 0-table refusal, and `a #2` beside an older `_common.sh` without the helper); 8 fail on master, and the older-`_common.sh` case fails on the previous revision of this fix, which refused. Windows (MSYS path conversion of the env var) is unchanged and unverified. Field evidence: none yet. — r-eng-backlog item 3, MendixMau
 - process(build): **Stage 5 drafts the ready set in parallel and applies serially.** The runbook dispatch row said "sequential within a module", which serialised drafting even for independent scripts; it now points to `iterative-build-loop.md` → Gate cost, the single statement of the rule. The unit is the build-plan row: every `BUILD` row whose "Depends on" rows are all applied, minus overlapping writers (two rows that replace, alter or drop+create the same document never share a ready set, and no row is drafted while it overlaps a queued unapplied one; `brd-to-build-plan.md` has Produces name every document a row writes), runs at once, its scripts in order, one `mdl-agent` per script. Applies stay one at a time through `bin/exec.sh`, and the ready set is recomputed after each. A queued draft made before a sibling apply landed is re-checked with `mxcli diff --format struct` (preflight STOP rule 23); any removal line (checked against `describe` per BUG-146) or STOP rule 21 target means re-draft, never patch, because a stale restatement of a shared document is exactly rule 21's silent seed-call loss and passes `check --references`. Report `ready set N, drafted N, applied k`; the `mdl-agent` template says a drafter never applies and never depends on an unapplied draft. Field evidence: none yet. — MendixMau
 - fix(platform-link): **CLI commits now show their changed documents in Studio Pro History.** Studio Pro's History → Model changes pane reads a `ModelChanges` array from the commit's `refs/notes/mx_metadata` note. Trap 6c's hand-written template set it to `[]`, so every mxcli/agent commit showed "Model changes 0" (field project: 270 of 270 notes empty). New `project-bin/mx-metadata-note.py` (stdlib only) computes the array from the commit's changed `.mxunit` files, in Studio Pro's entry shape: Status, UnitID, UnitType, UnitName and Module (walked up the `.mpr` Unit tree). It has `changes` / `write` / `backfill` / `sync <remote>` subcommands. `install-project-hooks.sh` now also installs post-commit and post-rewrite hooks that write the note and never block, and `--check` covers them, so `sync-project.sh` rolls them out to wired projects. Notes are published with `mx-metadata-note.py sync <remote>` after the branch push. Push config is never touched. With mxcli v0.26+ in the project root the hooks call `mxcli git note --write` instead (mendixlabs/mxcli#1337); the Python script is the fallback for older pins, and on 160 field commits both wrote the same 3,594 entries. Trap 6c rewritten. Measured against Studio Pro's own notes, 51 commits in 5 apps: 3387/3389 entries exact on all five fields. Field run on a 357-commit Mendix 11.15.0 app: 158 notes backfilled and pushed, and Studio Pro History lists the documents per revision. Review fixes: an earlier revision added `HEAD` + the notes ref to `remote.<r>.push`. It was dropped because any push refspec replaces `push.default`. A branch tracking a differently named upstream got a new same-named branch on Team Server where `simple` refuses, a missing local notes ref failed the whole push, and nobody knows whether Studio Pro's own push reads that config. The installer now only fetches the remote's notes (non-forced). It removes that exact `HEAD` + notes pair if present, and leaves and reports any other entry. `sync` handles a remote with no notes ref (it used to exit 1) and retries a rejected push once after re-merging. A note that already lists changes (Studio Pro's) is never overwritten by `write`/`backfill` without `--force`, and `sync` keeps a colleague's non-empty note over ours. The mxcli probe greps `git note --help` for `--write`. Hooks and docs call the script through `resolve_py`. Fixture `tests/wave2/test-mx-metadata-note.sh` (40 cases, over real captured template units; single- and two-tree layouts, amend, backfill and `--force`, push exit codes identical to a no-hooks clone, leftover-refspec cleanup, sync to an empty remote and its retry, notes fetch at install, a diverged notes merge; green under `init.defaultBranch` master and main). — field project (Mendix 11.15 app), MendixMau
 - learn(fixture-seeding): **explore the data structure first, choose rows by use case, scan actions for resets before any run.** Two seeding runs on public template apps: seeding raised journey passes 33 -> 58 and 20 -> 51 of the same sets (FAIL 93 -> 68, 163 -> 132; INVALID unchanged), and a "Reset all demodata" journey wiped accounts so 104 of 127 journeys reported `The username or password you entered is incorrect`, identical on empty and seeded databases. Skill gains three questions a seed must answer, a use-case checklist, a destructive-action scan, a generic traps table with symptoms, measured expectations and a denominator checklist; routing trigger now fires on seed/test/demo data and empty pages. Independent review fixes: object ids follow the Mendix bigint pattern with a business-key guard (no uuids), associations are seeded where the page's path stores them, four new traps (enum names, inheritance chain, calculated attributes, view/external entities), and the port-offset and container-label traps moved to `harness-architecture.md`. — MendixMau

project-bin/_common.sh

@@ -361,6 +361,22 @@ find_mxcli_cache() {
   fi
 }
 
+# ---------------------------------------------------------------------------
+# mxtk_sqlite_ro_uri <path> — print a read-only SQLite URI for <path>: absolute, URI-escaped,
+# ending in ?mode=ro. Hand it to Python as sqlite3.connect(uri, uri=True).
+# Escaping is the point: a plain "file:%s?mode=ro" cuts the path at a '#' or '?' in any folder
+# name ("a #2", "b?c"), drops mode=ro with it, and SQLite then CREATES an empty file at the
+# truncated path (a zero-byte "a " beside the model folder) and opens that instead.
+# Uses $PY when set, else resolve_py. Returns 1 when there is no Python. The caller decides
+# whether to pass the path through native_path first; this does no platform conversion.
+# ---------------------------------------------------------------------------
+mxtk_sqlite_ro_uri() {
+  local py="${PY:-$(resolve_py 2>/dev/null || true)}"
+  [ -n "$py" ] || return 1
+  "$py" -c "import os,sys,urllib.request as u
+print('file:'+u.pathname2url(os.path.abspath(sys.argv[1]))+'?mode=ro')" "$1" | tr -d '\r'
+}
+
 # ---------------------------------------------------------------------------
 # mxtk_model_version [mpr] — the model's Mendix version (e.g. 11.12.2), read from the
 # .mpr's own SQLite _MetaData._ProductVersion. v1 and v2 models both carry it (v2's .mpr
@@ -379,9 +395,9 @@ mxtk_model_version() {
   fi
   if [ -z "$v" ]; then
     py="${PY:-$(resolve_py 2>/dev/null || true)}"
-    [ -n "$py" ] && v=$("$py" -c "import sqlite3,sys,os,urllib.request as u
-c=sqlite3.connect('file:'+u.pathname2url(os.path.abspath(sys.argv[1]))+'?mode=ro',uri=True)
-print(c.execute('select _ProductVersion from _MetaData').fetchone()[0])" "$(native_path "$mpr")" 2>/dev/null | head -1 | tr -d '\r')
+    [ -n "$py" ] && v=$("$py" -c "import sqlite3,sys
+c=sqlite3.connect(sys.argv[1],uri=True)
+print(c.execute('select _ProductVersion from _MetaData').fetchone()[0])" "$(PY="$py" mxtk_sqlite_ro_uri "$(native_path "$mpr")")" 2>/dev/null | head -1 | tr -d '\r')
   fi
   case "$v" in
     [0-9]*.[0-9]*) printf '%s\n' "$v"; return 0 ;;

project-bin/app-facts.sh

@@ -284,11 +284,31 @@ log "catalog ok: build_mode=${BUILD_MODE:-unset} modules=$N_MODULES refs=$N_REFS
 # ---------------------------------------------------------------------------------------------
 log "step 2: inventory + dependency facts"
 T2=$(date +%s)
-DB="$DB" FACTS_DIR="$FACTS_DIR" MX_VERSION="$MX_VERSION" MPR_BASE="$MPR_BASE" MAX_LOOPS="$MAX_LOOPS" "$PY" - <<'PY' || exit 2
+# The catalog is opened through mxtk_sqlite_ro_uri (_common.sh): a bare "file:%s?mode=ro" cut the
+# path at a '#' or '?' in a folder name, lost mode=ro, and SQLite created and opened an empty file
+# beside the model folder. A _common.sh older than this script (or none) lacks the helper: build
+# the same URI inline, as require_py and find_mpr fall back above. native_path (when present)
+# turns an MSYS /c/... path into C:/... first, as mxtk_model_version does.
+DB_NATIVE="$DB"
+if type native_path >/dev/null 2>&1; then DB_NATIVE="$(native_path "$DB")"; fi
+if type mxtk_sqlite_ro_uri >/dev/null 2>&1; then
+  DB_URI="$(mxtk_sqlite_ro_uri "$DB_NATIVE")"
+else
+  DB_URI="$("$PY" -c "import os,sys,urllib.request as u
+print('file:'+u.pathname2url(os.path.abspath(sys.argv[1]))+'?mode=ro')" "$DB_NATIVE" | tr -d '\r')"
+fi
+[ -n "$DB_URI" ] || { echo "FAULT: could not build a read-only URI for $DB" >&2; exit 2; }
+DB="$DB" DB_URI="$DB_URI" FACTS_DIR="$FACTS_DIR" MX_VERSION="$MX_VERSION" MPR_BASE="$MPR_BASE" MAX_LOOPS="$MAX_LOOPS" "$PY" - <<'PY' || exit 2
 import json, os, sqlite3, sys, collections
 
-db = sqlite3.connect("file:%s?mode=ro" % os.environ["DB"], uri=True)
+db = sqlite3.connect(os.environ["DB_URI"], uri=True)
 db.row_factory = sqlite3.Row
+# The shell checked the catalog with the sqlite3 CLI on the plain path; this is a second open. If
+# it reached a different file, an empty graph must not be written as the app's facts.
+if db.execute("SELECT count(*) FROM sqlite_master WHERE type='table'").fetchone()[0] == 0:
+    sys.stderr.write("FAULT: %s opened with 0 tables (URI %s), though the catalog check passed. Refusing to write facts.\n"
+                     % (os.environ["DB"], os.environ["DB_URI"]))
+    sys.exit(2)
 F = os.environ["FACTS_DIR"]
 def rows(sql, *a): return [dict(r) for r in db.execute(sql, a)]
 def one(sql, *a):  return db.execute(sql, a).fetchone()[0]