@warpgogol/werkstatt-shared 0.14.0 → 0.15.0

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/vitest.config.ts

@@ -3,6 +3,14 @@ import { defineConfig } from "vitest/config";
 export default defineConfig({
   test: {
     environment: "node",
+    testTimeout: 30_000,
     include: ["src/**/*.test.ts"],
+    coverage: {
+      provider: "v8",
+      reporter: ["json", "json-summary", "text-summary", "html"],
+      reportsDirectory: "../../.coverage/integration",
+      include: ["src/integration/**/*.ts"],
+      exclude: ["src/integration/**/*.test.ts", "src/integration/**/*.d.ts"],
+    },
   },
 });

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;
+}

package/src/kernel/diagnostic.ts

@@ -0,0 +1,289 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+  Sole runtime and type owner of DiagnosticSeverity, DiagnosticEvidence, and
+  Diagnostic strict Zod schemas (RFC-0852). Types are inferred from schemas.
+  kernel/types.ts re-exports these types; the site plugin imports the schemas.
+</purpose>
+<non-goals>
+  <item>Do not define canonical JSON bytes or limits; RFC-0849 owns them.</item>
+  <item>Do not define EvidenceEnvelopeV1, certification identities, or dossier admission; RFC-0853 owns those.</item>
+  <item>Do not add command status vocabularies or suppression systems.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0852: Move canonical Diagnostic ownership from site plugin into the engine.</item>
+  <item>RFC-1027: Add structured remediation hints — remediationRefSchema and remediation field on Diagnostic.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+import {
+  isCanonicalJsonObjectV1,
+  canonicalJsonBytesV1,
+  type CanonicalJsonObjectV1,
+} from "../fingerprint/canonical-json.ts";
+
+// ---------------------------------------------------------------------------
+// Limits (RFC-0852 §Bounds)
+// ---------------------------------------------------------------------------
+
+export const DIAGNOSTIC_LIMITS = {
+  ruleIdChars: 128,
+  messageBytes: 4 * 1024,
+  fixHintBytes: 8 * 1024,
+  pathBytes: 1024,
+  urlBytes: 4 * 1024,
+  snippetBytes: 16 * 1024,
+  evidenceItems: 32,
+  dataBytes: 64 * 1024,
+  diagnosticBytes: 128 * 1024,
+  diagnosticsPerResult: 1000,
+  remediationActionBytes: 512,
+  remediationTargetFiles: 8,
+} as const;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function utf8ByteLength(value: string): number {
+  return Buffer.byteLength(value, "utf8");
+}
+
+// ---------------------------------------------------------------------------
+// Diagnostic rule ID — [A-Z0-9][A-Z0-9._-]* , max 128 ASCII chars
+// ---------------------------------------------------------------------------
+
+const diagnosticRuleIdPattern = /^[A-Z0-9][A-Z0-9._-]*$/;
+
+export const diagnosticRuleIdSchema = z
+  .string()
+  .max(DIAGNOSTIC_LIMITS.ruleIdChars)
+  .regex(
+    diagnosticRuleIdPattern,
+    "CERT-DIAGNOSTIC-SCHEMA-01: ruleId must match [A-Z0-9][A-Z0-9._-]*",
+  );
+
+// ---------------------------------------------------------------------------
+// Safe workspace-relative POSIX path
+// ---------------------------------------------------------------------------
+
+const unsafePathPatterns = [
+  /[/\\]\.\.([/\\]|$)/, // .. component
+  /[/\\]\.([/\\]|$)/, // . component (but allow leading . for dotfiles? No — RFC says reject empty/.)
+  /^\//, // absolute path
+  /^[/\\]/, // leading separator
+  /\\/, // backslash
+  /\0/, // NUL
+  /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//, // URI scheme
+  /^~([/\\]|$)/, // home expansion
+  /^[a-zA-Z]:[\\/]/, // Windows drive letter
+];
+
+function isSafeWorkspaceRelativePath(value: string): boolean {
+  if (value.length === 0) return false;
+  if (utf8ByteLength(value) > DIAGNOSTIC_LIMITS.pathBytes) return false;
+  for (const pattern of unsafePathPatterns) {
+    if (pattern.test(value)) return false;
+  }
+  // Reject empty components from split
+  const segments = value.split("/");
+  for (const seg of segments) {
+    if (seg.length === 0) return false; // empty component (e.g. "a//b")
+    if (seg === "." || seg === "..") return false;
+  }
+  return true;
+}
+
+export const safeWorkspaceRelativePathSchema = z.string().refine(isSafeWorkspaceRelativePath, {
+  message:
+    "CERT-DIAGNOSTIC-LOCATOR-01: path must be a workspace-relative POSIX path without absolute paths, backslashes, empty/./.. components, NUL, URI schemes, or home expansion",
+});
+
+// ---------------------------------------------------------------------------
+// Safe diagnostic URL — absolute http/https, no userinfo, no credentials
+// ---------------------------------------------------------------------------
+
+function isSafeDiagnosticUrl(value: string): boolean {
+  if (utf8ByteLength(value) > DIAGNOSTIC_LIMITS.urlBytes) return false;
+  if (/\0/.test(value)) return false;
+  if (/[\x00-\x1f\x7f]/.test(value)) return false; // control characters
+
+  let parsed: URL;
+  try {
+    parsed = new URL(value);
+  } catch {
+    return false;
+  }
+
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return false;
+
+  // Reject userinfo (credentials in authority)
+  if (parsed.username || parsed.password) return false;
+
+  // Reject credential-bearing query parameters (best-effort high-confidence)
+  const query = parsed.searchParams;
+  const credentialKeys = [
+    "token",
+    "access_token",
+    "secret",
+    "api_key",
+    "apikey",
+    "key",
+    "password",
+    "passwd",
+    "pwd",
+    "authorization",
+    "auth",
+    "signature",
+    "sig",
+  ];
+  for (const key of credentialKeys) {
+    if (query.has(key)) return false;
+  }
+
+  return true;
+}
+
+export const safeDiagnosticUrlSchema = z.string().refine(isSafeDiagnosticUrl, {
+  message:
+    "CERT-DIAGNOSTIC-LOCATOR-01: URL must be an absolute http/https URL with no userinfo, control characters, or credential-bearing query parameters",
+});
+
+// ---------------------------------------------------------------------------
+// Redacted diagnostic text — no known secrets/PII/absolute paths
+// ---------------------------------------------------------------------------
+
+const secretPatterns = [
+  /sk-[A-Za-z0-9_-]{20,}/, // OpenAI-style API key
+  /eyJ[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]+/, // JWT
+  /-----BEGIN (?:RSA |EC |OPENSSH |)PRIVATE KEY-----/, // private key
+  /Bearer\s+[A-Za-z0-9_-]{20,}/, // bearer token
+  /Authorization:\s*Bearer\s+[A-Za-z0-9_-]{20,}/i, // auth header
+  /(?:mongodb|postgres|postgresql|mysql|redis):\/\/[^\s@"']+:[^\s@"']+@/, // connection string
+  /(?:aws_access_key_id|aws_secret_access_key)\s*=\s*[A-Za-z0-9/+=]{16,}/, // AWS creds
+];
+
+const absolutePathPatterns = [
+  /^(?:\/|[A-Za-z]:[\\/]|~[\\/])/, // absolute or home path
+];
+
+const piiPatterns = [
+  /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/, // email
+  /\b\d{3}[-.]?\d{3}[-.]?\d{4}\b/, // phone (US-like)
+];
+
+function isRedactedDiagnosticText(value: string, maxBytes: number): boolean {
+  if (utf8ByteLength(value) > maxBytes) return false;
+  if (value.trim().length === 0) return false;
+
+  for (const pattern of secretPatterns) {
+    if (pattern.test(value)) return false;
+  }
+  for (const pattern of absolutePathPatterns) {
+    if (pattern.test(value)) return false;
+  }
+  for (const pattern of piiPatterns) {
+    if (pattern.test(value)) return false;
+  }
+  return true;
+}
+
+function redactedDiagnosticTextSchema(maxBytes: number) {
+  return z.string().refine((val) => isRedactedDiagnosticText(val, maxBytes), {
+    message: `CERT-DIAGNOSTIC-REDACTION-01: text must not contain known secrets, PII, or absolute paths and must be within ${maxBytes} UTF-8 bytes`,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Canonical JSON object V1 schema for Diagnostic.data
+// ---------------------------------------------------------------------------
+// RFC-0852: data must be a runtime-branded CanonicalJsonObjectV1 at parse time.
+// The TypeScript type is Record<string, unknown> for structural compatibility
+// with existing producers; the Zod custom check enforces canonical validation
+// before persistence. z.custom is used instead of z.record because Zod 4's
+// z.record structural validation rejects branded frozen objects created by
+// snapshotCanonicalJsonObjectV1.
+
+const canonicalJsonObjectV1Schema = z
+  .custom<Record<string, unknown>>(
+    (val): val is CanonicalJsonObjectV1 => isCanonicalJsonObjectV1(val),
+    {
+      message: "CERT-DIAGNOSTIC-SCHEMA-01: data must be a runtime-branded CanonicalJsonObjectV1",
+    },
+  )
+  .refine(
+    (val) => {
+      if (!isCanonicalJsonObjectV1(val)) return false;
+      const bytes = canonicalJsonBytesV1(val);
+      return bytes.length <= DIAGNOSTIC_LIMITS.dataBytes;
+    },
+    {
+      message: `CERT-DIAGNOSTIC-LIMIT-01: canonical data bytes must not exceed ${DIAGNOSTIC_LIMITS.dataBytes} bytes`,
+    },
+  );
+
+// ---------------------------------------------------------------------------
+// Severity
+// ---------------------------------------------------------------------------
+
+export const diagnosticSeveritySchema = z.enum(["error", "warning", "info"]);
+export type DiagnosticSeverity = z.infer<typeof diagnosticSeveritySchema>;
+
+// ---------------------------------------------------------------------------
+// Evidence
+// ---------------------------------------------------------------------------
+
+export const diagnosticEvidenceSchema = z
+  .object({
+    kind: z.enum(["rule", "rendered", "source", "config", "cache", "runtime"]),
+    ruleFile: safeWorkspaceRelativePathSchema.optional(),
+    ruleId: diagnosticRuleIdSchema.optional(),
+    file: safeWorkspaceRelativePathSchema.optional(),
+    url: safeDiagnosticUrlSchema.optional(),
+    snippet: redactedDiagnosticTextSchema(DIAGNOSTIC_LIMITS.snippetBytes).optional(),
+  })
+  .strict();
+
+export type DiagnosticEvidence = z.infer<typeof diagnosticEvidenceSchema>;
+
+// ---------------------------------------------------------------------------
+// Remediation reference (RFC-1027)
+// ---------------------------------------------------------------------------
+
+export const remediationRefSchema = z
+  .object({
+    ruleId: diagnosticRuleIdSchema,
+    action: redactedDiagnosticTextSchema(DIAGNOSTIC_LIMITS.remediationActionBytes),
+    template: redactedDiagnosticTextSchema(DIAGNOSTIC_LIMITS.fixHintBytes).optional(),
+    docRef: safeWorkspaceRelativePathSchema.optional(),
+    targetFiles: z
+      .array(safeWorkspaceRelativePathSchema)
+      .max(DIAGNOSTIC_LIMITS.remediationTargetFiles)
+      .optional(),
+  })
+  .strict();
+
+export type RemediationRef = z.infer<typeof remediationRefSchema>;
+
+// ---------------------------------------------------------------------------
+// Diagnostic
+// ---------------------------------------------------------------------------
+
+export const diagnosticSchema = z
+  .object({
+    ruleId: diagnosticRuleIdSchema,
+    severity: diagnosticSeveritySchema,
+    message: redactedDiagnosticTextSchema(DIAGNOSTIC_LIMITS.messageBytes),
+    file: safeWorkspaceRelativePathSchema.optional(),
+    line: z.number().int().positive().optional(),
+    column: z.number().int().positive().optional(),
+    fixHint: redactedDiagnosticTextSchema(DIAGNOSTIC_LIMITS.fixHintBytes).optional(),
+    remediation: remediationRefSchema.optional(),
+    evidence: z.array(diagnosticEvidenceSchema).max(DIAGNOSTIC_LIMITS.evidenceItems).optional(),
+    data: canonicalJsonObjectV1Schema.optional(),
+  })
+  .strict();
+
+export type Diagnostic = z.infer<typeof diagnosticSchema>;