@geraldmaron/construct 1.4.1 → 1.5.0

package/rules/common/comments.md

@@ -42,6 +42,7 @@ The blank line between the comment and the code is required. It signals "this co
 - **Narrative voice** (`// We weight BM25`, `// Now test the keys`, `// This correctly scores`) delete them
 - **Point-in-time notes** (`// X removed`, `// previously`, `// no longer`) belongs in git log
 - **Noise sentinels** (`// ok`, `// best effort`, `// skip`) delete them; use `/* non-critical */` inline only when the catch clause would otherwise look like a bug
+- **Other-project comparisons** (`// per the LangGraph thread-vs-store split`) delete them; describe the behavior on its own terms. A prior-art comparison belongs in a decision document (`docs/decisions/**`, `docs/notes/**`) where it can carry a citation
 
 ## SLA annotations (hooks only)
 

package/schemas/brand-voice.schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://geraldmaron.github.io/construct/schemas/brand-voice.schema.json",
+  "title": "Project brand voice override",
+  "type": "object",
+  "required": ["version"],
+  "additionalProperties": false,
+  "properties": {
+    "version": { "type": "integer", "minimum": 1 },
+    "formality": { "type": "integer", "minimum": 1, "maximum": 5 },
+    "toneOverride": {
+      "type": "object",
+      "description": "Maps doc type id to tone profile id from specialists/tone-profiles.json",
+      "additionalProperties": { "type": "string" }
+    },
+    "audienceLexicon": {
+      "type": "object",
+      "properties": {
+        "prefer": { "type": "array", "items": { "type": "string" } },
+        "avoid": { "type": "array", "items": { "type": "string" } }
+      }
+    }
+  }
+}

package/schemas/capability-registry.schema.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://construct.dev/schemas/capability-registry.schema.json",
+  "title": "Construct Capability Registry",
+  "type": "object",
+  "required": ["version", "capabilities"],
+  "properties": {
+    "version": { "type": "integer", "minimum": 1 },
+    "capabilities": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/capability" }
+    }
+  },
+  "$defs": {
+    "surfaceEntry": {
+      "type": "object",
+      "properties": {
+        "supported": { "type": "boolean" },
+        "primary": { "type": "boolean" },
+        "tool": { "type": "string" },
+        "command": { "type": "string" },
+        "jsonTwin": { "type": "boolean" },
+        "slashCommand": { "type": "string" }
+      }
+    },
+    "capability": {
+      "type": "object",
+      "required": ["id", "kind", "humanGate"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9.-]*$" },
+        "kind": {
+          "enum": ["capability", "workflow", "skill", "document-type", "ingest-strategy", "contract-chain"]
+        },
+        "name": { "type": "string" },
+        "description": { "type": "string" },
+        "criticality": { "enum": ["P0", "P1", "P2", "P3"] },
+        "ownerSpecialists": { "type": "array", "items": { "type": "string" } },
+        "skill": { "type": "string" },
+        "embeddedWorkflow": { "type": "string" },
+        "template": { "type": "string" },
+        "ingestStrategy": { "type": "string" },
+        "contracts": { "type": "array", "items": { "type": "string" } },
+        "surfaces": {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/surfaceEntry" }
+        },
+        "dependencies": {
+          "type": "object",
+          "properties": {
+            "skills": { "type": "array", "items": { "type": "string" } },
+            "templates": { "type": "array", "items": { "type": "string" } },
+            "rules": { "type": "array", "items": { "type": "string" } }
+          }
+        },
+        "verification": {
+          "type": "object",
+          "properties": {
+            "functional": { "type": "string" },
+            "hostEmulation": { "type": "string" },
+            "structureRequirements": { "type": "string" },
+            "verificationBar": { "type": "string" },
+            "untestableRationale": { "type": "string" }
+          }
+        },
+        "humanGate": {
+          "enum": ["proposal-only", "requires-human-approval", "autonomous"]
+        },
+        "lastValidated": { "type": ["string", "null"], "format": "date-time" }
+      }
+    }
+  }
+}

