@hraness/direct 0.7.5

package/src/index.ts

@@ -0,0 +1,51 @@
+import {
+  defineDirect,
+  parseDirectDefinition,
+  tryDefineDirect,
+} from "./core/definition.js";
+
+export const FIXTURE_QUERY_KEY = "__direct_fixture" as const;
+export const SCENARIO_QUERY_KEY = "__direct_scenario" as const;
+
+export {
+  defineDirect,
+  parseDirectDefinition,
+  tryDefineDirect,
+};
+export type {
+  DirectDefinition,
+  DirectDefinitionError,
+  DirectDefinitionInput,
+  DirectDefinitionLimits,
+} from "./core/definition.js";
+export type {
+  CoverageCatalogSnapshot,
+  CoverageEntry,
+  CoverageEntryInput,
+  CoverageMode,
+} from "./core/coverage.js";
+export type {
+  FixtureCreateInput,
+  FixtureEnvelope,
+  FixtureError,
+} from "./core/fixture.js";
+export type { WorldParser } from "./core/json.js";
+export type {
+  JsonArray,
+  JsonObject,
+  JsonPrimitive,
+  JsonValue,
+} from "./core/json-value.js";
+export type {
+  ActiveDirect,
+  DirectActivation,
+  QueryError,
+} from "./core/query.js";
+export type {
+  LogicalRuntime,
+  LogicalRuntimeSnapshot,
+} from "./core/runtime.js";
+export type {
+  ScenarioDefinition,
+  ScenarioDefinitionInput,
+} from "./core/scenario.js";

package/src/react.ts

@@ -0,0 +1,54 @@
+import {
+  createContext,
+  createElement,
+  useContext,
+  useSyncExternalStore,
+  type Context,
+  type ReactElement,
+  type ReactNode,
+} from "react";
+import type { JsonValue } from "./core/json-value.js";
+import type { DirectStore, DirectStoreSnapshot } from "./core/store.js";
+
+export interface DirectProviderProps<World extends JsonValue> {
+  readonly store: DirectStore<World>;
+  readonly children: ReactNode;
+}
+
+export interface DirectReactBindings<World extends JsonValue> {
+  readonly Context: Context<DirectStore<World> | null>;
+  readonly Provider: (props: DirectProviderProps<World>) => ReactElement;
+  readonly useStore: () => DirectStore<World>;
+  readonly useSnapshot: () => DirectStoreSnapshot<World>;
+  readonly useWorld: () => World;
+}
+
+export function createDirectReactBindings<World extends JsonValue>(): DirectReactBindings<World> {
+  const StoreContext = createContext<DirectStore<World> | null>(null);
+
+  const useStore = (): DirectStore<World> => {
+    const store = useContext(StoreContext);
+    if (store === null) {
+      throw new Error("Direct hooks require their matching Direct Provider");
+    }
+    return store;
+  };
+
+  const useSnapshot = (): DirectStoreSnapshot<World> => {
+    const store = useStore();
+    return useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
+  };
+
+  const bindings: DirectReactBindings<World> = {
+    Context: StoreContext,
+    Provider: ({ store, children }: DirectProviderProps<World>) => createElement(
+      StoreContext.Provider,
+      { value: store },
+      children,
+    ),
+    useStore,
+    useSnapshot,
+    useWorld: () => useSnapshot().world,
+  };
+  return Object.freeze(bindings);
+}

package/src/testing/activity.ts

