@pwfabric/runtime 0.0.0-stage → 1.0.0-rc.1

package/dist/connectors/module-loader.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Connector Module Loader
+ *
+ * Mirror of `BlockModuleLoader` (render/dynamic-block-loader.ts) for
+ * kind='connector' / kind='provider' atom bundles: fetches the ESM bundle
+ * from `bundleUrl`, SHA-256 verifies the bytes against
+ * `descriptor.integrity` BEFORE evaluation (same security boundary as block
+ * bundles — a CDN-side compromise must not execute under our origin), then
+ * imports it via a Blob URL and resolves the engine FACTORY under the
+ * stable export convention (`createConnector`, `default` fallback).
+ *
+ * Error isolation: a failed load never throws out of `tryLoad` — the
+ * failure reason is recorded per atom id (`getFailure`) so the registry can
+ * mark its entry failed and consumers degrade honestly. `load` (the raw
+ * form) rejects for callers that want the exception.
+ *
+ * @module @pwfabric/runtime/connectors/module-loader
+ */
+import type { ConnectorEngineDescriptor, ConnectorEngineFactory, ConnectorEngineModule } from './types.js';
+/**
+ * Evaluates verified bundle bytes into a module namespace. Injectable so
+ * tests (and non-browser hosts) can substitute the Blob-URL `import()`
+ * step, which only exists in browsers.
+ */
+export type ConnectorModuleEvaluator = (bytes: ArrayBuffer, descriptor: ConnectorEngineDescriptor) => Promise<ConnectorEngineModule>;
+/**
+ * Loader for connector-engine ESM bundles.
+ *
+ * - Caches loaded factories by atom id
+ * - Deduplicates concurrent requests for the same atom
+ * - Records the last failure reason per atom id (does NOT poison the cache
+ *   — a later retry is allowed and clears the failure on success)
+ */
+export declare class ConnectorModuleLoaderImpl {
+    private readonly cache;
+    private readonly pending;
+    private readonly failures;
+    private readonly evaluate;
+    constructor(options?: {
+        readonly evaluate?: ConnectorModuleEvaluator;
+    });
+    /**
+     * Load a connector engine bundle and return its factory. Rejects on
+     * failure (fetch / integrity / export shape / timeout) after recording
+     * the reason — see `tryLoad` for the non-throwing form.
+     */
+    load(descriptor: ConnectorEngineDescriptor): Promise<ConnectorEngineFactory>;
+    /**
+     * Non-throwing load: `null` on failure, with the reason retrievable via
+     * `getFailure(descriptor.id)`.
+     */
+    tryLoad(descriptor: ConnectorEngineDescriptor): Promise<ConnectorEngineFactory | null>;
+    /** Whether the factory for an atom id is already cached. */
+    isLoaded(atomId: string): boolean;
+    /** Last recorded failure reason for an atom id, or null. */
+    getFailure(atomId: string): string | null;
+    /** Invalidate cache (and failure record) for one atom id or all. */
+    invalidate(atomId?: string): void;
+    private doLoad;
+}
+/**
+ * Create a loader with injectable evaluation (tests / non-browser hosts).
+ */
+export declare function createConnectorModuleLoader(options?: {
+    readonly evaluate?: ConnectorModuleEvaluator;
+}): ConnectorModuleLoaderImpl;
+/**
+ * Singleton instance — mirrors `BlockModuleLoader`.
+ */
+export declare const ConnectorModuleLoader: ConnectorModuleLoaderImpl;

package/dist/connectors/module-loader.js

