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

package/dist/capability/platform-capabilities.js

@@ -0,0 +1,267 @@
+/**
+ * Platform Capability Definitions
+ *
+ * Canonical capability taxonomy.
+ * - persistence replaces data + state (merged)
+ * - interaction replaces behaviors (Tier 2)
+ * - entities is the canonical form write path
+ *
+ * platform/auth phantom capability removed — real auth
+ * enforcement lives in JWT middleware (requireAuthenticated()), not
+ * the capability system.
+ *
+ * platform/input retired — form submissions flow through
+ * platform/entities (entity_records), hard cutover, no fallback.
+ *
+ * Active capabilities: persistence, entities, navigation, interaction.
+ *
+ * @module @pwfabric/runtime/capability/platform-capabilities
+ */
+import { defineCapability, defineContract, defineConfigSchema, anySchema, } from '@pwfabric/core';
+import { createDataService } from '../data/manager.js';
+// ============================================================
+// PASSTHROUGH CONTRACT
+// ============================================================
+/**
+ * A passthrough contract for declaration-only capabilities.
+ * Accepts any input and produces any output with no validation.
+ * Used by: persistence, navigation, interaction, entities.
+ */
+const passthroughContract = defineContract()
+    .id('platform/passthrough')
+    .name('Platform Passthrough')
+    .description('Passthrough contract for platform capability declarations')
+    .state('stable')
+    .input(anySchema())
+    .output(anySchema())
+    .build();
+// ============================================================
+// CONFIG SCHEMAS
+// ============================================================
+/**
+ * persistenceConfigSchema merges former dataConfigSchema and stateConfigSchema.
+ * data fields: defaultCacheTtl, maxRetries, timeout
+ * state fields: persistenceEnabled, storageKey
+ */
+const persistenceConfigSchema = defineConfigSchema()
+    .field('defaultCacheTtl', (f) => f
+    .number()
+    .default(300)
+    .label('Default Cache TTL')
+    .description('Default cache time-to-live in seconds')
+    .min(0)
+    .max(86400))
+    .field('maxRetries', (f) => f
+    .number()
+    .default(3)
+    .label('Max Retries')
+    .description('Maximum number of retry attempts for failed requests')
+    .min(0)
+    .max(10))
+    .field('timeout', (f) => f
+    .number()
+    .default(5000)
+    .label('Request Timeout')
+    .description('Request timeout in milliseconds')
+    .min(1000)
+    .max(30000))
+    .field('persistenceEnabled', (f) => f
+    .boolean()
+    .default(true)
+    .label('Enable Persistence')
+    .description('Persist state to local storage'))
+    .field('storageKey', (f) => f
+    .string()
+    .default('pwfabric-state')
+    .label('Storage Key')
+    .description('Local storage key prefix for persisted state'))
+    .build();
+const navigationConfigSchema = defineConfigSchema()
+    .field('basePath', (f) => f.string().default('/').label('Base Path').description('Base path prefix for all routes'))
+    .field('trailingSlash', (f) => f.boolean().default(false).label('Trailing Slash').description('Append trailing slash to URLs'))
+    .build();
+const interactionConfigSchema = defineConfigSchema()
+    .field('executionMode', (f) => f
+    .select([
+    {
+        value: 'sync',
+        label: 'Synchronous',
+        description: 'Actions block the event chain until complete',
+    },
+    {
+        value: 'async',
+        label: 'Asynchronous',
+        description: 'Actions run in background without blocking',
+    },
+])
+    .default('async')
+    .label('Execution Mode')
+    .description('How behavior actions are executed when a trigger fires'))
+    .field('maxConcurrent', (f) => f
+    .number()
+    .default(5)
+    .label('Max Concurrent')
+    .description('Maximum number of behaviors that can execute simultaneously')
+    .min(1)
+    .max(20))
+    .field('errorPolicy', (f) => f
+    .select([
+    { value: 'ignore', label: 'Ignore', description: 'Silently swallow errors' },
+    {
+        value: 'log',
+        label: 'Log',
+        description: 'Log errors to console without stopping execution',
+    },
+    { value: 'halt', label: 'Halt', description: 'Stop the behavior chain on first error' },
+])
+    .default('log')
+    .label('Error Policy')
+    .description('How errors in behavior actions are handled'))
+    .field('debugMode', (f) => f
+    .boolean()
+    .default(false)
+    .label('Debug Mode')
+    .description('Emit detailed trace events for behavior execution'))
+    .build();
+// ============================================================
+// PLATFORM CAPABILITY DEFINITIONS
+// ============================================================
+/**
+ * Persistence capability
+ *
+ * Merges former data + state capabilities.
+ * Provides data fetching, mutation, persistence operations, and
+ * client-side state management with optional local storage persistence.
+ */
+export const persistenceCapability = defineCapability()
+    .id('platform/persistence')
+    .name('Data & State Persistence')
+    .description('Data fetching, mutation, persistence operations, and client-side state management')
+    .version('1.0.0')
+    .state('stable')
+    .tags(['data', 'state', 'persistence', 'api'])
+    .contract(passthroughContract)
+    .configSchema(persistenceConfigSchema)
+    .execute(async (config) => {
+    const cfg = config;
+    return createDataService({
+        ...(cfg?.defaultCacheTtl != null ? { defaultCacheTtl: cfg.defaultCacheTtl } : {}),
+        ...(cfg?.maxRetries != null ? { maxRetries: cfg.maxRetries } : {}),
+        ...(cfg?.timeout != null ? { timeout: cfg.timeout } : {}),
+    });
+})
+    .build();
+/**
+ * Navigation capability
+ *
+ * Provides multi-page surface navigation, base path configuration, and route handling.
+ * Renamed from routingCapability (platform/routing) to avoid confusion with framework-level routing.
+ */
+export const navigationCapability = defineCapability()
+    .id('platform/navigation')
+    .name('Navigation')
+    .description('Multi-page surface navigation, base path configuration, and route handling')
+    .version('1.0.0')
+    .state('stable')
+    .tags(['navigation', 'routing', 'url'])
+    .contract(passthroughContract)
+    .configSchema(navigationConfigSchema)
+    .execute(async (input) => {
+    const data = input;
+    const path = data?.path ?? '/';
+    const config = data?.config ?? {};
+    const basePath = config.basePath ?? '/';
+    const trailingSlash = config.trailingSlash ?? false;
+    let resolvedPath = path.startsWith(basePath) ? path : `${basePath}${path}`.replace(/\/+/g, '/');
+    if (trailingSlash && !resolvedPath.endsWith('/'))
+        resolvedPath += '/';
+    else if (!trailingSlash && resolvedPath.length > 1 && resolvedPath.endsWith('/'))
+        resolvedPath = resolvedPath.slice(0, -1);
+    return { resolvedPath, params: {} };
+})
+    .build();
+/**
+ * Interaction capability
+ *
+ * Replaces former behaviors capability.
+ * Provides event-driven interaction rules for dynamic surfaces.
+ */
+export const interactionCapability = defineCapability()
+    .id('platform/interaction')
+    .name('Interaction Rules')
+    .description('Event-driven interaction rules — attach triggers and actions to surface events for interactive, dynamic surfaces')
+    .version('1.0.0')
+    .state('stable')
+    .tags(['interaction', 'events', 'automation'])
+    .contract(passthroughContract)
+    .configSchema(interactionConfigSchema)
+    .execute(async () => ({ success: true }))
+    .build();
+/**
+ * Entities capability — NEW Tier 1 capability.
+ *
+ * Schema-driven entity definitions, CRUD store, and connector abstraction.
+ */
+export const entitiesCapability = defineCapability()
+    .id('platform/entities')
+    .name('Entity System')
+    .description('Schema-driven entity definitions, CRUD store, connector abstraction')
+    .version('1.0.0')
+    .state('stable')
+    .tags(['entities', 'schema', 'crud'])
+    .contract(passthroughContract)
+    .configSchema(defineConfigSchema()
+    .field('enableLifecycleHooks', (f) => f
+    .boolean()
+    .default(true)
+    .label('Enable Lifecycle Hooks')
+    .description('Enable entity lifecycle hook callbacks'))
+    .field('enableEventBridge', (f) => f
+    .boolean()
+    .default(false)
+    .label('Enable Event Bridge')
+    .description('Emit entity events to the platform event bridge'))
+    .build())
+    .execute(async () => ({ success: true }))
+    .build();
+// ============================================================
+// AGGREGATE EXPORTS
+// ============================================================
+/**
+ * All platform capabilities as an array.
+ *
+ * SOURCE OF TRUTH — derive all other lists from this array (see index.ts).
+ * platform/auth removed (phantom capability).
+ * routing renamed to navigation.
+ * platform/input removed — form writes flow through platform/entities.
+ */
+export const platformCapabilities = [
+    persistenceCapability,
+    entitiesCapability,
+    navigationCapability,
+    interactionCapability,
+];
+/**
+ * Register all platform capabilities with a registry
+ *
+ * @param registry - The capability registry to register with
+ * @returns An object with successfully registered IDs and any errors
+ */
+export function registerPlatformCapabilities(registry) {
+    const registered = [];
+    const errors = [];
+    for (const capability of platformCapabilities) {
+        const result = registry.register(capability);
+        if (result.success) {
+            registered.push(capability.id);
+        }
+        else {
+            errors.push({
+                id: capability.id,
+                error: result.error.type,
+            });
+        }
+    }
+    return { registered, errors };
+}
+//# sourceMappingURL=platform-capabilities.js.map

