terrascale 0.3.0

package/types/management-contracts.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @param {TerraScaleBlockedCapability} capability
+ * @returns {never}
+ */
+export function requireTerraScaleCapability(capability: TerraScaleBlockedCapability): never;
+/** Required capabilities whose producer/runtime admission is still open. */
+export const terraScaleReleaseBlockers: Readonly<{
+    management: Readonly<{
+        code: "management_contract_unavailable";
+        owner: "C06/C07 regional management service";
+        required: readonly string[];
+    }>;
+    betterAuth: Readonly<{
+        code: "security_authority_unavailable";
+        owner: "native single-writer security admission and C06/C07";
+        required: readonly string[];
+    }>;
+    qualification: Readonly<{
+        code: "runtime_qualification_unavailable";
+        owner: "real producer allocation and deployed customer application";
+        required: readonly string[];
+    }>;
+}>;
+/** @typedef {keyof typeof terraScaleReleaseBlockers} TerraScaleBlockedCapability */
+export class TerraScaleCapabilityUnavailableError extends Error {
+    /** @param {TerraScaleBlockedCapability} capability */
+    constructor(capability: TerraScaleBlockedCapability);
+    /**
+     * @readonly
+     * @type {string}
+     */
+    readonly code: string;
+    /**
+     * @readonly
+     * @type {TerraScaleBlockedCapability}
+     */
+    readonly capability: TerraScaleBlockedCapability;
+    /**
+     * @readonly
+     * @type {readonly string[]}
+     */
+    readonly required: readonly string[];
+}
+export type TerraScaleBlockedCapability = keyof typeof terraScaleReleaseBlockers;

package/types/management.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Required public management support remains closed until C06/C07 route admission.
+ * @returns {never}
+ */
+export function requireTerraScaleManagement(): never;
+export { terraScaleReleaseBlockers, TerraScaleCapabilityUnavailableError } from "./management-contracts.js";

package/types/native-origin.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function requireNativeRegion(value: unknown): string;
+/**
+ * @param {unknown} code
+ * @returns {string}
+ */
+export function nativeRegionalOrigin(code: unknown): string;
+/**
+ * Hosted identity refuses database API origins, without using native admission.
+ * @param {string} hostname
+ * @returns {boolean}
+ */
+export function isDataApiHostname(hostname: string): boolean;
+/**
+ * @param {string} raw
+ * @returns {string}
+ */
+export function nativeServiceOrigin(raw: string): string;
+/** Internal admission policy shared by native clients and qualification configuration. */
+export const terraScaleServiceDomain: "terrascale.tech";

