@distrohelena/canton-typescript-sdk 0.1.5 → 0.1.6

package/dist/testing/daml/daml-create-action-arbitrary.js

@@ -0,0 +1,34 @@
+import * as fc from "fast-check";
+import { TestingConfigurationError } from "../errors/testing-configuration-error.js";
+import { createDamlValueArbitrary } from "./daml-value-arbitrary.js";
+/**
+ * Builds a well-typed, actor-routed automatic create input from declarative
+ * DAML template metadata. Ledger command construction stays in the runtime
+ * adapter.
+ */
+export function createDeclarativeCreateActionArbitrary(catalog, target, options = {}) {
+    const template = catalog.getTemplate(target.templateId);
+    if (template === undefined) {
+        throw new TestingConfigurationError(`Declarative target '${target.key}' does not exist in the DAML catalog.`);
+    }
+    else if (target.actors.length === 0) {
+        throw new TestingConfigurationError(`Declarative target '${target.key}' requires at least one actor.`);
+    }
+    const templateFieldNames = new Set(template.fields.map((field) => field.name));
+    const unknownField = Object.keys(options.fieldArbitraries ?? {})
+        .find((name) => !templateFieldNames.has(name));
+    if (unknownField !== undefined) {
+        throw new TestingConfigurationError(`Declarative target '${target.key}' has no field generator '${unknownField}'.`);
+    }
+    const payload = fc.record(Object.fromEntries(template.fields.map((field) => [
+        field.name,
+        options.fieldArbitraries?.[field.name]
+            ?? createDamlValueArbitrary(field.type, options),
+    ])));
+    return fc.tuple(fc.constantFrom(...target.actors), payload).map(([actor, value]) => Object.freeze({
+        actor,
+        payload: Object.freeze(value),
+        targetKey: target.key,
+        templateId: target.templateId,
+    }));
+}

package/dist/testing/daml/daml-testing-catalog.d.ts

@@ -0,0 +1,38 @@
+import { DamlLfType } from "../../daml-lf/model/daml-lf-type.js";
+export interface DamlTestingChoice {
+    readonly argumentType?: DamlLfType;
+    readonly choice: string;
+    readonly templateId: string;
+}
+export interface DamlTestingTemplate {
+    readonly choices: readonly string[];
+    readonly fields: readonly {
+        readonly name: string;
+        readonly type: DamlLfType;
+    }[];
+    readonly templateId: string;
+}
+export interface DamlTestingCatalog {
+    readonly templates: readonly DamlTestingTemplate[];
+    getChoice(templateId: string, choice: string): DamlTestingChoice | undefined;
+    getTemplate(templateId: string): DamlTestingTemplate | undefined;
+}
+export declare function createDamlTestingCatalog(init: {
+    readonly getTemplates: () => readonly {
+        readonly choices: readonly {
+            readonly name: string;
+            readonly parameter?: {
+                readonly type: DamlLfType;
+            };
+        }[];
+        readonly fields?: readonly {
+            readonly name: string;
+            readonly type: DamlLfType;
+        }[];
+        readonly templateId: {
+            readonly moduleName: string;
+            readonly packageId: string;
+            readonly templateName: string;
+        };
+    }[];
+}): DamlTestingCatalog;

package/dist/testing/daml/daml-testing-catalog.js

@@ -0,0 +1,40 @@
+export function createDamlTestingCatalog(init) {
+    const choices = new Map();
+    const templates = init.getTemplates()
+        .map((template) => {
+        const templateId = formatTemplateId(template.templateId);
+        for (const choice of template.choices) {
+            choices.set(createChoiceKey(templateId, choice.name), Object.freeze({
+                templateId,
+                choice: choice.name,
+                ...(choice.parameter === undefined
+                    ? {}
+                    : { argumentType: choice.parameter.type }),
+            }));
+        }
+        return Object.freeze({
+            templateId,
+            choices: Object.freeze(template.choices.map(({ name }) => name)),
+            fields: Object.freeze((template.fields ?? []).map((field) => Object.freeze({
+                name: field.name,
+                type: field.type,
+            }))),
+        });
+    })
+        .sort((left, right) => left.templateId.localeCompare(right.templateId));
+    return Object.freeze({
+        templates: Object.freeze(templates),
+        getChoice(templateId, choice) {
+            return choices.get(createChoiceKey(templateId, choice));
+        },
+        getTemplate(templateId) {
+            return templates.find((template) => template.templateId === templateId);
+        },
+    });
+}
+function formatTemplateId(value) {
+    return `${value.packageId}:${value.moduleName}:${value.templateName}`;
+}
+function createChoiceKey(templateId, choice) {
+    return `${templateId}:${choice}`;
+}

