@nifrajs/cli 2.0.0 → 2.1.0

package/dist/cli.js

@@ -112,7 +112,7 @@ routes/ from the current directory. Run from your project root.
 Port: \`dev\` and \`start\` share the default ${DEFAULT_DEV_PORT}. Override with \`--port <n>\` (alias \`-p\`) or the
 \`PORT\` env var (\`--port\` wins over \`PORT\`, which wins over the default).`;
 // Kept in lockstep with packages/cli/package.json by check:publish's version-consistency gate.
-const CLI_VERSION = "2.0.0";
+const CLI_VERSION = "2.1.0";
 // A render adapter + nifra server are opaque to the CLI (it just forwards them); cast at the seam.
 const asAdapter = (v) => v;
 const asBunPlugins = (v) => v;

package/dist/mcp-http.js

@@ -19,7 +19,7 @@ import { loadTypesCorpus } from "./types-search.js";
 // tool factory + the transport core from one entry: `import { respondMcpHttp, docsTools } from "@nifrajs/cli/mcp"`.
 export { docsTools } from "./mcp-docs-tools.js";
 // Kept in lockstep with packages/cli/package.json by check:publish's version-consistency gate.
-const VERSION = "2.0.0";
+const VERSION = "2.1.0";
 const SERVER_INFO = { name: "nifra-docs", version: VERSION };
 const DOCS_HEALTH = "nifra docs MCP — POST JSON-RPC 2.0 here (methods: initialize, tools/list, tools/call). Tools: nifra_docs, nifra_example.";
 /** The two project-independent tools, reading the package's bundled corpus from disk (CLI use). */

package/docs/llms-full.txt

@@ -1731,12 +1731,23 @@ treated as a substitute for static provenance.
 
 ```ts
 // doc-check: skip — combines route and assurance-config excerpts.
-// route: exact effect declaration + runtime beacon at the owned adapter seam
-import { useCapability } from "@nifrajs/core/capabilities"
+// route: exact effect declaration + correlated execution at the owned adapter seam
+import { executeCapability } from "@nifrajs/core/capabilities"
+
+app.aroundCapability(async (effect, next) => {
+  // Ask an entitlement service or short-lived approval gate using token-only metadata.
+  // effect.signal aborts on request cancellation or the interceptor timeout.
+  if (!policyAllows(effect.capability, effect.target)) return // deny fail-closed
+  await next()
+}, { timeoutMs: 5_000 })
 
 app.post("/orders", { capabilities: ["db.write"] }, async (c) => {
-  useCapability(c, "db.write") // undeclared use fails before the effect
-  return orders.write(c.body)
+  return executeCapability(
+    c,
+    "db.write",
+    { target: "repo:orders" },
+    ({ signal }) => orders.write(c.body, { signal }),
+  )
 })
 
 // in nifra.assurance.ts, alongside policy:
@@ -1766,6 +1777,51 @@ Domain writes on `GET`/`HEAD` are hard violations. Each write definition may
 require request idempotency or durable command/provider-key evidence. The lockfile contains only
 method, path, and capability tokens—no payloads or tenant data—and CI never rewrites it.
 
+### Durable approval, compensation, and reconciliation
+
+The durable execution subpath turns the capability boundary into a crash-visible workflow.
+Approval resumes are HMAC-signed, expire, bind to the tenant, principal, capability, target, and
+digest, and are consumed atomically once. The effect journal marks execution before the provider
+call, so a crash after an external commit remains `ambiguous` for reconciliation instead
+of being retried blindly. Typed sagas persist compensation arguments separately from the sealed
+token-only ledger and compensate committed steps in reverse order with retry/backoff state.
+
+```ts
+// doc-check: skip — durable store implementations are deployment-specific.
+import {
+  createApprovalCoordinator,
+  createDurableEffectJournal,
+  createSagaEngine,
+} from "@nifrajs/core/durable-execution"
+import { effectTracing } from "@nifrajs/otel/effects"
+
+const effects = effectTracing({ exporter })
+app.use(effects)
+
+const approval = createApprovalCoordinator({
+  store: durableApprovalStore, // must declare durability: "durable"
+  secret: approvalHmacKey,     // 32+ random bytes, stored separately
+})
+const journal = createDurableEffectJournal({ store: durableEffectStore })
+
+await executeCapability(c, "payments.charge", {
+  target: "provider:stripe",
+  digest,
+  journal,
+  approval: {
+    gate: approval,
+    tenantId: c.principal.tenantId,
+    principalId: c.principal.userId,
+    resumeToken,
+  },
+}, ({ effectId, signal }) => payments.charge(input, { idempotencyKey: effectId, signal }))
+
+const sagas = createSagaEngine({
+  store: durableSagaStore,
+  observer: effects.observer,
+})
+```
+
 ### Already built in
 
 These add to Nifra's standing defaults: strict-by-default schema validation (unknown fields
@@ -5754,6 +5810,33 @@ import { defineAssurancePolicy } from "@nifrajs/core/assurance"
   IP-restriction, and security-header modules publish reflection-safe enforcement evidence.
   An ordered `AssurancePolicy` classifies every route and fails closed on missing or forbidden
   evidence without adding work to the request path.
+- **Owned effect execution.** `executeCapability()` correlates intent and terminal evidence with an
+  opaque `effectId`, records outcomes automatically, and forwards request cancellation. Add
+  order-scoped `aroundCapability()` policies for async approval/admission; they receive token-only
+  metadata, have bounded timeouts, and must call `next()` exactly once before the effect can run.
+- **Durable workflows (opt in).** `@nifrajs/core/durable-execution` provides tenant/principal-bound,
+  signed single-use approval resumes; a durable effect journal + reconciliation scanner; and a typed
+  saga state machine with reverse compensation, retry/backoff, and ambiguous-crash detection. Production
+  constructors reject stores that do not declare `durability: "durable"`. Operational scans use bounded
+  cursor pages through `reconcileEffectsPage()` / `reconcileSagasPage()`. Provider-confirmed manual
+  review uses effect-ID-bound `resolveAmbiguity()`, followed by `resume()` or `compensate()`.
+- **Production durable adapters.** `@nifrajs/core/durable-adapters` supplies
+  `PostgresDurableExecutionAdapter`, `SQLiteDurableExecutionAdapter`, and
+  `DurableObjectExecutionAdapter`. Each exposes compatible `effects`, `approvals`, `sagas`, and
+  `leases` stores. Run `runDurableExecutionAdapterConformance()` against the deployment backend.
+- **Bounded reconciliation workers.** `@nifrajs/core/reconciliation-worker` runs effect or saga
+  scans under an atomic lease with durable cursor checkpoints, a finite page budget, bounded handler
+  concurrency, filters, cancellation, and token-only metrics. A worker invocation always terminates.
+- **Rich wire values (opt in).** `@nifrajs/core/wire` round-trips dates, bigints, maps, sets, binary,
+  shared references, and cycles through JSON transports. Decoding validates every reachable shape,
+  preserves owned `__proto__` keys without prototype mutation, and enforces configurable node, depth,
+  collection-entry, and decoded-byte limits.
+- **Versioned transport codecs (opt in).** Add `.use(transportCodecs(registry))` from
+  `@nifrajs/core/transport-plugin` and configure the typed
+  client's `transport` option with the same registry. `@nifrajs/core/transport-codec` negotiates
+  bounded HTTP representations and supplies the same frame/loader adapters for WebSockets and
+  deferred data. Import `richWireCodec()` from `@nifrajs/core/transport-codec-rich`; the separate
+  subpath keeps rich-wire code out of plain JSON bundles.
 
 ```ts
 import { defineAssurancePolicy, evaluateRouteAssurance, NIFRA_ASSURANCE } from "@nifrajs/core/assurance"
