@warpgogol/werkstatt-shared 0.15.0 → 0.16.0

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/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/index.ts

@@ -1,10 +1,15 @@
 /*
 <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>Does not re-export engine runtime modules (executor, module registry, CLI).</non-goals>
+  <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>
 */
 
@@ -13,3 +18,5 @@ 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";

package/src/kernel/tests/drift-guard.test.ts

@@ -0,0 +1,112 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { guardTrackedOverwrite } from "../drift-guard.ts";
+
+describe("guardTrackedOverwrite (RFC-1126)", () => {
+  let dir: string;
+  const logger = { warn: vi.fn() };
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "drift-guard-"));
+    logger.warn.mockClear();
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("reports nothing to lose when the file does not exist", async () => {
+    const report = await guardTrackedOverwrite(
+      join(dir, "missing.json"),
+      "{}",
+      { format: "json" },
+      logger,
+    );
+    expect(report.wouldLose).toEqual([]);
+    expect(report.identical).toBe(false);
+    expect(logger.warn).not.toHaveBeenCalled();
+  });
+
+  it("reports identical when content matches", async () => {
+    const file = join(dir, "same.json");
+    writeFileSync(file, '{"a":1}\n');
+    const report = await guardTrackedOverwrite(file, '{"a":1}\n', { format: "json" }, logger);
+    expect(report.identical).toBe(true);
+    expect(logger.warn).not.toHaveBeenCalled();
+  });
+
+  it("warns with the lost key path for JSON drift", async () => {
+    const file = join(dir, "package.json");
+    writeFileSync(file, JSON.stringify({ dependencies: { "extra-dep": "^1.0.0" } }));
+    const report = await guardTrackedOverwrite(
+      file,
+      JSON.stringify({ dependencies: {} }),
+      { format: "json", fixHint: "edit the manifest" },
+      logger,
+    );
+    expect(report.wouldLose).toContain("dependencies.extra-dep");
+    expect(logger.warn).toHaveBeenCalledOnce();
+    expect(logger.warn.mock.calls[0]![0]).toContain("DRIFT-GUARD-01");
+    expect(logger.warn.mock.calls[0]![0]).toContain("dependencies.extra-dep");
+    expect(logger.warn.mock.calls[0]![0]).toContain("edit the manifest");
+  });
+
+  it("detects changed scalar values as lost edits", async () => {
+    const file = join(dir, "cfg.json");
+    writeFileSync(file, JSON.stringify({ version: "2.0.0" }));
+    const report = await guardTrackedOverwrite(
+      file,
+      JSON.stringify({ version: "1.0.0" }),
+      { format: "json" },
+      logger,
+    );
+    expect(report.wouldLose).toContain("version");
+  });
+
+  it("warns for YAML drift", async () => {
+    const file = join(dir, "config.yaml");
+    writeFileSync(file, "keep: yes\ndrop: gone\n");
+    const report = await guardTrackedOverwrite(file, "keep: yes\n", { format: "yaml" }, logger);
+    expect(report.wouldLose).toContain("drop");
+    expect(logger.warn).toHaveBeenCalledOnce();
+  });
+
+  it("warns for text drift listing removed lines", async () => {
+    const file = join(dir, "list.txt");
+    writeFileSync(file, "alpha\nbeta\ngamma\n");
+    const report = await guardTrackedOverwrite(file, "alpha\n", { format: "text" }, logger);
+    expect(report.wouldLose).toEqual(expect.arrayContaining(["beta", "gamma"]));
+  });
+
+  it("does not warn when new content only adds keys", async () => {
+    const file = join(dir, "grow.json");
+    writeFileSync(file, JSON.stringify({ a: 1 }));
+    const report = await guardTrackedOverwrite(
+      file,
+      JSON.stringify({ a: 1, b: 2 }),
+      { format: "json" },
+      logger,
+    );
+    expect(report.wouldLose).toEqual([]);
+    expect(report.identical).toBe(false);
+    expect(logger.warn).not.toHaveBeenCalled();
+  });
+
+  it("throws under strict instead of warning", async () => {
+    const file = join(dir, "strict.json");
+    writeFileSync(file, JSON.stringify({ manual: true }));
+    await expect(
+      guardTrackedOverwrite(file, "{}", { format: "json", strict: true }, logger),
+    ).rejects.toThrow("DRIFT-GUARD-01");
+    expect(logger.warn).not.toHaveBeenCalled();
+  });
+
+  it("falls back to line diff when existing JSON is unparseable", async () => {
+    const file = join(dir, "broken.json");
+    writeFileSync(file, "{ not json, custom-line\n");
+    const report = await guardTrackedOverwrite(file, "{}", { format: "json" }, logger);
+    expect(report.wouldLose.length).toBeGreaterThan(0);
+  });
+});

package/src/kernel/tests/workpiece-env.test.ts

