@neutron-build/nucleus 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tyler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,27 @@
+# @neutron-build/nucleus
+
+TypeScript client for the Nucleus database.
+
+14 data models over PostgreSQL wire protocol — SQL, KV, Vector, TimeSeries, Document, Graph, FTS, Geo, Blob, Streams, PubSub, Columnar, Datalog, CDC.
+
+## Installation
+
+```bash
+npm install @neutron-build/nucleus
+```
+
+## Usage
+
+```typescript
+import { createClient } from "@neutron-build/nucleus";
+import { query } from "@neutron-build/nucleus/sql";
+import { vectorSearch } from "@neutron-build/nucleus/vector";
+```
+
+## Documentation
+
+[neutron.build](https://neutron.build)
+
+## License
+
+MIT

package/dist/blob/index.d.ts

@@ -0,0 +1,42 @@
+import type { NucleusPlugin } from '../types.js';
+export interface BlobMeta {
+    key: string;
+    size: number;
+    contentType: string;
+    createdAt: Date;
+    metadata?: Record<string, string>;
+}
+export interface BlobPutOptions {
+    /** MIME content type (default `application/octet-stream`). */
+    contentType?: string;
+    /** Custom key/value metadata tags. */
+    metadata?: Record<string, string>;
+}
+export interface BlobModel {
+    /** Store a blob. `data` is a Uint8Array or a hex-encoded string. */
+    put(bucket: string, key: string, data: Uint8Array | string, opts?: BlobPutOptions): Promise<void>;
+    /** Retrieve a blob. Returns the decoded bytes and metadata, or `null`. */
+    get(bucket: string, key: string): Promise<{
+        data: Uint8Array;
+        meta: BlobMeta | null;
+    } | null>;
+    /** Delete a blob. Returns `true` if it existed. */
+    delete(bucket: string, key: string): Promise<boolean>;
+    /** Get metadata for a blob. */
+    meta(bucket: string, key: string): Promise<BlobMeta | null>;
+    /** Tag a blob with a key/value pair. */
+    tag(bucket: string, key: string, tagKey: string, tagValue: string): Promise<boolean>;
+    /** List blobs matching a prefix. */
+    list(bucket: string, prefix: string): Promise<BlobMeta[]>;
+    /** Check if a blob exists. */
+    exists(bucket: string, key: string): Promise<boolean>;
+    /** Return the total number of stored blobs. */
+    blobCount(): Promise<number>;
+    /** Return the deduplication ratio. */
+    dedupRatio(): Promise<number>;
+}
+/** Plugin: adds `.blob` to the client. */
+export declare const withBlob: NucleusPlugin<{
+    blob: BlobModel;
+}>;
+//# sourceMappingURL=index.d.ts.map

package/dist/blob/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/blob/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAa,aAAa,EAAmB,MAAM,aAAa,CAAC;AAO7E,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,IAAI,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,cAAc;IAC7B,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAMD,MAAM,WAAW,SAAS;IACxB,oEAAoE;IACpE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElG,0EAA0E;IAC1E,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,UAAU,CAAC;QAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;IAE9F,mDAAmD;IACnD,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEtD,+BAA+B;IAC/B,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;IAE5D,wCAAwC;IACxC,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAErF,oCAAoC;IACpC,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IAE1D,8BAA8B;IAC9B,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEtD,+CAA+C;IAC/C,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAE7B,sCAAsC;IACtC,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CAC/B;AAyID,0CAA0C;AAC1C,eAAO,MAAM,QAAQ,EAAE,aAAa,CAAC;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAKvD,CAAC"}

package/dist/blob/index.js

@@ -0,0 +1,121 @@
+// ---------------------------------------------------------------------------
+// @neutron/nucleus/blob — Blob storage model plugin
+// ---------------------------------------------------------------------------
+import { requireNucleus } from '../helpers.js';
+// ---------------------------------------------------------------------------
+// Hex helpers
+// ---------------------------------------------------------------------------
+function toHex(data) {
+    if (typeof data === 'string')
+        return data;
+    return Array.from(data)
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('');
+}
+function fromHex(hex) {
+    if (hex.length % 2 !== 0) {
+        throw new Error('Invalid hex string: odd length');
+    }
+    if (!/^[0-9a-fA-F]*$/.test(hex)) {
+        throw new Error('Invalid hex string: contains non-hex characters');
+    }
+    const bytes = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < bytes.length; i++) {
+        bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    }
+    return bytes;
+}
+function parseBlobMeta(raw) {
+    return {
+        key: raw.key,
+        size: raw.size,
+        contentType: raw.content_type,
+        createdAt: new Date(raw.created_at),
+        metadata: raw.metadata,
+    };
+}
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+class BlobModelImpl {
+    transport;
+    features;
+    constructor(transport, features) {
+        this.transport = transport;
+        this.features = features;
+    }
+    require() {
+        requireNucleus(this.features, 'Blob');
+    }
+    async put(bucket, key, data, opts = {}) {
+        this.require();
+        const fullKey = `${bucket}/${key}`;
+        const hexData = toHex(data);
+        const contentType = opts.contentType ?? 'application/octet-stream';
+        await this.transport.execute('SELECT BLOB_STORE($1, $2, $3)', [fullKey, hexData, contentType]);
+        if (opts.metadata) {
+            for (const [k, v] of Object.entries(opts.metadata)) {
+                await this.transport.execute('SELECT BLOB_TAG($1, $2, $3)', [fullKey, k, v]);
+            }
+        }
+    }
+    async get(bucket, key) {
+        this.require();
+        const fullKey = `${bucket}/${key}`;
+        const hexData = await this.transport.fetchval('SELECT BLOB_GET($1)', [fullKey]);
+        if (hexData === null)
+            return null;
+        const meta = await this.meta(bucket, key);
+        return { data: fromHex(hexData), meta };
+    }
+    async delete(bucket, key) {
+        this.require();
+        const fullKey = `${bucket}/${key}`;
+        return (await this.transport.fetchval('SELECT BLOB_DELETE($1)', [fullKey])) ?? false;
+    }
+    async meta(bucket, key) {
+        this.require();
+        const fullKey = `${bucket}/${key}`;
+        const raw = await this.transport.fetchval('SELECT BLOB_META($1)', [fullKey]);
+        if (!raw)
+            return null;
+        return parseBlobMeta(JSON.parse(raw));
+    }
+    async tag(bucket, key, tagKey, tagValue) {
+        this.require();
+        const fullKey = `${bucket}/${key}`;
+        return (await this.transport.fetchval('SELECT BLOB_TAG($1, $2, $3)', [fullKey, tagKey, tagValue])) ?? false;
+    }
+    async list(bucket, prefix) {
+        this.require();
+        const fullPrefix = `${bucket}/${prefix}`;
+        const raw = await this.transport.fetchval('SELECT BLOB_LIST($1)', [fullPrefix]);
+        if (!raw)
+            return [];
+        const items = JSON.parse(raw);
+        return items.map(parseBlobMeta);
+    }
+    async exists(bucket, key) {
+        const meta = await this.meta(bucket, key);
+        return meta !== null;
+    }
+    async blobCount() {
+        this.require();
+        return (await this.transport.fetchval('SELECT BLOB_COUNT()')) ?? 0;
+    }
+    async dedupRatio() {
+        this.require();
+        return (await this.transport.fetchval('SELECT BLOB_DEDUP_RATIO()')) ?? 0;
+    }
+}
+// ---------------------------------------------------------------------------
+// Plugin
+// ---------------------------------------------------------------------------
+/** Plugin: adds `.blob` to the client. */
+export const withBlob = {
+    name: 'blob',
+    init(transport, features) {
+        return { blob: new BlobModelImpl(transport, features) };
+    },
+};
+//# sourceMappingURL=index.js.map

