Add one trade to a ledger and you have invalidated the position, the average cost, the cash balance, the realised gain, the unrealised gain, the equity total, the tax report, the chart series and the allocation breakdown. Update one stock price and you have invalidated a subset of those for every user who holds it.

The usual approach is to enumerate:

Cache::forget("portfolio_summary_{$userId}");
Cache::forget("tax_report_{$userId}_{$year}");
Cache::forget("chart_data_{$userId}");
// ...and the one you forgot, which is why you are reading this

This works right up until someone adds a tenth derived value and updates four of the five places that need to forget it. The bug that results is the worst kind: intermittent, user-specific, invisible in tests, and it manifests as wrong numbers rather than an error.

Version the namespace, not the key

Instead of removing entries, make them unreachable. Every cache key carries the version counters of everything it depends on:

$key = sprintf(
    'portfolio_summary_u%d_v%d_m%d',
    $user->id,
    $this->userVersion($user),   // bumped when this user writes an event
    $this->marketVersion(),      // bumped when any price updates
);

return Cache::remember($key, now()->addDay(), fn () => $this->compute($user));

Invalidation is then an increment:

// A new trade or capital event: only this user's derived data is stale.
Cache::increment("user_version_{$user->id}");

// A price update: every user's valuations are stale.
Cache::increment('market_version');

One increment retires every key in that namespace at once — summary, tax report, chart series, allocation, the lot. Old entries are never deleted; they simply stop being addressed and expire on their own TTL.

The two dimensions matter because the invalidation sources are genuinely independent. Your own writes affect only you. A market price change affects everyone holding that instrument. A single counter would force you to bump the world every time one user recorded a trade.

Making the bump automatic

The remaining hole is a developer updating a price without remembering to increment. Close it at the model boundary rather than at the call sites:

protected static function booted(): void
{
    static::saved(fn () => Cache::increment('market_version'));
    static::deleted(fn () => Cache::increment('market_version'));
}

Now the invariant is enforced by the thing being changed, not by everyone who changes it.

What it costs

It is deliberately coarse. Bumping the market version invalidates cached data for every user, including those holding none of the affected instrument. That is over-invalidation, and you should be clear-eyed that you are trading recomputation for correctness.

At small scale that trade is obviously right: recomputation is cheap, and wrong numbers in a financial tool are not. At large scale — millions of users, prices ticking constantly — it becomes obviously wrong, and you would want per-instrument versions with the dependency tracking that implies. Somewhere in between there is a crossover point, and you should know roughly where yours is before you adopt this.

Old entries linger until TTL. Memory that would have been freed by an explicit forget is held a while longer. In practice this is why a TTL is not optional — a day is generous, and it bounds the accumulation.

Requires an atomic increment. Redis and Memcached give you this. A database cache driver can too, but check that your driver’s increment is genuinely atomic and not a read-modify-write, or concurrent bumps will be lost and you are back to serving stale data.

Where else it fits

Anywhere a set of derived values shares a small number of independent invalidation sources: a pricing engine keyed on customer tier and rate-card version, a permissions cache keyed on user and role-definition version, a rendered report keyed on tenant and template version.

The test for whether it applies is simple. Ask: when input X changes, can I confidently list every cache key that is now wrong? If the honest answer is “probably, but I would want to grep first” — the enumeration approach has already failed, and you just have not been bitten yet.

The idea is one rule:

Store facts. Derive everything else. Never store a value you could recompute.

You can adopt that rule in an ordinary relational schema, with ordinary models, on a Tuesday. No event store required. What follows is what it bought us in a financial ledger, and what it cost.

The rule, concretely

In a portfolio tracker there are exactly two kinds of fact:

• Capital events — money entering or leaving: deposits, withdrawals, dividends.
• Trade events — a signed quantity of an instrument at a price, plus fees and taxes.

That is the whole write model. Two append-only tables.

Everything a user actually looks at is absent from the schema: current position, weighted average cost, cash balance, realised gain, unrealised gain, total equity, allocation, tax liability. All of it is computed by replaying the log.

Corrections are new events, never edits. A trade entered wrong three months ago is fixed by recording a correcting event, not by updating the original row. The log is what happened, including the mistakes.

What it makes impossible

This is the part worth being precise about, because the benefit is not “cleaner code” — it is a category of bug that stops existing.

Drift. When a balance is stored, it is a second source of truth. Every code path that writes an event must also update it, correctly, under concurrency, forever. Miss one — a bulk import, an admin correction, a rollback — and the stored balance and the log disagree. There is no drift when there is nothing to drift from.

Migration corruption. Backfilling a stored aggregate is a one-shot operation you have to get right against production data. Derived values need no backfill; change the function and every answer changes with it.

Untraceable numbers. Every figure on screen has an origin you can walk back to specific rows. “Why is my average cost 43.20?” is answerable, exactly, every time. In a stored-balance design that question frequently has no answer at all.