@@ -0,0 +1,44 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { EMPTY_WORKPIECE_ENV, loadWorkpieceEnv } from "../workpiece-env.ts";
+
+describe("loadWorkpieceEnv (RFC-1126)", () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "workpiece-env-"));
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("returns the shared empty map when siteDirectory is undefined", async () => {
+    expect(await loadWorkpieceEnv(undefined)).toBe(EMPTY_WORKPIECE_ENV);
+  });
+
+  it("returns an empty map when .env is missing", async () => {
+    const env = await loadWorkpieceEnv(dir);
+    expect(env.size).toBe(0);
+  });
+
+  it("parses KEY=VALUE pairs including quoted values", async () => {
+    writeFileSync(
+      join(dir, ".env"),
+      'PUBLIC_IMAGE_PROVIDER=build-portable\nQUOTED="with space"\n# comment\n\n',
+    );
+    const env = await loadWorkpieceEnv(dir);
+    expect(env.get("PUBLIC_IMAGE_PROVIDER")).toBe("build-portable");
+    expect(env.get("QUOTED")).toBe("with space");
+    expect(env.has("# comment")).toBe(false);
+  });
+
+  it("does not mutate process.env", async () => {
+    writeFileSync(join(dir, ".env"), "WORKPIECE_ONLY_KEY=from-file\n");
+    delete process.env["WORKPIECE_ONLY_KEY"];
+    await loadWorkpieceEnv(dir);
+    expect(process.env["WORKPIECE_ONLY_KEY"]).toBeUndefined();
+  });
+});

package/src/kernel/types.ts

@@ -11,16 +11,23 @@
   <item>Kernel command contracts must stay explicit so agents cannot pass untyped command inputs.</item>
 </KEY_DECISIONS>
 <CHANGE_SUMMARY>
-  <item>RFC-1027: add RemediationHint interface and optional remediationHints field to KernelExecutionReport for agent-actionable fix suggestions.</item>
-  <item>RFC-1028: add moduleBasePath to KernelRegisteredCommandInfo, derived from modulePath (RFC-0960) for dynamic moduleSrcDir resolution in the pipeline executor.</item>
-  <item>RFC-1038: replace KernelModule with ModuleExport, KernelCommandDefinition with CommandDeclaration, KernelRuntimeContext.registry with actualState, KernelAppConfig uses ModuleExport.</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>
-  <history>RFC-0260, RFC-0267, RFC-0326, RFC-0390, RFC-0518, RFC-0579, RFC-0686, RFC-0960, RFC-1026</history>
+  <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>
+  <item>RFC-1130: qa.independent.run cacheable + cacheBypassFlags
+
+Steps 1-4: cacheBypassFlags field on KernelCommandDefinition, executor bypass at both cache call sites (hasCacheBypassFlag), qa.independent.run flipped to cacheable with narrowed reads + modulePaths, 14 new contract tests.</item>
+  <item>RFC-1133: cache direct executeKernelCommand executions with flag-keyed results</item>
+  <item>ADR-0089: kernel and shared code must not depend on ambient process state
+
+KernelRuntimeContext is the explicit-context carrier (workspaceRoot, site, workpieceEnv) — command handlers and shared code must not fall back to process.cwd() or process.env.NODE_ENV for correctness; callers pass roots and modes explicitly.</item>
+  <history>RFC-0260, RFC-0267, RFC-0326, RFC-0390, RFC-0518, RFC-0579, RFC-0686, RFC-0960, RFC-1026, RFC-1027, RFC-1028, RFC-1038</history>
 </CHANGE_SUMMARY>
 */
 
