zob-harness 0.1.0

package/.pi/extensions/zob-harness/src/promotion/factory.ts

@@ -0,0 +1,107 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { sha256 } from "../utils/hashing.js";
+import { isRecord } from "../utils/records.js";
+import { advancePromotionCandidate, createPromotionCandidate, promotionCandidateDir, promotionCandidateRef, validatePromotionCandidate, writePromotionCandidate } from "./candidate.js";
+import type { PromotionCandidateRecord } from "./types.js";
+
+export interface FactoryPromotionInput {
+  candidateId?: string;
+  runId: string;
+  goalId?: string;
+  todoId?: string;
+  sourceRef: string;
+  factoryName: string;
+  manifest: Record<string, unknown>;
+}
+
+function safeFactoryName(value: string): boolean {
+  return /^[a-zA-Z0-9._-]+$/.test(value) && !value.includes("..") && value.length > 0;
+}
+
+function hasForbiddenRawKeys(value: unknown): boolean {
+  if (!value || typeof value !== "object") return false;
+  if (Array.isArray(value)) return value.some(hasForbiddenRawKeys);
+  return Object.entries(value as Record<string, unknown>).some(([key, child]) => ["body", "prompt", "output", "content", "message", "text", "rationale", "diff", "patch", "transcript"].includes(key) || hasForbiddenRawKeys(child));
+}
+
+export function prepareFactoryPromotion(repoRoot: string, input: FactoryPromotionInput): { candidate: PromotionCandidateRecord; manifestRef: string; validationRef: string } {
+  if (!safeFactoryName(input.factoryName)) throw new Error(`Unsafe factory name: ${input.factoryName}`);
+  if (hasForbiddenRawKeys(input.manifest)) throw new Error("factory promotion manifest metadata must be body-free/hash-only");
+  const candidate = createPromotionCandidate({
+    candidateId: input.candidateId,
+    kind: "factory",
+    runId: input.runId,
+    goalId: input.goalId,
+    todoId: input.todoId,
+    sourceRef: input.sourceRef,
+    allowedPaths: [`.pi/factories/${input.factoryName}`, `reports/factory-runs/${input.factoryName}`],
+    changedPaths: [`.pi/factories/${input.factoryName}/manifest.json`],
+    comsThreadRef: input.candidateId ? promotionCandidateRef(input.candidateId, "promotion-coms-thread.json") : undefined,
+    metadata: { lane: "factory", factoryName: input.factoryName },
+  });
+  const candidateDir = promotionCandidateDir(repoRoot, candidate.candidateId);
+  mkdirSync(join(candidateDir, "factory"), { recursive: true });
+  const manifestRecord = {
+    schema: "zob.factory-promotion-manifest-draft.v1",
+    candidateId: candidate.candidateId,
+    factoryName: input.factoryName,
+    manifestHash: sha256(JSON.stringify(input.manifest)),
+    manifestMetadata: input.manifest,
+    requiresSmoke: true,
+    requiresPilot: true,
+    requiresOracle: true,
+    requiresHumanApproval: true,
+    activationSentinelWritten: false,
+    bodyStored: false,
+    promptBodiesStored: false,
+    outputBodiesStored: false,
+  };
+  const manifestRef = promotionCandidateRef(candidate.candidateId, "factory/manifest-draft.json");
+  writeFileSync(join(repoRoot, manifestRef), JSON.stringify(manifestRecord, null, 2), "utf8");
+  const validationErrors = validateFactoryPromotionManifest(manifestRecord);
+  const validationRef = promotionCandidateRef(candidate.candidateId, "factory/validation.json");
+  writeFileSync(join(repoRoot, validationRef), JSON.stringify({ schema: "zob.factory-promotion-validation.v1", candidateId: candidate.candidateId, valid: validationErrors.length === 0, errors: validationErrors, bodyStored: false, promptBodiesStored: false, outputBodiesStored: false }, null, 2), "utf8");
+  const prepared = advancePromotionCandidate(repoRoot, { ...candidate, comsThreadRef: promotionCandidateRef(candidate.candidateId, "promotion-coms-thread.json") }, { toStatus: "prepared", preparedArtifactRef: manifestRef, validationRefs: validationErrors.length === 0 ? [validationRef] : [] });
+  writePromotionCandidate(repoRoot, prepared);
+  return { candidate: prepared, manifestRef, validationRef };
+}
+
+export function activateFactoryPromotionInQuarantine(repoRoot: string, candidate: PromotionCandidateRecord): { candidate: PromotionCandidateRecord; sentinelRef: string } {
+  if (candidate.kind !== "factory") throw new Error("candidate kind must be factory");
+  if (candidate.status !== "approved") throw new Error("factory activation requires approved candidate");
+  const preflightErrors = validateFactoryPromotionCandidate(repoRoot, candidate);
+  if (preflightErrors.length > 0) throw new Error(preflightErrors.join("; "));
+  const applied = advancePromotionCandidate(repoRoot, candidate, { toStatus: "applied", applyScope: "quarantine_test_directory", applyPerformed: true });
+  const sentinelRef = promotionCandidateRef(candidate.candidateId, "factory/ACTIVATED.sentinel");
+  writeFileSync(join(repoRoot, sentinelRef), `factory promotion activated in quarantine for ${candidate.candidateId}\n`, "utf8");
+  writePromotionCandidate(repoRoot, applied);
+  return { candidate: applied, sentinelRef };
+}
+
+export function validateFactoryPromotionManifest(artifact: unknown): string[] {
+  const errors: string[] = [];
+  if (!isRecord(artifact)) return ["factory promotion manifest must be an object"];
+  if (artifact.schema !== "zob.factory-promotion-manifest-draft.v1") errors.push("factory promotion manifest schema mismatch");
+  if (artifact.requiresSmoke !== true || artifact.requiresPilot !== true || artifact.requiresOracle !== true || artifact.requiresHumanApproval !== true) errors.push("factory promotion requires smoke, pilot, oracle, and human approval gates");
+  if (artifact.activationSentinelWritten !== false) errors.push("activation sentinel must not be written during preparation");
+  if (artifact.bodyStored !== false || artifact.promptBodiesStored !== false || artifact.outputBodiesStored !== false) errors.push("factory promotion manifest must keep body flags false");
+  if (hasForbiddenRawKeys(artifact)) errors.push("factory promotion manifest must not include raw body-like keys");
+  return errors;
+}
+
+export function validateFactoryPromotionCandidate(repoRoot: string, candidate: PromotionCandidateRecord): string[] {
+  const errors = validatePromotionCandidate(repoRoot, candidate);
+  if (candidate.kind !== "factory") errors.push("candidate kind must be factory");
+  if (candidate.productionWritesPerformed !== false || candidate.autoApply !== false) errors.push("factory candidate must not perform production writes or auto-apply");
+  if (["oracle_reviewed", "approved", "applied"].includes(candidate.status)) {
+    const smokeRef = candidate.validationRefs.find((ref) => ref.endsWith("/factory/smoke.json") || ref.endsWith("factory/smoke.json"));
+    const pilotRef = candidate.validationRefs.find((ref) => ref.endsWith("/factory/pilot.json") || ref.endsWith("factory/pilot.json"));
+    if (!smokeRef) errors.push("factory promotion requires persisted smoke ref before oracle/approval/apply");
+    else if (!existsSync(join(repoRoot, smokeRef))) errors.push(`factory smoke ref does not exist: ${smokeRef}`);
+    if (!pilotRef) errors.push("factory promotion requires persisted pilot ref before oracle/approval/apply");
+    else if (!existsSync(join(repoRoot, pilotRef))) errors.push(`factory pilot ref does not exist: ${pilotRef}`);
+  }
+  return errors;
+}

