Iss Satellite Laravel Package

Technical Evaluation

Architecture fit

• Repo confirmed as appnave/nave-satellite-iss. The nave prefix reframes the earlier read: this is not a general-purpose tax library, it is an extracted module of the vendor's Nave platform. "Satellite" now reads as "peripheral service of our platform," which makes the package a fragment of someone else's application architecture rather than a self-contained adapter.
• v0.2.4 adds "Mega queries for Distrato/AVRA flow." Distrato (contract rescission) and AVRA are named business flows, not tax primitives. A tax library should not need to know what a distrato is. This is the strongest signal yet that the package is coupled to the vendor's domain model and data.
• "Mega queries" implies a query/reporting layer — Eloquent builders, raw SQL, or views — over tables the package likely does not own. That moves architecture fit from "conditional, isolate behind a port" toward "does not fit as a dependency; at best a source of rules and reference SQL."
• Fit remains conditional on our being in the Brazilian real-estate service-tax domain, but the bar has risen: it now also requires that we share the vendor's distrato/AVRA data shape.

Integration feasibility

• Mechanics unchanged: Composer-installable, MIT, standard Laravel package skeleton. Trivial to install, and installation tells us nothing.
• The new surface is data, not code. Feasibility now depends on whether the queries reference vendor-internal tables, views, or columns. If they do, adoption implies either replicating the vendor's schema or rewriting every query — in which case the package's value collapses to its SQL as documentation.
• Still zero dependents, zero external evidence of operation outside the author's stack.
• Version is v0.2.x: pre-1.0 semver. Anything may change in any release, including the shape of queries and the tax rules they encode.

Technical risk

• Remains High, and the vector has shifted. Previously the risk was documentation and ownership; it is now also data coupling and query performance.
• Schema coupling is confirmed as plausible rather than hypothetical. A release whose headline feature is queries is a release that reads our database (or expects one shaped like theirs).
• Performance risk is now explicit in the release title. "Mega queries" is the maintainer's own word. Unbounded joins, missing pagination, or full scans sit in our request path if invoked synchronously.
• Bus factor improves marginally: a second contributor (@noemimpimentel) appears. One drive-by contribution on a 0.x package is not a support commitment, but it is evidence the project is not abandoned.
• Documentation risk unchanged. "Mega queries" is the entire description of the feature; there is no doc, no migration note, no explanation of what Distrato/AVRA mean in package terms.
• Domain-liability risk increased. Distrato flows involve ISS on cancelled or refunded contracts — retention, refund, and reclassification rules. Hardcoded, unmaintained logic there is a compliance exposure, not a code-quality issue.
• The future-dated release metadata flagged previously is not resolved by this release and should still be verified.

Key questions

• Do the new queries read tables we own, tables the vendor owns, or tables that must exist for the package to work? This single answer determines whether the spike is one day or one week.
• Are the queries parameterized and scoped, or do they assume a specific schema, column naming, and row volume?
• Does the Distrato/AVRA flow encode tax rules (which change and which we must own) or only reporting shape (which we can ignore)?
• What does AVRA stand for inside the vendor's platform, and is the concept ours at all?
• Does v0.2.4 change any existing behavior, or is it purely additive? The changelog says "Add," but 0.x additivity should not be assumed.
• Same open questions as before: Laravel/PHP constraints, migrations shipped, outbound HTTP calls, global middleware, config defaults.
• Who owns this at the vendor, and is there any commitment to semver or security response?

Integration Approach

Stack fit

• Unchanged mechanically: auto-discovered Laravel package, clean fit in a monolith or modular monolith.
• New constraint: the package now plausibly requires read access to data outside its own tables. That is fine in a shared-schema monolith and unacceptable across service boundaries. In a service-oriented estate this argues more strongly for reimplementation — a tax calculator should be a function call, not a query against someone else's schema.
• If we are not in the Brazilian municipal-tax domain, fit remains zero and the release changes nothing.

Migration path

