@skill-harness/adapters 0.16.0 → 0.18.0

package/dist/learning-journal.js

@@ -1,256 +0,0 @@
-import { constants, openSync, closeSync, readSync, writeSync, fstatSync, lstatSync, fsyncSync, mkdirSync, unlinkSync } from 'node:fs';
-import { createHash, randomUUID } from 'node:crypto';
-import { types } from 'node:util';
-import { isAbsolute, join, dirname, parse, resolve } from 'node:path';
-import { interventionCanonicalJson } from '@skill-harness/core';
-export function learningJson(value) {
-    const limit = 2 * 1024 * 1024, cache = new WeakMap(), visiting = new WeakSet();
-    const size = (v, depth) => {
-        if (depth > 16)
-            throw Error('learning JSON depth bound');
-        if (v === null || typeof v === 'boolean' || typeof v === 'string' || typeof v === 'number' && Number.isFinite(v)) {
-            if (typeof v === 'string' && Buffer.byteLength(v) > limit)
-                throw Error('learning JSON byte bound');
-            const bytes = Buffer.byteLength(JSON.stringify(v));
-            if (bytes > limit)
-                throw Error('learning JSON byte bound');
-            return { bytes, height: 0 };
-        }
-        if (!v || typeof v !== 'object')
-            throw Error('plain learning JSON required');
-        if (types.isProxy(v))
-            throw Error('learning proxy refused');
-        const old = cache.get(v);
-        if (old) {
-            if (depth + old.height > 16)
-                throw Error('learning JSON depth bound');
-            return old;
-        }
-        if (visiting.has(v))
-            throw Error('cyclic learning JSON refused');
-        visiting.add(v);
-        const array = Array.isArray(v), prototype = Object.getPrototypeOf(v), descriptors = Object.getOwnPropertyDescriptors(v);
-        if (array ? prototype !== Array.prototype : prototype !== Object.prototype && prototype !== null)
-            throw Error('plain learning JSON required');
-        const keys = Reflect.ownKeys(descriptors);
-        if (array && (v.length > 4096 || keys.length !== v.length + 1))
-            throw Error('dense bounded learning array required');
-        const fields = array ? Array.from({ length: v.length }, (_, i) => String(i)) : keys;
-        let bytes = 2, height = 0;
-        for (let i = 0; i < fields.length; i++) {
-            const key = fields[i];
-            if (typeof key !== 'string')
-                throw Error('plain learning property required');
-            const d = descriptors[key];
-            if (!d || !('value' in d) || !d.enumerable)
-                throw Error('plain learning property required');
-            const child = size(d.value, depth + 1);
-            bytes += child.bytes + (i ? 1 : 0) + (array ? 0 : Buffer.byteLength(JSON.stringify(key)) + 1);
-            height = Math.max(height, child.height + 1);
-            if (bytes > limit)
-                throw Error('learning JSON byte bound');
-        }
-        visiting.delete(v);
-        const result = { bytes, height };
-        cache.set(v, result);
-        return result;
-    };
-    size(value, 0);
-    return interventionCanonicalJson(value);
-}
-export const learningHash = (value) => createHash('sha256').update(learningJson(value)).digest('hex');
-export const learningCopy = (value) => JSON.parse(learningJson(value));
-const LIMIT = 4 * 1024 * 1024;
-function directory(path) {
-    if (!isAbsolute(path))
-        throw Error('absolute learning directory required');
-    for (let p = path;; p = dirname(p)) {
-        const s = lstatSync(p);
-        if (!s.isDirectory() || s.isSymbolicLink())
-            throw Error('learning directory substitution');
-        if (p === parse(p).root)
-            break;
-    }
-    const s = lstatSync(path);
-    if ((s.mode & 0o077) || (process.getuid && s.uid !== process.getuid()))
-        throw Error('private owned learning directory required');
-}
-function sync(path) { const fd = openSync(path, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW); try {
-    fsyncSync(fd);
-}
-finally {
-    closeSync(fd);
-} }
-export function learningFile(path, limit = 1024 * 1024) {
-    if (!constants.O_NOFOLLOW || !constants.O_NONBLOCK)
-        throw Error('required safe file flags unavailable');
-    if (!isAbsolute(path))
-        throw Error('absolute learning file required');
-    // Reject every symlink ancestor, but do not require public parent directories to be private.
-    for (let p = dirname(path);; p = dirname(p)) {
-        const s = lstatSync(p);
-        if (!s.isDirectory() || s.isSymbolicLink())
-            throw Error('learning file ancestor substitution');
-        if (p === parse(p).root)
-            break;
-    }
-    const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
-    try {
-        const s = fstatSync(fd);
-        if (!s.isFile() || s.nlink !== 1 || s.size > limit)
-            throw Error('bounded regular learning file required');
-        const out = Buffer.alloc(limit + 1);
-        let n = 0;
-        while (n < out.length) {
-            const k = readSync(fd, out, n, out.length - n, n);
-            if (!k)
-                break;
-            n += k;
-        }
-        if (n > limit)
-            throw Error('learning file bound exceeded');
-        return out.subarray(0, n);
-    }
-    finally {
-        closeSync(fd);
-    }
-}
-/** Shared durable CAS for the weekly supervisor and trust lifecycle. Trusted cooperative filesystem,
- * not hostile same-UID rollback protection. A stranded claim is never automatically recovered. */
-export function learningJournal(path, initial) {
-    if (!constants.O_NOFOLLOW || !constants.O_NONBLOCK || !constants.O_DIRECTORY)
-        throw Error('required safe journal flags unavailable');
-    if (initial !== undefined) {
-        directory(dirname(path));
-        mkdirSync(path, { mode: 0o700 });
-        directory(path);
-        const value = learningCopy(initial), body = { prior: null, value }, record = { ...body, id: learningHash(body) };
-        const fd = openSync(join(path, 'events.jsonl'), constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
-        try {
-            writeAll(fd, Buffer.from(learningJson(record) + '\n'));
-            fsyncSync(fd);
-        }
-        finally {
-            closeSync(fd);
-        }
-        sync(path);
-        sync(dirname(path));
-    }
-    directory(path);
-    const identity = lstatSync(path), file = join(path, 'events.jsonl');
-    const check = () => { directory(path); const s = lstatSync(path); if (s.dev !== identity.dev || s.ino !== identity.ino)
-        throw Error('learning directory identity changed'); };
-    const read = () => {
-        check();
-        const stat = lstatSync(file);
-        if ((stat.mode & 0o077) || (process.getuid && stat.uid !== process.getuid()))
-            throw Error('private learning journal required');
-        const text = learningFile(file, LIMIT).toString('utf8');
-        if (!text.endsWith('\n'))
-            throw Error('learning history incomplete');
-        const lines = text.slice(0, -1).split('\n');
-        if (!lines.length || lines.length > 4096)
-            throw Error('learning history bound');
-        let prior = null;
-        return lines.map(line => { const r = JSON.parse(line); if (learningJson(r) !== line || Object.keys(r).sort().join() !== 'id,prior,value' || r.prior !== prior || r.id !== learningHash({ prior, value: r.value }))
-            throw Error('learning history identity mismatch'); prior = r.id; return r; });
-    };
-    read();
-    return { read, append(prior, value) {
-            check();
-            const lock = join(path, 'writer.lock'), token = randomUUID();
-            const fd = openSync(lock, constants.O_RDWR | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600), owned = fstatSync(fd);
-            let error, result;
-            try {
-                writeAll(fd, Buffer.from(token));
-                fsyncSync(fd);
-                const history = read();
-                if (history.at(-1).id !== prior)
-                    throw Error('stale learning CAS');
-                if (history.length >= 4096)
-                    throw Error('learning history bound');
-                const body = { prior, value: learningCopy(value) }, event = { ...body, id: learningHash(body) }, line = Buffer.from(learningJson(event) + '\n');
-                const out = openSync(file, constants.O_WRONLY | constants.O_APPEND | constants.O_NOFOLLOW | constants.O_NONBLOCK);
-                try {
-                    const s = fstatSync(out);
-                    if (!s.isFile() || s.nlink !== 1 || (s.mode & 0o077) || s.size + line.length > LIMIT)
-                        throw Error('learning append refused');
-                    writeAll(out, line);
-                    fsyncSync(out);
-                }
-                finally {
-                    closeSync(out);
-                }
-                sync(path);
-                result = event;
-            }
-            catch (e) {
-                error = e;
-            }
-            finally {
-                try {
-                    const s = lstatSync(lock);
-                    if (s.dev !== owned.dev || s.ino !== owned.ino || learningFile(lock, 128).toString() !== token)
-                        throw Error('learning lock ownership lost');
-                    unlinkSync(lock);
-                    sync(path);
-                }
-                catch (e) {
-                    error ??= e;
-                }
-                finally {
-                    try {
-                        closeSync(fd);
-                    }
-                    catch (e) {
-                        error ??= e;
-                    }
-                }
-            }
-            if (error)
-                throw error;
-            return result;
-        } };
-}
-/** One authoritative store per weekly key/policy in this archive; a renamed directory cannot refill it. */
-export function registerLearningStore(root, kind, key, target, binding) {
-    if (!/^[a-f0-9]{64}$/.test(key) || !isAbsolute(target) || !['weekly', 'trust', 'intervention', 'access', 'workspace'].includes(kind))
-        throw Error('invalid learning registration');
-    directory(root);
-    directory(dirname(target));
-    const parent = join(root, 'learning-stores');
-    try {
-        mkdirSync(parent, { mode: 0o700 });
-        sync(root);
-    }
-    catch (e) {
-        if (e.code !== 'EEXIST')
-            throw e;
-    }
-    directory(parent);
-    const path = join(parent, `${kind}-${key}`), initial = { type: 'learning-registration-v1', target: resolve(target), binding };
-    try {
-        learningJournal(path, initial);
-    }
-    catch (e) {
-        if (e.code !== 'EEXIST')
-            throw e;
-        const records = learningJournal(path).read();
-        if (records.length !== 1 || learningHash(records[0].value) !== learningHash(initial))
-            throw Error('learning key already bound to another store or input');
-    }
-}
-export function verifyLearningStore(root, kind, key, target, binding) {
-    if (!/^[a-f0-9]{64}$/.test(key) || !isAbsolute(target))
-        throw Error('invalid learning registration');
-    const records = learningJournal(join(root, 'learning-stores', `${kind}-${key}`)).read();
-    if (records.length !== 1 || learningHash(records[0].value) !== learningHash({ type: 'learning-registration-v1', target: resolve(target), binding }))
-        throw Error('learning store registration mismatch');
-}
-function writeAll(fd, bytes) { let n = 0; while (n < bytes.length) {
-    const k = writeSync(fd, bytes, n, bytes.length - n);
-    if (!k)
-        throw Error('learning write stalled');
-    n += k;
-} }
-//# sourceMappingURL=learning-journal.js.map

package/dist/learning-lifecycle.d.ts

@@ -1,28 +0,0 @@
-export interface LearningLifecycleInput {
-    caseManifestId: string;
-    hypothesisManifestId: string;
-    comparisonManifestId: string;
-    choiceManifestId: string | null;
-    adoptionManifestId: string | null;
-    rollbackManifestId: string | null;
-    outcomeManifestIds: string[];
-    predecessorManifestId: string | null;
-}
-export type LearningLifecycleState = 'awaiting-human-choice' | 'decision-recorded' | 'adopted-awaiting-outcome' | 'rolled-back' | 'outcome-observed';
-export interface LearningLifecycleView {
-    version: 'retained-learning-lifecycle-v1';
-    state: LearningLifecycleState;
-    predecessorManifestId: string | null;
-    links: {
-        case: string;
-        hypothesis: string;
-        comparison: string;
-        choice: string | null;
-        adoption: string | null;
-        rollback: string | null;
-        outcomes: string[];
-    };
-}
-/** Retains navigation only. Linked artifacts retain their own semantics and authority. */
-export declare function retainLearningLifecycle(root: string, input: LearningLifecycleInput): string;
-export declare function readLearningLifecycle(root: string, manifestId: string): LearningLifecycleView;

package/dist/learning-lifecycle.js

@@ -1,66 +0,0 @@
-import { readArchiveSource, retainArchiveSource } from './evidence-archive.js';
-const SHA = /^[a-f0-9]{64}$/;
-const closed = (value, names) => !!value && typeof value === 'object' && !Array.isArray(value) && Object.keys(value).sort().join() === names.sort().join();
-function available(root, id, parser) {
-    if (!SHA.test(id))
-        throw Error('invalid retained learning link');
-    const source = readArchiveSource(root, id);
-    if (source.status !== 'available' || source.reference.retention !== 'exact' || parser && source.reference.parser.id !== parser)
-        throw Error('retained learning link unavailable');
-    return source;
-}
-function validate(root, input, depth = 0) {
-    if (depth > 64)
-        throw Error('learning lifecycle predecessor bound exceeded');
-    if (!closed(input, ['caseManifestId', 'hypothesisManifestId', 'comparisonManifestId', 'choiceManifestId', 'adoptionManifestId', 'rollbackManifestId', 'outcomeManifestIds', 'predecessorManifestId']) || !Array.isArray(input.outcomeManifestIds) || input.outcomeManifestIds.length > 64 || new Set(input.outcomeManifestIds).size !== input.outcomeManifestIds.length)
-        throw Error('invalid bounded learning lifecycle');
-    for (const id of [input.caseManifestId, input.hypothesisManifestId, input.comparisonManifestId])
-        available(root, id);
-    for (const id of [input.choiceManifestId, input.adoptionManifestId, input.rollbackManifestId, ...input.outcomeManifestIds])
-        if (id !== null)
-            available(root, id);
-    if (input.adoptionManifestId && !input.choiceManifestId)
-        throw Error('quality choice required before adoption');
-    if (input.rollbackManifestId && !input.adoptionManifestId)
-        throw Error('adoption required before rollback');
-    if (input.outcomeManifestIds.length && !input.adoptionManifestId)
-        throw Error('adoption required before outcomes');
-    if (input.predecessorManifestId) {
-        const prior = read(root, input.predecessorManifestId, depth + 1);
-        if (prior.links.case !== input.caseManifestId || prior.links.hypothesis !== input.hypothesisManifestId || prior.links.comparison !== input.comparisonManifestId)
-            throw Error('learning lifecycle identity changed');
-        for (const key of ['choice', 'adoption', 'rollback'])
-            if (prior.links[key] !== null && prior.links[key] !== ({ choice: input.choiceManifestId, adoption: input.adoptionManifestId, rollback: input.rollbackManifestId })[key])
-                throw Error('learning lifecycle cannot regress or replace decisions');
-        if (prior.links.outcomes.some((id, index) => input.outcomeManifestIds[index] !== id))
-            throw Error('learning lifecycle cannot regress or replace outcomes');
-    }
-    const state = input.outcomeManifestIds.length ? 'outcome-observed' : input.rollbackManifestId ? 'rolled-back' : input.adoptionManifestId ? 'adopted-awaiting-outcome' : input.choiceManifestId ? 'decision-recorded' : 'awaiting-human-choice';
-    return { version: 'retained-learning-lifecycle-v1', state, predecessorManifestId: input.predecessorManifestId, links: { case: input.caseManifestId, hypothesis: input.hypothesisManifestId, comparison: input.comparisonManifestId, choice: input.choiceManifestId, adoption: input.adoptionManifestId, rollback: input.rollbackManifestId, outcomes: [...input.outcomeManifestIds] } };
-}
-/** Retains navigation only. Linked artifacts retain their own semantics and authority. */
-export function retainLearningLifecycle(root, input) {
-    const view = validate(root, input);
-    return retainArchiveSource(root, { sourceId: `learning-${view.links.comparison.slice(0, 24)}`, parser: { id: 'learning-lifecycle', version: '1' }, retention: 'exact', bytes: Buffer.from(JSON.stringify(view)) }).manifestId;
-}
-function read(root, manifestId, depth) {
-    if (depth > 64)
-        throw Error('learning lifecycle predecessor bound exceeded');
-    const source = available(root, manifestId, 'learning-lifecycle');
-    let value;
-    try {
-        value = JSON.parse(source.bytes.toString('utf8'));
-    }
-    catch {
-        throw Error('invalid retained learning lifecycle');
-    }
-    if (!closed(value, ['version', 'state', 'predecessorManifestId', 'links']) || value.version !== 'retained-learning-lifecycle-v1' || !closed(value.links, ['case', 'hypothesis', 'comparison', 'choice', 'adoption', 'rollback', 'outcomes']))
-        throw Error('invalid retained learning lifecycle');
-    const links = value.links;
-    const rebuilt = validate(root, { caseManifestId: links.case, hypothesisManifestId: links.hypothesis, comparisonManifestId: links.comparison, choiceManifestId: links.choice, adoptionManifestId: links.adoption, rollbackManifestId: links.rollback, outcomeManifestIds: links.outcomes, predecessorManifestId: value.predecessorManifestId }, depth);
-    if (rebuilt.state !== value.state || JSON.stringify(rebuilt) !== source.bytes.toString('utf8'))
-        throw Error('retained learning lifecycle changed');
-    return Object.freeze({ ...rebuilt, links: Object.freeze({ ...rebuilt.links, outcomes: Object.freeze(rebuilt.links.outcomes) }) });
-}
-export function readLearningLifecycle(root, manifestId) { return read(root, manifestId, 0); }
-//# sourceMappingURL=learning-lifecycle.js.map

package/dist/learning-trust-setup.d.ts

@@ -1,64 +0,0 @@
-import type { CalibrationPrediction, CalibrationSplit, ExposurePolicy } from '@skill-harness/core';
-import type { LearningCaseReference } from './learning-case.js';
-import { type TrustLifecycleInput } from './trust-lifecycle.js';
-export interface LearningTrustSetup {
-    caseName: string;
-    detectorId: string;
-    split: CalibrationSplit;
-    maxUnflagged: number;
-    unflagged: {
-        incidentId: string;
-        manifestId: string;
-        split: CalibrationSplit;
-    }[];
-    exposure: Omit<ExposurePolicy, 'component' | 'kind' | 'split'> | null;
-}
-/** Forms construct a frozen cohort from actual selected cases. Repeated observations of the
- * same target are ONE incident; a detector nomination never becomes its own reference label. */
-export declare function previewLearningTrust(directory: string, raw: LearningTrustSetup): {
-    input: TrustLifecycleInput;
-    policyDigest: string;
-    predictions: CalibrationPrediction[];
-    nominationCount: number;
-    independentIncidentCount: number;
-    caseManifestIds: string[];
-    labelsCreated: 0;
-    excludedOtherDetectors: number;
-};
-export declare function configureLearningTrust(directory: string, options: LearningTrustSetup, authorizedPolicyDigests: readonly string[]): {
-    policyId: string;
-    component: import("@skill-harness/core").CalibrationComponent;
-    calibration: {
-        version: "factory-calibration-v1";
-        reports: import("@skill-harness/core").CalibrationReport[];
-        excludedTuning: number;
-        referenceBasis: "independently-supplied-host-context";
-        advisoryOnly: true;
-    };
-    sampledIncidentIds: string[];
-    unflagged: {
-        sampled: number;
-        resolved: number;
-        misses: number;
-        unresolved: number;
-        conflicted: number;
-    };
-    attentionUsed: number;
-    retired: boolean;
-    exposures: {
-        mode: "ask" | "silent" | "retire";
-        reason: string;
-        id: string;
-    }[];
-    tip: string;
-    grantExpansion: false;
-};
-/** Selected case reference, not a retyped verdict. Separate explicit reference authority is
- * still required by linkCaseOutcome; this only supplies the exact preview to the operator. */
-export declare function previewLearningCaseLabel(directory: string, reference: LearningCaseReference): {
-    outcome: import("./trust-lifecycle.js").TrustReferenceOutcome;
-    caseReference: LearningCaseReference;
-    digest: string;
-    tip: string;
-    predictionId: string;
-};

package/dist/learning-trust-setup.js

@@ -1,55 +0,0 @@
-import { learningCopy, learningHash } from './learning-journal.js';
-import { openLearningWorkspace } from './learning-workspace.js';
-import { trustPolicyDigest } from './trust-lifecycle.js';
-/** Forms construct a frozen cohort from actual selected cases. Repeated observations of the
- * same target are ONE incident; a detector nomination never becomes its own reference label. */
-export function previewLearningTrust(directory, raw) {
-    const options = learningCopy(raw), workspace = openLearningWorkspace(directory), config = workspace.configuration();
-    if (Object.keys(options).sort().join() !== 'caseName,detectorId,exposure,maxUnflagged,split,unflagged' || !['calibration', 'heldout', 'tuning'].includes(options.split) || !Array.isArray(options.unflagged) || options.unflagged.length > 1024)
-        throw Error('closed trust setup required');
-    const page = workspace.cases(options.caseName), items = [...page.items];
-    for (let offset = 5; offset < page.total; offset += 5)
-        items.push(...workspace.cases(options.caseName, offset).items);
-    const chosen = items.filter(c => c.candidate.detector.id === options.detectorId);
-    if (!chosen.length)
-        throw Error('selected detector has no retained cases');
-    const component = { kind: 'detector', ...chosen[0].candidate.detector };
-    if (chosen.some(c => learningHash(c.candidate.detector) !== learningHash(chosen[0].candidate.detector)))
-        throw Error('detector versions/populations must be calibrated separately');
-    const binding = workspace.inspect(0).cases.find(b => b.name === options.caseName);
-    if (!binding || binding.state !== 'ready')
-        throw Error('case binding unavailable');
-    const incidents = new Map();
-    for (const c of chosen) {
-        const id = learningHash({ target: c.candidate.target, population: component.population });
-        if (!incidents.has(id))
-            incidents.set(id, c);
-    }
-    const cohort = [...[...incidents].map(([incidentId, c]) => ({ incidentId, manifestId: c.caseManifestId, flagged: true, split: options.split })), ...options.unflagged.map(c => ({ ...c, flagged: false }))];
-    const input = { archiveRoot: config.archiveRoot, component, seed: learningHash({ scope: config.scopeDigest, component, cohort }), maxUnflagged: options.maxUnflagged, cohort,
-        exposure: options.exposure ? { ...options.exposure, component, kind: 'positive', split: options.split === 'tuning' ? 'calibration' : options.split } : null };
-    const predictions = [...incidents].map(([incidentId]) => ({ id: learningHash({ incidentId, component, split: options.split }), incidentId, component, kind: 'positive', split: options.split }));
-    return { input, policyDigest: trustPolicyDigest(input), predictions, nominationCount: chosen.length, independentIncidentCount: incidents.size,
-        caseManifestIds: [...incidents.values()].map(c => c.caseManifestId), labelsCreated: 0, excludedOtherDetectors: items.length - chosen.length };
-}
-export function configureLearningTrust(directory, options, authorizedPolicyDigests) {
-    const preview = previewLearningTrust(directory, options), workspace = openLearningWorkspace(directory);
-    workspace.configureTrust(preview.input, authorizedPolicyDigests);
-    for (const p of preview.predictions)
-        workspace.trust().predict(p);
-    return workspace.trust().inspect(0);
-}
-/** Selected case reference, not a retyped verdict. Separate explicit reference authority is
- * still required by linkCaseOutcome; this only supplies the exact preview to the operator. */
-export function previewLearningCaseLabel(directory, reference) {
-    const trust = openLearningWorkspace(directory).trust(), config = trust.configuration();
-    const row = config.cohort.find(c => c.flagged && c.manifestId === reference.manifestId);
-    if (!row)
-        throw Error('case outside frozen calibration cohort');
-    const predictions = trust.history().filter(e => e.value.type === 'prediction' || e.value.type === 'correction').map(e => e.value.prediction);
-    const p = predictions.filter(p => p.incidentId === row.incidentId).at(-1);
-    if (!p)
-        throw Error('prediction missing');
-    return { predictionId: p.id, ...trust.previewCaseOutcome(p.id, reference) };
-}
-//# sourceMappingURL=learning-trust-setup.js.map