@cratis/pi 7.95.0 → 7.96.0

package/package/corpus/skills/cratis-chronicle-cli-operations/SKILL.md

@@ -247,6 +247,10 @@ store gets replayed. A failed partition you have not yet explained is not a
 thing to clear: read it, fix the handler, then replay. Clearing it first
 destroys the evidence and the same failure returns on the next event.
 
+## Compare a namespace with its model
+
+`cratis screenplay conform-namespace` is read-only and sits outside the `chronicle` group and its guard: it reads the registry, observers and event metadata of one namespace and compares them with a `.play` model. Use it for a post-deploy check; the procedure and exit codes are in `cratis-screenplay-render-and-gap-fill` [post-deploy check](../cratis-screenplay-render-and-gap-fill/references/post-deploy-check.md). Its exit `4` is a refused read: obtain a context with read access, never widen permissions.
+
 ## What the CLI cannot do
 
 There is no `delete`, `purge`, `redact`, or `revise` command. Event redaction

package/package/corpus/skills/cratis-screenplay-render-and-gap-fill/SKILL.md

@@ -205,6 +205,7 @@ Read [references/neighbouring-skills.md](references/neighbouring-skills.md) when
 - `references/renderability-gate.md` - classify the probe's codes, estimate the blast radius.
 - `references/delivery-protocol.md` - inputs, commands, reading results, `Customizations/`.
 - `references/gap-fill-handoff.md` - the brief for `slice-implementer`, fallback record flow.
+- `references/post-deploy-check.md` - after deployment, compare the model with a running namespace using `cratis screenplay conform-namespace`; read-only, with its exit codes.
 - `references/drift-and-fallback-record.md` - drift, publication refusals, the fallback record, code changed since verification.
 - Read `references/hand-written-changes.md` when investigating hand-written changes against the contract; it defines finding kinds, resolution routing and the report.
 - Read `references/worked-example.md` when preparing the classification and report for a refused render; it contains a complete model.

package/package/corpus/skills/cratis-screenplay-render-and-gap-fill/references/post-deploy-check.md

@@ -0,0 +1,57 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Post-deploy check: does the running namespace match the model
+
+After a render is delivered and deployed, `cratis screenplay conform-namespace` compares the
+compiled model with what one running Chronicle namespace holds. Render verification and
+`conform` never see the running store; this check does. How to read its verdict is in the
+toolchain's [observation comparison](../../cratis-screenplay-toolchain/references/observation-comparison.md),
+including the CLI version it needs.
+
+## Run it
+
+```bash
+cratis screenplay conform-namespace <model-root> --event-store <store> --namespace <namespace> -o json-compact
+```
+
+- Pass the model root (the root `.play` file or the folder of one application), never a single
+  fragment of a folder.
+- Name the event store and namespace explicitly. The built-in default is never assumed, and a
+  name differing only in case is reported, not chosen for you.
+- `--sequence` selects another sequence (default `event-log`); `--from`, `--to` and `--max-events`
+  bound the scan (default `100000` events, up to the tail captured at the start).
+- Add `--fail-on-drift` in a pipeline so the exit code carries the verdict.
+
+## Authorization and effect
+
+The command is read-only: it never replays observers, appends events or changes the model, and
+it is not a `chronicle` command, so the Chronicle mutation guard does not apply. It still needs a
+connection to the target server with permission to read the event type registry, observers and
+event metadata. Use the context the user named; resolve it as in `cratis-chronicle-cli-operations`.
+Do not log in, switch contexts or point at another environment to make it work. A production
+namespace is checked only when the request named it.
+
+## Act on the result
+
+| Exit | Meaning | Act |
+| --- | --- | --- |
+| `0` | The comparison ran | Read `hasDrift` and the findings; drift alone does not fail without `--fail-on-drift` |
+| `7` | Known drift (with `--fail-on-drift`) | Triage each Drift finding: fix the model through the model workflow, or fix the deployment; never edit a rendered file to silence it |
+| `8` | Inconclusive (with `--fail-on-drift`), or the scan was interrupted | Report inconclusive; widen coverage or wait for lagging reactors, then rerun once |
+| `5` | Model errors, missing store, namespace or sequence, invalid bounds | Fix the input; nothing was compared |
+| `2` | Server unreachable | Report the connection failure; do not retry through another route |
+| `3` | Chronicle refused or failed a read | Report it; no snapshot was built |
+| `4` | Authorization missing for a read | Ask the user for a context with read access; do not widen permissions yourself |
+
+Exit `4` for a refused read and exit `8` for an interrupted scan require Cratis CLI 3.89.1 or later
+(`cratis --version`). On an older CLI, treat any exit other than `0` and `7` as "not compared".
+
+A failed read is never an empty store.
+
+## Report
+
+Record the verdict next to the deployment: model identity, event store, namespace, sequence,
+examined range against the captured tail, `Complete`, Drift findings and Unknown reasons. A
+partial or inconclusive result is reported as such, never as a pass. Remediation that changes
+the model or code returns to the render and gap-fill procedure.

