@oscharko-dev/keiko 0.1.0-beta.0

package/dist/verification/classify.d.ts

@@ -0,0 +1,10 @@
+import type { CommandResult } from "../tools/index.js";
+import type { VerificationStatus } from "./types.js";
+export type AbortReason = "harness" | "memory" | undefined;
+export interface OutcomeInput {
+    readonly skipped: boolean;
+    readonly result: CommandResult | undefined;
+    readonly error: unknown;
+    readonly abortReason: AbortReason;
+}
+export declare function classifyOutcome(input: OutcomeInput): VerificationStatus;

package/dist/verification/classify.js

@@ -0,0 +1,53 @@
+// PURE outcome classification (ADR-0007 D1). The single authority mapping a settled runCommand
+// outcome — a resolved CommandResult OR a rejection — plus the orchestrator's abortReason to a
+// VerificationStatus. No IO, no spawn, no clock: the orchestrator owns all effects and calls this
+// once per step. The precedence is fixed and the first match wins; each branch is independently
+// unit-tested so a single-line mutation is caught.
+import { CommandCancelledError, CommandDeniedError, CommandTimeoutError } from "../tools/index.js";
+function classifyError(error, abortReason) {
+    if (error instanceof CommandDeniedError) {
+        return "denied";
+    }
+    if (abortReason === "memory") {
+        return "resource-exceeded";
+    }
+    if (abortReason === "harness") {
+        return "cancelled";
+    }
+    if (error instanceof CommandTimeoutError) {
+        return "timed-out";
+    }
+    if (error instanceof CommandCancelledError) {
+        // D1 branch 6's `memory → resource-exceeded` sub-case is handled earlier by branch 3
+        // (`abortReason === "memory"` returns before we reach here), so a CommandCancelledError that
+        // survives to this point is, by construction, a harness/plain cancellation.
+        return "cancelled";
+    }
+    return "failed";
+}
+function classifyResult(result) {
+    if (result.timedOut) {
+        return "timed-out";
+    }
+    if (result.truncated) {
+        return "resource-exceeded";
+    }
+    if (result.exitCode === 0) {
+        return "passed";
+    }
+    return "failed";
+}
+export function classifyOutcome(input) {
+    if (input.skipped) {
+        return "skipped";
+    }
+    if (input.error !== undefined) {
+        return classifyError(input.error, input.abortReason);
+    }
+    if (input.result !== undefined) {
+        return classifyResult(input.result);
+    }
+    // No result and no error is not a reachable runCommand settle state; treat as failed defensively
+    // at this internal boundary so the function is total over its input type.
+    return "failed";
+}

package/dist/verification/detect.d.ts

@@ -0,0 +1,4 @@
+import type { WorkspaceFs, WorkspaceInfo } from "../workspace/index.js";
+import type { ScriptCatalog, ScriptMapping } from "./types.js";
+export declare function classifyScripts(scripts: Readonly<Record<string, string>>): ScriptMapping;
+export declare function detectScripts(workspace: WorkspaceInfo, fs?: WorkspaceFs): ScriptCatalog;

package/dist/verification/detect.js