What falls out for free

A good sign you picked the right model is that features you did not design for turn out to be already built.

Time travel. “What did this look like in March?” needs no snapshot table. It is the same computation with the event stream filtered by date — a where clause, not a feature.

Inferred properties. How much fresh capital went in versus how much came from trading gains is derivable from the log alone. Nothing needed tagging at entry time, which matters enormously because users do not reliably tag anything.

Audit for free. The write model is the audit log. There is no separate table recording what changed, because nothing ever changes.

What it costs

Recompute latency, on every read. This is the whole bill, and it is real. You pay it with caching — which becomes the actual hard problem of the design, and which we wrote about separately in two-dimensional cache versioning .

Replay order becomes load-bearing. Realised gain depends on the sequence sells happened in. Events need a reliable ordering that is not “whatever id came out as”, and backdated entries have to slot into the right position rather than the end.

Discipline that the schema does not enforce. Nothing stops a future contributor adding a current_balance column for a quick dashboard win. We wrote the rule down as a short non-negotiable document in the repository and tested the invariants directly — cannot oversell, cash must reconcile exactly. A rule that lives only in someone’s head is not a rule.

Some things genuinely are facts. A closing price on a given day is not derivable from anything; it is an observation and it gets stored. The rule is “derive what is derivable”, not “store nothing” — and confusing the two leads to some very silly conversations.

The test

Ask one question about the aggregate you are about to store:

If this value and the records it summarises ever disagreed, how would you find out?

If the answer is “a customer would tell us”, or “we would not”, you are looking at a value that should be derived rather than stored. If the answer is “it does not matter much either way” — store it, and get on with something more interesting.

// Don't do this.
public function updated(Ticket $ticket): void
{
    if ($ticket->wasChanged('status_id')) {
        $ticket->business->decrement('email_credits');
        SendStatusEmail::dispatch($ticket);
    }
}

It sends an email when a ticket changes status and charges the tenant for it. It has three separate bugs, and only one of them is the one people usually look for.

Three failure modes, not one

Double-send. The job runs, times out after handing off to the mail provider, and is retried. The customer gets two “your repair is ready” messages. The usual fix — a sent_at column checked at the top of the job — narrows the window but does not close it: two workers can both read null before either writes.

Phantom quota burn. The credit is decremented, then the send fails terminally on an invalid address. The tenant paid for nothing. Or worse: the decrement and the send are in different transactions, one commits and the other does not, and the ledger and reality part company permanently.

Lost delivery on rollback. dispatch() inside a transaction hands the job to the queue immediately. If the surrounding transaction then rolls back, a worker picks up a job pointing at a status change that no longer exists. On a fast queue this races even without a rollback: the worker can start before the transaction commits and find nothing there.

Retry configuration addresses none of these. They are not transport problems.

Model the delivery, not the send

The fix is to stop thinking of sending as an action and start thinking of it as a claim that gets recorded, budgeted, and only then executed.

DB::transaction(function () use ($ticket, $status, $channel) {
    // 1. The row IS the claim. The unique index is the concurrency control.
    try {
        $delivery = NotificationDelivery::create([
            'ticket_status_id' => $status->id,
            'channel'          => $channel->name(),
            'state'            => DeliveryState::Pending,
        ]);
    } catch (QueryException $e) {
        if (! $this->isUniqueViolation($e)) {
            throw $e;
        }
        return; // Someone else already claimed this exact send. Nothing to do.
    }

    // 2. Budget it in the same transaction. Out of credit => the claim
    //    rolls back too, and there is no orphan row to retry later.
    $this->quotas->reserve($ticket->business, $channel->quotaKey(), $delivery);

    // 3. Dispatch last, and only if the transaction survives.
    SendNotificationDelivery::dispatch($delivery)->afterCommit();
});

Three properties, each fixing one of the bugs above:

1. The unique index on (ticket_status_id, channel) is the idempotency key. Not a flag that gets checked, a constraint that cannot be violated. Concurrent attempts race for the same key; the loser catches the violation and returns. This is the only version that is actually safe under concurrency, because the database is doing the mutual exclusion rather than your application logic.
2. The reservation shares the transaction with the claim. Both happen or neither does. There is no window in which one exists without the other.
3. afterCommit() moves dispatch after the commit. No job can reference a row that was rolled back, and no worker can start before the data it needs is visible.

Terminal and transient are different failures

Once delivery is a row with a state, the worker needs to say why it failed, and there are exactly two answers that matter:

try {
    $channel->send($delivery);
    $delivery->markSent();
} catch (TransientDeliveryException) {
    throw;                       // let the queue retry; reservation stands
} catch (TerminalDeliveryException $e) {
    $delivery->markFailed($e);
    $this->quotas->release($delivery);   // give the credit back
}

A provider timeout or a 5xx is transient: retry, keep the reservation held. An invalid phone number or a rejected template is terminal: stop, mark it failed, and release the budget.

