olyx-guardrails 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '069f552d05ca4f0ee61bf1496b27da5961477bb75eb422424b1cd19b31e1ac61'
-  data.tar.gz: 9189f069fc540a3ecab429ebec194cb9c870917966837fb4c7fff428d705ed78
+  metadata.gz: c330386f60e14497f63e1e07978fa28aa3b21b028685662fd524964689d6b340
+  data.tar.gz: 052c2af355cc8351a69052e1e07e5e8655c723b4f17b46c86f0d9726b4978d1d
 SHA512:
-  metadata.gz: 264d94b6a842c268cd30430ecf1cb6f2d49557d12266f331e594160e7100d8539b1c35351e4dbab58dd0525c97760c738a4f139270aefcb8d2f251835bd04e5c
-  data.tar.gz: 75bd129939354ed2333d622cc215cc4a34b0967e39fcb482345719ddd312f9637ceb6a13beddfd27cbfa242f6057bd82178590e8ab98e63e10d79a461fe99b6d
+  metadata.gz: 94dbcc7502ced8d907c5154c585ab735330b33fa4b8a7cd0f3d74e4ec6cc1d325991ecb15fbcb9a00a5033b263486e4c040285fa0243e8a92540c7ec171c1647
+  data.tar.gz: fd53482fe7bb8c4f977d01cc0ea0064b10ef29ca5d722b024862b7d581d54647fb7e7d6b6a935b4874bc80f67c5fbd152b004d5454c925a54287084cd2b763b0

data/CHANGELOG.md

@@ -3,6 +3,28 @@
 All notable changes to olyx-guardrails are documented here.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [1.1.0] - 2026-07-23
+
+### Changed
+
+- Rails metadata now validates consistently as a Hash at every facade and
+  adapter boundary.
+- Blocking exceptions use boundary-neutral wording, Active Job selectors
+  validate when declared, and inherited job declarations remain effective.
+- Notifier misuse raises `ArgumentError`; `nil` now means only that a valid
+  decision has zero risk.
+- The Rails generator provides copyable policy customization instructions and
+  tests the customized YAML path.
+- Contributor setup, complete local quality validation, and maintainer release
+  verification have canonical commands and documentation.
+- Closely coupled proxy objects were folded into their owning runtime,
+  configuration, result-building, and notification components.
+- Provider risk scores now require a finite Numeric value; numeric strings are
+  ignored instead of being coerced across the untrusted provider boundary.
+- Contributor and Rails appraisal locks use the current `net-imap` patch.
+- CI refreshes the Ruby advisory database and blocks known-vulnerable locked
+  dependencies without making the offline local quality gate network-dependent.
+
 ## [1.0.0] - 2026-07-21
 
 Initial public release.
@@ -13,7 +35,7 @@ Initial public release.
   prompt-injection, secret, and restricted-policy findings without
   transforming the input. Returns `allowed`, per-category detection flags,
   `risk_score`, and a `checks` array with one entry per category. The
