owlrunkit 0.18.3 → 0.19.0

package/scripts/runkit-contract/schemas/efficiency-metrics-v1.schema.json

@@ -0,0 +1,220 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://owlcoda.dev/schemas/runkit/efficiency-metrics-v1.json",
+  "title": "OwlCoda RunKit Efficiency Metrics V1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "status",
+    "exitCode",
+    "telemetry",
+    "networkRequests",
+    "duplicateCommands",
+    "confirmedFalseBlocks",
+    "manualInterventions",
+    "handoffWait",
+    "timeToAcceptableResult",
+    "issueCodes",
+    "issues",
+    "authorizationGranted"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "OwlCodaRunKitEfficiencyMetricsV1" },
+    "status": { "enum": ["efficiency_metrics", "efficiency_metrics_invalid"] },
+    "exitCode": { "enum": [0, 3] },
+    "telemetry": { "const": false },
+    "networkRequests": { "const": 0 },
+    "duplicateCommands": { "$ref": "#/$defs/duplicateCommands" },
+    "confirmedFalseBlocks": { "$ref": "#/$defs/explicitCount" },
+    "manualInterventions": { "$ref": "#/$defs/explicitCount" },
+    "handoffWait": { "$ref": "#/$defs/handoffWait" },
+    "timeToAcceptableResult": { "$ref": "#/$defs/timeToAcceptable" },
+    "details": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "duplicateCommandGroups",
+        "workflowDurations",
+        "handoffSamples",
+        "inputRefs"
+      ],
+      "properties": {
+        "duplicateCommandGroups": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/duplicateCommandGroup" }
+        },
+        "workflowDurations": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/workflowDuration" }
+        },
+        "handoffSamples": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/handoffSample" }
+        },
+        "inputRefs": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "issueCodes": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "enum": ["invalid_quick_receipts_excluded", "efficiency_input_store_invalid"]
+      }
+    },
+    "issues": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "authorizationGranted": { "const": false }
+  },
+  "$defs": {
+    "nonNegative": { "type": "integer", "minimum": 0 },
+    "hash": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "duplicateCommands": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["repeatedExecutions", "groupCount", "basis"],
+      "properties": {
+        "repeatedExecutions": { "$ref": "#/$defs/nonNegative" },
+        "groupCount": { "$ref": "#/$defs/nonNegative" },
+        "basis": { "const": "quick_receipts_same_command_candidate_input_and_dependency" }
+      }
+    },
+    "explicitCount": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["count", "basis"],
+      "properties": {
+        "count": { "$ref": "#/$defs/nonNegative" },
+        "basis": { "const": "explicit_events" }
+      }
+    },
+    "handoffWait": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "completedHandoffs",
+        "unresolvedHandoffs",
+        "staleHandoffs",
+        "totalMs",
+        "averageMs",
+        "maxMs"
+      ],
+      "properties": {
+        "completedHandoffs": { "$ref": "#/$defs/nonNegative" },
+        "unresolvedHandoffs": { "$ref": "#/$defs/nonNegative" },
+        "staleHandoffs": { "$ref": "#/$defs/nonNegative" },
+        "totalMs": { "$ref": "#/$defs/nonNegative" },
+        "averageMs": { "$ref": "#/$defs/nonNegative" },
+        "maxMs": { "$ref": "#/$defs/nonNegative" }
+      }
+    },
+    "timeToAcceptable": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "status",
+        "completedWorkflows",
+        "totalMs",
+        "averageMs",
+        "minMs",
+        "maxMs",
+        "latestMs"
+      ],
+      "properties": {
+        "status": { "enum": ["observed", "not_observed"] },
+        "completedWorkflows": { "$ref": "#/$defs/nonNegative" },
+        "totalMs": { "$ref": "#/$defs/nonNegative" },
+        "averageMs": { "$ref": "#/$defs/nonNegative" },
+        "minMs": { "$ref": "#/$defs/nonNegative" },
+        "maxMs": { "$ref": "#/$defs/nonNegative" },
+        "latestMs": { "$ref": "#/$defs/nonNegative" }
+      }
+    },
+    "duplicateCommandGroup": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["bindingFingerprint", "executions", "inputRefs"],
+      "properties": {
+        "bindingFingerprint": { "$ref": "#/$defs/hash" },
+        "executions": { "$ref": "#/$defs/nonNegative" },
+        "inputRefs": {
+          "type": "array",
+          "minItems": 2,
+          "items": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "workflowDuration": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["workflowId", "startedAt", "acceptableResultAt", "durationMs"],
+      "properties": {
+        "workflowId": { "type": "string", "minLength": 1 },
+        "startedAt": { "type": "string", "format": "date-time" },
+        "acceptableResultAt": { "type": "string", "format": "date-time" },
+        "durationMs": { "$ref": "#/$defs/nonNegative" }
+      }
+    },
+    "handoffSample": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "handoffEventId",
+        "acceptedEventId",
+        "workItemId",
+        "durationMs",
+        "handoffRef",
+        "acceptedRef"
+      ],
+      "properties": {
+        "handoffEventId": { "type": "string", "minLength": 1 },
+        "acceptedEventId": { "type": "string", "minLength": 1 },
+        "workItemId": { "type": "string", "minLength": 1 },
+        "durationMs": { "$ref": "#/$defs/nonNegative" },
+        "handoffRef": { "type": "string", "minLength": 1 },
+        "acceptedRef": { "type": "string", "minLength": 1 }
+      }
+    }
+  },
+  "examples": [{
+    "schemaVersion": "OwlCodaRunKitEfficiencyMetricsV1",
+    "status": "efficiency_metrics",
+    "exitCode": 0,
+    "telemetry": false,
+    "networkRequests": 0,
+    "duplicateCommands": {
+      "repeatedExecutions": 0,
+      "groupCount": 0,
+      "basis": "quick_receipts_same_command_candidate_input_and_dependency"
+    },
+    "confirmedFalseBlocks": { "count": 0, "basis": "explicit_events" },
+    "manualInterventions": { "count": 0, "basis": "explicit_events" },
+    "handoffWait": {
+      "completedHandoffs": 0,
+      "unresolvedHandoffs": 0,
+      "staleHandoffs": 0,
+      "totalMs": 0,
+      "averageMs": 0,
+      "maxMs": 0
+    },
+    "timeToAcceptableResult": {
+      "status": "not_observed",
+      "completedWorkflows": 0,
+      "totalMs": 0,
+      "averageMs": 0,
+      "minMs": 0,
+      "maxMs": 0,
+      "latestMs": 0
+    },
+    "issueCodes": [],
+    "issues": [],
+    "authorizationGranted": false
+  }]
+}