package/schemas/certification-run.schema.json

@@ -0,0 +1,130 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://construct.dev/schemas/certification-run.schema.json",
+  "title": "CertificationRun",
+  "description": "Durable result of a scenario-based certification execution. Records model, fixture, gates, qualitative verdict, cost, and redacted output pointers without storing secrets.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "id",
+    "scenarioId",
+    "capabilityId",
+    "model",
+    "fixture",
+    "verdict",
+    "gates",
+    "timing",
+    "evidenceVersion",
+    "createdAt"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "id": { "type": "string", "minLength": 1 },
+    "scenarioId": { "type": "string", "minLength": 1 },
+    "capabilityId": { "type": "string", "minLength": 1 },
+    "model": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["provider", "requestedId", "resolvedId", "tier"],
+      "properties": {
+        "provider": { "type": "string", "minLength": 1 },
+        "requestedId": { "type": "string", "minLength": 1 },
+        "resolvedId": { "type": "string", "minLength": 1 },
+        "tier": { "enum": ["free", "paid-reference", "hermetic", "unknown"] },
+        "paidOptIn": { "type": "boolean" },
+        "operatorAckAt": { "type": ["string", "null"] }
+      }
+    },
+    "fixture": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "sha256"],
+      "properties": {
+        "path": { "type": "string", "minLength": 1 },
+        "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+      }
+    },
+    "verdict": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "source"],
+      "properties": {
+        "status": { "enum": ["pass", "fail", "inconclusive"] },
+        "source": { "enum": ["deterministic", "qualitative", "skipped-provider", "error"] },
+        "reason": { "type": ["string", "null"] }
+      }
+    },
+    "gates": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "pass"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "pass": { "type": "boolean" },
+          "detail": { "type": ["string", "null"] },
+          "evidence": { "type": ["string", "null"] }
+        }
+      }
+    },
+    "qualitative": {
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "properties": {
+        "judgeModel": { "type": ["string", "null"] },
+        "score": { "type": ["number", "null"] },
+        "abstained": { "type": "boolean" }
+      }
+    },
+    "evaluation": {
+      "type": ["object", "null"],
+      "additionalProperties": true,
+      "properties": {
+        "schemaVersion": { "type": "integer" },
+        "blocked": { "type": ["boolean", "null"] },
+        "gates": { "type": "array" },
+        "evaluators": { "type": "array" },
+        "decision": {
+          "type": "object",
+          "properties": {
+            "promotable": { "type": "boolean" },
+            "reason": { "type": "string" },
+            "judgesConsulted": { "type": "integer" }
+          }
+        }
+      }
+    },
+    "timing": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["latencyMs"],
+      "properties": {
+        "latencyMs": { "type": "number", "minimum": 0 },
+        "startedAt": { "type": ["string", "null"] },
+        "finishedAt": { "type": ["string", "null"] }
+      }
+    },
+    "cost": {
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "properties": {
+        "currency": { "type": "string" },
+        "inputTokens": { "type": ["number", "null"] },
+        "outputTokens": { "type": ["number", "null"] },
+        "totalUsd": { "type": ["number", "null"] }
+      }
+    },
+    "artifacts": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "outputMarkdown": { "type": ["string", "null"] },
+        "outputJson": { "type": ["string", "null"] }
+      }
+    },
+    "evidenceVersion": { "type": "string", "minLength": 1 },
+    "createdAt": { "type": "string", "minLength": 1 }
+  }
+}

