@laserdata/laser-sdk 0.5.0 → 0.5.2

package/dist/managed/filters.js

@@ -1,4 +1,3 @@
-import { requireCapability } from "../client/capabilities.js";
 import { resultCodeIsRetryable } from "../wire/result.js";
 import { jsonCodec } from "../stream/codecs.js";
 import { decodeBrowseReply, encodeGetSchema } from "../wire/browse.js";
@@ -9,10 +8,9 @@ import { decodePolledBody, serverErrorCode } from "../iggy/apache-iggy.js";
 import { mintUlidValue } from "../runtime/ulid.js";
 import { decodeOne, encodeNamed } from "../wire/cbor.js";
 import { AGDX_FILTERED_ACK_CODE, AGDX_FILTERED_POLL_CODE, FILTER_OP_VERSION } from "../wire/codes.js";
-import { FilterMutateCommand, FilterOperationCommand, FilterPreviewCommand, FilterTestCommand, FilterValidateCommand, GetFilterBindingCommand, GetFilterCommand, ListFilterBindingsCommand, ListFilterRevisionsCommand, ListFiltersCommand } from "../wire/commands.js";
+import { FilterMutateCommand, FilterOperationCommand, FilterPreviewCommand, FilterTestCommand, GetFilterBindingCommand, ListFilterBindingsCommand, ListFilterRevisionsCommand, ListFiltersCommand } from "../wire/commands.js";
 import { CompiledFilter, usesRegex } from "../wire/filter-eval.js";
-import { consumerFilterDigest, decodeFilterReply, encodeFilteredAck, encodeFilteredPollRequest, nextFilteredStart, validateCatalogPage, validateConsumerFilter, validateFilterGroupRef, validateFilterMutationRequest, validateFilterPreviewRequest, validateFilterTestRequest, validateFilteredPollRequest } from "../wire/filter.js";
-import { filterAnnounceEvaluates } from "../wire/hello.js";
+import { decodeFilterReply, encodeFilteredAck, encodeFilteredPollRequest, nextFilteredStart, validateCatalogPage, validateFilterGroupRef, validateFilterMutationRequest, validateFilterPreviewRequest, validateFilterTestRequest, validateFilteredPollRequest } from "../wire/filter.js";
 import { MAX_FILTER_CATALOG_PAGE, MAX_FILTER_PARSE_DEPTH, MAX_FILTER_PREVIEW_EXAMINED, MAX_FILTERED_PAGE_BYTES } from "../wire/limits.js";
 const DEFAULT_COUNT = 100;
 const DEFAULT_MAX_REPLY_BYTES = 1024 * 1024;
@@ -29,6 +27,7 @@ const OUTCOME_POLL_INTERVAL_MS = 100;
 export const DEFAULT_OUTCOME_WAIT_MS = 30_000;
 const GET_STREAM_CODE = 200;
 const GET_TOPIC_CODE = 300;
+const GET_CONSUMER_GROUP_CODE = 600;
 const ATTACH_CONSUMER_SESSION_CODE = 14;
 const SYNC_CONSUMER_GROUP_CODE = 606;
 const GET_CONSUMER_OFFSET_ROUTING_CODE = 123;
