@spexcode/spec-eval 0.6.5

package/dist/sidecar.d.ts

@@ -0,0 +1,55 @@
+export type Verdict = {
+    status: 'pass' | 'fail';
+    note?: string;
+};
+export type EvidenceKind = 'image' | 'transcript' | 'video' | 'data';
+export type Evidence = {
+    hash: string;
+    kind: EvidenceKind;
+};
+export type Reading = {
+    scenario: string;
+    codeSha: string;
+    scenarioHash?: string;
+    evidence?: Evidence[];
+    blob?: string | null;
+    blobKind?: EvidenceKind;
+    timelineBlob?: string;
+    evaluator?: string;
+    by?: string;
+    verdict?: Verdict;
+    ts: string;
+};
+export declare function evidenceOf(r: {
+    evidence?: Evidence[];
+    blob?: string | null;
+    blobKind?: EvidenceKind;
+}): Evidence[];
+export declare function isJsonBlob(b: Buffer): boolean;
+export type Retraction = {
+    retracts: string;
+    scenario: string;
+    note?: string;
+    by?: string;
+    ts: string;
+};
+export type HumanOk = {
+    kind: 'human-ok';
+    scenario: string;
+    okTs: string;
+    okSha: string;
+    by: string;
+    ts: string;
+};
+export declare function readSidecar(sidecarPath: string): {
+    readings: Reading[];
+    retractions: Retraction[];
+    oks: HumanOk[];
+};
+export declare function applyRetractions(readings: Reading[], retractions: Retraction[]): Reading[];
+export declare function readReadings(sidecarPath: string): Reading[];
+export declare function appendReading(sidecarPath: string, r: Reading): void;
+export declare function appendRetraction(sidecarPath: string, r: Retraction): void;
+export declare function appendHumanOk(sidecarPath: string, r: HumanOk): void;
+export declare function humanOkFor(oks: HumanOk[], scenario: string, readingTs: string): HumanOk | null;
+export declare function latestPerScenario(readings: Reading[]): Map<string, Reading>;

package/dist/sidecar.js

@@ -0,0 +1,82 @@
+import { readFileSync, appendFileSync, existsSync } from 'node:fs';
+export function evidenceOf(r) {
+    if (r.evidence?.length)
+        return r.evidence;
+    if (r.blob)
+        return [{ hash: r.blob, kind: r.blobKind ?? 'image' }];
+    return [];
+}
+export function isJsonBlob(b) {
+    if (!b.length || b.includes(0))
+        return false; // empty or binary → not JSON text
+    if (b.length > 4_000_000)
+        return false; // don't parse an unbounded blob just to sniff a type
+    const s = b.toString('utf8').trim();
+    const open = s[0], close = s[s.length - 1];
+    if (!((open === '{' && close === '}') || (open === '[' && close === ']')))
+        return false;
+    try {
+        const v = JSON.parse(s);
+        return v !== null && typeof v === 'object';
+    }
+    catch {
+        return false;
+    }
+}
+export function readSidecar(sidecarPath) {
+    const readings = [];
+    const retractions = [];
+    const oks = [];
+    if (!existsSync(sidecarPath))
+        return { readings, retractions, oks };
+    for (const line of readFileSync(sidecarPath, 'utf8').split('\n')) {
+        const t = line.trim();
+        if (!t)
+            continue;
+        try {
+            const r = JSON.parse(t);
+            if (!r || typeof r.scenario !== 'string')
+                continue;
+            if (typeof r.retracts === 'string')
+                retractions.push(r);
+            else if (r.kind === 'human-ok' && typeof r.okTs === 'string')
+                oks.push(r);
+            else if (typeof r.codeSha === 'string')
+                readings.push(r);
+        }
+        catch { /* Keep earlier events readable after an incomplete append. */ }
+    }
+    return { readings, retractions, oks };
+}
+export function applyRetractions(readings, retractions) {
+    if (!retractions.length)
+        return readings;
+    const gone = new Set(retractions.map((x) => `${x.scenario}\0${x.retracts}`));
+    return readings.filter((r) => !gone.has(`${r.scenario}\0${r.ts}`));
+}
+export function readReadings(sidecarPath) {
+    const { readings, retractions } = readSidecar(sidecarPath);
+    return applyRetractions(readings, retractions);
+}
+export function appendReading(sidecarPath, r) {
+    appendFileSync(sidecarPath, JSON.stringify(r) + '\n');
+}
+export function appendRetraction(sidecarPath, r) {
+    appendFileSync(sidecarPath, JSON.stringify(r) + '\n');
+}
+export function appendHumanOk(sidecarPath, r) {
+    appendFileSync(sidecarPath, JSON.stringify(r) + '\n');
+}
+export function humanOkFor(oks, scenario, readingTs) {
+    let hit = null;
+    for (const o of oks)
+        if (o.scenario === scenario && o.okTs === readingTs)
+            hit = o;
+    return hit;
+}
+export function latestPerScenario(readings) {
+    const m = new Map();
+    for (const r of readings)
+        m.set(r.scenario, r); // later lines overwrite earlier → last wins
+    return m;
+}

package/dist/timeline.d.ts