package/types/postgres.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Validate and clone a builder descriptor without converting or interpolating values.
+ *
+ * @param {string} statement
+ * @param {readonly unknown[]} [parameters]
+ * @returns {PostgresBoundQuery}
+ */
+export function postgresQuery(statement: string, parameters?: readonly unknown[]): PostgresBoundQuery;
+/** @typedef {bigint | string} PostgresParameter */
+/**
+ * @typedef {{
+ *   readonly statement: string;
+ *   readonly parameters: readonly unknown[];
+ * }} PostgresQuery
+ */
+/**
+ * @typedef {{
+ *   readonly statement: string;
+ *   readonly parameters: readonly PostgresParameter[];
+ * }} PostgresBoundQuery
+ */
+/**
+ * @typedef {{
+ *   readonly host: string;
+ *   readonly port: number;
+ *   readonly tlsServerName: string;
+ *   readonly caCertificatePem: string;
+ *   readonly database: string;
+ *   readonly keyId: string;
+ *   readonly password: string;
+ *   readonly connectTimeoutMs?: number;
+ * }} PostgresConfig
+ */
+/**
+ * @typedef {{
+ *   readonly name: string;
+ *   readonly oid: 20 | 25;
+ * }} PostgresColumn
+ */
+/**
+ * @typedef {{
+ *   readonly command: string;
+ *   readonly affectedRows: number;
+ *   readonly columns: readonly PostgresColumn[];
+ *   readonly rows: readonly (readonly PostgresParameter[])[];
+ * }} PostgresResult
+ */
+/** Diagnostics retain SQLSTATE, but never driver messages, SQL or passwords. */
+export class PostgresError extends Error {
+    /**
+     * @param {"configuration" | "query" | "connection" | "database" | "protocol"} kind
+     * @param {string} [sqlState]
+     */
+    constructor(kind: "configuration" | "query" | "connection" | "database" | "protocol", sqlState?: string);
+    /**
+     * @override
+     * @readonly
+     */
+    override readonly name: "PostgresError";
+    /**
+     * @readonly
+     * @type {"configuration" | "query" | "connection" | "database" | "protocol"}
+     */
+    readonly kind: "configuration" | "query" | "connection" | "database" | "protocol";
+    /**
+     * @readonly
+     * @type {string | undefined}
+     */
+    readonly sqlState: string | undefined;
+}
+/** One driver connection; no automatic reconnect, mutation retry or callback replay. */
+export class PostgresClient {
+    /**
+     * @param {PostgresConfig} input
+     * @returns {Promise<PostgresClient>}
+     */
+    static connect(input: PostgresConfig): Promise<PostgresClient>;
+    /**
+     * @private
+     * @param {DriverClient} driver
+     * @param {typeof DatabaseError} databaseError
+     */
+    private constructor();
+    /**
+     * @param {PostgresQuery} input
+     * @returns {Promise<PostgresResult>}
+     */
+    query(input: PostgresQuery): Promise<PostgresResult>;
+    /**
+     * @returns {Promise<void>}
+     */
+    close(): Promise<void>;
+    #private;
+}
+export type PostgresParameter = bigint | string;
+export type PostgresQuery = {
+    readonly statement: string;
+    readonly parameters: readonly unknown[];
+};
+export type PostgresBoundQuery = {
+    readonly statement: string;
+    readonly parameters: readonly PostgresParameter[];
+};
+export type PostgresConfig = {
+    readonly host: string;
+    readonly port: number;
+    readonly tlsServerName: string;
+    readonly caCertificatePem: string;
+    readonly database: string;
+    readonly keyId: string;
+    readonly password: string;
+    readonly connectTimeoutMs?: number;
+};
+export type PostgresColumn = {
+    readonly name: string;
+    readonly oid: 20 | 25;
+};
+export type PostgresResult = {
+    readonly command: string;
+    readonly affectedRows: number;
+    readonly columns: readonly PostgresColumn[];
+    readonly rows: readonly (readonly PostgresParameter[])[];
+};

package/types/react/core.d.ts

