@arki/dot 0.3.0 → 0.4.0

package/src/diagnostics.ts

@@ -3,11 +3,11 @@
  *
  * Where the manifest describes the static shape of an app, a
  * `DotDiagnosticsSnapshot` is a point-in-time observability record: the
- * lifecycle state of the app and every pip, plus structured issues with
+ * lifecycle state of the app and every plugin, plus structured issues with
  * remediation guidance.
  *
  * CONTRACT: `DotDiagnosticsSnapshot` always exposes the same five arrays
- * (`pips`, `routes`, `services`, `lifecycle`, `issues`). Consumers must
+ * (`plugins`, `actions`, `services`, `lifecycle`, `issues`). Consumers must
  * never see an omitted array — empty is empty, but never missing.
  * This is the "5 arrays" contract referenced by the kernel spec.
  */
@@ -17,54 +17,58 @@ import type { DotLifecycleHook, DotLifecycleState } from './lifecycle.js';
 /** Severity of a single diagnostic issue. */
 export type DiagnosticSeverity = 'info' | 'warning' | 'error';
 
-/** Status of a pip/route/service/lifecycle entry. */
+/** Status of a plugin/action/service/lifecycle entry. */
 export type DiagnosticStatus = 'ok' | 'degraded' | 'failed' | 'skipped' | 'missing';
 
 /**
  * Single point-in-time diagnostic snapshot of a DotApp.
  *
- * Five top-level arrays — pips, routes, services, lifecycle, issues —
+ * Five top-level arrays — plugins, actions, services, lifecycle, issues —
  * are guaranteed to be present even when empty.
  */
 export type DotDiagnosticsSnapshot = {
+  /** Diagnostic snapshot schema version. 2 = actions/projections era. */
+  snapshotVersion: 2;
   /** ISO-8601 timestamp at which the snapshot was generated. */
   generatedAt: string;
   app: {
     name: string;
     state: DotLifecycleState;
   };
-  pips: PipDiagnostic[];
-  routes: RouteDiagnostic[];
+  plugins: PluginDiagnostic[];
+  actions: ActionDiagnostic[];
   services: ServiceDiagnostic[];
   lifecycle: LifecycleDiagnostic[];
   issues: DiagnosticIssue[];
 };
 
