@volter/twin-x 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,138 @@
+# `@volter/twin-x` — the X (Twitter) API v2 posting surface
+
+> **Legacy connector helpers:** this package still has callable helpers using the retired v1
+> `syncPull` API. Those paths require migration before use on the current kernel;
+> older helper descriptions below do not establish current compatibility. Check the
+> [generated index](../../../generated/INDEX.md) for protocol standing and use the
+> [shared model](../../../docs/concepts/the-model.md) for current state semantics.
+
+The org's **public voice**: post (with images or a video), quote, reply to a mention, retract, look a post or an
+account back up, and read the mentions / own / home timelines and recent search — offline, against local state, with
+X's own `tweet.fields` projection, bearer/scope gate and problem envelopes.
+
+```bash
+bun packages/twin/x/src/cli.ts serve --root /tmp/world
+# then point any X v2 client at it: X_TWIN_URL=http://127.0.0.1:<port> node --require @volter/world-core/inject app.js
+```
+
+## Coverage
+
+| Area | What the twin serves |
+|---|---|
+| `POST /2/tweets` | Create an **original post** — with `reply.in_reply_to_tweet_id` a **reply**, with `quote_tweet_id` a **quote**. One route, three body fields. Text over the account's limit (280, or its X Premium long-post entitlement) is refused before anything is written. `media.media_ids` attaches up to four images or one video this account uploaded; an unknown, foreign, expired or still-processing id is X's `Your media IDs are invalid.` |
+| `POST /2/media/upload` · `…/initialize` · `…/{id}/append` · `…/{id}/finalize` · `GET /2/media/upload?command=STATUS` | **Media upload**, needing `media.write`: an image (`tweet_image`, `dm_image`) in one request, multipart or base64 JSON, typed and sized from its own bytes; a video (`tweet_video`, `amplify_video`, MP4) in chunks, whose `processing_info` goes pending → in_progress → succeeded one STATUS read at a time (a file that is not an MP4 fails as `InvalidMedia`). Bytes live on the kernel's blob seam, content-addressed; an upload is not an entry — the post that attaches it is. GIF, DM video and subtitle categories are refused by name. |
+| media bytes | Served at X's own path shapes under the twin's base (a World's mount included): `/media/<name>.<ext>` for an image, `/ext_tw_video/<id>/pu/vid/avc1/<w>x<h>/<name>.mp4` for a video with HTTP Range, `/ext_tw_video_thumb/…` for a video's preview — a stand-in poster, since the twin decodes no frames. |
+| `DELETE /2/tweets/:id` | Retract a post. Only your own; only once. |
+| `GET /2/tweets/:id` · `GET /2/tweets?ids=` | Post lookup, single and bulk. The bulk form is **partial**, as X's is: the ids that exist in `data`, the ones that do not in `errors` — never a fabricated row. |
+| `GET /2/users/:id/mentions` | The mentions timeline — posts naming this account. |
+| `GET /2/users/:id/tweets` | The account's own posted timeline. |
+| `GET /2/users/:id/timelines/reverse_chronological` | The home timeline — the account plus the accounts it follows; refused for anyone else's id. |
+| `GET /2/users/:id` · `GET /2/users/by/username/:username` | User lookup (handles are case-insensitive). An unknown user is X's partial-error 200 with a `resource_type: "user"` row, never a fabricated account. `GET /2/users/me` is `xidentity`'s and is not claimed here. |
+| `GET /2/tweets/search/recent` | Recent search over the local corpus: keywords, quoted phrases and `from:`. Grammar the twin does not model (`OR`, negation, grouping, other operators) is **refused**, never silently ignored. |
+| projection | `tweet.fields`, `user.fields`, `media.fields` and `expansions` (`attachments.media_keys` included) + the `includes` sidecar. The default is X's three fields (`id`, `text`, `edit_history_tweet_ids`) and nothing else — a documented field the twin holds no state for is refused by name rather than quietly omitted. |
+| paging + windows | `pagination_token` / `meta.next_token`, `max_results` (5..100 on the timelines, 10..100 on search), and `since_id` / `until_id` / `start_time` / `end_time` with X's own id-beats-time precedence. |
+| auth | The bearer `xidentity`'s OAuth flow mints, its scope set, and X's `about:blank` 401 / `Forbidden` 403 problems. |
+| errors | `resource-not-found`, `invalid-request`, the 429 + legacy code 88 pair, `405` under `--read-only`. |
+| connector | Pull **both** timelines — mentions and the account's own posts — following `next_token` to the end of each; **push** a pending post/quote/reply/delete to the real vendor, confirmed under the id X minted. A post with media is **performed** by uploading each file to X first (an image in one request; a video chunked, then polled on STATUS until processed) and posting with the media ids X minted. |
+| `/_twin/*` | Twin-only control plane: seed an account (its profile — `description`, `location`, `url`, `protected`, `verified` — and its long-post entitlement), a bearer, an inbound mention, a follow edge, or an armed rate refusal. |
+
+`src/x-capabilities.ts` is the denominator: **114 capabilities, 74 done**. What is
+not modelled is enumerated there as a todo — polls, hide-reply, `entities`/`public_metrics`,
+the `user.fields` with no state behind them, full-archive search and the query grammar, likes/reposts/bookmarks, stream rules, the
+filtered and sampled **streaming** connections, GIFs, alt text, a video's real poster frame and X's transcoded
+variants — not omitted. One CORE todo remains and says why in its own title: `x.rate_limit.published_figures`
+needs X's published per-endpoint posting limits, and this pack makes no X call to fetch them.
+
+## One route, two operations, and why that is the whole point
+
+An original post and a reply are **the same HTTP operation** at X: `POST /2/tweets`, differing
+only by `reply.in_reply_to_tweet_id` in the body. The pinned official client proves it —
+`tweet()` posts `{text}` to `tweets` and `reply()` posts `{text, reply:{in_reply_to_tweet_id}}` to
+the same `tweets` (`twitter-api-v2@1.29.1`, `dist/cjs/v2/client.v2.write.js:89` and `:180`). A
+**quote** is a third body field on that same route (`quote_tweet_id`, `:187`).
+
+That matters beyond fidelity, because the example org **graduates the two at different times**:
+replying to a mention is allowed before posting under the org's own name is. A census keyed by
+method+path names ONE capability for both, and that ladder cannot be written down at all.
+
+So `x-spec-census.json` declares `requestKey: "method+path+body-field"` and carries **two** entries
+for that one route — `x.tweets.reply` when the field is present, `x.tweets.create` when it is
+absent — both mapped as `operationCapability`, so a consumer that has not learned to read the body
+**denies** rather than granting the first entry to both. Every other route in the census is an
+ordinary method+path row: this is not a single-endpoint vendor.
+
+A quote deliberately does **not** get a third census entry: for the split this census exists to
+express — answering someone versus speaking under the org's own name — a quote is an *original*
+post, so it resolves to the `x.tweets.create` side and the partition stays two-sided and total.
+
+The discriminator is the pack's own, not a vocabulary minted for the census: `x-twin.ts` branches
+on those exact fields to decide what it writes (`conversation_id`, `in_reply_to_user_id`,
+`referenced_tweets`), and `x-connector.ts` sends the same fields back to the real vendor on a push.
+`src/x-spec-census.test.ts` holds those three to each other, so a rename in one goes red.
+
+## Relationship to `@volter/twin-xidentity`
+
+`xidentity` owns **X's OAuth 2.0** — the x.com authorize screen, the authorization-code + PKCE
+round trip, and `GET /2/users/me`. This pack owns the **posting surface** and consumes the user
+access token that flow mints. It never models OAuth: X's authorization-code round trip is a
+capability of `xidentity`, and duplicating it here would be two accounts of one vendor's auth.
+
+The two agree about X rather than sharing code: `scripts/architecture.test.ts` (A3) forbids a
+cross-vendor pack import, so `src/x-problems.ts` and `src/x-scopes.ts` **transcribe** xidentity's
+problem envelopes and scope catalog — both grounded in the same X API v2 OpenAPI 2.167 document —
+and say so at the seam. If X's error shape is ever re-grounded, both files move together.
+
+Both packs claim `api.x.com` in the injector, path-scoped and **disjoint**: xidentity claims
+`/2/oauth2/{token,revoke}` and `/2/users/me`; this claims `/2/tweets`, `/2/tweets/:id`,
+`/2/tweets/search/recent`, `/2/users/{id}/{mentions,tweets,timelines/reverse_chronological}`,
+`/2/users/{id}` and `/2/users/by/username/{username}`. The user-id rule excludes `me` by a
+lookahead and the timeline rules need a trailing segment, so `/2/users/me` matches none of them
+and no request is claimable by both. An unclaimed path on that claimed host is refused loudly rather than mis-routed into a
+twin that cannot serve it.
+
+## The mirror — x.com's view of the twin
+
+A person doing X's core job opens a browser, so this pack ships a mirror: x.com's own look over the
+twin's state, for judging a post as it will appear.
+
+```bash
+bun packages/twin/x/src/cli.ts mirror --root /tmp/world --port 4700   # or: volter twin x mirror --root <state> --port <p>
+```
+
+- **Sign in** is x.com's two-step login: the account's `@handle`, then — in place of a password —
+  the bearer the twin issued for it through `/_twin/tokens`. The mirror checks the token is that
+  account's with X's own rule (the home timeline is served only to its own account). Handle and
+  token live in the tab's `sessionStorage`; the mirror keeps nothing else.
+- **Screens**: the profile (header, Posts / Replies), a single post's page with its reply box and
+  the replies the account can read, Notifications → Mentions, and Home with the compose box. A
+  post's media is x.com's rounded block under its text: one image at its own aspect, two to four
+  in a grid, or a video player — its own first frame, the play button and the duration badge until
+  it plays, then the player's controls. The composer posts text only.
+- **Reads** are the routes above — `GET /2/users/by/username/:username`, `/2/users/:id/tweets`,
+  `/2/users/:id/mentions`, `/2/users/:id/timelines/reverse_chronological`, `/2/tweets/:id`, each
+  expanding `attachments.media_keys`, and the media URLs they return —
+  on the same origin (`src/x-mirror-ui.ts` mounts the pack's own fetch adapter). **Writes** are
+  `POST /2/tweets`: a post, or a reply with `reply.in_reply_to_tweet_id`.
+- **What it does not draw**: engagement counts and the profile's Following / Followers numbers —
+  the twin models no `public_metrics`, so the slots are empty rather than zero. The avatar is a
+  lettered placeholder; the twin serves no profile images.
+- **Not yet readable inside a served World.** `volter world serve` has no mirror mount (only
+  `apps/cloud` mounts `/<org>/<world>/<vendor>/mirror/`), and on a World's wire an
+  `Authorization: Bearer` is read as the World's own credential ahead of the browser's session
+  cookie, so the mirror's X bearer is refused there as `token required`.
+
+**"Drafts in an outbox" is deliberately not here.** A draft sitting until someone approves it is an
+obligation on the posting *action* — org config — and building an outbox into a vendor pack would
+put behavior policy one layer further from where it belongs than putting it in platform code.
+
+## Evidence boundary
+
+**No X call is made anywhere in this pack, by any test, ever.** X's rate limits are punitive and
+this estate has been bitten. Every route and body shape is grounded in the pinned
+`twitter-api-v2@1.29.1` source (see `test-fixtures/x-openapi-operations.SOURCE.md`); the error
+envelopes and scope catalog are transcribed from `xidentity`, which grounded them in X's own
+OpenAPI document. The **rate-budget ceiling is explicitly not a transcription**: X's published
+per-endpoint figures in this repo cover `GET /2/users/me`, not the posting endpoints, so the
+declaration is deliberately conservative and files `x.rate_limit.published_figures` as a pinning
+todo. Wording for refusals X has never shown us is filed the same way (`x.errors.*_wording`)
+rather than dressed up as vendor prose.