@tomflow/proflow-platform-cli 0.1.0

package/dist/src/registry/npm-registry.js

@@ -0,0 +1,341 @@
+import { execFile } from "node:child_process";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { gunzipSync } from "node:zlib";
+import { parseModuleDescriptor, proflowPackageMetadataSchema, } from "@tomflow/proflow-module-contract";
+import { PlatformError } from "../errors.js";
+import { versionSatisfies } from "../modules.js";
+const execFileAsync = promisify(execFile);
+export const PRO_FLOW_SCOPE = "@tomflow";
+export const PRO_FLOW_PACKAGE_PREFIX = "@tomflow/proflow-";
+export function systemNpmRunner() {
+    return {
+        async run(args, cwd) {
+            try {
+                const result = await execFileAsync("npm", [...args], {
+                    cwd,
+                    encoding: "utf8",
+                    maxBuffer: 4 * 1024 * 1024,
+                });
+                return { stdout: result.stdout, stderr: result.stderr };
+            }
+            catch (error) {
+                throw npmFailure(error);
+            }
+        },
+    };
+}
+export async function resolveScopeRegistry(workspaceRoot, runner = systemNpmRunner()) {
+    const scoped = await runner.run(["config", "get", `${PRO_FLOW_SCOPE}:registry`], workspaceRoot);
+    const scopedValue = normalizeConfigValue(scoped.stdout);
+    if (scopedValue !== undefined)
+        return scopedValue;
+    const fallback = await runner.run(["config", "get", "registry"], workspaceRoot);
+    const registry = normalizeConfigValue(fallback.stdout);
+    if (registry === undefined) {
+        throw new PlatformError("REGISTRY_UNAVAILABLE", "npm registry is not configured");
+    }
+    return registry;
+}
+export async function discoverRegistryModules(options) {
+    const runner = options.runner ?? systemNpmRunner();
+    const registry = await resolveScopeRegistry(options.workspaceRoot, runner);
+    const names = options.packageName === undefined
+        ? await searchPackageNames(options.workspaceRoot, registry, runner)
+        : [validateRequestedPackageName(options.packageName)];
+    const candidates = [];
+    const rejected = [];
+    for (const packageName of names) {
+        const manifest = await viewManifest(options.workspaceRoot, registry, packageName, runner);
+        const assessed = assessManifest(manifest, registry, options.nodeVersion ?? process.versions.node);
+        if ("candidate" in assessed)
+            candidates.push(assessed.candidate);
+        else
+            rejected.push(assessed.rejected);
+    }
+    candidates.sort((left, right) => left.packageName.localeCompare(right.packageName));
+    rejected.sort((left, right) => left.packageName.localeCompare(right.packageName));
+    return { registry, candidates, rejected };
+}
+export async function loadRegistryModuleDescriptor(options) {
+    const runner = options.runner ?? systemNpmRunner();
+    const tempRoot = await mkdtemp(join(tmpdir(), "proflow-registry-manifest-"));
+    try {
+        const packed = await runner.run([
+            "pack",
+            `${options.candidate.packageName}@${options.candidate.moduleVersion}`,
+            "--json",
+            "--ignore-scripts",
+            `--pack-destination=${tempRoot}`,
+            `--registry=${options.candidate.registry}`,
+        ], options.workspaceRoot);
+        const filename = packFilename(packed.stdout, options.candidate.packageName);
+        const archive = await readFile(join(tempRoot, filename));
+        const manifestPath = `package/${options.candidate.manifest.replace(/^\.\//, "")}`;
+        const rawManifest = readTarEntry(archive, manifestPath);
+        const descriptor = parseModuleDescriptor(parseJson(rawManifest.toString("utf8"), `${options.candidate.packageName} module manifest`));
+        if (descriptor.packageName !== options.candidate.packageName ||
+            descriptor.moduleVersion !== options.candidate.moduleVersion) {
+            throw new PlatformError("REGISTRY_RESPONSE_INVALID", `Registry manifest identity/version mismatch for ${options.candidate.packageName}@${options.candidate.moduleVersion}`);
+        }
+        return descriptor;
+    }
+    finally {
+        await rm(tempRoot, { recursive: true, force: true });
+    }
+}
+function packFilename(stdout, packageName) {
+    const parsed = parseJson(stdout, `npm pack ${packageName}`);
+    if (!Array.isArray(parsed) || parsed.length !== 1 || !isRecord(parsed[0])) {
+        throw new PlatformError("REGISTRY_RESPONSE_INVALID", `npm pack response is invalid for ${packageName}`);
+    }
+    const filename = parsed[0].filename;
+    if (typeof filename !== "string" ||
+        filename === "" ||
+        filename.includes("/") ||
+        filename.includes("\\")) {
+        throw new PlatformError("REGISTRY_RESPONSE_INVALID", `npm pack filename is invalid for ${packageName}`);
+    }
+    return filename;
+}
+function readTarEntry(tgz, targetName) {
+    let tar;
+    try {
+        tar = gunzipSync(tgz);
+    }
+    catch {
+        throw new PlatformError("REGISTRY_RESPONSE_INVALID", "npm package tarball is not valid gzip");
+    }
+    for (let offset = 0; offset + 512 <= tar.length;) {
+        const header = tar.subarray(offset, offset + 512);
+        if (header.every((byte) => byte === 0))
+            break;
+        const name = tarString(header, 0, 100);
+        const prefix = tarString(header, 345, 155);
+        const entryName = prefix === "" ? name : `${prefix}/${name}`;
+        const sizeRaw = tarString(header, 124, 12).trim();
+        const size = sizeRaw === "" ? 0 : Number.parseInt(sizeRaw, 8);
+        if (!Number.isSafeInteger(size) || size < 0) {
+            throw new PlatformError("REGISTRY_RESPONSE_INVALID", "npm package tarball has an invalid entry size");
+        }
+        const dataStart = offset + 512;
+        const dataEnd = dataStart + size;
+        if (dataEnd > tar.length) {
+            throw new PlatformError("REGISTRY_RESPONSE_INVALID", "npm package tarball is truncated");
+        }
+        if (entryName === targetName) {
+            if (size > 1024 * 1024) {
+                throw new PlatformError("REGISTRY_RESPONSE_INVALID", "ProFlow module manifest exceeds 1 MiB");
+            }
+            return tar.subarray(dataStart, dataEnd);
+        }
+        offset = dataStart + Math.ceil(size / 512) * 512;
+    }
+    throw new PlatformError("REGISTRY_RESPONSE_INVALID", `npm package tarball does not contain ${targetName}`);
+}
+function tarString(header, start, length) {
+    const field = header.subarray(start, start + length);
+    const end = field.indexOf(0);
+    return field.subarray(0, end < 0 ? field.length : end).toString("utf8");
+}
+export async function discoverRegistryInstallClosure(options) {
+    const runner = options.runner ?? systemNpmRunner();
+    const queue = [validateRequestedPackageName(options.packageName)];
+    const seen = new Set();
+    const candidates = new Map();
+    const rejected = new Map();
+    let registry;
+    while (queue.length > 0) {
+        const packageName = queue.shift();
+        if (!packageName)
+            continue;
+        if (seen.has(packageName))
+            continue;
+        seen.add(packageName);
+        const discovered = await discoverRegistryModules({
+            workspaceRoot: options.workspaceRoot,
+            packageName,
+            runner,
+            ...(options.nodeVersion === undefined
+                ? {}
+                : { nodeVersion: options.nodeVersion }),
+        });
+        registry ??= discovered.registry;
+        for (const item of discovered.rejected)
+            rejected.set(item.packageName, item);
+        const candidate = discovered.candidates[0];
+        if (candidate === undefined) {
+            throw new PlatformError("PACKAGE_NOT_PROFLOW", `package ${packageName} is not an installable ProFlow module`);
+        }
+        candidates.set(candidate.packageName, candidate);
+        for (const dependency of candidate.installRequires) {
+            if (!seen.has(dependency))
+                queue.push(dependency);
+        }
+    }
+    if (registry === undefined) {
+        registry = await resolveScopeRegistry(options.workspaceRoot, runner);
+    }
+    return {
+        registry,
+        candidates: [...candidates.values()].sort((a, b) => a.packageName.localeCompare(b.packageName)),
+        rejected: [...rejected.values()].sort((a, b) => a.packageName.localeCompare(b.packageName)),
+    };
+}
+async function searchPackageNames(workspaceRoot, registry, runner) {
+    const result = await runner.run([
+        "search",
+        PRO_FLOW_PACKAGE_PREFIX,
+        "--json",
+        "--searchlimit=250",
+        "--prefer-online",
+        `--registry=${registry}`,
+    ], workspaceRoot);
+    const parsed = parseJson(result.stdout, "npm search response");
+    if (!Array.isArray(parsed)) {
+        throw new PlatformError("REGISTRY_RESPONSE_INVALID", "npm search response is not an array");
+    }
+    const names = new Set();
+    for (const raw of parsed) {
+        if (typeof raw?.name !== "string")
+            continue;
+        if (!raw.name.startsWith(PRO_FLOW_PACKAGE_PREFIX))
+            continue;
+        names.add(raw.name);
+    }
+    return [...names].sort();
+}
+async function viewManifest(workspaceRoot, registry, packageName, runner) {
+    const result = await runner.run([
+        "view",
+        packageName,
+        "--json",
+        "--prefer-online",
+        `--registry=${registry}`,
+    ], workspaceRoot);
+    const parsed = parseJson(result.stdout, `npm view ${packageName}`);
+    if (!isRecord(parsed)) {
+        throw new PlatformError("REGISTRY_RESPONSE_INVALID", `npm view response is not an object for ${packageName}`);
+    }
+    return parsed;
+}
+function assessManifest(manifest, registry, nodeVersion) {
+    if (typeof manifest.name !== "string" ||
+        !manifest.name.startsWith(PRO_FLOW_PACKAGE_PREFIX)) {
+        return rejectedManifest(manifest, "NOT_PROFLOW_MODULE", "package name is outside the ProFlow scope prefix");
+    }
+    const packageName = manifest.name;
+    const moduleVersion = typeof manifest.version === "string" ? manifest.version : undefined;
+    if (moduleVersion === undefined) {
+        return rejectedManifest(manifest, "METADATA_INVALID", "package version is missing");
+    }
+    if (typeof manifest.deprecated === "string" &&
+        manifest.deprecated.trim() !== "") {
+        return {
+            rejected: {
+                packageName,
+                moduleVersion,
+                reason: "DEPRECATED",
+                message: manifest.deprecated,
+            },
+        };
+    }
+    const metadata = proflowPackageMetadataSchema.safeParse(manifest.proflow);
+    if (!metadata.success) {
+        return {
+            rejected: {
+                packageName,
+                moduleVersion,
+                reason: "METADATA_INVALID",
+                message: "package.json.proflow does not satisfy the ProFlow Module Contract",
+            },
+        };
+    }
+    const nodeVersionRange = nodeRangeOf(manifest.engines);
+    if (nodeVersionRange !== undefined &&
+        !versionSatisfies(nodeVersion, nodeVersionRange)) {
+        return {
+            rejected: {
+                packageName,
+                moduleVersion,
+                reason: "NODE_INCOMPATIBLE",
+                message: `node ${nodeVersion} does not satisfy ${nodeVersionRange}`,
+            },
+        };
+    }
+    return {
+        candidate: {
+            packageName,
+            moduleVersion,
+            ...(typeof manifest.description === "string"
+                ? { description: manifest.description }
+                : {}),
+            installClass: metadata.data.installClass,
+            descriptor: metadata.data.descriptor,
+            manifest: metadata.data.manifest,
+            installRequires: [...metadata.data.installRequires],
+            ...(nodeVersionRange === undefined ? {} : { nodeVersionRange }),
+            registry,
+        },
+    };
+}
+function validateRequestedPackageName(packageName) {
+    if (!packageName.startsWith(PRO_FLOW_PACKAGE_PREFIX)) {
+        throw new PlatformError("PACKAGE_NOT_PROFLOW", `package ${packageName} is outside ${PRO_FLOW_PACKAGE_PREFIX}*`);
+    }
+    return packageName;
+}
+function nodeRangeOf(value) {
+    if (!isRecord(value))
+        return undefined;
+    return typeof value.node === "string" ? value.node : undefined;
+}
+function rejectedManifest(manifest, reason, message) {
+    return {
+        rejected: {
+            packageName: typeof manifest.name === "string" ? manifest.name : "<unknown>",
+            ...(typeof manifest.version === "string"
+                ? { moduleVersion: manifest.version }
+                : {}),
+            reason,
+            message,
+        },
+    };
+}
+function normalizeConfigValue(value) {
+    const trimmed = value.trim();
+    if (trimmed === "" || trimmed === "undefined" || trimmed === "null") {
+        return undefined;
+    }
+    return trimmed;
+}
+function parseJson(value, label) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        throw new PlatformError("REGISTRY_RESPONSE_INVALID", `${label} is not valid JSON`);
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function npmFailure(error) {
+    const detail = npmErrorText(error);
+    if (/E401|E403|ENEEDAUTH|authentication|authorized/i.test(detail)) {
+        return new PlatformError("REGISTRY_AUTH_REQUIRED", `npm registry authentication is required: ${detail}`);
+    }
+    if (/E404|not found/i.test(detail)) {
+        return new PlatformError("PACKAGE_NOT_FOUND", detail);
+    }
+    return new PlatformError("REGISTRY_UNAVAILABLE", detail);
+}
+function npmErrorText(error) {
+    if (!isRecord(error))
+        return String(error);
+    const stderr = typeof error.stderr === "string" ? error.stderr.trim() : "";
+    const message = typeof error.message === "string" ? error.message : String(error);
+    return stderr === "" ? message : stderr;
+}

