solid_loop 0.0.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e3bbfed94f57749cc453fa556177eb4aa339e304c41d5c6e2dd58f5f55cd7c55
+  data.tar.gz: beda9759a9b2d1d576b007cc6782139b06c97922b7ce0bb0117685190d437f93
+SHA512:
+  metadata.gz: b9447a7363162eac0dcc9c23964855897a427a09a50c7af701e07cbea1edd65967f72766b9e6d419a8312189d35492bf67c1a0253815c779b53e73aadb6e28a0
+  data.tar.gz: 3477debd8e6e9fa6b8b047fb4e7b0cb2cd36aa53edeedfa37c99e05ab1c213a0fc2618f92a22b7edb3e0a014f8d49b48dbf4400728ba4bd4f73819bc048b8a59

data/CHANGELOG.md

@@ -0,0 +1,156 @@
+# SolidLoop 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.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.0.4] - 2026-07-16
+
+#### Fixed
+- Admin dashboard time-series charts no longer fail with "Error Loading Chart:
+  This method is not implemented: Check that a complete date adapter is
+  provided." Chart.js v4 requires a registered date adapter for the time scale;
+  vendor `chartjs-adapter-date-fns` (bundled with date-fns) and load it after
+  Chart.js and before Chartkick in the admin layout.
+- Capture the failing LLM response in the wire-log `Event` on any non-2xx (e.g. OpenRouter `403`) — status, redacted response headers and a bounded (redacted) response body — and include that body in `loop.error_message` instead of the empty `"HTTP 403: "`; the streaming path now recovers the body the adapter drains via `on_data`, and connection/timeout failures are recorded too.
+- Redact `Authorization`, `x-api-key`, `api-key`, and API-key query parameters from persisted LLM event URLs, wire logs, and exception messages.
+- Treat MCP HTTP `404` responses as session loss so `session_recovery: :auto` can re-initialize mounted SolidLoop MCP sessions.
+- Preserve Gemini signed reasoning through the complete reasoning-packer and request-rendering path.
+- Resume unresolved tool steps before starting another LLM turn, with generation-token fencing so stale workers cannot overwrite pause/resume decisions.
+- Checkpoint each completed tool invocation (`executed_at`) so a duplicate or retried job replays its stored result instead of repeating the tool — in both parallel and sequential execution modes.
+- Preserve MCP `isError` as `ToolCall#is_success = false` while still returning the tool result to the model.
+- **`ToolExecutionJob` now requires its generation token.** A job with no token, or one that does not match the loop's current `execution_token`, fails closed (no-op) instead of adopting the loop's token; the same applies to the mid-pipeline `loop_active?` checks. Legacy one-argument `ToolExecutionJob(tool_call_id)` jobs enqueued before this release will no-op — drain or `resume!` affected loops after deploying.
+- **Sequential ordering is a checked invariant, not a convention.** Under `sequential_tool_calls?`, the first-unresolved guard runs under the parent assistant-message lock (the same lock results land under), and an out-of-order/stray/duplicate job no-ops **and re-dispatches the actual first unresolved call**, so a stray job self-heals the order instead of stalling the turn. Every "first/next tool call" selection goes through the explicit `ordered` scope.
+- **All generation-owned writes are token-fenced.** Assistant/tool turn persistence, `triggering_message` state, loop counters and MCP session/tool sync now re-validate the execution token under the loop row lock (or a conditional re-check around network calls) before writing; a stale worker that lost a pause/resume race performs zero mutations instead of corrupting the current run.
+- **Recovery only resumes the conversation tail.** `Loop#unresolved_tool_calls` starts from the newest visible user/assistant message and proceeds only when that tail is an assistant tool turn — an obsolete tool turn behind newer messages can no longer be resurrected.
+- **State advancement and successor-job dispatch are atomic.** Every dispatch site (`ResponseParsing`, `ToolCallXmlParser`, `ResponseCreation`, `Base.start!`/`#resume!`) enqueues the next job *inside* the transaction that commits the state change; `SolidLoop::ApplicationJob` sets `enqueue_after_transaction_commit = false` so the enqueue participates in it. This requires a same-database transactional job backend (Solid Queue / GoodJob) — see the README's "Job backend requirement" section.
+
+#### Added
+- **Steering — enqueue a user message onto a live loop, delivered at the next
+  turn boundary.** `Loop#enqueue_user_message(content)` stages a `role: user`
+  message (`steering: true, is_hidden: true, status: pending`, new `steering`
+  column + partial index) that is excluded from the in-flight turn and surfaced
+  as still-pending; it is materialized (un-hidden, `status: success`) at the
+  START of the next turn by `MessageBuilding#build_messages` via
+  `Loop#drain_pending_steering!`. Because materialization runs at a resolved
+  boundary and positions by `id`, the message always appends AFTER the last
+  resolved exchange and never between an `assistant(tool_calls)` message and its
+  tool results — the chat-format pairing invariant holds without special-casing.
+  Enqueue is rejected on a terminal (`completed`/`failed`) loop; a `paused`
+  (HITL) loop keeps the message pending until the next post-resume turn.
+- **Steering messages are editable/cancellable while pending.**
+  `Loop#edit_pending_message(id, content)` and `Loop#cancel_pending_message(id)`
+  mutate/void a still-staged message; `Loop#pending_user_messages` lists them in
+  enqueue order. Delivery is **exactly-once and crash-safe**: materialization
+  flips `pending -> success` under the message row lock guarded by a `pending?`
+  re-check, so a retried (or concurrent) turn build never re-delivers, and a
+  concurrent edit/cancel either wins the lock (applies cleanly, delivered next
+  turn) or loses it (sees the delivered status and is refused with
+  `SolidLoop::SteeringError`) — never a half-applied state.
+- **`SolidLoop::Mcp.server(toolset, auth:)` — serving toolsets over Streamable HTTP** (see `docs/decisions/mcp-server.md`): a mountable Rack endpoint per toolset (`mount SolidLoop::Mcp.server(SearchTools, auth: McpAuth.new) => "/mcp/search"`). The POST body dispatches straight into `Toolset#deliver` — the same method the in-process agent path calls — so one toolset is consumed locally and served externally with shared schemas, wire logs and admin. Exposure is the mount itself: an unmounted toolset is not exposed.
+- **Fail-closed auth with a principal:** `auth:` is required at construction and is any object responding to `call(token, request) -> principal | nil`; `nil` → empty 401. No token storage in the gem — bearer lists, DB lookups and IP allowlists live in the host's authorizer.
+- **`CallContext#principal`:** external calls arrive in tool handlers as `CallContext(agent: nil, loop: nil, principal: <authorizer's return>)`. Handlers must no longer assume `ctx.agent` / `ctx.loop` are present.
+- **`McpInboundSession`** (new migration): one row per external client connection — server name, principal label, `last_used_at`, `terminated_at`. `initialize` issues `Mcp-Session-Id` (honoring `Toolset#on_initialize` minting); requests without the header get `400`, unknown/terminated sessions `404`; `DELETE` terminates the session but keeps the row (a client must not be able to erase its own audit trail). Admin: **Inbound MCP** index/show pages.
+- **Inbound observability:** every request that reaches a session writes a loop-less `SolidLoop::Event` (`mcp_inbound_*`, eventable = the inbound session) with the JSON-RPC envelopes and a wire log.
+- **Protocol scope (deliberately narrow):** notifications (no `id`) → `202`; batch bodies → `-32600`; malformed JSON → `-32700`; **no SSE** — `GET` → `405` (the Streamable-HTTP no-stream option), POST always answers a single `application/json` response.
+- **Prompts DSL on `Mcp::Toolset`:** `prompt "name", description:, arguments: [...] do |args, ctx| ... end` served via `prompts/list` / `prompts/get` on every transport (in-process and mounted); the `prompts` capability is advertised only when prompts are declared. Handler exceptions become `-32603` (prompts have no `isError` shape).
+- **MCP client breadth:** `McpClient#list_prompts` / `#get_prompt` / `#list_resources` / `#read_resource` / `#server_capabilities`. Session initialization snapshots the server's capabilities — and, when advertised, the discovered prompts/resources lists — into `McpSession#metadata` (best-effort, with `mcp_list_prompts` / `mcp_list_resources` events); the admin session page shows them.
+- **HITL middleware seam:** `ToolContext#skip_execution!` lets policy middleware emit a rejected/expired tool result through the standard response and continuation path without invoking the tool.
+- **In-process principals:** `Base#mcp_principal` defaults to the loop subject and is passed to local toolsets through `CallContext#principal`.
+- **Per-tool-call idempotency key:** every tool invocation carries `ToolCall#idempotency_key` (`solid_loop:tool_call:<id>`) — exposed to in-process handlers as `CallContext#idempotency_key` and sent to remote MCP servers as `_meta["solidloop/idempotencyKey"]` on the `tools/call` params. `executed_at` cannot cover a crash between a remote side effect and the checkpoint commit; irreversible tools should dedupe on this key (see `docs/guides/mcp_transports.md`).
+- **`SolidLoop::Base#sequential_tool_calls?`** (default `false`): opt a specific agent into strict, one-at-a-time tool execution in model order (`def sequential_tool_calls? = true`). The single flag gates emission, the ordering guard and continuation together. Recommended for agents that gate tools on human approval — see _Changed_ below and `docs/guides/tool_middlewares.md`.
+
+#### Changed
+- `SolidLoop::Event#loop` is now optional (`loop_id` nullable was already in the schema): inbound MCP events have no loop.
+- **Same-turn tool calls now run in parallel by default.** When an assistant turn returns N tool calls, all N `ToolExecutionJob`s are enqueued at once and run concurrently across workers; the earlier strict model-order execution is now opt-in per agent via `sequential_tool_calls?`. Durability is preserved in both modes — execution-token fencing rejects stale-turn jobs and the `executed_at` checkpoint prevents duplicate execution — and the completion gate still queues the next LLM turn only after every result exists (fenced so exactly one job queues it). Per-tool HITL approval is cleanest under sequential mode, where a single call is in flight at a time. **Rollout:** a loop caught mid-turn across the upgrade from an earlier sequential-only build may have only its first call enqueued; a parallel-default worker will not chain the remaining calls, so it can stall with results missing. Drain in-flight tool loops before deploying, or `pause!`/`resume!` an affected loop afterward — `resume!` re-dispatches *every* unresolved call in parallel mode (only the first in sequential mode).
+
+## [0.0.3] - 2026-07-09
+
+#### Removed
+- **Native Ruby tools — every tool is now an MCP tool** (see `docs/decisions/mcp-only-tooling.md`):
+  - `SolidLoop::Base#tools` and the `FUNCTION_NAME` / `to_tool_spec` conventions for tool classes.
+  - The Ruby-tool resolution branch in `ToolMiddlewares::ToolExecution` — one execution path remains: `loop.mcp_tools`.
+  - The native merge in `Middlewares::MessageBuilding`; the LLM payload advertises `loop.mcp_tools` only.
+  - The unknown-tool feedback message lists the loop's MCP tools only.
+- `McpClient#last_response` (Faraday response) — replaced by `McpClient#last_result` (`Mcp::Result`).
+
+#### Migration notes (0.0.2 → 0.0.3)
+- Move each native tool class into a `SolidLoop::Mcp::Toolset` and replace `def tools` with an `mcps` entry — full before/after in `docs/decisions/mcp-only-tooling.md`:
+  ```ruby
+  class TaskTools < SolidLoop::Mcp::Toolset
+    server_name "tasks"
+    tool "check_task", description: "...", input_schema: { type: "object" } do |args, ctx|
+      "Task verified: #{args['path']}"
+    end
+  end
+
+  class MyAgent < SolidLoop::Base
+    def mcps = [ { name: :tasks, toolset: TaskTools } ]
+  end
+  ```
+- Behavior change: exceptions raised inside a tool no longer fail the loop — they return an `isError` tool result the model can self-correct on (standard MCP semantics).
+- Toolset schemas live in code, so discovery is free — agents using toolsets should return `true` from `refresh_mcp_tools?` so schemas persisted in `mcp_tools` don't go stale across deploys.
+
+#### Added
+- **MCP Transport Port:** `SolidLoop::Mcp::Transport` (a `deliver(payload, session_id:, context:)` port) and `SolidLoop::Mcp::Result` (body, session_id, raw_request, raw_response, status), so MCP servers can be reached over pluggable transports.
+- **`Mcp::HttpTransport`:** the Faraday implementation extracted from `McpClient` as the reference adapter; connection-level failures (timeouts, refused connections) are now wrapped in `SolidLoop::McpError`.
+- **Transport conformance suite:** RSpec shared examples (`"a solid_loop mcp transport"`) covering session identity, raw request/response presence, protocol vs transport error semantics, and thread safety of concurrent `deliver` calls.
+- **`Mcp::Toolset` (in-process MCP server):** the home of former native tools. `server_name` / `tool` DSL (name, description, input_schema, block); `deliver` dispatches `initialize` / `tools/list` / `tools/call` in-process with the JSON boundary preserved (blocks receive string-keyed arguments exactly as over HTTP). String results become text content; Hash results are serialized to JSON text content **and** `structuredContent`; raised exceptions become `isError: true` tool results. Stateless by default; `on_initialize` override mints real session ids.
+- **`Mcp::CallContext` (`agent:`, `loop:`):** threaded from `McpSessionInitializer` / `McpToolExecutionService` through the client into every `Transport#deliver`, so in-process toolsets reach domain state without a network hop.
+- **`mcps` config entry forms:** `toolset:` (class or instance) and `transport:` (any `Mcp::Transport` object) alongside the existing `url:` sugar; resolved by `Mcp::ClientFactory`. Non-HTTP transports default to `stateless: true`. `required_tools:` is now accepted as the explicit validation list (falls back to `tools:` as before).
+- **Tool-name prefixes and collision validation:** `prefix: "search"` advertises tools to the LLM as `search__fetch_url` and strips the prefix before `tools/call` reaches the server. Cross-server tool-name collisions within a loop now fail the loop at session initialization with a message naming the colliding servers — never resolved silently.
+- **`session_recovery: :auto | :fail` per server:** `:auto` (default) keeps today's behavior — one transparent re-initialize on session loss; `:fail` fails the tool call loudly instead, for servers where the session is expensive server-side state (e.g. a sandbox container per session).
+- **`transport_kind` on `solid_loop_mcp_sessions`** (`http` / `local` / `stdio` / `custom`, default `http`) — added to the init migration during the pre-release schema window and shown in the admin sessions list, session page, and Inspector. The Inspector works over local transports.
+- **`Mcp::StdioTransport` (restricted contract):** child-process MCP servers over stdin/stdout with a spawn-per-call lifecycle (spawn → `initialize` handshake → request → graceful shutdown, kill on timeout, all inside one `deliver`). Stateless servers only — the session id is synthetic and implies no server-side continuity; this is a deliberate consequence of the durable-async core. Options: `command:` (argv array, never a shell string), `env:`, `cwd:`, `timeout:` (per call, includes spawn+handshake). stderr is captured into the wire log via the new optional `Result#stderr`; non-JSON stdout lines are kept as diagnostics instead of failing the call.
+
+#### Storage prep
+- `events.request_data` / `events.response_data` are now nullable in the init migration — preparation for a future wire-log storage change that will stop persisting these payloads inline.
+
+#### Changed
+- **`McpClient` is now a thin protocol layer:** it builds JSON-RPC envelopes and delegates I/O to a transport (`transport:` keyword; defaults to `Mcp::HttpTransport` built from `url`/`token`/`headers`). Public API (`initialize_session`, `list_tools`, `call_tool`) is unchanged.
+- **Wire logs decoupled from Faraday:** `McpSessionInitializer` and `McpToolExecutionService` record Events from `Result#raw_request`/`raw_response`/`status`, and `McpClient#wire_log` renders the same data — identical observability for every transport. `McpClient#last_response` (a Faraday response) is replaced by `McpClient#last_result` (an `Mcp::Result`). Event logs no longer include HTTP headers, only the JSON-RPC envelopes and status.
+- **`McpClient` raises `McpError` on JSON-RPC protocol-error envelopes** (`{"error": {...}}` with a 2xx status) for `initialize` / `tools/list` / `tools/call` instead of silently returning `[]` or a pretty-printed envelope marked successful. Non-Hash response bodies no longer crash the client; `session_recovery:` is validated eagerly at client construction.
+
+## [0.0.2] - 2026-07-08 (internal milestone — not published to RubyGems)
+
+#### Added
+- **Admin Dashboard (Web UI):** Mountable admin area for observing agents in the browser.
+  - Dashboard overview plus index/show screens for `Loops`, `Messages`, `ToolCalls`, `Events`, `McpSessions`, and `McpTools`.
+  - Query objects (`SolidLoop::Admin::*Query`) encapsulating filtering, ordering, and pagination, with a shared `_pagination` partial.
+  - Standardized `admin` layout built on reusable CSS utility classes.
+  - Charts rendered from vendored, self-hosted assets (Chart.js + Chartkick) — no external CDN, works offline and under a strict Content-Security-Policy.
+- **MCP Inspector:** Interactive tool runner in the admin UI to invoke MCP tools ad‑hoc and replay previous tool calls, streaming results back via Turbo Streams (`run_tool`).
+- **Multi-Provider LLM Dialects:** Provider-specific request/response translation so agents can target different backends.
+  - `Dialects::Anthropic` — native `/v1/messages` support: system-prompt extraction, `thinking` (reasoning) blocks, `tool_use`/`tool_result` mapping, and tool-result merging.
+  - `Dialects::Gemini` and refactored `Dialects::OpenAi`.
+  - `LlmUsageParser::Anthropic` for provider-native token/usage telemetry.
+- **Live Observability:** `ObserveBroadcastJob` broadcasts newly created messages to a per-loop Turbo Stream channel (gated by `observe_enabled?`) for real-time UI updates.
+- **Multi-Rails Testing:** `Appraisal`-based gemfiles for Rails 7.1, 7.2, and 8.1.
+- **Test Infrastructure:** Full RSpec suite with per-provider integration specs (agent loops for OpenAI/Anthropic/Gemini, error recovery, legacy XML tool calls), LLM emulators (streaming, Anthropic, Gemini), an MCP emulator, and factories.
+- **Coverage Tooling:** `lib/tasks/coverage.rake`, contributor coverage docs, and expanded CI workflow.
+
+#### Changed
+- **Improved Tool Error Feedback:**
+  - Unknown/unresolvable tool calls now return a structured message listing all available tools (native + MCP) so the model can self-correct.
+  - Invalid JSON in tool-call arguments now yields a clear re-prompt with a column pointer to the syntax error, and automatically re-queues an `LlmCompletionJob` so the loop can retry instead of stalling.
+
+## [0.0.1] - 2026-04-12 (internal milestone)
+### Initial MVP
+
+#### Added
+- **Core Architecture:** `ActiveJob` + `PostgreSQL` foundation for long-lived, autonomous AI agents.
+- **Middleware System (Rack-style):**
+  - **LLM Middlewares:** Complete pipeline for `LlmCompletionJob` including `ErrorHandling`, `AgentInitialization`, `MessageBuilding`, `EventLogging`, `NetworkCalling`, and `ResponseParsing`.
+  - **Tool Middlewares:** Complete pipeline for `ToolExecutionJob` including `ErrorHandling`, `AgentInitialization`, `EventLogging`, `ToolExecution`, and `ResponseCreation`.
+- **Pipeline Builder DSL:** Allow Host applications and Agents to dynamically mutate pipelines (`insert_before`, `insert_after`, `use`, `replace`, `delete`).
+- **Resiliency:** Robust `ErrorHandling` to catch network timeouts and gracefully fail loops while preserving state and checkpoints in PostgreSQL.
+- **Dual Tooling Protocol:**
+  - Internal: Native Ruby object method invocation via `allowed_tools`.
+  - External: Model Context Protocol (MCP) Streamable HTTP Server integration (`McpClient`).
+- **Token Telemetry:** Aggregation and computation of TTFT (Time To First Token), TPS (Tokens Per Second), Prompt caching, and reasoning metadata via `LlmUsageParser`.
+- **Event Logging:** Captures raw TCP/IP payloads and MCP interaction states for observability and debugging.
+- **Payload Normalization:** Included optional `ToolCallXmlParser` for legacy open-source models generating `<tool_call>` XML blocks (disabled by default).
+
+#### Fixed
+- **N+1 Queries:** Added `inverse_of` to associations across `Loop`, `Message`, `ToolCall`, `Event`, `McpSession`, and `McpTool` models to ensure objects are correctly linked in memory during preloading.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,67 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+**ru.ruslan@gmail.com**. All complaints will be reviewed and investigated promptly
+and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+<https://www.contributor-covenant.org/version/2/1/code_of_conduct.html>.
+
+[homepage]: https://www.contributor-covenant.org

