Prism Laravel Package

Technical Evaluation

Architecture fit: Prism is a Laravel/PHP LLM integration package; StreamCollector is a public streaming utility that aggregates stream events into messages. For a TPM, the architectural relevance is not the class itself but what this release reveals about the package's release contract: a public class was removed in v0.132.0 with no mention in the release notes, breaking a known downstream consumer (prism-harness 0.13.0) on a routine composer update. v0.133.1 restores the class with an identical constructor, collect() and callback signature, so it is a drop-in restoration — but the underlying event shape has changed.

Integration feasibility: Straightforward. The restored class builds messages via StreamedMessages, so output now follows the current stream shape (one StepFinishEvent per step, one StreamEndEvent) and preserves per-step replay metadata. The vendor validated against a real consumer (prism-harness's own suite passes). No breaking changes are claimed in this release, and StreamCollector was the only public class removed since v0.131.0.

Technical risk: Moderate, and mostly process-driven rather than code-driven:

• The package is on 0.x, so SemVer gives no compatibility guarantees; silent removal of public API is a demonstrated failure mode, not a hypothetical.
• StreamCollector is now deprecated in favour of StreamedMessages::fromEvents(). Deprecation implies eventual removal, and no target version or timeline is stated.
• The restoration preserves the signature but not necessarily the output semantics for consumers that assumed a single terminal event — event cardinality per step has changed.

Key questions:

1. What release will remove StreamCollector, and will that removal be announced in the release notes and changelog?
2. Is the deprecation surfaced at runtime (e.g. trigger_error/E_USER_DEPRECATED) or only in PHPDoc? This determines whether we can detect usage in CI.
3. Is StreamedMessages::fromEvents() a strict behavioural equivalent for callback invocation order and per-step metadata, or are there edge cases?
4. Why did the upstream merge (PR #1043) bypass a public-API diff check? Is a changelog/BC-check gate now in place?
5. What is the supported version range and PHP/Laravel matrix for 0.133.x?

Integration Approach

Stack fit: Native Composer dependency in a Laravel application. No infrastructure change; the risk is entirely in dependency version management and stream-event consumption code.

Migration path: Two-track.

• Short term: pin to 0.133.1 with a caret constraint bounded below the next minor (~0.133.1 rather than ^0.133), commit the lock file, and avoid unconstrained composer update in CI. This directly closes the failure that hit prism-harness.
• Medium term: migrate call sites from StreamCollector to StreamedMessages::fromEvents(). The restoration gives us a safe window to do this deliberately rather than reactively.

Compatibility: Verified against prism-harness 0.13.0, which is a meaningful independent signal. Constructor, collect() and callback signatures are unchanged, so existing code compiles and runs without modification. Behavioural compatibility of the emitted event stream should be asserted, not assumed.

Sequencing:

1. Pin and lock 0.133.1; confirm CI is green on streaming tests.
2. Add a contract test asserting event shape (one StepFinishEvent per step, one StreamEndEvent) and replay-metadata presence.
3. Introduce a thin internal adapter/facade over StreamCollector so call sites are not coupled to the deprecated symbol.
4. Add a CI check for deprecation notices and a public-API diff against upstream tags to catch the next silent removal.
5. Migrate adapter internals to StreamedMessages::fromEvents(); delete the adapter when the class is removed.

Operational Impact

Maintenance: Low ongoing effort, but real deprecation debt. Budget a small, scheduled task to retire StreamCollector usage; treating it as "fixed forever" is the trap, since the deprecation is explicit and the package is pre-1.0.

Support: Vendor responsiveness is good — the class was restored within a release cycle and validated against a consumer with a regression suite. The concerning signal is the release-notes gap on v0.132.0, which turns routine dependency hygiene into an incident. Escalate as a process question, not a code question; ask for a published changelog policy and a BC-check gate before we deepen dependency.

Scaling: StreamCollector buffers collected messages per stream. Long-running or high-token streams increase memory proportional to accumulated events; per-step replay metadata adds further retained state now that each step emits its own StepFinishEvent. Validate memory behaviour on our largest expected stream before enabling in high-concurrency paths.

Failure modes:

• Silent API removal on composer update — Class "Prism\Prism\Streaming\StreamCollector" not found at runtime. Highest-impact, lowest-visibility failure; mitigated by pinning plus a lock-file policy.
• Event-cardinality assumptions — consumers expecting one terminal event per stream may double-count or truncate now that each step emits a finish event.
• Deprecation removal without notice — repeated behaviour pattern; treat the next minor bump as presumptively risky.
• Loss of replay metadata — regression risk if internal wrapping drops step metadata before our adapter sees it; covered by the contract test.

Ramp-up: Low. Single class, small surface (constructor, collect(), one callback), existing documentation and a validated consumer to reference. An engineer familiar with Laravel service providers and event streams can integrate in well under a day; the contract test and adapter are the only non-trivial additions.