@volter/twin-fal 0.1.0

package/dist/src/fal-budget.js

@@ -0,0 +1,410 @@
+// fal's CLIENT-SIDE RATE BUDGET — the pack's DECLARATION (the numbers) plus `guardFalClient`,
+// the choke point every live fal call goes through. The MECHANISM — the durable token-keyed
+// ledger, the rolling window, reserve-under-lock, the `Retry-After`/429 cooldown, fail-CLOSED on a
+// corrupt ledger — lives ONCE in the vendor-agnostic kernel (`@volter/world-core` → `rateBudget.ts`).
+// Read that module's header for the full rationale AND for the honest list of what the guard does
+// NOT guarantee (an injected clock or ledger path still defeats it — it guards carelessness, not
+// malice). This module is modeled on notion-budget.ts, the reference injected-client decorator.
+//
+// ── WHY FAL NEEDS ONE ───────────────────────────────────────────────────────────────
+// fal publishes CONCURRENCY, not a requests-per-second limit: "New accounts start with 2 concurrent
+// requests" scaling to 40 for self-serve (fal.ai/docs/documentation/model-apis/concurrency-limits),
+// above which it is contact-sales. Critically for this connector, fal also documents that requests in
+// the IN_QUEUE state do NOT count toward that limit — only IN_PROGRESS does — so `queue.status` /
+// `queue.result` polling is not documented as consuming the concurrency budget, and no separate
+// polling rate limit is published either. That is the dangerous shape: an endpoint with no published
+// ceiling that a completion-polling loop calls as fast as it can. fal's 429 carries type
+// `concurrent_requests_limit` and an `X-Fal-needs-retry: 1` header rather than `Retry-After`.
+//
+// ── HOW THE CEILING WAS CHOSEN ──────────────────────────────────────────────────────────────
+// NO DOCUMENTED REQUESTS-PER-SECOND OR PER-MINUTE LIMIT was found for the queue endpoints, so this
+// budget does NOT claim one. It is pinned to the kernel's conservative fallback (DEFAULT_RATE_BUDGET:
+// 60 weighted units / 60s at weight 2 = 30 calls/minute) — no more permissive than an undeclared
+// vendor already gets. The lowest documented fal number is 2 concurrent requests on a new account,
+// which bounds in-flight work, not call rate.
+//
+// ── WHAT THIS DOES NOT DO: PACE ─────────────────────────────────────────────────────────────
+// It bounds the 60s AVERAGE; it does NOT bound the instantaneous rate. The window has no
+// spacing, so a tight `await` loop can legitimately fire the whole allowance in a fraction of a
+// second. In that shape the vendor's own 429 can arrive BEFORE this ceiling does, and the backstop
+// is then the COOLDOWN: the guard reads the back-off off the thrown error (or the response's
+// exhaustion headers) and refuses every later call without touching the vendor. So the honest claim
+// is "bounds the 60s average, and converts the vendor's first 429 into a hard stop" — never
+// "refuses before the vendor ever 429s". Pacing is the CALLER's job; this module REFUSES, it never
+// sleeps (see the kernel header: it is deliberately not a scheduler). A tighter window would not
+// close the gap, it would only turn every legitimate multi-page pull into a cascade of refusals.
+//
+// ── HOW THE WEIGHTS WERE CHOSEN (and what is a judgement call) ──────────────────────────────
+// `queue.status` costs 4, twice `queue.result`. A JUDGEMENT CALL, not a published cost — fal
+// documents no per-endpoint price. It is priced up because status is the POLLED endpoint: a caller
+// waiting for a request to finish calls it in a loop with no natural bound, whereas `result` is
+// fetched at most once per completed handle. Doubling the poll price halves how long a runaway
+// poll loop can run before it is stopped, and barely touches a normal pull (one status plus one
+// result per handle).
+import { declareRateBudget, rateBudgetPath, rateBudgetWeight, RateBudget, RateBudgetError, } from '@volter/world-core';
+const VENDOR = 'fal';
+/** Rolling window, in ms. Spend older than this is pruned. */
+export const FAL_BUDGET_WINDOW_MS = 60_000;
+/** Weighted units allowed inside one window. See the header for where this number comes from. */
+export const FAL_BUDGET_CEILING = 60;
+/** Seconds. A `Retry-After` above this means the credential is throttled hard — fail loudly. */
+export const FAL_BUDGET_MAX_RETRY_AFTER_S = 300;
+/** Per-call cost, keyed by the client method the guard is about to invoke. See the header. */
+export const FAL_CALL_WEIGHTS = {
+    /** `queue.status` — the endpoint a completion-polling loop hammers. */
+    poll: 4,
+    /** Every other modeled call (`queue.result`, and anything unclassified). */
+    other: 2,
+};
+/**
+ * The client methods this pack PRICES BY NAME, as dotted paths into the injected client.
+ *
+ * Two kinds of entry: (a) every method this connector actually calls, and (b) an endpoint the
+ * VENDOR documents in a distinct tier which a consumer can reach through the guarded client even
+ * though this connector never calls it (see the weights section of the header). Used to build the
+ * guarded surface — and, in the pack's own suite, the counting fake.
+ *
+ * NOT a closed list, and not a claim about the injected client's shape. A path the real client does
+ * not have is SKIPPED (this connector's members are optional; inventing one would turn "observe
+ * nothing" into "call something that isn't there"), and a method absent from this list is still
+ * PRICED at `defaultWeight` when a caller reaches for it — an unmodeled endpoint must never be
+ * free, and dropping one would be worse than free because it would be invisible.
+ */
+export const FAL_BUDGETED_METHODS = [
+    'queue.status',
+    'queue.result',
+];
+/** THE PACK'S DECLARATION — pure data, the only fal-specific thing in the whole budget. */
+export const FAL_RATE_BUDGET = {
+    windowMs: FAL_BUDGET_WINDOW_MS,
+    ceiling: FAL_BUDGET_CEILING,
+    defaultWeight: FAL_CALL_WEIGHTS.other,
+    maxRetryAfterSeconds: FAL_BUDGET_MAX_RETRY_AFTER_S,
+    // Ordered: the kernel prices FIRST-MATCH-WINS, so the tightest tier is listed first.
+    rules: [
+        { match: "(^|\\.)status$", weight: FAL_CALL_WEIGHTS.poll },
+    ],
+    reason: "fal publishes CONCURRENCY limits, not a request rate: 2 concurrent requests on a new account rising to 40 " +
+        "self-serve, and it documents that IN_QUEUE requests do not count toward that limit — so queue.status / " +
+        "queue.result polling has NO published ceiling at all. With no documented figure to aim at, this ceiling is " +
+        "pinned to the kernel's conservative fallback (60 units / 60s at weight 2 = 30 calls/min) rather than " +
+        "invented — no more permissive than an undeclared vendor already gets. queue.status costs 4 because it is " +
+        "the endpoint a completion-polling loop hammers without bound — a judgement call, not a published cost. " +
+        "fal signals back-off with X-Fal-needs-retry rather than Retry-After; the 429 cooldown is the backstop.",
+};
+// Declared at module load, so merely importing this module (which `fal-connector.ts` does) is
+// enough to arm the real ceiling. A budget constructed BEFORE this runs falls back to the kernel's
+// DEFAULT_RATE_BUDGET — which is tighter in call COUNT but prices every call at 2, so for a vendor
+// with an expensive endpoint the fallback is CHEAPER there, not safer. `RateBudget` reads its policy
+// LIVE precisely so this declaration takes effect the moment it lands, and constructing through the
+// subclass below (whose module IS this one) makes the ordering a non-issue in practice.
+declareRateBudget(VENDOR, FAL_RATE_BUDGET);
+/** Price one fal call by its client method key (a dotted path, e.g. `queue.status`). */
+export function falCallWeight(method) {
+    return rateBudgetWeight(VENDOR, method);
+}
+/** Where fal's ledger lives. Token-keyed and cwd-independent by default (the vendor limits per
+ *  credential, so a cwd-scoped ledger would hand the same credential a fresh allowance in every
+ *  checkout, worktree and CI matrix leg); pass `root` to opt into world-scoped accounting. */
+export function falBudgetPath(opts = {}) {
+    const o = typeof opts === 'string' ? { root: opts } : opts;
+    // VENDOR spread LAST: a loosely-typed `{ vendor: 'other', … }` slipping through (TypeScript's
+    // excess-property check only catches object literals) must not redirect this pack's ledger to
+    // another vendor's file.
+    return rateBudgetPath({ ...o, vendor: VENDOR });
+}
+/**
+ * fal's budget — the shared kernel guard bound to this vendor's declaration. A real subclass,
+ * not an alias, so `budget instanceof FalBudget` means "a budget that accounts against this
+ * vendor's ledger under this vendor's ceiling": another vendor's `RateBudget` (with its own,
+ * possibly larger, ceiling) is NOT assignable where one of these is required.
+ */
+export class FalBudget extends RateBudget {
+    constructor(opts = {}) {
+        super({ ...opts, vendor: VENDOR });
+    }
+}
+export { RateBudgetError as FalBudgetError } from '@volter/world-core';
+/** Pull the budget wiring out of a caller's opts bag, so an entrypoint can forward it verbatim. */
+export function falBudgetOf(opts) {
+    return {
+        ...(opts.budget !== undefined ? { budget: opts.budget } : {}),
+        ...(opts.budgetOptions !== undefined ? { budgetOptions: opts.budgetOptions } : {}),
+    };
+}
+// ── the choke point ─────────────────────────────────────────────────────────────────────────
+/**
+ * Marks a client this module has already wrapped, so guarding twice cannot charge twice.
+ *
+ * A MODULE-PRIVATE `Symbol()`, deliberately not `Symbol.for()`: a global-registry symbol is
+ * reachable BY NAME, so any caller could stamp `client[Symbol.for(…)] = anything` on a RAW client and
+ * the guard would hand it straight back UNGUARDED — a one-line bypass of the whole budget. With a
+ * private symbol the only way to be branded is to have been wrapped by this function. The cost is
+ * that two copies of this module in one dependency tree would each wrap (double-charging a call);
+ * that is the SAFE direction, and over-charging is the tradeoff this module takes everywhere else.
+ */
+const GUARDED = Symbol('@volter/twin-fal.budget.guarded');
+/** Is this client already behind a budget? Returns the budget it is behind, if so. */
+export function falClientBudget(client) {
+    const mark = client?.[GUARDED];
+    // Belt and braces: only a REAL budget counts as "already guarded". A non-RateBudget value here
+    // could only come from a forged brand, and the answer to a forgery is to wrap anyway.
+    return mark instanceof RateBudget ? mark : undefined;
+}
+/**
+ * Wrap an INJECTED fal client so EVERY call it makes is charged against the shared budget
+ * BEFORE the request goes out. This pack's connector never constructs the transport itself (the
+ * consumer injects a client that satisfies `FalLikeClient` structurally), so the guard is a
+ * DECORATOR rather than a factory — which is exactly why every connector entrypoint applies it
+ * UNCONDITIONALLY instead of trusting the caller to have done it.
+ *
+ * IDEMPOTENT: wrapping an already-guarded client returns it unchanged, so a caller who forgot is
+ * protected and a caller who wrapped deliberately is not double-charged.
+ *
+ * A method that THROWS is still inspected: an SDK typically RAISES on a 429 rather than returning
+ * it, and that error's back-off is exactly the signal that must become a persisted cooldown. Losing
+ * it would leave the ledger cheerfully spending into a throttled credential. The original error is
+ * always re-raised afterwards — the budget never swallows a vendor failure — EXCEPT when the
+ * back-off is beyond the cap, where the budget's own louder "stop calling" error takes precedence.
+ */
+export function guardFalClient(client, opts = {}) {
+    // There is no value a caller can pass to end up with an UNGUARDED client. `null`/`undefined` (or
+    // omitting it) build the default budget; anything that is not a REAL `FalBudget` is refused
+    // loudly rather than trusted — a duck-typed stand-in with a no-op `checkBudget` would otherwise be
+    // the one clean way around the guard. Validated BEFORE the already-guarded early return, so
+    // `guardFalClient(alreadyGuarded, { budget: impostor })` is refused too rather than silently
+    // ignoring the impostor.
+    if (opts.budget !== undefined && opts.budget !== null && !(opts.budget instanceof FalBudget)) {
+        throw new Error('guardFalClient: `budget` must be a FalBudget — refusing to guard a fal client with an unverified rate guard');
+    }
+    if (falClientBudget(client))
+        return client;
+    const budget = opts.budget instanceof FalBudget
+        ? opts.budget
+        : new FalBudget({
+            // The default ledger is keyed by a hash of the credential — the vendor limits per credential,
+            // so a cwd-scoped ledger would hand it a fresh allowance per worktree/CI leg.
+            //
+            // HONESTLY: this pack does NOT hold the credential — the consumer's injected client does — so
+            // `FAL_KEY` is a BEST-EFFORT stand-in for it, not the real thing. If that env var names a
+            // different account than the injected client, spend is booked against the wrong ledger; if it
+            // is unset, every unattributed fal credential on the machine shares one (over-tight,
+            // which is the safe direction). A caller who knows the credential should say so:
+            // `budgetOptions: { token }` overrides this, and does so deliberately last in the spread.
+            ...(process.env.FAL_KEY !== undefined ? { token: process.env.FAL_KEY } : {}),
+            ...(opts.budgetOptions ?? {}),
+        });
+    /** Settle a reservation from whatever the call produced. May THROW (a back-off past the cap). */
+    const settle = (weight, reservation, v) => {
+        const status = responseStatus(v);
+        const headers = responseHeaders(v);
+        if (status !== undefined || headers !== undefined)
+            budget.recordCall(weight, headers, { status, reservation });
+        else
+            budget.recordCall(weight, undefined, { reservation });
+    };
+    /**
+     * Settle once the call RESOLVED: the vendor has answered. recordCall arms any cooldown before
+     * it throws (a back-off beyond the cap), so that refusal is swallowed and the answer kept — a
+     * write the vendor accepted is never reported failed and performed again on retry. A resolved
+     * answer that carries a non-2xx status still lets the louder refusal win.
+     */
+    const settleAnswered = (weight, reservation, v) => {
+        try {
+            settle(weight, reservation, v);
+        }
+        catch (e) {
+            const status = responseStatus(v);
+            if (!(e instanceof RateBudgetError) || (status !== undefined && (status < 200 || status >= 300)))
+                throw e;
+        }
+    };
+    /**
+     * Charge, call, settle — for a MODELED method, whose interface declares it `async`. Refusing
+     * REJECTS rather than throwing synchronously, so `client.x().catch(…)` behaves exactly as it does
+     * on an unguarded client. `checkBudget` RESERVES under lock, so nothing after its line runs when
+     * the budget refuses: the request is never made.
+     */
+    const chargeAsync = (method, invoke) => async (...args) => {
+        const weight = budget.weightFor(method);
+        const reservation = budget.checkBudget(weight);
+        try {
+            const res = await invoke(...args);
+            settleAnswered(weight, reservation, res);
+            return res;
+        }
+        catch (e) {
+            settle(weight, reservation, e); // may throw its own louder refusal, which wins
+            throw e;
+        }
+    };
+    /**
+     * Charge, call, settle — for an UNMODELED member reached through the passthrough Proxy, where the
+     * shape is unknown.
+     *
+     * Deliberately NOT `async`. Some vendor SDKs (twilio-shaped ones) build requests through
+     * SYNCHRONOUS chained accessors — `client.a.b('sid').c.create()` — where the intermediate calls
+     * return a resource context, not a promise. An `async` wrapper would turn every one of those into
+     * a `Promise` and `.c` would come back `undefined`: the guard would BREAK the client instead of
+     * guarding it. So a non-thenable return is treated as an accessor — still charged (we cannot know
+     * before calling, and over-charging is the safe direction) and wrapped, so the eventual async leaf
+     * is charged too rather than escaping the budget. The cost of the sync shape is that a REFUSAL on
+     * this path throws synchronously instead of rejecting; that is the honest signal for an accessor,
+     * and the modeled surface above (every method this connector actually calls) does not have it.
+     */
+    const charge = (method, invoke) => (...args) => {
+        const weight = budget.weightFor(method);
+        const reservation = budget.checkBudget(weight);
+        let out;
+        try {
+            out = invoke(...args);
+        }
+        catch (e) {
+            settle(weight, reservation, e); // may throw its own louder refusal, which wins
+            throw e;
+        }
+        if (!isThenable(out)) {
+            settle(weight, reservation, undefined);
+            return out !== null && (typeof out === 'object' || typeof out === 'function')
+                ? proxyThrough({}, out, method, charge)
+                : out;
+        }
+        return out.then((res) => { settleAnswered(weight, reservation, res); return res; }, (e) => { settle(weight, reservation, e); throw e; });
+    };
+    // Build the charged surface from FAL_BUDGETED_METHODS (see its docstring for why an absent path is
+    // SKIPPED rather than stubbed).
+    const guarded = {};
+    for (const path of FAL_BUDGETED_METHODS) {
+        const segs = path.split('.');
+        const leaf = segs[segs.length - 1];
+        let owner = client;
+        for (const seg of segs.slice(0, -1))
+            owner = owner?.[seg];
+        if (typeof owner?.[leaf] !== 'function')
+            continue;
+        const realOwner = owner;
+        let node = guarded;
+        for (const seg of segs.slice(0, -1))
+            node = (node[seg] ??= {});
+        // The method is resolved at CALL time, not here, so a client whose method is swapped later is
+        // still charged for whatever it actually runs.
+        node[leaf] = chargeAsync(path, (...args) => realOwner[leaf].apply(realOwner, args));
+    }
+    Object.defineProperty(guarded, GUARDED, { value: budget, enumerable: false });
+    // The surface above is what this connector calls. A real client has MORE — and a consumer who
+    // needs any of it must not be forced to keep the RAW client alongside, because every call through
+    // that would be unbudgeted. So the guarded object is a Proxy: known members come from the map
+    // above, anything else is taken from the real client and PRICED at `defaultWeight`.
+    return proxyThrough(guarded, client, '', charge);
+}
+/**
+ * Members JavaScript itself asks for. Wrapping any of these turns the object into something that
+ * looks thenable / mis-reports its own identity, which breaks `await`, `instanceof` and logging —
+ * so they always come from the target untouched, never priced.
+ */
+const NEVER_WRAP = new Set(['then', 'catch', 'finally', 'constructor', 'prototype', 'toJSON', 'toString', 'valueOf', 'inspect']);
+/** Does this look like a promise? (Only a thenable gets the settle-on-resolution treatment.) */
+function isThenable(v) {
+    return v !== null && (typeof v === 'object' || typeof v === 'function') && typeof v.then === 'function';
+}
+/**
+ * Symbols that name an ITERATION PROTOCOL. Reaching for one of these on a vendor object is how a
+ * paginator is driven (`for await (const page of client.things.list())`), i.e. it is the doorway to
+ * an unbounded sequence of REQUESTS — exactly what this budget exists to bound — so they are charged
+ * and their result is kept behind the proxy. Every other symbol (`Symbol.toStringTag`,
+ * `nodejs.util.inspect.custom`, …) is metadata rather than a request and passes through untouched.
+ */
+const ITERATOR_SYMBOLS = new Set([Symbol.asyncIterator, Symbol.iterator]);
+/**
+ * Serve `known` where it has the member; otherwise price a passthrough to `real`. Applied
+ * recursively, so a namespace member this pack never modeled is charged at `defaultWeight` rather
+ * than coming back `undefined`.
+ *
+ * CALLABLE NAMESPACES (§9 finding): a member can be BOTH a function and a namespace — twilio's
+ * `client.messages` is called as `client.messages(sid)` to get one message's context AND read as
+ * `client.messages.list()`. An earlier version returned the modeled node as a plain object whenever
+ * this pack modeled any child of it, which silently DROPPED the call signature and every unmodeled
+ * sibling — the module's own docstring calls a dropped member "worse than free, because it is
+ * invisible", and that is what it was doing. So when `real` is callable the proxy target is a
+ * function and an `apply` trap charges the call, while `known` stays the source of modeled members.
+ */
+function proxyThrough(known, real, prefix, charge, owner) {
+    const callable = typeof real === 'function';
+    // The target must itself be callable for the `apply` trap to exist at all. `known` stays the
+    // source of modeled members, read explicitly below rather than through the target.
+    const target = callable ? function proxied() { } : known;
+    return new Proxy(target, {
+        apply(_t, _thisArg, args) {
+            // Calling the namespace is itself a request-builder hop: charge it, and keep the result
+            // behind the proxy (charge() re-proxies a non-thenable) so the eventual leaf is charged too.
+            // `owner` is the object the function was read from — dropping it would silently break every
+            // method that relies on `this`.
+            return charge(prefix || 'call', (...a) => real.apply(owner, a))(...args);
+        },
+        get(_t, prop, receiver) {
+            if (typeof prop === 'symbol') {
+                const ownSym = Reflect.get(known, prop, receiver);
+                if (ownSym !== undefined)
+                    return ownSym; // the GUARDED brand, and anything we model
+                const fromSym = real?.[prop];
+                if (ITERATOR_SYMBOLS.has(prop) && typeof fromSym === 'function') {
+                    return charge(`${prefix}[${prop.description ?? 'iterator'}]`, (...args) => fromSym.apply(real, args));
+                }
+                return fromSym;
+            }
+            const name = String(prop);
+            if (NEVER_WRAP.has(name))
+                return Reflect.get(known, prop, receiver);
+            const key = prefix ? `${prefix}.${name}` : name;
+            const own = Reflect.get(known, prop, receiver);
+            const from = real?.[name];
+            // A member we model: the charged wrapper (a function) or a namespace we must keep descending
+            // into, so an unmodeled sibling is still priced rather than dropped.
+            if (typeof own === 'function')
+                return own;
+            if (own && typeof own === 'object') {
+                // `from` may be an object OR a CALLABLE namespace — both keep descending, which is what
+                // preserves `client.messages(sid)` alongside the modeled `client.messages.list()`.
+                return from && (typeof from === 'object' || typeof from === 'function')
+                    ? proxyThrough(own, from, key, charge, real)
+                    : own;
+            }
+            if (own !== undefined)
+                return own;
+            // A member only the real client has. Functions go through proxyThrough too, so one that also
+            // carries members (a callable namespace) keeps both its call signature and its siblings.
+            if (typeof from === 'function')
+                return proxyThrough({}, from, key, charge, real);
+            if (from && typeof from === 'object')
+                return proxyThrough({}, from, key, charge, real);
+            return from;
+        },
+        has(_t, prop) {
+            return Reflect.has(known, prop) || (real !== null && Reflect.has(real, prop));
+        },
+    });
+}
+/** The HTTP status a value carries, if it looks like one (an SDK error, or a raw response). */
+function responseStatus(v) {
+    const s = v?.status;
+    return typeof s === 'number' && Number.isFinite(s) ? s : undefined;
+}
+/**
+ * Response/error headers as a plain lower-cased record, or `undefined` when there are none. Accepts
+ * a `Headers` instance, a `Map`, or a plain object — an SDK's error type changes shape across
+ * versions and none of the three is worth depending on.
+ */
+function responseHeaders(v) {
+    const h = v?.headers;
+    if (!h || typeof h !== 'object')
+        return undefined;
+    const out = {};
+    if (typeof h.forEach === 'function') {
+        h.forEach((value, key) => { out[String(key).toLowerCase()] = String(value); });
+    }
+    else {
+        for (const [k, value] of Object.entries(h))
+            out[k.toLowerCase()] = String(value);
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}

package/dist/src/fal-capabilities.d.ts

@@ -0,0 +1,4 @@
+import { type CapabilityReport, type CapabilitySpec } from '@volter/world-tooling';
+export declare const FAL_CAPABILITIES: CapabilitySpec[];
+export declare const FAL_AREAS: readonly ["queue", "sync", "streaming", "realtime", "webhooks", "storage", "apps", "proxy", "auth", "errors", "connector", "conformance", "safety", "state"];
+export declare function falCapabilities(): Promise<CapabilityReport>;