owlrunkit 0.19.0 → 0.19.2

package/scripts/runkit-contract/schemas/team-project-event-v5.schema.json

@@ -0,0 +1,89 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://owlcoda.com/schemas/runkit/team-project-event-v5.schema.json",
+  "title": "OwlCoda RunKit Team Project Event V5",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "eventId",
+    "type",
+    "occurredAt",
+    "revisionId",
+    "assignmentId",
+    "workItemId",
+    "ownerAgentId",
+    "previousOwnedPaths",
+    "ownedPaths",
+    "previousMeasurable",
+    "measurable",
+    "reason",
+    "evidenceRefs"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "OwlCodaRunKitTeamProjectEventV5" },
+    "eventId": { "$ref": "#/$defs/id" },
+    "type": { "const": "work_item_scope_revised" },
+    "occurredAt": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$"
+    },
+    "revisionId": { "$ref": "#/$defs/id" },
+    "supersedesRevisionId": { "$ref": "#/$defs/id" },
+    "assignmentId": { "$ref": "#/$defs/id" },
+    "workItemId": { "$ref": "#/$defs/id" },
+    "ownerAgentId": { "$ref": "#/$defs/id" },
+    "previousOwnedPaths": { "$ref": "#/$defs/paths" },
+    "ownedPaths": { "$ref": "#/$defs/paths" },
+    "previousMeasurable": { "$ref": "#/$defs/nullableMeasurable" },
+    "measurable": { "$ref": "#/$defs/nullableMeasurable" },
+    "reason": { "type": "string", "minLength": 1 },
+    "evidenceRefs": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "type": "string", "minLength": 1 }
+    }
+  },
+  "examples": [
+    {
+      "schemaVersion": "OwlCodaRunKitTeamProjectEventV5",
+      "eventId": "scope-revision-001",
+      "type": "work_item_scope_revised",
+      "occurredAt": "2026-08-13T05:57:10.000Z",
+      "revisionId": "revision-001",
+      "assignmentId": "assignment-001",
+      "workItemId": "canonical-adapter",
+      "ownerAgentId": "luna-max",
+      "previousOwnedPaths": ["src/adapter/**"],
+      "ownedPaths": ["src/adapter/**", "src/canonical-store/**"],
+      "previousMeasurable": { "unit": "interface", "total": 1 },
+      "measurable": { "unit": "interface", "total": 2 },
+      "reason": "Diagnosis proved the canonical store is part of the same bounded fix.",
+      "evidenceRefs": ["docs/decisions/scope-revision.md"]
+    }
+  ],
+  "$defs": {
+    "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$" },
+    "paths": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "measurable": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["unit", "total"],
+      "properties": {
+        "unit": { "type": "string", "minLength": 1 },
+        "total": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "nullableMeasurable": {
+      "oneOf": [
+        { "$ref": "#/$defs/measurable" },
+        { "type": "null" }
+      ]
+    }
+  }
+}

package/scripts/runkit-contract/schemas/team-project-status-v3.schema.json

