@hraness/ghostget 0.17.2

package/src/read-admission-runtime.ts

@@ -0,0 +1,91 @@
+import * as Effect from "effect/Effect";
+import * as Either from "effect/Either";
+import * as Exit from "effect/Exit";
+import type { PortableOperationIdentityV1 } from "./provider-plugin-portable-identity";
+import {
+  acquirePortableProviderPluginInvocationLease,
+  createPortableProviderPluginInvocationLeaseContainmentController,
+  releasePortableProviderPluginInvocationLease
+} from "./provider-plugin-invocation-lease";
+import { settlePortableProviderPluginCleanup } from "./provider-plugin-cleanup-barrier";
+import {
+  acquireWebSessionCleanupAdmission,
+  WebSessionCleanupAdmissionBlockedError,
+  type WebSessionCleanupAdmissionIdentity
+} from "./web-session-cleanup-admission";
+import type { WebSessionCleanupBarrierRegistrar } from "./web-session-execution";
+import { readAttempt, type ReadEffectFailure } from "./read-effect";
+import { readNative } from "./read-effect-platform";
+import { runReadEffect } from "./read-effect-runtime";
+
+type Environment = Readonly<Record<string, string | undefined>>;
+
+/** Exact kernel/content custody stays synchronous. The program owns closing
+ * registration, joining every registered barrier, and releasing only a proven
+ * cleanup-complete controller. An unsafe controller remains durable. */
+export async function withReadCleanupAdmission<A>(
+  identity: WebSessionCleanupAdmissionIdentity,
+  environment: Environment,
+  operation: (register: WebSessionCleanupBarrierRegistrar) => Promise<A>,
+  acquiredAt: Date | undefined,
+  onBlocked: (error: WebSessionCleanupAdmissionBlockedError) => Promise<A>
+
+): Promise<A> {
+  const program: Effect.Effect<A, ReadEffectFailure> = Effect.gen(function*() {
+    const acquired = yield* Effect.either(readAttempt(() => acquireWebSessionCleanupAdmission(identity, environment, acquiredAt)));
+    if (Either.isLeft(acquired)) {
+      const cause = acquired.left.cause;
+      if (cause instanceof WebSessionCleanupAdmissionBlockedError) return yield* readNative(() => onBlocked(cause));
+      return yield* Effect.fail(acquired.left);
+    }
+    const admission = acquired.right;
+    const settlement = yield* Effect.exit(Effect.gen(function*() {
+      const outcome = yield* Effect.exit(readNative(() => operation(admission.registerCleanupBarrier)));
+      yield* readAttempt(admission.closeRegistration);
+      const barriers = yield* Effect.all(
+        admission.barriers.map(barrier => Effect.either(readNative(() => barrier))),
+        { concurrency: "unbounded" }
+      );
+      yield* readAttempt(() => {
+        if (barriers.some(Either.isLeft)) admission.cleanupUnsafe();
+        else { admission.cleanupComplete(); admission.release(); }
+      });
+      return yield* outcome;
+    }));
+    if (Exit.isFailure(settlement)) {
+      yield* readAttempt(() => {
+        admission.closeRegistration();
+        if (admission.current.claim.containment.status === "parent-owned") { admission.cleanupComplete(); admission.release(); }
+      });
+    }
+    return yield* settlement;
+  }).pipe(Effect.uninterruptible);
+  return runReadEffect(program);
+}
+
+/** AsyncLocalStorage in the native portable host retains descendant barrier
+ * registration. Its positive proof precedes the synchronous exact lease release;
+ * neither a failed operation nor Effect scope completion can substitute for it. */
+export async function withPortableReadAdmission<A>(
+  identity: PortableOperationIdentityV1,
+  runId: string,
+  environment: Environment,
+  acquiredAt: Date | undefined,
+  operation: () => Promise<A>
+
+): Promise<A> {
+  const program: Effect.Effect<A, ReadEffectFailure> = Effect.gen(function*() {
+    const containment = yield* readAttempt(() => createPortableProviderPluginInvocationLeaseContainmentController(
+      acquirePortableProviderPluginInvocationLease(identity, runId, environment, acquiredAt),
+      environment
+    ));
+    const outcome = yield* readNative(() => settlePortableProviderPluginCleanup(
+      operation,
+      { containment, cleanupComplete: containment.cleanupComplete }
+    ));
+    yield* readAttempt(() => releasePortableProviderPluginInvocationLease(containment.current, environment, new Date()));
+    if (outcome.status === "rejected") return yield* readAttempt(() => { throw outcome.reason; });
+    return outcome.value;
+  }).pipe(Effect.uninterruptible);
+  return runReadEffect(program);
+}

