Prism Harness Laravel Package

Technical Evaluation

The v0.15.0 release adds a host-controlled CallCostObserver extension point for capped model calls. This is a meaningful architectural addition but not a breaking change.

• Architecture fit: Fits Laravel’s service-container and config model. A host can implement Prism\Harness\Contracts\CallCostObserver, register it via RunContext::root(..., observer: $observer) or the RunContext constructor, or fall back to prism-harness.cost_observer. This supports multi-worker deployments where spend must be tracked across processes.
• Integration feasibility: High. The contract has two methods: reserving() runs after harness admission/reservation but before the provider request; settled() runs once per admitted call. Throwing from reserving() refuses the call before any request, releases the reservation without charge, skips settled(), and fails the run with RunNotPermitted. CallRefused('your_code') lets the host choose a stable refusal code.
• Technical risk: Moderate. The observer is trusted host code and the harness does not meter what it does. The host owns persistence. A worker that dies between reserving() and settled() leaves an open reservation that the host must expire. settled() fires exactly once even for failed calls and stopped streams, but if settled() throws, the harness settlement still stands and the exception propagates. An observer attached to an uncapped run is refused with budget_observer_uncapped, so every observed run needs a cap, even a large one.
• Key questions: Where will reservations and settlements be persisted? What TTL and reconciliation process will expire orphaned reservations? How will the host ledger reconcile worstCaseUsd, chargedUsd, and usageKnown? Which run trees must carry a cap and observer? How will custom CallRefused codes be governed and documented? What alerting is needed for observer exceptions and open reservations? Does the team understand that children inherit the observer and a run tree cannot drop or replace it once chosen?

Integration Approach

• Stack fit: Strong for Laravel/PHP applications already using Prism Harness with queued workers. The observer can be container-resolved, injected per root run, or configured globally. Coverage includes send, sendStructured, stream, and approve/deny/decide continuations on the capped path.
• Migration path: Low-friction. Release notes state no breaking changes. Existing runs continue to work without an observer. Adoption can be opt-in: first add caps to runs that need host-side spend control, then implement the observer, then wire injection or config fallback.
• Compatibility: Compatible with existing capped runs and child-run inheritance. The observer cannot be dropped or replaced once a run tree has one. The config fallback should be treated as a default, not a substitute for explicit run-tree ownership. Validate against the current Laravel/PHP version, queue driver, and persistence store before rollout.
• Sequencing: 1) Define the reservation/settlement persistence model and expiry policy. 2) Implement CallCostObserver with atomic reservation, idempotent settlement, and refusal-code mapping. 3) Add caps to all runs that will use the observer. 4) Inject the observer at root runs or configure the fallback. 5) Test refusal before request, settlement on success/failure/stopped stream, worker-death expiry, and settled() exception propagation. 6) Canary with a narrow set of capped runs, then expand.

Operational Impact

• Maintenance: The host owns the observer’s persistence, expiry, and reconciliation. This adds a new operational store and lifecycle to maintain. Keep the observer small, versioned, and covered by tests around reservation release and settlement idempotency.
• Support: Support teams will need runbooks for budget_observer_uncapped, host-defined CallRefused codes, fallback call_refused_by_host, open reservations from dead workers, and exceptions thrown from settled(). Logging should distinguish harness refusal from observer persistence failures.
• Scaling: Multi-worker deployments need a shared, concurrency-safe reservation store. Avoid process-local memory. Use atomic reserve/expire operations and expect contention around high-volume capped runs. Reservation expiry must be safe under retries and duplicate delivery.
• Failure modes: Worker death between reserve and settle leaves an open reservation; expire it on the host side. Observer exceptions during reserving() refuse the call cleanly. Observer exceptions during settled() do not undo harness settlement and will propagate. Uncapped runs with an observer are rejected. Stopped streams still produce exactly one settlement, so persistence must handle that outcome.
• Ramp-up: Moderate. The API surface is small, but the cost lifecycle is subtle. Teams need to understand capped-path semantics, observer inheritance, trusted-host responsibilities, and reservation expiry before enabling it broadly.