/*
<MODULE_CONTRACT>
  <purpose>Lazy-loading kernel module for RFC-0355 Bordbuch commands: append and validate, the append-only hash-chained event log for Sternsystems.</purpose>
  <non-goals>
    <item>Do not re-export types or utilities — the barrel bordbuch/index.ts remains the public API surface.</item>
    <item>Do not register mission or release commands here.</item>
  </non-goals>
</MODULE_CONTRACT>
<CHANGE_SUMMARY>
  <item>RFC-0626: add bordbuch.commit command registration.</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>
  <item>RFC-1231: step 1 — rename supportsAllSites to acceptsAllFlag

Mechanical sweep: the field only ever gated --all argv acceptance; fan-out
follows the parsed selector. Guard renamed assertAllSitesAllowed ->
assertAllFlagAccepted, message updated. 417 declaration sites + type
surfaces (KernelCommandMetadata, ForgeCommandMetadata) in one atomic pass.</item>
  <history>RFC-0583</history>
</CHANGE_SUMMARY>
*/

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

export async function createBordbuchModule(): Promise<ModuleExport> {
  const { runBordbuchAppend } = await import("./bordbuch-append.ts");
  const { runBordbuchValidate } = await import("./bordbuch-validate.ts");
  const { runBordbuchStatus } = await import("./bordbuch-status.ts");
  const { runBordbuchGenerate } = await import("./bordbuch-generate.ts");
  const { runBordbuchRepair } = await import("./bordbuch-repair.ts");
  const { runBordbuchCommit } = await import("./bordbuch-commit.ts");
  return {
    name: "bordbuch",
    version: "0.1.0",
    declarations: [],
    commands: [
      {
        name: "bordbuch.append",
        modulePath: "packages/werkstatt-engine/src/bordbuch/bordbuch.module.ts",
        generates: [],
        description:
          "Append a single entry to the Bordbuch through the controlled writer-role surface (RFC-0355). Required flags: `--system`, `--kind`, `--summary`, `--writer-role`.",
        scope: "workspace",
        acceptsAllFlag: false,
        mutatesState: true,
        flags: {
          system: { kind: "string", required: true, description: "Sternsystem id." },
          kind: { kind: "string", required: true, description: "Bordbuch entry kind." },
          summary: { kind: "string", required: true, description: "Human-readable event summary." },
          mission: { kind: "string", description: "Related mission id." },
          release: { kind: "string", description: "Related release id." },
          actor: { kind: "string", default: "agent", description: "Actor identity." },
          "writer-role": {
            kind: "string",
            required: true,
            description: "Controlled writer role allowed to append this entry kind.",
          },
          metadata: { kind: "string", description: "JSON metadata object." },
        },
        writes: ["systems/{system}/bordbuch/events.ndjson"],
        reads: ["systems/{system}/bordbuch/events.ndjson"],
        cacheable: false,
        execute: runBordbuchAppend,
      },
      {
        name: "bordbuch.validate",
        mutatesState: false,
        contract: "bordbuch",
        rules: [],
        modulePath: "packages/werkstatt-engine/src/bordbuch/bordbuch.module.ts",
        description:
          "Validate the Bordbuch hash-chain, lifecycle pairs, and sensitive payload guards (RFC-0355).",
        scope: "workspace",
        acceptsAllFlag: false,
        flags: {
          system: {
            kind: "string",
            description:
              "Sternsystem id. Defaults to the site name when running in a site-scoped pipeline.",
          },
        },
        reads: ["systems/{system}/bordbuch/events.ndjson"],
        execute: runBordbuchValidate,
      },
      {
        name: "bordbuch.status",
        coverage: "operator" as const,
        mutatesState: false,
        modulePath: "packages/werkstatt-engine/src/bordbuch/bordbuch.module.ts",
        description:
          "Read-only Bordbuch status projection: ledger hash, event count, latest event, open escalations (RFC-0473).",
        scope: "workspace",
        acceptsAllFlag: false,
        flags: {
          system: {
            kind: "string",
            description:
              "Sternsystem id. Defaults to the site name when running in a site-scoped pipeline.",
          },
        },
        reads: ["systems/{system}/bordbuch/events.ndjson"],
        execute: runBordbuchStatus,
      },
      {
        name: "bordbuch.generate",
        modulePath: "packages/werkstatt-engine/src/bordbuch/bordbuch.module.ts",
        description:
          "Generate rich public Bordbuch projections (JSON + HTML + YAML) from the unified ledger (RFC-0473).",
        scope: "workspace",
        acceptsAllFlag: false,
        mutatesState: true,
        flags: {
          system: {
            kind: "string",
            description:
              "Sternsystem id. Defaults to the site name when running in a site-scoped pipeline.",
          },
        },
        reads: ["systems/{system}/bordbuch/events.ndjson"],
        writes: [
          "systems/{system}/public/.well-known/bordbuch.json",
          "systems/{system}/public/.well-known/bordbuch/index.html",
          "systems/{system}/bordbuch/status.generated.yaml",
        ],
        generates: [
          {
            path: "systems/{system}/public/.well-known/bordbuch.json",
            phase: "build.post",
            conditional: true,
          },
          {
            path: "systems/{system}/public/.well-known/bordbuch/index.html",
            phase: "build.post",
            conditional: true,
          },
          { path: "public/.well-known/bordbuch.json", phase: "build.post", conditional: true },
          {
            path: "public/.well-known/bordbuch/index.html",
            phase: "build.post",
            conditional: true,
          },
          {
            path: "public/.well-known/bordbuch/events.ndjson",
            phase: "build.post",
            conditional: true,
          },
          {
            path: "public/.well-known/bordbuch/status.generated.yaml",
            phase: "build.post",
            conditional: true,
          },
        ],
        cacheable: false,
        execute: runBordbuchGenerate,
      },
      {
        name: "bordbuch.repair",
        modulePath: "packages/werkstatt-engine/src/bordbuch/bordbuch.module.ts",
        generates: [],
        description:
          "Repair orphan-mission-close violations by inserting missing mission-open events and recomputing the hash chain (RFC-0583). Required flags: `--system`.",
        scope: "workspace",
        acceptsAllFlag: false,
        mutatesState: true,
        flags: {
          system: { kind: "string", required: true, description: "Sternsystem id." },
          "dry-run": { kind: "boolean", description: "Show planned repairs without writing." },
          mission: { kind: "string", description: "Repair only the specified mission id." },
          metadata: {
            kind: "string",
            description:
              "JSON object with occurredAt, summary, actor for the inserted mission-open event.",
          },
        },
        writes: ["systems/{system}/bordbuch/events.ndjson"],
        reads: ["systems/{system}/bordbuch/events.ndjson"],
        cacheable: false,
        execute: runBordbuchRepair,
      },
      {
        name: "bordbuch.commit",
        modulePath: "packages/werkstatt-engine/src/bordbuch/bordbuch.module.ts",
        description:
          "Auto-commit dirty bordbuch projection files in the cache clone (RFC-0626). Internal pipeline step.",
        scope: "workspace",
        acceptsAllFlag: false,
        mutatesState: true,
        flags: {
          system: {
            kind: "string",
            description:
              "Sternsystem id. Defaults to the site name when running in a site-scoped pipeline.",
          },
        },
        reads: [
          "systems/{system}/public/.well-known/bordbuch.json",
          "systems/{system}/public/.well-known/bordbuch/index.html",
          "systems/{system}/bordbuch/status.generated.yaml",
        ],
        cacheable: false,
        execute: runBordbuchCommit,
      },
    ],
    pipelines: [],
  };
}