@forgeax/engine-plugin 0.1.20 → 0.1.23

package/README.md

@@ -1,6 +1,6 @@
 # @forgeax/engine-plugin
 
-`@forgeax/engine-plugin` is the sole ForgeaX runtime entry to [DeepSeek Cordis](https://www.npmjs.com/package/@deepseek-ai/cordis). The main export remains a thin re-export of `@deepseek-ai/cordis@4.0.1`; the opt-in `@forgeax/engine-plugin/loader` subpath adds the exact-pinned DeepSeek Harness Entry/Loader control plane plus a browser-safe static Catalog boundary.
+`@forgeax/engine/plugin` is the sole ForgeaX runtime entry to [DeepSeek Cordis](https://www.npmjs.com/package/@deepseek-ai/cordis). The main export remains a thin re-export of `@deepseek-ai/cordis@4.0.1`; the opt-in `@forgeax/engine/plugin/loader` subpath adds the exact-pinned Entry/Loader control plane plus a browser-safe static Catalog boundary.
 
 > [!IMPORTANT]
 > Cordis owns when a capability exists, what it depends on, and how it is reverted. ECS, Renderer, Assets, and Host packages own the direct data structures that execute it. Entry and Fiber work never enters per-entity, per-draw, or per-particle loops.
@@ -19,7 +19,7 @@
 The Catalog is not a package scanner. Devkit emits only modules already admitted by `forge.json.plugins[]`; production does not inspect `node_modules`, evaluate YAML, or construct arbitrary dynamic import strings.
 
 ```ts
-import { installCatalogLoader, projectPluginEntries } from '@forgeax/engine-plugin/loader';
+import { installCatalogLoader, projectPluginEntries } from '@forgeax/engine/plugin/loader';
 
 const catalog = new Map([
   ['./movement.ts', { realm: 'engine', load: () => import('./movement.ts') }],
@@ -33,12 +33,99 @@ await loader.await();
 
 `loader.update(id, { disabled: true })`, `loader.update(id, { config })`, and `loader.remove(id)` use native DeepSeek Harness Entry reconciliation. A failed config update rolls back to the last working Fiber and its contributions.
 
+## Root Group authoring
+
+Use one public Group as the project root. Each `usePlugin` declaration carries its
+configuration. A stable key is optional: when omitted, the native Plugin object is
+the child's identity; an explicit key preserves identity across reorder, config
+update, replacement, and retry. Reusing one Plugin object without distinct keys
+is rejected when it would create ambiguous instances.
+
+```ts
+import { definePluginGroup, usePlugin } from '@forgeax/engine/plugin';
+import type { Plugin } from '@forgeax/engine/plugin';
+
+const movement: Plugin.Object<{ speed: number }> = {
+  name: 'movement',
+  provide: 'movementSpeed',
+  apply(ctx, config: { speed: number }) {
+    ctx.provide('movementSpeed', config.speed);
+  },
+};
+
+const gameRoot = definePluginGroup({
+  name: 'game-root',
+  children: (config: { speed: number }) => [
+    usePlugin(movement, { speed: config.speed }, { key: 'movement' }),
+  ],
+});
+
+const rootFiber = await context.plugin(gameRoot, { speed: 6 });
+await rootFiber.await();
+
+// @ts-expect-error speed must be a number
+usePlugin(movement, { speed: 'not-a-number' }, { key: 'invalid' });
+```
+
+The Group owns reconciliation while each child Fiber owns its own effect and
+disposer. A rejected update leaves the prior Fiber and configuration as the
+last-known-good state; repair the child owner, then retry the same Entry update.
+The retry must await both the update and the Loader barrier before publishing a
+new state.
+
+```ts
+import type {
+  CatalogLoaderError,
+  CatalogLoader,
+  PluginCompositionError,
+} from '@forgeax/engine/plugin';
+
+function recoveryOwner(error: PluginCompositionError | CatalogLoaderError): string {
+  switch (error.code) {
+    case 'plugin-config-invalid':
+      return `Group config for ${error.detail.plugin}`;
+    case 'plugin-group-child-failed':
+      return `child ${error.detail.child}`;
+    case 'plugin-group-dependency-cycle':
+      return `dependency path ${error.detail.path.join(' > ')}`;
+    case 'plugin-group-key-duplicate':
+      return `stable key ${error.detail.key}`;
+    case 'plugin-group-key-required':
+      return `stable key for ${error.detail.plugin}`;
+    case 'plugin-group-provider-missing':
+      return `provider ${error.detail.service}`;
+    case 'plugin-catalog-missing':
+      return `Catalog entry ${error.detail.name}`;
+    case 'plugin-realm-mismatch':
+      return `realm ${error.detail.actual} for ${error.detail.name}`;
+    case 'plugin-entry-realm-mixed':
+      return `Group ${error.detail.group}`;
+    case 'plugin-realm-unsupported':
+      return `realm ${error.detail.realm}`;
+    case 'plugin-catalog-digest-mismatch':
+      return `Catalog digest ${error.detail.actual}`;
+  }
+}
+
+async function retryLastKnownGood(
+  loader: CatalogLoader,
+  entries: Parameters<CatalogLoader['root']['update']>[0],
+): Promise<void> {
+  await loader.root.update(entries);
+  await loader.await();
+}
+```
+
+`recoveryOwner` deliberately has no `default`: every closed error arm names its
+owner and detail. `retryLastKnownGood` is the owner-level recovery barrier; it
+does not dispose a working Fiber or fabricate a second registry.
+
 ## Native Cordis foundation
 
 The Loader does not replace direct Cordis composition. A host that already owns the plugin set can still create one World context and dispose an individual Fiber:
 
 ```ts
-import { createWorldContext } from '@forgeax/engine-ecs';
+import { createWorldContext } from '@forgeax/engine/ecs';
 import optionalGameFeature from './optional-game-feature';
 import projectPlugin from './project-plugin';
 
@@ -77,7 +164,7 @@ publishing the replacement.
 
 A plugin owns reversible runtime contributions, not JavaScript module evaluation. Component and system tokens are vocabulary; installing them into one World creates lifecycle state.
 
-`defineComponent` and `defineSystem` still publish tokens to legacy process-wide discovery. Unloading removes the World-local lease, schedule membership, and owned data; it does not delete imported token objects or invalidate archetypes in another World.
+`defineComponent` and `defineSystem` publish tokens as vocabulary. Unloading removes the World-local lease, schedule membership, and owned data; it does not delete imported token objects or invalidate archetypes in another World.
 
 ```mermaid
 flowchart LR
@@ -102,8 +189,8 @@ flowchart LR
 Register World vocabulary and its consumers in one generator effect. Yield each inverse immediately so partial activation and normal disposal share the same reverse order:
 
 ```ts
-import { defineComponent, defineSystem, Update } from '@forgeax/engine-ecs';
-import type { Plugin } from '@forgeax/engine-plugin';
+import { defineComponent, defineSystem, Update } from '@forgeax/engine/ecs';
+import type { Plugin } from '@forgeax/engine/plugin';
 
 const Position = defineComponent('Position', { x: 'f32' });
 const movement = defineSystem({
@@ -131,9 +218,6 @@ export default plugin;
 
 Disposal removes the system before releasing the component registration. The final component lease returns `component-in-use` while a live entity or registered system still references the token, preventing a half-unloaded World. The same token can be registered in two Worlds; each World owns an independent lease.
 
-> [!NOTE]
-> The legacy process-wide ECS discovery maps still exist for consumers not yet migrated to a target World. They are compatibility discovery only, not proof that a plugin is active. New plugin lifecycle code must use `world.components`; removing the legacy maps is a later migration after every name-based scene, restore, inspector, and external consumer has moved.
-
 ## Ownership rule
 
 Cleanup follows ownership, not access. A plugin removes an entity or component value only if it created or exclusively owns it. Shared game state needs an explicit owner; it must not be inferred from which systems happened to read it.
@@ -149,7 +233,7 @@ rebuilds the World instead of maintaining a second ownership graph for every ent
 
 A clean disposal leaves no active schedule entry, World lease, resource, listener, Host object, or
 plugin-owned ECS value from that Fiber. Imported component and system tokens may remain in the ESM realm
-and legacy discovery maps: they are inert vocabulary, not a live capability or unmanaged side effect.
+and token vocabulary: they are inert declarations, not a live capability or unmanaged side effect.
 
 ## Failure and performance boundaries
 

package/dist/__tests__/composition-contract.test-d.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=composition-contract.test-d.d.ts.map

package/dist/__tests__/composition-contract.test-d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composition-contract.test-d.d.ts","sourceRoot":"","sources":["../../src/__tests__/composition-contract.test-d.ts"],"names":[],"mappings":""}

package/dist/__tests__/composition.integration.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=composition.integration.test.d.ts.map

package/dist/__tests__/composition.integration.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composition.integration.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/composition.integration.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/public-api.test-d.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=public-api.test-d.d.ts.map

package/dist/__tests__/public-api.test-d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-api.test-d.d.ts","sourceRoot":"","sources":["../../src/__tests__/public-api.test-d.ts"],"names":[],"mappings":""}

package/dist/__tests__/realm-loader.integration.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=realm-loader.integration.test.d.ts.map

package/dist/__tests__/realm-loader.integration.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realm-loader.integration.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/realm-loader.integration.test.ts"],"names":[],"mappings":""}

package/dist/browser.d.ts

@@ -9,5 +9,7 @@
  */
 export * from '@deepseek-ai/cordis';
 export { createContextCapabilityResolver } from './capability.js';
+export { definePluginGroup, PluginCompositionError, type PluginCompositionErrorArgs, type PluginCompositionErrorCode, type PluginCompositionErrorDetailByCode, type PluginGroupOptions, type PluginUse, type PluginUseOptions, usePlugin, } from './composition.js';
+export { type CatalogPluginFiberState, type CatalogPluginInspection, type CatalogPluginInspectionEntry, type CatalogPluginInspectionFailure, inspectCatalogPlugins, } from './inspection.js';
 export { defineToolPlugin, isToolPlugin, type ToolPlugin, } from './tool-plugin.js';
 //# sourceMappingURL=browser.d.ts.map

package/dist/browser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,cAAc,qBAAqB,CAAC;AACpC,OAAO,EAAE,+BAA+B,EAAE,MAAM,iBAAiB,CAAC;AAClE,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,KAAK,UAAU,GAChB,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,cAAc,qBAAqB,CAAC;AACpC,OAAO,EAAE,+BAA+B,EAAE,MAAM,iBAAiB,CAAC;AAClE,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,KAAK,0BAA0B,EAC/B,KAAK,0BAA0B,EAC/B,KAAK,kCAAkC,EACvC,KAAK,kBAAkB,EACvB,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,SAAS,GACV,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,uBAAuB,EAC5B,KAAK,4BAA4B,EACjC,KAAK,8BAA8B,EACnC,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,KAAK,UAAU,GAChB,MAAM,kBAAkB,CAAC"}