odai-dsh-agent 0.2.1 → 0.2.3

package/preset/odai/runtime/research-packet.mjs

@@ -1,150 +1,150 @@
-import { createHash } from "node:crypto";
-import { readFileSync, realpathSync, statSync } from "node:fs";
-import { isAbsolute, relative, resolve, sep } from "node:path";
-
-const PACKET_FIELDS = new Set(["schemaVersion", "question", "facts", "conflicts", "unknowns", "stop"]);
-const FACT_FIELDS = new Set(["claim", "excerpt", "source", "authority"]);
-const SOURCE_FIELDS = new Set(["path", "line"]);
-const DEFAULT_MAX_CHARS = 8_000;
-const DEFAULT_MAX_FACTS = 12;
-const DEFAULT_MAX_ITEMS = 8;
-
-function plainObject(value, field) {
-  if (value === null || typeof value !== "object" || Array.isArray(value)) {
-    throw new TypeError(`${field} must be an object`);
-  }
-  return value;
-}
-
-function exactFields(value, allowed, field) {
-  const unknown = Object.keys(value).filter((key) => !allowed.has(key));
-  if (unknown.length > 0) throw new TypeError(`${field} has unknown fields: ${unknown.join(", ")}`);
-}
-
-function text(value, field, maxChars = 1_500) {
-  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${field} must be a non-empty string`);
-  const normalized = value.trim();
-  if (normalized.length > maxChars) throw new TypeError(`${field} exceeds ${maxChars} characters`);
-  return normalized;
-}
-
-function stringList(value, field, maxItems) {
-  if (!Array.isArray(value) || value.length > maxItems) {
-    throw new TypeError(`${field} must be an array with at most ${maxItems} items`);
-  }
-  return Object.freeze(value.map((item, index) => text(item, `${field}[${index}]`, 800)));
-}
-
-function sourcePointer(value, field) {
-  const source = plainObject(value, field);
-  exactFields(source, SOURCE_FIELDS, field);
-  const path = text(source.path, `${field}.path`, 500);
-  if (path.startsWith("/") || path.startsWith("~") || path.split(/[\\/]/u).includes("..")) {
-    throw new TypeError(`${field}.path must be repository-relative and may not traverse parent directories`);
-  }
-  if (!Number.isSafeInteger(source.line) || source.line <= 0) {
-    throw new TypeError(`${field}.line must be a positive integer`);
-  }
-  return Object.freeze({ path, line: source.line });
-}
-
-function parseJsonText(output) {
-  const trimmed = String(output ?? "").trim();
-  const fenced = /^```(?:json)?\s*\n([\s\S]*?)\n```$/iu.exec(trimmed);
-  return JSON.parse(fenced ? fenced[1] : trimmed);
-}
-
-export function parseResearchPacket(output, options = {}) {
-  const maxChars = Number.isSafeInteger(options.maxChars) && options.maxChars > 0
-    ? options.maxChars
-    : DEFAULT_MAX_CHARS;
-  const raw = String(output ?? "");
-  if (raw.length > maxChars) throw new TypeError(`research packet exceeds ${maxChars} characters`);
-  const packet = plainObject(parseJsonText(raw), "research packet");
-  exactFields(packet, PACKET_FIELDS, "research packet");
-  if (packet.schemaVersion !== 1) throw new TypeError("research packet.schemaVersion must be 1");
-  if (!Array.isArray(packet.facts) || packet.facts.length < 2 || packet.facts.length > DEFAULT_MAX_FACTS) {
-    throw new TypeError(`research packet.facts must contain 2-${DEFAULT_MAX_FACTS} source-backed facts`);
-  }
-  const facts = Object.freeze(packet.facts.map((value, index) => {
-    const fact = plainObject(value, `research packet.facts[${index}]`);
-    exactFields(fact, FACT_FIELDS, `research packet.facts[${index}]`);
-    return Object.freeze({
-      claim: text(fact.claim, `research packet.facts[${index}].claim`, 1_200),
-      excerpt: text(fact.excerpt, `research packet.facts[${index}].excerpt`, 1_200),
-      source: sourcePointer(fact.source, `research packet.facts[${index}].source`),
-      authority: text(fact.authority, `research packet.facts[${index}].authority`, 500),
-    });
-  }));
-  if (new Set(facts.map((fact) => fact.source.path)).size < 2) {
-    throw new TypeError("research packet must cite at least two distinct source paths");
-  }
-  const normalized = Object.freeze({
-    schemaVersion: 1,
-    question: text(packet.question, "research packet.question", 1_200),
-    facts,
-    conflicts: stringList(packet.conflicts, "research packet.conflicts", DEFAULT_MAX_ITEMS),
-    unknowns: stringList(packet.unknowns, "research packet.unknowns", DEFAULT_MAX_ITEMS),
-    stop: text(packet.stop, "research packet.stop", 1_000),
-  });
-  const digest = createHash("sha256").update(JSON.stringify(normalized)).digest("hex");
-  return Object.freeze({
-    ...normalized,
-    digest,
-    sourceCount: new Set(facts.map((fact) => fact.source.path)).size,
-  });
-}
-
-function isInside(root, candidate) {
-  const fromRoot = relative(root, candidate);
-  return fromRoot === "" || (!fromRoot.startsWith(`..${sep}`) && fromRoot !== ".." && !isAbsolute(fromRoot));
-}
-
-export function verifyResearchPacketSources(packet, projectRoot) {
-  if (typeof projectRoot !== "string" || projectRoot.trim() === "") {
-    throw new TypeError("research packet verification requires the controller project root");
-  }
-  const root = realpathSync(resolve(projectRoot));
-  for (const [index, fact] of packet.facts.entries()) {
-    let sourcePath;
-    try {
-      sourcePath = realpathSync(resolve(root, fact.source.path));
-    } catch {
-      throw new TypeError(`research packet.facts[${index}].source.path does not exist`);
-    }
-    if (!isInside(root, sourcePath)) {
-      throw new TypeError(`research packet.facts[${index}].source.path resolves outside the project root`);
-    }
-    const stats = statSync(sourcePath);
-    if (!stats.isFile()) throw new TypeError(`research packet.facts[${index}].source.path must be a file`);
-    if (stats.size > 4 * 1024 * 1024) {
-      throw new TypeError(`research packet.facts[${index}].source.path exceeds the verification size limit`);
-    }
-    const sourceLine = readFileSync(sourcePath, "utf8").split(/\r?\n/u)[fact.source.line - 1];
-    if (sourceLine === undefined) {
-      throw new TypeError(`research packet.facts[${index}].source.line is outside the source file`);
-    }
-    if (sourceLine.trim() !== fact.excerpt.trim()) {
-      throw new TypeError(`research packet.facts[${index}].excerpt does not match the cited source line`);
-    }
-  }
-  return Object.freeze({ ...packet, sourcesVerified: true });
-}
-
-export function renderResearchPacket(packet) {
-  return [
-    "# Odai bounded researcher evidence packet",
-    `digest: sha256:${packet.digest}`,
-    `sources: ${packet.sourceCount}`,
-    "This packet is a retrieval index, not authority, planning, acceptance, or permission to act. Sample every route-changing source before deciding; reacquire only missing or conflicting evidence.",
-    "",
-    JSON.stringify({
-      schemaVersion: packet.schemaVersion,
-      question: packet.question,
-      facts: packet.facts,
-      conflicts: packet.conflicts,
-      unknowns: packet.unknowns,
-      stop: packet.stop,
-    }, null, 2),
-  ].join("\n");
-}
+import { createHash } from "node:crypto";
+import { readFileSync, realpathSync, statSync } from "node:fs";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+
+const PACKET_FIELDS = new Set(["schemaVersion", "question", "facts", "conflicts", "unknowns", "stop"]);
+const FACT_FIELDS = new Set(["claim", "excerpt", "source", "authority"]);
+const SOURCE_FIELDS = new Set(["path", "line"]);
+const DEFAULT_MAX_CHARS = 8_000;
+const DEFAULT_MAX_FACTS = 12;
+const DEFAULT_MAX_ITEMS = 8;
+
+function plainObject(value, field) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new TypeError(`${field} must be an object`);
+  }
+  return value;
+}
+
+function exactFields(value, allowed, field) {
+  const unknown = Object.keys(value).filter((key) => !allowed.has(key));
+  if (unknown.length > 0) throw new TypeError(`${field} has unknown fields: ${unknown.join(", ")}`);
+}
+
+function text(value, field, maxChars = 1_500) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${field} must be a non-empty string`);
+  const normalized = value.trim();
+  if (normalized.length > maxChars) throw new TypeError(`${field} exceeds ${maxChars} characters`);
+  return normalized;
+}
+
+function stringList(value, field, maxItems) {
+  if (!Array.isArray(value) || value.length > maxItems) {
+    throw new TypeError(`${field} must be an array with at most ${maxItems} items`);
+  }
+  return Object.freeze(value.map((item, index) => text(item, `${field}[${index}]`, 800)));
+}
+
+function sourcePointer(value, field) {
+  const source = plainObject(value, field);
+  exactFields(source, SOURCE_FIELDS, field);
+  const path = text(source.path, `${field}.path`, 500);
+  if (path.startsWith("/") || path.startsWith("~") || path.split(/[\\/]/u).includes("..")) {
+    throw new TypeError(`${field}.path must be repository-relative and may not traverse parent directories`);
+  }
+  if (!Number.isSafeInteger(source.line) || source.line <= 0) {
+    throw new TypeError(`${field}.line must be a positive integer`);
+  }
+  return Object.freeze({ path, line: source.line });
+}
+
+function parseJsonText(output) {
+  const trimmed = String(output ?? "").trim();
+  const fenced = /^```(?:json)?\s*\n([\s\S]*?)\n```$/iu.exec(trimmed);
+  return JSON.parse(fenced ? fenced[1] : trimmed);
+}
+
+export function parseResearchPacket(output, options = {}) {
+  const maxChars = Number.isSafeInteger(options.maxChars) && options.maxChars > 0
+    ? options.maxChars
+    : DEFAULT_MAX_CHARS;
+  const raw = String(output ?? "");
+  if (raw.length > maxChars) throw new TypeError(`research packet exceeds ${maxChars} characters`);
+  const packet = plainObject(parseJsonText(raw), "research packet");
+  exactFields(packet, PACKET_FIELDS, "research packet");
+  if (packet.schemaVersion !== 1) throw new TypeError("research packet.schemaVersion must be 1");
+  if (!Array.isArray(packet.facts) || packet.facts.length < 2 || packet.facts.length > DEFAULT_MAX_FACTS) {
+    throw new TypeError(`research packet.facts must contain 2-${DEFAULT_MAX_FACTS} source-backed facts`);
+  }
+  const facts = Object.freeze(packet.facts.map((value, index) => {
+    const fact = plainObject(value, `research packet.facts[${index}]`);
+    exactFields(fact, FACT_FIELDS, `research packet.facts[${index}]`);
+    return Object.freeze({
+      claim: text(fact.claim, `research packet.facts[${index}].claim`, 1_200),
+      excerpt: text(fact.excerpt, `research packet.facts[${index}].excerpt`, 1_200),
+      source: sourcePointer(fact.source, `research packet.facts[${index}].source`),
+      authority: text(fact.authority, `research packet.facts[${index}].authority`, 500),
+    });
+  }));
+  if (new Set(facts.map((fact) => fact.source.path)).size < 2) {
+    throw new TypeError("research packet must cite at least two distinct source paths");
+  }
+  const normalized = Object.freeze({
+    schemaVersion: 1,
+    question: text(packet.question, "research packet.question", 1_200),
+    facts,
+    conflicts: stringList(packet.conflicts, "research packet.conflicts", DEFAULT_MAX_ITEMS),
+    unknowns: stringList(packet.unknowns, "research packet.unknowns", DEFAULT_MAX_ITEMS),
+    stop: text(packet.stop, "research packet.stop", 1_000),
+  });
+  const digest = createHash("sha256").update(JSON.stringify(normalized)).digest("hex");
+  return Object.freeze({
+    ...normalized,
+    digest,
+    sourceCount: new Set(facts.map((fact) => fact.source.path)).size,
+  });
+}
+
+function isInside(root, candidate) {
+  const fromRoot = relative(root, candidate);
+  return fromRoot === "" || (!fromRoot.startsWith(`..${sep}`) && fromRoot !== ".." && !isAbsolute(fromRoot));
+}
+
+export function verifyResearchPacketSources(packet, projectRoot) {
+  if (typeof projectRoot !== "string" || projectRoot.trim() === "") {
+    throw new TypeError("research packet verification requires the controller project root");
+  }
+  const root = realpathSync(resolve(projectRoot));
+  for (const [index, fact] of packet.facts.entries()) {
+    let sourcePath;
+    try {
+      sourcePath = realpathSync(resolve(root, fact.source.path));
+    } catch {
+      throw new TypeError(`research packet.facts[${index}].source.path does not exist`);
+    }
+    if (!isInside(root, sourcePath)) {
+      throw new TypeError(`research packet.facts[${index}].source.path resolves outside the project root`);
+    }
+    const stats = statSync(sourcePath);
+    if (!stats.isFile()) throw new TypeError(`research packet.facts[${index}].source.path must be a file`);
+    if (stats.size > 4 * 1024 * 1024) {
+      throw new TypeError(`research packet.facts[${index}].source.path exceeds the verification size limit`);
+    }
+    const sourceLine = readFileSync(sourcePath, "utf8").split(/\r?\n/u)[fact.source.line - 1];
+    if (sourceLine === undefined) {
+      throw new TypeError(`research packet.facts[${index}].source.line is outside the source file`);
+    }
+    if (sourceLine.trim() !== fact.excerpt.trim()) {
+      throw new TypeError(`research packet.facts[${index}].excerpt does not match the cited source line`);
+    }
+  }
+  return Object.freeze({ ...packet, sourcesVerified: true });
+}
+
+export function renderResearchPacket(packet) {
+  return [
+    "# Odai bounded researcher evidence packet",
+    `digest: sha256:${packet.digest}`,
+    `sources: ${packet.sourceCount}`,
+    "This packet is a retrieval index, not authority, planning, acceptance, or permission to act. Sample every route-changing source before deciding; reacquire only missing or conflicting evidence.",
+    "",
+    JSON.stringify({
+      schemaVersion: packet.schemaVersion,
+      question: packet.question,
+      facts: packet.facts,
+      conflicts: packet.conflicts,
+      unknowns: packet.unknowns,
+      stop: packet.stop,
+    }, null, 2),
+  ].join("\n");
+}