package/.pi/extensions/zob-harness/src/promotion/ledger.ts

@@ -0,0 +1,2 @@
+export { appendPromotionLedger, writePromotionCandidate } from "./candidate.js";
+export { writePromotionComsThread } from "./coms.js";

package/.pi/extensions/zob-harness/src/promotion/temp-agent.ts

@@ -0,0 +1,151 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { sha256 } from "../utils/hashing.js";
+import { safeFileStem } from "../utils/paths.js";
+import { parseJsonFile } from "../utils/json.js";
+import { isRecord } from "../utils/records.js";
+import { advancePromotionCandidate, createPromotionCandidate, promotionCandidateDir, promotionCandidateRef, validatePromotionCandidate, writePromotionCandidate } from "./candidate.js";
+import type { PromotionCandidateRecord } from "./types.js";
+
+export interface TempAgentCardPromotionInput {
+  candidateId?: string;
+  runId: string;
+  goalId?: string;
+  todoId?: string;
+  sourceRef: string;
+  agentName: string;
+  description: string;
+  allowedTools: string[];
+  outputContract: string;
+  scope: string;
+  mustDo: string[];
+  mustNotDo: string[];
+  writeToolsGate?: boolean;
+}
+
+const KNOWN_TOOLS = new Set(["read", "grep", "find", "ls", "bash", "edit", "write", "delegate_agent", "delegate_task", "zob_coms_send", "zob_goal_room_send", "zob_governed_request_extract"]);
+const WRITE_TOOLS = new Set(["bash", "edit", "write"]);
+
+export function validateTempAgentCardForPromotion(repoRoot: string, input: TempAgentCardPromotionInput): string[] {
+  const errors: string[] = [];
+  if (safeFileStem(input.agentName) !== input.agentName) errors.push("temp agent name must be path-safe and equal to its safe stem");
+  if (!input.description || input.description.trim().length < 10) errors.push("temp agent description is required");
+  if (!Array.isArray(input.allowedTools) || input.allowedTools.length === 0) errors.push("temp agent allowedTools are required");
+  for (const tool of input.allowedTools ?? []) {
+    if (!KNOWN_TOOLS.has(tool)) errors.push(`unknown temp agent tool: ${tool}`);
+    if (WRITE_TOOLS.has(tool) && input.writeToolsGate !== true) errors.push(`write-capable tool requires explicit writeToolsGate: ${tool}`);
+  }
+  if (!/^[a-z0-9._-]+\.v\d+$/i.test(input.outputContract)) errors.push("outputContract must be a safe contract id like name.v1");
+  if (!existsSync(join(repoRoot, ".pi", "output-contracts", `${input.outputContract}.json`))) errors.push(`output contract not found: ${input.outputContract}`);
+  if (!input.scope || input.scope.trim().length === 0) errors.push("temp agent scope is required");
+  if (!Array.isArray(input.mustDo) || input.mustDo.length === 0) errors.push("mustDo is required");
+  if (!Array.isArray(input.mustNotDo) || input.mustNotDo.length === 0) errors.push("mustNotDo is required");
+  return errors;
+}
+
+function renderAgentDraft(input: TempAgentCardPromotionInput): string {
+  return [
+    `# ${input.agentName}`,
+    "",
+    input.description,
+    "",
+    "## Scope",
+    input.scope,
+    "",
+    "## Tools",
+    input.allowedTools.map((tool) => `- ${tool}`).join("\n"),
+    "",
+    "## Output contract",
+    input.outputContract,
+    "",
+    "## MUST DO",
+    input.mustDo.map((item) => `- ${item}`).join("\n"),
+    "",
+    "## MUST NOT",
+    input.mustNotDo.map((item) => `- ${item}`).join("\n"),
+    "",
+    "## Persistence policy",
+    "This draft is quarantined until promotion approval, smoke validation, and oracle PASS/no_ship=false.",
+  ].join("\n");
+}
+
+export function prepareTempAgentPromotion(repoRoot: string, input: TempAgentCardPromotionInput): { candidate: PromotionCandidateRecord; preparedArtifactRef: string; draftRef: string; validationRef: string } {
+  const cardErrors = validateTempAgentCardForPromotion(repoRoot, input);
+  if (cardErrors.length > 0) throw new Error(cardErrors.join("; "));
+  const candidate = createPromotionCandidate({
+    candidateId: input.candidateId,
+    kind: "temp_agent",
+    runId: input.runId,
+    goalId: input.goalId,
+    todoId: input.todoId,
+    sourceRef: input.sourceRef,
+    allowedPaths: [".pi/agents"],
+    changedPaths: [`.pi/agents/${input.agentName}.md`],
+    comsThreadRef: input.candidateId ? promotionCandidateRef(input.candidateId, "promotion-coms-thread.json") : undefined,
+    metadata: { lane: "temp_agent", agentName: input.agentName, outputContract: input.outputContract },
+  });
+  const candidateDir = promotionCandidateDir(repoRoot, candidate.candidateId);
+  const draftText = renderAgentDraft(input);
+  const draftRef = promotionCandidateRef(candidate.candidateId, `agents/${input.agentName}.md`);
+  mkdirSync(join(candidateDir, "agents"), { recursive: true });
+  writeFileSync(join(repoRoot, draftRef), draftText, "utf8");
+  const preparedArtifact = {
+    schema: "zob.temp-agent-promotion-prepared.v1",
+    candidateId: candidate.candidateId,
+    agentName: input.agentName,
+    draftRef,
+    draftHash: sha256(draftText),
+    allowedTools: input.allowedTools,
+    outputContract: input.outputContract,
+    durableAgentWritePerformed: false,
+    catalogSmokeRequired: true,
+    bodyStored: false,
+    promptBodiesStored: false,
+    outputBodiesStored: false,
+  };
+  const preparedArtifactRef = promotionCandidateRef(candidate.candidateId, "temp-agent/prepared.json");
+  mkdirSync(join(candidateDir, "temp-agent"), { recursive: true });
+  writeFileSync(join(repoRoot, preparedArtifactRef), JSON.stringify(preparedArtifact, null, 2), "utf8");
+  const validationErrors = validateTempAgentPromotionArtifact(preparedArtifact);
+  const validationRef = promotionCandidateRef(candidate.candidateId, "temp-agent/validation.json");
+  writeFileSync(join(repoRoot, validationRef), JSON.stringify({ schema: "zob.temp-agent-promotion-validation.v1", candidateId: candidate.candidateId, valid: validationErrors.length === 0, errors: validationErrors, bodyStored: false, promptBodiesStored: false, outputBodiesStored: false }, null, 2), "utf8");
+  const prepared = advancePromotionCandidate(repoRoot, { ...candidate, comsThreadRef: promotionCandidateRef(candidate.candidateId, "promotion-coms-thread.json") }, { toStatus: "prepared", preparedArtifactRef, validationRefs: validationErrors.length === 0 ? [validationRef] : [] });
+  writePromotionCandidate(repoRoot, prepared);
+  return { candidate: prepared, preparedArtifactRef, draftRef, validationRef };
+}
+
+export function validateTempAgentPromotionArtifact(artifact: unknown): string[] {
+  const errors: string[] = [];
+  if (!isRecord(artifact)) return ["temp-agent promotion artifact must be an object"];
+  if (artifact.schema !== "zob.temp-agent-promotion-prepared.v1") errors.push("temp-agent promotion artifact schema mismatch");
+  if (typeof artifact.agentName !== "string" || safeFileStem(artifact.agentName) !== artifact.agentName) errors.push("agentName must be safe");
+  if (artifact.durableAgentWritePerformed !== false) errors.push("temp-agent promotion must not perform durable agent write during preparation");
+  if (artifact.bodyStored !== false || artifact.promptBodiesStored !== false || artifact.outputBodiesStored !== false) errors.push("temp-agent promotion artifact must keep body flags false");
+  if (!Array.isArray(artifact.allowedTools) || artifact.allowedTools.some((tool) => typeof tool !== "string")) errors.push("allowedTools must be string array");
+  return errors;
+}
+
+export function applyTempAgentPromotionInQuarantine(repoRoot: string, candidate: PromotionCandidateRecord): { candidate: PromotionCandidateRecord; appliedAgentRef: string; appliedMetadataRef: string } {
+  if (candidate.kind !== "temp_agent") throw new Error("candidate kind must be temp_agent");
+  if (candidate.status !== "approved") throw new Error("temp-agent quarantine apply requires approved candidate");
+  if (!candidate.preparedArtifactRef) throw new Error("temp-agent quarantine apply requires preparedArtifactRef");
+  const prepared = parseJsonFile(join(repoRoot, candidate.preparedArtifactRef));
+  if (!isRecord(prepared) || typeof prepared.agentName !== "string" || typeof prepared.draftRef !== "string") throw new Error("temp-agent prepared artifact missing agentName/draftRef");
+  const draftText = readFileSync(join(repoRoot, prepared.draftRef), "utf8");
+  const appliedAgentRef = promotionCandidateRef(candidate.candidateId, `temp-agent/applied-test-workspace/.pi/agents/${safeFileStem(prepared.agentName)}.md`);
+  mkdirSync(join(repoRoot, promotionCandidateRef(candidate.candidateId, "temp-agent/applied-test-workspace/.pi/agents")), { recursive: true });
+  writeFileSync(join(repoRoot, appliedAgentRef), draftText, "utf8");
+  const appliedMetadataRef = promotionCandidateRef(candidate.candidateId, "temp-agent/applied-test-workspace/apply-metadata.json");
+  writeFileSync(join(repoRoot, appliedMetadataRef), JSON.stringify({ schema: "zob.temp-agent-quarantine-apply.v1", candidateId: candidate.candidateId, appliedAgentRef, productionWritesPerformed: false, autoApply: false, bodyStored: false, promptBodiesStored: false, outputBodiesStored: false }, null, 2), "utf8");
+  const applied = advancePromotionCandidate(repoRoot, candidate, { toStatus: "applied", applyScope: "quarantine_test_directory", applyPerformed: true });
+  writePromotionCandidate(repoRoot, applied);
+  return { candidate: applied, appliedAgentRef, appliedMetadataRef };
+}
+
+export function validateTempAgentPromotionCandidate(repoRoot: string, candidate: PromotionCandidateRecord): string[] {
+  const errors = validatePromotionCandidate(repoRoot, candidate);
+  if (candidate.kind !== "temp_agent") errors.push("candidate kind must be temp_agent");
+  if (candidate.productionWritesPerformed !== false || candidate.autoApply !== false) errors.push("temp-agent candidate must not auto-apply production writes");
+  return errors;
+}

