@volter/twin-xai 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,246 @@
+# @volter/twin-xai
+
+A local, faithful **xAI (Grok) API** twin the real `@ai-sdk/xai` provider — or any
+OpenAI-compatible client — talks to unmodified: point it at the twin's `baseURL` and
+`generateText`/`streamText` (with tools), deferred completions, the grok model catalogs,
+Live Search parameters, api-key introspection, and tokenize-text all work. Built on the
+shared `@volter/world-core` kernel; see [the model](../../../docs/concepts/the-model.md) for storage and branching; no parallel side store.
+
+The same server also covers the official Grok Build CLI's documented chat-proxy seam.
+Generated Worlds seal both sides independently: `XAI_TWIN_AUTH_BASE_URL=${url}` exposes the
+virtual account's device authorization/token exchange/refresh surface to a consuming credential
+broker, while `GROK_CLI_CHAT_PROXY_BASE_URL=${url}/v1` routes inference. The virtual account issues
+the lease bearer that broker supplies to the CLI through Grok Build's external-auth provider command; the
+Twin honors `X-XAI-Token-Auth` and `x-grok-model-override` (including
+`grok-build`), and successful calls accumulate on that same account's virtual usage ledger.
+Remove either override—and set `TWIN_XAI_AUTH_SEAM=unsealed` when combining real OAuth with
+twinned inference—for an explicit partial-unseal acceptance run. No real renewable credential
+is copied into a sealed World. The official CLI does **not** consume
+`XAI_TWIN_AUTH_BASE_URL`: direct `grok login --device-auth` still uses xAI's fixed device-login
+origin and is an explicit capability todo, not a claimed sealed path.
+
+```ts
+import { createXai } from '@ai-sdk/xai';
+import { generateText } from 'ai';
+import { createXaiTwinServer } from '@volter/twin-xai';
+
+const { port } = createXaiTwinServer({});
+const xai = createXai({ apiKey: 'xai-twin', baseURL: `http://127.0.0.1:${port}/v1` });
+const res = await generateText({ model: xai('grok-4-0709'), prompt: 'hello' });
+// res.text starts with "[twin-stub:grok-4-0709]" — a deterministic stub, clearly labeled.
+```
+
+## The generative-stub design (be honest)
+
+The twin **cannot run Grok** — there are no weights here. So `POST /v1/chat/completions`,
+`POST /v1/completions`, and `POST /v1/messages` return a **deterministic STUB completion**
+that is unmistakably a twin stub (it carries a `[twin-stub:<model>]` marker and echoes your
+prompt), and **Live Search** returns deterministic **labeled stub citations** on a
+`twin.invalid` host — they **never** pretend to be real model output or real retrieval.
+
+What **is** faithful is the **entire protocol envelope**, including xAI's deltas from plain
+OpenAI compatibility:
+
+- chat response shape — `{ id:<uuid>, object:'chat.completion', created, model, choices:[…],
+  usage:{prompt_tokens, completion_tokens, total_tokens, prompt_tokens_details,
+  completion_tokens_details, num_sources_used}, system_fingerprint }` (xAI ids are
+  **UUID-formatted**, not `chatcmpl-…`; usage carries the xAI token-detail objects)
+- **errors** — xAI's gRPC-transcoded **flat `{ code, error }` strings** (e.g. `"Client
+  specified an invalid argument"`, `"Some requested entity was not found"`), never OpenAI's
+  nested `{ error: {…} }`; unknown models get the vendor's "does not exist or your team has
+  no access" 404
+- **streaming** via SSE — `chat.completion.chunk` deltas ending with `data: [DONE]`; each
+  streamed **tool call arrives as ONE COMPLETE delta** (id + name + full arguments — xAI does
+  not split arguments across chunks; the real `@ai-sdk/xai` chunk schema rejects split deltas)
+- **tool / function calling** — `tool_calls` + `finish_reason:'tool_calls'`, `tool_choice`
+  (none/required/named), `parallel_tool_calls`, schema-typed stub arguments
+- **reasoning** — `grok-3-mini` accepts `reasoning_effort` (low/high) and exposes
+  `message.reasoning_content` + `usage.completion_tokens_details.reasoning_tokens`; the
+  grok-4-family **rejects `reasoning_effort` (400)** and spends reasoning tokens without ever
+  exposing the trace — both modeled
+- **deferred completions** — `deferred:true` → `{ request_id }`, then
+  `GET /v1/chat/deferred-completion/:id` → `202` pending → `200` result → **consumed
+  (404 after)** — stateful, kernel-backed
+- **Live Search** — `search_parameters` (mode auto/on/off, sources web/x/news/rss,
+  `return_citations`) validated; `citations[]` + `usage.num_sources_used` served. The twin
+  treats `mode:'auto'` as searching so behavior stays deterministic
+- **structured outputs** — `response_format` json_object / json_schema → valid JSON content
+- **Anthropic-compatible `POST /v1/messages`** — content blocks, `tool_use` (from
+  `input_schema`), `stop_reason`, `usage`, and the **required `max_tokens`** rule
+- **legacy `POST /v1/completions`** — `text_completion` envelope
+
+The genuinely **stateful + static** surface is real, not a stub:
+
+- `POST /oauth2/device/code` + `/oauth2/token` — one coherent virtual Grok account with
+  pending/approve/deny, one-use device exchange, refresh rotation, expiring access tokens,
+  display identity, and shared virtual usage. `GET /oauth2/device` renders the small real
+  authorization page; in-process capability setup may make the same decision through the
+  Twin-only `/twin/oauth/authorizations` control seam, which is deliberately absent from the
+  network surface
+- `GET /v1/models` (+ `/:id`) — the grok catalog (OpenAI-compatible shape), **merged with
+  connector-observed real models** (observed models are catalog rows for listing/retrieval;
+  they do not gain inference behavior or alias resolution); catalog aliases (`grok-4` →
+  `grok-4-0709`) resolve for retrieval AND inference
+- `GET /v1/language-models` (+ `/:id`) — xAI's rich model objects (modalities, per-token
+  price fields, aliases). Price fields are deterministic representative constants, not a live
+  price sheet
+- `GET /v1/image-generation-models` (+ `/:id`)
+- `POST /v1/images/generations` — faithful shape (url | b64_json + revised_prompt, n 1–10)
+  including the xAI compatibility delta that OpenAI's `size`/`quality`/`style` are
+  **rejected (400)**
+- `GET /v1/api-key` — key introspection (redacted value, acls, blocked/disabled flags); the
+  reserved sentinel `xai-blocked` reports `api_key_blocked:true` and 403s everywhere else
+- `POST /v1/tokenize-text` — deterministic pseudo-tokenizer (faithful
+  `token_ids[].token_id/string_token/token_bytes` shape; tokens re-join to the input; NOT the
+  real Grok BPE)
+
+Auth is modeled on the live wire: missing/`xai-invalid` bearer → 401, `xai-blocked` → 403,
+any other ordinary API key accepted. A sealed Grok CLI request additionally requires a
+current access token issued by this Twin's OAuth state; a foreign/live token fails 401 rather
+than silently crossing Worlds. A deterministic `x-twin-force-rate-limit` trigger returns the
+faithful 429 + `retry-after`.
+
+## Scenario scripting (twin scaffolding)
+
+`xai-scenario.ts` (the anthropic-pack convention, adapted to the chat-completions wire):
+a JSON scenario file scripts the exact assistant turns a flow under test needs — matched on
+last user text / tools / tool-result turns / Nth call, answering with text and/or complete
+`tool_calls` — while the envelope (unary + SSE) stays vendor-faithful. Wire up via
+`createXaiTwinServer({ scenarioPath })`, `TWIN_XAI_SCENARIO`, or
+`world-xai serve --scenario <file>`. Scenarios apply **only** to `POST /v1/chat/completions`
+and are **twin scaffolding, not vendor surface** — deliberately absent from the capability
+manifest.
+
+## CLI
+
+```
+world-xai serve       [--port N] [--root DIR] [--read-only] [--scenario FILE]   # the API twin (SDK target)
+world-xai conformance [--root DIR]                                              # offline envelope checks
+```
+
+## Connector (pull; push refuses loudly)
+
+`syncXaiFromReal` pulls the real model catalogs (`/v1/models` + `/v1/language-models`) into
+the twin over an **injected client** (`liveXaiExecute(apiKey)` live; a fake in tests) — the
+pack holds no key and imports no SDK at runtime. The served catalogs merge observed models
+over the static table. **Push refuses loudly for every operation**: the xAI API has no
+client-writable resources (every endpoint is inference or read-only catalog/introspection),
+so `pushXaiAction` throws rather than silently dropping — or fabricating — a vendor write.
+
+## Rate budget (fail-closed, before every live call)
+
+`liveXaiExecute` is this pack's **one construction site** for a client that really reaches
+`api.x.ai`, and every request it issues goes through a **persistent, fail-closed rate budget**: a
+durable spend ledger keyed by **vendor and a hash of the API key** (limits are per key, so it is
+deliberately not cwd-scoped), consulted **before** the request, that **throws instead of calling**
+past a rolling-window ceiling or while a `Retry-After`/429/`x-ratelimit-remaining: 0` cooldown is
+armed. `checkBudget` **reserves** inside a file lock, so a burst is genuinely refused rather than
+raced through; a corrupt ledger counts as a **full** window rather than zero spend; and the ledger is
+on disk, so a fresh process does **not** get a fresh allowance. There is no option to disable it, and
+a `budget` that is not an unmodified `XaiBudget` — a duck-typed stand-in, a subclass overriding
+`checkBudget`, a `Proxy` trapping it — is refused rather than trusted.
+
+The mechanism is **shared and vendor-agnostic** (`@volter/world-core` → `packages/world-core/src/rateBudget.ts`);
+what lives here in [`xai-budget.ts`](src/xai-budget.ts) is xAI's **declaration** plus the
+vendor-bound `XaiBudget`. Read the kernel module's header for what the guard does *not* guarantee.
+
+**The numbers, honestly.** xAI **publishes no scalar rate limit at all** in its public docs — not in
+the API reference, not on the models page (which carries pricing and capability tables but no
+RPM/RPS/TPM figures), not in the overview or quickstart, and none of them even points at a dashboard
+where one could be read. So this declaration does **not** model a vendor limit and does not pretend
+to: it pins to the kernel's austere fallback — **60 weighted units / 60 s at 2 per call = 30 calls a
+minute** — rather than borrowing OpenAI's tier limits on the strength of xAI's OpenAI-compatible
+protocol. *Protocol compatibility is not quota compatibility.* Pricing is **flat, deliberately**:
+`XaiExecute` is typed GET-only over read-only catalogs and push refuses loudly, so no caller can
+reach a token-billed inference endpoint and no reachable endpoint is credibly dearer than another —
+inventing a ratio would be a made-up number dressed as vendor fact. A caller can tighten further;
+options may only tighten.
+
+Proven by [`xai-budget.test.ts`](src/xai-budget.test.ts), which drives the **real** executor over an
+injected `fetch` and an injected clock and asserts refusals **by counting calls**: after the 30th the
+fake has recorded exactly 30, and the 31st attempt throws with that count **unchanged** — "it threw"
+is not proof, "it threw and nothing left the process" is. Cross-process persistence is proven by
+really running a second process. Two source-level teeth also fail the build: no in-pack test may
+construct against the operator's real `$HOME` ledger, and the raw `api.x.ai` host may appear only in
+an allowlisted file.
+
+## Coverage
+
+The capability manifest (`xai-capabilities.ts`) enumerates the **real xAI API surface** as
+the honest denominator; `verify()` proves each `done` against the local twin, offline +
+deterministically. Run `bun scripts/twin-capabilities.ts xai` for the live numbers. The
+SDK-parity test (`xai-sdk.integration.test.ts`) drives the twin with the real, unmodified
+`@ai-sdk/xai` provider through its public `baseURL` option — `generateText`/`streamText`
+with tools, the exact call shape of the primary consumer.
+
+**Deliberately absent surface:** xAI publishes **no embeddings endpoint** (announced but not
+GA at authoring time), so embeddings appear nowhere in the manifest — the twin 404s
+`/v1/embeddings` exactly like the vendor, and listing it would be denominator padding. If
+xAI ships it, it enters the manifest as honest `todo`s.
+
+**Scope boundary (a different host, not an omission):** xAI's **Collections API** and
+**Management API** live on `management-api.x.ai` — a separate console/administration
+product. This pack twins the `api.x.ai` **inference** surface only; the management host is
+out of this pack's scope by that boundary.
+
+### Grok Build device-authorization UI
+
+xAI remains API-first, so this pack does **not** fabricate a mirror of the xAI key/billing
+console. Grok Build device authorization is different: its code-entry and permission-consent
+screens are vendor-owned browser steps inside the OAuth protocol itself. The denial and completion
+screens in this pack are explicitly Twin-local terminal states because no official equivalents
+were captured. The Twin serves those states on `/oauth2/device` and `/oauth2/device/consent` using one
+projection-backed React renderer with the exact self-served SpaceXAI symbol, progressive form
+submits, same-origin assets, UI-dimension capabilities, mutation coverage, and real-browser
+approval/denial/invalid-code/sign-out journeys. Blank and invalid entry states match the live
+disabled-button and clear-field redirect behavior. The permission rows
+come from the pending request's stored scopes; the visible decision mutates the same device row
+that `/oauth2/token` later exchanges. `world-xai mirror` is therefore only an alias for
+`world-xai serve`, never a separate or drifting renderer.
+
+### Done (proven, verifiable)
+- **Chat** — create + faithful envelope (UUID ids, usage detail objects), labeled stub,
+  validation (flat `{code,error}` 400s), vendor 404 for unknown models, `n`,
+  `max_tokens`/`max_completion_tokens`, system/multi-turn, `stop`, deterministic usage,
+  structured outputs, `seed`, `reasoning_effort` (grok-3-mini exposes / grok-4 rejects),
+  vision content parts (image_tokens counted)
+- **Streaming** — chunk sequence + `[DONE]`, content reconstruction, terminal
+  `finish_reason`, complete-delta tool calls, `stream_options.include_usage`
+- **Tools** — tool_calls envelope, `tool_choice`, `parallel_tool_calls`, schema-typed
+  arguments, tool-result round-trip
+- **Live Search** — `search_parameters` validation + citations + `num_sources_used`, source
+  selection (web/x/news/rss), `return_citations` toggle
+- **Deferred completions** — create (`request_id`), 202→200→consumed lifecycle
+- **Messages (Anthropic-compat)** — envelope, required-`max_tokens` rule, tools → `tool_use`
+- **Legacy completions** — `text_completion` envelope
+- **Models** — flat list/get, alias resolution, rich language-models, image-generation
+  models
+- **Images** — generations shape (url/b64_json, n bounds), OpenAI-param rejection delta
+- **api-key** — introspection incl. the blocked sentinel
+- **tokenize-text** — faithful token_ids shape
+- **Errors/protocol** — flat envelope, modeled 401/403/429, read-only 405
+- **Grok OAuth + CLI proxy** — brokered device authorization/exchange/refresh, the documented CLI chat-proxy override, session-token marker, and
+  `x-grok-model-override` routing for the built-in `grok-build` coding route
+- **Connector** — read surface, pull+map+merge (offline, injected client, idempotent),
+  loud push refusal
+- **Conformance** — offline envelope harness (9 checks)
+
+### Planned (todo — real vendor surface not yet reached)
+- **The Responses API** — `POST /v1/responses` (+ retrieve/delete/compact), xAI's current
+  first-class stateful inference surface (docs now file chat completions under "legacy")
+- Chat `logprobs`, presence/frequency penalties, cached prompt tokens
+- Deferred-completion expiry window
+- Live Search date range / max results / per-source filters
+- Anthropic-compat streaming + system/multi-block content
+- Legacy completions streaming + echo/suffix
+- api-key ACL enforcement
+- Direct `grok login --device-auth` redirection to a sealed Twin origin (the official CLI fixes
+  that login origin; brokered external auth is the supported one-sign-in seam today)
+- Connector pull of the image-generation catalog (`xai.connector.pull_image_generation_models`,
+  also filed in pull-audit.json)
+
+- Image URLs that resolve — serve deterministic placeholder image bytes at the URLs
+  `/v1/images/generations` returns
+
+There are no carve-outs. The labeled stub completion and the deterministic labeled citations are
+this twin's answer, not a shortfall from a "real" one; every capability is done or todo.