package/dist/capability/platform-capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-capabilities.js","sourceRoot":"","sources":["../../src/capability/platform-capabilities.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Platform Capability Definitions\n *\n * Canonical capability taxonomy.\n * - persistence replaces data + state (merged)\n * - interaction replaces behaviors (Tier 2)\n * - entities is the canonical form write path\n *\n * platform/auth phantom capability removed — real auth\n * enforcement lives in JWT middleware (requireAuthenticated()), not\n * the capability system.\n *\n * platform/input retired — form submissions flow through\n * platform/entities (entity_records), hard cutover, no fallback.\n *\n * Active capabilities: persistence, entities, navigation, interaction.\n *\n * @module @pwfabric/runtime/capability/platform-capabilities\n */\n\nimport {\n  defineCapability,\n  defineContract,\n  defineConfigSchema,\n  anySchema,\n} from '@pwfabric/core'\nimport type { Capability } from '@pwfabric/contracts'\nimport type { CapabilityRegistry } from '../registry.js'\nimport { createDataService } from '../data/manager.js'\n\n// ============================================================\n// PASSTHROUGH CONTRACT\n// ============================================================\n\n/**\n * A passthrough contract for declaration-only capabilities.\n * Accepts any input and produces any output with no validation.\n * Used by: persistence, navigation, interaction, entities.\n */\nconst passthroughContract = defineContract()\n  .id('platform/passthrough')\n  .name('Platform Passthrough')\n  .description('Passthrough contract for platform capability declarations')\n  .state('stable')\n  .input(anySchema())\n  .output(anySchema())\n  .build()\n\n// ============================================================\n// CONFIG SCHEMAS\n// ============================================================\n\n/**\n * persistenceConfigSchema merges former dataConfigSchema and stateConfigSchema.\n * data fields: defaultCacheTtl, maxRetries, timeout\n * state fields: persistenceEnabled, storageKey\n */\nconst persistenceConfigSchema = defineConfigSchema()\n  .field('defaultCacheTtl', (f) =>\n    f\n      .number()\n      .default(300)\n      .label('Default Cache TTL')\n      .description('Default cache time-to-live in seconds')\n      .min(0)\n      .max(86400)\n  )\n  .field('maxRetries', (f) =>\n    f\n      .number()\n      .default(3)\n      .label('Max Retries')\n      .description('Maximum number of retry attempts for failed requests')\n      .min(0)\n      .max(10)\n  )\n  .field('timeout', (f) =>\n    f\n      .number()\n      .default(5000)\n      .label('Request Timeout')\n      .description('Request timeout in milliseconds')\n      .min(1000)\n      .max(30000)\n  )\n  .field('persistenceEnabled', (f) =>\n    f\n      .boolean()\n      .default(true)\n      .label('Enable Persistence')\n      .description('Persist state to local storage')\n  )\n  .field('storageKey', (f) =>\n    f\n      .string()\n      .default('pwfabric-state')\n      .label('Storage Key')\n      .description('Local storage key prefix for persisted state')\n  )\n  .build()\n\nconst navigationConfigSchema = defineConfigSchema()\n  .field('basePath', (f) =>\n    f.string().default('/').label('Base Path').description('Base path prefix for all routes')\n  )\n  .field('trailingSlash', (f) =>\n    f.boolean().default(false).label('Trailing Slash').description('Append trailing slash to URLs')\n  )\n  .build()\n\nconst interactionConfigSchema = defineConfigSchema()\n  .field('executionMode', (f) =>\n    f\n      .select([\n        {\n          value: 'sync',\n          label: 'Synchronous',\n          description: 'Actions block the event chain until complete',\n        },\n        {\n          value: 'async',\n          label: 'Asynchronous',\n          description: 'Actions run in background without blocking',\n        },\n      ])\n      .default('async')\n      .label('Execution Mode')\n      .description('How behavior actions are executed when a trigger fires')\n  )\n  .field('maxConcurrent', (f) =>\n    f\n      .number()\n      .default(5)\n      .label('Max Concurrent')\n      .description('Maximum number of behaviors that can execute simultaneously')\n      .min(1)\n      .max(20)\n  )\n  .field('errorPolicy', (f) =>\n    f\n      .select([\n        { value: 'ignore', label: 'Ignore', description: 'Silently swallow errors' },\n        {\n          value: 'log',\n          label: 'Log',\n          description: 'Log errors to console without stopping execution',\n        },\n        { value: 'halt', label: 'Halt', description: 'Stop the behavior chain on first error' },\n      ])\n      .default('log')\n      .label('Error Policy')\n      .description('How errors in behavior actions are handled')\n  )\n  .field('debugMode', (f) =>\n    f\n      .boolean()\n      .default(false)\n      .label('Debug Mode')\n      .description('Emit detailed trace events for behavior execution')\n  )\n  .build()\n\n// ============================================================\n// PLATFORM CAPABILITY DEFINITIONS\n// ============================================================\n\n/**\n * Persistence capability\n *\n * Merges former data + state capabilities.\n * Provides data fetching, mutation, persistence operations, and\n * client-side state management with optional local storage persistence.\n */\nexport const persistenceCapability = defineCapability()\n  .id('platform/persistence')\n  .name('Data & State Persistence')\n  .description('Data fetching, mutation, persistence operations, and client-side state management')\n  .version('1.0.0')\n  .state('stable')\n  .tags(['data', 'state', 'persistence', 'api'])\n  .contract(passthroughContract)\n  .configSchema(persistenceConfigSchema)\n  .execute(async (config) => {\n    const cfg = config as Record<string, unknown> | undefined\n    return createDataService({\n      ...(cfg?.defaultCacheTtl != null ? { defaultCacheTtl: cfg.defaultCacheTtl as number } : {}),\n      ...(cfg?.maxRetries != null ? { maxRetries: cfg.maxRetries as number } : {}),\n      ...(cfg?.timeout != null ? { timeout: cfg.timeout as number } : {}),\n    })\n  })\n  .build()\n\n/**\n * Navigation capability\n *\n * Provides multi-page surface navigation, base path configuration, and route handling.\n * Renamed from routingCapability (platform/routing) to avoid confusion with framework-level routing.\n */\nexport const navigationCapability = defineCapability()\n  .id('platform/navigation')\n  .name('Navigation')\n  .description('Multi-page surface navigation, base path configuration, and route handling')\n  .version('1.0.0')\n  .state('stable')\n  .tags(['navigation', 'routing', 'url'])\n  .contract(passthroughContract)\n  .configSchema(navigationConfigSchema)\n  .execute(async (input) => {\n    const data = input as Record<string, unknown> | undefined\n    const path = (data?.path as string) ?? '/'\n    const config = (data?.config as Record<string, unknown>) ?? {}\n    const basePath = (config.basePath as string) ?? '/'\n    const trailingSlash = (config.trailingSlash as boolean) ?? false\n    let resolvedPath = path.startsWith(basePath) ? path : `${basePath}${path}`.replace(/\\/+/g, '/')\n    if (trailingSlash && !resolvedPath.endsWith('/')) resolvedPath += '/'\n    else if (!trailingSlash && resolvedPath.length > 1 && resolvedPath.endsWith('/'))\n      resolvedPath = resolvedPath.slice(0, -1)\n    return { resolvedPath, params: {} }\n  })\n  .build()\n\n/**\n * Interaction capability\n *\n * Replaces former behaviors capability.\n * Provides event-driven interaction rules for dynamic surfaces.\n */\nexport const interactionCapability = defineCapability()\n  .id('platform/interaction')\n  .name('Interaction Rules')\n  .description(\n    'Event-driven interaction rules — attach triggers and actions to surface events for interactive, dynamic surfaces'\n  )\n  .version('1.0.0')\n  .state('stable')\n  .tags(['interaction', 'events', 'automation'])\n  .contract(passthroughContract)\n  .configSchema(interactionConfigSchema)\n  .execute(async () => ({ success: true }))\n  .build()\n\n/**\n * Entities capability — NEW Tier 1 capability.\n *\n * Schema-driven entity definitions, CRUD store, and connector abstraction.\n */\nexport const entitiesCapability = defineCapability()\n  .id('platform/entities')\n  .name('Entity System')\n  .description('Schema-driven entity definitions, CRUD store, connector abstraction')\n  .version('1.0.0')\n  .state('stable')\n  .tags(['entities', 'schema', 'crud'])\n  .contract(passthroughContract)\n  .configSchema(\n    defineConfigSchema()\n      .field('enableLifecycleHooks', (f) =>\n        f\n          .boolean()\n          .default(true)\n          .label('Enable Lifecycle Hooks')\n          .description('Enable entity lifecycle hook callbacks')\n      )\n      .field('enableEventBridge', (f) =>\n        f\n          .boolean()\n          .default(false)\n          .label('Enable Event Bridge')\n          .description('Emit entity events to the platform event bridge')\n      )\n      .build()\n  )\n  .execute(async () => ({ success: true }))\n  .build()\n\n// ============================================================\n// AGGREGATE EXPORTS\n// ============================================================\n\n/**\n * All platform capabilities as an array.\n *\n * SOURCE OF TRUTH — derive all other lists from this array (see index.ts).\n * platform/auth removed (phantom capability).\n * routing renamed to navigation.\n * platform/input removed — form writes flow through platform/entities.\n */\nexport const platformCapabilities: readonly Capability[] = [\n  persistenceCapability,\n  entitiesCapability,\n  navigationCapability,\n  interactionCapability,\n] as const\n\n/**\n * Register all platform capabilities with a registry\n *\n * @param registry - The capability registry to register with\n * @returns An object with successfully registered IDs and any errors\n */\nexport function registerPlatformCapabilities(registry: CapabilityRegistry): {\n  registered: readonly string[]\n  errors: readonly { id: string; error: string }[]\n} {\n  const registered: string[] = []\n  const errors: { id: string; error: string }[] = []\n\n  for (const capability of platformCapabilities) {\n    const result = registry.register(capability)\n    if (result.success) {\n      registered.push(capability.id)\n    } else {\n      errors.push({\n        id: capability.id,\n        error: result.error.type,\n      })\n    }\n  }\n\n  return { registered, errors }\n}\n"]}

