@apifuse/provider-sdk 2.2.0-beta.60 → 2.2.0-beta.61

package/dist/runtime/{choice-wordlist.js → handle-wordlist.js}

@@ -118,21 +118,139 @@ wolverine womb woolworker workbasket wound wrangle wreckage wristwatch wrongdoin
 yacht yahoo yard yearbook yesterday yiddish yield yo-yo yodel yogurt yuppie zealot zebra zeppelin
 zestfully zigzagged zillion zipping zirconium zodiac zombie zookeeper zucchini
 `;
-export const CHOICE_WORDLIST_SIZE = 1_296;
-export const CHOICE_WORD_ENTROPY_BITS = Math.log2(CHOICE_WORDLIST_SIZE);
-export const STANDARD_CHOICE_WORD_COUNT = 4;
-export const HIGH_CHOICE_WORD_COUNT = 5;
-export const STANDARD_CHOICE_ENTROPY_BITS = STANDARD_CHOICE_WORD_COUNT * CHOICE_WORD_ENTROPY_BITS;
-export const HIGH_CHOICE_ENTROPY_BITS = HIGH_CHOICE_WORD_COUNT * CHOICE_WORD_ENTROPY_BITS;
+export const HANDLE_WORDLIST_SIZE = 1_296;
+export const HANDLE_WORD_ENTROPY_BITS = Math.log2(HANDLE_WORDLIST_SIZE);
+/**
+ * Bound handles live under `state.forConnection(connectionId)`: another
+ * connection cannot address them at all, so no guessing analysis applies. The
+ * only requirement is uniqueness among live handles of one connection
+ * (1,296^2 = 1.68M keys, CAS-if-absent with retries), which two words satisfy.
+ */
+export const BOUND_HANDLE_WORD_COUNT = 2;
+/** Public handles are addressable by anyone; ADR 0006 §2 guessing numbers apply. */
+export const PUBLIC_HANDLE_WORD_COUNT = 4;
+/** Used when a public kind declares `strength: "high"` or its ttl exceeds one hour. */
+export const HIGH_PUBLIC_HANDLE_WORD_COUNT = 5;
+export const PUBLIC_HANDLE_ENTROPY_BITS = PUBLIC_HANDLE_WORD_COUNT * HANDLE_WORD_ENTROPY_BITS;
+export const HIGH_PUBLIC_HANDLE_ENTROPY_BITS = HIGH_PUBLIC_HANDLE_WORD_COUNT * HANDLE_WORD_ENTROPY_BITS;
 export const EFF_SHORT_WORDLIST_2 = Object.freeze(EFF_SHORT_WORDLIST_2_TEXT.trim().split(/\s+/));
 const EFF_SHORT_WORD_SET = new Set(EFF_SHORT_WORDLIST_2);
-export function choiceWordAt(index) {
+/**
+ * Words the runtime may issue. The handle grammar joins words with `-`, so the
+ * one hyphenated official entry (`yo-yo`) would fuse with the separator and is
+ * never issued. The official list itself stays embedded unchanged.
+ */
+export const ISSUABLE_HANDLE_WORDS = Object.freeze(EFF_SHORT_WORDLIST_2.filter((word) => !word.includes("-")));
+export function handleWordAt(index) {
     const word = EFF_SHORT_WORDLIST_2[index];
     if (word === undefined) {
-        throw new RangeError(`Choice word index is out of range: ${index}`);
+        throw new RangeError(`Handle word index is out of range: ${index}`);
     }
     return word;
 }
-export function isChoiceWord(value) {
+export function isHandleWord(value) {
     return EFF_SHORT_WORD_SET.has(value);
 }
+/**
+ * Symmetric-deletion index (SymSpell, max distance 1). Two strings at
+ * Levenshtein distance <= 1 always share a form reachable by deleting at most
+ * one character from each side, so a lookup of the query and its one-deletion
+ * variants yields every candidate; a real distance check then removes the false
+ * positives (e.g. transpositions). ~10k entries, O(len) per lookup.
+ */
+/** Shortest and longest words in the list (3 and 10 for the official list). */
+export const MIN_HANDLE_WORD_LENGTH = Math.min(...EFF_SHORT_WORDLIST_2.map((word) => word.length));
+export const MAX_HANDLE_WORD_LENGTH = Math.max(...EFF_SHORT_WORDLIST_2.map((word) => word.length));
+const DELETION_INDEX = (() => {
+    const index = new Map();
+    const add = (form, word) => {
+        const bucket = index.get(form);
+        if (bucket === undefined)
+            index.set(form, [word]);
+        else if (!bucket.includes(word))
+            bucket.push(word);
+    };
+    for (const word of EFF_SHORT_WORDLIST_2) {
+        add(word, word);
+        for (const variant of oneDeletionVariants(word))
+            add(variant, word);
+    }
+    return index;
+})();
+function oneDeletionVariants(value) {
+    const variants = [];
+    for (let position = 0; position < value.length; position += 1) {
+        variants.push(value.slice(0, position) + value.slice(position + 1));
+    }
+    return variants;
+}
+/** True when Levenshtein distance between `left` and `right` is at most 1. */
+function withinEditDistanceOne(left, right) {
+    if (left === right)
+        return true;
+    const lengthDelta = left.length - right.length;
+    if (lengthDelta > 1 || lengthDelta < -1)
+        return false;
+    if (lengthDelta === 0) {
+        let mismatches = 0;
+        for (let position = 0; position < left.length; position += 1) {
+            if (left[position] !== right[position]) {
+                mismatches += 1;
+                if (mismatches > 1)
+                    return false;
+            }
+        }
+        return true;
+    }
+    const longer = lengthDelta > 0 ? left : right;
+    const shorter = lengthDelta > 0 ? right : left;
+    let longIndex = 0;
+    let shortIndex = 0;
+    let skipped = false;
+    while (shortIndex < shorter.length) {
+        if (longer[longIndex] === shorter[shortIndex]) {
+            longIndex += 1;
+            shortIndex += 1;
+            continue;
+        }
+        if (skipped)
+            return false;
+        skipped = true;
+        longIndex += 1;
+    }
+    return true;
+}
+/**
+ * Resolves one handle segment to a wordlist entry: the exact word, or the
+ * unique word at edit distance <= `maxDistance`. Returns null when no word or
+ * more than one word qualifies. The official list has pairwise edit distance
+ * >= 3, so at distance 1 every non-null answer is unique; the uniqueness check
+ * is kept as a guard so a wordlist change cannot silently make normalization
+ * map one input onto two different canonical handles.
+ */
+export function findHandleWordWithinDistance(segment, maxDistance) {
+    if (segment.length === 0)
+        return null;
+    if (EFF_SHORT_WORD_SET.has(segment))
+        return segment;
+    if (maxDistance !== 1)
+        return null;
+    // A segment that is more than one character shorter or longer than every
+    // word cannot be within distance 1 of any word. Rejecting it here also bounds
+    // the variant generation below (which is O(len²) in memory) against
+    // client-supplied garbage of arbitrary length.
+    if (segment.length < MIN_HANDLE_WORD_LENGTH - maxDistance ||
+        segment.length > MAX_HANDLE_WORD_LENGTH + maxDistance) {
+        return null;
+    }
+    const matches = new Set();
+    for (const form of [segment, ...oneDeletionVariants(segment)]) {
+        for (const candidate of DELETION_INDEX.get(form) ?? []) {
+            if (withinEditDistanceOne(segment, candidate))
+                matches.add(candidate);
+        }
+    }
+    if (matches.size !== 1)
+        return null;
+    return matches.values().next().value ?? null;
+}

package/dist/runtime/handle.d.ts

@@ -0,0 +1,71 @@
+import { type HandleContext, type HandleKind, type HandleStatus, type HandleTelemetryEvent } from "../handle.js";
+import type { ProviderRequestContext, ProviderRuntimeState } from "../types.js";
+declare const RECORD_VERSION = 1;
+export interface CreateHandleContextOptions {
+    readonly providerId: string;
+    readonly request?: ProviderRequestContext;
+    readonly state?: ProviderRuntimeState;
+    /** Clock used for record timestamps and TTL math; defaults to `Date.now`. */
+    readonly nowMs?: () => number;
+    /** Receives allowlisted metadata only; handle values, data, and results are never included. */
+    readonly onTelemetry?: (event: HandleTelemetryEvent) => void;
+    /**
+     * Lease held (and renewed) by a `committing` claim while upstream work runs.
+     * Defaults to 5 minutes; exposed so tests can exercise renewal quickly.
+     */
+    readonly commitLeaseMs?: number;
+}
+export interface CreateTestHandleContextOptions {
+    readonly providerId?: string;
+    readonly state?: ProviderRuntimeState;
+    readonly request?: ProviderRequestContext;
+    readonly nowMs?: () => number;
+    readonly onTelemetry?: (event: HandleTelemetryEvent) => void;
+}
+/**
+ * Persisted record shape (spec §6). `expires_at_ms` is the logical expiry the
+ * caller sees (sliding for drafts); `max_expires_at_ms` is the hard lifetime.
+ * Records are stored past their logical expiry for a grace window so an expired
+ * handle can be told apart from an unknown one (`HANDLE_EXPIRED` vs
+ * `HANDLE_NOT_FOUND`); after the grace window they are simply gone.
+ */
+export type StoredHandleRecord = {
+    readonly v: typeof RECORD_VERSION;
+    readonly kind: string;
+    readonly type: "cursor" | "draft";
+    /** `discarded` is an internal tombstone written by `discard`; reads treat it as absent. */
+    readonly status: HandleStatus | "discarded";
+    readonly data: unknown;
+    readonly result?: unknown;
+    readonly created_at_ms: number;
+    readonly expires_at_ms: number;
+    readonly max_expires_at_ms: number;
+    readonly committed_at_ms?: number;
+    /** Owner token of a `committing` claim; lets the claimant recognise its record after an ambiguous write. */
+    readonly claim_id?: string;
+};
+export type HandleNormalizationClass = "case" | "whitespace" | "separator" | "punctuation" | "typo";
+export interface NormalizedHandle {
+    readonly canonical: string;
+    readonly words: readonly string[];
+    readonly normalization: readonly HandleNormalizationClass[];
+}
+/**
+ * Tolerant parse of a raw handle string into its canonical form. Throws
+ * `HANDLE_KIND_MISMATCH` when the string does not start with the kind name and
+ * `HANDLE_INVALID` when the body cannot be resolved to the kind's word count.
+ */
+export declare function normalizeHandle(kind: HandleKind, raw: string): {
+    canonical: string;
+    words: string[];
+    normalization: string[];
+};
+export declare function formatNormalizationClasses(classes: readonly string[]): string;
+export declare function createHandleContext(options: CreateHandleContextOptions): HandleContext;
+/**
+ * Handle context for unit tests: memory state, a fixed connection, and an
+ * optional fake clock. Share one `state` between two contexts with different
+ * `request.connectionId`s to exercise bound isolation.
+ */
+export declare function createTestHandleContext(options?: CreateTestHandleContextOptions): HandleContext;
+export {};