package/dist/src/security/index.d.ts

@@ -0,0 +1,3 @@
+export type { WorkspaceLockHandle } from "./lock.ts";
+export { acquireWorkspaceLock, readWorkspaceLock, workspaceLockPath, } from "./lock.ts";
+export { redactDeep, redactPlanSecrets, redactSecretValues, SECRET_REDACTED, } from "./redact.ts";

package/dist/src/security/index.js

@@ -0,0 +1,2 @@
+export { acquireWorkspaceLock, readWorkspaceLock, workspaceLockPath, } from "./lock.js";
+export { redactDeep, redactPlanSecrets, redactSecretValues, SECRET_REDACTED, } from "./redact.js";

package/dist/src/security/lock.d.ts

@@ -0,0 +1,9 @@
+import type { LockRecord } from "../contracts.ts";
+import type { WorkspacePaths } from "../paths.ts";
+export interface WorkspaceLockHandle {
+    record: LockRecord;
+    release(): Promise<void>;
+}
+export declare function workspaceLockPath(paths: WorkspacePaths): string;
+export declare function readWorkspaceLock(paths: WorkspacePaths): Promise<LockRecord | undefined>;
+export declare function acquireWorkspaceLock(paths: WorkspacePaths, planRef: string): Promise<WorkspaceLockHandle>;

