@distrohelena/canton-typescript-sdk 0.1.43 → 0.1.45

package/dist/query/grpc/grpc-query-client.d.ts

@@ -17,6 +17,12 @@ export interface GrpcQueryClientOptions {
     readonly packageService: Pick<PackageServiceClient, "listPackagesAsync" | "getPackageAsync">;
     readonly contractCache?: GrpcContractCache;
     readonly endpointScope?: string;
+    /**
+     * Opt-in: after the first history replay, keep the materialized window in memory and only fetch offsets
+     * past it on later history queries — turning repeat full replays into delta reads. Off by default because
+     * the retained window lives for this client's lifetime and its RAM cost is the full replayed history.
+     */
+    readonly incrementalHistory?: boolean;
 }
 export declare class GrpcQueryClient implements QueryClient {
     private readonly options;

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

@@ -5,9 +5,10 @@ import { createQueryDataset } from "../canonical/query-dataset.js";
 import { normalizeAggregate, normalizeCount, normalizeFindMany, normalizeFindUnique, normalizeGroupBy } from "../canonical/query-normalizer.js";
 import { queryRelationEdges, queryRelations } from "../canonical/query-schema.js";
 import { QuerySource } from "../query-source.js";
-import { contractTypeMetadataFromCreations, createGrpcQueryDataset, mapGrpcQueryRelationFragment, referencedGrpcPackageIds } from "./grpc-relation-mapper.js";
+import { contractTypeMetadataFromCreations, createGrpcQueryDataset, mapGrpcQueryRelationFragment, packageMetadataFromEvents, referencedGrpcPackageIds } from "./grpc-relation-mapper.js";
 import { GrpcPackageRelationReader } from "./grpc-package-relation-reader.js";
 import { GrpcQuerySnapshotReader } from "./grpc-query-snapshot-reader.js";
+import { validDottedNameString } from "./grpc-query-value-mapper.js";
 export class GrpcQueryClient {
     options;
     source = QuerySource.grpc;
@@ -62,7 +63,7 @@ class DefaultGrpcQueryDataProvider {
     packages;
     constructor(options) {
         this.options = options;
-        this.snapshots = new GrpcQuerySnapshotReader(options.stateService, options.updateService);
+        this.snapshots = new GrpcQuerySnapshotReader(options.stateService, options.updateService, { incrementalHistory: options.incrementalHistory });
         this.packages = new GrpcPackageRelationReader(options.packageService);
     }
     async readDatasetAsync(query) {
@@ -76,29 +77,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 = 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
+                    ? packageMetadataFromEvents(fragment)
+                    : contractTypeMetadataFromCreations(fragment.creationIdentities)
+                : undefined;
             const packageMetadata = !requiresPackageMetadata(closure)
                 ? []
-                : query.relation === "packages" || query.relation === "contractTypes" || query.relation === "exerciseTypes"
+                : catalogRelation
                     ? await this.packages.readAllAsync()
-                    : useCreationsOnlyMetadata
-                        ? contractTypeMetadataFromCreations(fragment.creationIdentities)
-                        : await this.packages.readPackagesAsync(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(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")
                 : createGrpcQueryDataset(datasetFragment, packageMetadata, endInclusive, this.options.endpointScope ?? "ledger");
@@ -116,7 +132,7 @@ class DefaultGrpcQueryDataProvider {
         else if (query.relation === "watermark") {
             return createGrpcQueryDataset(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 = mapGrpcQueryRelationFragment([], active.activeContracts);
         if (!requiresPackageMetadata(closure)) {
             return fragmentDataset(fragment, endInclusive, this.options.endpointScope ?? "ledger", false);
@@ -177,23 +193,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 {
+        validDottedNameString(ref.moduleName, "template filter module name");
+        validDottedNameString(ref.entityName, "template filter entity name");
+        return true;
+    }
+    catch {
+        return false;
+    }
 }
 function predicateRequiresHistory(relation, predicate) {
     if (predicate === undefined || predicate.kind === "scalar") {

package/dist/query/grpc/grpc-query-snapshot-reader.d.ts

@@ -2,6 +2,7 @@ import { StateServiceClient } from "../../services/state/state-service-client.js
 import { UpdateServiceClient } from "../../services/update/update-service-client.js";
 import { type GetActiveContractsResponse as GetActiveContractsResponseType } from "../../transports/grpc/generated/canton/com/daml/ledger/api/v2/state_service.js";
 import { type GetUpdateResponse as GetUpdateResponseType } from "../../transports/grpc/generated/canton/com/daml/ledger/api/v2/update_service.js";
+import { type GrpcQueryTemplateRef } from "../../transports/grpc/mappers/contracts-mapper.js";
 type StateSnapshotReader = Pick<StateServiceClient, "getLedgerEndAsync" | "getLatestPrunedOffsetsAsync" | "getActiveContractsPageAsync">;
 type UpdateSnapshotReader = Pick<UpdateServiceClient, "getUpdatesPageAsync">;
 export interface GrpcHistorySnapshot {
@@ -17,15 +18,25 @@ export interface GrpcQuerySnapshotReaderOptions {
     readonly maxHistoryUpdates?: number;
     readonly maxActiveContractPages?: number;
     readonly maxActiveContracts?: number;
+    /**
+     * Opt-in: retain the last replayed history window in memory and only fetch offsets past it on later
+     * reads. Off by default because the retained window lives for this reader's lifetime — its RAM cost is
+     * the full materialized history, bounded only by maxHistoryUpdates.
+     */
+    readonly incrementalHistory?: boolean;
 }
 export declare class GrpcQuerySnapshotReader {
     private readonly stateService;
     private readonly updateService;
     private readonly options;
+    private historyCache;
     constructor(stateService: StateSnapshotReader, updateService: UpdateSnapshotReader, options?: GrpcQuerySnapshotReaderOptions);
+    /** Whether an incremental history window is already held, meaning the next read only fetches new offsets. */
+    get hasHistoryCache(): boolean;
     readCurrentHistoryAsync(): Promise<GrpcHistorySnapshot>;
     readHistoryAsync(endInclusive: string): Promise<GrpcHistorySnapshot>;
-    readActiveContractsAsync(activeAtOffset: string, parties?: readonly string[]): Promise<GrpcActiveContractSnapshot>;
+    private readHistoryRangeAsync;
+    readActiveContractsAsync(activeAtOffset: string, parties?: readonly string[], templateRefs?: readonly GrpcQueryTemplateRef[]): Promise<GrpcActiveContractSnapshot>;
     private historyError;
     private activeError;
 }

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

@@ -5,7 +5,7 @@ import { TransactionShape } from "../../transports/grpc/generated/canton/com/dam
 import { mapGrpcQueryContractsRequest } from "../../transports/grpc/mappers/contracts-mapper.js";
 import { immutableQueryValue } from "../canonical/query-dataset.js";
 import { QuerySnapshotIncompleteError } from "../errors/query-snapshot-incomplete-error.js";
-const DEFAULT_OPTIONS = {
+const DEFAULT_LIMITS = {
     maxHistoryPages: 10_000,
     maxHistoryUpdates: 1_000_000,
     maxActiveContractPages: 10_000,
@@ -16,11 +16,16 @@ export 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);
@@ -28,26 +33,49 @@ export 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,
@@ -58,18 +86,18 @@ export 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;
             }
@@ -77,33 +105,36 @@ export 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() : mapGrpcQueryContractsRequest({ parties }).eventFormat);
+        const eventFormat = freezeDeep(mapGrpcQueryContractsRequest({
+            ...(parties === undefined ? { allParties: true } : { parties }),
+            ...(templateRefs === undefined || templateRefs.length === 0 ? {} : { templateRefs: [...templateRefs] }),
+        }).eventFormat);
         const activeContracts = [];
         const observedPageTokens = new Set();
         let pageToken;
@@ -148,9 +179,9 @@ export class GrpcQuerySnapshotReader {
             pageToken = Uint8Array.from(nextPageToken);
         }
     }
-    historyError(endInclusive, reason) {
+    historyError(beginExclusive, endInclusive, reason) {
         return new QuerySnapshotIncompleteError({
-            beginExclusive: LEDGER_BEGIN,
+            beginExclusive,
             endInclusive,
             reason,
         });
@@ -165,13 +196,17 @@ export class GrpcQuerySnapshotReader {
     }
 }
 function validateOptions(options) {
-    const validated = { ...DEFAULT_OPTIONS, ...options };
+    const { incrementalHistory = false, ...limits } = options;
+    if (typeof incrementalHistory !== "boolean") {
+        throw new 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 ValidationError(`${name} must be a finite positive integer.`);
         }
     }
-    return Object.freeze(validated);
+    return Object.freeze({ ...validated, incrementalHistory });
 }
 function createHistoryUpdateFormat() {
     return {

package/dist/query/grpc/grpc-relation-mapper.d.ts

@@ -11,6 +11,13 @@ export interface GrpcQueryTypeIdentity {
         entityName: string;
     }>;
     readonly packageId: string;
+    /**
+     * The owning package's name when the event states it reliably: always for contract types
+     * (CreatedEvent/ExercisedEvent packageName is the contract's package), and for choice types only on
+     * direct exercises — an interface-exercised choice is owned by the interface, whose package name the
+     * event does not carry.
+     */
+    readonly packageName?: string;
     readonly choice?: string;
     readonly consuming?: boolean;
 }
@@ -70,7 +77,16 @@ export declare function referencedGrpcPackageIds(fragment: GrpcQueryRelationFrag
  * 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.
  */
 export declare function contractTypeMetadataFromCreations(creationIdentities: readonly GrpcQueryCreationIdentity[]): readonly GrpcPackageMetadata[];
+/**
+ * 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).
+ */
+export declare function packageMetadataFromEvents(fragment: Pick<GrpcQueryRelationFragment, "creationIdentities" | "typeIdentities">): readonly GrpcPackageMetadata[] | undefined;