@@ -0,0 +1,143 @@
+/**
+ * Connector Module Loader
+ *
+ * Mirror of `BlockModuleLoader` (render/dynamic-block-loader.ts) for
+ * kind='connector' / kind='provider' atom bundles: fetches the ESM bundle
+ * from `bundleUrl`, SHA-256 verifies the bytes against
+ * `descriptor.integrity` BEFORE evaluation (same security boundary as block
+ * bundles — a CDN-side compromise must not execute under our origin), then
+ * imports it via a Blob URL and resolves the engine FACTORY under the
+ * stable export convention (`createConnector`, `default` fallback).
+ *
+ * Error isolation: a failed load never throws out of `tryLoad` — the
+ * failure reason is recorded per atom id (`getFailure`) so the registry can
+ * mark its entry failed and consumers degrade honestly. `load` (the raw
+ * form) rejects for callers that want the exception.
+ *
+ * @module @pwfabric/runtime/connectors/module-loader
+ */
+import { verifyIntegrity } from '../render/dynamic-block-loader.js';
+const LOAD_TIMEOUT_MS = 10_000;
+// ============================================================
+// DEFAULT EVALUATOR (browser Blob-URL import)
+// ============================================================
+async function blobImportEvaluator(bytes, _descriptor) {
+    const blob = new Blob([bytes], { type: 'text/javascript' });
+    const blobUrl = URL.createObjectURL(blob);
+    try {
+        return (await import(/* webpackIgnore: true */ blobUrl));
+    }
+    finally {
+        URL.revokeObjectURL(blobUrl);
+    }
+}
+// ============================================================
+// MODULE LOADER
+// ============================================================
+/**
+ * Loader for connector-engine ESM bundles.
+ *
+ * - Caches loaded factories by atom id
+ * - Deduplicates concurrent requests for the same atom
+ * - Records the last failure reason per atom id (does NOT poison the cache
+ *   — a later retry is allowed and clears the failure on success)
+ */
+export class ConnectorModuleLoaderImpl {
+    cache = new Map();
+    pending = new Map();
+    failures = new Map();
+    evaluate;
+    constructor(options) {
+        this.evaluate = options?.evaluate ?? blobImportEvaluator;
+    }
+    /**
+     * Load a connector engine bundle and return its factory. Rejects on
+     * failure (fetch / integrity / export shape / timeout) after recording
+     * the reason — see `tryLoad` for the non-throwing form.
+     */
+    async load(descriptor) {
+        const cached = this.cache.get(descriptor.id);
+        if (cached)
+            return cached.factory;
+        const inflight = this.pending.get(descriptor.id);
+        if (inflight)
+            return inflight;
+        const promise = this.doLoad(descriptor);
+        this.pending.set(descriptor.id, promise);
+        try {
+            const factory = await promise;
+            this.cache.set(descriptor.id, { factory, loadedAt: Date.now() });
+            this.failures.delete(descriptor.id);
+            return factory;
+        }
+        catch (err) {
+            this.failures.set(descriptor.id, err instanceof Error ? err.message : String(err));
+            throw err;
+        }
+        finally {
+            this.pending.delete(descriptor.id);
+        }
+    }
+    /**
+     * Non-throwing load: `null` on failure, with the reason retrievable via
+     * `getFailure(descriptor.id)`.
+     */
+    async tryLoad(descriptor) {
+        try {
+            return await this.load(descriptor);
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Whether the factory for an atom id is already cached. */
+    isLoaded(atomId) {
+        return this.cache.has(atomId);
+    }
+    /** Last recorded failure reason for an atom id, or null. */
+    getFailure(atomId) {
+        return this.failures.get(atomId) ?? null;
+    }
+    /** Invalidate cache (and failure record) for one atom id or all. */
+    invalidate(atomId) {
+        if (atomId) {
+            this.cache.delete(atomId);
+            this.failures.delete(atomId);
+        }
+        else {
+            this.cache.clear();
+            this.failures.clear();
+        }
+    }
+    async doLoad(descriptor) {
+        const fetchAndEvaluate = async () => {
+            const res = await fetch(descriptor.bundleUrl, { credentials: 'omit' });
+            if (!res.ok) {
+                throw new Error(`Bundle fetch failed for ${descriptor.id}: ${res.status}`);
+            }
+            const bytes = await res.arrayBuffer();
+            // Same law as block bundles: integrity is verified BEFORE evaluation.
+            await verifyIntegrity(bytes, descriptor.integrity, descriptor.id);
+            return this.evaluate(bytes, descriptor);
+        };
+        const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error(`Module load timed out after ${LOAD_TIMEOUT_MS / 1000}s`)), LOAD_TIMEOUT_MS));
+        const mod = await Promise.race([fetchAndEvaluate(), timeoutPromise]);
+        const factory = mod.createConnector ?? mod.default;
+        if (typeof factory !== 'function') {
+            throw new Error(`Module at ${descriptor.bundleUrl} does not export a connector factory ` +
+                `(expected 'createConnector' or a default function export)`);
+        }
+        return factory;
+    }
+}
+/**
+ * Create a loader with injectable evaluation (tests / non-browser hosts).
+ */
+export function createConnectorModuleLoader(options) {
+    return new ConnectorModuleLoaderImpl(options);
+}
+/**
+ * Singleton instance — mirrors `BlockModuleLoader`.
+ */
+export const ConnectorModuleLoader = new ConnectorModuleLoaderImpl();
+//# sourceMappingURL=module-loader.js.map

