@hraness/ghostget 0.17.2

package/src/index.ts

@@ -0,0 +1,218 @@
+/**
+ * Side-effect-free provider-plugin authoring surface.
+ *
+ * Complete package and runtime validation remains available through
+ * `ghostget plugin check` and the explicitly trusted `ghostget plugin test`
+ * boundary. Importing this module never loads provider runtimes or local
+ * state.
+ */
+import {
+  isPortableProviderPluginVersion as isPortableProviderPluginVersionImplementation,
+  isProviderPluginId as isProviderPluginIdImplementation,
+  isProviderPluginOperationName as isProviderPluginOperationNameImplementation,
+  isProviderPluginSurfaceId as isProviderPluginSurfaceIdImplementation,
+  PROVIDER_PLUGIN_ID_MAX_LENGTH as providerPluginIdMaxLength,
+  PROVIDER_PLUGIN_OPERATION_NAME_MAX_LENGTH as providerPluginOperationNameMaxLength,
+} from "./provider-plugin-identifiers";
+
+export const PROVIDER_PLUGIN_ID_MAX_LENGTH = providerPluginIdMaxLength;
+export const PROVIDER_PLUGIN_OPERATION_NAME_MAX_LENGTH =
+  providerPluginOperationNameMaxLength;
+export const isPortableProviderPluginVersion =
+  isPortableProviderPluginVersionImplementation;
+export const isProviderPluginId = isProviderPluginIdImplementation;
+export const isProviderPluginOperationName =
+  isProviderPluginOperationNameImplementation;
+export const isProviderPluginSurfaceId =
+  isProviderPluginSurfaceIdImplementation;
+
+export type {
+  ProviderPluginId,
+  ProviderPluginOperationName,
+  ProviderPluginSurfaceId,
+} from "./provider-plugin-identifiers";
+
+export type {
+  LocalCliPluginBindingDefinitionV1,
+  LocalCliPluginOperationDefinitionV1,
+  LocalCliPluginRuntimeHooksV1,
+  LocalCliPluginRuntimeStatusV1,
+  LocalCliPluginRuntimeV1,
+  LinkedDevicePluginBindingDefinitionV1,
+  PortableProviderPluginProjectionDefinitionV1,
+  ProviderApiPluginBindingDefinitionV1,
+  ProviderApiPluginOperationDefinitionV1,
+  ProviderPluginAuthKind,
+  ProviderPluginAcceptedTargetReconciliationContextV1,
+  ProviderPluginBindingDefinitionV1,
+  ProviderPluginContractStateV1,
+  ProviderPluginDefinitionV1,
+  ProviderPluginImplementationSourceDefinitionV1,
+  ProviderPluginLinkedDeviceLifecycleRuntimeV1,
+  ProviderPluginOmniDefinitionV1,
+  ProviderPluginOperationDefinitionV1,
+  ProviderPluginReconciliationDefinitionV1,
+  ProviderPluginReconciliationContextV1,
+  ProviderPluginReconciliationOptionsV1,
+  ProviderPluginSubjectDefinitionV1,
+  ProviderPluginTransport,
+  WebSessionApiPluginBindingDefinitionV1,
+  WebSessionPluginOperationDefinitionV1,
+} from "./provider-plugin";
+
+export {
+  localCliToolArtifactForCurrentRuntime,
+  parseLocalCliToolIdentityV1,
+} from "./local-cli-tool-identity";
+
+export type {
+  LocalCliToolArtifactIdentityV1,
+  LocalCliToolIdentityV1,
+} from "./local-cli-tool-identity";
+
+export type {
+  LocalCliCleanupResourceIdentityV1,
+  LocalCliPrivateRootIdentityV1,
+  LocalCliProcessGroupIdentityV1,
+  ProviderPluginCleanupResourceIdentity,
+} from "./provider-plugin-cleanup-resource";
+
+export {
+  MESSAGE_LIKE_ME_SOURCE_CONVERSATION_COORDINATE_V1_CONTRACT_ID,
+  MESSAGE_LIKE_ME_SOURCE_CONVERSATION_COORDINATE_V1_SCHEMA_VERSION,
+  GHOSTGET_MESSAGING_CLIENT_INTENT_BINDING_V1_CONTRACT_ID,
+  GHOSTGET_MESSAGING_CLIENT_INTENT_BINDING_V1_FORMAT,
+  GHOSTGET_MESSAGING_CONTEXT_INSTANCE_V1_CONTRACT_ID,
+  GHOSTGET_MESSAGING_CONTEXT_INSTANCE_V2_CONTRACT_ID,
+  GHOSTGET_MESSAGING_CONTEXT_BINDING_V1_CONTRACT_DESCRIPTOR,
+  GHOSTGET_MESSAGING_CONTEXT_BINDING_V1_CONTRACT_HASH,
+  GHOSTGET_MESSAGING_CONTEXT_BINDING_V1_CONTRACT_ID,
+  GHOSTGET_MESSAGING_CONTEXT_BINDING_V1_FORMAT,
+  GHOSTGET_MESSAGING_CONTEXT_BINDING_V2_CONTRACT_DESCRIPTOR,
+  GHOSTGET_MESSAGING_CONTEXT_BINDING_V2_CONTRACT_HASH,
+  GHOSTGET_MESSAGING_CONTEXT_BINDING_V2_CONTRACT_ID,
+  GHOSTGET_MESSAGING_CONTEXT_BINDING_V2_FORMAT,
+  GHOSTGET_MESSAGING_RECEIPT_BINDING_V1_CONTRACT_DESCRIPTOR,
+  GHOSTGET_MESSAGING_RECEIPT_BINDING_V1_CONTRACT_HASH,
+  GHOSTGET_MESSAGING_RECEIPT_BINDING_V1_CONTRACT_ID,
+  GHOSTGET_MESSAGING_RECEIPT_BINDING_V1_FORMAT,
+  GHOSTGET_MESSAGING_RECEIPT_BINDING_V2_CONTRACT_DESCRIPTOR,
+  GHOSTGET_MESSAGING_RECEIPT_BINDING_V2_CONTRACT_HASH,
+  GHOSTGET_MESSAGING_RECEIPT_BINDING_V2_CONTRACT_ID,
+  GHOSTGET_MESSAGING_RECEIPT_BINDING_V2_FORMAT,
+  createBeeperMessageLikeMeContextBindingV1,
+  createBeeperMessageLikeMeContextBindingV2,
+  createGhostgetMessagingReceiptBindingV1,
+  createGhostgetMessagingReceiptBindingV2,
+  messageLikeMeSourceConversationCoordinateBindingV1,
+  parseMessageLikeMeSourceConversationCoordinateV1,
+  parseGhostgetMessagingClientIntentBindingV1,
+  parseGhostgetMessagingContextBindingV1,
+  parseGhostgetMessagingContextBindingV2,
+  ghostgetMessagingContextBindingSha256V1,
+  ghostgetMessagingContextBindingSha256V2,
+} from "./message-like-me-agentic-messaging";
+
+export type {
+  MessageLikeMeSourceConversationCoordinateBindingV1,
+  MessageLikeMeSourceConversationCoordinateV1,
+  GhostgetMessagingClientIntentBindingV1,
+  GhostgetMessagingContextBindingV1,
+  GhostgetMessagingContextBindingV2,
+  GhostgetMessagingReceiptBindingV1,
+  GhostgetMessagingReceiptBindingV2,
+  GhostgetMessagingReceiptStateV1,
+  GhostgetMessagingReceiptStateV2,
+} from "./message-like-me-agentic-messaging";
+
+export {
+  startProviderPluginCleanupTrackedOperation,
+} from "./provider-plugin-cleanup-execution";
+
+export type {
+  ProviderPluginCleanupBarrierRegistrar,
+  ProviderPluginCleanupProofController,
+  ProviderPluginCleanupResourcePublisher,
+} from "./provider-plugin-cleanup-execution";
+
+export type {
+  LocalCliDispatchEvent,
+  LocalCliExecution,
+  LocalCliExecutionOptions,
+  LocalCliFileResolver,
+  LocalCliOperationDeadline,
+  LocalCliOperationExecutor,
+  LocalCliProviderAcceptedMutationTargetEvent,
+  LocalCliProviderBoundMutationTargetEvent,
+} from "./local-cli-execution";
+
+export type { LocalCliRecipe } from "./model";
+
+export type {
+  PortableLinkedDevicePluginBindingV1,
+  PortableProviderApiPluginBindingV1,
+  PortableProviderApiPluginOperationV1,
+  PortableProviderPluginAuthKind,
+  PortableProviderPluginBindingV1,
+  PortableProviderPluginCapabilitiesV1,
+  PortableProviderPluginFileV1,
+  PortableProviderPluginManifestV1,
+  PortableProviderPluginProvenanceV1,
+  PortableProviderPluginSessionMaterialName,
+  PortableProviderPluginTransport,
+  PortableWebSessionApiPluginBindingV1,
+  PortableWebSessionPluginOperationV1,
+} from "./provider-plugin-package";
+
+export type {
+  PortablePluginCapabilityRequest,
+  PortablePluginCapabilityResult,
+  PortablePluginCredentialBinding,
+  PortablePluginCredentialSink,
+  PortablePluginHttpBody,
+  PortablePluginIdentity,
+  PortablePluginInvocationAuth,
+  PortablePluginInvocationFile,
+  PortablePluginJsonObject,
+  PortablePluginJsonValue,
+  PortablePluginRoute,
+  PortablePluginVersionedStateResult,
+  PortableProviderPluginHostMessage,
+  PortableProviderPluginMessage,
+  PortableProviderPluginMessageResult,
+  PortableProviderPluginProcessMessage,
+} from "./provider-plugin-protocol";
+
+export {
+  ARTICLE_DRAFT_DOCUMENT_IMAGE_SCHEMA_VERSION,
+  ARTICLE_DRAFT_DOCUMENT_SCHEMA_VERSION,
+  MAX_ARTICLE_DRAFT_BLOCKS,
+  MAX_ARTICLE_DRAFT_CHARACTERS,
+  MAX_ARTICLE_DRAFT_DOCUMENT_BYTES,
+  articleDraftDocumentIssues,
+  articleDraftDocumentV2Issues,
+  parseArticleDraftDocument,
+  parseArticleDraftDocumentV2,
+} from "./article-draft-document";
+
+export type {
+  ArticleDraftDocument,
+  ArticleDraftDocumentLimits,
+  ArticleDraftDocumentV2,
+  ArticleDraftDocumentV2Limits,
+  ArticleDraftImageBlock,
+  ArticleDraftLinkRange,
+  ArticleDraftStyleRange,
+  ArticleDraftTextBlock,
+  ArticleDraftTextBlockType,
+} from "./article-draft-document";
+
+export {
+  MAX_X_STATUS_ARTICLE_EMBED_CHARACTERS,
+  projectXStatusArticleEmbed,
+} from "./article-draft-embeds";
+
+export type {
+  ArticleDraftEmbedTarget,
+  XStatusArticleEmbed,
+} from "./article-draft-embeds";

