workspai 0.46.0 → 0.47.0

package/contracts/workspace-intelligence/workspace-graph-token-efficiency.v1.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://getrapidkit.com/schemas/workspace-graph-token-efficiency.v1.json",
+  "title": "Workspai Graph Retrieval Token-Efficiency Report",
+  "description": "A reproducible character-based estimate comparing readable proof-source text with one bounded graph retrieval payload. It is not an answer-quality or billing claim.",
+  "type": "object",
+  "required": ["schemaVersion", "generatedAt", "workspacePath", "query", "graph", "methodology", "corpus", "retrieval", "savings"],
+  "properties": {
+    "schemaVersion": { "const": "workspace-graph-token-efficiency.v1" },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "workspacePath": { "type": "string", "minLength": 1 },
+    "query": { "type": "string", "minLength": 1 },
+    "graph": {
+      "type": "object",
+      "required": ["schemaVersion", "sourceArtifact", "sourceHash", "entityCount", "relationCount", "proofCount"],
+      "properties": {
+        "schemaVersion": { "const": "workspace-knowledge-graph.v1" },
+        "sourceArtifact": { "type": "string", "minLength": 1 },
+        "sourceHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "entityCount": { "type": "integer", "minimum": 0 },
+        "relationCount": { "type": "integer", "minimum": 0 },
+        "proofCount": { "type": "integer", "minimum": 0 }
+      },
+      "additionalProperties": false
+    },
+    "methodology": {
+      "type": "object",
+      "required": ["id", "estimated", "charsPerToken", "claimBoundary"],
+      "properties": {
+        "id": { "const": "indexed-corpus-vs-bounded-retrieval.v1" },
+        "estimated": { "const": true },
+        "charsPerToken": { "const": 4 },
+        "claimBoundary": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    },
+    "corpus": {
+      "type": "object",
+      "required": ["artifactCount", "characterCount", "estimatedTokens", "unreadableArtifacts"],
+      "properties": {
+        "artifactCount": { "type": "integer", "minimum": 0 },
+        "characterCount": { "type": "integer", "minimum": 0 },
+        "estimatedTokens": { "type": "integer", "minimum": 0 },
+        "unreadableArtifacts": { "type": "array", "items": { "type": "string" }, "uniqueItems": true }
+      },
+      "additionalProperties": false
+    },
+    "retrieval": {
+      "type": "object",
+      "required": ["matchCount", "characterCount", "estimatedTokens", "truncated", "payload"],
+      "properties": {
+        "matchCount": { "type": "integer", "minimum": 0, "maximum": 100 },
+        "characterCount": { "type": "integer", "minimum": 0 },
+        "estimatedTokens": { "type": "integer", "minimum": 0 },
+        "truncated": { "type": "boolean" },
+        "payload": { "$ref": "workspace-knowledge-search.v1.json" }
+      },
+      "additionalProperties": false
+    },
+    "savings": {
+      "type": "object",
+      "required": ["estimatedTokensAvoided", "reductionRatio", "reductionPercent"],
+      "properties": {
+        "estimatedTokensAvoided": { "type": "integer", "minimum": 0 },
+        "reductionRatio": { "type": "number", "minimum": 0 },
+        "reductionPercent": { "type": "number", "minimum": 0, "maximum": 100 }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/contracts/workspace-intelligence/workspace-intelligence-run.v1.json

@@ -69,7 +69,12 @@
           "type": "object",
           "properties": {
             "id": { "const": "model" },
-            "artifacts": { "const": [".workspai/reports/workspace-model.json"] }
+            "artifacts": {
+              "const": [
+                ".workspai/reports/workspace-model.json",
+                ".workspai/reports/workspace-knowledge-graph.json"
+              ]
+            }
           }
         },
         {

package/contracts/workspace-intelligence/workspace-knowledge-graph-change-overlay.v1.json

@@ -0,0 +1,200 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://getrapidkit.com/schemas/workspace-knowledge-graph-change-overlay.v1.json",
+  "title": "Workspai Workspace Knowledge Graph Change Overlay",
+  "description": "Portable graph-to-graph entity and relation changes with bounded impact and proof artifact projection.",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "generatedAt",
+    "workspace",
+    "base",
+    "head",
+    "entities",
+    "relations",
+    "proofs",
+    "impactedEntityIds",
+    "changedArtifacts",
+    "summary"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "workspace-knowledge-graph-change-overlay.v1" },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "workspace": {
+      "type": "object",
+      "required": ["name"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "profile": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "base": { "$ref": "#/$defs/graphRevision" },
+    "head": { "$ref": "#/$defs/graphRevision" },
+    "entities": {
+      "allOf": [
+        { "$ref": "#/$defs/changeSet" },
+        {
+          "properties": {
+            "added": {
+              "type": "array",
+              "items": { "$ref": "workspace-knowledge-graph.v1.json#/properties/entities/items" }
+            },
+            "removed": {
+              "type": "array",
+              "items": { "$ref": "workspace-knowledge-graph.v1.json#/properties/entities/items" }
+            },
+            "changed": { "type": "array", "items": { "$ref": "#/$defs/entityChange" } }
+          }
+        }
+      ]
+    },
+    "relations": {
+      "allOf": [
+        { "$ref": "#/$defs/changeSet" },
+        {
+          "properties": {
+            "added": {
+              "type": "array",
+              "items": { "$ref": "workspace-knowledge-graph.v1.json#/properties/relations/items" }
+            },
+            "removed": {
+              "type": "array",
+              "items": { "$ref": "workspace-knowledge-graph.v1.json#/properties/relations/items" }
+            },
+            "changed": { "type": "array", "items": { "$ref": "#/$defs/relationChange" } }
+          }
+        }
+      ]
+    },
+    "proofs": {
+      "allOf": [
+        { "$ref": "#/$defs/changeSet" },
+        {
+          "properties": {
+            "added": {
+              "type": "array",
+              "items": { "$ref": "workspace-knowledge-graph.v1.json#/properties/proofs/items" }
+            },
+            "removed": {
+              "type": "array",
+              "items": { "$ref": "workspace-knowledge-graph.v1.json#/properties/proofs/items" }
+            },
+            "changed": { "type": "array", "items": { "$ref": "#/$defs/proofChange" } }
+          }
+        }
+      ]
+    },
+    "impactedEntityIds": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true
+    },
+    "changedArtifacts": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "not": { "pattern": "^(?:/|[A-Za-z]:[\\\\/])" }
+      },
+      "uniqueItems": true
+    },
+    "summary": {
+      "type": "object",
+      "required": [
+        "entityAdds",
+        "entityRemovals",
+        "entityChanges",
+        "relationAdds",
+        "relationRemovals",
+        "relationChanges",
+        "proofAdds",
+        "proofRemovals",
+        "proofChanges",
+        "impactedEntities",
+        "changedArtifacts",
+        "risk"
+      ],
+      "properties": {
+        "entityAdds": { "type": "integer", "minimum": 0 },
+        "entityRemovals": { "type": "integer", "minimum": 0 },
+        "entityChanges": { "type": "integer", "minimum": 0 },
+        "relationAdds": { "type": "integer", "minimum": 0 },
+        "relationRemovals": { "type": "integer", "minimum": 0 },
+        "relationChanges": { "type": "integer", "minimum": 0 },
+        "proofAdds": { "type": "integer", "minimum": 0 },
+        "proofRemovals": { "type": "integer", "minimum": 0 },
+        "proofChanges": { "type": "integer", "minimum": 0 },
+        "impactedEntities": { "type": "integer", "minimum": 0 },
+        "changedArtifacts": { "type": "integer", "minimum": 0 },
+        "risk": { "enum": ["none", "low", "medium", "high"] }
+      },
+      "additionalProperties": false
+    }
+  },
+  "$defs": {
+    "graphRevision": {
+      "type": "object",
+      "required": ["schemaVersion", "generatedAt", "fingerprint"],
+      "properties": {
+        "schemaVersion": { "const": "workspace-knowledge-graph.v1" },
+        "generatedAt": { "type": "string", "format": "date-time" },
+        "fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+      },
+      "additionalProperties": false
+    },
+    "changeSet": {
+      "type": "object",
+      "required": ["added", "removed", "changed"]
+    },
+    "entityChange": {
+      "type": "object",
+      "required": ["id", "before", "after", "changedFields"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "before": { "$ref": "workspace-knowledge-graph.v1.json#/properties/entities/items" },
+        "after": { "$ref": "workspace-knowledge-graph.v1.json#/properties/entities/items" },
+        "changedFields": {
+          "type": "array",
+          "items": { "type": "string" },
+          "minItems": 1,
+          "uniqueItems": true
+        }
+      },
+      "additionalProperties": false
+    },
+    "relationChange": {
+      "type": "object",
+      "required": ["id", "before", "after", "changedFields"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "before": { "$ref": "workspace-knowledge-graph.v1.json#/properties/relations/items" },
+        "after": { "$ref": "workspace-knowledge-graph.v1.json#/properties/relations/items" },
+        "changedFields": {
+          "type": "array",
+          "items": { "type": "string" },
+          "minItems": 1,
+          "uniqueItems": true
+        }
+      },
+      "additionalProperties": false
+    },
+    "proofChange": {
+      "type": "object",
+      "required": ["id", "before", "after", "changedFields"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "before": { "$ref": "workspace-knowledge-graph.v1.json#/properties/proofs/items" },
+        "after": { "$ref": "workspace-knowledge-graph.v1.json#/properties/proofs/items" },
+        "changedFields": {
+          "type": "array",
+          "items": { "type": "string" },
+          "minItems": 1,
+          "uniqueItems": true
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/contracts/workspace-intelligence/workspace-knowledge-graph.v1.json

@@ -0,0 +1,260 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://getrapidkit.com/schemas/workspace-knowledge-graph.v1.json",
+  "title": "Workspai Evidence-backed Workspace Knowledge Graph",
+  "description": "Portable, provider-neutral workspace entities, relations and proof paths with the canonical project dependency topology embedded as a projection.",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "generatedAt",
+    "source",
+    "workspace",
+    "projectTopology",
+    "entities",
+    "relations",
+    "proofs",
+    "providers",
+    "quality",
+    "diagnostics"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "workspace-knowledge-graph.v1" },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "source": {
+      "type": "object",
+      "required": ["kind", "artifact", "hashAlgorithm", "hash"],
+      "properties": {
+        "kind": { "enum": ["workspace-model", "workspace-contract", "workspace-sources"] },
+        "artifact": { "type": "string", "minLength": 1 },
+        "hashAlgorithm": { "const": "sha256" },
+        "hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+      },
+      "additionalProperties": false
+    },
+    "workspace": {
+      "type": "object",
+      "required": ["name"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "profile": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "projectTopology": { "$ref": "workspace-dependency-graph.v1.json" },
+    "entities": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "kind", "label", "identity", "attributes", "proofIds"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "kind": {
+            "enum": [
+              "workspace",
+              "project",
+              "service",
+              "api",
+              "endpoint",
+              "schema",
+              "package",
+              "module",
+              "file",
+              "symbol",
+              "database",
+              "queue",
+              "container",
+              "deployment",
+              "pipeline",
+              "environment",
+              "document",
+              "decision",
+              "test-suite",
+              "owner"
+            ]
+          },
+          "label": { "type": "string", "minLength": 1 },
+          "projectId": { "type": "string", "minLength": 1 },
+          "identity": {
+            "type": "object",
+            "required": ["key", "scope", "aliases", "fingerprint"],
+            "properties": {
+              "key": { "type": "string", "minLength": 1 },
+              "scope": { "enum": ["workspace", "project"] },
+              "aliases": { "type": "array", "items": { "type": "string" } },
+              "fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+            },
+            "additionalProperties": false
+          },
+          "attributes": {
+            "type": "object",
+            "additionalProperties": {
+              "type": ["string", "number", "boolean", "null", "array"],
+              "items": { "type": ["string", "number", "boolean", "null"] }
+            }
+          },
+          "proofIds": {
+            "type": "array",
+            "items": { "type": "string", "minLength": 1 },
+            "uniqueItems": true
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "relations": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "from", "to", "kind", "derivation", "trust", "confidence", "proofIds"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "from": { "type": "string", "minLength": 1 },
+          "to": { "type": "string", "minLength": 1 },
+          "kind": {
+            "enum": [
+              "contains",
+              "defines",
+              "imports",
+              "depends-on",
+              "exposes",
+              "implements",
+              "calls",
+              "reads-from",
+              "writes-to",
+              "publishes",
+              "consumes",
+              "deploys",
+              "runs-on",
+              "routes-to",
+              "documents",
+              "decided-by",
+              "tests",
+              "owns",
+              "generated-by",
+              "configured-by",
+              "references"
+            ]
+          },
+          "derivation": { "enum": ["extracted", "inferred", "authored"] },
+          "trust": { "enum": ["authoritative", "corroborated", "observed", "ambiguous"] },
+          "confidence": { "enum": ["high", "medium", "low"] },
+          "proofIds": {
+            "type": "array",
+            "items": { "type": "string", "minLength": 1 },
+            "minItems": 1,
+            "uniqueItems": true
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "proofs": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "provider",
+          "artifact",
+          "observedAt",
+          "derivation",
+          "trust",
+          "confidence",
+          "freshness"
+        ],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "provider": { "type": "string", "minLength": 1 },
+          "artifact": {
+            "type": "string",
+            "minLength": 1,
+            "not": { "pattern": "^(?:/|[A-Za-z]:[\\\\/])" }
+          },
+          "pointer": { "type": "string" },
+          "line": { "type": "integer", "minimum": 1 },
+          "column": { "type": "integer", "minimum": 1 },
+          "contentHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+          "observedAt": { "type": "string", "format": "date-time" },
+          "derivation": { "enum": ["extracted", "inferred", "authored"] },
+          "trust": { "enum": ["authoritative", "corroborated", "observed", "ambiguous"] },
+          "confidence": { "enum": ["high", "medium", "low"] },
+          "freshness": { "enum": ["fresh", "stale", "unknown"] },
+          "detail": { "type": "string" }
+        },
+        "additionalProperties": false
+      }
+    },
+    "providers": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "version",
+          "status",
+          "permission",
+          "discoveredEntities",
+          "discoveredRelations",
+          "proofCount",
+          "diagnostics"
+        ],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "version": { "type": "string", "minLength": 1 },
+          "status": { "enum": ["passed", "partial", "skipped", "failed"] },
+          "permission": { "enum": ["filesystem-read", "git-read", "runtime-probe", "network"] },
+          "discoveredEntities": { "type": "integer", "minimum": 0 },
+          "discoveredRelations": { "type": "integer", "minimum": 0 },
+          "proofCount": { "type": "integer", "minimum": 0 },
+          "diagnostics": { "type": "array", "items": { "type": "string" } }
+        },
+        "additionalProperties": false
+      }
+    },
+    "quality": {
+      "type": "object",
+      "required": [
+        "entityCount",
+        "relationCount",
+        "proofCount",
+        "entityProofCoverageRatio",
+        "relationProofCoverageRatio",
+        "providerSuccessRatio",
+        "conflictCount",
+        "unknownCount",
+        "portable",
+        "secretValuesEmitted"
+      ],
+      "properties": {
+        "entityCount": { "type": "integer", "minimum": 0 },
+        "relationCount": { "type": "integer", "minimum": 0 },
+        "proofCount": { "type": "integer", "minimum": 0 },
+        "entityProofCoverageRatio": { "type": "number", "minimum": 0, "maximum": 1 },
+        "relationProofCoverageRatio": { "type": "number", "minimum": 0, "maximum": 1 },
+        "providerSuccessRatio": { "type": "number", "minimum": 0, "maximum": 1 },
+        "conflictCount": { "type": "integer", "minimum": 0 },
+        "unknownCount": { "type": "integer", "minimum": 0 },
+        "portable": { "const": true },
+        "secretValuesEmitted": { "const": false }
+      },
+      "additionalProperties": false
+    },
+    "diagnostics": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["code", "severity", "message"],
+        "properties": {
+          "code": { "type": "string", "minLength": 1 },
+          "severity": { "enum": ["info", "warning", "error"] },
+          "message": { "type": "string", "minLength": 1 },
+          "entityIds": { "type": "array", "items": { "type": "string" } },
+          "relationIds": { "type": "array", "items": { "type": "string" } },
+          "recommendation": { "type": "string" }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/contracts/workspace-intelligence/workspace-knowledge-search.v1.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://getrapidkit.com/schemas/workspace-knowledge-search.v1.json",
+  "title": "Workspai Bounded Knowledge Graph Search",
+  "description": "A deterministic, bounded, proof-carrying retrieval projection intended for agents, MCP clients, IDEs, and CI consumers.",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "query",
+    "kind",
+    "limit",
+    "totalMatches",
+    "truncated",
+    "entities",
+    "relatedEntities",
+    "relations",
+    "proofs"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "workspace-knowledge-search.v1" },
+    "query": { "type": "string", "minLength": 1 },
+    "kind": {
+      "oneOf": [
+        { "type": "null" },
+        { "$ref": "workspace-knowledge-graph.v1.json#/properties/entities/items/properties/kind" }
+      ]
+    },
+    "limit": { "type": "integer", "minimum": 1, "maximum": 100 },
+    "totalMatches": { "type": "integer", "minimum": 0 },
+    "truncated": { "type": "boolean" },
+    "entities": {
+      "type": "array",
+      "maxItems": 100,
+      "items": { "$ref": "workspace-knowledge-graph.v1.json#/properties/entities/items" }
+    },
+    "relatedEntities": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "kind", "label"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "kind": { "$ref": "workspace-knowledge-graph.v1.json#/properties/entities/items/properties/kind" },
+          "label": { "type": "string", "minLength": 1 },
+          "projectId": { "type": "string", "minLength": 1 }
+        },
+        "additionalProperties": false
+      }
+    },
+    "relations": {
+      "type": "array",
+      "items": { "$ref": "workspace-knowledge-graph.v1.json#/properties/relations/items" }
+    },
+    "proofs": {
+      "type": "array",
+      "items": { "$ref": "workspace-knowledge-graph.v1.json#/properties/proofs/items" }
+    }
+  },
+  "additionalProperties": false
+}

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

@@ -159,6 +159,7 @@
       "label": "System understanding",
       "artifacts": [
         ".workspai/reports/workspace-model.json",
+        ".workspai/reports/workspace-knowledge-graph.json",
         ".workspai/reports/workspace-model-diff-last-run.json",
         ".workspai/reports/workspace-impact-last-run.json"
       ],
@@ -302,9 +303,10 @@
         "workspace graph mermaid"
       ],
       "reads": [
-        ".workspai/reports/workspace-model.json#graph"
+        ".workspai/reports/workspace-model.json",
+        ".workspai/reports/workspace-knowledge-graph.json"
       ],
-      "role": "Inspect or render the graph already embedded in the workspace model.",
+      "role": "Query the proof-backed graph derived from the canonical workspace model.",
       "chainStep": false
     },
     {
@@ -345,7 +347,8 @@
           "workspace model --json --write"
         ],
         "artifacts": [
-          ".workspai/reports/workspace-model.json"
+          ".workspai/reports/workspace-model.json",
+          ".workspai/reports/workspace-knowledge-graph.json"
         ]
       },
       {