@@ -0,0 +1,81 @@
+// npm-script detection and kind classification. Reads package.json through the workspace
+// WorkspaceFs boundary (never raw node:fs), mirroring the parseScripts approach in
+// src/tools/registry.ts but adding the kind-mapping layer the plan consumes.
+//
+// All name matching is done with plain substring/equality checks (no regex), so there is no
+// ReDoS surface at all (CodeQL js/polynomial-redos). Script NAMES are matched, never values.
+import { readWorkspaceFile } from "../workspace/index.js";
+// package.json is small; this cap is generous and prevents reading a pathological file.
+const PACKAGE_READ_BYTES = 262_144;
+function parseScripts(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        // A malformed package.json yields no scripts rather than throwing: detection is best-effort
+        // and the plan will mark every kind skipped, which is a visible, testable outcome (D4).
+        return {};
+    }
+    if (typeof parsed !== "object" || parsed === null) {
+        return {};
+    }
+    const scripts = parsed.scripts;
+    if (typeof scripts !== "object" || scripts === null) {
+        return {};
+    }
+    const out = {};
+    for (const [name, value] of Object.entries(scripts)) {
+        if (typeof value === "string") {
+            out[name] = value;
+        }
+    }
+    return out;
+}
+// Returns the first script name whose lowercased name satisfies `match`, preferring an exact-name
+// hit over a substring hit so `test` wins over `pretest`/`test:watch` for the test kind.
+function pickScript(names, exact, contains) {
+    for (const name of names) {
+        if (exact.includes(name.toLowerCase())) {
+            return name;
+        }
+    }
+    for (const name of names) {
+        const lower = name.toLowerCase();
+        if (contains.some((needle) => lower.includes(needle)) &&
+            !contains.some((needle) => isLifecycleWrapper(lower, needle))) {
+            return name;
+        }
+    }
+    return undefined;
+}
+function isLifecycleWrapper(lowerName, needle) {
+    return (lowerName === `pre${needle}` ||
+        lowerName === `post${needle}` ||
+        lowerName.startsWith(`pre${needle}:`) ||
+        lowerName.startsWith(`post${needle}:`));
+}
+// Maps script names to verification kinds via conventional heuristics. Exact-name matches win;
+// otherwise a substring of the lowercased name. `typecheck`/`type-check`/`tsc` → typecheck;
+// `lint`/`eslint` → lint; `build` → build; `test` → test.
+export function classifyScripts(scripts) {
+    const names = Object.keys(scripts);
+    return {
+        test: pickScript(names, ["test"], ["test"]),
+        typecheck: pickScript(names, ["typecheck", "type-check", "tsc"], ["typecheck", "type-check"]),
+        lint: pickScript(names, ["lint"], ["lint", "eslint"]),
+        build: pickScript(names, ["build"], ["build"]),
+    };
+}
+export function detectScripts(workspace, fs) {
+    let scripts;
+    try {
+        const content = readWorkspaceFile(workspace, "package.json", { maxBytes: PACKAGE_READ_BYTES }, fs);
+        scripts = parseScripts(content.text);
+    }
+    catch {
+        // No package.json or an unreadable one: no scripts detected. The plan marks kinds skipped (D4).
+        scripts = {};
+    }
+    return { scripts, mapping: classifyScripts(scripts) };
+}

package/dist/verification/errors.d.ts

@@ -0,0 +1,11 @@
+export declare const VERIFICATION_CODES: {
+    readonly PLAN_EMPTY: "VERIFICATION_PLAN_EMPTY";
+};
+export type VerificationCode = (typeof VERIFICATION_CODES)[keyof typeof VERIFICATION_CODES];
+export declare abstract class VerificationError extends Error {
+    abstract readonly code: VerificationCode;
+    constructor(message: string, secrets?: readonly string[]);
+}
+export declare class EmptyPlanError extends VerificationError {
+    readonly code: "VERIFICATION_PLAN_EMPTY";
+}

package/dist/verification/errors.js

@@ -0,0 +1,21 @@
+// Verification error taxonomy, mirroring the workspace/tools pattern (ADR-0005/0006). Errors
+// carry a stable `code` discriminant; callers switch on `code`, never parse `message`. Every
+// message is redacted at construction so errors are always safe to log. The only verification
+// error surfaced today is at the CLI/IO boundary (workspace detection failures are surfaced by
+// the workspace layer's own WorkspaceError); this base exists so later boundary failures have a
+// typed home without re-deriving the pattern.
+import { redact } from "../gateway/redaction.js";
+export const VERIFICATION_CODES = {
+    PLAN_EMPTY: "VERIFICATION_PLAN_EMPTY",
+};
+export class VerificationError extends Error {
+    constructor(message, secrets = []) {
+        super(redact(message, secrets));
+        this.name = new.target.name;
+    }
+}
+// Raised when a verification run is requested but the plan contains no steps (e.g. --only with an
+// empty selection). Surfaced as a non-green verification error at the CLI boundary.
+export class EmptyPlanError extends VerificationError {
+    code = VERIFICATION_CODES.PLAN_EMPTY;
+}

package/dist/verification/index.d.ts

