Workspace Intelligence / JSON Schema
Workspai Workspace Repair Transaction v1
Durable CLI-owned state for one governed workspace repair from plan through verification or rollback.
- Schema version
workspai.workspace-repair-transaction.v1- Contract path
contracts/workspace-intelligence/workspace-repair-transaction.v1.json- Publication
- embedded-type, json-schema
- Defined fields
- 100
- Artifact bindings
- 1
Why this contract exists
Architecture role
Defines a versioned interoperability boundary used by Workspai and contract-aware consumers.
Consumption boundary
- • Workspai CLI
- • Workspace Intelligence consumers
- • IDEs and agents
Related commands
Commands are linked only when the runtime contract identifies a direct production relationship. Supporting contracts may be consumed without having a single producer command.
Produced artifacts
These durable files are emitted by registered commands and validated against this contract.
| Artifact path | Schema | Producer |
|---|---|---|
| .workspai/reports/workspace-repair-last-run.json | workspai.workspace-repair-transaction.v1 | workspai workspace repair plan workspai workspace repair propose workspai workspace repair approve workspai workspace repair decide workspai workspace repair execute workspai workspace repair resume workspai workspace repair rollback workspai workspace repair cancel |
Field reference
Every declared schema property or published capability path is listed here. Required means the contract declares or publishes that field at the shown boundary.
| Field path | Type | Required | Meaning | Constraints |
|---|---|---|---|---|
| $defs.adapterEvaluation.adapterId | string | Yes | Defines the adapterid value at this contract boundary. | minLength: 1 |
| $defs.adapterEvaluation.ecosystem | string | Yes | Defines the ecosystem value at this contract boundary. | minLength: 1 |
| $defs.adapterEvaluation.manifests | array | Yes | Defines the manifests value at this contract boundary. | — |
| $defs.adapterEvaluation.message | string | Yes | Defines the message value at this contract boundary. | — |
| $defs.adapterEvaluation.missingExecutables | array | Yes | Defines the missingexecutables value at this contract boundary. | — |
| $defs.adapterEvaluation.projectPath | string | Yes | Defines the projectpath value at this contract boundary. | minLength: 1 |
| $defs.adapterEvaluation.requiredExecutables | array | Yes | Defines the requiredexecutables value at this contract boundary. | — |
| $defs.adapterEvaluation.status | enum | Yes | Defines the status value at this contract boundary. | enum: ready, partial, unsupported |
| $defs.adapterEvaluation.support | enum | Yes | Defines the support value at this contract boundary. | enum: full, conditional, unsupported |
| $defs.checkpoint.capturedAt | string | No | Defines the capturedat value at this contract boundary. | format: date-time |
| $defs.checkpoint.files | array | Yes | Defines the files value at this contract boundary. | — |
| $defs.checkpoint.restoredAt | string | No | Defines the restoredat value at this contract boundary. | format: date-time |
| $defs.checkpoint.status | enum | Yes | Defines the status value at this contract boundary. | enum: pending, captured, restored, conflicted, unavailable |
| $defs.checkpointFile.afterHash | string | null | No | Defines the afterhash value at this contract boundary. | — |
| $defs.checkpointFile.backupRef | string | No | Defines the backupref value at this contract boundary. | minLength: 1 |
| $defs.checkpointFile.beforeHash | string | null | Yes | Defines the beforehash value at this contract boundary. | — |
| $defs.checkpointFile.existed | boolean | Yes | Defines the existed value at this contract boundary. | — |
| $defs.checkpointFile.mode | integer | No | Defines the mode value at this contract boundary. | minimum: 0 · maximum: 65535 |
| $defs.checkpointFile.path | string | Yes | Defines the path value at this contract boundary. | minLength: 1 |
| $defs.decision.causes | array | No | Defines the causes value at this contract boundary. | minItems: 1 |
| $defs.decision.options | array | Yes | Defines the options value at this contract boundary. | minItems: 1 |
| $defs.decision.reason | string | Yes | Defines the reason value at this contract boundary. | minLength: 1 |
| $defs.decisionCause.adapterId | string | No | Defines the adapterid value at this contract boundary. | minLength: 1 |
| $defs.decisionCause.executable | string | No | Defines the executable value at this contract boundary. | minLength: 1 |
| $defs.decisionCause.id | string | Yes | Defines the id value at this contract boundary. | minLength: 1 |
| $defs.decisionCause.kind | enum | Yes | Defines the kind value at this contract boundary. | enum: missing-executable, unsupported-adapter, failed-precondition, risk-approval, policy-exception, source-repair-required |
| $defs.decisionCause.message | string | Yes | Defines the message value at this contract boundary. | minLength: 1 |
| $defs.decisionCause.projectPath | string | No | Defines the projectpath value at this contract boundary. | minLength: 1 |
| $defs.event.at | string | Yes | Defines the at value at this contract boundary. | format: date-time |
| $defs.event.message | string | Yes | Defines the message value at this contract boundary. | — |
| $defs.event.sequence | integer | Yes | Defines the sequence value at this contract boundary. | minimum: 1 |
| $defs.event.stageId | string | No | Defines the stageid value at this contract boundary. | — |
| $defs.event.status | string | No | Defines the status value at this contract boundary. | — |
| $defs.event.type | enum | Yes | Defines the type value at this contract boundary. | enum: planned, approval, checkpoint, stage, verification, decision, rollback, closed, failed, cancelled |
| $defs.invocation.args | array | Yes | Defines the args value at this contract boundary. | — |
| $defs.invocation.cwd | string | Yes | Defines the cwd value at this contract boundary. | minLength: 1 |
| $defs.invocation.executable | string | Yes | Defines the executable value at this contract boundary. | minLength: 1 |
| $defs.invocation.purpose | enum | Yes | Defines the purpose value at this contract boundary. | enum: repair, reconcile, audit, test, build, verify |
| $defs.invocation.timeoutMs | integer | Yes | Defines the timeoutms value at this contract boundary. | minimum: 1000 · maximum: 900000 |
| $defs.precondition.id | string | Yes | Defines the id value at this contract boundary. | minLength: 1 |
| $defs.precondition.message | string | Yes | Defines the message value at this contract boundary. | — |
| $defs.precondition.status | enum | Yes | Defines the status value at this contract boundary. | enum: passed, failed, unknown |
| $defs.stage.changedPaths | array | No | Defines the changedpaths value at this contract boundary. | — |
| $defs.stage.completedAt | string | No | Defines the completedat value at this contract boundary. | format: date-time |
| $defs.stage.exitCode | integer | null | No | Defines the exitcode value at this contract boundary. | — |
| $defs.stage.id | string | Yes | Defines the id value at this contract boundary. | minLength: 1 |
| $defs.stage.invocation | reference | No | Defines the invocation value at this contract boundary. | ref: #/$defs/invocation |
| $defs.stage.kind | enum | Yes | Defines the kind value at this contract boundary. | enum: repair, reconcile, audit, test, build, verify, rollback |
| $defs.stage.required | boolean | Yes | Defines the required value at this contract boundary. | — |
| $defs.stage.risk | enum | Yes | Defines the risk value at this contract boundary. | enum: safe, guarded, invasive |
| $defs.stage.startedAt | string | No | Defines the startedat value at this contract boundary. | format: date-time |
| $defs.stage.status | enum | Yes | Defines the status value at this contract boundary. | enum: pending, running, passed, failed, blocked, skipped, cancelled |
| $defs.stage.stderrTail | string | No | Defines the stderrtail value at this contract boundary. | — |
| $defs.stage.stdoutTail | string | No | Defines the stdouttail value at this contract boundary. | — |
| $defs.stage.summary | string | Yes | Defines the summary value at this contract boundary. | — |
| $defs.verification.artifact | string | Yes | Defines the artifact value at this contract boundary. | const: ".workspai/reports/workspace-intelligence-run-last-run.json" |
| $defs.verification.exitCode | integer | null | Yes | Defines the exitcode value at this contract boundary. | — |
| $defs.verification.remainingActionIds | array | No | Defines the remainingactionids value at this contract boundary. | — |
| $defs.verification.status | enum | Yes | Defines the status value at this contract boundary. | enum: passed, failed, not-run |
| $defs.verification.summary | string | Yes | Defines the summary value at this contract boundary. | — |
| $defs.verification.targetStatus | enum | No | Defines the targetstatus value at this contract boundary. | enum: passed, failed, unknown |
| $defs.verification.workspaceStatus | enum | No | Defines the workspacestatus value at this contract boundary. | enum: passed, blocked, failed |
| adapterEvaluations | array | No | Defines the adapterevaluations value at this contract boundary. | — |
| approval | object | Yes | Defines the approval value at this contract boundary. | additionalProperties: false |
| approval.approvedAt | string | No | Defines the approvedat value at this contract boundary. | format: date-time |
| approval.approvedBy | string | No | Defines the approvedby value at this contract boundary. | minLength: 1 |
| approval.approvedPlanHash | string | No | Defines the approvedplanhash value at this contract boundary. | pattern: ^[a-f0-9]{64}$ |
| approval.required | boolean | Yes | Defines the required value at this contract boundary. | const: true |
| approval.status | enum | Yes | Defines the status value at this contract boundary. | enum: pending, approved, rejected, expired |
| checkpoint | reference | Yes | Defines the checkpoint value at this contract boundary. | ref: #/$defs/checkpoint |
| createdAt | string | Yes | Defines the createdat value at this contract boundary. | format: date-time |
| decision | reference | No | Defines the decision value at this contract boundary. | ref: #/$defs/decision |
| events | array | Yes | Defines the events value at this contract boundary. | — |
| integrity | object | Yes | Defines the integrity value at this contract boundary. | additionalProperties: false |
| integrity.planHash | string | Yes | Defines the planhash value at this contract boundary. | pattern: ^[a-f0-9]{64}$ |
| integrity.sourceEvidenceHash | string | Yes | Defines the sourceevidencehash value at this contract boundary. | pattern: ^[a-f0-9]{64}$ |
| policy | object | Yes | Defines the policy value at this contract boundary. | additionalProperties: false |
| policy.allowBreaking | boolean | Yes | Defines the allowbreaking value at this contract boundary. | — |
| policy.allowForce | boolean | Yes | Defines the allowforce value at this contract boundary. | — |
| policy.autoRollback | boolean | Yes | Defines the autorollback value at this contract boundary. | — |
| policy.maxRisk | enum | Yes | Defines the maxrisk value at this contract boundary. | enum: safe, guarded, invasive |
| policy.strictVerify | boolean | Yes | Defines the strictverify value at this contract boundary. | const: true |
| preconditions | array | Yes | Defines the preconditions value at this contract boundary. | — |
| revision | integer | Yes | Defines the revision value at this contract boundary. | minimum: 1 |
| schemaVersion | string | Yes | Defines the schemaversion value at this contract boundary. | const: "workspai.workspace-repair-transaction.v1" |
| stages | array | Yes | Defines the stages value at this contract boundary. | minItems: 1 |
| state | enum | Yes | Defines the state value at this contract boundary. | enum: planned, awaiting-approval, approved, checkpointed, executing, verifying, closed, decision-required, rollback-required, rolling-back, rolled-back, failed, cancelled |
| target | object | Yes | Defines the target value at this contract boundary. | additionalProperties: false |
| target.actionIds | array | Yes | Defines the actionids value at this contract boundary. | minItems: 1 |
| target.blockerSignature | string | No | Defines the blockersignature value at this contract boundary. | minLength: 1 · maxLength: 256 |
| target.cardId | string | Yes | Defines the cardid value at this contract boundary. | minLength: 1 |
| target.projectName | string | No | Defines the projectname value at this contract boundary. | minLength: 1 |
| target.projectPath | string | No | Defines the projectpath value at this contract boundary. | minLength: 1 |
| target.scope | enum | Yes | Defines the scope value at this contract boundary. | enum: workspace, project |
| transactionId | string | Yes | Defines the transactionid value at this contract boundary. | pattern: ^[A-Za-z0-9_-]{12,128}$ |
| updatedAt | string | Yes | Defines the updatedat value at this contract boundary. | format: date-time |
| verification | reference | No | Defines the verification value at this contract boundary. | ref: #/$defs/verification |
| workspace | object | Yes | Defines the workspace value at this contract boundary. | additionalProperties: false |
| workspace.name | string | Yes | Defines the name value at this contract boundary. | minLength: 1 |
| workspace.rootRef | string | Yes | Defines the rootref value at this contract boundary. | const: "." |
Canonical machine-readable definition
The raw synchronized contract remains authoritative. The educational sections above are projections of this definition.
Show raw JSON
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://workspai.dev/contracts/workspace-intelligence/workspace-repair-transaction.v1.json",
"title": "Workspai Workspace Repair Transaction v1",
"description": "Durable CLI-owned state for one governed workspace repair from plan through verification or rollback.",
"type": "object",
"additionalProperties": false,
"required": [
"schemaVersion",
"transactionId",
"revision",
"createdAt",
"updatedAt",
"workspace",
"target",
"state",
"policy",
"approval",
"preconditions",
"checkpoint",
"stages",
"events",
"integrity"
],
"properties": {
"schemaVersion": {
"const": "workspai.workspace-repair-transaction.v1"
},
"transactionId": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{12,128}$"
},
"revision": {
"type": "integer",
"minimum": 1
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"workspace": {
"type": "object",
"additionalProperties": false,
"required": [
"name",
"rootRef"
],
"properties": {
"name": {
"type": "string",
"minLength": 1
},
"rootRef": {
"const": "."
}
}
},
"target": {
"type": "object",
"additionalProperties": false,
"required": [
"cardId",
"scope",
"actionIds"
],
"properties": {
"cardId": {
"type": "string",
"minLength": 1
},
"blockerSignature": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"scope": {
"enum": [
"workspace",
"project"
]
},
"projectName": {
"type": "string",
"minLength": 1
},
"projectPath": {
"type": "string",
"minLength": 1
},
"actionIds": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"type": "string",
"minLength": 1
}
}
}
},
"state": {
"enum": [
"planned",
"awaiting-approval",
"approved",
"checkpointed",
"executing",
"verifying",
"closed",
"decision-required",
"rollback-required",
"rolling-back",
"rolled-back",
"failed",
"cancelled"
]
},
"policy": {
"type": "object",
"additionalProperties": false,
"required": [
"maxRisk",
"allowForce",
"allowBreaking",
"autoRollback",
"strictVerify"
],
"properties": {
"maxRisk": {
"enum": [
"safe",
"guarded",
"invasive"
]
},
"allowForce": {
"type": "boolean"
},
"allowBreaking": {
"type": "boolean"
},
"autoRollback": {
"type": "boolean"
},
"strictVerify": {
"const": true
}
}
},
"approval": {
"type": "object",
"additionalProperties": false,
"required": [
"required",
"status"
],
"properties": {
"required": {
"const": true
},
"status": {
"enum": [
"pending",
"approved",
"rejected",
"expired"
]
},
"approvedAt": {
"type": "string",
"format": "date-time"
},
"approvedBy": {
"type": "string",
"minLength": 1
},
"approvedPlanHash": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
}
}
},
"preconditions": {
"type": "array",
"items": {
"$ref": "#/$defs/precondition"
}
},
"adapterEvaluations": {
"type": "array",
"items": {
"$ref": "#/$defs/adapterEvaluation"
}
},
"checkpoint": {
"$ref": "#/$defs/checkpoint"
},
"stages": {
"type": "array",
"minItems": 1,
"items": {
"$ref": "#/$defs/stage"
}
},
"verification": {
"$ref": "#/$defs/verification"
},
"decision": {
"$ref": "#/$defs/decision"
},
"events": {
"type": "array",
"items": {
"$ref": "#/$defs/event"
}
},
"integrity": {
"type": "object",
"additionalProperties": false,
"required": [
"planHash",
"sourceEvidenceHash"
],
"properties": {
"planHash": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"sourceEvidenceHash": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
}
}
}
},
"$defs": {
"adapterEvaluation": {
"type": "object",
"additionalProperties": false,
"required": [
"adapterId",
"ecosystem",
"projectPath",
"manifests",
"support",
"status",
"requiredExecutables",
"missingExecutables",
"message"
],
"properties": {
"adapterId": {
"type": "string",
"minLength": 1
},
"ecosystem": {
"type": "string",
"minLength": 1
},
"projectPath": {
"type": "string",
"minLength": 1
},
"manifests": {
"type": "array",
"items": {
"type": "string"
},
"uniqueItems": true
},
"support": {
"enum": [
"full",
"conditional",
"unsupported"
]
},
"status": {
"enum": [
"ready",
"partial",
"unsupported"
]
},
"requiredExecutables": {
"type": "array",
"items": {
"type": "string"
},
"uniqueItems": true
},
"missingExecutables": {
"type": "array",
"items": {
"type": "string"
},
"uniqueItems": true
},
"message": {
"type": "string"
}
}
},
"invocation": {
"type": "object",
"additionalProperties": false,
"required": [
"cwd",
"executable",
"args",
"purpose",
"timeoutMs"
],
"properties": {
"cwd": {
"type": "string",
"minLength": 1
},
"executable": {
"type": "string",
"minLength": 1
},
"args": {
"type": "array",
"items": {
"type": "string"
}
},
"purpose": {
"enum": [
"repair",
"reconcile",
"audit",
"test",
"build",
"verify"
]
},
"timeoutMs": {
"type": "integer",
"minimum": 1000,
"maximum": 900000
}
}
},
"precondition": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"status",
"message"
],
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"status": {
"enum": [
"passed",
"failed",
"unknown"
]
},
"message": {
"type": "string"
}
}
},
"checkpointFile": {
"type": "object",
"additionalProperties": false,
"required": [
"path",
"existed",
"beforeHash"
],
"properties": {
"path": {
"type": "string",
"minLength": 1
},
"existed": {
"type": "boolean"
},
"beforeHash": {
"type": [
"string",
"null"
]
},
"mode": {
"type": "integer",
"minimum": 0,
"maximum": 65535
},
"afterHash": {
"type": [
"string",
"null"
]
},
"backupRef": {
"type": "string",
"minLength": 1
}
}
},
"checkpoint": {
"type": "object",
"additionalProperties": false,
"required": [
"status",
"files"
],
"properties": {
"status": {
"enum": [
"pending",
"captured",
"restored",
"conflicted",
"unavailable"
]
},
"capturedAt": {
"type": "string",
"format": "date-time"
},
"restoredAt": {
"type": "string",
"format": "date-time"
},
"files": {
"type": "array",
"items": {
"$ref": "#/$defs/checkpointFile"
}
}
}
},
"stage": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"kind",
"status",
"required",
"risk",
"summary"
],
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"kind": {
"enum": [
"repair",
"reconcile",
"audit",
"test",
"build",
"verify",
"rollback"
]
},
"status": {
"enum": [
"pending",
"running",
"passed",
"failed",
"blocked",
"skipped",
"cancelled"
]
},
"required": {
"type": "boolean"
},
"risk": {
"enum": [
"safe",
"guarded",
"invasive"
]
},
"summary": {
"type": "string"
},
"invocation": {
"$ref": "#/$defs/invocation"
},
"startedAt": {
"type": "string",
"format": "date-time"
},
"completedAt": {
"type": "string",
"format": "date-time"
},
"exitCode": {
"type": [
"integer",
"null"
]
},
"stdoutTail": {
"type": "string"
},
"stderrTail": {
"type": "string"
},
"changedPaths": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"verification": {
"type": "object",
"additionalProperties": false,
"required": [
"status",
"artifact",
"exitCode",
"summary"
],
"properties": {
"status": {
"enum": [
"passed",
"failed",
"not-run"
]
},
"targetStatus": {
"enum": [
"passed",
"failed",
"unknown"
]
},
"workspaceStatus": {
"enum": [
"passed",
"blocked",
"failed"
]
},
"remainingActionIds": {
"type": "array",
"uniqueItems": true,
"items": {
"type": "string",
"minLength": 1
}
},
"artifact": {
"const": ".workspai/reports/workspace-intelligence-run-last-run.json"
},
"exitCode": {
"type": [
"integer",
"null"
]
},
"summary": {
"type": "string"
}
}
},
"decision": {
"type": "object",
"additionalProperties": false,
"required": [
"reason",
"options"
],
"properties": {
"reason": {
"type": "string",
"minLength": 1
},
"options": {
"type": "array",
"minItems": 1,
"items": {
"enum": [
"approve-guarded",
"approve-invasive",
"allow-breaking",
"allow-force",
"manual-repair",
"rollback",
"cancel"
]
}
},
"causes": {
"type": "array",
"minItems": 1,
"items": {
"$ref": "#/$defs/decisionCause"
}
}
}
},
"decisionCause": {
"type": "object",
"additionalProperties": false,
"required": [
"kind",
"id",
"message"
],
"properties": {
"kind": {
"enum": [
"missing-executable",
"unsupported-adapter",
"failed-precondition",
"risk-approval",
"policy-exception",
"source-repair-required"
]
},
"id": {
"type": "string",
"minLength": 1
},
"message": {
"type": "string",
"minLength": 1
},
"projectPath": {
"type": "string",
"minLength": 1
},
"adapterId": {
"type": "string",
"minLength": 1
},
"executable": {
"type": "string",
"minLength": 1
}
}
},
"event": {
"type": "object",
"additionalProperties": false,
"required": [
"sequence",
"at",
"type",
"message"
],
"properties": {
"sequence": {
"type": "integer",
"minimum": 1
},
"at": {
"type": "string",
"format": "date-time"
},
"type": {
"enum": [
"planned",
"approval",
"checkpoint",
"stage",
"verification",
"decision",
"rollback",
"closed",
"failed",
"cancelled"
]
},
"stageId": {
"type": "string"
},
"status": {
"type": "string"
},
"message": {
"type": "string"
}
}
}
}
}