@@ -0,0 +1,173 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://owlcoda.com/schemas/runkit/team-project-status-v3.schema.json",
+  "title": "OwlCoda RunKit Team Project Status V3",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "status",
+    "projectId",
+    "objective",
+    "overall",
+    "counts",
+    "milestones",
+    "workstreams",
+    "workItems",
+    "agents",
+    "readyQueue",
+    "criticalWorkItems",
+    "openDecisions",
+    "resolvedDecisions",
+    "deferredVerifications",
+    "openDeferredVerificationIds",
+    "integrationGates",
+    "dataCandidates",
+    "sourceDeliveries",
+    "warnings",
+    "projectTruthHash",
+    "authorizationGranted",
+    "deliveryDisposition",
+    "headline",
+    "dominantGap",
+    "nextAction",
+    "nextActorId",
+    "exitCode"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "OwlCodaRunKitTeamProjectStatusV3" },
+    "status": { "const": "team_project_status" },
+    "projectId": { "type": "string", "minLength": 1 },
+    "objective": { "type": "string", "minLength": 1 },
+    "overall": { "enum": ["planned", "active", "active_with_blockers", "completed"] },
+    "counts": { "type": "object" },
+    "milestones": { "type": "array", "items": { "type": "object" } },
+    "workstreams": { "type": "array", "items": { "type": "object" } },
+    "workItems": { "type": "array", "items": { "type": "object" } },
+    "agents": { "type": "array", "items": { "type": "object" } },
+    "readyQueue": { "type": "array", "items": { "type": "string" } },
+    "criticalWorkItems": { "type": "array", "items": { "type": "string" } },
+    "openDecisions": { "type": "array", "items": { "type": "object" } },
+    "resolvedDecisions": { "type": "array", "items": { "type": "object" } },
+    "deferredVerifications": { "type": "array", "items": { "type": "object" } },
+    "openDeferredVerificationIds": { "type": "array", "items": { "type": "string" } },
+    "integrationGates": { "type": "array", "items": { "type": "object" } },
+    "dataCandidates": { "type": "array", "items": { "type": "object" } },
+    "sourceDeliveries": { "type": "array", "items": { "type": "object" } },
+    "warnings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["code", "workItemId", "message", "truthRefs"],
+        "properties": {
+          "code": { "const": "no_bound_verification_receipt" },
+          "workItemId": { "type": "string", "minLength": 1 },
+          "message": { "type": "string", "minLength": 1 },
+          "truthRefs": {
+            "type": "array",
+            "uniqueItems": true,
+            "items": { "type": "string", "minLength": 1 }
+          }
+        }
+      }
+    },
+    "projectTruthHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "authorizationGranted": { "const": false },
+    "deliveryDisposition": {
+      "enum": ["work_in_progress", "code_complete_without_release_authority"]
+    },
+    "headline": { "type": "string", "minLength": 1 },
+    "dominantGap": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "id", "title", "workItemId", "agentId", "reason", "truthRefs"],
+      "properties": {
+        "kind": {
+          "enum": [
+            "decision",
+            "failed_work",
+            "work_item",
+            "deferred_verification",
+            "integration_gate",
+            "release_authority",
+            "none"
+          ]
+        },
+        "id": { "type": ["string", "null"] },
+        "title": { "type": ["string", "null"] },
+        "workItemId": { "type": ["string", "null"] },
+        "agentId": { "type": ["string", "null"] },
+        "reason": { "type": ["string", "null"] },
+        "truthRefs": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "nextAction": { "type": ["string", "null"] },
+    "nextActorId": { "type": ["string", "null"] },
+    "exitCode": { "const": 0 }
+  },
+  "examples": [
+    {
+      "schemaVersion": "OwlCodaRunKitTeamProjectStatusV3",
+      "status": "team_project_status",
+      "projectId": "g13-canary",
+      "objective": "Repair the bounded G13 canary contract",
+      "overall": "planned",
+      "counts": {},
+      "milestones": [],
+      "workstreams": [],
+      "workItems": [],
+      "agents": [],
+      "readyQueue": [],
+      "criticalWorkItems": [],
+      "openDecisions": [],
+      "resolvedDecisions": [],
+      "deferredVerifications": [],
+      "openDeferredVerificationIds": [],
+      "integrationGates": [],
+      "dataCandidates": [],
+      "sourceDeliveries": [],
+      "warnings": [],
+      "projectTruthHash": "0000000000000000000000000000000000000000000000000000000000000000",
+      "authorizationGranted": false,
+      "deliveryDisposition": "work_in_progress",
+      "headline": "Project is planned; assign the first ready WorkItem.",
+      "dominantGap": {
+        "kind": "none",
+        "id": null,
+        "title": null,
+        "workItemId": null,
+        "agentId": null,
+        "reason": null,
+        "truthRefs": []
+      },
+      "nextAction": null,
+      "nextActorId": null,
+      "exitCode": 0
+    }
+  ],
+  "allOf": [
+    {
+      "if": {
+        "properties": { "overall": { "const": "completed" } },
+        "required": ["overall"]
+      },
+      "then": {
+        "properties": {
+          "deliveryDisposition": { "const": "code_complete_without_release_authority" },
+          "nextAction": { "type": "string", "minLength": 1 },
+          "dominantGap": {
+            "properties": { "kind": { "const": "release_authority" } }
+          }
+        }
+      },
+      "else": {
+        "properties": { "deliveryDisposition": { "const": "work_in_progress" } }
+      }
+    }
+  ]
+}

package/scripts/runkit-contract/snapshot.mjs

@@ -8,6 +8,7 @@ import {
 } from "node:fs";
 import path from "node:path";
 
