oh-my-knowledge 0.48.0 → 0.49.0

package/dist/managed/store.js

@@ -1,7 +1,10 @@
-import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from 'node:fs';
-import { join, normalize } from 'node:path';
+import { existsSync, readFileSync, readdirSync, } from 'node:fs';
+import { isAbsolute, join, normalize } from 'node:path';
 import { hashString } from '../eval-core/evaluation-reporting.js';
 import { OMK_HOME } from '../eval-core/default-dirs.js';
+import { writeJsonFileAtomic } from '../shared/atomic-json.js';
+import { withFileLock } from '../shared/file-lock.js';
+import { isRfc3339Timestamp } from '../shared/timestamp.js';
 /**
  * 受管记录的 per-record 文件存储。一条记录一个 `.omk/managed/<id>.json`,镜像 report-store 的
  * 成熟模式(原子 tmp+rename):每次 install 只碰自己那个文件,independent write、不丢别人、
@@ -19,6 +22,8 @@ export function globalManagedDir() {
     return join(OMK_HOME, 'managed');
 }
 export function recordPath(dir, id) {
+    if (!isManagedRecordId(id))
+        throw new TypeError('invalid managed record id');
     return join(dir, `${id}.json`);
 }
 /** 稳定身份 = hash(kind, name)。源路径是可变属性、不进 id。kind 取自固定枚举(无 `|`),分隔可注入。 */
@@ -31,6 +36,18 @@ export { hashArtifactSource, isDistributablePath, distributableCopyFilter } from
 function isStringField(v) {
     return typeof v === 'string';
 }