package/dist/capability/type-mapping.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Capability Type Mapping
+ *
+ * Maps short-form CapabilityType strings to their corresponding platform
+ * capability IDs used in the registry.
+ *
+ * @module @pwfabric/runtime/capability/type-mapping
+ */
+import type { CapabilityId } from '@pwfabric/contracts';
+/**
+ * Maps short-form CapabilityType strings to registry CapabilityId values.
+ *
+ * Keys are the short-form types (e.g., 'persistence').
+ * Values are the full platform capability IDs (e.g., 'platform/persistence').
+ */
+export declare const CAPABILITY_TYPE_TO_ID: Record<string, string>;
+/**
+ * All known capability type keys
+ */
+export declare const CAPABILITY_TYPES: readonly string[];
+/**
+ * All known capability IDs
+ */
+export declare const CAPABILITY_IDS: readonly string[];
+/**
+ * Resolve a CapabilityType string to a CapabilityId.
+ *
+ * @param type - The capability type string (e.g., 'auth')
+ * @returns The corresponding CapabilityId, or null if not found
+ */
+export declare function resolveCapabilityId(type: string): CapabilityId | null;
+/**
+ * Resolve a CapabilityId back to a CapabilityType string.
+ *
+ * @param id - The capability ID (e.g., 'platform/persistence')
+ * @returns The corresponding type string, or null if not found
+ */
+export declare function resolveCapabilityType(id: string): string | null;
+/**
+ * Check if a CapabilityType string is known.
+ *
+ * @param type - The capability type string to check
+ * @returns true if the type is a known platform capability type
+ */
+export declare function isKnownCapabilityType(type: string): boolean;
+/**
+ * The canonical id, from EITHER spelling.
+ *
+ * Every reader that compares a capability id should go through this: a raw
+ * comparison against `'platform/…'` misses anything written the short way.
+ *
+ * Both spellings occur in real documents (`navigation`, `persistence`,
+ * `entities` next to `platform/navigation` …). Both are legitimate — the plan
+ * layer's contract types the short one, the registry and the pack's atoms use
+ * the long one — so a reader that accepts only one is blind to real data.
+ *
+ * `null` for anything outside the canonical four, which is the answer a caller
+ * needs for a retired name (`auth`, `input`) or one that never existed (`seo`):
+ * not a silent pass-through that would let a ghost look like a capability.
+ */
+export declare function canonicalCapabilityId(value: string): CapabilityId | null;
+/**
+ * Does this capability entry name the given canonical capability?
+ *
+ * The shape every one of those fourteen sites was hand-rolling:
+ * `caps.find((c) => c.capability === 'platform/persistence')`.
+ */
+export declare function isCapability(entry: {
+    capability?: string;
+} | null | undefined, id: string): boolean;