package/dist/blob/index.js.map

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

package/dist/cdc/index.d.ts

@@ -0,0 +1,14 @@
+import type { NucleusPlugin } from '../types.js';
+export interface CDCModel {
+    /** Read CDC events starting from the given offset. Returns raw JSON. */
+    read(offset: number): Promise<string>;
+    /** Return the total number of CDC events. */
+    count(): Promise<number>;
+    /** Read CDC events for a specific table starting from the given offset. */
+    tableRead(table: string, offset: number): Promise<string>;
+}
+/** Plugin: adds `.cdc` to the client. */
+export declare const withCDC: NucleusPlugin<{
+    cdc: CDCModel;
+}>;
+//# sourceMappingURL=index.d.ts.map

package/dist/cdc/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cdc/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAa,aAAa,EAAmB,MAAM,aAAa,CAAC;AAO7E,MAAM,WAAW,QAAQ;IACvB,wEAAwE;IACxE,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEtC,6CAA6C;IAC7C,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAEzB,2EAA2E;IAC3E,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC3D;AAoCD,yCAAyC;AACzC,eAAO,MAAM,OAAO,EAAE,aAAa,CAAC;IAAE,GAAG,EAAE,QAAQ,CAAA;CAAE,CAKpD,CAAC"}

package/dist/cdc/index.js

