@sublang/playbook 13.3.0 → 14.1.0

package/slc/workflow-contracts.json

@@ -0,0 +1,371 @@
+{
+  "schema": "sublang.playbook.workflow-contracts.v1",
+  "package": "@sublang/playbook",
+  "artifactSchema": 3,
+  "runtimeAbi": 1,
+  "description": "Public output interfaces for the packaged builtin workflows. The selected pipeline declares literalTargetBindings as its default nested-target namespace; explicit Source or compiler-dependency bindings override defaults and require their own interfaces. Hosts must honor the compiled bindings. Child output fields retain child-owned authority, while the shared envelope and terminal kind govern transport and authored failure; a local basename alone establishes no binding.",
+  "$defs": {
+    "compactError": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "message": {
+          "type": "string"
+        }
+      },
+      "required": ["name", "message"],
+      "additionalProperties": false
+    },
+    "json": {
+      "anyOf": [
+        {
+          "type": "null"
+        },
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "number"
+        },
+        {
+          "type": "string"
+        },
+        {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/json"
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/$defs/json"
+          }
+        }
+      ]
+    },
+    "completedCodeResult": {
+      "anyOf": [
+        {
+          "type": "object",
+          "properties": {
+            "playbookId": {
+              "const": "code"
+            },
+            "status": {
+              "const": "ok"
+            },
+            "output": {
+              "$ref": "#/$defs/json"
+            }
+          },
+          "required": ["playbookId", "status"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "playbookId": {
+              "const": "code"
+            },
+            "status": {
+              "enum": ["aborted", "error"]
+            },
+            "error": {
+              "$ref": "#/$defs/compactError"
+            }
+          },
+          "required": ["playbookId", "status", "error"],
+          "additionalProperties": false
+        }
+      ]
+    }
+  },
+  "workflows": {
+    "review": {
+      "callInput": "text",
+      "output": {
+        "type": "object",
+        "properties": {
+          "noUnsettledFindings": {
+            "const": true
+          },
+          "evaluatedRevision": {
+            "type": "string",
+            "description": "Exact receipt-observed repository revision evaluated by the final clean review round; it can include REVIEW-owned fixes after the caller's original commit."
+          }
+        },
+        "required": ["noUnsettledFindings", "evaluatedRevision"],
+        "additionalProperties": false
+      }
+    },
+    "decide": {
+      "callInput": "text",
+      "output": {
+        "anyOf": [
+          {
+            "type": "object",
+            "properties": {
+              "decideCommit": {
+                "type": "string",
+                "description": "Exact DECIDE-owned commit."
+              },
+              "evaluatedRevision": {
+                "type": "string",
+                "description": "Exact repository revision evaluated by the final passing review."
+              },
+              "noUnsettledFindings": {
+                "const": true
+              }
+            },
+            "required": [
+              "decideCommit",
+              "evaluatedRevision",
+              "noUnsettledFindings"
+            ],
+            "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "properties": {
+              "lastDecideCommit": {
+                "type": "string",
+                "description": "Exact last DECIDE-owned commit."
+              },
+              "noUnsettledFindings": {
+                "const": false
+              },
+              "reviewStatus": {
+                "enum": ["aborted", "error"]
+              },
+              "error": {
+                "$ref": "#/$defs/compactError"
+              }
+            },
+            "required": [
+              "lastDecideCommit",
+              "noUnsettledFindings",
+              "reviewStatus"
+            ],
+            "additionalProperties": false
+          }
+        ]
+      }
+    },
+    "code": {
+      "callInput": "text",
+      "output": {
+        "anyOf": [
+          {
+            "type": "object",
+            "properties": {
+              "status": {
+                "const": "complete"
+              },
+              "lastCodeCommit": {
+                "type": "string",
+                "description": "Exact last CODE-owned commit; excludes REVIEW-owned fix commits."
+              },
+              "finalEvaluatedRevision": {
+                "type": "string",
+                "description": "Exact repository revision evaluated by the final passing review; it may differ from lastCodeCommit."
+              },
+              "allReviewsPassed": {
+                "const": true
+              }
+            },
+            "required": [
+              "status",
+              "lastCodeCommit",
+              "finalEvaluatedRevision",
+              "allReviewsPassed"
+            ],
+            "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "properties": {
+              "status": {
+                "const": "review-failed"
+              },
+              "lastCodeCommit": {
+                "type": "string",
+                "description": "Exact last CODE-owned commit."
+              },
+              "error": {
+                "$ref": "#/$defs/compactError"
+              }
+            },
+            "required": ["status", "lastCodeCommit", "error"],
+            "additionalProperties": false
+          }
+        ]
+      }
+    },
+    "branch": {
+      "callInput": "text",
+      "output": {
+        "anyOf": [
+          {
+            "type": "object",
+            "properties": {
+              "status": {
+                "const": "branched"
+              },
+              "branch": {
+                "type": "string",
+                "description": "Exact new branch name."
+              },
+              "baseRevision": {
+                "type": "string",
+                "description": "Exact receipt-observed repository revision the branch was created from."
+              },
+              "issueSummary": {
+                "type": "string",
+                "description": "Concise issue-and-comments or request summary."
+              }
+            },
+            "required": ["status", "branch", "baseRevision", "issueSummary"],
+            "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "properties": {
+              "status": {
+                "const": "refused"
+              },
+              "coderOutput": {
+                "type": "string",
+                "description": "Complete refusal report."
+              }
+            },
+            "required": ["status", "coderOutput"],
+            "additionalProperties": false
+          }
+        ]
+      }
+    },
+    "pr": {
+      "callInput": "text",
+      "output": {
+        "anyOf": [
+          {
+            "type": "object",
+            "properties": {
+              "status": {
+                "const": "merged"
+              },
+              "pullRequest": {
+                "type": "string",
+                "description": "Exact pull request number as reported."
+              },
+              "pullRequestUrl": {
+                "type": "string",
+                "description": "Exact pull request URL as reported."
+              },
+              "localDefaultUpdated": {
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "status",
+              "pullRequest",
+              "pullRequestUrl",
+              "localDefaultUpdated"
+            ],
+            "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "properties": {
+              "status": {
+                "const": "not-merged"
+              },
+              "reason": {
+                "const": "not-published"
+              },
+              "coderOutput": {
+                "type": "string",
+                "description": "Complete report explaining why publication did not occur."
+              }
+            },
+            "required": ["status", "reason", "coderOutput"],
+            "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "properties": {
+              "status": {
+                "const": "not-merged"
+              },
+              "reason": {
+                "const": "fix-failed"
+              },
+              "pullRequest": {
+                "type": "string"
+              },
+              "pullRequestUrl": {
+                "type": "string"
+              },
+              "childResult": {
+                "$ref": "#/$defs/completedCodeResult"
+              }
+            },
+            "required": [
+              "status",
+              "reason",
+              "pullRequest",
+              "pullRequestUrl",
+              "childResult"
+            ],
+            "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "properties": {
+              "status": {
+                "const": "not-merged"
+              },
+              "reason": {
+                "enum": ["fix-not-published", "checks-failed"]
+              },
+              "pullRequest": {
+                "type": "string"
+              },
+              "pullRequestUrl": {
+                "type": "string"
+              }
+            },
+            "required": ["status", "reason", "pullRequest", "pullRequestUrl"],
+            "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "properties": {
+              "status": {
+                "const": "merge-unconfirmed"
+              },
+              "pullRequest": {
+                "type": "string"
+              },
+              "pullRequestUrl": {
+                "type": "string"
+              }
+            },
+            "required": ["status", "pullRequest", "pullRequestUrl"],
+            "additionalProperties": false
+          }
+        ]
+      }
+    }
+  },
+  "literalTargetBindings": {
+    "review": "review",
+    "decide": "decide",
+    "code": "code",
+    "branch": "branch",
+    "pr": "pr"
+  }
+}