package/dist/capability/type-mapping.js

@@ -0,0 +1,107 @@
+/**
+ * Capability Type Mapping
+ *
+ * Maps short-form CapabilityType strings to their corresponding platform
+ * capability IDs used in the registry.
+ *
+ * @module @pwfabric/runtime/capability/type-mapping
+ */
+import { capabilityId } from '@pwfabric/contracts';
+// ============================================================
+// TYPE-TO-ID MAPPING
+// ============================================================
+/**
+ * Maps short-form CapabilityType strings to registry CapabilityId values.
+ *
+ * Keys are the short-form types (e.g., 'persistence').
+ * Values are the full platform capability IDs (e.g., 'platform/persistence').
+ */
+export const CAPABILITY_TYPE_TO_ID = {
+    persistence: 'platform/persistence',
+    entities: 'platform/entities',
+    navigation: 'platform/navigation',
+    interaction: 'platform/interaction',
+};
+/**
+ * All known capability type keys
+ */
+export const CAPABILITY_TYPES = Object.keys(CAPABILITY_TYPE_TO_ID);
+/**
+ * All known capability IDs
+ */
+export const CAPABILITY_IDS = Object.values(CAPABILITY_TYPE_TO_ID);
+// ============================================================
+// LOOKUP FUNCTIONS
+// ============================================================
+/**
+ * Resolve a CapabilityType string to a CapabilityId.
+ *
+ * @param type - The capability type string (e.g., 'auth')
+ * @returns The corresponding CapabilityId, or null if not found
+ */
+export function resolveCapabilityId(type) {
+    const id = CAPABILITY_TYPE_TO_ID[type];
+    if (!id)
+        return null;
+    return capabilityId(id);
+}
+/**
+ * Resolve a CapabilityId back to a CapabilityType string.
+ *
+ * @param id - The capability ID (e.g., 'platform/persistence')
+ * @returns The corresponding type string, or null if not found
+ */
+export function resolveCapabilityType(id) {
+    for (const [type, capId] of Object.entries(CAPABILITY_TYPE_TO_ID)) {
+        if (capId === id)
+            return type;
+    }
+    return null;
+}
+/**
+ * Check if a CapabilityType string is known.
+ *
+ * @param type - The capability type string to check
+ * @returns true if the type is a known platform capability type
+ */
+export function isKnownCapabilityType(type) {
+    return type in CAPABILITY_TYPE_TO_ID;
+}
+/**
+ * The canonical id, from EITHER spelling.
+ *
+ * Every reader that compares a capability id should go through this: a raw
+ * comparison against `'platform/…'` misses anything written the short way.
+ *
+ * Both spellings occur in real documents (`navigation`, `persistence`,
+ * `entities` next to `platform/navigation` …). Both are legitimate — the plan
+ * layer's contract types the short one, the registry and the pack's atoms use
+ * the long one — so a reader that accepts only one is blind to real data.
+ *
+ * `null` for anything outside the canonical four, which is the answer a caller
+ * needs for a retired name (`auth`, `input`) or one that never existed (`seo`):
+ * not a silent pass-through that would let a ghost look like a capability.
+ */
+export function canonicalCapabilityId(value) {
+    const trimmed = value.trim();
+    if (trimmed === '')
+        return null;
+    const mapped = CAPABILITY_TYPE_TO_ID[trimmed];
+    if (mapped)
+        return capabilityId(mapped);
+    return CAPABILITY_IDS.includes(trimmed) ? capabilityId(trimmed) : null;
+}
+/**
+ * Does this capability entry name the given canonical capability?
+ *
+ * The shape every one of those fourteen sites was hand-rolling:
+ * `caps.find((c) => c.capability === 'platform/persistence')`.
+ */
+export function isCapability(entry, id) {
+    const declared = entry?.capability;
+    if (typeof declared !== 'string')
+        return false;
+    const canonical = canonicalCapabilityId(id);
+    return canonical !== null && canonicalCapabilityId(declared) === canonical;
+}
+//# sourceMappingURL=type-mapping.js.map