package/dist/connectors/module-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-loader.js","sourceRoot":"","sources":["../../src/connectors/module-loader.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Connector Module Loader\n *\n * Mirror of `BlockModuleLoader` (render/dynamic-block-loader.ts) for\n * kind='connector' / kind='provider' atom bundles: fetches the ESM bundle\n * from `bundleUrl`, SHA-256 verifies the bytes against\n * `descriptor.integrity` BEFORE evaluation (same security boundary as block\n * bundles — a CDN-side compromise must not execute under our origin), then\n * imports it via a Blob URL and resolves the engine FACTORY under the\n * stable export convention (`createConnector`, `default` fallback).\n *\n * Error isolation: a failed load never throws out of `tryLoad` — the\n * failure reason is recorded per atom id (`getFailure`) so the registry can\n * mark its entry failed and consumers degrade honestly. `load` (the raw\n * form) rejects for callers that want the exception.\n *\n * @module @pwfabric/runtime/connectors/module-loader\n */\n\nimport { verifyIntegrity } from '../render/dynamic-block-loader.js'\nimport type {\n  ConnectorEngineDescriptor,\n  ConnectorEngineFactory,\n  ConnectorEngineModule,\n} from './types.js'\n\n// ============================================================\n// TYPES\n// ============================================================\n\n/**\n * Evaluates verified bundle bytes into a module namespace. Injectable so\n * tests (and non-browser hosts) can substitute the Blob-URL `import()`\n * step, which only exists in browsers.\n */\nexport type ConnectorModuleEvaluator = (\n  bytes: ArrayBuffer,\n  descriptor: ConnectorEngineDescriptor\n) => Promise<ConnectorEngineModule>\n\ninterface CachedEngineModule {\n  readonly factory: ConnectorEngineFactory\n  readonly loadedAt: number\n}\n\nconst LOAD_TIMEOUT_MS = 10_000\n\n// ============================================================\n// DEFAULT EVALUATOR (browser Blob-URL import)\n// ============================================================\n\nasync function blobImportEvaluator(\n  bytes: ArrayBuffer,\n  _descriptor: ConnectorEngineDescriptor\n): Promise<ConnectorEngineModule> {\n  const blob = new Blob([bytes], { type: 'text/javascript' })\n  const blobUrl = URL.createObjectURL(blob)\n  try {\n    return (await import(/* webpackIgnore: true */ blobUrl)) as ConnectorEngineModule\n  } finally {\n    URL.revokeObjectURL(blobUrl)\n  }\n}\n\n// ============================================================\n// MODULE LOADER\n// ============================================================\n\n/**\n * Loader for connector-engine ESM bundles.\n *\n * - Caches loaded factories by atom id\n * - Deduplicates concurrent requests for the same atom\n * - Records the last failure reason per atom id (does NOT poison the cache\n *   — a later retry is allowed and clears the failure on success)\n */\nexport class ConnectorModuleLoaderImpl {\n  private readonly cache = new Map<string, CachedEngineModule>()\n  private readonly pending = new Map<string, Promise<ConnectorEngineFactory>>()\n  private readonly failures = new Map<string, string>()\n  private readonly evaluate: ConnectorModuleEvaluator\n\n  constructor(options?: { readonly evaluate?: ConnectorModuleEvaluator }) {\n    this.evaluate = options?.evaluate ?? blobImportEvaluator\n  }\n\n  /**\n   * Load a connector engine bundle and return its factory. Rejects on\n   * failure (fetch / integrity / export shape / timeout) after recording\n   * the reason — see `tryLoad` for the non-throwing form.\n   */\n  async load(descriptor: ConnectorEngineDescriptor): Promise<ConnectorEngineFactory> {\n    const cached = this.cache.get(descriptor.id)\n    if (cached) return cached.factory\n\n    const inflight = this.pending.get(descriptor.id)\n    if (inflight) return inflight\n\n    const promise = this.doLoad(descriptor)\n    this.pending.set(descriptor.id, promise)\n\n    try {\n      const factory = await promise\n      this.cache.set(descriptor.id, { factory, loadedAt: Date.now() })\n      this.failures.delete(descriptor.id)\n      return factory\n    } catch (err) {\n      this.failures.set(descriptor.id, err instanceof Error ? err.message : String(err))\n      throw err\n    } finally {\n      this.pending.delete(descriptor.id)\n    }\n  }\n\n  /**\n   * Non-throwing load: `null` on failure, with the reason retrievable via\n   * `getFailure(descriptor.id)`.\n   */\n  async tryLoad(descriptor: ConnectorEngineDescriptor): Promise<ConnectorEngineFactory | null> {\n    try {\n      return await this.load(descriptor)\n    } catch {\n      return null\n    }\n  }\n\n  /** Whether the factory for an atom id is already cached. */\n  isLoaded(atomId: string): boolean {\n    return this.cache.has(atomId)\n  }\n\n  /** Last recorded failure reason for an atom id, or null. */\n  getFailure(atomId: string): string | null {\n    return this.failures.get(atomId) ?? null\n  }\n\n  /** Invalidate cache (and failure record) for one atom id or all. */\n  invalidate(atomId?: string): void {\n    if (atomId) {\n      this.cache.delete(atomId)\n      this.failures.delete(atomId)\n    } else {\n      this.cache.clear()\n      this.failures.clear()\n    }\n  }\n\n  private async doLoad(descriptor: ConnectorEngineDescriptor): Promise<ConnectorEngineFactory> {\n    const fetchAndEvaluate = async (): Promise<ConnectorEngineModule> => {\n      const res = await fetch(descriptor.bundleUrl, { credentials: 'omit' })\n      if (!res.ok) {\n        throw new Error(`Bundle fetch failed for ${descriptor.id}: ${res.status}`)\n      }\n      const bytes = await res.arrayBuffer()\n      // Same law as block bundles: integrity is verified BEFORE evaluation.\n      await verifyIntegrity(bytes, descriptor.integrity, descriptor.id)\n      return this.evaluate(bytes, descriptor)\n    }\n\n    const timeoutPromise = new Promise<never>((_, reject) =>\n      setTimeout(\n        () => reject(new Error(`Module load timed out after ${LOAD_TIMEOUT_MS / 1000}s`)),\n        LOAD_TIMEOUT_MS\n      )\n    )\n\n    const mod = await Promise.race([fetchAndEvaluate(), timeoutPromise])\n\n    const factory = mod.createConnector ?? mod.default\n    if (typeof factory !== 'function') {\n      throw new Error(\n        `Module at ${descriptor.bundleUrl} does not export a connector factory ` +\n          `(expected 'createConnector' or a default function export)`\n      )\n    }\n    return factory\n  }\n}\n\n/**\n * Create a loader with injectable evaluation (tests / non-browser hosts).\n */\nexport function createConnectorModuleLoader(options?: {\n  readonly evaluate?: ConnectorModuleEvaluator\n}): ConnectorModuleLoaderImpl {\n  return new ConnectorModuleLoaderImpl(options)\n}\n\n/**\n * Singleton instance — mirrors `BlockModuleLoader`.\n */\nexport const ConnectorModuleLoader = new ConnectorModuleLoaderImpl()\n"]}