Collapse those into a generic catch-and-retry and you get a queue that spends the night retrying an address that will never be valid while the tenant’s allowance stays locked. This distinction is worth encoding as two exception types rather than a boolean, because the classification lives with the channel adapter that actually understands the provider’s error codes.

You still need a reconciler

The uncomfortable case: a worker dies between reserving and sending. No exception is thrown, so nothing is classified. The row sits Pending forever with budget held against it.

No amount of transactional care removes this — the process can always vanish. So a scheduled command sweeps deliveries left pending beyond a threshold and either re-queues or fails them.

That sweeper is only safe to run because of the idempotency work. Re-queuing a delivery that actually did send is harmless when the send is claimed by a unique row. In a design where sending is an action rather than a record, a reconciler is a double-send generator.

What it costs

An extra table with a unique index on a hot write path, a scheduled command, two exception types, and tests that have to exercise concurrency rather than a happy path.

What you get is that the awkward questions have boring answers. Can a customer get the same message twice? No — the constraint prevents it. Can a tenant be billed for a send that never happened? No — terminal failures release the reservation. What if we deploy mid-send? It is retried, and finds the work already claimed.

Those are good answers to have ready when the customer asking is the one being billed.

Not crawlers indexing you for a results page — that has been true for thirty years — but agents retrieving your content to answer a question right now, on behalf of someone who will never see your page. If your site publishes data, that audience needs something other than HTML, and the usual arrangement is unpleasant for everyone: they scrape, you get load and no attribution, and they get a number with no provenance.

We had a service where this was worth solving properly, and no commercial reason to keep the data scarce. Here is what we shipped, in the order it mattered.

1. A machine-readable answer to the actual question

Start here, because everything else is signposting to it.

Ours was an MCP server: stateless JSON-RPC 2.0 over Streamable HTTP, exposing a single tool that answers the one question the site exists to answer, in any requested currency, with the timestamp and source of the underlying data attached.

A few things we would tell anyone building one:

• Stateless is the right default. Streamable HTTP without a session layer means the server is an ordinary rate-limited HTTP endpoint, deployable and scalable exactly like the rest of the app. Sessions buy you very little for a read-only tool and cost you a lot of operational surface.
• Negotiate protocol versions explicitly, and support more than one. The specification is moving. Clients in the wild pin different revisions. Handle a version you do not know by responding with one you do, rather than failing.
• One tool that answers the real question beats five that expose your schema. The temptation is to publish get_metals_price, get_fx_rate, list_currencies and let the agent assemble the answer. Do not. Every join you push onto the caller is a chance for them to compute something wrong and attribute it to you.
• Return provenance in the payload. Not just the number — when it was computed, what it was derived from, what the caveats are. This is the single biggest advantage you have over being scraped, and it costs three extra fields.

2. Making it findable without being told

An endpoint nobody can discover is a private API with extra steps. This is the part that is genuinely new, and it is mostly cheap static documents.

• /.well-known/mcp.json — a server card. An MCP client that knows only your domain can find the server, learn what it exposes, and connect.
• /.well-known/api-catalog — the RFC 9727 linkset. A general-purpose way to say “here are my machine interfaces”, not specific to any one protocol, which matters because MCP will not be the last of these.
• Link headers on ordinary responses, advertising the sitemap, the catalogue and llms.txt. Consumers that fetch a page and never parse the body still see them.
• llms.txt and llms-full.txt — a plain-language map of the site, and a fuller dump for consumers that want everything in one request.

The principle underneath: a machine should be able to get from your bare domain name to a typed answer without a human reading your docs. Test that path end to end, because it is easy to ship four correct documents that do not actually chain.

3. Saying what you allow, on purpose

Most robots.txt files are ambiguous about AI use by accident — they were written before the question existed, and silence gets interpreted by whoever is doing the interpreting.

We name the major AI user agents explicitly and declare content signals separating indexing, inference-time retrieval and training. For this project all three are permitted, because the point of the service is to be used. That is not the right answer for everyone. The recommendation is not “allow everything” — it is decide, and write it down, because the alternative is having it decided for you.

What we would skip

Being honest about the parts that have not paid off yet:

• llms-full.txt has seen little use. Cheap to generate, so it stays, but we would not build it first.
• Discovery specifications are young. The RFC is stable; the MCP-adjacent conventions are not, and some of this will need revisiting. If you have limited time, ship the tool and the server card, and add the catalogue later.
• Nobody has a good analytics story here. Agent traffic is hard to distinguish from ordinary API traffic, so “did this work?” remains partly a matter of faith. If you need a measurable return before you build, this is not yet that.

Was it worth it?

For a public-interest service where being used correctly is the goal, clearly yes — the marginal cost over an already-public JSON API was small, and it replaced being scraped badly with being consumed properly.

For a commercial product where the data is the moat, the calculus is entirely different, and the honest answer may be that you want the opposite of all of this.