@procedures/store 0.0.0-stage → 0.1.0

package/src/storage/index.ts

@@ -0,0 +1,61 @@
+/**
+ * Procedure Storage Module
+ *
+ * Enables procedure registry to be backed by CollectionStorage.
+ * Provides persistence, sync, and remote registry capabilities.
+ */
+
+// Types
+export type {
+  SerializedProcedure,
+  HandlerReference,
+  HandlerLoader,
+  SyncDirection,
+  ConflictResolution,
+  WriteStrategy,
+  SyncConflict,
+  SyncResult,
+  SyncStatus,
+  SyncedRegistryOptions,
+  ProcedureStorageConfig,
+} from "./types.js";
+
+// Serialization
+export {
+  serializeProcedure,
+  deserializeProcedure,
+  deserializeProcedureSync,
+  getProcedureKey,
+  getSerializedKey,
+  serializeProcedures,
+  deserializeProcedures,
+  createDynamicHandlerLoader,
+} from "./serialization.js";
+export type { SerializeOptions, DeserializeOptions } from "./serialization.js";
+
+// The collection storages that need a Client (before: "@procedures/client/collections")
+export { ApiStorage } from "./api.js";
+export type { ApiStorageOptions } from "./api.js";
+export { HybridStorage } from "./hybrid.js";
+export type { HybridStorageOptions } from "./hybrid.js";
+
+// Adapter
+export { ProcedureStorageAdapter } from "./adapter.js";
+export type { ProcedureStorageAdapterOptions } from "./adapter.js";
+
+// Synced Registry
+export { SyncedProcedureRegistry, getProcedureStore } from "./synced-registry.js";
+export type { SyncedRegistrationOptions } from "./synced-registry.js";
+
+// Factory
+export {
+  createSyncedRegistry,
+  createMemorySyncedRegistry,
+  createApiSyncedRegistry,
+  createHybridSyncedRegistry,
+  createCustomSyncedRegistry,
+} from "./factory.js";
+export type { CreateSyncedRegistryConfig } from "./factory.js";
+
+// procedure.register (the other store procedures are in ../program-store)
+export { procedureRegisterProcedure } from "./procedures.js";

package/src/storage/procedures.ts

