@naxodev/apnea 0.2.0 → 0.2.2

package/schemas/state.schema.json

@@ -5,8 +5,21 @@
   "type": "object",
   "additionalProperties": false,
   "required": ["version", "slug", "step", "phase_index", "rounds", "vcs"],
+  "allOf": [
+    {
+      "if": {
+        "properties": { "version": { "const": 2 } },
+        "required": ["version"]
+      },
+      "then": { "required": ["pending_commit"] },
+      "description": "Runtime enforcement is authoritative: decodeRunState applies the same rule plus consistency checks the JSON Schema cannot express."
+    }
+  ],
   "properties": {
-    "version": { "const": 1 },
+    "version": {
+      "enum": [1, 2],
+      "description": "Version 1 is accepted INPUT for migration (decodes with pending_commit=null); version 2 is the OUTPUT every save writes and must carry pending_commit explicitly."
+    },
     "slug": { "type": "string", "minLength": 1 },
     "step": {
       "type": "string",
@@ -21,19 +34,39 @@
         "done"
       ]
     },
-    "phase_index": { "type": "integer", "minimum": 0 },
-    "phase_count_hint": { "type": ["integer", "null"], "minimum": 0 },
+    "phase_index": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991
+    },
+    "phase_count_hint": {
+      "type": ["integer", "null"],
+      "minimum": 0,
+      "maximum": 9007199254740991
+    },
     "rounds": {
       "type": "object",
       "description": "Keys like phase-01/plan_review or phase-01/code_review",
-      "additionalProperties": { "type": "integer", "minimum": 1 }
+      "additionalProperties": {
+        "type": "integer",
+        "minimum": 1,
+        "maximum": 9007199254740991
+      }
     },
     "vcs": { "type": "string", "enum": ["jj", "git"] },
     "allow_dirty": { "type": "boolean" },
     "goal": { "type": "string" },
     "last_error": { "type": ["string", "null"] },
-    "pending_artifact": { "type": ["string", "null"] },
+    "pending_artifact": {
+      "type": ["string", "null"],
+      "pattern": "^\\.apnea\\/(?!.*\\u0000)(?!\\.(?:/|$)|\\.\\.(?:/|$))(?!.*\\/\\.(?:\\/|$))(?!.*\\/\\.\\.(?:\\/|$))(?!.*\\\\)[^/]+(?:/[^/]+)*$"
+    },
     "pending_role": { "type": ["string", "null"] },
+    "pending_delivery": {
+      "type": ["string", "null"],
+      "enum": ["manual", "interactive", null],
+      "description": "Known delivery boundary for pending ownership; null is idle or legacy-ambiguous"
+    },
     "pending_floating_exit": {
       "type": "null",
       "deprecated": true,
@@ -41,9 +74,21 @@
     },
     "pending_pane_id": { "type": ["string", "null"] },
     "pending_pane_label": { "type": ["string", "null"] },
-    "pending_started_at": { "type": ["integer", "null"] },
-    "pending_deadline_ms": { "type": ["integer", "null"] },
-    "pending_nudged_at": { "type": ["integer", "null"] },
+    "pending_started_at": {
+      "type": ["integer", "null"],
+      "minimum": 0,
+      "maximum": 9007199254740991
+    },
+    "pending_deadline_ms": {
+      "type": ["integer", "null"],
+      "minimum": 0,
+      "maximum": 9007199254740991
+    },
+    "pending_nudged_at": {
+      "type": ["integer", "null"],
+      "minimum": 0,
+      "maximum": 9007199254740991
+    },
     "pending_final_grace": { "type": "boolean" },
     "pending_extended": { "type": "boolean" },
     "role_panes": {
@@ -60,8 +105,117 @@
     },
     "package_root": { "type": "string" },
     "reviewer_tree_fingerprint": { "type": ["string", "null"] },
-    "current_phase_package": { "type": ["string", "null"] },
-    "current_code_review": { "type": ["string", "null"] },
-    "phase_package_rework": { "type": "boolean" }
+    "current_phase_package": {
+      "type": ["string", "null"],
+      "pattern": "^\\.apnea\\/(?!.*\\u0000)(?!\\.(?:/|$)|\\.\\.(?:/|$))(?!.*\\/\\.(?:\\/|$))(?!.*\\/\\.\\.(?:\\/|$))(?!.*\\\\)[^/]+(?:/[^/]+)*$"
+    },
+    "current_code_review": {
+      "type": ["string", "null"],
+      "pattern": "^\\.apnea\\/(?!.*\\u0000)(?!\\.(?:/|$)|\\.\\.(?:/|$))(?!.*\\/\\.(?:\\/|$))(?!.*\\/\\.\\.(?:\\/|$))(?!.*\\\\)[^/]+(?:/[^/]+)*$"
+    },
+    "required_rework": {
+      "type": ["string", "null"],
+      "enum": ["plan", "code", "phase_package", null],
+      "description": "Exact dispatch target that owns the next review round"
+    },
+    "pending_commit": {
+      "description": "Durable record of an in-flight commit transaction (crash-recoverable commit completion). Requires step=committing and phase_index equal to the run's phase_index; non-committing states must carry null. Version-1 files must not contain this key.",
+      "oneOf": [
+        {
+          "type": "null"
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "backend",
+            "id",
+            "phase_index",
+            "message",
+            "no_remaining_phases",
+            "verify_log",
+            "branch",
+            "parent_commit",
+            "tree_id"
+          ],
+          "properties": {
+            "backend": { "const": "git" },
+            "id": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Transaction uuid; appears in the commit message as Apnea-Transaction: <id>"
+            },
+            "phase_index": { "type": "integer", "minimum": 1 },
+            "message": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Full commit message including the Apnea-Transaction trailer line"
+            },
+            "no_remaining_phases": { "type": "boolean" },
+            "verify_log": { "type": "string", "minLength": 1 },
+            "branch": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Full ref the commit must land on, e.g. refs/heads/apnea/<slug>"
+            },
+            "parent_commit": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Expected HEAD at completion; also the created commit's parent"
+            },
+            "tree_id": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Prepared tree id staged with .apnea excluded"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "backend",
+            "id",
+            "phase_index",
+            "message",
+            "no_remaining_phases",
+            "verify_log",
+            "change_id",
+            "content_fingerprint"
+          ],
+          "properties": {
+            "backend": { "const": "jj" },
+            "id": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Transaction uuid; appears in the change description as Apnea-Transaction: <id>"
+            },
+            "phase_index": { "type": "integer", "minimum": 1 },
+            "message": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Full description including the Apnea-Transaction trailer line"
+            },
+            "no_remaining_phases": { "type": "boolean" },
+            "verify_log": { "type": "string", "minLength": 1 },
+            "change_id": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Change id of the described working-copy change"
+            },
+            "content_fingerprint": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Fingerprint of the change's non-.apnea diff at preparation time"
+            }
+          }
+        }
+      ]
+    },
+    "phase_package_rework": {
+      "type": "boolean",
+      "deprecated": true,
+      "description": "Deprecated migration-only field. True migrates to required_rework=phase_package."
+    }
   }
 }