package/dist/connectors/types.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Connector Engine Types
+ *
+ * Platform-side vocabulary for CONNECTOR/PROVIDER atom engines. Two
+ * consumption paths, ONE engine source:
+ *
+ * 1. dataSource path — a surface dataSource `{kind:'entity', entityType,
+ *    connector:'graph-lists'}` routes through a `ConnectorEngineRegistry`:
+ *    when a loaded engine is registered under that connection name the read
+ *    goes through it (constructed with the world connection's config);
+ *    absent engine/config keeps today's behavior (default facade or honest
+ *    empty + `__errors` context), never a crash.
+ * 2. engine-bridge path — pack blocks get their connections/config from the
+ *    runtime-provided connections context (`SurfaceConnectionsContext`).
+ *    On the platform the value comes from the project's connections doc +
+ *    world connector rows; in the runner the existing `connections.json`
+ *    path is unchanged. Single dialect — the source differs, the shape
+ *    doesn't (mirrors the runner's `PwappConnection`).
+ *
+ * @module @pwfabric/runtime/connectors/types
+ */
+import type { EntityAggregate, EntityTypeId, EntityQuery } from '../entity/types.js';
+import type { ConnectorAggregateResult, ConnectorQueryResult } from '../entity/connector.js';
+/**
+ * Atom kinds that ship a connector engine bundle. `connector` = dynamic
+ * data engine (e.g. graph-lists); `provider` = fixed-enum provider motor
+ * facet (e.g. the single Graph motor behind graph-mail/graph-users/…).
+ */
+export type ConnectorEngineKind = 'connector' | 'provider';
+/**
+ * Descriptor for a loadable connector-engine atom bundle. Mirrors
+ * `DynamicBlockDescriptor` with the AtomRef `bundleUrl`
+ * vocabulary: the publish pipeline uploads the ESM bundle and stamps its
+ * SHA-256 — integrity is verified BEFORE evaluation (security boundary,
+ * same law as block bundles).
+ */
+export interface ConnectorEngineDescriptor {
+    /** Atom id of the engine (e.g. 'graph-lists', 'microsoft-graph-motor'). */
+    readonly id: string;
+    readonly kind: ConnectorEngineKind;
+    /** CDN URL of the ESM bundle produced by the publish pipeline. */
+    readonly bundleUrl: string;
+    /** SHA-256 of the bundle bytes (bare hex or SRI `sha256-<base64>`). */
+    readonly integrity: string;
+    readonly version?: string;
+}
+/**
+ * Per-call access-token supplier handed to an engine at construction —
+ * exactly the signature the existing engines already take
+ * (GraphListConnector / createGraphConnector). Re-invoked on every request
+ * so token rotation is transparent. Resolving to `null` means
+ * unauthenticated — engines degrade honestly (anon/empty), they do not
+ * throw at construction time.
+ */
+export type ConnectorAccessTokenHook = () => Promise<string | null>;
+/**
+ * Factory a connector-engine bundle must export. The wrapper convention
+ * (mirror of the block bundle's `Component` + `definition`) is a stable
+ * `createConnector` named export; `default` is accepted as fallback.
+ */
+export type ConnectorEngineFactory = (getAccessToken: ConnectorAccessTokenHook, config: Readonly<Record<string, unknown>>) => unknown;
+/** Module shape of an evaluated connector-engine bundle. */
+export interface ConnectorEngineModule {
+    readonly createConnector?: ConnectorEngineFactory;
+    readonly default?: ConnectorEngineFactory;
+}
+/**
+ * Minimal read contract every constructed engine must satisfy — the surface
+ * dataSource path only lists records. Engines that additionally implement
+ * the full `EntityConnector` interface can be registered into an
+ * `EntityFacade` (`facade.connectors.register(engine)`) for the write path.
+ */
+export interface ConnectorEngine {
+    readonly name?: string;
+    query(entityType: EntityTypeId, query: EntityQuery): Promise<ConnectorQueryResult>;
+    /** Optional: an engine that can count server-side; absent = list and reduce. */
+    aggregate?(entityType: EntityTypeId, aggregate: EntityAggregate): Promise<ConnectorAggregateResult>;
+}
+/**
+ * One configured connection: a connector engine bound to this world with
+ * per-connection config. `connection` is the connection NAME the surface
+ * dialect references (`dataSources[].connector`); `descriptor` says which
+ * engine bundle serves it; `config` is the world connection's config
+ * (never credential values — auth law).
+ */
+export interface ConnectorConnectionBinding {
+    readonly connection: string;
+    readonly descriptor: ConnectorEngineDescriptor;
+    readonly config?: Readonly<Record<string, unknown>>;
+    /** Auth binding BY NAME — resolved by the token resolver. */
+    readonly authProviderRef?: string;
+}
+/**
+ * Injectable token resolver — the registry derives each engine's
+ * `ConnectorAccessTokenHook` from this. By default the
+ * resolver answers `null` (engines behave as unauthenticated); a host plugs
+ * the AuthRegistry in through `setAccessTokenResolver` without another
+ * core change.
+ */
+export type ConnectorAccessTokenResolver = (binding: ConnectorConnectionBinding) => Promise<string | null>;
+/** Lifecycle state of a connection's engine inside the registry. */
+export type ConnectorEngineStatus = {
+    readonly state: 'unregistered';
+} | {
+    readonly state: 'pending';
+} | {
+    readonly state: 'ready';
+} | {
+    readonly state: 'failed';
+    readonly reason: string;
+};
+/**
+ * Registry of connection name → constructed engine instance. Distinct from
+ * the entity system's `ConnectorRegistry`, which manages
+ * `EntityConnector` instances INSIDE one facade — this registry owns
+ * loading + constructing engines from atom bundles, world-wide.
+ */
+export interface ConnectorEngineRegistry {
+    /** Declare the world's connections (replaces the current set). */
+    configure(bindings: readonly ConnectorConnectionBinding[]): void;
+    /** Register an already-constructed engine directly (host/in-process). */
+    register(connection: string, engine: ConnectorEngine): void;
+    /**
+     * Resolve the engine for a connection name — loads the bundle and
+     * constructs the engine on first use, then answers from cache. NEVER
+     * throws: a failed load/construction marks the entry `failed` (with
+     * reason) and resolves `null` so consumers degrade honestly.
+     */
+    resolve(connection: string): Promise<ConnectorEngine | null>;
+    /** Current lifecycle state of a connection (sync, for honest UI/errors). */
+    getStatus(connection: string): ConnectorEngineStatus;
+    /** Swap the token resolver (the auth-registry seam). Existing constructed
+     * engines keep their hook — it closes over the resolver reference, so a
+     * swap takes effect on the next token request, not the next construction. */
+    setAccessTokenResolver(resolver: ConnectorAccessTokenResolver): void;
+    /** Configured/registered connection names. */
+    list(): readonly string[];
+    /** Drop all bindings, instances, and failure states. */
+    clear(): void;
+}
+/**
+ * One connection as blocks/the renderer see it. Shape-compatible with the
+ * runner's `PwappConnection` (`connections.json` entry) — single dialect,
+ * different source (platform: project connections doc + world connector
+ * rows; runner: connections.json).
+ */
+export interface SurfaceConnection {
+    readonly name: string;
+    /** Connector engine (atom) id serving this connection. */
+    readonly connector?: string;
+    readonly config?: Readonly<Record<string, unknown>>;
+    /** World row status when known (e.g. 'active' | 'pending'). */
+    readonly status?: string;
+    readonly authProviderRef?: string;
+}
+/**
+ * Value carried by `SurfaceConnectionsContext` and the renderer's
+ * `connections` prop. `engines` may be null when the host provides the
+ * connections doc for bridge blocks but no loaded engines (yet).
+ */
+export interface SurfaceConnectionsValue {
+    readonly connections: readonly SurfaceConnection[];
+    readonly engines: ConnectorEngineRegistry | null;
+    /**
+     * the same live token the engine registry is constructed
+     * with, reachable by the data path.
+     *
+     * The registry already closes over a resolver, but it keeps it private, so a
+     * `rest` data source sitting beside an engine-backed one had no route to the
+     * identity the app was already signed in with. Exposed here, both paths draw
+     * on one bridge instead of the REST half having none.
+     */
+    readonly getAccessToken?: ConnectorAccessTokenResolver;
+}

