feat(effects): built-in effect library and the custom-unit authoring contract

[FelineStateMachine]

Closes #141. Grows the #139 effect machinery (s.effect, per-obligation journaling, at-least-once delivery) into a tiered standard library and formalizes the contract for authoring custom units. Single PR covering all six issue sections; the one deferred item is called out below.

1. The authoring contract (package/schema/effects.ts)

• EffectContext gains op and writeCreatedAt, so a unit can see the operation and measure the saved→fate latency.
• Failure severity. New PermanentEffectError / isPermanentEffectError: a handler throws it to retire the obligation immediately (a call the receiver will keep refusing) instead of re-arming until maxAttempts. An ordinary throw stays retryable. The ledger honors the distinction and both are counted in diagnostics.
• Naming/registration rules are unchanged and now documented as contract: app-unique durable names, fail-fast on collision. Anonymous built-ins take their identity from declaration order (anonymousEffectName), documented with the same orphaning caveat as a rename.
• requireMutationRuntime exposes the runtime seam so every built-in is on the public authoring surface — nothing private. s.log was reviewed against this and already qualified.

2. Built-in units (package/schema/effect-library.ts), tiered by risk

Observation — s.trace(label?) (saved→fate span in diagnostics, OpenTelemetry-shaped, no vendor coupling), s.debug() (dev-only timeline, records nothing in a PROD bundle). s.log stays in the core beside its runtime recorder.

Data-internal — s.notice(config) (durable, UI-agnostic message queue, idempotent by journal id — closes the "a rejected write flashed success" failure mode), s.mark(table, config) (patch the row when its fate resolves; absolute/convergent patch; skips a rolled-back insert), s.chain(verb, toInput) (issue a follow-up verb on synced, no saga API).

External — s.webhook(url, opts?) (POST row + fate with the journal id as Idempotency-Key; 4xx → permanent, 5xx/429/network → retryable; default 24-hour delivery window since receiver keys expire, null opts out).

3. Runtime

• notice-queue.ts — durable queue (OPFS → localStorage → memory), idempotent enqueue, TTL + dismissal, subscribe; drops entries expired-while-away on load.
• write-ledger.ts installs recordTrace/recordDebug/enqueueNotice/applyMark, owns the queue singleton, and exposes public listNotices/subscribeNotices/dismissNotice/dismissAllNotices.
• diagnostics.ts — effectTraces, effectDebugTimeline, activeNotices.

4. Preact

useNotices() hook + <Notices /> component render the durable queue as an ARIA live region; a toast stack is a userland wrapper over the same hook.

5. Docs

docs/effects.md — the library reference, the authoring contract, and a worked custom unit modeled on a built-in. Teaching-path link added to nouns-and-verbs.md (declare → observe → make fate data → compose → reach outside), plus README reference entries.

6. Tests

• Per-unit: happy path, rejection path, and idempotency mechanism (trace/notice/mark/chain/webhook).
• notice-queue: idempotent enqueue, TTL retirement, persisted reload dropping expired entries.
• Ledger: a PermanentEffectError retires on the first failure without exhausting attempts (alongside the existing quarantine test).
• A custom unit built purely against the public contract — both a contract test and the guide's worked example.

Verification

• deno task check green end-to-end (fmt, lint, doc, doc:closure, links, all suites — 21 JSR entrypoints).
• deno task build green; manifest updated for effect-library.ts, notice-queue.ts, Notices.tsx, use-notices.ts.
• Reference app adds s.trace("task-added") to addTask (dogfood); starter mirror + snapshot regenerated.

Deferred (follow-up)

The reference app's hand-rolled task-notice (publishNotice/useTaskNotice) is exactly the pattern s.notice replaces, but migrating it is a focused island refactor with its own snapshot churn — better as a separate PR than mixed into the library landing.

[FelineStateMachine]

Review pass (multi-agent + Codex) — findings addressed

Ran a three-agent correctness review plus a Codex release-readiness read. The converging headline was the anonymous-unit durable identity, which Codex flagged as the release blocker. Fixes landed in 48a2820:

Finding	Severity	Resolution
Anonymous notice/mark/chain named by a global module-load counter → a re-armed obligation could bind to the wrong unit across reloads (wrong follow-up verb for chain)	HIGH	Named <verb>#<position> at mutation() time — identity independent of module load order; reordering effects within one verb is the only footgun, documented
s.trace/s.debug/s.webhook fixed names collide when reused across verbs	(latent)	Content-named units now share one instance (cachedBuiltin); webhook keys on url+config
Notice queue: entry enqueued during the async load() window is clobbered	HIGH	load() merges persisted + in-flight entries instead of overwriting
Notice queue: TTL sweep on list() never persisted/emitted → activeNotices drift	MEDIUM	list() is a pure read; retirement in sweep() on a periodic timer; count computed from the live view
mark patch denial / vanished row → quarantine spam	LOW/MED	applyMark best-effort (swallows); documented as a convenience, not a guarantee
Notices aria-live region absent until first notice → first announcement dropped	MED	Region stays mounted (hidden when empty); custom children keyed

Verified sound by the reviewers (no change): webhook 4xx/5xx/429 classification, expiresAfterMs: null opt-out, tableless placeholder, notice idempotency key, persistence ordering, useNotices subscription lifecycle.

New tests cover verb-scoped anonymous naming, content-name sharing across verbs, and the notice boot-merge. deno task check + deno task build green.

Codex release-readiness note (for whoever cuts 0.9.0)

Verdict was NO-GO immediately, GO after a short stabilization gate. The blocking item (anonymous identity) is now resolved. Remaining pre-tag recommendations, not gated on this PR: a consumer-style import test over every new public symbol; a durable-format registry documenting the effect-journal and notice-queue on-disk formats (version + corruption/forward-version behavior); and a changelog with a "Persistence" section. Tracking these separately.