@@ -0,0 +1,41 @@
+// ---------------------------------------------------------------------------
+// @neutron/nucleus/cdc — Change Data Capture model plugin
+// ---------------------------------------------------------------------------
+import { requireNucleus } from '../helpers.js';
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+class CDCModelImpl {
+    transport;
+    features;
+    constructor(transport, features) {
+        this.transport = transport;
+        this.features = features;
+    }
+    require() {
+        requireNucleus(this.features, 'CDC');
+    }
+    async read(offset) {
+        this.require();
+        return (await this.transport.fetchval('SELECT CDC_READ($1)', [offset])) ?? '';
+    }
+    async count() {
+        this.require();
+        return (await this.transport.fetchval('SELECT CDC_COUNT()')) ?? 0;
+    }
+    async tableRead(table, offset) {
+        this.require();
+        return (await this.transport.fetchval('SELECT CDC_TABLE_READ($1, $2)', [table, offset])) ?? '';
+    }
+}
+// ---------------------------------------------------------------------------
+// Plugin
+// ---------------------------------------------------------------------------
+/** Plugin: adds `.cdc` to the client. */
+export const withCDC = {
+    name: 'cdc',
+    init(transport, features) {
+        return { cdc: new CDCModelImpl(transport, features) };
+    },
+};
+//# sourceMappingURL=index.js.map