package/schemas/demo-recording.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://construct.dev/schemas/demo-recording.schema.json",
+  "title": "Construct demo recording manifest",
+  "type": "object",
+  "required": ["spec"],
+  "properties": {
+    "name": { "type": "string" },
+    "title": { "type": "string" },
+    "engine": { "enum": ["playwright"] },
+    "workspace": { "type": "string", "default": "." },
+    "spec": { "type": "string" },
+    "playwrightConfig": { "type": "string" },
+    "baseUrl": { "type": "string", "format": "uri" },
+    "project": { "type": "string" },
+    "skipWebServer": { "type": "boolean" },
+    "timeout": { "type": "number" },
+    "webServer": {
+      "type": "object",
+      "properties": {
+        "command": { "type": "string" },
+        "url": { "type": "string" },
+        "cwd": { "type": "string" },
+        "timeout": { "type": "number" }
+      },
+      "required": ["command", "url"]
+    },
+    "artifactReveal": {
+      "type": "object",
+      "properties": {
+        "mode": { "enum": ["sameOrigin", "constructPreview"] },
+        "staticDir": { "type": "string" },
+        "file": { "type": "string" },
+        "path": { "type": "string" },
+        "scroll": { "type": "boolean" }
+      }
+    },
+    "output": {
+      "type": "object",
+      "properties": {
+        "format": { "enum": ["mp4", "webm"] },
+        "path": { "type": "string" }
+      }
+    }
+  }
+}

package/schemas/eval-dataset.schema.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://construct.dev/schemas/eval-dataset.schema.json",
+  "title": "EvalDatasetItem",
+  "description": "One provenance-backed evaluation dataset item for the governed AI improvement loop (construct-6zga.1.6). Preserves task input, capability snapshot, allowed tools, expected evidence and contract behavior, redaction state, source trace ids, human-label provenance, split assignment, and expiry, so a candidate can be evaluated on a held-out item that is provably not its own generating trace.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion", "id", "taskFamily", "taskInput", "capabilitySnapshot",
+    "allowedTools", "expectedEvidenceBehavior", "expectedContractResult",
+    "redaction", "sourceTraceIds", "humanLabel", "split", "expiry"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "id": { "type": "string", "minLength": 1 },
+    "taskFamily": { "type": "string", "minLength": 1 },
+    "taskInput": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["prompt"],
+      "properties": {
+        "prompt": { "type": "string" },
+        "intent": { "type": ["string", "null"] },
+        "risk": { "type": ["string", "null"] }
+      }
+    },
+    "capabilitySnapshot": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["capabilityClass"],
+      "properties": {
+        "capabilityClass": { "enum": ["hosted-direct", "hosted-routed", "local-capable", "local-constrained", "unknown"] },
+        "transport": { "type": ["string", "null"] },
+        "operatingProfileId": { "type": ["string", "null"] }
+      }
+    },
+    "allowedTools": { "type": "array", "items": { "type": "string" } },
+    "expectedEvidenceBehavior": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["requirement", "citationsRequired"],
+      "properties": {
+        "requirement": { "enum": ["none", "preferred", "required"] },
+        "citationsRequired": { "type": "boolean" }
+      }
+    },
+    "expectedContractResult": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["outcome"],
+      "properties": {
+        "outcome": { "enum": ["pass", "fail", "blocker", "handoff"] }
+      }
+    },
+    "redaction": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["state"],
+      "properties": {
+        "state": { "enum": ["raw", "redacted", "synthetic"] },
+        "fields": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "sourceTraceIds": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
+    "humanLabel": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["provenance"],
+      "properties": {
+        "provenance": { "enum": ["human", "model-assisted", "unlabeled"] },
+        "labeledBy": { "type": ["string", "null"] },
+        "rubricVersion": { "type": ["string", "null"] },
+        "correctionId": { "type": ["string", "null"] }
+      }
+    },
+    "split": { "enum": ["train", "dev", "test"] },
+    "expiry": { "type": ["string", "null"], "description": "ISO 8601 date after which the item is stale, or null for non-expiring" }
+  }
+}