package/package/corpus/skills/cratis-screenplay-toolchain/SKILL.md

@@ -65,7 +65,7 @@ superseded statement needs context; exceptions do not change the contract.
 | | Standalone `screenplay` | `cratis screenplay ...` |
 | --- | --- | --- |
 | Check root | `screenplay <root> --warnaserror --no-color` | `cratis screenplay validate <root> --warnings-as-errors -o json-compact` |
-| Scope/checks | `--scope <address>`, `--check <names>`; a scoped pass is not whole-application success | `validate --executable` (bundled binder, no write), `--check <names>`, `--scope`; `render --scope`/`--check`; `cratis screenplay conform` |
+| Scope/checks | `--scope <address>`, `--check <names>`; a scoped pass is not whole-application success | `validate --executable` (bundled binder, no write), `--check <names>`, `--scope`; `render --scope`/`--check`; `cratis screenplay conform`, `cratis screenplay conform-namespace` |
 | Declared gate | `screenplay <root> --print-gate`, `--format json`, `--no-gate-file` | `validate <root> --print-gate`, `--no-gate-file`; the same `screenplay.json` |
 | Reference execution | `screenplay test <root>` or MCP `run-specifications` | Discover bundled MCP capability; target tests are not V4 |
 | MCP | `screenplay mcp <root>`; discover schemas | `cratis screenplay mcp [root]`; registered by `cratis ai install` |
@@ -96,6 +96,8 @@ for MCP initialization, source identity and reporting. Without MCP, report
 version, source identity and any blocking codes; MCP `modelRevision` is semantic,
 not the source identity.
 
+Read [observation comparison](references/observation-comparison.md) when asking whether a running namespace holds what the model declares, or when reading a `conform-namespace` verdict. It differs from model comparison (model versus model) and `conform` (model versus code).
+
 ## Subsets (write from the one your mode needs)
 
 - **Design**: every construct family parses; use it to model first. Compiled shapes:

package/package/corpus/skills/cratis-screenplay-toolchain/references/observation-comparison.md

