dsh-data-cleaning-agent 0.9.13 → 0.9.16

package/lib/image-workflow.js

@@ -13,7 +13,13 @@ export function createImageWorkflow({ getWorkflow, execution, commands }) {
     task = await store.recordUpload(task.id, { expectedRevision: task.revision,
       source: { type: 'image', fileName: record.fileName, sizeBytes: record.sizeBytes,
         rowCount: rows.length, columnCount: 1, headers: ['主体标识'] } });
-    task = await store.updateDraft(task.id, { expectedRevision: task.revision, mappings });
+    task = await store.updateDraft(task.id, {
+      expectedRevision: task.revision,
+      mappings,
+      objectives: task.objectives.includes('complete_fields')
+        ? task.objectives
+        : [...task.objectives, 'complete_fields'],
+    });
     if (result.truncated || result.needsReview || rows.length > 100) {
       return { taskId: task.id, deliveryState: 'review_required', artifacts: [],
         reviewReason: rows.length > 100 || result.truncated ? '识别名单超出单批范围，请核验并拆分。' : '识别文本含模糊字符或待确认提示，请核验名单。' };

package/lib/qcc-command.js

@@ -198,6 +198,14 @@ export class QccCommandStore {
     return output;
   }
 
+  hasActiveForTask(taskId) {
+    this.cleanup();
+    const id = String(taskId ?? '');
+    return [...this.commands.values()].some((command) => (
+      command.taskId === id && ['prepared', 'running'].includes(command.state)
+    ));
+  }
+
   async run(commandId, execution) {
     const record = this.require(commandId);
     if (!execution?.agent || !execution?.token) {

package/lib/qcc-runs.js

@@ -191,6 +191,15 @@ export class G5RunStore {
     return this.snapshot(this.requireRun(id));
   }
 
+  capabilities(id) {
+    this.cleanup();
+    const record = this.runs.get(String(id ?? ''));
+    return {
+      liveRunAvailable: Boolean(record),
+      retryableFailuresAvailable: Boolean(record?.errors.some((item) => item.error?.retryable)),
+    };
+  }
+
   snapshot(record) {
     return clone({
       runId: record.id,

package/lib/skill-enrich.js

@@ -52,6 +52,7 @@ export function registerEnrichSkill(skills) {
       'When the user gives company names and asks to enrich / complete them with Qichacha (企查查), including registration fields, company panorama, ownership penetration, governance, historical changes, risk tags, intellectual property, or operational / bidding dimensions.',
     source: 'dsh-data-cleaning-agent',
     content: [
+      'UX-49 最高优先级：先检查本业务请求的信息是否充分，再考虑以下任何工具或执行规则。若仍含未补全的【】占位符，或没有实际企业名单/Excel/名单图片与待补字段，先用中文要求提供名单或文件及待补字段；零工具调用，包括 OAuth 检查、体检、OCR、MCP、创建 workflow。例子、说明、【企业名单】均不是企业。用户改过的初始模板按普通内容理解，不得整体忽略。有真实暂存来源和已选字段的安全任务凭证可提供这些信息，不要求重复提供。此规则只作用于数据清洗补全业务，不得全局拦截 DSH 发送或其它产品。',
       'You are an enterprise-list enrichment assistant. You fill company lists with Qichacha (QCC) data by calling QCC MCP tools. Never invent, pad, or fabricate any field.',
       '',
       'Workbench execution request (highest priority):',

package/lib/skill.js

@@ -15,6 +15,7 @@ export function registerSkill(skills) {
       'When the user asks to clean, complete, validate, de-duplicate, or summarize a batch of raw data rows, CSV records, or table-like data.',
     source: 'dsh-data-cleaning-agent',
     content: [
+      'UX-49 — Highest priority, before ANY tool: within this data-cleaning business request, if the message still contains an unfilled 【】 placeholder, or lacks actual rows/list/file and requested completion fields, ask the user to provide the actual enterprise list or Excel/list image and the fields to complete. Make ZERO tool calls (including profile, OAuth checks, OCR, MCP and workflow creation). Do not treat examples, instructions or 【企业名单】 as enterprises. Do not intercept other DSH products or the global send action. A valid staged-source task credential can supply the list/field scope; do not demand the same data twice. An edited initial template is ordinary user content, never discard it wholesale.',
       'You are a data cleaning and completion assistant. Work only on the rows the user actually provided; never invent, pad, or fabricate extra rows.',
       '',
       'Workflow:',

package/lib/web.js

@@ -7,13 +7,19 @@
  *  - 上传体大小上限（parseBody）。
  *  - 同步接口返回明细行仅供「已授权同源 UI」下载，不面向模型。
  */
+import { createHash, randomBytes } from 'node:crypto';
 import { parseCsv, parseXlsx, parseJson, detectFormat, toCsv } from './engine.js';
 import { runSync, DataCleaningJobs } from './jobs.js';
 import { QccBridgeError, QccHostBridge } from './qcc.js';
 import { QccCommandStore, registerQccCommandTool, TOOL_QCC_COMMAND } from './qcc-command.js';
 import { fingerprintRequest, G5RunStore } from './qcc-runs.js';
 import { PHASE3_BATCH_LIMITS, Phase3BatchService, Phase3RunStore } from './qcc-phase3-batch.js';
-import { publicWorkflowContract } from './workflow-contract.js';
+import {
+  WORKFLOW_ACTIONS,
+  allowedWorkflowActions,
+  deriveWorkflowFlow,
+  publicWorkflowContract,
+} from './workflow-contract.js';
 import { DataCleaningWorkflowStore, WorkflowError } from './workflow.js';
 import { ArtifactError, WorkflowArtifactStore } from './artifacts.js';
 import { renderArtifactPreview } from './artifact-preview.js';
@@ -141,6 +147,23 @@ function writeImageError(res, error) {
 }
 
 /** 从 JSON 协议解析上传：{ filename, content }。content 为字符串；xlsx 时为 base64。 */
+function canonicalize(value) {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (value === null || typeof value !== 'object') return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonicalize(value[key])]));
+}
+
+function sourceVerifier(headers, rows, previous = '') {
+  const match = /^sha256-canonical-rows-v1:([a-f0-9]{32}):[a-f0-9]{64}$/.exec(String(previous));
+  const salt = match?.[1] || randomBytes(16).toString('hex');
+  const canonical = JSON.stringify({
+    headers: (Array.isArray(headers) ? headers : []).map(String),
+    rows: canonicalize(Array.isArray(rows) ? rows : []),
+  });
+  const digest = createHash('sha256').update(salt).update('\0').update(canonical).digest('hex');
+  return `sha256-canonical-rows-v1:${salt}:${digest}`;
+}
+
 async function parseUpload(body) {
   let payload;
   try {
@@ -153,12 +176,20 @@ async function parseUpload(body) {
   const filename = String(payload?.filename ?? 'data.csv');
   const content = payload?.content ?? '';
   const fmt = detectFormat(filename);
+  let parsed;
   if (fmt === 'xlsx') {
     const buf = Buffer.from(String(content), 'base64');
-    return { fmt, ...(await parseXlsx(buf)) };
+    parsed = await parseXlsx(buf);
+  } else if (fmt === 'json') {
+    parsed = parseJson(String(content));
+  } else {
+    parsed = parseCsv(String(content));
   }
-  if (fmt === 'json') return { fmt, ...parseJson(String(content)) };
-  return { fmt, ...parseCsv(String(content)) };
+  return {
+    fmt,
+    ...parsed,
+    checksum: sourceVerifier(parsed.headers, parsed.rows, payload?.previousChecksum),
+  };
 }
 
 const UI_HTML = `<!doctype html>
@@ -307,7 +338,11 @@ export function mountWebRoutes(wctx, { logger, report, TOOL_NAME, SKILL_NAME })
   const disposers = [];
   const qccBridge = new QccHostBridge({ tools, logger });
   const g5Runs = new G5RunStore();
-  const execution = createWorkflowExecution({ getWorkflow: () => getWorkflow(), artifacts: wctx.fs ? new WorkflowArtifactStore({ fs: wctx.fs }) : null });
+  const execution = createWorkflowExecution({
+    getWorkflow: () => getWorkflow(),
+    artifacts: wctx.fs ? new WorkflowArtifactStore({ fs: wctx.fs }) : null,
+    getRun: (runId) => g5Runs.get(runId),
+  });
   const qccCommands = new QccCommandStore({ bridge: qccBridge, runs: g5Runs, lifecycle: execution });
   const imageIntake = new ImageIntakeStore({ tools,
     continueWorkflow: createImageWorkflow({ getWorkflow: () => getWorkflow(), execution, commands: qccCommands }) });
@@ -353,6 +388,22 @@ export function mountWebRoutes(wctx, { logger, report, TOOL_NAME, SKILL_NAME })
     return workflowReady;
   };
 
+  const workflowView = (task) => ({
+    ...task,
+    flow: deriveWorkflowFlow(task),
+    runtimeCapabilities: {
+      activeCommand: qccCommands.hasActiveForTask(task.id),
+      ...g5Runs.capabilities(task.qccRunId),
+    },
+  });
+
+  const requireWorkflowAction = (task, action) => {
+    if (!allowedWorkflowActions(task).includes(action)) {
+      const current = deriveWorkflowFlow(task).currentStage;
+      throw new WorkflowError('DC_WORKFLOW_ACTION_LOCKED', `当前任务位于“${current}”，不能执行该操作。`, 409);
+    }
+  };
+
   register('/data-cleaning/', (req, res) => {
     if (!isTrusted(req)) { res.writeHead(403); return res.end('untrusted origin'); }
     res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' });
@@ -490,7 +541,7 @@ export function mountWebRoutes(wctx, { logger, report, TOOL_NAME, SKILL_NAME })
           return writeJson(res, 200, {
             ok: true,
             marker: 'data-cleaning-workflow-v2',
-            tasks: await workflow.list(),
+            tasks: (await workflow.list()).map(workflowView),
           });
         }
         if (req.method === 'POST') {
@@ -499,7 +550,7 @@ export function mountWebRoutes(wctx, { logger, report, TOOL_NAME, SKILL_NAME })
           return writeJson(res, 201, {
             ok: true,
             marker: 'data-cleaning-workflow-v2',
-            task: await workflow.create(payload),
+            task: workflowView(await workflow.create(payload)),
           });
         }
         return writeJson(res, 405, { ok: false, code: 'DC_METHOD', message: 'GET or POST required' });
@@ -511,17 +562,18 @@ export function mountWebRoutes(wctx, { logger, report, TOOL_NAME, SKILL_NAME })
           return writeJson(res, 200, {
             ok: true,
             marker: 'data-cleaning-workflow-v2',
-            task: await workflow.require(taskId),
+            task: workflowView(await workflow.require(taskId)),
           });
         }
         if (req.method === 'PATCH') {
           const body = await readBody(req);
           const payload = body.length ? JSON.parse(body.toString('utf8')) : {};
-          await workflow.assertRequestOrigin(taskId, payload);
+          const current = await workflow.assertRequestOrigin(taskId, payload);
+          requireWorkflowAction(current, WORKFLOW_ACTIONS.EDIT_RULES);
           return writeJson(res, 200, {
             ok: true,
             marker: 'data-cleaning-workflow-v2',
-            task: await workflow.updateDraft(taskId, payload),
+            task: workflowView(await workflow.updateDraft(taskId, payload)),
           });
         }
         return writeJson(res, 405, { ok: false, code: 'DC_METHOD', message: 'GET or PATCH required' });
@@ -540,7 +592,7 @@ export function mountWebRoutes(wctx, { logger, report, TOOL_NAME, SKILL_NAME })
           return writeJson(res, 200, {
             ok: true,
             marker: 'data-cleaning-artifacts-v1',
-            task: current,
+            task: workflowView(current),
             artifacts: current.artifacts,
           });
         }
@@ -551,32 +603,24 @@ export function mountWebRoutes(wctx, { logger, report, TOOL_NAME, SKILL_NAME })
           if (Number(payload.expectedRevision) !== current.revision) {
             throw new WorkflowError('DC_WORKFLOW_REVISION_CONFLICT', 'Workflow task was updated by another session.', 409);
           }
-          let readyTask = current;
-          if (['rules_confirmed', 'diagnosed'].includes(readyTask.state)) {
-            readyTask = await workflow.prepareLocalExport(taskId, {
-              expectedRevision: readyTask.revision,
-              summary: payload.summary,
-            });
-          }
-          if (!['export_ready', 'partial'].includes(readyTask.state)) {
-            throw new WorkflowError('DC_WORKFLOW_EXPORT_STATE', 'Output is not ready for durable export.', 409);
-          }
+          requireWorkflowAction(current, WORKFLOW_ACTIONS.CREATE_LOCAL_ARTIFACTS);
           const artifacts = await artifactStore.createBundle(taskId, {
             rows: payload.rows,
             headers: payload.headers,
-            fieldSelection: readyTask.fieldSelection,
-            mappings: readyTask.mappings,
+            fieldSelection: current.fieldSelection,
+            mappings: current.mappings,
             exceptionRows: payload.exceptionRows,
-            baseName: payload.baseName || readyTask.title,
+            baseName: payload.baseName || current.title,
           });
-          const completed = await workflow.recordExport(taskId, {
-            expectedRevision: readyTask.revision,
+          const completed = await workflow.completeLocalDelivery(taskId, {
+            expectedRevision: current.revision,
+            summary: payload.summary,
             artifacts,
           });
           return writeJson(res, 201, {
             ok: true,
             marker: 'data-cleaning-artifacts-v1',
-            task: completed,
+            task: workflowView(completed),
             artifacts: completed.artifacts,
           });
         }
@@ -609,6 +653,22 @@ export function mountWebRoutes(wctx, { logger, report, TOOL_NAME, SKILL_NAME })
         return writeJson(res, 405, { ok: false, code: 'DC_METHOD', message: 'Artifact route requires GET or POST.' });
       }
 
+      if (rest.length === 2 && rest[1] === 'verify-source') {
+        if (req.method !== 'POST') {
+          return writeJson(res, 405, { ok: false, code: 'DC_METHOD', message: 'Source verification requires POST.' });
+        }
+        const body = await readBody(req);
+        const payload = body.length ? JSON.parse(body.toString('utf8')) : {};
+        const current = await workflow.assertRequestOrigin(taskId, payload);
+        const verified = Boolean(current.source?.checksum)
+          && sourceVerifier(payload.headers, payload.rows, current.source.checksum) === current.source.checksum;
+        return writeJson(res, 200, {
+          ok: true,
+          marker: 'data-cleaning-source-verifier-v1',
+          verified,
+        });
+      }
+
       if (rest.length !== 3 || rest[1] !== 'actions' || req.method !== 'POST') {
         return writeJson(res, 404, { ok: false, code: 'DC_WORKFLOW_ROUTE', message: 'Workflow route not found.' });
       }
@@ -617,27 +677,22 @@ export function mountWebRoutes(wctx, { logger, report, TOOL_NAME, SKILL_NAME })
       const action = rest[2];
       await workflow.assertRequestOrigin(taskId, payload);
       const actions = {
-        upload: () => workflow.recordUpload(taskId, payload),
-        rules: () => workflow.confirmRules(taskId, payload),
-        quality: () => workflow.recordQuality(taskId, payload),
-        'match-start': () => workflow.startMatch(taskId, payload),
-        match: () => workflow.recordMatch(taskId, payload),
-        'enrich-start': () => workflow.startEnrichment(taskId, payload),
-        enrichment: () => workflow.recordEnrichment(taskId, payload),
-        'local-export-ready': () => workflow.prepareLocalExport(taskId, payload),
-        export: () => workflow.recordExport(taskId, payload),
-        'parse-failed': () => workflow.recordParseFailure(taskId, payload),
-        'authorization-required': () => workflow.requireAuthorization(taskId, payload),
-        fail: () => workflow.recordFailure(taskId, payload),
-        cancel: () => workflow.cancel(taskId, payload),
+        upload: { action: WORKFLOW_ACTIONS.IMPORT_DATA, run: () => workflow.recordUpload(taskId, payload) },
+        rules: { action: WORKFLOW_ACTIONS.CONFIRM_RULES, run: () => workflow.confirmRules(taskId, payload) },
+        quality: { action: WORKFLOW_ACTIONS.RUN_QUALITY, run: () => workflow.recordQuality(taskId, payload) },
+        'retry-delivery': { action: WORKFLOW_ACTIONS.RETRY_DELIVERY, run: async () => (
+          await execution.retryDelivery({ taskId, expectedRevision: payload.expectedRevision })
+        ).task },
       };
       if (!actions[action]) {
         return writeJson(res, 404, { ok: false, code: 'DC_WORKFLOW_ACTION', message: `Unknown workflow action: ${action}` });
       }
+      const current = await workflow.require(taskId);
+      requireWorkflowAction(current, actions[action].action);
       return writeJson(res, 200, {
         ok: true,
         marker: 'data-cleaning-workflow-v2',
-        task: await actions[action](),
+        task: workflowView(await actions[action].run()),
       });
     } catch (error) {
       if (error instanceof SyntaxError) {
@@ -984,7 +1039,7 @@ export function mountWebRoutes(wctx, { logger, report, TOOL_NAME, SKILL_NAME })
     if (!isTrusted(req)) return writeJson(res, 403, { ok: false, error: 'untrusted origin' });
     try {
       const body = await readBody(req);
-      const { fmt, headers, rows } = await parseUpload(body);
+      const { fmt, headers, rows, checksum } = await parseUpload(body);
       writeJson(res, 200, {
         ok: true,
         fmt,
@@ -992,6 +1047,7 @@ export function mountWebRoutes(wctx, { logger, report, TOOL_NAME, SKILL_NAME })
         rowCount: rows.length,
         preview: rows.slice(0, 5),
         rows,
+        checksum,
       });
     } catch (error) {
       writeJson(res, 400, { ok: false, code: error?.code ?? 'DC_PARSE', message: error instanceof Error ? error.message : String(error) });

package/lib/workflow-contract.js

@@ -10,6 +10,27 @@
 import { QCC_FIELD_CATALOG } from './qcc-field-catalog.js';
 
 export const WORKFLOW_SCHEMA_VERSION = 2;
+export const FLOW_VERSION = 1;
+
+export const WORKFLOW_STAGE_ACCESS = Object.freeze({
+  CURRENT: 'current',
+  READ: 'read',
+  LOCKED: 'locked',
+});
+
+export const WORKFLOW_ACTIONS = Object.freeze({
+  IMPORT_DATA: 'import-data',
+  EDIT_RULES: 'edit-rules',
+  CONFIRM_RULES: 'confirm-rules',
+  RUN_QUALITY: 'run-quality',
+  PREPARE_QCC_COMMAND: 'prepare-qcc-command',
+  RUN_LOCAL_CLEAN: 'run-local-clean',
+  RUN_LOCAL_COMPLETE: 'run-local-complete',
+  CREATE_LOCAL_ARTIFACTS: 'create-local-artifacts',
+  RESOLVE_CANDIDATE: 'resolve-candidate',
+  RETRY_FAILED: 'retry-failed',
+  RETRY_DELIVERY: 'retry-delivery',
+});
 
 export const WORKFLOW_STAGES = Object.freeze([
   Object.freeze({ id: 'upload', label: '上传数据', order: 1 }),
@@ -79,17 +100,17 @@ const STATE_IDS = new Set(WORKFLOW_STATES);
 const TRANSITIONS = Object.freeze({
   draft: ['uploaded', 'parse_failed', 'cancelled'],
   uploaded: ['draft', 'rules_confirmed', 'parse_failed', 'cancelled'],
-  rules_confirmed: ['diagnosed', 'matching', 'matched', 'review_required', 'export_ready', 'authorization_required', 'failed', 'cancelled'],
-  diagnosed: ['matching', 'matched', 'review_required', 'export_ready', 'authorization_required', 'failed', 'cancelled'],
-  matching: ['matched', 'review_required', 'authorization_required', 'partial', 'failed', 'cancelled'],
-  review_required: ['matching', 'matched', 'authorization_required', 'partial', 'failed', 'cancelled'],
+  rules_confirmed: ['diagnosed', 'failed', 'cancelled'],
+  diagnosed: ['matching', 'export_ready', 'completed', 'authorization_required', 'failed', 'cancelled'],
+  matching: ['matched', 'review_required', 'authorization_required', 'partial', 'completed', 'failed', 'cancelled'],
+  review_required: ['matching', 'matched', 'authorization_required', 'partial', 'completed', 'failed', 'cancelled'],
   matched: ['enriching', 'export_ready', 'authorization_required', 'partial', 'failed', 'cancelled'],
   enriching: ['export_ready', 'review_required', 'authorization_required', 'partial', 'failed', 'cancelled'],
-  export_ready: ['enriching', 'completed', 'failed', 'cancelled'],
+  export_ready: ['enriching', 'partial', 'completed', 'failed', 'cancelled'],
   parse_failed: ['draft', 'uploaded', 'cancelled'],
   authorization_required: ['matching', 'enriching', 'failed', 'cancelled'],
-  partial: ['matching', 'review_required', 'enriching', 'export_ready', 'authorization_required', 'completed', 'failed', 'cancelled'],
-  failed: ['draft', 'uploaded', 'rules_confirmed', 'diagnosed', 'matching', 'enriching', 'cancelled'],
+  partial: ['review_required', 'authorization_required', 'completed', 'failed', 'cancelled'],
+  failed: ['partial', 'completed', 'cancelled'],
   completed: [],
   cancelled: [],
 });
@@ -173,6 +194,100 @@ export function normalizeWorkflowDraft(value = {}) {
   };
 }
 
+export function requiresQcc(task) {
+  return Array.isArray(task?.objectives)
+    && task.objectives.some((objective) => ['validate_identity', 'complete_fields'].includes(objective));
+}
+
+function currentStageFor(task) {
+  switch (task?.state) {
+    case 'draft':
+    case 'parse_failed':
+      return 'upload';
+    case 'uploaded':
+    case 'rules_confirmed':
+      return 'rules';
+    case 'diagnosed':
+      return requiresQcc(task) ? 'match' : 'enrich';
+    case 'matching':
+    case 'review_required':
+      return 'match';
+    case 'matched':
+    case 'enriching':
+      return 'enrich';
+    case 'export_ready':
+    case 'partial':
+    case 'completed':
+      return 'download';
+    case 'authorization_required':
+    case 'failed':
+    case 'cancelled':
+      return STAGE_IDS.has(task?.stage) ? task.stage : 'upload';
+    default:
+      return STAGE_IDS.has(task?.stage) ? task.stage : 'upload';
+  }
+}
+
+export function allowedWorkflowActions(task) {
+  const state = task?.state;
+  if (state === 'draft' || state === 'parse_failed') {
+    return [WORKFLOW_ACTIONS.IMPORT_DATA, WORKFLOW_ACTIONS.EDIT_RULES];
+  }
+  if (state === 'uploaded') {
+    return [WORKFLOW_ACTIONS.IMPORT_DATA, WORKFLOW_ACTIONS.EDIT_RULES, WORKFLOW_ACTIONS.CONFIRM_RULES];
+  }
+  if (state === 'rules_confirmed') return [WORKFLOW_ACTIONS.RUN_QUALITY];
+  if (state === 'diagnosed') {
+    return requiresQcc(task)
+      ? [WORKFLOW_ACTIONS.PREPARE_QCC_COMMAND]
+      : [
+          WORKFLOW_ACTIONS.RUN_LOCAL_CLEAN,
+          WORKFLOW_ACTIONS.RUN_LOCAL_COMPLETE,
+          WORKFLOW_ACTIONS.CREATE_LOCAL_ARTIFACTS,
+        ];
+  }
+  if (state === 'review_required') return [WORKFLOW_ACTIONS.RESOLVE_CANDIDATE];
+  if (state === 'export_ready') {
+    return requiresQcc(task)
+      ? [WORKFLOW_ACTIONS.RETRY_DELIVERY]
+      : [WORKFLOW_ACTIONS.CREATE_LOCAL_ARTIFACTS];
+  }
+  if (state === 'partial') {
+    return [
+      WORKFLOW_ACTIONS.RETRY_FAILED,
+      ...(task?.error?.code === 'DC_DELIVERY_FAILED' ? [WORKFLOW_ACTIONS.RETRY_DELIVERY] : []),
+    ];
+  }
+  if (state === 'failed' && task?.error?.code === 'DC_DELIVERY_FAILED' && task?.qccRunId) {
+    return [WORKFLOW_ACTIONS.RETRY_DELIVERY];
+  }
+  return [];
+}
+
+export function deriveWorkflowFlow(task) {
+  const currentStage = currentStageFor(task);
+  const stageAccess = Object.fromEntries(WORKFLOW_STAGES.map(({ id }) => [id, WORKFLOW_STAGE_ACCESS.LOCKED]));
+  stageAccess[currentStage] = WORKFLOW_STAGE_ACCESS.CURRENT;
+
+  const makeReadable = (stage, condition) => {
+    if (condition && stage !== currentStage) stageAccess[stage] = WORKFLOW_STAGE_ACCESS.READ;
+  };
+  makeReadable('upload', Boolean(task?.source));
+  makeReadable('rules', !['draft', 'uploaded', 'parse_failed'].includes(task?.state));
+  makeReadable('match', requiresQcc(task) && Boolean(task?.matchSummary || task?.qccRunId));
+  makeReadable('enrich', Boolean(task?.enrichmentSummary));
+  makeReadable('download', Array.isArray(task?.artifacts) && task.artifacts.length > 0);
+
+  const allowedActions = allowedWorkflowActions(task);
+  return {
+    flowVersion: FLOW_VERSION,
+    currentStage,
+    stageAccess,
+    allowedActions,
+    nextAction: allowedActions[0] ?? null,
+  };
+}
+
 export function canTransition(from, to) {
   if (!STATE_IDS.has(from) || !STATE_IDS.has(to)) return false;
   return TRANSITIONS[from].includes(to);
@@ -187,7 +302,10 @@ export function assertWorkflowTransition(from, to) {
 export function publicWorkflowContract() {
   return {
     schemaVersion: WORKFLOW_SCHEMA_VERSION,
+    flowVersion: FLOW_VERSION,
     stages: WORKFLOW_STAGES,
+    stageAccessModes: Object.values(WORKFLOW_STAGE_ACCESS),
+    actions: Object.values(WORKFLOW_ACTIONS),
     states: WORKFLOW_STATES,
     terminalStates: TERMINAL_WORKFLOW_STATES,
     sourceTypes: SOURCE_TYPES,