package/scripts/runkit-contract/schemas/external-runtime-report-v1.schema.json

@@ -0,0 +1,125 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://owlcoda.dev/schemas/runkit/external-runtime-report-v1.schema.json",
+  "title": "OwlCoda RunKit External Runtime Report V1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "externalMutation",
+    "rollbackPerformed",
+    "finalExternalState",
+    "failedStage",
+    "lastPassedStage",
+    "rollbackOutcome",
+    "stages",
+    "recoveryEvidence",
+    "authorizationGranted"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "OwlCodaRunKitExternalRuntimeReportV1" },
+    "externalMutation": { "enum": ["changed", "unchanged", "unknown"] },
+    "rollbackPerformed": { "type": "boolean" },
+    "finalExternalState": { "$ref": "#/$defs/finalState" },
+    "failedStage": { "$ref": "#/$defs/nullableStageId" },
+    "lastPassedStage": { "$ref": "#/$defs/nullableStageId" },
+    "rollbackOutcome": { "enum": ["not_required", "succeeded", "failed", "unknown"] },
+    "stages": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 128,
+      "items": { "$ref": "#/$defs/stage" }
+    },
+    "recoveryEvidence": {
+      "type": "array",
+      "maxItems": 128,
+      "items": { "$ref": "#/$defs/recoveryEvidence" }
+    },
+    "authorizationGranted": { "const": false }
+  },
+  "$defs": {
+    "hashOrNull": {
+      "oneOf": [
+        { "type": "null" },
+        { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }
+      ]
+    },
+    "stageId": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$"
+    },
+    "nullableStageId": {
+      "oneOf": [
+        { "type": "null" },
+        { "$ref": "#/$defs/stageId" }
+      ]
+    },
+    "reference": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1024,
+      "pattern": "^[^\\r\\n\\u0000]+$"
+    },
+    "summary": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 2048,
+      "pattern": "^[^\\u0000]+$"
+    },
+    "finalState": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "stateRef", "fingerprint", "summary"],
+      "properties": {
+        "status": { "enum": ["changed", "unchanged", "restored", "unknown"] },
+        "stateRef": { "$ref": "#/$defs/reference" },
+        "fingerprint": { "$ref": "#/$defs/hashOrNull" },
+        "summary": { "$ref": "#/$defs/summary" }
+      }
+    },
+    "stage": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["stageId", "status", "summary", "evidenceRefs"],
+      "properties": {
+        "stageId": { "$ref": "#/$defs/stageId" },
+        "status": { "enum": ["passed", "failed", "skipped"] },
+        "summary": { "$ref": "#/$defs/summary" },
+        "evidenceRefs": {
+          "type": "array",
+          "maxItems": 128,
+          "items": { "$ref": "#/$defs/reference" }
+        }
+      }
+    },
+    "capturedBefore": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["stageId", "stateRef", "fingerprint"],
+      "properties": {
+        "stageId": { "$ref": "#/$defs/stageId" },
+        "stateRef": { "$ref": "#/$defs/reference" },
+        "fingerprint": { "$ref": "#/$defs/hashOrNull" }
+      }
+    },
+    "restoresTo": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["stateRef", "fingerprint"],
+      "properties": {
+        "stateRef": { "$ref": "#/$defs/reference" },
+        "fingerprint": { "$ref": "#/$defs/hashOrNull" }
+      }
+    },
+    "recoveryEvidence": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["artifactRef", "capturedBefore", "restoresTo"],
+      "properties": {
+        "artifactRef": { "$ref": "#/$defs/reference" },
+        "capturedBefore": { "$ref": "#/$defs/capturedBefore" },
+        "restoresTo": { "$ref": "#/$defs/restoresTo" }
+      }
+    }
+  }
+}

