humanish 0.104.3 → 0.106.0

package/dist/verify/verify.js

@@ -0,0 +1,333 @@
+import path from "node:path";
+import { listStudyAnalysisExecutions } from "../analysis/store-executions.js";
+import { loadStudyAnalysis } from "../analysis/load.js";
+import { studyAnalysisSharingProblems } from "../analysis/sharing.js";
+import { containsSensitive } from "../evidence/redaction.js";
+import { validatePreparedRunArtifactPaths } from "../run/paths.js";
+import { RUN_BUNDLE_FILE, RUN_BUNDLE_SCHEMA } from "../run/bundle.js";
+import { isCleanupResult, isRunBundle } from "../run/bundle-shape.js";
+import { readRunJsonIfExists, readRunTextIfExists, resolveRunPath } from "../run/locate.js";
+import { isRecord } from "../run/type-guards.js";
+import { actorVerdictConsistencyFindings, noEngagementActorFindings, validateCodexAppServerEvidence, validateTerminalProductEvidence, } from "./actor.js";
+import { invalidRunEvidenceReferences, MAX_REPORTED_FINDINGS, missingLocalEvidenceArtifacts, rawScreenshotPostureWarnings, rawScreenshotStreamIds, redactedShapeFramePaths, scanRunPublicSafetyArtifacts, streamScreenshotPaths, } from "./artifacts.js";
+import { runNotFinishedWarnings } from "./liveness.js";
+import { costAndReceiptFindings } from "./costs.js";
+import { rerunLineageFindings } from "./rerun.js";
+import { sharedWorldEvidenceFindings } from "./shared-world.js";
+import { subjectStateFindings, undeclaredSubjectStateWarnings } from "./subject.js";
+export const VERIFY_SCHEMA = "humanish.verify-result.v1";
+// The UNSCANNED_ARTIFACT reason names this many paths and counts the rest.
+const MAX_LISTED_UNSCANNED = 10;
+export async function verifyRun(cwdInput, runInput) {
+    const cwd = path.resolve(cwdInput);
+    let runPaths;
+    try {
+        runPaths = await resolveRunPath(cwd, runInput);
+    }
+    catch {
+        return invalidRunStorageVerifyResult(cwd, runInput);
+    }
+    return verifyResolvedRun(cwd, runInput, runPaths);
+}
+export function invalidRunStorageVerifyResult(cwd, runInput) {
+    return {
+        schema: VERIFY_SCHEMA,
+        ok: false,
+        cwd,
+        run: runInput,
+        checks: [
+            {
+                name: "run storage containment",
+                ok: false,
+                message: "run storage must contain only identity-bound directories and single-link regular files",
+            },
+        ],
+        shareSafety: {
+            status: "blocked",
+            reasons: [{ code: "VERIFY_FAILED", message: "Run storage failed containment validation." }],
+        },
+        warnings: [],
+        error: {
+            code: "HUMANISH_INVALID_RUN_BUNDLE",
+            message: "Run storage failed containment validation.",
+        },
+    };
+}
+/** Verify a run already resolved to prepared paths; null reports the run as not found. */
+export async function verifyResolvedRun(cwd, runInput, runPaths) {
+    const checks = [];
+    if (!runPaths) {
+        return {
+            schema: VERIFY_SCHEMA,
+            ok: false,
+            cwd,
+            run: runInput,
+            checks,
+            shareSafety: {
+                status: "blocked",
+                reasons: [
+                    {
+                        code: "VERIFY_FAILED",
+                        message: `Run not found: ${runInput}`,
+                    },
+                ],
+            },
+            warnings: [],
+            error: {
+                code: "HUMANISH_RUN_NOT_FOUND",
+                message: `Run not found: ${runInput}`,
+            },
+        };
+    }
+    const bundlePath = path.join(runPaths.absoluteRunRoot, RUN_BUNDLE_FILE);
+    const bundle = await readRunJsonIfExists(runPaths, RUN_BUNDLE_FILE);
+    const cleanupJson = await readRunJsonIfExists(runPaths, "cleanup.json");
+    const reviewJson = await readRunJsonIfExists(runPaths, "review.json");
+    const reviewMarkdown = await readRunTextIfExists(runPaths, "review.md");
+    checks.push(...bundlePresenceChecks(bundle, reviewJson !== null && reviewMarkdown !== null));
+    const derivedPublicSafetyFindings = [];
+    const unscannedArtifacts = [];
+    const publicSafetyFindings = await scanRunPublicSafetyArtifacts(runPaths, derivedPublicSafetyFindings, {
+        recordingPaths: new Set(isRunBundle(bundle)
+            ? bundle.streams.flatMap((stream) => (stream.recording ? [stream.recording.path] : []))
+            : []),
+        screenshotPaths: isRunBundle(bundle) ? streamScreenshotPaths(bundle) : new Set(),
+    }, unscannedArtifacts);
+    // JSON escapes can hide a sensitive value from the byte scan while the
+    // decoded recording exposes it to Observer, feedback, or analysis input.
+    if (publicSafetyFindings.length < MAX_REPORTED_FINDINGS &&
+        bundle !== null &&
+        containsSensitive(JSON.stringify(bundle))) {
+        publicSafetyFindings.push("sensitive decoded run.json");
+    }
+    checks.push({
+        name: "public-safety scan",
+        ok: publicSafetyFindings.length === 0,
+        message: publicSafetyFindings.length === 0
+            ? "run text artifacts and public-proof paths must not match known secret or browser-profile patterns"
+            : `public-safety findings: ${publicSafetyFindings.slice(0, 5).join(", ")}`,
+    });
+    const missingEvidenceArtifacts = isRunBundle(bundle)
+        ? await missingLocalEvidenceArtifacts(runPaths, bundle)
+        : [];
+    const redactedShapeFrames = isRunBundle(bundle)
+        ? await redactedShapeFramePaths(runPaths, bundle)
+        : new Set();
+    const invalidEvidenceReferences = isRunBundle(bundle) ? invalidRunEvidenceReferences(bundle) : [];
+    checks.push({
+        name: "local evidence artifacts exist",
+        ok: missingEvidenceArtifacts.length === 0 && invalidEvidenceReferences.length === 0,
+        message: missingEvidenceArtifacts.length === 0 && invalidEvidenceReferences.length === 0
+            ? "referenced local screenshot/trace/log/filesystem artifacts are present"
+            : invalidEvidenceReferences.length > 0
+                ? `invalid evidence artifact references: ${invalidEvidenceReferences.join(", ")}`
+                : `missing local evidence artifacts: ${missingEvidenceArtifacts.join(", ")}`,
+    });
+    checks.push(...(await evidenceChecks(runPaths, bundle, cleanupJson)));
+    const recordingOk = checks.every((check) => check.ok);
+    if (derivedPublicSafetyFindings.length > 0)
+        checks.push({
+            name: "derived analysis public-safety scan",
+            ok: false,
+            message: "Derived analysis contains sensitive text or unsafe artifact paths; sharing is blocked, original recording remains independently verifiable.",
+        });
+    const ok = checks.every((check) => check.ok);
+    const warnings = isRunBundle(bundle)
+        ? [
+            ...rawScreenshotPostureWarnings(bundle, redactedShapeFrames),
+            ...undeclaredSubjectStateWarnings(bundle),
+            ...desktopGeometryWarnings(bundle),
+            ...(await runNotFinishedWarnings(runPaths, bundle)),
+        ]
+        : [];
+    const shareSafety = isRunBundle(bundle)
+        ? buildShareSafety({
+            ok,
+            bundle,
+            publicSafetyFindings,
+            unscannedArtifacts,
+            redactedShapeFrames,
+        })
+        : {
+            status: "blocked",
+            reasons: [
+                {
+                    code: "VERIFY_FAILED",
+                    message: "Run bundle failed verification.",
+                },
+            ],
+        };
+    await applyAnalysisSharing(runPaths, warnings, shareSafety);
+    return {
+        schema: VERIFY_SCHEMA,
+        ok,
+        ...(!ok && recordingOk ? { recordingOk: true } : {}),
+        cwd,
+        run: runInput,
+        bundlePath: path.relative(cwd, bundlePath),
+        checks,
+        shareSafety,
+        warnings,
+        ...(ok
+            ? {}
+            : {
+                error: {
+                    code: "HUMANISH_INVALID_RUN_BUNDLE",
+                    message: "Run bundle failed verification.",
+                },
+            }),
+    };
+}
+/** verifyRun for a caller that already holds prepared paths. Revalidates them first. */
+export async function verifyRunPrepared(cwdInput, runInput, runPaths) {
+    const cwd = path.resolve(cwdInput);
+    try {
+        await validatePreparedRunArtifactPaths(runPaths);
+    }
+    catch {
+        return invalidRunStorageVerifyResult(cwd, runInput);
+    }
+    return verifyResolvedRun(cwd, runInput, runPaths);
+}
+/** Whether run.json, its schema, shape and redaction, and the review artifacts are present. */
+function bundlePresenceChecks(bundle, reviewArtifactsExist) {
+    return [
+        {
+            name: "run.json exists",
+            ok: bundle !== null,
+            message: bundle === null ? "run.json missing" : "run.json present",
+        },
+        {
+            name: "run schema",
+            ok: isRecord(bundle) && bundle.schema === RUN_BUNDLE_SCHEMA,
+            message: "run bundle schema is humanish.run-bundle.v1",
+        },
+        {
+            name: "run bundle shape",
+            ok: isRunBundle(bundle),
+            message: "run bundle must include source, persona, scenario, lifecycle, simulations, streams, events, artifacts, review, and feedback candidates",
+        },
+        {
+            name: "redaction passed",
+            ok: isRecord(bundle) && isRecord(bundle.redaction) && bundle.redaction.status === "passed",
+            message: "redaction status must be passed",
+        },
+        {
+            name: "review artifacts exist",
+            ok: reviewArtifactsExist,
+            message: "review.json and review.md must exist",
+        },
+    ];
+}
+/**
+ * Interpretation validity is independent of run validity. Keep recordings usable, while refusing
+ * to silently promote stale or malformed derived text into sharing.
+ */
+async function applyAnalysisSharing(runPaths, warnings, shareSafety) {
+    const analysis = await loadStudyAnalysis(runPaths);
+    const analysisSharing = studyAnalysisSharingProblems(analysis);
+    const executionHistory = await listStudyAnalysisExecutions(runPaths);
+    if (!analysisSharing.unverified &&
+        !analysisSharing.sensitive &&
+        executionHistory.warnings.length === 0)
+        return;
+    warnings.push("Some study analysis or correction records could not be validated against current evidence.");
+    shareSafety.reasons.push({
+        code: "ANALYSIS_UNVERIFIED",
+        message: "Derived analysis or corrections need review against the current evidence before sharing.",
+    });
+    if (analysisSharing.sensitive)
+        shareSafety.status = "blocked";
+    else if (shareSafety.status === "share_ready")
+        shareSafety.status = "local_only";
+}
+/** Passes when `findings` is empty; otherwise lists them after `failLabel`. */
+function findingsCheck(name, findings, okMessage, failLabel, failSuffix = "") {
+    return {
+        name,
+        ok: findings.length === 0,
+        message: findings.length === 0 ? okMessage : `${failLabel}: ${findings.join(", ")}${failSuffix}`,
+    };
+}
+/** The bundle-content checks, in report order. A bundle that fails its shape guard has no findings. */
+async function evidenceChecks(runPaths, bundle, cleanupJson) {
+    const valid = isRunBundle(bundle) ? bundle : null;
+    const checks = [
+        findingsCheck("terminal-product evidence", valid ? await validateTerminalProductEvidence(runPaths, valid) : [], "live terminal-product streams either are absent or carry the substrate/cleanup/interventions/cost ledgers + a ledger-derived no-spend proof + redacted terminal evidence, with proven teardown and known spend within the declared cap", "terminal-product findings"),
+        findingsCheck("codex app-server evidence", valid ? await validateCodexAppServerEvidence(runPaths, valid) : [], "live Codex app-server streams either are absent or include valid redacted trace evidence", "codex app-server findings"),
+        findingsCheck("actor engagement", valid ? noEngagementActorFindings(valid) : [], "live actor traces that claim goal_satisfied carry at least one action or message", "no-engagement findings", " — a hollow run is not credible evidence"),
+        findingsCheck("actor verdict consistency", valid ? actorVerdictConsistencyFindings(valid) : [], "live pass verdicts do not hide failed, blocked, or timed-out actor traces", "actor verdict findings"),
+        findingsCheck("subject state provenance", valid ? subjectStateFindings(valid) : [], "subject state claims match the recorded seed/external evidence (or the subject block is honestly absent)", "subject state findings"),
+        findingsCheck("shared-world evidence", valid ? sharedWorldEvidenceFindings(valid) : [], "live shared-world runs either are absent or carry well-formed evidence for their mode (concurrent participant windows, state series and outcomes covering every role, or an older run's sequential timeline), single-plane provenance, digest-only checkpoints and the mandatory attributionLimits", "shared-world findings"),
+        {
+            name: "cleanup receipt",
+            ok: cleanupJson === null || (isCleanupResult(cleanupJson) && cleanupJson.ok),
+            message: cleanupJson === null
+                ? "cleanup receipt not present; cleanup was not requested"
+                : isCleanupResult(cleanupJson) && cleanupJson.ok
+                    ? "cleanup receipt is present and successful"
+                    : "cleanup receipt is present but malformed or failed",
+        },
+        findingsCheck("rerun lineage", valid ? rerunLineageFindings(valid) : [], "rerun bundles either are absent or link selected participants to their prior status and a fan-out rerun event", "rerun lineage findings"),
+        // Cost is ADVISORY on magnitude, FAIL-CLOSED on labeling/provenance (claims match mechanism).
+        // Absence PASSES (fail-open on display); a claimed dollar figure without its ratesAsOf date +
+        // source, or a total that does not match its known lines, FAILS. Magnitude is never inspected —
+        // a correctly-labeled huge estimate still passes.
+        findingsCheck("cost estimate labeling", valid ? costAndReceiptFindings(valid) : [], "cost figures are absent, or every claimed estimate carries its ratesAsOf date + source and the total matches its known lines (estimates never presented as exact)", "cost labeling findings"),
+    ];
+    return checks;
+}
+/** Non-fatal hosted-desktop geometry disclosures, deduplicated across shared-screen streams. */
+function desktopGeometryWarnings(bundle) {
+    return [...new Set(bundle.streams.flatMap((stream) => stream.desktopGeometry?.warnings ?? []))];
+}
+function buildShareSafety(args) {
+    const reasons = [];
+    if (!args.ok) {
+        reasons.push({
+            code: "VERIFY_FAILED",
+            message: "The run bundle is not valid enough to promote into public feedback.",
+        });
+    }
+    if (args.publicSafetyFindings.length > 0) {
+        reasons.push({
+            code: "PUBLIC_SAFETY_FINDINGS",
+            message: "Text artifacts or public-proof paths matched known secret, token, local-path, browser-profile, or hosted-substrate URL patterns.",
+        });
+    }
+    if (args.bundle.publication !== undefined || args.bundle.commsReceiving !== undefined) {
+        reasons.push({
+            code: "REAL_COMMUNICATIONS",
+            message: "This study used real email. Message content may appear in recordings, narration or analysis. Local review is supported; screenshot blurring does not make it public-safe.",
+        });
+    }
+    if (args.bundle.streams.some((stream) => stream.recording !== undefined)) {
+        reasons.push({
+            code: "CONTINUOUS_MEDIA",
+            message: "Continuous screen/audio recordings are retained for local review. Screenshot redaction does not redact this media.",
+        });
+    }
+    if (args.unscannedArtifacts.length > 0) {
+        const paths = [...args.unscannedArtifacts].sort();
+        const shown = paths.slice(0, MAX_LISTED_UNSCANNED).join(", ");
+        const more = paths.length - MAX_LISTED_UNSCANNED;
+        reasons.push({
+            code: "UNSCANNED_ARTIFACT",
+            message: `The public-safety scan cannot read ${paths.length} file(s) as text, and they are not stream screenshots under screenshots/ or registered recordings: ${shown}${more > 0 ? ` and ${more} more` : ""}. Review them before sharing.`,
+        });
+    }
+    const rawStreamIds = rawScreenshotStreamIds(args.bundle, args.redactedShapeFrames);
+    if (rawStreamIds.length > 0) {
+        reasons.push({
+            code: "RAW_SCREENSHOTS",
+            message: `Full-fidelity screenshots, or frames with no redaction claim, are present on ${rawStreamIds.join(", ")}. This is valid local evidence, but not share-ready as-is.`,
+        });
+    }
+    if (reasons.some((reason) => reason.code === "VERIFY_FAILED" || reason.code === "PUBLIC_SAFETY_FINDINGS")) {
+        return { status: "blocked", reasons };
+    }
+    if (reasons.length > 0) {
+        return { status: "local_only", reasons };
+    }
+    return { status: "share_ready", reasons: [] };
+}