@@ -0,0 +1,228 @@
+import type { JsonValue } from "../core/json-value.js";
+import type { LogicalRuntime } from "../core/runtime.js";
+import type {
+  DirectStore,
+  StoreError,
+  StoreGeneration,
+} from "../core/store.js";
+import type { OperationId } from "../core/ids.js";
+import { renderUnknownReason } from "../core/reason.js";
+import { err, ok, type Result } from "../core/result.js";
+
+export type DirectActivityScopeError =
+  | {
+    readonly code: "scope-closed";
+    readonly message: string;
+    readonly operation: null;
+    readonly storeError: null;
+    readonly reason: null;
+  }
+  | {
+    readonly code: "operation-id-failed";
+    readonly message: string;
+    readonly operation: null;
+    readonly storeError: null;
+    readonly reason: unknown;
+  }
+  | {
+    readonly code: "store-begin-failed" | "store-settle-failed";
+    readonly message: string;
+    readonly operation: OperationId;
+    readonly storeError: StoreError;
+    readonly reason: null;
+  };
+
+export type DirectActivityRunError =
+  | {
+    readonly code: "begin-failed";
+    readonly message: string;
+    readonly operation: null;
+    readonly workError: null;
+    readonly activityError: DirectActivityScopeError;
+  }
+  | {
+    readonly code: "work-failed";
+    readonly message: string;
+    readonly operation: OperationId;
+    readonly workError: unknown;
+    readonly activityError: null;
+  }
+  | {
+    readonly code: "settlement-failed";
+    readonly message: string;
+    readonly operation: OperationId;
+    readonly workError: null;
+    readonly activityError: DirectActivityScopeError;
+  }
+  | {
+    readonly code: "work-and-settlement-failed";
+    readonly message: string;
+    readonly operation: OperationId;
+    readonly workError: unknown;
+    readonly activityError: DirectActivityScopeError;
+  };
+
+export interface DirectActivityLease {
+  readonly generation: StoreGeneration;
+  readonly operation: OperationId;
+  /** Settle once. Later calls return the first settlement result unchanged. */
+  readonly release: () => Result<true, DirectActivityScopeError>;
+  readonly isReleased: () => boolean;
+}
+
+export interface DirectActivityScope {
+  readonly begin: (namespace?: string) => Result<DirectActivityLease, DirectActivityScopeError>;
+  readonly run: <Value>(
+    namespace: string,
+    work: () => Value | PromiseLike<Value>,
+  ) => Promise<Result<Value, DirectActivityRunError>>;
+}
+
+export interface DirectActivityScopeOptions {
+  /** Fence new activity once the owning composition has been aborted. */
+  readonly signal?: AbortSignal;
+}
+
+function storeErrorMessage(cause: StoreError): string {
+  return renderUnknownReason(cause, "Direct store operation failed");
+}
+
+function operationError(reason: unknown): DirectActivityScopeError {
+  return Object.freeze({
+    code: "operation-id-failed",
+    message: renderUnknownReason(reason),
+    operation: null,
+    storeError: null,
+    reason,
+  });
+}
+
+function closedScopeError(): DirectActivityScopeError {
+  return Object.freeze({
+    code: "scope-closed",
+    message: "The Direct activity scope is closed",
+    operation: null,
+    storeError: null,
+    reason: null,
+  });
+}
+
+function storeError(
+  code: "store-begin-failed" | "store-settle-failed",
+  operation: OperationId,
+  cause: StoreError,
+): DirectActivityScopeError {
+  return Object.freeze({
+    code,
+    message: storeErrorMessage(cause),
+    operation,
+    storeError: cause,
+    reason: null,
+  });
+}
+
+/**
+ * Couple deterministic operation IDs to the store's generation-fenced activity
+ * ledger. A lease owns exactly one settlement attempt, including a failed one.
+ */
+export function createDirectActivityScope<World extends JsonValue>(
+  store: DirectStore<World>,
+  runtime: LogicalRuntime,
+  options: DirectActivityScopeOptions = {},
+): DirectActivityScope {
+  const signal = options.signal;
+  const isClosed = (): boolean => signal?.aborted === true;
+  const begin = (namespace = "activity"): Result<DirectActivityLease, DirectActivityScopeError> => {
+    if (isClosed()) return err(closedScopeError());
+    let operation: OperationId;
+    try {
+      operation = runtime.nextOperationId(namespace);
+    } catch (reason) {
+      return err(operationError(reason));
+    }
+    if (isClosed()) return err(closedScopeError());
+
+    const currentGeneration = store.getSnapshot().generation;
+    const started = store.beginActivity(currentGeneration, operation);
+    if (!started.ok) {
+      return err(storeError("store-begin-failed", operation, started.error));
+    }
+    if (isClosed()) {
+      const settled = started.value.settle();
+      return settled.ok
+        ? err(closedScopeError())
+        : err(storeError("store-settle-failed", operation, settled.error));
+    }
+
+    let released = false;
+    let releaseResult: Result<true, DirectActivityScopeError> | null = null;
+    const lease: DirectActivityLease = Object.freeze({
+      generation: currentGeneration,
+      operation,
+      isReleased: () => released,
+      release: () => {
+        if (releaseResult !== null) return releaseResult;
+        released = true;
+        const settled = started.value.settle();
+        releaseResult = settled.ok
+          ? ok<true>(true)
+          : err(storeError("store-settle-failed", operation, settled.error));
+        return releaseResult;
+      },
+    });
+    return ok(lease);
+  };
+
+  const run: DirectActivityScope["run"] = async (namespace, work) => {
+    const started = begin(namespace);
+    if (!started.ok) {
+      return err(Object.freeze({
+        code: "begin-failed",
+        message: started.error.message,
+        operation: null,
+        workError: null,
+        activityError: started.error,
+      }));
+    }
+
+    let workResult: Result<Awaited<ReturnType<typeof work>>, unknown>;
+    try {
+      workResult = ok(await work());
+    } catch (reason) {
+      workResult = err(reason);
+    }
+    const released = started.value.release();
+
+    if (workResult.ok && released.ok) return ok(workResult.value);
+    if (!workResult.ok && released.ok) {
+      return err(Object.freeze({
+        code: "work-failed",
+        message: renderUnknownReason(workResult.error),
+        operation: started.value.operation,
+        workError: workResult.error,
+        activityError: null,
+      }));
+    }
+    if (workResult.ok && !released.ok) {
+      return err(Object.freeze({
+        code: "settlement-failed",
+        message: released.error.message,
+        operation: started.value.operation,
+        workError: null,
+        activityError: released.error,
+      }));
+    }
+    if (!workResult.ok && !released.ok) {
+      return err(Object.freeze({
+        code: "work-and-settlement-failed",
+        message: `${renderUnknownReason(workResult.error)}; settlement failed: ${released.error.message}`,
+        operation: started.value.operation,
+        workError: workResult.error,
+        activityError: released.error,
+      }));
+    }
+    throw new Error("Unreachable activity result");
+  };
+
+  return Object.freeze({ begin, run });
+}