package/dist/capability/type-mapping.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-mapping.js","sourceRoot":"","sources":["../../src/capability/type-mapping.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAGlD,+DAA+D;AAC/D,qBAAqB;AACrB,+DAA+D;AAE/D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAA2B;IAC3D,WAAW,EAAE,sBAAsB;IACnC,QAAQ,EAAE,mBAAmB;IAC7B,UAAU,EAAE,qBAAqB;IACjC,WAAW,EAAE,sBAAsB;CAC3B,CAAA;AAEV;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAC,IAAI,CAAC,qBAAqB,CAAsB,CAAA;AAEvF;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,CAAC,qBAAqB,CAAsB,CAAA;AAEvF,+DAA+D;AAC/D,mBAAmB;AACnB,+DAA+D;AAE/D;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,MAAM,EAAE,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAA;IACtC,IAAI,CAAC,EAAE;QAAE,OAAO,IAAI,CAAA;IACpB,OAAO,YAAY,CAAC,EAAE,CAAC,CAAA;AACzB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,EAAU;IAC9C,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,qBAAqB,CAAC,EAAE,CAAC;QAClE,IAAI,KAAK,KAAK,EAAE;YAAE,OAAO,IAAI,CAAA;IAC/B,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAY;IAChD,OAAO,IAAI,IAAI,qBAAqB,CAAA;AACtC,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAa;IACjD,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAA;IAC5B,IAAI,OAAO,KAAK,EAAE;QAAE,OAAO,IAAI,CAAA;IAC/B,MAAM,MAAM,GAAG,qBAAqB,CAAC,OAAO,CAAC,CAAA;IAC7C,IAAI,MAAM;QAAE,OAAO,YAAY,CAAC,MAAM,CAAC,CAAA;IACvC,OAAO,cAAc,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;AACxE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,KAAiD,EAAE,EAAU;IACxF,MAAM,QAAQ,GAAG,KAAK,EAAE,UAAU,CAAA;IAClC,IAAI,OAAO,QAAQ,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAA;IAC9C,MAAM,SAAS,GAAG,qBAAqB,CAAC,EAAE,CAAC,CAAA;IAC3C,OAAO,SAAS,KAAK,IAAI,IAAI,qBAAqB,CAAC,QAAQ,CAAC,KAAK,SAAS,CAAA;AAC5E,CAAC","sourcesContent":["/**\n * Capability Type Mapping\n *\n * Maps short-form CapabilityType strings to their corresponding platform\n * capability IDs used in the registry.\n *\n * @module @pwfabric/runtime/capability/type-mapping\n */\n\nimport { capabilityId } from '@pwfabric/contracts'\nimport type { CapabilityId } from '@pwfabric/contracts'\n\n// ============================================================\n// TYPE-TO-ID MAPPING\n// ============================================================\n\n/**\n * Maps short-form CapabilityType strings to registry CapabilityId values.\n *\n * Keys are the short-form types (e.g., 'persistence').\n * Values are the full platform capability IDs (e.g., 'platform/persistence').\n */\nexport const CAPABILITY_TYPE_TO_ID: Record<string, string> = {\n  persistence: 'platform/persistence',\n  entities: 'platform/entities',\n  navigation: 'platform/navigation',\n  interaction: 'platform/interaction',\n} as const\n\n/**\n * All known capability type keys\n */\nexport const CAPABILITY_TYPES = Object.keys(CAPABILITY_TYPE_TO_ID) as readonly string[]\n\n/**\n * All known capability IDs\n */\nexport const CAPABILITY_IDS = Object.values(CAPABILITY_TYPE_TO_ID) as readonly string[]\n\n// ============================================================\n// LOOKUP FUNCTIONS\n// ============================================================\n\n/**\n * Resolve a CapabilityType string to a CapabilityId.\n *\n * @param type - The capability type string (e.g., 'auth')\n * @returns The corresponding CapabilityId, or null if not found\n */\nexport function resolveCapabilityId(type: string): CapabilityId | null {\n  const id = CAPABILITY_TYPE_TO_ID[type]\n  if (!id) return null\n  return capabilityId(id)\n}\n\n/**\n * Resolve a CapabilityId back to a CapabilityType string.\n *\n * @param id - The capability ID (e.g., 'platform/persistence')\n * @returns The corresponding type string, or null if not found\n */\nexport function resolveCapabilityType(id: string): string | null {\n  for (const [type, capId] of Object.entries(CAPABILITY_TYPE_TO_ID)) {\n    if (capId === id) return type\n  }\n  return null\n}\n\n/**\n * Check if a CapabilityType string is known.\n *\n * @param type - The capability type string to check\n * @returns true if the type is a known platform capability type\n */\nexport function isKnownCapabilityType(type: string): boolean {\n  return type in CAPABILITY_TYPE_TO_ID\n}\n\n/**\n * The canonical id, from EITHER spelling.\n *\n * Every reader that compares a capability id should go through this: a raw\n * comparison against `'platform/…'` misses anything written the short way.\n *\n * Both spellings occur in real documents (`navigation`, `persistence`,\n * `entities` next to `platform/navigation` …). Both are legitimate — the plan\n * layer's contract types the short one, the registry and the pack's atoms use\n * the long one — so a reader that accepts only one is blind to real data.\n *\n * `null` for anything outside the canonical four, which is the answer a caller\n * needs for a retired name (`auth`, `input`) or one that never existed (`seo`):\n * not a silent pass-through that would let a ghost look like a capability.\n */\nexport function canonicalCapabilityId(value: string): CapabilityId | null {\n  const trimmed = value.trim()\n  if (trimmed === '') return null\n  const mapped = CAPABILITY_TYPE_TO_ID[trimmed]\n  if (mapped) return capabilityId(mapped)\n  return CAPABILITY_IDS.includes(trimmed) ? capabilityId(trimmed) : null\n}\n\n/**\n * Does this capability entry name the given canonical capability?\n *\n * The shape every one of those fourteen sites was hand-rolling:\n * `caps.find((c) => c.capability === 'platform/persistence')`.\n */\nexport function isCapability(entry: { capability?: string } | null | undefined, id: string): boolean {\n  const declared = entry?.capability\n  if (typeof declared !== 'string') return false\n  const canonical = canonicalCapabilityId(id)\n  return canonical !== null && canonicalCapabilityId(declared) === canonical\n}\n"]}