package/dist/connectors/types.js

@@ -0,0 +1,23 @@
+/**
+ * Connector Engine Types
+ *
+ * Platform-side vocabulary for CONNECTOR/PROVIDER atom engines. Two
+ * consumption paths, ONE engine source:
+ *
+ * 1. dataSource path — a surface dataSource `{kind:'entity', entityType,
+ *    connector:'graph-lists'}` routes through a `ConnectorEngineRegistry`:
+ *    when a loaded engine is registered under that connection name the read
+ *    goes through it (constructed with the world connection's config);
+ *    absent engine/config keeps today's behavior (default facade or honest
+ *    empty + `__errors` context), never a crash.
+ * 2. engine-bridge path — pack blocks get their connections/config from the
+ *    runtime-provided connections context (`SurfaceConnectionsContext`).
+ *    On the platform the value comes from the project's connections doc +
+ *    world connector rows; in the runner the existing `connections.json`
+ *    path is unchanged. Single dialect — the source differs, the shape
+ *    doesn't (mirrors the runner's `PwappConnection`).
+ *
+ * @module @pwfabric/runtime/connectors/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/connectors/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/connectors/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG","sourcesContent":["/**\n * Connector Engine Types\n *\n * Platform-side vocabulary for CONNECTOR/PROVIDER atom engines. Two\n * consumption paths, ONE engine source:\n *\n * 1. dataSource path — a surface dataSource `{kind:'entity', entityType,\n *    connector:'graph-lists'}` routes through a `ConnectorEngineRegistry`:\n *    when a loaded engine is registered under that connection name the read\n *    goes through it (constructed with the world connection's config);\n *    absent engine/config keeps today's behavior (default facade or honest\n *    empty + `__errors` context), never a crash.\n * 2. engine-bridge path — pack blocks get their connections/config from the\n *    runtime-provided connections context (`SurfaceConnectionsContext`).\n *    On the platform the value comes from the project's connections doc +\n *    world connector rows; in the runner the existing `connections.json`\n *    path is unchanged. Single dialect — the source differs, the shape\n *    doesn't (mirrors the runner's `PwappConnection`).\n *\n * @module @pwfabric/runtime/connectors/types\n */\n\nimport type { EntityAggregate, EntityTypeId, EntityQuery } from '../entity/types.js'\nimport type { ConnectorAggregateResult, ConnectorQueryResult } from '../entity/connector.js'\n\n// ============================================================\n// ENGINE DESCRIPTOR (what the loader consumes)\n// ============================================================\n\n/**\n * Atom kinds that ship a connector engine bundle. `connector` = dynamic\n * data engine (e.g. graph-lists); `provider` = fixed-enum provider motor\n * facet (e.g. the single Graph motor behind graph-mail/graph-users/…).\n */\nexport type ConnectorEngineKind = 'connector' | 'provider'\n\n/**\n * Descriptor for a loadable connector-engine atom bundle. Mirrors\n * `DynamicBlockDescriptor` with the AtomRef `bundleUrl`\n * vocabulary: the publish pipeline uploads the ESM bundle and stamps its\n * SHA-256 — integrity is verified BEFORE evaluation (security boundary,\n * same law as block bundles).\n */\nexport interface ConnectorEngineDescriptor {\n  /** Atom id of the engine (e.g. 'graph-lists', 'microsoft-graph-motor'). */\n  readonly id: string\n  readonly kind: ConnectorEngineKind\n  /** CDN URL of the ESM bundle produced by the publish pipeline. */\n  readonly bundleUrl: string\n  /** SHA-256 of the bundle bytes (bare hex or SRI `sha256-<base64>`). */\n  readonly integrity: string\n  readonly version?: string\n}\n\n// ============================================================\n// ENGINE MODULE CONVENTION (what a bundle exports)\n// ============================================================\n\n/**\n * Per-call access-token supplier handed to an engine at construction —\n * exactly the signature the existing engines already take\n * (GraphListConnector / createGraphConnector). Re-invoked on every request\n * so token rotation is transparent. Resolving to `null` means\n * unauthenticated — engines degrade honestly (anon/empty), they do not\n * throw at construction time.\n */\nexport type ConnectorAccessTokenHook = () => Promise<string | null>\n\n/**\n * Factory a connector-engine bundle must export. The wrapper convention\n * (mirror of the block bundle's `Component` + `definition`) is a stable\n * `createConnector` named export; `default` is accepted as fallback.\n */\nexport type ConnectorEngineFactory = (\n  getAccessToken: ConnectorAccessTokenHook,\n  config: Readonly<Record<string, unknown>>\n) => unknown\n\n/** Module shape of an evaluated connector-engine bundle. */\nexport interface ConnectorEngineModule {\n  readonly createConnector?: ConnectorEngineFactory\n  readonly default?: ConnectorEngineFactory\n}\n\n/**\n * Minimal read contract every constructed engine must satisfy — the surface\n * dataSource path only lists records. Engines that additionally implement\n * the full `EntityConnector` interface can be registered into an\n * `EntityFacade` (`facade.connectors.register(engine)`) for the write path.\n */\nexport interface ConnectorEngine {\n  readonly name?: string\n  query(entityType: EntityTypeId, query: EntityQuery): Promise<ConnectorQueryResult>\n  /** Optional: an engine that can count server-side; absent = list and reduce. */\n  aggregate?(entityType: EntityTypeId, aggregate: EntityAggregate): Promise<ConnectorAggregateResult>\n}\n\n// ============================================================\n// CONNECTION BINDING (registry configuration unit)\n// ============================================================\n\n/**\n * One configured connection: a connector engine bound to this world with\n * per-connection config. `connection` is the connection NAME the surface\n * dialect references (`dataSources[].connector`); `descriptor` says which\n * engine bundle serves it; `config` is the world connection's config\n * (never credential values — auth law).\n */\nexport interface ConnectorConnectionBinding {\n  readonly connection: string\n  readonly descriptor: ConnectorEngineDescriptor\n  readonly config?: Readonly<Record<string, unknown>>\n  /** Auth binding BY NAME — resolved by the token resolver. */\n  readonly authProviderRef?: string\n}\n\n/**\n * Injectable token resolver — the registry derives each engine's\n * `ConnectorAccessTokenHook` from this. By default the\n * resolver answers `null` (engines behave as unauthenticated); a host plugs\n * the AuthRegistry in through `setAccessTokenResolver` without another\n * core change.\n */\nexport type ConnectorAccessTokenResolver = (\n  binding: ConnectorConnectionBinding\n) => Promise<string | null>\n\n// ============================================================\n// REGISTRY (name → engine instance)\n// ============================================================\n\n/** Lifecycle state of a connection's engine inside the registry. */\nexport type ConnectorEngineStatus =\n  | { readonly state: 'unregistered' }\n  | { readonly state: 'pending' }\n  | { readonly state: 'ready' }\n  | { readonly state: 'failed'; readonly reason: string }\n\n/**\n * Registry of connection name → constructed engine instance. Distinct from\n * the entity system's `ConnectorRegistry`, which manages\n * `EntityConnector` instances INSIDE one facade — this registry owns\n * loading + constructing engines from atom bundles, world-wide.\n */\nexport interface ConnectorEngineRegistry {\n  /** Declare the world's connections (replaces the current set). */\n  configure(bindings: readonly ConnectorConnectionBinding[]): void\n\n  /** Register an already-constructed engine directly (host/in-process). */\n  register(connection: string, engine: ConnectorEngine): void\n\n  /**\n   * Resolve the engine for a connection name — loads the bundle and\n   * constructs the engine on first use, then answers from cache. NEVER\n   * throws: a failed load/construction marks the entry `failed` (with\n   * reason) and resolves `null` so consumers degrade honestly.\n   */\n  resolve(connection: string): Promise<ConnectorEngine | null>\n\n  /** Current lifecycle state of a connection (sync, for honest UI/errors). */\n  getStatus(connection: string): ConnectorEngineStatus\n\n  /** Swap the token resolver (the auth-registry seam). Existing constructed\n   * engines keep their hook — it closes over the resolver reference, so a\n   * swap takes effect on the next token request, not the next construction. */\n  setAccessTokenResolver(resolver: ConnectorAccessTokenResolver): void\n\n  /** Configured/registered connection names. */\n  list(): readonly string[]\n\n  /** Drop all bindings, instances, and failure states. */\n  clear(): void\n}\n\n// ============================================================\n// SURFACE CONNECTIONS CONTEXT VALUE (single dialect)\n// ============================================================\n\n/**\n * One connection as blocks/the renderer see it. Shape-compatible with the\n * runner's `PwappConnection` (`connections.json` entry) — single dialect,\n * different source (platform: project connections doc + world connector\n * rows; runner: connections.json).\n */\nexport interface SurfaceConnection {\n  readonly name: string\n  /** Connector engine (atom) id serving this connection. */\n  readonly connector?: string\n  readonly config?: Readonly<Record<string, unknown>>\n  /** World row status when known (e.g. 'active' | 'pending'). */\n  readonly status?: string\n  readonly authProviderRef?: string\n}\n\n/**\n * Value carried by `SurfaceConnectionsContext` and the renderer's\n * `connections` prop. `engines` may be null when the host provides the\n * connections doc for bridge blocks but no loaded engines (yet).\n */\nexport interface SurfaceConnectionsValue {\n  readonly connections: readonly SurfaceConnection[]\n  readonly engines: ConnectorEngineRegistry | null\n  /**\n   * the same live token the engine registry is constructed\n   * with, reachable by the data path.\n   *\n   * The registry already closes over a resolver, but it keeps it private, so a\n   * `rest` data source sitting beside an engine-backed one had no route to the\n   * identity the app was already signed in with. Exposed here, both paths draw\n   * on one bridge instead of the REST half having none.\n   */\n  readonly getAccessToken?: ConnectorAccessTokenResolver\n}\n"]}

