@query-farm/vgi 0.28.0 → 0.29.1

package/dist/split-token.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Split-token envelope: the framework's wrapper around a worker's split payload.
+ *
+ * A split token *names* a unit of scan work so a distributed engine can
+ * re-request exactly the work it was handed. The worker supplies only the
+ * payload; everything around it is stamped here, so an author cannot forget the
+ * consistency anchor or mis-bind the fingerprint, and never writes crypto.
+ *
+ * Layout (little-endian, fixed prefix) — byte-identical across every SDK:
+ *
+ * ```
+ * offset  size  field
+ * 0       1     format_version      currently 1
+ * 1       1     flags               bit0 = payload_sealed; bits 1-7 reserved, MUST be 0
+ * 2       2     anchor_len          u16 LE
+ * 4       16    bind_fingerprint    truncated SHA-256 of the bind identity
+ * 20      var   consistency_anchor  anchor_len bytes
+ * 20+n    var   payload             the worker's own bytes
+ * ```
+ *
+ * **The header is plaintext on every transport; only the payload is sealed.**
+ * That is not a preference: a worker has no signing key on subprocess and unix,
+ * which is DuckDB's primary path, so a header readable only through AEAD would be
+ * unreadable exactly where DuckDB runs. It also matters for streaming — a
+ * checkpointed position must survive key rotation.
+ *
+ * @module
+ */
+import type { AuthContext } from "@query-farm/vgi-rpc";
+/** Envelope format version. Checked unconditionally, before anything else. */
+export declare const SPLIT_TOKEN_FORMAT_VERSION = 1;
+/** Stable error-kind strings, identical across SDKs. */
+export declare const SPLIT_TOKEN_INVALID = "SPLIT_TOKEN_INVALID";
+export declare const SPLIT_SNAPSHOT_EXPIRED = "SPLIT_SNAPSHOT_EXPIRED";
+export declare const SPLIT_TRANSACTION_ENDED = "SPLIT_TRANSACTION_ENDED";
+/**
+ * Why a split token was refused.
+ *
+ * The kind matters to a connector: only `SPLIT_SNAPSHOT_EXPIRED` means "re-run
+ * the query", and neither kind is retriable in place. Keeping the anchor in the
+ * PLAINTEXT header rather than in the AAD is what makes that distinction
+ * expressible — inside the AAD both collapse into one tag-check failure.
+ */
+export declare class SplitTokenError extends Error {
+    readonly kind: string;
+    constructor(kind: string, message: string);
+}
+/**
+ * Derive the 16-byte binding check for a bind call.
+ *
+ * Minted **and** verified by the same worker, so it needs self-consistency only
+ * — it does not have to agree with any client, which is why the cross-SDK byte
+ * fixtures do not cover it. 16 bytes is a binding check, not a MAC: forgery
+ * resistance comes from the seal where a key exists, and from the uid trust
+ * boundary where one does not.
+ *
+ * Uses Web Crypto rather than a hash dependency so this works unchanged in the
+ * browser and Cloudflare Workers builds.
+ */
+export declare function bindFingerprint(schemaPath: string[], functionName: string, args: Uint8Array, settings: Uint8Array, projection: Uint8Array): Promise<Uint8Array>;
+/**
+ * Encode the consistency anchor.
+ *
+ * `catalog_version` is the counter that MOVES within an attach, so it is what a
+ * plan is pinned to; `resolved_data_version` is fixed at attach and would say
+ * nothing about staleness.
+ */
+export declare function splitAnchor(catalogVersion: bigint | number): Uint8Array;
+/** Stamp (and, when a key exists, seal) a worker payload into a split token. */
+export declare function buildSplitToken(opts: {
+    payload: Uint8Array;
+    fingerprint: Uint8Array;
+    anchor: Uint8Array;
+    signingKey?: Uint8Array;
+    auth?: AuthContext;
+}): Promise<Uint8Array>;
+/**
+ * Verify a split token and return the worker's payload.
+ *
+ * `expectedFingerprint` and `currentAnchor` are optional; omitting one skips that
+ * check.
+ */
+export declare function openSplitToken(token: Uint8Array, opts?: {
+    signingKey?: Uint8Array;
+    auth?: AuthContext;
+    expectedFingerprint?: Uint8Array;
+    currentAnchor?: Uint8Array;
+}): Promise<Uint8Array>;

package/dist/types.d.ts

@@ -13,6 +13,14 @@ export declare enum NullHandling {
     DEFAULT = "DEFAULT",
     SPECIAL = "SPECIAL"
 }
+export declare enum ArgumentMonotonicity {
+    UNKNOWN = "UNKNOWN",
+    CONSTANT = "CONSTANT",
+    NON_DECREASING = "NON_DECREASING",
+    STRICTLY_INCREASING = "STRICTLY_INCREASING",
+    NON_INCREASING = "NON_INCREASING",
+    STRICTLY_DECREASING = "STRICTLY_DECREASING"
+}
 export declare enum OrderPreservation {
     /** Output rows are in same order as input rows (DuckDB INSERTION_ORDER). */
     PRESERVES_ORDER = "PRESERVES_ORDER",