@laserdata/laser-sdk 0.5.3 → 0.6.0

package/dist/client/laser.js

@@ -10,18 +10,19 @@ import { Workflow } from "../agent/workflow.js";
 import { aguiEvents, publishStateDelta, publishStateSnapshot, reconstructState } from "../bridges/agui.js";
 import { AgentScope } from "../agent/scope.js";
 import { ChunkAssembler } from "../agent/assembler.js";
-import { AgentRegistry, ClientMetadataRequest, encodePresenceInput, newRegistryCache } from "../agent/registry.js";
+import { AgentRegistry, ClientMetadataRequest, encodePresence, newRegistryCache } from "../agent/registry.js";
 import { AsyncOnce } from "../runtime/async-once.js";
 import { Stream } from "../stream/stream.js";
 import { ContextScope } from "../context-scope.js";
 import { Sessions } from "../session.js";
-import { ActionKind, GovernorState, encodePolicyEvidence, decodePolicyEvidence, POLICY_DECISION_OPERATION } from "../govern.js";
+import { ActionKind, GovernorState, encodePolicyEvidence, POLICY_DECISION_OPERATION } from "../govern.js";
 import { MemoryBackend, MemoryHandle } from "../memory/handle.js";
 import { MemoryTopicBuilder } from "../memory/topic.js";
 import { NOOP_OBSERVER } from "../observe.js";
 import { executeBatch } from "../managed/batch.js";
-import { Fork } from "../managed/forks.js";
+import { ForkHandle } from "../managed/forks.js";
 import { Kv } from "../managed/kv.js";
+import { LeaseCoordinator } from "../managed/coordination.js";
 import { Bindings, Projections, Schemas } from "../managed/projections.js";
 import { QueryRequest } from "../managed/query.js";
 import { Destinations } from "../managed/destinations.js";
@@ -30,7 +31,7 @@ import { GraphHandle } from "../managed/graph.js";
 import { Runs } from "../managed/runs.js";
 import { Watch } from "../managed/watch.js";
 import { AGDX_HELLO_CODE, AGDX_SET_CLIENT_METADATA_CODE, CONTROL_OP_VERSION, QUERY_OP_VERSION } from "../wire/codes.js";
-import { QueryCancelCommand, QueryCommand, QueryStatusCommand } from "../wire/commands.js";
+import { QueryCancelCommand, QueryCommand, QueryPageCommand, QueryStatusCommand } from "../wire/commands.js";
 import { encodeControlEnvelope } from "../wire/control.js";
 import { decodeBackendAnnounce } from "../wire/hello.js";
 import { AgentId, ConversationId } from "../types/ids.js";
@@ -43,27 +44,27 @@ import { AgentTopic } from "../provenance/agent-topic.js";
 import { encodeProvenanceHeaders, provenancePartitionKey } from "../provenance/provenance.js";
 import { CHANGES_TOPIC, CONTROL_TOPIC, DLQ_TOPIC, OPS_STREAM } from "../wire/topics.js";
 import { encodeNamed } from "../wire/cbor.js";
-import { ConfigError, NoStreamError, PresenceConflictError, QueryExecutionError, InvalidError, TimeoutError, UnsupportedError } from "./errors.js";
+import { ConfigError, NoStreamError, PresenceConflictError, QueryExecutionError, ProtocolError, InvalidError, TimeoutError, UnsupportedError } from "./errors.js";
 import { executeManaged } from "./managed.js";
 import { INTERNAL_GOVERN, INTERNAL_REPLY_HUB, INTERNAL_TRANSPORT, INTERNAL_VERIFIER } from "./internals.js";