package/schemas/execution-capability-profile.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://construct.dev/schemas/execution-capability-profile.schema.json",
+  "title": "Construct Execution Capability Profile",
+  "description": "The single resolved capability record consumed by model routing and specialist prompt composition (construct-6zga.1.8). Keyed by provider, requested/resolved model, adapter protocol, and observation time. Every capability declares its evidence source and confidence; unknowns compile to conservative defaults with a degraded flag.",
+  "type": "object",
+  "required": ["schemaVersion", "key", "capabilityClass", "transport", "capabilities", "degraded", "evidenceSources"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": { "type": "integer", "minimum": 1 },
+    "key": {
+      "type": "object",
+      "required": ["provider", "requestedModel", "resolvedModel", "adapterProtocol", "observedAt"],
+      "additionalProperties": false,
+      "properties": {
+        "provider": { "type": "string" },
+        "requestedModel": { "type": ["string", "null"] },
+        "resolvedModel": { "type": ["string", "null"] },
+        "adapterProtocol": { "type": "string" },
+        "observedAt": { "type": ["string", "null"] }
+      }
+    },
+    "capabilityClass": { "enum": ["hosted-direct", "hosted-routed", "local-constrained", "local-capable", "unknown"] },
+    "transport": { "enum": ["direct", "routed", "local", "unknown"] },
+    "capabilities": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#/$defs/field" }
+    },
+    "degraded": { "type": "boolean" },
+    "evidenceSources": { "type": "array", "items": { "$ref": "#/$defs/evidenceSource" } }
+  },
+  "$defs": {
+    "evidenceSource": { "enum": ["provider_metadata", "live_probe", "operator_override", "compatibility_fallback", "unknown"] },
+    "confidence": { "enum": ["high", "medium", "low", "none"] },
+    "field": {
+      "type": "object",
+      "required": ["value", "source", "confidence"],
+      "additionalProperties": false,
+      "properties": {
+        "value": {},
+        "source": { "$ref": "#/$defs/evidenceSource" },
+        "confidence": { "$ref": "#/$defs/confidence" }
+      }
+    }
+  }
+}

package/schemas/execution-policy.schema.json

