@distrohelena/canton-typescript-sdk 0.1.43 → 0.1.45

package/dist/cjs/query/grpc/grpc-contract-cache.js

@@ -65,12 +65,19 @@ class GrpcContractCache {
     async populateAsync(parties, key) {
         const activeContracts = [];
         const seenPageTokens = new Set();
+        // Every continuation request must be identical to the first page's request apart from the page
+        // token: the participant validates each token against the request it was minted for, so adopting
+        // the response's now-explicit activeAtOffset into page 2+ makes it reject the token
+        // (INVALID_ACS_PAGE_TOKEN) — the token was prepared for a request with the field absent. The token
+        // itself pins the snapshot offset; the echoed offset is only tracked to validate it stays constant.
+        const baseRequest = (0, contracts_mapper_js_1.mapGrpcQueryContractsRequest)(parties === undefined ? { allParties: true } : { parties });
         let activeAtOffset;
         let pageToken;
         do {
-            const page = materializeActiveContractsPage(await this.stateService.getActiveContractsPageAsync((0, contracts_mapper_js_1.mapGrpcQueryContractsRequest)(parties === undefined
-                ? { allParties: true, activeAtOffset, pageToken }
-                : { parties, activeAtOffset, pageToken })));
+            const page = materializeActiveContractsPage(await this.stateService.getActiveContractsPageAsync({
+                ...baseRequest,
+                pageToken: pageToken === undefined ? undefined : Uint8Array.from(pageToken),
+            }));
             if (activeAtOffset === undefined) {
                 activeAtOffset = page.activeAtOffset;
             }

package/dist/cjs/query/grpc/grpc-query-client.js

@@ -11,6 +11,7 @@ const query_source_js_1 = require("../query-source.js");
 const grpc_relation_mapper_js_1 = require("./grpc-relation-mapper.js");
 const grpc_package_relation_reader_js_1 = require("./grpc-package-relation-reader.js");
 const grpc_query_snapshot_reader_js_1 = require("./grpc-query-snapshot-reader.js");
+const grpc_query_value_mapper_js_1 = require("./grpc-query-value-mapper.js");
 class GrpcQueryClient {
     options;
     source = query_source_js_1.QuerySource.grpc;
@@ -66,7 +67,7 @@ class DefaultGrpcQueryDataProvider {
     packages;
     constructor(options) {
         this.options = options;
-        this.snapshots = new grpc_query_snapshot_reader_js_1.GrpcQuerySnapshotReader(options.stateService, options.updateService);
+        this.snapshots = new grpc_query_snapshot_reader_js_1.GrpcQuerySnapshotReader(options.stateService, options.updateService, { incrementalHistory: options.incrementalHistory });
         this.packages = new grpc_package_relation_reader_js_1.GrpcPackageRelationReader(options.packageService);
     }
     async readDatasetAsync(query) {
@@ -80,29 +81,44 @@ class DefaultGrpcQueryDataProvider {
             return cachedContractsDataset(cached.contracts, cached.activeAtOffset, this.options.endpointScope ?? "ledger");
         }
         else if (needsHistory) {
-            console.warn(`[GrpcQueryClient] Falling back to a full ledger replay from offset 0 for a "${query.relation}" query. `
-                + "This is expensive and should be an extreme edge case. It is usually triggered by a \"contracts\" query "
-                + "that does not explicitly prove `active: true` (so archived contracts may be in scope), or by querying "
-                + "\"transactions\"/\"events\"/\"exercises\" directly. Add an explicit active:true filter if only current state is needed.");
+            // With a warm incremental window only the new offsets are fetched, which is no longer worth a warning.
+            if (!(this.options.incrementalHistory === true && this.snapshots.hasHistoryCache)) {
+                console.warn(`[GrpcQueryClient] Falling back to a full ledger replay from offset 0 for a "${query.relation}" query. `
+                    + "This is expensive and should be an extreme edge case. It is usually triggered by a \"contracts\" query "
+                    + "that does not explicitly prove `active: true` (so archived contracts may be in scope), or by querying "
+                    + "\"transactions\"/\"events\"/\"exercises\" directly. Add an explicit active:true filter if only current state is needed"
+                    + (this.options.incrementalHistory === true
+                        ? "; incrementalHistory is enabled, so later history queries will fetch only new offsets."
+                        : ", or enable the incrementalHistory option to fetch only new offsets on repeat history queries."));
+            }
             const endInclusive = cached?.activeAtOffset ?? (await this.options.stateService.getLedgerEndAsync({})).offset;
             const history = await this.snapshots.readHistoryAsync(endInclusive);
             const transactions = history.updates.flatMap((response) => response.update.oneofKind === "transaction" ? [response.update.transaction] : []);
             const fragment = (0, grpc_relation_mapper_js_1.mapGrpcQueryRelationFragment)(transactions);
-            const useCreationsOnlyMetadata = requiresPackageMetadata(closure)
-                && query.relation !== "packages" && query.relation !== "contractTypes" && query.relation !== "exerciseTypes"
-                && derivableFromCreationsOnly(closure);
+            // Catalog queries rooted at packages/contractTypes/exerciseTypes need every known package's
+            // full type inventory, which only the decoded archives provide.
+            const catalogRelation = query.relation === "packages" || query.relation === "contractTypes" || query.relation === "exerciseTypes";
+            const closureNeedsExercises = closure.has("exercises") || closure.has("exerciseTypes");
+            // Non-catalog metadata can usually come straight from the fetched events: creations always name
+            // their own package, and direct exercises name their choice owner's. packageMetadataFromEvents
+            // returns undefined when the window holds an interface-exercised choice (owner package name is
+            // not on the event), and "packages" rows (version) have no event equivalent at all — both fall
+            // back to the archive decode.
+            const derivedMetadata = requiresPackageMetadata(closure) && !catalogRelation && !closure.has("packages")
+                ? closureNeedsExercises
+                    ? (0, grpc_relation_mapper_js_1.packageMetadataFromEvents)(fragment)
+                    : (0, grpc_relation_mapper_js_1.contractTypeMetadataFromCreations)(fragment.creationIdentities)
+                : undefined;
             const packageMetadata = !requiresPackageMetadata(closure)
                 ? []
-                : query.relation === "packages" || query.relation === "contractTypes" || query.relation === "exerciseTypes"
+                : catalogRelation
                     ? await this.packages.readAllAsync()
-                    : useCreationsOnlyMetadata
-                        ? (0, grpc_relation_mapper_js_1.contractTypeMetadataFromCreations)(fragment.creationIdentities)
-                        : await this.packages.readPackagesAsync((0, grpc_relation_mapper_js_1.referencedGrpcPackageIds)(fragment));
-            // The closure guarantees this query never reads "exercises" here, but the replayed window can still
-            // contain unrelated exercises (createGrpcQueryDataset always resolves package metadata for every
-            // exercise in the fragment). contractTypeMetadataFromCreations only knows about templates, so drop
-            // the exercises this query doesn't need instead of paying for their canonical keys.
-            const datasetFragment = useCreationsOnlyMetadata ? { ...fragment, exercises: [] } : fragment;
+                    : derivedMetadata ?? await this.packages.readPackagesAsync((0, grpc_relation_mapper_js_1.referencedGrpcPackageIds)(fragment));
+            // When the closure never reads exercises, the replayed window's unrelated exercises are dropped:
+            // createGrpcQueryDataset resolves canonical keys for every exercise present, and creations-only
+            // metadata knows nothing about choices. When the closure does read exercises, the event-derived
+            // metadata covers them and they stay.
+            const datasetFragment = derivedMetadata !== undefined && !closureNeedsExercises ? { ...fragment, exercises: [] } : fragment;
             return packageMetadata.length === 0
                 ? fragmentDataset(fragment, endInclusive, this.options.endpointScope ?? "ledger")
                 : (0, grpc_relation_mapper_js_1.createGrpcQueryDataset)(datasetFragment, packageMetadata, endInclusive, this.options.endpointScope ?? "ledger");
@@ -120,7 +136,7 @@ class DefaultGrpcQueryDataProvider {
         else if (query.relation === "watermark") {
             return (0, grpc_relation_mapper_js_1.createGrpcQueryDataset)((0, grpc_relation_mapper_js_1.mapGrpcQueryRelationFragment)([]), [], endInclusive, this.options.endpointScope ?? "ledger");
         }
-        const active = await this.snapshots.readActiveContractsAsync(endInclusive, partiesFor(query));
+        const active = await this.snapshots.readActiveContractsAsync(endInclusive, partiesFor(query), pushdownTemplateRefsFor(query));
         const fragment = (0, grpc_relation_mapper_js_1.mapGrpcQueryRelationFragment)([], active.activeContracts);
         if (!requiresPackageMetadata(closure)) {
             return fragmentDataset(fragment, endInclusive, this.options.endpointScope ?? "ledger", false);
@@ -181,23 +197,109 @@ function predicateProvesActive(predicate) {
 function requiresPackageMetadata(closure) {
     return closure.has("packages") || closure.has("contractTypes") || closure.has("exercises") || closure.has("exerciseTypes");
 }
+const MAX_PUSHDOWN_TEMPLATE_FILTERS = 25;
 /**
- * True when contractType metadata can be derived from the fetched creation events alone (see
- * contractTypeMetadataFromCreations), instead of decoding LF packages. Every CreatedEvent already carries its
- * own packageName, so this always holds whenever the query's closure needs only "contractTypes" (plus
- * "contracts"/"transactions"/"events", which carry no package linkage of their own). It does NOT extend to
- * "exercises"/"exerciseTypes": ExercisedEvent.packageName documents "the package name of the contract" — i.e.
- * the template side — so it is not a reliable source for the choice owner's package name when a choice was
- * exercised via an interface. "packages" is excluded because its own rows (e.g. version) have no event
- * equivalent at all.
- *
- * The caller is responsible for dropping any exercises the fetched fragment happens to contain before handing
- * it to createGrpcQueryDataset: a full-history fragment reflects the *entire* replayed window, not just what
- * this query's closure touches, and createGrpcQueryDataset unconditionally resolves package metadata for
- * every exercise present — this function only knows about templates, not choices.
+ * Extracts template filters the ACS request itself can apply, so non-matching contracts are never
+ * downloaded or materialized. The participant scans its whole ACS either way — the win is wire volume and
+ * client-side decode/freeze work, not node time. Correctness rule: the evaluator re-applies the complete
+ * predicate over whatever rows come back, so a pushed filter set only has to be a SUPERSET of possible
+ * matches — over-fetching is fine, under-fetching never happens because pins are only read from top-level
+ * AND conjuncts (anything under or/not is ignored) and any single conjunct constrains every matching row.
+ * Returns undefined (wildcard fetch) when no full package/module/entity pin can be proven or a pinned value
+ * is not a syntactically valid identifier (a malformed value can never match, but pushing it would make the
+ * node reject the request instead of returning the empty result the evaluator would produce).
  */
-function derivableFromCreationsOnly(closure) {
-    return closure.has("contractTypes") && !closure.has("exercises") && !closure.has("exerciseTypes") && !closure.has("packages");
+function pushdownTemplateRefsFor(query) {
+    if (query.relation !== "contracts") {
+        return undefined;
+    }
+    const stringValues = (operator, value) => operator === "equals" && typeof value === "string"
+        ? [value]
+        : operator === "in" && Array.isArray(value) && value.every((item) => typeof item === "string") ? value : undefined;
+    let packageRefs;
+    let moduleNames;
+    let entityNames;
+    let fqnRefs;
+    for (const conjunct of flattenAndConjuncts(query.predicate)) {
+        if (conjunct.kind === "scalar" && conjunct.path.length === 2 && conjunct.path[0] === "templateId") {
+            const values = stringValues(conjunct.operator, conjunct.value);
+            if (values === undefined) {
+                continue;
+            }
+            else if (conjunct.path[1] === "packageId") {
+                packageRefs ??= values;
+            }
+            else if (conjunct.path[1] === "moduleName") {
+                moduleNames ??= values;
+            }
+            else if (conjunct.path[1] === "entityName") {
+                entityNames ??= values;
+            }
+        }
+        else if (conjunct.kind === "relation" && conjunct.edge === "contractType" && conjunct.quantifier === "one") {
+            for (const inner of flattenAndConjuncts(conjunct.predicate)) {
+                if (inner.kind !== "scalar" || inner.path.length !== 1) {
+                    continue;
+                }
+                const values = stringValues(inner.operator, inner.value);
+                if (values === undefined) {
+                    continue;
+                }
+                else if (inner.path[0] === "packageName") {
+                    packageRefs ??= values.map((name) => `#${name}`);
+                }
+                else if (inner.path[0] === "moduleName") {
+                    moduleNames ??= values;
+                }
+                else if (inner.path[0] === "entityName") {
+                    entityNames ??= values;
+                }
+                else if (inner.path[0] === "templateFqn") {
+                    const triples = values.map(templateRefFromFqn);
+                    if (triples.every((triple) => triple !== undefined)) {
+                        fqnRefs ??= triples;
+                    }
+                }
+            }
+        }
+    }
+    const refs = fqnRefs ?? (packageRefs !== undefined && moduleNames !== undefined && entityNames !== undefined
+        ? packageRefs.flatMap((packageId) => moduleNames.flatMap((moduleName) => entityNames.map((entityName) => ({ packageId, moduleName, entityName }))))
+        : undefined);
+    return refs !== undefined && refs.length > 0 && refs.length <= MAX_PUSHDOWN_TEMPLATE_FILTERS && refs.every(isValidTemplateRef)
+        ? refs
+        : undefined;
+}
+function flattenAndConjuncts(predicate) {
+    if (predicate === undefined) {
+        return [];
+    }
+    else if (predicate.kind === "and") {
+        return predicate.children.flatMap(flattenAndConjuncts);
+    }
+    return [predicate];
+}
+function templateRefFromFqn(fqn) {
+    const parts = fqn.split(":");
+    return parts.length === 3 && parts.every((part) => part.length > 0)
+        ? { packageId: `#${parts[0]}`, moduleName: parts[1], entityName: parts[2] }
+        : undefined;
+}
+function isValidTemplateRef(ref) {
+    const validPackage = ref.packageId.startsWith("#")
+        ? /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(ref.packageId.slice(1))
+        : /^[0-9a-f]{64}$/.test(ref.packageId);
+    if (!validPackage) {
+        return false;
+    }
+    try {
+        (0, grpc_query_value_mapper_js_1.validDottedNameString)(ref.moduleName, "template filter module name");
+        (0, grpc_query_value_mapper_js_1.validDottedNameString)(ref.entityName, "template filter entity name");
+        return true;
+    }
+    catch {
+        return false;
+    }
 }
 function predicateRequiresHistory(relation, predicate) {
     if (predicate === undefined || predicate.kind === "scalar") {

package/dist/cjs/query/grpc/grpc-query-snapshot-reader.js

@@ -9,7 +9,7 @@ const transaction_filter_js_1 = require("../../transports/grpc/generated/canton/
 const contracts_mapper_js_1 = require("../../transports/grpc/mappers/contracts-mapper.js");
 const query_dataset_js_1 = require("../canonical/query-dataset.js");
 const query_snapshot_incomplete_error_js_1 = require("../errors/query-snapshot-incomplete-error.js");
-const DEFAULT_OPTIONS = {
+const DEFAULT_LIMITS = {
     maxHistoryPages: 10_000,
     maxHistoryUpdates: 1_000_000,
     maxActiveContractPages: 10_000,
@@ -20,11 +20,16 @@ class GrpcQuerySnapshotReader {
     stateService;
     updateService;
     options;
+    historyCache;
     constructor(stateService, updateService, options = {}) {
         this.stateService = stateService;
         this.updateService = updateService;
         this.options = validateOptions(options);
     }
+    /** Whether an incremental history window is already held, meaning the next read only fetches new offsets. */
+    get hasHistoryCache() {
+        return this.historyCache !== undefined;
+    }
     async readCurrentHistoryAsync() {
         const ledgerEnd = await this.stateService.getLedgerEndAsync({});
         return this.readHistoryAsync(ledgerEnd.offset);
@@ -32,26 +37,49 @@ class GrpcQuerySnapshotReader {
     async readHistoryAsync(endInclusive) {
         const end = parseOffset(endInclusive);
         if (end === undefined) {
-            throw this.historyError(endInclusive, "invalid-offset");
+            throw this.historyError(LEDGER_BEGIN, endInclusive, "invalid-offset");
+        }
+        const cached = this.options.incrementalHistory ? this.historyCache : undefined;
+        // History is append-only, so a cached window ending at or past the requested offset already contains
+        // the complete answer: an exact hit is returned as-is, a shorter request is a prefix of the window.
+        if (cached !== undefined && cached.end >= end) {
+            const updates = cached.end === end
+                ? cached.updates
+                : cached.updates.filter((update) => {
+                    const offset = parseOffset(extractUpdateOffset(update));
+                    return offset !== undefined && offset <= end;
+                });
+            return freezeSnapshot({ endInclusive, updates: Object.freeze([...updates]) });
+        }
+        const beginExclusive = cached?.end ?? 0n;
+        const snapshot = await this.readHistoryRangeAsync(beginExclusive, end, endInclusive, cached?.updates ?? []);
+        if (this.options.incrementalHistory && (this.historyCache === undefined || this.historyCache.end < end)) {
+            this.historyCache = { end, updates: snapshot.updates };
         }
+        return snapshot;
+    }
+    async readHistoryRangeAsync(beginExclusive, end, endInclusive, seed) {
+        const begin = beginExclusive.toString();
         const pruned = await this.stateService.getLatestPrunedOffsetsAsync({});
         const prunedUpTo = parseOffset(pruned.participantPrunedUpToInclusive);
-        if (prunedUpTo === undefined || prunedUpTo !== 0n) {
-            throw this.historyError(endInclusive, "participant-pruned");
+        // Offsets at or below beginExclusive are already held (or not requested), so pruning only breaks the
+        // read when it reaches past the range start.
+        if (prunedUpTo === undefined || prunedUpTo > beginExclusive) {
+            throw this.historyError(begin, endInclusive, "participant-pruned");
         }
         const updateFormat = freezeDeep(createHistoryUpdateFormat());
         const updates = [];
         const observedPageTokens = new Set();
-        let expectedLowestExclusive = 0n;
+        let expectedLowestExclusive = beginExclusive;
         let pageToken;
         let pagesRead = 0;
         let previousUpdateOffset;
         while (true) {
             if (pagesRead >= this.options.maxHistoryPages) {
-                throw this.historyError(endInclusive, "max-pages-exceeded");
+                throw this.historyError(begin, endInclusive, "max-pages-exceeded");
             }
             const request = {
-                beginOffsetExclusive: LEDGER_BEGIN,
+                beginOffsetExclusive: begin,
                 endOffsetInclusive: endInclusive,
                 updateFormat,
                 descendingOrder: false,
@@ -62,18 +90,18 @@ class GrpcQuerySnapshotReader {
             const lowest = parseOffset(response.lowestPageOffsetExclusive);
             const highest = parseOffset(response.highestPageOffsetInclusive);
             if (lowest === undefined || highest === undefined) {
-                throw this.historyError(endInclusive, "missing-boundary");
+                throw this.historyError(begin, endInclusive, "missing-boundary");
             }
             else if (lowest !== expectedLowestExclusive || highest < lowest || highest > end) {
-                throw this.historyError(endInclusive, "page-boundary-mismatch");
+                throw this.historyError(begin, endInclusive, "page-boundary-mismatch");
             }
-            if (response.updates.length > this.options.maxHistoryUpdates - updates.length) {
-                throw this.historyError(endInclusive, "max-updates-exceeded");
+            if (response.updates.length > this.options.maxHistoryUpdates - seed.length - updates.length) {
+                throw this.historyError(begin, endInclusive, "max-updates-exceeded");
             }
             for (const update of response.updates) {
                 const updateOffset = parseOffset(extractUpdateOffset(update));
                 if (updateOffset === undefined || updateOffset <= lowest || updateOffset > highest || (previousUpdateOffset !== undefined && updateOffset <= previousUpdateOffset)) {
-                    throw this.historyError(endInclusive, "page-boundary-mismatch");
+                    throw this.historyError(begin, endInclusive, "page-boundary-mismatch");
                 }
                 previousUpdateOffset = updateOffset;
             }
@@ -81,33 +109,36 @@ class GrpcQuerySnapshotReader {
             const nextPageToken = response.nextPageToken;
             if (nextPageToken === undefined || nextPageToken.length === 0) {
                 if (highest !== end) {
-                    throw this.historyError(endInclusive, "nonterminal-page-without-token");
+                    throw this.historyError(begin, endInclusive, "nonterminal-page-without-token");
                 }
                 return freezeSnapshot({
                     endInclusive,
-                    updates: Object.freeze(updates),
+                    updates: Object.freeze([...seed, ...updates]),
                 });
             }
             else if (highest >= end) {
-                throw this.historyError(endInclusive, "nonterminal-page-reaches-end");
+                throw this.historyError(begin, endInclusive, "nonterminal-page-reaches-end");
             }
             else if (highest <= lowest) {
-                throw this.historyError(endInclusive, "page-boundary-mismatch");
+                throw this.historyError(begin, endInclusive, "page-boundary-mismatch");
             }
             const tokenKey = tokenKeyFor(nextPageToken);
             if (observedPageTokens.has(tokenKey)) {
-                throw this.historyError(endInclusive, "repeated-page-token");
+                throw this.historyError(begin, endInclusive, "repeated-page-token");
             }
             observedPageTokens.add(tokenKey);
             expectedLowestExclusive = highest;
             pageToken = Uint8Array.from(nextPageToken);
         }
     }
-    async readActiveContractsAsync(activeAtOffset, parties) {
+    async readActiveContractsAsync(activeAtOffset, parties, templateRefs) {
         if (parseOffset(activeAtOffset) === undefined) {
             throw this.activeError(activeAtOffset, "invalid-offset");
         }
-        const eventFormat = freezeDeep(parties === undefined ? createAllPartiesEventFormat() : (0, contracts_mapper_js_1.mapGrpcQueryContractsRequest)({ parties }).eventFormat);
+        const eventFormat = freezeDeep((0, contracts_mapper_js_1.mapGrpcQueryContractsRequest)({
+            ...(parties === undefined ? { allParties: true } : { parties }),
+            ...(templateRefs === undefined || templateRefs.length === 0 ? {} : { templateRefs: [...templateRefs] }),
+        }).eventFormat);
         const activeContracts = [];
         const observedPageTokens = new Set();
         let pageToken;
@@ -152,9 +183,9 @@ class GrpcQuerySnapshotReader {
             pageToken = Uint8Array.from(nextPageToken);
         }
     }
-    historyError(endInclusive, reason) {
+    historyError(beginExclusive, endInclusive, reason) {
         return new query_snapshot_incomplete_error_js_1.QuerySnapshotIncompleteError({
-            beginExclusive: LEDGER_BEGIN,
+            beginExclusive,
             endInclusive,
             reason,
         });
@@ -170,13 +201,17 @@ class GrpcQuerySnapshotReader {
 }
 exports.GrpcQuerySnapshotReader = GrpcQuerySnapshotReader;
 function validateOptions(options) {
-    const validated = { ...DEFAULT_OPTIONS, ...options };
+    const { incrementalHistory = false, ...limits } = options;
+    if (typeof incrementalHistory !== "boolean") {
+        throw new validation_error_js_1.ValidationError("incrementalHistory must be a boolean.");
+    }
+    const validated = { ...DEFAULT_LIMITS, ...limits };
     for (const [name, value] of Object.entries(validated)) {
         if (!Number.isFinite(value) || !Number.isInteger(value) || value <= 0) {
             throw new validation_error_js_1.ValidationError(`${name} must be a finite positive integer.`);
         }
     }
-    return Object.freeze(validated);
+    return Object.freeze({ ...validated, incrementalHistory });
 }
 function createHistoryUpdateFormat() {
     return {

package/dist/cjs/query/grpc/grpc-relation-mapper.js

@@ -4,6 +4,7 @@ exports.mapGrpcQueryRelationFragment = mapGrpcQueryRelationFragment;
 exports.createGrpcQueryDataset = createGrpcQueryDataset;
 exports.referencedGrpcPackageIds = referencedGrpcPackageIds;
 exports.contractTypeMetadataFromCreations = contractTypeMetadataFromCreations;
+exports.packageMetadataFromEvents = packageMetadataFromEvents;
 const validation_error_js_1 = require("../../core/errors/validation-error.js");
 const query_dataset_js_1 = require("../canonical/query-dataset.js");
 const public_identity_js_1 = require("../canonical/public-identity.js");
@@ -248,40 +249,92 @@ function referencedGrpcPackageIds(fragment) {
  * Derives contractType metadata straight from already-fetched created-contract events instead of the
  * Package Service. Only valid where the caller has confirmed the query's relation closure is a subset of
  * {contracts, contractTypes} — every contract's own creation event already carries packageName directly,
- * so no archive decode is needed. "version" is a placeholder: this path is unreachable from any query that
- * can see the "packages" relation, so it is never observed.
+ * so no archive decode is needed. "version" is a per-package placeholder: this path is unreachable from
+ * any query that can see the "packages" relation, so it is never observed.
  */
 function contractTypeMetadataFromCreations(creationIdentities) {
     const packages = new Map();
-    for (const creation of creationIdentities) {
-        const packageId = creation.representativePackageId ?? creation.creationPackageId;
-        const { moduleName, entityName } = creation.templateId;
-        let pkg = packages.get(packageId);
-        if (pkg === undefined) {
-            pkg = { name: creation.packageName, templates: new Map() };
-            packages.set(packageId, pkg);
-        }
-        else if (pkg.name !== creation.packageName) {
-            throw new validation_error_js_1.ValidationError(`gRPC query package ${packageId} reports conflicting package names`);
-        }
-        const identity = `${moduleName}${entityName}`;
-        if (!pkg.templates.has(identity)) {
-            const templateFqn = `${pkg.name}:${moduleName}:${entityName}`;
-            pkg.templates.set(identity, Object.freeze({
-                moduleName,
-                entityName,
-                payloadType: "template",
-                aliases: Object.freeze([templateFqn, `${moduleName}:${entityName}`, entityName]),
-                templateFqn,
-                choices: Object.freeze([]),
-            }));
+    addDerivedCreationEntries(packages, creationIdentities);
+    return finalizeDerivedPackages(packages);
+}
+/**
+ * Extends the creations-only derivation to exercises: for a direct exercise the choice owner IS the
+ * exercised template, so the event's own packageName names the owner's package and choice/consuming come
+ * straight off the event. Returns undefined when the window contains an interface-exercised choice — its
+ * owner is the interface, whose package name the event does not carry, so only the decoded archive can
+ * produce its canonical choiceFqn. Unobserved choices are simply absent, which is complete for query plans
+ * that reach exerciseTypes only through observed exercises (never for exerciseTypes catalog queries).
+ */
+function packageMetadataFromEvents(fragment) {
+    if (fragment.typeIdentities.some((identity) => identity.choice !== undefined && identity.packageName === undefined)) {
+        return undefined;
+    }
+    const packages = new Map();
+    addDerivedCreationEntries(packages, fragment.creationIdentities);
+    for (const identity of fragment.typeIdentities) {
+        if (identity.packageName === undefined) {
+            throw new validation_error_js_1.ValidationError("gRPC query contract type identity is missing its package name");
+        }
+        const template = derivedTemplateFor(derivedPackageFor(packages, identity.packageId, identity.packageName), identity.templateId.moduleName, identity.templateId.entityName);
+        if (identity.choice !== undefined) {
+            const consuming = template.choices.get(identity.choice);
+            if (consuming !== undefined && consuming !== identity.consuming) {
+                throw new validation_error_js_1.ValidationError(`gRPC query choice ${identity.choice} reports conflicting consuming flags`);
+            }
+            template.choices.set(identity.choice, identity.consuming === true);
         }
     }
+    return finalizeDerivedPackages(packages);
+}
+function addDerivedCreationEntries(packages, creationIdentities) {
+    for (const creation of creationIdentities) {
+        derivedTemplateFor(derivedPackageFor(packages, creation.representativePackageId ?? creation.creationPackageId, creation.packageName), creation.templateId.moduleName, creation.templateId.entityName);
+    }
+}
+function derivedPackageFor(packages, packageId, packageName) {
+    const existing = packages.get(packageId);
+    if (existing === undefined) {
+        const created = { name: packageName, templates: new Map() };
+        packages.set(packageId, created);
+        return created;
+    }
+    else if (existing.name !== packageName) {
+        throw new validation_error_js_1.ValidationError(`gRPC query package ${packageId} reports conflicting package names`);
+    }
+    return existing;
+}
+function derivedTemplateFor(pkg, moduleName, entityName) {
+    const identity = `${moduleName} ${entityName}`;
+    let template = pkg.templates.get(identity);
+    if (template === undefined) {
+        template = { moduleName, entityName, choices: new Map() };
+        pkg.templates.set(identity, template);
+    }
+    return template;
+}
+function finalizeDerivedPackages(packages) {
     return Object.freeze([...packages.entries()].map(([id, pkg]) => Object.freeze({
         id,
         name: pkg.name,
-        version: "unresolved",
-        templates: Object.freeze([...pkg.templates.values()]),
+        // Unique per package: two versions of the same package name can both appear in one window, and
+        // duplicate name+version pairs are rejected during dataset normalization.
+        version: `unresolved-${id}`,
+        templates: Object.freeze([...pkg.templates.values()].map((template) => {
+            const templateFqn = `${pkg.name}:${template.moduleName}:${template.entityName}`;
+            return Object.freeze({
+                moduleName: template.moduleName,
+                entityName: template.entityName,
+                payloadType: "template",
+                aliases: Object.freeze([templateFqn, `${template.moduleName}:${template.entityName}`, template.entityName]),
+                templateFqn,
+                choices: Object.freeze([...template.choices.entries()].map(([choice, consuming]) => Object.freeze({
+                    choice,
+                    consuming,
+                    aliases: Object.freeze([`${templateFqn}:${choice}`, `${template.moduleName}:${template.entityName}:${choice}`, `${template.entityName}:${choice}`, choice]),
+                    choiceFqn: `${templateFqn}:${choice}`,
+                })).sort((left, right) => left.choice.localeCompare(right.choice))),
+            });
+        })),
     })));
 }
 function compareTemplateMetadata(left, right) {
@@ -304,7 +357,6 @@ function normalizeGrpcPackageMetadataUnsafe(packages) {
     }
     const packageValues = Array.from(packages);
     const packageIds = new Set();
-    const packageNameVersions = new Set();
     const normalized = [];
     for (const pkg of packageValues) {
         if (pkg === null || typeof pkg !== "object") {
@@ -319,11 +371,10 @@ function normalizeGrpcPackageMetadataUnsafe(packages) {
             throw new validation_error_js_1.ValidationError(`gRPC query has duplicate package metadata ${packageId}`);
         }
         packageIds.add(packageId);
-        const nameVersion = `${packageName}\u0000${packageVersion}`;
-        if (packageNameVersions.has(nameVersion)) {
-            throw new validation_error_js_1.ValidationError(`gRPC query has duplicate package metadata ${packageName}@${packageVersion}`);
-        }
-        packageNameVersions.add(nameVersion);
+        // Same name+version under two different ids is NOT rejected: package ids are content-addressed, so a
+        // recompiled or re-uploaded DAR legitimately reappears with a new id and an unchanged manifest. The
+        // name-derived canonical rows go through deduplicateCanonicalRows, which throws on any genuine
+        // metadata conflict for one canonical key — the only conflict that would actually matter.
         const templatesValue = value.templates;
         if (!Array.isArray(templatesValue)) {
             throw new validation_error_js_1.ValidationError(`gRPC query package ${packageId} templates are invalid`);
@@ -569,12 +620,19 @@ function identitiesFor(event) {
 }
 function typeIdentityRows(event, registry) {
     const template = requiredTemplate(event.templateId, "event template");
-    const contract = { pk: registry.get(contractIdentity(template)), templateId: copyTemplate(template), packageId: template.packageId };
+    const contract = { pk: registry.get(contractIdentity(template)), templateId: copyTemplate(template), packageId: template.packageId, packageName: event.packageName };
     if (!isExercised(event)) {
         return [contract];
     }
     const owner = exerciseOwner(event);
-    return [contract, { pk: registry.get(exerciseIdentity(owner, event.choice, event.consuming)), templateId: copyTemplate(owner), packageId: owner.packageId, choice: event.choice, consuming: event.consuming }];
+    return [contract, {
+            pk: registry.get(exerciseIdentity(owner, event.choice, event.consuming)),
+            templateId: copyTemplate(owner),
+            packageId: owner.packageId,
+            ...(event.interfaceId === undefined ? { packageName: event.packageName } : {}),
+            choice: event.choice,
+            consuming: event.consuming,
+        }];
 }
 function activeContractEntries(responses) {
     const entries = responses.map((response) => {

package/dist/cjs/transports/grpc/mappers/contracts-mapper.js

@@ -56,6 +56,17 @@ function createFilters(request) {
             },
         });
     }
+    for (const ref of request.templateRefs ?? []) {
+        cumulative.push({
+            identifierFilter: {
+                oneofKind: "templateFilter",
+                templateFilter: {
+                    templateId: { packageId: ref.packageId, moduleName: ref.moduleName, entityName: ref.entityName },
+                    includeCreatedEventBlob,
+                },
+            },
+        });
+    }
     if (request.interfaceId) {
         cumulative.push({
             identifierFilter: {

package/dist/query/grpc/grpc-contract-cache.js

@@ -61,12 +61,19 @@ export class GrpcContractCache {
     async populateAsync(parties, key) {
         const activeContracts = [];
         const seenPageTokens = new Set();
+        // Every continuation request must be identical to the first page's request apart from the page
+        // token: the participant validates each token against the request it was minted for, so adopting
+        // the response's now-explicit activeAtOffset into page 2+ makes it reject the token
+        // (INVALID_ACS_PAGE_TOKEN) — the token was prepared for a request with the field absent. The token
+        // itself pins the snapshot offset; the echoed offset is only tracked to validate it stays constant.
+        const baseRequest = mapGrpcQueryContractsRequest(parties === undefined ? { allParties: true } : { parties });
         let activeAtOffset;
         let pageToken;
         do {
-            const page = materializeActiveContractsPage(await this.stateService.getActiveContractsPageAsync(mapGrpcQueryContractsRequest(parties === undefined
-                ? { allParties: true, activeAtOffset, pageToken }
-                : { parties, activeAtOffset, pageToken })));
+            const page = materializeActiveContractsPage(await this.stateService.getActiveContractsPageAsync({
+                ...baseRequest,
+                pageToken: pageToken === undefined ? undefined : Uint8Array.from(pageToken),
+            }));
             if (activeAtOffset === undefined) {
                 activeAtOffset = page.activeAtOffset;
             }