package/src/read-client.ts

@@ -0,0 +1,521 @@
+import { canonicalJson, sha256 } from "./canonical-json";
+import { loadAuthSnapshotIfPresent } from "./auth";
+import {
+  createPortableProviderPluginCatalog,
+} from "./provider-plugin-portable-catalog";
+import type { ProviderPluginRegistry } from "./provider-plugin-registry";
+import { providerPluginRegistry } from "./provider-plugins";
+import {
+  ReadProjectionDurableRepairError,
+  READ_PROJECTION_TRANSITION_SETTLEMENT_WAIT_MS,
+  isReadProjectionCorruptionError,
+  publishReadProjection,
+  readReadProjection,
+  repairReadProjection,
+  removeReadProjection,
+  projectionAuthIdentityHash,
+  withSettledReadProjectionAuthAdmission,
+  type ReadProjectionCacheResult,
+  type ReadProjectionPublication,
+  type ReadProjectionQuery,
+  type ReadProjectionAdmissionSettlementOptions,
+} from "./read-projections";
+import {
+  isPublicWebSessionInvocationAuthority,
+  publicWebSessionAuthorityIdentityHash,
+} from "./web-session-authentication-policy";
+import {
+  createReadProjectionQueryForInvocation,
+  executeReadInvocation,
+  prepareInvocation,
+  type InvocationResult,
+  type PreparedInvocation,
+} from "./runtime";
+
+type Environment = Readonly<Record<string, string | undefined>>;
+const MAX_FRESH_FOR_MS = 365 * 24 * 60 * 60 * 1_000;
+
+export type CapabilityReadRequest = {
+  readonly adapterId: string;
+  readonly operationId: string;
+  readonly input?: unknown;
+  readonly authId?: string;
+};
+
+export type ReadCapabilityOptions = {
+  readonly environment?: Environment;
+  readonly registry?: ProviderPluginRegistry;
+  readonly freshForMs?: number;
+  readonly now?: Date;
+};
+
+export type RevalidateCapabilityOptions = ReadCapabilityOptions & {
+  readonly headed?: boolean;
+  readonly signal?: AbortSignal;
+};
+
+export type ReadProjectionCacheOutcome =
+  | {
+      readonly status: "stored";
+      readonly publication: ReadProjectionPublication;
+    }
+  | {
+      readonly status: "retained";
+      readonly reason: "live-read-failed";
+    }
+  | {
+      readonly status: "miss";
+      readonly reason: "no-cached-snapshot";
+    }
+  | {
+      readonly status: "skipped";
+      readonly reason: "auth-subject-unbound";
+    }
+  | {
+      readonly status: "error";
+      readonly message: string;
+    };
+
+export type RevalidatedCapability = {
+  readonly cachedBefore: ReadProjectionCacheResult | null;
+  readonly live: InvocationResult;
+  readonly cache: ReadProjectionCacheOutcome;
+};
+
+type PreparedReadOptions = RevalidateCapabilityOptions & {
+  readonly registry: ProviderPluginRegistry;
+  readonly executeRead?: typeof executeReadInvocation;
+};
+
+function selectedRegistry(
+  environment: Environment,
+  registry: ProviderPluginRegistry | undefined,
+): ProviderPluginRegistry {
+  return registry
+    ?? createPortableProviderPluginCatalog(
+      providerPluginRegistry,
+      environment,
+    ).registry;
+}
+
+function prepareCapability(
+  request: CapabilityReadRequest,
+  environment: Environment,
+  registry: ProviderPluginRegistry,
+): PreparedInvocation {
+  return prepareInvocation(
+    request.adapterId,
+    request.operationId,
+    request.input === undefined ? {} : request.input,
+    request.authId,
+    environment,
+    registry,
+  );
+}
+
+function exactAuthHash(invocation: PreparedInvocation): string {
+  return sha256(canonicalJson(invocation.auth));
+}
+
+function withInvocationAuthorityAdmission<T>(
+  invocation: PreparedInvocation,
+  environment: Environment,
+  operation: () => T,
+  options: ReadProjectionAdmissionSettlementOptions = {},
+): T {
+  return isPublicWebSessionInvocationAuthority(invocation.auth)
+    ? operation()
+    : withSettledReadProjectionAuthAdmission(
+        invocation.auth.id,
+        environment,
+        operation,
+        options,
+      );
+}
+
+function liveReadDiscardedError(
+  invocation: PreparedInvocation,
+  cause?: unknown,
+): Error {
+  return new Error(
+    `auth locator ${invocation.auth.id} changed while the live read was running; its result was discarded`,
+    cause === undefined ? undefined : { cause },
+  );
+}
+
+function isOptionalAdmissionRewrite(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+  return error.message.includes("could not safely open optional read projection admission")
+    && error.message.includes("state file changed while it was read");
+}
+
+type AuthRealmState = "matches" | "missing" | "changed";
+
+function authRealmState(
+  invocation: PreparedInvocation,
+  query: ReadProjectionQuery | null,
+  environment: Environment,
+): AuthRealmState {
+  if (isPublicWebSessionInvocationAuthority(invocation.auth)) {
+    const expected = publicWebSessionAuthorityIdentityHash(invocation.auth);
+    return invocation.readProjectionAuthIdentityHash === expected
+      && (query === null || query.identity.auth.hash === expected)
+      ? "matches"
+      : "changed";
+  }
+  const snapshot = loadAuthSnapshotIfPresent(
+    invocation.auth.id,
+    environment,
+  );
+  if (snapshot === null) return "missing";
+  const current = snapshot.auth;
+  const currentHash = sha256(canonicalJson(current));
+  const preparedAuthIdentityHash =
+    invocation.readProjectionAuthIdentityHash;
+  if (preparedAuthIdentityHash === undefined) {
+    throw new Error(
+      "prepared invocation is missing its auth lifetime identity; prepare it again",
+    );
+  }
+  if (
+    currentHash !== exactAuthHash(invocation)
+    || current.subject !== invocation.auth.subject
+  ) return "changed";
+  const currentAuthIdentityHash = projectionAuthIdentityHash(
+    current.id,
+    currentHash,
+    environment,
+  );
+  if (
+    currentAuthIdentityHash !== preparedAuthIdentityHash
+    || (
+      query !== null
+      && query.identity.auth.hash !== preparedAuthIdentityHash
+    )
+  ) return "changed";
+  return "matches";
+}
+
+function requireCurrentAuthRealm(
+  invocation: PreparedInvocation,
+  query: ReadProjectionQuery | null,
+  environment: Environment,
+): void {
+  if (authRealmState(invocation, query, environment) !== "matches") {
+    throw new Error(
+      `auth locator ${invocation.auth.id} changed since this invocation was prepared`,
+    );
+  }
+}
+
+function validateReadOptions(options: ReadCapabilityOptions): void {
+  if (
+    options.now !== undefined
+    && (
+      !(options.now instanceof Date)
+      || !Number.isFinite(options.now.getTime())
+    )
+  ) throw new Error("read projection observation time is invalid");
+  if (
+    options.freshForMs !== undefined
+    && (
+      typeof options.freshForMs !== "number"
+      || !Number.isSafeInteger(options.freshForMs)
+      || options.freshForMs < 0
+      || options.freshForMs > MAX_FRESH_FOR_MS
+    )
+  ) throw new Error("read projection freshness window is malformed");
+}
+
+function boundedErrorMessage(error: unknown): string {
+  const message = error instanceof Error ? error.message : String(error);
+  return Buffer.byteLength(message, "utf8") <= 8 * 1024
+    ? message
+    : `${Buffer.from(message, "utf8").subarray(0, 8 * 1024).toString("utf8")}…`;
+}
+
+export function readCachedPreparedCapability(
+  invocation: PreparedInvocation,
+  options: ReadCapabilityOptions & { readonly registry: ProviderPluginRegistry },
+): ReadProjectionCacheResult {
+  const environment = options.environment ?? process.env;
+  validateReadOptions(options);
+  return withInvocationAuthorityAdmission(
+    invocation,
+    environment,
+    () => {
+      const query = createReadProjectionQueryForInvocation(
+        invocation,
+        environment,
+        options.registry,
+      );
+      if (authRealmState(invocation, query, environment) !== "matches") {
+        return Object.freeze({ status: "miss" as const, key: query.key });
+      }
+      const cached = readReadProjection(query, {
+        environment,
+        ...(options.now === undefined ? {} : { now: options.now }),
+        ...(options.freshForMs === undefined
+          ? {}
+          : { freshForMs: options.freshForMs }),
+      });
+      if (authRealmState(invocation, query, environment) !== "matches") {
+        return Object.freeze({ status: "miss" as const, key: query.key });
+      }
+      return cached;
+    },
+  );
+}
+
+export function readCachedCapability(
+  request: CapabilityReadRequest,
+  options: ReadCapabilityOptions = {},
+): ReadProjectionCacheResult {
+  const environment = options.environment ?? process.env;
+  const registry = selectedRegistry(environment, options.registry);
+  return readCachedPreparedCapability(
+    prepareCapability(request, environment, registry),
+    { ...options, environment, registry },
+  );
+}
+
+export async function revalidatePreparedCapability(
+  invocation: PreparedInvocation,
+  options: PreparedReadOptions,
+  cachedBeforeOverride?: ReadProjectionCacheResult | null,
+): Promise<RevalidatedCapability> {
+  const environment = options.environment ?? process.env;
+  validateReadOptions(options);
+  const query = withInvocationAuthorityAdmission(
+    invocation,
+    environment,
+    () => {
+      const prepared = invocation.auth.subject === undefined
+        ? null
+        : createReadProjectionQueryForInvocation(
+            invocation,
+            environment,
+            options.registry,
+          );
+      requireCurrentAuthRealm(invocation, prepared, environment);
+      return prepared;
+    },
+  );
+  let cacheReadError: unknown = null;
+  let cachedBefore: ReadProjectionCacheResult | null;
+  try {
+    cachedBefore = cachedBeforeOverride !== undefined
+      ? cachedBeforeOverride
+      : query === null
+        ? null
+        : readCachedPreparedCapability(invocation, {
+            environment,
+            registry: options.registry,
+            ...(options.now === undefined ? {} : { now: options.now }),
+            ...(options.freshForMs === undefined
+              ? {}
+              : { freshForMs: options.freshForMs }),
+          });
+  } catch (error) {
+    withInvocationAuthorityAdmission(
+      invocation,
+      environment,
+      () => requireCurrentAuthRealm(invocation, query, environment),
+    );
+    cacheReadError = error;
+    cachedBefore = null;
+  }
+  withInvocationAuthorityAdmission(
+    invocation,
+    environment,
+    () => requireCurrentAuthRealm(invocation, query, environment),
+  );
+  const live = await (options.executeRead ?? executeReadInvocation)(
+    invocation,
+    {
+      headed: options.headed ?? false,
+      environment,
+      registry: options.registry,
+      ...(options.signal === undefined ? {} : { signal: options.signal }),
+    },
+  );
+  try {
+    return withInvocationAuthorityAdmission(
+      invocation,
+      environment,
+      () => {
+      if (authRealmState(invocation, query, environment) !== "matches") {
+        throw liveReadDiscardedError(invocation);
+      }
+      if (query === null) {
+        return Object.freeze({
+          cachedBefore,
+          live,
+          cache: Object.freeze({
+            status: "skipped" as const,
+            reason: "auth-subject-unbound" as const,
+          }),
+        });
+      }
+      if (live.receipt.status !== "succeeded") {
+        if (cacheReadError !== null) {
+          return Object.freeze({
+            cachedBefore,
+            live,
+            cache: Object.freeze({
+              status: "error" as const,
+              message: boundedErrorMessage(cacheReadError),
+            }),
+          });
+        }
+        if (cachedBefore?.status !== "hit") {
+          return Object.freeze({
+            cachedBefore,
+            live,
+            cache: Object.freeze({
+              status: "miss" as const,
+              reason: "no-cached-snapshot" as const,
+            }),
+          });
+        }
+        return Object.freeze({
+          cachedBefore,
+          live,
+          cache: Object.freeze({
+            status: "retained" as const,
+            reason: "live-read-failed" as const,
+          }),
+        });
+      }
+      const publicationOptions = {
+        environment,
+        runId: live.receipt.runId,
+        startedAt: live.receipt.startedAt,
+        finishedAt: live.receipt.finishedAt,
+      } as const;
+      let publication: ReadProjectionPublication;
+      try {
+        if (isReadProjectionCorruptionError(cacheReadError)) {
+          publication = repairReadProjection(
+            query,
+            live.output,
+            {
+              ...publicationOptions,
+              corruption: cacheReadError,
+              observedBeforeLive: true,
+            },
+          );
+        } else {
+          try {
+            publication = publishReadProjection(
+              query,
+              live.output,
+              publicationOptions,
+            );
+          } catch (error) {
+            if (!isReadProjectionCorruptionError(error)) throw error;
+            publication = repairReadProjection(
+              query,
+              live.output,
+              {
+                ...publicationOptions,
+                corruption: error,
+                observedBeforeLive: false,
+              },
+            );
+          }
+        }
+      } catch (error) {
+        if (
+          error instanceof ReadProjectionDurableRepairError
+          && error.queryKey === query.key
+        ) {
+          publication = error.publication;
+        } else {
+          return Object.freeze({
+            cachedBefore,
+            live,
+            cache: Object.freeze({
+              status: "error" as const,
+              message: boundedErrorMessage(error),
+            }),
+          });
+        }
+      }
+      if (authRealmState(invocation, query, environment) !== "matches") {
+        removeReadProjection(query, environment);
+        throw new Error(
+          `auth locator ${invocation.auth.id} changed while the live read was being published; its result was discarded`,
+        );
+      }
+      return Object.freeze({
+        cachedBefore,
+        live,
+        cache: Object.freeze({
+          status: "stored" as const,
+          publication,
+        }),
+      });
+    },
+      { maximumWaitMs: READ_PROJECTION_TRANSITION_SETTLEMENT_WAIT_MS },
+    );
+  } catch (error) {
+    if (isOptionalAdmissionRewrite(error)) {
+      throw liveReadDiscardedError(invocation, error);
+    }
+    throw error;
+  }
+}
+
+export async function revalidateCapability(
+  request: CapabilityReadRequest,
+  options: RevalidateCapabilityOptions = {},
+): Promise<RevalidatedCapability> {
+  const environment = options.environment ?? process.env;
+  const registry = selectedRegistry(environment, options.registry);
+  return revalidatePreparedCapability(
+    prepareCapability(request, environment, registry),
+    { ...options, environment, registry },
+  );
+}
+
+/**
+ * Return the current exact snapshot synchronously and start one explicit live
+ * R1 revalidation. UI callers can render `cached` before awaiting
+ * `revalidation`; Ghostget never hides a transport refresh in a cache lookup.
+ */
+export function staleWhileRevalidateCapability(
+  request: CapabilityReadRequest,
+  options: RevalidateCapabilityOptions = {},
+): {
+  readonly cached: ReadProjectionCacheResult | null;
+  readonly revalidation: Promise<RevalidatedCapability>;
+} {
+  const environment = options.environment ?? process.env;
+  const registry = selectedRegistry(environment, options.registry);
+  const invocation = prepareCapability(request, environment, registry);
+  validateReadOptions(options);
+  let cached: ReadProjectionCacheResult | null = null;
+  let cacheReadCompleted = false;
+  if (invocation.auth.subject !== undefined) {
+    try {
+      cached = readCachedPreparedCapability(invocation, {
+        ...options,
+        environment,
+        registry,
+      });
+      cacheReadCompleted = true;
+    } catch {
+      // A corrupt or unavailable local projection must not prevent the live
+      // R1 contract from running and reporting its independent outcome.
+    }
+  }
+  return Object.freeze({
+    cached,
+    revalidation: revalidatePreparedCapability(
+      invocation,
+      { ...options, environment, registry },
+      cacheReadCompleted ? cached : undefined,
+    ),
+  });
+}