package/scripts/runkit-contract/schemas/onboarding-bootstrap-plan-v1.schema.json

@@ -0,0 +1,168 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://owlcoda.dev/schemas/runkit/onboarding-bootstrap-plan-v1.json",
+  "title": "OwlCoda RunKit Onboarding Bootstrap Plan V1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "status",
+    "exitCode",
+    "dryRun",
+    "writesPerformed",
+    "workspaceRoot",
+    "exactSpec",
+    "localBinding",
+    "registry",
+    "upgradeSafety",
+    "profiles",
+    "sharedSkill",
+    "steps",
+    "estimatedAdditionalSteps",
+    "estimatedEvidenceObjects",
+    "rollbackScope",
+    "issueCodes",
+    "nextCommand",
+    "authorizationGranted",
+    "planSha256"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "OwlCodaRunKitOnboardingBootstrapPlanV1" },
+    "status": { "enum": ["bootstrap_ready", "bootstrap_blocked"] },
+    "exitCode": { "enum": [0, 2] },
+    "dryRun": { "const": true },
+    "writesPerformed": { "const": 0 },
+    "workspaceRoot": { "type": "string", "minLength": 1 },
+    "exactSpec": { "$ref": "#/$defs/exactSpec" },
+    "localBinding": { "$ref": "#/$defs/localBinding" },
+    "registry": { "$ref": "#/$defs/registry" },
+    "upgradeSafety": { "enum": ["safe", "unsafe"] },
+    "profiles": { "$ref": "#/$defs/profiles" },
+    "sharedSkill": { "$ref": "#/$defs/sharedSkill" },
+    "steps": {
+      "type": "array",
+      "minItems": 6,
+      "maxItems": 6,
+      "items": { "$ref": "#/$defs/step" }
+    },
+    "estimatedAdditionalSteps": { "type": "integer", "minimum": 0 },
+    "estimatedEvidenceObjects": { "type": "integer", "minimum": 0 },
+    "rollbackScope": { "$ref": "#/$defs/strings" },
+    "issueCodes": { "$ref": "#/$defs/strings" },
+    "nextCommand": { "type": "string", "minLength": 1 },
+    "authorizationGranted": { "const": false },
+    "planSha256": { "$ref": "#/$defs/hashRef" }
+  },
+  "$defs": {
+    "exactSpec": {
+      "type": "string",
+      "pattern": "^owlrunkit@[0-9]+\\.[0-9]+\\.[0-9]+$"
+    },
+    "hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "hashRef": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "strings": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "localBinding": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["status", "version", "resolved", "integrity"],
+          "properties": {
+            "status": { "const": "bound" },
+            "version": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$" },
+            "resolved": { "type": "string", "minLength": 1 },
+            "integrity": { "type": "string", "pattern": "^sha512-" }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["status"],
+          "properties": {
+            "status": { "type": "string", "minLength": 1 }
+          }
+        }
+      ]
+    },
+    "registry": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["status", "version", "shasum", "integrity", "tarballUrl"],
+          "properties": {
+            "status": { "const": "verified" },
+            "version": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$" },
+            "shasum": { "type": "string", "pattern": "^[a-f0-9]{40}$" },
+            "integrity": { "type": "string", "pattern": "^sha512-" },
+            "tarballUrl": { "type": "string", "minLength": 1 }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["status", "issueCodes"],
+          "properties": {
+            "status": { "type": "string", "minLength": 1 },
+            "issueCodes": { "$ref": "#/$defs/strings" }
+          }
+        }
+      ]
+    },
+    "profiles": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "action", "issueCodes", "evidenceRef"],
+      "properties": {
+        "status": { "enum": ["ready", "blocked"] },
+        "action": { "enum": ["detect_then_reconcile", "validate_current", "reconcile"] },
+        "issueCodes": { "$ref": "#/$defs/strings" },
+        "evidenceRef": {
+          "oneOf": [
+            { "type": "null" },
+            { "$ref": "#/$defs/hash" }
+          ]
+        }
+      }
+    },
+    "sharedSkill": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "blocking", "issueCodes", "nextCommand"],
+      "properties": {
+        "status": { "enum": ["not_checked", "valid", "version_mismatch", "invalid"] },
+        "blocking": { "const": false },
+        "issueCodes": { "$ref": "#/$defs/strings" },
+        "nextCommand": {
+          "oneOf": [
+            { "type": "null" },
+            { "type": "string", "minLength": 1 }
+          ]
+        }
+      }
+    },
+    "step": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "action", "writes"],
+      "properties": {
+        "id": {
+          "enum": [
+            "exact_package_binding",
+            "initialize_core",
+            "reconcile_profiles",
+            "validate_profiles",
+            "adopt_registry_release",
+            "doctor"
+          ]
+        },
+        "action": { "type": "string", "minLength": 1 },
+        "writes": { "type": "integer", "minimum": 0 }
+      }
+    }
+  }
+}