@@ -0,0 +1,114 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://construct.dev/schemas/execution-policy.schema.json",
+  "title": "Construct Execution Policy",
+  "description": "The immutable per-turn execution policy compiled from an ExecutionCapabilityProfile plus the turn's intent, risk, and evidence requirement (construct-6zga.1.2). The single record the owned loop reads for prompt section budgets, tool limits, evidence-first requirement, output budget, visible-thinking policy, continuation/compaction trigger, and caching eligibility. Compiled only from measured capability class/transport/values and the turn inputs — never from a provider or model name.",
+  "type": "object",
+  "required": ["schemaVersion", "source", "prompt", "tools", "evidence", "output", "continuation", "caching", "degradedMode", "telemetry"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": { "type": "integer", "minimum": 1 },
+    "source": {
+      "type": "object",
+      "required": ["capabilityClass", "transport", "intent", "risk", "evidenceRequirement", "evidenceSources"],
+      "additionalProperties": false,
+      "properties": {
+        "profileSchemaVersion": { "type": ["integer", "null"] },
+        "profileKey": {
+          "type": ["object", "null"],
+          "properties": {
+            "provider": { "type": "string" },
+            "requestedModel": { "type": ["string", "null"] },
+            "resolvedModel": { "type": ["string", "null"] },
+            "adapterProtocol": { "type": "string" },
+            "observedAt": { "type": ["string", "null"] }
+          }
+        },
+        "capabilityClass": { "$ref": "#/$defs/capabilityClass" },
+        "transport": { "enum": ["direct", "routed", "local", "unknown"] },
+        "intent": { "$ref": "#/$defs/intent" },
+        "risk": { "$ref": "#/$defs/risk" },
+        "evidenceRequirement": { "$ref": "#/$defs/evidenceRequirement" },
+        "evidenceSources": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "prompt": {
+      "type": "object",
+      "required": ["systemPromptTier", "operatingProfileId", "sectionBudgets", "retrievalFirst", "preferCompressedGuidance"],
+      "additionalProperties": false,
+      "properties": {
+        "systemPromptTier": { "type": "string" },
+        "operatingProfileId": { "type": "string" },
+        "sectionBudgets": {
+          "type": "object",
+          "additionalProperties": { "type": "integer", "minimum": 0 }
+        },
+        "retrievalFirst": { "type": "boolean" },
+        "preferCompressedGuidance": { "type": "boolean" }
+      }
+    },
+    "tools": {
+      "type": "object",
+      "required": ["maxToolSchemas", "allowedToolGroups", "maxToolIterations"],
+      "additionalProperties": false,
+      "properties": {
+        "maxToolSchemas": { "type": "integer", "minimum": 0 },
+        "allowedToolGroups": { "type": "array", "items": { "$ref": "#/$defs/toolGroup" } },
+        "maxToolIterations": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "evidence": {
+      "type": "object",
+      "required": ["evidenceFirst", "citationsRequired"],
+      "additionalProperties": false,
+      "properties": {
+        "evidenceFirst": { "type": "boolean" },
+        "citationsRequired": { "type": "boolean" }
+      }
+    },
+    "output": {
+      "type": "object",
+      "required": ["outputTokenBudget", "visibleThinking"],
+      "additionalProperties": false,
+      "properties": {
+        "outputTokenBudget": { "type": "integer", "minimum": 1 },
+        "visibleThinking": { "enum": ["hidden", "summary", "full"] }
+      }
+    },
+    "continuation": {
+      "type": "object",
+      "required": ["compactionTriggerRatio", "compactionTriggerTokens"],
+      "additionalProperties": false,
+      "properties": {
+        "compactionTriggerRatio": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 },
+        "compactionTriggerTokens": { "type": ["integer", "null"], "minimum": 1 }
+      }
+    },
+    "caching": {
+      "type": "object",
+      "required": ["eligible", "scope"],
+      "additionalProperties": false,
+      "properties": {
+        "eligible": { "type": "boolean" },
+        "scope": { "enum": ["none", "stable-prefix"] }
+      }
+    },
+    "degradedMode": { "type": "boolean" },
+    "telemetry": {
+      "type": "object",
+      "required": ["degraded", "reasons"],
+      "additionalProperties": false,
+      "properties": {
+        "degraded": { "type": "boolean" },
+        "reasons": { "type": "array", "items": { "type": "string" } }
+      }
+    }
+  },
+  "$defs": {
+    "capabilityClass": { "enum": ["hosted-direct", "hosted-routed", "local-constrained", "local-capable", "unknown"] },
+    "intent": { "enum": ["repository-summary", "code-change", "research", "tool-failure", "general"] },
+    "risk": { "enum": ["low", "medium", "high"] },
+    "evidenceRequirement": { "enum": ["none", "preferred", "required"] },
+    "toolGroup": { "enum": ["read", "search", "edit", "shell", "construct", "heavy-mcp"] }
+  }
+}

package/schemas/improvement-proposal.schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://construct.dev/schemas/improvement-proposal.schema.json",
+  "title": "ImprovementProposal",
+  "description": "A candidate change in the governed AI improvement loop (construct-6zga.1.5). Never an applied mutation: it declares its type, affected profiles, blast radius, rollback target, required gates, approver, and rollout mode, plus immutable lineage, and moves only through the legal operator states.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion", "id", "type", "state", "affectedProfiles", "blastRadius",
+    "rollbackTarget", "requiredGates", "rolloutMode", "lineage", "approver"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "id": { "type": "string", "minLength": 1 },
+    "type": { "enum": ["prompt", "role-flavor", "skill", "routing-rule", "contract", "provider-adapter", "policy-config"] },
+    "state": {
+      "enum": ["observed", "rejected", "reproduce_failed", "baseline_failed", "proposal_ready", "evaluation_failed", "awaiting_approval", "approved", "applied", "rolled_back", "superseded"]
+    },
+    "affectedProfiles": { "type": "array", "items": { "type": "string" } },
+    "blastRadius": { "enum": ["single-surface", "multi-surface", "global"] },
+    "rollbackTarget": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["version"],
+      "properties": {
+        "version": { "type": "string" },
+        "ref": { "type": ["string", "null"] }
+      }
+    },
+    "requiredGates": { "type": "array", "items": { "type": "string" } },
+    "rolloutMode": { "enum": ["sandbox", "staged", "monitored"] },
+    "dependencies": { "type": "array", "items": { "type": "string" } },
+    "evaluationReportId": { "type": ["string", "null"] },
+    "terminalReason": { "type": ["string", "null"] },
+    "lineage": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["inputTraceIds", "baselineVersion", "candidateVersion", "capabilitySnapshot", "evaluatorVersions"],
+      "properties": {
+        "inputTraceIds": { "type": "array", "items": { "type": "string" }, "description": "Immutable input-trace references; the controller refuses an empty set as insufficient provenance" },
+        "baselineVersion": { "type": "string" },
+        "candidateVersion": { "type": "string" },
+        "capabilitySnapshot": { "type": "object" },
+        "evaluatorVersions": { "type": "array", "items": { "type": "string" } },
+        "budgets": { "type": ["object", "null"] }
+      }
+    },
+    "approver": {
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "additionalProperties": true,
+          "required": ["identity"],
+          "properties": {
+            "identity": { "type": "string" },
+            "approvedAt": { "type": ["string", "null"] },
+            "decision": { "type": ["string", "null"] }
+          }
+        }
+      ]
+    },
+    "rollout": { "type": ["object", "null"] }
+  }
+}

