@cratis/pi 0.0.1 → 2.0.1

package/package/corpus/skills/cratis-engineering-effect-boundaries/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: cratis-engineering-effect-boundaries
+description: Apply the Cratis effect-boundary contract when writing or reviewing code that publishes, persists, generates, propagates, or releases. On those boundaries partial success is failure - no catch-and-continue, no defaulting to success on an unknown outcome. Use when a degraded run could still report success; defer style questions and specification authoring to their own workflows.
+license: LICENSE
+---
+
+# Effect boundaries fail loudly
+
+An **effect boundary** is the point where work leaves the process and becomes
+something other people observe: a package published, a row written, a file
+generated, content propagated to other repositories, a release cut.
+
+The contract:
+
+> On an effect boundary, **partial success is failure.** No catch-and-continue,
+> no defaulting to success on an unknown outcome. A degraded operation must fail
+> the operation, surface the delta, or emit an explicit degraded-mode signal.
+
+Silent failure is the dominant recurring bug archetype across Cratis. The
+2026-08-24 organization-wide review found one disease with six manifestations,
+in the release action, the Arc proxy generator, Stage, the Chronicle container
+host, Chronicle constraint enforcement, and corpus propagation. They are written
+out in [failure-archetypes.md](references/failure-archetypes.md); read them
+before deciding that your case is different.
+
+## When you need this
+
+- You are writing or reviewing a `catch` around an operation with an effect —
+  publish, write, generate, copy, notify, tag, release.
+- An operation processes a set and some members can fail independently: a
+  fan-out, a batch, a matrix, a per-file generator.
+- A call returns an outcome you did not model: an unexpected status code, a
+  null, an empty result, a timeout.
+- Two implementations of one interface exist and only one of them really
+  enforces the behavior — an in-memory or SQL sibling of a real store.
+- A host, container, or long-running process can reach a "started" state while
+  the thing it started has already thrown.
+
+## When you do not
+
+- **Pure computation with no effect.** A parser that returns a partial tree for
+  a caller that inspects it is not an effect boundary.
+- **A retry that will still report the final outcome truthfully.** Retrying is
+  not swallowing; reporting success after the retries also failed is.
+- **A genuinely optional enrichment whose absence is stated in the result.** An
+  optional cache warm that records `cache: skipped` is a degraded-mode signal,
+  which is exactly what this contract asks for.
+- **Style, naming, or structure questions.** Those belong to the C# and
+  TypeScript conventions.
+- **Deciding whether an operation should exist at all.** That is a product or
+  scope ruling, not an error-handling one.
+
+## Steps
+
+1. **Name the boundary before you write the handler.** Say out loud what leaves
+   the process: which package, which rows, which files, which repositories.
+   If nothing leaves, this contract does not apply and you can stop here.
+2. **Enumerate the outcomes the call can produce, including the ones you did not
+   design for.** An unexpected status code, an empty response, and a timeout are
+   outcomes. A handler that maps everything it did not enumerate onto success is
+   the defect.
+3. **Choose one of the three permitted responses to a degraded outcome, and say
+   which one you chose.** Fail the operation; or complete and surface the delta
+   in the result; or emit an explicit degraded-mode signal the caller must
+   handle. Anything else is catch-and-continue.
+4. **Make partial fan-out visible in the aggregate, not just in the log.** Count
+   attempted, succeeded, and failed, and put all three in the returned result
+   and the summary line. "29 of 36 succeeded" and "36 of 36 succeeded" must not
+   produce the same output.
+5. **Refuse to convert an unknown into a pass.** An outcome the code could not
+   classify is `indeterminate`. Report it as its own state; never roll it up
+   into the success count.
+6. **Check the sibling implementations of the same interface.** When a real
+   store enforces a constraint, its in-memory and SQL siblings must enforce the
+   same one or throw `NotSupported`. A sibling that silently accepts what the
+   real one rejects makes every specification that uses it pass vacuously.
+7. **Make the process state follow the work.** If startup threw, the host is not
+   `Running`. A liveness or readiness state that survives a failed start is a
+   lie the orchestrator will believe.
+8. **Plant the failure and watch it surface.** Force the degraded outcome —
+   inject the status code, delete an input, fail one fan-out member — and
+   confirm the operation fails, the delta appears, or the degraded signal fires.
+   A boundary whose failure path was never executed is not known to have one.
+
+## What breaks
+
+Every item below is a real Cratis defect, not an illustration. Detail and issue
+references are in [failure-archetypes.md](references/failure-archetypes.md).
+
+- **A swallowed conflict reported as a successful release.** The release action
+  caught a 422 from a concurrent publish and reported the release as done. The
+  version was never published, and the only artifact that said so was a caught
+  exception nobody saw.
+- **A generator that degrades silently.** The Arc proxy generator emitted fewer
+  proxies than its inputs implied and exited zero. The failure shows up much
+  later as a missing TypeScript type, far from the generator that dropped it.
+- **A renderer that quietly renders less.** Stage produced degraded output on a
+  path that reported success, so the difference between correct output and
+  partial output was invisible at the boundary that produced it.
+- **A container that stays `Running` after startup threw.** The Chronicle host
+  reported healthy while the thing it hosts had already failed to start, so the
+  orchestrator kept routing to it.
+- **A constraint that only one implementation enforces.** Chronicle unique
+  constraints were not enforced on the SQL and in-memory storage providers.
+  Every specification exercising them passed while proving nothing.
+- **A fan-out that succeeded 29 times out of 36 and said "done".** Corpus
+  propagation aggregated per-target results into a single success, so seven
+  repositories silently did not receive the change.
+
+The shared symptom: **the failure is discovered downstream, by someone who
+cannot see the boundary that caused it.** That is what makes this archetype
+expensive rather than merely annoying.
+
+## How it is proven
+
+- **The failure path was executed.** Name the planted defect and the observed
+  result: the injected status code, the removed input, the failed fan-out
+  member — and what the operation did in response.
+- **Counts appear on success.** The clean run reports how many subjects it
+  attempted and how many succeeded. A bare "OK" cannot be distinguished from a
+  run over an empty set.
+- **Exit codes carry the verdict.** `0` ran clean, `1` found defects, `2` could
+  not run. A wrapper that exits `0` because the wrapper finished has thrown the
+  child's verdict away; check the child's status and, in a pipeline, the status
+  of every stage.
+- **The degraded signal is asserted, not just emitted.** A specification reads
+  the delta or the degraded-mode field and fails when it is absent.
+- **Sibling implementations are covered by the same specification.** The test
+  that proves the constraint runs against every implementation of the interface,
+  not only the one that enforces it.

