@guanlin4924/devflow-pi 0.1.94 → 0.1.95

package/plugins/devflow-quality/skills/workflow-run-acceptance-tests/SKILL.md

@@ -7,6 +7,8 @@ description: "Execute the frozen TC acceptance suite after code review. Use the
 
 此步骤在代码审查后运行。它的目标是执行冻结的 `TC-*`，而不是根据交付总结重新猜测要测什么。
 
+对 `execution_surface: ui|api_flow` 的自动化 TC，`workflow-generate-mainflow-cases` 是本步骤绑定阶段的**真实前置条件**（不是新的主链步骤，也不是可选的开发者同步）：先用它为每个这类 TC 编译 `.devflow/planning/generated-cases/{feature}/TC-xxxx.json`、校验整个目录、独立 AI 审查并提交逐 TC `execution_plan` 批准。没有 DSL 或没有有效批准的 TC 只能 `blocked(dsl_not_approved)`，不得进入收口。
+
 ## 输入边界
 
 测试意图只能读取：
@@ -26,25 +28,29 @@ description: "Execute the frozen TC acceptance suite after code review. Use the
 ## 过程
 
 1. 用 `devflow_acceptance_tests(feature)` 检查测试集已由 CP-3 冻结。若有 stale 或候选 TC，停止并回到需求/测试设计。
-2. 读取冻结 TC 与其 oracle、前置数据、身份和自动化模式。
+2. 读取冻结 TC 与其 oracle、前置数据、身份、自动化模式和 `execution_surface`。
    对 `api_refs`、`workload_refs` 和 `risk_refs` 指向的专项用例，保留其契约、性能/迁移或韧性义务；没有适配器或环境时必须写为 blocked，不能用普通主流程替代。
-3. 读取代码审查报告、代码索引和实际源码，仅为每个 TC 绑定运行适配器；不得改变 TC 的断言、范围或预期。
+3. 读取代码审查报告、代码索引和实际源码，仅为每个 TC 绑定运行适配器；不得改变 TC 的断言、范围或预期。对每个自动化 `ui|api_flow` TC，若 `generated-cases/{feature}/TC-xxxx.json` 不存在或已过期（TC 重冻结、代码变更），先调用 `workflow-generate-mainflow-cases`；它无法生成的正向 UI/API TC（无稳定 locator、无法准备或隔离数据、纯视觉判断）按下一步降级，异常/边界/权限/性能专项 TC 也不由它生成。
 4. 写入 `.devflow/planning/features/{feature}/acceptance-test-bindings.json`：
    - 固定 `test_suite.graph_revision` 与 `fingerprint`；
    - 每个 TC 恰好一条绑定；
-   - `mode` 必须与冻结 TC 的 `automation_mode` 一致；
-   - 通用自动化用例使用 `{ "kind": "command", "argv": [ ... ] }`，不使用 shell 字符串；
+   - 默认 `mode` 与冻结 TC 的 `automation_mode` 一致。只允许单向降级：`automated → manual|blocked`、`manual → blocked`；`automated → manual` 必须先提交并由用户确认有效的 `mode_override` approval，其他降级必须保留 owner、reason 和 blocked_by；禁止升级；
+   - `execution_surface: ui|api_flow` 必须使用 `{ "kind": "devflow_playwright", "dsl_file": ".devflow/planning/generated-cases/{feature}/TC-xxxx.json", "environment_profile": "local", "timeout_seconds": 600, "artifacts": {"trace":"on_failure","screenshots":"on_failure","max_total_bytes":104857600} }`。绑定不得携带 argv、env、runner、config、result_file 或哈希；
+   - 每个 `devflow_playwright` TC 执行前必须存在有效的逐 TC `execution_plan` approval，profile（`.devflow/planning/test-environments/{profile}.json`）必须存在有效 `environment_profile` approval；缺失、DSL 或 profile 字节变化导致 pins 失效时只能 blocked（`dsl_not_approved` / `environment_profile_not_approved`），不得运行。Agent 用 `devflow_approval(action="propose", kind="environment_profile", items=[{"subject":"{profile}"}])` 提交 profile，用户在 `/devflow` → “待审批”确认；Agent 不能确认，也不能自写批准记录；
+   - `execution_surface: project_test` 的通用自动化用例使用 `{ "kind": "command", "argv": [ ... ] }`，不使用 shell 字符串。命令策略：`npm test` 要求项目已登记 `test` 脚本；`npm|pnpm|yarn run <name>` 要求 `<name>` 是初始化工具链已登记的脚本名，且 `run` 后必须紧跟脚本名（不得在 `run` 之前或之间放选项），额外参数只能放在 `--` 之后；argv 不得引用 `DEVFLOW_` 保留变量或 Devflow Playwright Runtime 路径（那属于 `devflow_playwright`）；
    - Core 生成的 API TC 可直接使用 `{ "kind": "http", "base_url_env": "DEVFLOW_TEST_BASE_URL", "headers_env": { "Authorization": "DEVFLOW_TEST_AUTHORIZATION" } }`。请求、HTTP 状态和异常码断言来自冻结 TC 的 `execution`，绑定只能提供环境地址和鉴权，不得重写测试意图；若场景需要专用夹具，可额外配置 `{ "setup": { "argv": [ ... ] } }`，Core 会先记录并执行该受控命令，再发 HTTP 请求；