package/src/invocation-read-platform.ts

@@ -0,0 +1,55 @@
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { readAttempt, ReadEffectFailure } from "./read-effect";
+import type { InvocationResult, RunReceipt } from "./runtime";
+import type { ReadFailureProjection } from "./web-session-execution";
+
+export type ReadExecution = {
+  readonly status: "succeeded" | "failed" | "partial" | "indeterminate";
+  readonly output: unknown;
+  readonly finalUrl: string | null;
+  readonly dispatchStarted: boolean;
+  readonly dispatch: RunReceipt["dispatch"];
+  readonly error?: string;
+  readonly readFailure?: ReadFailureProjection;
+  readonly noOp?: true;
+  readonly privateArtifactsPreserved?: boolean;
+  readonly recoveryHandle?: string;
+};
+
+export type ReadInvocationNative = {
+  readonly provisional: RunReceipt;
+  readonly transportLabel: string;
+  readonly apiOperation: boolean;
+  readonly execute: () => Promise<unknown>;
+  readonly persist: (receipt: RunReceipt) => void;
+  readonly parse: (raw: unknown) => ReadExecution;
+  readonly rejected: (cause: unknown) => ReadExecution;
+  readonly now: () => string;
+  readonly finalOrigin: (url: string | null) => string | null;
+  readonly recoveryHandle: (value: string | undefined) => string | null;
+  readonly redact: (value: string) => string;
+};
+
+function platform(native: ReadInvocationNative) {
+  return {
+    provisional: native.provisional,
+    transportLabel: native.transportLabel,
+    apiOperation: native.apiOperation,
+    execute: Effect.tryPromise({ try: native.execute, catch: cause => new ReadEffectFailure({ cause }) }),
+    persist: (receipt: RunReceipt) => readAttempt(() => native.persist(receipt)),
+    parse: (raw: unknown) => readAttempt(() => native.parse(raw)),
+    rejected: (cause: unknown) => readAttempt(() => native.rejected(cause)),
+    now: readAttempt(native.now),
+    finalOrigin: (url: string | null) => readAttempt(() => native.finalOrigin(url)),
+    recoveryHandle: native.recoveryHandle,
+    redact: native.redact,
+  };
+}
+
+export class ReadInvocationPlatform extends Context.Tag("wrench/ReadInvocationPlatform/v1")<ReadInvocationPlatform, ReturnType<typeof platform>>() { }
+
+export const ReadInvocationPlatformLive = (native: ReadInvocationNative): Layer.Layer<ReadInvocationPlatform> => Layer.succeed(ReadInvocationPlatform, platform(native));
+
+export type ReadInvocationOutcome = InvocationResult;