package/dist/cdc/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cdc/index.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,0DAA0D;AAC1D,8EAA8E;AAG9E,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAiB/C,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E,MAAM,YAAY;IAEG;IACA;IAFnB,YACmB,SAAoB,EACpB,QAAyB;QADzB,cAAS,GAAT,SAAS,CAAW;QACpB,aAAQ,GAAR,QAAQ,CAAiB;IACzC,CAAC;IAEI,OAAO;QACb,cAAc,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IACvC,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,MAAc;QACvB,IAAI,CAAC,OAAO,EAAE,CAAC;QACf,OAAO,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAS,qBAAqB,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACxF,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,OAAO,EAAE,CAAC;QACf,OAAO,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAS,oBAAoB,CAAC,CAAC,IAAI,CAAC,CAAC;IAC5E,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,KAAa,EAAE,MAAc;QAC3C,IAAI,CAAC,OAAO,EAAE,CAAC;QACf,OAAO,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAS,+BAA+B,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACzG,CAAC;CACF;AAED,8EAA8E;AAC9E,SAAS;AACT,8EAA8E;AAE9E,yCAAyC;AACzC,MAAM,CAAC,MAAM,OAAO,GAAqC;IACvD,IAAI,EAAE,KAAK;IACX,IAAI,CAAC,SAAoB,EAAE,QAAyB;QAClD,OAAO,EAAE,GAAG,EAAE,IAAI,YAAY,CAAC,SAAS,EAAE,QAAQ,CAAC,EAAE,CAAC;IACxD,CAAC;CACF,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,59 @@
+import type { Transport, NucleusFeatures, NucleusPlugin } from './types.js';
+export interface NucleusClientConfig {
+    /** Base URL of the Nucleus (or PostgreSQL HTTP proxy) server. */
+    url: string;
+    /** Extra HTTP headers sent with every request. */
+    headers?: Record<string, string>;
+    /** Request timeout in milliseconds (default 30000). */
+    timeout?: number;
+    /** Override the default transport (e.g. for testing or explicit platform choice). */
+    transport?: Transport;
+    /** Maximum retry attempts for transient failures (default 3). */
+    maxRetries?: number;
+    /** Base delay in ms between retries — uses exponential backoff (default 1000). */
+    retryDelay?: number;
+    /** Time-to-live for cached SELECT results in ms (default 60000). */
+    cacheTTL?: number;
+    /** Whether to cache SELECT queries (default true on mobile). */
+    cacheEnabled?: boolean;
+    /** Whether to queue writes when offline (default true on mobile). */
+    offlineQueueEnabled?: boolean;
+    /** Maximum number of queued offline operations (default 100). */
+    maxQueueSize?: number;
+}
+/** The minimal client surface available before any plugins are applied. */
+export interface NucleusClientBase {
+    readonly transport: Transport;
+    readonly features: NucleusFeatures;
+    close(): Promise<void>;
+    ping(): Promise<void>;
+}
+/**
+ * A lazy builder that accumulates plugins via `.use()` then resolves them all
+ * at `.connect()` time. The return type of `.connect()` is the intersection of
+ * `NucleusClientBase` with every plugin's contribution `T`.
+ *
+ * ```ts
+ * const db = await createClient({ url: '...' })
+ *   .use(withSQL)
+ *   .use(withKV)
+ *   .connect();
+ *
+ * db.sql.query(...);
+ * db.kv.get(...);
+ * ```
+ */
+export interface NucleusClientBuilder<Acc> {
+    /** Register a plugin. Returns a new builder whose type includes `T`. */
+    use<T>(plugin: NucleusPlugin<T>): NucleusClientBuilder<Acc & T>;
+    /** Connect to the server, detect features, and initialise all plugins. */
+    connect(): Promise<NucleusClientBase & Acc>;
+}
+/**
+ * Create a new Nucleus client builder.
+ *
+ * Call `.use(plugin)` to add model support, then `.connect()` to establish the
+ * connection and resolve the fully-typed client.
+ */
+export declare function createClient(config: NucleusClientConfig): NucleusClientBuilder<Record<string, never>>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAQ5E,MAAM,WAAW,mBAAmB;IAClC,iEAAiE;IACjE,GAAG,EAAE,MAAM,CAAC;IACZ,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qFAAqF;IACrF,SAAS,CAAC,EAAE,SAAS,CAAC;IAItB,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kFAAkF;IAClF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,qEAAqE;IACrE,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,iEAAiE;IACjE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAMD,2EAA2E;AAC3E,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAMD;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,oBAAoB,CAAC,GAAG;IACvC,wEAAwE;IACxE,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,oBAAoB,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;IAEhE,0EAA0E;IAC1E,OAAO,IAAI,OAAO,CAAC,iBAAiB,GAAG,GAAG,CAAC,CAAC;CAC7C;AAgED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,mBAAmB,GAAG,oBAAoB,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAErG"}

package/dist/client.js

