@warpgogol/werkstatt-shared 0.14.1 → 0.16.0

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

package/src/kernel/drift-guard.ts

@@ -0,0 +1,166 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-1126: pre-overwrite drift guard. Generators that rewrite git-tracked files
+call guardTrackedOverwrite before writing; when the on-disk content carries
+manual edits that the new content would destroy, the guard warns (default) or
+throws (--strict) listing the exact keys/sections that would be lost.
+</purpose>
+<non-goals>
+  <item>Does not perform the write itself — callers write via context.io / writeFileIfChanged after the guard returns.</item>
+  <item>Does not decide marker-protocol skips — callers run hasGeneratedMarker checks first; the guard only sees files about to be written.</item>
+  <item>Does not guard non-tracked files — the caller decides which paths are git-tracked generated outputs.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<KEY_DECISIONS>
+  <item>Warn-by-default: an unattended pipeline must not break on pre-existing drift; --strict is the sole fail-hard opt-in (never --force, which keeps DNA-93 cache-clearing semantics).</item>
+  <item>The guard is a pre-write side effect, never a cached result — command-result caching (RFC-0390) must not cache it.</item>
+</KEY_DECISIONS>
+<CHANGE_SUMMARY>
+  <item>RFC-1126: initial implementation — DriftReport, DriftGuardOptions, guardTrackedOverwrite with json/yaml/text key extraction.</item>
+  <item>RFC-1126: step 1 — shared contracts (drift guard + workpiece env)
+
+Add guardTrackedOverwrite (json/yaml/text lost-key diff, warn-by-default, --strict fail-hard) and loadWorkpieceEnv (dotenv.parse wrapper) to werkstatt-shared kernel subpath; extend KernelRuntimeContext with optional workpieceEnv field.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { readFile } from "node:fs/promises";
+import { parse as yamlParse } from "yaml";
+
+export interface DriftReport {
+  file: string;
+  /** Keys/sections present on disk but absent or changed in the new content (dotted paths). */
+  wouldLose: string[];
+  /** True when on-disk content already equals new content — caller may skip the write. */
+  identical: boolean;
+}
+
+export interface DriftGuardOptions {
+  format: "json" | "yaml" | "text";
+  /** Fail-hard instead of warning. */
+  strict?: boolean;
+  /** Remediation hint appended to the warning/error message. */
+  fixHint?: string;
+}
+
+export interface DriftGuardLogger {
+  warn(msg: string): void;
+}
+
+const MAX_REPORTED_KEYS = 20;
+
+/** Collect dotted paths present in `oldValue` but absent or changed in `newValue`. */
+function collectLostKeys(
+  oldValue: unknown,
+  newValue: unknown,
+  prefix: string,
+  out: string[],
+): void {
+  if (out.length >= MAX_REPORTED_KEYS) return;
+  if (oldValue === null || typeof oldValue !== "object") {
+    if (oldValue !== newValue) out.push(prefix);
+    return;
+  }
+  if (Array.isArray(oldValue)) {
+    if (!Array.isArray(newValue)) {
+      out.push(prefix);
+      return;
+    }
+    for (let i = 0; i < oldValue.length; i++) {
+      if (i >= newValue.length) {
+        out.push(`${prefix}[${i}]`);
+      } else {
+        collectLostKeys(oldValue[i], newValue[i], `${prefix}[${i}]`, out);
+      }
+      if (out.length >= MAX_REPORTED_KEYS) return;
+    }
+    return;
+  }
+  const oldObj = oldValue as Record<string, unknown>;
+  const newObj =
+    newValue !== null && typeof newValue === "object" && !Array.isArray(newValue)
+      ? (newValue as Record<string, unknown>)
+      : {};
+  for (const key of Object.keys(oldObj)) {
+    const path = prefix ? `${prefix}.${key}` : key;
+    if (!(key in newObj)) {
+      out.push(path);
+    } else {
+      collectLostKeys(oldObj[key], newObj[key], path, out);
+    }
+    if (out.length >= MAX_REPORTED_KEYS) return;
+  }
+}
+
+function diffStructured(format: "json" | "yaml", existing: string, next: string): string[] {
+  try {
+    const oldValue: unknown = format === "json" ? JSON.parse(existing) : yamlParse(existing);
+    const newValue: unknown = format === "json" ? JSON.parse(next) : yamlParse(next);
+    const out: string[] = [];
+    collectLostKeys(oldValue, newValue, "", out);
+    return out;
+  } catch {
+    // Unparseable existing content — fall back to line diff so drift is still visible.
+    return diffText(existing, next);
+  }
+}
+
+function diffText(existing: string, next: string): string[] {
+  const nextLines = new Set(next.split("\n").map((l) => l.trim()));
+  const lost: string[] = [];
+  for (const line of existing.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed && !nextLines.has(trimmed)) {
+      lost.push(trimmed.length > 80 ? `${trimmed.slice(0, 77)}…` : trimmed);
+      if (lost.length >= MAX_REPORTED_KEYS) break;
+    }
+  }
+  return lost;
+}
+
+/**
+ * Compare newContent against the on-disk file before overwriting. Returns a
+ * DriftReport; warns via logger (or throws when options.strict) listing the
+ * keys that would be destroyed. Never throws for a missing file — nothing to
+ * lose. Callers should skip the write entirely when report.identical is true.
+ */
+export async function guardTrackedOverwrite(
+  filePath: string,
+  newContent: string,
+  options: DriftGuardOptions,
+  logger: DriftGuardLogger,
+): Promise<DriftReport> {
+  let existing: string | null = null;
+  try {
+    existing = await readFile(filePath, "utf-8");
+  } catch {
+    // File absent — nothing to lose.
+  }
+
+  if (existing === null) {
+    return { file: filePath, wouldLose: [], identical: false };
+  }
+  if (existing === newContent) {
+    return { file: filePath, wouldLose: [], identical: true };
+  }
+
+  const wouldLose =
+    options.format === "text"
+      ? diffText(existing, newContent)
+      : diffStructured(options.format, existing, newContent);
+
+  if (wouldLose.length === 0) {
+    return { file: filePath, wouldLose, identical: false };
+  }
+
+  const hint = options.fixHint ? ` ${options.fixHint}` : "";
+  const message =
+    `DRIFT-GUARD-01: ${filePath} — manual edits would be destroyed: ` +
+    `${wouldLose.join(", ")}.${hint}`;
+
+  if (options.strict) {
+    throw new Error(message);
+  }
+  logger.warn(message);
+  return { file: filePath, wouldLose, identical: false };
+}