@@ -51,9 +50,9 @@ const UTF8 = new TextEncoder();
  */
 export const READER_TAG = Symbol("laser.filters.reader");
 /**
- * Server-side consumer filters: filtered readers, previews, sample tests, and
- * the saved-filter catalog. Build it with `Laser.filters()`. Native reads need
- * a server that serves consumer filters. The catalog also needs a managed
+ * The catalog and native filter commands behind a consumer group's filter
+ * handle, reached through `ConsumerGroup.filter()`. Native commands need a
+ * server that serves consumer filters. The catalog also needs a managed
  * plane. Either missing throws `UnsupportedError`.
  */
 export class Filters {
@@ -63,17 +62,10 @@ export class Filters {
         this.transport = transport;
         this.capabilities = capabilities;
     }
-    /** A filtered reader over `stream` / `topic`. */
-    reader(stream, topic) {
-        return new FilteredReaderBuilder(this.transport, this.capabilities, this, { stream, topic });
-    }
-    /** Validate and compile `filter` on the server without running it. */
-    async validate(filter) {
-        validateConsumerFilter(filter);
-        const outcome = await this.native(FilterValidateCommand, filter);
-        if (outcome.kind === "validated")
-            return outcome.validation;
-        throw unexpected("validate");
+    /** Throws `UnsupportedError` unless the group filter catalog is served. */
+    async requireCatalog() {
+        const capabilities = await this.capabilities();
+        requireManagedCommand(capabilities, FilterMutateCommand);
     }
     /** Evaluate a filter against one supplied record and explain the verdict. */
     async test(filter, payload, headers = []) {
@@ -107,42 +99,49 @@ export class Filters {
             return outcome.preview;
         throw unexpected("preview");
     }
-    /** One saved filter with its latest revision and bindings. */
-    async get(filterId) {
-        const outcome = await this.catalog(GetFilterCommand, { v: FILTER_OP_VERSION, filterId });
-        if (outcome.kind === "filter")
-            return outcome.detail;
-        throw unexpected("get");
-    }
-    /** One page of saved filters, newest first. */
-    async list(options = {}) {
+    /** One page of a filter's revisions, newest first. */
+    async revisions(filterId, options = {}) {
         const request = {
             v: FILTER_OP_VERSION,
-            ...(options.nameContains !== undefined ? { nameContains: options.nameContains } : {}),
-            ...(options.state !== undefined ? { state: options.state } : {}),
-            ...(options.beforeId !== undefined ? { beforeId: options.beforeId } : {}),
+            filterId,
             page: options.page ?? 0,
             pageSize: options.pageSize ?? DEFAULT_PAGE_SIZE
         };
         validateCatalogPage(request.page, request.pageSize);
-        const outcome = await this.catalog(ListFiltersCommand, request);
-        if (outcome.kind === "filters")
+        const outcome = await this.catalog(ListFilterRevisionsCommand, request);
+        if (outcome.kind === "revisions")
             return outcome.page;
-        throw unexpected("list");
+        throw unexpected("revisions");
     }
-    /** One page of a filter's revisions, newest first. */
-    async revisions(filterId, options = {}) {
+    /**
+     * One page of saved filters whose name contains `nameContains`, newest first.
+     *
+     * @internal
+     */
+    async list(nameContains, options = {}, beforeId) {
         const request = {
             v: FILTER_OP_VERSION,
-            filterId,
+            nameContains,
+            ...(beforeId !== undefined ? { beforeId } : {}),
             page: options.page ?? 0,
             pageSize: options.pageSize ?? DEFAULT_PAGE_SIZE
         };
         validateCatalogPage(request.page, request.pageSize);
-        const outcome = await this.catalog(ListFilterRevisionsCommand, request);
-        if (outcome.kind === "revisions")
+        const outcome = await this.catalog(ListFiltersCommand, request);
+        if (outcome.kind === "filters")
             return outcome.page;
-        throw unexpected("revisions");
+        throw unexpected("filters");
+    }
+    /**
+     * Drop a saved filter. The catalog releases every group bound to it.
+     *
+     * @internal
+     */
+    async dropFilter(filterId) {
+        const applied = await this.apply({ kind: "drop", filterId });
+        if (applied.result.kind === "dropped")
+            return applied.catalogPosition;
+        throw unexpected("drop");
     }
     /** The binding of one consumer group. Throws with reason `not_found` when it is unbound. */
     async binding(group) {
@@ -175,119 +174,80 @@ export class Filters {
             operationId
         });
         if (outcome.kind === "mutation")
-            return outcome.outcome;
+            return checkedMutationOutcome(operationId, outcome.outcome);
         throw unexpected("operation");
     }
-    /** Save a new filter as revision 1. */
-    async register(name, filter, options = {}) {
-        const result = await this.apply({
-            kind: "register",
-            name,
-            description: options.description ?? "",
-            filter
-        });
-        if (result.kind === "registered")
-            return result.revision;
-        throw unexpected("register");
-    }
     /** Add a revision. `expectedRevision` must still be the latest one. */
     async revise(filterId, expectedRevision, filter) {
-        const result = await this.apply({ kind: "revise", filterId, expectedRevision, filter });
-        if (result.kind === "revised")
-            return result.revision;
+        const applied = await this.apply({ kind: "revise", filterId, expectedRevision, filter });
+        if (applied.result.kind === "revised")
+            return applied.result.revision;
         throw unexpected("revise");
     }
-    /** Replace a filter's description. */
-    async describe(filterId, description) {
-        await this.apply({ kind: "describe", filterId, description });
-    }
-    /** Hide a filter from new bindings. Existing bindings keep executing. */
-    async archive(filterId) {
-        await this.apply({ kind: "archive", filterId });
-    }
-    /** Delete a filter. Throws with reason `conflict` while a consumer group is bound to it. */
-    async delete(filterId) {
-        await this.apply({ kind: "drop", filterId });
-    }
-    /** Pin an existing consumer group to one revision. */
-    async bind(group, filterId, revision) {
-        const result = await this.apply({ kind: "bind", group, filterId, revision });
-        if (result.kind === "bound")
-            return result.binding;
-        throw unexpected("bind");
-    }
-    /** Release a consumer group while it is still bound to `expectedDigest`. */
-    async unbind(group, expectedDigest) {
-        const result = await this.apply({ kind: "unbind", group, expectedDigest });
-        if (result.kind === "unbound")
-            return result.binding;
-        throw unexpected("unbind");
+    /** Pause or resume a revision without changing its executable content or digest. */
+    async setRevisionEnabled(filterId, revision, enabled) {
+        await this.apply({ kind: "set_revision_enabled", filterId, revision, enabled });
     }
-    /** Release this exact saved binding, even after its group name was reused. */
-    async unbindBinding(binding) {
-        const result = await this.apply({
+    /**
+     * Give `group` its policy in one catalog transaction: a definition saved as
+     * the group's own filter, or one of its existing revisions. A repeat with
+     * the same digest keeps the binding, another digest conflicts. The returned
+     * position is where the fold applied it, carried by the group's reads so
+     * they never see this configuration as absent.
+     */
+    async configureGroup(group, policy, operationId = mintUlidValue(), expectedIdentity) {
+        const identity = expectedIdentity ?? (await nativeGroup(this.transport, group, group.group)).identity;
+        const applied = await this.apply({ kind: "configure_group", group, policy, expectedIdentity: identity }, operationId);
+        if (applied.result.kind === "bound")
+            return bound(applied.result.binding, applied);
+        throw unexpected("configure_group");
+    }
+    /**
+     * Release this exact saved binding, including a group incarnation that was
+     * deleted and recreated under the same name.
+     */
+    async releaseGroup(binding) {
+        const applied = await this.apply({
             kind: "unbind",
             group: binding.group,
             expectedDigest: binding.digest,
             expectedIdentity: binding.identity
         });
-        if (result.kind === "unbound")
-            return result.binding;
+        if (applied.result.kind === "unbound")
+            return bound(applied.result.binding, applied);
         throw unexpected("unbind");
     }
-    /**
-     * Submit a mutation under a new operation id and wait for its authoritative
-     * outcome. A lost reply is retried under the same id, which the catalog
-     * answers with the first attempt's outcome. A rejection throws
-     * `FilterExecutionError`. An outcome still pending after
-     * {@link DEFAULT_OUTCOME_WAIT_MS} throws `AmbiguousMutationError` naming the
-     * operation id.
-     */
-    async apply(mutation) {
-        return this.applyAs(mintUlidValue(), mutation);
-    }
-    /**
-     * {@link Filters.apply} under a caller-chosen `operationId`, so a caller that
-     * records the id first can resume the same mutation after a crash.
-     */
-    async applyAs(operationId, mutation) {
-        const outcome = await this.submit(operationId, mutation);
-        if (outcome.status.kind === "pending") {
-            return this.waitForOutcome(operationId, DEFAULT_OUTCOME_WAIT_MS);
-        }
-        return settled(operationId, outcome.status);
-    }
-    /** Create the group if absent, then bind it. A failed bind can leave an unbound group. */
-    async createConsumerGroup(group, filterId, revision) {
-        const capabilities = await this.capabilities();
-        requireCapability(capabilities, "filters");
-        requireManagedCommand(capabilities, FilterMutateCommand);
-        if (this.transport.ensureConsumerGroup === undefined)
-            throw new ConfigError("this transport cannot create consumer groups");
-        await this.transport.ensureConsumerGroup(group.stream, group.topic, group.group);
-        return this.bind(group, filterId, revision);
-    }
-    /** Pause or resume a revision without changing its executable content or digest. */
-    async setRevisionEnabled(filterId, revision, enabled) {
-        await this.apply({ kind: "set_revision_enabled", filterId, revision, enabled });
-    }
     /** Send one mutation under a caller-chosen `operationId`. The outcome may be pending. */
     async mutate(operationId, mutation) {
         const request = { v: FILTER_OP_VERSION, operationId, mutation };
         validateFilterMutationRequest(request);
         const outcome = await this.catalog(FilterMutateCommand, request);
         if (outcome.kind === "mutation")
-            return outcome.outcome;
+            return checkedMutationOutcome(operationId, outcome.outcome);
         throw unexpected("mutate");
     }
-    /** Wait for the outcome of `operationId` for at most `timeoutMs`. */
+    // Submit a mutation and wait for its authoritative outcome. A lost reply is
+    // retried under the same id, which the catalog answers with the first
+    // attempt's outcome. A rejection throws `FilterExecutionError`. An outcome
+    // still pending after `DEFAULT_OUTCOME_WAIT_MS` throws
+    // `AmbiguousMutationError` naming the operation id.
+    async apply(mutation, operationId = mintUlidValue()) {
+        const submitted = await this.submit(operationId, mutation);
+        const outcome = submitted.status.kind === "pending"
+            ? await this.waitForOutcome(operationId, DEFAULT_OUTCOME_WAIT_MS)
+            : submitted;
+        return {
+            result: settled(operationId, outcome.status),
+            ...(outcome.catalogPosition !== undefined ? { catalogPosition: outcome.catalogPosition } : {})
+        };
+    }
     async waitForOutcome(operationId, timeoutMs) {
         const deadline = Date.now() + timeoutMs;
         for (;;) {
             try {
                 const outcome = await this.operation(operationId);
                 if (outcome.status.kind !== "pending")
-                    return settled(operationId, outcome.status);
+                    return outcome;
             }
             catch (error) {
                 if (!isNotYetApplied(error))
@@ -327,76 +287,55 @@ export class Filters {
         throw filterError(reply.error);
     }
 }
-/** Builds a {@link FilteredReader}. Start from `Filters.reader`. */
+function checkedMutationOutcome(operationId, outcome) {
+    if (outcome.v !== FILTER_OP_VERSION ||
+        outcome.operationId !== operationId ||
+        (outcome.catalogPosition?.operationId !== undefined &&
+            outcome.catalogPosition.operationId !== operationId)) {
+        throw new ProtocolError("filter mutation outcome does not match the requested operation");
+    }
+    return outcome;
+}
+function bound(binding, applied) {
+    return {
+        binding,
+        ...(applied.catalogPosition !== undefined ? { catalogPosition: applied.catalogPosition } : {})
+    };
+}
+/** Builds a {@link FilteredReader} over one consumer group. Start from `ConsumerGroup.reader()`. */
 export class FilteredReaderBuilder {
     transport;
     capabilities;
     filters;
     source;
-    consumerName;
-    partitionIds = [];
-    filterRef;
+    consumer;
+    filter;
+    minCatalogPosition;
     startAt = { kind: "next" };
     pageCount = DEFAULT_COUNT;
+    examinedBudget;
     replyBytes = DEFAULT_MAX_REPLY_BYTES;
     mode = "primary";
     guarded = false;
     idleMs = DEFAULT_IDLE_INTERVAL_MS;
     maxUnacked = DEFAULT_MAX_UNACKED_PAGES;
-    constructor(transport, capabilities, filters, source) {
+    selectedPartitions = new Set();
+    constructor(transport, capabilities, filters, source, consumer, filter, minCatalogPosition) {
         this.transport = transport;
         this.capabilities = capabilities;
         this.filters = filters;
         this.source = source;
+        this.consumer = consumer;
+        this.filter = filter;
+        this.minCatalogPosition = minCatalogPosition;
     }
-    /** Read as the independent consumer `name`. */
-    consumer(name) {
-        this.consumerName = { kind: "consumer", name };
-        return this;
-    }
-    /**
-     * Read as a member of the existing consumer group `name`. A reader built
-     * from a connection string joins over its own connection, so every reader
-     * is its own member.
-     */
-    group(name) {
-        this.consumerName = { kind: "group", name };
-        return this;
-    }
-    /** Read the existing group by its native numeric identity. */
-    groupId(id) {
-        if (typeof id === "number" && !Number.isSafeInteger(id))
-            throw new InvalidError("consumer group id must be an integer");
-        const value = BigInt(id);
-        if (value < 0n || value > 0xffffffffn)
-            throw new InvalidError("consumer group id exceeds 32 bits");
-        this.consumerName = { kind: "group_id", id: value };
-        return this;
-    }
-    /**
-     * Read only `partitionId`. Repeat for more. An independent consumer reads
-     * every partition when none is named, including partitions added later.
-     */
-    partition(partitionId) {
-        this.partitionIds.push(partitionId);
-        return this;
-    }
-    /** Which filter runs. A group defaults to its bound revision. */
-    filter(filter) {
-        this.filterRef = filter;
-        return this;
-    }
-    /** Run `filter` from the request. Needs no catalog. */
-    inline(filter) {
-        return this.filter({ kind: "inline", filter });
-    }
-    /** Run a saved revision. */
-    revision(filterId, revision) {
-        return this.filter({ kind: "revision", filterId, revision });
+    /** @internal */
+    static create(transport, capabilities, filters, source, consumer, filter, minCatalogPosition) {
+        return new FilteredReaderBuilder(transport, capabilities, filters, source, consumer, filter, minCatalogPosition);
     }
     /**
      * Where each partition read at the build starts. Defaults to after the
-     * stored offset. A partition a group hands this reader later always resumes
+     * stored offset. A partition the group hands this reader later always resumes
      * after the group's stored offset, so the previous owner's unacknowledged
      * backlog is read, not skipped.
      */
@@ -404,11 +343,29 @@ export class FilteredReaderBuilder {
         this.startAt = start;
         return this;
     }
+    /** Read this partition only while the group assigns it to this member. Repeat for several. */
+    partition(partitionId) {
+        if (!Number.isSafeInteger(partitionId) || partitionId < 0 || partitionId > 0xffff_ffff) {
+            throw new InvalidError("partition must be an unsigned 32-bit integer");
+        }
+        this.selectedPartitions.add(partitionId);
+        return this;
+    }
     /** Most matching records per page. */
     count(count) {
         this.pageCount = count;
         return this;
     }
+    /**
+     * Most source records one page examines, independent of `count`. Without it
+     * the server's own budget bounds the scan. A page that examines its budget
+     * without a match returns empty and the reader continues from where it
+     * stopped.
+     */
+    maxExamined(records) {
+        this.examinedBudget = records;
+        return this;
+    }
     /** Most record bytes per page. The server may lower it. */
     maxReplyBytes(bytes) {
         this.replyBytes = bytes;
@@ -447,92 +404,67 @@ export class FilteredReaderBuilder {
     }
     async build() {
         const capabilities = await this.capabilities();
-        if (!capabilities.filters.native) {
-            throw new UnsupportedError("consumer filters are not served by this server");
+        if (this.filter.kind === "group" && !capabilities.filters.groupPolicyReads) {
+            throw new UnsupportedError("this server serves consumer filters but not group-aware reads, upgrade it before reading groups through the Laser SDK");
         }
-        const evaluation = capabilities.filters.evaluation;
-        if (this.filterRef?.kind === "inline" &&
-            evaluation !== undefined &&
-            !filterAnnounceEvaluates(evaluation, this.filterRef.filter.evaluatorVersion, this.filterRef.filter.codec)) {
-            throw new UnsupportedError(`this server does not evaluate ${this.filterRef.filter.codec} filters of evaluator version ${String(this.filterRef.filter.evaluatorVersion)}`);
+        if (this.filter.kind !== "group" && !capabilities.filters.native) {
+            throw new UnsupportedError("consumer filters are not served by this server");
         }
         if (this.mode === "primary" && this.transport.connectsNodes !== true) {
-            throw new ConfigError("primary filtered reads open data connections, so they need a Laser connected from a connection string. Read in local mode for an injected client");
-        }
-        const consumer = this.consumerName;
-        if (consumer === undefined) {
-            throw new ConfigError("a filtered reader needs .consumer(name), .group(name), or .groupId(id)");
-        }
-        const filter = this.filterRef ?? (consumer.kind !== "consumer" ? { kind: "bound" } : undefined);
-        if (filter === undefined) {
-            throw new ConfigError("an independent filtered reader needs .inline(..), .revision(..), or .filter(..)");
+            throw new ConfigError("primary group reads open data connections, so they need a Laser connected from a connection string. Read in local mode for an injected client");
         }
+        const consumer = this.consumer;
         const request = {
             v: FILTER_OP_VERSION,
             source: this.source,
             partitionId: 0,
             consumer,
-            filter,
+            filter: this.filter,
             start: this.startAt,
             count: this.pageCount,
             maxReplyBytes: this.replyBytes,
-            readMode: this.mode
+            readMode: this.mode,
+            ...(this.examinedBudget !== undefined ? { maxExamined: this.examinedBudget } : {}),
+            ...(this.minCatalogPosition !== undefined
+                ? { minCatalogPosition: this.minCatalogPosition }
+                : {})
         };
         validateFilteredPollRequest(request);
-        const guard = this.guarded && filter.kind !== "bound"
-            ? await compileGuard(this.transport, await definition(this.filters, filter))
-            : undefined;
-        if (consumer.kind !== "consumer" && this.partitionIds.length > 0) {
-            throw new ConfigError("a group reader reads the partitions the group assigns it");
-        }
         const pinnedSource = consumer.kind === "group_id"
             ? await sourceIncarnation(this.transport, this.source)
             : undefined;
-        const coordinator = consumer.kind !== "consumer" &&
-            this.transport.connectsNodes === true &&
-            this.transport.openCoordinator !== undefined
+        // A group reader owns the connection that holds its membership, so two
+        // readers are two members. An injected client has only the shared one.
+        const coordinator = this.transport.connectsNodes === true && this.transport.openCoordinator !== undefined
             ? await this.transport.openCoordinator()
             : sharedCoordinator(this.transport);
         let membership;
-        let partitionIds;
-        let discovers = false;
         try {
-            if (consumer.kind !== "consumer") {
-                membership = await Membership.join(coordinator, this.source, consumer.kind === "group_id" ? Number(consumer.id) : consumer.name, this.transport, pinnedSource);
-                partitionIds = membership.partitions;
-            }
-            else if (this.partitionIds.length > 0) {
-                partitionIds = this.partitionIds;
-            }
-            else {
-                partitionIds = await topicPartitions(this.transport, this.source);
-                discovers = true;
-            }
+            membership = await Membership.join(coordinator, this.source, consumer.kind === "group_id" ? Number(consumer.id) : consumer.name, this.transport, pinnedSource);
         }
         catch (error) {
             await coordinator.close();
             throw error;
         }
-        return new FilteredReader({
+        return FilteredReader.create({
             transport: this.transport,
             ...(pinnedSource === undefined ? {} : { pinnedSource }),
             filters: this.filters,
             coordinator,
             request,
-            inlineDigest: filter.kind === "inline" ? consumerFilterDigest(filter.filter) : undefined,
             start: this.startAt,
             idleIntervalMs: this.idleMs,
             maxUnackedPages: this.maxUnacked,
-            guard,
+            guard: undefined,
             guardEnabled: this.guarded,
             membership,
-            discovers,
-            partitionIds
+            selectedPartitions: new Set(this.selectedPartitions),
+            partitionIds: membership.partitions.filter((partition) => this.selectedPartitions.size === 0 || this.selectedPartitions.has(partition))
         });
     }
 }
 /**
- * Reads only the records a consumer filter selects, with their original
+ * Reads the records a consumer group's policy selects, with their original
  * offsets, and stores progress through fenced acknowledgments. Pages are read
  * ahead of acknowledgments, and a page's safe offset is stored only after it
  * and every earlier page of the partition are fully handled. Pages that
@@ -554,7 +486,6 @@ export class FilteredReader {
     sequence = 0;
     owner = {};
     retiredOwners = new WeakSet();
-    listedAt;
     closed = false;
     deferredError;
     pinnedSource;
@@ -565,11 +496,14 @@ export class FilteredReader {
         this.routes = new Routes(settings.transport, settings.coordinator);
         this.guard = settings.guard;
         this.pinnedSource = settings.pinnedSource;
-        this.listedAt = settings.discovers ? performance.now() : undefined;
         for (const partitionId of settings.partitionIds) {
             this.progress.set(partitionId, new PartitionProgress(settings.start));
         }
     }
+    /** @internal */
+    static create(settings) {
+        return new FilteredReader(settings);
+    }
     /** The next page with at least one match. Waits while nothing is new, up to `timeoutMs` when given. */
     async nextPage(options = {}) {
         const deadline = options.timeoutMs === undefined ? undefined : Date.now() + options.timeoutMs;
@@ -641,6 +575,43 @@ export class FilteredReader {
         this.partitionProgress(page.partitionId).completePage(sequence);
         await this.flush(page.partitionId);
     }
+    /**
+     * Mark this partition's records through `record` handled without storing
+     * yet. The normal consumer delivers in order, so every delivery completes
+     * the prefix through it, and it stores that prefix on its own cadence
+     * through `flushCompleted`.
+     *
+     * @internal
+     */
+    handled(record) {
+        const tag = record[READER_TAG];
+        if (tag?.owner !== this.owner)
+            return;
+        this.progress.get(record.partitionId)?.completeThrough(tag.sequence, record.offset);
+    }
+    /**
+     * Store every completed prefix now.
+     *
+     * @internal
+     */
+    async flushCompleted() {
+        if (this.settings.request.readMode !== "primary")
+            return;
+        let failure;
+        for (const partitionId of [...this.progress.keys()]) {
+            try {
+                await this.flush(partitionId);
+            }
+            catch (error) {
+                failure ??= error;
+            }
+        }
+        if (failure !== undefined) {
+            throw failure instanceof Error
+                ? failure
+                : new TransportError("storing group progress failed", true, { cause: failure });
+        }
+    }
     /** The partitions this reader reads now. */
     partitions() {
         return [...this.progress.keys()].filter((partitionId) => !this.revoked.has(partitionId));
@@ -725,9 +696,6 @@ export class FilteredReader {
         }
         if (this.settings.membership?.isDue() === true)
             await this.refreshMembership();
-        if (this.listedAt !== undefined && performance.now() - this.listedAt >= ASSIGNMENT_REFRESH_MS) {
-            await this.refreshPartitions();
-        }
         const readable = this.partitions();
         if (readable.length === 0)
             return { kind: "idle" };
@@ -796,6 +764,13 @@ export class FilteredReader {
                 return { kind: "empty", more: false };
             }
             this.restartAfter(partitionId, error);
+            // The group's policy changed under this read. The partition restarted
+            // from its stored offset and is read again at once under the policy the
+            // group holds now. Only an explicit acknowledgment of a record read
+            // under the old policy reports the change.
+            if (error instanceof FilterExecutionError && error.reason === "conflict") {
+                return { kind: "empty", more: true };
+            }
             throw error;
         }
         this.requireOpen();
@@ -811,7 +786,7 @@ export class FilteredReader {
         if (recordHead.getUint32(12, true) !== page.matched || page.matched > request.count)
             throw new ProtocolError("filtered record body has invalid counts");
         const messages = decodePolledBody(page.records);
-        validatePage(request, this.settings.inlineDigest, page, messages);
+        validatePage(request, page, messages);
         if (request.consumer.kind === "group_id") {
             const pinned = this.pinnedSource;
             const current = page.generation;
@@ -828,16 +803,19 @@ export class FilteredReader {
             this.pinnedSource ??= current;
         }
         const unevaluated = new Set(page.unevaluated);
-        if (this.settings.guardEnabled && this.guard === undefined) {
-            this.guard = await compileGuard(this.settings.transport, await boundDefinition(this.settings.filters, request.source, page));
-        }
-        if (this.guard !== undefined) {
-            try {
-                checkGuard(this.guard, page, messages, unevaluated);
+        // An unfiltered page ran no filter, so there is nothing to check.
+        if (page.policy.mode === "filtered") {
+            if (this.settings.guardEnabled && this.guard === undefined) {
+                this.guard = await compileGuard(this.settings.transport, await boundDefinition(this.settings.filters, request.source, page));
             }
-            catch (error) {
-                this.restartAfter(partitionId, error);
-                throw error;
+            if (this.guard !== undefined) {
+                try {
+                    checkGuard(this.guard, page, messages, unevaluated);
+                }
+                catch (error) {
+                    this.restartAfter(partitionId, error);
+                    throw error;
+                }
             }
         }
         this.sequence += 1;
@@ -869,7 +847,7 @@ export class FilteredReader {
             partitionId,
             offset: message.offset,
             frontier: page.frontier,
-            evaluated: !unevaluated.has(message.offset),
+            evaluated: page.policy.mode === "filtered" && !unevaluated.has(message.offset),
             payload: message.payload,
             headers: message.headers,
             headersMalformed: message.headersMalformed !== undefined,
@@ -907,8 +885,7 @@ export class FilteredReader {
         }
         if (error.reason === "source_changed")
             this.settings.membership?.expire();
-        const request = this.settings.request;
-        if (request.filter.kind === "bound")
+        if (this.settings.guardEnabled)
             this.guard = undefined;
     }
     // Store the completed prefix of one partition. A lost reply keeps the target
@@ -927,8 +904,10 @@ export class FilteredReader {
             partitionId,
             consumer: request.consumer,
             generation: target.generation,
-            digest: target.digest,
-            offset: target.offset
+            ...(target.digest === undefined ? {} : { digest: target.digest }),
+            offset: target.offset,
+            mode: target.mode,
+            policyGeneration: target.policyGeneration
         };
         const encoded = encodeFilteredAck(ack);
         for (let rerouted = false;; rerouted = true) {
@@ -949,6 +928,7 @@ export class FilteredReader {
                 return;
             }
             catch (error) {
+                this.restartAfter(partitionId, error);
                 if (rerouted || !isRouteLost(error))
                     throw error;
             }
@@ -988,11 +968,13 @@ export class FilteredReader {
         if (membership === undefined || !(await membership.sync()))
             return;
         this.requireOpen();
-        const assigned = new Set(membership.partitions);
+        const selection = this.settings.selectedPartitions;
+        const assigned = new Set(membership.partitions.filter((partition) => selection === undefined || selection.size === 0 || selection.has(partition)));
         const rejoined = membership.takeRejoined();
         const stale = rejoined ? this.routes.detach() : [];
         if (rejoined) {
-            if (this.settings.request.filter.kind === "bound")
+            // A rejoin can land in a recreated group with another binding.
+            if (this.settings.guardEnabled)
                 this.guard = undefined;
             this.retiredOwners.add(this.owner);
             this.owner = {};
@@ -1022,17 +1004,6 @@ export class FilteredReader {
         for (const partitionId of left)
             await this.routes.release(partitionId);
     }
-    // An independent reader of every partition picks up partitions added to
-    // the topic since the build, resuming their stored progress.
-    async refreshPartitions() {
-        const listed = await topicPartitions(this.settings.transport, this.settings.request.source);
-        this.listedAt = performance.now();
-        for (const partitionId of listed) {
-            if (!this.progress.has(partitionId)) {
-                this.progress.set(partitionId, new PartitionProgress({ kind: "next" }));
-            }
-        }
-    }
     // Forget a revoked partition once nothing of it is in flight.
     retire(partitionId) {
         const progress = this.progress.get(partitionId);
@@ -1162,7 +1133,9 @@ class PartitionProgress {
             : {
                 offset: page.safeAckOffset,
                 generation: page.generation,
-                digest: page.policy.digest,
+                ...(page.policy.digest === undefined ? {} : { digest: page.policy.digest }),
+                mode: page.policy.mode,
+                policyGeneration: page.policy.policyGeneration,
                 ...(page.policy.groupId !== undefined ? { groupId: page.policy.groupId } : {})
             };
         const newest = this.pages.at(-1);
@@ -1233,6 +1206,11 @@ class Routes {
     opening = new Map();
     partitions = new Map();
     closed = false;
+    // Whether the deployment is one node, learned on the first route. A single
+    // node is every partition's primary, and the address it advertises can be
+    // one the caller cannot reach (a port mapped by a container runtime, a slot
+    // behind a proxy), so its data connection dials what the caller dialed.
+    singleNode;
     /** Data connections these routes opened. */
     opened = 0;
     constructor(transport, coordinator) {
@@ -1252,7 +1230,12 @@ class Routes {
             ? encodeOffsetRouting(source, consumer, partitionId)
             : encodePollRouting(source, consumer, partitionId)));
         this.requireOpen();
-        const endpoint = `${route.ip}:${String(route.tcpPort)}`;
+        if (this.singleNode === undefined) {
+            const count = this.transport.clusterNodeCount;
+            this.singleNode = count === undefined ? false : (await count.call(this.transport)) <= 1;
+        }
+        const dial = this.singleNode ? { ...route, ip: "", tcpPort: 0 } : route;
+        const endpoint = this.singleNode ? "caller" : `${route.ip}:${String(route.tcpPort)}`;
         const existing = this.connections.get(endpoint);
         const reuse = existing === undefined ? undefined : sessionReuse(existing.session, route.session);
         if (existing !== undefined && reuse === "raise") {
@@ -1268,7 +1251,7 @@ class Routes {
             await this.dropEndpoint(endpoint);
         }
         if (!this.connections.has(endpoint)) {
-            if (route.tcpPort === 0) {
+            if (!this.singleNode && route.tcpPort === 0) {
                 throw new UnsupportedError(`partition primary ${route.name} serves no TCP endpoint`);
             }
             let pending = this.opening.get(endpoint);
@@ -1281,7 +1264,7 @@ class Routes {
                 }
                 pending = this.opening.get(endpoint);
                 if (pending === undefined && !this.connections.has(endpoint)) {
-                    pending = attach(open.bind(this.transport), route).then((connection) => {
+                    pending = attach(open.bind(this.transport), dial).then((connection) => {
                         this.opened += 1;
                         return connection;
                     });
@@ -1374,7 +1357,7 @@ async function attach(open, route) {
     return connection;
 }
 // The shared transport as a coordinator, for a reader that has no connection
-// of its own: an injected client, or an independent reader.
+// of its own: an injected client.
 function sharedCoordinator(transport) {
     return {
         send: (code, payload) => transport.sendManaged(code, payload),
@@ -1387,10 +1370,6 @@ function sharedCoordinator(transport) {
         close: () => Promise.resolve()
     };
 }
-async function topicPartitions(transport, source) {
-    const count = await transport.getTopicPartitionCount(source.stream, source.topic);
-    return Array.from({ length: count }, (_, index) => index);
-}
 /** This reader's membership of a consumer group, held by its coordinator connection. */
 class Membership {
     coordinator;
@@ -1507,6 +1486,37 @@ async function sourceIncarnation(transport, source) {
         topicCreatedAtMicros: topic.created
     };
 }
+/**
+ * Read a consumer group's native id and name, and the stream and topic
+ * incarnations that scope it. Throws with reason `not_found` when the group
+ * does not exist.
+ */
+export async function nativeGroup(transport, source, group) {
+    const incarnation = await sourceIncarnation(transport, source);
+    const reply = await transport.sendManaged(GET_CONSUMER_GROUP_CODE, concat([identifier(source.stream), identifier(source.topic), identifier(group)]));
+    // The reply begins with id:u32, partitions:u32, members:u32, then the name
+    // as one length byte and its bytes. A missing group answers an empty body.
+    if (reply.byteLength === 0)
+        throw filterError({
+            code: { kind: "known", name: "NotFound" },
+            reason: "not_found",
+            message: `consumer group ${String(group)} does not exist`
+        });
+    if (reply.byteLength < 13)
+        throw new ProtocolError("consumer group metadata is truncated");
+    const view = new DataView(reply.buffer, reply.byteOffset, reply.byteLength);
+    const id = view.getUint32(0, true);
+    if (typeof group === "number" && id !== group)
+        throw new ProtocolError("consumer group metadata identifies another group");
+    const length = view.getUint8(12);
+    if (reply.byteLength < 13 + length)
+        throw new ProtocolError("consumer group metadata is truncated");
+    return {
+        id,
+        name: new TextDecoder().decode(reply.subarray(13, 13 + length)),
+        identity: { ...incarnation, groupId: BigInt(id) }
+    };
+}
 function identifier(name) {
     if (typeof name === "number") {
         const encoded = new Uint8Array(6);
@@ -1614,7 +1624,7 @@ function sameBytes(left, right) {
 // Re-evaluate every returned record with the shared evaluator before the
 // caller sees it.
 function checkGuard(guard, page, messages, unevaluated) {
-    if (!sameBytes(page.policy.digest, guard.digest)) {
+    if (page.policy.digest === undefined || !sameBytes(page.policy.digest, guard.digest)) {
         throw filterError({
             code: { kind: "known", name: "Conflict" },
             reason: "conflict",
@@ -1747,7 +1757,7 @@ async function boundDefinition(filters, requested, page) {
             identity.topicId === source.topicId &&
             identity.topicCreatedAtMicros === source.topicCreatedAtMicros);
         if (binding !== undefined) {
-            if (!sameBytes(binding.digest, page.policy.digest))
+            if (page.policy.digest === undefined || !sameBytes(binding.digest, page.policy.digest))
                 throw new ProtocolError("served policy differs from the group's catalog binding");
             return definition(filters, {
                 kind: "revision",
@@ -1766,8 +1776,8 @@ async function boundDefinition(filters, requested, page) {
 async function definition(filters, filter) {
     if (filter.kind === "inline")
         return filter.filter;
-    if (filter.kind === "bound")
-        throw new ConfigError("resolve a bound guard from the served page");
+    if (filter.kind === "bound" || filter.kind === "group")
+        throw new ConfigError("resolve a group guard from the served page");
     const { filterId, revision } = filter;
     for (let page = 0;; page += 1) {
         const revisions = await filters.revisions(filterId, { page, pageSize: MAX_FILTER_CATALOG_PAGE });
@@ -1831,7 +1841,7 @@ function sameGeneration(left, right) {
         left.partitionCreatedRevision === right.partitionCreatedRevision &&
         left.purgeGeneration === right.purgeGeneration);
 }
-function validatePage(request, inlineDigest, page, messages) {
+function validatePage(request, page, messages) {
     const invalid = () => {
         throw new ProtocolError("filtered page does not match its request or scan boundary");
     };
@@ -1844,14 +1854,20 @@ function validatePage(request, inlineDigest, page, messages) {
         page.matched !== messages.length ||
         page.matched > request.count ||
         page.matched > page.examined ||
-        page.policy.digest.length !== 32 ||
+        (request.maxExamined !== undefined && page.examined > request.maxExamined) ||
+        (page.policy.mode === "filtered") !== (page.policy.digest !== undefined) ||
+        (page.policy.digest !== undefined && page.policy.digest.length !== 32) ||
+        (page.policy.mode === "unfiltered" && page.policy.groupId === undefined) ||
+        (page.policy.mode === "unfiltered" && page.matched !== page.examined) ||
+        (page.policy.mode === "unfiltered" &&
+            (page.policy.filterId !== undefined || page.policy.revision !== undefined)) ||
+        // A strict group read runs a binding and never accepts an unfiltered page.
+        (page.policy.mode === "unfiltered" && request.filter.kind !== "group") ||
         (request.consumer.kind !== "consumer") !== (page.policy.groupId !== undefined))
         invalid();
     const body = new DataView(page.records.buffer, page.records.byteOffset, page.records.byteLength);
     if (body.getUint32(0, true) !== page.partitionId || body.getBigUint64(4, true) !== page.frontier)
         invalid();
-    if (inlineDigest !== undefined && !sameBytes(inlineDigest, page.policy.digest))
-        invalid();
     if (request.filter.kind === "revision" &&
         (page.policy.filterId !== request.filter.filterId ||
             page.policy.revision !== request.filter.revision))
@@ -1861,7 +1877,12 @@ function validatePage(request, inlineDigest, page, messages) {
         const cursor = request.start.continuation;
         if (!sameGeneration(cursor.generation, page.generation) ||
             cursor.groupId !== page.policy.groupId ||
-            !sameBytes(cursor.digest, page.policy.digest) ||
+            cursor.mode !== page.policy.mode ||
+            cursor.policyGeneration !== page.policy.policyGeneration ||
+            (cursor.digest === undefined) !== (page.policy.digest === undefined) ||
+            (cursor.digest !== undefined &&
+                page.policy.digest !== undefined &&
+                !sameBytes(cursor.digest, page.policy.digest)) ||
             cursor.readMode !== request.readMode)
             invalid();
         start = cursor.nextScanOffset;