@distrohelena/canton-typescript-sdk 0.1.50 → 0.1.52

package/dist/cjs/daml-interface/emission/project-emitter.js

@@ -30,6 +30,7 @@ class ProjectEmitter {
     /** Emits the complete in-memory DAML interface project from analyzed templates. */
     emitProject(analysis, moduleImportStyle = daml_module_import_style_js_1.DamlModuleImportStyles.esm) {
         this.namedTypeEmitter.prepareProjectOrThrow(analysis.templates, analysis.typeDefinitions, analysis.packageMetadata);
+        this.templateBindingEmitter.providePackageMetadata(analysis.packageMetadata);
         const templateBindingFiles = analysis.templates.map((template) => this.templateBindingEmitter.emitTemplateBindingFile(template));
         const namedTypeFiles = this.namedTypeEmitter.emitPreparedNamedTypeFiles(analysis.typeDefinitions, templateBindingFiles, moduleImportStyle);
         const templateFiles = analysis.templates.map((template) => this.templateBindingEmitter.emitTemplateFile(template, namedTypeFiles, moduleImportStyle));

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

@@ -22,7 +22,7 @@ class RegistryEmitter {
                 "export class GeneratedRegistry {",
                 "    public static fromCreatedEvent(event: DamlCreatedEventSource): unknown {",
                 "        const normalized = DamlEventSourceNormalizer.normalizeCreated(event);",
-                "        switch (`${normalized.metadata.templateId.packageId}:${normalized.metadata.templateId.moduleName}:${normalized.metadata.templateId.entityName}`) {",
+                "        switch (`${normalized.metadata.templateId.moduleName}:${normalized.metadata.templateId.entityName}`) {",
                 ...createdCases,
                 "            default:",
                 "                throw new DamlMaterializationError(\"template ID\", \"no generated template binding matches the created event\");",
@@ -31,7 +31,7 @@ class RegistryEmitter {
                 "",
                 "    public static fromExercisedEvent(event: DamlExercisedEventSource): unknown {",
                 "        const normalized = DamlEventSourceNormalizer.normalizeExercised(event);",
-                "        switch (`${normalized.metadata.templateId.packageId}:${normalized.metadata.templateId.moduleName}:${normalized.metadata.templateId.entityName}`) {",
+                "        switch (`${normalized.metadata.templateId.moduleName}:${normalized.metadata.templateId.entityName}`) {",
                 ...exercisedCases,
                 "            default:",
                 "                throw new DamlMaterializationError(\"template ID\", \"no generated template binding matches the exercised event\");",
@@ -43,7 +43,21 @@ class RegistryEmitter {
         });
     }
     emitCases(project, methodName) {
-        return project.templateFiles.map((file) => `            case "${file.binding.templateIdLiteral}":\n                return ${file.binding.className}.${methodName}(event);`);
+        // Dispatch is by module:entity — package ids are version-specific under smart contract upgrades,
+        // so any version of a template routes to its binding; the binding's own identity guard then
+        // verifies the package name when the event carries one.
+        const seen = new Map();
+        return project.templateFiles.map((file) => {
+            const parts = file.binding.templateIdLiteral.split(":");
+            const dispatchKey = `${parts[1]}:${parts[2]}`;
+            const existing = seen.get(dispatchKey);
+            if (existing !== undefined && existing !== file.binding.templateIdLiteral) {
+                throw new Error(`Generated registry cannot dispatch '${dispatchKey}': templates '${existing}' and `
+                    + `'${file.binding.templateIdLiteral}' collide on module:entity across packages.`);
+            }
+            seen.set(dispatchKey, file.binding.templateIdLiteral);
+            return `            case "${dispatchKey}":\n                return ${file.binding.className}.${methodName}(event);`;
+        });
     }
 }
 exports.RegistryEmitter = RegistryEmitter;

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

@@ -10,10 +10,15 @@ const relative_module_specifier_js_1 = require("./relative-module-specifier.js")
 /** Emits typed contract and exercise-event bindings for analyzed DAML templates. */
 class TemplateBindingEmitter {
     nameResolver;
+    packageMetadata;
     constructor(nameResolver = new type_script_name_resolver_js_1.TypeScriptNameResolver()) {
         this.nameResolver = nameResolver;
         void this.nameResolver;
     }
+    /** Supplies per-package metadata so emitted identity checks can match by package NAME across upgrades. */
+    providePackageMetadata(metadata) {
+        this.packageMetadata = metadata;
+    }
     /** Prepares stable collision-safe names before emitting a complete project. */
     prepareTemplatesOrThrow(templates) {
         this.nameResolver.prepareTemplatesOrThrow(templates);
@@ -49,7 +54,8 @@ class TemplateBindingEmitter {
             templateIdentityKey: this.nameResolver.getTemplateIdentityKey(template),
             namespaceAlias: this.nameResolver.getNamespaceAlias(template),
             className,
-            templateIdLiteral: this.nameResolver.getTemplateIdLiteral(template),
+            templateIdLiteral: this.templateIdLiteral(template),
+            packageName: this.packageMetadata?.get(template.templateId.packageId)?.packageName,
             path: this.nameResolver.getTemplateFilePath(template),
             createFieldsTypeName: this.nameResolver.getCreateFieldsTypeName(template),
             createdEventTypeName: this.nameResolver.getCreatedEventTypeName(template),
@@ -133,6 +139,7 @@ class TemplateBindingEmitter {
         return [
             `export class ${binding.className} extends ${this.getSdkName("DamlTemplate", runtimeWrapperTypeNames)} implements ${binding.createFieldsTypeName} {`,
             `    public static readonly templateId = ${JSON.stringify(binding.templateIdLiteral)};`,
+            ...(binding.packageName === undefined ? [] : [`    public static readonly packageName = ${JSON.stringify(binding.packageName)};`]),
             `    private static readonly descriptor: ${this.getSdkName("DamlTypeDescriptor", runtimeWrapperTypeNames)} = ${this.emitTemplateDescriptor(binding)};`,
             "",
             ...binding.createFields.map((field) => `    public readonly ${field.propertyName}: ${field.typeName};`),
@@ -144,7 +151,7 @@ class TemplateBindingEmitter {
             "",
             `    public static fromCreatedEvent(event: ${this.getSdkName("DamlCreatedEventSource", runtimeWrapperTypeNames)}): ${binding.className} {`,
             `        const normalized = ${this.getSdkName("DamlEventSourceNormalizer", runtimeWrapperTypeNames)}.normalizeCreated(event);`,
-            `        ${binding.className}.assertTemplateIdentity(normalized.metadata.templateId);`,
+            `        ${binding.className}.assertTemplateIdentity(normalized.metadata.templateId, normalized.metadata.packageName);`,
             `        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,",
@@ -154,7 +161,7 @@ class TemplateBindingEmitter {
             "",
             `    public static fromExercisedEvent(event: ${this.getSdkName("DamlExercisedEventSource", runtimeWrapperTypeNames)}): ${exercisedReturnType} {`,
             `        const normalized = ${this.getSdkName("DamlEventSourceNormalizer", runtimeWrapperTypeNames)}.normalizeExercised(event);`,
-            `        ${binding.className}.assertTemplateIdentity(normalized.metadata.templateId);`,
+            `        ${binding.className}.assertTemplateIdentity(normalized.metadata.templateId, normalized.metadata.packageName);`,
             "        switch (normalized.choice) {",
             ...binding.choices.map((choice) => `            case ${JSON.stringify(choice.name)}:\n                return ${choice.exercisedEventTypeName}.fromNormalizedEvent(normalized);`),
             "            default:",
@@ -162,11 +169,7 @@ class TemplateBindingEmitter {
             "        }",
             "    }",
             "",
-            "    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 ${this.getSdkName("DamlMaterializationError", runtimeWrapperTypeNames)}("template ID", \`Expected template '${binding.templateIdLiteral}' but received '\${identity.packageId}:\${identity.moduleName}:\${identity.entityName}'\`);`,
-            "        }",
-            "    }",
+            ...this.emitAssertTemplateIdentity(binding, runtimeWrapperTypeNames),
             "}",
         ].join("\n");
     }
@@ -193,12 +196,12 @@ class TemplateBindingEmitter {
             "",
             `    public static fromExercisedEvent(event: ${this.getSdkName("DamlExercisedEventSource", runtimeWrapperTypeNames)}): ${choice.exercisedEventTypeName} {`,
             `        const normalized = ${this.getSdkName("DamlEventSourceNormalizer", runtimeWrapperTypeNames)}.normalizeExercised(event);`,
-            `        ${choice.exercisedEventTypeName}.assertTemplateIdentity(normalized.metadata.templateId);`,
+            `        ${choice.exercisedEventTypeName}.assertTemplateIdentity(normalized.metadata.templateId, normalized.metadata.packageName);`,
             `        return ${choice.exercisedEventTypeName}.fromNormalizedEvent(normalized);`,
             "    }",
             "",
             `    public static fromNormalizedEvent(event: ${this.getSdkName("DamlNormalizedExercisedEvent", runtimeWrapperTypeNames)}): ${choice.exercisedEventTypeName} {`,
-            `        ${choice.exercisedEventTypeName}.assertTemplateIdentity(event.metadata.templateId);`,
+            `        ${choice.exercisedEventTypeName}.assertTemplateIdentity(event.metadata.templateId, event.metadata.packageName);`,
             `        if (event.choice !== ${JSON.stringify(choice.name)}) {`,
             `            throw new ${this.getSdkName("DamlMaterializationError", runtimeWrapperTypeNames)}("choice", \`Expected choice '${choice.name}' but received '\${event.choice}'\`);`,
             "        }",
@@ -207,14 +210,28 @@ class TemplateBindingEmitter {
             `        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 ${this.getSdkName("DamlMaterializationError", runtimeWrapperTypeNames)}("template ID", \`Expected template '${binding.templateIdLiteral}' but received '\${identity.packageId}:\${identity.moduleName}:\${identity.entityName}'\`);`,
-            "        }",
-            "    }",
+            ...this.emitAssertTemplateIdentity(binding, runtimeWrapperTypeNames),
             "}",
         ].join("\n");
     }
+    /**
+     * Emits the identity guard for materialization. Module and entity must match exactly; the package is
+     * matched by NAME when the event provides one — never by exact package id, because smart contract
+     * upgrades give every version its own id while contracts from any version stay materializable.
+     */
+    emitAssertTemplateIdentity(binding, runtimeWrapperTypeNames) {
+        const lines = [
+            "    private static assertTemplateIdentity(identity: { readonly packageId: string; readonly moduleName: string; readonly entityName: string }, packageName?: string): void {",
+            `        if (identity.moduleName !== ${JSON.stringify(this.moduleName(binding))} || identity.entityName !== ${JSON.stringify(this.entityName(binding))}) {`,
+            `            throw new ${this.getSdkName("DamlMaterializationError", runtimeWrapperTypeNames)}("template ID", \`Expected template '${binding.templateIdLiteral}' but received '\${identity.packageId}:\${identity.moduleName}:\${identity.entityName}'\`);`,
+            "        }",
+        ];
+        if (binding.packageName !== undefined) {
+            lines.push(`        if (packageName !== undefined && packageName !== ${JSON.stringify(binding.packageName)}) {`, `            throw new ${this.getSdkName("DamlMaterializationError", runtimeWrapperTypeNames)}("template ID", \`Expected package '${binding.packageName}' but received '\${packageName}' for template '${binding.templateIdLiteral}'\`);`, "        }");
+        }
+        lines.push("    }");
+        return lines;
+    }
     emitTemplateDescriptor(binding) {
         return `{ kind: "record", fields: [${binding.createFields.map((field) => `{ damlLabel: ${JSON.stringify(field.name)}, propertyName: ${JSON.stringify(field.propertyName)}, type: ${this.emitDescriptor(field.type)} }`).join(", ")}] }`;
     }
@@ -515,8 +532,16 @@ class TemplateBindingEmitter {
         }
         return (hash >>> 0).toString(36).padStart(6, "0").slice(-6);
     }
-    packageId(binding) {
-        return binding.templateIdLiteral.split(":")[0];
+    /**
+     * The emitted identity literal NEVER contains a package id when the package name is known: package ids
+     * are version-specific under smart contract upgrades, while packageName:module:entity is stable. The
+     * id-based form remains only for metadata-less invocations (tests driving the emitter directly).
+     */
+    templateIdLiteral(template) {
+        const packageName = this.packageMetadata?.get(template.templateId.packageId)?.packageName;
+        return packageName === undefined
+            ? this.nameResolver.getTemplateIdLiteral(template)
+            : `${packageName}:${template.templateId.moduleName}:${template.templateId.templateName}`;
     }
     moduleName(binding) {
         return binding.templateIdLiteral.split(":")[1];

package/dist/cjs/daml-interface/emission-model/generated-template-binding.js

@@ -21,6 +21,8 @@ class GeneratedTemplateBinding {
     namespaceAlias;
     className;
     templateIdLiteral;
+    /** The owning package's name; enables upgrade-aware (name-based) identity checks in emitted code. */
+    packageName;
     path;
     createFieldsTypeName;
     createdEventTypeName;
@@ -31,6 +33,7 @@ class GeneratedTemplateBinding {
         this.namespaceAlias = init.namespaceAlias ?? init.className;
         this.className = init.className;
         this.templateIdLiteral = init.templateIdLiteral;
+        this.packageName = init.packageName;
         this.path = init.path;
         this.createFieldsTypeName = init.createFieldsTypeName;
         this.createdEventTypeName = init.createdEventTypeName;

package/dist/cjs/daml-interface/runtime/daml-event-source-normalizer.js

@@ -147,6 +147,7 @@ function identityFrom(value, path) {
 function freezeCreatedMetadata(event, templateId) {
     return Object.freeze(removeUndefined({
         templateId,
+        packageName: optionalPackageName(event, "created event source"),
         offset: optionalString(event, ["offset", "createdEventOffset", "created_event_offset"], "offset", "created event source"),
         nodeId: optionalNodeId(event, ["nodeId", "node_id"], "node ID", "created event source"),
         witnessParties: optionalStringArray(event, ["witnessParties", "witness_parties", "witnesses"], "witness parties", "created event source"),
@@ -160,6 +161,7 @@ function freezeExercisedMetadata(event, source, templateId) {
     const transaction = asObject(readProperty(event, ["transaction"]).value) ?? asObject(root?.transaction);
     return Object.freeze(removeUndefined({
         templateId,
+        packageName: optionalPackageName(event, "exercised event source"),
         offset: optionalString(event, ["offset"], "offset", "exercised event source")
             ?? optionalString(transaction ?? {}, ["offset"], "offset", "exercised event source"),
         nodeId: optionalNodeId(event, ["nodeId", "node_id"], "node ID", "exercised event source"),
@@ -527,6 +529,17 @@ function cloneAndFreeze(value, seen = new WeakMap()) {
 function removeUndefined(value) {
     return Object.fromEntries(Object.entries(value).filter(([, field]) => field !== undefined));
 }
+/** Protobuf-generated events default packageName to ""; treat the default as absent, not invalid. */
+function optionalPackageName(event, context) {
+    const { value } = readProperty(event, ["packageName", "package_name"]);
+    if (value === undefined || value === null || value === "") {
+        return undefined;
+    }
+    if (typeof value !== "string") {
+        throw sourceError(context, "package name must be a string");
+    }
+    return value;
+}
 function sourceError(path, detail) {
     return new daml_materialization_error_js_1.DamlMaterializationError(path, detail);
 }

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

@@ -27,6 +27,7 @@ export class ProjectEmitter {
     /** Emits the complete in-memory DAML interface project from analyzed templates. */
     emitProject(analysis, moduleImportStyle = DamlModuleImportStyles.esm) {
         this.namedTypeEmitter.prepareProjectOrThrow(analysis.templates, analysis.typeDefinitions, analysis.packageMetadata);
+        this.templateBindingEmitter.providePackageMetadata(analysis.packageMetadata);
         const templateBindingFiles = analysis.templates.map((template) => this.templateBindingEmitter.emitTemplateBindingFile(template));
         const namedTypeFiles = this.namedTypeEmitter.emitPreparedNamedTypeFiles(analysis.typeDefinitions, templateBindingFiles, moduleImportStyle);
         const templateFiles = analysis.templates.map((template) => this.templateBindingEmitter.emitTemplateFile(template, namedTypeFiles, moduleImportStyle));

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

@@ -19,7 +19,7 @@ export class RegistryEmitter {
                 "export class GeneratedRegistry {",
                 "    public static fromCreatedEvent(event: DamlCreatedEventSource): unknown {",
                 "        const normalized = DamlEventSourceNormalizer.normalizeCreated(event);",
-                "        switch (`${normalized.metadata.templateId.packageId}:${normalized.metadata.templateId.moduleName}:${normalized.metadata.templateId.entityName}`) {",
+                "        switch (`${normalized.metadata.templateId.moduleName}:${normalized.metadata.templateId.entityName}`) {",
                 ...createdCases,
                 "            default:",
                 "                throw new DamlMaterializationError(\"template ID\", \"no generated template binding matches the created event\");",
@@ -28,7 +28,7 @@ export class RegistryEmitter {
                 "",
                 "    public static fromExercisedEvent(event: DamlExercisedEventSource): unknown {",
                 "        const normalized = DamlEventSourceNormalizer.normalizeExercised(event);",
-                "        switch (`${normalized.metadata.templateId.packageId}:${normalized.metadata.templateId.moduleName}:${normalized.metadata.templateId.entityName}`) {",
+                "        switch (`${normalized.metadata.templateId.moduleName}:${normalized.metadata.templateId.entityName}`) {",
                 ...exercisedCases,
                 "            default:",
                 "                throw new DamlMaterializationError(\"template ID\", \"no generated template binding matches the exercised event\");",
@@ -40,6 +40,20 @@ export class RegistryEmitter {
         });
     }
     emitCases(project, methodName) {
-        return project.templateFiles.map((file) => `            case "${file.binding.templateIdLiteral}":\n                return ${file.binding.className}.${methodName}(event);`);
+        // Dispatch is by module:entity — package ids are version-specific under smart contract upgrades,
+        // so any version of a template routes to its binding; the binding's own identity guard then
+        // verifies the package name when the event carries one.
+        const seen = new Map();
+        return project.templateFiles.map((file) => {
+            const parts = file.binding.templateIdLiteral.split(":");
+            const dispatchKey = `${parts[1]}:${parts[2]}`;
+            const existing = seen.get(dispatchKey);
+            if (existing !== undefined && existing !== file.binding.templateIdLiteral) {
+                throw new Error(`Generated registry cannot dispatch '${dispatchKey}': templates '${existing}' and `
+                    + `'${file.binding.templateIdLiteral}' collide on module:entity across packages.`);
+            }
+            seen.set(dispatchKey, file.binding.templateIdLiteral);
+            return `            case "${dispatchKey}":\n                return ${file.binding.className}.${methodName}(event);`;
+        });
     }
 }

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

@@ -6,7 +6,12 @@ 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;
+    private packageMetadata?;
     constructor(nameResolver?: TypeScriptNameResolver);
+    /** Supplies per-package metadata so emitted identity checks can match by package NAME across upgrades. */
+    providePackageMetadata(metadata: ReadonlyMap<string, {
+        readonly packageName: string;
+    }>): void;
     /** 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. */
@@ -18,6 +23,12 @@ export declare class TemplateBindingEmitter {
     private emitImports;
     private emitTemplateClass;
     private emitChoiceEventClass;
+    /**
+     * Emits the identity guard for materialization. Module and entity must match exactly; the package is
+     * matched by NAME when the event provides one — never by exact package id, because smart contract
+     * upgrades give every version its own id while contracts from any version stay materializable.
+     */
+    private emitAssertTemplateIdentity;
     private emitTemplateDescriptor;
     private emitDescriptor;
     private getTypeName;
@@ -33,7 +44,12 @@ export declare class TemplateBindingEmitter {
     private getNamedReferenceKey;
     private toTypeName;
     private shortHash;
-    private packageId;
+    /**
+     * The emitted identity literal NEVER contains a package id when the package name is known: package ids
+     * are version-specific under smart contract upgrades, while packageName:module:entity is stable. The
+     * id-based form remains only for metadata-less invocations (tests driving the emitter directly).
+     */
+    private templateIdLiteral;
     private moduleName;
     private entityName;
     private relativeFilePath;

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

@@ -7,10 +7,15 @@ import { RelativeModuleSpecifier } from "./relative-module-specifier.js";
 /** Emits typed contract and exercise-event bindings for analyzed DAML templates. */
 export class TemplateBindingEmitter {
     nameResolver;
+    packageMetadata;
     constructor(nameResolver = new TypeScriptNameResolver()) {
         this.nameResolver = nameResolver;
         void this.nameResolver;
     }
+    /** Supplies per-package metadata so emitted identity checks can match by package NAME across upgrades. */
+    providePackageMetadata(metadata) {
+        this.packageMetadata = metadata;
+    }
     /** Prepares stable collision-safe names before emitting a complete project. */
     prepareTemplatesOrThrow(templates) {
         this.nameResolver.prepareTemplatesOrThrow(templates);
@@ -46,7 +51,8 @@ export class TemplateBindingEmitter {
             templateIdentityKey: this.nameResolver.getTemplateIdentityKey(template),
             namespaceAlias: this.nameResolver.getNamespaceAlias(template),
             className,
-            templateIdLiteral: this.nameResolver.getTemplateIdLiteral(template),
+            templateIdLiteral: this.templateIdLiteral(template),
+            packageName: this.packageMetadata?.get(template.templateId.packageId)?.packageName,
             path: this.nameResolver.getTemplateFilePath(template),
             createFieldsTypeName: this.nameResolver.getCreateFieldsTypeName(template),
             createdEventTypeName: this.nameResolver.getCreatedEventTypeName(template),
@@ -130,6 +136,7 @@ export class TemplateBindingEmitter {
         return [
             `export class ${binding.className} extends ${this.getSdkName("DamlTemplate", runtimeWrapperTypeNames)} implements ${binding.createFieldsTypeName} {`,
             `    public static readonly templateId = ${JSON.stringify(binding.templateIdLiteral)};`,
+            ...(binding.packageName === undefined ? [] : [`    public static readonly packageName = ${JSON.stringify(binding.packageName)};`]),
             `    private static readonly descriptor: ${this.getSdkName("DamlTypeDescriptor", runtimeWrapperTypeNames)} = ${this.emitTemplateDescriptor(binding)};`,
             "",
             ...binding.createFields.map((field) => `    public readonly ${field.propertyName}: ${field.typeName};`),
@@ -141,7 +148,7 @@ export class TemplateBindingEmitter {
             "",
             `    public static fromCreatedEvent(event: ${this.getSdkName("DamlCreatedEventSource", runtimeWrapperTypeNames)}): ${binding.className} {`,
             `        const normalized = ${this.getSdkName("DamlEventSourceNormalizer", runtimeWrapperTypeNames)}.normalizeCreated(event);`,
-            `        ${binding.className}.assertTemplateIdentity(normalized.metadata.templateId);`,
+            `        ${binding.className}.assertTemplateIdentity(normalized.metadata.templateId, normalized.metadata.packageName);`,
             `        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,",
@@ -151,7 +158,7 @@ export class TemplateBindingEmitter {
             "",
             `    public static fromExercisedEvent(event: ${this.getSdkName("DamlExercisedEventSource", runtimeWrapperTypeNames)}): ${exercisedReturnType} {`,
             `        const normalized = ${this.getSdkName("DamlEventSourceNormalizer", runtimeWrapperTypeNames)}.normalizeExercised(event);`,
-            `        ${binding.className}.assertTemplateIdentity(normalized.metadata.templateId);`,
+            `        ${binding.className}.assertTemplateIdentity(normalized.metadata.templateId, normalized.metadata.packageName);`,
             "        switch (normalized.choice) {",
             ...binding.choices.map((choice) => `            case ${JSON.stringify(choice.name)}:\n                return ${choice.exercisedEventTypeName}.fromNormalizedEvent(normalized);`),
             "            default:",
@@ -159,11 +166,7 @@ export class TemplateBindingEmitter {
             "        }",
             "    }",
             "",
-            "    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 ${this.getSdkName("DamlMaterializationError", runtimeWrapperTypeNames)}("template ID", \`Expected template '${binding.templateIdLiteral}' but received '\${identity.packageId}:\${identity.moduleName}:\${identity.entityName}'\`);`,
-            "        }",
-            "    }",
+            ...this.emitAssertTemplateIdentity(binding, runtimeWrapperTypeNames),
             "}",
         ].join("\n");
     }
@@ -190,12 +193,12 @@ export class TemplateBindingEmitter {
             "",
             `    public static fromExercisedEvent(event: ${this.getSdkName("DamlExercisedEventSource", runtimeWrapperTypeNames)}): ${choice.exercisedEventTypeName} {`,
             `        const normalized = ${this.getSdkName("DamlEventSourceNormalizer", runtimeWrapperTypeNames)}.normalizeExercised(event);`,
-            `        ${choice.exercisedEventTypeName}.assertTemplateIdentity(normalized.metadata.templateId);`,
+            `        ${choice.exercisedEventTypeName}.assertTemplateIdentity(normalized.metadata.templateId, normalized.metadata.packageName);`,
             `        return ${choice.exercisedEventTypeName}.fromNormalizedEvent(normalized);`,
             "    }",
             "",
             `    public static fromNormalizedEvent(event: ${this.getSdkName("DamlNormalizedExercisedEvent", runtimeWrapperTypeNames)}): ${choice.exercisedEventTypeName} {`,
-            `        ${choice.exercisedEventTypeName}.assertTemplateIdentity(event.metadata.templateId);`,
+            `        ${choice.exercisedEventTypeName}.assertTemplateIdentity(event.metadata.templateId, event.metadata.packageName);`,
             `        if (event.choice !== ${JSON.stringify(choice.name)}) {`,
             `            throw new ${this.getSdkName("DamlMaterializationError", runtimeWrapperTypeNames)}("choice", \`Expected choice '${choice.name}' but received '\${event.choice}'\`);`,
             "        }",
@@ -204,14 +207,28 @@ export class TemplateBindingEmitter {
             `        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 ${this.getSdkName("DamlMaterializationError", runtimeWrapperTypeNames)}("template ID", \`Expected template '${binding.templateIdLiteral}' but received '\${identity.packageId}:\${identity.moduleName}:\${identity.entityName}'\`);`,
-            "        }",
-            "    }",
+            ...this.emitAssertTemplateIdentity(binding, runtimeWrapperTypeNames),
             "}",
         ].join("\n");
     }
+    /**
+     * Emits the identity guard for materialization. Module and entity must match exactly; the package is
+     * matched by NAME when the event provides one — never by exact package id, because smart contract
+     * upgrades give every version its own id while contracts from any version stay materializable.
+     */
+    emitAssertTemplateIdentity(binding, runtimeWrapperTypeNames) {
+        const lines = [
+            "    private static assertTemplateIdentity(identity: { readonly packageId: string; readonly moduleName: string; readonly entityName: string }, packageName?: string): void {",
+            `        if (identity.moduleName !== ${JSON.stringify(this.moduleName(binding))} || identity.entityName !== ${JSON.stringify(this.entityName(binding))}) {`,
+            `            throw new ${this.getSdkName("DamlMaterializationError", runtimeWrapperTypeNames)}("template ID", \`Expected template '${binding.templateIdLiteral}' but received '\${identity.packageId}:\${identity.moduleName}:\${identity.entityName}'\`);`,
+            "        }",
+        ];
+        if (binding.packageName !== undefined) {
+            lines.push(`        if (packageName !== undefined && packageName !== ${JSON.stringify(binding.packageName)}) {`, `            throw new ${this.getSdkName("DamlMaterializationError", runtimeWrapperTypeNames)}("template ID", \`Expected package '${binding.packageName}' but received '\${packageName}' for template '${binding.templateIdLiteral}'\`);`, "        }");
+        }
+        lines.push("    }");
+        return lines;
+    }
     emitTemplateDescriptor(binding) {
         return `{ kind: "record", fields: [${binding.createFields.map((field) => `{ damlLabel: ${JSON.stringify(field.name)}, propertyName: ${JSON.stringify(field.propertyName)}, type: ${this.emitDescriptor(field.type)} }`).join(", ")}] }`;
     }
@@ -512,8 +529,16 @@ export class TemplateBindingEmitter {
         }
         return (hash >>> 0).toString(36).padStart(6, "0").slice(-6);
     }
-    packageId(binding) {
-        return binding.templateIdLiteral.split(":")[0];
+    /**
+     * The emitted identity literal NEVER contains a package id when the package name is known: package ids
+     * are version-specific under smart contract upgrades, while packageName:module:entity is stable. The
+     * id-based form remains only for metadata-less invocations (tests driving the emitter directly).
+     */
+    templateIdLiteral(template) {
+        const packageName = this.packageMetadata?.get(template.templateId.packageId)?.packageName;
+        return packageName === undefined
+            ? this.nameResolver.getTemplateIdLiteral(template)
+            : `${packageName}:${template.templateId.moduleName}:${template.templateId.templateName}`;
     }
     moduleName(binding) {
         return binding.templateIdLiteral.split(":")[1];

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

@@ -19,6 +19,8 @@ export declare class GeneratedTemplateBinding {
     readonly namespaceAlias: string;
     readonly className: string;
     readonly templateIdLiteral: string;
+    /** The owning package's name; enables upgrade-aware (name-based) identity checks in emitted code. */
+    readonly packageName?: string;
     readonly path: string;
     readonly createFieldsTypeName: string;
     readonly createdEventTypeName: string;
@@ -29,6 +31,7 @@ export declare class GeneratedTemplateBinding {
         namespaceAlias?: string;
         className: string;
         templateIdLiteral: string;
+        packageName?: string;
         path: string;
         createFieldsTypeName: string;
         createdEventTypeName: string;

package/dist/daml-interface/emission-model/generated-template-binding.js

@@ -17,6 +17,8 @@ export class GeneratedTemplateBinding {
     namespaceAlias;
     className;
     templateIdLiteral;
+    /** The owning package's name; enables upgrade-aware (name-based) identity checks in emitted code. */
+    packageName;
     path;
     createFieldsTypeName;
     createdEventTypeName;
@@ -27,6 +29,7 @@ export class GeneratedTemplateBinding {
         this.namespaceAlias = init.namespaceAlias ?? init.className;
         this.className = init.className;
         this.templateIdLiteral = init.templateIdLiteral;
+        this.packageName = init.packageName;
         this.path = init.path;
         this.createFieldsTypeName = init.createFieldsTypeName;
         this.createdEventTypeName = init.createdEventTypeName;

package/dist/daml-interface/runtime/daml-event-source-normalizer.d.ts

@@ -8,6 +8,8 @@ export type DamlCreatedEventSource = CreatedEvent | GetContractResponse | Active
 export type DamlExercisedEventSource = ExercisedEvent | ExerciseResult | Event | DamlJsonEventRecord;
 export type DamlCreatedEventMetadata = {
     readonly templateId: DamlTypeIdentity;
+    /** The template's package NAME — the stable identity across smart-contract-upgrade versions. */
+    readonly packageName?: string;
     readonly offset?: string;
     readonly nodeId?: number;
     readonly witnessParties?: readonly string[];
@@ -18,6 +20,8 @@ export type DamlCreatedEventMetadata = {
 };
 export type DamlExercisedEventMetadata = {
     readonly templateId: DamlTypeIdentity;
+    /** The template's package NAME — the stable identity across smart-contract-upgrade versions. */
+    readonly packageName?: string;
     readonly offset?: string;
     readonly nodeId?: number;
     readonly actingParties?: readonly string[];

package/dist/daml-interface/runtime/daml-event-source-normalizer.js

@@ -143,6 +143,7 @@ function identityFrom(value, path) {
 function freezeCreatedMetadata(event, templateId) {
     return Object.freeze(removeUndefined({
         templateId,
+        packageName: optionalPackageName(event, "created event source"),
         offset: optionalString(event, ["offset", "createdEventOffset", "created_event_offset"], "offset", "created event source"),
         nodeId: optionalNodeId(event, ["nodeId", "node_id"], "node ID", "created event source"),
         witnessParties: optionalStringArray(event, ["witnessParties", "witness_parties", "witnesses"], "witness parties", "created event source"),
@@ -156,6 +157,7 @@ function freezeExercisedMetadata(event, source, templateId) {
     const transaction = asObject(readProperty(event, ["transaction"]).value) ?? asObject(root?.transaction);
     return Object.freeze(removeUndefined({
         templateId,
+        packageName: optionalPackageName(event, "exercised event source"),
         offset: optionalString(event, ["offset"], "offset", "exercised event source")
             ?? optionalString(transaction ?? {}, ["offset"], "offset", "exercised event source"),
         nodeId: optionalNodeId(event, ["nodeId", "node_id"], "node ID", "exercised event source"),
@@ -523,6 +525,17 @@ function cloneAndFreeze(value, seen = new WeakMap()) {
 function removeUndefined(value) {
     return Object.fromEntries(Object.entries(value).filter(([, field]) => field !== undefined));
 }
+/** Protobuf-generated events default packageName to ""; treat the default as absent, not invalid. */
+function optionalPackageName(event, context) {
+    const { value } = readProperty(event, ["packageName", "package_name"]);
+    if (value === undefined || value === null || value === "") {
+        return undefined;
+    }
+    if (typeof value !== "string") {
+        throw sourceError(context, "package name must be a string");
+    }
+    return value;
+}
 function sourceError(path, detail) {
     return new DamlMaterializationError(path, detail);
 }

package/node/start-local-participant-358.sh

@@ -91,6 +91,8 @@ cat > "$RUNTIME_DIR/canton.conf" <<EOF
 canton {
   parameters { manual-start = no }
   participants.participant358 {
+    # The pruning live spec needs a safe pruning offset promptly on a fresh participant.
+    parameters { journal-garbage-collection-delay = 0s }
     storage {
       type = postgres
       config {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@distrohelena/canton-typescript-sdk",
-    "version": "0.1.50",
+    "version": "0.1.52",
     "license": "Apache-2.0",
     "type": "module",
     "main": "./dist/index.js",
@@ -87,6 +87,7 @@
     },
     "scripts": {
         "build": "node ./scripts/clean-dist.mjs && tsc -p tsconfig.json && tsc -p tsconfig.cjs.json && node ./scripts/write-cjs-package.mjs",
+        "prepublishOnly": "npm run build && npm run test:unit",
         "generate:daml-interface": "node ./dist/daml-interface/cli/daml-interface-cli-main.js",
         "generate:grpc": "node ./scripts/generate-grpc-bindings.mjs",
         "examples:check": "npm run build && tsc -p tsconfig.examples.json --noEmit",