@@ -0,0 +1,146 @@
+/**
+ * procedure.register: register a procedure at run time, from a handler reference.
+ *
+ * With `persist`, the procedure goes into the store of a synced registry (`createSyncedRegistry()`),
+ * and only with a handler that the store's loader allows: never a stub (deep dive CORE-16). Without
+ * a store, `persist` fails with the code NOT_CONFIGURED.
+ *
+ * The programs of `procedure.define` have their own store: `procedure.store`, `load` and `sync`
+ * (../program-store/procedures.ts, roadmap 3.2).
+ */
+
+import { defineProcedure } from "@procedures/client";
+import type { AnyProcedure, ProcedureContext, ProcedurePath } from "@procedures/client";
+import { PROCEDURE_REGISTRY, type ProcedureRegistry } from "@procedures/client";
+import { pathToKey } from "@procedures/client";
+import type { HandlerReference, SerializedProcedure } from "./types.js";
+import { deserializeProcedure, deserializeProcedureSync } from "./serialization.js";
+import { getProcedureStore, type SyncedProcedureRegistry } from "./synced-registry.js";
+import { ProcedureStoreError } from "../errors.js";
+
+// =============================================================================
+// Any Schema Helper
+// =============================================================================
+
+const anySchema: {
+  parse: (data: unknown) => unknown;
+  safeParse: (data: unknown) => { success: true; data: unknown };
+  _output: unknown;
+} = {
+  parse: (data: unknown) => data,
+  safeParse: (data: unknown) => ({ success: true as const, data }),
+  _output: undefined as unknown,
+};
+
+// =============================================================================
+// The store of the caller
+// =============================================================================
+
+export { ProcedureStoreError } from "../errors.js";
+
+/** The registry of the caller: the context's registry when it has one, else the global one. */
+function callerRegistry(ctx: ProcedureContext | undefined): ProcedureRegistry {
+  return (ctx as (ProcedureContext & { registry?: ProcedureRegistry }) | undefined)?.registry ?? PROCEDURE_REGISTRY;
+}
+
+/** The store of the caller's registry, or a NOT_CONFIGURED error. */
+function requireStore(ctx: ProcedureContext | undefined, what: string): SyncedProcedureRegistry {
+  const store = getProcedureStore(callerRegistry(ctx));
+  if (!store) {
+    throw new ProcedureStoreError(
+      "NOT_CONFIGURED",
+      `${what} needs a procedure store, and this registry has none. ` +
+        "Wrap the registry with createSyncedRegistry() or new SyncedProcedureRegistry()."
+    );
+  }
+  return store;
+}
+
+
+// =============================================================================
+// procedure.register - Register procedure at runtime
+// =============================================================================
+
+interface RegisterInput {
+  /** Procedure path */
+  path: ProcedurePath;
+  /** Procedure metadata */
+  metadata?: Record<string, unknown>;
+  /** Whether procedure supports streaming */
+  streaming?: boolean;
+  /** Handler reference for loading */
+  handlerRef?: HandlerReference;
+  /** Whether to persist to storage */
+  persist?: boolean;
+}
+
+interface RegisterOutput {
+  success: boolean;
+  message: string;
+  path: ProcedurePath;
+  /** False for a declaration: the procedure has no handler, and a Client sends its calls to the transport */
+  hasHandler: boolean;
+}
+
+export const procedureRegisterProcedure: AnyProcedure = defineProcedure({
+  path: ["procedure", "register"],
+  input: anySchema as any,
+  output: anySchema as any,
+  metadata: {
+    description: "Register a procedure at runtime",
+    tags: ["procedure", "registry", "storage"],
+  },
+  handler: async (input: RegisterInput, ctx: ProcedureContext): Promise<RegisterOutput> => {
+    const { path, metadata = {}, streaming, handlerRef, persist = false } = input;
+    const key = pathToKey(path);
+    const serialized: SerializedProcedure = {
+      path,
+      metadata,
+      streaming,
+      handlerRef,
+      storedAt: Date.now(),
+    };
+
+    if (persist) {
+      // A stored procedure needs a handler: never store a stub (deep dive CORE-16)
+      const store = requireStore(ctx, "procedure.register with persist");
+      const loader = store.getHandlerLoader();
+      const procedure = handlerRef && loader ? await deserializeProcedure(serialized, { handlerLoader: loader }) : undefined;
+      if (!procedure?.handler) {
+        throw new ProcedureStoreError(
+          "NO_HANDLER",
+          `procedure.register with persist needs a handler for ${key}: give a handlerRef ` +
+            "that the handler loader of the store allows."
+        );
+      }
+      store.register(procedure, { override: false, handlerRef });
+      await store.flushWrites();
+      return { success: true, message: `Registered and stored ${key}`, path, hasHandler: true };
+    }
+
+    // No persist: load the handler when the store's loader allows it, else declare a stub
+    const loader = getProcedureStore(callerRegistry(ctx))?.getHandlerLoader();
+    const procedure =
+      handlerRef && loader ? await deserializeProcedure(serialized, { handlerLoader: loader }) : deserializeProcedureSync(serialized);
+    try {
+      callerRegistry(ctx).register(procedure, { override: false });
+    } catch (error) {
+      return {
+        success: false,
+        message: error instanceof Error ? error.message : "Registration failed",
+        path,
+        hasHandler: false,
+      };
+    }
+
+    const hasHandler = typeof procedure.handler === "function";
+    return {
+      success: true,
+      message: hasHandler
+        ? `Registered ${key}`
+        : `Registered ${key} with no handler: a Client sends the calls of this path to its transport`,
+      path,
+      hasHandler,
+    };
+  },
+});

package/src/storage/serialization.ts