@@ -0,0 +1,68 @@
+// ---------------------------------------------------------------------------
+// Nucleus client — builder + `.use()` plugin composition
+// ---------------------------------------------------------------------------
+import { createTransport } from './transport.js';
+import { detectFeatures } from './features.js';
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+class ClientBuilder {
+    config;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    plugins;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    constructor(config, plugins = []) {
+        this.config = config;
+        this.plugins = plugins;
+    }
+    use(plugin) {
+        return new ClientBuilder(this.config, [...this.plugins, plugin]);
+    }
+    async connect() {
+        const transport = this.config.transport ?? createTransport({
+            url: this.config.url,
+            headers: this.config.headers,
+            timeout: this.config.timeout,
+            maxRetries: this.config.maxRetries,
+            retryDelay: this.config.retryDelay,
+            cacheTTL: this.config.cacheTTL,
+            cacheEnabled: this.config.cacheEnabled,
+            offlineQueueEnabled: this.config.offlineQueueEnabled,
+            maxQueueSize: this.config.maxQueueSize,
+        });
+        const features = await detectFeatures(transport);
+        // Base client object
+        const base = {
+            transport,
+            features,
+            close: () => transport.close(),
+            ping: () => transport.ping(),
+        };
+        // Merge plugin contributions into the base object
+        const reserved = new Set(['transport', 'features', 'close', 'ping']);
+        const client = base;
+        for (const plugin of this.plugins) {
+            const contribution = plugin.init(transport, features);
+            for (const key of Object.keys(contribution)) {
+                if (reserved.has(key)) {
+                    throw new Error(`Plugin "${plugin.name}" cannot override reserved property "${key}"`);
+                }
+            }
+            Object.assign(client, contribution);
+        }
+        return client;
+    }
+}
+// ---------------------------------------------------------------------------
+// Public factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a new Nucleus client builder.
+ *
+ * Call `.use(plugin)` to add model support, then `.connect()` to establish the
+ * connection and resolve the fully-typed client.
+ */
+export function createClient(config) {
+    return new ClientBuilder(config);
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,yDAAyD;AACzD,8EAA8E;AAG9E,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAuE/C,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E,MAAM,aAAa;IACA,MAAM,CAAsB;IAC7C,8DAA8D;IAC7C,OAAO,CAAuB;IAE/C,8DAA8D;IAC9D,YAAY,MAA2B,EAAE,UAAgC,EAAE;QACzE,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED,GAAG,CAAI,MAAwB;QAC7B,OAAO,IAAI,aAAa,CAAU,IAAI,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;IAC5E,CAAC;IAED,KAAK,CAAC,OAAO;QACX,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,IAAI,eAAe,CAAC;YACzD,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,GAAG;YACpB,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO;YAC5B,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO;YAC5B,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,UAAU;YAClC,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,UAAU;YAClC,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ;YAC9B,YAAY,EAAE,IAAI,CAAC,MAAM,CAAC,YAAY;YACtC,mBAAmB,EAAE,IAAI,CAAC,MAAM,CAAC,mBAAmB;YACpD,YAAY,EAAE,IAAI,CAAC,MAAM,CAAC,YAAY;SACvC,CAAC,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,cAAc,CAAC,SAAS,CAAC,CAAC;QAEjD,qBAAqB;QACrB,MAAM,IAAI,GAAsB;YAC9B,SAAS;YACT,QAAQ;YACR,KAAK,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,KAAK,EAAE;YAC9B,IAAI,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE;SAC7B,CAAC;QAEF,kDAAkD;QAClD,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;QACrE,MAAM,MAAM,GAAG,IAA+B,CAAC;QAC/C,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAClC,MAAM,YAAY,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;YACtD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,YAAsB,CAAC,EAAE,CAAC;gBACtD,IAAI,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;oBACtB,MAAM,IAAI,KAAK,CAAC,WAAW,MAAM,CAAC,IAAI,wCAAwC,GAAG,GAAG,CAAC,CAAC;gBACxF,CAAC;YACH,CAAC;YACD,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;QACtC,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;CACF;AAED,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,MAA2B;IACtD,OAAO,IAAI,aAAa,CAAC,MAAM,CAAC,CAAC;AACnC,CAAC"}

package/dist/columnar/index.d.ts

@@ -0,0 +1,20 @@
+import type { NucleusPlugin } from '../types.js';
+export interface ColumnarModel {
+    /** Insert a row into a columnar table. Returns `true` on success. */
+    insert(table: string, values: Record<string, unknown>): Promise<boolean>;
+    /** Return the number of rows in a columnar table. */
+    count(table: string): Promise<number>;
+    /** Return the sum of a numeric column. */
+    sum(table: string, column: string): Promise<number>;
+    /** Return the average of a numeric column. */
+    avg(table: string, column: string): Promise<number>;
+    /** Return the minimum value of a column. */
+    min(table: string, column: string): Promise<unknown>;
+    /** Return the maximum value of a column. */
+    max(table: string, column: string): Promise<unknown>;
+}
+/** Plugin: adds `.columnar` to the client. */
+export declare const withColumnar: NucleusPlugin<{
+    columnar: ColumnarModel;
+}>;
+//# sourceMappingURL=index.d.ts.map

package/dist/columnar/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/columnar/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAa,aAAa,EAAmB,MAAM,aAAa,CAAC;AAO7E,MAAM,WAAW,aAAa;IAC5B,qEAAqE;IACrE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEzE,qDAAqD;IACrD,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEtC,0CAA0C;IAC1C,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEpD,8CAA8C;IAC9C,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEpD,4CAA4C;IAC5C,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAErD,4CAA4C;IAC5C,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACtD;AA0DD,8CAA8C;AAC9C,eAAO,MAAM,YAAY,EAAE,aAAa,CAAC;IAAE,QAAQ,EAAE,aAAa,CAAA;CAAE,CAKnE,CAAC"}

package/dist/columnar/index.js

@@ -0,0 +1,60 @@
+// ---------------------------------------------------------------------------
+// @neutron/nucleus/columnar — Columnar analytics model plugin
+// ---------------------------------------------------------------------------
+import { requireNucleus, assertIdentifier } from '../helpers.js';
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+class ColumnarModelImpl {
+    transport;
+    features;
+    constructor(transport, features) {
+        this.transport = transport;
+        this.features = features;
+    }
+    require() {
+        requireNucleus(this.features, 'Columnar');
+    }
+    async insert(table, values) {
+        this.require();
+        assertIdentifier(table, 'table name');
+        const valuesJson = JSON.stringify(values);
+        return (await this.transport.fetchval('SELECT COLUMNAR_INSERT($1, $2)', [table, valuesJson])) ?? false;
+    }
+    async count(table) {
+        this.require();
+        assertIdentifier(table, 'table name');
+        return (await this.transport.fetchval('SELECT COLUMNAR_COUNT($1)', [table])) ?? 0;
+    }
+    async sum(table, column) {
+        this.require();
+        assertIdentifier(table, 'table name');
+        return (await this.transport.fetchval('SELECT COLUMNAR_SUM($1, $2)', [table, column])) ?? 0;
+    }
+    async avg(table, column) {
+        this.require();
+        assertIdentifier(table, 'table name');
+        return (await this.transport.fetchval('SELECT COLUMNAR_AVG($1, $2)', [table, column])) ?? 0;
+    }
+    async min(table, column) {
+        this.require();
+        assertIdentifier(table, 'table name');
+        return this.transport.fetchval('SELECT COLUMNAR_MIN($1, $2)', [table, column]);
+    }
+    async max(table, column) {
+        this.require();
+        assertIdentifier(table, 'table name');
+        return this.transport.fetchval('SELECT COLUMNAR_MAX($1, $2)', [table, column]);
+    }
+}
+// ---------------------------------------------------------------------------
+// Plugin
+// ---------------------------------------------------------------------------
+/** Plugin: adds `.columnar` to the client. */
+export const withColumnar = {
+    name: 'columnar',
+    init(transport, features) {
+        return { columnar: new ColumnarModelImpl(transport, features) };
+    },
+};
+//# sourceMappingURL=index.js.map

package/dist/columnar/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/columnar/index.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,8DAA8D;AAC9D,8EAA8E;AAG9E,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AA0BjE,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E,MAAM,iBAAiB;IAEF;IACA;IAFnB,YACmB,SAAoB,EACpB,QAAyB;QADzB,cAAS,GAAT,SAAS,CAAW;QACpB,aAAQ,GAAR,QAAQ,CAAiB;IACzC,CAAC;IAEI,OAAO;QACb,cAAc,CAAC,IAAI,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IAC5C,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,KAAa,EAAE,MAA+B;QACzD,IAAI,CAAC,OAAO,EAAE,CAAC;QACf,gBAAgB,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC;QACtC,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QAC1C,OAAO,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAU,gCAAgC,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC;IAClH,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,KAAa;QACvB,IAAI,CAAC,OAAO,EAAE,CAAC;QACf,gBAAgB,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC;QACtC,OAAO,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAS,2BAA2B,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAC5F,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,KAAa,EAAE,MAAc;QACrC,IAAI,CAAC,OAAO,EAAE,CAAC;QACf,gBAAgB,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC;QACtC,OAAO,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAS,6BAA6B,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACtG,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,KAAa,EAAE,MAAc;QACrC,IAAI,CAAC,OAAO,EAAE,CAAC;QACf,gBAAgB,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC;QACtC,OAAO,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAS,6BAA6B,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACtG,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,KAAa,EAAE,MAAc;QACrC,IAAI,CAAC,OAAO,EAAE,CAAC;QACf,gBAAgB,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC;QACtC,OAAO,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,6BAA6B,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC;IACjF,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,KAAa,EAAE,MAAc;QACrC,IAAI,CAAC,OAAO,EAAE,CAAC;QACf,gBAAgB,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC;QACtC,OAAO,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,6BAA6B,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC;IACjF,CAAC;CACF;AAED,8EAA8E;AAC9E,SAAS;AACT,8EAA8E;AAE9E,8CAA8C;AAC9C,MAAM,CAAC,MAAM,YAAY,GAA+C;IACtE,IAAI,EAAE,UAAU;IAChB,IAAI,CAAC,SAAoB,EAAE,QAAyB;QAClD,OAAO,EAAE,QAAQ,EAAE,IAAI,iBAAiB,CAAC,SAAS,EAAE,QAAQ,CAAC,EAAE,CAAC;IAClE,CAAC;CACF,CAAC"}

package/dist/datalog/index.d.ts

@@ -0,0 +1,20 @@
+import type { NucleusPlugin } from '../types.js';
+export interface DatalogModel {
+    /** Add a fact to the knowledge base. */
+    assert(fact: string): Promise<boolean>;
+    /** Remove a fact from the knowledge base. */
+    retract(fact: string): Promise<boolean>;
+    /** Define a rule with a head and body. */
+    rule(head: string, body: string): Promise<boolean>;
+    /** Evaluate a Datalog query pattern. Returns results as CSV text. */
+    query(pattern: string): Promise<string>;
+    /** Clear all facts and rules. */
+    clear(): Promise<boolean>;
+    /** Import the graph model into the Datalog knowledge base. Returns count of facts imported. */
+    importGraph(): Promise<number>;
+}
+/** Plugin: adds `.datalog` to the client. */
+export declare const withDatalog: NucleusPlugin<{
+    datalog: DatalogModel;
+}>;
+//# sourceMappingURL=index.d.ts.map

package/dist/datalog/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/datalog/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAa,aAAa,EAAmB,MAAM,aAAa,CAAC;AAO7E,MAAM,WAAW,YAAY;IAC3B,wCAAwC;IACxC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEvC,6CAA6C;IAC7C,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAExC,0CAA0C;IAC1C,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEnD,qEAAqE;IACrE,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAExC,iCAAiC;IACjC,KAAK,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAE1B,+FAA+F;IAC/F,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CAChC;AAmDD,6CAA6C;AAC7C,eAAO,MAAM,WAAW,EAAE,aAAa,CAAC;IAAE,OAAO,EAAE,YAAY,CAAA;CAAE,CAKhE,CAAC"}

package/dist/datalog/index.js

@@ -0,0 +1,53 @@
+// ---------------------------------------------------------------------------
+// @neutron/nucleus/datalog — Datalog reasoning model plugin
+// ---------------------------------------------------------------------------
+import { requireNucleus } from '../helpers.js';
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+class DatalogModelImpl {
+    transport;
+    features;
+    constructor(transport, features) {
+        this.transport = transport;
+        this.features = features;
+    }
+    require() {
+        requireNucleus(this.features, 'Datalog');
+    }
+    async assert(fact) {
+        this.require();
+        return (await this.transport.fetchval('SELECT DATALOG_ASSERT($1)', [fact])) ?? false;
+    }
+    async retract(fact) {
+        this.require();
+        return (await this.transport.fetchval('SELECT DATALOG_RETRACT($1)', [fact])) ?? false;
+    }
+    async rule(head, body) {
+        this.require();
+        return (await this.transport.fetchval('SELECT DATALOG_RULE($1, $2)', [head, body])) ?? false;
+    }
+    async query(pattern) {
+        this.require();
+        return (await this.transport.fetchval('SELECT DATALOG_QUERY($1)', [pattern])) ?? '';
+    }
+    async clear() {
+        this.require();
+        return (await this.transport.fetchval('SELECT DATALOG_CLEAR()')) ?? false;
+    }
+    async importGraph() {
+        this.require();
+        return (await this.transport.fetchval('SELECT DATALOG_IMPORT_GRAPH()')) ?? 0;
+    }
+}
+// ---------------------------------------------------------------------------
+// Plugin
+// ---------------------------------------------------------------------------
+/** Plugin: adds `.datalog` to the client. */
+export const withDatalog = {
+    name: 'datalog',
+    init(transport, features) {
+        return { datalog: new DatalogModelImpl(transport, features) };
+    },
+};
+//# sourceMappingURL=index.js.map

package/dist/datalog/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/datalog/index.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,4DAA4D;AAC5D,8EAA8E;AAG9E,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AA0B/C,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E,MAAM,gBAAgB;IAED;IACA;IAFnB,YACmB,SAAoB,EACpB,QAAyB;QADzB,cAAS,GAAT,SAAS,CAAW;QACpB,aAAQ,GAAR,QAAQ,CAAiB;IACzC,CAAC;IAEI,OAAO;QACb,cAAc,CAAC,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IAC3C,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,IAAY;QACvB,IAAI,CAAC,OAAO,EAAE,CAAC;QACf,OAAO,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAU,2BAA2B,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC;IAChG,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,IAAY;QACxB,IAAI,CAAC,OAAO,EAAE,CAAC;QACf,OAAO,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAU,4BAA4B,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC;IACjG,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,IAAY,EAAE,IAAY;QACnC,IAAI,CAAC,OAAO,EAAE,CAAC;QACf,OAAO,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAU,6BAA6B,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC;IACxG,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,OAAe;QACzB,IAAI,CAAC,OAAO,EAAE,CAAC;QACf,OAAO,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAS,0BAA0B,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC9F,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,OAAO,EAAE,CAAC;QACf,OAAO,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAU,wBAAwB,CAAC,CAAC,IAAI,KAAK,CAAC;IACrF,CAAC;IAED,KAAK,CAAC,WAAW;QACf,IAAI,CAAC,OAAO,EAAE,CAAC;QACf,OAAO,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAS,+BAA+B,CAAC,CAAC,IAAI,CAAC,CAAC;IACvF,CAAC;CACF;AAED,8EAA8E;AAC9E,SAAS;AACT,8EAA8E;AAE9E,6CAA6C;AAC7C,MAAM,CAAC,MAAM,WAAW,GAA6C;IACnE,IAAI,EAAE,SAAS;IACf,IAAI,CAAC,SAAoB,EAAE,QAAyB;QAClD,OAAO,EAAE,OAAO,EAAE,IAAI,gBAAgB,CAAC,SAAS,EAAE,QAAQ,CAAC,EAAE,CAAC;IAChE,CAAC;CACF,CAAC"}