package/scripts/runkit-contract/schemas/onboarding-bootstrap-receipt-v1.schema.json

@@ -0,0 +1,130 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://owlcoda.dev/schemas/runkit/onboarding-bootstrap-receipt-v1.json",
+  "title": "OwlCoda RunKit Onboarding Bootstrap Receipt V1",
+  "oneOf": [
+    { "$ref": "#/$defs/success" },
+    { "$ref": "#/$defs/failure" }
+  ],
+  "$defs": {
+    "baseProperties": {
+      "schemaVersion": { "const": "OwlCodaRunKitOnboardingBootstrapReceiptV1" },
+      "exitCode": { "enum": [0, 2] },
+      "bootstrapId": {
+        "type": "string",
+        "pattern": "^bootstrap-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
+      },
+      "planSha256": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+      "exactSpec": {
+        "type": "string",
+        "pattern": "^owlrunkit@[0-9]+\\.[0-9]+\\.[0-9]+$"
+      },
+      "startedAt": { "type": "string", "format": "date-time" },
+      "completedAt": { "type": "string", "format": "date-time" },
+      "completedSteps": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["id", "status"],
+          "properties": {
+            "id": { "type": "string", "minLength": 1 },
+            "status": { "type": "string", "minLength": 1 }
+          }
+        }
+      },
+      "rollbackPerformed": { "type": "boolean" },
+      "rollbackOutcome": { "enum": ["not_required", "restored", "failed"] },
+      "authorizationGranted": { "const": false }
+    },
+    "success": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "status",
+        "exitCode",
+        "bootstrapId",
+        "planSha256",
+        "exactSpec",
+        "startedAt",
+        "completedAt",
+        "completedSteps",
+        "profileStatus",
+        "adoptionStatus",
+        "doctorStatus",
+        "rollbackPerformed",
+        "rollbackOutcome",
+        "authorizationGranted"
+      ],
+      "properties": {
+        "schemaVersion": { "const": "OwlCodaRunKitOnboardingBootstrapReceiptV1" },
+        "status": { "const": "bootstrapped" },
+        "exitCode": { "const": 0 },
+        "bootstrapId": { "$ref": "#/$defs/baseProperties/bootstrapId" },
+        "planSha256": { "$ref": "#/$defs/baseProperties/planSha256" },
+        "exactSpec": { "$ref": "#/$defs/baseProperties/exactSpec" },
+        "startedAt": { "$ref": "#/$defs/baseProperties/startedAt" },
+        "completedAt": { "$ref": "#/$defs/baseProperties/completedAt" },
+        "completedSteps": { "$ref": "#/$defs/baseProperties/completedSteps" },
+        "profileStatus": { "enum": ["profiles_already_current", "profiles_reconciled"] },
+        "adoptionStatus": { "enum": ["adopted", "ok"] },
+        "doctorStatus": { "const": "ready" },
+        "rollbackPerformed": { "const": false },
+        "rollbackOutcome": { "const": "not_required" },
+        "authorizationGranted": { "const": false }
+      }
+    },
+    "failure": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "status",
+        "exitCode",
+        "bootstrapId",
+        "planSha256",
+        "exactSpec",
+        "startedAt",
+        "completedAt",
+        "completedSteps",
+        "failedStep",
+        "issueCodes",
+        "rollbackPerformed",
+        "rollbackOutcome",
+        "restoredPaths",
+        "authorizationGranted"
+      ],
+      "properties": {
+        "schemaVersion": { "const": "OwlCodaRunKitOnboardingBootstrapReceiptV1" },
+        "status": { "const": "bootstrap_failed" },
+        "exitCode": { "const": 2 },
+        "bootstrapId": { "$ref": "#/$defs/baseProperties/bootstrapId" },
+        "planSha256": { "$ref": "#/$defs/baseProperties/planSha256" },
+        "exactSpec": { "$ref": "#/$defs/baseProperties/exactSpec" },
+        "startedAt": { "$ref": "#/$defs/baseProperties/startedAt" },
+        "completedAt": { "$ref": "#/$defs/baseProperties/completedAt" },
+        "completedSteps": { "$ref": "#/$defs/baseProperties/completedSteps" },
+        "failedStep": {
+          "oneOf": [
+            { "type": "null" },
+            { "type": "string", "minLength": 1 }
+          ]
+        },
+        "issueCodes": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "rollbackPerformed": { "const": true },
+        "rollbackOutcome": { "enum": ["restored", "failed"] },
+        "restoredPaths": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "authorizationGranted": { "const": false }
+      }
+    }
+  }
+}