-export type PipDiagnostic = {
-  pip: string;
+export type PluginDiagnostic = {
+  plugin: string;
   status: Extract<DiagnosticStatus, 'ok' | 'degraded' | 'failed' | 'skipped'>;
   issues: DiagnosticIssue[];
 };
 
-export type RouteDiagnostic = {
+export type ActionDiagnostic = {
   id: string;
-  pip: string;
+  plugin: string;
+  binding: string;
+  /** Structural configure-phase health only; not runtime liveness. */
   status: Extract<DiagnosticStatus, 'ok' | 'degraded' | 'failed'>;
   issues: DiagnosticIssue[];
 };
 
 export type ServiceDiagnostic = {
   service: string;
-  pip: string;
+  plugin: string;
   status: Extract<DiagnosticStatus, 'ok' | 'degraded' | 'failed' | 'missing'>;
   issues: DiagnosticIssue[];
 };
 
 export type LifecycleDiagnostic = {
-  pip: string;
+  plugin: string;
   hook: DotLifecycleHook;
   state: DotLifecycleState;
-  /** 0-based topological order of this pip within the hook pass. */
+  /** 0-based topological order of this plugin within the hook pass. */
   order: number;
   /** Wall-clock duration of the hook call, in milliseconds. */
   durationMs?: number;
@@ -72,7 +76,7 @@ export type LifecycleDiagnostic = {
 };
 
 /**
- * Single structured issue surfaced by the kernel or by a pip.
+ * Single structured issue surfaced by the kernel or by a plugin.
  *
  * `code`, `message`, `remediation` and `docsUrl` are required so that issues
  * are always actionable — never just "something went wrong".
@@ -81,7 +85,7 @@ export type DiagnosticIssue = {
   /** Stable machine-readable code, e.g. `DOT_LIFECYCLE_E003`. */
   code: string;
   severity: DiagnosticSeverity;
-  pip?: string;
+  plugin?: string;
   message: string;
   /** Human-readable remediation: what the developer should do. */
   remediation: string;

package/src/index.ts

@@ -3,20 +3,29 @@
  *
  * Public surface:
  *   - `defineApp(name)` — the entry point for composing applications.
- *   - `pip(config)` — author lifecycle-aware pips with typed needs/provides.
+ *   - `plugin(config)` — author lifecycle-aware plugins with typed needs/provides.
  *   - `service<T>()` / `token<T>()(key)` — service witnesses for DI wiring.
- *   - `rename(pip, map)` — mount-time multi-instance primitive.
+ *   - `rename(plugin, map)` — mount-time multi-instance primitive.
  *   - Lifecycle / manifest / diagnostics types.
- *   - `testApp` / `bootTestApp` — test harnesses for pip authors.
+ *   - `testApp` / `bootTestApp` — test harnesses for plugin authors.
  */
 
 // #region Kernel — public surface
 export { defineApp } from './define-app.js';
-export type { DotApp, DotAppBuilder, DotAppConfigured, UseGuard } from './define-app.js';
+export type {
+  DotApp,
+  DotAppBuilder,
+  DotAppConfigured,
+  NormalizeProvides,
+  UseAllAvail,
+  UseAllGuard,
+  UseGuard,
+} from './define-app.js';
 
-export { isLazy, lazy, lazyOf, pip, provide, rename, service, token, DotPipError } from './pip-contract.js';
+export { isLazy, lazy, lazyOf, plugin, provide, rename, service, token, DotPluginError } from './plugin-contract.js';
 export type {
-  AnyPip,
+  AnyPlugin,
+  ActionSource,
   CtxOf,
   DotConfigureContext,
   EmptyShape,
@@ -25,15 +34,19 @@ export type {
   Lazy,
   LazyService,
   NeedsShape,
-  Pip,
-  PipNeeds,
-  PipProvides,
+  NoReservedKeys,
+  Plugin,
+  PluginNeeds,
+  PluginProvides,
   RenamedProvides,
   Service,
   ServiceRecord,
   Token,
   WireNeeds,
-} from './pip-contract.js';
+} from './plugin-contract.js';
+
+export { initPlugins } from './init-plugins.js';
+export type { InitPluginsFactory } from './init-plugins.js';
 
 export {
   DotLifecycleError,
@@ -43,26 +56,30 @@ export {
 export type {
   DotLifecycleHook,
   DotLifecycleState,
-  DotLifecyclePipFailure,
+  DotLifecyclePluginFailure,
   DotLifecycleErrorCodeValue,
 } from './lifecycle.js';
 
 export type {
   DotAppManifest,
-  PipManifest,
-  RouteManifest,
+  ActionDirection,
+  ActionManifest,
+  JsonObject,
+  JsonValue,
+  PluginManifest,
+  ProjectionManifest,
   ServiceManifest,
   LifecycleManifest,
   DependencyEdge,
   DependencyEdgeKind,
   ServiceKind,
-  RouteTransport,
 } from './manifest.js';
+export { toJsonObject } from './manifest.js';
 
 export type {
   DotDiagnosticsSnapshot,
-  PipDiagnostic,
-  RouteDiagnostic,
+  PluginDiagnostic,
+  ActionDiagnostic,
   ServiceDiagnostic,
   LifecycleDiagnostic,
   DiagnosticIssue,
@@ -75,19 +92,19 @@ export type {
   DotLifecycleEventStatus,
   DotLifecycleObserver,
   DotPhaseLifecycleEvent,
-  DotPipHookLifecycleEvent,
+  DotPluginHookLifecycleEvent,
 } from './lifecycle-observer.js';
 
 export { renderTimeline } from './timeline.js';
 export type { RenderTimelineOptions } from './timeline.js';
 
-export { testApp, bootTestApp, testPip } from './test-harness.js';
-export type { TestAppOptions, TestPipBuilder } from './test-harness.js';
+export { testApp, bootTestApp, testPlugin } from './test-harness.js';
+export type { TestAppOptions, TestPluginBuilder } from './test-harness.js';
 
 export { hookSignals } from './signals.js';
 export type { HookSignalsOptions, SignalTarget } from './signals.js';
 
 // Task 9b: CLI envelope type is exported so adapter packages can produce the
-// same shape from related tooling (release-tooling, pip scaffolds, etc.).
+// same shape from related tooling (release-tooling, plugin scaffolds, etc.).
 export type { DotCliEnvelope, DotCliEnvelopeStatus } from './cli/render-explain.js';
 // #endregion

package/src/init-plugins.ts

@@ -0,0 +1,142 @@
+import type {
+  CtxOf,
+  DotConfigureContext,
+  EmptyShape,
+  InferredProvides,
+  KernelCtx,
+  NeedsShape,
+  NoReservedKeys,
+  Plugin,
+  ActionSource,
+  Service,
+  ServiceRecord,
+  WireNeeds,
+} from './plugin-contract.js';
+import { plugin as definePlugin, service } from './plugin-contract.js';
+
+type MaybePromise<T> = T | Promise<T>;
+type ServiceKey<TServices extends object> = Extract<keyof TServices, string>;
+type ServiceKeys<TServices extends object> = readonly ServiceKey<TServices>[];
+
+type PickServices<TServices extends object, TKeys extends ServiceKeys<TServices>> = {
+  readonly [K in TKeys[number]]: TServices[K];
+};
+
+type WitnessesFor<TServices extends object, TKeys extends ServiceKeys<TServices>> = {
+  readonly [K in TKeys[number]]: Service<TServices[K]>;
+};
+
+type SchemaCheckedProvides<TServices extends object, TProvides extends ServiceRecord> = {
+  readonly [K in keyof TProvides]: K extends keyof TServices
+    ? TProvides[K] extends TServices[K]
+      ? TProvides[K]
+      : never
+    : TProvides[K];
+};
+
+type CommonPluginDefinition = {
+  readonly name: string;
+  readonly version?: string;
+  readonly actions?: readonly ActionSource[];
+  readonly configure?: (ctx: DotConfigureContext) => void;
+};
+
+type KeyArrayPluginDefinition<
+  TServices extends object,
+  TKeys extends ServiceKeys<TServices>,
+  TProvides extends ServiceRecord & NoReservedKeys,
+> = CommonPluginDefinition & {
+  readonly needs?: TKeys;
+  readonly boot?: (ctx: PickServices<TServices, TKeys> & KernelCtx) => MaybePromise<SchemaCheckedProvides<TServices, TProvides> | void>;
+  readonly start?: (ctx: PickServices<TServices, TKeys> & TProvides & KernelCtx) => MaybePromise<void>;
+  readonly stop?: (ctx: PickServices<TServices, TKeys> & TProvides & KernelCtx) => MaybePromise<void>;
+  readonly dispose?: (ctx: PickServices<TServices, TKeys> & TProvides & KernelCtx) => MaybePromise<void>;
+};
+
+type WitnessPluginDefinition<
+  TServices extends object,
+  TShape extends NeedsShape & NoReservedKeys,
+  TProvides extends ServiceRecord & NoReservedKeys,
+> = CommonPluginDefinition & {
+  readonly needs: TShape;
+  readonly boot?: (ctx: CtxOf<TShape> & KernelCtx) => MaybePromise<SchemaCheckedProvides<TServices, TProvides> | void>;
+  readonly start?: (ctx: CtxOf<TShape> & TProvides & KernelCtx) => MaybePromise<void>;
+  readonly stop?: (ctx: CtxOf<TShape> & TProvides & KernelCtx) => MaybePromise<void>;
+  readonly dispose?: (ctx: CtxOf<TShape> & TProvides & KernelCtx) => MaybePromise<void>;
+};
+
+export type InitPluginsFactory<TServices extends object> = {
+  plugin<
+    const TKeys extends ServiceKeys<TServices> = readonly [],
+    TProvides extends ServiceRecord & NoReservedKeys = EmptyShape,
+  >(
+    def: KeyArrayPluginDefinition<TServices, TKeys, TProvides>,
+  ): Plugin<PickServices<TServices, TKeys>, InferredProvides<TProvides>>;
+  plugin<TShape extends NeedsShape & NoReservedKeys, TProvides extends ServiceRecord & NoReservedKeys = EmptyShape>(
+    def: WitnessPluginDefinition<TServices, TShape, TProvides>,
+  ): Plugin<WireNeeds<TShape>, InferredProvides<TProvides>>;
+  needs<const TKeys extends ServiceKeys<TServices>>(...keys: TKeys): WitnessesFor<TServices, TKeys>;
+};
+
+type ErasedPluginDefinition<TServices extends object> =
+  | KeyArrayPluginDefinition<TServices, ServiceKeys<TServices>, ServiceRecord & NoReservedKeys>
+  | WitnessPluginDefinition<TServices, NeedsShape & NoReservedKeys, ServiceRecord & NoReservedKeys>;
+
+type KernelPluginDefinition = Parameters<
+  typeof definePlugin<NeedsShape & NoReservedKeys, ServiceRecord & NoReservedKeys>
+>[0];
+
+function needsFor<TServices extends object, const TKeys extends ServiceKeys<TServices>>(
+  keys: TKeys,
+): WitnessesFor<TServices, TKeys> {
+  const needs: Record<string, Service<unknown>> = {};
+  for (const key of keys) {
+    needs[key] = service<TServices[typeof key]>();
+  }
+  return needs as WitnessesFor<TServices, TKeys>;
+}
+
+function isServiceKeyArray<TServices extends object>(
+  needs: ErasedPluginDefinition<TServices>['needs'],
+): needs is ServiceKeys<TServices> {
+  return Array.isArray(needs);
+}
+
+function createPluginFactory<TServices extends object>(): InitPluginsFactory<TServices> {
+  const factory = {
+    plugin(def: ErasedPluginDefinition<TServices>): Plugin<ServiceRecord, ServiceRecord> {
+      const rawNeeds = def.needs;
+      const needs = isServiceKeyArray<TServices>(rawNeeds)
+        ? needsFor<TServices, ServiceKeys<TServices>>(rawNeeds)
+        : rawNeeds;
+      // Factory seam: key-array authoring is runtime-compiled to the same
+      // witness record that the kernel already understands.
+      const kernelDef: KernelPluginDefinition = {
+        name: def.name,
+        ...(def.version === undefined ? {} : { version: def.version }),
+        ...(needs === undefined ? {} : { needs }),
+        ...(def.actions === undefined ? {} : { actions: def.actions }),
+        ...(def.configure === undefined ? {} : { configure: def.configure }),
+        ...(def.boot === undefined ? {} : { boot: def.boot as KernelPluginDefinition['boot'] }),
+        ...(def.start === undefined ? {} : { start: def.start as KernelPluginDefinition['start'] }),
+        ...(def.stop === undefined ? {} : { stop: def.stop as KernelPluginDefinition['stop'] }),
+        ...(def.dispose === undefined ? {} : { dispose: def.dispose as KernelPluginDefinition['dispose'] }),
+      };
+      return definePlugin(kernelDef) as unknown as Plugin<ServiceRecord, ServiceRecord>;
+    },
+    needs<const TKeys extends ServiceKeys<TServices>>(...keys: TKeys): WitnessesFor<TServices, TKeys> {
+      return needsFor<TServices, typeof keys>(keys);
+    },
+  };
+  return factory as InitPluginsFactory<TServices>;
+}
+
+export const initPlugins = {
+  context<TServices extends object>() {
+    return {
+      create(): InitPluginsFactory<TServices> {
+        return createPluginFactory<TServices>();
+      },
+    };
+  },
+};