feat: add module runtime lifecycle

packages/contracts/src/module-manifest.ts

@@ -9,6 +9,7 @@ import {
 import { semanticVersionRangeSchema, semanticVersionSchema } from "./versions.js";
 
 const moduleVersionMapSchema = z.record(moduleIdSchema, semanticVersionRangeSchema);
+const capabilityVersionMapSchema = z.record(capabilityIdSchema, semanticVersionRangeSchema);
 
 const moduleDependenciesSchema = z
   .object({
@@ -20,11 +21,11 @@ const moduleDependenciesSchema = z
 
 const capabilityDependenciesSchema = z
   .object({
-    required: z.array(capabilityIdSchema).default(() => []),
-    optional: z.array(capabilityIdSchema).default(() => []),
+    required: capabilityVersionMapSchema.default(() => ({})),
+    optional: capabilityVersionMapSchema.default(() => ({})),
   })
   .strict()
-  .default(() => ({ required: [], optional: [] }));
+  .default(() => ({ required: {}, optional: {} }));
 
 const dependenciesSchema = z
   .object({
@@ -34,9 +35,16 @@ const dependenciesSchema = z
   .strict()
   .default(() => ({
     modules: { required: {}, optional: {} },
-    capabilities: { required: [], optional: [] },
+    capabilities: { required: {}, optional: {} },
   }));
 
+export const moduleCapabilityDeclarationSchema = z
+  .object({
+    id: capabilityIdSchema,
+    version: semanticVersionSchema,
+  })
+  .strict();
+
 export const moduleBucketDeclarationSchema = z
   .object({
     id: logicalBucketIdSchema,
@@ -64,6 +72,7 @@ function reportDuplicates(
   values: readonly string[],
   path: readonly (string | number)[],
   context: z.RefinementCtx,
+  property?: string,
 ): void {
   const seen = new Set<string>();
   values.forEach((value, index) => {
@@ -71,7 +80,7 @@ function reportDuplicates(
       context.addIssue({
         code: "custom",
         message: `${value} is declared more than once.`,
-        path: [...path, index],
+        path: [...path, index, ...(property ? [property] : [])],
       });
     }
     seen.add(value);
@@ -80,7 +89,7 @@ function reportDuplicates(
 
 export const moduleManifestSchema = z
   .object({
-    manifestVersion: z.literal(1),
+    manifestVersion: z.literal(2),
     id: moduleIdSchema,
     name: z.string().trim().min(1).max(120),
     description: z.string().trim().min(1).max(500).optional(),
@@ -92,37 +101,33 @@ export const moduleManifestSchema = z
       })
       .strict(),
     dependencies: dependenciesSchema,
-    capabilities: z.array(capabilityIdSchema).default(() => []),
+    capabilities: z.array(moduleCapabilityDeclarationSchema).default(() => []),
     permissions: z.array(permissionIdSchema).default(() => []),
     storage: moduleStorageSchema,
     entrypoints: entrypointsSchema,
   })
   .strict()
   .superRefine((manifest, context) => {
-    reportDuplicates(manifest.capabilities, ["capabilities"], context);
+    reportDuplicates(
+      manifest.capabilities.map((capability) => capability.id),
+      ["capabilities"],
+      context,
+      "id",
+    );
     reportDuplicates(manifest.permissions, ["permissions"], context);
-    reportDuplicates(
-      manifest.dependencies.capabilities.required,
-      ["dependencies", "capabilities", "required"],
-      context,
-    );
-    reportDuplicates(
-      manifest.dependencies.capabilities.optional,
-      ["dependencies", "capabilities", "optional"],
-      context,
-    );
     reportDuplicates(
       manifest.storage.buckets.map((bucket) => bucket.id),
       ["storage", "buckets"],
       context,
+      "id",
     );
 
     manifest.capabilities.forEach((capability, index) => {
-      if (!capability.startsWith(`${manifest.id}.`)) {
+      if (!capability.id.startsWith(`${manifest.id}.`)) {
         context.addIssue({
           code: "custom",
           message: `Capability identifiers owned by this module must begin with ${manifest.id}.`,
-          path: ["capabilities", index],
+          path: ["capabilities", index, "id"],
         });
       }
     });
@@ -157,33 +162,27 @@ export const moduleManifestSchema = z
       }
     }
 
-    const ownedCapabilities = new Set(manifest.capabilities);
-    const requiredCapabilities = new Set(manifest.dependencies.capabilities.required);
-    manifest.dependencies.capabilities.required.forEach((capability, index) => {
-      if (ownedCapabilities.has(capability)) {
-        context.addIssue({
-          code: "custom",
-          message: "A module does not need to depend on a capability it owns.",
-          path: ["dependencies", "capabilities", "required", index],
-        });
+    const ownedCapabilities = new Set(manifest.capabilities.map((capability) => capability.id));
+    for (const dependencyKind of ["required", "optional"] as const) {
+      for (const capability of Object.keys(manifest.dependencies.capabilities[dependencyKind])) {
+        if (ownedCapabilities.has(capability)) {
+          context.addIssue({
+            code: "custom",
+            message: "A module does not need to depend on a capability it owns.",
+            path: ["dependencies", "capabilities", dependencyKind, capability],
+          });
+        }
       }
-    });
-    manifest.dependencies.capabilities.optional.forEach((capability, index) => {
-      if (ownedCapabilities.has(capability)) {
-        context.addIssue({
-          code: "custom",
-          message: "A module does not need to depend on a capability it owns.",
-          path: ["dependencies", "capabilities", "optional", index],
-        });
-      }
-      if (requiredCapabilities.has(capability)) {
+    }
+    for (const capability of Object.keys(manifest.dependencies.capabilities.required)) {
+      if (Object.hasOwn(manifest.dependencies.capabilities.optional, capability)) {
         context.addIssue({
           code: "custom",
           message: `${capability} cannot be both a required and optional capability dependency.`,
-          path: ["dependencies", "capabilities", "optional", index],
+          path: ["dependencies", "capabilities", "optional", capability],
         });
       }
-    });
+    }
   });
 
 export function parseModuleManifest(input: unknown): ModuleManifest {
@@ -197,3 +196,4 @@ export function safeParseModuleManifest(input: unknown) {
 export type ModuleManifestInput = z.input<typeof moduleManifestSchema>;
 export type ModuleManifest = z.output<typeof moduleManifestSchema>;
 export type ModuleBucketDeclaration = z.output<typeof moduleBucketDeclarationSchema>;
+export type ModuleCapabilityDeclaration = z.output<typeof moduleCapabilityDeclarationSchema>;