Schema Laravel Package

Technical Evaluation

Architecture fit. gosuperscript/axiom is a PHP rules/expression-evaluation library (the terminology in this release — "presence" vs "equality" overloads, operator resolution ordering — describes a parser/evaluator that resolves operator semantics at expression-compile or evaluation time). For a Laravel codebase it fits the "business rules as data" slot: eligibility checks, pricing/discount conditions, feature gating, workflow guards, validation logic that product wants to change without a deploy. It is a library, not a Laravel-native package: expect to wire the service provider, config, and any cast/validation integration yourself unless upstream ships a Laravel bridge. Fit is good where you have many small, frequently changing predicates; poor where you have a handful of static conditionals that plain PHP expresses more clearly.

Integration feasibility. Low-to-moderate effort. A single class or facade call plus a rule source (config array, DB column, or file) gets you a working proof of concept. The real cost is not the wiring — it is building the guardrails: schema/contract for rule expressions, a place to store them, an authoring surface for non-engineers, and a test harness that pins expected outcomes per rule. Budget for that, not for the glue code.

Technical risk.

• Pre-1.0 API instability. At v0.6.x the public API is explicitly not frozen. Minor bumps may rename classes, change the expression grammar, or alter evaluation semantics without a major-version signal. Pin exactly and upgrade deliberately.
• This release is behavior-affecting despite being a patch. Reordering resolution so presence operators are evaluated before equality overloads changes which operator wins when an expression could be read either way. Fixing an incorrect precedence is the right call, but any stored rule that was written against the old, wrong precedence may now evaluate differently — silently. Treat this as a semantic change requiring regression testing of existing rule corpora, not a drop-in patch.
• Correctness is the whole product. A rule engine that mis-evaluates is worse than hardcoded logic because it fails quietly and at business-logic level. Precedence fixes landing in patch releases are a signal that the grammar is still being stabilized.
• Bus factor / provenance. Single-maintainer project (@robertvansteen) under an unfamiliar vendor namespace. Verify license, repo activity, issue responsiveness, and whether security disclosures have a channel before this carries revenue-affecting logic.

Key questions.

1. Is there a documented grammar/precedence table, and did this release change documented behavior or only correct an undocumented bug?
2. Which of our stored expressions, if any, contain both a presence check and an equality comparison on the same operand? Those are the at-risk rules.
3. What is the 1.0 timeline, and is there a stated backward-compatibility policy for 0.x?
4. Does an official Laravel integration (service provider, config publish, validation rule, Blade/JSON casting) exist, or is it DIY?
5. What is the failure behavior on unparseable or partially resolvable expressions — throw, default-true, default-false? Default-true is unacceptable for gating logic.
6. Can rule expressions be evaluated in isolation with a pinned evaluator version, so we can A/B old vs. new semantics before rollout?

Integration Approach

Stack fit. Framework-agnostic PHP library, so Laravel fit is whatever we build around it. Recommended shape: a thin internal wrapper service (RuleEvaluator) that owns the axiom dependency, exposes a single evaluate(string $rule, array $context): bool, and is the only place the third-party API appears. Everything else in the app — controllers, jobs, models — depends on our wrapper. This contains upgrade blast radius to one file and one test suite, which is the correct posture for a 0.x dependency. Bind via a service provider, drive the rule source from config or an Eloquent model, and cache compiled rules if compilation is non-trivial.

Migration path. Do not migrate existing conditionals wholesale. Start greenfield: pick one rules-heavy, low-risk surface (e.g., promotional eligibility or notification routing) and implement it in axiom behind the wrapper. Keep the existing PHP logic in place as the reference implementation and run both in shadow mode on production traffic, logging divergences. Only cut over for that one surface once divergence is zero for a full cycle. Legacy conditionals outside that surface stay untouched — no rewrite mandate.

