Core Laravel Package

Product Decisions This Supports

• Build vs. buy for the audit trail. The single biggest decision this package informs: whether to hand-roll hash chaining, canonicalization, signing, and verification in-house or adopt a library. Chronicle covers the parts teams chronically underestimate — canonical payload hashing, key rings with rotation-safe verification, checkpoint signing, and incremental verification — so the realistic comparison is "two to three engineer-weeks plus permanent maintenance" versus one dependency.
• Whether to commit to a regulated/enterprise segment. SOC 2 CC7.x, ISO 27001 A.8.15/8.16, PCI DSS Req. 10, HIPAA audit controls, and financial-record retention rules all ask you to demonstrate that logs are complete and unaltered. A database table with a deleted_at is a weak answer; a verifiable ledger with signed checkpoints and external anchoring is a defensible one. This package is effectively a go/no-go enabler for selling into those buyers.
• Roadmap sequencing for a "trust & compliance" epic. Chronicle decomposes into shippable increments with clear PM-level scoping: (1) ledger + HasChronicle automatic model auditing, (2) chronicle:checkpoint on a schedule, (3) external anchoring (RFC 3161 TSA in core, or AWS S3 Object Lock via laravel-chronicle/anchor-s3), (4) KMS/HSM signing via laravel-chronicle/kms-aws so the private key never lives in app config, (5) scalable verification modes in CI/ops. Each step is independently valuable and independently demoable — good for quarterly planning.
• Ops/SLA decisions on verification cost. chronicle:verify --checkpoints-only --anchors returning an O(checkpoints) proof rather than a full re-walk is a meaningful operational lever: it turns "verify the ledger" from a nightly batch that grows forever into something you can run hourly or on-demand from an auditor. That changes what you can promise in a security questionnaire.
• Key-management and blast-radius design. The key ring model (active key signs, retired keys still verify; chronicle:key:rotate writes a boundary checkpoint first) means key rotation is a scheduled maintenance event, not a breaking migration. PM decision: who owns the private key, where it lives (env vs. KMS/HSM), and what the rotation cadence is — this is a policy input, not just an engineering one.
• GDPR/erasure posture. The explicit "GDPR erasure" claim in the feature matrix forces a design conversation early: what personal data goes into metadata, what gets tokenized, and how erasure coexists with an immutable ledger. Better to settle this before shipping than to discover it during a DSR.
• Auditor-facing artifacts as a product surface. Signed, verifiable exports and compliance reports mean you can hand a third party something they can check without trusting your word or your database. Useful both as an internal control and as a customer-facing trust feature ("export your audit history, verify it yourself").
• Test/CI strategy. Chronicle\Testing\LedgerSeeder drives the real write path (hash chain + signing) inside one transaction, so seeded ledgers actually verify — raw factory inserts do not. PM-relevant because it prevents a class of "our audit tests pass but prove nothing" bugs and keeps integration suites fast.

When to Consider This Package

Consider adopting when:

• The application is Laravel 12/13 on PHP 8.2+, and ext-sodium + ext-openssl are acceptable production dependencies (verify this against your hosting/container baseline — a non-trivial share of managed PHP platforms and hardened images omit or gate these).
• Audit records are evidence rather than UI. If someone outside your company — an auditor, a regulator, a customer's security team, an insurer — will rely on the log, tamper-evidence has real value. If the log is only ever read by your own support team, it probably does not.
• You have, or are willing to assign, an owner for signing keys and a documented rotation/recovery procedure. Chronicle makes correct key handling possible; it does not remove the operational obligation.
• Expected volume is compatible with append-only growth: the read path has cursor pagination and constant-memory streaming, and verification is incremental — but the ledger still only grows. Have a partitioning/archival plan before you pass a few million entries.
• You want the audit trail to be an infrastructure concern rather than scattered domain code — HasChronicle, Chronicle::observe(), and the fluent record()->actor()->action()->subject()->commit() chain make this consistent across teams.

Look elsewhere when:

• You need an activity feed, "who changed this field" UI, or a notification trigger — spatie/laravel-activitylog and similar are cheaper, simpler, and come with a decade of ecosystem familiarity. Chronicle is heavier and its value is precisely the part an activity feed doesn't need.
• You are not on Laravel 12+ or PHP 8.2+. Hard requirement, not a soft one.
• Your organization cannot tolerate the vendor risk profile today: ~128 stars, zero dependents on Packagist, no stated commercial support, and a namespace (laravel-chronicle) that is community rather than first-party. That is a young, unproven dependency in a security-critical path — reasonable teams will defer.
• You need write throughput well beyond a single database writer without a sharded/partitioned ledger design; the hash chain is inherently serial, and that is a property of the approach, not a bug you can configure away.
• Regulatory obligation is specifically immutable storage (WORM) at the storage layer. Hash chaining detects tampering; it does not prevent it. You still need database-level controls plus an external anchor in a separate trust domain, and the anchoring story is opt-in and relatively new here.
• You cannot run the chronicle:verify cadence in CI or ops, or have no plan to act on a verification failure. A tamper-detection system nobody monitors is a compliance liability, not an asset.

How to Pitch It (Stakeholders)

To executives and buyers: Chronicle turns "we have logs" into "we can prove our logs are complete and unaltered." Most of the cost of compliance is evidence-gathering, and audit trails are one of the few controls you can make self-verifying. It is MIT-licensed, self-hosted, and replaces what would otherwise be a bespoke, permanently-maintained cryptographic component. The pragmatic framing: it compresses months of audit-prep friction and unblocks enterprise and regulated deals, at the cost of one dependency and a key-management runbook. The caveat to state plainly: this is an early-stage package (~128 stars, no dependent projects, no commercial support tier), so adoption should be paired with an abstraction seam and a documented exit path rather than wired into every call site.

To engineering: It does the cryptographic work properly and gets out of the way. Payload canonicalization, SHA-256 hash chaining, ULID generation, and transactional persistence are handled inside commit(); automatic Eloquent auditing is a single trait or Chronicle::observe() registration. Signing is pluggable — Ed25519 via libsodium or ECDSA P-256 via OpenSSL out of the box, with KMS/HSM adapters available — and the key ring means rotation is a scheduled operation (chronicle:key:rotate writes a boundary checkpoint) rather than a data migration. Verification is tiered, so CI doesn't re-walk the entire ledger on every run: full, --since-last-checkpoint, --from-checkpoint/--to-checkpoint, --checkpoints-only --anchors, and --resume. LedgerSeeder seeds verifiable fixtures through the real write path, which fixes the common trap where factory-inserted audit rows silently fail integrity checks. The reference resolver is DB-free by default (resolveReference / referenceLabel) and only hydrates on explicit opt-in — a detail that matters when rendering audit views over a large ledger.

What I would flag before sign-off: the append-only chain is serial by construction; the ext-sodium/ext-openssl requirements must be confirmed against the deployment image; anchor failures are non-fatal by design (good for availability, but it means your monitoring must alert on pending/failed anchors, not assume the checkpoint implies anchoring); and the external anchoring and KMS paths are the newest parts of the surface area, so pilot them in staging with a real TSA/S3 bucket before betting a compliance deadline on them. Recommended rollout: adopt the ledger and checkpoints first, add anchoring once verification is running in CI and someone owns the alerting, then move the private key to KMS.