@warpgogol/werkstatt-shared 0.14.1 → 0.16.0

package/src/integration/tests/dispatch.test.ts

@@ -35,7 +35,7 @@ const EVENT: IntegrationEvent = {
 test("executeDispatch skips destinations when the tenant holds no secrets", async () => {
   const result = await executeDispatch({ siteId: "warpgogol-com", event: EVENT }, {});
   expect(result.routed.length).toBe(0);
-  expect(result.skipped.includes("crm:pipedrive")).toBeTruthy();
+  expect(result.skipped.includes("crm:lagebild")).toBeTruthy();
 });
 
 function stubDispatcher(
@@ -59,7 +59,7 @@ function stubDispatcher(
 test("dispatchToTenant acks on a routed reply and forwards only the inbound secret", async () => {
   let seen: Request | undefined;
   const dispatcher = stubDispatcher(
-    { routed: ["crm:pipedrive"], failed: [], skipped: [] },
+    { routed: ["crm:lagebild"], failed: [], skipped: [] },
     200,
     (r) => (seen = r),
   );
@@ -71,11 +71,11 @@ test("dispatchToTenant acks on a routed reply and forwards only the inbound secr
   expect(outcome.ok).toBe(true);
   expect(seen?.headers.get("x-integration-secret")).toBe("inbound-secret");
   const body = await seen!.text();
-  expect(!body.includes("PIPEDRIVE")).toBeTruthy();
+  expect(!body.includes("LAGEBILD")).toBeTruthy();
 });
 
 test("dispatchToTenant retries when nothing routed but something failed", async () => {
-  const dispatcher = stubDispatcher({ routed: [], failed: ["crm:pipedrive"], skipped: [] });
+  const dispatcher = stubDispatcher({ routed: [], failed: ["crm:lagebild"], skipped: [] });
   const outcome = await dispatchToTenant(dispatcher, { siteId: "x", event: EVENT }, "s");
   expect(outcome.ok).toBe(false);
 });

package/src/integration/tests/hub-runtime.test.ts

@@ -1,10 +1,10 @@
 /*
 <MODULE_CONTRACT>
 <purpose>RFC-0176: verify the inbound/queue runtime — authenticateInbound, IntegrationEventSchema,
-routeEventToReady (self-enabling Pipedrive route), and consumeIntegrationBatch dedup via a KV-backed
+routeEventToReady (self-enabling Lagebild route), and consumeIntegrationBatch dedup via a KV-backed
 seen-set. fetch + KV are stubbed so the full producer→consumer flow is exercised without Cloudflare.</purpose>
 <responsibilities>
-  <item>Assert a valid event routes once to the pipedrive gogol-adapter destination.</item>
+  <item>Assert a valid event routes once to the lagebild gogol-adapter destination.</item>
   <item>Assert a queue redelivery is deduped (no double-write) via the KV seen-set.</item>
   <item>Assert inbound auth + event-shape validation are fail-closed.</item>
 </responsibilities>
@@ -14,6 +14,7 @@ seen-set. fetch + KV are stubbed so the full producer→consumer flow is exercis
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0176: initial queue/inbound runtime test.</item>
+  <item>Lagebild replaced Pipedrive as sole CRM destination — test updated accordingly.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -30,8 +31,10 @@ import {
 } from "../index.ts";
 
 const SECRETS: IntegrationSecrets = {
-  INTEGRATION_PIPEDRIVE_API_TOKEN: "tok",
-  INTEGRATION_PIPEDRIVE_DOMAIN: "acme",
+  LAGEBILD_API_URL: "https://lagebild-api.example.workers.dev",
+  LAGEBILD_API_KEY: "lbk_test_key_0001",
+  LAGEBILD_TENANT_ID: "ten_warpgogol000001",
+  LAGEBILD_SOURCE_SYSTEM_ID: "site_warpgogol_com",
 };
 
 const EVENT: IntegrationEvent = {
@@ -63,13 +66,18 @@ const realFetch = globalThis.fetch;
 
 beforeEach(() => {
   fetchCalls = [];
-  // Stub Pipedrive persons + leads endpoints — both return a usable id.
+  // Stub Lagebild ingress endpoint — returns accepted with a submission id.
   globalThis.fetch = (async (url: string | URL | Request) => {
     fetchCalls.push(String(url));
     return {
       ok: true,
       status: 200,
-      json: async () => ({ data: { id: 1 } }),
+      json: async () => ({
+        submission_id: "sub_test123",
+        accepted: true,
+        is_replay: false,
+        correlation_id: null,
+      }),
     } as unknown as Response;
   }) as typeof fetch;
 });
@@ -78,17 +86,17 @@ afterEach(() => {
   globalThis.fetch = realFetch;
 });
 
-test("routeEventToReady routes a lead to the pipedrive gogol-adapter destination", async () => {
+test("routeEventToReady routes a lead to the lagebild gogol-adapter destination", async () => {
   const result = await routeEventToReady(EVENT, SECRETS);
-  expect(result.routed).toEqual(["crm:pipedrive"]);
+  expect(result.routed).toEqual(["crm:lagebild"]);
   expect(result.failed.length).toBe(0);
-  // pipedrive adapter performs persons + leads calls.
-  expect(fetchCalls.length).toBe(2);
+  // lagebild adapter performs a single POST to /v1/ingress.
+  expect(fetchCalls.length).toBe(1);
 });
 
 test("routeEventToReady skips when destination secrets are absent", async () => {
   const result = await routeEventToReady(EVENT, {});
-  expect(result.skipped).toEqual(["crm:pipedrive"]);
+  expect(result.skipped).toEqual(["crm:lagebild"]);
   expect(result.routed.length).toBe(0);
   expect(fetchCalls.length).toBe(0);
 });
@@ -98,13 +106,13 @@ test("consumeIntegrationBatch dedups a queue redelivery via KV (no double-write)
   const dedup = kvDedup(kv);
 
   const first = await consumeIntegrationBatch([EVENT], SECRETS, dedup);
-  expect(first[0].routed).toEqual(["crm:pipedrive"]);
+  expect(first[0].routed).toEqual(["crm:lagebild"]);
   const afterFirst = fetchCalls.length;
-  expect(afterFirst).toBe(2);
+  expect(afterFirst).toBe(1);
 
   // Redeliver the SAME eventId — must be skipped by dedup, no new fetches.
   const second = await consumeIntegrationBatch([EVENT], SECRETS, dedup);
-  expect(second[0].skipped).toEqual(["crm:pipedrive"]);
+  expect(second[0].skipped).toEqual(["crm:lagebild"]);
   expect(fetchCalls.length).toBe(afterFirst);
   expect(kv.size()).toBe(1);
 });

package/src/integration/tests/idempotency.test.ts

@@ -0,0 +1,81 @@
+/*
+<MODULE_CONTRACT>
+<purpose>RFC-1112: verify the Upstash Redis REST receipt store. get parses the stored
+{ receipt, bodyHash } record or returns null on a miss; put issues SET NX EX with the
+receipt JSON and the configured key prefix. Both throw on transport errors so the
+caller can decide fail-open semantics. fetch is stubbed — no network.</purpose>
+<responsibilities>
+  <item>get → null on miss, parsed record on hit, correct key prefix.</item>
+  <item>put → SET key JSON NX EX ttl command shape.</item>
+  <item>transport errors propagate (throw).</item>
+</responsibilities>
+<non-goals><item>No network — fetch stubbed.</item></non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY><item>RFC-1112: initial receipt store test.</item></CHANGE_SUMMARY>
+*/
+
+import { test, expect } from "vitest";
+import { restRedisReceiptStore, type ReceiptStoreRecord } from "../idempotency.ts";
+import type { ActionReceipt } from "@warpgogol/werkstatt-shared/agent";
+
+const RECEIPT: ActionReceipt = {
+  receiptId: "11111111-1111-1111-1111-111111111111",
+  status: "accepted",
+  duplicate: false,
+  submittedAt: "2026-07-05T00:00:00.000Z",
+};
+
+const CONFIG = { url: "https://eu-redis.upstash.io", token: "redis-secret" };
+
+function stubFetch(status: number, result: unknown) {
+  return async () => new Response(JSON.stringify({ result }), { status });
+}
+
+test("restRedisReceiptStore.get returns null on a miss", async () => {
+  const store = restRedisReceiptStore(CONFIG, stubFetch(200, null) as unknown as typeof fetch);
+  expect(await store.get("key-1")).toBeNull();
+});
+
+test("restRedisReceiptStore.get parses the stored record", async () => {
+  const record: ReceiptStoreRecord = { receipt: RECEIPT, bodyHash: "abc123" };
+  const store = restRedisReceiptStore(
+    CONFIG,
+    stubFetch(200, JSON.stringify(record)) as unknown as typeof fetch,
+  );
+  const got = await store.get("key-1");
+  expect(got).toEqual(record);
+});
+
+test("restRedisReceiptStore.get uses the configured key prefix", async () => {
+  let capturedBody = "";
+  const fetchSpy = (async (_url: unknown, init?: { body?: string }) => {
+    capturedBody = init?.body ?? "";
+    return new Response(JSON.stringify({ result: null }), { status: 200 });
+  }) as unknown as typeof fetch;
+  const store = restRedisReceiptStore({ ...CONFIG, prefix: "custom-prefix" }, fetchSpy);
+  await store.get("key-9");
+  expect(capturedBody).toBe(JSON.stringify(["GET", "custom-prefix:key-9"]));
+});
+
+test("restRedisReceiptStore.put issues SET key JSON NX EX ttl", async () => {
+  let capturedBody = "";
+  const fetchSpy = (async (_url: unknown, init?: { body?: string }) => {
+    capturedBody = init?.body ?? "";
+    return new Response(JSON.stringify({ result: "OK" }), { status: 200 });
+  }) as unknown as typeof fetch;
+  const store = restRedisReceiptStore(CONFIG, fetchSpy);
+  await store.put("key-1", "hash-1", RECEIPT, 86400);
+  const command = JSON.parse(capturedBody) as string[];
+  expect(command[0]).toBe("SET");
+  expect(command[1]).toBe("gogol-agent-idem:key-1");
+  const record = JSON.parse(command[2]!) as ReceiptStoreRecord;
+  expect(record.bodyHash).toBe("hash-1");
+  expect(record.receipt.receiptId).toBe(RECEIPT.receiptId);
+  expect(command.slice(3)).toEqual(["NX", "EX", "86400"]);
+});
+
+test("restRedisReceiptStore throws on transport errors", async () => {
+  const store = restRedisReceiptStore(CONFIG, stubFetch(500, null) as unknown as typeof fetch);
+  await expect(() => store.get("key-1")).rejects.toThrow();
+  await expect(() => store.put("key-1", "h", RECEIPT, 60)).rejects.toThrow();
+});

package/src/integration/vitest.config.ts

@@ -3,6 +3,7 @@ import { defineConfig } from "vitest/config";
 export default defineConfig({
   test: {
     environment: "node",
+    testTimeout: 30_000,
     include: ["src/**/*.test.ts"],
     coverage: {
       provider: "v8",

package/src/kernel/desired-state.ts

@@ -0,0 +1,227 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+Desired-state composition types for RFC-1038. Defines the declarative target
+(DesiredState), the runtime actual state (ActualState, replacing KernelRegistry),
+component/command/pipeline declarations, and the module export shape that
+replaces KernelModule.register().
+</purpose>
+<non-goals>
+  <item>Does not implement reconciliation logic — see reconciler.ts.</item>
+  <item>Does not implement overlay resolution — see overlay.ts.</item>
+  <item>Does not define Zod schemas — see component/schemas.ts.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1038: initial implementation — desired-state composition types replacing ComponentManifestV1, KernelModule, KernelRegistry.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { Sha256Digest } from "../fingerprint/primitives.ts";
+import type { ComponentScope, ScopeContext, ComponentDeclaration } from "../component/contracts.ts";
+import type {
+  KernelFlagSpec,
+  GeneratedArtifactSpec,
+  KernelPipelineStep,
+  KernelCommandMetadata,
+  KernelCommandInput,
+  KernelRuntimeContext,
+  KernelCommandResult,
+  ModuleFiberState,
+} from "./types.ts";
+
+/**
+ * Unified component type — replaces ComponentManifestV1.
+ * Re-exported from contracts.ts for convenience.
+ */
+export type { ComponentDeclaration };
+
+export interface DesiredState {
+  /** Stable component declarations keyed by componentId. Map for O(1) lookup. */
+  components: Map<string, ComponentDeclaration>;
+  /** Capability contracts that must be satisfied. */
+  requiredCapabilities: string[];
+  /** Available artifacts for resolution. */
+  availableArtifacts: ReadonlyMap<string, Sha256Digest>;
+  /** Admitted grants for resolution. */
+  admittedGrants: ReadonlyArray<{ scope: string; resource: string }>;
+  /** Profile ID for resolution. */
+  profileId: string;
+}
+
+export interface ReconciliationDelta {
+  /** Components to activate (present in desired, absent in actual). */
+  toActivate: ComponentDeclaration[];
+  /** Components to deactivate (absent in desired, present in actual). */
+  toDeactivate: string[];
+  /** Components to reconfigure (present in both, but config changed). */
+  toReconfigure: Array<{
+    id: string;
+    oldConfig: Record<string, unknown>;
+    newConfig: Record<string, unknown>;
+  }>;
+  /** Components unchanged (present in both, config identical). */
+  unchanged: string[];
+  /** Missing dependencies — required capabilities with no provider. */
+  missingDependencies: Array<{ capability: string; requiredBy: string }>;
+}
+
+export interface ReconciliationResult {
+  delta: ReconciliationDelta;
+  applied: boolean;
+  /** Components that failed to activate. */
+  failures: Array<{ id: string; reason: string }>;
+  /** Time taken to reconcile, in milliseconds. */
+  durationMs: number;
+}
+
+/**
+ * Command declaration — replaces KernelCommandDefinition for registration.
+ * Carries ALL metadata fields from KernelCommandDefinition plus the execute function.
+ * Type safety is preserved: execute receives typed KernelCommandInput and KernelRuntimeContext.
+ */
+export interface CommandDeclaration extends KernelCommandMetadata {
+  /** Command name — e.g. "sternsystem.validate". */
+  name: string;
+  /** RFC-0260: declared flag schema. */
+  flags?: Record<string, KernelFlagSpec>;
+  /** RFC-0266: workspace-root-relative path globs this command reads. */
+  reads?: string[];
+  /** RFC-0266: workspace-root-relative path globs this command writes. */
+  writes?: string[];
+  /** RFC-0637: paths relative to module src/ for cache hashing. */
+  modulePaths?: string[];
+  /** RFC-0687: command names whose outputs this validator checks. */
+  validatesOutputs?: string[];
+  /** RFC-0960: repo-relative path to the implementing source file. */
+  modulePath?: string;
+  /** RFC-0960: declared generated artifacts. */
+  generates?: GeneratedArtifactSpec[];
+  /** RFC-0963: the single contract this validator enforces. */
+  contract?: string;
+  /** RFC-0963: the rule IDs this validator enforces. */
+  rules?: string[];
+  /** The execute function — typed, same signature as KernelCommandDefinition.execute. */
+  execute: (
+    input: KernelCommandInput,
+    context: KernelRuntimeContext,
+  ) => Promise<void | KernelCommandResult> | void | KernelCommandResult;
+}
+
+/**
+ * Pipeline declaration — replaces registerPipeline() calls.
+ * Carries the pipeline name and steps with all KernelPipelineStep fields.
+ */
+export interface PipelineDeclaration {
+  /** Pipeline name — e.g. "packages.check". */
+  name: string;
+  /** Pipeline steps with command references, args, timeouts, and dependsOn (RFC-0686). */
+  steps: KernelPipelineStep[];
+}
+
+/**
+ * Module export — replaces KernelModule.
+ * Each *.module.ts file exports this object instead of calling register().
+ * The reconciler reads declarations, commands, and pipelines from this export.
+ */
+export interface ModuleExport {
+  /** Module name — e.g. "sternsystem". */
+  name: string;
+  /** Module version. */
+  version: string;
+  /** Component declarations for desired-state composition. */
+  declarations: ComponentDeclaration[];
+  /**
+   * Command declarations — replaces registerCommand() calls.
+   * execute functions may lazy-load implementations via `await import()`
+   * inside the execute body, preserving the current lazy-loading pattern.
+   */
+  commands: CommandDeclaration[];
+  /** Pipeline declarations — replaces registerPipeline() calls. */
+  pipelines: PipelineDeclaration[];
+  /**
+   * Optional conditional declaration builder.
+   * Replaces conditional registration logic in register() bodies.
+   * Receives the runtime context (env vars, profile, etc.) and returns
+   * additional or modified declarations/commands/pipelines.
+   * This runs at startup before reconciliation, not at registration time.
+   */
+  conditionalBuilder?: (context: ModuleBuildContext) => {
+    declarations?: ComponentDeclaration[];
+    commands?: CommandDeclaration[];
+    pipelines?: PipelineDeclaration[];
+  };
+}
+
+/**
+ * Build context passed to conditionalBuilder.
+ * Provides environment and profile information for conditional declarations.
+ */
+export interface ModuleBuildContext {
+  /** Environment variables (process.env snapshot). */
+  env: Record<string, string | undefined>;
+  /** Profile ID from kernel config. */
+  profileId: string;
+  /** Whether this is a long-running process (dev server, watch mode). */
+  longRunning: boolean;
+}
+
+/**
+ * Actual state — replaces KernelRegistry entirely.
+ * The desired state is the declarative target; the actual state is what's
+ * currently running. The reconciler updates actual state to match desired state.
+ * Command execution reads from actual state — no separate registry needed.
+ *
+ * Commands and pipelines are always available — they're the module's interface,
+ * not dynamically activated. They're populated once at startup from ModuleExport[]
+ * and never change. The reconciler only manages components (capabilities and effects).
+ * A command may check component state at execution time if it depends on a capability.
+ */
+export interface ActualState {
+  /** Active components with their runtime fiber state, keyed by componentId. */
+  components: ReadonlyMap<string, { declaration: ComponentDeclaration; state: ModuleFiberState }>;
+  /**
+   * All declared commands from all ModuleExport[], keyed by command name.
+   * Populated once at startup, never changes.
+   */
+  commands: ReadonlyMap<string, CommandDeclaration>;
+  /**
+   * All declared pipelines from all ModuleExport[], keyed by pipeline name.
+   * Populated once at startup, never changes.
+   */
+  pipelines: ReadonlyMap<string, KernelPipelineStep[]>;
+  /**
+   * Map from command name to module name — used for command manifest generation.
+   * Populated once at startup alongside commands.
+   */
+  commandModules?: ReadonlyMap<string, string>;
+}
+
+/**
+ * Mutable version of ActualState — used by the reconciler for component mutations.
+ * Commands and pipelines are still readonly (populated once at startup).
+ */
+export interface MutableActualState {
+  components: Map<string, { declaration: ComponentDeclaration; state: ModuleFiberState }>;
+  commands: ReadonlyMap<string, CommandDeclaration>;
+  pipelines: ReadonlyMap<string, KernelPipelineStep[]>;
+}
+
+/**
+ * Overlay — layered patch on the base desired state.
+ * Allows scope-specific modifications without rewriting the base.
+ */
+export interface DesiredStateOverlay {
+  /** Overlay ID — stable and unique within the scope. */
+  id: string;
+  /** Scope this overlay applies to (RFC-1036). */
+  scope: ComponentScope;
+  /** Scope context (e.g., missionId for per-mission overlays). */
+  context: ScopeContext;
+  /** Components to add or replace in the base desired state. */
+  addOrReplace: Map<string, ComponentDeclaration>;
+  /** Component IDs to remove from the base desired state. */
+  remove: string[];
+  /** Priority — higher priority overlays override lower ones. */
+  priority: number;
+}