package/dist/testing/daml/daml-value-arbitrary.d.ts

@@ -0,0 +1,8 @@
+import * as fc from "fast-check";
+import { DamlNumeric } from "../../core/types/daml-numeric.js";
+import { DamlParty } from "../../core/types/daml-party.js";
+import { DamlLfType } from "../../daml-lf/model/daml-lf-type.js";
+export type DamlTestingValue = string | bigint | DamlParty | DamlNumeric;
+export declare function createDamlValueArbitrary(type: DamlLfType, options?: {
+    readonly valueParties?: readonly string[];
+}): fc.Arbitrary<DamlTestingValue>;

package/dist/testing/daml/daml-value-arbitrary.js

@@ -0,0 +1,43 @@
+import * as fc from "fast-check";
+import { DamlNumeric } from "../../core/types/daml-numeric.js";
+import { DamlParty } from "../../core/types/daml-party.js";
+import { DamlLfBuiltinType } from "../../daml-lf/model/daml-lf-builtin-type.js";
+import { TestingConfigurationError } from "../errors/testing-configuration-error.js";
+export function createDamlValueArbitrary(type, options = {}) {
+    if (type.typeConReference !== undefined) {
+        throw new TestingConfigurationError("Automatic DAML value generation does not yet support type constructors.");
+    }
+    switch (type.builtinType) {
+        case DamlLfBuiltinType.text:
+            return fc.string({ maxLength: 64 });
+        case DamlLfBuiltinType.int64:
+            return fc.bigInt({
+                min: -(2n ** 63n),
+                max: (2n ** 63n) - 1n,
+            });
+        case DamlLfBuiltinType.numeric:
+            return createNumericArbitrary(type.numericScale);
+        case DamlLfBuiltinType.party:
+            if (options.valueParties === undefined || options.valueParties.length === 0) {
+                throw new TestingConfigurationError("Automatic DAML party generation requires non-empty valueParties.");
+            }
+            return fc.constantFrom(...options.valueParties).map((party) => new DamlParty(party));
+        default:
+            throw new TestingConfigurationError(`Automatic DAML value generation does not support '${type.builtinType}'.`);
+    }
+}
+function createNumericArbitrary(scale) {
+    const fractionScale = Math.min(scale ?? 6, 6);
+    if (fractionScale < 1) {
+        throw new TestingConfigurationError("Automatic DAML numeric generation requires a Numeric scale of at least one.");
+    }
+    const denominator = 10 ** fractionScale;
+    return fc.integer({ min: -1_000_000, max: 1_000_000 })
+        .filter((value) => value % denominator !== 0)
+        .map((value) => new DamlNumeric(formatNumeric(value, fractionScale)));
+}
+function formatNumeric(value, scale) {
+    const sign = value < 0 ? "-" : "";
+    const digits = Math.abs(value).toString().padStart(scale + 1, "0");
+    return `${sign}${digits.slice(0, -scale)}.${digits.slice(-scale)}`;
+}

package/dist/testing/daml/declarative-campaign-arbitrary.d.ts