-  `length` check runs first; content and AI checks are skipped (not just
+  `length` check runs first; content and LLM checks are skipped (not just
   failed) when it does, so an oversized payload never pays their cost.
 - `Olyx::Guardrails.redact` — transforms text by removing every
   regex-detected PII, secret, and restricted-policy match, without making an
@@ -33,9 +55,9 @@ Initial public release.
   monitoring-only restricted-content rules, `substring`/`whole_word`/`regexp`
   term matching, case-aware regex support, configurable safe replacements,
   and `Policy.from_h` for YAML/JSON-style Hash loading.
-- `ai_failure_mode:` controls how an analyzer failure is handled: `:allow`
-  (default, keeps the deterministic result), `:block` (adds a failed `ai`
-  check and rejects), or `:raise` (`AiAnalyzerError`).
+- `llm_failure_mode:` controls how a provider failure is handled: `:allow`
+  (default, keeps the deterministic result), `:block` (adds a failed `llm`
+  check and rejects), or `:raise` (`LlmProviderError`).
 - Invalid configuration — duplicate rule names, empty-matching or invalid
   patterns, malformed message arrays, invalid custom regexes — raises
   `ArgumentError` at construction time rather than silently degrading into a
@@ -61,31 +83,29 @@ Initial public release.
   span. Custom patterns extend detection and are classified as secrets; use
   `PolicyRule` for named business restrictions instead.
 
-### AI analyzer hook
+### LLM provider hook
 
-- Optional `ai_analyzer:` callable receives `(text, context)` and returns a
+- Optional `llm_provider:` callable receives `(text, context)` and returns a
   Hash or a schema-model object implementing `deep_to_h`/`to_h`. Findings
   can add a violation but cannot clear a deterministic one. Boolean fields
   must be actual `true`/`false` values; non-finite risk scores are ignored
   rather than crashing. Exceptions and malformed responses are bounded under
-  `result[:ai_analysis][:error]` and handled per `ai_failure_mode`.
-- Optional `Integrations::OpenAIAnalyzer` connector for the official OpenAI
-  Ruby SDK: sends a strict `OpenAI::BaseModel` schema through the Responses
-  API, consumes the parsed schema-model result, defaults to `store: false`,
-  and has no model allowlist — it forwards any String/Symbol model
-  identifier and relies on Structured Outputs support as the compatibility
-  check. Refusals, API failures, and missing parsed output degrade into the
-  same `result[:ai_analysis][:error]` path. The `openai` gem is optional and
-  loaded lazily.
+  `result[:llm_analysis][:error]` and handled per `llm_failure_mode`.
+- Provider transport is application-owned. The gem has no vendor SDK adapters,
+  endpoint assumptions, model allowlists, or model-specific parameters.
+  A framework-free local HTTP example demonstrates an open-source-first
+  classifier boundary using only Ruby standard-library HTTP and JSON support.
 
 ### Notifications
 
 - Vendor-neutral `Notifier` dispatches one sanitized, deeply frozen,
   versioned event to named callable handlers. Handlers run synchronously and
   independently — one failure doesn't stop the others, and errors are
-  returned per handler rather than raised. Input previews, AI reasons,
+  returned per handler rather than raised. Input previews, LLM reasons,
   metadata keys/values, and handler errors are bounded and redacted with the
   policy's restricted-content rules and the built-in PII/secret detectors.
+- Notification events expose optional provider reasoning as `llm_reason`;
+  the pre-release `ai_reason` field is not retained.
 
 ### Rails integration
 
@@ -103,15 +123,23 @@ Initial public release.
 - `Rails::ActiveJobHandler` enqueues sanitized notification events through
   any Active Job backend, resolving a reload-safe String/Symbol job
   constant at delivery time.
+- The initial compatibility window covers Rails 8.0 and 8.1. Only listed Rails
+  series are tested and supported; subsequent gem releases may remove a series
+  after its upstream security support ends.
 
 ### Quality and security posture
 
-- No runtime dependencies for the core checks; Rails and the OpenAI SDK are
-  both optional and loaded only when used.
-- CI enforces RuboCop, a Flog structural-complexity gate (max 10 per
-  ordinary method, 60 per class/module, with documented DSL exemptions
-  only), and a RubyCritic maintainability gate, alongside the Appraisal
-  matrix across Rails 7.2, 8.0, and 8.1.
+- The core has one lightweight runtime dependency, Ruby's `base64` bundled gem.
+  Rails remains optional and is loaded only when used.
+- CI enforces RuboCop — including calibrated structural-complexity cops
+  (`Metrics/AbcSize`, `CyclomaticComplexity`, `PerceivedComplexity`,
+  `ClassLength`) in place of a separate complexity tool — and a RubyCritic
+  maintainability gate, alongside the Appraisal matrix across Rails 8.0
+  and 8.1.
+- Native RDoc covers every supported public class, module, constant, attribute,
+  and method. CI blocks undocumented additions to the explicit public API
+  manifest while leaving implementation-only constants outside the
+  compatibility contract.
 - Least-privilege, SHA-pinned CI actions; CodeQL and OpenSSF Scorecard
   scanning; a private vulnerability-reporting process (see
   [SECURITY.md](SECURITY.md)).

data/CODE_OF_CONDUCT.md

@@ -13,9 +13,7 @@ for everyone, regardless of background, identity, experience, or ability.
 - Respect privacy and confidentiality.
 - Focus disagreement on ideas, evidence, and project outcomes.
 
-Harassment, discrimination, threats, sexualized conduct, sustained disruption,
-doxing, or publication of another person's private information are not
-acceptable.
+Harassment, discrimination, threats, sexualized conduct, sustained disruption, doxing, or publication of another person's private information are not acceptable.
 
 ## Enforcement
 
@@ -24,5 +22,4 @@ or remove contributions, issue warnings, temporarily restrict participation, or
 permanently ban participants when necessary. Reports will be handled as
 confidentially as reasonably possible, with conflicts of interest recused.
 
-This policy applies in project spaces and when someone is publicly representing
-the project.
+This policy applies in project spaces and when someone is publicly representing the project.

data/CONTRIBUTING.md

@@ -4,19 +4,44 @@ Thank you for improving Olyx Guardrails.
 
 ## Development setup
 
+Detection logic (`lib/olyx/guardrails/pii/`, `secrets/`, `injection_detector.rb`,
+`policy*`, and friends) remains independent of Rails at gem runtime. The
+repository installs Rails as a development and test dependency so every
+contributor runs the integration tests from the same default bundle. Consuming
+applications that use only `require "olyx/guardrails"` do not load Rails.
+
+Prepare the complete development bundle:
+
 ```bash
 rbenv install
-bundle install
-bundle exec rake test
-COVERAGE=true bundle exec rake test
-bundle exec rubocop --cache false
-bundle exec ruby script/flog_gate.rb
-bundle exec rubycritic -f console -f json -p tmp/rubycritic
-ruby script/rubycritic_gate.rb tmp/rubycritic/report.json
-bundle exec appraisal install
+bin/setup
+```
+
+Run the complete pre-pull-request gate:
+
+```bash
+bin/ci
+```
+
+`bin/ci` runs coverage-enforced tests, documentation validation, public RDoc
+coverage, RuboCop, RubyCritic, and the strict per-file quality gate. Individual
+tests remain runnable through `bundle exec ruby -Itest path/to/test_file.rb`.
+CI separately refreshes the Ruby advisory database and audits the committed
+dependency lockfile. This network-backed check stays outside `bin/ci` so the
+local quality gate remains reproducible offline after setup.
+
+### Rails adapter changes
+
+```bash
 bundle exec appraisal rake test
 ```
 
+Run this in addition to the above only when the change touches
+`lib/olyx/guardrails/rails/`, `lib/generators/`, or their tests. The Appraisal
+matrix covers Rails 8.0 and 8.1; Rails integration changes must pass every
+configured line while the standalone core remains free of Rails runtime
+dependencies.
+
 Ruby 3.4 or newer is supported. Changes must remain compatible with the oldest
 supported Ruby unless the same pull request deliberately changes the gem's
 requirement.
@@ -31,27 +56,71 @@ address genuine responsibility or clarity problems, but do not introduce proxy
 methods, unnecessary indirection, or metaprogramming merely to silence a
 heuristic.
 
-Flog is also a blocking structural gate: ordinary methods must score at most
-10, and each class or module must total at most 60. Do not split cohesive code,
-hide behavior behind dynamic dispatch, or weaken a public API merely to improve
-a score. A public DSL or metaprogramming macro may be listed in
-`.flog_exemptions.yml` only when it is the clearest design; the entry must use
-Flog's fully-qualified method name and contain an explicit DSL/metaprogramming
-reason. Stale or unexplained exemptions fail CI.
+RuboCop's `Metrics/AbcSize` (max 10), `Metrics/CyclomaticComplexity` (max 7),
+`Metrics/PerceivedComplexity` (max 7), and `Metrics/ClassLength` (max 60 lines)
+are the blocking structural-complexity gate, calibrated against this
+codebase's measured distribution rather than RuboCop's looser defaults. Do not
+split cohesive code, hide behavior behind dynamic dispatch, or weaken a public
+API merely to improve a score. A public DSL or metaprogramming macro that
+genuinely needs more room is a `# rubocop:disable` with an inline reason, or a
+file-level exclude in `.rubocop.yml` with a comment explaining the constraint
+— reviewed like any other exception, not a separate exemption file.
+
+## Documentation
+
+Public documentation follows the same contract discipline as production code:
+
+- write simple, declarative sentences in the present tense;
+- keep the README focused on the shortest correct integration;
+- place task-oriented explanations in the appropriate guide;
+- keep signatures, defaults, return shapes, and exceptions in `docs/API.md`;
+- use complete, copyable examples with synthetic data;
+- link to one canonical explanation instead of duplicating it; and
+- update documentation and tests in the same change as public behavior.
 
-The Appraisal matrix covers Rails 7.2, 8.0, and 8.1. Rails integration changes
-must pass every configured Rails line while the standalone core remains free of
-Rails runtime dependencies.
+Run `ruby script/documentation_gate.rb` after changing Markdown. The gate checks
+local files and heading anchors. CI also syntax-checks every Ruby example.
+
+Public code comments use native RDoc conventions and the same concise,
+declarative style. Document behavior, accepted arguments, return values,
+exceptions, security boundaries, and non-obvious edge cases. Do not narrate
+implementation mechanics or repeat the method name. Add supported source files
+to the RDoc whitelist in `olyx-guardrails.gemspec`; implementation-only
+constants remain outside that manifest and are not compatibility commitments.
 
 ## Pull requests
 
-1. Open an issue first for substantial API or policy changes.
-2. Keep each pull request focused and include tests for behavior changes.
-3. Add adversarial regression tests for security-sensitive fixes.
+Contributions follow the same fork-and-pull-request workflow used by established
+open-source projects:
+
+1. Open an issue first for substantial API, policy, or architectural changes.
+   Small fixes may go directly to a pull request.
+2. Fork the repository and create a focused branch from the latest `master`.
+   Do not work directly on `master`.
+3. Add tests for behavior changes and adversarial regression tests for
+   security-sensitive fixes.
 4. Update README, API reference, examples, and changelog when public behavior
    changes.
-5. Confirm tests, RuboCop, Flog, RubyCritic, syntax checks, and gem packaging
-   pass locally.
+5. Run `bin/ci` locally, plus the Appraisal Rails matrix when the change touches
+   `lib/olyx/guardrails/rails/` or `lib/generators/`.
+6. Open a draft pull request early when maintainer feedback would prevent
+   rework. Mark it ready only when its description and validation checklist are
+   complete.
+
+Pull requests run with read-only GitHub token permissions, including
+contributions from forks. CI never requires repository secrets. The protected
+default branch requires the supported Ruby and Rails matrix, dependency audit,
+quality gate, CodeQL analysis, resolved review conversations, and maintainer
+approval. Maintainers squash approved pull requests, and GitHub deletes the
+source branch after merge.
+
+Maintainers may ask for a pull request to be split when unrelated behavior,
+refactoring, or generated dependency changes make review unsafe. Force-pushing
+a contributor branch is acceptable while responding to review; GitHub
+dismisses stale approvals when the protected branch changes.
+
+Maintainer releases follow [docs/RELEASING.md](docs/RELEASING.md). Do not
+publish an artifact that has not completed that runbook.
 
 Never include real credentials, personal data, production endpoints, or
 customer content in fixtures. Use clearly synthetic values.