Statamic Products Laravel Package

Technical Evaluation

Architecture fit

• Two releases are now in scope. 1.11.1 was a presentation-layer patch to the file picker; 1.12.0 is an additive domain-model change to credit lines. They are independent — the picker work is unchanged and unaffected.
• 1.12.0 introduces the package's first point-in-time concept: an added_at timestamp written by the model when it numbers a credit line, plus two read paths that accept it (Access::creditLinesAt($at) and AccessView::creditLines(includeEnded: …, at: $at)). This is new API surface, not a patch, and it is the first release in this lineage that implies a schema change.
• The semantics are the important architectural decision: null means "has always been there", not "unknown". Lines from the takeover (which carry their own number) and all lines saved before 1.12.0 are permanently undated. That is a deliberate and defensible choice for a system that must not retroactively invalidate existing grants, but it means point-in-time accuracy only holds for data created after the upgrade.
• The immutability guard ("once set it is fixed") is a second architectural decision: the model silently returns the stored value when a form or import drops or alters added_at. This protects audit integrity at the cost of silent-write behavior, which is the kind of thing integrators need told explicitly.
• Everything remains server-side and model-enforced. No middleware, no guard, no new configuration lever. The integration footprint stays one migration plus optional query changes.

Integration feasibility

• Drop-in from 1.11.x and 1.10.x at the Composer level; the caveat is the migration. Unlike 1.11.1, this release changes the persisted shape of credit lines, so composer update alone is not a complete upgrade.
• The new arguments are additive and named-argument compatible: creditLines() without at behaves exactly as before, and ended_at semantics are untouched. Existing call sites and views need no edits to keep working.
• Blast radius is narrower than it looks: only code that reconstructs historical state (grant replay, entitlement audits, "was this line present when the grant was issued?" checks) benefits. Ordinary "what does this access have right now" reads are unaffected.

Technical risk

• Moderate-low. The code path is additive and backward compatible, but three things can bite:
  1. Migration is now in scope. Nullable timestamp column, and potentially an index. Any environment where package migrations are published rather than auto-loaded needs a check; a missed migration surfaces as a query error on the new column, not a graceful degradation.
  2. The upgrade boundary is a permanent data seam. Lines created before the deploy are indistinguishable from lines that "always existed". For any grant issued before 1.12.0, a replay at an earlier date will include lines that were in fact added later (but before the upgrade). This is not a bug to fix — it is a limitation to document and to route around by treating pre-upgrade grants as un-replayable.
  3. Silent immutability. A form or import that drops added_at gets the stored value back rather than an error. Good for integrity, but it means a genuine data-correction need has no supported path through the normal write surface.
• Secondary risk: at interacts with includeEnded and with timezone/precision in ways the notes do not pin down. Getting boundary handling wrong produces off-by-one grant decisions that are hard to notice in testing and expensive in production.

Key questions

• Does the release ship a migration, is it auto-loaded or publishable, and does it add an index suitable for (access_id, added_at) range filtering? On a large credit-line table an unindexed point-in-time query is a table scan.
• Confirm null semantics and that no backfill is attempted. Is there a documented statement that pre-1.12.0 grants cannot be replayed accurately?
• Boundary behavior at $at: inclusive (<=) or exclusive (<)? What precision is stored (seconds vs microseconds), and in what timezone — is added_at written in UTC regardless of app timezone?
• Does at also filter on ended_at, or is it purely a lower bound on existence? A line that ended before $at — excluded or returned?
• Do takeover/imported lines with their own number really stay null forever, and is that acceptable to finance/audit, who may read null as "no data" rather than "always present"?
• What is the supported escape hatch for correcting a genuinely wrong added_at? Is the silent revert logged anywhere, and can support distinguish "user edit ignored" from "save succeeded"?
• Are there regression tests for: double-submit with the field dropped, import that alters the value, replay across the upgrade boundary, and a grant made at the exact stored timestamp?

Integration Approach

Stack fit

• Still a standard Laravel package integration — service-provider bootstrapping unchanged, no queue or cache dependency, no new config keys. The only new operational step is php artisan migrate.
• Presentation layer (the 1.11.1 picker work) and domain layer (added_at) are orthogonal; they can be sequenced or shipped together without coupling.

Migration path

• Bump the Composer constraint to ^1.12.0, run composer update for the package only, then php artisan migrate. Confirm whether the migration is auto-discovered or must be published — this differs between package designs and is the single most likely cause of a failed deploy.
• No vendor:publish for config implied. No backfill script exists or is needed; the null-means-always-present semantics are the intentional substitute for backfill.
• Do not attempt to synthesize added_at for historical rows. Doing so would convert "undated, therefore always present" into concrete timestamps that were never recorded, and would silently change replay results for every existing grant.
• Teams on 1.10.x still inherit the 1.10.0 authorization behavior change; that remains a prerequisite to reason about, not something 1.12.0 supersedes.