-import { OPEN_CAPABILITIES, managedCapabilitiesFrom, mergeCapabilities, isReady, servesConsistency } from "./capabilities.js";
+import { OPEN_CAPABILITIES, advertisedTopology, managedCapabilitiesFrom, mergeCapabilities, isReady, servesConsistency } from "./capabilities.js";
 const LOCAL_CONNECTION_STRING = "iggy:iggy@127.0.0.1:8090";
 // The Iggy error code a server answers an unknown command with.
 const INVALID_COMMAND = 3;
 const DEFAULT_TOPOLOGY = {
     opsStream: OPS_STREAM,
     controlTopic: CONTROL_TOPIC,
-    deadLetterTopic: DLQ_TOPIC,
+    dlqTopic: DLQ_TOPIC,
     changesTopic: CHANGES_TOPIC
 };
 const NO_TOPOLOGY_OVERRIDES = {
     opsStream: false,
     controlTopic: false,
-    deadLetterTopic: false,
+    dlqTopic: false,
     changesTopic: false
 };
 export class LaserBuilder {
-    create;
+    connectWith;
     connectOptionsValue = {};
     publishOptionsValue = {};
     connectionStringValue;
@@ -78,8 +79,12 @@ export class LaserBuilder {
     verifierValue;
     topologyValue = DEFAULT_TOPOLOGY;
     topologyOverridesValue = NO_TOPOLOGY_OVERRIDES;
-    constructor(create) {
-        this.create = create;
+    constructor(connectWith) {
+        this.connectWith = connectWith;
+    }
+    /** @internal */
+    static create(connectWith) {
+        return new LaserBuilder(connectWith);
     }
     /**
      * Budget for the initial connect: TCP dial, TLS handshake, login, and the managed capability probe. An expired budget rejects with `TimeoutError` naming the stage that stalled. Default: 30 seconds, or `LASER_CONNECT_TIMEOUT_MS`.
@@ -109,19 +114,15 @@ export class LaserBuilder {
         return this;
     }
     credentials(username, password) {
-        this.credentialsValue = { kind: "usernamePassword", username, password };
-        return this;
-    }
-    token(value) {
-        this.credentialsValue = { kind: "token", token: value };
+        this.credentialsValue = { username, password };
         return this;
     }
-    iggyClient(client, options = {}) {
+    client(client, options = {}) {
         this.clientValue = client;
         this.ownershipValue = options.ownership ?? "borrowed";
         return this;
     }
-    defaultStream(value) {
+    stream(value) {
         this.defaultStreamValue = value;
         return this;
     }
@@ -151,9 +152,9 @@ export class LaserBuilder {
         this.topologyOverridesValue = { ...this.topologyOverridesValue, controlTopic: true };
         return this;
     }
-    deadLetterTopic(value) {
-        this.topologyValue = { ...this.topologyValue, deadLetterTopic: value };
-        this.topologyOverridesValue = { ...this.topologyOverridesValue, deadLetterTopic: true };
+    dlqTopic(value) {
+        this.topologyValue = { ...this.topologyValue, dlqTopic: value };
+        this.topologyOverridesValue = { ...this.topologyOverridesValue, dlqTopic: true };
         return this;
     }
     changesTopic(value) {
@@ -161,15 +162,17 @@ export class LaserBuilder {
         this.topologyOverridesValue = { ...this.topologyOverridesValue, changesTopic: true };
         return this;
     }
-    connect() {
+    /** Connects with the configured settings. A configuration conflict
+     * rejects before any I/O, like every other failure of the connect. */
+    async connect() {
         const modes = Number(this.connectionStringValue !== undefined) +
             Number(this.addressValue !== undefined) +
             Number(this.clientValue !== undefined);
         if (modes > 1) {
-            throw new ConfigError("connectionString(), address(), and iggyClient() are mutually exclusive");
+            throw new ConfigError("connectionString(), address(), and client() are mutually exclusive");
         }
         if (this.credentialsValue !== undefined && this.addressValue === undefined) {
-            throw new ConfigError("credentials() and token() require address()");
+            throw new ConfigError("credentials() requires address()");
         }
         if (this.addressValue !== undefined) {
             const { host, port } = this.addressValue;
@@ -180,14 +183,14 @@ export class LaserBuilder {
         const topologyEntries = [
             ["opsStream", this.topologyValue.opsStream],
             ["controlTopic", this.topologyValue.controlTopic],
-            ["deadLetterTopic", this.topologyValue.deadLetterTopic],
+            ["dlqTopic", this.topologyValue.dlqTopic],
             ["changesTopic", this.topologyValue.changesTopic]
         ];
         for (const [name, value] of topologyEntries) {
             if (value.length === 0)
                 throw new ConfigError(`${name} must not be empty`);
         }
-        return this.create({
+        return this.connectWith({
             connectOptions: connectOptions(this.connectOptionsValue),
             publishOptions: publishOptions(this.publishOptionsValue),
             ...(this.connectionStringValue !== undefined
@@ -208,10 +211,13 @@ export class LaserBuilder {
     }
 }
 export { INTERNAL_GOVERN, INTERNAL_REPLY_HUB, INTERNAL_TRANSPORT, INTERNAL_VERIFIER } from "./internals.js";
-function newSharedState() {
+// `connectionString` is the string the client dialed, absent for an injected
+// client, which has nothing to dial a coordination connection with.
+function newSharedState(connectionString) {
     return {
         registryCaches: new Map(),
         replyHubs: new Map(),
+        leases: LeaseCoordinator.forConnection(connectionString),
         announcedTopology: DEFAULT_TOPOLOGY
     };
 }
@@ -244,7 +250,7 @@ function actionKind(kind) {
 }
 function metadataString(envelope, key) {
     const value = envelope.metadata?.get(key);
-    return value?.kind === "string" ? value.value : undefined;
+    return value?.kind === "str" ? value.value : undefined;
 }
 function metadataActionFields(envelope) {
     const onBehalfOf = metadataString(envelope, METADATA_DELEGATED_BY);
@@ -319,10 +325,10 @@ export class Laser {
             ? this.configuredTopology.controlTopic
             : this.shared.announcedTopology.controlTopic;
     }
-    get deadLetterTopic() {
-        return this.topologyOverrides.deadLetterTopic
-            ? this.configuredTopology.deadLetterTopic
-            : this.shared.announcedTopology.deadLetterTopic;
+    get dlqTopic() {
+        return this.topologyOverrides.dlqTopic
+            ? this.configuredTopology.dlqTopic
+            : this.shared.announcedTopology.dlqTopic;
     }
     get changesTopic() {
         return this.topologyOverrides.changesTopic
@@ -330,32 +336,29 @@ export class Laser {
             : this.shared.announcedTopology.changesTopic;
     }
     static builder() {
-        return new LaserBuilder(async (options) => {
+        return LaserBuilder.create(async (options) => {
             const deadline = Date.now() + options.connectOptions.timeoutMs;
             let transport;
+            let dialed;
             if (options.client !== undefined) {
                 transport = await ApacheIggyTransport.fromClient(options.client, options.ownership, options.publishOptions, deadline);
             }
             else if (options.address !== undefined) {
-                const credentials = options.credentials ?? {
-                    kind: "usernamePassword",
-                    username: "iggy",
-                    password: "iggy"
-                };
-                const userInfo = credentials.kind === "token"
-                    ? encodeURIComponent(credentials.token)
-                    : `${encodeURIComponent(credentials.username)}:${encodeURIComponent(credentials.password)}`;
+                const credentials = options.credentials ?? { username: "iggy", password: "iggy" };
+                const userInfo = `${encodeURIComponent(credentials.username)}:${encodeURIComponent(credentials.password)}`;
                 const authorityHost = options.address.host.includes(":")
                     ? `[${options.address.host.replace(/^\[|\]$/g, "")}]`
                     : options.address.host;
-                transport = await ApacheIggyTransport.connect(`iggy://${userInfo}@${authorityHost}:${String(options.address.port)}`, options.publishOptions, deadline);
+                dialed = `iggy://${userInfo}@${authorityHost}:${String(options.address.port)}`;
+                transport = await ApacheIggyTransport.connect(dialed, options.publishOptions, deadline);
             }
             else {
-                transport = await ApacheIggyTransport.connect(options.connectionString ?? LOCAL_CONNECTION_STRING, options.publishOptions, deadline);
+                dialed = options.connectionString ?? LOCAL_CONNECTION_STRING;
+                transport = await ApacheIggyTransport.connect(dialed, options.publishOptions, deadline);
             }
             const laser = new Laser(transport, options.defaultStream, options.capabilities === undefined
                 ? new AsyncOnce()
-                : AsyncOnce.resolved(options.capabilities), newSharedState(), options.observer, options.governor === undefined
+                : AsyncOnce.resolved(options.capabilities), newSharedState(dialed), options.observer, options.governor === undefined
                 ? undefined
                 : new GovernorState(options.governor.policy, options.governor.mode, undefined, options.governor.retention), options.verifier, options.topology, options.topologyOverrides, options.capabilities ?? OPEN_CAPABILITIES);
             if (options.capabilities === undefined)
@@ -363,15 +366,14 @@ export class Laser {
             return laser;
         });
     }
-    static fromIggyClient(client, options = {}) {
-        const builder = Laser.builder()
-            .iggyClient(client, options.ownership === undefined ? {} : { ownership: options.ownership })
-            .capabilities(options.capabilities ?? OPEN_CAPABILITIES);
-        if (options.defaultStream !== undefined)
-            builder.defaultStream(options.defaultStream);
-        if (options.observer !== undefined)
-            builder.observer(options.observer);
-        return builder.connect();
+    /**
+     * Wrap a connected, logged-in Apache Iggy client with no default stream.
+     * Chain `withDefaultStream`, `withCapabilities`, or `withObserver` to
+     * configure the handle. A `borrowed` client (the default) stays open when
+     * the handle closes, an `owned` one closes with it.
+     */
+    static fromClient(client, options = {}) {
+        return Laser.builder().client(client, options).capabilities(OPEN_CAPABILITIES).connect();
     }
     /**
      * Connect using an Iggy connection string. Connecting gives up after 30 seconds, or `LASER_CONNECT_TIMEOUT_MS`, with a `TimeoutError` that says whether the server never accepted the connection or never answered the login. Use `Laser.builder().connectTimeout()` for another budget.
@@ -379,14 +381,14 @@ export class Laser {
     static async connect(connectionString) {
         const deadline = Date.now() + connectOptions().timeoutMs;
         const transport = await ApacheIggyTransport.connect(connectionString, undefined, deadline);
-        const laser = new Laser(transport, undefined, new AsyncOnce(), newSharedState());
+        const laser = new Laser(transport, undefined, new AsyncOnce(), newSharedState(connectionString));
         await laser.probeCapabilitiesBefore(deadline);
         return laser;
     }
     static async connectWithStream(connectionString, stream) {
         const deadline = Date.now() + connectOptions().timeoutMs;
         const transport = await ApacheIggyTransport.connect(connectionString, undefined, deadline);
-        const laser = new Laser(transport, stream, new AsyncOnce(), newSharedState());
+        const laser = new Laser(transport, stream, new AsyncOnce(), newSharedState(connectionString));
         await laser.probeCapabilitiesBefore(deadline);
         return laser;
     }
@@ -406,15 +408,48 @@ export class Laser {
     withDefaultStream(stream) {
         return new Laser(this.transport, stream, this.capabilitiesOnce, this.shared, this.observer, this.governor, this.verifier, this.configuredTopology, this.topologyOverrides, this.configuredCapabilities, this.capabilityOverride, false);
     }
+    /** A clone whose managed operations use `opsStream` instead of the ops
+     * stream the deployment announced. The connection is shared. */
+    withOpsStream(opsStream) {
+        return this.withTopology({ opsStream });
+    }
+    /** A clone whose control commands publish to `controlTopic` on the ops
+     * stream. The connection is shared. */
+    withControlTopic(controlTopic) {
+        return this.withTopology({ controlTopic });
+    }
+    /** A clone whose dead-letter capsules publish to `dlqTopic` on the ops
+     * stream. The connection is shared. */
+    withDlqTopic(dlqTopic) {
+        return this.withTopology({ dlqTopic });
+    }
+    /** A clone whose change-feed records are read from `changesTopic` on the ops
+     * stream. The connection is shared. */
+    withChangesTopic(changesTopic) {
+        return this.withTopology({ changesTopic });
+    }
+    withTopology(override) {
+        const topology = {
+            opsStream: this.opsStream,
+            controlTopic: this.controlTopic,
+            dlqTopic: this.dlqTopic,
+            changesTopic: this.changesTopic,
+            ...override
+        };
+        const overrides = {
+            opsStream: this.topologyOverrides.opsStream || override.opsStream !== undefined,
+            controlTopic: this.topologyOverrides.controlTopic || override.controlTopic !== undefined,
+            dlqTopic: this.topologyOverrides.dlqTopic || override.dlqTopic !== undefined,
+            changesTopic: this.topologyOverrides.changesTopic || override.changesTopic !== undefined
+        };
+        return new Laser(this.transport, this.defaultStream, this.capabilitiesOnce, this.shared, this.observer, this.governor, this.verifier, topology, overrides, this.configuredCapabilities, this.capabilityOverride, false);
+    }
     withCapabilities(capabilities) {
         return new Laser(this.transport, this.defaultStream, this.capabilitiesOnce, this.shared, this.observer, this.governor, this.verifier, this.configuredTopology, this.topologyOverrides, this.configuredCapabilities, capabilities, false);
     }
     withGovernor(governor, mode, retention = {}) {
         return new Laser(this.transport, this.defaultStream, this.capabilitiesOnce, this.shared, this.observer, new GovernorState(governor, mode, undefined, retention), this.verifier, this.configuredTopology, this.topologyOverrides, this.configuredCapabilities, this.capabilityOverride, false);
     }
-    withVerifier(verifier) {
-        return new Laser(this.transport, this.defaultStream, this.capabilitiesOnce, this.shared, this.observer, this.governor, verifier, this.configuredTopology, this.topologyOverrides, this.configuredCapabilities, this.capabilityOverride, false);
-    }
     withObserver(observer) {
         return new Laser(this.transport, this.defaultStream, this.capabilitiesOnce, this.shared, observer, this.governor, this.verifier, this.configuredTopology, this.topologyOverrides, this.configuredCapabilities, this.capabilityOverride, false);
     }
@@ -481,7 +516,9 @@ export class Laser {
             if (isReady(capabilities))
                 return capabilities;
             if (capabilities.backends.length === 0) {
-                throw new UnsupportedError("server has no managed backend descriptors");
+                throw new UnsupportedError("server has no managed backend descriptors", {
+                    surface: "readiness"
+                });
             }
             if (Date.now() >= deadline) {
                 throw new TimeoutError("timed out waiting for managed backend readiness", {
@@ -492,41 +529,45 @@ export class Laser {
         }
     }
     applyAdvertisedTopology(capabilities) {
-        const topology = capabilities.topology;
+        const topology = advertisedTopology(capabilities);
         if (topology === undefined)
             return;
         this.shared.announcedTopology = {
             opsStream: topology.opsStream,
             controlTopic: topology.controlTopic,
-            deadLetterTopic: topology.dlqTopic,
+            dlqTopic: topology.dlqTopic,
             changesTopic: topology.changesTopic
         };
     }
+    /** @internal */
     [INTERNAL_TRANSPORT]() {
         return this.transport;
     }
+    /** @internal */
     [INTERNAL_VERIFIER]() {
         return this.verifier;
     }
+    /** @internal */
     [INTERNAL_REPLY_HUB](topic) {
         return this.replyHub(topic);
     }
+    /** @internal */
     [INTERNAL_GOVERN](action) {
         if (this.governor === undefined)
             return Promise.resolve(action.payload.slice());
         return this.governor.govern(action, (evidence) => this.emitPolicyEvidence(action.stream, evidence));
     }
-    get iggyClient() {
+    get client() {
         return this.transport.iggyClient;
     }
     stream(name) {
-        return new Stream(this.transport, name, (stream, topic, payload, provenance) => this[INTERNAL_GOVERN]({
+        return Stream.create(this.transport, name, (stream, topic, payload, provenance) => this[INTERNAL_GOVERN]({
             kind: ActionKind.Publish,
             stream,
             topic,
-            ...(provenance?.agent !== undefined ? { source: provenance.agent.asString() } : {}),
+            ...(provenance?.agent !== undefined ? { source: provenance.agent.asStr() } : {}),
             ...(provenance?.targetAgentId !== undefined
-                ? { target: provenance.targetAgentId.asString() }
+                ? { target: provenance.targetAgentId.asStr() }
                 : {}),
             ...(provenance !== undefined ? { conversation: provenance.conversationId } : {}),
             ...(provenance?.correlationId !== undefined
@@ -575,13 +616,13 @@ export class Laser {
         }), this.verifier);
     }
     agent(id) {
-        return new AgentScope(this, id);
+        return AgentScope.create(this, id);
     }
     contract(router) {
-        return new ContractBuilder(this, router);
+        return ContractBuilder.create(this, router);
     }
     workflow(name) {
-        return new Workflow(this, name);
+        return Workflow.create(this, name);
     }
     publishStateSnapshot(topic, source, conversation, state) {
         return publishStateSnapshot(this, topic, source, conversation, state);
@@ -602,13 +643,13 @@ export class Laser {
         return scatterReport(this, source, selector, payload, inboxRoute, deadlineMs);
     }
     context(conversation) {
-        return new ContextScope(this, conversation);
+        return ContextScope.create(this, conversation);
     }
     /** The session accessor: one conversation seen as typed turns, a model-ready
      * context, scoped memory, and checkpointed replay. Built on `context`, so a
      * session is never a second store. */
-    sessions(options) {
-        return new Sessions(this, options);
+    sessions(config) {
+        return Sessions.create(this, config);
     }
     memory(namespace) {
         return this.memoryWith(namespace, MemoryBackend.Auto);
@@ -619,7 +660,7 @@ export class Laser {
     }
     /** Configures a durable memory topic before opening it. */
     memoryTopic(topic) {
-        return new MemoryTopicBuilder(this, topic);
+        return MemoryTopicBuilder.create(this, topic);
     }
     memoryWith(namespace, backend, embedder) {
         return backend === MemoryBackend.Vector
@@ -646,15 +687,15 @@ export class Laser {
             ...(provenance.correlationId !== undefined
                 ? { correlation: provenance.correlationId }
                 : {}),
-            ...(provenance.agent !== undefined ? { agent: provenance.agent.asString() } : {})
+            ...(provenance.agent !== undefined ? { agent: provenance.agent.asStr() } : {})
         }, async () => {
             const governedPayload = await this[INTERNAL_GOVERN]({
                 kind: ActionKind.Send,
                 stream,
                 topic,
-                ...(provenance.agent !== undefined ? { source: provenance.agent.asString() } : {}),
+                ...(provenance.agent !== undefined ? { source: provenance.agent.asStr() } : {}),
                 ...(provenance.targetAgentId !== undefined
-                    ? { target: provenance.targetAgentId.asString() }
+                    ? { target: provenance.targetAgentId.asStr() }
                     : {}),
                 conversation: provenance.conversationId,
                 ...(provenance.correlationId !== undefined
@@ -673,19 +714,6 @@ export class Laser {
             await this.transport.sendMessageWithHeaders(stream, topic, governedPayload, headers, provenancePartitionKey(provenance));
         });
     }
-    async policyEvidence(conversation) {
-        const messages = await this.context(conversation).fetch([AgentTopic.Audit], Number.MAX_SAFE_INTEGER);
-        return messages.flatMap((message) => {
-            if (message.envelope?.operation !== POLICY_DECISION_OPERATION)
-                return [];
-            try {
-                return [decodePolicyEvidence(message.envelope.body)];
-            }
-            catch {
-                return [];
-            }
-        });
-    }
     async emitPolicyEvidence(stream, evidence) {
         const conversation = evidence.conversation === undefined
             ? ConversationId.parse("00000000000000000000000000")
@@ -706,10 +734,10 @@ export class Laser {
         };
     }
     async reassembleChannel(conversation, topic, channel) {
-        const cursor = await this.topic(topic).replay({ batchSize: 1_000 });
+        const cursor = (await this.topic(topic).replay()).batch(1_000);
         const envelopes = [];
         for (;;) {
-            const records = await cursor.poll();
+            const records = await cursor.pollRecords();
             if (records.length === 0)
                 break;
             for (const record of records) {
@@ -735,7 +763,9 @@ export class Laser {
     async consumed(target, at) {
         if (this.transport.resolveStreamTopicNames === undefined ||
             this.transport.getConsumerOffset === undefined) {
-            throw new UnsupportedError("the active Iggy transport cannot resolve consumer offsets");
+            throw new UnsupportedError("the active Iggy transport cannot resolve consumer offsets", {
+                surface: "stream"
+            });
         }
         const names = await this.transport.resolveStreamTopicNames(at.streamId, at.topicId);
         if (names === undefined) {
@@ -744,7 +774,7 @@ export class Laser {
         const consumer = target.kind === "group"
             ? {
                 kind: "group",
-                name: typeof target.name === "string" ? target.name : target.name.asString()
+                name: typeof target.name === "string" ? target.name : target.name.asStr()
             }
             : { kind: "consumer", name: target.name };
         const offset = await this.transport.getConsumerOffset(names.stream, names.topic, consumer, at.partitionId);
@@ -756,7 +786,9 @@ export class Laser {
     }
     async redriveDeadLetter(capsule) {
         if (this.transport.resolveStreamTopicNames === undefined) {
-            throw new UnsupportedError("the active Iggy transport cannot resolve dead-letter sources");
+            throw new UnsupportedError("the active Iggy transport cannot resolve dead-letter sources", {
+                surface: "stream"
+            });
         }
         const source = capsule.source;
         const names = await this.transport.resolveStreamTopicNames(source.streamId, source.topicId);
@@ -787,7 +819,7 @@ export class Laser {
         const correlationId = provenance.correlationId ?? ConversationId.new().toString();
         const correlated = { ...provenance, correlationId };
         const hub = await this.replyHub(replyTopic);
-        const ticket = hub.subscribe(correlationId, correlated.targetAgentId?.asString());
+        const ticket = hub.subscribe(correlationId, correlated.targetAgentId?.asStr());
         try {
             await this.sendAgent(requestTopic, payload, correlated);
         }
@@ -798,16 +830,16 @@ export class Laser {
         return ticket.wait(timeoutMs, signal);
     }
     clientMetadata() {
-        return new ClientMetadataRequest(this.transport);
+        return ClientMetadataRequest.create(this.transport);
     }
     async advertisePresence(presence) {
-        const requested = presence.agent.asString();
+        const requested = AgentId.new(presence.agent).asStr();
         const advertised = this.shared.advertisedAgent;
         if (advertised !== undefined && advertised !== requested) {
             throw new PresenceConflictError(advertised, requested);
         }
         this.shared.advertisedAgent = requested;
-        await this.managedTransport().sendManaged(AGDX_SET_CLIENT_METADATA_CODE, encodePresenceInput(presence));
+        await this.managedTransport().sendManaged(AGDX_SET_CLIENT_METADATA_CODE, encodePresence(presence));
     }
     async clearPresence() {
         await this.managedTransport().sendManaged(AGDX_SET_CLIENT_METADATA_CODE, new Uint8Array());
@@ -822,7 +854,7 @@ export class Laser {
             this.shared.registryCaches.set(stream, cache);
         }
         const cursor = await this.topic(AgentTopic.Registry).replay();
-        return new AgentRegistry(cursor, cache, () => this.clientMetadata(), undefined, this.verifier);
+        return AgentRegistry.create(cursor, cache, () => this.clientMetadata(), undefined, this.verifier);
     }
     async publishCard(source, card) {
         validateAgentCard(card);
@@ -850,7 +882,7 @@ export class Laser {
         await this.topic(AgentTopic.Registry).ensure(1);
         let fact = this.agdx(AgentTopic.Registry, operator, ConversationId.new())
             .status(operation)
-            .body(new TextEncoder().encode(agent.asString()));
+            .body(new TextEncoder().encode(agent.asStr()));
         if (key !== undefined)
             fact = fact.signedBy(key);
         await fact.send();
@@ -879,13 +911,18 @@ export class Laser {
         return this.queryTarget({ kind: "operational", index });
     }
     queryTarget(target) {
-        return new QueryRequest(target, (query) => this.executeQuery(query), (executionId) => this.queryStatus(executionId), (executionId) => this.cancelQuery(executionId));
+        return QueryRequest.create(target, (query) => this.executeQuery(query), (executionId) => this.queryStatus(executionId), (executionId) => this.cancelQuery(executionId));
     }
     queryLakehouse(destinationId, destinationGeneration) {
         return this.queryTarget({ kind: "lakehouse", destinationId, destinationGeneration });
     }
     destinations() {
-        return new Destinations(this.managedTransport(), () => this.capabilities());
+        return Destinations.create(this.managedTransport(), () => this.capabilities());
+    }
+    /** Sends one checkpoint request envelope, the deep form behind every
+     * `destinations()` mutation. */
+    executeCheckpoint(request) {
+        return this.destinations().executeCheckpoint(request);
     }
     // What a consumer group needs to reach its filter policy and read through
     // the partition primaries.
@@ -910,11 +947,12 @@ export class Laser {
                     : {}),
                 ...(transport.connectsNodes !== undefined ? { connectsNodes: transport.connectsNodes } : {})
             },
-            capabilities: () => this.capabilities()
+            capabilities: () => this.capabilities(),
+            refreshCapabilities: () => this.refreshCapabilities()
         };
     }
     kv(namespace) {
-        return new Kv(this.managedTransport(), () => this.capabilities(), namespace);
+        return Kv.create(this.managedTransport(), () => this.capabilities(), namespace, this.shared.leases);
     }
     async kvNamespaces() {
         return Kv.namespaces(this.managedTransport(), () => this.capabilities());
@@ -924,28 +962,28 @@ export class Laser {
         return executeBatch(this.managedTransport(), capabilities, ops);
     }
     fork(forkId) {
-        return new Fork(this.managedTransport(), () => this.capabilities(), forkId);
+        return ForkHandle.create(this.managedTransport(), () => this.capabilities(), forkId);
     }
     async forks() {
-        return Fork.forks(this.managedTransport(), () => this.capabilities());
+        return ForkHandle.forks(this.managedTransport(), () => this.capabilities());
     }
     projections() {
-        return new Projections(this.managedTransport(), () => this.capabilities(), (command) => this.publishControl(command));
+        return Projections.create(this.managedTransport(), () => this.capabilities(), (command) => this.publishControl(command));
     }
     bindings() {
-        return new Bindings((command) => this.publishControl(command));
+        return Bindings.create((command) => this.publishControl(command));
     }
     schemas() {
-        return new Schemas(this.managedTransport(), () => this.capabilities(), (command) => this.publishControl(command));
+        return Schemas.create(this.managedTransport(), () => this.capabilities(), (command) => this.publishControl(command));
     }
     runs() {
-        return new Runs(this.managedTransport(), () => this.capabilities(), (command) => this.publishControl(command));
+        return Runs.create(this.managedTransport(), () => this.capabilities(), (command) => this.publishControl(command));
     }
     watch() {
-        return new Watch(() => this.capabilities(), (options) => this.stream(this.opsStream).topic(this.changesTopic).replay(options));
+        return Watch.create(() => this.capabilities(), () => this.stream(this.opsStream).topic(this.changesTopic).replay());
     }
     graph(name) {
-        return new GraphHandle(this.managedTransport(), () => this.capabilities(), name);
+        return GraphHandle.create(this.managedTransport(), () => this.capabilities(), name);
     }
     async whoami() {
         return whoami(this.managedTransport(), await this.capabilities());
@@ -982,49 +1020,96 @@ export class Laser {
             .topic(this.controlTopic)
             .send(payload, { key: new TextEncoder().encode("control") });
     }
+    /** Executes a pre-built `Query` and returns the raw paged result. Most
+     * callers want `query(index)...fetch()` instead. Needs `laser-plane` in Laser
+     * Stack or LaserData Cloud, otherwise it fails with `UnsupportedError`. */
     async executeQuery(query) {
         const capabilities = await this.capabilities();
         if (query.text !== undefined && !capabilities.query.keyword) {
-            throw new UnsupportedError("keyword query is not served by this deployment");
+            throw new UnsupportedError("keyword query is not served by this deployment", {
+                surface: "query",
+                feature: "keyword"
+            });
         }
         if (!servesConsistency(capabilities, query.consistency)) {
-            throw new UnsupportedError(`${query.consistency} query consistency is not served by this deployment`);
+            throw new UnsupportedError(`${query.consistency} query consistency is not served by this deployment`, { surface: "query", feature: "consistency" });
         }
         const reply = await executeManaged(this.managedTransport(), capabilities, QueryCommand, {
             v: QUERY_OP_VERSION,
             query
         });
-        if (reply.kind === "ok")
+        if (reply.kind === "ok") {
+            if (reply.result.context.executionId.asU128() !== query.executionId.asU128()) {
+                throw new ProtocolError("query reply execution id does not match the request");
+            }
             return reply.result;
-        if (reply.error.kind === "unsupported") {
-            throw new UnsupportedError(reply.error.message);
         }
         throw new QueryExecutionError(`query failed: ${reply.error.kind}`, reply.error);
     }
+    /** Retrieves the next cursor page of an executing query. Needs the
+     * `cursorPaging` capability. */
+    async queryPage(executionId, cursor, deadlineMicros) {
+        const capabilities = await this.capabilities();
+        if (!capabilities.query.cursorPaging) {
+            throw new UnsupportedError("query cursor paging is not advertised by this deployment", {
+                surface: "query",
+                feature: "cursor_paging"
+            });
+        }
+        const reply = await executeManaged(this.managedTransport(), capabilities, QueryPageCommand, {
+            v: QUERY_OP_VERSION,
+            executionId,
+            cursor,
+            deadlineMicros
+        });
+        if (reply.kind === "ok") {
+            if (reply.result.context.executionId.asU128() !== executionId.asU128()) {
+                throw new ProtocolError("query reply execution id does not match the request");
+            }
+            return reply.result;
+        }
+        throw new QueryExecutionError(`query page failed: ${reply.error.kind}`, reply.error);
+    }
+    /** Reads the current state of an executing or recently completed query. */
     async queryStatus(executionId) {
         const capabilities = await this.capabilities();
         if (!capabilities.query.executionStatus) {
-            throw new UnsupportedError("query execution status is not served by this deployment");
+            throw new UnsupportedError("query execution status is not served by this deployment", {
+                surface: "query",
+                feature: "execution_status"
+            });
         }
         const reply = await executeManaged(this.managedTransport(), capabilities, QueryStatusCommand, {
             v: QUERY_OP_VERSION,
             executionId
         });
-        if (reply.kind === "ok")
+        if (reply.kind === "ok") {
+            if (reply.status.executionId.asU128() !== executionId.asU128()) {
+                throw new ProtocolError("query status execution id does not match the request");
+            }
             return reply.status;
+        }
         throw new QueryExecutionError(`query status failed: ${reply.error.kind}`, reply.error);
     }
+    /** Cancels an executing query by its unguessable identity. */
     async cancelQuery(executionId) {
         const capabilities = await this.capabilities();
         if (!capabilities.query.cancellation) {
-            throw new UnsupportedError("query cancellation is not served by this deployment");
+            throw new UnsupportedError("query cancellation is not served by this deployment", {
+                surface: "query",
+                feature: "cancellation"
+            });
         }
         const reply = await executeManaged(this.managedTransport(), capabilities, QueryCancelCommand, {
             v: QUERY_OP_VERSION,
             executionId
         });
-        if (reply.kind === "ok")
+        if (reply.kind === "ok") {
+            if (reply.status.executionId.asU128() !== executionId.asU128()) {
+                throw new ProtocolError("query status execution id does not match the request");
+            }
             return reply.status;
+        }
         throw new QueryExecutionError(`query cancellation failed: ${reply.error.kind}`, reply.error);
     }
     /** Closes owned transport resources. Safe to call more than once. */
@@ -1036,6 +1121,7 @@ export class Laser {
                 }, () => undefined);
             }
             this.shared.replyHubs.clear();
+            await this.shared.leases.close();
             await closeProducerStatistics(this.transport);
             await this.observe("laser.close", { operation: "close" }, () => this.transport.close());
         })();