package/src/invocation-read-program.ts

@@ -0,0 +1,93 @@
+import * as Effect from "effect/Effect";
+import * as Either from "effect/Either";
+import {
+  ReadInvocationPlatform,
+  type ReadExecution,
+  type ReadInvocationOutcome
+} from "./invocation-read-platform";
+import { readAttempt, ReadEffectFailure } from "./read-effect";
+import { readFailureProjection } from "./web-session-execution";
+
+const failed = (error: string): ReadExecution => ({
+  status: "failed",
+  output: null,
+  finalUrl: null,
+  dispatchStarted: false,
+  dispatch: { planned: 0, started: 0, verified: 0 },
+  error
+});
+
+/** The complete R1 publication sequence: provisional receipt before execution,
+ * bounded foreign decoding, zero-dispatch proof, redaction and final receipt
+ * before output. R2/R3 confirmation and journal transitions remain separate. */
+export const readInvocationProgram: Effect.Effect<ReadInvocationOutcome, ReadEffectFailure, ReadInvocationPlatform> = Effect.gen(function*() {
+  const platform = yield* ReadInvocationPlatform;
+  yield* platform.persist(platform.provisional).pipe(Effect.mapError(error => new ReadEffectFailure({
+    cause: new Error("refusing to start execution because its provisional receipt could not be stored", { cause: error.cause })
+  })));
+  const result = yield* Effect.either(platform.execute);
+  let execution: ReadExecution;
+  if (Either.isLeft(result)) execution = yield* platform.rejected(result.left.cause);
+  else execution = yield* platform.parse(result.right).pipe(Effect.catchTag(
+    "ReadEffectFailure",
+    () => Effect.succeed(failed("provider executor terminated without returning a bounded result"))
+  ));
+  if (execution.dispatch.planned !== 0 || execution.dispatch.started !== 0
+    || execution.dispatch.verified !== 0
+    || execution.dispatchStarted
+    || execution.noOp === true
+    || (execution.status !== "succeeded" && execution.status !== "failed")) {
+    execution = failed("provider executor returned invalid dispatch progress");
+  }
+  const readFailure = execution.status === "failed"
+    ? execution.readFailure ?? readFailureProjection("contract-drift")
+    : undefined;
+  const output = readFailure === undefined ? execution.output : null;
+  const privateArtifactsPreserved = execution.privateArtifactsPreserved === true;
+  const recoveryHandle = platform.recoveryHandle(execution.recoveryHandle);
+  const recoveryMessage = privateArtifactsPreserved
+    ? `private browser artifacts were preserved; ghostget doctor must prove and complete exact browser-session recovery before retry${recoveryHandle === null ? "" : `; recovery handle: ${recoveryHandle}`}`
+    : null;
+  const finishedAt = yield* platform.now;
+  const finalOrigin = yield* platform.finalOrigin(execution.finalUrl);
+  const error = yield* readAttempt(() => {
+    if (execution.error === undefined) return null;
+    if (recoveryMessage !== null) return recoveryMessage;
+    const reason = platform.apiOperation ? platform.redact(execution.error).slice(0, 2_000) : null;
+    return platform.redact(platform.apiOperation
+      ? `${platform.transportLabel} operation failed before the dispatch boundary${reason === null ? "" : `; reason: ${reason}`}`
+      : "browser recipe failed before the dispatch boundary");
+  });
+  const receipt = {
+    ...platform.provisional,
+    status: execution.status,
+    dispatchStarted: false,
+    dispatch: execution.dispatch,
+    finishedAt,
+    finalOrigin,
+    error
+  };
+  const stored = yield* Effect.either(platform.persist(receipt));
+  if (Either.isLeft(stored)) return {
+    receipt: {
+      ...receipt,
+      status: "failed" as const,
+      error: `${platform.transportLabel} read completed, but its final receipt could not be stored${recoveryMessage === null ? "" : `; ${recoveryMessage}`}`
+    },
+    output: null,
+    replayed: false,
+    readFailure: readFailure?.category === "cleanup-required"
+      ? readFailure
+      : readFailureProjection("contract-drift"),
+    privateArtifactsPreserved,
+    ...(recoveryHandle === null ? {} : { recoveryHandle }),
+  };
+  return {
+    receipt,
+    output,
+    replayed: false,
+    ...(readFailure === undefined ? {} : { readFailure }),
+    privateArtifactsPreserved,
+    ...(recoveryHandle === null ? {} : { recoveryHandle })
+  };
+});

package/src/invocation-read-runtime.ts

@@ -0,0 +1,11 @@
+import * as Effect from "effect/Effect";
+import { readInvocationProgram } from "./invocation-read-program";
+import {
+  ReadInvocationPlatformLive,
+  type ReadInvocationNative,
+  type ReadInvocationOutcome
+} from "./invocation-read-platform";
+import { runReadEffect } from "./read-effect-runtime";
+
+export const runReadInvocation = (native: ReadInvocationNative): Promise<ReadInvocationOutcome> =>
+  runReadEffect(readInvocationProgram.pipe(Effect.provide(ReadInvocationPlatformLive(native))));