.agents/skills: add mz-demo-data for live SQL-generated demo data

[frankmcsherry]

Opening this as a draft, for visibility and discussion rather than as a deployment mechanism. The skill has been sitting in a local scratch directory excluded from git, which meant nobody else could see it or build on it. This makes it shareable. Where it should ultimately live is an open question, see below.

What it is

A skill that stands up continuously-updating, realistic synthetic data inside a running Materialize instance using nothing but views over mz_now(). No Kafka, no external load generator, no seed scripts. The technique is the "moments" construction from this blog post.

The audience is people evaluating Materialize, not people developing it. So SKILL.md reads as a guided path rather than a SQL reference. It walks an agent through connecting, picking or designing a domain, proposing the model in plain language before writing any SQL, allocating a byte budget, loading, and proving the result with a heartbeat and an invariant query. There is an explicit "things to not do" list, the most important being: do not claim it works until the heartbeat ticks against the user's own instance.

How it works

Two layers.

Scaffold builds a sliding window of timestamps and hashes each into 16 deterministic bytes. Stable, never edited per domain.

Domains turn those bytes into entities. Primary keys derive from a moment's bytes. Child rows re-hash their parent's bytes. So when a moment falls out of the retention window, every row derived from it vanishes at the same time. That is referential integrity without declaring a single constraint, and it is the insight the whole approach rests on.

Six domains ship: auctions, ecommerce, banking, iot, clickstream, zoo. Each bakes in an invariant that holds by construction rather than by check constraint, which is the part that is hard to fake with off-the-shelf data. Banking is the headline: the sum of all balances is exactly zero at every consistent timestamp regardless of how many transactions are in flight.

SKILL.md is also honest about what the construction cannot promise. Ids come from 24 bits of MD5 entropy, so at default settings the birthday paradox produces a few hundred collisions in steady state. There is a section on which invariant shapes survive that (aggregate equalities, sum-to-zero, FK-by-re-derivation) and which do not (per-parent fanout equality, per-id uniqueness), so nobody demos a claim that quietly is not true.

Verification

Loaded against Materialize v26.36.0 in the Docker emulator.

• All six domains load and coexist in one database.
• All eight documented invariants hold: orphan bids 0, orphan line items 0, ecommerce fanout balances, SUM(balance) 0, orphan alerts 0, and all three zoo invariants.
• SUM(balance) stayed at exactly 0 across repeated sampling while data churned underneath.
• The sliding window advances correctly: row count pinned at the expected retention / tick while both ends of the window advanced in lockstep with wall clock.

Open questions for reviewers

1. Where should this actually live? In-repo makes it discoverable for us but prospects do not clone the development repo. A standalone public repo, a plugin, or the docs quickstart are all plausible and are not mutually exclusive. Kept here as a symlink over misc/demo-data/ specifically so the directory can be lifted out whole.

2. Should this connect to misc/mcp-materialize-agents/? That server's README describes almost exactly the "live context for agents" story, down to the customer-support-agent example. The natural pairing is: this skill seeds the churning data and the indexed views, the MCP server exposes them as tools, and any agent consumes them. That would also make the demo work outside Claude Code. Not done here, but it seems like the obvious next step.

3. Is there a "context graph" domain worth adding? Prospects reportedly respond to this framing more than any other. The shared people pool already makes every domain co-keyed on the same 256 identities, so a per-person context bundle is mostly a matter of adding an index and a documented access path. What is unresolved is whether "graph" means one entity plus everything attached to it, or genuinely following links several hops out. The second is harder to land quickly but it is the version other systems cannot do.

Release notes

None. Developer and evaluation tooling only, no user-visible product change.