package/docs/README.md

@@ -0,0 +1,67 @@
+# Find the right doc
+
+Start with the reading order in [CONTRIBUTING.md](../CONTRIBUTING.md#read-these-in-order). This page
+sorts everything under `docs/` by what it is for. Nothing here moves files; a folder that holds more
+than one kind is split file by file.
+
+## Follow a guide to do a task
+
+- [ramp/README.md](ramp/README.md): current state, how to pick work and the quality bar.
+- [architecture/local-browser-runtime.md](architecture/local-browser-runtime.md): run a study in a
+  local Firecracker browser.
+- [architecture/real-email-receiving.md](architecture/real-email-receiving.md) and
+  [architecture/comms-inbox.md](architecture/comms-inbox.md): give participants real or captured
+  inboxes.
+- [architecture/participant-media.md](architecture/participant-media.md) and
+  [architecture/desktop-recording.md](architecture/desktop-recording.md): add a camera, speech or
+  a desktop video.
+- [architecture/observer-review.md](architecture/observer-review.md): watch and review a study.
+- [architecture/project-layout.md](architecture/project-layout.md): the `humanish/` and
+  `.humanish/` folders `init` creates.
+- [product/lobby-trivia-3player-external-public.md](product/lobby-trivia-3player-external-public.md):
+  a worked example of the external-public shared-world lab.
+- [release/open-source-readiness.md](release/open-source-readiness.md): the release gates and the
+  publish procedure. Its opening audit is a dated snapshot.
+
+## Look up what the code does now
+
+- [contracts/](contracts/schemas.md): bundle, lab, policy, feedback, analysis and cost contracts.
+  Documented fields are API. [contracts/schemas.md](contracts/schemas.md) indexes every schema.
+- [architecture/observer.md](architecture/observer.md), [architecture/serve.md](architecture/serve.md):
+  the Observer and the run library server.
+- [architecture/desktop-sessions.md](architecture/desktop-sessions.md),
+  [architecture/browser-control.md](architecture/browser-control.md),
+  [architecture/guest-desktop.md](architecture/guest-desktop.md): hosted desktops, the browser
+  control protocol and the guest runtime.
+- [architecture/state-driven-executor.md](architecture/state-driven-executor.md): the `CuaExecutor`
+  library path.
+- [architecture/task-protocol-support.md](architecture/task-protocol-support.md): which routes
+  accept `actors[0].tasks`.
+- [architecture/external-public-shared-world.md](architecture/external-public-shared-world.md) and
+  [architecture/terminal-product-lane.md](architecture/terminal-product-lane.md): two routes in
+  depth. Both keep dated slice notes beside the current rules.
+- [architecture/restricted-codex-analysis.md](architecture/restricted-codex-analysis.md) and
+  [product/automatic-analysis.md](product/automatic-analysis.md): study analysis.
+- [release/public-readiness-standard.md](release/public-readiness-standard.md): what may appear in
+  the public repository and the npm package.
+
+## Read why the code is shaped this way
+
+- [principles/](principles/engineering.md): engineering, invariants and defaults, actor fidelity,
+  the three roles and the self-driving harness.
+- [decisions/](decisions/README.md): one record per decision, each naming the code or test that
+  enforces it.
+- [architecture/actor-contract.md](architecture/actor-contract.md) and
+  [architecture/github-feedback-loop.md](architecture/github-feedback-loop.md): design records with
+  their context and open items.
+- [product/open-source-install-experience.md](product/open-source-install-experience.md): the
+  product target for install and first run.
+
+## Treat these folders as history
+
+`goals/`, `plans/` and `roadmap/` hold dated plans, status logs and receipts. They may name files
+that have since moved, so `docs:check` skips them (`HISTORY_DIRECTORIES` in
+[scripts/lib/doc-paths.ts](../scripts/lib/doc-paths.ts)). One file there is current:
+[goals/current.md](goals/current.md), the live status page.
+
+`assets/` holds images that ship in the npm package, such as the README hero.