package/dist/capability/validation.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Surface Capability Validation
+ *
+ * Validates that a surface's capability requirements
+ * can be satisfied by the capabilities registered in a registry.
+ *
+ * @module @pwfabric/runtime/capability/validation
+ */
+import type { CapabilityRegistry } from '../registry.js';
+/**
+ * A capability requirement declared by a surface.
+ */
+export interface CapabilityRequirement {
+    /** The capability type string (e.g., 'persistence' or 'platform/persistence') */
+    readonly capability: string;
+    /** Whether this capability is required (true) or optional (false) */
+    readonly required: boolean;
+    /** Optional configuration for the capability */
+    readonly config?: Record<string, unknown>;
+}
+/**
+ * Result of validating surface capabilities against a registry.
+ */
+export interface CapabilityValidationResult {
+    /** Whether all required capabilities are satisfied */
+    readonly valid: boolean;
+    /** IDs of capabilities that are registered and satisfy requirements */
+    readonly satisfied: readonly string[];
+    /** IDs of required capabilities that are NOT registered */
+    readonly missing: readonly string[];
+    /** IDs of optional capabilities that are NOT registered */
+    readonly optional: readonly string[];
+}
+/**
+ * Validate that a surface's capability requirements can be met
+ * by the capabilities available in the registry.
+ *
+ * Capability strings can be either:
+ * - Short-form types from starters (e.g., 'persistence') which are resolved via type-mapping
+ * - Full capability IDs (e.g., 'platform/persistence') used directly
+ *
+ * @param requirements - The capability requirements declared by a surface
+ * @param registry - The capability registry to validate against
+ * @returns A ValidationResult indicating which requirements are met
+ */
+export declare function validateSurfaceCapabilities(requirements: readonly CapabilityRequirement[], registry: CapabilityRegistry): CapabilityValidationResult;

