@distrohelena/canton-typescript-sdk 0.1.46 → 0.1.48

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

@@ -2,16 +2,18 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GrpcQueryClient = void 0;
 const validation_error_js_1 = require("../../core/errors/validation-error.js");
+const contract_cache_required_error_js_1 = require("../errors/contract-cache-required-error.js");
+const history_walk_required_error_js_1 = require("../errors/history-walk-required-error.js");
 const query_capability_error_js_1 = require("../errors/query-capability-error.js");
 const in_memory_query_evaluator_js_1 = require("../canonical/in-memory-query-evaluator.js");
 const query_dataset_js_1 = require("../canonical/query-dataset.js");
 const query_normalizer_js_1 = require("../canonical/query-normalizer.js");
 const query_schema_js_1 = require("../canonical/query-schema.js");
 const query_source_js_1 = require("../query-source.js");
+const public_identity_js_1 = require("../canonical/public-identity.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;
@@ -41,6 +43,9 @@ class GrpcQueryClient {
     async invalidateContractsCache(args) {
         await this.options.contractCache?.invalidateContractsCache(args);
     }
+    async inspectContractsCache(args) {
+        return this.options.contractCache?.inspectContractsCacheAsync(args);
+    }
     delegate(relation) {
         return {
             findMany: async (args = {}) => this.execute((0, query_normalizer_js_1.normalizeFindMany)(relation, args)),
@@ -65,6 +70,7 @@ class DefaultGrpcQueryDataProvider {
     options;
     snapshots;
     packages;
+    warnedReplayRelations = new Set();
     constructor(options) {
         this.options = options;
         this.snapshots = new grpc_query_snapshot_reader_js_1.GrpcQuerySnapshotReader(options.stateService, options.updateService, { incrementalHistory: options.incrementalHistory });
@@ -77,19 +83,27 @@ class DefaultGrpcQueryDataProvider {
         const cached = activeOnly && this.options.contractCache !== undefined
             ? await this.options.contractCache.readSnapshotAsync({ parties: partiesFor(query) })
             : undefined;
-        if (cached !== undefined && !needsHistory && !requiresPackageMetadata(closure)) {
-            return cachedContractsDataset(cached.contracts, cached.activeAtOffset, this.options.endpointScope ?? "ledger");
+        // The snapshot stores per-contract creation metadata, so contractTypes joins are served from cache
+        // too; only exercises/exerciseTypes/packages (whose rows the snapshot cannot answer) force a fetch.
+        if (cached !== undefined && !needsHistory && !closure.has("exercises") && !closure.has("exerciseTypes") && !closure.has("packages")) {
+            return cachedContractsDataset(cached, this.options.endpointScope ?? "ledger");
         }
         else if (needsHistory) {
-            // 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. `
+            if (this.options.walkHistory !== true) {
+                throw new history_walk_required_error_js_1.HistoryWalkRequiredError(query.relation);
+            }
+            // With a warm incremental window only the new offsets are fetched, which is no longer worth a
+            // warning; otherwise warn once per relation per client, not once per query.
+            if (!(this.options.incrementalHistory === true && this.snapshots.hasHistoryCache) && !this.warnedReplayRelations.has(query.relation)) {
+                this.warnedReplayRelations.add(query.relation);
+                (this.options.logger ?? 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."));
+                        : ", or enable the incrementalHistory option to fetch only new offsets on repeat history queries.")
+                    + ` This warning is logged once per relation; further "${query.relation}" replays stay silent.`);
             }
             const endInclusive = cached?.activeAtOffset ?? (await this.options.stateService.getLedgerEndAsync({})).offset;
             const history = await this.snapshots.readHistoryAsync(endInclusive);
@@ -123,33 +137,68 @@ class DefaultGrpcQueryDataProvider {
                 ? fragmentDataset(fragment, endInclusive, this.options.endpointScope ?? "ledger")
                 : (0, grpc_relation_mapper_js_1.createGrpcQueryDataset)(datasetFragment, packageMetadata, endInclusive, this.options.endpointScope ?? "ledger");
         }
-        const endInclusive = cached?.activeAtOffset ?? (await this.options.stateService.getLedgerEndAsync({})).offset;
         if (query.relation === "packages" || query.relation === "contractTypes" || query.relation === "exerciseTypes") {
             // A proven-active where/include on "contracts" (see predicateRequiresHistory/includesRequireHistory)
-            // can put "contracts" in the closure here without needsHistory being true, so the ACS still has to
-            // be read — otherwise that where/include would silently resolve against an empty row set.
-            const contractsFragment = closure.has("contracts")
-                ? (0, grpc_relation_mapper_js_1.mapGrpcQueryRelationFragment)([], (await this.snapshots.readActiveContractsAsync(endInclusive, partiesFor(query))).activeContracts)
-                : (0, grpc_relation_mapper_js_1.mapGrpcQueryRelationFragment)([]);
+            // can put "contracts" in the closure here without needsHistory being true. Those rows come from
+            // the warmed cache — the ACS is never downloaded implicitly.
+            const contractsSnapshot = closure.has("contracts") ? await this.requireCachedSnapshotAsync(query) : undefined;
+            const endInclusive = contractsSnapshot?.activeAtOffset ?? (await this.options.stateService.getLedgerEndAsync({})).offset;
+            const contractsFragment = contractsSnapshot === undefined
+                ? (0, grpc_relation_mapper_js_1.mapGrpcQueryRelationFragment)([])
+                : fragmentFromCachedSnapshot(contractsSnapshot);
             return (0, grpc_relation_mapper_js_1.createGrpcQueryDataset)(contractsFragment, await this.packages.readAllAsync(), endInclusive, this.options.endpointScope ?? "ledger");
         }
         else if (query.relation === "watermark") {
+            const endInclusive = (await this.options.stateService.getLedgerEndAsync({})).offset;
             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), 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);
+        // Only an active-only "contracts" query can reach here (anything else forces history above), and the
+        // cache gate has already failed — the ACS is never downloaded per query, so this is a hard error.
+        throw new contract_cache_required_error_js_1.ContractCacheRequiredError(partiesFor(query));
+    }
+    async requireCachedSnapshotAsync(query) {
+        const snapshot = this.options.contractCache === undefined
+            ? undefined
+            : await this.options.contractCache.readSnapshotAsync({ parties: partiesFor(query) });
+        if (snapshot === undefined) {
+            throw new contract_cache_required_error_js_1.ContractCacheRequiredError(partiesFor(query));
         }
-        // Reaching here guarantees query.relation === "contracts" with needsHistory === false, which (per
-        // predicateRequiresHistory/includesRequireHistory above) is only possible when the closure never
-        // touches "exercises"/"exerciseTypes"/"packages"/"transactions"/"events" — those unconditionally force
-        // history. So requiresPackageMetadata(closure) here can only be "contractTypes", and every contract in
-        // this ACS-only fragment already carries its own packageName — no Package Service call needed.
-        const packageMetadata = (0, grpc_relation_mapper_js_1.contractTypeMetadataFromCreations)(fragment.creationIdentities);
-        return (0, grpc_relation_mapper_js_1.createGrpcQueryDataset)(fragment, packageMetadata, endInclusive, this.options.endpointScope ?? "ledger");
+        return snapshot;
     }
 }
+/** Rebuilds an ACS-shaped relation fragment from a cached snapshot, with no transport involved. */
+function fragmentFromCachedSnapshot(snapshot) {
+    const metadataByContractId = new Map(snapshot.creationMetadata.map((entry) => [entry.contractId, entry]));
+    const creationIdentities = snapshot.contracts.map((row) => {
+        const metadata = metadataByContractId.get(row.contractId);
+        if (metadata === undefined) {
+            throw new validation_error_js_1.ValidationError(`Cached contract snapshot is missing creation metadata for ${row.contractId}`);
+        }
+        return {
+            contractId: row.contractId,
+            offset: row.createdEventOffset,
+            templateId: row.templateId,
+            creationPackageId: row.templateId.packageId,
+            representativePackageId: metadata.representativePackageId,
+            packageName: metadata.packageName,
+            payload: row.payload,
+            witnesses: row.witnesses,
+            createdAt: row.createdAt ?? new Date(0),
+        };
+    });
+    return {
+        contracts: snapshot.contracts,
+        transactions: [],
+        events: [],
+        exercises: [],
+        typeIdentities: [],
+        packageIdentities: [],
+        creationIdentities,
+        // Only the contract ids are consumed (they mark creating transactions as legitimately absent, so the
+        // createdTransaction edge is flagged incomplete instead of pretending to be empty).
+        activeContractIdentities: snapshot.contracts.map((row) => ({ contractId: row.contractId, synchronizerId: "", reassignmentCounter: "0", activationOffset: row.createdEventOffset, activationNodeId: 0 })),
+    };
+}
 function requiresHistory(query) {
     if (query.relation === "transactions" || query.relation === "events" || query.relation === "exercises") {
         return true;
@@ -197,110 +246,6 @@ 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;
-/**
- * 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 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") {
         return false;
@@ -381,9 +326,47 @@ function addRelationPath(relation, path, relations) {
         }
     }
 }
-function cachedContractsDataset(contracts, offset, instanceId) {
+/**
+ * Builds a dataset entirely from a cached snapshot: contract rows plus contractType rows derived from the
+ * stored per-contract creation metadata, joined through private keys. No transport calls. History-only
+ * edges stay incomplete so anything the snapshot cannot answer still fails loudly instead of lying.
+ */
+function cachedContractsDataset(snapshot, instanceId) {
+    const offset = snapshot.activeAtOffset;
+    const metadataByContractId = new Map(snapshot.creationMetadata.map((entry) => [entry.contractId, entry]));
+    const creations = snapshot.contracts.map((row) => {
+        const metadata = metadataByContractId.get(row.contractId);
+        if (metadata === undefined) {
+            throw new validation_error_js_1.ValidationError(`Cached contract snapshot is missing creation metadata for ${row.contractId}`);
+        }
+        return {
+            creationPackageId: row.templateId.packageId,
+            representativePackageId: metadata.representativePackageId,
+            packageName: metadata.packageName,
+            templateId: row.templateId,
+        };
+    });
+    const typeRowsByPk = new Map();
+    for (const pkg of (0, grpc_relation_mapper_js_1.contractTypeMetadataFromCreations)(creations)) {
+        for (const template of pkg.templates) {
+            const pk = (0, public_identity_js_1.canonicalPublicNumericIdentityParts)([template.payloadType, template.templateFqn]);
+            if (!typeRowsByPk.has(pk)) {
+                typeRowsByPk.set(pk, { pk, payloadType: template.payloadType, aliases: template.aliases, packageName: pkg.name, moduleName: template.moduleName, entityName: template.entityName, templateFqn: template.templateFqn });
+            }
+        }
+    }
+    const typeRows = [...typeRowsByPk.values()];
+    const contractTypeKeys = creations.map((creation) => [(0, public_identity_js_1.canonicalPublicNumericIdentityParts)(["template", `${creation.packageName}:${creation.templateId.moduleName}:${creation.templateId.entityName}`])]);
+    const typeKeys = typeRows.map((row) => [row.pk]);
     const empty = [];
-    return basicDataset({ contracts: contracts, transactions: empty, events: empty, exercises: empty }, offset, instanceId, false);
+    const edges = Object.fromEntries(query_schema_js_1.queryRelations.map((relation) => [relation, Object.fromEntries(Object.keys(query_schema_js_1.queryRelationEdges[relation] ?? {}).map((edge) => [edge, { ...cachedEdgePaths(relation, edge), complete: false }]))]));
+    edges.contracts.contractType = { privateKeys: { source: contractTypeKeys, target: typeKeys } };
+    edges.contractTypes.contracts = { privateKeys: { source: typeKeys, target: contractTypeKeys } };
+    return (0, query_dataset_js_1.createQueryDataset)({
+        rows: { contracts: snapshot.contracts, contractTypes: typeRows, events: empty, exercises: empty, exerciseTypes: empty, packages: empty, transactions: empty, watermark: [{ singleton: true, ix: offset, offset, instanceId }] },
+        uniqueKeys: { contracts: [["contractId"]], contractTypes: [["pk"]], events: [["pk"]], exercises: [["tpePk", "contractTpePk", "exerciseEventPk", "contractId"]], exerciseTypes: [["pk"]], packages: [["pk"], ["id"]], transactions: [["ix"], ["offset"]], watermark: [["singleton"]] },
+        edges: edges,
+    });
 }
 function fragmentDataset(fragment, offset, instanceId, completeHistoryEdges = true) {
     return basicDataset(fragment, offset, instanceId, completeHistoryEdges);

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

@@ -83,6 +83,7 @@ class GrpcQuerySnapshotReader {
                 endOffsetInclusive: endInclusive,
                 updateFormat,
                 descendingOrder: false,
+                maxPageSize: this.options.historyPageSize,
                 pageToken: pageToken === undefined ? undefined : Uint8Array.from(pageToken),
             };
             const response = await this.updateService.getUpdatesPageAsync(request);
@@ -150,6 +151,7 @@ class GrpcQuerySnapshotReader {
             const request = {
                 activeAtOffset,
                 eventFormat,
+                maxPageSize: this.options.activeContractPageSize,
                 pageToken: pageToken === undefined ? undefined : Uint8Array.from(pageToken),
             };
             const response = await this.stateService.getActiveContractsPageAsync(request);
@@ -201,17 +203,17 @@ class GrpcQuerySnapshotReader {
 }
 exports.GrpcQuerySnapshotReader = GrpcQuerySnapshotReader;
 function validateOptions(options) {
-    const { incrementalHistory = false, ...limits } = options;
+    const { incrementalHistory = false, historyPageSize, activeContractPageSize, ...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)) {
+    for (const [name, value] of Object.entries({ ...validated, ...(historyPageSize === undefined ? {} : { historyPageSize }), ...(activeContractPageSize === undefined ? {} : { activeContractPageSize }) })) {
         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, incrementalHistory });
+    return Object.freeze({ ...validated, historyPageSize, activeContractPageSize, incrementalHistory });
 }
 function createHistoryUpdateFormat() {
     return {

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

@@ -58,6 +58,9 @@ class PqsQueryClient {
         return { source: query_source_js_1.QuerySource.pqs, cached: false };
     }
     async invalidateContractsCache(_args) { }
+    async inspectContractsCache(_args) {
+        return undefined;
+    }
     createPhysicalDelegate(relation, hasUnique = true) {
         const queryRelation = queryRelationForPqs[relation];
         const delegate = {

package/dist/core/types/canton-logger.d.ts

@@ -0,0 +1,4 @@
+/** Minimal logging seam for SDK diagnostics; defaults to the global console when not provided. */
+export interface CantonLogger {
+    warn(message: string): void;
+}

package/dist/core/types/canton-logger.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -2,6 +2,9 @@ export { CantonClient } from "./client/canton-client.js";
 export { CantonManager } from "./query/canton-manager.js";
 export { QuerySource } from "./query/query-source.js";
 export { MemoryQueryCache } from "./query/cache/memory-query-cache.js";
+export type { CantonLogger } from "./core/types/canton-logger.js";
+export { ContractCacheRequiredError } from "./query/errors/contract-cache-required-error.js";
+export { HistoryWalkRequiredError } from "./query/errors/history-walk-required-error.js";
 export { QueryCapabilityError } from "./query/errors/query-capability-error.js";
 export { QuerySnapshotIncompleteError } from "./query/errors/query-snapshot-incomplete-error.js";
 export type { QuerySnapshotIncompleteReason } from "./query/errors/query-snapshot-incomplete-error.js";

package/dist/index.js

@@ -2,6 +2,8 @@ export { CantonClient } from "./client/canton-client.js";
 export { CantonManager } from "./query/canton-manager.js";
 export { QuerySource } from "./query/query-source.js";
 export { MemoryQueryCache } from "./query/cache/memory-query-cache.js";
+export { ContractCacheRequiredError } from "./query/errors/contract-cache-required-error.js";
+export { HistoryWalkRequiredError } from "./query/errors/history-walk-required-error.js";
 export { QueryCapabilityError } from "./query/errors/query-capability-error.js";
 export { QuerySnapshotIncompleteError } from "./query/errors/query-snapshot-incomplete-error.js";
 export { PqsQueryError } from "./query/errors/pqs-query-error.js";

package/dist/query/canton-manager-options.d.ts

@@ -1,4 +1,5 @@
 import { CantonClientOptions } from "../client/canton-client-options.js";
+import { CantonLogger } from "../core/types/canton-logger.js";
 import { QueryCacheStore } from "./cache/query-cache-store.js";
 import { QuerySource } from "./query-source.js";
 export interface PqsQueryOptions {
@@ -8,10 +9,35 @@ export interface PqsQueryOptions {
 export interface QueryCacheOptions {
     readonly store: QueryCacheStore;
     readonly ttlMs: number;
+    /** Per-request ACS page size for cache prewarms; omitted means the participant's default. */
+    readonly maxPageSize?: number;
+    /**
+     * BETA: opt into delta refresh. Re-warms with a warm (or expired) snapshot then try to patch it forward
+     * from the update stream instead of re-downloading the ACS. Any unprovable window — reassignments or
+     * topology changes, pruning past the snapshot, exceeded budgets — falls back to the full download
+     * automatically. Off by default: every re-warm performs the full ACS download.
+     */
+    readonly betaDeltaRefresh?: boolean;
+    /** Delta refresh only: skip the delta attempt when the ledger has run further than this past the snapshot. */
+    readonly maxDeltaOffsetGap?: number;
+    /** Delta refresh only: abandon the delta (fall back to full download) after this many applied updates. */
+    readonly maxDeltaUpdates?: number;
 }
 export interface CantonManagerOptions {
     readonly grpc: CantonClientOptions;
     readonly querySource: QuerySource;
     readonly pqs?: PqsQueryOptions;
     readonly cache?: QueryCacheOptions;
+    /**
+     * Opt-in for gRPC typed queries: keep the replayed history window in memory and fetch only new offsets
+     * on later history queries. Costs RAM for the manager's lifetime — see GrpcQueryClientOptions.
+     */
+    readonly incrementalHistory?: boolean;
+    /**
+     * Opt-in for gRPC typed queries: permit queries that replay ledger history. Off by default — such
+     * queries throw HistoryWalkRequiredError so the replay cost is never paid implicitly.
+     */
+    readonly walkHistory?: boolean;
+    /** Receives SDK diagnostics (e.g. the once-per-relation full-replay warning); defaults to console. */
+    readonly logger?: CantonLogger;
 }

package/dist/query/canton-manager.js

@@ -34,9 +34,12 @@ export class CantonManager {
                 updateService: this.grpc.updateService,
                 packageService: this.grpc.packageService,
                 endpointScope: options.grpc.ledgerEndpoint ?? "ledger",
+                incrementalHistory: options.incrementalHistory,
+                walkHistory: options.walkHistory,
+                logger: options.logger,
                 contractCache: options.cache === undefined
                     ? undefined
-                    : new GrpcContractCache(this.grpc.stateService, options.cache.store, options.cache.ttlMs, options.grpc.ledgerEndpoint ?? "ledger"),
+                    : new GrpcContractCache(this.grpc.stateService, options.cache.store, options.cache.ttlMs, options.grpc.ledgerEndpoint ?? "ledger", undefined, options.cache.maxPageSize, this.grpc.updateService, { enabled: options.cache.betaDeltaRefresh, maxOffsetGap: options.cache.maxDeltaOffsetGap, maxUpdates: options.cache.maxDeltaUpdates }),
             });
         }
     }

package/dist/query/errors/contract-cache-required-error.d.ts

@@ -0,0 +1,11 @@
+import { CantonError } from "../../core/errors/canton-error.js";
+/**
+ * gRPC typed queries never download the ACS implicitly: reading active contracts requires an explicitly
+ * warmed contract cache, so the (potentially very large) ACS transfer only ever happens when the caller
+ * asks for it via cacheContracts(). Thrown when an ACS-backed query runs without a warm entry for its
+ * party scope.
+ */
+export declare class ContractCacheRequiredError extends CantonError {
+    readonly parties?: readonly string[] | undefined;
+    constructor(parties?: readonly string[] | undefined);
+}

package/dist/query/errors/contract-cache-required-error.js

@@ -0,0 +1,17 @@
+import { CantonError } from "../../core/errors/canton-error.js";
+/**
+ * gRPC typed queries never download the ACS implicitly: reading active contracts requires an explicitly
+ * warmed contract cache, so the (potentially very large) ACS transfer only ever happens when the caller
+ * asks for it via cacheContracts(). Thrown when an ACS-backed query runs without a warm entry for its
+ * party scope.
+ */
+export class ContractCacheRequiredError extends CantonError {
+    parties;
+    constructor(parties) {
+        super("gRPC active-contract queries require a warmed contract cache. Configure the cache "
+            + "({ store, ttlMs }) and call cacheContracts("
+            + (parties === undefined ? "" : JSON.stringify({ parties }))
+            + ") before querying; the prewarm's party scope must match the query's.");
+        this.parties = parties;
+    }
+}

package/dist/query/errors/history-walk-required-error.d.ts

@@ -0,0 +1,10 @@
+import { CantonError } from "../../core/errors/canton-error.js";
+/**
+ * gRPC typed queries never replay ledger history implicitly: transactions/events/exercises queries — and
+ * contracts queries whose predicates or includes reach archived state — require the walkHistory option, so
+ * the (potentially very expensive) replay only ever happens when the caller asked for it.
+ */
+export declare class HistoryWalkRequiredError extends CantonError {
+    readonly relation: string;
+    constructor(relation: string);
+}

package/dist/query/errors/history-walk-required-error.js

@@ -0,0 +1,16 @@
+import { CantonError } from "../../core/errors/canton-error.js";
+/**
+ * gRPC typed queries never replay ledger history implicitly: transactions/events/exercises queries — and
+ * contracts queries whose predicates or includes reach archived state — require the walkHistory option, so
+ * the (potentially very expensive) replay only ever happens when the caller asked for it.
+ */
+export class HistoryWalkRequiredError extends CantonError {
+    relation;
+    constructor(relation) {
+        super(`The "${relation}" query requires replaying ledger history, which is disabled by default. `
+            + "Enable the walkHistory option to permit it (pair it with incrementalHistory so repeat "
+            + "queries fetch only new offsets), or reshape the query to active-only state served by the "
+            + "contract cache.");
+        this.relation = relation;
+    }
+}

package/dist/query/grpc/grpc-contract-cache.d.ts

@@ -1,12 +1,33 @@
 import { StateServiceClient } from "../../services/state/state-service-client.js";
+import { UpdateServiceClient } from "../../services/update/update-service-client.js";
 import { QueryCacheStore } from "../cache/query-cache-store.js";
 import { ContractRow } from "../model-types.js";
-import { ContractCacheArgs, ContractCacheResult } from "../query-client.js";
-type ActiveContractsReader = Pick<StateServiceClient, "getActiveContractsPageAsync">;
+import { ContractCacheArgs, ContractCacheInspection, ContractCacheResult } from "../query-client.js";
+type ActiveContractsReader = Pick<StateServiceClient, "getActiveContractsPageAsync"> & Partial<Pick<StateServiceClient, "getLedgerEndAsync" | "getLatestPrunedOffsetsAsync">>;
+type CacheUpdateReader = Pick<UpdateServiceClient, "getUpdatesPageAsync">;
+/** Budgets for patching a warm snapshot forward from the update stream instead of re-downloading the ACS. */
+export interface GrpcContractCacheDeltaOptions {
+    /**
+     * BETA: delta refresh is opt-in. When absent or false, every re-warm performs the full ACS download
+     * regardless of the other options here.
+     */
+    readonly enabled?: boolean;
+    /** Skip the delta attempt outright when the ledger has run further than this past the snapshot. */
+    readonly maxOffsetGap?: number;
+    /** Abandon the delta (fall back to a full download) after this many applied updates. */
+    readonly maxUpdates?: number;
+}
+/** Per-contract creation facts the contractType join needs; stored so cached reads never re-fetch the ACS. */
+export interface GrpcCachedCreationMetadata {
+    readonly contractId: string;
+    readonly packageName: string;
+    readonly representativePackageId: string | null;
+}
 /** Internal point-in-time active-contract cache lookup used by query planning. */
 export interface GrpcCachedContractSnapshot {
     readonly activeAtOffset: string;
     readonly contracts: readonly ContractRow[];
+    readonly creationMetadata: readonly GrpcCachedCreationMetadata[];
 }
 export declare class GrpcContractCache {
     private readonly stateService;
@@ -14,13 +35,29 @@ export declare class GrpcContractCache {
     private readonly ttlMs;
     private readonly endpointScope;
     private readonly now;
+    private readonly maxPageSize?;
+    private readonly updateService?;
+    private readonly delta;
     private readonly inflight;
-    constructor(stateService: ActiveContractsReader, store: QueryCacheStore, ttlMs: number, endpointScope: string, now?: () => number);
+    constructor(stateService: ActiveContractsReader, store: QueryCacheStore, ttlMs: number, endpointScope: string, now?: () => number, maxPageSize?: number | undefined, updateService?: CacheUpdateReader | undefined, delta?: GrpcContractCacheDeltaOptions);
     cacheContracts(args?: ContractCacheArgs): Promise<ContractCacheResult>;
     readContractsAsync(args?: ContractCacheArgs): Promise<readonly ContractRow[] | undefined>;
     readSnapshotAsync(args?: ContractCacheArgs): Promise<GrpcCachedContractSnapshot | undefined>;
     invalidateContractsCache(args?: ContractCacheArgs): Promise<void>;
+    /** Measures the cached snapshot against the current ledger end, without changing anything. */
+    inspectContractsCacheAsync(args?: ContractCacheArgs): Promise<ContractCacheInspection | undefined>;
     private populateAsync;
+    /**
+     * Patches the base snapshot forward from the update stream instead of re-downloading the ACS. Returns
+     * undefined — meaning "do the full download instead" — whenever correctness cannot be proven cheaply:
+     * pruning past the base offset, an offset gap or update count beyond the configured budgets, any
+     * reassignment or topology change in the window (multi-synchronizer moves cannot be patched safely), an
+     * exercised event where ACS_DELTA promises none, or an archive/create inconsistent with the base rows.
+     */
+    private tryDeltaRefreshAsync;
+    private readDeltaWindowAsync;
+    private writeSnapshotAsync;
+    private fullRefreshAsync;
     private clearInflight;
 }
 export declare function normalizeParties(args?: ContractCacheArgs): readonly string[] | undefined;