twilic 3.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 77255a004384acecbf760c61ac408ed7b68e2c7fc024fe531eaa12d22a98871f
+  data.tar.gz: '06395f1bc4a676a50b35d7579a9840f27ce344b7dd67ac5043dcb3864dd989de'
+SHA512:
+  metadata.gz: 8a7c06ce15e75fbeb76a8b0c71fd7d652accb1a2e1fe2033eb4bcae7c458be638918850daad0780a8cce27d6ee6ef20de2e74736923b190c25b9a8df1558acbb
+  data.tar.gz: 83f906d9fd124badec3bcb963aa0c9e9279012dd46dfd435872b63d29518e5c5598cc8ea2c39b22fc0ce2ac53f3bc0b37ecaac9acfe52d2333ee3782f3b60212

data/.editorconfig

@@ -0,0 +1,18 @@
+root = true
+
+[*.{rb,rake,yml,yaml,md,sh}]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.{rb,rake}]
+indent_style = space
+indent_size = 2
+
+[*.{yml,yaml,md,sh}]
+indent_style = space
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false

data/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

data/.gitignore

@@ -0,0 +1,9 @@
+/node_modules/
+/.bundle/
+/vendor/bundle/
+/pkg/
+/coverage/
+*.gem
+.DS_Store
+/scripts/rust-client-check/target/
+/scripts/rust-server-fixtures/target/

data/.markdownlint.jsonc