Compatibility. Pin to an exact patch (v0.6.10), not a caret range. Confirm PHP version support against our runtime and Laravel version constraints before anything else; a 0.x library's composer.json is often narrow. Check for conflicting global state (error handlers, custom autoloaders, static caches) — common in expression libraries and a frequent source of "works in isolation, breaks in the app" issues. Verify behavior under Octane/long-running workers if we use them: static evaluator state and memoized rules must be request-safe.

Sequencing.

1. Spike (1–2 days): install pinned v0.6.10, write the wrapper, express 10 real production rules, compare against current PHP logic in tests.
2. Decide: proceed, or stop and keep conditionals in code. This is a genuine off-ramp — write the decision down.
3. Build guardrails: expression schema/lint, rule storage + versioning, per-rule fixture tests pinning expected outcomes.
4. Adopt v0.6.10 fresh for all new rules. Do not retrofit existing rules onto it during the spike.
5. Shadow-mode one surface in production, log divergences, cut over at zero divergence.
6. Establish an upgrade ritual: each axiom release triggers a rule-corpus regression run before merge. v0.6.10 is the first case — if we already have stored rules, re-run the corpus against it and diff.

Operational Impact

Maintenance. Low code churn, meaningful ongoing discipline. Two recurring costs: (a) upgrade evaluation — every release, including patches like this one, must be run against the full rule corpus because 0.x patch releases can change evaluation semantics; (b) rule hygiene — expressions accumulate, drift, and outlive the business logic they encode. Without ownership and a deprecation path for stale rules, the rule store becomes an unreadable second codebase. Assign a named owner for the rule store, and require every rule to carry an owner, a purpose, and a review date.

Support. Support burden shifts from engineering to whoever authors rules. If product/ops can write expressions, they will write both valid-but-wrong rules and rules that parse but mean something unintended — and precedence subtleties (exactly the class of bug this release fixed) are not something a non-engineer will reason about correctly. Mitigation: a linter, a rule-preview/dry-run tool that shows evaluated output against sample contexts, and mandatory review before a rule goes live. Budget for building those; they are not optional if non-engineers touch expressions. Upstream support is a single maintainer with no SLA — assume we are on our own for triage and be prepared to vendor a fork if a blocking bug lands.

Scaling. Evaluation is in-process and CPU-bound; cost scales with rule count × context size × evaluation frequency, not with user count. Three concerns: hot-path evaluation on every request (cache compiled rules; memoize per-request results), unbounded expression complexity (cap depth/length at authoring time — a pathological rule is a self-inflicted DoS), and context assembly (fetching every field a rule might reference is often more expensive than evaluation itself; use lazy context resolution). For batch workloads, rules evaluated across large record sets need per-batch timing, since a slow rule multiplies by row count.

Failure modes.

• Silent semantic drift (highest severity): rules evaluate differently after an upgrade, no error raised, business logic quietly wrong. Detection: pinned fixtures + corpus regression per upgrade. This is the failure mode v0.6.10 introduces.
• Fail-open on error: unparseable or unresolvable expression returns true/allowed. Unacceptable for gating, discount, and entitlement logic — force fail-closed with loud logging, and alert on parse errors as a first-class signal.
• Precedence ambiguity: authors writing expressions whose meaning depends on resolution order. Detection: reject ambiguous expressions at lint time; require explicit parentheses.
• Single-maintainer abandonment: upstream stops shipping. Mitigation: wrapper isolation means we can fork or replace the evaluator without touching call sites — the wrapper is the insurance policy, which is the main reason to insist on it.
• Context shape mismatch: rule references a field not present in the supplied context, evaluating to null-presence rather than erroring. Validate context against a declared shape before evaluation.

Ramp-up. Engineering ramp is short — half a day to a working prototype. Organizational ramp is the long pole: 2–4 weeks to establish authoring conventions, the lint/preview tooling, the fixture-testing habit, and the upgrade ritual, assuming one engineer owns it. Sequence the shadow-mode pilot in parallel with tooling so the guardrails are proven against real rules before the second team adopts. Do not open rule authoring to non-engineers until lint, preview, and review are all in place — the first bad rule that ships silently will cost more trust than the tooling costs to build.