package/dist/context.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Execution context for PWFabric runtime
+ */
+import { type Logger } from '@pwfabric/core';
+/**
+ * Runtime context interface
+ */
+export interface RuntimeContext {
+    readonly id: string;
+    readonly logger: Logger;
+    readonly startTime: Date;
+    readonly metadata: Map<string, unknown>;
+}
+/**
+ * Create a new runtime context
+ */
+export declare function createContext(name: string): RuntimeContext;
+/**
+ * Context builder for fluent API
+ */
+export declare class ContextBuilder {
+    private name;
+    private meta;
+    withName(name: string): this;
+    withMetadata(key: string, value: unknown): this;
+    build(): RuntimeContext;
+}

package/dist/context.js

@@ -0,0 +1,38 @@
+/**
+ * Execution context for PWFabric runtime
+ */
+import { createLogger } from '@pwfabric/core';
+/**
+ * Create a new runtime context
+ */
+export function createContext(name) {
+    return {
+        id: crypto.randomUUID(),
+        logger: createLogger(`runtime:${name}`),
+        startTime: new Date(),
+        metadata: new Map(),
+    };
+}
+/**
+ * Context builder for fluent API
+ */
+export class ContextBuilder {
+    name = 'default';
+    meta = new Map();
+    withName(name) {
+        this.name = name;
+        return this;
+    }
+    withMetadata(key, value) {
+        this.meta.set(key, value);
+        return this;
+    }
+    build() {
+        const ctx = createContext(this.name);
+        for (const [key, value] of this.meta) {
+            ctx.metadata.set(key, value);
+        }
+        return ctx;
+    }
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAe,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAY1D;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,OAAO;QACL,EAAE,EAAE,MAAM,CAAC,UAAU,EAAE;QACvB,MAAM,EAAE,YAAY,CAAC,WAAW,IAAI,EAAE,CAAC;QACvC,SAAS,EAAE,IAAI,IAAI,EAAE;QACrB,QAAQ,EAAE,IAAI,GAAG,EAAE;KACpB,CAAA;AACH,CAAC;AAED;;GAEG;AACH,MAAM,OAAO,cAAc;IACjB,IAAI,GAAG,SAAS,CAAA;IAChB,IAAI,GAAG,IAAI,GAAG,EAAmB,CAAA;IAEzC,QAAQ,CAAC,IAAY;QACnB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,YAAY,CAAC,GAAW,EAAE,KAAc;QACtC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;QACzB,OAAO,IAAI,CAAA;IACb,CAAC;IAED,KAAK;QACH,MAAM,GAAG,GAAG,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACpC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YACrC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;QAC9B,CAAC;QACD,OAAO,GAAG,CAAA;IACZ,CAAC;CACF","sourcesContent":["/**\n * Execution context for PWFabric runtime\n */\n\nimport { type Logger, createLogger } from '@pwfabric/core'\n\n/**\n * Runtime context interface\n */\nexport interface RuntimeContext {\n  readonly id: string\n  readonly logger: Logger\n  readonly startTime: Date\n  readonly metadata: Map<string, unknown>\n}\n\n/**\n * Create a new runtime context\n */\nexport function createContext(name: string): RuntimeContext {\n  return {\n    id: crypto.randomUUID(),\n    logger: createLogger(`runtime:${name}`),\n    startTime: new Date(),\n    metadata: new Map(),\n  }\n}\n\n/**\n * Context builder for fluent API\n */\nexport class ContextBuilder {\n  private name = 'default'\n  private meta = new Map<string, unknown>()\n\n  withName(name: string): this {\n    this.name = name\n    return this\n  }\n\n  withMetadata(key: string, value: unknown): this {\n    this.meta.set(key, value)\n    return this\n  }\n\n  build(): RuntimeContext {\n    const ctx = createContext(this.name)\n    for (const [key, value] of this.meta) {\n      ctx.metadata.set(key, value)\n    }\n    return ctx\n  }\n}\n"]}

package/dist/data/DataCapabilityProvider.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Data Capability Provider
+ *
+ * React context bridge between the capability registry and the render layer.
+ * Instantiates a DataService with config and exposes it via useDataService() hook.
+ *
+ * This is the canonical pattern for capability → React integration.
+ * Other capabilities (auth, routing, analytics, etc.) should follow the same structure.
+ *
+ * @module @pwfabric/runtime/data/DataCapabilityProvider
+ */
+import * as React from 'react';
+import type { DataServiceInterface, DataServiceConfig } from './types.js';
+export interface DataCapabilityProviderProps {
+    readonly config?: DataServiceConfig;
+    readonly service?: DataServiceInterface;
+    readonly children: React.ReactNode;
+}
+/**
+ * Provides a DataService instance to the component tree.
+ *
+ * Usage:
+ * - Pass `config` to let the provider create a DataService internally.
+ * - Pass `service` to inject an existing DataService (useful for testing or
+ *   when the capability registry has already instantiated one).
+ * - If both are provided, `service` takes precedence.
+ */
+export declare function DataCapabilityProvider({ config, service, children, }: DataCapabilityProviderProps): React.ReactElement;
+/**
+ * Access the DataService from the nearest DataCapabilityProvider.
+ *
+ * @throws Error if called outside of a DataCapabilityProvider.
+ */
+export declare function useDataService(): DataServiceInterface;
+/**
+ * Optionally access the DataService — returns null if no provider is present.
+ * Useful for components that work with or without data binding.
+ */
+export declare function useOptionalDataService(): DataServiceInterface | null;

package/dist/data/DataCapabilityProvider.js

@@ -0,0 +1,58 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Data Capability Provider
+ *
+ * React context bridge between the capability registry and the render layer.
+ * Instantiates a DataService with config and exposes it via useDataService() hook.
+ *
+ * This is the canonical pattern for capability → React integration.
+ * Other capabilities (auth, routing, analytics, etc.) should follow the same structure.
+ *
+ * @module @pwfabric/runtime/data/DataCapabilityProvider
+ */
+import * as React from 'react';
+import { DataService } from './manager.js';
+// ============================================================
+// CONTEXT
+// ============================================================
+const DataServiceContext = React.createContext(null);
+/**
+ * Provides a DataService instance to the component tree.
+ *
+ * Usage:
+ * - Pass `config` to let the provider create a DataService internally.
+ * - Pass `service` to inject an existing DataService (useful for testing or
+ *   when the capability registry has already instantiated one).
+ * - If both are provided, `service` takes precedence.
+ */
+export function DataCapabilityProvider({ config, service, children, }) {
+    const dataService = React.useMemo(() => {
+        if (service)
+            return service;
+        return new DataService(config);
+    }, [service, config]);
+    return _jsx(DataServiceContext.Provider, { value: dataService, children: children });
+}
+// ============================================================
+// HOOK
+// ============================================================
+/**
+ * Access the DataService from the nearest DataCapabilityProvider.
+ *
+ * @throws Error if called outside of a DataCapabilityProvider.
+ */
+export function useDataService() {
+    const service = React.useContext(DataServiceContext);
+    if (!service) {
+        throw new Error('useDataService must be used within a DataCapabilityProvider');
+    }
+    return service;
+}
+/**
+ * Optionally access the DataService — returns null if no provider is present.
+ * Useful for components that work with or without data binding.
+ */
+export function useOptionalDataService() {
+    return React.useContext(DataServiceContext);
+}
+//# sourceMappingURL=DataCapabilityProvider.js.map

package/dist/data/DataCapabilityProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DataCapabilityProvider.js","sourceRoot":"","sources":["../../src/data/DataCapabilityProvider.tsx"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAG1C,+DAA+D;AAC/D,UAAU;AACV,+DAA+D;AAE/D,MAAM,kBAAkB,GAAG,KAAK,CAAC,aAAa,CAA8B,IAAI,CAAC,CAAA;AAYjF;;;;;;;;GAQG;AACH,MAAM,UAAU,sBAAsB,CAAC,EACrC,MAAM,EACN,OAAO,EACP,QAAQ,GACoB;IAC5B,MAAM,WAAW,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,EAAE;QACrC,IAAI,OAAO;YAAE,OAAO,OAAO,CAAA;QAC3B,OAAO,IAAI,WAAW,CAAC,MAAM,CAAC,CAAA;IAChC,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAA;IAErB,OAAO,KAAC,kBAAkB,CAAC,QAAQ,IAAC,KAAK,EAAE,WAAW,YAAG,QAAQ,GAA+B,CAAA;AAClG,CAAC;AAED,+DAA+D;AAC/D,OAAO;AACP,+DAA+D;AAE/D;;;;GAIG;AACH,MAAM,UAAU,cAAc;IAC5B,MAAM,OAAO,GAAG,KAAK,CAAC,UAAU,CAAC,kBAAkB,CAAC,CAAA;IACpD,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,6DAA6D,CAAC,CAAA;IAChF,CAAC;IACD,OAAO,OAAO,CAAA;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB;IACpC,OAAO,KAAK,CAAC,UAAU,CAAC,kBAAkB,CAAC,CAAA;AAC7C,CAAC","sourcesContent":["/**\n * Data Capability Provider\n *\n * React context bridge between the capability registry and the render layer.\n * Instantiates a DataService with config and exposes it via useDataService() hook.\n *\n * This is the canonical pattern for capability → React integration.\n * Other capabilities (auth, routing, analytics, etc.) should follow the same structure.\n *\n * @module @pwfabric/runtime/data/DataCapabilityProvider\n */\n\nimport * as React from 'react'\nimport { DataService } from './manager.js'\nimport type { DataServiceInterface, DataServiceConfig } from './types.js'\n\n// ============================================================\n// CONTEXT\n// ============================================================\n\nconst DataServiceContext = React.createContext<DataServiceInterface | null>(null)\n\n// ============================================================\n// PROVIDER\n// ============================================================\n\nexport interface DataCapabilityProviderProps {\n  readonly config?: DataServiceConfig\n  readonly service?: DataServiceInterface\n  readonly children: React.ReactNode\n}\n\n/**\n * Provides a DataService instance to the component tree.\n *\n * Usage:\n * - Pass `config` to let the provider create a DataService internally.\n * - Pass `service` to inject an existing DataService (useful for testing or\n *   when the capability registry has already instantiated one).\n * - If both are provided, `service` takes precedence.\n */\nexport function DataCapabilityProvider({\n  config,\n  service,\n  children,\n}: DataCapabilityProviderProps): React.ReactElement {\n  const dataService = React.useMemo(() => {\n    if (service) return service\n    return new DataService(config)\n  }, [service, config])\n\n  return <DataServiceContext.Provider value={dataService}>{children}</DataServiceContext.Provider>\n}\n\n// ============================================================\n// HOOK\n// ============================================================\n\n/**\n * Access the DataService from the nearest DataCapabilityProvider.\n *\n * @throws Error if called outside of a DataCapabilityProvider.\n */\nexport function useDataService(): DataServiceInterface {\n  const service = React.useContext(DataServiceContext)\n  if (!service) {\n    throw new Error('useDataService must be used within a DataCapabilityProvider')\n  }\n  return service\n}\n\n/**\n * Optionally access the DataService — returns null if no provider is present.\n * Useful for components that work with or without data binding.\n */\nexport function useOptionalDataService(): DataServiceInterface | null {\n  return React.useContext(DataServiceContext)\n}\n"]}