package/src/testing/coverage-binding.ts

@@ -0,0 +1,99 @@
+import {
+  createCoverageCatalogSnapshot,
+  parseCoverageCatalogSnapshot,
+  type CoverageCatalogSnapshot,
+  type CoverageEntry,
+  type CoverageError,
+} from "../core/coverage.js";
+import type { DirectDefinition } from "../core/definition.js";
+import type { JsonValue } from "../core/json-value.js";
+import { renderUnknownReason } from "../core/reason.js";
+import { err, ok, type Result } from "../core/result.js";
+
+export type CoverageBindingError =
+  | {
+    readonly code: "invalid-coverage";
+    readonly message: string;
+    readonly coverageError: CoverageError;
+  }
+  | {
+    readonly code: "coverage-mismatch" | "invalid-definition";
+    readonly message: string;
+    readonly coverageError: null;
+  };
+
+function sameEntry(
+  actual: CoverageEntry,
+  expected: CoverageEntry,
+): boolean {
+  if (
+    actual.key !== expected.key
+    || actual.mode !== expected.mode
+    || actual.claim !== expected.claim
+    || actual.scenarios.length !== expected.scenarios.length
+  ) return false;
+  return actual.scenarios.every((scenario, index) => scenario === expected.scenarios[index]);
+}
+
+/** Parse a browser value and prove exact equality with an owned expected snapshot. */
+export function parseExpectedCoverageCatalogSnapshot(
+  input: unknown,
+  expected: CoverageCatalogSnapshot,
+): Result<CoverageCatalogSnapshot, CoverageBindingError> {
+  const parsed = parseCoverageCatalogSnapshot(input);
+  if (!parsed.ok) {
+    return err(Object.freeze({
+      code: "invalid-coverage",
+      message: parsed.error.message,
+      coverageError: parsed.error,
+    }));
+  }
+
+  try {
+    if (
+      parsed.value.schema !== expected.schema
+      || parsed.value.entries.length !== expected.entries.length
+      || parsed.value.entries.some((entry, index) => {
+        const expectedEntry = expected.entries[index];
+        return expectedEntry === undefined || !sameEntry(entry, expectedEntry);
+      })
+    ) {
+      return err(Object.freeze({
+        code: "coverage-mismatch",
+        message: "Published Direct coverage does not exactly match the authored definition",
+        coverageError: null,
+      }));
+    }
+  } catch (reason) {
+    return err(Object.freeze({
+      code: "invalid-definition",
+      message: renderUnknownReason(reason, "Expected Direct coverage could not be inspected"),
+      coverageError: null,
+    }));
+  }
+  return ok(expected);
+}
+
+/**
+ * Parse a browser-published coverage value and prove that it is the exact
+ * snapshot authored by the definition running the verifier.
+ */
+export function parseDefinitionCoverageSnapshot<
+  World extends JsonValue,
+  Route extends string,
+>(
+  input: unknown,
+  definition: Pick<DirectDefinition<World, Route>, "coverage">,
+): Result<CoverageCatalogSnapshot, CoverageBindingError> {
+  let expected: CoverageCatalogSnapshot;
+  try {
+    expected = createCoverageCatalogSnapshot(definition.coverage);
+  } catch (reason) {
+    return err(Object.freeze({
+      code: "invalid-definition",
+      message: renderUnknownReason(reason, "Direct definition coverage could not be inspected"),
+      coverageError: null,
+    }));
+  }
+  return parseExpectedCoverageCatalogSnapshot(input, expected);
+}

