@skill-harness/core 0.11.0 → 0.12.0

package/dist/qualification-store.d.ts

@@ -0,0 +1,187 @@
+import { QUALIFICATION_OAUTH_DIRECTORY_POLICY_V2, QUALIFICATION_TERMINAL_RECEIPT_VERSION_V3, type QualificationArmV1, type QualificationConfigV1, type QualificationInvocationRequestV1, type QualificationRole, type QualificationAccountingPolicy, verifyQualificationExecutable } from "./qualification-config.js";
+export declare const QUALIFICATION_INVOCATION_VERSION: "qualification-invocation-v1";
+export declare const QUALIFICATION_INVOCATION_VERSION_V2: "qualification-invocation-v2";
+export declare const QUALIFICATION_INVOCATION_VERSION_V3: "qualification-invocation-v3";
+export declare const QUALIFICATION_INVOCATION_VERSION_V4: "qualification-invocation-v4";
+export declare const QUALIFICATION_INVOCATION_INPUT_BINDING_VERSION: "qualification-invocation-input-binding-v1";
+export declare const QUALIFICATION_LIFECYCLE_VERSION: "qualification-lifecycle-v1";
+export declare const QUALIFICATION_ACCOUNTING_VERSION: "qualification-accounting-v1";
+export type QualificationLifecyclePhase = "prepared" | "launch-claimed" | "running" | "terminal";
+export type QualificationTerminalStatus = "completed" | "failed" | "timed-out" | "aborted" | "refused" | "invalid-artifact";
+export interface QualificationInvocationInputBindingV1 {
+    schema_version: typeof QUALIFICATION_INVOCATION_INPUT_BINDING_VERSION;
+    content_type: "application/json";
+    bytes: number;
+    sha256: string;
+}
+export interface QualificationInvocationInputOccurrenceV1 {
+    path: string;
+    realpath: string;
+    device: number;
+    inode: number;
+    mode: number;
+    uid: number;
+    gid: number;
+    link_count: number;
+    bytes: number;
+    sha256: string;
+}
+export interface QualificationInvocationV1 {
+    schema_version: typeof QUALIFICATION_INVOCATION_VERSION | typeof QUALIFICATION_INVOCATION_VERSION_V2 | typeof QUALIFICATION_INVOCATION_VERSION_V3 | typeof QUALIFICATION_INVOCATION_VERSION_V4;
+    /** Present only in v2/v3 records; omission retains the historical digest. */
+    oauth_directory_policy?: typeof QUALIFICATION_OAUTH_DIRECTORY_POLICY_V2;
+    /** Present only in v3 records; omission cannot be interpreted as v3. */
+    terminal_receipt_version?: typeof QUALIFICATION_TERMINAL_RECEIPT_VERSION_V3;
+    invocation_input?: QualificationInvocationInputBindingV1;
+    invocation_input_occurrence?: QualificationInvocationInputOccurrenceV1;
+    prepared_attempt?: 0;
+    accounting_event_sha256?: null;
+    invocation_id: string;
+    measurement_identity_sha256: string;
+    continuation_authority_sha256: string;
+    continuation_authority_expires_at: string;
+    scenario: QualificationInvocationRequestV1["scenario"];
+    role: QualificationRole;
+    counts_as_measurement: boolean;
+    arms: {
+        subject: string;
+        judge: string;
+        selected: string;
+    };
+    repetition: number;
+    /** Present only in v4 judge-panel member invocations. */
+    panel?: NonNullable<QualificationInvocationRequestV1["panel"]>;
+    requested: {
+        provider: string;
+        model: string;
+    };
+    authentication: QualificationArmV1["authentication"];
+    pins: {
+        product: QualificationConfigV1["product"];
+        engine: QualificationConfigV1["engine"];
+        producer: QualificationConfigV1["producer"];
+        runner: QualificationConfigV1["runner"];
+    };
+    configuration_sha256: string;
+    created_at: string;
+    ceiling_policy: QualificationAccountingPolicy;
+    execution: {
+        executable: QualificationArmV1["executable"];
+        executable_identity: ReturnType<typeof verifyQualificationExecutable>;
+        resources: QualificationArmV1["resources"];
+        working_directory_identity: {
+            realpath: string;
+            device: number;
+            inode: number;
+        };
+        arguments: string[];
+        allowed_environment_names: string[];
+        timeout_ms: number;
+        output_limit_bytes: number;
+        fallback: false;
+        metered_override: false;
+    };
+    expected_artifact: {
+        path: string;
+        type: "pi-jsonl";
+    };
+    /** Self-digest over every preceding field; detects accidental mutation. */
+    invocation_sha256: string;
+}
+export interface QualificationLifecycleEvent {
+    seq: number;
+    from: QualificationLifecyclePhase | null;
+    to: QualificationLifecyclePhase;
+    terminal_status: QualificationTerminalStatus | null;
+    at: string;
+    detail: Record<string, unknown>;
+    previous_sha256: string | null;
+    event_sha256: string;
+}
+export interface QualificationLifecycleV1 {
+    schema_version: typeof QUALIFICATION_LIFECYCLE_VERSION;
+    invocation_id: string;
+    phase: QualificationLifecyclePhase;
+    terminal_status: QualificationTerminalStatus | null;
+    events: QualificationLifecycleEvent[];
+    chain_head: string;
+}
+export interface QualificationAccountingEventInput {
+    invocation_id: string;
+    role: QualificationRole;
+    call_class: "subject" | "judge";
+    counts_as_measurement: boolean;
+    launched_at: string;
+}
+export interface QualificationAccountingEvent extends QualificationAccountingEventInput {
+    seq: number;
+    previous_sha256: string | null;
+    event_sha256: string;
+}
+export interface QualificationAccountingLedgerV1 {
+    schema_version: typeof QUALIFICATION_ACCOUNTING_VERSION;
+    policy: QualificationAccountingPolicy;
+    events: QualificationAccountingEvent[];
+    chain_head: string | null;
+}
+export interface QualificationAccountingReport {
+    counts: {
+        subject: number;
+        judge: number;
+        measurement: number;
+        total: number;
+    };
+    roles: Partial<Record<QualificationRole, number>>;
+    chain_head: string | null;
+}
+export interface QualificationSpoolValidation {
+    ok: true;
+    configuration_sha256: string;
+    invocations: number;
+    accounting: QualificationAccountingReport;
+}
+export declare function qualificationSpoolPaths(spoolDir: string, invocationId?: string): {
+    root: string;
+    configuration: string;
+    accounting: string;
+    lock: string;
+    invocations: string;
+    artifacts: string;
+    invocation: string | undefined;
+    invocationRecord: string | undefined;
+    lifecycle: string | undefined;
+    invocationLock: string | undefined;
+    terminal: string | undefined;
+};
+export declare function prepareQualificationInvocation(options: {
+    spool_dir: string;
+    config_path: string;
+    request_path: string;
+    expected_configuration_sha256?: string;
+    now?: () => string;
+    /** Deterministic source-race injection for offline tests only. */
+    test_hooks?: {
+        after_initial_input_validation?: () => void;
+    };
+}): QualificationInvocationV1;
+export declare function readQualificationInvocation(spoolDir: string, invocationId: string): QualificationInvocationV1;
+export declare function readQualificationLifecycle(spoolDir: string, invocationId: string): QualificationLifecycleV1;
+export declare function writeQualificationLifecycle(spoolDir: string, lifecycle: QualificationLifecycleV1): void;
+export declare function transitionQualificationLifecycle(lifecycle: QualificationLifecycleV1, to: QualificationLifecyclePhase, options: {
+    at: string;
+    terminal_status?: QualificationTerminalStatus | null;
+    detail?: Record<string, unknown>;
+}): QualificationLifecycleV1;
+export declare function createQualificationAccountingLedger(policy?: QualificationAccountingPolicy): QualificationAccountingLedgerV1;
+export declare function appendQualificationAccountingEvent(inputLedger: QualificationAccountingLedgerV1, input: QualificationAccountingEventInput): QualificationAccountingLedgerV1;
+export declare function validateQualificationAccountingLedger(value: unknown): QualificationAccountingReport;
+export declare function readQualificationAccounting(spoolDir: string): QualificationAccountingLedgerV1;
+export declare function writeQualificationAccounting(spoolDir: string, ledger: QualificationAccountingLedgerV1): void;
+export declare function validateQualificationSpool(spoolDir: string): QualificationSpoolValidation;
+export declare function readQualificationSpoolConfig(spoolDir: string): QualificationConfigV1;
+export declare function withQualificationFileLock<T>(lockPath: string, action: () => T): T;
+export declare function atomicWriteCanonical(path: string, value: unknown, exclusive: boolean): void;
+export declare function atomicWriteBytes(path: string, bytes: Buffer, exclusive: boolean): void;
+export declare function readCanonicalJson(path: string, ctx: string): unknown;
+export declare function verifyQualificationInvocationInput(invocation: QualificationInvocationV1): QualificationInvocationInputBindingV1;
+export declare function fsyncQualificationDirectory(path: string): void;