@triflux/core 10.0.0-alpha.1 → 10.0.0

package/hub/adaptive-diagnostic.mjs

@@ -0,0 +1,323 @@
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { normalizeError } from './reflexion.mjs';
+
+const DEFAULT_KNOWN_ERRORS_PATH = resolve(
+  dirname(fileURLToPath(import.meta.url)),
+  'lib/known-errors.json',
+);
+const DEFAULT_CONFIDENCE = 0.5;
+const ADAPTIVE_CONFIDENCE_STEP = 0.1;
+const MAX_ADAPTIVE_CONFIDENCE = 0.95;
+
+function clone(value) {
+  return value == null ? value : JSON.parse(JSON.stringify(value));
+}
+
+function pickString(...values) {
+  for (const value of values) {
+    if (typeof value === 'string' && value.trim()) return value.trim();
+  }
+  return '';
+}
+
+function pickObject(...values) {
+  return values.find(
+    (value) => value && typeof value === 'object' && !Array.isArray(value),
+  ) || {};
+}
+
+function clampConfidence(value, fallback = DEFAULT_CONFIDENCE) {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric)) return fallback;
+  return Math.max(0, Math.min(1, numeric));
+}
+
+function normalizeLookup(text) {
+  return String(text || '').trim().toLowerCase();
+}
+
+function readPathValue(source, path) {
+  if (!source || !path) return undefined;
+  return String(path)
+    .split('.')
+    .filter(Boolean)
+    .reduce((current, key) => current?.[key], source);
+}
+
+function renderTemplate(template, observation, signature) {
+  if (!template) return '';
+  const context = pickObject(observation.context);
+  const dna = pickObject(observation.dna);
+  const dnaValue = signature.dna_factor
+    ? readPathValue(dna, signature.dna_factor) ??
+      readPathValue(context, signature.dna_factor) ??
+      readPathValue(observation, signature.dna_factor)
+    : undefined;
+  const variables = {
+    ...context,
+    ...pickObject(observation.variables),
+    host: pickString(observation.host, context.host),
+    value: dnaValue,
+  };
+  return String(template).replace(/\{([^}]+)\}/gu, (match, key) => {
+    const value = variables[key];
+    return value == null || value === '' ? match : String(value);
+  });
+}
+
+function buildKnownContextText(observation) {
+  return normalizeLookup(
+    [
+      pickString(observation.contextLabel, observation.context),
+      pickString(observation.phase),
+      pickString(observation.step),
+    ]
+      .filter(Boolean)
+      .join(' '),
+  );
+}
+
+function buildErrorText(observation = {}) {
+  return [
+    pickString(observation.error),
+    pickString(observation.stderr),
+    pickString(observation.tool_output, observation.output),
+    pickString(observation.message),
+  ]
+    .filter(Boolean)
+    .join('\n')
+    .trim();
+}
+
+function normalizeObservation(observation = {}) {
+  const errorText = buildErrorText(observation);
+  const projectSlug = pickString(
+    observation.project_slug,
+    observation.projectSlug,
+    observation.context?.project_slug,
+    observation.context?.projectSlug,
+  );
+  return {
+    ...clone(observation),
+    errorText,
+    errorPattern: normalizeError(errorText),
+    projectSlug,
+    tool: pickString(observation.tool, observation.tool_name),
+    contextText: buildKnownContextText(observation),
+  };
+}
+
+function compileSignatures(raw = {}) {
+  return Object.entries(raw.signatures || {}).map(([id, signature]) => ({
+    id,
+    ...clone(signature),
+    matcher: new RegExp(String(signature.pattern || ''), 'iu'),
+  }));
+}
+
+export function loadKnownErrors(filePath = DEFAULT_KNOWN_ERRORS_PATH) {
+  try {
+    const parsed = JSON.parse(readFileSync(filePath, 'utf8'));
+    return {
+      path: filePath,
+      version: parsed.version ?? 1,
+      signatures: compileSignatures(parsed),
+    };
+  } catch {
+    return { path: filePath, version: 0, signatures: [] };
+  }
+}
+
+function scoreKnownMatch(signature, observation) {
+  if (!observation.errorText || !signature.matcher.test(observation.errorText)) {
+    return null;
+  }
+  if (
+    signature.tool &&
+    observation.tool &&
+    normalizeLookup(signature.tool) !== normalizeLookup(observation.tool)
+  ) {
+    return null;
+  }
+  if (
+    signature.context &&
+    observation.contextText &&
+    !observation.contextText.includes(normalizeLookup(signature.context))
+  ) {
+    return null;
+  }
+  return clampConfidence(
+    Number(signature.confidence_base ?? DEFAULT_CONFIDENCE) +
+      (signature.tool && observation.tool ? 0.02 : 0) +
+      (signature.context && observation.contextText ? 0.02 : 0) +
+      (signature.dna_factor ? 0.01 : 0),
+  );
+}
+
+function severityFromConfidence(confidence, fallback = 'medium') {
+  if (confidence >= 0.9) return 'critical';
+  if (confidence >= 0.75) return 'high';
+  if (confidence >= 0.55) return 'medium';
+  return fallback;
+}
+
+export function matchKnownError(catalog, observationInput = {}) {
+  const observation = normalizeObservation(observationInput);
+  const matched = (catalog?.signatures || [])
+    .map((signature) => {
+      const confidence = scoreKnownMatch(signature, observation);
+      return confidence == null ? null : { signature, confidence };
+    })
+    .filter(Boolean)
+    .sort((left, right) => right.confidence - left.confidence)[0];
+
+  if (!matched) return null;
+  const { signature, confidence } = matched;
+  return {
+    matched: true,
+    source: 'known',
+    signature_id: signature.id,
+    project_slug: observation.projectSlug,
+    error_pattern: observation.errorPattern,
+    error_message: observation.errorText,
+    confidence,
+    severity: signature.severity || severityFromConfidence(confidence),
+    tool: signature.tool || observation.tool,
+    context: signature.context || observation.contextText || null,
+    root_cause: signature.root_cause || 'known failure pattern',
+    rule: renderTemplate(signature.rule_template, observation, signature),
+    fix: signature.fix || null,
+    dna_factor: signature.dna_factor || null,
+  };
+}
+
+function resolveRuleStore(options = {}) {
+  return options.store || options.adaptiveMemory || null;
+}
+
+function ensureAdaptiveRule(store, observation) {
+  if (!store?.findAdaptiveRule || !store?.addAdaptiveRule || !observation.projectSlug) {
+    return null;
+  }
+  const identity = {
+    project_slug: observation.projectSlug,
+    pattern: observation.errorPattern,
+  };
+  const current = store.findAdaptiveRule(identity.project_slug, identity.pattern);
+  if (!current) {
+    return store.addAdaptiveRule(identity);
+  }
+  if (!store.updateRuleConfidence) return current;
+  return store.updateRuleConfidence(
+    identity.project_slug,
+    identity.pattern,
+    Math.min(MAX_ADAPTIVE_CONFIDENCE, current.confidence + ADAPTIVE_CONFIDENCE_STEP),
+    { hit_count_increment: 1 },
+  );
+}
+
+function buildAdaptiveDiagnosis(rule, observation) {
+  if (!rule) {
+    return {
+      matched: false,
+      source: 'novel',
+      project_slug: observation.projectSlug,
+      error_pattern: observation.errorPattern,
+      error_message: observation.errorText,
+      confidence: DEFAULT_CONFIDENCE,
+      severity: 'low',
+      root_cause: '새로운 실패 패턴으로 분류됨',
+      rule: '',
+      fix: null,
+    };
+  }
+  const matched = Number(rule.hit_count || 0) > 1 || Number(rule.confidence || 0) > DEFAULT_CONFIDENCE;
+  const confidence = clampConfidence(rule.confidence, DEFAULT_CONFIDENCE);
+  return {
+    matched,
+    source: matched ? 'adaptive' : 'novel',
+    project_slug: rule.project_slug,
+    error_pattern: rule.pattern,
+    error_message: observation.errorText,
+    confidence,
+    severity: severityFromConfidence(confidence, matched ? 'medium' : 'low'),
+    root_cause: matched
+      ? '반복 관측된 adaptive rule과 일치'
+      : 'adaptive memory에 첫 관측으로 저장됨',
+    rule: matched
+      ? `프로젝트 ${rule.project_slug}에서 동일 패턴이 ${rule.hit_count}회 관측되었습니다.`
+      : `프로젝트 ${rule.project_slug}의 adaptive memory에 패턴을 기록했습니다.`,
+    fix: matched ? '최근 성공한 수정/회피 전략을 재적용하세요.' : '추가 관측 후 adaptive rule을 승격하세요.',
+    adaptive_rule: clone(rule),
+  };
+}
+
+function createHealthyState(catalog) {
+  return {
+    state: 'healthy',
+    known_errors_count: catalog.signatures.length,
+    last_error: null,
+  };
+}
+
+function createDegradedState(error) {
+  return {
+    state: 'degraded',
+    known_errors_count: 0,
+    last_error: {
+      name: error?.name || 'Error',
+      message: error?.message || 'unknown adaptive diagnostic error',
+    },
+  };
+}
+
+export function createDiagnosticPipeline(options = {}) {
+  const store = resolveRuleStore(options);
+  let catalog = options.knownErrors ? { signatures: compileSignatures({ signatures: options.knownErrors }) } : null;
+  let health = catalog ? createHealthyState(catalog) : null;
+
+  function ensureCatalog() {
+    if (catalog) return catalog;
+    try {
+      catalog = loadKnownErrors(options.knownErrorsPath || DEFAULT_KNOWN_ERRORS_PATH);
+      health = createHealthyState(catalog);
+    } catch (error) {
+      catalog = { signatures: [] };
+      health = createDegradedState(error);
+    }
+    return catalog;
+  }
+
+  function diagnoseFailure(observationInput = {}) {
+    const observation = normalizeObservation(observationInput);
+    const nextCatalog = ensureCatalog();
+    const known = matchKnownError(nextCatalog, observation);
+    if (known) return known;
+    const adaptiveRule = observation.errorPattern
+      ? ensureAdaptiveRule(store, observation)
+      : null;
+    return buildAdaptiveDiagnosis(adaptiveRule, observation);
+  }
+
+  function getHealth() {
+    return clone(health || ensureCatalog() && health);
+  }
+
+  function listKnownErrors() {
+    return (ensureCatalog().signatures || []).map(({ matcher, ...signature }) => clone(signature));
+  }
+
+  return Object.freeze({
+    diagnose: diagnoseFailure,
+    diagnoseFailure,
+    run: diagnoseFailure,
+    getHealth,
+    listKnownErrors,
+  });
+}
+
+export { DEFAULT_KNOWN_ERRORS_PATH };
+export default createDiagnosticPipeline;