-   - 人工或环境阻塞用例必须有 owner 与原因/阻塞源。
+   - 人工用例保留 owner 与执行说明；`human-acceptance-results.json` 仅是草稿和交接材料，最终结果必须来自有效的逐 TC `human_result` approval；
+   - 环境阻塞用例必须有 owner 与阻塞源。
    - `evidence_strategy=causal` 的自动用例额外写 `evidence_files`（项目根目录内的 HAR、控制台、DOM 快照、截图或日志文件相对路径）。Core 在执行前校验文件存在且未越出项目根目录，并把内容哈希写入结果；不能只填 Markdown 描述。
    - `evidence_strategy=observation` 只能保持 `blocked`，其观测计划是风险收口输入，不是测试通过证据。
-5. 调用 `devflow_run_acceptance_tests(action="validate", feature=...)`。不通过时修正绑定，不得绕过。
-6. 调用 `devflow_run_acceptance_tests(action="run", feature=...)`。该 Core 工具记录每个 TC 的命令哈希、退出码和输出摘要。
-7. 失败、未执行或 blocked 的 TC 只能报告为 `blocked`/`failed`，不得进入版本收口。
+5. 调用 `devflow_run_acceptance_tests(action="validate", feature=...)`。它校验 adapter 与 `execution_surface` 的兼容矩阵、`devflow_playwright` 禁用键、DSL 存在且合法、`tc_sha256` 与覆盖。不通过时修正绑定，不得绕过。
+6. 对每个 manual TC，检查用户已在 `/devflow` → “待审批”中确认 `human_result`；Core 按当前 suite fingerprint、`tc_sha256` 和证据哈希重新校验。缺失或失效时保持 blocked。
+7. 调用 `devflow_run_acceptance_tests(action="run", feature=...)`。该 Core 工具执行 automated TC（`devflow_playwright` 在净化环境和独立运行目录中执行，并校验 Runtime 完整性与结果 nonce），合并已校验的 manual TC 结果，并记录命令/证据哈希、退出码、`dsl_approval`、`execution_surface`、`legacy_unclassified` 和降级记录。
+8. 失败、未执行或 blocked 的 TC 只能报告为 `blocked`/`failed`，不得进入版本收口。验收未全 passed 是硬门禁：即使默认 soft 模式，`run-acceptance-tests` 完成和 `release-closeout` 确认时 Core 也会重新校验结果并以 `acceptance_results_not_passed` 拒绝。可用 `devflow_run_acceptance_tests(action="validate_results", feature=...)` 预先检查。该校验会对照当前批准、DSL/profile 哈希与运行目录重新验证每条记录：运行后修改 DSL 或 profile、或批准被新的批准替换，都会使已记录的 passed 失效，必须重跑。
 
 ## 输出
 
 - `.devflow/planning/features/{feature}/acceptance-test-bindings.json`
 - `.devflow/planning/test-runs/{feature}/acceptance-results.json`
 