package/src/read-effect-platform.ts

@@ -0,0 +1,7 @@
+import * as Effect from "effect/Effect";
+import { ReadEffectFailure } from "./read-effect";
+
+/** Adapts a native operation. AbortSignal/native settlement rules belong to the
+ * supplied product port, not to interruption of this Promise subscription. */
+export const readNative = <A>(work: () => Promise<A>): Effect.Effect<A, ReadEffectFailure> =>
+  Effect.tryPromise({ try: work, catch: cause => new ReadEffectFailure({ cause }) });

package/src/read-effect-runtime.ts

@@ -0,0 +1,14 @@
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Option from "effect/Option";
+import type { ReadEffectFailure } from "./read-effect";
+
+/** Only genuine Promise/plugin boundaries interpret closed read programs. */
+export async function runReadEffect<A>(program: Effect.Effect<A, ReadEffectFailure>): Promise<A> {
+  const exit = await Effect.runPromiseExit(program);
+  if (Exit.isSuccess(exit)) return exit.value;
+  const failure = Cause.failureOption(exit.cause);
+  if (Option.isSome(failure)) throw failure.value.cause;
+  throw Cause.squash(exit.cause);
+}

package/src/read-effect.ts

@@ -0,0 +1,52 @@
+import * as Cause from "effect/Cause";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Option from "effect/Option";
+
+/** A foreign boundary failure retains the original rejection privately. */
+export class ReadEffectFailure extends Data.TaggedError("ReadEffectFailure")<{
+  readonly cause: unknown;
+  readonly cleanupCause?: unknown;
+  readonly primaryCause?: unknown;
+}> { }
+
+export const readAttempt = <A>(work: () => A): Effect.Effect<A, ReadEffectFailure> =>
+  Effect.try({ try: work, catch: cause => new ReadEffectFailure({ cause }) });
+
+/** Native acquisition and finalization settle before ownership leaves the scope.
+ * A failing finalizer retains the primary failure while preserving the previous
+ * finally-block precedence at the Promise boundary. */
+export function withReadResource<Resource, A, R>(
+  acquire: Effect.Effect<Resource, ReadEffectFailure, R>,
+  use: (resource: Resource) => Effect.Effect<A, ReadEffectFailure, R>,
+  release: (resource: Resource) => Effect.Effect<void, ReadEffectFailure, R>,
+
+): Effect.Effect<A, ReadEffectFailure, R> {
+  return Effect.gen(function*() {
+    let finalization: Exit.Exit<void, ReadEffectFailure> = Exit.void;
+    const outcome = yield* Effect.scoped(Effect.gen(function*() {
+      const resource = yield* Effect.acquireRelease(
+        acquire,
+        resource =>
+          Effect.exit(release(resource)).pipe(Effect.map(exit => { finalization = exit; }))
+      );
+      return yield* Effect.exit(use(resource));
+    }));
+    return yield* resumeReadOutcome(outcome, finalization);
+  });
+}
+
+/** Preserve native finalizer rejection precedence and the primary Cause. */
+export function resumeReadOutcome<A>(
+  outcome: Exit.Exit<A, ReadEffectFailure>,
+  finalization: Exit.Exit<void, ReadEffectFailure>
+
+): Effect.Effect<A, ReadEffectFailure> {
+  if (Exit.isFailure(finalization)) {
+    const cleanup = Cause.failureOption(finalization.cause);
+    if (Option.isSome(cleanup) && Exit.isFailure(outcome)) return Effect.fail(new ReadEffectFailure({ cause: cleanup.value.cause, primaryCause: outcome.cause }));
+    return Effect.failCause(finalization.cause);
+  }
+  return outcome;
+}