package/package/corpus/skills/cratis-engineering-effect-boundaries/references/failure-archetypes.md

@@ -0,0 +1,133 @@
+# The six cited failure archetypes
+
+These are the six manifestations the 2026-08-24 Cratis organization-wide review
+identified as one disease: silent failure on an effect boundary. Each is a real,
+tracked defect. Read them as the shape of the mistake, not as a list of fixed
+bugs — the same shape keeps reappearing in new code.
+
+For each: what the boundary was, what the code did, why the failure was
+expensive, and what the contract required instead.
+
+## 1. A swallowed conflict reported as a successful release
+
+*release-action #178.*
+
+**Boundary.** Publishing a version — the most public effect there is.
+
+**What happened.** A concurrent publish made the registry return HTTP 422. The
+action caught it and continued, and the run reported the release as successful.
+
+**Why it was expensive.** The one artifact that recorded the truth was an
+exception nobody saw. Everything downstream — release notes, subscriber pins,
+the assumption that the version existed — was built on a success that had not
+happened. Nothing later in the pipeline re-checked the registry, because a
+successful publish is normally proof enough.
+
+**What the contract required.** A 422 on publish is an outcome that must be
+classified, not caught. Either the version already exists and is byte-identical
+(report it as already-published, explicitly), or it does not and the publish
+failed. "Caught an exception, carried on" is neither.
+
+## 2. A generator that degrades silently
+
+*Arc #2571, #2564, #2527 — the proxy generator.*
+
+**Boundary.** Generating TypeScript proxies from C# sources. The output is what
+the whole frontend compiles against.
+
+**What happened.** The generator produced fewer proxies than its inputs implied
+and still exited zero.
+
+**Why it was expensive.** The symptom appears far from the cause: a missing
+TypeScript type in a component, at a point where nobody is thinking about the
+generator. The natural first hypothesis is that the frontend is wrong.
+
+**What the contract required.** A generator that consumed N inputs and emitted
+fewer than N artifacts reports the delta and fails, or names the skipped inputs
+and why. Reporting the count on success is what makes the shortfall visible at
+all: "generated 41 of 41" and "generated 38 of 41" have to read differently.
+
+## 3. A renderer that quietly renders less
+
+*Stage #53.*
+
+**Boundary.** Rendering output that someone will look at and act on.
+
+**What happened.** A degraded rendering path produced partial output while
+reporting success.
+
+**Why it was expensive.** Partial output looks like output. There is no error to
+search for and no count to compare, so the difference between correct and
+degraded is invisible at exactly the boundary that produced it.
+
+**What the contract required.** A renderer that could not render something says
+so in its result — a degraded-mode signal the caller has to handle, not a log
+line at the end of a stream nobody reads.
+
+## 4. A container that stays `Running` after startup threw
+
+*Chronicle #3682.*
+
+**Boundary.** Process and container lifecycle — the state an orchestrator reads
+to decide whether to send traffic.
+
+**What happened.** Startup threw, and the container remained in `Running`.
+
+**Why it was expensive.** The orchestrator believed the reported state and kept
+routing to a host that had never finished starting. The failure surfaces as
+inexplicable behavior in callers rather than as a failed start.
+
+**What the contract required.** Process state follows the work. If startup
+failed, the process exits non-zero or reports unhealthy. A liveness state that
+survives a failed start is not a degraded signal, it is a false one.
+
+## 5. A constraint that only one implementation enforces
+
+*Chronicle #3744 — unique constraints on the SQL and in-memory providers.*
+
+**Boundary.** Persistence, and the invariant the store is supposed to guarantee.
+
+**What happened.** Unique constraints were not enforced on the SQL and in-memory
+storage providers, while the primary provider enforced them.
+
+**Why it was expensive.** This is the worst variant, because it does not fail —
+it makes specifications pass vacuously. Every test written against the
+in-memory provider proved that duplicate writes were accepted, and read as
+proof that the constraint worked. The gap only appears in the one environment
+nobody tests against by default.
+
+**What the contract required.** An alternate implementation of an interface
+matches the primary one's *semantics*, not just its signature. Where it cannot,
+it throws rather than silently accepting. The specification that proves the
+constraint runs against every implementation.
+
+## 6. A fan-out that succeeded 29 times out of 36 and said "done"
+
+*The retired corpus propagation.*
+
+**Boundary.** Propagating content into other repositories — an effect in 36
+places at once.
+
+**What happened.** Per-target results were aggregated into a single overall
+success. Seven repositories did not receive the change, and the aggregate said
+nothing about it.
+
+**Why it was expensive.** Nobody knew which seven. Recovering meant re-deriving
+the target list and comparing every repository by hand, long after the run's
+own record of what happened had been lost to log rotation.
+
+**What the contract required.** Attempted, succeeded, and failed are three
+separate numbers, all three in the returned result and the summary line. A
+fan-out that cannot name its failures has not reported its outcome. "29 of 36"
+is not a success with a footnote; on an effect boundary it is a failure.
+
+## What the six have in common
+
+- The failing code **caught something and continued**, or **mapped an
+  unmodelled outcome onto success**.
+- The success signal was **produced by the layer that failed**, so no later
+  check re-derived it.
+- The cost was paid **downstream, by someone who could not see the boundary**.
+- In the two worst cases (2 and 5) the defect made verification itself
+  meaningless: a green generator run and a green specification suite that were
+  both measuring nothing.

package/package/corpus/skills/cratis-fundamentals-concept/verification.json

@@ -0,0 +1,8 @@
+{
+  "skill": "cratis-fundamentals-concept",
+  "input": "Create a strongly typed value for a domain concept.",
+  "fixtures": [],
+  "assertions": [
+    { "kind": "skill-contains", "value": "ConceptAs<T>" }
+  ]
+}