package/dist/src/security/lock.js

@@ -0,0 +1,89 @@
+import { createHash } from "node:crypto";
+import { mkdir, open, readFile, realpath, unlink, } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { PlatformError } from "../errors.js";
+import { isLockRecord } from "../persistence/guards.js";
+export function workspaceLockPath(paths) {
+    return join(paths.runtime, "apply.lock");
+}
+function errorHasCode(error, code) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === code);
+}
+async function computeFingerprint(root) {
+    let canonical = root;
+    try {
+        canonical = await realpath(root);
+    }
+    catch {
+        canonical = resolve(root);
+    }
+    return createHash("sha256").update(canonical).digest("hex").slice(0, 16);
+}
+export async function readWorkspaceLock(paths) {
+    let raw;
+    try {
+        raw = await readFile(workspaceLockPath(paths), "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    return isLockRecord(parsed) ? parsed : undefined;
+}
+function lockedError(existing) {
+    const details = existing === undefined
+        ? "existing lock is unreadable"
+        : `pid=${existing.pid} planRef=${existing.planRef} since=${existing.createdAt} fingerprint=${existing.workspaceFingerprint}`;
+    return new PlatformError("WORKSPACE_LOCKED", `workspace apply already in progress (${details})`);
+}
+// v1 single-process exclusive lock: O_EXCL create, no distributed coordination,
+// and no reclaim of a lock that cannot be proven stale.
+export async function acquireWorkspaceLock(paths, planRef) {
+    const file = workspaceLockPath(paths);
+    await mkdir(paths.runtime, { recursive: true });
+    const record = {
+        pid: process.pid,
+        createdAt: new Date().toISOString(),
+        planRef,
+        workspaceFingerprint: await computeFingerprint(paths.root),
+    };
+    let handle;
+    try {
+        handle = await open(file, "wx", 0o644);
+    }
+    catch (error) {
+        if (errorHasCode(error, "EEXIST")) {
+            throw lockedError(await readWorkspaceLock(paths));
+        }
+        throw error;
+    }
+    try {
+        await handle.writeFile(`${JSON.stringify(record, null, 2)}\n`, {
+            encoding: "utf8",
+        });
+    }
+    finally {
+        await handle.close();
+    }
+    return {
+        record,
+        async release() {
+            try {
+                await unlink(file);
+            }
+            catch (error) {
+                if (!errorHasCode(error, "ENOENT"))
+                    throw error;
+            }
+        },
+    };
+}

package/dist/src/security/redact.d.ts

@@ -0,0 +1,6 @@
+import type { DeploymentPlan } from "../contracts.ts";
+export declare const SECRET_REDACTED = "<redacted>";
+export declare function isValidSecretRef(value: string): boolean;
+export declare function redactSecretValues(values: Record<string, string>, _secretRefs: readonly string[]): Record<string, string>;
+export declare function redactDeep(value: unknown, rawSecrets: readonly string[]): unknown;
+export declare function redactPlanSecrets(plan: DeploymentPlan): DeploymentPlan;

package/dist/src/security/redact.js

@@ -0,0 +1,48 @@
+export const SECRET_REDACTED = "<redacted>";
+const SECRET_REF_PATTERN = /^(?:secret:\/\/[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*|credential-ref:[A-Za-z0-9._-]+)$/;
+export function isValidSecretRef(value) {
+    return SECRET_REF_PATTERN.test(value);
+}
+// secretRef slot values are opaque reference identities (e.g.
+// `secret://model-provider/default`, `credential-ref:local-platform`), NOT raw
+// tokens/passwords. They are safe to persist and display verbatim, so this
+// function preserves them instead of substituting a redaction marker. Raw
+// secret leak scanning is `redactDeep`'s job, not this function's.
+export function redactSecretValues(values, _secretRefs) {
+    return { ...values };
+}
+function redactString(value, secrets) {
+    let out = value;
+    for (const secret of secrets) {
+        if (secret.length === 0)
+            continue;
+        out = out.split(secret).join(SECRET_REDACTED);
+    }
+    return out;
+}
+// Deep-structural redaction: returns a clone with every occurrence of a raw
+// secret value replaced, in any nested string position. This is the leak-scan
+// layer for genuine raw secret values (test sentinels or future non-secretRef
+// sensitive values). secretRef references are NOT raw secrets and must never be
+// passed here as raw secrets.
+export function redactDeep(value, rawSecrets) {
+    const secrets = rawSecrets.filter((secret) => secret.length > 0);
+    if (typeof value === "string")
+        return redactString(value, secrets);
+    if (Array.isArray(value))
+        return value.map((item) => redactDeep(item, secrets));
+    if (typeof value === "object" && value !== null) {
+        const out = {};
+        for (const [key, item] of Object.entries(value)) {
+            out[key] = redactDeep(item, secrets);
+        }
+        return out;
+    }
+    return value;
+}
+// Plans are public DTOs whose secretRef config values are opaque reference
+// identities, not raw secrets. This returns a non-mutating clone that preserves
+// secretRef references verbatim (no `<redacted>` substitution).
+export function redactPlanSecrets(plan) {
+    return structuredClone(plan);
+}

package/dist/src/verification/index.d.ts

@@ -0,0 +1,2 @@
+export type { VerifyResult } from "./verify.ts";
+export { configFingerprint, verificationRefOf, verifyModule, verifyModules, } from "./verify.ts";

package/dist/src/verification/index.js

@@ -0,0 +1 @@
+export { configFingerprint, verificationRefOf, verifyModule, verifyModules, } from "./verify.js";

package/dist/src/verification/verify.d.ts

@@ -0,0 +1,33 @@
+import type { ModuleOperationResult } from "@tomflow/proflow-module-contract";
+import type { ResolvedModule, VerificationRecord } from "../contracts.ts";
+import type { ModuleCatalog } from "../modules.ts";
+import type { WorkspacePaths } from "../paths.ts";
+export interface VerifyResult {
+    moduleRef: string;
+    record: VerificationRecord;
+    result: ModuleOperationResult;
+    observedEffects: string[];
+}
+/**
+ * Derives a stable verificationRef from the record's own identity fields. It is
+ * deterministic (no randomness) yet unique per verification event, because the
+ * recorded `verifiedAt` timestamp is part of the canonical input.
+ */
+export declare function verificationRefOf(record: Omit<VerificationRecord, "verificationRef">): string;
+/**
+ * Fingerprints the identity-defining config of an external resource. Key order
+ * is normalized so the fingerprint is stable regardless of insertion order.
+ */
+export declare function configFingerprint(values: Record<string, string>, secretRefs?: readonly string[]): string;
+/**
+ * Verifies a single module by dispatching its public `verify` primitive through
+ * the lifecycle boundary, then appending a Version Verification Record. The
+ * verdict always comes from the live adapter result, never from persisted
+ * history. Records are appended, never overwritten.
+ */
+export declare function verifyModule(catalog: ModuleCatalog, module: ResolvedModule, paths: WorkspacePaths): Promise<VerifyResult>;
+/**
+ * Verifies every module that declares the `verify` primitive; modules without
+ * it are skipped (the descriptor is the truth for what is verifiable).
+ */
+export declare function verifyModules(catalog: ModuleCatalog, modules: readonly ResolvedModule[], paths: WorkspacePaths): Promise<VerifyResult[]>;

package/dist/src/verification/verify.js

@@ -0,0 +1,114 @@
+import { createHash } from "node:crypto";
+import { dispatchLifecycle } from "../lifecycle/index.js";
+import { appendVerification, loadConfig } from "../persistence/index.js";
+/**
+ * Derives a stable verificationRef from the record's own identity fields. It is
+ * deterministic (no randomness) yet unique per verification event, because the
+ * recorded `verifiedAt` timestamp is part of the canonical input.
+ */
+export function verificationRefOf(record) {
+    const canonical = JSON.stringify([
+        record.moduleRef,
+        record.moduleVersion,
+        record.resourceIdentity ?? null,
+        record.resourceVersion ?? null,
+        record.result,
+        record.verifiedAt,
+    ]);
+    const digest = createHash("sha256").update(canonical).digest("hex");
+    return `verify-${record.moduleRef}-${digest.slice(0, 16)}`;
+}
+/**
+ * Fingerprints the identity-defining config of an external resource. Key order
+ * is normalized so the fingerprint is stable regardless of insertion order.
+ */
+export function configFingerprint(values, secretRefs = []) {
+    const entries = [
+        ...Object.entries(values)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, value]) => `${key}=${value}`),
+        ...[...secretRefs].sort().map((key) => `secretRef=${key}`),
+    ];
+    const digest = createHash("sha256").update(entries.join("\n")).digest("hex");
+    return `fp-${digest.slice(0, 16)}`;
+}
+// A verification record is a binary verdict: only an explicit SUCCEEDED maps to
+// PASS. BLOCKED / ACTION_REQUIRED / FAILED are all recorded as FAIL so a pending
+// human action or blocked dependency can never masquerade as a passing verify.
+function verdictOf(status) {
+    return status === "SUCCEEDED" ? "PASS" : "FAIL";
+}
+function summaryOf(result) {
+    if (result.status === "SUCCEEDED") {
+        const checks = result.checks ?? [];
+        if (checks.length === 0)
+            return "verify succeeded";
+        const passed = checks.filter((check) => check.status === "PASS").length;
+        return `verify succeeded (${passed}/${checks.length} checks passed)`;
+    }
+    if (result.status === "ACTION_REQUIRED" &&
+        result.actionRequired !== undefined) {
+        return `action required: ${result.actionRequired.action} — ${result.actionRequired.description}`;
+    }
+    if (result.error !== undefined) {
+        return `${result.error.code}: ${result.error.message}`;
+    }
+    return `verify ${result.status.toLowerCase()}`;
+}
+function evidenceRefsOf(result) {
+    return (result.checks ?? []).map((check) => `check:${check.id}:${check.status}`);
+}
+/**
+ * Verifies a single module by dispatching its public `verify` primitive through
+ * the lifecycle boundary, then appending a Version Verification Record. The
+ * verdict always comes from the live adapter result, never from persisted
+ * history. Records are appended, never overwritten.
+ */
+export async function verifyModule(catalog, module, paths) {
+    const dispatched = await dispatchLifecycle(catalog, module, "verify");
+    const result = dispatched.result;
+    let resourceIdentity;
+    let resourceVersion;
+    if (module.kind === "external-resource") {
+        const config = await loadConfig(paths, module.moduleRef);
+        const secretRefs = module.configSlots
+            .filter((slot) => slot.type === "secretRef")
+            .map((slot) => slot.key);
+        resourceIdentity = configFingerprint(config?.publicValues ?? {}, secretRefs);
+        resourceVersion = result.resourceVersion;
+    }
+    const base = {
+        moduleRef: module.moduleRef,
+        moduleVersion: module.moduleVersion,
+        result: verdictOf(result.status),
+        summary: summaryOf(result),
+        evidenceRefs: evidenceRefsOf(result),
+        verifiedAt: new Date().toISOString(),
+        ...(resourceIdentity !== undefined ? { resourceIdentity } : {}),
+        ...(resourceVersion !== undefined ? { resourceVersion } : {}),
+    };
+    const record = {
+        ...base,
+        verificationRef: verificationRefOf(base),
+    };
+    await appendVerification(paths, record);
+    return {
+        moduleRef: module.moduleRef,
+        record,
+        result,
+        observedEffects: dispatched.observedEffects,
+    };
+}
+/**
+ * Verifies every module that declares the `verify` primitive; modules without
+ * it are skipped (the descriptor is the truth for what is verifiable).
+ */
+export async function verifyModules(catalog, modules, paths) {
+    const results = [];
+    for (const module of modules) {
+        if (!module.lifecycle.includes("verify"))
+            continue;
+        results.push(await verifyModule(catalog, module, paths));
+    }
+    return results;
+}