/*
<MODULE_CONTRACT>
<purpose>
RFC-0564: Kernel module registering swim.join, swim.leave, swim.members, and
swim.status workspace commands. All commands are workspace-scoped and not
cacheable (they depend on external network state and workshop-local files).
</purpose>
<non-goals>
  <item>Do not implement command handlers — those live in handlers.ts.</item>
  <item>Do not implement genome log I/O — that lives in genome-log.ts.</item>
  <item>Do not implement config loading — that lives in config.ts.</item>
</non-goals>
</MODULE_CONTRACT>
<KEY_DECISIONS>
  <item>Module registers commands only — SWIM logic lives in the sibling handler modules.</item>
</KEY_DECISIONS>
<CHANGE_SUMMARY>
  <item>RFC-0564: initial implementation — swim module with join, leave, members, status commands.</item>
  <item>RFC-1097: step 6 — compass.migrate codemod run

Mechanical v1 to v2 header migration across the workspace: 942 files rewritten — CHANGE_SUMMARY windows collapsed into history, forbidden v1 blocks stripped, KEY_DECISIONS seeded from @ai-invariant comments (5 files) or TODO placeholders (103 files), blocks reordered to canonical order.</item>
  <item>RFC-1097: sweep — werkstatt-engine clean

Sweep batch 4: 73 Compass headers on headerless engine files (certification, component-runtime, isolation, evolution, testing), real KEY_DECISIONS on 75 files (kernel, cache, dht, swim, gitmesh, runtime), ~80 purpose expansions (CONTRACT-02/PURPOSE-02), non-goals on 13 CONTRACT-03 files, CS-07 history literal fix repo-wide (253 files). Policy: .template.ts/.template.astro excludedPaths. werkstatt-engine now 0 diagnostics.</item>
  <item>RFC-1173: declare mutatesState on all kernel commands — collectDeclarationDiagnostics emits error-severity MUTATES-STATE-DECLARED, command.manifest.validate is the blocking consumer in packages.check, sweep declares the flag on every command definition (factories hardcode false for read-only check specs)</item>
</CHANGE_SUMMARY>
*/

import type { ModuleExport } from "@warpgogol/werkstatt-shared/kernel";

export async function createSwimModule(): Promise<ModuleExport> {
  const { runSwimJoin, runSwimLeave, runSwimMembers, runSwimStatus } =
    await import("./handlers.ts");
  return {
    name: "swim",
    version: "0.1.0",

    declarations: [],
    commands: [
      {
        name: "swim.join",
        coverage: "operator" as const,
        mutatesState: true,
        modulePath: "packages/werkstatt-engine/src/kernel/swim/swim-module.ts",
        generates: [],
        description:
          "RFC-0564: join a SWIM workshop network. Probes the seed node via UDP, " +
          "creates werkstatt.swim.json if missing (generating UUID v7 for workshopId), " +
          "records alive event to the CRDT genome log with Ed25519 signature. " +
          "Ephemeral — SWIM instance is destroyed when command exits. " +
          "Use --seed <host:port> to specify the seed node. Use --json for machine-readable output.",
        scope: "workspace",
        cacheable: false,
        requiresNetwork: true,
        flags: {
          seed: { kind: "string", description: "Seed node address (host:port)." },
        },
        reads: ["werkstatt.identity.json"],
        writes: ["werkstatt.swim.json", "werkstatt.genome.log"],
        execute: runSwimJoin,
      },
      {
        name: "swim.leave",
        coverage: "operator" as const,
        mutatesState: true,
        modulePath: "packages/werkstatt-engine/src/kernel/swim/swim-module.ts",
        generates: [],
        description:
          "RFC-0564: leave a SWIM workshop network. Records left event to the CRDT " +
          "genome log with Ed25519 signature. Ephemeral — no long-running daemon to shut down. " +
          "Use --json for machine-readable output.",
        scope: "workspace",
        cacheable: false,
        flags: {},
        reads: ["werkstatt.swim.json", "werkstatt.identity.json"],
        writes: ["werkstatt.genome.log"],
        execute: runSwimLeave,
      },
      {
        name: "swim.members",
        coverage: "operator" as const,
        mutatesState: false,
        modulePath: "packages/werkstatt-engine/src/kernel/swim/swim-module.ts",
        description:
          "RFC-0564: list workshop members from the CRDT genome log. Local-only query — " +
          "no network I/O. Reads werkstatt.genome.log, verifies signatures, derives membership " +
          "view (latest event per workshop wins). Use --json for machine-readable output.",
        scope: "workspace",
        cacheable: false,
        flags: {},
        reads: ["werkstatt.swim.json", "werkstatt.genome.log", "werkstatt.identity.json"],
        execute: runSwimMembers,
      },
      {
        name: "swim.status",
        coverage: "operator" as const,
        mutatesState: false,
        modulePath: "packages/werkstatt-engine/src/kernel/swim/swim-module.ts",
        description:
          "RFC-0564: check local SWIM status. Reports configuration state, workshopId, " +
          "genome log size (warns at 10MB), membership view, and any skipped entries. " +
          "Local-only query — no network I/O. Use --json for machine-readable output.",
        scope: "workspace",
        cacheable: false,
        flags: {},
        reads: ["werkstatt.swim.json", "werkstatt.genome.log", "werkstatt.identity.json"],
        execute: runSwimStatus,
      },
    ],
    pipelines: [],
  };
}