@@ -0,0 +1,283 @@
+/**
+ * Procedure Serialization
+ *
+ * Utilities for converting procedures to/from serialized format.
+ * Enables storage and transmission of procedure definitions.
+ */
+
+import type { AnyProcedure, ProcedurePath } from "@procedures/client";
+import { pathToKey } from "@procedures/client";
+import type { SerializedProcedure, HandlerReference, HandlerLoader } from "./types.js";
+
+// =============================================================================
+// Any Schema (for deserialized procedures without schemas)
+// =============================================================================
+
+/**
+ * Passthrough schema that accepts any value.
+ * Used for deserialized procedures where original schemas aren't available.
+ */
+const anySchema: {
+  parse: (data: unknown) => unknown;
+  safeParse: (data: unknown) => { success: true; data: unknown };
+  _output: unknown;
+} = {
+  parse: (data: unknown) => data,
+  safeParse: (data: unknown) => ({ success: true as const, data }),
+  _output: undefined as unknown,
+};
+
+// =============================================================================
+// Serialize Procedure
+// =============================================================================
+
+/**
+ * Options for serializing a procedure.
+ */
+export interface SerializeOptions {
+  /** Handler reference to store (optional, handlers can't be serialized directly) */
+  handlerRef?: HandlerReference | undefined;
+
+  /** Whether to include version info */
+  includeVersion?: boolean | undefined;
+}
+
+/**
+ * Serialize a procedure to storable format.
+ *
+ * Note: Handler functions cannot be serialized. If the procedure has a handler,
+ * you should provide a `handlerRef` that can be used to load it later.
+ *
+ * @param procedure - Procedure to serialize
+ * @param options - Serialization options
+ * @returns Serialized procedure definition
+ *
+ * @example
+ * ```typescript
+ * const serialized = serializeProcedure(myProcedure, {
+ *   handlerRef: {
+ *     module: "@procedures/cli-run",
+ *     export: "libScanHandler",
+ *   },
+ * });
+ * ```
+ */
+export function serializeProcedure(
+  procedure: AnyProcedure,
+  options: SerializeOptions = {}
+): SerializedProcedure {
+  const serialized: SerializedProcedure = {
+    path: procedure.path,
+    metadata: { ...procedure.metadata },
+    storedAt: Date.now(),
+  };
+
+  // Only include streaming if explicitly set
+  if (procedure.streaming !== undefined) {
+    serialized.streaming = procedure.streaming;
+  }
+
+  // Include handler reference if provided
+  if (options.handlerRef) {
+    serialized.handlerRef = options.handlerRef;
+  }
+
+  // Include version if requested
+  if (options.includeVersion) {
+    serialized.version = 1;
+  }
+
+  return serialized;
+}
+
+// =============================================================================
+// Deserialize Procedure
+// =============================================================================
+
+/**
+ * Options for deserializing a procedure.
+ */
+export interface DeserializeOptions {
+  /** Handler loader to restore handlers from references */
+  handlerLoader?: HandlerLoader | undefined;
+}
+
+/**
+ * Deserialize a procedure from stored format.
+ *
+ * Returns a stub procedure without a handler unless a handlerLoader is provided
+ * and the serialized procedure has a handlerRef.
+ *
+ * @param data - Serialized procedure data
+ * @param options - Deserialization options
+ * @returns Procedure (stub if no handler can be loaded)
+ *
+ * @example
+ * ```typescript
+ * // Deserialize as stub (no handler)
+ * const stub = await deserializeProcedure(data);
+ *
+ * // Deserialize with handler loading
+ * const proc = await deserializeProcedure(data, {
+ *   handlerLoader: myLoader,
+ * });
+ * ```
+ */
+export async function deserializeProcedure(
+  data: SerializedProcedure,
+  options: DeserializeOptions = {}
+): Promise<AnyProcedure> {
+  const procedure: AnyProcedure = {
+    path: data.path,
+    input: anySchema,
+    output: anySchema,
+    metadata: { ...data.metadata },
+  };
+
+  // Set streaming if present
+  if (data.streaming !== undefined) {
+    procedure.streaming = data.streaming;
+  }
+
+  // Try to load handler if reference exists and loader is provided
+  if (data.handlerRef && options.handlerLoader) {
+    try {
+      const handler = await options.handlerLoader.load(data.handlerRef);
+      if (handler && typeof handler === "function") {
+        procedure.handler = handler as AnyProcedure["handler"];
+      }
+    } catch {
+      // Handler loading failed, procedure remains a stub
+    }
+  }
+
+  return procedure;
+}
+
+/**
+ * Synchronous version that always returns a stub.
+ * Use when you don't need to load handlers.
+ */
+export function deserializeProcedureSync(data: SerializedProcedure): AnyProcedure {
+  const procedure: AnyProcedure = {
+    path: data.path,
+    input: anySchema,
+    output: anySchema,
+    metadata: { ...data.metadata },
+  };
+
+  if (data.streaming !== undefined) {
+    procedure.streaming = data.streaming;
+  }
+
+  return procedure;
+}
+
+// =============================================================================
+// Storage Key Utilities
+// =============================================================================
+
+/**
+ * Get the storage key (ID) for a procedure.
+ * Uses the dot-separated path as the key.
+ *
+ * @param pathOrProcedure - Procedure path or procedure object
+ * @returns Storage key string
+ */
+export function getProcedureKey(pathOrProcedure: ProcedurePath | AnyProcedure): string {
+  const path = Array.isArray(pathOrProcedure) ? pathOrProcedure : pathOrProcedure.path;
+  return pathToKey(path);
+}
+
+/**
+ * Get the storage key from a serialized procedure.
+ */
+export function getSerializedKey(data: SerializedProcedure): string {
+  return pathToKey(data.path);
+}
+
+// =============================================================================
+// Batch Operations
+// =============================================================================
+
+/**
+ * Serialize multiple procedures.
+ *
+ * @param procedures - Procedures to serialize
+ * @param options - Serialization options
+ * @returns Array of [key, serialized] tuples for batch storage
+ */
+export function serializeProcedures(
+  procedures: AnyProcedure[],
+  options: SerializeOptions = {}
+): Array<[string, SerializedProcedure]> {
+  return procedures.map((proc) => [
+    getProcedureKey(proc),
+    serializeProcedure(proc, options),
+  ]);
+}
+
+/**
+ * Deserialize multiple procedures.
+ *
+ * @param items - Array of serialized procedures
+ * @param options - Deserialization options
+ * @returns Array of procedures
+ */
+export async function deserializeProcedures(
+  items: SerializedProcedure[],
+  options: DeserializeOptions = {}
+): Promise<AnyProcedure[]> {
+  return Promise.all(items.map((item) => deserializeProcedure(item, options)));
+}
+
+// =============================================================================
+// Default Handler Loader
+// =============================================================================
+
+/**
+ * Create a handler loader using dynamic imports of the allowed modules only.
+ *
+ * A stored procedure record names the module of its handler, and the storage can be remote
+ * (`api`, `hybrid`). So the loader imports only the modules in `allowedModules` (exact package
+ * names, or a prefix that ends with "*"), and never a URL or a path (`data:`, `file:`, `node:`,
+ * `./x`, `/x`, a drive letter). Before, it imported any module that a record named: a record
+ * with `node:child_process` ran a shell command (BUGS-2026-07 M11, deep dive CORE-7, DATA-11).
+ *
+ * @param allowedModules - Module names the loader may import, such as "@procedures/git"
+ * @returns Handler loader that uses import() to load allowed modules
+ *
+ * @example
+ * ```typescript
+ * const loader = createDynamicHandlerLoader(["@procedures/*"]);
+ * const handler = await loader.load({
+ *   module: "@procedures/cli-run",
+ *   export: "libScanHandler",
+ * });
+ * ```
+ */
+export function createDynamicHandlerLoader(allowedModules: readonly string[]): HandlerLoader {
+  const allowed = (specifier: string): boolean => {
+    // A URL scheme (data:, file:, node:, C:) or a relative or absolute path is never allowed
+    if (/^[a-z][a-z0-9+.-]*:/i.test(specifier) || /^[./\\]/.test(specifier)) {
+      return false;
+    }
+    return allowedModules.some((entry) =>
+      entry.endsWith("*") ? specifier.startsWith(entry.slice(0, -1)) : specifier === entry
+    );
+  };
+  return {
+    async load(ref: HandlerReference): Promise<unknown | undefined> {
+      if (!allowed(ref.module)) {
+        return undefined;
+      }
+      try {
+        // The specifier is checked against the allowlist above. A bundler cannot follow it.
+        const module = await import(/* @vite-ignore */ ref.module);
+        return module[ref.export];
+      } catch {
+        return undefined;
+      }
+    },
+  };
+}