@distrohelena/canton-typescript-sdk 0.1.46 → 0.1.48

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

@@ -1,14 +1,16 @@
 import { ValidationError } from "../../core/errors/validation-error.js";
+import { ContractCacheRequiredError } from "../errors/contract-cache-required-error.js";
+import { HistoryWalkRequiredError } from "../errors/history-walk-required-error.js";
 import { QueryCapabilityError } from "../errors/query-capability-error.js";
 import { InMemoryQueryEvaluator } from "../canonical/in-memory-query-evaluator.js";
 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 { canonicalPublicNumericIdentityParts } from "../canonical/public-identity.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;
@@ -38,6 +40,9 @@ export 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(normalizeFindMany(relation, args)),
@@ -61,6 +66,7 @@ class DefaultGrpcQueryDataProvider {
     options;
     snapshots;
     packages;
+    warnedReplayRelations = new Set();
     constructor(options) {
         this.options = options;
         this.snapshots = new GrpcQuerySnapshotReader(options.stateService, options.updateService, { incrementalHistory: options.incrementalHistory });
@@ -73,19 +79,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 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);
@@ -119,33 +133,68 @@ class DefaultGrpcQueryDataProvider {
                 ? fragmentDataset(fragment, endInclusive, this.options.endpointScope ?? "ledger")
                 : 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")
-                ? mapGrpcQueryRelationFragment([], (await this.snapshots.readActiveContractsAsync(endInclusive, partiesFor(query))).activeContracts)
-                : 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
+                ? mapGrpcQueryRelationFragment([])
+                : fragmentFromCachedSnapshot(contractsSnapshot);
             return 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 createGrpcQueryDataset(mapGrpcQueryRelationFragment([]), [], endInclusive, this.options.endpointScope ?? "ledger");
         }
-        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);
+        // 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 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 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 = contractTypeMetadataFromCreations(fragment.creationIdentities);
-        return 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 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;
@@ -193,110 +242,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 {
-        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") {
         return false;
@@ -377,9 +322,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 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 contractTypeMetadataFromCreations(creations)) {
+        for (const template of pkg.templates) {
+            const pk = 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) => [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(queryRelations.map((relation) => [relation, Object.fromEntries(Object.keys(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 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/query/grpc/grpc-query-snapshot-reader.d.ts

@@ -18,6 +18,10 @@ export interface GrpcQuerySnapshotReaderOptions {
     readonly maxHistoryUpdates?: number;
     readonly maxActiveContractPages?: number;
     readonly maxActiveContracts?: number;
+    /** Per-request page size for history reads; omitted means the participant's default. */
+    readonly historyPageSize?: number;
+    /** Per-request page size for ACS reads; omitted means the participant's default. */
+    readonly activeContractPageSize?: 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

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

@@ -79,6 +79,7 @@ export 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);
@@ -146,6 +147,7 @@ export class GrpcQuerySnapshotReader {
             const request = {
                 activeAtOffset,
                 eventFormat,
+                maxPageSize: this.options.activeContractPageSize,
                 pageToken: pageToken === undefined ? undefined : Uint8Array.from(pageToken),
             };
             const response = await this.stateService.getActiveContractsPageAsync(request);
@@ -196,17 +198,17 @@ export class GrpcQuerySnapshotReader {
     }
 }
 function validateOptions(options) {
-    const { incrementalHistory = false, ...limits } = options;
+    const { incrementalHistory = false, historyPageSize, activeContractPageSize, ...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)) {
+    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 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/query/grpc/grpc-relation-mapper.d.ts

@@ -73,6 +73,8 @@ export declare function mapGrpcQueryRelationFragment(source: readonly Transactio
 export declare function createGrpcQueryDataset(fragment: GrpcQueryRelationFragment, packages: readonly GrpcPackageMetadata[], endInclusive: string, instanceId: string): QueryDataset;
 /** Package payloads required for a contract/history relation plan, excluding creation-only provenance. */
 export declare function referencedGrpcPackageIds(fragment: GrpcQueryRelationFragment): readonly string[];
+/** The minimal creation facts needed to derive a contract's type metadata without decoding its package. */
+export type GrpcCreationTypeSource = Pick<GrpcQueryCreationIdentity, "creationPackageId" | "representativePackageId" | "packageName" | "templateId">;
 /**
  * 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
@@ -80,7 +82,7 @@ export declare function referencedGrpcPackageIds(fragment: GrpcQueryRelationFrag
  * 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[];
+export declare function contractTypeMetadataFromCreations(creationIdentities: readonly GrpcCreationTypeSource[]): 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

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

@@ -1,5 +1,5 @@
 import { ContractCountArgs, ContractFindManyArgs, ContractFindUniqueArgs, ContractGroupByArgs, JsonProjectionResult } from "../model-types.js";
-import { ContractCacheArgs, ContractCacheResult, QueryClient } from "../query-client.js";
+import { ContractCacheArgs, ContractCacheInspection, ContractCacheResult, QueryClient } from "../query-client.js";
 import { QuerySource } from "../query-source.js";
 import { PqsSchemaProfileV1 } from "./pqs-schema-profile.js";
 export interface PqsQueryExecutor {
@@ -35,6 +35,7 @@ export declare class PqsQueryClient implements QueryClient {
     $queryRaw<TRow>(sql: string, values?: readonly unknown[]): Promise<readonly TRow[]>;
     cacheContracts(_args?: ContractCacheArgs): Promise<ContractCacheResult>;
     invalidateContractsCache(_args?: ContractCacheArgs): Promise<void>;
+    inspectContractsCache(_args?: ContractCacheArgs): Promise<ContractCacheInspection | undefined>;
     private createPhysicalDelegate;
     private readPhysicalAsync;
     private countPhysicalAsync;

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

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

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

@@ -18,10 +18,28 @@ export type ContractCacheResult = {
     readonly activeAtOffset: string;
     readonly contractCount: number;
     readonly expiresAt: Date;
+    /**
+     * How this prewarm was satisfied: "full" downloaded the ACS, "delta" patched the previous snapshot
+     * forward from the update stream, "noop" found the ledger unchanged and only re-stamped the TTL.
+     */
+    readonly refresh: "full" | "delta" | "noop";
+    /** Ledger-end minus the previous snapshot's offset at refresh time; undefined on a cold prewarm. */
+    readonly offsetGap?: string;
+    /** Update count applied by a "delta" refresh. */
+    readonly deltaUpdateCount?: number;
 } | {
     readonly source: QuerySource.pqs;
     readonly cached: false;
 };
+/** Measurement of a cached ACS snapshot against the current ledger end, for deciding when to re-warm. */
+export interface ContractCacheInspection {
+    readonly activeAtOffset: string;
+    readonly ledgerEndOffset: string;
+    /** ledgerEndOffset - activeAtOffset: how far the ledger has run past the snapshot. */
+    readonly offsetGap: string;
+    readonly contractCount: number;
+    readonly expiresAt: Date;
+}
 export interface QueryDelegate<TRow, TWhere, TSelect, TOrderBy, TUnique, TInclude = never, TGroupBy = never, TGroupRow = never> {
     findMany<TArgs extends FindManyArgs<TWhere, TSelect, TOrderBy, TInclude>>(args?: TArgs): Promise<readonly (TRow & JsonProjectionResult<TArgs>)[]>;
     findUnique<TArgs extends {
@@ -52,6 +70,8 @@ export interface QueryClient {
     $queryRaw<TRow>(sql: string, values?: readonly unknown[]): Promise<readonly TRow[]>;
     cacheContracts(args?: ContractCacheArgs): Promise<ContractCacheResult>;
     invalidateContractsCache(args?: ContractCacheArgs): Promise<void>;
+    /** Measures a warmed snapshot against the current ledger end (undefined when cold or not cache-backed). */
+    inspectContractsCache(args?: ContractCacheArgs): Promise<ContractCacheInspection | undefined>;
     readonly contracts: {
         findMany<TArgs extends ContractFindManyArgs>(args?: TArgs): Promise<readonly (ContractResult & JsonProjectionResult<TArgs>)[]>;
         findUnique<TArgs extends ContractFindUniqueArgs>(args: TArgs): Promise<(ContractResult & JsonProjectionResult<TArgs>) | undefined>;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@distrohelena/canton-typescript-sdk",
-    "version": "0.1.46",
+    "version": "0.1.48",
     "license": "Apache-2.0",
     "type": "module",
     "main": "./dist/index.js",