@@ -0,0 +1,15 @@
+import * as fc from "fast-check";
+import { InvariantCampaign } from "../campaign/campaign-types.js";
+import { ResolvedDeclarativeTarget } from "../targets/target.js";
+import { DeclarativeAction, DeclarativeActionGenerationOptions } from "./daml-action-arbitrary.js";
+import { DamlTestingCatalog } from "./daml-testing-catalog.js";
+/**
+ * Produces exact-depth declarative action sequences for a campaign. Every
+ * resolved target must be declared by the campaign and every generated actor
+ * must be eligible for that target before execution starts.
+ */
+export declare function createDeclarativeCampaignArbitrary(init: {
+    readonly campaign: InvariantCampaign;
+    readonly catalog: DamlTestingCatalog;
+    readonly targets: readonly ResolvedDeclarativeTarget[];
+} & DeclarativeActionGenerationOptions): fc.Arbitrary<readonly DeclarativeAction[]>;

package/dist/testing/daml/declarative-campaign-arbitrary.js

@@ -0,0 +1,30 @@
+import * as fc from "fast-check";
+import { TestingConfigurationError } from "../errors/testing-configuration-error.js";
+import { createDeclarativeActionArbitrary, } from "./daml-action-arbitrary.js";
+/**
+ * Produces exact-depth declarative action sequences for a campaign. Every
+ * resolved target must be declared by the campaign and every generated actor
+ * must be eligible for that target before execution starts.
+ */
+export function createDeclarativeCampaignArbitrary(init) {
+    validateTargets(init.campaign, init.targets);
+    return fc.array(createDeclarativeActionArbitrary(init.catalog, init.targets, init), {
+        minLength: init.campaign.config.depth,
+        maxLength: init.campaign.config.depth,
+    });
+}
+function validateTargets(campaign, targets) {
+    const declaredTargets = new Map(campaign.targets.map((target) => [target.key, target]));
+    const allActors = Object.keys(campaign.runtime.actors);
+    for (const target of targets) {
+        const declared = declaredTargets.get(target.key);
+        if (declared === undefined) {
+            throw new TestingConfigurationError(`Declarative target '${target.key}' is absent from the campaign definition.`);
+        }
+        const eligibleActors = new Set(declared.actors ?? allActors);
+        const invalidActor = target.actors.find((actor) => !eligibleActors.has(actor));
+        if (invalidActor !== undefined) {
+            throw new TestingConfigurationError(`Declarative target '${target.key}' assigns ineligible actor '${invalidActor}'.`);
+        }
+    }
+}

package/dist/testing/errors/invariant-campaign-failure.d.ts

@@ -0,0 +1,24 @@
+import { CampaignInvariantFailure } from "../campaign/campaign-runner.js";
+import { CampaignMetrics } from "../campaign/campaign-metrics.js";
+export interface InvariantCampaignFailureInit<Trace = unknown> {
+    readonly artifactPath?: string;
+    readonly cause?: unknown;
+    readonly failures: readonly CampaignInvariantFailure[];
+    readonly message: string;
+    readonly metrics: CampaignMetrics;
+    readonly trace?: Trace;
+}
+/**
+ * A safe public summary of a failed invariant campaign.
+ *
+ * The original cause is intentionally retained in a private field so that
+ * credentials or transport details cannot be serialized with this error.
+ */
+export declare class InvariantCampaignFailure<Trace = unknown> extends Error {
+    #private;
+    readonly artifactPath?: string;
+    readonly failures: readonly CampaignInvariantFailure[];
+    readonly metrics: CampaignMetrics;
+    readonly trace?: Trace;
+    constructor(init: InvariantCampaignFailureInit<Trace>);
+}

package/dist/testing/errors/invariant-campaign-failure.js