package/.pi/extensions/zob-harness/src/promotion/types.ts

@@ -0,0 +1,149 @@
+export const PROMOTION_KINDS = ["documentation_writeback", "temp_agent", "factory", "write_lane"] as const;
+export type PromotionKind = typeof PROMOTION_KINDS[number];
+
+export const PROMOTION_STATUSES = ["proposal", "prepared", "validated", "oracle_reviewed", "approved", "applied", "rejected", "blocked"] as const;
+export type PromotionStatus = typeof PROMOTION_STATUSES[number];
+
+export const PROMOTION_APPLY_SCOPES = ["none", "manual_apply_only", "quarantine_test_directory"] as const;
+export type PromotionApplyScope = typeof PROMOTION_APPLY_SCOPES[number];
+
+export interface PromotionGates {
+  comsThreadRequired: boolean;
+  sandboxRequired: boolean;
+  validationRequired: boolean;
+  oracleRequired: boolean;
+  humanApprovalRequired: boolean;
+  rollbackRequired: boolean;
+}
+
+export interface PromotionCandidateInput {
+  candidateId?: string;
+  kind: PromotionKind;
+  runId: string;
+  goalId?: string;
+  todoId?: string;
+  sourceRef: string;
+  sourceHash?: string;
+  comsThreadRef?: string;
+  goalRoomMessageRefs?: string[];
+  preparedArtifactRef?: string | null;
+  validationRefs?: string[];
+  oracleReviewRef?: string | null;
+  oracleVerdict?: "PASS" | "WARN" | "FAIL" | null;
+  oracleNoShip?: boolean | null;
+  approvalRef?: string | null;
+  rollbackRef?: string | null;
+  changedPaths?: string[];
+  allowedPaths?: string[];
+  forbiddenPaths?: string[];
+  gates?: Partial<PromotionGates>;
+  applyScope?: PromotionApplyScope;
+  metadata?: Record<string, unknown>;
+}
+
+export interface PromotionCandidateRecord {
+  schema: "zob.promotion-candidate.v1";
+  candidateId: string;
+  kind: PromotionKind;
+  runId: string;
+  goalId: string | null;
+  todoId: string | null;
+  status: PromotionStatus;
+  sourceRef: string;
+  sourceHash: string | null;
+  preparedArtifactRef: string | null;
+  validationRefs: string[];
+  oracleReviewRef: string | null;
+  oracleVerdict: "PASS" | "WARN" | "FAIL" | null;
+  oracleNoShip: boolean | null;
+  approvalRef: string | null;
+  rollbackRef: string | null;
+  comsThreadRef: string | null;
+  goalRoomMessageRefs: string[];
+  changedPaths: string[];
+  changedPathHashes: string[];
+  allowedPaths: string[];
+  forbiddenPaths: string[];
+  gates: PromotionGates;
+  applyScope: PromotionApplyScope;
+  applyPerformed: boolean;
+  productionWritesPerformed: false;
+  autoApply: false;
+  parentOwned: true;
+  bodyStored: false;
+  promptBodiesStored: false;
+  outputBodiesStored: false;
+  metadata: Record<string, unknown>;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface PromotionTransitionInput {
+  toStatus: PromotionStatus;
+  preparedArtifactRef?: string;
+  validationRefs?: string[];
+  oracleReviewRef?: string;
+  oracleVerdict?: "PASS" | "WARN" | "FAIL";
+  oracleNoShip?: boolean;
+  approvalRef?: string;
+  rollbackRef?: string;
+  goalRoomMessageRefs?: string[];
+  applyScope?: PromotionApplyScope;
+  applyPerformed?: boolean;
+  metadata?: Record<string, unknown>;
+}
+
+export interface PromotionComsMessageRef {
+  msgId: string;
+  kind: "STATUS_UPDATE" | "FINDING" | "RISK" | "BLOCKER" | "NO_SHIP_ALERT" | "CONTEXT_REQUEST" | "DELEGATION_REQUEST" | "ORACLE_REQUEST" | "QUESTION" | "ANSWER";
+  sender: string;
+  status: "queued" | "acked" | "running" | "completed" | "blocked" | "timeout" | "stale" | "offline";
+  bodyHash: string;
+  outputHash?: string | null;
+  artifactRefs: string[];
+  evidenceRefs: string[];
+  requiresParentAction: boolean;
+  countsAsCompletion: boolean;
+  parentVisible: true;
+  hiddenPeerChat: false;
+  workerToWorkerDirect: false;
+  bodyStored: false;
+  promptBodiesStored: false;
+  outputBodiesStored: false;
+}
+
+export interface PromotionComsThreadInput {
+  threadId?: string;
+  goalId: string;
+  todoId?: string;
+  candidateId: string;
+  kind: PromotionKind;
+  messageRefs?: PromotionComsMessageRef[];
+  requiredAcks?: string[];
+  stalePolicy?: "stale_blocks_completion";
+}
+
+export interface PromotionComsThreadRecord {
+  schema: "zob.promotion-coms-thread.v1";
+  threadId: string;
+  goalId: string;
+  todoId: string | null;
+  candidateId: string;
+  kind: PromotionKind;
+  messageRefs: PromotionComsMessageRef[];
+  requiredAcks: string[];
+  stalePolicy: "stale_blocks_completion";
+  parentVisible: true;
+  parentOwnedActions: true;
+  hiddenPeerChat: false;
+  bodyStored: false;
+  promptBodiesStored: false;
+  outputBodiesStored: false;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface PromotionValidationResult {
+  valid: boolean;
+  errors: string[];
+}

package/.pi/extensions/zob-harness/src/promotion/validate.ts

@@ -0,0 +1,6 @@
+export { validatePromotionCandidate, transitionAllowed } from "./candidate.js";
+export { validatePromotionComsMessageRef, validatePromotionComsReadiness, validatePromotionComsThread } from "./coms.js";
+export { validateDocumentationPromotion, validateDocumentationPromotionCandidate } from "./documentation.js";
+export { validateFactoryPromotionCandidate, validateFactoryPromotionManifest } from "./factory.js";
+export { validateTempAgentCardForPromotion, validateTempAgentPromotionArtifact, validateTempAgentPromotionCandidate } from "./temp-agent.js";
+export { validateWriteLaneDiffMetadata, validateWriteLanePromotionCandidate } from "./write-lane.js";

package/.pi/extensions/zob-harness/src/promotion/write-lane.ts

@@ -0,0 +1,162 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+import { sha256 } from "../utils/hashing.js";
+import { safeFileStem } from "../utils/paths.js";
+import { isRecord } from "../utils/records.js";
+import { advancePromotionCandidate, createPromotionCandidate, promotionCandidateDir, promotionCandidateRef, validatePromotionCandidate, writePromotionCandidate } from "./candidate.js";
+import type { PromotionCandidateRecord } from "./types.js";
+
+export interface WriteLaneChangeInput {
+  path: string;
+  draftText: string;
+}
+
+export interface PrepareWriteLanePromotionInput {
+  candidateId?: string;
+  runId: string;
+  goalId?: string;
+  todoId?: string;
+  sourceRef: string;
+  allowedPaths: string[];
+  forbiddenPaths?: string[];
+  changes: WriteLaneChangeInput[];
+}
+
+function validateLogicalPath(path: string): string[] {
+  const errors: string[] = [];
+  if (typeof path !== "string" || path.trim().length === 0) return ["path must be non-empty"];
+  if (path.startsWith("/") || path.includes("..") || path.includes("\\") || path.includes("\0")) errors.push(`path must be safe relative: ${path}`);
+  if (/(^|\/)\.env($|[./])|(^|\/)(\.ssh|\.aws)(\/|$)|secret|credential|\.pem$|\.p12$|\.pfx$/i.test(path)) errors.push(`path must not reference secrets: ${path}`);
+  return errors;
+}
+
+function insideAnyLogical(child: string, parents: string[]): boolean {
+  const c = child.replace(/\/+$/g, "");
+  return parents.some((parent) => {
+    const p = parent.replace(/\/+$/g, "");
+    return c === p || c.startsWith(`${p}/`);
+  });
+}
+
+function pathMatchesForbidden(path: string, forbiddenPaths: string[]): boolean {
+  return forbiddenPaths.some((forbidden) => path === forbidden || path.startsWith(`${forbidden.replace(/\/+$/g, "")}/`) || new RegExp(forbidden.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*")).test(path));
+}
+
+export function prepareWriteLanePromotion(repoRoot: string, input: PrepareWriteLanePromotionInput): { candidate: PromotionCandidateRecord; sandboxRootRef: string; diffMetadataRef: string; rollbackRef: string; validationRef: string } {
+  if (!Array.isArray(input.allowedPaths) || input.allowedPaths.length === 0) throw new Error("write lane requires explicit allowedPaths");
+  const pathErrors = [
+    ...input.allowedPaths.flatMap(validateLogicalPath),
+    ...(input.forbiddenPaths ?? []).flatMap(validateLogicalPath),
+    ...input.changes.flatMap((change) => validateLogicalPath(change.path)),
+  ];
+  for (const change of input.changes) {
+    if (!insideAnyLogical(change.path, input.allowedPaths)) pathErrors.push(`write lane change outside allowedPaths: ${change.path}`);
+    if (pathMatchesForbidden(change.path, input.forbiddenPaths ?? [])) pathErrors.push(`write lane change matches forbiddenPaths: ${change.path}`);
+  }
+  if (pathErrors.length > 0) throw new Error(pathErrors.join("; "));
+  const preliminary = createPromotionCandidate({
+    candidateId: input.candidateId,
+    kind: "write_lane",
+    runId: input.runId,
+    goalId: input.goalId,
+    todoId: input.todoId,
+    sourceRef: input.sourceRef,
+    comsThreadRef: input.candidateId ? promotionCandidateRef(input.candidateId, "promotion-coms-thread.json") : undefined,
+    metadata: { lane: "write_lane", logicalAllowedPaths: input.allowedPaths, logicalForbiddenPaths: input.forbiddenPaths ?? [] },
+  });
+  const sandboxRootRef = promotionCandidateRef(preliminary.candidateId, "write-lane/sandbox");
+  const sandboxRoot = join(repoRoot, sandboxRootRef);
+  const changedPaths: string[] = [];
+  const fileRecords = input.changes.map((change) => {
+    const safeParts = change.path.split("/").map((part) => safeFileStem(part));
+    const relativeSandboxPath = safeParts.join("/");
+    const targetRef = `${sandboxRootRef}/${relativeSandboxPath}`;
+    const targetPath = join(repoRoot, targetRef);
+    const resolvedTarget = resolve(targetPath);
+    const resolvedSandbox = resolve(sandboxRoot);
+    if (resolvedTarget !== resolvedSandbox && !resolvedTarget.startsWith(`${resolvedSandbox}/`)) throw new Error(`sandbox write escaped sandbox root: ${change.path}`);
+    mkdirSync(dirname(targetPath), { recursive: true });
+    writeFileSync(targetPath, change.draftText, "utf8");
+    changedPaths.push(targetRef);
+    return {
+      logicalPath: change.path,
+      sandboxRef: targetRef,
+      contentHash: sha256(change.draftText),
+      bodyStored: false,
+    };
+  });
+  const diffHash = sha256(JSON.stringify(fileRecords.map((record) => [record.logicalPath, record.sandboxRef, record.contentHash])));
+  const diffMetadata = {
+    schema: "zob.write-lane-diff-metadata.v1",
+    candidateId: preliminary.candidateId,
+    sandboxRootRef,
+    changedPaths,
+    fileRecords,
+    diffHash,
+    productionWritesPerformed: false,
+    autoApply: false,
+    bodyStored: false,
+    promptBodiesStored: false,
+    outputBodiesStored: false,
+  };
+  const rollback = {
+    schema: "zob.write-lane-rollback-metadata.v1",
+    candidateId: preliminary.candidateId,
+    rollbackStrategy: "delete_quarantine_test_workspace_or_discard_merge_candidate",
+    sandboxRootRef,
+    rollbackHash: sha256(JSON.stringify({ sandboxRootRef, changedPaths, diffHash })),
+    productionWritesPerformed: false,
+    bodyStored: false,
+    promptBodiesStored: false,
+    outputBodiesStored: false,
+  };
+  const candidateDir = promotionCandidateDir(repoRoot, preliminary.candidateId);
+  mkdirSync(join(candidateDir, "write-lane"), { recursive: true });
+  const diffMetadataRef = promotionCandidateRef(preliminary.candidateId, "write-lane/diff-metadata.json");
+  const rollbackRef = promotionCandidateRef(preliminary.candidateId, "write-lane/rollback.json");
+  writeFileSync(join(repoRoot, diffMetadataRef), JSON.stringify(diffMetadata, null, 2), "utf8");
+  writeFileSync(join(repoRoot, rollbackRef), JSON.stringify(rollback, null, 2), "utf8");
+  const validationErrors = validateWriteLaneDiffMetadata(diffMetadata);
+  const validationRef = promotionCandidateRef(preliminary.candidateId, "write-lane/validation.json");
+  writeFileSync(join(repoRoot, validationRef), JSON.stringify({ schema: "zob.write-lane-validation.v1", candidateId: preliminary.candidateId, valid: validationErrors.length === 0, errors: validationErrors, bodyStored: false, promptBodiesStored: false, outputBodiesStored: false }, null, 2), "utf8");
+  const candidate: PromotionCandidateRecord = {
+    ...preliminary,
+    changedPaths: changedPaths.sort(),
+    changedPathHashes: changedPaths.sort().map((path) => sha256(path)),
+    allowedPaths: [sandboxRootRef],
+    forbiddenPaths: [],
+    comsThreadRef: promotionCandidateRef(preliminary.candidateId, "promotion-coms-thread.json"),
+    metadata: { ...preliminary.metadata, diffHash, sandboxRootRef, logicalAllowedPaths: input.allowedPaths, logicalForbiddenPaths: input.forbiddenPaths ?? [] },
+  };
+  const prepared = advancePromotionCandidate(repoRoot, candidate, { toStatus: "prepared", preparedArtifactRef: diffMetadataRef, validationRefs: validationErrors.length === 0 ? [validationRef] : [], rollbackRef });
+  writePromotionCandidate(repoRoot, prepared);
+  return { candidate: prepared, sandboxRootRef, diffMetadataRef, rollbackRef, validationRef };
+}
+
+export function validateWriteLaneDiffMetadata(artifact: unknown): string[] {
+  const errors: string[] = [];
+  if (!isRecord(artifact)) return ["write-lane diff metadata must be an object"];
+  if (artifact.schema !== "zob.write-lane-diff-metadata.v1") errors.push("write-lane diff metadata schema mismatch");
+  if (!Array.isArray(artifact.changedPaths) || artifact.changedPaths.length === 0) errors.push("write lane requires changedPaths");
+  if (typeof artifact.diffHash !== "string" || !/^[a-f0-9]{64}$/i.test(artifact.diffHash)) errors.push("write lane requires diffHash");
+  if (artifact.productionWritesPerformed !== false || artifact.autoApply !== false) errors.push("write lane preparation must not perform production writes or auto-apply");
+  if (artifact.bodyStored !== false || artifact.promptBodiesStored !== false || artifact.outputBodiesStored !== false) errors.push("write-lane diff metadata must keep body flags false");
+  return errors;
+}
+
+export function markWriteLaneAppliedInQuarantine(repoRoot: string, candidate: PromotionCandidateRecord): PromotionCandidateRecord {
+  if (candidate.kind !== "write_lane") throw new Error("candidate kind must be write_lane");
+  if (candidate.status !== "approved") throw new Error("write lane quarantine apply requires approved candidate");
+  const applied = advancePromotionCandidate(repoRoot, candidate, { toStatus: "applied", applyScope: "quarantine_test_directory", applyPerformed: true });
+  writePromotionCandidate(repoRoot, applied);
+  return applied;
+}
+
+export function validateWriteLanePromotionCandidate(repoRoot: string, candidate: PromotionCandidateRecord): string[] {
+  const errors = validatePromotionCandidate(repoRoot, candidate);
+  if (candidate.kind !== "write_lane") errors.push("candidate kind must be write_lane");
+  if (candidate.productionWritesPerformed !== false || candidate.autoApply !== false) errors.push("write lane candidate must not perform production writes or auto-apply");
+  if (!String(candidate.metadata?.sandboxRootRef ?? "").startsWith(`reports/promotions/${candidate.candidateId}/write-lane/sandbox`)) errors.push("write lane sandboxRootRef must stay inside candidate promotion workspace");
+  return errors;
+}