workspai 0.68.0 → 0.69.0

package/contracts/runtime-command-surface.v1.json

@@ -49,6 +49,7 @@
     "import",
     "adopt",
     "goal",
+    "change",
     "agent",
     "snapshot",
     "live",
@@ -102,6 +103,74 @@
       "config",
       "show"
     ],
+    [
+      "change",
+      "begin"
+    ],
+    [
+      "change",
+      "list"
+    ],
+    [
+      "change",
+      "predict"
+    ],
+    [
+      "change",
+      "authorize"
+    ],
+    [
+      "change",
+      "resume"
+    ],
+    [
+      "change",
+      "effect"
+    ],
+    [
+      "change",
+      "effect",
+      "record"
+    ],
+    [
+      "change",
+      "verification"
+    ],
+    [
+      "change",
+      "verification",
+      "record"
+    ],
+    [
+      "change",
+      "status"
+    ],
+    [
+      "change",
+      "explain"
+    ],
+    [
+      "change",
+      "verify"
+    ],
+    [
+      "change",
+      "abort"
+    ],
+    [
+      "change",
+      "capsule"
+    ],
+    [
+      "change",
+      "capsule",
+      "validate"
+    ],
+    [
+      "change",
+      "capsule",
+      "export"
+    ],
     [
       "infra",
       "down"
@@ -300,6 +369,145 @@
         "cache"
       ]
     },
+    {
+      "invocation": "change",
+      "summary": "Compose Goal intent, architecture generations, typed effects, independent verification, and uncertainty into a tamper-evident change capsule.",
+      "canonicalArgv": [
+        "change"
+      ]
+    },
+    {
+      "invocation": "change abort",
+      "summary": "Terminate an open decision transaction with a durable reason while preserving its evidence history.",
+      "canonicalArgv": [
+        "change",
+        "abort"
+      ]
+    },
+    {
+      "invocation": "change authorize",
+      "summary": "Grant explicit bounded effect classes before any mutation receipt can enter the decision ledger.",
+      "canonicalArgv": [
+        "change",
+        "authorize"
+      ]
+    },
+    {
+      "invocation": "change begin",
+      "summary": "Begin a decision transaction by pinning an immutable Goal Pack and exact Model, Graph, and live-input generation.",
+      "canonicalArgv": [
+        "change",
+        "begin"
+      ]
+    },
+    {
+      "invocation": "change capsule",
+      "summary": "Inspect the validation and export command group for change capsules.",
+      "canonicalArgv": [
+        "change",
+        "capsule"
+      ]
+    },
+    {
+      "invocation": "change capsule export",
+      "summary": "Export a validated portable capsule manifest to a workspace-contained destination.",
+      "canonicalArgv": [
+        "change",
+        "capsule",
+        "export"
+      ]
+    },
+    {
+      "invocation": "change capsule validate",
+      "summary": "Validate capsule integrity, decision-head binding, baseline materialization, and referenced local evidence.",
+      "canonicalArgv": [
+        "change",
+        "capsule",
+        "validate"
+      ]
+    },
+    {
+      "invocation": "change effect",
+      "summary": "Inspect the typed effect-receipt command group for proof-carrying changes.",
+      "canonicalArgv": [
+        "change",
+        "effect"
+      ]
+    },
+    {
+      "invocation": "change effect record",
+      "summary": "Record an idempotent observed effect receipt without treating model intent or prediction as execution proof.",
+      "canonicalArgv": [
+        "change",
+        "effect",
+        "record"
+      ]
+    },
+    {
+      "invocation": "change explain",
+      "summary": "Explain the evidence chain and safe next actions for an open, blocked, or sealed change.",
+      "canonicalArgv": [
+        "change",
+        "explain"
+      ]
+    },
+    {
+      "invocation": "change list",
+      "summary": "Discover open, blocked, sealed, aborted, and invalid change capsules with integrity and assurance summaries.",
+      "canonicalArgv": [
+        "change",
+        "list"
+      ]
+    },
+    {
+      "invocation": "change predict",
+      "summary": "Attach a bounded noncanonical architecture prediction that is explicitly ineligible as proof.",
+      "canonicalArgv": [
+        "change",
+        "predict"
+      ]
+    },
+    {
+      "invocation": "change resume",
+      "summary": "Resume a blocked or human-paused transaction into an explicit bounded state with a durable human reason.",
+      "canonicalArgv": [
+        "change",
+        "resume"
+      ]
+    },
+    {
+      "invocation": "change status",
+      "summary": "Read the derived decision state, assurance coverage, blockers, and remaining uncertainty.",
+      "canonicalArgv": [
+        "change",
+        "status"
+      ]
+    },
+    {
+      "invocation": "change verification",
+      "summary": "Inspect the independent Goal-criterion verification receipt command group.",
+      "canonicalArgv": [
+        "change",
+        "verification"
+      ]
+    },
+    {
+      "invocation": "change verification record",
+      "summary": "Admit a typed verification receipt only when it binds the current Model, Graph, effect head, and immutable Goal criterion.",
+      "canonicalArgv": [
+        "change",
+        "verification",
+        "record"
+      ]
+    },
+    {
+      "invocation": "change verify",
+      "summary": "Refresh canonical architecture, derive the actual Graph delta, compare prediction with observation, and run independent verification.",
+      "canonicalArgv": [
+        "change",
+        "verify"
+      ]
+    },
     {
       "invocation": "checkpoint",
       "summary": "Capture a named project or workspace checkpoint that can anchor later comparison or recovery.",
@@ -1889,6 +2097,80 @@
         ]
       ]
     },
