Tracing Sdk Laravel Package

Technical Evaluation

Architecture fit

onematrix/tracing-sdk is not a Laravel package in the conventional sense — it is a framework-agnostic PHP client with a single, narrow responsibility: take a payload, canonicalize it (RFC 8785 JCS for JSON, W3C C14N for XML), hash it with Keccak-256, and POST the resulting record to an external Indexer service. Architecturally that makes it an outbound adapter, not a service layer. It slots in cleanly as an anti-corruption layer at the edge of a bounded context: your domain emits data, the SDK normalizes and fingerprints it, the Indexer stores it.

The fit is good if — and only if — you have a genuine data-integrity / tamper-evidence / provenance requirement (audit trails, regulatory attestation, chain-of-custody, document notarization). It is a poor fit as a general observability or tracing tool despite the name; there is no span model, no sampling, no context propagation. The package name is misleading and will cause scope confusion in stakeholder conversations — flag this early.

Secondary fit consideration: the SDK implies a hard runtime dependency on a separately operated Indexer. You are not adopting a library, you are adopting a two-party system. That is a product decision, not just a technical one.

Integration feasibility

Mechanically straightforward: composer require, construct a client with an endpoint + credentials, call a record-emitting method. Small surface area, low learning curve. The real feasibility questions are dependency and contract:

Technical risk

1. Supply chain / provenance (high). Zero stars, zero dependents, zero external validation. A single-maintainer package on the write path of your audit records is a concentrated risk. Pin to an exact commit SHA, vendor it, and review the code before it touches production.
2. Cryptographic correctness is unverifiable by inspection (high). If the canonicalization is subtly wrong, hashes are stable within your system but fail cross-implementation verification. You will not discover this until an auditor or a second-language verifier disagrees with you — the worst possible time.
3. Determinism edge cases (medium-high). Float serialization, Unicode escaping, key ordering with non-ASCII, empty containers, and duplicate keys. Each is a silent-failure class.
4. Synchronous external dependency (medium). If the SDK performs a blocking HTTP call inline, it inherits the Indexer's latency and availability. Must not sit on a user request path.
5. Data egress / PII (medium). You are shipping payloads to a third-party service. Canonicalization does not anonymize; hashing happens after the payload is constructed, and the payload itself is transmitted. Confirm exactly what leaves your boundary.
6. Immutability trap (medium). Once records are written, changing canonicalization rules invalidates every prior hash. This is effectively a schema you can never migrate.

Key questions for the maintainer

• Does the SDK bundle a Keccak implementation, or depend on one? Which, and what PHP extensions does it require?
• Does it pass the RFC 8785 reference test vectors? Are there conformance tests in the repo?
• Is the HTTP call blocking? Is there a transport interface I can swap or fake in tests?
• What is the retry / timeout / idempotency contract with the Indexer? Are records deduplicated server-side?
• Is there a batch endpoint, or one HTTP round-trip per record?
• What does the Indexer response contain (receipt, sequence number, proof)? Does the SDK surface it?
• What is the versioning and deprecation policy? Is 0.x API stable?
• What is the licensing and long-term maintenance commitment?

Integration Approach

Stack fit

Laravel 9–11 / PHP 8.1+. Because the package is framework-agnostic, conflict risk with existing dependencies is low except for the HTTP client and Keccak polyfill. Recommended placement:

Domain event / model observer
        ↓
IntegrityRecordBuilder (your code — owns payload shape)
        ↓
onematrix/tracing-sdk (canonicalize + hash)
        ↓
Queued Job (retries, backoff, DLQ)
        ↓
IndexerClient (wraps SDK transport, adds correlation IDs + metrics)

Wrap the SDK. Never call it from controllers, models, or Eloquent events directly. Bind it in a dedicated service provider with config from config/integrity.php and credentials in the secret store.

Migration path

Additive — there is nothing to migrate away from. Two caveats:

• If you already produce SHA-256 audit digests, do not attempt to convert them. Keccak-256 and SHA-256 are not interchangeable and there is no migration. Run a dual-write period with an explicit cutover date and a documented "records before date X use algorithm A" rule.
• If you already send records to a different integrity service, the canonicalization rules will differ. Re-hashing historical payloads will not reproduce prior hashes. Treat the cutover as a new epoch with an epoch identifier in the record envelope.

Compatibility

• Pin the exact version and commit; add to your dependency-review allowlist.
• Verify ext-gmp (or ext-bcmath) availability across your fleet and CI images — this is the most likely deployment surprise.
• Confirm the Guzzle/HttpClient constraint against your Laravel version before committing.
• Test on the oldest and newest PHP minor you support; polyfilled Keccak can be slow on older runtimes.

Sequencing

Do not skip Phase 1. The cost of discovering a canonicalization divergence in production is a full audit-record re-issuance, not a bug fix.

Operational Impact

Maintenance

You are taking on ownership of a dependency nobody else uses. Budget for: quarterly review of upstream commits (there may be none), a vendored fork if the maintainer disappears, and internal documentation of the canonicalization contract because upstream docs are likely thin. Realistically, plan for the possibility that you will own this code within 12 months — factor that into the build-vs-buy comparison. The SDK's actual logic is a few hundred lines; a first-party implementation is a credible alternative and removes the supply-chain question entirely.

Support

No community, no SLA, no Stack Overflow corpus, no CVE history (nothing to have CVEs in yet — which is not the same as being secure). Support is entirely internal. Name a technical owner before Phase 3, not after.

Scaling

Cost is dominated by two things: canonicalization CPU (JSON tree rebuild + sort; XML DOM parse) and Keccak throughput. Pure-PHP Keccak is roughly an order of magnitude slower than the C extension. Model it:

• At 100 records/sec, per-record canonicalize+hash should stay in the low single-digit milliseconds — fine.
• At 5,000 records/sec, you need batching, dedicated queue workers sized for CPU (not I/O), and horizontal scale on the emit tier.
• One HTTP round-trip per record will not scale past low hundreds/sec — confirm a batch endpoint exists, or aggregate client-side.
• The Indexer becomes a hard capacity ceiling. Negotiate its rate limits before Phase 4, and confirm whether it is self-hosted (then it is your on-call problem too) or vendor-operated (then it is a third-party SLA you must contract).

Failure modes

Ramp-up

Low for the API — a mid-level engineer is productive in half a day. Moderate for the semantics: engineers must understand why canonicalization exists, why Keccak ≠ SHA-3, why you cannot change the payload shape without invalidating history, and why the hash must never be computed on data that has already been transformed. That is a 1-hour team session plus a short ADR, and it should be mandatory before anyone touches the emit path.

Bottom line for a go/no-go: the technical integration is cheap; the trust investment is not. Gate on Phase 1 hash verification and a named owner. If either fails, build the ~300 lines in-house — you will get equivalent function, no supply-chain exposure, and full control over the one thing that actually matters here: the canonicalization contract.