@ngockhoale/ukit 3.0.5 → 3.0.7

package/src/core/observability/support/retention.js

@@ -0,0 +1,155 @@
+/**
+ * retention.js (TASK-009, SPEC §5 DF-FR10) — support-view cap/age pruning.
+ *
+ *   pruneSupportView(dir, policy?) → { ok: true, removed: string[], bytes }
+ *                                  | { ok: false, reason }
+ *
+ * This is the retention owner for the user-facing `UKit Support` folder —
+ * deliberately SEPARATE from segments/retention.js, which governs the
+ * private canonical store. The two stores have different caps, different
+ * audiences, and different deletion safety rules.
+ *
+ * Ownership rule (the safety boundary): a file inside the support dir is
+ * prunable only when it is a regular file AND
+ *   - listed in the current manifest.json `files` map, or
+ *   - matches the digest naming convention `digest-<16 hex>.md`.
+ * Symlinks, directories, foreign-named files, and — when no manifest
+ * exists — static-named files are never touched. User-owned contents
+ * survive pruning unconditionally.
+ *
+ * Eviction order under the byte cap mirrors the projector's priority:
+ * digests first (oldest mtime first), then records.jsonl, then SUMMARY.md,
+ * README.md, and manifest.json last — core self-description outlives
+ * derived content.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { ioReason } from '../segments/internal.js';
+
+export const STATIC_OWNED_NAMES = new Set([
+  'README.md',
+  'SUMMARY.md',
+  'manifest.json',
+  'records.jsonl',
+]);
+
+export const DIGEST_NAME_RE = /^digest-[0-9a-f]{16}\.md$/;
+
+/** Names this module may ever treat as owned. */
+export function isOwnedName(name) {
+  return STATIC_OWNED_NAMES.has(name) || DIGEST_NAME_RE.test(name);
+}
+
+export const DEFAULT_SUPPORT_POLICY = Object.freeze({
+  maxBytes: 8 * 1024 * 1024,
+  maxAgeMs: 30 * 24 * 60 * 60 * 1000,
+});
+
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+async function readManifestFiles(dir) {
+  try {
+    const raw = await fs.promises.readFile(path.join(dir, 'manifest.json'), 'utf8');
+    const manifest = JSON.parse(raw);
+    if (isPlainObject(manifest) && isPlainObject(manifest.files)) {
+      return new Set(Object.keys(manifest.files));
+    }
+  } catch {
+    // missing/corrupt manifest → only convention-named digests stay owned
+  }
+  return null;
+}
+
+/** Eviction priority: lower number = evicted sooner. */
+function evictionRank(name) {
+  if (DIGEST_NAME_RE.test(name)) return 0;
+  if (name === 'records.jsonl') return 1;
+  if (name === 'SUMMARY.md') return 2;
+  if (name === 'README.md') return 3;
+  return 4; // manifest.json and anything else owned
+}
+
+/**
+ * @param {string} dir resolved support directory
+ * @param {{ maxBytes?: number, maxAgeMs?: number, now?: number }} [policy]
+ */
+export async function pruneSupportView(dir, policy = {}) {
+  const maxBytes = Number.isFinite(policy.maxBytes) ? policy.maxBytes : DEFAULT_SUPPORT_POLICY.maxBytes;
+  const maxAgeMs = Number.isFinite(policy.maxAgeMs) ? policy.maxAgeMs : DEFAULT_SUPPORT_POLICY.maxAgeMs;
+  const now = Number.isFinite(policy.now) ? policy.now : Date.now();
+
+  let dirStat;
+  try {
+    dirStat = await fs.promises.lstat(dir);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return { ok: true, removed: [], bytes: 0 };
+    return { ok: false, reason: ioReason(err) };
+  }
+  if (dirStat.isSymbolicLink() || !dirStat.isDirectory()) {
+    return { ok: false, reason: 'support_path_not_directory' };
+  }
+
+  const manifestOwned = await readManifestFiles(dir);
+
+  let entries;
+  try {
+    entries = await fs.promises.readdir(dir);
+  } catch (err) {
+    return { ok: false, reason: ioReason(err) };
+  }
+
+  // Snapshot owned regular files with stats. Never follow symlinks.
+  const owned = [];
+  for (const name of entries) {
+    const ownedByManifest = manifestOwned !== null && manifestOwned.has(name);
+    const ownedByConvention = DIGEST_NAME_RE.test(name);
+    if (!ownedByManifest && !ownedByConvention) continue;
+    let st;
+    try {
+      st = await fs.promises.lstat(path.join(dir, name));
+    } catch {
+      continue;
+    }
+    if (!st.isFile()) continue; // symlink/dir at an owned name → not ours to touch
+    owned.push({ name, size: st.size, mtimeMs: st.mtimeMs });
+  }
+
+  const removed = [];
+  const remove = async (entry) => {
+    try {
+      await fs.promises.rm(path.join(dir, entry.name), { force: true });
+      removed.push(entry.name);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+
+  // Age pass: owned files past the age cap go first.
+  const survivors = [];
+  for (const entry of owned) {
+    if (now - entry.mtimeMs > maxAgeMs) {
+      await remove(entry);
+    } else {
+      survivors.push(entry);
+    }
+  }
+
+  // Cap pass: evict lowest-priority owned content until under maxBytes.
+  let total = survivors.reduce((sum, e) => sum + e.size, 0);
+  if (total > maxBytes) {
+    const order = survivors
+      .slice()
+      .sort((a, b) => evictionRank(a.name) - evictionRank(b.name) || a.mtimeMs - b.mtimeMs);
+    for (const entry of order) {
+      if (total <= maxBytes) break;
+      if (await remove(entry)) total -= entry.size;
+    }
+  }
+
+  return { ok: true, removed, bytes: Math.max(0, total) };
+}

package/src/core/runtimeConfig.js

@@ -293,9 +293,12 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
       fastPath: { stage: 'off' },
       escalation: { stage: 'off' },
     },
-    // C52 M07 UNIC Decision Agent (docs/pstack/UNIC_DECISION_SPEC §17). All
-    // stages ship 'off' — zero outbound calls, deterministic policy stays
-    // authoritative. `enabled:false` is the global emergency disable.
+    // C52 M07: `unic-decision` is the owner's local non-LLM Lava/JEV model in
+    // UNIC Provider. Its OpenAI-compatible API is transport only, not proof of
+    // remote hosting or generative-LLM billing. Prefer bounded typed decisions
+    // when staged on; all stages currently ship 'off' (no decision request),
+    // deterministic safety/completion policy stays authoritative.
+    // `enabled:false` is the global emergency disable.
     decisionPlane: {
       enabled: true,
       stage: 'off',

package/src/decision/client.js

@@ -1,9 +1,17 @@
 /**
  * client.js (TASK-002 / M07)
  *
- * Typed client for the UNIC Decision Agent: OpenAI-compatible
- * `POST <baseUrl>/v1/chat/completions` against the configured UNIC gateway
- * (docs/pstack/UNIC_DECISION_SPEC.md §3/§15/§16).
+ * Typed client for the owner's LOCAL `unic-decision` model in UNIC Provider.
+ * It uses Lava/JEV technology and is NOT an LLM. OpenAI-compatible
+ * `POST <baseUrl>/v1/chat/completions` is only its interoperability transport,
+ * not evidence of remote hosting, generative semantics, or LLM pricing.
+ * See docs/pstack/UNIC_DECISION_SPEC.md (identity, §3/§15/§16).
+ *
+ * Prefer bounded classify/select/rank/score questions when decisionPlane.stage
+ * enables the caller; derive candidates in code, pass compact state and typed
+ * questions to createDecisionClient(...).requestBatch({ statePacket, questions }),
+ * then validate the outcome and retain deterministic safety/permission gates.
+ * The client does not itself switch a disabled rollout stage on.
  *
  * - Endpoint + credentials resolve via gatewayProbe env indirection only —
  *   no literal keys, no new credential store.

package/template_project/.claude/ukit/index/unic-decision.mjs

@@ -2,8 +2,12 @@
 /**
  * unic-decision.mjs (TASK-005 / M07, SPEC §5 FR-011)
  *
- * Standalone installed-side adapter for the UNIC Decision Agent
- * (docs/pstack/UNIC_DECISION_SPEC.md §8/§9, CONTRACTS.md C13/C14).
+ * Standalone installed-side adapter for the owner's local, non-LLM
+ * Lava/JEV `unic-decision` model in UNIC Provider. OpenAI-compatible
+ * /v1/chat/completions is a transport for easy integration, not evidence of
+ * an external generative LLM or LLM pricing. Prefer bounded typed semantic
+ * decisions when the caller's decisionPlane stage is enabled; this adapter
+ * does not change the rollout stage or override deterministic safety gates.
  *
  * Modes:
  *   node unic-decision.mjs --health-probe        one no-tools request; the ONLY

package/template_project/.omp/RULES.md

@@ -48,9 +48,8 @@ Your own model does not change mid-turn. A tier only applies when work is handed
 - Images: `@vision` only. `@default`/`@slow` cannot see images on the UNIC gateway and must never
   guess at their contents — hand every image to `ukit-vision-analyst` first.
 
-Doing everything inline is exactly what makes UKit look like it only has one model. Keep direct
-execution for trivial/simple work; delegate when the tier differs or when a noisy lane would other-
-wise flood this context.
+Doing everything inline is what makes UKit look like it only has one model. Keep direct execution
+for trivial/simple work; delegate when the tier differs or a noisy lane would flood this context.
 
 ## 7. Safe Patch
 
@@ -73,6 +72,7 @@ last thing you emit is one short line naming what is unfinished and what you nee
 a status — the user cannot distinguish it from a crash.
 
 > Maintainer note, not a per-turn rule: `modelRoles` in `.omp/config.yml` ships UNIC gateway names.
-> On a non-UNIC provider, edit only the three cost tiers — `smol`, `default`, `slow` — never `vision`,
-> which stays `unic-vision` (capability lane, not a cost tier). Old keys `lite`/`code`/`smart` remain
-> as compat aliases — edit each alias alongside its tier (smol↔lite, default↔code, slow↔smart).
+> On a non-UNIC provider, edit only the cost tiers `smol`/`default`/`slow` — never `vision`
+> (`unic-vision`) or `decision` (`unic-decision`, the LOCAL JEV/Lava typed-decision model —
+> `docs/pstack/UNIC_DECISION_GUIDE.md`); both are capability lanes. Aliases `lite`/`code`/`smart`
+> map smol↔lite, default↔code, slow↔smart — edit each alongside its tier.

package/template_project/.omp/config.yml

@@ -13,6 +13,12 @@ modelRoles:
   default: unic-code
   slow: unic-smart
   vision: unic-vision
+  # `decision` is a capability lane like `vision`, not a cost tier: it binds to
+  # the LOCAL JEV/Lava typed-decision model `unic-decision` (bounded classify/
+  # select/rank/score calls — see docs/pstack/UNIC_DECISION_GUIDE.md). It is NOT
+  # a handoff tier, so tier maps (handoff-model-guard.sh tierOf) never see it.
+  # On a non-UNIC provider leave it unset — there is no cost-tier alias for it.
+  decision: unic-decision
   # Back-compat aliases — INDEPENDENT keys, not references. A maintainer overriding a
   # cost tier above must edit the matching alias too (smol↔lite, default↔code,
   # slow↔smart), or the alias keeps resolving to the old unic-* value.

package/template_project/docs/UKIT_INTERNALS.md

@@ -140,6 +140,15 @@ the root contract is the only carrier — keep both in sync with
 
 ## 3-Tier Model Routing — full detail
 
+`unic-decision` is **not** another LLM tier. The owner built this local,
+near-zero-cost Lava/JEV model in UNIC Provider for fast typed semantic
+decisions; the OpenAI-compatible API is a convenience transport, not a
+generative-LLM or external-hosting claim. When `decisionPlane.stage` enables
+it, use bounded candidate choices/rankings/scores through
+`.claude/ukit/index/unic-decision.mjs`; keep safety, authorization and
+completion gates deterministic. The shipped stage is `off` until explicitly
+promoted. See `docs/pstack/UNIC_DECISION_SPEC.md` in the UKit development repo.
+
 UKit routes tasks to one of three model tiers based on task complexity. The main session
 model never changes mid-turn: a tier only takes effect when work is handed to an agent
 whose own definition binds that model.

package/template_project/instructions/overlays/omp-rules.md

@@ -45,9 +45,8 @@ Your own model does not change mid-turn. A tier only applies when work is handed
 - Images: `@vision` only. `@default`/`@slow` cannot see images on the UNIC gateway and must never
   guess at their contents — hand every image to `ukit-vision-analyst` first.
 
-Doing everything inline is exactly what makes UKit look like it only has one model. Keep direct
-execution for trivial/simple work; delegate when the tier differs or when a noisy lane would other-
-wise flood this context.
+Doing everything inline is what makes UKit look like it only has one model. Keep direct execution
+for trivial/simple work; delegate when the tier differs or a noisy lane would flood this context.
 
 ## 7. Safe Patch
 
@@ -70,6 +69,7 @@ last thing you emit is one short line naming what is unfinished and what you nee
 a status — the user cannot distinguish it from a crash.
 
 > Maintainer note, not a per-turn rule: `modelRoles` in `.omp/config.yml` ships UNIC gateway names.
-> On a non-UNIC provider, edit only the three cost tiers — `smol`, `default`, `slow` — never `vision`,
-> which stays `unic-vision` (capability lane, not a cost tier). Old keys `lite`/`code`/`smart` remain
-> as compat aliases — edit each alias alongside its tier (smol↔lite, default↔code, slow↔smart).
+> On a non-UNIC provider, edit only the cost tiers `smol`/`default`/`slow` — never `vision`
+> (`unic-vision`) or `decision` (`unic-decision`, the LOCAL JEV/Lava typed-decision model —
+> `docs/pstack/UNIC_DECISION_GUIDE.md`); both are capability lanes. Aliases `lite`/`code`/`smart`
+> map smol↔lite, default↔code, slow↔smart — edit each alongside its tier.