package/src/runtime.d.ts

@@ -32,10 +32,65 @@ export interface CaptainResult {
 export type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
     readonly [key: string]: JsonValue;
 };
+export declare const PLAYBOOK_FAILURE_CODES: readonly ["commit-missing", "commit-residual", "pre-existing-lost", "commits-more-than-one", "history-rewritten", "foreign-change", "observation-unstable", "attribution-ambiguous", "receipt-missing", "judge-failed", "player-failed", "aborted", "child-failed", "runtime-defect"];
+export type PlaybookFailureCode = (typeof PLAYBOOK_FAILURE_CODES)[number];
+/** The bounded path lists one failure code's evidence may carry (DR-063 §1). */
+export interface PlaybookFailurePaths {
+    /** Paths changed in the worktree that no commit carries. */
+    readonly uncommitted?: readonly string[];
+    /** Pre-existing baseline paths the call changed before committing. */
+    readonly altered?: readonly string[];
+    /** Pre-existing baseline paths whose content is nowhere. */
+    readonly lost?: readonly string[];
+    /** Paths whose entry differs or is missing on either side. */
+    readonly changed?: readonly string[];
+    /** Paths omitted from the lists above by the 32-path bound. */
+    readonly truncated?: number;
+}
+/** The bounded error record a failure cause may carry (DR-063 §1). */
+export interface PlaybookFailureErrorEvidence {
+    readonly name: string;
+    readonly message: string;
+}
+/** The closed evidence object of one failure cause (DR-063 §1). */
+export interface PlaybookFailureEvidence {
+    readonly required?: PlaybookRepositoryDisposition;
+    readonly observed?: PlaybookRepositoryReceipt['classification'];
+    readonly baselineHead?: string;
+    readonly afterHead?: string;
+    readonly commitOid?: string;
+    readonly paths?: PlaybookFailurePaths;
+    readonly reason?: string;
+    readonly error?: PlaybookFailureErrorEvidence;
+    readonly errorCode?: string;
+    readonly roleId?: string;
+    readonly playerId?: string;
+    readonly playbookId?: string;
+    readonly cause?: PlaybookFailureCause;
+}
+/**
+ * Why a parked workflow failed (DR-063 §1): one code from the closed list and
+ * the closed evidence object that code names. Evidence holds repository paths,
+ * dispositions, classifications, and revision identities only — never file
+ * content, player prose, or internal call and session identities.
+ */
+export interface PlaybookFailureCause {
+    readonly code: PlaybookFailureCode;
+    readonly evidence: PlaybookFailureEvidence;
+}
+/**
+ * Validate, detach, and freeze one failure cause (DR-063 §1). The check is
+ * closed per code: exactly the evidence members that code names, nothing else,
+ * and a `child-failed` cause nests at most four deep. A value this rejects is
+ * not a cause, so a caller omits it rather than publishing an invented one.
+ */
+export declare function assertPlaybookFailureCause(value: unknown): PlaybookFailureCause;
 export interface NormalizedError {
     name: string;
     message: string;
     stack?: string;
+    /** DR-063 §2: present exactly when the underlying error carried a valid one. */
+    cause?: PlaybookFailureCause;
 }
 export type PlaybookStateValue = string | {
     readonly [key: string]: PlaybookStateValue;
@@ -181,12 +236,23 @@ export interface PlaybookRepositoryObservation {
     readonly projection: Readonly<Record<string, JsonValue>>;
     readonly projectionDigest: string;
 }
+/**
+ * The fate of the baseline projection entries a governed call absorbed into
+ * its one commit, altered, or lost (DR-062). Each list holds sorted unique
+ * baseline paths and the three are pairwise disjoint.
+ */
+export interface PlaybookRepositoryPreExistingChanges {
+    readonly absorbed: readonly string[];
+    readonly altered: readonly string[];
+    readonly lost: readonly string[];
+}
 /** The fail-closed classification of one complete physical or logical receipt. */
 export interface PlaybookRepositoryReceipt {
     readonly classification: 'unchanged' | 'one-descendant-commit' | 'multiple-commits' | 'rewritten-or-non-descendant' | 'worktree-only-change' | 'concurrent-or-foreign-change' | 'observation-ambiguous';
     readonly baseline: PlaybookRepositoryObservation;
     readonly after?: PlaybookRepositoryObservation;
     readonly commitOid?: string;
+    readonly preExisting?: PlaybookRepositoryPreExistingChanges;
 }
 /** One durably ordered physical governed-player boundary (DR-040). */
 export interface PlaybookEffectBoundary {
@@ -324,9 +390,13 @@ export interface PlaybookRuntimeSnapshot {
     };
     suspendedCall?: PlaybookSuspendedCall;
 }
+export type PlaybookControlStanding = 'ready' | 'no-op' | 'blocked';
+export type PlaybookControlActionReason = 'receipt-complete';
 export interface PlaybookControlAction {
     id: string;
     label: string;
+    standing?: PlaybookControlStanding;
+    reason?: PlaybookControlActionReason;
 }
 export interface PlaybookControlView {
     state: PlaybookState;