-`acceptance-results.json` 是 Core-owned 的执行事实；Markdown 结论不能替代它。
+`acceptance-results.json` 是 Core 指定写入的本地执行缓存（Agent 不得写入，可读取用于展示）；Markdown 结论不能替代它，收口以 Core 对它的重新校验（`validate_results`）为准。Hook 会拦截常规 Write/Edit/Bash 误写，但不是对同一系统用户下任意进程的安全隔离；未配置外部受保护信任根时，不得宣称结果在密码学意义上不可伪造。

package/src/approval-store.ts

@@ -0,0 +1,340 @@
+import { randomUUID } from "node:crypto";
+import type { Database } from "bun:sqlite";
+
+/**
+ * Core human-approval primitive (control.db, schema v3).
+ *
+ * `proposeApproval` may be reached from an agent tool. `confirmApproval` must
+ * only be called from the runtime extension's interactive UI callback: there
+ * is deliberately no CLI or agent-tool entry point for it.
+ */
+
+export const APPROVAL_KINDS = ["execution_plan", "environment_profile", "mode_override", "human_result"] as const;
+export type ApprovalKind = typeof APPROVAL_KINDS[number];
+export const HUMAN_RESULT_STATUSES = ["passed", "failed", "blocked"] as const;
+export type HumanResultStatus = typeof HUMAN_RESULT_STATUSES[number];
+export type ProposalStatus = "proposed" | "consumed" | "rejected" | "expired";
+
+/** An unconfirmed proposal older than this can no longer be confirmed. */
+export const PROPOSAL_TTL_MS = 24 * 60 * 60 * 1000;
+export const APPROVED_VIA = "runtime_ui_confirm";
+
+export type ApprovalErrorCode =
+  | "approval_requires_database_authority"
+  | "invalid_proposal"
+  | "invalid_decision"
+  | "proposal_not_found"
+  | "proposal_not_pending"
+  | "proposal_expired"
+  | "pins_unavailable"
+  | "pins_mismatch"
+  | "state_revision_mismatch";
+
+export class ApprovalError extends Error {
+  constructor(readonly code: ApprovalErrorCode, message: string) {
+    super(`${code}: ${message}`);
+    this.name = "ApprovalError";
+  }
+}
+
+export interface ProposalRecord {
+  id: string;
+  projectId: string;
+  feature: string;
+  kind: ApprovalKind;
+  subjectKey: string;
+  payload: Record<string, unknown>;
+  pins: Record<string, unknown>;
+  stateRevision: number;
+  status: ProposalStatus;
+  createdAt: string;
+  resolvedAt: string | null;
+}
+
+export interface ApprovalRecord {
+  id: string;
+  proposalId: string;
+  projectId: string;
+  feature: string;
+  kind: ApprovalKind;
+  subjectKey: string;
+  pins: Record<string, unknown>;
+  decision: Record<string, unknown>;
+  approvedVia: string;
+  approvedAt: string;
+  supersededAt: string | null;
+}
+
+export interface ProposeInput {
+  projectId: string;
+  feature: string;
+  kind: ApprovalKind;
+  subjectKey: string;
+  payload: Record<string, unknown>;
+  pins: Record<string, unknown>;
+  stateRevision: number;
+}
+
+export interface CurrentPins {
+  pins: Record<string, unknown>;
+  stateRevision: number;
+}
+
+export interface ConfirmInput {
+  projectId: string;
+  proposalId: string;
+  decision: Record<string, unknown>;
+  /**
+   * Recomputes the current pins for the stored proposal. It runs inside the
+   * write transaction (BEGIN IMMEDIATE), so it must be synchronous.
+   */
+  recompute: (proposal: ProposalRecord) => CurrentPins;
+  now?: Date;
+}
+
+export type ConfirmResult =
+  | { ok: true; approvalId: string; supersededIds: string[] }
+  | { ok: false; code: ApprovalErrorCode; message: string };
+
+/** Deterministic key-sorted JSON used to compare pins. */
+export function canonicalPinsJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonicalPinsJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value as Record<string, unknown>).sort().map(key => `${JSON.stringify(key)}:${canonicalPinsJson((value as Record<string, unknown>)[key])}`).join(",")}}`;
+  }
+  if (value === undefined) return "null";
+  return JSON.stringify(value);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function isKind(value: unknown): value is ApprovalKind {
+  return typeof value === "string" && (APPROVAL_KINDS as readonly string[]).includes(value);
+}
+
+const PIN_KEYS: Record<ApprovalKind, string[]> = {
+  execution_plan: ["dsl_sha256", "suite_fingerprint", "suite_graph_revision", "tc_sha256"],
+  environment_profile: ["profile_sha256"],
+  mode_override: ["binding_entry_sha256", "from", "suite_fingerprint", "tc_sha256", "to"],
+  human_result: ["evidence", "suite_fingerprint", "tc_sha256"],
+};
+
+/** Enforces the change-list §1.8 subject_key and pins_json shapes. */
+export function validatePinsShape(kind: ApprovalKind, subjectKey: string, pins: Record<string, unknown>): string[] {
+  const errors: string[] = [];
+  const keys = Object.keys(pins).sort();
+  if (canonicalPinsJson(keys) !== canonicalPinsJson(PIN_KEYS[kind])) errors.push(`${kind} pins must contain exactly: ${PIN_KEYS[kind].join(", ")}`);
+  if (kind === "environment_profile") {
+    if (!/^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/.test(subjectKey)) errors.push("environment_profile subject_key must be a profile name");
+  } else if (!/^TC-[A-Za-z0-9_-]+$/.test(subjectKey)) {
+    errors.push(`${kind} subject_key must be a TC id`);
+  }
+  for (const key of keys) {
+    const value = pins[key];
+    if (key.endsWith("sha256") || key === "suite_fingerprint") {
+      if (typeof value !== "string" || value.length === 0) errors.push(`pin ${key} must be a non-empty string`);
+    }
+  }
+  if (kind === "human_result") {
+    const evidence = pins.evidence;
+    if (!Array.isArray(evidence) || evidence.some(item => !isRecord(item) || typeof item.path !== "string" || typeof item.sha256 !== "string")) {
+      errors.push("human_result evidence pins must be [{path, sha256}]");
+    }
+  }
+  return errors;
+}
+
+/** Validates a UI decision; human_result verdicts must come from the user. */
+export function validateDecision(kind: ApprovalKind, decision: Record<string, unknown>, pins: Record<string, unknown>): string[] {
+  const errors: string[] = [];
+  if (kind === "human_result") {
+    const keys = Object.keys(decision).sort();
+    if (canonicalPinsJson(keys) !== canonicalPinsJson(["actual_result", "status"])) errors.push("human_result decision must contain exactly status and actual_result");
+    if (!(HUMAN_RESULT_STATUSES as readonly string[]).includes(String(decision.status))) errors.push("human_result status must be passed, failed, or blocked");
+    if (typeof decision.actual_result !== "string" || !decision.actual_result.trim()) errors.push("human_result actual_result is required");
+    if (decision.status === "passed" && (!Array.isArray(pins.evidence) || pins.evidence.length === 0)) errors.push("a passed human_result requires at least one pinned evidence file");
+  } else if (canonicalPinsJson(decision) !== canonicalPinsJson({ approved: true })) {
+    errors.push(`${kind} decision must be {approved: true}`);
+  }
+  return errors;
+}
+
+export function databaseAuthority(db: Database, projectId: string): string | null {
+  const row = db.query("SELECT authority FROM authority_state WHERE project_id=?").get(projectId) as { authority: string } | null;
+  return row?.authority ?? null;
+}
+
+function assertDatabaseAuthority(db: Database, projectId: string): void {
+  const authority = databaseAuthority(db, projectId);
+  if (authority !== "database") {
+    throw new ApprovalError("approval_requires_database_authority", `project authority is ${authority ?? "unregistered"}; approvals require database authority`);
+  }
+}
+
+function proposalFromRow(row: any): ProposalRecord {
+  return {
+    id: row.id, projectId: row.project_id, feature: row.feature, kind: row.kind, subjectKey: row.subject_key,
+    payload: JSON.parse(row.payload_json), pins: JSON.parse(row.pins_json), stateRevision: row.state_revision,
+    status: row.status, createdAt: row.created_at, resolvedAt: row.resolved_at ?? null,
+  };
+}
+
+function approvalFromRow(row: any): ApprovalRecord {
+  return {
+    id: row.id, proposalId: row.proposal_id, projectId: row.project_id, feature: row.feature, kind: row.kind,
+    subjectKey: row.subject_key, pins: JSON.parse(row.pins_json), decision: JSON.parse(row.decision_json),
+    approvedVia: row.approved_via, approvedAt: row.approved_at, supersededAt: row.superseded_at ?? null,
+  };
+}
+
+function validateProposeInput(input: ProposeInput): void {
+  if (!isKind(input.kind)) throw new ApprovalError("invalid_proposal", `unknown approval kind: ${String(input.kind)}`);
+  if (!input.feature || /[/\\\x00-\x1f\x7f]/.test(input.feature)) throw new ApprovalError("invalid_proposal", "feature must be a plain feature name");
+  if (!isRecord(input.payload)) throw new ApprovalError("invalid_proposal", "payload must be an object");
+  if (!isRecord(input.pins)) throw new ApprovalError("invalid_proposal", "pins must be an object");
+  if (!Number.isInteger(input.stateRevision) || input.stateRevision < 0) throw new ApprovalError("invalid_proposal", "state_revision must be a non-negative integer");
+  const shapeErrors = validatePinsShape(input.kind, input.subjectKey, input.pins);
+  if (shapeErrors.length) throw new ApprovalError("invalid_proposal", shapeErrors.join("; "));
+}
+
+/** Must run inside a write transaction; expires older open proposals for the subject, then inserts. */
+function insertProposal(db: Database, input: ProposeInput, timestamp: string): { proposalId: string; expiredIds: string[] } {
+  assertDatabaseAuthority(db, input.projectId);
+  const proposalId = randomUUID();
+  const open = db.query(`SELECT id FROM approval_proposals
+    WHERE project_id=? AND feature=? AND kind=? AND subject_key=? AND status='proposed'`).all(input.projectId, input.feature, input.kind, input.subjectKey) as Array<{ id: string }>;
+  for (const item of open) {
+    db.query("UPDATE approval_proposals SET status='expired',resolved_at=? WHERE id=? AND status='proposed'").run(timestamp, item.id);
+  }
+  db.query(`INSERT INTO approval_proposals(id,project_id,feature,kind,subject_key,payload_json,pins_json,state_revision,status,created_at,resolved_at)
+    VALUES (?,?,?,?,?,?,?,?,'proposed',?,NULL)`).run(
+    proposalId, input.projectId, input.feature, input.kind, input.subjectKey,
+    canonicalPinsJson(input.payload), canonicalPinsJson(input.pins), input.stateRevision, timestamp,
+  );
+  return { proposalId, expiredIds: open.map(item => item.id) };
+}
+
+/**
+ * Records a proposal with the pins observed at proposal time. An older open
+ * proposal for the same feature/kind/subject is expired so only the newest
+ * proposal can be confirmed.
+ */
+export function proposeApproval(db: Database, input: ProposeInput, options: { now?: Date } = {}): { proposalId: string; expiredIds: string[] } {
+  validateProposeInput(input);
+  const timestamp = (options.now ?? new Date()).toISOString();
+  return db.transaction(() => insertProposal(db, input, timestamp)).immediate();
+}
+
+/**
+ * All-or-nothing batch propose: every item is validated first, then all inserts and
+ * "expire older open proposal for the same subject" updates run in ONE immediate
+ * transaction that rolls back completely on any error.
+ */
+export function proposeApprovals(db: Database, inputs: ProposeInput[], options: { now?: Date } = {}): Array<{ proposalId: string; expiredIds: string[] }> {
+  if (!Array.isArray(inputs) || inputs.length === 0) throw new ApprovalError("invalid_proposal", "at least one proposal is required");
+  for (const input of inputs) validateProposeInput(input);
+  const timestamp = (options.now ?? new Date()).toISOString();
+  return db.transaction(() => inputs.map(input => insertProposal(db, input, timestamp))).immediate();
+}
+
+export function getProposal(db: Database, projectId: string, proposalId: string): ProposalRecord | null {
+  const row = db.query("SELECT * FROM approval_proposals WHERE id=? AND project_id=?").get(proposalId, projectId);
+  return row ? proposalFromRow(row) : null;
+}
+
+export function listProposals(db: Database, projectId: string, filter: { feature?: string; status?: ProposalStatus; kind?: ApprovalKind } = {}): ProposalRecord[] {
+  const clauses = ["project_id=?"]; const params: Array<string> = [projectId];
+  if (filter.feature) { clauses.push("feature=?"); params.push(filter.feature); }
+  if (filter.status) { clauses.push("status=?"); params.push(filter.status); }
+  if (filter.kind) { clauses.push("kind=?"); params.push(filter.kind); }
+  return (db.query(`SELECT * FROM approval_proposals WHERE ${clauses.join(" AND ")} ORDER BY created_at, id`).all(...params) as any[]).map(proposalFromRow);
+}
+
+export function listApprovals(db: Database, projectId: string, filter: { feature?: string; kind?: ApprovalKind; includeSuperseded?: boolean } = {}): ApprovalRecord[] {
+  const clauses = ["project_id=?"]; const params: Array<string> = [projectId];
+  if (filter.feature) { clauses.push("feature=?"); params.push(filter.feature); }
+  if (filter.kind) { clauses.push("kind=?"); params.push(filter.kind); }
+  if (!filter.includeSuperseded) clauses.push("superseded_at IS NULL");
+  // approved_at has millisecond precision, so confirmations in one transaction
+  // window can tie. rowid preserves the actual append order; UUID ordering does not.
+  return (db.query(`SELECT * FROM approvals WHERE ${clauses.join(" AND ")} ORDER BY approved_at, rowid`).all(...params) as any[]).map(approvalFromRow);
+}
+
+/** The user declined the proposal in the UI; it can never be confirmed afterwards. */
+export function rejectProposal(db: Database, projectId: string, proposalId: string, options: { now?: Date } = {}): boolean {
+  const timestamp = (options.now ?? new Date()).toISOString();
+  return db.query("UPDATE approval_proposals SET status='rejected',resolved_at=? WHERE id=? AND project_id=? AND status='proposed'")
+    .run(timestamp, proposalId, projectId).changes === 1;
+}
+
+export function proposalIsExpired(proposal: Pick<ProposalRecord, "createdAt">, now = new Date()): boolean {
+  const created = Date.parse(proposal.createdAt);
+  return !Number.isFinite(created) || now.getTime() - created > PROPOSAL_TTL_MS;
+}
+
+/**
+ * Confirms one proposal in a single IMMEDIATE transaction: re-checks database
+ * authority, proposal state and TTL, recomputes the pins (CAS), inserts the
+ * approval, consumes the proposal and supersedes the previous approval for the
+ * same feature/kind/subject. Stale or expired proposals are marked expired and
+ * the call fails; nothing else is written in that case.
+ */
+export function confirmApproval(db: Database, input: ConfirmInput): ConfirmResult {
+  const now = input.now ?? new Date();
+  const timestamp = now.toISOString();
+  const expire = (proposalId: string) => {
+    db.query("UPDATE approval_proposals SET status='expired',resolved_at=? WHERE id=? AND status='proposed'").run(timestamp, proposalId);
+  };
+  const transaction = db.transaction((): ConfirmResult => {
+    const authority = databaseAuthority(db, input.projectId);
+    if (authority !== "database") {
+      return { ok: false, code: "approval_requires_database_authority", message: `project authority is ${authority ?? "unregistered"}` };
+    }
+    const row = db.query("SELECT * FROM approval_proposals WHERE id=? AND project_id=?").get(input.proposalId, input.projectId);
+    if (!row) return { ok: false, code: "proposal_not_found", message: `unknown proposal: ${input.proposalId}` };
+    const proposal = proposalFromRow(row);
+    if (proposal.status !== "proposed") return { ok: false, code: "proposal_not_pending", message: `proposal is ${proposal.status}` };
+    if (proposalIsExpired(proposal, now)) {
+      expire(proposal.id);
+      return { ok: false, code: "proposal_expired", message: "proposal is older than the confirmation window; propose again" };
+    }
+    const decisionErrors = isRecord(input.decision) ? validateDecision(proposal.kind, input.decision, proposal.pins) : ["decision must be an object"];
+    if (decisionErrors.length) return { ok: false, code: "invalid_decision", message: decisionErrors.join("; ") };
+    let current: CurrentPins;
+    try {
+      current = input.recompute(proposal);
+    } catch (error) {
+      return { ok: false, code: "pins_unavailable", message: error instanceof Error ? error.message : String(error) };
+    }
+    if (!current || !isRecord(current.pins) || canonicalPinsJson(current.pins) !== canonicalPinsJson(proposal.pins)) {
+      expire(proposal.id);
+      return { ok: false, code: "pins_mismatch", message: "suite, TC, binding, DSL, profile or evidence changed since the proposal; propose again" };
+    }
+    if (current.stateRevision !== proposal.stateRevision) {
+      expire(proposal.id);
+      return { ok: false, code: "state_revision_mismatch", message: `workflow state revision changed from ${proposal.stateRevision} to ${current.stateRevision}; propose again` };
+    }
+    const superseded = db.query(`SELECT id FROM approvals
+      WHERE project_id=? AND feature=? AND kind=? AND subject_key=? AND superseded_at IS NULL`).all(proposal.projectId, proposal.feature, proposal.kind, proposal.subjectKey) as Array<{ id: string }>;
+    for (const item of superseded) {
+      db.query("UPDATE approvals SET superseded_at=? WHERE id=? AND superseded_at IS NULL").run(timestamp, item.id);
+    }
+    const approvalId = randomUUID();
+    db.query(`INSERT INTO approvals(id,proposal_id,project_id,feature,kind,subject_key,pins_json,decision_json,approved_via,approved_at,superseded_at)
+      VALUES (?,?,?,?,?,?,?,?,?,?,NULL)`).run(
+      approvalId, proposal.id, proposal.projectId, proposal.feature, proposal.kind, proposal.subjectKey,
+      canonicalPinsJson(proposal.pins), canonicalPinsJson(input.decision), APPROVED_VIA, timestamp,
+    );
+    const consumed = db.query("UPDATE approval_proposals SET status='consumed',resolved_at=? WHERE id=? AND status='proposed'").run(timestamp, proposal.id);
+    if (consumed.changes !== 1) throw new ApprovalError("proposal_not_pending", "proposal was consumed concurrently");
+    return { ok: true, approvalId, supersededIds: superseded.map(item => item.id) };
+  });
+  try {
+    return transaction.immediate();
+  } catch (error) {
+    if (error instanceof ApprovalError) return { ok: false, code: error.code, message: error.message };
+    throw error;
+  }
+}

package/src/constants.ts

@@ -1,5 +1,5 @@
 export const PRODUCT_NAME = "Devflow Pi";
-export const PRODUCT_VERSION = "0.1.94";
+export const PRODUCT_VERSION = "0.1.95";
 export const PROJECT_SCHEMA_VERSION = 1;
 export const OMP_RUNTIME_VERSION = "17.2.7";