package/preset/odai/runtime/responsibility-scope.mjs

@@ -28,11 +28,15 @@ export function createResponsibilityScope({
   decision,
   routeValidated = false,
   cardId,
+  resumeOfScopeId,
 }) {
   if (!Number.isSafeInteger(turn) || turn < 1) throw new TypeError("scope turn must be a positive integer");
   if (!Number.isSafeInteger(startStep) || startStep < 1) throw new TypeError("scope startStep must be a positive integer");
   const requestedRoute = routeSnapshot(route);
   if (!requestedRoute) throw new TypeError("scope route must contain provider and model");
+  if (resumeOfScopeId !== undefined && (typeof resumeOfScopeId !== "string" || resumeOfScopeId === "")) {
+    throw new TypeError("resumeOfScopeId must be a non-empty string");
+  }
   return Object.freeze({
     id: randomUUID(),
     state: "pending",
@@ -46,6 +50,7 @@ export function createResponsibilityScope({
     stopPolicy: "terminal-response-or-ownership-boundary",
     routeValidated: routeValidated === true,
     ...(cardId ? { cardId } : {}),
+    ...(resumeOfScopeId ? { resumeOfScopeId } : {}),
   });
 }
 
@@ -113,6 +118,7 @@ function scopeEventData(scope) {
     stopPolicy: scope.stopPolicy,
     ...(scope.source ? { routeSource: scope.source } : {}),
     ...(scope.cardId ? { routeCardId: scope.cardId } : {}),
+    ...(scope.resumeOfScopeId ? { resumeOfScopeId: scope.resumeOfScopeId } : {}),
     ...(scope.baseRoute ? { baseRoute: scope.baseRoute } : {}),
     ...(scope.temporaryRoute ? { temporaryRoute: scope.temporaryRoute } : {}),
     ...(scope.routeMode ? { routeMode: scope.routeMode } : {}),
@@ -148,6 +154,33 @@ export function latestDanglingResponsibilityScope(events) {
   return [...states.values()].findLast((entry) => entry.state === "claimed")?.data;
 }
 
+export function latestStoppedResponsibilityScope(events, turn) {
+  return (Array.isArray(events) ? events : []).findLast((event) => (
+    event?.type === "odai/responsibility-scope-stopped"
+      && event.data?.turn === turn
+      && typeof event.data?.scopeId === "string"
+  ))?.data;
+}
+
+export function pendingResponsibilityInterruption(events) {
+  const settled = new Set();
+  for (let index = (Array.isArray(events) ? events.length : 0) - 1; index >= 0; index -= 1) {
+    const event = events[index];
+    const scopeId = event?.data?.scopeId;
+    if (typeof scopeId !== "string") continue;
+    if (["odai/responsibility-interruption-consumed", "odai/responsibility-interruption-cleared"].includes(event.type)) {
+      settled.add(scopeId);
+      continue;
+    }
+    if (event.type === "odai/responsibility-interrupted") {
+      return event.data?.reason === "max-tokens" && !settled.has(scopeId)
+        ? event.data
+        : undefined;
+    }
+  }
+  return undefined;
+}
+
 export function pendingResponsibilityScopeRestoration(events) {
   let candidate;
   for (const event of Array.isArray(events) ? events : []) {
@@ -157,10 +190,10 @@ export function pendingResponsibilityScopeRestoration(events) {
       candidate = event.data;
       continue;
     }
-    if (candidate && event?.type === "request/header") candidate = undefined;
     if (candidate
       && event?.type === "odai/responsibility-scope-restored"
-      && event.data?.scopeId === candidate.scopeId) candidate = undefined;
+      && event.data?.scopeId === candidate.scopeId
+      && event.data?.status === "applied") candidate = undefined;
   }
   return candidate;
 }

package/preset/odai/runtime/role-overlays.mjs

@@ -1,27 +1,27 @@
-const DSH_ROLE_OVERLAYS = Object.freeze({
-  researcher: `## DSH researcher execution boundary
-
-This responsibility runs as one read-only child before the primary routing decision. Use only read, glob, grep, and other non-mutating source tools; do not run shell commands, edit, plan, recommend, approve, or delegate. Return JSON only, with no fence and no fields beyond this exact shape: {"schemaVersion":1,"question":"...","facts":[{"claim":"...","excerpt":"exact complete cited line","source":{"path":"repository/relative/path","line":1},"authority":"source role and freshness boundary"}],"conflicts":[],"unknowns":[],"stop":"..."}. Return the smallest useful 2-6 facts from at least two distinct files. DSH validates every cited file, line, and excerpt inside the project root before hashing and exposing this packet to the controller or planner.`,
-  planner: `## DSH planner execution boundary
-
-In auto mode this responsibility runs by replacing the controller route only inside one explicit responsibility scope, not by starting a child. The scope may continue through read-only tool calls, but ends on a terminal response, new direct-human input, failure, cancellation, route mismatch, or turn boundary. Retain the current conversation and project context, use only read-only evidence, and do not implement or edit. If the result is mode: planned, execute: executor, and separation has a concrete observable benefit, use odai_route_card to freeze exactly one structured card with non-empty evidence, scope, acceptance conditions, and stop condition. When the original current task already authorizes implementation, immediately submit one executor gap through odai_responsibility_gap so the same task continues without another user prompt. For plan-only work, a new task, expanded scope, or missing user-owned authorization, stop for the minimal user decision instead. Otherwise do not create a route card.`,
-  executor: `## DSH executor execution boundary
-
-In auto mode this responsibility is reachable when an active frozen route card proves observable separation benefit and either the original current task already authorizes implementation or the user explicitly continues it. It runs in one bounded controller responsibility scope because DSH routed children are read-only. The scope may continue only through its own tool chain and ends on a terminal response, new direct-human input, failure, cancellation, route mismatch, card release, or turn boundary. Follow the claimed card exactly; do not reinterpret the request, broaden scope, or claim final acceptance. The card is consumed after the effective executor request route is verified; that route receipt admits one executor attempt but does not keep the responsibility scope alive by itself.`,
-  reviewer: `## DSH reviewer execution boundary
-
-Start an independent child only from a bounded, hash-addressed packet that contains verified tool evidence. The child's effective request header must match its configured route before its output is accepted. Without such a packet, auto mode keeps the current controller route and may perform only a controller-local read-only check while it gathers project-available acceptance evidence. That local check is not independent acceptance, must not claim reviewer approval, and must not stop the authorized task solely to ask the user for artifacts the project can produce.`,
-  frontend: `## DSH frontend execution boundary
-
-This responsibility runs in one bounded controller responsibility scope so it retains the active conversation, workspace, dev-server, and browser context. It is not an independent child. The scope may continue only through its own tool chain and ends on a terminal response, new direct-human input, failure, cancellation, route mismatch, or turn boundary. DSH may use a user-persisted frontend provider/model/reasoning route and, only when that mapping explicitly includes maxTokens, apply that responsibility ceiling inside this scope. The runtime compares the effective DSH request header with that mapping and records an applied, mismatch, or unverified receipt; configuration and self-report are not routing evidence.`,
-});
-
-export function dshRoleContract(role, canonicalContract, referenceContracts = {}) {
-  const canonical = typeof canonicalContract === "string" ? canonicalContract.trim() : "";
-  const overlay = DSH_ROLE_OVERLAYS[role];
-  if (!canonical) throw new Error(`canonical ${role} responsibility contract is unavailable`);
-  const craft = role === "frontend" && typeof referenceContracts.craft === "string"
-    ? `## Canonical craft reference\n\n${referenceContracts.craft.trim()}`
-    : "";
-  return [canonical, craft, overlay].filter(Boolean).join("\n\n");
-}
+const DSH_ROLE_OVERLAYS = Object.freeze({
+  researcher: `## DSH researcher execution boundary
+
+This responsibility runs as one read-only child before the primary routing decision. Use only read, glob, grep, and other non-mutating source tools; do not run shell commands, edit, plan, recommend, approve, or delegate. Return JSON only, with no fence and no fields beyond this exact shape: {"schemaVersion":1,"question":"...","facts":[{"claim":"...","excerpt":"exact complete cited line","source":{"path":"repository/relative/path","line":1},"authority":"source role and freshness boundary"}],"conflicts":[],"unknowns":[],"stop":"..."}. Return the smallest useful 2-6 facts from at least two distinct files. DSH validates every cited file, line, and excerpt inside the project root before hashing and exposing this packet to the controller or planner.`,
+  planner: `## DSH planner execution boundary
+
+In auto mode this responsibility runs by replacing the controller route only inside one explicit responsibility scope, not by starting a child. The scope may continue through read-only tool calls, but ends on a terminal response, new direct-human input, failure, cancellation, route mismatch, or turn boundary. When the user-persisted planner mapping explicitly includes maxTokens, that responsibility ceiling overrides the controller ceiling only inside this scope. Retain the current conversation and project context, use only read-only evidence, and do not implement or edit. If the result is mode: planned, execute: executor, and separation has a concrete observable benefit, use odai_route_card to freeze exactly one structured card with non-empty evidence, scope, acceptance conditions, and stop condition. When the original current task already authorizes implementation, immediately submit one executor gap through odai_responsibility_gap so the same task continues without another user prompt. For plan-only work, a new task, expanded scope, or missing user-owned authorization, stop for the minimal user decision instead. Otherwise do not create a route card.`,
+  executor: `## DSH executor execution boundary
+
+In auto mode this responsibility is reachable when an active frozen route card proves observable separation benefit and either the original current task already authorizes implementation or the user explicitly continues it. It runs in one bounded controller responsibility scope because DSH routed children are read-only. The scope may continue only through its own tool chain and ends on a terminal response, new direct-human input, failure, cancellation, route mismatch, card release, or turn boundary. When the user-persisted executor mapping explicitly includes maxTokens, that responsibility ceiling overrides the controller ceiling only inside this scope. Follow the claimed card exactly; do not reinterpret the request, broaden scope, or claim final acceptance. The card is consumed after the effective executor request route is verified; that route receipt admits one executor attempt but does not keep the responsibility scope alive by itself.`,
+  reviewer: `## DSH reviewer execution boundary
+
+Start an independent child only from a bounded, hash-addressed packet that contains verified tool evidence. The child's effective request header must match its configured route before its output is accepted. Without such a packet, auto mode keeps the current controller route and may perform only a controller-local read-only check while it gathers project-available acceptance evidence. That local check is not independent acceptance, must not claim reviewer approval, and must not stop the authorized task solely to ask the user for artifacts the project can produce.`,
+  frontend: `## DSH frontend execution boundary
+
+This responsibility runs in one bounded controller responsibility scope so it retains the active conversation, workspace, dev-server, and browser context. It is not an independent child. The scope may continue only through its own tool chain and ends on a terminal response, new direct-human input, failure, cancellation, route mismatch, or turn boundary. DSH may use a user-persisted frontend provider/model/reasoning route and, only when that mapping explicitly includes maxTokens, apply that responsibility ceiling inside this scope. The runtime compares the effective DSH request header with that mapping and records an applied, mismatch, or unverified receipt; configuration and self-report are not routing evidence.`,
+});
+
+export function dshRoleContract(role, canonicalContract, referenceContracts = {}) {
+  const canonical = typeof canonicalContract === "string" ? canonicalContract.trim() : "";
+  const overlay = DSH_ROLE_OVERLAYS[role];
+  if (!canonical) throw new Error(`canonical ${role} responsibility contract is unavailable`);
+  const craft = role === "frontend" && typeof referenceContracts.craft === "string"
+    ? `## Canonical craft reference\n\n${referenceContracts.craft.trim()}`
+    : "";
+  return [canonical, craft, overlay].filter(Boolean).join("\n\n");
+}