@laserdata/laser-sdk 0.0.1-rc.1 → 0.0.1-rc.3

package/README.md

@@ -1,11 +1,10 @@
 # Laser SDK for TypeScript
 
-The native TypeScript client for LaserData over Apache Iggy. It provides typed
-streaming, declared projections and query, key-value state, copy-on-write
-forks, a knowledge graph, and an optional agent runtime over one connection.
+The native TypeScript client for LaserData over Apache Iggy. It provides typed streaming, declared projections and query, key-value state, copy-on-write forks, a knowledge graph, and an optional agent runtime over one connection.
 
-This prerelease targets Node 22.14 or later. Bun, Deno, and browsers are not
-supported because the Apache Iggy transport uses Node TCP and TLS APIs.
+This prerelease targets Node 22.14 or later. Bun, Deno, and browsers are not supported because the Apache Iggy transport uses Node TCP and TLS APIs.
+
+> **Prerelease (`0.0.1-rc.3`).** Pin an exact version while the public API and wire contract are still in release-candidate development.
 
 ## Install
 
@@ -13,13 +12,48 @@ supported because the Apache Iggy transport uses Node TCP and TLS APIs.
 npm install @laserdata/laser-sdk
 ```
 
-The package is ESM-first. A CommonJS application can load it with dynamic
-`import()`.
+The package is ESM-first. A CommonJS application can load it with dynamic `import()`.
 
 ## Connect and stream
 
 ```ts
