@cratis/pi 7.36.1 → 7.38.0

package/package/corpus/harnesses/copilot/instructions/frontend-quality.instructions.md

@@ -0,0 +1,60 @@
+---
+applyTo: "**/*.{ts,tsx}"
+profile: application
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+---
+<!-- cratis-ai: generated Copilot instructions. Do not edit; rules/ is the source. -->
+
+# Frontend Code Quality
+
+The frontend is software engineering, held to the same bar as the backend — and it is the part most prone to silent degradation under iterative AI editing: orphaned code, duplicated components, sprawling files, shipped placeholders, untested state machines hidden in JSX. This rule is the maintainability contract that prevents that. It complements [react.md](./react.instructions.md) (architecture), [typescript.md](./typescript.instructions.md) (style), and [frontend-testing.md](./frontend-testing.instructions.md) (specs).
+
+Aim for CUPID code: **Composable**, **Unix-like** (small focused pieces), **Predictable**, **Idiomatic**, **Domain-based**.
+
+## Non-negotiables
+
+1. **Never ship placeholder or dead UI as if it were real.** "Coming soon", lorem-ipsum, fake counts, and stubbed fixtures must not reach a screen backing a feature the code actually implements. An empty state is the *designed* empty state for that surface, not a build-time apology. When you implement the real behavior, delete the placeholder and its strings in the same change.
+2. **Components stay small and single-responsibility.** A `// Section` comment inside a component means that section is its own component. A presentational `.tsx` over ~150 lines, or with more than one clear responsibility, is decomposed. Parent owns state; children receive props.
+3. **State logic lives in a view model, not the component.** Per [react.md](./react.instructions.md): extract a `withViewModel` view model (or a tested state module) as soon as a component has 3+ `useState`, any `useCallback`/state-syncing `useEffect`, or derived values. `useCallback`/`useMemo` inside a `withViewModel` component is a smell. Never store React state in a view model; never call hooks inside one — inject the Cratis abstraction. A view model must be constructible in a spec without React.
+4. **Reuse before rewrite.** Check the shared component surface and existing style constants before adding a component or a long class string. Never duplicate a primitive that already exists; prefer a Cratis Components wrapper or an existing shared component over a new one.
+5. **Test behavior, not implementation trivia.** Non-trivial view-model/helper logic gets BDD specs (see [frontend-testing.md](./frontend-testing.instructions.md)). Storybook is visual coverage, not a replacement for behavioral specs.
+6. **No `any`, descriptive names, no orphaned code.** `unknown` or a real type, never `any`. After editing a `.tsx`, read past its last closing `};` to confirm no stale `return (...)` block, duplicate body, or unreachable code remains. Comment only a non-obvious *why* — no "what"/provenance comments.
+
+## Smell guards
+
+Stop-and-fix signals during implementation and review:
+
+| Smell | Why it matters | Preferred move |
+|---|---|---|
+| New component added without checking the shared component surface and `@cratis/components` | Duplicates fragment the design system | Reuse an existing primitive/wrapper, or document the missing one |
+| Slice-local helper promoted to the shared component folder after one use | Freezes a one-off as a shared API | Keep it beside the slice until a second real consumer appears |
+| A vendor UI control (any `primereact/*`, `@mui/*`, … import) where a Cratis component exists | Bypasses Arc binding, the overlay environment and validation; adds a second focus owner | Use the `@cratis/components` subpath component |
+| Import from the `@cratis/components` root barrel in new code | Pulls optional-peer-heavy exports, hides intent | Import from subpaths (`CommandDialog`, `DataPage`, `DataTables`, `Dialogs`, `Dropdown`, `Toolbar`, `Common`) |
+| Component API has many boolean visual flags (`primary`, `selected`, `muted`, …) | State combinations become undefined | One typed `variant`/`tone` union, or split components |
+| A reusable component reaches into domain strings, generated proxies, identity, query, command, or navigation | It is no longer a primitive | Move it to the slice, or make it explicitly Cratis-aware and test/story it as such |
+| Class/style string copied 3× or grown hard to scan | Styling changes become search-and-replace bugs | Extract to a shared style constant or a focused child component |
+| `style={{ ... }}` with static token names | Bypasses theming and review | Move to `className`; keep `style` only for runtime values |
+
+## Definition of done for a frontend change
+
+- [ ] No placeholder/stub copy ships for behavior that is actually implemented.
+- [ ] Each component is single-responsibility; oversized components were split.
+- [ ] State/logic crossing the [react.md](./react.instructions.md) thresholds lives in a view model.
+- [ ] Reused existing primitives/wrappers instead of duplicating.
+- [ ] No smell guard above is triggered without a short, intentional reason.
+- [ ] File read past its final `};` — no orphaned code.
+- [ ] New/changed reusable or stateful components have Storybook stories.
+- [ ] New/changed view-model/helper behavior has BDD specs (see [frontend-testing.md](./frontend-testing.instructions.md)).
+- [ ] Lint, conditional test, and build pass (the project's frontend gates).
+
+## Review discipline
+
+Treat the frontend gates as seriously as the backend build/test gates — a green lint is the floor, not the goal. For any non-trivial frontend change, run a correctness review (and a reuse/dead-code pass) before completing it. Degradation accrues one "it lints, ship it" at a time.
+
+## See also
+
+- [react.md](./react.instructions.md) — MVVM, Cratis Components, queries/commands.
+- [typescript.md](./typescript.instructions.md) — style, type discipline.
+- [frontend-testing.md](./frontend-testing.instructions.md) — BDD Vitest specs and layout.

package/package/corpus/harnesses/copilot/instructions/frontend-testing.instructions.md

@@ -0,0 +1,127 @@
+---
+applyTo: "**/for_*/**/*.{ts,tsx}"
+profile: application
+paths:
+  - "**/for_*/**/*.ts"
+  - "**/for_*/**/*.tsx"
+---
+<!-- cratis-ai: generated Copilot instructions. Do not edit; rules/ is the source. -->
+
+# Frontend Testing
+
+Frontend tests are specifications. The `for_/when_/and_` shape is intentionally the same BDD language as the backend Cratis Specifications: one subject, one context, clear setup, small assertions, no framework noise. When in doubt, mirror the structure in the Cratis Components source before inventing a new style.
+
+The quality goal is CUPID code: frontend logic that cannot be tested in isolation is usually doing too much or depending on the wrong abstraction.
+
+## Frameworks
+
+- [Vitest](https://vitest.dev/) for running tests; Mocha-style `describe`/`it`/`beforeEach` structure.
+- [SinonJS](https://sinonjs.org) for mocking/stubbing.
+- [Chai](https://www.chaijs.com) — **always the `.should` fluent interface**, never `expect()`. `result.should.equal(expected)` reads as a sentence and matches the project's prose preference.
+
+## Location and naming
+
+Tests live next to the unit they specify:
+
+```
+<Slice>/
+    <Subject>.ts
+    for_<Subject>/
+        when_<context>/
+            and_<extra_context>.ts
+```
+
+| Shape | Use for |
+|---|---|
+| `for_<Subject>/when_<context>/and_<extra>.ts` | default — view models, helpers with branches, component specs |
+| `for_<Subject>/when_<context>.ts` | tiny pure-helper spec with no useful extra context |
+
+snake_case file/folder names so the path reads as a scenario sentence. Use `should` in `it()` descriptions (spaces, not underscores — TS specs read as human sentences). Don't add `.test.ts`/`.spec.ts` files unless the config changes intentionally.
+
+## BDD structure
+
+```ts
+import { describe, beforeEach, it } from 'vitest';
+import { MyViewModel } from '../../MyViewModel';
+
+describe('when filtering active candidates', () => {
+    let viewModel: MyViewModel;
+
+    beforeEach(() => {
+        viewModel = new MyViewModel();
+        viewModel.setSearch('senior');
+    });
+
+    it('should keep candidates matching the search text', () => {
+        viewModel.filteredItems.should.have.lengthOf(1);
+    });
+});
+```
+
+- `describe('when ...')` names the scenario, not the class.
+- `beforeEach` does the arrange/act once for the context; each `it('should ...')` asserts one observable outcome.
+
+## What to test
+
+Behavior that can regress without TypeScript catching it:
+
+- View-model state transitions, computed getters, filtering/sorting/selection, wizard steps, validation state, command-value derivation.
+- Pure helpers: parsing, formatting, path lookup, grouping, boundary cases.
+- Command orchestration outside `CommandDialog`: handling of unauthorized / invalid / exception / success outcomes.
+- React component rendering only when markup, wrapper behavior, disabled state, or integration with a wrapped component is the point.
+
+**Do not test:** generated Cratis proxies; framework/Cratis Components internals; CSS pixel-perfection; trivial presentational pass-throughs with no branch/derived behavior.
+
+## View models
+
+Plain TypeScript classes constructible directly in a spec:
+
+- No React hooks; no direct `window`/`localStorage`/`location`/timers/network — inject the Cratis/browser abstraction (see [react.md](./react.instructions.md)).
+- Derived values are getters, not `useMemo`.
+- Commands are methods with explicit inputs, not inline closures hidden in JSX.
+
+Pass small typed fakes or `sinon.stub()` instances for dependencies; avoid broad harnesses until a second spec reuses them.
+
+## Component specs
+
+The environment is `node`. For behavior that doesn't need browser events, use server-rendered markup:
+
+```ts
+import React from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { vi } from 'vitest';
+
+vi.mock('@cratis/components/Dialogs', () => ({
+    Dialog: (props: { buttons?: React.ReactNode; children?: React.ReactNode }) =>
+        React.createElement('div', null, props.children, props.buttons),
+}));
+
+describe('when rendered while busy', () => {
+    let html: string;
+    beforeEach(() => { html = renderToStaticMarkup(React.createElement(MyDialog, { isBusy: true })); });
+    it('should disable the confirm button', () => { html.should.include('disabled'); });
+});
+```
+
+- Mock only the external component boundary needed; prefer typed mock props over `any`.
+- Add jsdom / Testing Library only when behavior truly requires DOM events; don't make it the default.
+- Avoid snapshots — they hide behavior and make refactors noisy.
+
+## Stories vs tests
+
+Storybook covers visual states, documentation, and manual verification; Vitest covers behavior. A component with non-trivial logic usually needs both — Storybook for variants/interactive state, Vitest for view-model/helper behavior and narrow rendered-component behavior.
+
+## Async and time
+
+Use `vi.useFakeTimers()` for time-dependent behavior; restore with `vi.useRealTimers()` in `afterEach`. Never depend on the real current date, random values, network, or browser storage. For suspense-query tests, clear the Arc query caches in teardown.
+
+## Gate
+
+Run the project's frontend test gate (e.g. `yarn test`) for frontend changes; it complements lint and build, it does not replace them.
+
+## See also
+
+- [react.md](./react.instructions.md) — MVVM, view-model testability, Arc hooks.
+- [frontend-quality.md](./frontend-quality.instructions.md) — the engineering bar these specs serve.
+- [specs.md](./specs.instructions.md) — the backend BDD language this mirrors.
+- skill: **cratis-application-react-specifications** — the step-by-step workflow that applies these conventions.

package/package/corpus/harnesses/copilot/instructions/git-commits.instructions.md

@@ -0,0 +1,139 @@
+---
+applyTo: "**/*"
+---
+<!-- cratis-ai: generated Copilot instructions. Do not edit; rules/ is the source. -->
+
+# How to Write Git Commits
+
+Commits are the permanent record of how the codebase evolved. Each commit should tell a clear story: *what* changed and *why*. A reviewer reading `git log --oneline` should understand the arc of the work without opening any diffs.
+
+## Never rewrite history
+
+**Committed history is append-only. Never rewrite it — under any circumstances, on any branch, including your own.**
+
+These commands are **forbidden** unless the human explicitly asks for that specific command on that specific branch in that specific message:
+
+| Forbidden | Why |
+|---|---|
+| `git rebase` (any form, incl. `-i`, `--onto`, `--autosquash`) | rewrites every replayed commit; the originals become unreachable |
+| `git commit --amend` | replaces the tip commit; the original is unreachable immediately |
+| `git reset --hard`, `git reset` onto an earlier commit | discards commits and, with `--hard`, uncommitted work too |
+| `git push --force`, `git push --force-with-lease`, `git push -f` | destroys the remote's copy — the one backup that survives local loss |
+| `git branch -D` / `git branch -d` on a branch holding unmerged commits | strands those commits with no ref; `git gc` then deletes them |
+| `git checkout`/`git switch` away while another agent's commits sit only on this branch | the commits leave with the branch and the working tree silently reverts |
+| `git filter-branch`, `git filter-repo`, history-rewriting scripts | rewrites the entire history graph |
+| `git gc --prune=now`, `git reflog expire` | destroys the recovery path for anything already stranded |
+| `git merge --squash`, `gh pr merge --squash`, `--rebase`, the **Squash and merge** / **Rebase and merge** buttons | collapses or replays the branch's commits into new ones; every original commit becomes unreachable and the branch's real history is destroyed at the moment of merge |
+
+**Merging is part of this rule, and it is the easiest place to get it wrong.** A squash merge feels
+like an integration step rather than a rewrite, which is exactly why it slips past: the branch is
+deleted straight afterwards, so the commits it collapsed have no ref left and `gc` eventually takes
+them. **Always merge with a true merge commit** — `git merge --no-ff`, or `gh pr merge --merge`.
+Never `--squash`, never `--rebase`, and never the equivalent buttons in the GitHub UI.
+
+If a repository's settings only allow squash or rebase merges, that is a **setting to raise with the
+owner, not a licence to squash.** Stop and ask.
+
+**This is not stylistic.** A commit can exist as an object (`git cat-file -t <sha>` succeeds) while being absent from every branch *and* from the working tree — reachable only through `git reflog`, and only until `gc` runs. Work has already been lost in this repository exactly this way: a branch checkout carried another session's commit away, the branch was deleted, and the file changes silently reverted in the tree. It was recovered from the reflog by luck, because someone asked the right question in time.
+
+### What to do instead
+
+- **Made a mistake in the last commit?** Add a new commit that corrects it. The wrong state stays in history, and that is fine — history is a record of what happened, not a curated story of what you wish had happened.
+- **Need to undo a commit?** `git revert <sha>` — it records the undo as a new commit and loses nothing.
+- **Messy commits before a PR?** Leave them. A reviewer reading a coherent series of small commits is better served than by one squashed blob, and the project does not require a linear history.
+- **Landing a PR?** `gh pr merge --merge` (a real merge commit). **Not `--squash`, not `--rebase`.** The commits on the branch are the record of how the change was actually built; squashing throws that away permanently in exchange for a tidier `main`, which is not a trade this project makes.
+- **Need someone else's changes?** `git merge`, never `git rebase`.
+- **Need to move a commit to another branch?** `git cherry-pick` — it copies, leaving the original reachable.
+- **Working alongside another agent or session?** Use `git worktree add` so each has its own checkout and branch. Never two sessions committing in one working tree.
+
+### Before you finish
+
+Verify your own commits are still reachable on the branch **and** that their content is still in the working tree — those are two different things. `git log --oneline -5` plus a `grep` for something the commit introduced. If a commit has gone missing, `git reflog` is the recovery tool: find the SHA, `git tag` it immediately so `gc` cannot take it, then `git cherry-pick` it back.
+
+## Logical Grouping
+
+Every commit must be a **single logical unit of work**. Group related changes together; separate unrelated changes into distinct commits.
+
+### What belongs in one commit
+
+- A bug fix and the spec that proves it.
+- A new file and the changes to existing files needed to integrate it (imports, registrations, wiring).
+- A refactor that moves or renames code — only the mechanical transformation, nothing else.
+- An interface change together with all implementation updates required to compile.
+
+### What does NOT belong in one commit
+
+- A bug fix mixed with an unrelated feature.
+- Source code changes mixed with unrelated spec additions for a different area.
+- Formatting or style cleanups bundled with behavioral changes.
+- Multiple independent fixes or features squashed into a single commit.
+
+### Deciding where to split
+
+Ask: "If I needed to revert this commit, would I lose exactly one coherent change?" If reverting would undo two unrelated things, it should be two commits.
+
+Common split points:
+
+1. **Infrastructure / plumbing first** — interface additions, new types, or schema changes that later commits build on.
+2. **Core logic second** — the behavioral change that uses the new infrastructure.
+3. **Specs / tests third** — the specs that prove the behavioral change works. Specs may also be combined with the core logic commit when they are tightly coupled (e.g., a TDD red-green cycle or a bug fix with its regression test).
+4. **Integration or wiring last** — connecting the new behavior to the rest of the system (DI registration, routing, UI hookup).
+
+When a task produces both source fixes and new integration specs, prefer separate commits for the source changes and the specs — unless the specs are inseparable from the fix (e.g., a single bug fix + its regression test).
+
+## Commit Messages
+
+### Format
+
+```text
+<imperative summary of what this commit does>
+
+<optional body — why the change was made, context, trade-offs>
+```
+
+- **Subject line**: imperative mood, present tense. Start with a verb: `Add`, `Fix`, `Remove`, `Rename`, `Extract`, `Update`, `Support`.
+- **No period** at the end of the subject line.
+- **72-character limit** on the subject line. If you cannot describe the change in 72 characters, the commit is probably too large — split it.
+- **Body**: separated from the subject by a blank line. Explain *why*, not *what* (the diff shows the what). Use bullet points for multi-part changes.
+
+### Good examples
+
+```text
+Fix duplicate key crash in IdentityStorage.Populate
+
+The upsert used InsertOne which threw on existing identities.
+Replace with ReplaceOne using upsert: true.
+```
+
+```text
+Add type-safe event migration API with expression-based builders
+
+Introduce EventTypeMigration<TUpgrade, TPrevious> base class with
+typed property builders for Split, Join, Rename, and DefaultValue
+operations. Migrators are discovered automatically by convention.
+```
+
+```text
+Add integration specs for observer replay on redaction
+```
+
+### Bad examples
+
+- `Fix stuff` — meaningless.
+- `WIP` — never commit work-in-progress; stage and commit when the unit is complete.
+- `Add files` — says nothing about what or why.
+- `Fix bug and add new feature and update docs` — three unrelated things.
+- `Changed Observer.Handling.cs` — describes a file, not a behavior.
+
+## When to Commit
+
+- **After each logical unit passes the build** — `dotnet build` with zero errors and zero warnings, or `yarn compile` with zero errors.
+- **Before starting a different kind of work** — about to switch from fixing a bug to adding a feature? Commit the bug fix first.
+- **After completing specs for a change** — if the specs are a separate commit from the source change.
+- **Never commit code that does not compile.** Every commit must be a buildable, working state of the codebase.
+
+## Staging Discipline
+
+- Use `git add <specific files>` rather than `git add .` or `git add -A`. Only stage files that belong to the current logical unit.
+- Review `git diff --cached` before committing to verify nothing unrelated was staged.
+- If you realize mid-commit that unrelated changes are mixed in, unstage them and commit only the related subset.

package/package/corpus/harnesses/copilot/instructions/github-actions.instructions.md

@@ -0,0 +1,87 @@
+---
+applyTo: ".github/workflows/**"
+paths:
+  - ".github/workflows/**"
+---
+<!-- cratis-ai: generated Copilot instructions. Do not edit; rules/ is the source. -->
+
+# GitHub Actions workflows: capacity, cost, and release discipline
+
+> **Why this rule exists.** On 2026-08-25 the organization's hosted runners starved for
+> most of a working day: every repository ran its scheduled jobs at the same minute,
+> hour-long jobs with no timeout occupied the shared concurrency pool, and a
+> comment-triggered assistant booted a runner for every comment in two repositories.
+> The remediation that followed is encoded here so it stays true.
+
+## The budget you are spending
+
+- The whole organization shares **one hosted-runner concurrency pool** (20 concurrent
+  jobs on the Free plan, 5 for macOS). Every queued job competes with every repository.
+- **Public repositories** run free on hosted runners; **private repositories bill every
+  minute** — Linux 1×, Windows 2×, macOS 10× — against a small monthly allowance.
+- The organization runs its own scale set (`cratis-arc`). Jobs there cost nothing and
+  do not touch the hosted pool.
+
+## Scheduling
+
+- **Never schedule on the top of the hour**, and never copy another repository's cron.
+  `0 6 * * *` in 36 repositories produced a 270-job stampede into 20 slots. Pick a
+  deterministic offset unique to the repository (minute 1–59, spread across 03:00–07:00 UTC).
+- A scheduled workflow that exists to keep coverage (nightly full matrix, health probe)
+  should run the *narrowest* thing that preserves the claim it exists to make.
+- **A scheduled workflow whose subject no longer exists is deleted, not left running.**
+  It still queues into the shared pool every day, and a scheduled no-op is the worst
+  kind: it never fails, so nothing ever draws attention to it. Deleting it is also the
+  only way to stop handing it whatever secrets it was passed — `Cratis/AI` ran a daily
+  package update against a repository with no package manifest of any kind, checking out
+  the full history under an organization-wide write PAT to find nothing to update.
+
+## Every job, always
+
+- **`timeout-minutes` on every job.** The default is 6 hours; one hung job holds a
+  pool slot for all of it. Tiers that work: quick checks 15, builds 30–45,
+  publish/release 60, integration/benchmarks 120.
+- **A `concurrency` group on every pull-request verification workflow** with
+  `cancel-in-progress: true`, keyed `${{ github.workflow }}-${{ github.ref }}`.
+  **Never** cancel-in-progress on publish, release, or deploy workflows — a cancelled
+  half-publish is worse than a queued one.
+
+## Matrices and operating systems
+
+- Run the full OS matrix on `schedule`/`workflow_dispatch`; run **Linux only on pull
+  request syncs**. Windows bills double and macOS ten-fold, and per-PR duplication has
+  to earn that cost with unique signal. (Measured before adopting this: 75 dual-OS runs
+  of one private repository, zero Windows-only failures.)
+- Skip the expensive job entirely for documentation-only changes: a cheap change-detection
+  job (`git diff --name-only HEAD^1 HEAD` on the merge commit) gating the build job.
+
+## Runners
+
+- Private-repository jobs belong on the organization scale set: `runs-on: cratis-arc`,
+  or a repository variable such as `${{ vars.<REPO>_RUNNER || 'ubuntu-latest' }}` so
+  routing changes without a code change.
+- On self-hosted runners, `actions/setup-dotnet` cannot write `/usr/share/dotnet`.
+  Set `DOTNET_INSTALL_DIR: ${{ runner.temp }}/dotnet` on the setup step.
+- **Never** route `pull_request`-triggered jobs of a *public* repository to self-hosted
+  runners — that hands code execution on our infrastructure to any fork.
+
+## Automation that writes back
+
+- A bot that pushes to a branch must **retry with `git pull --rebase`** — the branch
+  moves while the job runs, and a plain push loses the whole run to a non-fast-forward.
+- A bot's pre-push verification build must match the strictest configuration any CI in
+  the organization applies to the same commit (build `Release` when consumers enforce
+  analyzers there). Do not add `[skip ci]` to bot commits as a load optimization: the
+  downstream CI run is the only check that sees the merged result.
+- Comment-triggered agent workflows must gate on the trigger phrase in the job's `if:`
+  (for example `contains(github.event.comment.body, '@claude')`) so a runner only
+  starts when the agent is actually addressed.
+
+## Releases
+
+- A pull request that changes nothing outward-facing — workflow edits, CI configuration,
+  documentation — carries the **`no-release`** label, never `patch`. See
+  [`pull-requests.md`](./pull-requests.instructions.md). Merging config-only work under `patch` cut
+  four unintended releases on 2026-08-25.
+- Every repository's release-intent gate must accept `no-release`; a gate that only
+  accepts `major`/`minor`/`patch` forces exactly that mistake.

package/package/corpus/harnesses/copilot/instructions/glossary.instructions.md

@@ -0,0 +1,63 @@
+---
+applyTo: "**/*"
+---
+<!-- cratis-ai: generated Copilot instructions. Do not edit; rules/ is the source. -->
+
+# Cratis Glossary
+
+One precise line per load-bearing term, so the same word means the same thing everywhere. When a rule or skill uses one of these, this is the definition it intends.
+
+## Events & streams
+
+- **Event** — an immutable, past-tense **fact** that something happened; an `[EventType]` record. Never mutated; lives in the log forever.
+- **Event source** — the entity an event stream belongs to (the stream key); identified by an `EventSourceId<T>`.
+- **Event source id** — the strongly-typed identity of an event source (`EventSourceId<T>`). Implicit in the event context — **never** an event payload property.
+- **Event stream** — the ordered events for one event source within an event sequence.
+- **Event sequence** — a named, append-ordered log; `EventSequenceId` (the event **log**, **outbox**, **inbox**).
+- **Event log** — the default event sequence where domain events are appended.
+- **Outbox / inbox** — cross-service event sequences: a producer appends its public contract event to the outbox; a consumer observes the inbox.
+- **EventContext** — metadata traveling with an event (event source id, sequence number, occurred, causation/correlation, subject).
+
+## Read side
+
+- **Read model** — a `[ReadModel]` record holding queryable derived state, built by a projection or reducer; exposes `static` query methods.
+- **Projection** — declares how a read model is built by consuming **events** (model-bound attributes, or fluent `IProjectionFor<T>`); pure events→state, no side effects, never reads other read models.
+- **Reducer** — `IReducerFor<T>`; a "current state + event → next state" read-model builder; the last-resort escape hatch when projections can't express the transition.
+- **Reactor** — `IReactor`; observes events and produces **side effects** (notifications, commands, follow-up events). The "if this then that".
+- **Observer** — Chronicle's umbrella for anything consuming an event sequence (projection, reducer, reactor); carries subscription / replay / **quarantine** state. Projection replay and catch-up each walk the sequence in one globally ordered job step; a new catch-up failure stops that step. Full replay is inactive and completion does not resume a quarantined observer (Chronicle v19.50.1, `Documentation/concepts/observers.mdx`, `Observation/Jobs/{CatchUpObserver,ReplayObserver}.cs` under `Source/Kernel/Core/`).
+- **Sink** — where a read model is persisted (MongoDB, EF Core).
+- **AutoMap** — Chronicle's on-by-default mapping of matching event→read-model property names; **never call `.AutoMap()`**.
+- **Query** — a `static` method on a `[ReadModel]`; returns derived state, **snapshot** (one-shot) or **observable** (live).
+
+## Write side
+
+- **Command** — a `[Command]` record expressing an imperative **intent**; its public `Handle()` produces event(s) (or a response).
+- **Provide()** — the command method that fetches/computes data after validation/authorization and before `Handle()`; may short-circuit with a `ValidationResult`.
+- **Causation chain** — the ordered links saying how an append came about (root process → command → …), each carrying properties. A command records its **name and its property values** there, so an event says what the command was asked to do; the chain lives in the event log and is as permanent as the events.
+- **Constraint** — `IConstraint`; an **append-time** invariant (uniqueness / concurrency) enforced at the event-store level.
+- **DCB (Dynamic Consistency Boundary)** — enforcing a state-dependent rule under concurrency over explicitly enrolled event-state reads: stream decisions/exact scopes or protected, admitted projection decision reads. Plain injected models and `Result<TEvent, ValidationResult>` alone are advisory, not a guard.
+- **Consistency boundary** — the scope within which an invariant holds atomically (an event source, a routed stream, or the event state enrolled by an admitted protected decision read).
+- **EventForEventSourceId** — self-describing wrapper to append an event to a **specific** (cross-stream) event source, from a command `Handle()` or from a reactor handler (reactor support has shipped since Chronicle 15.35). It carries the event stream type and id, source type, subject, occurred time, tags and causation, so it is also how a reactor sets those explicitly.
+- **ReactorDelivery** — the identity of one delivery of one event to one reactor partition; declare it as a handler parameter and Chronicle passes it in. Stable across a replay and across recovering a failed partition, so a receipt kept under its `Id` is what makes a side effect survive re-delivery. An identity, not a guarantee — Chronicle does not know whether the effect ran.
+
+## Structure & types
+
+- **Slice** — the vertical unit of one behavior (command + events + projection + read model + component + specs), created/changed/deleted together.
+- **Slice types** — **State Change** (command → events), **State View** (events → read model), **Automation** (events → side effect, including a follow-up command or event — a Screenplay `produces` / `invokes`), **Translation** (data from *outside* the model's own facts → our own facts: an external system's or another service's data recorded as events we own, keeping the external fact distinct from the local one). A reactor that turns our own event into a follow-up event or command is an Automation, not a Translation.
+- **Concept** — a `ConceptAs<T>`, a strongly-typed wrapper over a primitive domain value (never raw `Guid`/`string`/`int`).
+- **EventSourceId<T>** — the strongly-typed event-source identity; derive entity identities from this, not `ConceptAs<Guid>`.
+- **Proxy** — the generated TypeScript command/query client, produced from C# on a **Debug** build; carries a `// @generated by Cratis` header and is never hand-edited.
+
+## Compliance & multi-tenancy
+
+- **Subject / `[Subject]`** — the natural person a piece of PII belongs to (for GDPR erasure); defaults to the `EventSourceId<T>` identity.
+- **`[PII]`** — marks an inherently personal value so Chronicle can manage/erase it.
+- **`[NotAudited]`** — an **Arc** marking (`Cratis.Arc.Chronicle.Commands`, not a Chronicle type) for a value that is secret but *not* personal data (password, token, API key), so it is never written to the causation chain. Withholds only; it does not encrypt the value, so pair it with `[Encrypted]` for an operational secret. It never enrolls a value in erasure the way Chronicle's `[PII]` does.
+- **`[Encrypted]`** — a Chronicle marking (`Cratis.Chronicle.ProtectedValues`, Chronicle 19.32.0+) that encrypts an **operational secret** (API key, token, a company's bank account number) at rest on the event, without erasure. It does not keep a command input off the causation chain, so a secret gets `[Encrypted]` **plus** `[NotAudited]`. Never combine it with `[PII]` (`CHR0053`); never put it on an event source id (`CHR0052`).
+- **`[OnceOnly]`** — marks a reactor handler (or the whole reactor class) as non-replayable: Chronicle skips it for every event arriving as part of a **replay** — observer rewind, redaction, revision. Replay-exclusion only, not exactly-once, not a per-event-source run limit or deduplication; ordinary catch-up, crash redelivery and failed-partition recovery can run the handler again (Chronicle v19.50.1, `Documentation/code-analysis/CHR0022.mdx`). Use a `ReactorDelivery` receipt for that case.
+- **Namespace / tenant** — Chronicle isolates tenants by **namespace**; each namespace has its own events, observers, and read models.
+
+## Profiles
+
+- **Application profile** — building an app *on* Cratis (event-sourced CQRS, vertical slices, MVVM frontend).
+- **Framework profile** — contributing to a Cratis framework repo *itself* (Arc, Chronicle, Fundamentals, Components — libraries). See `framework.md`.

package/package/corpus/harnesses/copilot/instructions/go-engineering.instructions.md

@@ -0,0 +1,61 @@
+---
+profile: framework
+applyTo: "**/*.go,go.mod,go.sum,**/go.mod,**/go.sum"
+paths:
+  - "**/*.go"
+  - "go.mod"
+  - "go.sum"
+  - "**/go.mod"
+  - "**/go.sum"
+---
+<!-- cratis-ai: generated Copilot instructions. Do not edit; rules/ is the source. -->
+
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Go framework parity and module releases
+
+`cratis/engineering/go` composes the Go language profile. Repository-owned
+context, not this rule, defines module paths, layout, quality-gate commands,
+release configuration and the exact C# parity target.
+
+## Preserve the product contract
+
+Before changing a Go port, inspect its owning C# API, implementation and tests
+at the parity target revision. Translate concepts idiomatically, not literally:
+context plus errors, constructors/options, explicit registration, named values
+and deliberate stream lifetimes. Do not change sibling implementations to
+accommodate the port.
+
+Preserve routes, verbs, camelCase JSON where contracted, envelopes, UUID byte
+order/encoding, protobuf fields and RPCs, tenancy, event ordering, retry and
+checkpoint semantics. Record each deliberate divergence in repository-owned
+parity documentation with source path/revision, Go surface, status, executable
+evidence and caller migration implications. A compilation check is not wire,
+streaming or lifecycle parity. Unsupported behavior fails explicitly, never as
+no-op success. Keep a limited conformance result limited; do not claim whole-product parity.
+
+## Release compatibility
+
+- Review signatures, interface growth, public struct comparability, wrapped
+  errors, defaults and wire behavior. API-diff tools supplement consumer tests.
+- Experimental v0 breaking APIs require a **minor** bump and migration notes,
+  not a patch. From v1, incompatible APIs need a planned major version.
+- Apply exactly one release-intent label under the repository's PR policy.
+  Check how its configured `Cratis/release-action` maps v0 changes before release.
+- Root modules use immutable `vX.Y.Z` tags created through the configured
+  release-action workflow. Do not create duplicate manual releases or move tags.
+  Nested modules need their own explicitly reviewed tag policy.
+- Plan `/v2` migrations across the module directive, imports, examples, consumers
+  and parallel support. Neither v0 nor v1 gets a `/v0` or `/v1` suffix.
+- Correct a bad release with a new release and, when appropriate, documented
+  retractions in a newer published version. Retraction does not erase downloads
+  or prohibit an explicit request for the old version.
+- Verify release consumption without local workspace/replacement assistance.
+  Source/tag availability, module download, consumer compilation and proxy/pkg.go.dev
+  indexing are separate results. Indexing delay never justifies retagging.
+
+Adapted from the repository-owned
+[Chronicle.Go parity rule](https://github.com/Cratis/Chronicle.Go/blob/v0.9.1/.cratis/ai/rules/go-cratis-parity.md)
+and [repository-owned module release guidance](https://github.com/Cratis/Chronicle.Go/tree/v0.9.1/.cratis/ai/skills),
+with repository-specific paths and commands removed.