@@ -0,0 +1,17 @@
+export type { ResourceDimension, ResourceLimitDecision, ScriptCatalog, ScriptMapping, VerificationKind, VerificationPlan, VerificationReport, VerificationResourceLimits, VerificationResult, VerificationStatus, VerificationStep, } from "./types.js";
+export { DEFAULT_VERIFICATION_LIMITS } from "./types.js";
+export { VERIFICATION_CODES, VerificationError, EmptyPlanError } from "./errors.js";
+export type { VerificationCode } from "./errors.js";
+export { classifyScripts, detectScripts } from "./detect.js";
+export { classifyOutcome } from "./classify.js";
+export type { AbortReason, OutcomeInput } from "./classify.js";
+export { buildVerificationPlan, resolveTargetedTests } from "./plan.js";
+export type { PlanOptions } from "./plan.js";
+export { nodeResourceMonitor } from "./monitor.js";
+export type { ResourceMonitor } from "./monitor.js";
+export { buildAppliedLimits } from "./limits.js";
+export type { BreachedDimension } from "./limits.js";
+export { runVerification } from "./orchestrator.js";
+export type { VerificationDeps } from "./orchestrator.js";
+export { buildVerificationSummary, renderMarkdownSummary, summarizeForAudit } from "./summary.js";
+export type { AuditResultEntry, VerificationAuditSummary, VerificationResultSummary, VerificationSummary, } from "./summary.js";

package/dist/verification/index.js

@@ -0,0 +1,13 @@
+// Public barrel for the verification orchestrator layer (ADR-0007). Verification reuses the #6
+// command boundary unchanged; this layer adds plan construction, per-command resource limits,
+// best-effort memory monitoring, classified+redacted evidence, and audit/CLI/Markdown surfaces.
+// Explicit named re-exports, `type` keyword for type-only, double quotes, `.js`.
+export { DEFAULT_VERIFICATION_LIMITS } from "./types.js";
+export { VERIFICATION_CODES, VerificationError, EmptyPlanError } from "./errors.js";
+export { classifyScripts, detectScripts } from "./detect.js";
+export { classifyOutcome } from "./classify.js";
+export { buildVerificationPlan, resolveTargetedTests } from "./plan.js";
+export { nodeResourceMonitor } from "./monitor.js";
+export { buildAppliedLimits } from "./limits.js";
+export { runVerification } from "./orchestrator.js";
+export { buildVerificationSummary, renderMarkdownSummary, summarizeForAudit } from "./summary.js";

package/dist/verification/limits.d.ts

@@ -0,0 +1,3 @@
+import type { ResourceLimitDecision, VerificationResourceLimits } from "./types.js";
+export type BreachedDimension = "wall-time" | "output-size" | "memory" | undefined;
+export declare function buildAppliedLimits(limits: VerificationResourceLimits, breached: BreachedDimension): readonly ResourceLimitDecision[];

package/dist/verification/limits.js

@@ -0,0 +1,40 @@
+// Builds the four-dimension appliedLimits record for a step (ADR-0007 D2), with HONEST `enforced`
+// flags: wall-time and output-size are enforced by #6; memory is enforced only on Linux with a
+// ceiling set; network is documented-not-OS-enforced in Wave 1. `breached` is set only on the
+// single dimension that actually fired for the step. Pure — no IO.
+const NETWORK_NOTE = "documented; OS-level isolation deferred to container wave (ADR-0006)";
+const MEMORY_OFF_NOTE = "best-effort; Linux /proc sampler only — not enforced on this run";
+function memoryEnforced(limits) {
+    return process.platform === "linux" && limits.maxMemoryBytes !== undefined;
+}
+export function buildAppliedLimits(limits, breached) {
+    const memEnforced = memoryEnforced(limits);
+    return [
+        {
+            dimension: "wall-time",
+            limit: limits.wallTimeMs,
+            enforced: true,
+            breached: breached === "wall-time" ? true : undefined,
+        },
+        {
+            dimension: "output-size",
+            limit: limits.maxOutputBytes,
+            enforced: true,
+            breached: breached === "output-size" ? true : undefined,
+        },
+        {
+            dimension: "memory",
+            limit: limits.maxMemoryBytes ?? 0,
+            enforced: memEnforced,
+            note: memEnforced ? undefined : MEMORY_OFF_NOTE,
+            breached: breached === "memory" ? true : undefined,
+        },
+        {
+            dimension: "network",
+            limit: limits.network,
+            enforced: false,
+            note: NETWORK_NOTE,
+            breached: undefined,
+        },
+    ];
+}

