@colophon-claims/verify 0.0.0 → 0.2.0

package/dist/profile/errors.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The product's typed error posture (spec §4.3, assumption A8).
+ *
+ * Every operation returns either a typed result or a typed error — never a silent
+ * fallback, never free-text-only failure. Callers branch on `code` (and, where they
+ * care, on `issues[].path`), never on `message`: messages are prose and free to
+ * change; codes and paths are the contract.
+ *
+ * The v1 code set refines the spec §4.3 categories per A8 ("refined per operation
+ * in BP-10"):
+ *
+ * - `authority` is realized as `authority-denied` (the operations-boundary refusal).
+ * - `journal-integrity`, `not-found`, `conflict`, and `invalid-invocation` are BP-10
+ *   refinements: a malformed audit journal, a missing subject, a workspace/draft
+ *   collision, and a CLI-level invocation error are four different situations a
+ *   machine caller must distinguish.
+ * - `venue-unavailable`, `venue-unverifiable`, and `execution` are reserved here so
+ *   later packets (venue selection, launch) extend the taxonomy without a breaking
+ *   change; BP-10 raises `execution` only as the carrier for untyped throws.
+ */
+export declare const PRODUCT_ERROR_CODES: readonly ["validation", "illegal-transition", "authority-denied", "record-integrity", "journal-integrity", "not-found", "conflict", "invalid-invocation", "venue-unavailable", "venue-unverifiable", "execution"];
+export type ProductErrorCode = (typeof PRODUCT_ERROR_CODES)[number];
+export interface ProductIssue {
+    readonly path: string;
+    readonly message: string;
+}
+/**
+ * The machine-readable error envelope (spec §4.3): the same shape on the library
+ * surface and inside the CLI's `--json` output.
+ */
+export interface ProductErrorEnvelope {
+    readonly code: ProductErrorCode;
+    readonly detail: string;
+    readonly issues?: readonly ProductIssue[];
+}
+export declare class BenchmarkProductError extends Error {
+    readonly code: ProductErrorCode;
+    readonly issues: readonly ProductIssue[];
+    constructor(code: ProductErrorCode, message: string, issues?: readonly ProductIssue[]);
+}
+/** Throws a typed error carrying a single issue. */
+export declare function refuse(code: ProductErrorCode, path: string, message: string): never;
+/** Throws a typed error carrying every issue; the first issue's message leads. */
+export declare function refuseWithIssues(code: ProductErrorCode, issues: readonly ProductIssue[]): never;
+/**
+ * Adapts any thrown value to the machine-readable envelope. A typed error keeps its
+ * code and issues; anything else is carried as `execution` — visible, never swallowed.
+ */
+export declare function toErrorEnvelope(cause: unknown): ProductErrorEnvelope;

package/dist/profile/errors.js

@@ -0,0 +1,78 @@
+/**
+ * The product's typed error posture (spec §4.3, assumption A8).
+ *
+ * Every operation returns either a typed result or a typed error — never a silent
+ * fallback, never free-text-only failure. Callers branch on `code` (and, where they
+ * care, on `issues[].path`), never on `message`: messages are prose and free to
+ * change; codes and paths are the contract.
+ *
+ * The v1 code set refines the spec §4.3 categories per A8 ("refined per operation
+ * in BP-10"):
+ *
+ * - `authority` is realized as `authority-denied` (the operations-boundary refusal).
+ * - `journal-integrity`, `not-found`, `conflict`, and `invalid-invocation` are BP-10
+ *   refinements: a malformed audit journal, a missing subject, a workspace/draft
+ *   collision, and a CLI-level invocation error are four different situations a
+ *   machine caller must distinguish.
+ * - `venue-unavailable`, `venue-unverifiable`, and `execution` are reserved here so
+ *   later packets (venue selection, launch) extend the taxonomy without a breaking
+ *   change; BP-10 raises `execution` only as the carrier for untyped throws.
+ */
+export const PRODUCT_ERROR_CODES = [
+    /** Draft or document content invalid (schema issues carried in `issues`). */
+    "validation",
+    /** The operation is not valid in the subject's current lifecycle state. */
+    "illegal-transition",
+    /** The acting principal is not a workspace member or lacks the required grant. */
+    "authority-denied",
+    /** Stored sealed bytes fail their digest check on read. */
+    "record-integrity",
+    /** The audit journal on disk is not well-formed, ordered JSONL. */
+    "journal-integrity",
+    /** The named workspace, draft, or record does not exist. */
+    "not-found",
+    /** The write collides with existing state (workspace already initialized, draft id taken). */
+    "conflict",
+    /** CLI-level: unknown verb, unknown flag, or missing required flag. */
+    "invalid-invocation",
+    /** Reserved for later packets (spec §7.3): the selected venue is not available. */
+    "venue-unavailable",
+    /** Reserved for later packets (spec §7.3): a venue guarantee cannot be verified. */
+    "venue-unverifiable",
+    /** Backend-reported or untyped failure, carried through rather than swallowed. */
+    "execution",
+];
+export class BenchmarkProductError extends Error {
+    code;
+    issues;
+    constructor(code, message, issues = []) {
+        super(message);
+        this.name = "BenchmarkProductError";
+        this.code = code;
+        this.issues = issues;
+    }
+}
+/** Throws a typed error carrying a single issue. */
+export function refuse(code, path, message) {
+    throw new BenchmarkProductError(code, message, [{ path, message }]);
+}
+/** Throws a typed error carrying every issue; the first issue's message leads. */
+export function refuseWithIssues(code, issues) {
+    const [first] = issues;
+    throw new BenchmarkProductError(code, first === undefined ? code : first.message, issues);
+}
+/**
+ * Adapts any thrown value to the machine-readable envelope. A typed error keeps its
+ * code and issues; anything else is carried as `execution` — visible, never swallowed.
+ */
+export function toErrorEnvelope(cause) {
+    if (cause instanceof BenchmarkProductError) {
+        return cause.issues.length > 0
+            ? { code: cause.code, detail: cause.message, issues: cause.issues }
+            : { code: cause.code, detail: cause.message };
+    }
+    return {
+        code: "execution",
+        detail: cause instanceof Error ? cause.message : String(cause),
+    };
+}

package/dist/profile/inspect-assurance.d.ts

@@ -0,0 +1,16 @@
+import type { InspectSelectionManifest } from "./inspect-manifest.js";
+export interface InspectAssurance {
+    readonly independence?: string;
+    readonly minVerdicts?: number;
+    readonly distinctEvaluator?: boolean;
+    readonly verdictRule?: string;
+}
+export type InspectEvaluationStrategy = "embedded" | "separate-log-verification";
+export declare const INSPECT_SEPARATE_ASSURANCE_LIMITATIONS: readonly ["Inspect scores came from scorers in the same task execution; official verdicts separately verified the sealed projection from the native log.", "Separate verifier processes and evaluator keys on this self-run venue do not establish a separate real-world party.", "Log verification is not independent rescoring and does not establish method diversity."];
+export declare function deriveInspectEvaluationStrategy(assurance: Readonly<InspectAssurance> | undefined): InspectEvaluationStrategy;
+export declare function inspectLogVerifierMethod(manifest: InspectSelectionManifest, selectionManifestSha256: string): {
+    readonly name: "benchmark-product-inspect-log-verifier";
+    readonly digest: {
+        readonly sha256: string;
+    };
+};

package/dist/profile/inspect-assurance.js

@@ -0,0 +1,30 @@
+import { createHash } from "node:crypto";
+import { canonicalJsonBytes } from "@jinn-network/trust-core";
+export const INSPECT_SEPARATE_ASSURANCE_LIMITATIONS = [
+    "Inspect scores came from scorers in the same task execution; official verdicts separately verified the sealed projection from the native log.",
+    "Separate verifier processes and evaluator keys on this self-run venue do not establish a separate real-world party.",
+    "Log verification is not independent rescoring and does not establish method diversity.",
+];
+export function deriveInspectEvaluationStrategy(assurance) {
+    return (assurance?.independence ?? "disclosed") === "disclosed"
+        && (assurance?.minVerdicts ?? 1) === 1
+        && (assurance?.distinctEvaluator ?? false) === false
+        && (assurance?.verdictRule ?? "sole") === "sole"
+        ? "embedded"
+        : "separate-log-verification";
+}
+export function inspectLogVerifierMethod(manifest, selectionManifestSha256) {
+    const method = {
+        schema: "jinn.network/benchmark-product/inspect-log-verifier-method/1",
+        selectionManifestSha256,
+        adapterVersion: manifest.runtime.adapterVersion,
+        workerSha256: manifest.runtime.workerSha256,
+        inspectVersion: manifest.runtime.inspectVersion,
+    };
+    return {
+        name: "benchmark-product-inspect-log-verifier",
+        digest: {
+            sha256: createHash("sha256").update(canonicalJsonBytes(method)).digest("hex"),
+        },
+    };
+}

package/dist/profile/inspect-disclosure.d.ts

@@ -0,0 +1,28 @@
+import type { VerdictRule } from "@jinn-network/task-execution-profiles";
+import { INSPECT_ADAPTER_ID, type InspectSelectionManifest } from "./inspect-manifest.js";
+import { type InspectAssurance } from "./inspect-assurance.js";
+export interface InspectScoringProjectionDisclosure {
+    readonly measurementName: string;
+    readonly scorerName: string;
+    readonly subScoreKey?: string;
+    readonly passValue: string | number | boolean | null;
+}
+export interface InspectRuntimeMethodDisclosure {
+    readonly adapterId: typeof INSPECT_ADAPTER_ID;
+    readonly selectionManifestSha256: string;
+    readonly scorerNames: readonly string[];
+    readonly projections: readonly InspectScoringProjectionDisclosure[];
+    readonly verdictRule: VerdictRule;
+    readonly verdictRuleText: string;
+    readonly nativeAnalysis: {
+        readonly metrics: unknown;
+        readonly epochReducers: readonly string[] | null;
+    };
+    readonly evaluatorRelationship: "same-execution-scorer";
+    readonly scoreSourceRelationship: "same-execution-scorer";
+    readonly officialEvaluationRelationship: "same-execution-scorer" | "separate-log-verifier";
+    readonly officialEvaluatorCount: number;
+    readonly partyIndependence: "not-established";
+}
+/** Public method disclosure derived only from the authenticated Inspect selection. */
+export declare function describeInspectRuntimeMethod(manifest: InspectSelectionManifest, selectionManifestSha256: string, assurance?: Readonly<InspectAssurance>): InspectRuntimeMethodDisclosure;

package/dist/profile/inspect-disclosure.js

@@ -0,0 +1,54 @@
+import { INSPECT_ADAPTER_ID, isInspectMultiScorerSelection, } from "./inspect-manifest.js";
+import { deriveInspectEvaluationStrategy } from "./inspect-assurance.js";
+function ruleText(rule) {
+    if ("threshold" in rule) {
+        return `${rule.threshold.measurement} ${rule.threshold.op} ${JSON.stringify(rule.threshold.value)}`;
+    }
+    if ("all" in rule)
+        return `all(${rule.all.map(ruleText).join(", ")})`;
+    if ("any" in rule)
+        return `any(${rule.any.map(ruleText).join(", ")})`;
+    if ("not" in rule)
+        return `not(${ruleText(rule.not)})`;
+    if ("inconclusiveWhen" in rule) {
+        return `inconclusive[${rule.class}] when ${ruleText(rule.inconclusiveWhen)}`;
+    }
+    return "pass" in rule ? "pass" : "fail";
+}
+/** Public method disclosure derived only from the authenticated Inspect selection. */
+export function describeInspectRuntimeMethod(manifest, selectionManifestSha256, assurance) {
+    const strategy = deriveInspectEvaluationStrategy(assurance);
+    const projections = isInspectMultiScorerSelection(manifest)
+        ? manifest.scoring.projections
+        : [{
+                measurementName: "inspect-score-pass",
+                scorerName: manifest.scorer.name,
+                passValue: manifest.scorer.passValue,
+            }];
+    const verdictRule = isInspectMultiScorerSelection(manifest)
+        ? manifest.scoring.verdictRule
+        : { threshold: { measurement: "inspect-score-pass", op: "eq", value: true } };
+    return {
+        adapterId: INSPECT_ADAPTER_ID,
+        selectionManifestSha256,
+        scorerNames: isInspectMultiScorerSelection(manifest)
+            ? manifest.scorers.map((scorer) => scorer.name)
+            : [manifest.scorer.name],
+        projections,
+        verdictRule,
+        verdictRuleText: ruleText(verdictRule),
+        nativeAnalysis: isInspectMultiScorerSelection(manifest)
+            ? {
+                metrics: manifest.scoring.inspectMetrics,
+                epochReducers: manifest.scoring.inspectEpochReducers,
+            }
+            : { metrics: null, epochReducers: null },
+        evaluatorRelationship: "same-execution-scorer",
+        scoreSourceRelationship: "same-execution-scorer",
+        officialEvaluationRelationship: strategy === "embedded"
+            ? "same-execution-scorer"
+            : "separate-log-verifier",
+        officialEvaluatorCount: assurance?.minVerdicts ?? 1,
+        partyIndependence: "not-established",
+    };
+}