data/CONTRIBUTING.md

@@ -0,0 +1,82 @@
+# Contributing to SolidLoop
+
+Thanks for your interest in improving SolidLoop! This document explains how to
+set up the project locally, run the test suite, and submit changes.
+
+By participating in this project you agree to abide by our
+[Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Getting started
+
+SolidLoop is a Rails engine gem backed by ActiveJob + PostgreSQL. You will need:
+
+- Ruby >= 3.1
+- PostgreSQL (running locally and reachable by the dummy app)
+- Bundler
+
+Clone the repo and install dependencies:
+
+```bash
+git clone git@github.com:ruslan/solid_loop.git
+cd solid_loop
+bundle install
+```
+
+Prepare the test database (one-time):
+
+```bash
+cd test/dummy && RAILS_ENV=test bundle exec rails db:create db:schema:load && cd -
+```
+
+## Running the tests
+
+The default suite runs against the current Rails version:
+
+```bash
+bundle exec rspec
+# or
+make test
+```
+
+We support Rails 7.1, 7.2, and 8.1 via [Appraisal](https://github.com/thoughtbot/appraisal).
+Install the appraisal gemfiles and run the suite across all supported versions:
+
+```bash
+bundle exec appraisal install
+bundle exec appraisal rspec
+```
+
+## Test coverage
+
+Coverage is collected with SimpleCov (HTML + JSON formatters). After running the
+suite, `coverage/coverage.json` is generated. Analyze it with the bundled Rake task:
+
+```bash
+bundle exec rake coverage:report            # full report, worst-covered first
+bundle exec rake coverage:report'[partial]' # partially-covered files with line numbers
+bundle exec rake coverage:report'[,,branch]' # coverage of lines changed on this branch
+```
+
+New code should ship with tests. Please check that your changed lines are covered
+before opening a pull request.
+
+## Submitting changes
+
+1. Fork the repository and create a topic branch from the default branch.
+2. Make your change with accompanying tests.
+3. Ensure the full suite is green across supported Rails versions.
+4. Update `CHANGELOG.md` under an `## [Unreleased]` heading describing your change.
+5. Open a pull request with a clear description of the motivation and approach.
+
+## Reporting bugs
+
+Open an issue with:
+
+- The SolidLoop version, Ruby version, and Rails version.
+- A minimal reproduction (a failing spec is ideal).
+- Expected vs. actual behavior, including any relevant backtrace.
+
+## Coding style
+
+Match the style of the surrounding code. Keep changes focused — unrelated
+refactors are easier to review as separate pull requests.

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Ruslan Mukhametov
+
+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.