package/dist/verification/monitor.d.ts

@@ -0,0 +1,4 @@
+export interface ResourceMonitor {
+    readonly watch: (pid: number | undefined, maxBytes: number | undefined, onBreach: () => void) => () => void;
+}
+export declare const nodeResourceMonitor: ResourceMonitor;

package/dist/verification/monitor.js

@@ -0,0 +1,58 @@
+// The ResourceMonitor seam and its Node adapter (ADR-0007 D3). The orchestrator wraps the injected
+// SpawnFn and calls watch(pid, maxBytes, onBreach) on the spawned child; the returned function
+// clears the interval. This is the swap point the container wave replaces with a cgroup sampler.
+//
+// nodeResourceMonitor reads /proc/<pid>/status VmRSS — a SYSTEM path, not workspace content — so
+// it uses raw node:fs (read-only, bounded, no secrets), NOT WorkspaceFs. VmRSS is reported by the
+// kernel directly in kB, making it page-size-independent (correct on aarch64 with 16/64 KiB pages).
+// On non-Linux, or when maxBytes is undefined, watch is a documented no-op and the memory dimension
+// is recorded enforced:false.
+import { readFileSync } from "node:fs";
+const SAMPLE_INTERVAL_MS = 250;
+const NO_OP = () => {
+    // Documented no-op: nothing to unwatch when monitoring is disabled or unavailable.
+};
+// Reads resident-set bytes from /proc/<pid>/status (VmRSS line). The kernel reports VmRSS
+// directly in kB, so the result is page-size-independent. Returns undefined when the file is
+// gone (process exited), when VmRSS is absent (zombie), or on any parse failure — so a transient
+// read race or zombie process is never treated as a breach.
+function readRssBytes(pid) {
+    let raw;
+    try {
+        raw = readFileSync(`/proc/${String(pid)}/status`, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    for (const line of raw.split("\n")) {
+        if (line.startsWith("VmRSS:")) {
+            const parts = line.split(/\s+/);
+            // Expected format: "VmRSS:    1234 kB"  → parts = ["VmRSS:", "1234", "kB"]
+            const kb = Number.parseInt(parts[1] ?? "", 10);
+            if (!Number.isFinite(kb)) {
+                return undefined;
+            }
+            return kb * 1_024;
+        }
+    }
+    return undefined;
+}
+export const nodeResourceMonitor = {
+    watch: (pid, maxBytes, onBreach) => {
+        if (process.platform !== "linux" || maxBytes === undefined || pid === undefined) {
+            return NO_OP;
+        }
+        let fired = false;
+        const timer = setInterval(() => {
+            const rss = readRssBytes(pid);
+            if (rss !== undefined && rss > maxBytes && !fired) {
+                fired = true;
+                onBreach();
+            }
+        }, SAMPLE_INTERVAL_MS);
+        timer.unref();
+        return () => {
+            clearInterval(timer);
+        };
+    },
+};

package/dist/verification/orchestrator.d.ts

@@ -0,0 +1,16 @@
+import { type CommandRule, type SpawnFn } from "../tools/index.js";
+import { type WorkspaceFs } from "../workspace/fs.js";
+import type { WorkspaceInfo } from "../workspace/index.js";
+import { type ResourceMonitor } from "./monitor.js";
+import type { VerificationPlan, VerificationReport } from "./types.js";
+export interface VerificationDeps {
+    readonly workspace: WorkspaceInfo;
+    readonly signal?: AbortSignal | undefined;
+    readonly spawn?: SpawnFn | undefined;
+    readonly monitor?: ResourceMonitor | undefined;
+    readonly processEnv?: NodeJS.ProcessEnv | undefined;
+    readonly now?: (() => number) | undefined;
+    readonly fs?: WorkspaceFs | undefined;
+}
+export declare const VERIFICATION_COMMAND_RULES: readonly CommandRule[];
+export declare function runVerification(plan: VerificationPlan, deps: VerificationDeps): Promise<VerificationReport>;