@cognica-io/uqa-wasm 0.1.6

package/LICENSES/UQA-FOSS-EXCEPTION-1.0.txt

@@ -0,0 +1,85 @@
+UQA Engine FOSS Exception
+Version 1.0, 3 August 2026
+
+Copyright (c) 2023-2026 Cognica, Inc.
+
+This Exception is an additional permission under section 7 of the GNU Affero
+General Public License version 3 (the "AGPL"). It applies only to UQA Engine
+material for which Cognica, Inc. has authority to grant this permission (the
+"Program") and that is distributed with a notice referring to this Exception.
+
+1. Definitions
+
+"Application" means a work, other than the Program, that uses the Program
+through a documented interface. Interfaces include Rust crate interfaces,
+application binary interfaces, static or dynamic linking, foreign-function
+interfaces, inter-process interfaces, language bindings, module imports, and
+WebAssembly imports or bundling.
+
+"Qualifying FOSS Application" means an Application for which:
+
+  a. the complete source code of the Application is made available under one
+     or more licenses approved by the Open Source Initiative at the time the
+     Application is conveyed or made available for remote use;
+
+  b. the source provided is the form preferred for making modifications and
+     includes the material reasonably required to build and run the
+     Application, excluding the Program, System Libraries as defined by the
+     AGPL, and unmodified third-party dependencies under their own licenses;
+     and
+
+  c. the Application is not merely a nominal or thin open-source wrapper whose
+     effective function is supplied by proprietary application code combined
+     with, loaded by, controlled by, or specifically designed for that
+     wrapper.
+
+"Combined Work" means a work formed by combining the Program with a
+Qualifying FOSS Application through one or more Interfaces.
+
+2. Additional permission
+
+To the extent permitted by the applicable license or licenses of the
+Qualifying FOSS Application, you may combine the Program with that Application
+and run, reproduce, and convey the resulting Combined Work without applying
+the AGPL to the independent code of the Qualifying FOSS Application solely
+because of that combination. The independent application code may remain
+under its applicable OSI-approved license or licenses.
+
+You may reproduce the minimum interface declarations reasonably necessary to
+perform that combination without changing the license of the independent
+application code. This permission does not extend to copied implementation
+code from the Program.
+
+3. Conditions and retained obligations
+
+This Exception does not relicense the Program. The Program, modifications to
+the Program, and Program implementation code copied into another work remain
+governed by the AGPL. All AGPL obligations that apply to those portions,
+including corresponding-source and remote-network-interaction obligations,
+remain in force.
+
+When conveying or making a Combined Work available under this Exception, you
+must provide a copy of this Exception with the licensing notices for the
+Program and identify the Program portions as AGPL-3.0-only with this additional
+permission.
+
+No permission is granted for a proprietary Application, for an Application
+whose complete source is not available as required above, or for proprietary
+modules that form part of the effective Application. If the requirements of
+this Exception are not met, no additional permission is granted; rights that
+you otherwise have under the AGPL remain unaffected.
+
+This Exception grants permission only from the copyright holders of the
+Program. It does not alter the license of the Qualifying FOSS Application or
+guarantee that the Application's license permits the proposed combination.
+
+4. No trademark or third-party grant
+
+This Exception grants no right to use Cognica or UQA trademarks. It grants no
+right in third-party material included with or used by the Program.
+
+5. Removal
+
+You may remove this additional permission from a copy or modified version as
+allowed by section 7 of the AGPL. A copy from which it has been removed remains
+available under the AGPL without this Exception.

package/LICENSES/UQA-NONCOMMERCIAL-EXCEPTION-1.0.txt

