@ngockhoale/ukit 3.0.6 → 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/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/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.