@volter/twin-xidentity 0.1.0

package/dist/src/xidentity-budget.d.ts

@@ -0,0 +1,50 @@
+import { RateBudget, type RateBudgetDeclaration, type RateBudgetOptions, type RateBudgetReservation, type RateBudgetSnapshot } from '@volter/world-core';
+/** Rolling window, in ms — X's own 15-minute rate-limit window. */
+export declare const XIDENTITY_BUDGET_WINDOW_MS: number;
+/** Weighted units allowed inside one window — X's own per-user allowance for GET /2/users/me. */
+export declare const XIDENTITY_BUDGET_CEILING = 75;
+/** Weighted units allowed in any 60s (the kernel's burst sub-window): 3× the window's average
+ *  pace, and UNDER the kernel fallback's burst of 30. */
+export declare const XIDENTITY_BUDGET_BURST_CEILING = 15;
+/** Seconds. A `Retry-After` above this means the client is throttled hard — fail loudly, don't sleep. */
+export declare const XIDENTITY_BUDGET_MAX_RETRY_AFTER_S = 900;
+/** Per-call cost, keyed by `"<METHOD> <path>"`. See the header for what is documented vs. judged. */
+export declare const XIDENTITY_CALL_WEIGHTS: {
+    /** `GET /2/users/me` — 75/15min per user is the PUBLISHED limit; weight 1 transcribes it. */
+    readonly usersMe: 1;
+    /** `POST /2/oauth2/revoke` — logs a human out of an app on a REAL account. Priced as a human
+     *  blast radius, not a throttle (a judgement call, stated as one). */
+    readonly revoke: 15;
+    /** Everything else (the token endpoint): no published scalar limit → priced conservatively. */
+    readonly other: 3;
+};
+/** THE PACK'S DECLARATION — pure data, the only X-specific thing in the whole budget. */
+export declare const XIDENTITY_RATE_BUDGET: RateBudgetDeclaration;
+/**
+ * Price one call. The key is `"<METHOD> <path>"` with the query string split off. NORMALIZED
+ * (upper-cased method, collapsed trailing slash) because the anchored rules are otherwise trivially
+ * evaded by input variation: `fetch` upper-cases a known method before sending, so
+ * `execute('post', '/2/oauth2/revoke')` really does issue the destructive call and must be priced
+ * as one.
+ */
+export declare function xIdentityCallWeight(method: string, path: string): number;
+/** Where this vendor's ledger lives. Token-keyed and cwd-independent by default; pass `root` to
+ *  opt into world-scoped accounting. */
+export declare function xIdentityBudgetPath(opts?: {
+    root?: string;
+    token?: string;
+} | string): string;
+/** Construction options. The vendor is fixed; everything else may only TIGHTEN. */
+export type XIdentityBudgetOptions = Omit<RateBudgetOptions, 'vendor'>;
+/**
+ * This vendor's budget — the shared kernel guard bound to this declaration. A real subclass, not
+ * an alias, so `budget instanceof XIdentityBudget` means "a budget that accounts against
+ * XIDENTITY's ledger under XIDENTITY's ceiling".
+ */
+export declare class XIdentityBudget extends RateBudget {
+    constructor(opts?: XIdentityBudgetOptions);
+}
+export { RateBudgetError as XIdentityBudgetError } from '@volter/world-core';
+export type { RateBudgetErrorKind as XIdentityBudgetErrorKind } from '@volter/world-core';
+export type XIdentityBudgetReservation = RateBudgetReservation;
+export type XIdentityBudgetSnapshot = RateBudgetSnapshot;

package/dist/src/xidentity-budget.js

