Core features vs. samples

In plain words

Kumiko ships with two very different kinds of ready-made code, and confusing them leads to real mistakes. The first kind — bundled features — is production code, the same code your own app runs, meant to be imported and used exactly as-is; it is tested, boot-validated, and kept working release after release. The second kind — samples — is teaching code, written to show one idea as clearly as possible, with a test that proves the idea still works, but never meant to be imported into a real app or depended on for a production feature. Think of it like a furniture store: the bundled features are the flat-pack shelving unit you actually buy and put in your living room; the samples are the little cutaway diorama in the showroom that shows you how the joints fit together — you look at it, you learn from it, but you do not carry it home and put your books on it. If you import a sample’s code directly into a real app, you have taken the showroom diorama home, and it was never built to hold your books.

bundled feature (packages/bundled-features/) --> import it, run it in prod
sample (samples/recipes/, samples/apps/)      --> read it, copy the pattern, don't import it

Why the split exists

Both kinds of code are event-sourced Kumiko features and both are tested — so from the framework’s point of view, nothing structurally distinguishes them. The split is about what the code promises.

A bundled feature (packages/bundled-features/src/<name>/) promises: this is safe to run in production, its schema is stable across versions, its integrations (hooks, extension points, boot-validator checks) are correct, and when the framework finds a bug in it, you get a patched version for free. audit, secrets, user, tenant, jobs — these are the ready-made pieces covered in Bundled features vs. custom. That page is about a different axis: bundled vs. your own business code. This page is about samples, which are neither.

A sample (samples/recipes/<name>/, samples/apps/<name>/) promises something narrower: this pattern works, here is the shortest correct demonstration of it, and here is a test that fails the moment the framework regresses it. Samples exist so the framework’s own feature set has a worked example for every capability — relations, embedded fields, search, realtime, rate limiting, multi-currency money, and so on (see the full list in samples/README.md). They are not shipped as an npm package. They are not boot-validated as part of your app. Nobody patches them for you when a schema you copied out of one turns out to need a security fix six months from now — because it is your copy, in your app, and the framework has no idea it exists.

What tells them apart in practice

	Bundled feature	Sample
Lives in	packages/bundled-features/src/<name>/	samples/recipes/<name>/, samples/apps/<name>/
Published as	Part of @cosmicdrift/kumiko-bundled-features	Not published at all
You use it by	import { ... } from "@cosmicdrift/kumiko-bundled-features/<name>"	Reading the source, copying the pattern into your own feature
Framework patches it	Yes — version bumps carry fixes	No — once copied, it is your code
Test type	Integration + unit, gates every framework release	Integration/unit, gates that the pattern still works
Purpose	Solve a cross-cutting problem for you	Show you how to solve a specific problem yourself

Two of the two entries in the “recipes” table are worth calling out because they map directly to bundled features’ extension points rather than to a copyable pattern: recipes/cross-feature-events and recipes/designer-demo. Even those stay samples — they demonstrate the extension mechanism, they are not the mechanism itself.

The decision rule

Never import from samples/. If you find yourself doing that, what you actually want is either a bundled feature (check samples/README.md’s table and the bundled-features package first) or your own feature, written using the sample as a reference.

When you are about to build something and are not sure how — full-text search, a state machine, encrypted per-tenant config, rate limiting — check the recipes table first. Read the recipe, understand the two or three primitives it combines, then write your own feature using those primitives directly. The recipe’s job is done the moment you understand the pattern; it was never meant to become a dependency of your app.

See also

• Bundled features vs. custom — the other axis: ready-made cross-cutting features vs. your own business features. Samples are neither of those.
• Features and composition — what a feature definition is, the shape every bundled feature and every sample shares.