@volter/twin-x 0.1.0

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

@@ -0,0 +1,54 @@
+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 X_BUDGET_WINDOW_MS: number;
+/** Weighted units allowed inside one window. See the EVIDENCE BOUNDARY above: conservative, not
+ *  transcribed. */
+export declare const X_BUDGET_CEILING = 50;
+/** Weighted units allowed in any 60s (the kernel's burst sub-window): 10, well under the kernel
+ *  fallback's burst of 30, so no VENDOR_BURST_ANCHOR entry is required in
+ *  scripts/rate-budget-isolation.test.ts. */
+export declare const X_BUDGET_BURST_CEILING = 10;
+/** Seconds. A `Retry-After` above this means the client is throttled hard — fail loudly, don't sleep. */
+export declare const X_BUDGET_MAX_RETRY_AFTER_S = 900;
+/** Per-call cost, keyed by `"<METHOD> <path>"`. */
+export declare const X_CALL_WEIGHTS: {
+    /** A post or a reply — the org's public voice SPEAKING. The expensive act. */
+    readonly write: 5;
+    /** Reading who mentioned the org. Cheap: it is the input to a decision, not an act. */
+    readonly read: 1;
+    /** A media upload call (one-shot, initialize, append, finalize) and its STATUS read. Staging a
+     *  file publishes nothing — only the post that attaches it speaks — so it is priced as a read:
+     *  the smallest weight the kernel allows, the post itself still paying the write. */
+    readonly media: 1;
+    /** Everything else on the vendor: no figure of our own → priced at the write. */
+    readonly other: 5;
+};
+/** THE PACK'S DECLARATION — pure data, the only X-specific thing in the whole budget. */
+export declare const X_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/tweets')` really does post in public and must be priced as one.
+ */
+export declare function xCallWeight(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 xBudgetPath(opts?: {
+    root?: string;
+    token?: string;
+} | string): string;
+/** Construction options. The vendor is fixed; everything else may only TIGHTEN. */
+export type XBudgetOptions = Omit<RateBudgetOptions, 'vendor'>;
+/**
+ * This vendor's budget — the shared kernel guard bound to this declaration. A real subclass, not
+ * an alias, so `budget instanceof XBudget` means "a budget that accounts against X's ledger under
+ * X's ceiling".
+ */
+export declare class XBudget extends RateBudget {
+    constructor(opts?: XBudgetOptions);
+}
+export { RateBudgetError as XBudgetError } from '@volter/world-core';
+export type { RateBudgetErrorKind as XBudgetErrorKind } from '@volter/world-core';
+export type XBudgetReservation = RateBudgetReservation;
+export type XBudgetSnapshot = RateBudgetSnapshot;

package/dist/src/x-budget.js

@@ -0,0 +1,123 @@
+// The X posting surface's CLIENT-SIDE RATE BUDGET — this pack's DECLARATION (the numbers) plus
+// the thin typed bindings `liveXExecute` 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 ──────────────────────────────────────────────────────────────
+// The vendor's SCHEME is first-party and recorded in this repo: X publishes per-endpoint rate
+// limits on 15-minute windows and answers an exceeded window with HTTP 429 and legacy error
+// code 88 (docs.x.com/x-api/fundamentals/rate-limits, fetched 2026-08-21 — the fetch recorded in
+// spec-sources.json's `xidentity` entry, and transcribed by
+// packages/twin/xidentity/src/xidentity-budget.ts). This declaration transcribes the SCHEME: the
+// window is the vendor's own 15 minutes, and 429/code-88 is what the guard expects back.
+//
+// EVIDENCE BOUNDARY — READ THIS BEFORE TRUSTING THE NUMBER. The per-endpoint FIGURES for the
+// POSTING endpoints (`POST /2/tweets`, `DELETE /2/tweets/:id`, `GET /2/users/:id/mentions`) were
+// NOT fetched by this build: no X call is made anywhere in this pack, by standing rule, and the
+// figure recorded in this repo covers `GET /2/users/me` only. So the ceiling here is NOT a
+// transcription — it is a deliberately CONSERVATIVE choice: 50 weighted units per 15 minutes,
+// BELOW every posting figure X is reported to publish, with a WRITE priced at 5 and a read at 1
+// so a runaway poster exhausts the budget an order of magnitude before a runaway reader does.
+// Pinning these to the vendor's published figures is `x.rate_limit.published_figures` (todo).
+// A budget that is too tight fails closed and costs a retry; one that is too loose spends a real
+// org's real posting allowance, so the asymmetry decides the direction.
+import { declareRateBudget, rateBudgetPath, rateBudgetWeight, RateBudget, } from '@volter/world-core';
+const VENDOR = 'x';
+/** Rolling window, in ms — X's own 15-minute rate-limit window. */
+export const X_BUDGET_WINDOW_MS = 15 * 60_000;
+/** Weighted units allowed inside one window. See the EVIDENCE BOUNDARY above: conservative, not
+ *  transcribed. */
+export const X_BUDGET_CEILING = 50;
+/** Weighted units allowed in any 60s (the kernel's burst sub-window): 10, well under the kernel
+ *  fallback's burst of 30, so no VENDOR_BURST_ANCHOR entry is required in
+ *  scripts/rate-budget-isolation.test.ts. */
+export const X_BUDGET_BURST_CEILING = 10;
+/** Seconds. A `Retry-After` above this means the client is throttled hard — fail loudly, don't sleep. */
+export const X_BUDGET_MAX_RETRY_AFTER_S = 900;
+/** Per-call cost, keyed by `"<METHOD> <path>"`. */
+export const X_CALL_WEIGHTS = {
+    /** A post or a reply — the org's public voice SPEAKING. The expensive act. */
+    write: 5,
+    /** Reading who mentioned the org. Cheap: it is the input to a decision, not an act. */
+    read: 1,
+    /** A media upload call (one-shot, initialize, append, finalize) and its STATUS read. Staging a
+     *  file publishes nothing — only the post that attaches it speaks — so it is priced as a read:
+     *  the smallest weight the kernel allows, the post itself still paying the write. */
+    media: 1,
+    /** Everything else on the vendor: no figure of our own → priced at the write. */
+    other: 5,
+};
+/** THE PACK'S DECLARATION — pure data, the only X-specific thing in the whole budget. */
+export const X_RATE_BUDGET = {
+    windowMs: X_BUDGET_WINDOW_MS,
+    ceiling: X_BUDGET_CEILING,
+    burstCeiling: X_BUDGET_BURST_CEILING,
+    defaultWeight: X_CALL_WEIGHTS.other,
+    maxRetryAfterSeconds: X_BUDGET_MAX_RETRY_AFTER_S,
+    rules: [
+        { match: '^POST /2/tweets$', weight: X_CALL_WEIGHTS.write },
+        { match: '^DELETE /2/tweets/', weight: X_CALL_WEIGHTS.write },
+        { match: '^GET /2/users/[^/]+/mentions$', weight: X_CALL_WEIGHTS.read },
+        { match: '^POST /2/media/upload(?:/initialize|/[0-9]+/(?:append|finalize))?$', weight: X_CALL_WEIGHTS.media },
+        { match: '^GET /2/media/upload$', weight: X_CALL_WEIGHTS.media },
+    ],
+    reason: "X publishes per-endpoint rate limits on 15-minute windows and answers an exceeded window with "
+        + 'HTTP 429 and legacy error code 88 (docs.x.com/x-api/fundamentals/rate-limits, fetched '
+        + '2026-08-21 and recorded in spec-sources.json under xidentity). The WINDOW here is the '
+        + "vendor's own 15 minutes and the 429/code-88 pair is what the guard expects back. The "
+        + 'per-endpoint FIGURES for the posting endpoints were NOT fetched by this build — no X call is '
+        + 'made anywhere in this pack, and the figure this repo holds covers GET /2/users/me only — so '
+        + 'the ceiling of 50 units is a deliberately CONSERVATIVE choice rather than a transcription, '
+        + 'sitting below every posting figure X is reported to publish. A write (a post or a reply — the '
+        + "org's public voice speaking, on a real account, in public) costs 5; reading the mentions "
+        + 'timeline costs 1, because reading is the input to a decision and posting is the act. So a '
+        + 'runaway poster exhausts the window after ten posts while a runaway reader gets fifty reads. '
+        + 'A media upload call (one-shot, initialize, append, finalize, STATUS) costs 1: staging a file '
+        + 'publishes nothing, and the post that attaches it still pays the write. '
+        + 'Pinning these to the vendor\'s published posting figures is x.rate_limit.published_figures '
+        + '(todo). A budget that is too tight fails closed and costs a retry; one that is too loose '
+        + "spends a real org's real posting allowance in public, so the asymmetry decides the direction. "
+        + "The burstCeiling of 10 units/60s bounds the instant and stays under the kernel fallback's 30.",
+};
+// Declared at module load, so merely importing this module (which `x-connector.ts` does) is
+// enough to arm the real ceiling.
+declareRateBudget(VENDOR, X_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/tweets')` really does post in public and must be priced as one.
+ */
+export function xCallWeight(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 xBudgetPath(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 XBudget` means "a budget that accounts against X's ledger under
+ * X's ceiling".
+ */
+export class XBudget extends RateBudget {
+    constructor(opts = {}) {
+        super({ ...opts, vendor: VENDOR });
+    }
+}
+export { RateBudgetError as XBudgetError } from '@volter/world-core';

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

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