@nusoft/nuos-build-catalogue 0.33.1 → 0.35.1

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/dist/path-resolution.d.ts

@@ -52,6 +52,15 @@ export declare function resolveCatalogueRoot(flag: string | boolean | undefined,
 export declare function resolveIndexDir(buildRoot: string, ctx?: ResolutionContext): string;
 export declare function resolveWorkflowsPath(buildRoot: string, flag: string | boolean | undefined, ctx?: ResolutionContext): string;
 export declare function resolveIndexPath(buildRoot: string, flag: string | boolean | undefined, ctx?: ResolutionContext): string;
+/**
+ * Resolve the cross-agent memory store path. Always co-located with the
+ * doc-index in the same `.nuos-catalogue/` directory, but in a separate
+ * file (`memory.nv`) so that the doc-index reindex (which holds an
+ * exclusive lock on `index.nv`) never contends with memory writes.
+ * Resolves `NUOS_CATALOGUE_MEMORY_PATH` env var when set; otherwise
+ * derives from `resolveIndexDir`. See D131.
+ */
+export declare function resolveMemoryPath(buildRoot: string, flag: string | boolean | undefined, ctx?: ResolutionContext): string;
 export declare function resolveHashPath(buildRoot: string, flag: string | boolean | undefined, ctx?: ResolutionContext): string;
 /**
  * Soft warning surfaced after a `migrate` or `regenerate` run: if the

package/dist/path-resolution.js

@@ -108,6 +108,22 @@ export function resolveIndexPath(buildRoot, flag, ctx) {
         return path.resolve(flag);
     return path.join(resolveIndexDir(buildRoot, ctx), 'index.nv');
 }
+/**
+ * Resolve the cross-agent memory store path. Always co-located with the
+ * doc-index in the same `.nuos-catalogue/` directory, but in a separate
+ * file (`memory.nv`) so that the doc-index reindex (which holds an
+ * exclusive lock on `index.nv`) never contends with memory writes.
+ * Resolves `NUOS_CATALOGUE_MEMORY_PATH` env var when set; otherwise
+ * derives from `resolveIndexDir`. See D131.
+ */
+export function resolveMemoryPath(buildRoot, flag, ctx) {
+    if (typeof flag === 'string' && flag.length > 0)
+        return path.resolve(flag);
+    const env = ctxEnv(ctx);
+    if (env.NUOS_CATALOGUE_MEMORY_PATH)
+        return path.resolve(env.NUOS_CATALOGUE_MEMORY_PATH);
+    return path.join(resolveIndexDir(buildRoot, ctx), 'memory.nv');
+}
 export function resolveHashPath(buildRoot, flag, ctx) {
     if (typeof flag === 'string' && flag.length > 0)
         return path.resolve(flag);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nusoft/nuos-build-catalogue",
-  "version": "0.33.1",
+  "version": "0.35.1",
   "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",
+    "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

@@ -134,14 +134,38 @@ fi
 # ---------- Rule 2: active-decision modification block (WU 111 ship) ---
 
 dim "[nuos:pre-commit] active-decision modification check"
-modified_decisions=$(git diff --cached --name-only --diff-filter=M \
+#
+# "Immutable once accepted" — this blocks edits only to a decision whose
+# status *in HEAD* is already a locked state (`accepted` or `active`).
+# Editing a still-`proposed` decision is allowed: promoting it to
+# accepted/active is the sanctioned lifecycle step, not a violation, and
+# proposed decisions are in-flight by design. New decision files are
+# additions (excluded by --diff-filter=M), so a decision born `accepted`
+# is never blocked on creation. The locked-status check uses the HEAD
+# pre-image, so flipping an accepted decision back to `proposed` to sneak
+# a substantive edit is still caught.
+candidate_decisions=$(git diff --cached --name-only --diff-filter=M \
   | grep -E '^docs/build/decisions/D[0-9]+.*\.md$' \
   | grep -v '/superseded/' \
   || true)
 
-if [[ -n "$modified_decisions" ]]; then
+locked_decisions=""
+if [[ -n "$candidate_decisions" ]]; then
+  while IFS= read -r f; do
+    [[ -z "$f" ]] && continue
+    head_status=$(git show "HEAD:$f" 2>/dev/null \
+      | grep -m1 -E '^\*\*Status:\*\*' \
+      | sed -E 's/^\*\*Status:\*\*[[:space:]]*//' \
+      | awk '{print tolower($1)}')
+    case "$head_status" in
+      accepted|active) locked_decisions+="${f}"$'\n' ;;
+    esac
+  done <<< "$candidate_decisions"
+fi
+
+if [[ -n "$locked_decisions" ]]; then
   red "✖ active-decision modification — BLOCKED (WU 111 enforcement):"
-  while IFS= read -r f; do echo "    — $f"; done <<< "$modified_decisions"
+  while IFS= read -r f; do [[ -n "$f" ]] && echo "    — $f"; done <<< "$locked_decisions"
   red "  Decisions are immutable once accepted. The discipline is to write a"
   red "  superseding D-NNN+1 and link forward. Use:"
   red "    nuos-catalogue decision supersede <target> --by=<new-D> --reason=\"...\""
@@ -149,10 +173,53 @@ if [[ -n "$modified_decisions" ]]; then
   red "  If this edit is a non-substantive typo fix or link cleanup that does"
   red "  not change the decision's meaning, you may bypass this block with"
   red "  --no-verify. CLAUDE.md prohibits --no-verify for substantive changes."
-  log_event "active-decision-block" "$(echo "$modified_decisions" | tr '\n' ',')"
+  log_event "active-decision-block" "$(echo "$locked_decisions" | tr '\n' ',')"
   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

@@ -134,14 +134,38 @@ fi
 # ---------- Rule 2: active-decision modification block (WU 111 ship) ---
 
 dim "[nuos:pre-commit] active-decision modification check"
-modified_decisions=$(git diff --cached --name-only --diff-filter=M \
+#
+# "Immutable once accepted" — this blocks edits only to a decision whose
+# status *in HEAD* is already a locked state (`accepted` or `active`).
+# Editing a still-`proposed` decision is allowed: promoting it to
+# accepted/active is the sanctioned lifecycle step, not a violation, and
+# proposed decisions are in-flight by design. New decision files are
+# additions (excluded by --diff-filter=M), so a decision born `accepted`
+# is never blocked on creation. The locked-status check uses the HEAD
+# pre-image, so flipping an accepted decision back to `proposed` to sneak
+# a substantive edit is still caught.
+candidate_decisions=$(git diff --cached --name-only --diff-filter=M \
   | grep -E '^docs/build/decisions/D[0-9]+.*\.md$' \
   | grep -v '/superseded/' \
   || true)
 
-if [[ -n "$modified_decisions" ]]; then
+locked_decisions=""
+if [[ -n "$candidate_decisions" ]]; then
+  while IFS= read -r f; do
+    [[ -z "$f" ]] && continue
+    head_status=$(git show "HEAD:$f" 2>/dev/null \
+      | grep -m1 -E '^\*\*Status:\*\*' \
+      | sed -E 's/^\*\*Status:\*\*[[:space:]]*//' \
+      | awk '{print tolower($1)}')
+    case "$head_status" in
+      accepted|active) locked_decisions+="${f}"$'\n' ;;
+    esac
+  done <<< "$candidate_decisions"
+fi
+
+if [[ -n "$locked_decisions" ]]; then
   red "✖ active-decision modification — BLOCKED (WU 111 enforcement):"
-  while IFS= read -r f; do echo "    — $f"; done <<< "$modified_decisions"
+  while IFS= read -r f; do [[ -n "$f" ]] && echo "    — $f"; done <<< "$locked_decisions"
   red "  Decisions are immutable once accepted. The discipline is to write a"
   red "  superseding D-NNN+1 and link forward. Use:"
   red "    nuos-catalogue decision supersede <target> --by=<new-D> --reason=\"...\""
@@ -149,10 +173,53 @@ if [[ -n "$modified_decisions" ]]; then
   red "  If this edit is a non-substantive typo fix or link cleanup that does"
   red "  not change the decision's meaning, you may bypass this block with"
   red "  --no-verify. CLAUDE.md prohibits --no-verify for substantive changes."
-  log_event "active-decision-block" "$(echo "$modified_decisions" | tr '\n' ',')"
+  log_event "active-decision-block" "$(echo "$locked_decisions" | tr '\n' ',')"
   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