@@ -7375,7 +7458,7 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 ## @nifrajs/otel
 
-`ActiveObservation`, `AttributeValue`, `causalitySpanLink`, `combineObservationAdapters`, `consoleSpanExporter`, `createObservationLifecycle`, `EndObservation`, `formatTraceparent`, `generateSpanId`, `generateTraceId`, `NifraSpan`, `ObservationAdapter`, `ObservationClock`, `ObservationContext`, `ObservationLifecycle`, `ObservationLifecycleOptions`, `ObservationLink`, `ObservationParent`, `otlpExporter`, `OtlpExporter`, `OtlpExporterOptions`, `ParsedTraceparent`, `parseTraceparent`, `SpanStatus`, `StartObservation`, `TraceContext`, `traceHeaders`, `tracing`, `TracingOptions`
+`ActiveObservation`, `AttributeValue`, `causalitySpanLink`, `combineObservationAdapters`, `consoleSpanExporter`, `createObservationLifecycle`, `effectTracing`, `EffectTracingOptions`, `EffectTracingPlugin`, `EndObservation`, `formatTraceparent`, `generateSpanId`, `generateTraceId`, `NifraSpan`, `ObservationAdapter`, `ObservationClock`, `ObservationContext`, `ObservationLifecycle`, `ObservationLifecycleOptions`, `ObservationLink`, `ObservationParent`, `otlpExporter`, `OtlpExporter`, `OtlpExporterOptions`, `ParsedTraceparent`, `parseTraceparent`, `SpanStatus`, `StartObservation`, `TraceContext`, `traceHeaders`, `tracing`, `TracingOptions`
 
 ## @nifrajs/prompt