+function isNonEmptyString(v) {
+    return typeof v === 'string' && v.length > 0;
+}
+function isManagedRecordId(v) {
+    return typeof v === 'string' && /^[0-9a-f]{12}$/.test(v);
+}
+function isNonNegativeSafeInteger(v) {
+    return typeof v === 'number' && Number.isSafeInteger(v) && v >= 0;
+}
+function isRate(v) {
+    return typeof v === 'number' && Number.isFinite(v) && v >= 0 && v <= 1;
+}
 /** 仅当字段缺省或是 string 才放行(可选 string 字段的脏值守卫,如 source.url / evidence.verdict)。 */
 function isOptionalString(v) {
     return v === undefined || typeof v === 'string';
@@ -47,27 +64,41 @@ function isOptionalSha(v) {
 }
 // 受管记录可安装的 kind(managed 记录绝不是 baseline)。
 const MANAGED_KINDS = new Set(['skill', 'prompt', 'agent', 'workflow']);
+const MANAGED_DECISIONS = new Set(['promote', 'reject', 'rollback']);
+const VERDICTS = new Set([
+    'PROGRESS',
+    'CAUTIOUS',
+    'REGRESS',
+    'NOISE',
+    'UNDERPOWERED',
+    'SOLO',
+]);
+const OVERRIDE_VERDICTS = new Set([...VERDICTS, 'UNKNOWN']);
+const OVERRIDDEN_BLOCKS = new Set(['drifted', 'no_evidence', 'incomparable', 'verdict_blocked']);
 // 校验到**运行时实际收窄**的边界,不止「字段是 string」:记录文件是用户可手改、且可能随仓库分发(被
 // loadAllManagedRecords 无 opt-in 读到)的不可信输入。若只查 string,畸形记录(如 source.url 是对象、
 // sourceKind 是任意串)会绕过 validator,在下游(omk list 的 sourceLabel ?? → dispWidth(对象) 等)
 // 抛 TypeError 让命令崩溃。这里把 source / evidence 收窄到 list 等消费方实际解引用的类型,判脏即丢弃该文件。
-function isManagedArtifactRecord(value) {
+function isManagedArtifactRecord(value, expectedId) {
     if (!value || typeof value !== 'object')
         return false;
     const r = value;
     if (!(r.recordKind === 'managed-artifact'
         && r.schemaVersion === 2
-        && isStringField(r.id)
-        && isStringField(r.name)
+        && isManagedRecordId(r.id)
+        && (expectedId === undefined || r.id === expectedId)
+        && isNonEmptyString(r.name)
         && isStringField(r.kind) && MANAGED_KINDS.has(r.kind)
-        && isStringField(r.contentHash)
+        && r.id === managedRecordId(r.kind, r.name)
+        && isNonEmptyString(r.contentHash)
+        && isRfc3339Timestamp(r.installedAt)
         && r.source && typeof r.source === 'object'
         && Array.isArray(r.distribution)
         && Array.isArray(r.evidence)
         && Array.isArray(r.decisions)))
         return false;
     const src = r.source;
-    if (!(isStringField(src.locator)
+    if (!(isNonEmptyString(src.locator)
         && (src.sourceKind === 'file' || src.sourceKind === 'git')
         && typeof src.isDirectorySkill === 'boolean'
         && isOptionalString(src.url)
@@ -77,22 +108,51 @@ function isManagedArtifactRecord(value) {
     // 读取的 locator(畸形但可通过上面 string 校验)→ 「读了什么」与「显示什么」不一致。判脏丢弃。
     if (src.sourceKind === 'file' && (src.url !== undefined || src.ref !== undefined))
         return false;
-    const okDist = r.distribution.every((d) => d && typeof d === 'object'
-        && isStringField(d.path) && isStringField(d.contentHash));
+    const distributionPaths = new Set();
+    const okDist = r.distribution.every((d) => {
+        if (!d || typeof d !== 'object')
+            return false;
+        const target = d;
+        if (!isNonEmptyString(target.label)
+            || !isNonEmptyString(target.path)
+            || !isAbsolute(target.path)
+            || !isNonEmptyString(target.contentHash)
+            || !isRfc3339Timestamp(target.copiedAt))
+            return false;
+        const pathKey = normalize(target.path).replace(/[\\/]+$/, '') || target.path;
+        if (distributionPaths.has(pathKey))
+            return false;
+        distributionPaths.add(pathKey);
+        return true;
+    });
+    const evidenceKeys = new Set();
     const okEv = r.evidence.every((e) => {
         if (!e || typeof e !== 'object')
             return false;
         const ev = e;
-        if (!(isStringField(ev.reportId) && isStringField(ev.contentHash) && isStringField(ev.recordedAt)))
+        if (!isNonEmptyString(ev.reportId)
+            || !isNonEmptyString(ev.contentHash)
+            || !isRfc3339Timestamp(ev.recordedAt)
+            || (ev.verdict !== undefined && !VERDICTS.has(String(ev.verdict))))
             return false;
-        if (!isOptionalString(ev.verdict))
+        const evidenceKey = `${ev.reportId}\0${ev.contentHash}`;
+        if (evidenceKeys.has(evidenceKey))
             return false;
+        evidenceKeys.add(evidenceKey);
+        if (ev.sampleCoverage !== undefined) {
+            const coverage = ev.sampleCoverage;
+            if (!coverage
+                || typeof coverage !== 'object'
+                || !isNonNegativeSafeInteger(coverage.count)
+                || !isNonEmptyString(coverage.hash))
+                return false;
+        }
         // comparability 若存在:必须是带 string cliVersion 的对象(list / promote 会读它)。可选 marker
         // judgePromptHash / debiasMode 同样收窄到声明类型 —— 否则任意类型脏值会穿过 validator 原样进 `omk list
         // --json`(及未来 promote gate)消费方。
         if (ev.comparability !== undefined) {
             const c = ev.comparability;
-            if (!c || typeof c !== 'object' || !isStringField(c.cliVersion))
+            if (!c || typeof c !== 'object' || !isNonEmptyString(c.cliVersion))
                 return false;
             if (!isOptionalString(c.judgePromptHash))
                 return false;
@@ -111,36 +171,53 @@ function isManagedArtifactRecord(value) {
         if (!d || typeof d !== 'object')
             return false;
         const dec = d;
-        if (!isStringField(dec.decisionKind))
+        if (!MANAGED_DECISIONS.has(String(dec.decisionKind))
+            || !isNonEmptyString(dec.actor)
+            || !isRfc3339Timestamp(dec.decidedAt))
             return false;
         // promote/reject/rollback 的证据指针(promote 写)同样收窄:任意类型脏值不得穿过 validator 进
         // deriveManagedState / promote 消费方。actor / decidedAt / reason 是 install 后才追加的可选展示字段,
         // 旧记录(install 时 decisions 恒空)无,按 optional 读。
-        if (!isOptionalString(dec.actor) || !isOptionalString(dec.decidedAt) || !isOptionalString(dec.reason))
+        if (!isOptionalString(dec.reason))
+            return false;
+        if ((dec.contentHash !== undefined && !isNonEmptyString(dec.contentHash))
+            || (dec.reportId !== undefined && !isNonEmptyString(dec.reportId)))
             return false;
-        if (!isOptionalString(dec.contentHash) || !isOptionalString(dec.reportId))
+        if ((dec.decisionKind === 'promote' || dec.decisionKind === 'rollback')
+            && !isNonEmptyString(dec.contentHash))
             return false;
         if (dec.override !== undefined) {
             const o = dec.override;
-            if (!o || typeof o !== 'object' || !isStringField(o.verdict))
+            if (dec.decisionKind !== 'promote'
+                || !o
+                || typeof o !== 'object'
+                || !OVERRIDE_VERDICTS.has(String(o.verdict)))
                 return false;
             if (o.overriddenBlocks !== undefined
-                && !(Array.isArray(o.overriddenBlocks) && o.overriddenBlocks.every((b) => typeof b === 'string')))
+                && !(Array.isArray(o.overriddenBlocks)
+                    && o.overriddenBlocks.every((block) => OVERRIDDEN_BLOCKS.has(String(block)))))
                 return false;
         }
         return true;
     });
     // observations(#235)缺省合法(旧记录无);present 必须是数组,每条窄到声明类型 —— healthBand / confidence
     // 驱动读时 marker(deriveProductionGap),畸形脏值会让 list / Studio 误判,故判脏丢整条记录(同 okEv / okDec)。
+    const observationIds = new Set();
     const okObs = r.observations === undefined || (Array.isArray(r.observations) && r.observations.every((o) => {
         if (!o || typeof o !== 'object')
             return false;
         const obs = o;
         if (obs.observationKind !== 'production-health')
             return false;
-        if (!isStringField(obs.reportId) || !isStringField(obs.observedAt))
+        if (!isNonEmptyString(obs.reportId)
+            || observationIds.has(obs.reportId)
+            || !isRfc3339Timestamp(obs.observedAt))
             return false;
-        if (typeof obs.gapRate !== 'number' || typeof obs.weightedGapRate !== 'number' || typeof obs.segmentCount !== 'number')
+        observationIds.add(obs.reportId);
+        if (!isRate(obs.gapRate)
+            || !isRate(obs.weightedGapRate)
+            || obs.weightedGapRate > obs.gapRate
+            || !isNonNegativeSafeInteger(obs.segmentCount))
             return false;
         if (obs.confidence !== 'high' && obs.confidence !== 'low' && obs.confidence !== 'underpowered')
             return false;
@@ -149,17 +226,20 @@ function isManagedArtifactRecord(value) {
         const g = obs.gapByType;
         if (!g || typeof g !== 'object')
             return false;
-        return ['failed_search', 'explicit_marker', 'hedging', 'repeated_failure'].every((k) => typeof g[k] === 'number');
+        return ['failed_search', 'explicit_marker', 'hedging', 'repeated_failure']
+            .every((key) => isNonNegativeSafeInteger(g[key]));
     }));
     return okDist && okEv && okDec && okObs;
 }
 export function loadManagedRecord(dir, id) {
+    if (!isManagedRecordId(id))
+        return null;
     const path = recordPath(dir, id);
     if (!existsSync(path))
         return null;
     try {
         const parsed = JSON.parse(readFileSync(path, 'utf-8'));
-        return isManagedArtifactRecord(parsed) ? parsed : null;
+        return isManagedArtifactRecord(parsed, id) ? parsed : null;
     }
     catch {
         return null;
@@ -169,12 +249,13 @@ function readRecordsFromDir(dir) {
     if (!existsSync(dir))
         return [];
     const out = [];
-    for (const entry of readdirSync(dir)) {
-        if (!entry.endsWith('.json'))
+    for (const entry of readdirSync(dir).sort()) {
+        const match = /^([0-9a-f]{12})\.json$/.exec(entry);
+        if (!match)
             continue;
         try {
             const parsed = JSON.parse(readFileSync(join(dir, entry), 'utf-8'));
-            if (isManagedArtifactRecord(parsed))
+            if (isManagedArtifactRecord(parsed, match[1]))
                 out.push(parsed);
         }
         catch {
@@ -183,6 +264,17 @@ function readRecordsFromDir(dir) {
     }
     return out;
 }
+function persistManagedRecord(dir, record) {
+    if (!isManagedArtifactRecord(record, record.id)) {
+        throw new TypeError('invalid managed artifact record');
+    }
+    writeJsonFileAtomic(recordPath(dir, record.id), record);
+}
+function withManagedRecordLock(dir, recordId, operation) {
+    if (!isManagedRecordId(recordId))
+        throw new TypeError('invalid managed record id');
+    return withFileLock(join(dir, `${recordId}.lock`), operation, { label: `managed record ${recordId}` });
+}
 /** 读全部记录。项目目录空 → 兜底全局(镜像 observe inbox 的 project→global)。 */
 export function loadAllManagedRecords(dir = managedDir()) {
     const local = readRecordsFromDir(dir);
@@ -244,13 +336,14 @@ export function mergeManagedRecord(prev, next) {
 }
 /** 读旧记录 → 合并 → 原子 tmp+rename 只写该 id 的文件。返回合并后记录。 */
 export function upsertManagedRecord(dir, record) {
-    const merged = mergeManagedRecord(loadManagedRecord(dir, record.id), record);
-    mkdirSync(dir, { recursive: true });
-    const path = recordPath(dir, record.id);
-    const tmp = `${path}.tmp.${process.pid}.${Date.now()}`;
-    writeFileSync(tmp, JSON.stringify(merged, null, 2));
-    renameSync(tmp, path);
-    return merged;
+    if (!isManagedArtifactRecord(record, record.id)) {
+        throw new TypeError('invalid managed artifact record');
+    }
+    return withManagedRecordLock(dir, record.id, () => {
+        const merged = mergeManagedRecord(loadManagedRecord(dir, record.id), record);
+        persistManagedRecord(dir, merged);
+        return merged;
+    });
 }
 /**
  * 追加一条评测证据(append-only)。与 install 的 upsert 路径相反——`mergeManagedRecord` 刻意**保留旧
@@ -260,21 +353,25 @@ export function upsertManagedRecord(dir, record) {
  * null —— 这是"管理是 install 显式 opt-in"的体现:eval 绝不为未纳管的 skill 凭空建记录。
  */
 export function appendManagedEvidence(dir, recordId, evidence) {
-    const prev = loadManagedRecord(dir, recordId);
-    if (!prev)
+    if (!isManagedRecordId(recordId))
         return null;
-    const dup = prev.evidence.some((e) => e.reportId === evidence.reportId && e.contentHash === evidence.contentHash);
-    const merged = dup
-        ? prev
-        : { ...prev, evidence: [...prev.evidence, evidence] };
-    if (!dup) {
-        mkdirSync(dir, { recursive: true });
-        const path = recordPath(dir, recordId);
-        const tmp = `${path}.tmp.${process.pid}.${Date.now()}`;
-        writeFileSync(tmp, JSON.stringify(merged, null, 2));
-        renameSync(tmp, path);
-    }
-    return merged;
+    return withManagedRecordLock(dir, recordId, () => {
+        const prev = loadManagedRecord(dir, recordId);
+        if (!prev)
+            return null;
+        const duplicateIndex = prev.evidence.findIndex((entry) => entry.reportId === evidence.reportId && entry.contentHash === evidence.contentHash);
+        const candidateEvidence = duplicateIndex >= 0
+            ? prev.evidence.map((entry, index) => index === duplicateIndex ? evidence : entry)
+            : [...prev.evidence, evidence];
+        if (!isManagedArtifactRecord({ ...prev, evidence: candidateEvidence }, recordId)) {
+            throw new TypeError('invalid managed evidence');
+        }
+        if (duplicateIndex >= 0)
+            return prev;
+        const merged = { ...prev, evidence: candidateEvidence };
+        persistManagedRecord(dir, merged);
+        return merged;
+    });
 }
 /**
  * 追加一条 observe 生产健康观测(append-only,#235)。同 evidence 不走 upsert:`mergeManagedRecord` 保留旧
@@ -283,21 +380,26 @@ export function appendManagedEvidence(dir, recordId, evidence) {
  * 匹配)返回 null —— 与 evidence 同口径:observe 绝不为未纳管 skill 凭空建记录(管理是 install 显式 opt-in)。
  */
 export function appendManagedObservation(dir, recordId, observation) {
-    const prev = loadManagedRecord(dir, recordId);
-    if (!prev)
+    if (!isManagedRecordId(recordId))
         return null;
-    const dup = (prev.observations ?? []).some((o) => o.reportId === observation.reportId);
-    const merged = dup
-        ? prev
-        : { ...prev, observations: [...(prev.observations ?? []), observation] };
-    if (!dup) {
-        mkdirSync(dir, { recursive: true });
-        const path = recordPath(dir, recordId);
-        const tmp = `${path}.tmp.${process.pid}.${Date.now()}`;
-        writeFileSync(tmp, JSON.stringify(merged, null, 2));
-        renameSync(tmp, path);
-    }
-    return merged;
+    return withManagedRecordLock(dir, recordId, () => {
+        const prev = loadManagedRecord(dir, recordId);
+        if (!prev)
+            return null;
+        const observations = prev.observations ?? [];
+        const duplicateIndex = observations.findIndex((entry) => entry.reportId === observation.reportId);
+        const candidateObservations = duplicateIndex >= 0
+            ? observations.map((entry, index) => index === duplicateIndex ? observation : entry)
+            : [...observations, observation];
+        if (!isManagedArtifactRecord({ ...prev, observations: candidateObservations }, recordId)) {
+            throw new TypeError('invalid managed observation');
+        }
+        if (duplicateIndex >= 0)
+            return prev;
+        const merged = { ...prev, observations: candidateObservations };
+        persistManagedRecord(dir, merged);
+        return merged;
+    });
 }
 /**
  * 把受管记录的 drift 基线(contentHash)重锚到新源内容哈,保留 evidence / decisions / source /
@@ -309,18 +411,20 @@ export function appendManagedObservation(dir, recordId, observation) {
  * 返回 null(同 evidence / decision:管理是 install 显式 opt-in)。
  */
 export function rebaselineManagedContentHash(dir, recordId, newHash) {
-    const prev = loadManagedRecord(dir, recordId);
-    if (!prev)
+    if (!isNonEmptyString(newHash))
+        throw new TypeError('newHash must be a non-empty string');
+    if (!isManagedRecordId(recordId))
         return null;
-    if (prev.contentHash === newHash)
-        return prev;
-    const merged = { ...prev, contentHash: newHash };
-    mkdirSync(dir, { recursive: true });
-    const path = recordPath(dir, recordId);
-    const tmp = `${path}.tmp.${process.pid}.${Date.now()}`;
-    writeFileSync(tmp, JSON.stringify(merged, null, 2));
-    renameSync(tmp, path);
-    return merged;
+    return withManagedRecordLock(dir, recordId, () => {
+        const prev = loadManagedRecord(dir, recordId);
+        if (!prev)
+            return null;
+        if (prev.contentHash === newHash)
+            return prev;
+        const merged = { ...prev, contentHash: newHash };
+        persistManagedRecord(dir, merged);
+        return merged;
+    });
 }
 /**
  * 当前内容(contentHash === record.contentHash)是否处于 promoted 态。决定是 append-only 事件流,
@@ -379,37 +483,42 @@ export function currentPromoteOverride(record) {
  * (未 install)返回 null,与 evidence 同口径(管理是 install 显式 opt-in,绝不为未纳管 skill 凭空建记录)。
  */
 export function appendManagedDecision(dir, recordId, decision) {
-    const prev = loadManagedRecord(dir, recordId);
-    if (!prev)
+    if (!isManagedRecordId(recordId))
         return null;
-    const isPromotion = decision.decisionKind === 'promote' || decision.decisionKind === 'rollback';
-    const onCurrent = decision.contentHash !== undefined && decision.contentHash === prev.contentHash;
-    const dup = isPromotion && onCurrent
-        // promote/rollback 当前内容:不改变 promoted 态 → no-op(promote 当已 promoted、rollback 当未 promoted)。
-        ? (decision.decisionKind === 'promote') === isCurrentlyPromoted(prev)
-        : decision.contentHash !== undefined
-            && prev.decisions.some((d) => d.decisionKind === decision.decisionKind && d.contentHash === decision.contentHash);
-    const merged = dup
-        ? prev
-        : { ...prev, decisions: [...prev.decisions, decision] };
-    if (!dup) {
-        mkdirSync(dir, { recursive: true });
-        const path = recordPath(dir, recordId);
-        const tmp = `${path}.tmp.${process.pid}.${Date.now()}`;
-        writeFileSync(tmp, JSON.stringify(merged, null, 2));
-        renameSync(tmp, path);
-    }
-    return merged;
+    return withManagedRecordLock(dir, recordId, () => {
+        const prev = loadManagedRecord(dir, recordId);
+        if (!prev)
+            return null;
+        if (!isManagedArtifactRecord({ ...prev, decisions: [...prev.decisions, decision] }, recordId)) {
+            throw new TypeError('invalid managed decision');
+        }
+        const isPromotion = decision.decisionKind === 'promote' || decision.decisionKind === 'rollback';
+        const onCurrent = decision.contentHash !== undefined && decision.contentHash === prev.contentHash;
+        const dup = isPromotion && onCurrent
+            // promote/rollback 当前内容:不改变 promoted 态 → no-op(promote 当已 promoted、rollback 当未 promoted)。
+            ? (decision.decisionKind === 'promote') === isCurrentlyPromoted(prev)
+            : decision.contentHash !== undefined
+                && prev.decisions.some((d) => d.decisionKind === decision.decisionKind && d.contentHash === decision.contentHash);
+        if (dup)
+            return prev;
+        const merged = { ...prev, decisions: [...prev.decisions, decision] };
+        persistManagedRecord(dir, merged);
+        return merged;
+    });
 }
 /**
  * 统一的记录构造点——所有消费方(CLI / 未来 server / SDK)经此组装,保证 schema 一致。
  * 只接收事实(身份、源、hash、分发落点);evidence/decisions 恒为空(eval/promote 的地盘)。
  */
 export function buildManagedArtifactRecord(input) {
+    const id = input.id ?? managedRecordId(input.kind, input.name);
+    if (id !== managedRecordId(input.kind, input.name)) {
+        throw new TypeError('managed record id must match kind and name');
+    }
     return {
         recordKind: 'managed-artifact',
         schemaVersion: 2,
-        id: input.id ?? managedRecordId(input.kind, input.name),
+        id,
         name: input.name,
         kind: input.kind,
         source: input.source,

package/dist/observability/codex-trace-adapter.d.ts

@@ -0,0 +1,5 @@
+/** Codex rollout JSONL -> source-neutral Trace IR. */
+import type { TraceSession } from './trace-ir.js';
+export declare function isCodexJsonl(records: unknown[]): boolean;
+export declare function isCodexGuardianRollout(records: unknown[]): boolean;
+export declare function parseCodexSessionFile(filePath: string, rawRecords: unknown[]): TraceSession;