ripple-sql 0.1.0__tar.gz

ripple_sql-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+target/
+.coverage
+htmlcov/
+.env
+.DS_Store
+.idea/
+.vscode/
+
+# keep uv.lock tracked (reproducible installs); do not ignore it
+benchmark/corpus/
+
+# run logs are local receipts, never tracked
+benchmark/*.log
+coverage_stderr.log
+
+benchmark/accuracy_partial.json
+
+benchmark/corpus_holdout/*/
+!benchmark/corpus_holdout/manifest.json
+
+# private review handoff, never ship
+REVIEW-HANDOFF.md
+PLAN-PRIVATE.md

ripple_sql-0.1.0/CHANGELOG.md

@@ -0,0 +1,226 @@
+# Changelog
+
+Notable changes to Ripple. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and Ripple aims for
+[semantic versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-08
+
+First public release.
+
+### Added
+- Column-level SQL lineage, offline, across Snowflake, BigQuery, Databricks, Redshift, Postgres, DuckDB, and Spark SQL.
+- Three ways in: a dbt project (compiled manifest or raw), a monorepo of dbt projects each parsed in its own dialect, or a plain folder of `.sql` files.
+- `breaks`, `trace`, `models`, `columns`, `graph`, `ci`, `serve`, and `mcp` commands.
+- A trust label on every edge (`verified`, `high_confidence`, `moderate`, `review_required`). Uncertain lineage is flagged, never guessed, and trust follows the path.
+- Multi-statement scripts and dumps handled statement by statement, so a data dump becomes its tables and views instead of a parse error.
+- Downstream reach into the dbt semantic layer (metrics, dimensions) and Looker (LookML dashboards and fields), so a column traces to the metric and dashboard it feeds. Looker support is the `looker` extra.
+- An MCP server, so an agent can ask what a change breaks before it opens a pull request.
+- A GitHub Action and `ripple ci` for pull-request blast-radius comments.
+- `ripple serve` opens on the map: every model in the project in its layer, source tables on the left, dashboards on the right, with the links between them. Hovering a model lights its whole chain upstream and down and fades the rest; clicking one unfolds its columns; clicking a column asks. Typing in the question box filters the map before it asks. Models in a layer sit level with the models feeding them, so links cross as little as one pass can manage. Past forty models a layer folds behind "more", and past four hundred links the wires draw only for the lit chain, so a large repo stays readable. The map is computed in `home.model_map` from the graph's nodes and edges, pure and tested; the page draws it from `static/explore.js` and never fetches. An answer replaces the map with "All models" as the way back. The answer page's stylesheet moved to `static/answer.css`.
+- Two more doors to the answer page. `ripple ci --html PATH` writes one page for the whole change, a view per changed column with the rebuild list and the graph embedded for follow-ups; the GitHub Action keeps it as a workflow artifact and links it from the comment. The MCP `breaks` and `trace` tools now carry the answer's text for the agent to relay, and with `page: true` return `html_path`, a file the person can open. Nothing is sent anywhere.
+- The text answer, rewritten after a readability review: columns that share a source share one line, so the arrow only appears where a name changes; "step" replaces "hop"; dashboard numbers sit in their own section with the kind as a word after the name ("orders (semantic model): is_food_order"); a column the graph could not prove keeps its own line ending in "needs review". jaffle-shop's `ecom.raw_products.type` went from 34 lines to 16. The answer page's JavaScript twin of this text is checked against the Python under node in the test suite.
+- The answer page. `ripple breaks orders.order_total --open` (and `trace`) writes one self-contained HTML file and opens it: the question, the ripple hop by hop with review flags and dashboard numbers marked, the terminal text beside it with a copy button, and a box to ask the next question, answered inside the page from the graph it carries (under a 5 MB budget, `RIPPLE_EMBED_GRAPH_BYTES`). `--html PATH` writes it where you say. No server, nothing sent, nothing loaded from the network. A link with `?q=model.column&dir=trace` opens straight on a question.
+- One answer contract, `ripple.answer`: a `breaks` or `trace` result as nodes with hop depth and trust, links, and summary counts, plus the headline every surface prints. The CLI headline and "hit hardest" line now come from it, so the terminal, MCP, the pull-request comment, and the coming answer page render the same answer.
+
+- `benchmark/walk.py` walks the MCP ladder on every corpus and holdout
+  repository the way an agent would (summary, unresolved tables, a question
+  about each, ingest their columns, ask again, name every model) and fails
+  on anything a first-time user would hit. It runs nightly. The first passes
+  found seven classes no unit test had, each now pinned: dbt-disabled models
+  the summary counted but no tool could name; a monorepo source declared
+  twice that took ingested columns on one copy; an ingest swallowed by a
+  same-named model; a table created `LIKE` another that accepted any column;
+  a model's own name refused as ambiguous; deploy-time placeholder
+  qualifiers (`{hscic}.ccgs`, `{{params.dataset}}.blocks`) listed in a
+  spelling no ingest could use; and a column list an agent would copy,
+  truncated at 200 on a table read on more.
+- `breaks` answers carry `also_matches` when a spelling was settled by being
+  one model's own name and other models carry it as an alias.
+- Every MCP response now ends with a `next` line an agent can act on, the
+  way the CLI ends on `try:`. The summary and `breaks` hints count before
+  they blame: review links that trace to tables outside the project are sent
+  to `unresolved_tables`, links reading columns a declared schema lacks say
+  which table to re-ingest, and the rest are named as ambiguous names or
+  unparsed statements, which no ingest fixes. `ingest_schema` reports the
+  review and star-only counts before and after, including an honest
+  "nothing moved".
+- `breaks` on a table outside the project answers with the models that read
+  it; a column it never saw read returns the columns readers actually use
+  (the full list, so it can be handed straight to `ingest_schema`) instead of
+  "0 impacted, complete".
+- `unresolved_tables` reports the qualified spelling the SQL wrote (the one an
+  ingest must use) and includes tables only the engine saw, such as a raw
+  table read by name inside a dbt model.
+- dbt seeds are loaded in raw mode: a CSV's header row is the table's
+  columns, so `ref('state_codes')` resolves and `SELECT *` over it expands.
+
+- Dialect is read from the SQL when nothing declares it: a file starting
+  with `-- Databricks notebook source` is databricks (dbdemos-notebooks was
+  parsed as tsql), stl_/svv_ system tables and DISTKEY/SORTKEY are redshift
+  (dbt-labs/redshift has no profile and was guessed snowflake), and a dbt
+  project with no profile now sniffs its models before falling back to the
+  default, saying "the SQL reads as X" rather than "guessed". Plain SQL
+  beside a dbt project inherits the project's declared dialect instead of
+  assuming postgres (Snowflake's tasty_bytes demo).
+- The summary prints three shared-name warnings and a count instead of
+  every one (HTTP Archive's almanac printed 841 lines); `ripple --json` now
+  carries the full `warnings` list. The "try:" hint prefers a name a person
+  can type over a path-qualified collision name.
+- Plain SQL folders laid out as `<project>/<dataset>/<table>/query.sql`
+  (Mozilla's bigquery-etl, Dataform-style repos) now name each relation by
+  its directory and answer to `dataset.table` and `project.dataset.table`.
+  Before, 887 files were all called "query" and no reference could bind.
+- A directory holding a `schema.yaml`/`schema.json` and no SQL becomes a
+  base table with those declared columns, so `SELECT *` views over tables
+  loaded outside the repo expand instead of degrading everything downstream
+  to review. On bigquery-etl this took trusted links from 6,191 to 22,916.
+- An ambiguous target now suggests the spellings a person would type
+  (`telemetry_derived.events_v1`), not path-mangled internal names.
+- `breaks` and `trace` take `--depth N` (and the MCP tools a `depth`
+  argument) to follow lineage past the default 25 hops; `trace` now
+  discloses when it stopped at the cap, the way `breaks` always has.
+- The per-file wall-clock budget (`RIPPLE_PARSE_BUDGET_S`) now covers the
+  analysis phase too, not just the parse: a generated 3.7MB one-line SELECT
+  parses in seconds and then wedged column analysis for over two minutes.
+  A model that blows the budget reports `timed_out`; the rest of the
+  project still resolves.
+- Statements over 1MB are refused up front with the file named and
+  `RIPPLE_MAX_SQL_BYTES` to override, instead of grinding for minutes: a
+  10,000-model repo with two multi-MB generated dumps now cold-builds in
+  43s instead of 8+ minutes.
+- Usage ingest: `ripple ingest-usage <file>` takes a query-history export
+  (JSONL or JSON array) and `ripple usage` reports which models actually ran
+  in the window, which didn't, and what the queries read outside the project.
+  Statements with no database context are skipped rather than guessed, the
+  word "unused" never appears (a quarterly job looks identical to a dead one),
+  and the query text itself is never stored.
+- Usage collect: `ripple collect-usage` (and the `collect_usage` MCP tool)
+  runs your already-authenticated warehouse CLI — `snow`, `bq`, or
+  `databricks` — and ingests the result in one step. No credential is read,
+  stored, or transmitted; the raw rows are spooled to a temp file, aggregated,
+  and deleted inside the same call. A partial or polluted export is refused
+  outright, and with several configured connections and no declared default,
+  collect lists them instead of picking one.
+- MCP: `ingest_usage`, `usage_summary`, and `collect_usage` tools; `ripple
+  doctor` self-test for MCP client setup.
+- `ripple ci --select dbt` prints the models to rebuild as a dbt `--select`
+  string, computed from git and column lineage: no state backend, no
+  manifest artifact, no meter. Enumerates only what the diff actually
+  touches; anything uncertain (unparseable diff, depth-capped blast, changed
+  row filter, a deleted model's readers) widens to `model+` rather than
+  being skipped, so a missed rebuild can't happen silently. The PR comment
+  and `--json` report carry the same rebuild set, and `breaks_all` now
+  reports honest completeness instead of a hardcoded `true`.
+
+### Changed
+- The answer page looks like its name. A cool water palette: an off-white ground with a hint of blue, deep slate ink, one teal that marks the column you asked about (the drop, with two faint rings that settle when the page opens) and the one button. Links leaving that column carry the teal and fade to gray with distance. A three-ring mark sits by the name. Less to read: the coverage ladder is a status line per rung with the sentence behind a details link, the command's text is folded under a Show text button with Copy text beside it, and the fine print under the question box is one short line.
+- The answer page and `ripple serve` wear a plainer skin: one type scale, one corner radius, system faces, hairlines instead of cards, the accent kept for the one action, state colors kept apart from it (ink for the column you asked about, teal for a dashboard number, amber for a link that needs review), and the command's text on a light well instead of a dark panel. The dotted background, the tracked all-caps labels, and the pill chips are gone.
+- `ripple serve` is now the answer page, live. It opens on a question box, five columns worth asking about first, and the coverage ladder (which external tables still block links, whether query history has been brought in, and the command that moves each rung) instead of painting the whole graph. Answers are computed per request from the files as they are now, by the same renderer the CLI uses, so the page and the terminal cannot disagree. `ripple serve orders.order_total` opens straight on a question. The server stays localhost-only and read-only. `/api/breaks` and `/api/trace` return the answer contract with its text; `/api/graph` is unchanged.
+
+### Fixed
+- Ripple holds on Windows. Every SQL, YAML, LookML, manifest, and cache file is read and written as UTF-8 whatever the machine's code page (a test scans the source for a text read or write that forgets to say so). A pipe out of `ripple` carries UTF-8 too, so the arrows in the text survive `ripple breaks ... > out.txt` and the MCP transport on Windows, and a console that cannot draw an arrow shows a placeholder instead of crashing. A model's path is the same forward-slash string on every OS, so a PR comment written on Linux names the same model on a Windows laptop. CI runs the suite on Windows.
+- Eight shapes `ripple ci` used to miss, all of them edits that change which rows survive while every per-column signature stays the same: a filter reached through a join alias (`join flags f ... where f.big`), a filter reached through two CTE hops, a GROUP BY key or expression, a QUALIFY on the select's own alias, and a union branch. One rule replaces the case-by-case checks: the row-deciding closure, every WHERE, HAVING, QUALIFY, JOIN, GROUP BY, and DISTINCT clause plus the whole chain of expressions behind every column those clauses read, through CTEs, derived tables, and set operations. A change anywhere in it widens to the whole model; when sqlglot cannot resolve the statement the raw clause text is the floor. The closure also covers the clauses that pick which rows survive rather than filtering them: an ORDER BY under a row cap (`limit`, `offset`, `fetch`, `top`) or a `DISTINCT ON`, and every projected expression under a plain `SELECT DISTINCT`, since those decide which rows count as duplicates. Ordering without a cap decides nothing and stays precise, and a projection inside a joined subquery no longer widens readers of untouched columns, while the join's kind, source, match condition, and join condition still do. The set operator itself is part of it, since `UNION` keeps one row per duplicate where `UNION ALL` keeps both and `EXCEPT` is not `INTERSECT`, and so are the clauses that reshape a row set without filtering a column (`TABLESAMPLE`, `CONNECT BY`, `PIVOT`, `MATCH_RECOGNIZE`). Duplicates are compared by value, so renaming an output under `SELECT DISTINCT` decides nothing.
+- A column read only by a downstream WHERE, JOIN, or window key changes every row of that reader. The comment said "nothing downstream" and `--fail-on breaks` let it through; the comment now says "filters rows in paid" (or joins, or frames a window) and the gate fails.
+- `ripple ci --html` crashed with a KeyError on any changed column whose blast radius passed the depth cap, and the change page flattened a window key or a review flag into "filters rows on it". Both facts now travel from ci.py into the page.
+- `ripple breaks --json`, `ripple trace --json`, and the MCP `breaks` and `trace` tools returned the raw graph counts next to the contract's text, so a payload could disagree with its own words. Every JSON door now carries the contract under `answer`, the preview text under `text`, and top-level counts aligned to it. The MCP `page` flag is now inside the tool's declared properties.
+- The answer page's own follow-up walk counted dashboard numbers as columns and skipped wildcard links; it is now a port of the graph's walk, checked against Python under node. A dashboard-only hit no longer reads as "Nothing downstream reads it".
+- A trace stand-in for a reader the walk never listed sat one step further back instead of one step nearer. The contract's merge order now knows the graph's fourth trust level, "moderate", instead of raising on it.
+- `ripple ci --select dbt` no longer lists `metric:`, `semantic:`, or `exposure:` names, which dbt cannot build.
+- `ripple serve` refuses requests whose Host header is not loopback, so a page on another domain that rebinds DNS to 127.0.0.1 cannot read the graph. YAML and LookML edits now refresh the live graph and the disk cache. Concurrent first requests build the graph once.
+- One pruned walk decides which files on disk feed lineage, shared by the disk cache and the live server, so a `dbt run` writing under `target/` no longer invalidates the graph on every request; the live server computes the fingerprint before taking its lock.
+- A follow-up asked on the answer page resolves a model spelling the way the command does, whatever its case, so a name `ripple breaks` answers is no longer refused by the page it wrote. A spelling that names several models says so instead of guessing, and keeps what else it could have meant. A column no link touches is still a column, so `select 1 as x` answers there too. A link that resolves to nothing says so rather than showing the answer the page was written for.
+- The live server saw a file rename that kept the file count and timestamps as no change and answered from a stale graph. One stamp over path, size, and time now serves the live check and the disk cache, and build directories are excluded whatever their case.
+- The answer page's export carries each link's reason once, so an offline follow-up keeps the explanation behind a review flag; equal-depth hits are ordered by depth, trust label, and model on both sides, so the offline text matches the command's; the twin says "at the depth cap" when no depth is known.
+- The home page's starters rank by reader models, not dashboard entries.
+- The `breaks` headline and the pull-request comment counted dashboard numbers as columns: "19 columns in 4 models and 7 dashboard numbers" was 12 columns plus the 7 numbers themselves. One helper now counts model columns and dashboard numbers apart, in the CLI, the MCP payload, the answer page, and the CI comment. A change that reaches only dashboard numbers still fails `--fail-on breaks`.
+
+- Ingested schemas were invisible to a dbt project living in a subfolder:
+  the CLI and MCP write `.ripple/schemas.json` at the repo root, the loader
+  read only the dbt folder. Every ingest on such a repo was a silent no-op.
+- A read of a column missing from a declared or ingested schema was
+  downgraded with no reason attached; the edge now says which column and
+  which table's list may be incomplete.
+- An ingested qualified table no longer claims a bare name a model owns, and
+  `model_columns` prefers the analyzed model when a name is shared with a
+  source.
+- The semantic layer parser reads dbt's inline syntax (`semantic_model:`
+  nested under a model, dimensions and entities on columns, metrics on the
+  model). jaffle-shop migrated to it upstream and the old top-level parser
+  silently produced zero semantic nodes, so the README's own hero output
+  stopped reproducing. A metric with a constant or computed `expr` is
+  dropped, never guessed. The rename now also reaches `metric:lifetime_spend`
+  four hops down.
+- Review sweep (11 findings fixed, each pinned by a test):
+  a hostile BigQuery `region` value can no longer smuggle SQL into the
+  user's authenticated `bq` session; Databricks collection reports its
+  scope as `visible-to-this-login` (its history API has no mine/account
+  split); a Snowflake window clamped to INFORMATION_SCHEMA's 7 days is
+  disclosed instead of silently misreported, and account-scope collections
+  hitting the row limit flag truncation; a qualified table read inside a
+  same-named CTE is no longer erased; two tables sharing a leaf name both
+  count; a valid export mixing offset-less and offset-bearing timestamps
+  no longer crashes ingestion; usage summaries (MCP and CLI) warn when the
+  project's models changed since ingest; and `ripple doctor`'s fallback
+  command now actually forwards `--path`, so the copy-paste config serves
+  the project it printed instead of the client's working directory.
+- Usage attribution now uses model identity instead of bare leaf names.
+  With dbt-manifest aliases, a read of `other_db.payments` is an outside
+  table, not a sighting of this project's `payments`. Without identity,
+  one model name referenced from several databases in a single export is
+  refused into the ambiguous bucket rather than merged, because merging
+  them is exactly how usage counts end up confidently wrong.
+- The graph cache is written atomically (write-then-rename). A crash mid
+  write used to leave a corrupt file at the live path, where the matching
+  fingerprint made every later session fail the load and silently pay the
+  full rebuild, which on a large repo is exactly the MCP client timeout.
+- The declared sqlglot floor was a promise the tests didn't keep: versions
+  below 30.14 parse T-SQL temp tables and UPDATE derivations differently,
+  producing silently wrong lineage. The floor is now the tested truth
+  (`sqlglot>=30.14,<31`), a CI job runs the full suite against the exact
+  floor, and a test asserts sqlglot's license stays MIT so a change inside
+  the allowed range fails loudly instead of arriving silently.
+- A CTE named after the model that contains it (dbt's `with X as (...)
+  select * from X` house style) no longer downgrades every pass-through
+  edge to review_required. The CTE shadows only the model's own name, which
+  is not ambiguous; on dbt's jaffle-shop this alone was 17 of 18 review
+  flags. A CTE shadowing a different model still downgrades.
+- The summary's "why so many review links" line now counts before it blames:
+  external tables are only named as the cause with the number of review
+  links they actually account for. `ripple ingest-schema` prints whether the
+  review count moved, including an honest "still N".
+- `ripple ci` no longer says "nothing downstream" about a removed column
+  whose consumers exist: the current graph has already lost the column and
+  its edges, so the blast is now computed against the base state.
+- Usage ingest only counts statements that read or write data. GRANT, SHOW,
+  DESCRIBE and other administrative statements no longer register as model
+  sightings (a GRANT could make a dead model look alive), and `SHOW TABLES
+  IN <schema>` no longer fabricates the schema as an outside table.
+  `COPY INTO` now counts as a write.
+- `ripple doctor` shell-quotes the config command it prints, so the
+  no-binary-on-PATH fallback (`python -c "..."`) survives copy-paste.
+- A collected usage report names its platform and connection instead of the
+  temp spool filename.
+
+- Window `PARTITION BY` and `ORDER BY` columns are no longer reported as value
+  sources. `lag(mrr) over (partition by customer_id order by date_month)` now
+  traces to `mrr` alone. The keys are kept as `window` edges into
+  `(window key)`, so `breaks` still reports a model whose window partitions on
+  a column you renamed. This was the largest miss in the held-out benchmark;
+  see `benchmark/HOLDOUT.md` for what that does and does not let us claim.
+- `ripple ci` widened any edit inside a CTE to the whole model: one renamed
+  column in a `with source, renamed select *` model reported "internal
+  logic changed: 30 columns in 15 downstream models derive differently".
+  Inner expressions are now attributed to the output columns whose lineage
+  passes through them, so a rename is a remove and an add, and a formula
+  change lands on the columns that derive from it. Only an inner expression
+  no output column reaches (a flag used just in a WHERE) still widens the
+  whole model.
+
+### Removed
+- The dark whole-graph canvas that `ripple serve` used to open (`static/index.html`). Every surface now draws one answer.
+
+[Unreleased]: https://github.com/bteh/ripple/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/bteh/ripple/releases/tag/v0.1.0

ripple_sql-0.1.0/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 2026 Brian Teh
+
+   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.