@honua/react 0.1.12 → 0.1.14

package/columnar/types.d.ts

@@ -0,0 +1,175 @@
+import type { ColumnarTelemetryOptions } from "./telemetry.js";
+/** Version discriminator for the first Honua columnar batch contract. */
+export declare const COLUMNAR_BATCH_VERSION: "1.0";
+/** Stable structured-clone discriminator for a columnar batch. */
+export declare const COLUMNAR_BATCH_KIND: "honua.columnar-batch";
+/** Stable structured-clone discriminator for a worker transfer message. */
+export declare const COLUMNAR_TRANSFER_KIND: "honua.columnar-transfer";
+/** Conservative defaults for one independently transferable batch. */
+export declare const DEFAULT_COLUMNAR_BATCH_MAX_ROWS = 1000000;
+export declare const DEFAULT_COLUMNAR_BATCH_MAX_BACKING_BYTES: number;
+export declare const DEFAULT_COLUMNAR_BATCH_MAX_SCHEMA_NODES = 4096;
+export declare const DEFAULT_COLUMNAR_BATCH_MAX_METADATA_ENTRIES = 8192;
+export declare const DEFAULT_COLUMNAR_BATCH_MAX_BUFFER_VIEWS = 16384;
+export declare const DEFAULT_COLUMNAR_BATCH_MAX_STRING_BYTES: number;
+/**
+ * Adapter-declared logical type name. Adapters may use Arrow or GeoArrow names
+ * and metadata, but this Honua envelope does not itself define an Arrow memory
+ * layout or replace an Arrow schema.
+ */
+export interface ColumnarTypeV1 {
+    readonly name: string;
+    readonly parameters?: Readonly<Record<string, string | number | boolean>>;
+}
+/** Dependency-free field description carried with a Honua columnar batch. */
+export interface ColumnarFieldV1 {
+    readonly name: string;
+    readonly type: ColumnarTypeV1;
+    readonly nullable: boolean;
+    readonly children?: readonly ColumnarFieldV1[];
+    readonly metadata?: Readonly<Record<string, string>>;
+}
+/**
+ * A versioned schema identity and its dependency-free field descriptions.
+ * The id must change whenever field order, types, nullability, CRS, or
+ * extension metadata changes.
+ */
+export interface ColumnarSchemaV1 {
+    readonly id: string;
+    readonly fields: readonly ColumnarFieldV1[];
+    readonly metadata?: Readonly<Record<string, string>>;
+}
+/** Adapter-declared purpose of a buffer in the Honua envelope. */
+export type ColumnarBufferRole = "validity" | "offsets" | "type-ids" | "values" | "dictionary" | "geometry" | "custom";
+/**
+ * A view onto an owned transferable backing buffer. Multiple descriptors may
+ * reference the same `ArrayBuffer`; transfer and memory accounting deduplicate
+ * by backing-buffer identity.
+ */
+export interface ColumnarBufferV1 {
+    readonly id: string;
+    readonly role: ColumnarBufferRole;
+    /** Dot-separated field path when the buffer belongs to one field. */
+    readonly field?: string;
+    readonly data: ArrayBuffer;
+    readonly byteOffset: number;
+    readonly byteLength: number;
+}
+/** One deterministic sort key carried with a batch identity. */
+export interface ColumnarOrderingKeyV1 {
+    readonly field: string;
+    readonly direction: "ascending" | "descending";
+    readonly nulls: "first" | "last";
+}
+/**
+ * Ordering contract for pagination, cache reuse, renderer picking, and
+ * deterministic reconstruction after a worker transfer.
+ */
+export interface ColumnarOrderingV1 {
+    readonly stable: boolean;
+    readonly keys: readonly ColumnarOrderingKeyV1[];
+}
+/** Freshness validators captured when the producing source was observed. */
+export interface ColumnarFreshnessV1 {
+    /** RFC 3339 instant at which the source result was observed. */
+    readonly observedAt: string;
+    /** RFC 3339 instant after which the batch must be revalidated. */
+    readonly staleAfter?: string;
+    /** Opaque source validator, such as an HTTP ETag. */
+    readonly validator?: string;
+    /** Opaque monotonic source generation or revision. */
+    readonly generation?: string;
+}
+/**
+ * Identity required to safely reuse or render a columnar batch.
+ *
+ * `authorizationScope` is an opaque, non-secret scope fingerprint. Producers
+ * must never place a bearer token, API key, cookie, or credential in it.
+ */
+export interface ColumnarBatchIdentityV1 {
+    readonly sourceId: string;
+    readonly sourceVersion: string;
+    readonly schemaVersion: string;
+    readonly planId: string;
+    readonly authorizationScope: string;
+    readonly ordering: ColumnarOrderingV1;
+    readonly freshness: ColumnarFreshnessV1;
+}
+/** Input accepted by {@link createColumnarBatch}. */
+export interface CreateColumnarBatchInput {
+    readonly id: string;
+    readonly schema: ColumnarSchemaV1;
+    readonly rowCount: number;
+    readonly sequence: number;
+    readonly rowOffset?: number;
+    /** Cache/auth/order/freshness identity; required by normative adapters. */
+    readonly identity?: ColumnarBatchIdentityV1;
+    readonly buffers: readonly ColumnarBufferV1[];
+}
+/**
+ * Protocol-neutral, dependency-free transport representation of one columnar
+ * record batch. Adapters can reference existing Arrow/GeoArrow buffers and
+ * metadata, but consumers still need the originating adapter's layout contract.
+ */
+export interface ColumnarBatchV1 extends CreateColumnarBatchInput {
+    readonly kind: typeof COLUMNAR_BATCH_KIND;
+    readonly version: typeof COLUMNAR_BATCH_VERSION;
+}
+/** Explicit creation and transfer ceilings. There is no unbounded mode. */
+export interface ColumnarBatchLimits {
+    readonly maxRows?: number;
+    /** Counts complete unique backing buffers, not only referenced slices. */
+    readonly maxBackingBytes?: number;
+    /** Maximum total top-level and nested schema fields. */
+    readonly maxSchemaNodes?: number;
+    /** Maximum combined schema, field, and type-parameter entries. */
+    readonly maxMetadataEntries?: number;
+    /** Maximum number of buffer descriptors, including zero-byte/shared views. */
+    readonly maxBufferViews?: number;
+    /** Maximum UTF-8 bytes across descriptor identifiers, keys, and string values. */
+    readonly maxStringBytes?: number;
+}
+/** Exact payload-copy and backing-allocation accounting for a batch. */
+export interface ColumnarBatchMetrics {
+    readonly rows: number;
+    /** Sum of descriptor slice lengths; overlapping slices count separately. */
+    readonly logicalBytes: number;
+    /** Sum of `byteLength` for complete unique transferable backing buffers. */
+    readonly backingBytes: number;
+    /** Bytes relinquished when the transfer list is posted. */
+    readonly transferBytes: number;
+    /** Always zero: the SDK never slices or clones payload buffers. */
+    readonly copiedBytes: 0;
+    readonly bufferViews: number;
+    readonly backingBuffers: number;
+}
+/** Structured-clone-safe worker message paired with an exact transfer list. */
+export interface ColumnarTransferMessageV1 {
+    readonly kind: typeof COLUMNAR_TRANSFER_KIND;
+    readonly version: typeof COLUMNAR_BATCH_VERSION;
+    readonly batch: ColumnarBatchV1;
+    readonly metrics: ColumnarBatchMetrics;
+}
+export type ColumnarBatchLeaseState = "owned" | "transferring" | "transferred" | "disposed";
+export type ColumnarTransferErrorCode = "invalid-batch" | "row-limit-exceeded" | "memory-limit-exceeded" | "schema-limit-exceeded" | "metadata-limit-exceeded" | "buffer-view-limit-exceeded" | "string-limit-exceeded" | "already-leased" | "aborted" | "already-transferred" | "disposed" | "transport-failed";
+/** Typed failures for validation, ownership, cancellation, and transport. */
+export declare class HonuaColumnarTransferError extends Error {
+    readonly code: ColumnarTransferErrorCode;
+    constructor(code: ColumnarTransferErrorCode, message: string, options?: {
+        readonly cause?: unknown;
+    });
+}
+/** Synchronous ownership handoff plus optional asynchronous consumer ack. */
+export type ColumnarTransferTarget = (message: ColumnarTransferMessageV1, 
+/** Transfer list for an optional subsequent worker/port handoff. */
+transfer: readonly ArrayBuffer[]) => void | Promise<void>;
+export interface ColumnarTransferOptions extends ColumnarBatchLimits, ColumnarTelemetryOptions {
+    /** Cancellation is honored before the SDK performs its ownership handoff. */
+    readonly signal?: AbortSignal;
+}
+export interface ColumnarTransferReceipt {
+    readonly batchId: string;
+    readonly metrics: ColumnarBatchMetrics;
+    readonly acknowledged: true;
+}
+//# sourceMappingURL=types.d.ts.map