@@ -0,0 +1,96 @@
+UQA Engine Noncommercial Application Exception
+Version 1.0, 3 August 2026
+
+Copyright (c) 2023-2026 Cognica, Inc.
+
+This Exception is an additional permission under section 7 of the GNU Affero
+General Public License version 3 (the "AGPL"). It applies only to UQA Engine
+material for which Cognica, Inc. has authority to grant this permission (the
+"Program") and that is distributed with a notice referring to this Exception.
+
+The AGPL itself permits commercial use. This Exception does not prohibit,
+limit, or charge for any activity already permitted by the AGPL. It grants an
+optional additional permission only for the qualifying uses defined below.
+
+1. Definitions
+
+"Application" means a work, other than the Program, that uses the Program
+through a documented interface. Interfaces include Rust crate interfaces,
+application binary interfaces, static or dynamic linking, foreign-function
+interfaces, inter-process interfaces, language bindings, module imports, and
+WebAssembly imports or bundling.
+
+"Eligible User" means:
+
+  a. a natural person acting only on that person's own behalf;
+
+  b. an accredited educational institution or public research institution;
+     or
+
+  c. a nonprofit or charitable organization that does not distribute profits
+     to private owners or shareholders.
+
+"Noncommercial Purpose" means personal learning, teaching, independent
+academic research, reproducibility research, or charitable research that:
+
+  a. is not performed for direct or indirect monetary compensation or
+     commercial advantage;
+
+  b. does not support production operations, customer workloads, paid
+     consulting, advertising, subscriptions, sales, licensing, or another
+     revenue-generating activity;
+
+  c. is not development, testing, or evaluation of a product or service that
+     is intended for commercial use; and
+
+  d. is not performed for a for-profit sponsor that receives proprietary,
+     exclusive, or preferential rights in the work or its results.
+
+"Qualifying Noncommercial Application" means an Application used and, if
+applicable, conveyed by an Eligible User solely for a Noncommercial Purpose.
+
+2. Additional permission
+
+An Eligible User may combine the Program with a Qualifying Noncommercial
+Application and use, reproduce, and convey the resulting combination without
+applying the AGPL to the independent code of that Application solely because
+of that combination. The independent application code may remain private or
+under terms chosen by its copyright holder.
+
+You may reproduce the minimum interface declarations reasonably necessary to
+perform that combination without changing the license of the independent
+application code. This permission does not extend to copied implementation
+code from the Program.
+
+3. Conditions and retained obligations
+
+This Exception does not relicense the Program. The Program, modifications to
+the Program, and Program implementation code copied into another work remain
+governed by the AGPL. All AGPL obligations that apply to those portions,
+including corresponding-source and remote-network-interaction obligations,
+remain in force.
+
+When conveying an application under this Exception, you must provide a copy of
+this Exception with the licensing notices for the Program and identify the
+Program portions as AGPL-3.0-only with this additional permission.
+
+Each user and each use must independently satisfy the definitions above. If a
+user or use ceases to qualify, this additional permission no longer applies to
+that use. The user may continue under the AGPL or under separate written terms
+from Cognica. Rights that the user otherwise has under the AGPL remain
+unaffected.
+
+Use by a for-profit entity, government operational use, paid or commercially
+sponsored research, and commercial evaluation are not presumed to qualify.
+They require compliance with the AGPL or separate written terms from Cognica.
+
+4. No trademark or third-party grant
+
+This Exception grants no right to use Cognica or UQA trademarks. It grants no
+right in third-party material included with or used by the Program.
+
+5. Removal
+
+You may remove this additional permission from a copy or modified version as
+allowed by section 7 of the AGPL. A copy from which it has been removed remains
+available under the AGPL without this Exception.

package/LICENSING.md