package/dist/capability/validation.js

@@ -0,0 +1,54 @@
+/**
+ * Surface Capability Validation
+ *
+ * Validates that a surface's capability requirements
+ * can be satisfied by the capabilities registered in a registry.
+ *
+ * @module @pwfabric/runtime/capability/validation
+ */
+import { resolveCapabilityId } from './type-mapping.js';
+// ============================================================
+// VALIDATION
+// ============================================================
+/**
+ * Validate that a surface's capability requirements can be met
+ * by the capabilities available in the registry.
+ *
+ * Capability strings can be either:
+ * - Short-form types from starters (e.g., 'persistence') which are resolved via type-mapping
+ * - Full capability IDs (e.g., 'platform/persistence') used directly
+ *
+ * @param requirements - The capability requirements declared by a surface
+ * @param registry - The capability registry to validate against
+ * @returns A ValidationResult indicating which requirements are met
+ */
+export function validateSurfaceCapabilities(requirements, registry) {
+    const satisfied = [];
+    const missing = [];
+    const optional = [];
+    for (const requirement of requirements) {
+        const { capability, required } = requirement;
+        // Try to resolve short-form type to full ID, or use as-is
+        const resolvedId = resolveCapabilityId(capability);
+        const lookupId = resolvedId ?? capability;
+        // Check if the capability is registered
+        // Use capabilityId() cast since registry.has() expects a branded CapabilityId
+        const isRegistered = registry.has(lookupId);
+        if (isRegistered) {
+            satisfied.push(capability);
+        }
+        else if (required) {
+            missing.push(capability);
+        }
+        else {
+            optional.push(capability);
+        }
+    }
+    return {
+        valid: missing.length === 0,
+        satisfied,
+        missing,
+        optional,
+    };
+}
+//# sourceMappingURL=validation.js.map