package/src/testing/evidence.ts

@@ -0,0 +1,59 @@
+import type { CoverageEntry, CoverageMode } from "../core/coverage.js";
+
+export type CoverageEvidenceStatus =
+  | "direct-required"
+  | "fixture-verified"
+  | "not-exercised"
+  | "partial"
+  | "verified";
+
+export type CoverageEvidenceStatusFor<Mode extends CoverageMode> =
+  Mode extends "direct"
+    ? "direct-required" | "verified"
+    : Mode extends "fixture"
+      ? "not-exercised" | "partial" | "verified"
+      : "fixture-verified" | "not-exercised" | "partial" | "verified";
+
+export interface CoverageEvidenceFacts {
+  /** Scenario IDs whose product-owned assertions passed in the current evidence set. */
+  readonly exercisedScenarios: ReadonlySet<string>;
+  /** Whether current direct evidence for the substituted production port passed. */
+  readonly directEvidence?: "missing" | "verified";
+}
+
+/**
+ * Classify claim evidence from its declared proof mode and current facts.
+ * Scenario actions and assertions remain product-owned; this function owns only
+ * the shared completion taxonomy.
+ */
+export function classifyCoverageEvidence<
+  Entry extends CoverageEntry,
+>(
+  entry: Entry,
+  facts: CoverageEvidenceFacts,
+): CoverageEvidenceStatusFor<Entry["mode"]> {
+  const directVerified = facts.directEvidence === "verified";
+  if (entry.mode === "direct") {
+    return (directVerified ? "verified" : "direct-required") as CoverageEvidenceStatusFor<
+      Entry["mode"]
+    >;
+  }
+
+  let exercised = 0;
+  for (const scenario of entry.scenarios) {
+    if (facts.exercisedScenarios.has(scenario)) exercised += 1;
+  }
+  if (exercised === 0) {
+    return (directVerified && entry.mode === "mixed" ? "partial" : "not-exercised") as
+      CoverageEvidenceStatusFor<Entry["mode"]>;
+  }
+  if (exercised < entry.scenarios.length) {
+    return "partial" as CoverageEvidenceStatusFor<Entry["mode"]>;
+  }
+  if (entry.mode === "fixture") {
+    return "verified" as CoverageEvidenceStatusFor<Entry["mode"]>;
+  }
+  return (directVerified ? "verified" : "fixture-verified") as CoverageEvidenceStatusFor<
+    Entry["mode"]
+  >;
+}

package/src/testing/index.ts

@@ -0,0 +1,22 @@
+import {
+  parseCoverageCatalogSnapshot as parseCoverageCatalogSnapshotCore,
+} from "../core/coverage.js";
+
+/** Parse an exact coverage snapshot, including `window.__direct.manifest.coverage`. */
+export function parseCoverageCatalogSnapshot(
+  input: unknown,
+): ReturnType<typeof parseCoverageCatalogSnapshotCore> {
+  return parseCoverageCatalogSnapshotCore(input);
+}
+export type {
+  CoverageCatalogSnapshot,
+  CoverageEntry,
+  CoverageError,
+} from "../core/coverage.js";
+export * from "./activity.js";
+export * from "./coverage-binding.js";
+export * from "./evidence.js";
+export * from "./manifest.js";
+export * from "./probe.js";
+export * from "./session.js";
+export * from "./scripted-transport.js";