@@ -0,0 +1,81 @@
+# UQA Engine Licensing Policy
+
+Policy version 1.0, effective 2026-08-03.
+
+UQA Engine is open-source software licensed under the GNU Affero General Public License version 3 only (`AGPL-3.0-only`). Cognica, Inc. also provides two optional additional permissions and offers separate commercial terms. These alternatives do not revoke or reduce any right granted by the AGPL.
+
+The legal terms are the [AGPL license](LICENSE) and the applicable exception text. This document explains how the available paths are intended to work; it does not replace those terms.
+
+## Public-core commitment
+
+Code accepted into the public UQA Engine core will remain available under at least one license approved by the Open Source Initiative. A commercial license for a release does not withdraw, terminate, or narrow rights already granted for that release under an open-source license.
+
+## Available paths
+
+| Path | Who may use it | License of an independent application | License of UQA Engine and modifications to UQA Engine |
+| --- | --- | --- | --- |
+| AGPL | Anyone, including commercial users | Governed by the AGPL to the extent the AGPL applies | AGPL-3.0-only |
+| FOSS exception | A complete qualifying open-source application | May remain under its OSI-approved license | AGPL-3.0-only |
+| Noncommercial exception | A qualifying personal, educational, academic, or charitable application | May remain under terms chosen by its author | AGPL-3.0-only |
+| Commercial license | A customer with a signed agreement from Cognica | May remain proprietary as agreed | May remain proprietary as agreed |
+
+Commercial activity is not prohibited by the AGPL. A business may use UQA Engine without paying a fee if it complies with the AGPL or qualifies for the FOSS exception. A commercial license is an alternative for a customer that needs rights beyond those public terms.
+
+## 1. AGPL-3.0-only
+
+The AGPL is the default license for the complete repository and all published packages unless a file or package states otherwise. It permits use for any purpose, including commercial use, subject to its conditions.
+
+Use this path when the complete deployment and distribution can comply with the AGPL. The two public exceptions are optional; no one is required to use them.
+
+## 2. FOSS exception
+
+The [UQA Engine FOSS Exception](LICENSES/UQA-FOSS-EXCEPTION-1.0.txt) permits a qualifying application distributed with complete source under an OSI-approved license to combine with UQA Engine without changing the license of the application's independent code solely because of that combination.
+
+The exception covers ordinary integration mechanisms, including static or dynamic linking, Rust dependencies, foreign-function interfaces, language bindings, imports, and WebAssembly bundling. It does not relicense UQA Engine as Apache-2.0, MIT, MPL-2.0, or the application's license. UQA Engine, copied UQA Engine implementation code, and modifications to UQA Engine remain under the AGPL. The application's own license must also permit the proposed combination; OSI approval alone does not guarantee license compatibility in every direction.
+
+A commercial organization may use this exception when the complete application genuinely qualifies as open-source software. Publishing only a thin wrapper while keeping the effective application proprietary does not qualify.
+
+## 3. Noncommercial exception
+
+The [UQA Engine Noncommercial Application Exception](LICENSES/UQA-NONCOMMERCIAL-EXCEPTION-1.0.txt) permits a qualifying personal, educational, academic-research, or charitable application to keep its independent application code under terms chosen by its author.
+
+The exception does not permit UQA Engine itself or modifications to UQA Engine to become proprietary. It does not cover paid services, advertising or subscription-supported services, customer workloads, commercial product development, consulting, or research performed for a for-profit sponsor that receives proprietary or exclusive results.
+
+For-profit evaluation and proof-of-concept use are not automatically covered by this exception. Contact Cognica for written evaluation or commercial terms when the ordinary AGPL path is unsuitable.
+
+## 4. Commercial license
+
+Cognica offers separate commercial terms for proprietary applications, closed modifications, software-as-a-service deployments, OEM distribution, devices, appliances, and customers that require contractual support, warranties, or other assurances. See [COMMERCIAL.md](https://github.com/cognica-io/uqa-engine/blob/main/COMMERCIAL.md).
+
+A commercial license is granted only through a separate signed agreement. The public repository does not itself grant commercial-license rights.
+
+## Common cases
+
+| Scenario | Expected path |
+| --- | --- |
+| An AGPL service publishes its complete corresponding source | AGPL |
+| A company distributes a complete Apache-2.0 application that embeds UQA Engine | FOSS exception |
+| An individual builds a private, unpaid learning project | Noncommercial exception |
+| A university conducts independent academic research without proprietary sponsorship | Noncommercial exception |
+| A company evaluates UQA Engine internally under the AGPL | AGPL |
+| A proprietary SaaS product keeps its application and UQA Engine changes closed | Commercial license |
+| An OEM embeds UQA Engine in a closed product or device | Commercial license |
+| A proprietary product publishes only a thin open-source wrapper around UQA Engine | AGPL or commercial license; the FOSS exception does not apply |
+
+## Third-party software
+
+These terms apply only to material for which Cognica has authority to grant the stated rights. Dependencies, bundled libraries, data sets, models, and other third-party material remain governed by their own licenses and notices. A commercial agreement from Cognica does not replace third-party obligations.
+
+## Package metadata and distributions
+
+Cargo, Python, Node.js, and WebAssembly package metadata reports `AGPL-3.0-only` because the AGPL is the base open-source license. The two exceptions are additional permissions, not a choice to relicense UQA Engine under the application's license.
+
+Official source and registry distributions must carry a licensing notice that identifies this policy and the applicable exception texts. A copy that does not carry an exception notice remains available under the AGPL but does not grant that optional exception. Redistributors relying on an exception must include the applicable exception text as required by that exception.
+
+## Contributions
+
+Alternative licensing requires Cognica to retain sufficient rights in every accepted contribution. External copyrightable contributions of code or documentation are governed by [CONTRIBUTOR_POLICY.md](https://github.com/cognica-io/uqa-engine/blob/main/CONTRIBUTOR_POLICY.md). Issues, design discussion, bug reports, and other feedback that do not contribute copyrightable material do not require a contributor agreement.
+
+## Questions
+
+Licensing questions and requests for evaluation or commercial terms may be sent to `jaepil@cognica.io`. Obtain independent legal advice for a definitive interpretation of how a license applies to a particular product or deployment.

package/README.md

@@ -0,0 +1,27 @@
+# UQA for Browser WebAssembly
+
+`@cognica-io/uqa-wasm` provides the embedded UQA Engine and direct local or Cloud HTTP SQL for browser applications through WebAssembly.
+
+## Install
+
+```sh
+npm install @cognica-io/uqa-wasm
+```
+
+## Use
+
+```javascript
+import { Engine, UQA } from "@cognica-io/uqa-wasm";
+
+await UQA.load();
+const engine = await Engine.open(`${UQA.persistDir}/notes.uqa`);
+const result = await engine.sql("SELECT 1 AS n");
+console.log(result.rows);
+engine.close();
+```
+
+See the [UQA Engine manual](https://github.com/cognica-io/uqa-engine/blob/main/docs/manual/reference/08-bindings-and-extensions.md) for the complete Browser WASM binding contract.
+
+## License
+
+UQA Engine is licensed under AGPL-3.0-only with optional FOSS and noncommercial application exceptions. See `LICENSING.md` in this package.

package/index.d.ts

@@ -0,0 +1,259 @@
+//
+// Unified Query Algebra
+//
+// Copyright (c) 2023-2026 Cognica, Inc.
+//
+
+export type JSValue =
+  | null
+  | boolean
+  | number
+  | string
+  | Uint8Array
+  | JSValue[]
+  | { [key: string]: JSValue };
+
+export type ParamInput = SQLParam | JSValue;
+
+export type SQLFunctionVolatility = "volatile" | "stable" | "immutable";
+
+export interface SQLFunctionOptions {
+  volatility?: SQLFunctionVolatility;
+  mayMutateEngine?: boolean;
+}
+
+export type SQLTableFunctionRows = JSValue[][] | Array<Record<string, JSValue>>;
+
+export type SQLTableFunctionResult =
+  | { columns: string[]; rows: SQLTableFunctionRows }
+  | [string[], SQLTableFunctionRows];
+
+export type SQLAggregateState =
+  & ({ observe(...args: JSValue[]): unknown } | { step(...args: JSValue[]): unknown })
+  & ({ finish(): JSValue } | { finalize(): JSValue });
+
+export interface SQLResult {
+  columns: string[];
+  rows: Array<Record<string, JSValue>>;
+  affectedRows: number;
+}
+
+export interface HttpSQLExecution {
+  result: SQLResult;
+  requestId: string;
+}
+
+export interface HttpSQLBatchExecution {
+  results: SQLResult[];
+  requestId: string;
+}
+
+export type HttpSQLStreamFrame =
+  | { type: "metadata"; columns: string[]; rowCount: number; spilledToDisk: boolean; requestId: string }
+  | { type: "row"; row: Record<string, JSValue> }
+  | { type: "complete"; rowCount: number; requestId: string }
+  | { type: "error"; code: string; message: string; requestId: string };
+
+export declare class HttpEngineError extends Error {
+  readonly code?: string;
+  readonly status?: number;
+  readonly requestId?: string;
+}
+
+export declare class HttpSQLStream implements AsyncIterable<HttpSQLStreamFrame> {
+  readonly requestId: string;
+  nextFrame(): Promise<HttpSQLStreamFrame | null>;
+  [Symbol.asyncIterator](): AsyncIterator<HttpSQLStreamFrame>;
+}
+
+export declare class HttpEngine {
+  constructor(url: string, token: string);
+  static fromEnv(environment?: { UQA_URL?: string; UQA_TOKEN?: string }): HttpEngine;
+  sql(query: string, params?: ParamInput[]): Promise<SQLResult>;
+  sqlWithMetadata(query: string, params?: ParamInput[]): Promise<HttpSQLExecution>;
+  sqlBatch(statements: Array<[string, ParamInput[]]>): Promise<SQLResult[]>;
+  sqlBatchWithMetadata(statements: Array<[string, ParamInput[]]>): Promise<HttpSQLBatchExecution>;
+  sqlStream(query: string, params?: ParamInput[]): Promise<HttpSQLStream>;
+}
+
+export interface SearchHit {
+  docId: number;
+  score: number;
+}
+
+export interface SQLNotice {
+  level: string;
+  message: string;
+}
+
+export interface ReliabilityBin {
+  avgPredicted: number;
+  avgActual: number;
+  count: number;
+}
+
+export interface CalibrationReport {
+  ece: number;
+  brier: number;
+  logLoss: number;
+  bins: ReliabilityBin[];
+}
+
+export interface CompressionOptions {
+  codec?: string;
+  pageSize?: number;
+  chunkPages?: number;
+  level?: number;
+}
+
+/** Tagged SQL parameter (vector / tensor); scalars pass directly. */
+export declare class SQLParam {
+  static scalar(value: JSValue | bigint): SQLParam;
+  static vector(values: Float32Array | number[]): SQLParam;
+  static tensor(values: Array<Float32Array | number[]>): SQLParam;
+}
+
+export declare function vector(values: Float32Array | number[]): SQLParam;
+export declare function tensor(values: Array<Float32Array | number[]>): SQLParam;
+
+export declare const UQA: {
+  /** Preload the WASM module and restore persisted databases. */
+  load(): Promise<void>;
+  /** Flush every persistent database to IndexedDB; rejects when IndexedDB is unavailable. */
+  persist(): Promise<void>;
+  /** Directory on the virtual filesystem that persists to IndexedDB. */
+  persistDir: string;
+  detectDatabaseFile(
+    path: string
+  ): Promise<"missing" | "sqlite" | "compressed" | "compressed_encrypted" | "unrecognized">;
+};
+
+export declare class Engine {
+  /** Create an in-memory engine. */
+  static inMemory(): Promise<Engine>;
+  /**
+   * Open a persistent database on the virtual filesystem. Place it
+   * under `UQA.persistDir` and call `UQA.persist()` to survive page
+   * reloads. Encryption is not available in browser builds.
+   */
+  static open(path: string): Promise<Engine>;
+  static openAuto(path: string): Promise<Engine>;
+  static openCompressed(path: string, options?: CompressionOptions): Promise<Engine>;
+
+  /** Create an independent SQL session over the same persistent database. */
+  newSession(): Promise<Engine>;
+
+  sql(query: string, params?: ParamInput[]): Promise<SQLResult>;
+  sqlBatch(statements: Array<[string, ParamInput[]]>): Promise<SQLResult[]>;
+  /** Register a synchronous JavaScript scalar callback. Promise results are rejected. */
+  registerScalarFunction(
+    name: string,
+    callback: (...args: JSValue[]) => JSValue,
+    options?: SQLFunctionOptions
+  ): Promise<void>;
+  /** Register a synchronous JavaScript table callback. Promise results are rejected. */
+  registerTableFunction(
+    name: string,
+    callback: (...args: JSValue[]) => SQLTableFunctionResult,
+    options?: SQLFunctionOptions
+  ): Promise<void>;
+  /** Register a factory that creates one synchronous JavaScript state object per SQL group. */
+  registerAggregateFunction(
+    name: string,
+    factory: () => SQLAggregateState,
+    options?: SQLFunctionOptions
+  ): Promise<void>;
+  createDefaultTable(name: string, ftsFields: string[]): Promise<void>;
+  createVectorField(table: string, field: string, dimensions: number): Promise<boolean>;
+  addDocument(table: string, docId: number, document: Record<string, JSValue | bigint>): Promise<void>;
+  addDocumentWithVectors(
+    table: string,
+    docId: number,
+    document: Record<string, JSValue | bigint>,
+    vectors: Record<string, number[] | number[][]>
+  ): Promise<void>;
+  addVector(table: string, docId: number, field: string, vector: Float32Array | number[]): Promise<boolean>;
+  addVectorValues(
+    table: string,
+    docId: number,
+    field: string,
+    vectors: Array<Float32Array | number[]>
+  ): Promise<boolean>;
+  getDocument(table: string, docId: number): Promise<Record<string, JSValue> | null>;
+  deleteDocument(table: string, docId: number): Promise<void>;
+  documentCount(table: string): Promise<number>;
+  search(
+    table: string,
+    field: string,
+    query: string,
+    topK?: number,
+    scoring?: "bm25" | "bayesian"
+  ): Promise<SearchHit[]>;
+  knnSearch(table: string, field: string, vector: Float32Array | number[], topK?: number): Promise<SearchHit[]>;
+  vectorSimilaritySearch(
+    table: string,
+    field: string,
+    vector: Float32Array | number[],
+    threshold: number
+  ): Promise<SearchHit[]>;
+  hybridSearch(
+    table: string,
+    textField: string,
+    textQuery: string,
+    vectorField: string,
+    queryVector: Float32Array | number[],
+    topK?: number,
+    knnPool?: number
+  ): Promise<SearchHit[]>;
+  robustHybridSearch(
+    table: string,
+    textField: string,
+    textQuery: string,
+    vectorField: string,
+    queryVector: Float32Array | number[],
+    topK?: number,
+    knnPool?: number,
+    alpha?: number
+  ): Promise<SearchHit[]>;
+  estimateScoringParams(
+    table: string,
+    field: string,
+    nSamples?: number,
+    tokensPerQuery?: number,
+    seed?: number
+  ): Promise<Record<string, number>>;
+  learnScoringParams(
+    table: string,
+    field: string,
+    query: string,
+    labels: Array<0 | 1>
+  ): Promise<Record<string, number>>;
+  updateScoringParams(table: string, field: string, score: number, label: 0 | 1): Promise<void>;
+  calibrationReport(
+    table: string,
+    field: string,
+    query: string,
+    labels: Array<0 | 1>
+  ): Promise<CalibrationReport>;
+  saveScoringParams(name: string, params: Record<string, number>): Promise<void>;
+  loadScoringParams(name: string): Promise<Record<string, number> | null>;
+  loadAllScoringParams(): Promise<Record<string, Record<string, number>>>;
+  dropScoringParams(name: string): Promise<boolean>;
+  runCypher(graph: string, query: string, params?: Record<string, JSValue>): Promise<SQLResult>;
+  createGraph(name: string): Promise<boolean>;
+  dropGraph(name: string): Promise<boolean>;
+  listGraphs(): Promise<string[]>;
+  listPathIndexes(): Promise<string[]>;
+  tableNames(): Promise<string[]>;
+  listViews(): Promise<string[]>;
+  listSchemas(): Promise<string[]>;
+  listSequences(): Promise<string[]>;
+  listNamedAnalyzers(): Promise<string[]>;
+  listForeignServers(): Promise<string[]>;
+  listForeignTables(): Promise<string[]>;
+  takeSQLNotices(): Promise<SQLNotice[]>;
+  sqlFunctionDepthLimit(): Promise<number>;
+  setSQLFunctionDepthLimit(limit: number): Promise<void>;
+  cancel(): Promise<void>;
+  close(): Promise<void>;
+}