• The recommendation hardens: do not adopt as a dependency. Spike, extract the rules and any useful SQL as reference, and reimplement behind our own interface.
• Spike scope grows from "read the source" to "read the source and map the data model." Budget 2–3 days rather than 1–2. Concretely: enumerate every table and column the queries touch, and confirm whether we have them.
• If the spike reveals that the Distrato/AVRA queries encode genuinely non-trivial tax treatment we cannot derive independently, reconsider — but only as a wrapped, pinned, feature-flagged dependency, never in the domain layer.
• Pin exact versions (no caret) if we depend at all. At 0.x, a caret range is effectively an unbounded dependency.

Compatibility

• New dimension: database compatibility. Confirm the queries run on our engine and version, not just MySQL-default syntax. Check for vendor-specific functions, window functions, CTEs, and collation assumptions.
• Confirm whether the package ships migrations or expects tables to pre-exist. The latter is worse — implicit schema ownership with no setup path.
• Existing checks still apply: require/require-dev against our support matrix, config namespace and facade alias collisions, hidden assumptions about queue driver, cache store, HTTP client.

Sequencing

1. Diff v0.2.3 → v0.2.4 and read the new query code first. It is the highest-information artifact in the repo.
2. Source, license, and transitive dependency audit — unchanged.
3. New gate: data-model review. List required tables, columns, and expected volumes. If we do not have the schema and will not create it, stop; the package is out.
4. Sandbox spike on a scratch app matching production PHP/Laravel/database versions.
5. Contract tests against observed behavior, including output for a distrato case.
6. Decision gate: reimplement (default) or wrap.
7. If wrap: own IssCalculator/IssClient port, package as sole adapter, feature-flag, shadow-run against the current process.
8. Cutover last, after parallel-run agreement on a representative invoice sample, explicitly including cancelled/distrato contracts.

Operational Impact

Maintenance

• Still effectively ours, and the burden just grew. Owning a fork now means owning queries as well as rules — and queries against a schema that will drift from the vendor's as their platform evolves.
• The 0.x version line means upstream breakage is normal. Plan for a fork within 6–12 months, or skip the fork and reimplement now.
• Tax and distrato rules both need an owner and a review cadence. Distrato treatment is at least as volatile as tax rates.

Support

• No change: no community, no SLA, no advisory feed. Escalation is a named contact or nothing.
• The second contributor is a mild positive signal on project liveness, not a support channel. Do not treat it as one.
• Dependency inventory entry now needs a second review dimension: schema dependency and query ownership, alongside the existing named-owner and exit-plan fields.

Scaling

• This is the changed section. Previously scaling risk was "availability of an external service, if any." It is now also our own database: unbounded or heavy queries executing in our request path, on our primary, at our invoice volumes.
• Determine whether the queries are invoked per-invoice, per-batch, or per-report. Per-report at end-of-month is tolerable; per-invoice in the request path is not without measurement.
• If distrato queries join across large contract tables, test against production-scale row counts, not a seed dataset. "Mega" written by the author should be taken at face value until measured.

Failure modes

• Wrong numbers from a stale distrato rule set — highest severity, unchanged in kind, now broader in scope. Surfaces as a compliance finding, not an error.
• Schema drift — the vendor renames a column or reshapes a table; our pinned copy keeps working until it silently matches nothing and returns empty or null. Silent, insidious, and new with this release.
• Query performance regression on our database — lock contention or slow requests traced back to a package we do not control. New with this release.
• Silent config defaults diverging from our tax settings — unchanged, still highest-frequency.
• ServiceProvider boot failure after a Laravel upgrade — loud, easy to catch, low severity.
• Tag/branch divergence given the unresolved future-dated release — deploying something other than what was reviewed.

Ramp-up

• Low for installation, high for behavioral understanding. The release makes this worse: understanding the package now requires understanding the vendor's data model, which is undocumented by definition.
• Plan engineer time to read source and map schema. Capture the findings — rules, table dependencies, query shapes — in our wiki at spike time. This artifact is the deliverable; the dependency is not.
• Default recommendation is now firm: spike, then reimplement behind an interface. v0.2.4 moves the package from "unowned code" toward "unowned code with an implicit claim on our database," and the case for inheriting it has weakened, not strengthened.