@nusoft/nuos-build-catalogue 0.33.3 → 0.36.0

package/dist/embedder/ollama.d.ts

@@ -32,6 +32,13 @@
  * idle-timeout (the keep_alive: "1m" we sent) cleans up within a
  * minute.
  *
+ * **Bounded footprint while loaded.** Beyond unloading promptly, each call
+ * also pins `options.num_ctx` (see EMBED_NUM_CTX) so the model loads with an
+ * embedding-sized context window instead of inheriting the daemon's
+ * chat-sized OLLAMA_CONTEXT_LENGTH. Without this the 639MB model loads at
+ * ~5.7GB resident; with it, ~1.1GB. This is what keeps a reindex from pushing
+ * a developer's machine into swap.
+ *
  * Sizing note — the new 0.6b default is ~600MB on disk and runs
  * comfortably on any modern laptop, including CPU-only. The 4b variant
  * (~2.5GB) and 8b variant (~4.7GB, benefits from ~16GB RAM + Metal)

package/dist/embedder/ollama.js

@@ -32,6 +32,13 @@
  * idle-timeout (the keep_alive: "1m" we sent) cleans up within a
  * minute.
  *
+ * **Bounded footprint while loaded.** Beyond unloading promptly, each call
+ * also pins `options.num_ctx` (see EMBED_NUM_CTX) so the model loads with an
+ * embedding-sized context window instead of inheriting the daemon's
+ * chat-sized OLLAMA_CONTEXT_LENGTH. Without this the 639MB model loads at
+ * ~5.7GB resident; with it, ~1.1GB. This is what keeps a reindex from pushing
+ * a developer's machine into swap.
+ *
  * Sizing note — the new 0.6b default is ~600MB on disk and runs
  * comfortably on any modern laptop, including CPU-only. The 4b variant
  * (~2.5GB) and 8b variant (~4.7GB, benefits from ~16GB RAM + Metal)
@@ -47,6 +54,16 @@ const KNOWN_DIMENSIONS = {
     'qwen3-embedding:4b': 2560,
     'qwen3-embedding:0.6b': 1024,
 };
+// Context window for embedding loads. The Ollama daemon's global
+// OLLAMA_CONTEXT_LENGTH — set high for chat models (commonly 32K–64K) — is
+// inherited by every model that doesn't override it. Inherited unchanged, it
+// inflates the 639MB qwen3-embedding:0.6b model to ~5.7GB resident, which is
+// enough to push a 16–18GB developer machine into swap during a reindex.
+// Embedding inputs are capped at ~600 tokens (MAX_CHUNK_CHARS in
+// indexer/chunk.ts), so a 2048-token window leaves ~3x headroom and never
+// truncates a chunk. Measured 2026-06-01 (qwen3-embedding:0.6b, Apple Silicon):
+// inherited 32K ctx → 5.7GB resident; num_ctx 2048 → 1.1GB resident.
+const EMBED_NUM_CTX = 2048;
 export class OllamaEmbedder {
     dimensions;
     modelId;
@@ -68,7 +85,13 @@ export class OllamaEmbedder {
             const probe = await fetch(`${host}/api/embed`, {
                 method: 'POST',
                 headers: { 'content-type': 'application/json' },
-                body: JSON.stringify({ model: modelId, input: 'probe' }),
+                body: JSON.stringify({
+                    model: modelId,
+                    input: 'probe',
+                    // Pin the context window here too — the probe is what first loads the
+                    // model, so without it the probe alone would pull in the full ~5.7GB.
+                    options: { num_ctx: EMBED_NUM_CTX },
+                }),
             });
             if (!probe.ok) {
                 const body = await probe.text().catch(() => '<unreadable>');
@@ -121,6 +144,9 @@ export class OllamaEmbedder {
                 // Keep the model warm only for the duration of one operation.
                 // dispose() at the end of the run sends keep_alive: 0 to unload.
                 keep_alive: '1m',
+                // Cap the context window so the model loads at ~1.1GB rather than
+                // inheriting the daemon's chat-sized window and ballooning to ~5.7GB.
+                options: { num_ctx: EMBED_NUM_CTX },
             }),
         });
         if (!res.ok) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nusoft/nuos-build-catalogue",
