Lista Firme Bundle Laravel Package

Technical Evaluation

Architecture fit

• stevro/ListaFirme is a thin domain adapter: CIF/CUI validation plus company lookups against ANAF (Romanian tax authority). It is not an architectural pillar — it should sit behind an application-owned port (e.g. CompanyRegistry::validate(), CompanyRegistry::lookup()), with the package bound in a service provider. That keeps vendor semantics out of domain code and makes the dependency swappable.
• Fit is good for a Laravel monolith or modular monolith handling merchant/partner onboarding, KYC-adjacent checks, or invoice-entity validation. Poor fit if we need multi-country coverage — this is Romania-specific and will need a sibling adapter per jurisdiction.
• v4.1's "multiple fallbacks to CIF checkers" is architecturally significant: the package now internally chains validation strategies. That is convenience, but it also means the package — not our code — decides which source of truth wins. We should confirm the precedence order is configurable, otherwise we inherit an opaque resolution policy.

Integration feasibility

• Low effort. Composer install, publish config, optional facade. A developer-day or two to wrap in an adapter with contract tests.
• The fallback work materially reduces integration risk: single-source dependencies on ANAF availability are the main reason these packages break in production, and redundancy is the right fix.
• Main feasibility unknown is the outbound footprint: N fallback checkers implies up to N HTTP calls per validation. That changes timeout budgeting, queue design, and rate-limit posture versus a single call.

Technical risk

• Upstream contract drift (highest). "Upgraded ANAF checker to v8" pins us to a specific ANAF web-service contract. If ANAF's current published version is v9, v8 is a lagging target and could be deprecated or silently return degraded/partial payloads. Must be verified against ANAF's current documentation before adoption — treat as a blocking question, not a note.
• Semantic ambiguity from fallbacks. An offline checksum check and an authoritative ANAF lookup answer different questions ("well-formed" vs "registered and active"). If the fallback chain returns a single boolean, we cannot tell which one fired. That is a correctness risk for onboarding decisions and an audit risk if status is ever challenged.
• Silent degradation. Fallbacks typically fail soft. Without instrumentation we will not know we have been running on a secondary checker for weeks. Needs explicit telemetry per checker.
• Evidence gaps. No prior assessment and only changelog text available: no confirmed PHP/Laravel version matrix, test coverage, license, release cadence, or maintainer depth. The package appears single-maintainer, which is the dominant long-term risk for a tax-authority-coupled dependency.
• Minor-version surface area. 4.0 → 4.1 is a minor bump with no stated breaking changes, but fallback additions commonly introduce new config keys, env vars, and changed return shapes for edge cases. Verify, do not assume.

Key questions

1. What is the fallback precedence order, is it configurable, and can we observe which checker produced a given result?
2. Does the ANAF v8 upgrade cover the currently published ANAF contract, or are we knowingly behind?
3. What are the declared PHP/Laravel constraints, test coverage, and license?
4. What is the per-validation worst-case latency and outbound call count with all fallbacks engaged?
5. Does the package distinguish "invalid format" from "valid format, not found / inactive" in its return contract?
6. Is the maintainer responsive to ANAF contract changes, and what is our fork/patch plan if not?

Integration Approach

Stack fit

• Verify composer.json against our runtime before committing: PHP version floor and Laravel support range are the usual friction points for packages of this vintage. If we run the current Laravel major, confirm it is explicitly supported rather than incidentally working.
• Confirm the HTTP client usage — if the package hard-codes Guzzle options, we need to know whether it respects our proxy, retry, and timeout conventions.

Migration path

• Greenfield for us (no prior assessment, no incumbent). Adopt at 4.1 rather than 4.0 — the fallback work is exactly the reliability hardening we would otherwise build ourselves.
• If any team already pulls 4.0 transitively, the 4.0 → 4.1 step is a routine composer update with no stated breaking changes, but re-run the CIF validation regression suite: fallback ordering changes outcomes, not just reliability.

Compatibility

• Diff the published config between 4.0 and 4.1 for new keys (checker selection, per-checker timeouts, ANAF endpoint URL). New required env vars are the most common cause of "works locally, silent failure in staging."
• Check whether the fallback chain issues calls serially. If so, worst-case validation latency is additive and may breach web-request or queue-worker timeouts.
• Validate the ANAF v8 request/response contract against a small real sample set in staging before trusting it — schema-level compatibility will not surface in unit tests.

Sequencing

1. Pin 4.1 behind the CompanyRegistry port; no direct package usage in domain or controller code.
2. Write contract tests against a recorded fixture set covering: valid CIF, well-formed but unregistered CIF, inactive/deregistered company, ANAF timeout, all-checkers-failed.
3. Instrument per-checker outcome (which checker fired, latency, failure reason) and emit to existing observability.
4. Introduce caching in the adapter layer — company registry data changes on the order of days, not seconds. Cache-aside with explicit TTL and a manual invalidation path.
5. Roll out behind a feature flag; shadow-run against the current process (or manual checks) to compare verdicts before it gates any real onboarding decision.
6. Only then move bulk/backfill validation to queued jobs with rate limiting toward ANAF.

Operational Impact

Maintenance

• Ongoing maintenance is upstream-driven: ANAF changes its contract, the package must follow, and we must upgrade. Budget for one or two forced upgrades per year and track the repo's release feed.
• Single-maintainer concentration is the real exposure. Mitigation: keep the adapter port thin so a fork, a direct ANAF client, or a commercial registry API are all plausible swap-ins within days, not weeks.

Support

• No vendor SLA. Support path is the upstream issue tracker plus our own adapter layer. Do not let this package become load-bearing for a revenue-critical flow without an internal owner and a documented fallback procedure (manual registry lookup) for full outage.
• Fallbacks improve availability but shift the support question from "is ANAF up?" to "which checker answered, and do we trust it?" — that needs to be answerable from logs.

Scaling

• Cost per validation scales with fallback depth. At volume, a serial multi-checker chain is the dominant latency and rate-limit cost. Cache aggressively, batch where the workflow allows, and reserve full-chain validation for first-time or low-confidence cases.
• Outbound rate limits toward ANAF are the hard ceiling; per-checker circuit breakers should short-circuit the chain when a source is known-down rather than paying its timeout on every call.

Failure modes

• All checkers fail: confirm the package throws rather than returning false. A silent false maps a valid company to "rejected" and blocks legitimate onboarding — the worst failure mode here.
• Weak-checker fallback: a checksum-only pass reports "valid" for a company that is not registered or is inactive. Must not be treated as equivalent to an authoritative pass in downstream decisions.
• Stale cache: company status changes (deregistration, inactivity) will be masked until TTL expiry. Define TTL by risk tolerance of the consuming workflow, not by convenience.
• Contract drift: ANAF v8 becomes unsupported and responses degrade to empty-but-200. Detect via payload shape validation, not just HTTP status.
• Timeout stacking: full chain exceeds request budget under partial ANAF degradation — a partial outage becomes a total one. Enforce an overall deadline.

Ramp-up

• Low for a Laravel developer: hours to integrate, half a day to read the port and adapter.
• Non-trivial for the domain: CIF checksum rules, the distinction between format validity and registry status, and the fallback precedence need written internal documentation. Without it, the first incident will be debugged by whoever happens to know Romanian tax semantics.
• Recommend a short written runbook covering: what each checker means, expected verdicts for the fixture set, how to force a cache refresh, and how to fall back to manual registry lookup.