@@ -0,0 +1,366 @@
+/**
+ * @template TValue
+ * @typedef {{ readonly kind: "snapshot" | "data"; readonly value: TValue }
+ *   | { readonly kind: "reset"; readonly reset: ReactiveReset<TValue> }
+ *   | { readonly kind: "error"; readonly error: unknown }} ReactiveHttpEvent
+ */
+/**
+ * Typed boundary for the owning HTTP contract. Implementations perform the
+ * documented request and polling protocol; this adapter only maps events to
+ * the hook's observer and propagates AbortSignal.
+ *
+ * @template TRequest, TValue
+ * @typedef {{
+ *   readonly subscribe: (
+ *     request: TRequest,
+ *     observer: { readonly event: (event: ReactiveHttpEvent<TValue>) => void },
+ *     context: ReactiveSubscriptionContext,
+ *   ) => ReactiveDisposer | void | Promise<ReactiveDisposer | void>;
+ * }} ReactiveHttpTransport
+ */
+/**
+ * @template TRequest, TValue
+ * @param {ReactiveHttpTransport<TRequest, TValue>} transport
+ * @param {TRequest} request
+ * @param {string | readonly unknown[]} [key]
+ * @returns {ReactiveQuerySource<TValue>}
+ */
+export function createReactiveHttpQuery<TRequest, TValue>(transport: ReactiveHttpTransport<TRequest, TValue>, request: TRequest, key?: string | readonly unknown[]): ReactiveQuerySource<TValue>;
+/** @typedef {import("../database-view.js").DatabaseQueryCallbacks} DatabaseQueryCallbacks */
+/** @typedef {import("../database-view.js").DatabaseQueryOptions} DatabaseQueryOptions */
+/** @typedef {import("../database-view.js").DatabaseQuerySource} DatabaseQuerySource */
+/** @typedef {import("../database-view.js").DatabaseViewBinding} DatabaseViewBinding */
+/** @typedef {import("../database-view.js").DatabaseViewPosition} DatabaseViewPosition */
+/** @typedef {import("../database-view.js").DatabaseViewSnapshot} DatabaseViewSnapshot */
+/**
+ * A subscription cleanup returned by a typed reactive transport.
+ *
+ * @typedef {(() => void) | { readonly dispose: () => void } | { readonly unsubscribe: () => void }} ReactiveDisposer
+ */
+/**
+ * @typedef {{
+ *   readonly signal: AbortSignal;
+ * }} ReactiveSubscriptionContext
+ */
+/**
+ * @template TValue
+ * @typedef {{
+ *   readonly next: (value: TValue) => void;
+ *   readonly error: (error: unknown) => void;
+ *   readonly reset: (reset: ReactiveReset<TValue>) => void;
+ * }} ReactiveQueryCallbacks
+ */
+/**
+ * The operation owned by the public reactive contract. It may use HTTP
+ * long-polling or WebSocket delivery; the hook does not know or care which.
+ *
+ * @template TValue
+ * @typedef {{
+ *   readonly key?: string | readonly unknown[];
+ *   readonly subscribe: (
+ *     observer: ReactiveQueryCallbacks<TValue>,
+ *     context: ReactiveSubscriptionContext,
+ *   ) => ReactiveDisposer | void | Promise<ReactiveDisposer | void>;
+ * }} ReactiveQuerySource
+ */
+/**
+ * @typedef {"checkpoint-expired"
+ *   | "retention-advanced"
+ *   | "generation-changed"
+ *   | "checkpoint-not-current"
+ *   | "view-diverged"
+ *   | "oversized"
+ *   | "invalid-operations"
+ *   | "invalid-checkpoint"
+ *   | "backpressure"
+ *   | (string & {})} ReactiveResetReason
+ */
+/**
+ * A server-authorized reset. The checkpoint remains opaque to the hook.
+ *
+ * @template TValue
+ * @typedef {{
+ *   readonly reason: ReactiveResetReason;
+ *   readonly data?: TValue;
+ *   readonly checkpoint?: string | Uint8Array;
+ *   readonly code?: string;
+ *   readonly message?: string;
+ * }} ReactiveReset
+ */
+/** @typedef {"subscription" | "transport" | "remote" | "cancelled" | "mutation"} ReactiveErrorKind */
+/**
+ * @typedef {{
+ *   readonly kind: ReactiveErrorKind;
+ *   readonly code: string;
+ *   readonly message: string;
+ *   readonly cause?: unknown;
+ *   readonly terraScale?: TerraScaleError;
+ *   readonly database?: Extract<DatabaseResult<never>, { readonly ok: false }>["error"];
+ * }} ReactiveError
+ */
+/** @typedef {"pending" | "success" | "error" | "reset"} ReactiveQueryStatus */
+/**
+ * @template TValue
+ * @typedef {{
+ *   readonly status: ReactiveQueryStatus;
+ *   readonly data: TValue | undefined;
+ *   readonly error: ReactiveError | undefined;
+ *   readonly reset: ReactiveReset<TValue> | undefined;
+ *   readonly isLoading: boolean;
+ *   readonly isFetching: boolean;
+ *   readonly isStale: boolean;
+ * }} ReactiveQueryState
+ */
+/**
+ * @template TValue
+ * @typedef {{
+ *   readonly enabled?: boolean;
+ *   readonly initialData?: TValue;
+ * }} ReactiveQueryOptions
+ */
+/**
+ * Framework-neutral query observer used by useQuery and SSR-safe tests.
+ *
+ * @template TValue
+ */
+export class ReactiveQueryObserver<TValue> {
+    /**
+     * @param {ReactiveQuerySource<TValue>} source
+     * @param {ReactiveQueryOptions<TValue>} [options]
+     */
+    constructor(source: ReactiveQuerySource<TValue>, options?: ReactiveQueryOptions<TValue>);
+    /** @returns {ReactiveQueryState<TValue>} */
+    getSnapshot: () => ReactiveQueryState<TValue>;
+    /** @returns {ReactiveQueryState<TValue>} */
+    getServerSnapshot: () => ReactiveQueryState<TValue>;
+    /**
+     * Updates the small, hook-facing option set without replacing the external
+     * store. React may render a hook with a new options object while preserving
+     * the observer; an `enabled` transition must therefore start/stop delivery
+     * at the subscription boundary instead of leaving a stale subscription.
+     *
+     * @param {ReactiveQueryOptions<TValue>} [options]
+     * @returns {void}
+     */
+    updateOptions(options?: ReactiveQueryOptions<TValue>): void;
+    /**
+     * @param {() => void} listener
+     * @returns {() => void}
+     */
+    subscribe: (listener: () => void) => () => void;
+    /** @returns {void} */
+    start(): void;
+    /**
+     * Aborts HTTP polling and disposes the current transport subscription.
+     *
+     * @returns {void}
+     */
+    dispose(): void;
+    /**
+     * Restart only while an enabled query has live observers.
+     *
+     * @returns {void}
+     */
+    refetch(): void;
+    #private;
+}
+/**
+ * @typedef {{
+ *   readonly signal: AbortSignal;
+ *   readonly idempotencyKey: string;
+ * }} ReactiveMutationContext
+ */
+/** @typedef {void | (() => void) | { readonly rollback: () => void }} OptimisticRollback */
+/**
+ * @template TValue, TVariables
+ * @typedef {{
+ *   readonly mutationFn: (
+ *     variables: TVariables,
+ *     context: ReactiveMutationContext,
+ *   ) => Promise<TValue | TerraScaleResult<TValue> | DatabaseResult<TValue>>;
+ *   readonly idempotencyKey?: string | ((variables: TVariables) => string);
+ *   readonly onMutate?: (variables: TVariables, context: ReactiveMutationContext) => OptimisticRollback | Promise<OptimisticRollback>;
+ * }} ReactiveMutationOptions
+ */
+/** @typedef {"idle" | "pending" | "success" | "error" | "cancelled"} ReactiveMutationStatus */
+/**
+ * @template TValue
+ * @typedef {{
+ *   readonly status: ReactiveMutationStatus;
+ *   readonly data: TValue | undefined;
+ *   readonly error: ReactiveError | undefined;
+ *   readonly idempotencyKey: string | undefined;
+ *   readonly isPending: boolean;
+ * }} ReactiveMutationState
+ */
+/**
+ * @template TValue, TVariables
+ */
+export class ReactiveMutationObserver<TValue, TVariables> {
+    /**
+     * @param {ReactiveMutationOptions<TValue, TVariables>} options
+     */
+    constructor(options: ReactiveMutationOptions<TValue, TVariables>);
+    /**
+     * Keep callbacks current when a component re-renders without replacing the
+     * observer (the normal `useMutation` lifecycle). A mutation already running
+     * captures the callbacks it started with, so a render cannot redirect an
+     * in-flight durable request.
+     *
+     * @param {ReactiveMutationOptions<TValue, TVariables>} options
+     * @returns {void}
+     */
+    updateOptions(options: ReactiveMutationOptions<TValue, TVariables>): void;
+    /** @returns {ReactiveMutationState<TValue>} */
+    getSnapshot: () => ReactiveMutationState<TValue>;
+    /**
+     * @param {() => void} listener
+     * @returns {() => void}
+     */
+    subscribe: (listener: () => void) => () => void;
+    /**
+     * @param {TVariables} variables
+     * @returns {Promise<TValue>}
+     */
+    mutateAsync(variables: TVariables): Promise<TValue>;
+    /**
+     * @param {TVariables} variables
+     * @returns {void}
+     */
+    mutate(variables: TVariables): void;
+    /**
+     * Cancels the durable request and immediately rolls back its presentation.
+     *
+     * @returns {void}
+     */
+    cancel(): void;
+    /** @returns {void} */
+    reset(): void;
+    /** @returns {void} */
+    dispose(): void;
+    #private;
+}
+export class ReactiveMutationError extends Error {
+    /**
+     * @param {string} code
+     * @param {string} message
+     * @param {unknown} [cause]
+     */
+    constructor(code: string, message: string, cause?: unknown);
+    /** @override @readonly */
+    override readonly name: "ReactiveMutationError";
+    /** @readonly @type {string} */
+    readonly code: string;
+    /** @override @readonly @type {unknown} */
+    override readonly cause: unknown;
+}
+export type ReactiveHttpEvent<TValue> = {
+    readonly kind: "snapshot" | "data";
+    readonly value: TValue;
+} | {
+    readonly kind: "reset";
+    readonly reset: ReactiveReset<TValue>;
+} | {
+    readonly kind: "error";
+    readonly error: unknown;
+};
+/**
+ * Typed boundary for the owning HTTP contract. Implementations perform the
+ * documented request and polling protocol; this adapter only maps events to
+ * the hook's observer and propagates AbortSignal.
+ */
+export type ReactiveHttpTransport<TRequest, TValue> = {
+    readonly subscribe: (request: TRequest, observer: {
+        readonly event: (event: ReactiveHttpEvent<TValue>) => void;
+    }, context: ReactiveSubscriptionContext) => ReactiveDisposer | void | Promise<ReactiveDisposer | void>;
+};
+export type DatabaseQueryCallbacks = import("../database-view.js").DatabaseQueryCallbacks;
+export type DatabaseQueryOptions = import("../database-view.js").DatabaseQueryOptions;
+export type DatabaseQuerySource = import("../database-view.js").DatabaseQuerySource;
+export type DatabaseViewBinding = import("../database-view.js").DatabaseViewBinding;
+export type DatabaseViewPosition = import("../database-view.js").DatabaseViewPosition;
+export type DatabaseViewSnapshot = import("../database-view.js").DatabaseViewSnapshot;
+/**
+ * A subscription cleanup returned by a typed reactive transport.
+ */
+export type ReactiveDisposer = (() => void) | {
+    readonly dispose: () => void;
+} | {
+    readonly unsubscribe: () => void;
+};
+export type ReactiveSubscriptionContext = {
+    readonly signal: AbortSignal;
+};
+export type ReactiveQueryCallbacks<TValue> = {
+    readonly next: (value: TValue) => void;
+    readonly error: (error: unknown) => void;
+    readonly reset: (reset: ReactiveReset<TValue>) => void;
+};
+/**
+ * The operation owned by the public reactive contract. It may use HTTP
+ * long-polling or WebSocket delivery; the hook does not know or care which.
+ */
+export type ReactiveQuerySource<TValue> = {
+    readonly key?: string | readonly unknown[];
+    readonly subscribe: (observer: ReactiveQueryCallbacks<TValue>, context: ReactiveSubscriptionContext) => ReactiveDisposer | void | Promise<ReactiveDisposer | void>;
+};
+export type ReactiveResetReason = "checkpoint-expired" | "retention-advanced" | "generation-changed" | "checkpoint-not-current" | "view-diverged" | "oversized" | "invalid-operations" | "invalid-checkpoint" | "backpressure" | (string & {});
+/**
+ * A server-authorized reset. The checkpoint remains opaque to the hook.
+ */
+export type ReactiveReset<TValue> = {
+    readonly reason: ReactiveResetReason;
+    readonly data?: TValue;
+    readonly checkpoint?: string | Uint8Array;
+    readonly code?: string;
+    readonly message?: string;
+};
+export type ReactiveErrorKind = "subscription" | "transport" | "remote" | "cancelled" | "mutation";
+export type ReactiveError = {
+    readonly kind: ReactiveErrorKind;
+    readonly code: string;
+    readonly message: string;
+    readonly cause?: unknown;
+    readonly terraScale?: TerraScaleError;
+    readonly database?: Extract<DatabaseResult<never>, {
+        readonly ok: false;
+    }>["error"];
+};
+export type ReactiveQueryStatus = "pending" | "success" | "error" | "reset";
+export type ReactiveQueryState<TValue> = {
+    readonly status: ReactiveQueryStatus;
+    readonly data: TValue | undefined;
+    readonly error: ReactiveError | undefined;
+    readonly reset: ReactiveReset<TValue> | undefined;
+    readonly isLoading: boolean;
+    readonly isFetching: boolean;
+    readonly isStale: boolean;
+};
+export type ReactiveQueryOptions<TValue> = {
+    readonly enabled?: boolean;
+    readonly initialData?: TValue;
+};
+export type ReactiveMutationContext = {
+    readonly signal: AbortSignal;
+    readonly idempotencyKey: string;
+};
+export type OptimisticRollback = void | (() => void) | {
+    readonly rollback: () => void;
+};
+export type ReactiveMutationOptions<TValue, TVariables> = {
+    readonly mutationFn: (variables: TVariables, context: ReactiveMutationContext) => Promise<TValue | TerraScaleResult<TValue> | DatabaseResult<TValue>>;
+    readonly idempotencyKey?: string | ((variables: TVariables) => string);
+    readonly onMutate?: (variables: TVariables, context: ReactiveMutationContext) => OptimisticRollback | Promise<OptimisticRollback>;
+};
+export type ReactiveMutationStatus = "idle" | "pending" | "success" | "error" | "cancelled";
+export type ReactiveMutationState<TValue> = {
+    readonly status: ReactiveMutationStatus;
+    readonly data: TValue | undefined;
+    readonly error: ReactiveError | undefined;
+    readonly idempotencyKey: string | undefined;
+    readonly isPending: boolean;
+};
+import type { TerraScaleError } from "../result.js";
+import type { DatabaseResult } from "../database-types.js";
+import type { TerraScaleResult } from "../result.js";
+export { createDatabaseQuery, DatabaseSubscriptionError, DatabaseSubscriptionView } from "../database-view.js";