@@ -0,0 +1,22 @@
+{
+  "default": true,
+  "MD013": false,
+  "MD004": {
+    "style": "dash"
+  },
+  "MD007": {
+    "indent": 2
+  },
+  "MD029": {
+    "style": "ordered"
+  },
+  "MD031": true,
+  "MD032": true,
+  "MD040": true,
+  "MD046": {
+    "style": "fenced"
+  },
+  "MD024": {
+    "siblings_only": true
+  }
+}

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,53 @@
+PATH
+  remote: .
+  specs:
+    twilic (3.0.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.3)
+    json (2.19.5)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    minitest (5.27.0)
+    parallel (2.1.0)
+    parser (3.3.11.1)
+      ast (~> 2.4.1)
+      racc
+    prism (1.9.0)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.4.2)
+    regexp_parser (2.12.0)
+    rubocop (1.86.2)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (>= 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.49.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    ruby-progressbar (1.13.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+
+PLATFORMS
+  arm64-darwin-24
+  ruby
+
+DEPENDENCIES
+  minitest (~> 5.25)
+  rake (~> 13.2)
+  rubocop (~> 1.69)
+  twilic!
+
+BUNDLED WITH
+   2.5.23

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Twilic (maintained by Minagishl)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,119 @@
+# Twilic (Ruby)
+
+Ruby implementation of the Twilic wire format and session-aware encoder/decoder.
+
+This gem's default `Twilic.encode` / `Twilic.decode` API targets Twilic v2.
+
+## What this gem provides
+
+- Dynamic encoding/decoding (`Twilic.encode`, `Twilic.decode`)
+- Schema-aware encoding (`Twilic.encode_with_schema`)
+- Batch and micro-batch encoding (`Twilic.encode_batch`, `SessionEncoder#encode_micro_batch`)
+- Stateful features (base snapshots, state patch, template batch, control stream, trained dictionary)
+
+## Project layout
+
+```text
+twilic-ruby/
+  lib/twilic.rb                   # public API
+  lib/twilic/core/                # wire, model, codec, session, protocol, v2
+  scripts/                        # Rust interop fixtures and smoke checks
+  docs/
+```
+
+The repository root stays thin: `require "twilic"` only. Implementation details live under `lib/twilic/core/`, similar to `internal/core/` in the Go module.
+
+## Requirements
+
+- Ruby 3.3 or later
+
+## Install
+
+```bash
+gem install twilic
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem "twilic"
+```
+
+## Quick start
+
+```ruby
+require "twilic"
+
+value = Twilic.map(
+  "id" => Twilic.u64(1001),
+  "name" => Twilic.string("alice")
+)
+
+bytes = Twilic.encode(value)
+decoded = Twilic.decode(bytes)
+puts Twilic.equal(decoded, value) # => true
+```
+
+## Session encoder example
+
+```ruby
+require "twilic"
+
+enc = Twilic.new_session_encoder
+
+value = Twilic.map(
+  "id" => Twilic.u64(1),
+  "role" => Twilic.string("admin")
+)
+
+bytes = enc.encode(value)
+```
+
+## Development
+
+Run checks locally:
+
+```bash
+bundle install
+bundle exec rake test
+```
+
+Rust client interop smoke check (Ruby server -> Rust client):
+
+```bash
+bash scripts/check-rust-client-interop.sh
+```
+
+Ruby client interop smoke check (Rust server -> Ruby client):
+
+```bash
+bash scripts/check-ruby-client-interop.sh
+```
+
+Run both directions:
+
+```bash
+bash scripts/check-interop.sh
+```
+
+Note: these scripts expect `../twilic-rust` to exist as a sibling directory.
+
+## Markdown formatting
+
+Documentation is formatted and linted with Prettier and markdownlint (see [`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md)).
+
+## CI and release (GitHub Actions)
+
+- CI workflow: `.github/workflows/ci.yml`
+- Interop workflow: `.github/workflows/interop.yml`
+- Release workflow: `.github/workflows/publish-gem.yml` (tag `v*` must match `lib/twilic/version.rb`)
+
+## Spec parity
+
+This gem mirrors the Twilic wire format spec at [twilic/twilic](https://github.com/twilic/twilic) and stays in lockstep with the [Rust](https://github.com/twilic/twilic-rust), [Go](https://github.com/twilic/twilic-go), and [Zig](https://github.com/twilic/twilic-zig) reference implementations.
+
+See [`docs/SPEC-TEST-TRACEABILITY.md`](docs/SPEC-TEST-TRACEABILITY.md) for the spec-section to test mapping.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: :test

data/docs/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [3.0.0] - 2026-05-24
+
+Initial public release of the Ruby implementation of Twilic, tracking the v3 release line shared with [twilic-rust](https://github.com/twilic/twilic-rust) and [twilic-js](https://github.com/twilic/twilic-js).
+
+### Added
+
+- Core wire format with dynamic `Value` model and `Encode` / `Decode` APIs.
+- Schema-aware encoding (`encode_with_schema`), batch encoding (`encode_batch`), and session-based micro-batch and patch support.
+- Stateful transport features: base snapshots, state patch encoding, template batch handling, control stream support, and trained dictionary support.
+- Public gem API at `Twilic` with implementation under `lib/twilic/core/`.
+- Spec conformance tests and traceability mapping in [`docs/SPEC-TEST-TRACEABILITY.md`](SPEC-TEST-TRACEABILITY.md).
+- Rust interop fixture stream, value parity tests, and bidirectional smoke scripts under `scripts/`.
+- Interop helpers in `lib/twilic/core/interop_fixtures.rb` for cross-language fixture emission and decoding.
+- GitHub Actions workflows for CI, Interop, commitlint, invisible character check, PR message validation, and tagged gem publish via RubyGems Trusted Publishing (OIDC).
+- GitHub issue templates, pull request template, and contributor documentation.
+- Markdown formatting with Prettier and markdownlint.
+
+### Fixed
+
+- PR Message Check: skip template validation for Dependabot pull requests.
+
+[unreleased]: https://github.com/twilic/twilic-ruby/compare/v3.0.0...HEAD
+[3.0.0]: https://github.com/twilic/twilic-ruby/releases/tag/v3.0.0

data/docs/CONTRIBUTING.md

@@ -0,0 +1,51 @@
+# Contributing
+
+Thank you for improving the Twilic Ruby implementation.
+
+## Scope
+
+This gem implements the Twilic wire format and session-aware encoder/decoder. Keep changes aligned with the normative spec in [twilic/twilic](https://github.com/twilic/twilic).
+
+## Development
+
+Requirements:
+
+- Ruby 3.3 or later
+- Bundler
+
+Implementation code belongs in `lib/twilic/core/`. The repository root (`lib/twilic.rb`) re-exports the stable public API.
+
+```bash
+bundle install
+bundle exec rake test
+```
+
+Markdown in this repository is formatted with Prettier and linted with markdownlint (same tooling as [twilic/twilic](https://github.com/twilic/twilic)):
+
+```bash
+pnpm install
+pnpm format        # write
+pnpm format:check  # CI check
+pnpm lint          # markdownlint
+```
+
+Interop scripts under `scripts/` expect `../twilic-rust` as a sibling clone. They verify Rust and Ruby decode the same logical values and that `bundle exec rake test TEST=test/twilic/core/interop_fixtures_test.rb` passes (encode/decode roundtrip, wire parity, and cross-language value checks).
+
+## Commit Messages
+
+We follow [Conventional Commits](https://www.conventionalcommits.org/).
+
+Examples:
+
+- `feat: add FOR bitpack vector codec`
+- `fix(session): reset intern table on control frame`
+
+## Contribution Checklist
+
+- Tests added or updated for behavior changes
+- `bundle exec rake test` passes locally
+- `pnpm format:check` and `pnpm lint` pass when Markdown changes
+- Interop fixtures updated when wire behavior changes
+- Commit messages follow Conventional Commits
+
+By contributing to this repository, you agree that your contribution may be distributed under the MIT license used by the project.

data/docs/SPEC-TEST-TRACEABILITY.md

@@ -0,0 +1,87 @@
+# SPEC Test Traceability (5/6/8/10/13/15/18)
+
+This file maps `twilic/SPEC.md` requirements to Ruby tests in `twilic-ruby`.
+
+## 5. Dynamic Profile
+
+| SPEC section    | Requirement (short)                            | Tests                                                                                                                   |
+| --------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| 5.2 key table   | First key literal, later key ref by id         | `DynamicProfileSpecTest#test_two_field_map_keeps_map_and_uses_key_ids`                                                  |
+| 5.3 shape table | Repeated shape registration/promotion behavior | `DynamicProfileSpecTest#test_shape_promotes_after_second_three_field_map`                                               |
+| 5.4 MAP         | Map roundtrip and key-ref decode behavior      | `DynamicProfileSpecTest#test_two_field_map_keeps_map_and_uses_key_ids`, `TwilicTest#test_codec_roundtrip_dynamic_value` |
+| 5.5 ARRAY       | ARRAY vs typed vector threshold behavior       | `DynamicProfileSpecTest#test_typed_vector_threshold_is_applied`                                                         |
+
+## 6. Bound Profile
+
+| SPEC section      | Requirement (short)                     | Tests             |
+| ----------------- | --------------------------------------- | ----------------- |
+| 6.1 schema        | Required field handling, schema decode  | _not yet covered_ |
+| 6.2 schema_id     | Emit on first use, omit in same context | _not yet covered_ |
+| 6.3 SCHEMA_OBJECT | Schema object message roundtrip         | _not yet covered_ |
+
+## 8. Numeric Encoding
+
+| SPEC section                | Requirement (short)                                                       | Tests             |
+| --------------------------- | ------------------------------------------------------------------------- | ----------------- |
+| 8.1 scalar integer          | Zigzag/varuint scalar integer behavior                                    | _not yet covered_ |
+| 8.2 range-aware bit packing | Bounded integer handling in schema context with fixed-width range offsets | _not yet covered_ |
+| 8.4 vector integer codecs   | Plain/direct/delta/FOR/delta-FOR/delta-delta/RLE/patched/Simple8b         | _not yet covered_ |
+| 8.5 float vector codecs     | XOR float vs plain behavior                                               | _not yet covered_ |
+
+## 10. Strings
+
+| SPEC section                | Requirement (short)                                 | Tests             |
+| --------------------------- | --------------------------------------------------- | ----------------- |
+| 10.2 LITERAL                | Literal mode encode/decode                          | _not yet covered_ |
+| 10.3 REF                    | String ref reuse behavior                           | _not yet covered_ |
+| 10.4 PREFIX_DELTA           | Prefix-delta mode encode/decode                     | _not yet covered_ |
+| 10.5 string table           | Reset clears string table state                     | _not yet covered_ |
+| 10.6 field-local dictionary | String dictionary/ref behavior in column codec path | _not yet covered_ |
+| 10.8 INLINE_ENUM            | Control-driven enum promotion path                  | _not yet covered_ |
+
+## 13. Batch / Stateful Extensions
+
+| SPEC section                  | Requirement (short)                                                               | Tests                                                                                                       |
+| ----------------------------- | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| 13.1 ROW_BATCH                | Small batch uses row batch                                                        | _not yet covered_                                                                                           |
+| 13.2 COLUMN_BATCH             | Large batch uses column batch and null strategy paths                             | _not yet covered_                                                                                           |
+| 13.5.1 session state          | Unknown reference policy behavior (base/template/dict families)                   | `TwilicTest#test_unknown_reference_policy_supports_stateless_retry`                                         |
+| 13.5.2 BASE_SNAPSHOT          | Snapshot registration/reference                                                   | `InteropFixturesTest#test_codec_encode_decode_roundtrip`                                                    |
+| 13.5.3 STATE_PATCH            | Patch roundtrip and bounds checks                                                 | `TwilicTest#test_session_patch_and_micro_batch`, `InteropFixturesTest#test_session_encode_decode_roundtrip` |
+| 13.5.4 previous-message patch | Previous-message patch selection                                                  | _not yet covered_                                                                                           |
+| 13.5.5 TEMPLATE_BATCH         | Template create/reuse and changed mask                                            | `TwilicTest#test_session_patch_and_micro_batch`, `InteropFixturesTest#test_session_encode_decode_roundtrip` |
+| 13.5.6 CONTROL_STREAM         | Plain/RLE/Bitpack/Huffman/Fse paths and compaction behavior                       | `InteropFixturesTest#test_decode_rust_server_frames`                                                        |
+| 13.5.7 trained dictionary     | Dictionary id assignment and `dict_id + compressed block` path in column encoding | _not yet covered_                                                                                           |
+| 13.5.8 RESET_STATE            | Reset clears tables/state references                                              | _not yet covered_                                                                                           |
+
+## 18. Encoder Auto-Selection Rules
+
+| Rule cluster             | Requirement (short)                                    | Tests                                                                                                                                             |
+| ------------------------ | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Dynamic map/shape rules  | Repeated-shape promotion, map fallback, key refs       | `DynamicProfileSpecTest#test_shape_promotes_after_second_three_field_map`, `DynamicProfileSpecTest#test_two_field_map_keeps_map_and_uses_key_ids` |
+| Typed vector rules       | Array cardinality/type based vectorization             | `DynamicProfileSpecTest#test_typed_vector_threshold_is_applied`                                                                                   |
+| String mode rules        | Empty/literal/ref/prefix-delta transitions             | _not yet covered_                                                                                                                                 |
+| Batch selection rules    | Row vs column threshold, micro-batch shape requirement | _not yet covered_                                                                                                                                 |
+| Stateful patch threshold | Prefer patch only at low change ratio                  | _not yet covered_                                                                                                                                 |
+| Numeric codec choice     | i64/u64/float codec heuristics                         | _not yet covered_                                                                                                                                 |
+
+## 15. Trained Dictionary Transport
+
+| SPEC section                      | Requirement (short)                                                                                    | Tests             |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------ | ----------------- |
+| 15.4 trained dictionary transport | Dictionary transport carries id/version/hash/invalidation/fallback metadata and validates payload hash | _not yet covered_ |
+
+## Interop Coverage
+
+| Area                                 | Tests                                                                                                                |
+| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
+| Ruby fixture encode/decode roundtrip | `InteropFixturesTest#test_codec_encode_decode_roundtrip`, `InteropFixturesTest#test_session_encode_decode_roundtrip` |
+| Rust server -> Ruby client           | `InteropFixturesTest#test_decode_rust_server_frames`, `scripts/check-ruby-client-interop.sh`                         |
+| Ruby server -> Rust client           | `InteropFixturesTest#test_rust_decodes_ruby_frames_with_same_values`, `scripts/check-rust-client-interop.sh`         |
+
+## Current Gaps (explicit)
+
+- Most bound-profile, numeric codec, string mode, batch selection, and trained-dictionary spec sections are not yet covered by dedicated Ruby tests.
+- Optional-only extension note: Section 6.4 (zero-copy layout) is not implemented as a conformance target.
+- Optional-only extension note: Section 10.7 (static dictionary) is not implemented as a conformance target.
+- Rust-dependent interop tests skip when `twilic-rust` is not checked out (expected `../twilic-rust` sibling or `TWILIC_RUST_ROOT`).

data/lib/twilic/core/api.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "twilic/core/v2"
+require "twilic/core/protocol"
+
+module Twilic
+  module Core
+    module API
+      module_function
+
+      def encode(value)
+        V2.encode_v2(value)
+      end
+
+      def decode(bytes)
+        V2.decode_v2(bytes)
+      end
+
+      def encode_with_schema(schema, value)
+        enc = Protocol::SessionEncoder.new(Session::SessionOptions.default)
+        enc.encode_with_schema(schema, value)
+      end
+
+      def encode_batch(values)
+        enc = Protocol::SessionEncoder.new(Session::SessionOptions.default)
+        enc.encode_batch(values)
+      end
+    end
+  end
+end