package/dist/capability/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/capability/validation.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AAgCvD,+DAA+D;AAC/D,aAAa;AACb,+DAA+D;AAE/D;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,2BAA2B,CACzC,YAA8C,EAC9C,QAA4B;IAE5B,MAAM,SAAS,GAAa,EAAE,CAAA;IAC9B,MAAM,OAAO,GAAa,EAAE,CAAA;IAC5B,MAAM,QAAQ,GAAa,EAAE,CAAA;IAE7B,KAAK,MAAM,WAAW,IAAI,YAAY,EAAE,CAAC;QACvC,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,WAAW,CAAA;QAE5C,0DAA0D;QAC1D,MAAM,UAAU,GAAG,mBAAmB,CAAC,UAAU,CAAC,CAAA;QAClD,MAAM,QAAQ,GAAG,UAAU,IAAI,UAAU,CAAA;QAEzC,wCAAwC;QACxC,8EAA8E;QAC9E,MAAM,YAAY,GAAG,QAAQ,CAAC,GAAG,CAAC,QAA2D,CAAC,CAAA;QAE9F,IAAI,YAAY,EAAE,CAAC;YACjB,SAAS,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;QAC5B,CAAC;aAAM,IAAI,QAAQ,EAAE,CAAC;YACpB,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;QAC1B,CAAC;aAAM,CAAC;YACN,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;QAC3B,CAAC;IACH,CAAC;IAED,OAAO;QACL,KAAK,EAAE,OAAO,CAAC,MAAM,KAAK,CAAC;QAC3B,SAAS;QACT,OAAO;QACP,QAAQ;KACT,CAAA;AACH,CAAC","sourcesContent":["/**\n * Surface Capability Validation\n *\n * Validates that a surface's capability requirements\n * can be satisfied by the capabilities registered in a registry.\n *\n * @module @pwfabric/runtime/capability/validation\n */\n\nimport type { CapabilityRegistry } from '../registry.js'\nimport { resolveCapabilityId } from './type-mapping.js'\n\n// ============================================================\n// TYPES\n// ============================================================\n\n/**\n * A capability requirement declared by a surface.\n */\nexport interface CapabilityRequirement {\n  /** The capability type string (e.g., 'persistence' or 'platform/persistence') */\n  readonly capability: string\n  /** Whether this capability is required (true) or optional (false) */\n  readonly required: boolean\n  /** Optional configuration for the capability */\n  readonly config?: Record<string, unknown>\n}\n\n/**\n * Result of validating surface capabilities against a registry.\n */\nexport interface CapabilityValidationResult {\n  /** Whether all required capabilities are satisfied */\n  readonly valid: boolean\n  /** IDs of capabilities that are registered and satisfy requirements */\n  readonly satisfied: readonly string[]\n  /** IDs of required capabilities that are NOT registered */\n  readonly missing: readonly string[]\n  /** IDs of optional capabilities that are NOT registered */\n  readonly optional: readonly string[]\n}\n\n// ============================================================\n// VALIDATION\n// ============================================================\n\n/**\n * Validate that a surface's capability requirements can be met\n * by the capabilities available in the registry.\n *\n * Capability strings can be either:\n * - Short-form types from starters (e.g., 'persistence') which are resolved via type-mapping\n * - Full capability IDs (e.g., 'platform/persistence') used directly\n *\n * @param requirements - The capability requirements declared by a surface\n * @param registry - The capability registry to validate against\n * @returns A ValidationResult indicating which requirements are met\n */\nexport function validateSurfaceCapabilities(\n  requirements: readonly CapabilityRequirement[],\n  registry: CapabilityRegistry\n): CapabilityValidationResult {\n  const satisfied: string[] = []\n  const missing: string[] = []\n  const optional: string[] = []\n\n  for (const requirement of requirements) {\n    const { capability, required } = requirement\n\n    // Try to resolve short-form type to full ID, or use as-is\n    const resolvedId = resolveCapabilityId(capability)\n    const lookupId = resolvedId ?? capability\n\n    // Check if the capability is registered\n    // Use capabilityId() cast since registry.has() expects a branded CapabilityId\n    const isRegistered = registry.has(lookupId as ReturnType<typeof resolveCapabilityId> & string)\n\n    if (isRegistered) {\n      satisfied.push(capability)\n    } else if (required) {\n      missing.push(capability)\n    } else {\n      optional.push(capability)\n    }\n  }\n\n  return {\n    valid: missing.length === 0,\n    satisfied,\n    missing,\n    optional,\n  }\n}\n"]}

package/dist/connectors/declared-connector.d.ts

@@ -0,0 +1,48 @@
+/**
+ * build an engine from its DECLARATION.
+ *
+ * A REST engine is not a class. A class has a call signature, and a
+ * hand-written engine that takes one options object where the runtime passes
+ * two positional arguments ends up asking SharePoint for `lists/undefined`.
+ * A declaration has no signature to get wrong.
+ *
+ * WHAT THIS MODULE IS ALLOWED TO KNOW: how to turn seven declared facts into
+ * an `HttpEntityConnector`. It must not know a vendor's name, and the
+ * placement test measures exactly that — no provider name anywhere in
+ * `packages/runtime`. Everything SharePoint-shaped lives in the declaration,
+ * which lives in the pack that ships the connector.
+ *
+ * WHAT THE BASE DOES NOT LEARN. `entityPathMapper` and `responseMapper` stay
+ * plain functions on `HttpConnectorConfig`; this builds them. The pre-flight —
+ * Graph cannot address a list before its site id is resolved — is handled by
+ * constructing ONE base per resolved binding, so the mapper stays synchronous.
+ * Making it asynchronous would teach a shared contract one vendor's
+ * addressing dance.
+ *
+ * @module @pwfabric/runtime/connectors/declared-connector
+ */
+import type { EngineDeclaration } from '@pwfabric/contracts';
+import type { EntityConnector } from '../entity/connector.js';
+/**
+ * The only value transforms a declaration may name.
+ *
+ * CLOSED ON PURPOSE. A declaration carries a NAME, never a function — the
+ * moment it could carry a function it would be a class again with extra steps,
+ * and an AI-written declaration would regain the power to get something wrong.
+ * An unknown name throws at construction (see `resolveTransform`) rather than
+ * passing values through unchanged, because a silently skipped transform looks
+ * exactly like a field the source never sent.
+ *
+ * These two are named for what they DO, not for who needs them: the runtime
+ * must not learn a vendor's name.
+ */
+export declare const VALUE_TRANSFORMS: Readonly<Record<string, (value: unknown) => unknown>>;
+export interface DeclaredConnectorOptions {
+    /** Connection name — the engine reports it, and the registry keys on it. */
+    readonly name: string;
+    readonly declaration: EngineDeclaration;
+    /** Per-connection config the declaration's templates draw on. */
+    readonly config: Readonly<Record<string, unknown>>;
+    readonly getAccessToken: () => Promise<string | null>;
+}
+export declare function createDeclaredConnector(options: DeclaredConnectorOptions): EntityConnector;