@distrohelena/canton-typescript-sdk 0.1.29 → 0.1.30

package/dist/daml-interface/emission/registry-emitter.d.ts

@@ -1,7 +1,8 @@
 import { GeneratedDamlInterfaceProject } from "../emission-model/generated-daml-interface-project.js";
 import { GeneratedRegistryFile } from "../emission-model/generated-registry-file.js";
+import { type DamlModuleImportStyle } from "./daml-module-import-style.js";
 export declare class RegistryEmitter {
     /** Emits a registry that dispatches created and exercised events by template id. */
-    emitRegistry(project: GeneratedDamlInterfaceProject): GeneratedRegistryFile;
+    emitRegistry(project: GeneratedDamlInterfaceProject, moduleImportStyle?: DamlModuleImportStyle): GeneratedRegistryFile;
     private emitCases;
 }

package/dist/daml-interface/emission/registry-emitter.js

@@ -1,11 +1,10 @@
 import { GeneratedRegistryFile } from "../emission-model/generated-registry-file.js";
+import { RelativeModuleSpecifier } from "./relative-module-specifier.js";
 export class RegistryEmitter {
     /** Emits a registry that dispatches created and exercised events by template id. */
-    emitRegistry(project) {
+    emitRegistry(project, moduleImportStyle) {
         const importLines = project.templateFiles.map((file) => {
-            const modulePath = file.path
-                .replace(/^generated\//, "./")
-                .replace(/\.ts$/, ".js");
+            const modulePath = RelativeModuleSpecifier.fromPaths("generated/registry.ts", file.path, moduleImportStyle);
             return `import { ${file.binding.className} } from "${modulePath}";`;
         });
         const createdCases = this.emitCases(project, "fromCreatedEvent");

package/dist/daml-interface/emission/relative-module-specifier.d.ts

@@ -0,0 +1,7 @@
+import { type DamlModuleImportStyle } from "./daml-module-import-style.js";
+/** Formats generated-project relative module specifiers for the selected execution mode. */
+export declare class RelativeModuleSpecifier {
+    private constructor();
+    /** Resolves a generated TypeScript target path relative to a generated source path. */
+    static fromPaths(fromPath: string, toPath: string, moduleImportStyle?: DamlModuleImportStyle): string;
+}

package/dist/daml-interface/emission/relative-module-specifier.js

@@ -0,0 +1,17 @@
+import { DamlModuleImportStyles, } from "./daml-module-import-style.js";
+/** Formats generated-project relative module specifiers for the selected execution mode. */
+export class RelativeModuleSpecifier {
+    constructor() { }
+    /** Resolves a generated TypeScript target path relative to a generated source path. */
+    static fromPaths(fromPath, toPath, moduleImportStyle = DamlModuleImportStyles.esm) {
+        const from = fromPath.split("/").slice(0, -1);
+        const to = toPath.replace(/\.ts$/, "").split("/");
+        while (from[0] === to[0] && from.length > 0) {
+            from.shift();
+            to.shift();
+        }
+        const relativePath = from.map(() => "..").concat(to).join("/") || ".";
+        const prefixedPath = relativePath.startsWith(".") ? relativePath : `./${relativePath}`;
+        return moduleImportStyle === DamlModuleImportStyles.esm ? `${prefixedPath}.js` : prefixedPath;
+    }
+}

package/dist/daml-interface/emission/support-file-emitter.d.ts

@@ -2,13 +2,14 @@ import { DamlInterfaceAnalysisResult } from "../analysis/daml-interface-analyzer
 import { GeneratedDamlInterfaceProject } from "../emission-model/generated-daml-interface-project.js";
 import { GeneratedNamedTypeFile } from "../emission-model/generated-named-type-file.js";
 import { GeneratedSupportFile } from "../emission-model/generated-support-file.js";
+import { type DamlModuleImportStyle } from "./daml-module-import-style.js";
 export declare class SupportFileEmitter {
     /** Emits shared support files for the generated DAML interface project. */
     emitSupportFiles(analysis: DamlInterfaceAnalysisResult, namedTypeFiles?: readonly GeneratedNamedTypeFile[]): readonly GeneratedSupportFile[];
     /** Emits one barrel module for each generated DAML package/module namespace. */
-    emitNamespaceFiles(project: GeneratedDamlInterfaceProject): readonly GeneratedSupportFile[];
+    emitNamespaceFiles(project: GeneratedDamlInterfaceProject, moduleImportStyle?: DamlModuleImportStyle): readonly GeneratedSupportFile[];
     /** Emits the generated project index file. */
-    emitIndexFile(project: GeneratedDamlInterfaceProject): GeneratedSupportFile;
+    emitIndexFile(project: GeneratedDamlInterfaceProject, moduleImportStyle?: DamlModuleImportStyle): GeneratedSupportFile;
     private getNamespaceGroups;
     private getFileNameWithoutExtension;
     private assertDistinctModuleExportedSymbols;

package/dist/daml-interface/emission/support-file-emitter.js

@@ -1,4 +1,5 @@
 import { GeneratedSupportFile } from "../emission-model/generated-support-file.js";
+import { RelativeModuleSpecifier } from "./relative-module-specifier.js";
 export class SupportFileEmitter {
     /** Emits shared support files for the generated DAML interface project. */
     emitSupportFiles(analysis, namedTypeFiles = []) {
@@ -18,25 +19,23 @@ export class SupportFileEmitter {
         ];
     }
     /** Emits one barrel module for each generated DAML package/module namespace. */
-    emitNamespaceFiles(project) {
+    emitNamespaceFiles(project, moduleImportStyle) {
         return this.getNamespaceGroups(project).map((group) => new GeneratedSupportFile({
             path: `${group.directoryPath}/index.ts`,
             contents: `${[
-                ...(group.namedTypeFile === undefined ? [] : ["export * from \"./types.js\";"]),
+                ...(group.namedTypeFile === undefined ? [] : [`export * from ${JSON.stringify(RelativeModuleSpecifier.fromPaths(`${group.directoryPath}/index.ts`, group.namedTypeFile.path, moduleImportStyle))};`]),
                 ...group.templateFiles
-                    .map((file) => this.getFileNameWithoutExtension(file.path))
-                    .map((fileName) => `export * from "./${fileName}.js";`),
+                    .map((file) => `export * from ${JSON.stringify(RelativeModuleSpecifier.fromPaths(`${group.directoryPath}/index.ts`, file.path, moduleImportStyle))};`),
             ].join("\n")}\n`,
         }));
     }
     /** Emits the generated project index file. */
-    emitIndexFile(project) {
+    emitIndexFile(project, moduleImportStyle) {
         const exportLines = this.getNamespaceGroups(project)
-            .map((group) => `export * as ${group.alias} from "${group.directoryPath
-            .replace(/^generated\//, "./")}/index.js";`);
+            .map((group) => `export * as ${group.alias} from ${JSON.stringify(RelativeModuleSpecifier.fromPaths("generated/index.ts", `${group.directoryPath}/index.ts`, moduleImportStyle))};`);
         const lines = [
             ...exportLines,
-            'export * from "./registry.js";',
+            `export * from ${JSON.stringify(RelativeModuleSpecifier.fromPaths("generated/index.ts", "generated/registry.ts", moduleImportStyle))};`,
         ];
         return new GeneratedSupportFile({
             path: "generated/index.ts",

package/dist/daml-interface/emission/template-binding-emitter.d.ts

@@ -2,6 +2,7 @@ import { AnalyzedTemplate } from "../analysis/analyzed-template.js";
 import { GeneratedNamedTypeFile } from "../emission-model/generated-named-type-file.js";
 import { GeneratedTemplateBindingFile } from "../emission-model/generated-template-binding-file.js";
 import { TypeScriptNameResolver } from "./type-script-name-resolver.js";
+import { type DamlModuleImportStyle } from "./daml-module-import-style.js";
 /** Emits typed contract and exercise-event bindings for analyzed DAML templates. */
 export declare class TemplateBindingEmitter {
     private readonly nameResolver;
@@ -9,7 +10,7 @@ export declare class TemplateBindingEmitter {
     /** Prepares stable collision-safe names before emitting a complete project. */
     prepareTemplatesOrThrow(templates: readonly AnalyzedTemplate[]): void;
     /** Emits a generated TypeScript file for one analyzed DAML template. */
-    emitTemplateFile(template: AnalyzedTemplate, namedTypeFiles?: readonly GeneratedNamedTypeFile[]): GeneratedTemplateBindingFile;
+    emitTemplateFile(template: AnalyzedTemplate, namedTypeFiles?: readonly GeneratedNamedTypeFile[], moduleImportStyle?: DamlModuleImportStyle): GeneratedTemplateBindingFile;
     /** Emits binding metadata without source, for resolving named declaration exports first. */
     emitTemplateBindingFile(template: AnalyzedTemplate): GeneratedTemplateBindingFile;
     private createBinding;
@@ -20,7 +21,11 @@ export declare class TemplateBindingEmitter {
     private emitTemplateDescriptor;
     private emitDescriptor;
     private getTypeName;
+    private getArrayElementTypeName;
     private getPrimitiveTypeName;
+    private resolveRuntimeWrapperTypeNames;
+    private getSdkName;
+    private emitImportedName;
     private normalizeType;
     private resolveNamedReferences;
     private walkNamedReferences;

package/dist/daml-interface/emission/template-binding-emitter.js

@@ -3,6 +3,7 @@ import { GeneratedChoiceBinding } from "../emission-model/generated-choice-bindi
 import { GeneratedTemplateBinding, GeneratedTemplateBindingField, } from "../emission-model/generated-template-binding.js";
 import { GeneratedTemplateBindingFile } from "../emission-model/generated-template-binding-file.js";
 import { TypeScriptNameResolver } from "./type-script-name-resolver.js";
+import { RelativeModuleSpecifier } from "./relative-module-specifier.js";
 /** Emits typed contract and exercise-event bindings for analyzed DAML templates. */
 export class TemplateBindingEmitter {
     nameResolver;
@@ -15,12 +16,12 @@ export class TemplateBindingEmitter {
         this.nameResolver.prepareTemplatesOrThrow(templates);
     }
     /** Emits a generated TypeScript file for one analyzed DAML template. */
-    emitTemplateFile(template, namedTypeFiles = []) {
-        const namedReferences = this.resolveNamedReferences(template, namedTypeFiles);
+    emitTemplateFile(template, namedTypeFiles = [], moduleImportStyle) {
+        const namedReferences = this.resolveNamedReferences(template, namedTypeFiles, moduleImportStyle);
         const binding = this.createBinding(template, namedReferences);
         return new GeneratedTemplateBindingFile({
             path: binding.path,
-            contents: this.emitContents(binding, namedReferences),
+            contents: this.emitContents(binding, namedReferences, moduleImportStyle),
             binding,
         });
     }
@@ -35,10 +36,16 @@ export class TemplateBindingEmitter {
         });
     }
     createBinding(template, namedReferences) {
+        const className = this.nameResolver.getTemplateClassName(template);
+        const choices = template.choices.map((choice) => ({
+            choice,
+            exercisedEventTypeName: this.nameResolver.getExercisedEventTypeName(template, choice),
+        }));
+        const runtimeWrapperTypeNames = this.resolveRuntimeWrapperTypeNames(className, choices.map((entry) => entry.exercisedEventTypeName));
         return new GeneratedTemplateBinding({
             templateIdentityKey: this.nameResolver.getTemplateIdentityKey(template),
             namespaceAlias: this.nameResolver.getNamespaceAlias(template),
-            className: this.nameResolver.getTemplateClassName(template),
+            className,
             templateIdLiteral: this.nameResolver.getTemplateIdLiteral(template),
             path: this.nameResolver.getTemplateFilePath(template),
             createFieldsTypeName: this.nameResolver.getCreateFieldsTypeName(template),
@@ -48,24 +55,25 @@ export class TemplateBindingEmitter {
                 propertyName: this.nameResolver.getFieldPropertyName(template, field),
                 constructorParameterName: this.nameResolver.getFieldConstructorParameterName(template, field),
                 type: this.normalizeType(field.type),
-                typeName: this.getTypeName(this.normalizeType(field.type), namedReferences),
+                typeName: this.getTypeName(this.normalizeType(field.type), namedReferences, runtimeWrapperTypeNames),
             })),
-            choices: template.choices.map((choice) => new GeneratedChoiceBinding({
+            choices: choices.map(({ choice, exercisedEventTypeName }) => new GeneratedChoiceBinding({
                 choiceIdentityKey: this.nameResolver.getChoiceIdentityKey(template, choice),
                 name: choice.name,
                 methodName: this.nameResolver.getChoiceMethodName(template, choice),
                 choiceTypeName: this.nameResolver.getChoiceTypeName(template, choice),
-                exercisedEventTypeName: this.nameResolver.getExercisedEventTypeName(template, choice),
+                exercisedEventTypeName,
                 parameterName: this.nameResolver.getChoiceParameterName(template, choice),
                 parameterType: this.normalizeType(choice.parameterType),
-                parameterTypeName: this.getTypeName(this.normalizeType(choice.parameterType), namedReferences),
+                parameterTypeName: this.getTypeName(this.normalizeType(choice.parameterType), namedReferences, runtimeWrapperTypeNames),
                 returnType: this.normalizeType(choice.returnType),
-                returnTypeName: this.getTypeName(this.normalizeType(choice.returnType), namedReferences),
+                returnTypeName: this.getTypeName(this.normalizeType(choice.returnType), namedReferences, runtimeWrapperTypeNames),
             })),
         });
     }
-    emitContents(binding, namedReferences) {
-        const imports = this.emitImports(binding, namedReferences);
+    emitContents(binding, namedReferences, moduleImportStyle) {
+        const runtimeWrapperTypeNames = this.resolveRuntimeWrapperTypeNames(binding.className, binding.choices.map((choice) => choice.exercisedEventTypeName));
+        const imports = this.emitImports(binding, namedReferences, runtimeWrapperTypeNames, moduleImportStyle);
         const fields = binding.createFields.map((field) => `    readonly ${field.propertyName}: ${field.typeName};`);
         const constructorParameters = binding.createFields.map((field) => `${field.constructorParameterName}: ${field.typeName}`);
         const constructorAssignments = binding.createFields.map((field) => `        this.${field.propertyName} = ${field.constructorParameterName};`);
@@ -80,14 +88,14 @@ export class TemplateBindingEmitter {
             ...fields,
             "}",
             "",
-            this.emitTemplateClass(binding, constructorParameters, constructorAssignments, orderedArguments, exercisedReturnType),
+            this.emitTemplateClass(binding, constructorParameters, constructorAssignments, orderedArguments, exercisedReturnType, runtimeWrapperTypeNames),
             ...(binding.choices.length === 0 ? [] : ["", ...binding.choices.flatMap((choice) => [
-                    this.emitChoiceEventClass(binding, choice),
+                    this.emitChoiceEventClass(binding, choice, runtimeWrapperTypeNames),
                     "",
                 ])]),
         ].join("\n");
     }
-    emitImports(binding, namedReferences) {
+    emitImports(binding, namedReferences, runtimeWrapperTypeNames, moduleImportStyle) {
         const namedImports = new Map();
         for (const reference of namedReferences.values()) {
             const imported = namedImports.get(reference.path) ?? new Map();
@@ -95,17 +103,34 @@ export class TemplateBindingEmitter {
             namedImports.set(reference.path, imported);
         }
         return [
-            'import { DamlEventSourceNormalizer, DamlMaterializationError, DamlTemplate, DamlValueConverter, DamlValueMaterializer } from "@distrohelena/canton-typescript-sdk/daml-interface";',
-            'import type { DamlCreatedEventSource, DamlDate, DamlExercisedEventMetadata, DamlExercisedEventSource, DamlNormalizedExercisedEvent, DamlNumeric, DamlParty, DamlTimestamp, DamlTypeDescriptor, DamlUnit } from "@distrohelena/canton-typescript-sdk/daml-interface";',
-            `import { GeneratedDamlTypeDescriptorRegistry } from ${JSON.stringify(this.relativeFilePath(binding.path, "generated/support/descriptors.ts"))};`,
+            `import { ${[
+                "DamlEventSourceNormalizer",
+                "DamlMaterializationError",
+                "DamlTemplate",
+                "DamlValueConverter",
+                "DamlValueMaterializer",
+            ].map((name) => this.emitImportedName(name, runtimeWrapperTypeNames)).join(", ")} } from "@distrohelena/canton-typescript-sdk/daml-interface";`,
+            `import type { ${[
+                "DamlCreatedEventSource",
+                "DamlDate",
+                "DamlExercisedEventMetadata",
+                "DamlExercisedEventSource",
+                "DamlNormalizedExercisedEvent",
+                "DamlNumeric",
+                "DamlParty",
+                "DamlTimestamp",
+                "DamlTypeDescriptor",
+                "DamlUnit",
+            ].map((name) => this.emitImportedName(name, runtimeWrapperTypeNames)).join(", ")} } from "@distrohelena/canton-typescript-sdk/daml-interface";`,
+            `import { GeneratedDamlTypeDescriptorRegistry } from ${JSON.stringify(this.relativeFilePath(binding.path, "generated/support/descriptors.ts", moduleImportStyle))};`,
             ...[...namedImports.entries()].sort(([left], [right]) => left.localeCompare(right)).map(([path, imported]) => `import type { ${[...imported.entries()].sort(([left], [right]) => left.localeCompare(right)).map(([name, alias]) => name === alias ? name : `${name} as ${alias}`).join(", ")} } from ${JSON.stringify(path)};`),
         ];
     }
-    emitTemplateClass(binding, constructorParameters, constructorAssignments, orderedArguments, exercisedReturnType) {
+    emitTemplateClass(binding, constructorParameters, constructorAssignments, orderedArguments, exercisedReturnType, runtimeWrapperTypeNames) {
         return [
-            `export class ${binding.className} extends DamlTemplate implements ${binding.createFieldsTypeName} {`,
+            `export class ${binding.className} extends ${this.getSdkName("DamlTemplate", runtimeWrapperTypeNames)} implements ${binding.createFieldsTypeName} {`,
             `    public static readonly templateId = ${JSON.stringify(binding.templateIdLiteral)};`,
-            `    private static readonly descriptor: DamlTypeDescriptor = ${this.emitTemplateDescriptor(binding)};`,
+            `    private static readonly descriptor: ${this.getSdkName("DamlTypeDescriptor", runtimeWrapperTypeNames)} = ${this.emitTemplateDescriptor(binding)};`,
             "",
             ...binding.createFields.map((field) => `    public readonly ${field.propertyName}: ${field.typeName};`),
             ...(binding.createFields.length === 0 ? [] : [""]),
@@ -114,48 +139,48 @@ export class TemplateBindingEmitter {
             ...constructorAssignments,
             "    }",
             "",
-            `    public static fromCreatedEvent(event: DamlCreatedEventSource): ${binding.className} {`,
-            "        const normalized = DamlEventSourceNormalizer.normalizeCreated(event);",
+            `    public static fromCreatedEvent(event: ${this.getSdkName("DamlCreatedEventSource", runtimeWrapperTypeNames)}): ${binding.className} {`,
+            `        const normalized = ${this.getSdkName("DamlEventSourceNormalizer", runtimeWrapperTypeNames)}.normalizeCreated(event);`,
             `        ${binding.className}.assertTemplateIdentity(normalized.metadata.templateId);`,
-            `        const fields = DamlValueMaterializer.materialize<${binding.createFieldsTypeName}>(DamlValueConverter.decode(normalized.payload, ${binding.className}.descriptor, GeneratedDamlTypeDescriptorRegistry, "create arguments"));`,
+            `        const fields = ${this.getSdkName("DamlValueMaterializer", runtimeWrapperTypeNames)}.materialize<${binding.createFieldsTypeName}>(${this.getSdkName("DamlValueConverter", runtimeWrapperTypeNames)}.decode(normalized.payload, ${binding.className}.descriptor, GeneratedDamlTypeDescriptorRegistry, "create arguments"));`,
             `        return new ${binding.className}(`,
             "            normalized.contractId,",
             ...orderedArguments,
             "        );",
             "    }",
             "",
-            `    public static fromExercisedEvent(event: DamlExercisedEventSource): ${exercisedReturnType} {`,
-            "        const normalized = DamlEventSourceNormalizer.normalizeExercised(event);",
+            `    public static fromExercisedEvent(event: ${this.getSdkName("DamlExercisedEventSource", runtimeWrapperTypeNames)}): ${exercisedReturnType} {`,
+            `        const normalized = ${this.getSdkName("DamlEventSourceNormalizer", runtimeWrapperTypeNames)}.normalizeExercised(event);`,
             `        ${binding.className}.assertTemplateIdentity(normalized.metadata.templateId);`,
             "        switch (normalized.choice) {",
             ...binding.choices.map((choice) => `            case ${JSON.stringify(choice.name)}:\n                return ${choice.exercisedEventTypeName}.fromNormalizedEvent(normalized);`),
             "            default:",
-            `                throw new DamlMaterializationError("choice", \`Unexpected choice '\${normalized.choice}' for template '${binding.templateIdLiteral}'\`);`,
+            `                throw new ${this.getSdkName("DamlMaterializationError", runtimeWrapperTypeNames)}("choice", \`Unexpected choice '\${normalized.choice}' for template '${binding.templateIdLiteral}'\`);`,
             "        }",
             "    }",
             "",
             "    private static assertTemplateIdentity(identity: { readonly packageId: string; readonly moduleName: string; readonly entityName: string }): void {",
             `        if (identity.packageId !== ${JSON.stringify(this.packageId(binding))} || identity.moduleName !== ${JSON.stringify(this.moduleName(binding))} || identity.entityName !== ${JSON.stringify(this.entityName(binding))}) {`,
-            `            throw new DamlMaterializationError("template ID", \`Expected template '${binding.templateIdLiteral}' but received '\${identity.packageId}:\${identity.moduleName}:\${identity.entityName}'\`);`,
+            `            throw new ${this.getSdkName("DamlMaterializationError", runtimeWrapperTypeNames)}("template ID", \`Expected template '${binding.templateIdLiteral}' but received '\${identity.packageId}:\${identity.moduleName}:\${identity.entityName}'\`);`,
             "        }",
             "    }",
             "}",
         ].join("\n");
     }
-    emitChoiceEventClass(binding, choice) {
+    emitChoiceEventClass(binding, choice, runtimeWrapperTypeNames) {
         return [
             `export class ${choice.exercisedEventTypeName} {`,
-            `    private static readonly argumentDescriptor: DamlTypeDescriptor = ${this.emitDescriptor(choice.parameterType)};`,
-            `    private static readonly resultDescriptor: DamlTypeDescriptor = ${this.emitDescriptor(choice.returnType)};`,
+            `    private static readonly argumentDescriptor: ${this.getSdkName("DamlTypeDescriptor", runtimeWrapperTypeNames)} = ${this.emitDescriptor(choice.parameterType)};`,
+            `    private static readonly resultDescriptor: ${this.getSdkName("DamlTypeDescriptor", runtimeWrapperTypeNames)} = ${this.emitDescriptor(choice.returnType)};`,
             "",
             `    public readonly choiceName = ${JSON.stringify(choice.name)} as const;`,
             "    public readonly contractId: string;",
             `    public readonly argument: ${choice.parameterTypeName};`,
             `    public readonly result: ${choice.returnTypeName};`,
             "    public readonly consuming: boolean;",
-            "    public readonly metadata: DamlExercisedEventMetadata;",
+            `    public readonly metadata: ${this.getSdkName("DamlExercisedEventMetadata", runtimeWrapperTypeNames)};`,
             "",
-            "    public constructor(contractId: string, argument: " + choice.parameterTypeName + ", result: " + choice.returnTypeName + ", consuming: boolean, metadata: DamlExercisedEventMetadata) {",
+            "    public constructor(contractId: string, argument: " + choice.parameterTypeName + ", result: " + choice.returnTypeName + ", consuming: boolean, metadata: " + this.getSdkName("DamlExercisedEventMetadata", runtimeWrapperTypeNames) + ") {",
             "        this.contractId = contractId;",
             "        this.argument = argument;",
             "        this.result = result;",
@@ -163,25 +188,25 @@ export class TemplateBindingEmitter {
             "        this.metadata = metadata;",
             "    }",
             "",
-            `    public static fromExercisedEvent(event: DamlExercisedEventSource): ${choice.exercisedEventTypeName} {`,
-            "        const normalized = DamlEventSourceNormalizer.normalizeExercised(event);",
+            `    public static fromExercisedEvent(event: ${this.getSdkName("DamlExercisedEventSource", runtimeWrapperTypeNames)}): ${choice.exercisedEventTypeName} {`,
+            `        const normalized = ${this.getSdkName("DamlEventSourceNormalizer", runtimeWrapperTypeNames)}.normalizeExercised(event);`,
             `        ${choice.exercisedEventTypeName}.assertTemplateIdentity(normalized.metadata.templateId);`,
             `        return ${choice.exercisedEventTypeName}.fromNormalizedEvent(normalized);`,
             "    }",
             "",
-            `    public static fromNormalizedEvent(event: DamlNormalizedExercisedEvent): ${choice.exercisedEventTypeName} {`,
+            `    public static fromNormalizedEvent(event: ${this.getSdkName("DamlNormalizedExercisedEvent", runtimeWrapperTypeNames)}): ${choice.exercisedEventTypeName} {`,
             `        ${choice.exercisedEventTypeName}.assertTemplateIdentity(event.metadata.templateId);`,
             `        if (event.choice !== ${JSON.stringify(choice.name)}) {`,
-            `            throw new DamlMaterializationError("choice", \`Expected choice '${choice.name}' but received '\${event.choice}'\`);`,
+            `            throw new ${this.getSdkName("DamlMaterializationError", runtimeWrapperTypeNames)}("choice", \`Expected choice '${choice.name}' but received '\${event.choice}'\`);`,
             "        }",
-            `        const argument = DamlValueMaterializer.materialize<${choice.parameterTypeName}>(DamlValueConverter.decode(event.argument, ${choice.exercisedEventTypeName}.argumentDescriptor, GeneratedDamlTypeDescriptorRegistry, "choice argument"));`,
-            `        const result = DamlValueMaterializer.materialize<${choice.returnTypeName}>(DamlValueConverter.decode(event.result, ${choice.exercisedEventTypeName}.resultDescriptor, GeneratedDamlTypeDescriptorRegistry, "exercise result"));`,
+            `        const argument = ${this.getSdkName("DamlValueMaterializer", runtimeWrapperTypeNames)}.materialize<${choice.parameterTypeName}>(${this.getSdkName("DamlValueConverter", runtimeWrapperTypeNames)}.decode(event.argument, ${choice.exercisedEventTypeName}.argumentDescriptor, GeneratedDamlTypeDescriptorRegistry, "choice argument"));`,
+            `        const result = ${this.getSdkName("DamlValueMaterializer", runtimeWrapperTypeNames)}.materialize<${choice.returnTypeName}>(${this.getSdkName("DamlValueConverter", runtimeWrapperTypeNames)}.decode(event.result, ${choice.exercisedEventTypeName}.resultDescriptor, GeneratedDamlTypeDescriptorRegistry, "exercise result"));`,
             `        return new ${choice.exercisedEventTypeName}(event.contractId, argument, result, event.consuming, event.metadata);`,
             "    }",
             "",
             "    private static assertTemplateIdentity(identity: { readonly packageId: string; readonly moduleName: string; readonly entityName: string }): void {",
             `        if (identity.packageId !== ${JSON.stringify(this.packageId(binding))} || identity.moduleName !== ${JSON.stringify(this.moduleName(binding))} || identity.entityName !== ${JSON.stringify(this.entityName(binding))}) {`,
-            `            throw new DamlMaterializationError("template ID", \`Expected template '${binding.templateIdLiteral}' but received '\${identity.packageId}:\${identity.moduleName}:\${identity.entityName}'\`);`,
+            `            throw new ${this.getSdkName("DamlMaterializationError", runtimeWrapperTypeNames)}("template ID", \`Expected template '${binding.templateIdLiteral}' but received '\${identity.packageId}:\${identity.moduleName}:\${identity.entityName}'\`);`,
             "        }",
             "    }",
             "}",
@@ -216,24 +241,24 @@ export class TemplateBindingEmitter {
                 return `{ kind: "namedReference", identity: { packageId: ${JSON.stringify(type.identity.packageId)}, moduleName: ${JSON.stringify(type.identity.moduleName)}, entityName: ${JSON.stringify(type.identity.name)} }, typeArguments: [${(type.typeArguments ?? []).map((argument) => this.emitDescriptor(argument)).join(", ")}] }`;
         }
     }
-    getTypeName(type, namedReferences) {
+    getTypeName(type, namedReferences, runtimeWrapperTypeNames = new Map()) {
         switch (type.kind) {
             case "primitive":
-                return this.getPrimitiveTypeName(type.builtinType);
+                return this.getPrimitiveTypeName(type.builtinType, runtimeWrapperTypeNames);
             case "contractId":
                 return "string";
             case "optional":
-                return `${this.getTypeName(type.element, namedReferences)} | undefined`;
+                return `${this.getTypeName(type.element, namedReferences, runtimeWrapperTypeNames)} | undefined`;
             case "list":
-                return `readonly ${this.getTypeName(type.element, namedReferences)}[]`;
+                return `readonly ${this.getArrayElementTypeName(type.element, namedReferences, runtimeWrapperTypeNames)}[]`;
             case "textMap":
-                return `ReadonlyMap<string, ${this.getTypeName(type.value, namedReferences)}>`;
+                return `ReadonlyMap<string, ${this.getTypeName(type.value, namedReferences, runtimeWrapperTypeNames)}>`;
             case "genMap":
-                return `ReadonlyMap<${this.getTypeName(type.key, namedReferences)}, ${this.getTypeName(type.value, namedReferences)}>`;
+                return `ReadonlyMap<${this.getTypeName(type.key, namedReferences, runtimeWrapperTypeNames)}, ${this.getTypeName(type.value, namedReferences, runtimeWrapperTypeNames)}>`;
             case "record":
-                return `{ ${type.fields.map((field) => `readonly ${field.propertyName}: ${this.getTypeName(field.type, namedReferences)};`).join(" ")} }`;
+                return `{ ${type.fields.map((field) => `readonly ${field.propertyName}: ${this.getTypeName(field.type, namedReferences, runtimeWrapperTypeNames)};`).join(" ")} }`;
             case "variant":
-                return type.constructors.map((constructor) => `{ readonly tag: ${JSON.stringify(constructor.constructor)}; readonly value: ${this.getTypeName(constructor.payload, namedReferences)}; }`).join(" | ");
+                return type.constructors.map((constructor) => `{ readonly tag: ${JSON.stringify(constructor.constructor)}; readonly value: ${this.getTypeName(constructor.payload, namedReferences, runtimeWrapperTypeNames)}; }`).join(" | ");
             case "enum":
                 return type.constructors.map((constructor) => JSON.stringify(constructor)).join(" | ");
             case "typeVariable":
@@ -242,23 +267,70 @@ export class TemplateBindingEmitter {
                 const name = this.getNamedReference(type.identity, namedReferences).alias;
                 return (type.typeArguments?.length ?? 0) === 0
                     ? name
-                    : `${name}<${(type.typeArguments ?? []).map((argument) => this.getTypeName(argument, namedReferences)).join(", ")}>`;
+                    : `${name}<${(type.typeArguments ?? []).map((argument) => this.getTypeName(argument, namedReferences, runtimeWrapperTypeNames)).join(", ")}>`;
             }
         }
     }
-    getPrimitiveTypeName(type) {
+    getArrayElementTypeName(type, namedReferences, runtimeWrapperTypeNames) {
+        const name = this.getTypeName(type, namedReferences, runtimeWrapperTypeNames);
+        return type.kind === "optional" || type.kind === "variant" || type.kind === "enum"
+            ? `(${name})`
+            : name;
+    }
+    getPrimitiveTypeName(type, runtimeWrapperTypeNames) {
         switch (type) {
-            case DamlLfBuiltinType.unit: return "DamlUnit";
+            case DamlLfBuiltinType.unit: return runtimeWrapperTypeNames.get("DamlUnit") ?? "DamlUnit";
             case DamlLfBuiltinType.bool: return "boolean";
             case DamlLfBuiltinType.int64: return "bigint";
-            case DamlLfBuiltinType.date: return "DamlDate";
-            case DamlLfBuiltinType.timestamp: return "DamlTimestamp";
-            case DamlLfBuiltinType.numeric: return "DamlNumeric";
-            case DamlLfBuiltinType.party: return "DamlParty";
+            case DamlLfBuiltinType.date: return runtimeWrapperTypeNames.get("DamlDate") ?? "DamlDate";
+            case DamlLfBuiltinType.timestamp: return runtimeWrapperTypeNames.get("DamlTimestamp") ?? "DamlTimestamp";
+            case DamlLfBuiltinType.numeric: return runtimeWrapperTypeNames.get("DamlNumeric") ?? "DamlNumeric";
+            case DamlLfBuiltinType.party: return runtimeWrapperTypeNames.get("DamlParty") ?? "DamlParty";
             case DamlLfBuiltinType.text: return "string";
             default: throw new Error(`Cannot emit unsupported primitive DAML type '${type}'`);
         }
     }
+    resolveRuntimeWrapperTypeNames(className, exercisedEventTypeNames) {
+        const usedNames = new Set([className, ...exercisedEventTypeNames]);
+        const names = new Map();
+        for (const name of [
+            "DamlCreatedEventSource",
+            "DamlDate",
+            "DamlEventSourceNormalizer",
+            "DamlExercisedEventMetadata",
+            "DamlExercisedEventSource",
+            "DamlMaterializationError",
+            "DamlNormalizedExercisedEvent",
+            "DamlNumeric",
+            "DamlParty",
+            "DamlTemplate",
+            "DamlTimestamp",
+            "DamlTypeDescriptor",
+            "DamlUnit",
+            "DamlValueConverter",
+            "DamlValueMaterializer",
+        ]) {
+            let localName = name;
+            let suffix = 2;
+            if (usedNames.has(localName)) {
+                localName = `GeneratedRuntime${name}`;
+            }
+            while (usedNames.has(localName)) {
+                localName = `GeneratedRuntime${name}_${suffix}`;
+                suffix += 1;
+            }
+            usedNames.add(localName);
+            names.set(name, localName);
+        }
+        return names;
+    }
+    getSdkName(name, runtimeWrapperTypeNames) {
+        return runtimeWrapperTypeNames.get(name) ?? name;
+    }
+    emitImportedName(name, runtimeWrapperTypeNames) {
+        const localName = this.getSdkName(name, runtimeWrapperTypeNames);
+        return localName === name ? name : `${name} as ${localName}`;
+    }
     normalizeType(type) {
         if ("kind" in type) {
             return type;
@@ -304,7 +376,7 @@ export class TemplateBindingEmitter {
                 throw new Error("Cannot emit unsupported DAML type");
         }
     }
-    resolveNamedReferences(template, namedTypeFiles) {
+    resolveNamedReferences(template, namedTypeFiles, moduleImportStyle) {
         const identities = new Map();
         for (const type of [
             ...template.createFields.map((field) => this.normalizeType(field.type)),
@@ -376,7 +448,7 @@ export class TemplateBindingEmitter {
                     }];
             }
             return [key, {
-                    path: this.relativeFilePath(this.nameResolver.getTemplateFilePath(template), file.path),
+                    path: this.relativeFilePath(this.nameResolver.getTemplateFilePath(template), file.path, moduleImportStyle),
                     exportedName,
                     alias: alias,
                 }];
@@ -449,14 +521,7 @@ export class TemplateBindingEmitter {
     entityName(binding) {
         return binding.templateIdLiteral.split(":")[2];
     }
-    relativeFilePath(fromPath, toPath) {
-        const from = fromPath.split("/").slice(0, -1);
-        const to = toPath.split("/");
-        while (from[0] === to[0] && from.length > 0) {
-            from.shift();
-            to.shift();
-        }
-        const relative = from.map(() => "..").concat(to).join("/") || ".";
-        return `${relative.startsWith(".") ? relative : `./${relative}`}`.replace(/\.ts$/, ".js");
+    relativeFilePath(fromPath, toPath, moduleImportStyle) {
+        return RelativeModuleSpecifier.fromPaths(fromPath, toPath, moduleImportStyle);
     }
 }

package/dist/daml-interface/emission-model/generated-daml-interface-project.d.ts

@@ -1,18 +1,27 @@
 import { GeneratedNamedTypeFile } from "./generated-named-type-file.js";
 import { GeneratedRegistryFile } from "./generated-registry-file.js";
+import { GeneratedSpecFile } from "./generated-spec-file.js";
 import { GeneratedSupportFile } from "./generated-support-file.js";
 import { GeneratedTemplateBindingFile } from "./generated-template-binding-file.js";
+type GeneratedProductionFile = GeneratedTemplateBindingFile | GeneratedNamedTypeFile | GeneratedRegistryFile | GeneratedSupportFile;
 export declare class GeneratedDamlInterfaceProject {
     readonly templateFiles: readonly GeneratedTemplateBindingFile[];
     readonly namedTypeFiles: readonly GeneratedNamedTypeFile[];
     readonly supportFiles: readonly GeneratedSupportFile[];
     readonly registryFile?: GeneratedRegistryFile;
     readonly indexFile?: GeneratedSupportFile;
+    /** Every non-spec module emitted by this project. */
+    readonly productionFiles: readonly GeneratedProductionFile[];
+    /** Runnable specs, each colocated with exactly one production module. */
+    readonly specFiles: readonly GeneratedSpecFile[];
     constructor(init: {
         templateFiles: readonly GeneratedTemplateBindingFile[];
         namedTypeFiles?: readonly GeneratedNamedTypeFile[];
         supportFiles?: readonly GeneratedSupportFile[];
         registryFile?: GeneratedRegistryFile;
         indexFile?: GeneratedSupportFile;
+        specFiles?: readonly GeneratedSpecFile[];
     });
+    private validateFilesOrThrow;
 }
+export {};

package/dist/daml-interface/emission-model/generated-daml-interface-project.js

@@ -4,11 +4,60 @@ export class GeneratedDamlInterfaceProject {
     supportFiles;
     registryFile;
     indexFile;
+    /** Every non-spec module emitted by this project. */
+    productionFiles;
+    /** Runnable specs, each colocated with exactly one production module. */
+    specFiles;
     constructor(init) {
-        this.templateFiles = init.templateFiles;
-        this.namedTypeFiles = init.namedTypeFiles ?? [];
-        this.supportFiles = init.supportFiles ?? [];
-        this.registryFile = init.registryFile;
-        this.indexFile = init.indexFile;
+        const templateFiles = [...init.templateFiles];
+        const namedTypeFiles = [...(init.namedTypeFiles ?? [])];
+        const supportFiles = [...(init.supportFiles ?? [])];
+        const registryFile = init.registryFile;
+        const indexFile = init.indexFile;
+        const productionFiles = [
+            ...templateFiles,
+            ...namedTypeFiles,
+            ...supportFiles,
+            ...(registryFile === undefined ? [] : [registryFile]),
+            ...(indexFile === undefined ? [] : [indexFile]),
+        ];
+        const specFiles = [...(init.specFiles ?? [])];
+        this.validateFilesOrThrow(productionFiles, specFiles);
+        this.templateFiles = Object.freeze(templateFiles);
+        this.namedTypeFiles = Object.freeze(namedTypeFiles);
+        this.supportFiles = Object.freeze(supportFiles);
+        this.registryFile = registryFile;
+        this.indexFile = indexFile;
+        this.productionFiles = Object.freeze(productionFiles);
+        this.specFiles = Object.freeze(specFiles);
+    }
+    validateFilesOrThrow(productionFiles, specFiles) {
+        const productionPaths = new Set();
+        for (const file of productionFiles) {
+            if (file.path.endsWith(".spec.ts")) {
+                throw new Error(`Generated production file path must not end in .spec.ts: ${file.path}`);
+            }
+            else if (!file.path.endsWith(".ts")) {
+                throw new Error(`Generated production file path must end in .ts: ${file.path}`);
+            }
+            else if (productionPaths.has(file.path)) {
+                throw new Error(`Duplicate production file path: ${file.path}`);
+            }
+            productionPaths.add(file.path);
+        }
+        const specPaths = new Set();
+        for (const specFile of specFiles) {
+            if (!productionPaths.has(specFile.productionPath)) {
+                throw new Error(`Generated spec references a production path that does not exist: ${specFile.productionPath}`);
+            }
+            const expectedPath = specFile.productionPath.replace(/\.ts$/, ".spec.ts");
+            if (specFile.path !== expectedPath) {
+                throw new Error(`Generated spec path must be the sibling .spec.ts file for ${specFile.productionPath}: ${specFile.path}`);
+            }
+            else if (specPaths.has(specFile.path)) {
+                throw new Error(`Duplicate generated spec file path: ${specFile.path}`);
+            }
+            specPaths.add(specFile.path);
+        }
     }
 }

package/dist/daml-interface/emission-model/generated-spec-file.d.ts

@@ -0,0 +1,7 @@
+/** A runnable Node test generated beside one production DAML module. */
+export declare class GeneratedSpecFile {
+    readonly path: string;
+    readonly contents: string;
+    readonly productionPath: string;
+    constructor(path: string, contents: string, productionPath: string);
+}