@farmslot/protocol 0.37.0 → 0.39.0

package/schemas/recipe-v1.schema.json

@@ -40,6 +40,19 @@
             "type": "string",
             "minLength": 1,
             "description": "Human-readable statement that successful linked nodes establish."
+          },
+          "kind": {
+            "enum": ["acceptance", "qa-case", "qa-check"],
+            "description": "Acceptance criterion, QA case or QA check proved by the recipe."
+          },
+          "parentId": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Registered parent claim whose outcome includes this required check."
+          },
+          "proofMode": {
+            "enum": ["state", "visual", "mixed"],
+            "description": "State assertions, visual review, or both are required to prove this claim."
           }
         },
         "additionalProperties": false
@@ -67,14 +80,21 @@
         "required": {
           "type": "array",
           "description": "Parameter names callers must provide when no default satisfies them.",
-          "items": { "type": "string", "minLength": 1 },
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
           "uniqueItems": true
         },
         "properties": {
           "type": "object",
           "description": "Named parameter definitions available to callers and call nodes.",
-          "propertyNames": { "pattern": "^[A-Za-z0-9_-]+$" },
-          "additionalProperties": { "$ref": "#/$defs/paramSchema" }
+          "propertyNames": {
+            "pattern": "^[A-Za-z0-9_-]+$"
+          },
+          "additionalProperties": {
+            "$ref": "#/$defs/paramSchema"
+          }
         }
       },
       "additionalProperties": false
@@ -86,10 +106,14 @@
         "type": {
           "description": "Allowed JSON value type or types for this parameter.",
           "oneOf": [
-            { "enum": ["string", "number", "integer", "boolean", "object", "array"] },
+            {
+              "enum": ["string", "number", "integer", "boolean", "object", "array"]
+            },
             {
               "type": "array",
-              "items": { "enum": ["string", "number", "integer", "boolean", "object", "array"] },
+              "items": {
+                "enum": ["string", "number", "integer", "boolean", "object", "array"]
+              },
               "minItems": 1,
               "uniqueItems": true
             }
@@ -115,14 +139,21 @@
         "required": {
           "type": "array",
           "description": "Required keys within an object parameter.",
-          "items": { "type": "string", "minLength": 1 },
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
           "uniqueItems": true
         },
         "properties": {
           "type": "object",
           "description": "Named child schemas for an object parameter.",
-          "propertyNames": { "pattern": "^[A-Za-z0-9_-]+$" },
-          "additionalProperties": { "$ref": "#/$defs/paramSchema" }
+          "propertyNames": {
+            "pattern": "^[A-Za-z0-9_-]+$"
+          },
+          "additionalProperties": {
+            "$ref": "#/$defs/paramSchema"
+          }
         },
         "items": {
           "$ref": "#/$defs/paramSchema",
@@ -152,7 +183,10 @@
     },
     "proofLinks": {
       "type": "array",
-      "items": { "type": "string", "minLength": 1 },
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
       "uniqueItems": true
     },
     "transition": {
@@ -166,7 +200,16 @@
               "description": "Node id to execute after this node succeeds."
             }
           },
-          "not": { "anyOf": [{ "required": ["cases"] }, { "required": ["default"] }] }
+          "not": {
+            "anyOf": [
+              {
+                "required": ["cases"]
+              },
+              {
+                "required": ["default"]
+              }
+            ]
+          }
         },
         {
           "required": ["cases", "default"],
@@ -174,7 +217,10 @@
             "cases": {
               "type": "object",
               "minProperties": 1,
-              "additionalProperties": { "type": "string", "minLength": 1 },
+              "additionalProperties": {
+                "type": "string",
+                "minLength": 1
+              },
               "description": "Maps an action result case to the next node id."
             },
             "default": {
@@ -183,7 +229,9 @@
               "description": "Node id used when no declared result case matches."
             }
           },
-          "not": { "required": ["next"] }
+          "not": {
+            "required": ["next"]
+          }
         }
       ]
     },