package/columnar/types.d.ts.map

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

package/columnar/types.js

@@ -0,0 +1,22 @@
+/** Version discriminator for the first Honua columnar batch contract. */
+export const COLUMNAR_BATCH_VERSION = "1.0";
+/** Stable structured-clone discriminator for a columnar batch. */
+export const COLUMNAR_BATCH_KIND = "honua.columnar-batch";
+/** Stable structured-clone discriminator for a worker transfer message. */
+export const COLUMNAR_TRANSFER_KIND = "honua.columnar-transfer";
+/** Conservative defaults for one independently transferable batch. */
+export const DEFAULT_COLUMNAR_BATCH_MAX_ROWS = 1_000_000;
+export const DEFAULT_COLUMNAR_BATCH_MAX_BACKING_BYTES = 64 * 1024 * 1024;
+export const DEFAULT_COLUMNAR_BATCH_MAX_SCHEMA_NODES = 4_096;
+export const DEFAULT_COLUMNAR_BATCH_MAX_METADATA_ENTRIES = 8_192;
+export const DEFAULT_COLUMNAR_BATCH_MAX_BUFFER_VIEWS = 16_384;
+export const DEFAULT_COLUMNAR_BATCH_MAX_STRING_BYTES = 1024 * 1024;
+/** Typed failures for validation, ownership, cancellation, and transport. */
+export class HonuaColumnarTransferError extends Error {
+    code;
+    constructor(code, message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.code = code;
+        this.name = "HonuaColumnarTransferError";
+    }
+}