+    {
+      "artifactPath": ".workspai/decisions/change-id/transaction.json",
+      "schemaVersion": "workspai.decision-transaction.v1",
+      "contractPath": "contracts/workspace-intelligence/decision-transaction.v1.json",
+      "producerCommands": [
+        [
+          "change"
+        ]
+      ]
+    },
+    {
+      "artifactPath": ".workspai/decisions/change-id/checkpoint.json",
+      "schemaVersion": "workspai.decision-checkpoint.v1",
+      "contractPath": "contracts/workspace-intelligence/decision-checkpoint.v1.json",
+      "producerCommands": [
+        [
+          "change"
+        ]
+      ]
+    },
+    {
+      "artifactPath": ".workspai/changes/change-id/lease.json",
+      "schemaVersion": "workspai.architecture-change-lease.v1",
+      "contractPath": "contracts/workspace-intelligence/architecture-change-lease.v1.json",
+      "producerCommands": [
+        [
+          "change",
+          "begin"
+        ]
+      ]
+    },
+    {
+      "artifactPath": ".workspai/changes/change-id/predicted-overlay.json",
+      "schemaVersion": "workspai.predicted-architecture-change.v1",
+      "contractPath": "contracts/workspace-intelligence/predicted-architecture-change.v1.json",
+      "producerCommands": [
+        [
+          "change",
+          "predict"
+        ]
+      ]
+    },
+    {
+      "artifactPath": ".workspai/changes/change-id/actual-overlay.json",
+      "schemaVersion": "workspace-knowledge-graph-change-overlay.v1",
+      "contractPath": "contracts/workspace-intelligence/workspace-knowledge-graph-change-overlay.v1.json",
+      "producerCommands": [
+        [
+          "change",
+          "verify"
+        ]
+      ]
+    },
+    {
+      "artifactPath": ".workspai/changes/change-id/architecture-surprises.json",
+      "schemaVersion": "workspai.architecture-surprise-report.v1",
+      "contractPath": "contracts/workspace-intelligence/architecture-surprise-report.v1.json",
+      "producerCommands": [
+        [
+          "change",
+          "verify"
+        ]
+      ]
+    },
+    {
+      "artifactPath": ".workspai/changes/change-id/capsule.json",
+      "schemaVersion": "workspai.proof-carrying-change-capsule.v1",
+      "contractPath": "contracts/workspace-intelligence/proof-carrying-change-capsule.v1.json",
+      "producerCommands": [
+        [
+          "change"
+        ]
+      ]
+    },
     {
       "artifactPath": ".workspai/goals/index.json",
       "schemaVersion": "workspai.goal-index.v1",

package/contracts/workspace-intelligence/architecture-change-lease.v1.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://workspai.dev/schemas/workspace-intelligence/architecture-change-lease.v1.json",
+  "title": "Workspai Architecture Change Lease",
+  "type": "object",
+  "required": ["schemaVersion", "changeId", "goalId", "createdAt", "workspace", "scope", "baseline", "generation", "semantics", "privateMaterialization"],
+  "properties": {
+    "schemaVersion": { "const": "workspai.architecture-change-lease.v1" },
+    "changeId": { "type": "string", "pattern": "^change-[a-z0-9][a-z0-9-]{7,95}$" },
+    "goalId": { "type": "string", "minLength": 1 },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "workspace": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string", "minLength": 1 } }, "additionalProperties": false },
+    "scope": { "$ref": "decision-event.v1.json#/$defs/scope" },
+    "baseline": {
+      "type": "object",
+      "required": ["model", "graph"],
+      "properties": {
+        "model": { "$ref": "decision-event.v1.json#/$defs/artifactReference" },
+        "graph": {
+          "type": "object",
+          "required": ["role", "artifact", "schemaVersion", "digest", "inputHash"],
+          "properties": {
+            "role": { "type": "string", "minLength": 1 },
+            "artifact": { "type": "string", "minLength": 1 },
+            "schemaVersion": { "type": "string", "minLength": 1 },
+            "digest": { "$ref": "decision-event.v1.json#/$defs/digest" },
+            "inputHash": { "$ref": "decision-event.v1.json#/$defs/sha256" }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "generation": { "$ref": "decision-event.v1.json#/$defs/sha256" },
+    "semantics": { "const": "optimistic-generation-guard" },
+    "privateMaterialization": {
+      "type": "object",
+      "required": ["artifact", "role", "portable", "authoritative", "digest"],
+      "properties": {
+        "artifact": { "type": "string", "minLength": 1 },
+        "role": { "const": "hash-bound-baseline-cache" },
+        "portable": { "const": false },
+        "authoritative": { "const": false },
+        "digest": { "$ref": "decision-event.v1.json#/$defs/digest" }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/contracts/workspace-intelligence/architecture-surprise-report.v1.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://workspai.dev/schemas/workspace-intelligence/architecture-surprise-report.v1.json",
+  "title": "Workspai Architecture Surprise Report",
+  "type": "object",
+  "required": ["schemaVersion", "changeId", "generatedAt", "prediction", "actual", "matched", "unpredicted", "missing", "summary"],
+  "properties": {
+    "schemaVersion": { "const": "workspai.architecture-surprise-report.v1" },
+    "changeId": { "type": "string", "pattern": "^change-[a-z0-9][a-z0-9-]{7,95}$" },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "prediction": { "oneOf": [{ "$ref": "decision-event.v1.json#/$defs/artifactReference" }, { "type": "null" }] },
+    "actual": { "$ref": "decision-event.v1.json#/$defs/artifactReference" },
+    "matched": { "$ref": "#/$defs/operations" },
+    "unpredicted": { "$ref": "#/$defs/operations" },
+    "missing": { "$ref": "#/$defs/operations" },
+    "summary": {
+      "type": "object",
+      "required": ["predicted", "actual", "matched", "unpredicted", "missing", "verdict"],
+      "properties": {
+        "predicted": { "type": "integer", "minimum": 0 },
+        "actual": { "type": "integer", "minimum": 0 },
+        "matched": { "type": "integer", "minimum": 0 },
+        "unpredicted": { "type": "integer", "minimum": 0 },
+        "missing": { "type": "integer", "minimum": 0 },
+        "verdict": { "enum": ["exact", "within-expectation", "surprising", "no-prediction"] }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "operations": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["operation", "targetKind", "targetId"],
+        "properties": {
+          "operation": { "type": "string", "minLength": 1 },
+          "targetKind": { "type": "string", "minLength": 1 },
+          "targetId": { "type": "string", "minLength": 1 }
+        },
+        "additionalProperties": false
+      }
+    }
+  }
+}

package/contracts/workspace-intelligence/change-operation-result.v1.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://workspai.dev/schemas/workspace-intelligence/change-operation-result.v1.json",
+  "title": "Workspai Change Operation Result",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "operation",
+    "changeId",
+    "state",
+    "capsule",
+    "artifacts",
+    "nextActions"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "workspai.change-operation-result.v1" },
+    "operation": {
+      "enum": [
+        "begin",
+        "predict",
+        "authorize",
+        "resume",
+        "effect-record",
+        "verification-record",
+        "status",
+        "verify",
+        "explain",
+        "abort",
+        "capsule-validate",
+        "capsule-export"
+      ]
+    },
+    "changeId": { "type": "string", "pattern": "^change-[a-z0-9][a-z0-9-]{7,95}$" },
+    "state": { "type": "string", "minLength": 1 },
+    "capsule": { "$ref": "proof-carrying-change-capsule.v1.json" },
+    "artifacts": {
+      "type": "object",
+      "additionalProperties": { "type": ["string", "null"] }
+    },
+    "nextActions": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+  },
+  "additionalProperties": false
+}

package/contracts/workspace-intelligence/decision-checkpoint.v1.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://workspai.dev/schemas/workspace-intelligence/decision-checkpoint.v1.json",
+  "title": "Workspai Decision Checkpoint",
+  "type": "object",
+  "required": ["schemaVersion", "transactionId", "generatedAt", "generation", "eventCount", "eventHeadDigest", "state", "transactionDigest"],
+  "properties": {
+    "schemaVersion": { "const": "workspai.decision-checkpoint.v1" },
+    "transactionId": { "type": "string", "pattern": "^change-[a-z0-9][a-z0-9-]{7,95}$" },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "generation": { "type": "integer", "minimum": 1 },
+    "eventCount": { "type": "integer", "minimum": 1 },
+    "eventHeadDigest": { "$ref": "decision-event.v1.json#/$defs/sha256" },
+    "state": { "enum": ["draft", "scoped", "evidence-ready", "authorized", "executing", "verifying", "awaiting-human", "blocked", "committed", "rejected", "aborted", "superseded"] },
+    "transactionDigest": { "$ref": "decision-event.v1.json#/$defs/sha256" }
+  },
+  "additionalProperties": false
+}

package/contracts/workspace-intelligence/decision-event.v1.json

@@ -0,0 +1,134 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://workspai.dev/schemas/workspace-intelligence/decision-event.v1.json",
+  "title": "Workspai Decision Event",
+  "type": "object",
+  "required": ["schemaVersion", "transactionId", "sequence", "kind", "occurredAt", "actor", "previousEventDigest", "payload", "digest"],
+  "properties": {
+    "schemaVersion": { "const": "workspai.decision-event.v1" },
+    "transactionId": { "type": "string", "pattern": "^change-[a-z0-9][a-z0-9-]{7,95}$" },
+    "sequence": { "type": "integer", "minimum": 1 },
+    "kind": { "enum": ["created", "scope-bound", "evidence-attached", "plan-attached", "authorized", "effect-requested", "effect-recorded", "effect-uncertain", "verification-started", "verification-recorded", "human-required", "blocked", "resumed", "committed", "rejected", "aborted", "superseded"] },
+    "occurredAt": { "type": "string", "format": "date-time" },
+    "actor": {
+      "type": "object",
+      "required": ["kind", "id"],
+      "properties": {
+        "kind": { "enum": ["human", "agent", "cli", "ci", "extension"] },
+        "id": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    },
+    "previousEventDigest": { "oneOf": [{ "$ref": "#/$defs/sha256" }, { "type": "null" }] },
+    "payload": { "$ref": "#/$defs/payload" },
+    "digest": { "$ref": "#/$defs/sha256" }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "digest": {
+      "type": "object",
+      "required": ["algorithm", "semantics", "value"],
+      "properties": {
+        "algorithm": { "const": "sha256" },
+        "semantics": { "enum": ["canonical-json-v1", "raw-bytes-v1", "workspace-model-structural-v1"] },
+        "value": { "$ref": "#/$defs/sha256" }
+      },
+      "additionalProperties": false
+    },
+    "artifactReference": {
+      "type": "object",
+      "required": ["role", "artifact", "schemaVersion", "digest"],
+      "properties": {
+        "role": { "type": "string", "minLength": 1 },
+        "artifact": { "type": "string", "minLength": 1 },
+        "schemaVersion": { "type": "string", "minLength": 1 },
+        "digest": { "$ref": "#/$defs/digest" }
+      },
+      "additionalProperties": false
+    },
+    "scope": {
+      "type": "object",
+      "required": ["kind", "projects"],
+      "properties": {
+        "kind": { "enum": ["workspace", "project", "project-set"] },
+        "projects": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true }
+      },
+      "additionalProperties": false
+    },
+    "authorization": {
+      "type": "object",
+      "required": ["grantedBy", "grant", "effectClasses"],
+      "properties": {
+        "grantedBy": { "type": "string", "minLength": 1 },
+        "grant": { "enum": ["bounded-effects", "verification-only"] },
+        "effectClasses": { "type": "array", "items": { "enum": ["filesystem", "command", "configuration", "dependency", "external"] }, "minItems": 1, "uniqueItems": true }
+      },
+      "additionalProperties": false
+    },
+    "effectReceipt": {
+      "type": "object",
+      "required": ["id", "effectClass", "status", "summary", "artifacts", "observedAt", "idempotencyKey"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "effectClass": { "enum": ["filesystem", "command", "configuration", "dependency", "external"] },
+        "status": { "enum": ["succeeded", "failed", "uncertain"] },
+        "summary": { "type": "string", "minLength": 1 },
+        "command": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
+        "artifacts": { "type": "array", "items": { "$ref": "#/$defs/artifactReference" } },
+        "observedAt": { "type": "string", "format": "date-time" },
+        "idempotencyKey": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    },
+    "verificationReceipt": {
+      "type": "object",
+      "required": ["id", "criterionId", "status", "summary", "target", "artifacts", "observedAt"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "criterionId": { "type": "string", "minLength": 1 },
+        "status": { "enum": ["passed", "failed", "inconclusive"] },
+        "summary": { "type": "string", "minLength": 1 },
+        "target": {
+          "type": "object",
+          "required": ["modelHash", "graphHash", "effectHeadDigest"],
+          "properties": {
+            "modelHash": { "$ref": "#/$defs/sha256" },
+            "graphHash": { "$ref": "#/$defs/sha256" },
+            "effectHeadDigest": { "$ref": "#/$defs/sha256" }
+          },
+          "additionalProperties": false
+        },
+        "artifacts": { "type": "array", "items": { "$ref": "#/$defs/artifactReference" } },
+        "observedAt": { "type": "string", "format": "date-time" }
+      },
+      "additionalProperties": false
+    },
+    "blocker": {
+      "type": "object",
+      "required": ["code", "actionable"],
+      "properties": {
+        "code": { "type": "string", "minLength": 1 },
+        "actionable": { "type": "boolean" },
+        "details": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "payload": {
+      "type": "object",
+      "required": ["summary"],
+      "properties": {
+        "summary": { "type": "string", "minLength": 1 },
+        "scope": { "$ref": "#/$defs/scope" },
+        "references": { "type": "array", "items": { "$ref": "#/$defs/artifactReference" } },
+        "authorization": { "$ref": "#/$defs/authorization" },
+        "effect": { "$ref": "#/$defs/effectReceipt" },
+        "verification": { "$ref": "#/$defs/verificationReceipt" },
+        "blocker": { "$ref": "#/$defs/blocker" },
+        "resumeTo": { "enum": ["authorized", "executing", "verifying"] },
+        "reason": { "type": "string" }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/contracts/workspace-intelligence/decision-transaction.v1.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://workspai.dev/schemas/workspace-intelligence/decision-transaction.v1.json",
+  "title": "Workspai Decision Transaction Projection",
+  "type": "object",
+  "required": ["schemaVersion", "id", "purpose", "createdAt", "updatedAt", "state", "generation", "eventCount", "eventHeadDigest", "intent", "requiredCriteria", "scope", "evidence", "plans", "authorization", "effects", "verifications", "blockers"],
+  "properties": {
+    "schemaVersion": { "const": "workspai.decision-transaction.v1" },
+    "id": { "type": "string", "pattern": "^change-[a-z0-9][a-z0-9-]{7,95}$" },
+    "purpose": { "const": "proof-carrying-change" },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "updatedAt": { "type": "string", "format": "date-time" },
+    "state": { "enum": ["draft", "scoped", "evidence-ready", "authorized", "executing", "verifying", "awaiting-human", "blocked", "committed", "rejected", "aborted", "superseded"] },
+    "generation": { "type": "integer", "minimum": 1 },
+    "eventCount": { "type": "integer", "minimum": 1 },
+    "eventHeadDigest": { "$ref": "decision-event.v1.json#/$defs/sha256" },
+    "intent": { "$ref": "decision-event.v1.json#/$defs/artifactReference" },
+    "requiredCriteria": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+    "scope": { "oneOf": [{ "$ref": "decision-event.v1.json#/$defs/scope" }, { "type": "null" }] },
+    "evidence": { "type": "array", "items": { "$ref": "decision-event.v1.json#/$defs/artifactReference" } },
+    "plans": { "type": "array", "items": { "$ref": "decision-event.v1.json#/$defs/artifactReference" } },
+    "authorization": { "oneOf": [{ "$ref": "decision-event.v1.json#/$defs/authorization" }, { "type": "null" }] },
+    "effects": { "type": "array", "items": { "$ref": "decision-event.v1.json#/$defs/effectReceipt" } },
+    "verifications": { "type": "array", "items": { "$ref": "decision-event.v1.json#/$defs/verificationReceipt" } },
+    "blockers": { "type": "array", "items": { "$ref": "decision-event.v1.json#/$defs/blocker" } },
+    "terminalReason": { "type": "string" }
+  },
+  "additionalProperties": false
+}

package/contracts/workspace-intelligence/goal-index.v1.json

@@ -111,6 +111,19 @@
             "uniqueItems": true,
             "items": { "type": "string", "minLength": 1 }
           },
+          "changeTransactionId": {
+            "type": "string",
+            "pattern": "^change-[a-z0-9][a-z0-9-]{7,95}$"
+          },
+          "changeTransactionIds": {
+            "type": "array",
+            "maxItems": 25,
+            "uniqueItems": true,
+            "items": {
+              "type": "string",
+              "pattern": "^change-[a-z0-9][a-z0-9-]{7,95}$"
+            }
+          },
           "verificationReceipt": {
             "type": "object",
             "required": [