@@ -0,0 +1,37 @@
+/**
+ * A safe public summary of a failed invariant campaign.
+ *
+ * The original cause is intentionally retained in a private field so that
+ * credentials or transport details cannot be serialized with this error.
+ */
+export class InvariantCampaignFailure extends Error {
+    artifactPath;
+    failures;
+    metrics;
+    trace;
+    #cause;
+    constructor(init) {
+        super(init.message);
+        this.name = "InvariantCampaignFailure";
+        this.artifactPath = init.artifactPath;
+        this.failures = Object.freeze(init.failures.map((failure) => Object.freeze({
+            ...failure,
+        })));
+        this.metrics = snapshotMetrics(init.metrics);
+        this.trace = init.trace;
+        this.#cause = init.cause;
+        Object.freeze(this);
+    }
+}
+function snapshotMetrics(metrics) {
+    return Object.freeze({
+        byActor: snapshotMetricGroup(metrics.byActor),
+        byTarget: snapshotMetricGroup(metrics.byTarget),
+    });
+}
+function snapshotMetricGroup(group) {
+    return Object.freeze(Object.fromEntries(Object.entries(group).map(([key, values]) => [
+        key,
+        Object.freeze({ ...values }),
+    ])));
+}

package/dist/testing/errors/testing-configuration-error.d.ts

@@ -0,0 +1,3 @@
+export declare class TestingConfigurationError extends Error {
+    constructor(message: string);
+}

package/dist/testing/errors/testing-configuration-error.js

@@ -0,0 +1,6 @@
+export class TestingConfigurationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "TestingConfigurationError";
+    }
+}

package/dist/testing/handlers/handler.d.ts

@@ -0,0 +1,19 @@
+export type CampaignHandlerCleanup = "none" | {
+    readonly archive: (contractId: string) => Promise<void>;
+    readonly discover: () => Promise<readonly string[]>;
+    readonly trackCreated?: (contractId: string) => void;
+};
+export interface CampaignHandler<Input = unknown, Context = unknown> {
+    readonly assume?: (context: Context, input: Input) => boolean | Promise<boolean>;
+    readonly cleanup: CampaignHandlerCleanup;
+    readonly name: string;
+}
+export declare function handler<Input = unknown, Context = unknown>(name: string, init: Omit<CampaignHandler<Input, Context>, "name">): CampaignHandler<Input, Context>;
+export declare function evaluateHandlerAssumptionAsync<Input, Context>(value: CampaignHandler<Input, Context>, context: Context, input: Input): Promise<{
+    readonly kind: "eligible";
+} | {
+    readonly kind: "discarded";
+    readonly reason: string;
+}>;
+export declare function bound(value: number, minimum: number, maximum: number): number;
+export declare function bound(value: bigint, minimum: bigint, maximum: bigint): bigint;

package/dist/testing/handlers/handler.js