Compatibility

• Semver-minor: additive methods, additive nullable column, additive named arguments. No removed or renamed surface.
• Behavioral caveats worth writing down: (a) the picker is no longer confined to a folder, only started in it (1.11.1); (b) any line without added_at is treated as existing at every point in time (1.12.0); (c) writes that alter added_at are silently ignored rather than rejected.
• Named-argument dependency (at:) is a minor forward-compatibility coupling — a future parameter rename would break callers. Prefer documenting the signature as stable.

Sequencing

1. Upgrade to ^1.12.0 in staging; run migrations and verify the column and index exist on a production-sized copy of the credit-line table.
2. Verify 1.11.1 picker behavior still holds (open-in-folder, subfolder navigation, graceful denial on ../). These are independent regressions.
3. Verify current-state reads: creditLines() with and without includeEnded returns identical results to 1.11.1 for the same fixtures.
4. Verify point-in-time behavior with fixtures: a line created before the upgrade (null), a takeover line (null), a line created after the upgrade with a known added_at, and a line that has ended. Assert results at timestamps before, exactly at, and after each.
5. Verify immutability: submit a form with added_at omitted and with added_at altered; confirm both persist the originally stored value. Confirm the behavior is at least observable in logs.
6. Timezone check: force a non-UTC app timezone and confirm at comparisons still return the expected set.
7. Promote. No feature flag needed, but schedule the migration as its own step rather than bundling it into an app deploy that also changes entitlement logic.

Operational Impact

Maintenance

• Two small ongoing obligations instead of none: owning a package migration (including any index decision) and owning the null/undated data forever, since it will never converge.
• The immutability guard reduces a class of data-integrity drift but adds a support-time question ("why didn't my edit stick?") that will recur at low volume.
• Auditing gets easier: replay against a grant time is now expressible without bespoke queries. That is real leverage for compliance and for reconciliation work.

Support

• Expect two distinct ticket families. From 1.11.1: "I navigated above my folder and nothing happened" (denial not legible). From 1.12.0: "I corrected the date and it reverted" and "the grant replay shows a line that wasn't there."
• Give first-line support a one-line script for each: out-of-scope navigation → expected, server-enforced; unchanged added_at → expected, by design, escalate for a manual data fix if genuinely wrong.
• Pre-empt the replay question in the help center with the seam: any grant issued before the 1.12.0 deploy should be treated as "all lines present", not replayed precisely.

Scaling

• The picker change (1.11.1) still has no scaling impact. The added_at filter adds a range predicate on a table that historically only had point reads; without an index this degrades as credit lines accumulate per access. Confirm the index ships or add it.
• Write path is unchanged in cost — one timestamp assignment on line creation. No effect on numbering throughput.
• Read path: creditLinesAt is strictly narrower than creditLines() when a date is supplied, so the risk is index availability, not query shape.

Failure modes

• Silent empty state (1.11.1, fixed): watch for the same class in empty and permission-filtered folders.
• Denial not surfaced (1.11.1): user navigates out of scope, sees nothing. Still the likeliest new complaint from that release.
• Path traversal (1.11.1): unchanged server guard is now the only line of defense — keep it under test.
• Missing migration (1.12.0): new-column queries fail outright. Highest-severity new failure mode; enforce via deploy checklist.
• Over-trusting replay (1.12.0): treating an undated line as dated, or replaying a pre-upgrade grant, produces a plausible but wrong entitlement answer. This is the dangerous one because it fails silently and looks correct.
• Misread nulls (1.12.0): downstream reporting that maps null to "unknown" rather than "always present" will mis-state history.
• Boundary off-by-one (1.12.0): inclusive/exclusive or timezone mismatch flips a line in or out of a grant at the margin.
• Ignored write (1.12.0): a correction is silently discarded; the operator believes it succeeded.

Ramp-up

• Still low, but no longer near-zero. A developer needs one new sentence beyond the 1.11.1 model: a credit line with no added_at has always existed, and once a line has one it cannot be changed.
• The full mental model is now three sentences: narrowing is declared once via AccessContainers::allow() and enforced only on the server; the picker's folder is a convenience, not a control; credit lines are datable and immutable, and undated means always present.
• Budget a short session with finance/audit — not engineering — for the null semantics. That is where the misinterpretation risk lives, and it is not a code-reading exercise.