+import { validateReplayableEvidence } from "./acceptance-evidence.mjs";
 import { canonicalSourceFingerprint } from "./source-fingerprint.mjs";
 import {
   assertAllowedKeys,
@@ -185,21 +186,140 @@ function validateRequest(request) {
   if (!context.valid) throw new Error(`Snapshot verification context is invalid: ${context.issues.join("; ")}`);
 }
 
-export function verifySnapshotEvidence({ workspaceRoot, runId, snapshot }) {
+function exactKeys(value, label, keys, { optional = [] } = {}) {
+  assertAllowedKeys(value, label, [...keys, ...optional]);
+  if (!isRecord(value) || keys.some(key => !Object.hasOwn(value, key))) {
+    throw new Error(`${label} is missing required fields.`);
+  }
+}
+
+function validRepositoryState(state, label) {
+  try {
+    exactKeys(state, label, [
+      "head",
+      "statusMode",
+      "statusSha256",
+      "statusByteCount",
+      "statusEntryCount",
+      "selectedFiles",
+      "manifestFingerprint",
+    ]);
+    const files = normalizedFileMap(state.selectedFiles);
+    return typeof state.head === "string"
+      && state.head.length > 0
+      && state.statusMode === STATUS_MODE
+      && /^[a-f0-9]{64}$/u.test(state.statusSha256)
+      && Number.isSafeInteger(state.statusByteCount)
+      && state.statusByteCount >= 0
+      && Number.isSafeInteger(state.statusEntryCount)
+      && state.statusEntryCount >= 0
+      && files !== null
+      && canonicalSourceFingerprint(files) === state.manifestFingerprint;
+  } catch {
+    return false;
+  }
+}
+
+function snapshotContractIssues(snapshot) {
   const issues = [];
-  if (!isRecord(snapshot) || snapshot.schemaVersion !== "OwlCodaRunKitSnapshotV1") {
-    return { valid: false, issues: ["Unsupported snapshot schemaVersion."] };
+  try {
+    exactKeys(snapshot, "Snapshot", [
+      "schemaVersion",
+      "runId",
+      "snapshotId",
+      "status",
+      "mode",
+      "targetRoot",
+      "verificationContextFingerprint",
+      "repositoryBefore",
+      "repositoryAfter",
+      "command",
+      "authorizationGranted",
+    ], { optional: ["visual"] });
+    exactKeys(snapshot.command, "Snapshot command", [
+      "startedAt",
+      "endedAt",
+      "durationMs",
+      "exitCode",
+      "stdoutPath",
+      "stdoutSha256",
+      "stdoutLineCount",
+      "stderrPath",
+      "stderrSha256",
+      "stderrLineCount",
+      "evidence",
+    ]);
+  } catch (error) {
+    return [error instanceof Error ? error.message : String(error)];
+  }
+  if (
+    snapshot.schemaVersion !== "OwlCodaRunKitSnapshotV1"
+    || typeof snapshot.runId !== "string"
+    || snapshot.runId.length === 0
+    || typeof snapshot.snapshotId !== "string"
+    || snapshot.snapshotId.length === 0
+    || !new Set(["project", "foreign_readonly"]).has(snapshot.mode)
+    || typeof snapshot.targetRoot !== "string"
+    || snapshot.targetRoot.length === 0
+    || !/^[a-f0-9]{64}$/u.test(snapshot.verificationContextFingerprint)
+    || snapshot.authorizationGranted !== false
+    || !validRepositoryState(snapshot.repositoryBefore, "repositoryBefore")
+    || !validRepositoryState(snapshot.repositoryAfter, "repositoryAfter")
+    || typeof snapshot.command.startedAt !== "string"
+    || typeof snapshot.command.endedAt !== "string"
+    || !Number.isSafeInteger(snapshot.command.durationMs)
+    || snapshot.command.durationMs < 0
+    || !Number.isInteger(snapshot.command.exitCode)
+    || typeof snapshot.command.stdoutPath !== "string"
+    || typeof snapshot.command.stderrPath !== "string"
+    || !/^[a-f0-9]{64}$/u.test(snapshot.command.stdoutSha256)
+    || !/^[a-f0-9]{64}$/u.test(snapshot.command.stderrSha256)
+    || !Number.isSafeInteger(snapshot.command.stdoutLineCount)
+    || snapshot.command.stdoutLineCount < 0
+    || !Number.isSafeInteger(snapshot.command.stderrLineCount)
+    || snapshot.command.stderrLineCount < 0
+  ) {
+    issues.push("Snapshot contract is invalid.");
   }
+  const evidence = validateReplayableEvidence(snapshot.command.evidence);
+  if (!evidence.valid) issues.push(...evidence.issues);
+  const stable = stableTarget(snapshot.repositoryBefore, snapshot.repositoryAfter);
+  const expectedStatus = !stable
+    ? "invalidated_by_target_write"
+    : snapshot.command.exitCode === 0
+      ? "snapshot_passed"
+      : "snapshot_failed";
+  if (snapshot.status !== expectedStatus) {
+    issues.push("Snapshot status does not match its command and repository state.");
+  }
+  return issues;
+}
+
+export function verifySnapshotEvidence({
+  workspaceRoot,
+  runId,
+  snapshot,
+  requirePassed = true,
+}) {
+  const issues = [];
+  issues.push(...snapshotContractIssues(snapshot));
+  if (issues.length > 0) return { valid: false, issues };
   if (snapshot.runId !== runId) issues.push("Snapshot runId does not match the execution.");
-  if (snapshot.status !== "snapshot_passed") issues.push("Snapshot did not pass.");
+  if (requirePassed && snapshot.status !== "snapshot_passed") {
+    issues.push("Snapshot did not pass.");
+  }
   for (const [label, relativePath, expected] of [
     ["stdout", snapshot.command?.stdoutPath, snapshot.command?.stdoutSha256],
     ["stderr", snapshot.command?.stderrPath, snapshot.command?.stderrSha256],
   ]) {
     try {
       const absolutePath = resolveWithinRoot(workspaceRoot, relativePath, `${label} evidence path`);
-      const actual = sha256(readFileSync(absolutePath));
+      const bytes = readFileSync(absolutePath);
+      const actual = sha256(bytes);
       if (actual !== expected) issues.push(`${label} evidence hash mismatch.`);
+      if (lineCount(bytes) !== snapshot.command[`${label}LineCount`]) {
+        issues.push(`${label} evidence line count mismatch.`);
+      }
     } catch (error) {
       issues.push(error instanceof Error ? error.message : String(error));
     }