@@ -0,0 +1,31 @@
+export function handler(name, init) {
+    if (name.length === 0) {
+        throw new Error("Invariant campaign handler names must not be empty.");
+    }
+    return Object.freeze({
+        name,
+        cleanup: init.cleanup,
+        ...(init.assume === undefined ? {} : { assume: init.assume }),
+    });
+}
+export async function evaluateHandlerAssumptionAsync(value, context, input) {
+    if (value.assume === undefined || await value.assume(context, input)) {
+        return { kind: "eligible" };
+    }
+    return {
+        kind: "discarded",
+        reason: "handler assumption returned false",
+    };
+}
+export function bound(value, minimum, maximum) {
+    if (minimum > maximum) {
+        throw new Error("Invariant campaign bounds require minimum <= maximum.");
+    }
+    else if (value < minimum) {
+        return minimum;
+    }
+    else if (value > maximum) {
+        return maximum;
+    }
+    return value;
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,22 @@
+export { defineInvariantCampaign } from "./campaign/campaign-definition.js";
+export { CampaignReplayArtifact, createCampaignFingerprint, loadCampaignReplayArtifactAsync, selectCampaignCounterexampleTrace, serializeCampaignReplayArtifact, writeCampaignReplayArtifactAsync, } from "./campaign/campaign-artifact.js";
+export { applyAcceptedGhostTransition, CampaignModel, createCampaignModel, reconcileCampaignModel, } from "./campaign/campaign-model.js";
+export { CampaignInvariantFailure, CampaignExecutableAction, CampaignLifecyclePhase, CampaignLifecycleTrace, evaluateCampaignInvariantsAsync, runCampaignLifecycleCheckAsync, runInvariantCampaignCheckAsync, runCampaignCheckAsync, } from "./campaign/campaign-runner.js";
+export { CampaignMetricOutcome, CampaignMetrics, createCampaignMetrics, recordCampaignAction, } from "./campaign/campaign-metrics.js";
+export { CampaignSchedulingTarget, createCampaignScheduleArbitrary, createInvariantCampaignScheduleArbitrary, ScheduledCampaignSlot, scheduleCampaignSlots, } from "./campaign/campaign-scheduler.js";
+export { createDamlTestingCatalog, DamlTestingCatalog, DamlTestingChoice, DamlTestingTemplate, } from "./daml/daml-testing-catalog.js";
+export { createDamlValueArbitrary, DamlTestingValue, } from "./daml/daml-value-arbitrary.js";
+export { DamlNumeric } from "../core/types/daml-numeric.js";
+export { DamlParty } from "../core/types/daml-party.js";
+export { createDeclarativeActionArbitrary, DeclarativeAction, DeclarativeActionGenerationOptions, } from "./daml/daml-action-arbitrary.js";
+export { createDeclarativeCampaignArbitrary } from "./daml/declarative-campaign-arbitrary.js";
+export { createDeclarativeChoiceActionArbitrary, DeclarativeChoiceAction, } from "./daml/daml-choice-action-arbitrary.js";
+export { createDeclarativeCreateActionArbitrary, DeclarativeCreateAction, DeclarativeCreateActionGenerationOptions, } from "./daml/daml-create-action-arbitrary.js";
+export { bound, CampaignHandler, CampaignHandlerCleanup, evaluateHandlerAssumptionAsync, handler, } from "./handlers/handler.js";
+export { CantonCommandOutcome, CantonTestRoute, CantonTestRuntime, classifyCantonCommandOutcome, createCantonTestRuntime, pollUntilAsync, toCampaignMetricOutcome, } from "./runtime/canton-test-runtime.js";
+export { executeDeclarativeActionAsync } from "./runtime/declarative-action-executor.js";
+export { CampaignRunIsolation, runWithCampaignIsolationAsync, } from "./runtime/campaign-isolation.js";
+export { excludeChoice, ExcludedChoiceTarget, excludeTemplate, ExcludedTemplateTarget, targetCreate, targetChoice, targetTemplate, resolveDeclarativeTargets, ResolvedDeclarativeChoiceTarget, ResolvedDeclarativeCreateTarget, ResolvedDeclarativeTarget, TemplateCreateTarget, TemplateTarget, TemplateTargetBuilder, } from "./targets/target.js";
+export { CampaignInvariant, CampaignIsolation, CampaignRuntime, CampaignTarget, CantonTestActor, InvariantCampaign, InvariantCampaignConfig, invariant, ResolvedInvariantCampaignConfig, } from "./campaign/campaign-types.js";
+export { TestingConfigurationError } from "./errors/testing-configuration-error.js";
+export { InvariantCampaignFailure, InvariantCampaignFailureInit, } from "./errors/invariant-campaign-failure.js";

package/dist/testing/index.js

@@ -0,0 +1,22 @@
+export { defineInvariantCampaign } from "./campaign/campaign-definition.js";
+export { createCampaignFingerprint, loadCampaignReplayArtifactAsync, selectCampaignCounterexampleTrace, serializeCampaignReplayArtifact, writeCampaignReplayArtifactAsync, } from "./campaign/campaign-artifact.js";
+export { applyAcceptedGhostTransition, createCampaignModel, reconcileCampaignModel, } from "./campaign/campaign-model.js";
+export { evaluateCampaignInvariantsAsync, runCampaignLifecycleCheckAsync, runInvariantCampaignCheckAsync, runCampaignCheckAsync, } from "./campaign/campaign-runner.js";
+export { createCampaignMetrics, recordCampaignAction, } from "./campaign/campaign-metrics.js";
+export { createCampaignScheduleArbitrary, createInvariantCampaignScheduleArbitrary, scheduleCampaignSlots, } from "./campaign/campaign-scheduler.js";
+export { createDamlTestingCatalog, } from "./daml/daml-testing-catalog.js";
+export { createDamlValueArbitrary, } from "./daml/daml-value-arbitrary.js";
+export { DamlNumeric } from "../core/types/daml-numeric.js";
+export { DamlParty } from "../core/types/daml-party.js";
+export { createDeclarativeActionArbitrary, } from "./daml/daml-action-arbitrary.js";
+export { createDeclarativeCampaignArbitrary } from "./daml/declarative-campaign-arbitrary.js";
+export { createDeclarativeChoiceActionArbitrary, } from "./daml/daml-choice-action-arbitrary.js";
+export { createDeclarativeCreateActionArbitrary, } from "./daml/daml-create-action-arbitrary.js";
+export { bound, evaluateHandlerAssumptionAsync, handler, } from "./handlers/handler.js";
+export { classifyCantonCommandOutcome, createCantonTestRuntime, pollUntilAsync, toCampaignMetricOutcome, } from "./runtime/canton-test-runtime.js";
+export { executeDeclarativeActionAsync } from "./runtime/declarative-action-executor.js";
+export { runWithCampaignIsolationAsync, } from "./runtime/campaign-isolation.js";
+export { excludeChoice, excludeTemplate, targetCreate, targetChoice, targetTemplate, resolveDeclarativeTargets, } from "./targets/target.js";
+export { invariant, } from "./campaign/campaign-types.js";
+export { TestingConfigurationError } from "./errors/testing-configuration-error.js";
+export { InvariantCampaignFailure, } from "./errors/invariant-campaign-failure.js";

package/dist/testing/runtime/campaign-isolation.d.ts

@@ -0,0 +1,14 @@
+export type CampaignRunIsolation = {
+    readonly kind: "cleanup";
+} | {
+    readonly kind: "external";
+    readonly reset: (phase: "before-run" | "after-run") => Promise<void>;
+} | {
+    readonly create: () => Promise<string>;
+    readonly kind: "snapshot";
+    readonly restore: (snapshot: string) => Promise<void>;
+};
+export declare function runWithCampaignIsolationAsync(init: {
+    readonly isolation: CampaignRunIsolation;
+    readonly runAsync: () => Promise<void>;
+}): Promise<void>;

package/dist/testing/runtime/campaign-isolation.js

@@ -0,0 +1,23 @@
+export async function runWithCampaignIsolationAsync(init) {
+    if (init.isolation.kind === "external") {
+        await init.isolation.reset("before-run");
+        try {
+            await init.runAsync();
+        }
+        finally {
+            await init.isolation.reset("after-run");
+        }
+        return;
+    }
+    else if (init.isolation.kind === "snapshot") {
+        const snapshot = await init.isolation.create();
+        try {
+            await init.runAsync();
+        }
+        finally {
+            await init.isolation.restore(snapshot);
+        }
+        return;
+    }
+    await init.runAsync();
+}

package/dist/testing/runtime/canton-test-runtime.d.ts

@@ -0,0 +1,58 @@
+import { CampaignIsolation, CantonTestActor } from "../campaign/campaign-types.js";
+import { CampaignMetricOutcome } from "../campaign/campaign-metrics.js";
+export interface CantonTestRoute {
+    readonly actAs: readonly string[];
+    readonly actor: string;
+    readonly participant: string;
+    readonly party: string;
+    readonly readAs: readonly string[];
+}
+export type CantonCommandOutcome = {
+    readonly commandId?: string;
+    readonly kind: "accepted";
+    readonly transactionId?: string;
+} | {
+    readonly details: string;
+    readonly kind: "protocol-revert";
+    readonly statusCode: number;
+} | {
+    readonly details: string;
+    readonly kind: "transport-error";
+    readonly statusCode?: number;
+} | {
+    readonly details: string;
+    readonly kind: "timeout";
+    readonly statusCode?: number;
+} | {
+    readonly details: string;
+    readonly kind: "malformed-response";
+} | {
+    readonly details: string;
+    readonly kind: "unknown-commit-outcome";
+    readonly statusCode?: number;
+};
+export interface CantonTestRuntime<Participant = unknown> {
+    readonly actors: Readonly<Record<string, CantonTestActor>>;
+    readonly isolation: CampaignIsolation;
+    readonly participants: Readonly<Record<string, Participant>>;
+    readLedgerEndAsync(participant: string): Promise<string>;
+    resolveRoute(actor: string): CantonTestRoute;
+    submitAndWaitAsync(actor: string, request: unknown): Promise<CantonCommandOutcome>;
+}
+export declare function createCantonTestRuntime<Participant>(init: {
+    readonly actors: Readonly<Record<string, CantonTestActor>>;
+    readonly isolation: CampaignIsolation;
+    readonly participants: Readonly<Record<string, Participant>>;
+}): CantonTestRuntime<Participant>;
+export declare function classifyCantonCommandOutcome(input: {
+    readonly error?: unknown;
+    readonly response?: unknown;
+}): CantonCommandOutcome;
+/** Converts the runtime's transport-safe outcome into the campaign metric union. */
+export declare function toCampaignMetricOutcome(outcome: CantonCommandOutcome): CampaignMetricOutcome;
+export declare function pollUntilAsync<T>(init: {
+    readonly intervalMs: number;
+    readonly isReady: (value: T) => boolean;
+    readonly readAsync: () => Promise<T>;
+    readonly timeoutMs: number;
+}): Promise<T>;

package/dist/testing/runtime/canton-test-runtime.js

@@ -0,0 +1,138 @@
+import { TestingConfigurationError } from "../errors/testing-configuration-error.js";
+export function createCantonTestRuntime(init) {
+    for (const [name, actor] of Object.entries(init.actors)) {
+        if (init.participants[actor.participant] === undefined) {
+            throw new TestingConfigurationError(`Canton test actor '${name}' references unknown participant '${actor.participant}'.`);
+        }
+    }
+    const actors = Object.freeze({ ...init.actors });
+    const participants = Object.freeze({ ...init.participants });
+    const resolveRoute = (actorName) => {
+        const actor = actors[actorName];
+        if (actor === undefined) {
+            throw new TestingConfigurationError(`Canton test runtime has no actor '${actorName}'.`);
+        }
+        return Object.freeze({
+            actor: actorName,
+            participant: actor.participant,
+            party: actor.party,
+            actAs: Object.freeze([...(actor.actAs ?? [actor.party])]),
+            readAs: Object.freeze([...(actor.readAs ?? [])]),
+        });
+    };
+    return Object.freeze({
+        actors,
+        participants,
+        isolation: init.isolation,
+        async readLedgerEndAsync(participantName) {
+            const participant = participants[participantName];
+            const stateService = readObjectProperty(participant, "stateService");
+            const getLedgerEndAsync = readFunctionProperty(stateService, "getLedgerEndAsync");
+            if (getLedgerEndAsync === undefined) {
+                throw new TestingConfigurationError(`Canton test participant '${participantName}' has no stateService.getLedgerEndAsync method.`);
+            }
+            const response = await getLedgerEndAsync.call(stateService);
+            const offset = readStringProperty(response, "offset");
+            if (offset === undefined) {
+                throw new TestingConfigurationError(`Canton test participant '${participantName}' returned no ledger end offset.`);
+            }
+            return offset;
+        },
+        resolveRoute,
+        async submitAndWaitAsync(actorName, request) {
+            const route = resolveRoute(actorName);
+            const participant = participants[route.participant];
+            const commandService = readObjectProperty(participant, "commandService");
+            const submitAndWaitAsync = readFunctionProperty(commandService, "submitAndWaitAsync");
+            if (submitAndWaitAsync === undefined) {
+                throw new TestingConfigurationError(`Canton test participant '${route.participant}' has no commandService.submitAndWaitAsync method.`);
+            }
+            try {
+                return classifyCantonCommandOutcome({
+                    response: await submitAndWaitAsync.call(commandService, request),
+                });
+            }
+            catch (error) {
+                return classifyCantonCommandOutcome({ error });
+            }
+        },
+    });
+}
+export function classifyCantonCommandOutcome(input) {
+    if (input.error === undefined) {
+        const transactionId = readStringProperty(input.response, "transactionId");
+        const commandId = readStringProperty(input.response, "commandId");
+        return {
+            kind: "accepted",
+            ...(transactionId === undefined ? {} : { transactionId }),
+            ...(commandId === undefined ? {} : { commandId }),
+        };
+    }
+    const statusCode = readNumberProperty(input.error, "code");
+    const details = readStringProperty(input.error, "details") ?? "Unknown command failure.";
+    if ((statusCode === 9 && details.startsWith("DAML_INTERPRETATION_ERROR("))
+        || (statusCode === 3 && details.startsWith("DAML_AUTHORIZATION_ERROR("))) {
+        return { kind: "protocol-revert", statusCode, details };
+    }
+    else if (statusCode === 14 || statusCode === 13) {
+        return { kind: "transport-error", statusCode, details };
+    }
+    else if (statusCode === 4) {
+        return { kind: "timeout", statusCode, details };
+    }
+    return { kind: "unknown-commit-outcome", statusCode, details };
+}
+/** Converts the runtime's transport-safe outcome into the campaign metric union. */
+export function toCampaignMetricOutcome(outcome) {
+    if (outcome.kind !== "accepted") {
+        return {
+            kind: outcome.kind,
+            reason: outcome.details,
+        };
+    }
+    const updateId = outcome.transactionId ?? outcome.commandId;
+    return updateId === undefined
+        ? {
+            kind: "malformed-response",
+            reason: "Canton command response has no transaction or command ID.",
+        }
+        : { kind: "accepted", updateId };
+}
+export async function pollUntilAsync(init) {
+    const deadline = Date.now() + init.timeoutMs;
+    while (true) {
+        const value = await init.readAsync();
+        if (init.isReady(value)) {
+            return value;
+        }
+        else if (Date.now() >= deadline) {
+            throw new Error("Canton test runtime polling timed out.");
+        }
+        await new Promise((resolveDelay) => {
+            setTimeout(resolveDelay, init.intervalMs);
+        });
+    }
+}
+function readNumberProperty(value, key) {
+    const candidate = value;
+    const property = candidate?.[key];
+    return typeof property === "number" ? property : undefined;
+}
+function readObjectProperty(value, key) {
+    const candidate = value;
+    const property = candidate?.[key];
+    return property !== null && typeof property === "object"
+        ? property
+        : undefined;
+}
+function readFunctionProperty(value, key) {
+    const property = value?.[key];
+    return typeof property === "function"
+        ? property
+        : undefined;
+}
+function readStringProperty(value, key) {
+    const candidate = value;
+    const property = candidate?.[key];
+    return typeof property === "string" ? property : undefined;
+}

package/dist/testing/runtime/declarative-action-executor.d.ts

@@ -0,0 +1,16 @@
+import { DeclarativeAction } from "../daml/daml-action-arbitrary.js";
+import { DeclarativeChoiceAction } from "../daml/daml-choice-action-arbitrary.js";
+import { CantonTestRuntime } from "./canton-test-runtime.js";
+import { CampaignMetricOutcome } from "../campaign/campaign-metrics.js";
+/**
+ * Converts a generated declarative action into SDK command types and submits
+ * it over the actor's configured Canton route. Choice actions deliberately
+ * require an explicit contract resolver: the testing SDK never guesses an
+ * active contract ID from stale local state.
+ */
+export declare function executeDeclarativeActionAsync(init: {
+    readonly action: DeclarativeAction;
+    readonly applicationId: string;
+    readonly resolveContractIdAsync?: (action: DeclarativeChoiceAction) => Promise<string>;
+    readonly runtime: CantonTestRuntime;
+}): Promise<CampaignMetricOutcome>;