@skill-harness/adapters 0.15.0 → 0.16.0

package/dist/blind-intervention.d.ts

@@ -1,6 +1,11 @@
 import { type BlindQualityChoice, type InterventionManifest, type InterventionEvidence, type InterventionQualification } from "@skill-harness/core";
 /** Explicit private retention. Host role declarations are NOT authentication. No provider is called. */
 export declare function retainBlindIntervention(root: string, manifest: InterventionManifest, evidence: InterventionEvidence[], qualification: InterventionQualification, author: string): string;
+/** Opaque linkage metadata only; never exposes roles, arm identities or cost before choice. */
+export declare function readBlindInterventionBinding(root: string, id: string, author: string): Readonly<{
+    experimentDigest: string;
+    investigationDigest: string;
+}>;
 /** One immutable quality choice per comparison. Reopening cannot reset the reveal gate. */
 export declare function openBlindIntervention(root: string, id: string, author: string): Readonly<{
     view: () => {
@@ -12,6 +17,7 @@ export declare function openBlindIntervention(root: string, id: string, author:
         limitations: string[];
     };
     quality(): BlindQualityChoice | null;
+    previewChoice(input: BlindQualityChoice): BlindQualityChoice;
     readArtifact: (label: string, hash: string) => Buffer<ArrayBuffer>;
     choose(input: BlindQualityChoice): BlindQualityChoice;
     reveal(): {

package/dist/blind-intervention.js

@@ -90,7 +90,13 @@ function load(root, id, author) {
             throw new Error("blind artifact unavailable");
         artifacts.set(ref.hash, artifact.bytes);
     }
-    return createBlindComparison(bundle.manifest, assessIntervention(bundle.manifest, bundle.evidence, { ...bundle.qualification, artifacts }), bundle.seed);
+    const assessment = assessIntervention(bundle.manifest, bundle.evidence, { ...bundle.qualification, artifacts });
+    return { blind: createBlindComparison(bundle.manifest, assessment, bundle.seed), manifest: bundle.manifest };
+}
+/** Opaque linkage metadata only; never exposes roles, arm identities or cost before choice. */
+export function readBlindInterventionBinding(root, id, author) {
+    const { manifest } = load(root, id, author);
+    return Object.freeze({ experimentDigest: manifest.id, investigationDigest: manifest.investigationSha256 });
 }
 function directory(path) {
     const s = lstatSync(path);
@@ -159,10 +165,11 @@ function readChoice(root, id) {
 export function openBlindIntervention(root, id, author) {
     if (!SHA.test(id))
         throw new Error("invalid blind comparison identity");
-    const current = () => load(root, id, author);
+    const current = () => load(root, id, author).blind;
     return Object.freeze({
         view: () => current().view(),
         quality() { const blind = current(), choice = readChoice(root, id); return choice ? blind.choose(choice) : null; },
+        previewChoice(input) { return current().choose(input); },
         readArtifact: (label, hash) => current().readArtifact(label, hash),
         choose(input) {
             const blind = current(), choice = blind.choose(input);

package/dist/evidence-archive.d.ts

@@ -36,6 +36,14 @@ export declare function retainArchiveSource(root: string, input: ArchiveSourceIn
     manifestId: string;
     reference: ArchiveSourceReference;
 };
+export type ArchiveReferenceRead = {
+    status: 'available';
+    reference: ArchiveSourceReference;
+} | Exclude<ArchiveRead, {
+    status: 'available';
+}>;
+/** Metadata only for explicit archive inventory. Does not claim content availability. */
+export declare function readArchiveSourceReference(root: string, manifestId: string): ArchiveReferenceRead;
 export declare function readArchiveSource(root: string, manifestId: string, maxBytes?: number): ArchiveRead;
 export interface ArchivedJsonl {
     status: "complete" | "partial" | "error";

package/dist/evidence-archive.js

@@ -149,27 +149,31 @@ export function retainArchiveSource(root, input) {
     syncDirectory(resolve(root));
     return { manifestId, reference };
 }
-export function readArchiveSource(root, manifestId, maxBytes = LIMIT) {
-    if (!Number.isSafeInteger(maxBytes) || maxBytes < 0 || maxBytes > LIMIT)
-        return { status: "error", reason: "invalid read bound" };
+/** Metadata only for explicit archive inventory. Does not claim content availability. */
+export function readArchiveSourceReference(root, manifestId) {
     if (!HASH.test(manifestId))
-        return { status: "error", reason: "invalid manifest identity" };
+        return { status: 'error', reason: 'invalid manifest identity' };
     try {
-        let manifest;
-        try {
-            directory(root, false);
-            directory(join(root, "manifests"), false);
-            manifest = readVerified(join(root, "manifests", manifestId), manifestId, 8192);
-        }
-        catch (error) {
-            if (absent(error))
-                return { status: "missing", reason: "manifest" };
-            throw error;
-        }
-        const text = manifest.toString("utf8");
+        directory(root, false);
+        directory(join(root, 'manifests'), false);
+        const text = readVerified(join(root, 'manifests', manifestId), manifestId, 8192).toString('utf8');
         const reference = JSON.parse(text);
         if (!validReference(reference) || JSON.stringify(reference) !== text)
-            fail("invalid manifest");
+            fail('invalid manifest');
+        return { status: 'available', reference };
+    }
+    catch (error) {
+        return absent(error) ? { status: 'missing', reason: 'manifest' } : { status: 'error', reason: 'invalid or inaccessible retained evidence' };
+    }
+}
+export function readArchiveSource(root, manifestId, maxBytes = LIMIT) {
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 0 || maxBytes > LIMIT)
+        return { status: "error", reason: "invalid read bound" };
+    try {
+        const manifest = readArchiveSourceReference(root, manifestId);
+        if (manifest.status !== 'available')
+            return manifest;
+        const { reference } = manifest;
         if (reference.retention === "reference-only")
             return { status: "missing", reason: "not-retained" };
         if (reference.bytes > maxBytes)

package/dist/index.d.ts

@@ -19,6 +19,10 @@ export * from "./archive-read-capability.js";
 export * from "./archived-work.js";
 export * from "./blind-intervention.js";
 export * from "./learning-lifecycle.js";
+export * from "./learning-workspace.js";
+export * from "./learning-trust-setup.js";
+export { learningHash, learningFile } from "./learning-journal.js";
+export * from "./learning-case.js";
 export * from "./archive-observer.js";
 export * from "./weekly-investigation.js";
 export * from "./intervention-run.js";

package/dist/index.js

@@ -31,6 +31,10 @@ export * from "./archive-read-capability.js";
 export * from "./archived-work.js";
 export * from "./blind-intervention.js";
 export * from "./learning-lifecycle.js";
+export * from "./learning-workspace.js";
+export * from "./learning-trust-setup.js";
+export { learningHash, learningFile } from "./learning-journal.js";
+export * from "./learning-case.js";
 export * from "./archive-observer.js";
 export * from "./weekly-investigation.js";
 export * from "./intervention-run.js";

package/dist/learning-journal.d.ts

@@ -14,5 +14,5 @@ export declare function learningJournal(path: string, initial?: Record<string, u
     append(prior: string, value: Record<string, unknown>): LearningEvent;
 };
 /** One authoritative store per weekly key/policy in this archive; a renamed directory cannot refill it. */
-export declare function registerLearningStore(root: string, kind: 'weekly' | 'trust' | 'intervention' | 'access', key: string, target: string, binding: string): void;
-export declare function verifyLearningStore(root: string, kind: 'weekly' | 'trust' | 'intervention' | 'access', key: string, target: string, binding: string): void;
+export declare function registerLearningStore(root: string, kind: 'weekly' | 'trust' | 'intervention' | 'access' | 'workspace', key: string, target: string, binding: string): void;
+export declare function verifyLearningStore(root: string, kind: 'weekly' | 'trust' | 'intervention' | 'access' | 'workspace', key: string, target: string, binding: string): void;

package/dist/learning-journal.js

@@ -214,7 +214,7 @@ export function learningJournal(path, initial) {
 }
 /** 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'].includes(kind))
+    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));

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

@@ -0,0 +1,64 @@
+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

@@ -0,0 +1,55 @@
+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