@@ -0,0 +1,25 @@
+export type TimelineEvent = {
+    at: number;
+    step: string;
+    node?: string;
+};
+export type StepTimeline = {
+    v: 2;
+    axis: string;
+    events: TimelineEvent[];
+};
+export type LegacyTimelineEvent = {
+    tMs: number;
+    step: string;
+    node?: string;
+};
+export type LegacyStepTimeline = {
+    v: 1;
+    events: LegacyTimelineEvent[];
+};
+export declare function validateTimeline(raw: unknown): string[];
+export declare function normalizeTimeline(raw: unknown): {
+    axis: string;
+    events: TimelineEvent[];
+};
+export declare function stepAt(events: TimelineEvent[], pos: number): TimelineEvent | null;

package/dist/timeline.js

@@ -0,0 +1,65 @@
+const V2_EVENT_KEYS = new Set(['at', 'step', 'node']);
+const V1_EVENT_KEYS = new Set(['tMs', 'step', 'node']);
+export function validateTimeline(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        return ['timeline must be a JSON object { v, axis, events }'];
+    const o = raw;
+    if (o.v !== 1 && o.v !== 2)
+        return ['`v` must be 1 (legacy time axis) or 2 (axis-tagged)'];
+    const errs = [];
+    const v2 = o.v === 2;
+    const posKey = v2 ? 'at' : 'tMs';
+    const rootKeys = v2 ? new Set(['v', 'axis', 'events']) : new Set(['v', 'events']);
+    const evKeys = v2 ? V2_EVENT_KEYS : V1_EVENT_KEYS;
+    for (const k of Object.keys(o))
+        if (!rootKeys.has(k))
+            errs.push(`unknown field \`${k}\` (allowed: ${[...rootKeys].join(', ')})`);
+    if (v2 && (typeof o.axis !== 'string' || !o.axis.trim()))
+        errs.push('`axis` must be a non-empty string (e.g. time, frame, line, index)');
+    if (!Array.isArray(o.events)) {
+        errs.push('`events` must be an array');
+        return errs;
+    }
+    let prev = -Infinity;
+    o.events.forEach((e, i) => {
+        if (typeof e !== 'object' || e === null || Array.isArray(e)) {
+            errs.push(`events[${i}] must be an object`);
+            return;
+        }
+        const ev = e;
+        for (const k of Object.keys(ev))
+            if (!evKeys.has(k))
+                errs.push(`events[${i}]: unknown field \`${k}\` (allowed: ${[...evKeys].join(', ')})`);
+        const pos = ev[posKey];
+        if (typeof pos !== 'number' || !Number.isFinite(pos) || pos < 0) {
+            errs.push(`events[${i}].${posKey} must be a finite number ≥ 0`);
+        }
+        else {
+            if (pos < prev)
+                errs.push(`events[${i}].${posKey} is out of order (the list is ordered by position)`);
+            prev = pos;
+        }
+        if (typeof ev.step !== 'string' || !ev.step.trim())
+            errs.push(`events[${i}].step must be a non-empty string`);
+        if (ev.node !== undefined && (typeof ev.node !== 'string' || !ev.node.trim()))
+            errs.push(`events[${i}].node must be a non-empty string when present`);
+    });
+    return errs;
+}
+export function normalizeTimeline(raw) {
+    const o = (raw ?? {});
+    const events = Array.isArray(o.events) ? o.events : [];
+    if (o.v === 1)
+        return { axis: 'time', events: events.map((e) => ({ at: e.tMs, step: e.step, ...(e.node ? { node: e.node } : {}) })) };
+    return { axis: typeof o.axis === 'string' ? o.axis : 'time', events: events.map((e) => ({ at: e.at, step: e.step, ...(e.node ? { node: e.node } : {}) })) };
+}
+export function stepAt(events, pos) {
+    let hit = null;
+    for (const e of events) {
+        if (e.at <= pos)
+            hit = e;
+        else
+            break;
+    }
+    return hit;
+}

package/dist/ui-path.d.ts

@@ -0,0 +1 @@
+export declare const isUiPath: (p: string) => boolean;

package/dist/ui-path.js

@@ -0,0 +1,2 @@
+const UI_FILE = /\.(jsx|tsx|vue|svelte|css)$/;
+export const isUiPath = (p) => UI_FILE.test(p) || p.includes('spec-dashboard/');

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@spexcode/spec-eval",
+  "version": "0.6.5",
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js",
+    "./sessioneval": "./dist/sessioneval.js",
+    "./evaltab": "./dist/evaltab.js",
+    "./cli": "./dist/cli.js",
+    "./cache": "./dist/cache.js",
+    "./filing": "./dist/filing.js",
+    "./humanok": "./dist/humanok.js",
+    "./scenarios": "./dist/scenarios.js",
+    "./host": "./dist/host.js",
+    "./remarks": "./dist/remarks.js",
+    "./package.json": "./package.json"
+  },
+  "files": ["dist"],
+  "description": "The eval/loss engine \u2014 eval.md declares scenarios, a flat evals.ndjson sidecar records readings (a second git-as-database axis), freshness compares each reading's stored scenario-contract hash and git ancestry on its governed code, and evidence lives content-addressed under the shared git common dir. `spex eval add|ls|scenario ls|lint|retract|clean`.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node ../scripts/build-dist.mjs",
+    "prepublishOnly": "node ../scripts/release-publish.mjs --from-package-publish",
+    "test": "tsx --import ../scripts/test-home.mjs --test src/*.test.ts"
+  },
+  "dependencies": {
+    "@spexcode/spec-core": "0.6.5"
+  },
+  "devDependencies": {
+    "@types/node": "^20.16.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.3"
+  }
+}