package/hub/adaptive-inject.mjs

@@ -0,0 +1,186 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+const SECTION_HEADING = '## Adaptive Rules (triflux auto-generated)';
+const DEFAULT_MAX_RULES = 10;
+const SECTION_RE = /^## Adaptive Rules \(triflux auto-generated\)$/mu;
+const BLOCK_RE = /<!-- tfx-adaptive:start rule_id="([^"]+)" confidence=([0-9.]+) occurrences=(\d+) first_seen=([0-9-]+) last_seen=([0-9-]+) -->\r?\n([^\r\n]*)\r?\n<!-- tfx-adaptive:end -->/gu;
+
+function cloneRule(rule) {
+  return Object.freeze({ ...rule });
+}
+
+function clampConfidence(value) {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric)) return 0;
+  return Math.min(1, Math.max(0, numeric));
+}
+
+function normalizeOccurrences(value) {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric)) return 1;
+  return Math.max(1, Math.trunc(numeric));
+}
+
+function formatConfidence(value) {
+  return Number(clampConfidence(value).toFixed(6)).toString();
+}
+
+function normalizeDate(value, fallback) {
+  const text = String(value ?? fallback ?? '').trim();
+  return text || fallback;
+}
+
+function normalizeRuleInput(rule, fallback = {}) {
+  if (!rule || typeof rule !== 'object') return null;
+
+  const id = String(rule.id ?? rule.rule_id ?? fallback.id ?? '').trim();
+  const text = String(rule.rule ?? rule.text ?? fallback.rule ?? '').trim();
+  const firstSeen = normalizeDate(
+    rule.firstSeen ?? rule.first_seen,
+    fallback.firstSeen ?? fallback.lastSeen ?? '1970-01-01',
+  );
+  const lastSeen = normalizeDate(rule.lastSeen ?? rule.last_seen, fallback.lastSeen ?? firstSeen);
+  if (!id || !text || /["\r\n]/u.test(id) || /[\r\n]/u.test(text)) {
+    return null;
+  }
+
+  return cloneRule({
+    id,
+    rule: text,
+    confidence: clampConfidence(rule.confidence ?? fallback.confidence),
+    occurrences: normalizeOccurrences(rule.occurrences ?? fallback.occurrences),
+    firstSeen,
+    lastSeen,
+  });
+}
+
+function trimLeadingBlankLines(text) {
+  return String(text ?? '').replace(/^(?:[ \t]*\r?\n)+/u, '');
+}
+
+function trimTrailingBlankLines(text) {
+  return String(text ?? '').replace(/(?:\r?\n[ \t]*)+$/u, '');
+}
+
+function parseInjectedRules(sectionBody = '') {
+  const matches = Array.from(String(sectionBody).matchAll(BLOCK_RE));
+  return matches.map(([, id, confidence, occurrences, firstSeen, lastSeen, text]) => cloneRule({
+    id,
+    rule: text,
+    confidence: clampConfidence(confidence),
+    occurrences: normalizeOccurrences(occurrences),
+    firstSeen,
+    lastSeen,
+  }));
+}
+
+function readDocument(claudeMdPath) {
+  const raw = existsSync(claudeMdPath) ? readFileSync(claudeMdPath, 'utf8') : '';
+  const sectionStart = raw.search(SECTION_RE);
+  if (sectionStart === -1) {
+    return { before: raw, after: '', rules: [] };
+  }
+
+  const headingEnd = raw.indexOf('\n', sectionStart);
+  const bodyStart = headingEnd === -1 ? raw.length : headingEnd + 1;
+  const rest = raw.slice(bodyStart);
+  const nextHeadingOffset = rest.search(/^#{1,6}\s/mu);
+  const sectionEnd = nextHeadingOffset === -1 ? raw.length : bodyStart + nextHeadingOffset;
+  const body = raw.slice(bodyStart, sectionEnd);
+
+  return {
+    before: raw.slice(0, sectionStart),
+    after: raw.slice(sectionEnd),
+    rules: parseInjectedRules(body),
+  };
+}
+
+function serializeRule(rule) {
+  return [
+    `<!-- tfx-adaptive:start rule_id="${rule.id}" confidence=${formatConfidence(rule.confidence)} occurrences=${rule.occurrences} first_seen=${rule.firstSeen} last_seen=${rule.lastSeen} -->`,
+    rule.rule,
+    '<!-- tfx-adaptive:end -->',
+  ].join('\n');
+}
+
+function serializeDocument(before, rules, after) {
+  const section = rules.length > 0
+    ? `${SECTION_HEADING}\n\n${rules.map(serializeRule).join('\n\n')}`
+    : '';
+  const parts = [trimTrailingBlankLines(before), section, trimLeadingBlankLines(after)].filter(Boolean);
+  return parts.length > 0 ? `${parts.join('\n\n')}\n` : '';
+}
+
+function enforceMaxRules(rules, maxRules) {
+  if (rules.length <= maxRules) return rules.map(cloneRule);
+  const ranked = rules
+    .map((rule, index) => ({ ...rule, index }))
+    .sort((left, right) => (
+      left.confidence - right.confidence
+      || left.occurrences - right.occurrences
+      || left.lastSeen.localeCompare(right.lastSeen)
+      || left.index - right.index
+      || left.id.localeCompare(right.id)
+    ));
+  const removedIds = new Set(ranked.slice(0, rules.length - maxRules).map((rule) => rule.id));
+  return rules.filter((rule) => !removedIds.has(rule.id)).map(cloneRule);
+}
+
+export function createAdaptiveInjector(opts = {}) {
+  const claudeMdPath = resolve(opts.claudeMdPath ?? join(process.cwd(), 'CLAUDE.md'));
+  const maxRules = Number.isInteger(opts.maxRules) && opts.maxRules > 0 ? opts.maxRules : DEFAULT_MAX_RULES;
+
+  function listInjected() {
+    return readDocument(claudeMdPath).rules.map(cloneRule);
+  }
+
+  function inject(rule) {
+    const document = readDocument(claudeMdPath);
+    const targetId = String(rule?.id ?? rule?.rule_id ?? '').trim();
+    const existing = document.rules.find((item) => item.id === targetId);
+    const normalized = normalizeRuleInput(rule, existing ?? {});
+    if (!normalized) return false;
+
+    const nextRules = existing
+      ? document.rules.map((item) => (item.id === normalized.id
+        ? cloneRule({
+          ...item,
+          confidence: normalized.confidence,
+          occurrences: normalized.occurrences,
+          lastSeen: normalized.lastSeen,
+        })
+        : cloneRule(item)))
+      : [...document.rules.map(cloneRule), normalized];
+    const limitedRules = enforceMaxRules(nextRules, maxRules);
+    writeFileSync(claudeMdPath, serializeDocument(document.before, limitedRules, document.after), 'utf8');
+    return limitedRules.some((item) => item.id === normalized.id);
+  }
+
+  function remove(ruleId) {
+    const targetId = String(ruleId ?? '').trim();
+    if (!targetId || !existsSync(claudeMdPath)) return false;
+    const document = readDocument(claudeMdPath);
+    if (!document.rules.some((rule) => rule.id === targetId)) return false;
+    const nextRules = document.rules.filter((rule) => rule.id !== targetId).map(cloneRule);
+    writeFileSync(claudeMdPath, serializeDocument(document.before, nextRules, document.after), 'utf8');
+    return true;
+  }
+
+  function cleanup(activeRuleIds = []) {
+    const activeIds = new Set(Array.isArray(activeRuleIds) ? activeRuleIds : Array.from(activeRuleIds));
+    return listInjected().reduce(
+      (count, rule) => count + (activeIds.has(rule.id) ? 0 : Number(remove(rule.id))),
+      0,
+    );
+  }
+
+  return Object.freeze({
+    inject,
+    remove,
+    listInjected,
+    cleanup,
+  });
+}
+
+export default createAdaptiveInjector;

package/hub/adaptive-memory.mjs

@@ -0,0 +1,163 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const SESSION_FILE = 'adaptive-session.json';
+const DEFAULT_CONFIDENCE = 0.5;
+const TIER2_DECAY_STEP = 0.2;
+const TIER2_DECAY_INTERVAL = 5;
+const TIER2_REMOVE_THRESHOLD = 0.3;
+const TIER3_WARN_THRESHOLD = 10;
+const TIER3_REMOVE_THRESHOLD = 20;
+
+const clone = (v) => (v == null ? v : JSON.parse(JSON.stringify(v)));
+const clamp01 = (v) => { const n = Number(v); return Number.isFinite(n) ? Number(Math.max(0, Math.min(1, n)).toFixed(4)) : DEFAULT_CONFIDENCE; };
+const toDate = (v = Date.now()) => { const d = new Date(v); return Number.isNaN(d.getTime()) ? new Date().toISOString().slice(0, 10) : d.toISOString().slice(0, 10); };
+const uniq = (arr) => [...new Set(arr.filter((s) => typeof s === 'string' && s.trim()))];
+const slugify = (v) => String(v || '').trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 80);
+const buildId = (r) => { const e = slugify(r.id); if (e) return e; const p = slugify(r.pattern); return p || `adaptive-${Date.now()}`; };
+const readJson = (f, fb) => { if (!existsSync(f)) return clone(fb); try { return { ...clone(fb), ...JSON.parse(readFileSync(f, 'utf8')) }; } catch { return clone(fb); } };
+const writeJson = (f, v) => writeFileSync(f, `${JSON.stringify(v, null, 2)}\n`, 'utf8');
+const strip = (r) => { if (!r) return null; const { sessionIds, ...pub } = r; return clone(pub); };
+const sortRules = (list) => [...list].sort((a, b) => a.tier - b.tier || b.confidence - a.confidence || a.id.localeCompare(b.id));
+const upsert = (list, r) => [...list.filter((x) => x.id !== r.id), r];
+const without = (list, id) => list.filter((x) => x.id !== id);
+
+function toRule(rule, tier, sessionId, existing = null) {
+  return {
+    id: existing?.id || buildId(rule),
+    pattern: String(rule.pattern || existing?.pattern || ''),
+    rootCause: String(rule.rootCause || rule.root_cause || existing?.rootCause || ''),
+    rule: String(rule.rule || existing?.rule || ''),
+    confidence: clamp01(rule.confidence ?? existing?.confidence),
+    occurrences: Math.max(1, Number(existing?.occurrences || 0) + 1),
+    firstSeen: existing?.firstSeen || toDate(rule.timestamp),
+    lastSeen: toDate(rule.timestamp),
+    sessionsWithout: 0,
+    tier,
+    dnaFactor: rule.dnaFactor ?? rule.dna_factor ?? existing?.dnaFactor ?? null,
+    sessionIds: uniq([...(existing?.sessionIds || []), sessionId]),
+  };
+}
+
+export function createAdaptiveMemory(opts = {}) {
+  const projectSlug = slugify(opts.projectSlug);
+  if (!projectSlug) throw new Error('projectSlug is required');
+
+  const sessionDir = opts.sessionDir || join(process.cwd(), '.omc', 'state');
+  const globalDir = opts.globalDir || join(homedir(), '.triflux', 'adaptive');
+  const sessionFile = join(sessionDir, SESSION_FILE);
+  const projectFile = join(globalDir, `${projectSlug}.json`);
+
+  mkdirSync(sessionDir, { recursive: true });
+  mkdirSync(globalDir, { recursive: true });
+
+  let ss = readJson(sessionFile, { projectSlug, sessionId: null, rules: [] });
+  let ps = readJson(projectFile, { projectSlug, history: {}, tier2: [], tier3: [] });
+
+  function saveSession() {
+    if (ss.rules.length === 0) { rmSync(sessionFile, { force: true }); return; }
+    writeJson(sessionFile, ss);
+  }
+
+  function saveProject() {
+    const has = Object.keys(ps.history).length > 0 || ps.tier2.length > 0 || ps.tier3.length > 0;
+    if (!has) { rmSync(projectFile, { force: true }); return; }
+    writeJson(projectFile, ps);
+  }
+
+  const saveAll = () => { saveSession(); saveProject(); };
+
+  function getSessionId(id) {
+    const next = String(id || ss.sessionId || 'session-current');
+    ss = { ...ss, sessionId: next };
+    return next;
+  }
+
+  const getDurable = (id) => ps.tier3.find((r) => r.id === id) || ps.tier2.find((r) => r.id === id) || null;
+
+  function promote(ruleId) {
+    const t2 = ps.tier2.find((r) => r.id === ruleId);
+    if (t2 && t2.occurrences >= 3 && t2.confidence >= 0.8) {
+      const next = { ...t2, tier: 3, sessionsWithout: 0 };
+      ps = { ...ps, tier2: without(ps.tier2, ruleId), tier3: upsert(ps.tier3, next) };
+      saveProject();
+      return { rule: strip(next), promoted: true, fromTier: 2, toTier: 3 };
+    }
+    const cand = ps.history[ruleId];
+    if (cand && cand.occurrences >= 2 && cand.sessionIds.length >= 2) {
+      const next = { ...cand, tier: 2, sessionsWithout: 0 };
+      const { [ruleId]: _, ...history } = ps.history;
+      ps = { ...ps, history, tier2: upsert(ps.tier2, next) };
+      ss = { ...ss, rules: without(ss.rules, ruleId) };
+      saveAll();
+      return { rule: strip(next), promoted: true, fromTier: 1, toTier: 2 };
+    }
+    const cur = getDurable(ruleId) || ps.history[ruleId] || null;
+    return { rule: strip(cur), promoted: false, fromTier: cur?.tier ?? null, toTier: cur?.tier ?? null };
+  }
+
+  function record(rule = {}) {
+    if (!rule.pattern) return { rule: null, promoted: false, fromTier: null, toTier: null };
+    const sessionId = getSessionId(rule.sessionId);
+    const ruleId = buildId(rule);
+    const durable = getDurable(ruleId);
+    if (durable) {
+      const next = toRule(rule, durable.tier, sessionId, durable);
+      ps = durable.tier === 3 ? { ...ps, tier3: upsert(ps.tier3, next) } : { ...ps, tier2: upsert(ps.tier2, next) };
+      saveProject();
+      const res = promote(ruleId);
+      return res.promoted ? res : { rule: strip(next), promoted: false, fromTier: durable.tier, toTier: durable.tier };
+    }
+    const cand = toRule(rule, 1, sessionId, ps.history[ruleId]);
+    ps = { ...ps, history: { ...ps.history, [ruleId]: cand } };
+    ss = { ...ss, rules: upsert(ss.rules, { ...cand, tier: 1 }) };
+    saveAll();
+    const res = promote(ruleId);
+    return res.promoted ? res : { rule: strip(cand), promoted: false, fromTier: 1, toTier: 1 };
+  }
+
+  function decay(sessionId) {
+    const nextId = String(sessionId || `session-${Date.now()}`);
+    if (ss.sessionId === nextId) return { sessionId: nextId, tier1Cleared: 0, updated: [], warned: [], removed: [] };
+    const warned = [], removed = [], updated = [];
+    const tier1Cleared = ss.rules.length;
+    const tier2 = ps.tier2.flatMap((r) => {
+      const sw = Number(r.sessionsWithout || 0) + 1;
+      const conf = sw % TIER2_DECAY_INTERVAL === 0 ? clamp01(r.confidence - TIER2_DECAY_STEP) : r.confidence;
+      if (conf < TIER2_REMOVE_THRESHOLD) { removed.push(r.id); return []; }
+      updated.push(r.id);
+      return [{ ...r, sessionsWithout: sw, confidence: conf }];
+    });
+    const tier3 = ps.tier3.flatMap((r) => {
+      const sw = Number(r.sessionsWithout || 0) + 1;
+      if (sw >= TIER3_REMOVE_THRESHOLD) { removed.push(r.id); return []; }
+      if (sw === TIER3_WARN_THRESHOLD) warned.push(r.id);
+      updated.push(r.id);
+      return [{ ...r, sessionsWithout: sw }];
+    });
+    ss = { ...ss, sessionId: nextId, rules: [] };
+    ps = { ...ps, tier2, tier3 };
+    saveAll();
+    return { sessionId: nextId, tier1Cleared, updated, warned, removed };
+  }
+
+  function getRule(id) { return strip(ss.rules.find((r) => r.id === id) || getDurable(id)); }
+  function getTier(tier) {
+    if (tier === 1) return sortRules(ss.rules).map(strip);
+    if (tier === 2) return sortRules(ps.tier2).map(strip);
+    if (tier === 3) return sortRules(ps.tier3).map(strip);
+    return [];
+  }
+  function getAllRules() { return sortRules([...ss.rules, ...ps.tier2, ...ps.tier3]).map(strip); }
+  function reset(target = 'all') {
+    const rs = target === 'all' || target === 1 || target === 'session';
+    const rp = target === 'all' || target === 2 || target === 3 || target === 'project';
+    if (rs) ss = { ...ss, rules: [] };
+    if (rp) ps = { ...ps, history: {}, tier2: [], tier3: [] };
+    saveAll();
+    return { sessionCleared: rs, projectCleared: rp };
+  }
+
+  return { record, promote, decay, getRule, getAllRules, getTier, reset };
+}