@effect-agent/testing 0.1.0-beta.9 → 0.1.0-beta.90

package/dist/Certification.d.mts

@@ -0,0 +1,106 @@
+import { Crypto, Duration, Effect, Layer } from "effect";
+import { DurableRuntimeFailpointLocation } from "effect-agent/durable-failpoint";
+import { SubmissionLedger } from "effect-agent/submission-ledger";
+import { CertificationCaseResult, CertificationReport, CertificationScenario, CertificationSweepResult, CertificationTierThreeReport } from "effect-agent/testing/certification";
+import { ThreadStore } from "effect-agent/thread-store";
+import { WakeScheduler } from "effect-agent/wake-scheduler";
+//#region src/Certification.d.ts
+/**
+ * P7 WP2 — `certifyDurableAdapters` (plan §1): the one certification entry point a durable
+ * adapter pair runs to earn a Schema-encoded certificate.
+ *
+ * - **Tier 1 — port contract**: the two shared conformance case arrays, verbatim, through
+ *   `certifyPorts` (TEST-004/STORE-010).
+ * - **Tier 2 — coordinator protocol + failpoint convergence**: the durable coordinator is
+ *   assembled over the CANDIDATE Layer pair with a scripted deterministic model; every
+ *   reached `DurableRuntimeFailpointLocation` is armed one-shot across the six scenario shapes
+ *   (plain / uncertain-tool / durable-steps / approval / join / delegation). Unreached locations
+ *   share a verified clean run per shape; new unaccounted-for locations get a full sweep.
+ *   After the injected fault the runner asserts the state stays CLASSIFIABLE (recovery +
+ *   the public unblocking operations `resolveUnknown`/`resolveApproval` are the only levers
+ *   used) and that the re-drive CONVERGES to `verifyThreadInvariants` with `requireAllSettled`,
+ *   including a fully discharged digest-chain check, because the runner captures per-batch producer
+ *   identity at append time.
+ * - **Tier 3 — real loss lever**: recorded honestly. A durable adapter either supplies a
+ *   `CertificationCrashLever` executed in this run, cites its committed real-loss evidence
+ *   (process-kill / eviction suites), or the certificate says `not-exercised`. A non-durable
+ *   reference adapter records `not-applicable`.
+ *
+ * The runner is adapter-neutral and platform-neutral: it imports nothing Node-only, so the
+ * same entry point runs under `@effect/vitest` on Node and inside workerd (storage-cloudflare's
+ * in-workerd runner). It must run under a TestClock (Tier 1 drives lease expiry through
+ * virtual time), and requires only `Crypto.Crypto` from the environment.
+ */
+/**
+ * A real-loss lever supplied by an adapter that wants Tier 3 exercised IN this certification
+ * run (kill/evict/reopen around a designated row subset). Rows report with
+ * `suite: "real-loss"`. Failures must be captured per-row — the lever's error channel is
+ * `never` so a certificate is always produced.
+ */
+type CertificationCrashLever = Effect.Effect<ReadonlyArray<CertificationCaseResult>>;
+interface CertifyDurableAdaptersOptions<LedgerE = never, StoreE = never> {
+  /** Adapter pair identity named by the certificate (durability is read from the ledger). */
+  readonly adapter: {
+    readonly name: string;
+    readonly version?: string | undefined;
+  };
+  /**
+   * The candidate Layer pair. When both ports must share one connection root (the ADR-0011
+   * "same file" rule), pass the SAME combined Layer instance for both fields — Layer
+   * memoization builds it once. A candidate may require `Crypto.Crypto` (the memory reference
+   * does); the certification's own environment supplies nothing else.
+   */
+  readonly submissionLedger: Layer.Layer<SubmissionLedger, LedgerE, Crypto.Crypto>;
+  readonly threadStore: Layer.Layer<ThreadStore, StoreE, Crypto.Crypto>;
+  /** Defaults to `WakeScheduler.layerNoop`; the runner re-drives lanes explicitly. */
+  readonly wakeScheduler?: Layer.Layer<WakeScheduler> | undefined;
+  /** Executes Tier 3 in this run; takes precedence over `tierThreeEvidence`. */
+  readonly crashLever?: CertificationCrashLever | undefined;
+  /** Repository-relative citations of committed real-loss suites (Tier 3 `recorded-evidence`). */
+  readonly tierThreeEvidence?: ReadonlyArray<string> | undefined;
+  /**
+   * The candidate ledger's configured ownership lease (defaults to the D5 default, 30s).
+   * Every Tier-2 re-drive round advances the TestClock past this lease before reclaiming:
+   * a live lease may block ALL new claims (the SQL adapters do; the memory reference also
+   * allows same-producer reclaim), so the adapter-NEUTRAL recovery lever after a mid-Attempt
+   * fault is lease expiry — exactly the documented D5 liveness mechanism, driven through
+   * virtual time.
+   */
+  readonly ownershipLeaseDuration?: Duration.Duration | undefined;
+}
+/** The six Tier-2 scenario shapes in sweep order. */
+declare const CERTIFICATION_SCENARIOS: ReadonlyArray<CertificationScenario>;
+/**
+ * Coordinator failpoint locations that none of the six scenario shapes can reach, recorded
+ * honestly instead of silently claimed. These require operator, compaction, reservation,
+ * background-worker, or Agent-update paths the shapes do not take. They are pinned in-process
+ * by the P5/S2 suites (`packages/testing/test/durable-tools.test.ts` "resolveUnknown is idempotent across the
+ * intent failpoint", `durable-runtime.test.ts` abort rows,
+ * `durable-subagents.test.ts` abort propagation) and by the process-kill/eviction crash
+ * matrices. Runner tests assert the observed never-fired set equals EXACTLY this list, so a
+ * protocol change that silently stops exercising a location fails the certification.
+ */
+declare const TIER2_UNREACHED_LOCATIONS: ReadonlyArray<DurableRuntimeFailpointLocation>;
+/** Locations of `tier2` rows whose armed fault never fired in ANY scenario, sorted. */
+declare const tier2NeverFiredLocations: (tier2: ReadonlyArray<CertificationSweepResult>) => ReadonlyArray<DurableRuntimeFailpointLocation>;
+/**
+ * Resolve the Tier-3 record honestly (plan §1): a non-durable reference adapter has no real
+ * loss to exercise (`not-applicable`); a supplied lever runs NOW (`exercised`); committed
+ * real-loss citations are recorded (`recorded-evidence`); otherwise the certificate says
+ * `not-exercised` — a scoped statement, never a silent claim.
+ */
+declare const resolveTierThree: (durability: "durable-cloudflare" | "durable-node" | "non-durable", options: {
+  readonly crashLever?: CertificationCrashLever | undefined;
+  readonly tierThreeEvidence?: ReadonlyArray<string> | undefined;
+}) => Effect.Effect<CertificationTierThreeReport, never, never>;
+/**
+ * Certify one durable adapter pair (plan §1, §8 WP2). Runs Tier 2 FIRST over pristine
+ * storage (each cell converges to all-settled before the next starts, so the recovery scan
+ * never sees foreign leftovers), then Tier 1's port contract cases (whose lanes deliberately
+ * end in every nonterminal shape), then records Tier 3. Requires `Crypto.Crypto` and a
+ * TestClock-backed environment; the candidate Layers are built exactly once.
+ */
+declare const certifyDurableAdapters: <LedgerE = never, StoreE = never>(options: CertifyDurableAdaptersOptions<LedgerE, StoreE>) => Effect.Effect<CertificationReport, LedgerE | StoreE, Crypto.Crypto>;
+//#endregion
+export { CERTIFICATION_SCENARIOS, CertificationCrashLever, CertifyDurableAdaptersOptions, TIER2_UNREACHED_LOCATIONS, certifyDurableAdapters, resolveTierThree, tier2NeverFiredLocations };
+//# sourceMappingURL=Certification.d.mts.map