@spine-event-engine/testing 2.0.0-snapshot.21 → 2.0.0-snapshot.23

package/dist/ai-test/scripted-attempts.d.ts

@@ -0,0 +1,261 @@
+import { type MessageSchema } from "@spine-event-engine/core";
+import type { AiAnswer, AiDecisionResult, AiFailure, AiModelDefinition, AiValidationIssue } from "@spine-event-engine/ai";
+import { type AiCandidateAdmission, type AiAttemptRequest, type AiAttemptReplay, type AiAttemptTicket, type AiBackendExecution, type AiBackendOutcome } from "@spine-event-engine/ai/spi/adapter";
+import { type AiContentDigest, type AiUsage, type DecisionAnswer, type DecisionDistribution, type DecisionQuestion, type DecisionResponse, type GenerationResponse } from "@spine-event-engine/proto/agent";
+import type { AiTestGate, AiTestRequest, AiTestResponses } from "./ai-test-backend.js";
+interface FailureScript {
+    readonly kind: "failure";
+    readonly code: AiFailure["code"];
+    readonly retryable: boolean;
+    usage?: AiUsage;
+}
+interface TextScript {
+    readonly kind: "text";
+    readonly text: string;
+    usage?: AiUsage;
+}
+interface DecisionScript {
+    readonly kind: "decision";
+    readonly result: AiDecisionResult;
+    usage?: AiUsage;
+}
+interface DelayScript {
+    readonly kind: "delay";
+    readonly gate: Gate;
+}
+/**
+ * One queued simulated provider response or release gate.
+ */
+export type Script = FailureScript | TextScript | DecisionScript | DelayScript;
+type DecisionQuestionDefinition = Extract<AiModelDefinition<MessageSchema, MessageSchema>, {
+    kind: "decision";
+}>["questions"][string];
+/**
+ * Queued behavior for one factory-created capability.
+ */
+export interface ScriptQueue {
+    /**
+     * Validated immutable capability declaration.
+     */
+    readonly definition: Readonly<AiModelDefinition<MessageSchema, MessageSchema>>;
+    /**
+     * Responses not yet consumed by physical requests.
+     */
+    readonly scripts: Script[];
+}
+/**
+ * Mutable internal observation copied by the public snapshot method.
+ */
+export interface RequestRecord extends AiTestRequest {
+    /**
+     * Runtime operation identity used for attempt numbering.
+     */
+    readonly operation: string;
+    /**
+     * Runtime-assigned attempt identity after the begin barrier.
+     */
+    ticketId?: string;
+    /**
+     * Whether the reservation barrier admitted physical dispatch.
+     */
+    dispatched?: boolean;
+    /**
+     * Whether an admitted request reached a terminal scripted outcome.
+     */
+    settled?: boolean;
+    /**
+     * Whether no scripted response matched the admitted request.
+     */
+    unexpected?: boolean;
+    /**
+     * Local validation issues saved after response admission.
+     */
+    validationIssues: readonly AiValidationIssue[];
+    /**
+     * Exact previous generation text used to prepare a correction request.
+     */
+    candidateText?: string;
+    /**
+     * Candidate text copied from the prior invalid attempt.
+     */
+    correctionCandidate?: string;
+}
+interface ScriptedAttemptOps {
+    /**
+     * Returns a capability key without conflating revisions.
+     *
+     * @param name Name for this operation.
+     * @param version Version for this operation.
+     * @returns Revision-qualified capability key.
+     */
+    key(name: string, version: string): string;
+    /**
+     * Returns the scripted responses result.
+     *
+     * @typeParam O Generated output descriptor.
+     * @param queue Queue for this operation.
+     * @param output Output for this operation.
+     * @returns Queue writer for this capability.
+     */
+    responses<O extends MessageSchema>(queue: ScriptQueue, output: O): AiTestResponses<O>;
+    /**
+     * Returns the scripted record result.
+     *
+     * @param request Request for this operation.
+     * @param attempt Attempt for this operation.
+     * @param prior Prior for this operation.
+     * @returns Mutable internal request record.
+     */
+    record(request: AiBackendExecution, attempt: number, prior?: RequestRecord): RequestRecord;
+    /**
+     * Returns the scripted snapshot result.
+     *
+     * @param record Record for this operation.
+     * @returns Immutable physical-request observation.
+     */
+    snapshot(record: RequestRecord): AiTestRequest;
+    /**
+     * Returns the scripted execute result.
+     *
+     * @param request Request for this operation.
+     * @param record Record for this operation.
+     * @param queue Queue for this operation.
+     * @returns Admitted output or recorded failure.
+     */
+    execute(request: AiBackendExecution, record: RequestRecord, queue?: ScriptQueue): Promise<AiBackendOutcome>;
+    /**
+     * Restores a saved response without consuming a queued physical script.
+     *
+     * @param request Selected scripted execution.
+     * @param saved Durable response and matching original failure.
+     * @returns Saved admitted output or exact recorded failure.
+     */
+    replay(request: AiBackendExecution, saved: AiAttemptReplay): AiBackendOutcome;
+    /**
+     * Checks saved failure correlation before reuse.
+     *
+     * @param response Saved terminal response.
+     * @param failure Original persisted failure, when available.
+     * @returns Exact saved failure.
+     */
+    replayFailure(response: AiAttemptReplay["response"], failure?: AiFailure): AiBackendOutcome;
+    /**
+     * Returns the scripted prepare result.
+     *
+     * @param request Request for this operation.
+     * @param record Record for this operation.
+     * @returns Typed model-facing request.
+     */
+    prepare(request: AiBackendExecution, record: RequestRecord): AiAttemptRequest;
+    /**
+     * Returns the scripted question result.
+     *
+     * @param id Id for this operation.
+     * @param question Question for this operation.
+     * @returns Typed question record.
+     */
+    question(id: string, question: DecisionQuestionDefinition): DecisionQuestion;
+    /**
+     * Returns the SHA-256 digest of content.
+     *
+     * @param value Value for this operation.
+     * @returns SHA-256 content digest.
+     */
+    digest(value: string): AiContentDigest;
+    /**
+     * Returns the scripted failure result.
+     *
+     * @param request Request for this operation.
+     * @param ticket Ticket for this operation.
+     * @param code Code for this operation.
+     * @param retryable Retryable for this operation.
+     * @param usage Usage for this operation.
+     * @returns Runtime-recorded safe failure.
+     */
+    failure(request: AiBackendExecution, ticket: AiAttemptTicket, code: AiFailure["code"], retryable: boolean, usage?: AiUsage): Promise<AiBackendOutcome>;
+    /**
+     * Validates and journals one generation candidate.
+     *
+     * @param request Request for this operation.
+     * @param ticket Ticket for this operation.
+     * @param record Record for this operation.
+     * @param script Script for this operation.
+     * @returns Validated output or recorded failure.
+     */
+    generation(request: AiBackendExecution, ticket: AiAttemptTicket, record: RequestRecord, script: TextScript): Promise<AiBackendOutcome>;
+    /**
+     * Validates and journals one non-generative decision.
+     *
+     * @param request Request for this operation.
+     * @param ticket Ticket for this operation.
+     * @param record Record for this operation.
+     * @param script Script for this operation.
+     * @returns Validated output or recorded failure.
+     */
+    decision(request: AiBackendExecution, ticket: AiAttemptTicket, record: RequestRecord, script: DecisionScript): Promise<AiBackendOutcome>;
+    /**
+     * Builds one provider answer for the decision journal.
+     *
+     * @param id Id for this operation.
+     * @param answer Answer for this operation.
+     * @returns Typed provider answer.
+     */
+    answer(id: string, answer: AiAnswer): DecisionAnswer;
+    /**
+     * Maps one answer kind to its Proto oneof.
+     *
+     * @param answer Answer for this operation.
+     * @returns Typed answer oneof.
+     */
+    answerValue(answer: AiAnswer): DecisionAnswer["value"];
+    /**
+     * Builds a provider answer distribution.
+     *
+     * @param probabilities Probabilities for this operation.
+     * @returns Typed full distribution.
+     */
+    distribution(probabilities: Readonly<Record<string, number>>): DecisionDistribution;
+    /**
+     * Builds a generation response for the journal.
+     *
+     * @param request Request for this operation.
+     * @param script Script for this operation.
+     * @param admitted Admitted for this operation.
+     * @param failure Failure for this operation.
+     * @returns Journal-ready generation response.
+     */
+    generationReply(request: AiBackendExecution, script: TextScript, admitted: AiCandidateAdmission, failure?: AiFailure): GenerationResponse;
+    /**
+     * Builds a decision response for the journal.
+     *
+     * @param request Request for this operation.
+     * @param script Script for this operation.
+     * @param admitted Admitted for this operation.
+     * @param failure Failure for this operation.
+     * @returns Journal-ready decision response.
+     */
+    decisionReply(request: AiBackendExecution, script: DecisionScript, admitted: AiCandidateAdmission, failure?: AiFailure): DecisionResponse;
+}
+/**
+ * One externally released response gate.
+ */
+declare class Gate implements AiTestGate {
+    #private;
+    /**
+     * Completes the pending response.
+     */
+    release(): void;
+    /**
+     * Awaits gate release or cancellation.
+     *
+     * @param signal Signal for this operation.
+     * @returns Completion after release or cancellation.
+     */
+    wait(signal: AbortSignal): Promise<void>;
+}
+/**
+ * Constructs scripted requests and crosses the same runtime barriers as adapters.
+ */
+export declare const ScriptedAttempts: ScriptedAttemptOps;
+export {};
+//# sourceMappingURL=scripted-attempts.d.ts.map

package/dist/ai-test/scripted-attempts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scripted-attempts.d.ts","sourceRoot":"","sources":["../../src/ai-test/scripted-attempts.ts"],"names":[],"mappings":"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"}