@@ -194,7 +242,9 @@
         "action": {
           "type": "string",
           "minLength": 1,
-          "not": { "enum": ["call", "end"] },
+          "not": {
+            "enum": ["call", "end"]
+          },
           "description": "Registered action name to execute; action-specific fields are declared by its manifest."
         },
         "intent": {
@@ -210,7 +260,10 @@
         "cases": {
           "type": "object",
           "minProperties": 1,
-          "additionalProperties": { "type": "string", "minLength": 1 },
+          "additionalProperties": {
+            "type": "string",
+            "minLength": 1
+          },
           "description": "Maps an action result case to the next node id."
         },
         "default": {
@@ -225,9 +278,24 @@
         "visual_review": {
           "$ref": "#/$defs/visualReviewRelationship",
           "description": "Optional visual-review hierarchy and related-surface links for ui.capture_surface and ui.screenshot nodes."
+        },
+        "retryGroup": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Declared retry identity; earlier failed attempts remain in the trace."
+        },
+        "retryAttempts": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 3,
+          "description": "Maximum attempts for a declared retry, including the first execution."
         }
       },
-      "allOf": [{ "$ref": "#/$defs/transition" }],
+      "allOf": [
+        {
+          "$ref": "#/$defs/transition"
+        }
+      ],
       "additionalProperties": true
     },
     "visualReviewRelationship": {
@@ -261,7 +329,10 @@
         },
         "related": {
           "type": "array",
-          "items": { "type": "string", "minLength": 1 },
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
           "uniqueItems": true,
           "description": "Related visual capture node ids within this recipe."
         }
@@ -284,7 +355,9 @@
         "ref": {
           "type": "string",
           "minLength": 1,
-          "not": { "pattern": "\\{\\{\\s*(?:params|outputs)\\." },
+          "not": {
+            "pattern": "\\{\\{\\s*(?:params|outputs)\\."
+          },
           "description": "Static recipe id resolved from configured recipe libraries."
         },
         "params": {
@@ -299,6 +372,14 @@
           "type": "string",
           "minLength": 1,
           "description": "Node id to execute after the called recipe succeeds."
+        },
+        "claimBindings": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string",
+            "minLength": 1
+          },
+          "description": "Map declared child claims to registered parent claims; unbound child ids are qualified by this call."
         }
       },
       "additionalProperties": false
@@ -320,9 +401,15 @@
     },
     "workflowNode": {
       "oneOf": [
-        { "$ref": "#/$defs/actionNode" },
-        { "$ref": "#/$defs/callNode" },
-        { "$ref": "#/$defs/endNode" }
+        {
+          "$ref": "#/$defs/actionNode"
+        },
+        {
+          "$ref": "#/$defs/callNode"
+        },
+        {
+          "$ref": "#/$defs/endNode"
+        }
       ]
     },
     "workflow": {
@@ -342,8 +429,12 @@
         "nodes": {
           "type": "object",
           "minProperties": 1,
-          "propertyNames": { "pattern": "^[A-Za-z0-9_-]+$" },
-          "additionalProperties": { "$ref": "#/$defs/workflowNode" },
+          "propertyNames": {
+            "pattern": "^[A-Za-z0-9_-]+$"
+          },
+          "additionalProperties": {
+            "$ref": "#/$defs/workflowNode"
+          },
           "description": "Named action, recipe-call, and terminal nodes in the executable graph."
         }
       },

package/scripts/acceptance.d.mts

@@ -0,0 +1,16 @@
+export const ACCEPTANCE_STATUS_ARTIFACT: 'artifacts/acceptance-status.json';
+export const ACCEPTANCE_VERDICTS: readonly [
+  'proven',
+  'weak',
+  'missing',
+  'untestable',
+  'failed',
+  'awaiting-review',
+];
+export const ACCEPTANCE_PROOF_MODES: readonly ['state', 'visual', 'mixed'];
+export const ACCEPTANCE_CRITERION_ID_PATTERN: RegExp;
+export function acceptanceCriterionId(index: number): string;
+export function validateAcceptanceStatusLedger(value: unknown): string[];
+export function acceptanceCriteriaView(criteria: readonly unknown[], ledger: unknown): unknown[];
+export function summarizeAcceptanceStatus(ledger: unknown, criteria?: readonly unknown[]): unknown;
+export function renderAcceptanceCoverage(ledger: unknown, criteria?: readonly unknown[]): string;

package/scripts/acceptance.mjs

