@thyn-ai/sqai 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,555 @@
+import { MojoRuntimeConfig, MojoRuntime, QueryResponse, ResolveResponse, Runtime, ResolvedPlan, QueryWithMetadataResponse, VerifyResponse } from 'algenta-sdk';
+export { QueryResponse, ResolveResponse, ResolvedPlan } from 'algenta-sdk';
+
+/** Capability contract: the generated, hash-pinned inventory of everything
+ * SQAI exposes. Loaded from the vendored contracts/algenta-capabilities.json
+ * (synced hash-verified from the decision-engine generator). SQAI keeps no
+ * handwritten operation lists — this file is the only authority. */
+interface CapabilitySignatureParam {
+    name: string;
+    type: string;
+}
+interface CapabilityEntry {
+    name: string;
+    category: "query" | "aggregation" | "scalar_math" | "statistical" | "financial" | "datetime" | "vector_matrix" | "transformation" | "simulation" | "unsupported_internal" | "non_deterministic" | "write";
+    deterministic: boolean;
+    deterministic_when_seeded?: boolean;
+    seed_required?: boolean;
+    read_only: boolean;
+    typescript: boolean;
+    python: boolean;
+    ai_sdk: boolean;
+    summary?: string;
+    signature: {
+        params: CapabilitySignatureParam[];
+        returns: string;
+    };
+}
+interface CapabilityContract {
+    schema_version: number;
+    algenta_sdk_version: string;
+    algenta_core_version: string;
+    query_spec_version: string;
+    capability_contract_hash: string;
+    runtime_bundle: {
+        version: string;
+        platforms: Record<string, {
+            sha256: string;
+            url: string;
+        }>;
+    };
+    filter_operators?: string[];
+    time_filters?: string[];
+    capabilities: CapabilityEntry[];
+}
+interface CapabilityMatch {
+    entry: CapabilityEntry;
+    score: number;
+}
+/** all-readonly = (read_only AND deterministic) OR
+ *                 (read_only AND deterministic_when_seeded AND seed present) —
+ * seed presence is checked at validation time; this predicate answers whether
+ * the capability is ever eligible. */
+declare function isReadOnlyEligible(entry: CapabilityEntry): boolean;
+declare class ContractIndex {
+    readonly contract: CapabilityContract;
+    private readonly byName;
+    constructor(contract: CapabilityContract);
+    get(name: string): CapabilityEntry | undefined;
+    has(name: string): boolean;
+    /** Nearest capability names by token-normalized edit affinity — used for
+     * unsupported_operation remediation. */
+    nearest(name: string, limit?: number): string[];
+    search(query: string, limit?: number): CapabilityMatch[];
+}
+
+/** SQAI_* environment mapping and zero-config mode inference.
+ *
+ * Inference order (explicit config always overrides):
+ *   SQAI_ENGINE_URL present -> "self_hosted"
+ *   SQAI_API_KEY present    -> "api"
+ *   otherwise               -> "local"
+ */
+type SqaiMode = "local" | "api" | "self_hosted";
+
+/** Application policy: pre-execution validation the model can never override.
+ *
+ * SQAI validates; Algenta calculates. Package capability = the contract's
+ * all-readonly surface; application policy = the subset enabled here; a model
+ * request = one operation inside that subset.
+ */
+
+interface SqaiPolicy {
+    allowedSources?: string[];
+    /** Per-source field allowlist. */
+    allowedFields?: Record<string, string[]>;
+    /** "all-readonly" (default) or explicit "module.function" ids. */
+    allowedFunctions?: "all-readonly" | string[];
+}
+
+/** Embedded trust root for signed managed-runtime bundles.
+ *
+ * The provisioner only installs bundles whose manifest signature (RS256 —
+ * RSASSA-PKCS1-v1_5 + SHA-256 over the exact shipped manifest bytes) verifies
+ * against one of these keys. Revocation and rollback protection live here so
+ * a single release-process edit rotates the whole trust posture:
+ *
+ *   - TRUSTED_KEYS       the accepted verification keys (key_id + PEM)
+ *   - REVOKED_KEY_IDS    key_ids that must never verify again
+ *   - MIN_ACCEPTED_RUNTIME_VERSION
+ *                        the rollback floor: bundle manifests whose
+ *                        runtime_bundle_version compares below this are
+ *                        rejected (reason `rollback_protected`)
+ *
+ * Tests (and the release process) can override every value through
+ * RuntimeProvisioner options — nothing here is reachable from user input.
+ */
+interface TrustedKey {
+    key_id: string;
+    algorithm: "RS256";
+    public_key_pem: string;
+    /** ISO-8601 instant; key is not accepted before it. */
+    valid_from?: string;
+    /** ISO-8601 instant; key is not accepted after it. */
+    valid_to?: string;
+}
+
+/** Managed-runtime provisioning: zero-setup for the computation plane.
+ *
+ * The query plane never touches this module. On first computation-plane call:
+ *   1. Reuse a healthy daemon whose version matches the contract pin.
+ *   2. Otherwise verify + spawn the installed bundle for this platform.
+ *   3. Otherwise download the contract-pinned bundle (tarball sha256 + RS256
+ *      manifest against the embedded trust root — see runtime/trust.ts and
+ *      runtime/bundle.ts), extract atomically, spawn.
+ *
+ * Concurrency hardening: a per-version lock file (`<cacheDir>/<version>.lock`
+ * with `{pid, created_at}`) serializes installers across processes — fresh
+ * locks are poll-waited (max 90s) while re-checking for a completed install,
+ * stale locks (>10 min) are removed. Downloads land in `tmp-<random>` names,
+ * verification happens BEFORE extraction, extraction lands in a `tmp-<random>`
+ * directory that is atomically renamed into place, and every failure cleans
+ * its temp state — a partial install is never left behind.
+ */
+
+interface RuntimeStatus {
+    available: boolean;
+    runtime_available: boolean;
+    engine: string | null;
+    module_count: number;
+    platform: string;
+    managed: boolean;
+}
+interface ProvisionerOptions {
+    contract: CapabilityContract;
+    autoInstall: boolean;
+    /** Injection points for tests. */
+    runtimeFactory?: (config?: MojoRuntimeConfig) => MojoRuntime;
+    downloadBundle?: (url: string, destination: string) => Promise<void>;
+    /** Bundle cache directory (default: OS user cache — runtimeCacheDir()). */
+    cacheDir?: string;
+    /** Trust-root overrides (default: the embedded trust root). */
+    trustedKeys?: TrustedKey[];
+    revokedKeyIds?: string[];
+    minAcceptedRuntimeVersion?: string;
+    /** Lock policy overrides. */
+    lockFreshMs?: number;
+    lockWaitTimeoutMs?: number;
+    lockPollIntervalMs?: number;
+}
+declare function currentPlatformKey(): string;
+declare function runtimeCacheDir(): string;
+declare class RuntimeProvisioner {
+    private readonly options;
+    private readonly trustRoot;
+    private runtime;
+    private ensurePromise;
+    constructor(options: ProvisionerOptions);
+    /** Lazily resolve a usable runtime; concurrent callers share one attempt. */
+    ensure(): Promise<MojoRuntime>;
+    status(): Promise<RuntimeStatus>;
+    stop(): Promise<void>;
+    private newRuntime;
+    private cacheDir;
+    private doEnsure;
+    private provisionError;
+    private wrapVerificationError;
+    private manifestExpectations;
+    /** Verify an existing install if present; returns null when absent/invalid. */
+    private verifiedInstallOrNull;
+    private acquireLock;
+    private lockIsStale;
+    /** Serialize installers on `<cacheDir>/<version>.lock`; returns the verified install. */
+    private ensureInstalled;
+    /** Holder-of-the-lock path: download → verify → extract → atomic rename. */
+    private downloadVerifyExtract;
+    /** Spawn the installed bundle's daemon through MojoRuntime autoStart. */
+    private spawnInstalled;
+}
+
+/** Public SQAI types.
+ *
+ * Vocabulary rule: Algenta envelope field names pass through verbatim
+ * (plan_hash, schema_revision, intent_signature, deterministic_scope,
+ * decision_path, validated, engine_used, ...). SQAI never invents parallel
+ * names for the same concept.
+ */
+
+/** Contract-derived wire value: everything the computation plane can
+ * transport. The wire schema transports; the capability contract authorizes. */
+type AlgentaWireValue = null | boolean | number | string | AlgentaWireValue[] | {
+    [key: string]: AlgentaWireValue;
+} | {
+    type: "decimal" | "bigint";
+    value: string;
+};
+interface SqaiSource {
+    name: string;
+    source_id: string | null;
+    dataset_id: string | null;
+    fields: string[];
+    typed_fields: Array<{
+        name: string;
+        type: string;
+    }>;
+    row_count: number | null;
+    schema_revision: string | null;
+    status: string;
+}
+interface QueryFilterCondition {
+    column?: string;
+    dimension_hint?: string;
+    op: "eq" | "in" | "gt" | "gte" | "lt" | "lte" | "is_null" | "is_not_null";
+    value?: string | number | boolean;
+    values?: Array<string | number | boolean>;
+}
+interface QueryFilterSpec {
+    time_filter?: string;
+    conditions?: QueryFilterCondition[];
+}
+/** The caller/model-authored resolve-spec — Algenta names verbatim. */
+interface QuerySpec {
+    metric: string;
+    aggregation?: "sum" | "avg" | "count" | "min" | "max";
+    group_by?: string;
+    filter?: QueryFilterSpec;
+    limit?: number;
+    order?: "asc" | "desc";
+    source_name?: string;
+}
+type ComputationBinding = {
+    parameter: string | number;
+    source: string;
+    field: string;
+    filter?: QueryFilterSpec;
+} | {
+    parameters: Array<string | number>;
+    source: string;
+    fields: string[];
+    filter?: QueryFilterSpec;
+    alignment: "rowwise";
+    nullPolicy?: "pairwise" | "preserve";
+};
+interface ComputationSpec {
+    module: string;
+    function: string;
+    args?: AlgentaWireValue[];
+    kwargs?: Record<string, AlgentaWireValue>;
+    bindings?: ComputationBinding[];
+    seed?: number | string;
+}
+type SqaiIntent = {
+    version: "1";
+    kind: "query";
+    spec: QuerySpec;
+} | {
+    version: "1";
+    kind: "computation";
+    spec: ComputationSpec;
+};
+interface DeterminismEnvelope {
+    runtime_bundle_version: string;
+    runtime_bundle_sha256: string;
+    platform: string;
+    architecture: string;
+    kernel_build: string;
+    precision_mode: string;
+    thread_count: number;
+    seed?: number | string;
+    input_hash: string;
+}
+interface BindingProvenance {
+    source_name: string;
+    fields: string[];
+    schema_revision: string | null;
+    row_count: number;
+    input_hash: string;
+}
+interface ComputeResult {
+    status: "ok";
+    value: AlgentaWireValue;
+    value_type: string;
+    module: string;
+    function: string;
+    seed?: number | string;
+    invocation_hash: string;
+    computation_hash: string;
+    contract_hash: string;
+    determinism: DeterminismEnvelope;
+    provenance?: {
+        bindings: BindingProvenance[];
+    };
+    latency_ms: number;
+    request_id: string;
+}
+type AskOutcome = {
+    status: "ok";
+    data: QueryResponse;
+    resolution: ResolveResponse;
+} | {
+    status: "needs_clarification";
+    resolution: ResolveResponse;
+} | {
+    status: "rejected";
+    resolution: ResolveResponse;
+};
+type SqaiOutcome = {
+    kind: "query";
+    outcome: AskOutcome;
+} | {
+    kind: "computation";
+    outcome: ComputeResult;
+};
+interface ColumnExtract {
+    columns: Record<string, Array<number | null>>;
+    row_count: number;
+    source_name: string;
+    schema_revision: string | null;
+    alignment: "rowwise";
+    input_hash: string;
+}
+interface SqaiResultRecord {
+    result_id: string;
+    tenant_id: string | null;
+    source_ids: string[];
+    created_at: number;
+    expires_at: number;
+    byte_size: number;
+    value: unknown;
+}
+interface ResultStoreConfig {
+    ttlMs?: number;
+    maxResultCount?: number;
+    maxStoredResultBytes?: number;
+    maxTenantResultBytes?: number;
+}
+
+/** Computation dispatch: delegate a validated computation to Algenta.
+ *
+ * Local mode → the managed runtime daemon via algenta-sdk's MojoRuntime.
+ * self_hosted / api mode → POST {baseUrl}/v1/libraries/execute.
+ * SQAI performs no calculation of its own in either path.
+ */
+
+type DispatchTarget = {
+    kind: "local";
+    runtime: MojoRuntime;
+} | {
+    kind: "http";
+    baseUrl: string;
+    apiKey?: string;
+    fetchImpl?: typeof fetch;
+};
+
+/** The SQAI client: a thin, policy-checked facade over the Algenta runtime.
+ *
+ * Query plane   — connect / resolve / query / verify / ask, in-process.
+ * Computation   — validate against the capability contract, resolve bindings
+ *                 through the upstream aligned extraction primitive, delegate
+ *                 to the managed runtime, pass results through verbatim.
+ *
+ * SQAI reimplements nothing: every discrepancy is fixed upstream in Algenta.
+ */
+
+interface SqaiConfig {
+    mode?: SqaiMode;
+    apiKey?: string;
+    engineUrl?: string;
+    tenantId?: string;
+    policy?: SqaiPolicy;
+    enforceLimits?: boolean;
+    /** Milliseconds. Applies to HTTP transport AND, on the computation plane,
+     * rides to the daemon as an enforced per-request timeout (it can lower the
+     * daemon's ceiling, never raise it) — never advisory. */
+    timeout?: number;
+    maxRetries?: number;
+    resultStore?: ResultStoreConfig;
+    /** BYO substrate (tests). */
+    runtime?: Runtime;
+    /** BYO computation dispatch target (tests / custom self-hosted engines). */
+    computeTarget?: DispatchTarget;
+}
+declare class SQAI {
+    readonly mode: SqaiMode;
+    private readonly algentaRuntime;
+    private readonly rawRuntime;
+    private readonly policy;
+    private readonly tenantId;
+    private readonly engineUrl;
+    private readonly apiKey;
+    private readonly contractIndex;
+    private readonly resultStore;
+    private readonly provisioner;
+    private readonly configuredTarget;
+    private readonly timeoutMs;
+    private readonly sources;
+    constructor(config?: SqaiConfig);
+    connect(source: string | Array<Record<string, unknown>> | Record<string, unknown>, options?: {
+        name?: string;
+    }): Promise<SqaiSource>;
+    listSources(): SqaiSource[];
+    resolve(spec: QuerySpec): Promise<ResolveResponse>;
+    query(plan: ResolvedPlan | ResolveResponse): Promise<QueryResponse>;
+    queryWithMetadata(plan: ResolvedPlan | ResolveResponse): Promise<QueryWithMetadataResponse>;
+    verify(plan: ResolvedPlan | ResolveResponse): Promise<VerifyResponse>;
+    ask(spec: QuerySpec): Promise<AskOutcome>;
+    extractColumns(sourceName: string, columns: string[], options?: {
+        filter?: Record<string, unknown>;
+        limit?: number;
+        nullPolicy?: "pairwise" | "preserve";
+    }): Promise<ColumnExtract>;
+    compute(spec: ComputationSpec): Promise<ComputeResult>;
+    run(intent: SqaiIntent): Promise<SqaiOutcome>;
+    capabilities(): CapabilityContract;
+    searchCapabilities(query: string, limit?: number): CapabilityMatch[];
+    storeResult(value: unknown, sourceIds?: string[]): string;
+    getResult(resultId: string): SqaiResultRecord;
+    deleteResult(resultId: string): void;
+    readonly runtime: {
+        status: () => Promise<RuntimeStatus>;
+        ensure: () => Promise<void>;
+        stop: () => Promise<void>;
+    };
+    private checkQueryPolicy;
+    private dispatchTarget;
+    private resolveBindings;
+}
+declare function createSQAI(config?: SqaiConfig): SQAI;
+
+/** SQAI failure contract.
+ *
+ * Algenta error codes pass through verbatim (`source: "algenta"`); SQAI adds
+ * its own codes in the same snake_case vocabulary (`source: "sqai"`). A code
+ * is never renamed and the same condition never gets two codes.
+ */
+type SqaiErrorSource = "algenta" | "sqai";
+interface SqaiErrorOptions {
+    retryable?: boolean;
+    requestId?: string | null;
+    source?: SqaiErrorSource;
+    details?: Record<string, unknown>;
+}
+declare class SqaiError extends Error {
+    readonly code: string;
+    readonly retryable: boolean;
+    readonly requestId: string | null;
+    readonly source: SqaiErrorSource;
+    readonly details: Record<string, unknown>;
+    constructor(code: string, message: string, options?: SqaiErrorOptions);
+    toResult(): {
+        status: "error";
+        code: string;
+        message: string;
+        retryable: boolean;
+        request_id: string | null;
+    };
+}
+/** Codes SQAI adds on top of the Algenta vocabulary. */
+declare const SQAI_ERROR_CODES: readonly ["unsupported_operation", "seed_required", "duplicate_argument_binding", "policy_denied_source", "policy_denied_field", "policy_denied_function", "source_already_registered", "runtime_provision_failed", "daemon_port_conflict", "unsupported_platform", "compute_runtime_unavailable", "result_not_found", "contract_mismatch", "invalid_intent"];
+
+/** Two-hash determinism contract.
+ *
+ * invocation_hash — known BEFORE execution: the normalized operation identity
+ * (module, function, args, kwargs, resolved bindings, seed, contract hash,
+ * input hashes, declared execution scope). `explainQuery` returns this one.
+ *
+ * computation_hash — known only AFTER execution: invocation_hash plus the
+ * canonically serialized result.
+ *
+ * Both are domain-separated and rendered with the cross-language canonical
+ * JSON (algenta-sdk canonicalJson === algenta-core canonical_json, locked by
+ * the upstream conformance suite), so TypeScript and Python produce identical
+ * hashes for identical work.
+ */
+
+interface InvocationIdentity {
+    module: string;
+    function: string;
+    args: AlgentaWireValue[];
+    kwargs: Record<string, AlgentaWireValue>;
+    resolved_bindings: Array<{
+        parameter: string | number;
+        source_name: string;
+        fields: string[];
+        input_hash: string;
+    }>;
+    seed: number | string | null;
+    contract_hash: string;
+    execution_scope: string;
+}
+declare function invocationHash(identity: InvocationIdentity): string;
+declare function computationHash(invocation: string, result: unknown): string;
+
+/** Opaque, authorized result store.
+ *
+ * result_id is random (never derived from tenant/source/schema/hash material),
+ * so the identifier is unlinkable and reveals nothing — including whether a
+ * result exists. Authorization is enforced through stored tenant metadata:
+ * a lookup from the wrong tenant returns the same result_not_found as a
+ * missing id.
+ */
+
+declare class ResultStore {
+    private readonly config;
+    private readonly records;
+    private totalBytes;
+    constructor(config?: ResultStoreConfig);
+    store(value: unknown, options: {
+        tenantId: string | null;
+        sourceIds: string[];
+    }): string;
+    get(resultId: string, tenantId: string | null): SqaiResultRecord;
+    delete(resultId: string, tenantId: string | null): void;
+    private tenantBytes;
+    private evictExpired;
+    private evictOldest;
+    private evictOldestForTenant;
+}
+
+/** Computation-plane validation: dynamic, against the embedded capability
+ * contract. The zod wire schema (in @thyn-ai/sqai-ai-sdk) only transports values;
+ * everything here authorizes them. SQAI computes nothing — a validated
+ * computation is delegated to Algenta verbatim.
+ *
+ * Argument assembly: every signature parameter is supplied through EXACTLY one
+ * of args (positional), kwargs (by name), or bindings (by name or index).
+ * Duplicate assignment is `duplicate_argument_binding`; SQAI never silently
+ * overwrites an argument.
+ */
+
+interface ResolvedBindingValue {
+    parameter: string | number;
+    values: AlgentaWireValue;
+    provenance: BindingProvenance;
+}
+interface ValidatedComputation {
+    entry: CapabilityEntry;
+    /** Final positional argument vector, ordered by the signature params. */
+    argsVector: AlgentaWireValue[];
+    seed: number | string | null;
+    bindings: ResolvedBindingValue[];
+}
+declare function lookupCapability(index: ContractIndex, module: string, functionName: string): CapabilityEntry;
+declare function validateComputation(spec: ComputationSpec, index: ContractIndex, policy: SqaiPolicy | undefined, resolvedBindings: ResolvedBindingValue[]): ValidatedComputation;
+
+export { type AlgentaWireValue, type AskOutcome, type BindingProvenance, type CapabilityContract, type CapabilityEntry, type CapabilityMatch, type ColumnExtract, type ComputationBinding, type ComputationSpec, type ComputeResult, ContractIndex, type DeterminismEnvelope, type InvocationIdentity, type QueryFilterCondition, type QueryFilterSpec, type QuerySpec, type ResolvedBindingValue, ResultStore, type ResultStoreConfig, RuntimeProvisioner, type RuntimeStatus, SQAI, SQAI_ERROR_CODES, type SqaiConfig, SqaiError, type SqaiErrorSource, type SqaiIntent, type SqaiOutcome, type SqaiPolicy, type SqaiResultRecord, type SqaiSource, type ValidatedComputation, computationHash, createSQAI, currentPlatformKey, invocationHash, isReadOnlyEligible, lookupCapability, runtimeCacheDir, validateComputation };