@@ -0,0 +1,83 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Observation comparison: model versus running store
+
+Requires Cratis CLI 3.85.0 or later (`cratis --version`) for `cratis screenplay conform-namespace`, and
+3.89.1 or later for the refused-read exit `4` and clean Ctrl+C handling described below; older CLIs lack
+the verb. Without it, report "observation comparison not run" and do not substitute `conform`.
+
+## Three comparisons, three questions
+
+| Comparison | Compares | Answers | Does not answer |
+| --- | --- | --- | --- |
+| Model comparison (`semantic-diff`) | two authored models | what changed between revisions | whether anything runs |
+| `cratis screenplay conform` | a model with source code | whether hand-written code realizes the slice | whether the deployed system did it |
+| Observation comparison (`cratis screenplay conform-namespace`) | a compiled model with a bounded snapshot of one running Chronicle namespace | do the observed event relationships agree with the model | payload agreement, behavior, specifications passing |
+
+Reach for observation comparison after a deploy, or when a namespace may have diverged from the
+model: are the declared event types registered, were undeclared events appended, did each command
+and reactor append what the model says it produces, and are the declared reactions subscribed.
+It reads event metadata only, never payloads, event source ids or command values.
+
+## Read the verdict
+
+The host reports three verdict values and a separate completeness flag.
+
+| `HasDrift` | Meaning | Action |
+| --- | --- | --- |
+| true | Known drift exists, even if other evidence is incomplete | Triage each Drift finding |
+| false | The comparison was complete and found no drift | Report no drift, with the scope |
+| null (omitted in JSON, `inconclusive` in human output) | Drift is neither established nor ruled out | Report inconclusive; never turn it into "no drift" |
+
+`Complete` is true only when the scan covered the sequence fully **and** no finding is Unknown.
+A report can have `HasDrift` true and `Complete` false.
+
+## Finding outcomes
+
+| Outcome | Reading |
+| --- | --- |
+| Drift | The store disagrees with the model on something the evidence establishes |
+| Informational | A difference that is not a contradiction, such as a declared event that has not yet been appended |
+| Unknown | The evidence cannot establish agreement or disagreement; the reason says why |
+| Excluded | Outside this application, such as a foreign event or a platform consumer |
+
+Typical Drift: a declared event type missing from the registry, an undeclared event appended,
+an undeclared generation, a mapped producer appending outside its declared productions, or a
+declared reaction with no subscription.
+
+## Unknown reasons
+
+| Reason | What to do |
+| --- | --- |
+| `PartialCoverage` | Widen the range (`--from`, `--to`, `--max-events`) and rerun |
+| `UnattributedEvents` | Events without a command or reactor in their causation; the producer cannot be judged |
+| `UnmappedProducer`, `UnmappedConstruct`, `AmbiguousIdentity` | The model name did not map to exactly one observed identity; do not guess one |
+| `OpaqueReaction`, `ConditionalProduction`, `DescribedHandler`, `NonEventTrigger` | The model does not state the production unconditionally, so absence proves nothing |
+| `ConsumerBehind` | The reactor has not reached the tail; wait for it and rerun |
+| `ConsumerKindNotCompared` | Projections and reducers are not compared; their subscriptions are never evidence either way |
+
+## Pitfalls
+
+- "No matching appends within coverage" does not mean the command or reactor never ran. It is
+  Informational: no attributed event shows that it ran inside the examined range.
+- Scanned absence under partial coverage is Unknown, never drift. Registry checks are the
+  exception: the event-type registry is read in full, so a declared event that is not registered
+  (`EventNotRegistered`) is drift whatever the coverage. A missing production is drift only
+  with full coverage, an unambiguous producer mapping, another event attributed to that producer,
+  and no unattributed appends of the expected type.
+- Presence is stronger than absence: an undeclared event that was appended is drift even under
+  partial coverage.
+- A clean result proves only the relationships it checked. Read the report's not-established
+  statements; they list the limits.
+- Event generations are approximated: each appended event counts against the highest registered
+  generation of its type.
+- One sequence is compared per run, `event-log` by default.
+
+## Report it
+
+State the verdict value, `Complete`, the event store, namespace and sequence, the examined range
+against the captured tail, each Drift finding with its statement, and each Unknown reason. The
+post-deploy procedure and its exit codes are in
+[post-deploy check](../../cratis-screenplay-render-and-gap-fill/references/post-deploy-check.md).
+Run the comparison through the CLI; no MCP tool offers it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cratis/pi",
-  "version": "7.95.0",
+  "version": "7.96.0",
   "description": "Configuration-aware Cratis AI integration for Pi",
   "type": "module",
   "files": [