@@ -0,0 +1,233 @@
+// Portable acceptance contract. Operator scripts and clients consume the same implementation.
+const ACCEPTANCE_STATUS_ARTIFACT = 'artifacts/acceptance-status.json';
+const ACCEPTANCE_VERDICTS = [
+  'proven',
+  'weak',
+  'missing',
+  'untestable',
+  'failed',
+  'awaiting-review',
+];
+const ACCEPTANCE_PROOF_MODES = ['state', 'visual', 'mixed'];
+const ACCEPTANCE_CRITERION_ID_PATTERN = /^AC-[1-9][0-9]*$/;
+
+function acceptanceCriterionId(index) {
+  return `AC-${index + 1}`;
+}
+
+function isRecord(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function validateAcceptanceStatusLedger(value) {
+  const issues = [];
+  if (!isRecord(value)) return ['acceptance ledger: expected object'];
+  if (value.schemaVersion !== 1 && value.schemaVersion !== 2)
+    issues.push('acceptance ledger schemaVersion: expected 1 or 2');
+  if (value.schemaVersion === 2 && !isNonEmptyString(value.recipeRunId))
+    issues.push('acceptance ledger recipeRunId: expected execution identity');
+  if (value.schemaVersion === 2) {
+    const recording = value.recording;
+    if (
+      !isRecord(recording) ||
+      ![
+        'not-required',
+        'explicit-off',
+        'recording',
+        'finalizing',
+        'complete',
+        'incomplete',
+        'failed',
+      ].includes(recording.status) ||
+      !Array.isArray(recording.segments) ||
+      recording.segments.some(
+        (segment) =>
+          !isRecord(segment) ||
+          !isNonEmptyString(segment.videoPath) ||
+          !/^sha256:[a-f0-9]{64}$/.test(segment.videoDigest),
+      )
+    )
+      issues.push('acceptance ledger recording: invalid capture state or segments');
+  }
+  if (!Array.isArray(value.criteria)) {
+    issues.push('acceptance ledger criteria: expected array');
+    return issues;
+  }
+  if (
+    value.schemaVersion === 2 &&
+    value.judgments !== undefined &&
+    (!Array.isArray(value.judgments) ||
+      value.judgments.some(
+        (judgment) =>
+          !isRecord(judgment) ||
+          judgment.recipeRunId !== value.recipeRunId ||
+          !isNonEmptyString(judgment.claimId) ||
+          !['confirmed', 'rejected'].includes(judgment.verdict) ||
+          !isNonEmptyString(judgment.actor) ||
+          !isNonEmptyString(judgment.reason) ||
+          !Number.isFinite(Date.parse(judgment.judgedAt)) ||
+          !Array.isArray(judgment.moments),
+      ))
+  )
+    issues.push('acceptance ledger judgments: invalid visual review');
+  const seen = new Set();
+  value.criteria.forEach((entry, index) => {
+    const prefix = `acceptance ledger criteria[${index}]`;
+    if (!isRecord(entry)) {
+      issues.push(`${prefix}: expected object`);
+      return;
+    }
+    if (
+      !isNonEmptyString(entry.id) ||
+      (value.schemaVersion === 1 && !ACCEPTANCE_CRITERION_ID_PATTERN.test(entry.id))
+    ) {
+      issues.push(`${prefix}.id: expected AC-<N>`);
+    } else if (seen.has(entry.id)) {
+      issues.push(`${prefix}.id: duplicate ${entry.id}`);
+    } else {
+      seen.add(entry.id);
+    }
+    if (typeof entry.text !== 'string') issues.push(`${prefix}.text: expected string`);
+    if (!ACCEPTANCE_VERDICTS.includes(entry.verdict)) {
+      issues.push(`${prefix}.verdict: expected one of ${ACCEPTANCE_VERDICTS.join(', ')}`);
+    }
+    if (entry.proofMode !== undefined && !ACCEPTANCE_PROOF_MODES.includes(entry.proofMode)) {
+      issues.push(`${prefix}.proofMode: expected one of ${ACCEPTANCE_PROOF_MODES.join(', ')}`);
+    }
+    for (const key of ['evidence', 'recipeNodes']) {
+      const list = entry[key];
+      if (!Array.isArray(list) || list.some((item) => !isNonEmptyString(item))) {
+        issues.push(`${prefix}.${key}: expected an array of non-empty strings`);
+      }
+    }
+    if (value.schemaVersion === 2) {
+      if (!['acceptance', 'qa-case', 'qa-check'].includes(entry.kind))
+        issues.push(`${prefix}.kind: invalid claim kind`);
+      if (!ACCEPTANCE_PROOF_MODES.includes(entry.proofMode))
+        issues.push(`${prefix}.proofMode: required`);
+      if (
+        !Array.isArray(entry.assertionIndices) ||
+        entry.assertionIndices.some((index) => !Number.isInteger(index) || index < 0)
+      )
+        issues.push(`${prefix}.assertionIndices: invalid trace references`);
+      if (
+        !Array.isArray(entry.moments) ||
+        entry.moments.some(
+          (moment) =>
+            !isRecord(moment) ||
+            moment.recipeRunId !== value.recipeRunId ||
+            !/^sha256:[a-f0-9]{64}$/.test(moment.videoDigest) ||
+            !Number.isInteger(moment.traceIndex) ||
+            moment.traceIndex < 0,
+        )
+      )
+        issues.push(`${prefix}.moments: invalid moment references`);
+    }
+    if (entry.note !== undefined && typeof entry.note !== 'string') {
+      issues.push(`${prefix}.note: expected string`);
+    }
+    if (value.schemaVersion === 1 && !isNonEmptyString(entry.updatedAt)) {
+      issues.push(`${prefix}.updatedAt: expected non-empty string`);
+    }
+  });
+  return issues;
+}
+
+function acceptanceCriteriaView(criteria, ledger) {
+  const byId = new Map((ledger?.criteria ?? []).map((entry) => [entry.id, entry]));
+  const rows = criteria.map((criterion) => ({
+    ...criterion,
+    status: byId.get(criterion.id) ?? null,
+  }));
+  for (const entry of ledger?.criteria ?? []) {
+    if (!criteria.some((criterion) => criterion.id === entry.id)) {
+      rows.push({ id: entry.id, text: entry.text, status: entry });
+    }
+  }
+  return rows;
+}
+
+function summarizeAcceptanceStatus(ledger, criteria) {
+  const total = criteria
+    ? Math.max(criteria.length, ledger.criteria.length)
+    : ledger.criteria.length;
+  const summary = {
+    proven: 0,
+    weak: 0,
+    failed: 0,
+    'awaiting-review': 0,
+    missing: 0,
+    untestable: 0,
+    unrecorded: 0,
+    total,
+  };
+  for (const criterion of ledger.criteria) summary[criterion.verdict] += 1;
+  summary.unrecorded =
+    total - ACCEPTANCE_VERDICTS.reduce((count, verdict) => count + summary[verdict], 0);
+  return summary;
+}
+
+function cell(value) {
+  return (
+    value
+      .replace(/\|/g, '\\|')
+      .replace(/\s*\n\s*/g, ' ')
+      .trim() || '-'
+  );
+}
+
+function list(values) {
+  return values.length > 0 ? cell(values.join(', ')) : '-';
+}
+
+function renderAcceptanceCoverage(ledger, criteria = ledger.criteria) {
+  const summary = summarizeAcceptanceStatus(ledger, criteria);
+  const rows = acceptanceCriteriaView(criteria, ledger);
+  const untestable = ledger.criteria
+    .filter((criterion) => criterion.verdict === 'untestable')
+    .map((criterion) => criterion.id);
+  const lines = [
+    '## Recipe coverage',
+    '',
+    '| AC | Criterion | Verdict | Proof mode | Recipe nodes | Evidence | Note |',
+    '| --- | --- | --- | --- | --- | --- | --- |',
+  ];
+  for (const row of rows) {
+    const status = row.status;
+    lines.push(
+      `| ${row.id} | ${cell(row.text)} | ${status ? status.verdict.toUpperCase() : 'NO VERDICT'} | ` +
+        `${status?.proofMode ?? '-'} | ${list(status?.recipeNodes ?? [])} | ` +
+        `${list(status?.evidence ?? [])} | ${cell(status?.note ?? '')} |`,
+    );
+  }
+  lines.push(
+    '',
+    `Overall recipe coverage: ${summary.proven}/${summary.total} ACs PROVEN ` +
+      `(untestable: ${untestable.length > 0 ? untestable.join(', ') : 'none'}, ` +
+      `weak: ${summary.weak}, missing: ${summary.missing}` +
+      (summary.failed ? `, failed: ${summary.failed}` : '') +
+      (summary['awaiting-review'] ? `, awaiting review: ${summary['awaiting-review']}` : '') +
+      `${summary.unrecorded > 0 ? `, no verdict: ${summary.unrecorded}` : ''})`,
+    '',
+  );
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// task-dir IO
+
+export {
+  ACCEPTANCE_CRITERION_ID_PATTERN,
+  ACCEPTANCE_PROOF_MODES,
+  ACCEPTANCE_STATUS_ARTIFACT,
+  ACCEPTANCE_VERDICTS,
+  acceptanceCriteriaView,
+  acceptanceCriterionId,
+  renderAcceptanceCoverage,
+  summarizeAcceptanceStatus,
+  validateAcceptanceStatusLedger,
+};