package/types/react/index.d.ts

@@ -0,0 +1,54 @@
+/**
+ * React's external-store primitive gives useQuery one SSR-safe snapshot and
+ * makes every server update flow through the typed reactive subscription.
+ * Keep the source object stable between renders.
+ *
+ * @template TValue
+ * @param {ReactiveQuerySource<TValue>} source
+ * @param {ReactiveQueryOptions<TValue>} [options]
+ * @returns {ReactiveQueryState<TValue> & { readonly refetch: () => void }}
+ */
+export function useQuery<TValue>(source: ReactiveQuerySource<TValue>, options?: ReactiveQueryOptions<TValue>): ReactiveQueryState<TValue> & {
+    readonly refetch: () => void;
+};
+/**
+ * @template TValue, TVariables
+ * @typedef {ReactiveMutationState<TValue> & {
+ *   readonly mutate: (variables: TVariables) => void;
+ *   readonly mutateAsync: (variables: TVariables) => Promise<TValue>;
+ *   readonly cancel: () => void;
+ *   readonly reset: () => void;
+ * }} UseMutationResult
+ */
+/**
+ * A durable mutation always receives one idempotency identity and AbortSignal.
+ * The optional onMutate result is a reversible presentation rollback; it is
+ * never an offline queue and is removed on either acceptance or rejection.
+ *
+ * @template TValue
+ * @template [TVariables=void]
+ * @param {ReactiveMutationOptions<TValue, TVariables>} options
+ * @returns {UseMutationResult<TValue, TVariables>}
+ */
+export function useMutation<TValue, TVariables = void>(options: ReactiveMutationOptions<TValue, TVariables>): UseMutationResult<TValue, TVariables>;
+/**
+ * Explicitly disposes a mutation observer created outside a React tree.
+ *
+ * @template TValue, TVariables
+ * @param {ReactiveMutationObserver<TValue, TVariables>} observer
+ * @returns {void}
+ */
+export function disposeMutation<TValue, TVariables>(observer: ReactiveMutationObserver<TValue, TVariables>): void;
+export * from "./core.js";
+export type UseMutationResult<TValue, TVariables> = ReactiveMutationState<TValue> & {
+    readonly mutate: (variables: TVariables) => void;
+    readonly mutateAsync: (variables: TVariables) => Promise<TValue>;
+    readonly cancel: () => void;
+    readonly reset: () => void;
+};
+import type { ReactiveQuerySource } from "./core.js";
+import type { ReactiveQueryOptions } from "./core.js";
+import type { ReactiveQueryState } from "./core.js";
+import type { ReactiveMutationOptions } from "./core.js";
+import { ReactiveMutationObserver } from "./core.js";
+import type { ReactiveMutationState } from "./core.js";