package/columnar/worker.d.ts

@@ -0,0 +1,157 @@
+import { type ColumnarTelemetry } from "./telemetry.js";
+import { type ColumnarBatchLimits, type ColumnarBatchMetrics, type ColumnarBatchV1 } from "./types.js";
+export declare const COLUMNAR_WORKER_PROTOCOL_VERSION: "1.0";
+export declare const COLUMNAR_WORKER_REQUEST_KIND: "honua.columnar-worker.request";
+export declare const COLUMNAR_WORKER_CANCEL_KIND: "honua.columnar-worker.cancel";
+export declare const COLUMNAR_WORKER_PROGRESS_KIND: "honua.columnar-worker.progress";
+export declare const COLUMNAR_WORKER_RESULT_KIND: "honua.columnar-worker.result";
+export declare const COLUMNAR_WORKER_ERROR_KIND: "honua.columnar-worker.error";
+export type ColumnarWorkerSessionState = "idle" | "running" | "disposed";
+/**
+ * Cross-request ordering contract for one session. `none` treats every request
+ * as independent; `strict` requires one ordered batch stream.
+ */
+export type ColumnarWorkerStreamOrdering = "none" | "strict";
+export type ColumnarWorkerErrorCode = "invalid-request" | "invalid-response" | "unknown-operation" | "queue-full" | "aborted" | "operation-failed" | "worker-failed" | "disposed";
+export declare class HonuaColumnarWorkerError extends Error {
+    readonly code: ColumnarWorkerErrorCode;
+    constructor(code: ColumnarWorkerErrorCode, message: string, options?: {
+        readonly cause?: unknown;
+        readonly requestId?: string;
+        readonly operation?: string;
+    });
+    readonly requestId: string | undefined;
+    readonly operation: string | undefined;
+}
+export interface ColumnarWorkerMessageEvent {
+    readonly data: unknown;
+}
+export interface ColumnarWorkerFaultEvent {
+    readonly error?: unknown;
+    readonly message?: string;
+}
+/**
+ * Minimal transport seam implemented by a browser Worker, MessagePort adapter,
+ * or an application-owned worker wrapper. The factory owns CSP URL policy.
+ */
+export interface ColumnarWorkerTransport {
+    postMessage(message: unknown, transfer: readonly ArrayBuffer[]): void;
+    addEventListener(type: "message", listener: (event: ColumnarWorkerMessageEvent) => void): void;
+    addEventListener(type: "error", listener: (event: ColumnarWorkerFaultEvent) => void): void;
+    removeEventListener(type: "message", listener: (event: ColumnarWorkerMessageEvent) => void): void;
+    removeEventListener(type: "error", listener: (event: ColumnarWorkerFaultEvent) => void): void;
+    /** Must terminate or close the underlying worker/port. Idempotence is required. */
+    dispose(): void;
+}
+export type ColumnarWorkerFactory = () => ColumnarWorkerTransport | Promise<ColumnarWorkerTransport>;
+export interface ColumnarWorkerRequestV1 {
+    readonly kind: typeof COLUMNAR_WORKER_REQUEST_KIND;
+    readonly version: typeof COLUMNAR_WORKER_PROTOCOL_VERSION;
+    readonly requestId: string;
+    readonly operation: string;
+    readonly batch: ColumnarBatchV1;
+    readonly metrics: ColumnarBatchMetrics;
+}
+export interface ColumnarWorkerCancelV1 {
+    readonly kind: typeof COLUMNAR_WORKER_CANCEL_KIND;
+    readonly version: typeof COLUMNAR_WORKER_PROTOCOL_VERSION;
+    readonly requestId: string;
+}
+export interface ColumnarWorkerProgressV1 {
+    readonly kind: typeof COLUMNAR_WORKER_PROGRESS_KIND;
+    readonly version: typeof COLUMNAR_WORKER_PROTOCOL_VERSION;
+    readonly requestId: string;
+    readonly fraction: number;
+    readonly stage?: string;
+}
+export interface ColumnarWorkerResultV1 {
+    readonly kind: typeof COLUMNAR_WORKER_RESULT_KIND;
+    readonly version: typeof COLUMNAR_WORKER_PROTOCOL_VERSION;
+    readonly requestId: string;
+    readonly batch: ColumnarBatchV1;
+    readonly metrics: ColumnarBatchMetrics;
+}
+export interface ColumnarWorkerErrorV1 {
+    readonly kind: typeof COLUMNAR_WORKER_ERROR_KIND;
+    readonly version: typeof COLUMNAR_WORKER_PROTOCOL_VERSION;
+    readonly requestId: string;
+    readonly code: "invalid-request" | "unknown-operation" | "aborted" | "operation-failed";
+    readonly message: string;
+}
+export interface ColumnarWorkerExecutionProgress {
+    readonly requestId: string;
+    readonly fraction: number;
+    readonly stage?: string;
+}
+export interface ColumnarWorkerExecutionResult {
+    readonly requestId: string;
+    readonly operation: string;
+    readonly batch: ColumnarBatchV1;
+    readonly inputMetrics: ColumnarBatchMetrics;
+    readonly outputMetrics: ColumnarBatchMetrics;
+}
+export interface ExecuteColumnarWorkerOperationOptions extends ColumnarBatchLimits {
+    readonly signal?: AbortSignal;
+    readonly onProgress?: (progress: ColumnarWorkerExecutionProgress) => void;
+}
+export interface CreateColumnarWorkerSessionOptions {
+    readonly createWorker: ColumnarWorkerFactory;
+    /** Includes the active request. Defaults to 16; there is no unbounded mode. */
+    readonly maxPendingRequests?: number;
+    /**
+     * Cross-request ordering contract. Defaults to `none`, which accepts every
+     * request independently. `strict` declares that this session carries one
+     * ordered batch stream and rejects a non-increasing `sequence` or a
+     * non-contiguous `rowOffset` before the batch is transferred.
+     */
+    readonly streamOrdering?: ColumnarWorkerStreamOrdering;
+    /**
+     * Milliseconds a cancelled in-flight request may take to be acknowledged by
+     * the worker before the transport is retired. Defaults to 50. A cooperative
+     * operation that observes its signal acknowledges well inside the window and
+     * keeps the worker warm; a non-cooperative one is retired at the deadline.
+     */
+    readonly cancelAcknowledgementMs?: number;
+    /**
+     * Optional observer for this session. Off by default. Every `execute` emits
+     * one `columnar-worker-operation` span spanning enqueue through settlement,
+     * and the ownership handoff it performs emits its own `columnar-transfer`
+     * span, both bound to the input batch's identity.
+     */
+    readonly telemetry?: ColumnarTelemetry;
+}
+export interface ColumnarWorkerSession {
+    readonly state: ColumnarWorkerSessionState;
+    readonly pendingRequests: number;
+    execute(operation: string, batch: ColumnarBatchV1, options?: ExecuteColumnarWorkerOperationOptions): Promise<ColumnarWorkerExecutionResult>;
+    dispose(): void;
+}
+export interface ColumnarWorkerOperationContext {
+    readonly requestId: string;
+    readonly signal: AbortSignal;
+    reportProgress(fraction: number, stage?: string): void;
+}
+export type ColumnarWorkerOperation = (batch: ColumnarBatchV1, context: ColumnarWorkerOperationContext) => ColumnarBatchV1 | Promise<ColumnarBatchV1>;
+export interface StartColumnarWorkerHostOptions {
+    readonly transport: ColumnarWorkerTransport;
+    readonly operations: Readonly<Record<string, ColumnarWorkerOperation>>;
+    readonly batchLimits?: ColumnarBatchLimits;
+    /** Defensive ceiling for direct protocol callers. Defaults to one. */
+    readonly maxActiveRequests?: number;
+}
+export interface ColumnarWorkerHost {
+    readonly activeRequests: number;
+    readonly disposed: boolean;
+    dispose(): void;
+}
+/**
+ * Create a lazy, serial worker session. Only one transferred request is active;
+ * queued batches stay caller-owned until dispatch. Cancelling active work
+ * settles the caller immediately and gives the worker a bounded window to
+ * acknowledge the cancellation; a worker that misses the window is retired so a
+ * non-cooperative operation cannot escape bounds.
+ */
+export declare function createColumnarWorkerSession(options: CreateColumnarWorkerSessionOptions): ColumnarWorkerSession;
+/** Register worker-local operations on a transport without importing a worker runtime. */
+export declare function startColumnarWorkerHost(options: StartColumnarWorkerHostOptions): ColumnarWorkerHost;
+//# sourceMappingURL=worker.d.ts.map

package/columnar/worker.d.ts.map

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