-import { Laser, jsonCodec } from "@laserdata/laser-sdk"
+import { Laser } from "@laserdata/laser-sdk"
+
+await using laser = await Laser.connect(
+  process.env.LASER_CONNECTION_STRING ?? "iggy:iggy@127.0.0.1:8090"
+)
+const topic = laser.stream("commerce").topic("orders")
+await topic.ensure(4)
+await topic.publish().json({ id: "order-1", total: 42 }).send()
+
+const records = await (await topic.replay()).poll()
+console.log(`read ${records.length} order(s)`)
+```
+
+Use the bare `user:password@host:port` connection string. The SDK supplies the Apache Iggy TCP scheme internally. One connection addresses every stream on the server. Select a stream explicitly with `laser.stream(name)`, then a topic with `.topic(name)`. `Laser.connectWithStream()` only pins a default stream so `laser.topic(name)` can be used as a shortcut. It does not limit the connection to that stream. `Laser.connectEnv()` reads `LASER_CONNECTION_STRING` and the optional `LASER_STREAM`. `Laser.local()` targets the default local server. `Laser.builder()` accepts a connection string, an address and credentials, or an injected Apache Iggy client with explicit owned or borrowed lifetime.
+
+Owned connections retry the initial handshake and reconnect after a dropped socket, with unlimited retries at one-second intervals by default. Set `reconnection_retries` to a non-negative integer and `reconnection_interval` to `250ms`, `1s`, or `1m` in the connection string to tune the policy. Laser owns this loop because the upstream Node reconnect path can leave its connect promise pending. An injected client remains under its caller's lifecycle and reconnect policy.
+
+LaserData Cloud hostnames automatically use TLS with the public LaserData root CA embedded in the package. `LASER_TLS_CERT` selects another CA file and `LASER_NO_TLS` disables automatic TLS. Other hosts keep the connection string's TLS settings unchanged.
+
+## Streaming model
+
+`laser.stream(name).topic(name)` addresses any stream. `laser.topic(name)` is the default-stream shortcut. Topics support:
+
+- raw, JSON, CBOR, MessagePack, Avro, Protobuf, and JSON Schema records
+- exact headers, metadata, indexes, projection and schema IDs, inline payload, claim-check, routing keys, explicit partitions, and heterogeneous batches
+- direct producers with bounded retry and explicit batching
+- standalone and consumer-group readers with first, last, next, offset, or timestamp starts
+- automatic or explicit offset commits, replay, cancellation, and bounded `nextWithin()` waits
+
+Delivery is at least once. Ordering is per selected partition. A handler should make external effects idempotent, or use the fenced managed coordination path when a monotonic holder token is required.
+
+## Runtime-checked records
+
+TypeScript types disappear at runtime. A typed topic therefore takes an explicit codec that validates decoded values instead of pretending a generic parameter can validate bytes.
+
+```ts
+import { jsonCodec } from "@laserdata/laser-sdk"
 
 interface Order {
   readonly id: string
@@ -27,118 +61,108 @@ interface Order {
 }
 
 const orderCodec = jsonCodec<Order>((value) => {
-  if (typeof value !== "object" || value === null) throw new Error("order must be an object")
+  if (typeof value !== "object" || value === null) throw new TypeError("order must be an object")
   const order = value as Record<string, unknown>
   if (typeof order.id !== "string" || typeof order.total !== "number") {
-    throw new Error("order has invalid fields")
+    throw new TypeError("order fields are invalid")
   }
   return { id: order.id, total: order.total }
 })
 
-const laser = await Laser.connectWithStream(
-  process.env.LASER_CONNECTION_STRING ?? "iggy://iggy:iggy@127.0.0.1:8090",
-  "commerce"
-)
-
-try {
-  const topic = laser.topic("orders")
-  await topic.ensure(4)
-  await topic.publish().json({ id: "order-1", total: 42 }, orderCodec).send()
+const orders = laser.stream("commerce").topic("orders").json(orderCodec)
+await orders.publish({ id: "order-1", total: 42 })
 
-  const record = await topic.json(orderCodec).records("orders-export").nextWithin(1_000)
-  console.log(record?.value)
-} finally {
-  await laser.close()
-}
+const reader = await orders.records("orders-export")
+const record = await reader.nextWithin(1_000)
+console.log(record?.value)
 ```
 
-Use `Laser.connect()` when no default stream is needed, `Laser.connectEnv()`
-for `LASER_CONNECTION_STRING` and `LASER_STREAM`, or `Laser.local()` for the
-default local server. `Laser.builder()` accepts a connection string, an address
-and credentials, or an injected Apache Iggy client with explicit owned or
-borrowed lifetime.
+Registered Avro, Protobuf, and JSON Schema topics compile the writer schema once, validate before transport I/O, stamp its schema ID, and decode through the same schema on reads.
 
-LaserData Cloud hostnames automatically use TLS with the public LaserData root
-CA embedded in the package. `LASER_TLS_CERT` selects another CA file and
-`LASER_NO_TLS` disables automatic TLS. Other hosts keep the connection string's
-TLS settings unchanged.
+## Managed data surfaces
 
-## Streaming model
+LaserData Cloud announces its capabilities during connection setup. Stock Apache Iggy serves streaming and returns `UnsupportedError` for managed calls. The same client code can feature-detect through `laser.capabilities()`.
 
-`laser.stream(name).topic(name)` addresses any stream. `laser.topic(name)` is
-the default-stream shortcut. Topics support:
+The root client exposes query, projections, bindings, schemas, key-value and CAS, forks, graph traversal, RBAC, runs, watch feeds, and independent managed command batches. Query uses the managed command path, not a request topic. Every command is encoded through the same Rust-owned AGDX fixtures consumed by the other SDKs.
 
-- raw, JSON, CBOR, MessagePack, Avro, Protobuf, and JSON Schema records
-- exact headers, metadata, indexes, projection and schema IDs, inline payload,
-  claim-check, routing keys, explicit partitions, and heterogeneous batches
-- direct producers with bounded retry and explicit batching
-- standalone and consumer-group readers with first, last, next, offset, or
-  timestamp starts
-- automatic or explicit offset commits, replay, cancellation, and bounded
-  `nextWithin()` waits
+```ts
+import { graphNodeEntity } from "@laserdata/laser-sdk"
 
-Delivery is at least once. Ordering is per selected partition. A handler should
-make external effects idempotent, or use the fenced managed coordination path
-when a monotonic holder token is required.
+const paid = await laser.query("orders_v1").whereEq("status", "paid").limit(20).fetch()
 
-## Managed data surfaces
+const key = new TextEncoder().encode("user:42")
+const session = { cart: ["sku-1"] }
+await laser.kv("sessions").set(key).json(session).ttl(300_000_000n).send()
+const stored = await laser.kv("sessions").get(key)
+
+const checkout = graphNodeEntity("Service", "checkout")
+const nearby = await laser.graph("ops").neighbors(checkout.id, "out", undefined, 2)
+```
+
+Accessors are cheap to construct. I/O happens at terminal verbs such as `send()`, `fetch()`, `poll()`, and `nextWithin()`.
 
-LaserData Cloud announces its capabilities during connection setup. Stock
-Apache Iggy serves streaming and returns `UnsupportedError` for managed calls.
-The same client code can feature-detect through `laser.capabilities()`.
+Durable memory can use the default audit topic through `laser.memory(namespace)`, an existing isolated topic through `laser.memoryOnTopic(topic)`, or a configured topic:
 
-The root client exposes query, projections, bindings, schemas, key-value and
-CAS, forks, graph traversal, RBAC, runs, watch feeds, and independent managed
-command batches. Query uses the managed command path, not a request topic.
-Every command is encoded through the same Rust-owned AGDX fixtures consumed by
-the other SDKs.
+```ts
+const incidents = await laser.memoryTopic("incidents").partitions(4).ttl(86_400_000).build()
+
+await incidents.remember(new TextEncoder().encode("checkout uses the read replica")).send()
+```
+
+TypeScript duration inputs use milliseconds. `noExpiry()` keeps the raw memory history until ordinary topic retention removes it.
 
 ## Agents and coordination
 
-The agent layer adds provenance, typed AGDX commands and responses, chunked
-streams, registry and presence, routing, reliable commit-after-handle delivery,
-deduplication, retry and dead-letter handling, contracts, scatter, and workflow
-execution. Workflow journals support replay and resume, verifier panels,
-budgets, compensation, and fenced steps.
+The agent layer adds provenance, typed AGDX commands and responses, chunked streams, registry and presence, routing, reliable commit-after-handle delivery, deduplication, retry and dead-letter handling, contracts, scatter, and workflow execution. Workflow journals support replay and resume, verifier panels, budgets, compensation, and fenced steps.
+
+Context, snapshots, log and vector memory, action governance, replayable intent decisions, Ed25519 signing, delegation, A2A, MCP, AG-UI, and edge authorization are available from the root package. The SDK transports model provenance but does not invoke a model.
+
+```ts
+import { Agent, AgentId, AgentTopic } from "@laserdata/laser-sdk"
+
+await using handle = Agent.builder()
+  .id(AgentId.new("support"))
+  .listenOn(AgentTopic.Commands)
+  .respondOn(AgentTopic.Responses)
+  .handler({
+    handle(message, context) {
+      return context.respond(message.payload)
+    }
+  })
+  .spawn(laser)
+
+await handle.ready()
+// The agent now consumes with commit-after-handle delivery.
+```
+
+Waiting operations accept `AbortSignal` or an explicit timeout where their contract permits one. Owned roots and spawned handles must be closed or shut down. Scoped views do not own the shared connection.
+
+## Errors and ownership
 
-Context, snapshots, log and vector memory, action governance, replayable
-intent decisions, Ed25519 signing, delegation, A2A, MCP, AG-UI, and edge
-authorization are available from the root package. The SDK transports model
-provenance but does not invoke a model.
+All SDK failures extend `LaserError` and carry a stable `kind`. Configuration, timeout, cancellation, unsupported managed capability, codec, transport, policy, and signature failures have dedicated subclasses. Catch the narrow subclass when recovery differs, otherwise report the base error with its cause.
 
-Waiting operations accept `AbortSignal` or an explicit timeout where their
-contract permits one. Owned roots and spawned handles must be closed or shut
-down. Scoped views do not own the shared connection.
+`Laser.connect*()` owns its Apache Iggy client. `Laser.builder()` can instead borrow or own an injected client explicitly. `Laser`, `Producer`, `Consumer`, and `AgentHandle` support `await using`. Their explicit `close()` and `shutdown()` methods remain idempotent. Closing a scoped view never closes the root connection.
 
 ## Package exports
 
 - `@laserdata/laser-sdk` is the ordinary application surface
 - `@laserdata/laser-sdk/full` adds the complete native wire namespace
-- `@laserdata/laser-sdk/testing` provides clocks, stores, fake transports,
-  factories, observers, and bounded eventually checks
+- `@laserdata/laser-sdk/testing` provides clocks, stores, fake transports, factories, observers, and bounded eventually checks
 - `@laserdata/laser-sdk/opentelemetry` adapts the observer seam to OpenTelemetry
 
-`laser.iggyClient()` is the Apache Iggy escape hatch for native administrative
-or transport operations that Laser does not wrap.
+`laser.iggyClient()` is the Apache Iggy escape hatch for native administrative or transport operations that Laser does not wrap.
 
 ## Examples and verification
 
-The nine non-benchmark examples live in
-[`examples/typescript`](../../examples/typescript/README.md). Shared behavior is
-covered by every feature under [`bdd/scenarios`](../../bdd/scenarios).
+The nine non-benchmark examples live in [`examples/typescript`](../../examples/typescript/README.md). Shared behavior is covered by every feature under [`bdd/scenarios`](../../bdd/scenarios).
 
 ```sh
 npm ci
 npm run verify
 ```
 
-`verify` runs style, formatting, lint, dependency boundaries, strict types,
-builds, API reports, unit and wire tests, robustness, coverage, licenses, and
-packed-consumer checks. Live Apache Iggy integration and shared BDD are separate
-Docker-backed gates.
+`verify` runs style, formatting, lint, dependency boundaries, strict types, builds, API reports, unit and wire tests, robustness, coverage, licenses, and packed-consumer checks. Live Apache Iggy integration and shared BDD are separate Docker-backed gates.
 
 ## Security and license
 
-Report security issues through the repository security policy. The package is
-Apache-2.0 licensed. Apache and Apache Iggy are trademarks of the Apache
-Software Foundation.
+Report security issues through the repository security policy. The package is Apache-2.0 licensed. Apache and Apache Iggy are trademarks of the Apache Software Foundation.

package/dist/agent/agdx.d.ts

@@ -0,0 +1,55 @@
+import { type BytesLike } from "../client/bytes.js";
+import type { LaserTransport } from "../iggy/apache-iggy.js";
+import { type UlidSource } from "../runtime/ulid.js";
+import { type SigningKey } from "../signing.js";
+import { type AgentId as SdkAgentId, type ConversationId as SdkConversationId } from "../types/ids.js";
+import { type AgentEnvelope, type AgentErrorBody, type IdempotencyKey, type TaskState, type TokenUsage } from "../wire/agent.js";
+import { ContentType } from "../wire/content.js";
+import { ChannelId, CorrelationId, type LogPosition, RecordId } from "../wire/ids.js";
+import type { Value } from "../wire/value.js";
+export declare const DEFAULT_CHUNK_FLUSH_BYTES = 512;
+export declare const DEFAULT_CHUNK_LINGER_MS = 20;
+export declare const MAX_CHUNK_BODY_BYTES: number;
+export type AgdxLogPosition = LogPosition;
+export interface Agdx {
+    readonly topicName: string;
+    command(correlation: CorrelationId, body: BytesLike): AgdxSend;
+    respond(correlation: CorrelationId, body: BytesLike): AgdxSend;
+    emit(body: BytesLike): AgdxSend;
+    status(operation: string): AgdxSend;
+    fail(correlation: CorrelationId, error: AgentErrorBody): AgdxSend;
+    stream(correlation: CorrelationId, purpose: string): AgdxStream;
+    requestInput(replyTopic: string, prompt: BytesLike, timeoutMs: number, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<Uint8Array>;
+}
+export declare function createAgdx(transport: LaserTransport, streamName: string, topicName: string, source: SdkAgentId, conversation: SdkConversationId, ulidSource?: UlidSource, govern?: (envelope: AgentEnvelope, willSign: boolean) => Promise<Uint8Array>): Agdx;
+export interface AgdxSend {
+    withTarget(target: SdkAgentId): this;
+    withCause(cause: RecordId, causeAt?: LogPosition): this;
+    withCorrelation(correlation: CorrelationId): this;
+    withIdempotencyKey(key: IdempotencyKey): this;
+    withDeadlineMicros(deadlineMicros: bigint): this;
+    withTaskState(state: TaskState): this;
+    withOperation(operation: string): this;
+    withTool(tool: string): this;
+    withUsage(usage: TokenUsage): this;
+    withMetadata(key: string, value: Value): this;
+    last(): this;
+    contentType(contentType: ContentType): this;
+    body(body: BytesLike): this;
+    signedBy(key: SigningKey): this;
+    send(): Promise<RecordId | undefined>;
+}
+export interface AgdxStream {
+    readonly channel: ChannelId;
+    withDeadlineMicros(deadlineMicros: bigint): this;
+    withTarget(target: SdkAgentId): this;
+    contentType(contentType: ContentType): this;
+    buffered(maxChunks: number, lingerMs: number): this;
+    write(body: BytesLike): Promise<void>;
+    flush(): Promise<void>;
+    finish(finishReason: string, usage?: TokenUsage): Promise<void>;
+    fail(error: AgentErrorBody): Promise<void>;
+}
+//# sourceMappingURL=agdx.d.ts.map

package/dist/agent/agdx.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agdx.d.ts","sourceRoot":"","sources":["../../src/agent/agdx.ts"],"names":[],"mappings":"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"}