@@ -0,0 +1,108 @@
+// X identity's CLIENT-SIDE RATE BUDGET — this pack's DECLARATION (the numbers) plus the thin typed
+// bindings `liveXIdentityExecute` uses. 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`).
+//
+// ── HOW THE CEILING WAS CHOSEN (live-fetched first-party figures) ───────────────────────────────
+// X PUBLISHES per-endpoint rate limits. From https://docs.x.com/x-api/fundamentals/rate-limits
+// (fetched 2026-08-21): `GET /2/users/me` is **75 requests / 15 minutes per user** (no per-app
+// row), other user lookups are 300/15min (app) and 900/15min (user), windows are 15 minutes, and
+// exceeding one answers HTTP 429 with legacy code 88. The OAuth token/revoke endpoints publish NO
+// scalar limit on that page — that absence is stated here rather than dressed up, and those calls
+// are priced ABOVE the documented read so the undocumented surface is the conservative one.
+//
+// The window is therefore the vendor's own 15 minutes and the ceiling is the vendor's own 75,
+// with `GET /2/users/me` at weight 1 — the declaration REPRODUCES the published per-user budget
+// for the one endpoint the connector reads (the github-budget precedent: when the vendor's scheme
+// is already a windowed budget, transcribe it). The kernel demands a `burstCeiling` for any
+// window longer than its 60s burst sub-window; 15 units/60s (15 users/me reads a minute, 3× the
+// window's average pace) bounds the instant WITHOUT out-bursting the kernel fallback's 30, so no
+// VENDOR_BURST_ANCHOR entry is required in `scripts/rate-budget-isolation.test.ts`.
+import { declareRateBudget, rateBudgetPath, rateBudgetWeight, RateBudget, } from '@volter/world-core';
+const VENDOR = 'xidentity';
+/** Rolling window, in ms — X's own 15-minute rate-limit window. */
+export const XIDENTITY_BUDGET_WINDOW_MS = 15 * 60_000;
+/** Weighted units allowed inside one window — X's own per-user allowance for GET /2/users/me. */
+export const XIDENTITY_BUDGET_CEILING = 75;
+/** Weighted units allowed in any 60s (the kernel's burst sub-window): 3× the window's average
+ *  pace, and UNDER the kernel fallback's burst of 30. */
+export const XIDENTITY_BUDGET_BURST_CEILING = 15;
+/** Seconds. A `Retry-After` above this means the client is throttled hard — fail loudly, don't sleep. */
+export const XIDENTITY_BUDGET_MAX_RETRY_AFTER_S = 900;
+/** Per-call cost, keyed by `"<METHOD> <path>"`. See the header for what is documented vs. judged. */
+export const XIDENTITY_CALL_WEIGHTS = {
+    /** `GET /2/users/me` — 75/15min per user is the PUBLISHED limit; weight 1 transcribes it. */
+    usersMe: 1,
+    /** `POST /2/oauth2/revoke` — logs a human out of an app on a REAL account. Priced as a human
+     *  blast radius, not a throttle (a judgement call, stated as one). */
+    revoke: 15,
+    /** Everything else (the token endpoint): no published scalar limit → priced conservatively. */
+    other: 3,
+};
+/** THE PACK'S DECLARATION — pure data, the only X-specific thing in the whole budget. */
+export const XIDENTITY_RATE_BUDGET = {
+    windowMs: XIDENTITY_BUDGET_WINDOW_MS,
+    ceiling: XIDENTITY_BUDGET_CEILING,
+    burstCeiling: XIDENTITY_BUDGET_BURST_CEILING,
+    defaultWeight: XIDENTITY_CALL_WEIGHTS.other,
+    maxRetryAfterSeconds: XIDENTITY_BUDGET_MAX_RETRY_AFTER_S,
+    rules: [
+        { match: '^GET /2/users/me$', weight: XIDENTITY_CALL_WEIGHTS.usersMe },
+        { match: '^POST /2/oauth2/revoke$', weight: XIDENTITY_CALL_WEIGHTS.revoke },
+    ],
+    reason: 'X publishes per-endpoint rate limits (https://docs.x.com/x-api/fundamentals/rate-limits, '
+        + 'fetched 2026-08-21): GET /2/users/me is 75 requests / 15 minutes PER USER, windows are 15 '
+        + 'minutes, and exceeding one answers HTTP 429 with legacy code 88 "Rate limit exceeded". This '
+        + "declaration transcribes that scheme: the window is the vendor's own 15 minutes, the ceiling "
+        + "is the vendor's own 75, and GET /2/users/me costs 1 — the one documented figure for the one "
+        + 'endpoint the connector reads. The OAuth token and revoke endpoints publish NO scalar limit '
+        + 'on that page; they are priced ABOVE the documented read (defaultWeight 3, revoke 15) so the '
+        + 'undocumented surface is the conservative one. POST /2/oauth2/revoke costs 15 because it is '
+        + 'the one destructive call here — it logs a human out of an app on a REAL account — which is a '
+        + 'human blast radius, not a throttle; that price is a judgement call, stated as one. The '
+        + "burstCeiling of 15 units/60s (3x the window's average pace, under the kernel fallback's "
+        + 'burst of 30) bounds the instant, and the 429 / Retry-After cooldown is the backstop.',
+};
+// Declared at module load, so merely importing this module (which `xidentity-connector.ts` does)
+// is enough to arm the real ceiling.
+declareRateBudget(VENDOR, XIDENTITY_RATE_BUDGET);
+/**
+ * Price one call. The key is `"<METHOD> <path>"` with the query string split off. NORMALIZED
+ * (upper-cased method, collapsed trailing slash) because the anchored rules are otherwise trivially
+ * evaded by input variation: `fetch` upper-cases a known method before sending, so
+ * `execute('post', '/2/oauth2/revoke')` really does issue the destructive call and must be priced
+ * as one.
+ */
+export function xIdentityCallWeight(method, path) {
+    const { bare, query } = splitQuery(path);
+    return rateBudgetWeight(VENDOR, `${String(method).toUpperCase()} ${bare}`, query);
+}
+function splitQuery(path) {
+    const at = path.indexOf('?');
+    const query = {};
+    if (at !== -1)
+        for (const [k, v] of new URLSearchParams(path.slice(at + 1)))
+            query[k] = v;
+    const raw = at === -1 ? path : path.slice(0, at);
+    const bare = raw.length > 1 && raw.endsWith('/') ? raw.replace(/\/+$/, '') : raw;
+    return { bare, query };
+}
+/** Where this vendor's ledger lives. Token-keyed and cwd-independent by default; pass `root` to
+ *  opt into world-scoped accounting. */
+export function xIdentityBudgetPath(opts = {}) {
+    const o = typeof opts === 'string' ? { root: opts } : opts;
+    // VENDOR spread LAST: a loosely-typed `{ vendor: 'other', … }` slipping through must not
+    // redirect this pack's ledger.
+    return rateBudgetPath({ ...o, vendor: VENDOR });
+}
+/**
+ * This vendor's budget — the shared kernel guard bound to this declaration. A real subclass, not
+ * an alias, so `budget instanceof XIdentityBudget` means "a budget that accounts against
+ * XIDENTITY's ledger under XIDENTITY's ceiling".
+ */
+export class XIdentityBudget extends RateBudget {
+    constructor(opts = {}) {
+        super({ ...opts, vendor: VENDOR });
+    }
+}
+export { RateBudgetError as XIdentityBudgetError } from '@volter/world-core';

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

@@ -0,0 +1,3 @@
+import { type CapabilityReport, type CapabilitySpec } from '@volter/world-tooling';
+export declare const XIDENTITY_CAPABILITIES: CapabilitySpec[];
+export declare function xidentityCapabilities(): Promise<CapabilityReport>;