-  "version": "0.33.3",
+  "version": "0.36.0",
   "description": "NuOS build-catalogue tooling: semantic search (WU 110) + migration runner that lifts markdown artefacts into JSON-backed workflow records (WU 111, Phase G).",
   "type": "module",
   "bin": {
@@ -19,15 +19,16 @@
     "build": "rm -rf dist && tsc && chmod +x dist/cli.js",
     "prepublishOnly": "npm run build",
     "verify-storage": "tsx scripts/verify-persistence.ts",
-    "test": "tsx --test tests/chunk.test.ts tests/metadata.test.ts tests/crawl.test.ts tests/migrate.test.ts tests/commands-read.test.ts tests/regenerate.test.ts tests/commands-write.test.ts tests/ac-parse.test.ts tests/create.test.ts tests/init.test.ts tests/wu-111-soak-findings.test.ts tests/plan.test.ts tests/mode.test.ts tests/render.test.ts tests/swarm.test.ts tests/setup-progress-bar.test.ts tests/setup-ollama-pull.test.ts tests/setup-run-llm-setup.test.ts tests/wu-active.test.ts tests/install-claude-hooks.test.ts tests/protocols-in-sync.test.ts tests/end-of-session.test.ts tests/hooks-in-sync.test.ts tests/memory-store-separation.test.ts",
+    "test": "tsx --test tests/chunk.test.ts tests/metadata.test.ts tests/crawl.test.ts tests/migrate.test.ts tests/commands-read.test.ts tests/regenerate.test.ts tests/commands-write.test.ts tests/ac-parse.test.ts tests/create.test.ts tests/init.test.ts tests/wu-111-soak-findings.test.ts tests/plan.test.ts tests/mode.test.ts tests/render.test.ts tests/swarm.test.ts tests/setup-progress-bar.test.ts tests/setup-ollama-pull.test.ts tests/setup-run-llm-setup.test.ts tests/wu-active.test.ts tests/install-claude-hooks.test.ts tests/protocols-in-sync.test.ts tests/end-of-session.test.ts tests/hooks-in-sync.test.ts tests/memory-store-separation.test.ts tests/state-compile.test.ts tests/state-drift-check.test.ts tests/hook-isolation.test.ts",
     "typecheck": "tsc --noEmit",
     "index": "tsx src/cli.ts index",
     "search": "tsx src/cli.ts search"
   },
   "dependencies": {
-    "@nusoft/nuvector": "^0.1.5",
     "@nusoft/nuflow": "^0.4.1",
-    "@nusoft/nuflow-pack-nuos-build-catalogue": "^0.1.0"
+    "@nusoft/nuflow-pack-nuos-build-catalogue": "^0.3.0",
+    "@nusoft/nuvector": "^0.1.5",
+    "@nusoft/nuwiki": "^0.3.0"
   },
   "devDependencies": {
     "@nusoft/nuflow": "file:../nuflow",

package/scripts/hooks/pre-commit

@@ -177,6 +177,49 @@ if [[ -n "$locked_decisions" ]]; then
   EXIT_CODE=1
 fi
 
+# ---------- Rule 3: STATE.md generated-region drift block (WU 113b Stage B) ---
+
+# Only run when docs/build/STATE.md is in the staged changes.
+# Guard on nuos-catalogue being present and supporting `state drift-check`.
+# Fail-open: if the binary is absent, old (doesn't know drift-check), or
+# errors for any infra reason, skip this check silently — a missing binary
+# must never block all commits.
+#
+# Old-binary detection: an old binary (< 0.35.0) exits non-zero with
+# "unknown state subcommand: drift-check" on stderr. We distinguish this
+# from a genuine drift finding by checking whether the output contains the
+# drift-specific marker phrase. If the output does NOT contain "generated regions"
+# (the phrase only the new drift-check command emits), we skip.
+staged_state_md=$(git diff --cached --name-only | grep -F 'docs/build/STATE.md' || true)
+
+if [[ -n "$staged_state_md" ]]; then
+  dim "[nuos:pre-commit] STATE.md generated-region drift check (WU 113b)"
+
+  if ! command -v nuos-catalogue > /dev/null 2>&1; then
+    dim "[nuos:pre-commit] nuos-catalogue not found — skipping STATE.md drift check"
+  else
+    # Run drift-check; capture output + exit code.
+    drift_output=$(nuos-catalogue state drift-check 2>&1) || drift_exit=$?
+    drift_exit=${drift_exit:-0}
+
+    if [[ $drift_exit -ne 0 ]]; then
+      # Non-zero exit — check whether this is a genuine drift finding or an
+      # infra/version problem (old binary, missing store, etc.).
+      if echo "$drift_output" | grep -qF 'generated regions'; then
+        # Confirmed generated-region drift — block the commit.
+        red "✖ STATE.md generated-region drift — BLOCKED (WU 113b enforcement):"
+        echo "$drift_output" | while IFS= read -r line; do echo "  $line"; done
+        log_event "state-drift-block" "generated-region drift detected"
+        EXIT_CODE=1
+      else
+        # Not a drift finding (unknown subcommand from old binary, infra error, etc.)
+        # — skip silently (fail open).
+        dim "[nuos:pre-commit] STATE.md drift check returned non-zero (not a drift finding) — skipping"
+      fi
+    fi
+  fi
+fi
+
 # ---------- Result ------------------------------------------------------
 
 if [[ $EXIT_CODE -eq 0 ]]; then

package/templates/hooks/pre-commit

@@ -177,6 +177,49 @@ if [[ -n "$locked_decisions" ]]; then
   EXIT_CODE=1
 fi
 
+# ---------- Rule 3: STATE.md generated-region drift block (WU 113b Stage B) ---
+
+# Only run when docs/build/STATE.md is in the staged changes.
+# Guard on nuos-catalogue being present and supporting `state drift-check`.
+# Fail-open: if the binary is absent, old (doesn't know drift-check), or
+# errors for any infra reason, skip this check silently — a missing binary
+# must never block all commits.
+#
+# Old-binary detection: an old binary (< 0.35.0) exits non-zero with
+# "unknown state subcommand: drift-check" on stderr. We distinguish this
+# from a genuine drift finding by checking whether the output contains the
+# drift-specific marker phrase. If the output does NOT contain "generated regions"
+# (the phrase only the new drift-check command emits), we skip.
+staged_state_md=$(git diff --cached --name-only | grep -F 'docs/build/STATE.md' || true)
+
+if [[ -n "$staged_state_md" ]]; then
+  dim "[nuos:pre-commit] STATE.md generated-region drift check (WU 113b)"
+
+  if ! command -v nuos-catalogue > /dev/null 2>&1; then
+    dim "[nuos:pre-commit] nuos-catalogue not found — skipping STATE.md drift check"
+  else
+    # Run drift-check; capture output + exit code.
+    drift_output=$(nuos-catalogue state drift-check 2>&1) || drift_exit=$?
+    drift_exit=${drift_exit:-0}
+
+    if [[ $drift_exit -ne 0 ]]; then
+      # Non-zero exit — check whether this is a genuine drift finding or an
+      # infra/version problem (old binary, missing store, etc.).
+      if echo "$drift_output" | grep -qF 'generated regions'; then
+        # Confirmed generated-region drift — block the commit.
+        red "✖ STATE.md generated-region drift — BLOCKED (WU 113b enforcement):"
+        echo "$drift_output" | while IFS= read -r line; do echo "  $line"; done
+        log_event "state-drift-block" "generated-region drift detected"
+        EXIT_CODE=1
+      else
+        # Not a drift finding (unknown subcommand from old binary, infra error, etc.)
+        # — skip silently (fail open).
+        dim "[nuos:pre-commit] STATE.md drift check returned non-zero (not a drift finding) — skipping"
+      fi
+    fi
+  fi
+fi
+
 # ---------- Result ------------------------------------------------------
 
 if [[ $EXIT_CODE -eq 0 ]]; then

package/templates/starter-kit/methodfile.json

@@ -17,7 +17,13 @@
     "database": null,
     "deployment": null,
     "externalServices": [],
-    "notes": null
+    "notes": null,
+    "services": {
+      "database": { "provider": "none", "migrations": "none", "deployOnMerge": false, "secrets": [] },
+      "jobs": { "provider": "none", "deployOnMerge": false, "secrets": [] },
+      "web": { "provider": "none", "autoDeploy": false, "secrets": [] }
+    },
+    "servicesComment": "Backend service wiring (D150 / WU 231). Per service: 'provider', whether it 'deployOnMerge' to main, and the 'secrets' it needs; 'database' also names its 'migrations' tool; 'web' declares 'autoDeploy' (e.g. Vercel's Git integration). Set provider to 'none' to opt a service out. When a provider is set, `nuos init` scaffolds the deploy automation (build packages → migrate deploy → jobs deploy via the installed CLI) and the doctor verifies the secrets exist and flags deploy drift. Providers — database: supabase|neon|railway|none; jobs: trigger.dev|none; web: vercel|none."
   },
   "testing": {
     "framework": "vitest",