package/schemas/mcp-tool-output.schema.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://construct.dev/schemas/mcp-tool-output.schema.json",
+  "title": "Construct MCP tool output/error envelope (target contract)",
+  "description": "Target, additive contract for MCP tool results (self-audit construct-rr63.6.1). Tools today return ad-hoc shapes: a success payload, or { error: string }. There is no outputSchema and no structured error vocabulary. This contract defines the typed error and degradation shape a Wave-4 implementation migrates toward. It is intentionally not yet wired into the 75 tool registrations; the migration accepts the legacy string error OR the structured object so it can land tool-by-tool without breaking callers.",
+  "type": "object",
+  "properties": {
+    "error": {
+      "description": "Absent on success. Legacy ad-hoc string OR the structured target object.",
+      "oneOf": [
+        {
+          "type": "string",
+          "description": "Legacy ad-hoc error message (current behaviour, to be migrated)."
+        },
+        {
+          "type": "object",
+          "required": ["code", "message"],
+          "additionalProperties": false,
+          "properties": {
+            "code": {
+              "type": "string",
+              "description": "Stable, machine-branchable discriminant.",
+              "enum": [
+                "INVALID_INPUT",
+                "NOT_FOUND",
+                "CAPABILITY_UNAVAILABLE",
+                "PROVIDER_EXECUTION_FAILED",
+                "SERVER_UNREACHABLE",
+                "INTERNAL"
+              ]
+            },
+            "message": {
+              "type": "string",
+              "description": "Human-readable explanation."
+            },
+            "details": {
+              "type": "object",
+              "description": "Optional structured context (offending field, path, provider, etc.)."
+            }
+          }
+        }
+      ]
+    },
+    "degraded": {
+      "type": "boolean",
+      "description": "True when the tool returned a reduced result instead of failing — e.g. a capability the host could not provide."
+    },
+    "degradationReason": {
+      "type": "string",
+      "description": "Typed reason a result is degraded. Shared vocabulary with the host capability matrix (construct-rr63.4.1).",
+      "enum": [
+        "not-installed",
+        "config-missing",
+        "mcp-unresolvable",
+        "token-unset",
+        "server-unreachable",
+        "capability-unavailable"
+      ]
+    }
+  }
+}