@skill-harness/adapters 0.12.0 → 0.13.0

package/dist/work-case-review.js

@@ -0,0 +1,220 @@
+import { constants, closeSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { appendWorkCaseDecision } from "@skill-harness/core";
+import { readArchiveSource } from "./evidence-archive.js";
+import { readWorkCandidate } from "./work-case-archive.js";
+import { readWorkSignalBatch, readWorkSignalCase } from "./work-signal-cases.js";
+const SHA = /^[a-f0-9]{64}$/;
+const missing = (error) => error?.code === "ENOENT";
+function assertDirectory(path) {
+    const stat = lstatSync(path);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || (stat.mode & 0o077) || (process.getuid && stat.uid !== process.getuid()))
+        throw new Error("private case directory required");
+}
+function syncDirectory(path) {
+    const fd = openSync(path, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+    try {
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function privateDirectory(path) {
+    let created = false;
+    try {
+        mkdirSync(path, { mode: 0o700 });
+        created = true;
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+    }
+    assertDirectory(path);
+    return created;
+}
+function bytes(path, limit) {
+    const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        const stat = fstatSync(fd);
+        if (!stat.isFile() || stat.nlink !== 1 || stat.size > limit || (stat.mode & 0o077))
+            throw new Error("invalid case history file");
+        const out = Buffer.alloc(limit + 1);
+        let used = 0;
+        while (used <= limit) {
+            const n = readSync(fd, out, used, out.length - used, used);
+            if (!n)
+                break;
+            used += n;
+        }
+        if (used > limit)
+            throw new Error("case history bound exceeded");
+        return out.subarray(0, used);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function historyAt(directory, caseId, brandNew = false) {
+    let raw;
+    try {
+        raw = bytes(join(directory, "history.jsonl"), 1024 * 1024);
+    }
+    catch (error) {
+        if (missing(error) && brandNew)
+            return [];
+        if (missing(error))
+            throw new Error("case history missing; explicit recovery required");
+        throw error;
+    }
+    if (!raw.length || raw.at(-1) !== 10)
+        throw new Error("case history incomplete; explicit recovery required");
+    const records = raw.toString("utf8").trimEnd().split("\n").map(line => JSON.parse(line));
+    let valid = [];
+    for (const record of records) {
+        if (record.caseId !== caseId || record.decision_schema !== 1)
+            throw new Error("case history binding mismatch");
+        const { id, decision_schema: _schema, ...input } = record;
+        valid = appendWorkCaseDecision(valid, input);
+        if (!valid.some(r => r.id === id))
+            throw new Error("case history identity mismatch");
+    }
+    return valid;
+}
+function assertAuthor(author) {
+    if (typeof author !== "string" || !author || author.length > 512 || /[\u0000-\u001f\u007f]/.test(author))
+        throw new Error("explicit operator author required");
+}
+/** Operator-selected batch/author capability. Not user authentication, worker authority or scenario promotion. */
+export function createWorkCaseReviewer(root, batchId, author) {
+    assertAuthor(author);
+    const source = readArchiveSource(root, batchId);
+    if (source.status !== "available" || source.reference.parser.id !== "work-candidate-batch" || source.reference.parser.version !== "1" || source.reference.retention !== "exact")
+        throw new Error("case batch missing or invalid");
+    const batch = JSON.parse(source.bytes.toString("utf8"));
+    if (batch.version !== "work-candidate-batch-v1" || batch.visibility !== "silent" || batch.promotion !== "not-authorized"
+        || !Array.isArray(batch.candidateIds) || batch.candidateIds.length > 4096 || batch.candidateIds.some((id) => typeof id !== "string" || !SHA.test(id)))
+        throw new Error("invalid selected case batch");
+    return createSelectedCaseReviewer(root, author, batch.candidateIds, id => readWorkCandidate(root, id));
+}
+/** Explicit new signal contract; the existing v2 entry point still refuses these batches. */
+export function createWorkSignalReviewer(root, batchId, author) {
+    assertAuthor(author);
+    const batch = readWorkSignalBatch(root, batchId);
+    const reviewer = createSelectedCaseReviewer(root, author, batch.candidateIds, id => {
+        const selected = readWorkSignalCase(root, id);
+        if (selected.observationId !== batch.observationId)
+            throw new Error("work signal case outside frozen observation");
+        return selected.candidate;
+    });
+    return { ...reviewer, list(offset = 0, limit = 5) {
+            const current = readWorkSignalBatch(root, batchId);
+            return { ...reviewer.list(offset, limit), observationId: current.observationId, issues: current.issues };
+        } };
+}
+function createSelectedCaseReviewer(root, author, ids, readCandidate) {
+    const allowed = new Set(ids);
+    const selected = (id) => { if (!allowed.has(id))
+        throw new Error("case outside selected batch"); return readCandidate(id); };
+    const getHistory = (caseManifestId) => {
+        const candidate = selected(caseManifestId), directory = join(root, "case-decisions", candidate.id);
+        try {
+            assertDirectory(join(root, "case-decisions"));
+            assertDirectory(directory);
+        }
+        catch (error) {
+            if (missing(error))
+                return [];
+            throw error;
+        }
+        return historyAt(directory, candidate.id);
+    };
+    return {
+        history: getHistory,
+        list(offset = 0, limit = 5) {
+            if (!Number.isSafeInteger(offset) || offset < 0 || !Number.isSafeInteger(limit) || limit < 1 || limit > 5)
+                throw new Error("bounded case page required");
+            const ids = [...allowed].sort();
+            return { total: ids.length, offset, items: ids.slice(offset, offset + limit).map(caseManifestId => {
+                    const candidate = selected(caseManifestId), current = getHistory(caseManifestId).at(-1) ?? null;
+                    return { caseManifestId, candidate, priorDecisionId: current?.id ?? null, disposition: current?.disposition ?? "unresolved" };
+                }) };
+        },
+        decide(request) {
+            if (!request || Object.keys(request).sort().join() !== "caseManifestId,disposition,note,priorDecisionId"
+                || !["confirmed_defect", "expected_behavior", "exemplar", "uncertain", "skip"].includes(request.disposition)
+                || typeof request.note !== "string" || request.note.length > 4000
+                || !(request.priorDecisionId === null || (typeof request.priorDecisionId === "string" && SHA.test(request.priorDecisionId))))
+                throw new Error("invalid case review request");
+            const candidate = selected(request.caseManifestId);
+            const parent = join(root, "case-decisions");
+            privateDirectory(parent);
+            const directory = join(parent, candidate.id);
+            const lockPath = join(parent, candidate.id + ".lock"), token = randomUUID();
+            const lock = openSync(lockPath, constants.O_RDWR | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+            const identity = fstatSync(lock);
+            let primary;
+            let result;
+            try {
+                writeFileSync(lock, token);
+                fsyncSync(lock);
+                // Hold the case lock BEFORE first directory creation; concurrent first reviewers cannot poison initialization.
+                const brandNew = privateDirectory(directory);
+                const before = historyAt(directory, candidate.id, brandNew);
+                const after = appendWorkCaseDecision(before, { caseId: candidate.id, priorDecisionId: request.priorDecisionId,
+                    disposition: request.disposition, author, evidence: [request.caseManifestId], note: request.note });
+                if (after.length > before.length) {
+                    const path = join(directory, "history.jsonl");
+                    const fd = openSync(path, constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW | constants.O_NONBLOCK, 0o600);
+                    try {
+                        const stat = fstatSync(fd);
+                        if (!stat.isFile() || stat.nlink !== 1 || (stat.mode & 0o077))
+                            throw new Error("invalid case history destination");
+                        const line = Buffer.from(JSON.stringify(after.at(-1)) + "\n");
+                        if (stat.size + line.length > 1024 * 1024)
+                            throw new Error("case history bound exceeded");
+                        let offset = 0;
+                        while (offset < line.length) {
+                            const n = writeSync(fd, line, offset, line.length - offset);
+                            if (!n)
+                                throw new Error("case history write stalled");
+                            offset += n;
+                        }
+                        fsyncSync(fd);
+                    }
+                    finally {
+                        closeSync(fd);
+                    }
+                }
+                syncDirectory(directory);
+                syncDirectory(parent);
+                syncDirectory(root);
+                result = { current: after.at(-1), replayed: after.length === before.length };
+            }
+            catch (error) {
+                primary = error;
+            }
+            finally {
+                try {
+                    const present = lstatSync(lockPath);
+                    if (present.dev !== identity.dev || present.ino !== identity.ino || bytes(lockPath, 128).toString() !== token)
+                        throw new Error("case writer lock ownership lost");
+                    unlinkSync(lockPath);
+                    syncDirectory(parent);
+                }
+                catch (error) {
+                    if (!primary)
+                        primary = error;
+                }
+                finally {
+                    closeSync(lock);
+                }
+            }
+            if (primary)
+                throw primary;
+            return result;
+        },
+    };
+}
+//# sourceMappingURL=work-case-review.js.map

package/dist/work-signal-cases.d.ts

@@ -0,0 +1,15 @@
+/** Case records point to frozen inputs, not cached verdicts or caller-authored authority. */
+export declare function captureWorkSignalCases(root: string, observationId: string): {
+    batchId: string;
+    observationId: string;
+    candidateIds: string[];
+};
+export declare function readWorkSignalCase(root: string, manifestId: string): {
+    observationId: string;
+    candidate: import("@skill-harness/core").WorkCaptureCaseV2 | import("@skill-harness/core").WorkCaptureCaseV3;
+};
+export declare function readWorkSignalBatch(root: string, manifestId: string): {
+    observationId: string;
+    candidateIds: string[];
+    issues: string[];
+};

package/dist/work-signal-cases.js

@@ -0,0 +1,54 @@
+import { readArchiveSource, retainArchiveSource } from "./evidence-archive.js";
+import { readWorkSignalObservation } from "./work-signal-observation.js";
+const SHA = /^[a-f0-9]{64}$/;
+const hash = (v) => typeof v === "string" && SHA.test(v);
+function read(root, id, parser) {
+    const source = readArchiveSource(root, id);
+    if (source.status !== "available" || source.reference.retention !== "exact" || source.reference.parser.id !== parser || source.reference.parser.version !== "1"
+        || source.bytes.length > 128 * 1024)
+        throw new Error("work signal case evidence unavailable or unsupported");
+    let value;
+    try {
+        value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(source.bytes));
+    }
+    catch {
+        throw new Error("invalid work signal case JSON");
+    }
+    return { value, sourceId: source.reference.sourceId };
+}
+function closed(v, keys) {
+    if (!v || typeof v !== "object" || Array.isArray(v) || Object.keys(v).sort().join() !== [...keys].sort().join())
+        throw new Error("invalid closed work signal case record");
+}
+function retain(root, sourceId, parser, value) {
+    return retainArchiveSource(root, { sourceId, parser: { id: parser, version: "1" }, retention: "exact", bytes: Buffer.from(JSON.stringify(value)) }).manifestId;
+}
+/** Case records point to frozen inputs, not cached verdicts or caller-authored authority. */
+export function captureWorkSignalCases(root, observationId) {
+    const observation = readWorkSignalObservation(root, observationId);
+    const candidateIds = observation.detection.cases.map(candidate => retain(root, `work-signal-case-${candidate.id}`, "work-signal-case", { version: "work-signal-case-v1", observationId, caseId: candidate.id }));
+    const batchId = retain(root, `work-signal-batch-${observationId}`, "work-signal-batch", { version: "work-signal-batch-v1", observationId, candidateIds, visibility: "silent", promotion: "not-authorized" });
+    return { batchId, observationId, candidateIds };
+}
+export function readWorkSignalCase(root, manifestId) {
+    const { value, sourceId } = read(root, manifestId, "work-signal-case");
+    closed(value, ["version", "observationId", "caseId"]);
+    if (value.version !== "work-signal-case-v1" || !hash(value.observationId) || !hash(value.caseId) || sourceId !== `work-signal-case-${value.caseId}`)
+        throw new Error("work signal case binding mismatch");
+    const observation = readWorkSignalObservation(root, value.observationId);
+    const candidate = observation.detection.cases.find(c => c.id === value.caseId);
+    if (!candidate)
+        throw new Error("case is not nominated by frozen work signal inputs");
+    return { observationId: value.observationId, candidate };
+}
+export function readWorkSignalBatch(root, manifestId) {
+    const { value, sourceId } = read(root, manifestId, "work-signal-batch");
+    closed(value, ["version", "observationId", "candidateIds", "visibility", "promotion"]);
+    if (value.version !== "work-signal-batch-v1" || !hash(value.observationId) || sourceId !== `work-signal-batch-${value.observationId}`
+        || value.visibility !== "silent" || value.promotion !== "not-authorized" || !Array.isArray(value.candidateIds)
+        || value.candidateIds.length > 1024 || !value.candidateIds.every(hash) || new Set(value.candidateIds).size !== value.candidateIds.length)
+        throw new Error("invalid work signal batch binding");
+    const observation = readWorkSignalObservation(root, value.observationId);
+    return { observationId: value.observationId, candidateIds: value.candidateIds, issues: observation.detection.issues };
+}
+//# sourceMappingURL=work-signal-cases.js.map

package/dist/work-signal-observation.d.ts

@@ -0,0 +1,23 @@
+import { type WorkSignalFacts, type WorkSignalSnapshot } from "@skill-harness/core";
+interface WorkSignalInput {
+    observation_schema: "work-signal-observation-v1";
+    snapshot: WorkSignalSnapshot;
+    facts: WorkSignalFacts;
+}
+/** Explicit private host-fact retention, not automatic discovery, authenticated authority or case promotion. */
+export declare function retainWorkSignalObservation(root: string, snapshot: WorkSignalSnapshot, facts: WorkSignalFacts): {
+    manifestId: string;
+    inputSha256: string;
+};
+/** Re-derive, never trust a cached nomination. Missing/corrupt inputs fail rather than becoming empty work. */
+export declare function readWorkSignalObservation(root: string, manifestId: string): {
+    manifestId: string;
+    inputSha256: string;
+    input: WorkSignalInput;
+    detection: {
+        version: "work-signals-v1";
+        cases: (import("@skill-harness/core").WorkCaptureCaseV2 | import("@skill-harness/core").WorkCaptureCaseV3)[];
+        issues: string[];
+    };
+};
+export {};

package/dist/work-signal-observation.js

@@ -0,0 +1,89 @@
+import { detectAdditionalWorkCases } from "@skill-harness/core";
+import { readArchiveSource, retainArchiveSource } from "./evidence-archive.js";
+const LIMIT = 1024 * 1024;
+function closed(value, keys) {
+    if (!value || typeof value !== "object" || Array.isArray(value) || ![Object.prototype, null].includes(Object.getPrototypeOf(value)))
+        throw new Error("closed work signal object required");
+    const descriptors = Object.getOwnPropertyDescriptors(value), names = Reflect.ownKeys(value);
+    if (names.length !== keys.length || names.some(k => typeof k !== "string" || !keys.includes(k) || !descriptors[k].enumerable || !Object.hasOwn(descriptors[k], "value")))
+        throw new Error("closed work signal fields required");
+}
+function array(value) {
+    if (!Array.isArray(value) || Object.getPrototypeOf(value) !== Array.prototype || value.length > 256
+        || Reflect.ownKeys(value).length !== value.length + 1)
+        throw new Error("bounded dense work signal array required");
+    for (let i = 0; i < value.length; i++) {
+        const d = Object.getOwnPropertyDescriptor(value, String(i));
+        if (!d || !d.enumerable || !Object.hasOwn(d, "value"))
+            throw new Error("dense work signal data array required");
+    }
+}
+// Only called after closed primitive/shape validation. Arrays retain observation order.
+function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    if (value !== null && typeof value === "object")
+        return `{${Object.keys(value).sort().map(k => `${JSON.stringify(k)}:${canonical(value[k])}`).join(",")}}`;
+    return JSON.stringify(value);
+}
+function validate(value) {
+    closed(value, ["observation_schema", "snapshot", "facts"]);
+    if (value.observation_schema !== "work-signal-observation-v1")
+        throw new Error("unsupported work signal observation");
+    closed(value.snapshot, ["snapshotDigest", "scopeValid", "obligations"]);
+    closed(value.facts, ["scopeDigest", "version", "population", "expectedWaits", "checkpoints", "violations", "priorAccepted"]);
+    const s = value.snapshot, f = value.facts;
+    if (typeof s.scopeValid !== "boolean")
+        throw new Error("invalid work signal scope state");
+    array(s.obligations);
+    array(f.expectedWaits);
+    array(f.checkpoints);
+    array(f.violations);
+    array(f.priorAccepted);
+    const seen = new Set();
+    for (const o of s.obligations) {
+        closed(o, ["id", "digest", "intentDigest", "policyDigest", "artifactDigest", "acceptance", "coverage"]);
+        if (seen.has(o.digest))
+            throw new Error("duplicate work signal obligation identity");
+        seen.add(o.digest);
+    }
+    for (const c of f.checkpoints)
+        closed(c, ["obligationDigest", "deadlineMs", "observedAt", "status", "evidence"]);
+    for (const v of f.violations)
+        closed(v, ["obligationDigest", "status", "evidence"]);
+    for (const p of f.priorAccepted)
+        closed(p, ["obligationDigest", "intentDigest", "policyDigest", "artifactDigest", "acceptanceEvidence"]);
+    const input = value;
+    // Shared rules validate scalar types, exact scope, bounded timestamps, enums and evidence identities.
+    detectAdditionalWorkCases(input.snapshot, input.facts);
+    return input;
+}
+/** Explicit private host-fact retention, not automatic discovery, authenticated authority or case promotion. */
+export function retainWorkSignalObservation(root, snapshot, facts) {
+    const input = validate({ observation_schema: "work-signal-observation-v1", snapshot, facts });
+    const bytes = Buffer.from(canonical(input));
+    if (bytes.length > LIMIT)
+        throw new Error("work signal observation exceeds byte bound");
+    const stored = retainArchiveSource(root, { sourceId: `work-signals-${snapshot.snapshotDigest}`, parser: { id: "work-signal-observation", version: "1" }, retention: "exact", bytes });
+    return { manifestId: stored.manifestId, inputSha256: stored.reference.sha256 };
+}
+/** Re-derive, never trust a cached nomination. Missing/corrupt inputs fail rather than becoming empty work. */
+export function readWorkSignalObservation(root, manifestId) {
+    const stored = readArchiveSource(root, manifestId);
+    if (stored.status !== "available" || stored.reference.retention !== "exact" || stored.reference.parser.id !== "work-signal-observation"
+        || stored.reference.parser.version !== "1" || stored.bytes.length > LIMIT)
+        throw new Error("work signal observation unavailable or unsupported");
+    let text, decoded;
+    try {
+        text = new TextDecoder("utf-8", { fatal: true }).decode(stored.bytes);
+        decoded = JSON.parse(text);
+    }
+    catch {
+        throw new Error("invalid work signal observation JSON");
+    } // No raw byte excerpts in diagnostics.
+    const input = validate(decoded);
+    if (canonical(input) !== text || stored.reference.sourceId !== `work-signals-${input.snapshot.snapshotDigest}`)
+        throw new Error("work signal observation binding mismatch");
+    return { manifestId, inputSha256: stored.reference.sha256, input, detection: detectAdditionalWorkCases(input.snapshot, input.facts) };
+}
+//# sourceMappingURL=work-signal-observation.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@skill-harness/adapters",
-    "version": "0.12.0",
+    "version": "0.13.0",
     "description": "skill-harness harness adapters — pi runner + claude-code judge routing (internal API)",
     "type": "module",
     "license": "MIT",
@@ -40,6 +40,7 @@
         "prepack": "node ../../scripts/release-pack.mjs --guard"
     },
     "dependencies": {
-        "@skill-harness/core": "0.12.0"
+        "@skill-harness/core": "0.13.0",
+        "typebox": "1.3.4"
     }
 }