@@ -94,6 +101,12 @@ export interface KernelCommandMetadata {
    * command.reads.validate enforces this. Defaults to true.
    */
   cacheable?: boolean;
+  /**
+   * RFC-1130: flag names that bypass the result cache when present in argv
+   * (`--name` or `--name=value` forms). Both the cache read and the cache
+   * write are skipped — for flags that reduce coverage (e.g. `--rfc`).
+   */
+  cacheBypassFlags?: string[];
   /**
    * RFC-0518: declarative gate metadata. Optional. When present, describes the
    * gate's severity, phase, conditional logic, surfaces protected, rules enforced,
@@ -275,6 +288,52 @@ export interface KernelRuntimeContext {
    * plugin. Validators consume this instead of a static constant.
    */
   ownershipMap?: GeneratorOwnershipEntry[];
+  /**
+   * RFC-1126: parsed `.env` of the resolved site workspace (mission workpiece
+   * for mission.* commands, cache clone otherwise). Populated by the executor
+   * from `context.site.directory/.env` via dotenv.parse; absent or empty when
+   * no site is resolved or no .env exists. Fallback only — `process.env`
+   * always wins: `process.env["KEY"] ?? context.workpieceEnv?.get("KEY")`.
+   */
+  workpieceEnv?: ReadonlyMap<string, string>;
+  /**
+   * RFC-1133: per-invocation command-result cache carrier. Pipeline executors
+   * populate it with the shared layer plus `treeIndex`/`moduleHashCache`
+   * amortization; `executeKernelCommand` sets `{ layer }` once per invocation.
+   * When absent, `executeRegisteredCommand` lazily opens a layer for that call.
+   */
+  resultCache?: KernelResultCacheContext;
+}
+
+/**
+ * RFC-1133: narrow structural port over the engine's `CacheLayer`.
+ * werkstatt-shared cannot import engine types (SHARED-04), so the carrier is
+ * declared here and satisfied structurally — `CacheLayer` needs no explicit
+ * `implements`.
+ */
+export interface KernelResultCacheStore {
+  readonly available: boolean;
+  get(namespace: string, key: string): Promise<{ data: unknown } | null>;
+  set(
+    namespace: string,
+    key: string,
+    data: unknown,
+    mtime: number,
+    contentHash: string,
+  ): Promise<void>;
+  close(): Promise<void>;
+}
+
+/**
+ * RFC-1133: cache structures shared across one pipeline run or one direct
+ * `executeKernelCommand` invocation.
+ */
+export interface KernelResultCacheContext {
+  layer: KernelResultCacheStore;
+  /** Pipeline-only: workspace tree index enabling the mtime fast path (RFC-0685). */
+  treeIndex?: Map<string, { mtimeMs: number; size: number }>;
+  /** Pipeline-only: per-run module hash memo (RFC-0637). */
+  moduleHashCache?: Map<string, string>;
 }
 
 /**

package/src/kernel/workpiece-env.ts

@@ -0,0 +1,48 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-1126: lazy .env loader for the resolved site workspace. The kernel CLI loads
+dotenv from process.cwd() (the workshop root) only — a workpiece .env is invisible
+to pipeline commands unless each command implements its own fallback (the m000075
+readWorkpieceEnv pattern). This module generalizes that fallback once: the executor
+populates KernelRuntimeContext.workpieceEnv from <context.site.directory>/.env.
+</purpose>
+<non-goals>
+  <item>Does not override process.env — real environment always wins; this map is a fallback only.</item>
+  <item>Does not implement a general .env hierarchy (shell profiles, CI secrets) — only the resolved-site .env.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<KEY_DECISIONS>
+  <item>dotenv.parse is reused (already a kernel dependency) instead of a hand-rolled regex parser.</item>
+  <item>Node-only module (node:fs) — kernel-subpath export only, never re-exported from client-reachable barrels.</item>
+</KEY_DECISIONS>
+<CHANGE_SUMMARY>
+  <item>RFC-1126: initial implementation — loadWorkpieceEnv + EMPTY_WORKPIECE_ENV.</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 { join } from "node:path";
+import { parse as dotenvParse } from "dotenv";
+
+/** Shared empty map for contexts without a resolved site or .env file. */
+export const EMPTY_WORKPIECE_ENV: ReadonlyMap<string, string> = new Map();
+
+/**
+ * Parse `<siteDirectory>/.env` into a ReadonlyMap. Returns an empty map when
+ * the site is undefined or the file is missing/unreadable — never throws.
+ */
+export async function loadWorkpieceEnv(
+  siteDirectory: string | undefined,
+): Promise<ReadonlyMap<string, string>> {
+  if (!siteDirectory) return EMPTY_WORKPIECE_ENV;
+  try {
+    const raw = await readFile(join(siteDirectory, ".env"), "utf-8");
+    return new Map(Object.entries(dotenvParse(raw)));
+  } catch {
+    return EMPTY_WORKPIECE_ENV;
+  }
+}

package/src/middleware/access-protection.ts

@@ -9,6 +9,9 @@
   <item>Do not use Node.js-specific APIs (Buffer, crypto.timingSafeEqual) — runs in Cloudflare Workers runtime.</item>
 </non-goals>
 </MODULE_CONTRACT>
+<KEY_DECISIONS>
+  <item>PIN check runs in the Workers runtime — Web Crypto only, no Node APIs.</item>
+</KEY_DECISIONS>
 <CHANGE_SUMMARY>
   <item>RFC-0899: Initial access protection middleware for dev/alt subdomains.</item>
   <item>RFC-1097: step 6 — compass.migrate codemod run

package/src/middleware/language-redirect.ts

@@ -6,6 +6,9 @@
 </non-goals>
 <!-- @ai-invariant Generated factory output (RFC-0055) flows through system.md i18n config; do not hand-edit app copies. -->
 </MODULE_CONTRACT>
+<KEY_DECISIONS>
+  <item>Redirect target derives from system.md i18n config — no hardcoded locale list.</item>
+</KEY_DECISIONS>
 <CHANGE_SUMMARY>
   <item>RFC-0133: backfilled MODULE_MAP and CHANGE_SUMMARY markers for compass.validate compliance.</item>
 </CHANGE_SUMMARY>

package/src/observability/index.ts

@@ -50,6 +50,14 @@ export {
   type UnixNanoString,
 } from "./otlp-json.ts";
 
+export {
+  emitPipelineLogEvent,
+  getPipelineLogEvents,
+  type PipelineLogEvent,
+  type PipelineLogKind,
+  type PipelineLogSeverity,
+} from "./pipeline-log.ts";
+
 export { createMetricsPusher, type MetricsPusher, type MetricsPusherEnv } from "./pusher.ts";
 
 export { redactUrl } from "./redact.ts";