package/src/kernel/fs-atomic.ts

@@ -0,0 +1,131 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+  RFC-0258: atomic file-write primitive for workspace-shared kernel-command
+  outputs. Every kernel command that writes a file outside its target app
+  directory (workspace root, docs/, packages/ontology/) MUST write through
+  writeFileAtomic instead of node:fs/promises writeFile, so that a reader
+  polling the target path never observes a torn/partial file when Turborepo
+  runs multiple app builds in parallel.
+</purpose>
+<non-goals>
+  <item>Do not provide cross-process mutual exclusion (locks) — outputs are deterministic (RFC-0087), so convergent atomic writes are sufficient.</item>
+  <item>Do not fall back to a non-atomic write when retries are exhausted — fail loudly instead.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<KEY_DECISIONS>
+  <item>Writes go through temp-file plus rename — readers never observe partial content.</item>
+  <item>Canonical implementation lives in @warpgogol/forge — this is a compatibility re-export.</item>
+</KEY_DECISIONS>
+<CHANGE_SUMMARY>
+  <item>RFC-0258: initial implementation.</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>
+</CHANGE_SUMMARY>
+*/
+
+import { writeFile, rename as fsRename, unlink } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { dirname, join, basename } from "node:path";
+import { randomBytes } from "node:crypto";
+
+export interface WriteFileAtomicOptions {
+  /** Max rename retries on transient EPERM/EBUSY. Default 10, linear 50ms backoff. */
+  retries?: number;
+}
+
+// Indirection seam so unit tests can simulate a transient EPERM/EBUSY
+// on the first rename attempt without monkey-patching the frozen node:fs/promises
+// module namespace (ESM named exports are read-only bindings). Production code
+// always goes through fsRename; only tests in this package call the setter.
+let renameImpl: typeof fsRename = fsRename;
+
+/** @internal test-only seam — do not call from production code. */
+export function __setRenameImplForTests(impl: typeof fsRename | undefined): void {
+  renameImpl = impl ?? fsRename;
+}
+
+const DEFAULT_RETRIES = 10;
+const RETRY_BACKOFF_MS = 50;
+
+const RETRYABLE_CODES = new Set(["EPERM", "EBUSY"]);
+
+function isRetryableError(error: unknown): boolean {
+  if (!error || typeof error !== "object") return false;
+  const code = (error as NodeJS.ErrnoException).code;
+  return typeof code === "string" && RETRYABLE_CODES.has(code);
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function makeTempPath(filePath: string): string {
+  const dir = dirname(filePath);
+  const name = basename(filePath);
+  const random = randomBytes(6).toString("hex");
+  return join(dir, `${name}.${random}.tmp`);
+}
+
+/**
+ * Write `content` to `filePath` atomically: write to a temp file in the same
+ * directory, then rename over the target. Rename within one directory is
+ * atomic on POSIX; a bounded retry loop absorbs transient EPERM/EBUSY
+ * (e.g. a reader briefly holding the file handle during overwrite).
+ *
+ * On failure (write or all rename retries exhausted), the temp file is
+ * unlinked in a finally block and the original error is rethrown — this
+ * helper never falls back to a non-atomic write.
+ */
+export async function writeFileAtomic(
+  filePath: string,
+  content: string | Uint8Array,
+  options?: WriteFileAtomicOptions,
+): Promise<void> {
+  const retries = options?.retries ?? DEFAULT_RETRIES;
+  const tempPath = makeTempPath(filePath);
+  let tempWritten = false;
+
+  try {
+    await writeFile(tempPath, content);
+    tempWritten = true;
+
+    let attempt = 0;
+    // Bounded retry loop: attempt 0 is the first try, then up to `retries` more.
+    for (;;) {
+      try {
+        await renameImpl(tempPath, filePath);
+        return;
+      } catch (error) {
+        if (attempt >= retries || !isRetryableError(error)) {
+          throw error;
+        }
+        attempt += 1;
+        // EPERM on rename-over-existing: try unlinking the target
+        // first (it may have been briefly locked by a reader that has since
+        // released it), then retry the rename on the next iteration.
+        if (existsSync(filePath)) {
+          try {
+            await unlink(filePath);
+          } catch {
+            // If unlink also fails, the retry loop will try again.
+          }
+        }
+        await sleep(RETRY_BACKOFF_MS * attempt);
+      }
+    }
+  } finally {
+    if (tempWritten) {
+      try {
+        // If rename succeeded, the temp file no longer exists — unlink is a no-op error we swallow.
+        await unlink(tempPath);
+      } catch {
+        // Expected in the success path (temp file already renamed away) — ignore.
+      }
+    }
+  }
+}

package/src/kernel/index.ts

@@ -0,0 +1,22 @@
+/*
+<MODULE_CONTRACT>
+  <purpose>Barrel export for @warpgogol/werkstatt-shared/kernel sub-path. Re-exports the kernel contract cluster (command/pipeline types, workspace IO, atomic fs, desired state, diagnostic schemas) sunk from @warpgogol/werkstatt-engine per RFC-1104.</purpose>
+  <non-goals>
+    <item>Does not re-export engine runtime modules (executor, module registry, CLI).</item>
+  </non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1104: initial barrel — kernel contract cluster sunk from werkstatt-engine.</item>
+  <item>RFC-1126: step 1 — shared contracts (drift guard + workpiece env)
+
+Add guardTrackedOverwrite (json/yaml/text lost-key diff, warn-by-default, --strict fail-hard) and loadWorkpieceEnv (dotenv.parse wrapper) to werkstatt-shared kernel subpath; extend KernelRuntimeContext with optional workpieceEnv field.</item>
+</CHANGE_SUMMARY>
+*/
+
+export * from "./types.ts";
+export * from "./workspace-io.ts";
+export * from "./fs-atomic.ts";
+export * from "./desired-state.ts";
+export * from "./diagnostic.ts";
+export * from "./drift-guard.ts";
+export * from "./workpiece-env.ts";