mirai-graph 1.0.0-rc.1

package/schemas/relation.schema.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mirai-graph.dev/schemas/relation.schema.json",
+  "title": "Mirai Graph Relation",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["id", "type", "source", "target", "readiness", "evidence", "profile"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^relation\\.[a-z0-9_.]+$"
+    },
+    "type": {
+      "type": "string",
+      "minLength": 1
+    },
+    "source": {
+      "type": "string",
+      "minLength": 1
+    },
+    "target": {
+      "type": "string",
+      "minLength": 1
+    },
+    "readiness": {
+      "type": "string",
+      "enum": ["draft", "review_ready", "accepted", "blocked", "deprecated"]
+    },
+    "evidence": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "uniqueItems": true
+    },
+    "profile": {
+      "type": "string",
+      "minLength": 1
+    }
+  }
+}

package/schemas/risk-control-matrix.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mirai-graph.dev/schemas/risk-control-matrix.schema.json",
+  "title": "Mirai Graph Risk Control Matrix",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["schema_version", "id", "profile", "public_safety", "risks", "evidence_refs", "limitations"],
+  "properties": {
+    "schema_version": { "type": "string", "minLength": 1 },
+    "id": { "type": "string", "minLength": 1 },
+    "profile": { "const": "implementation_control" },
+    "public_safety": { "const": "synthetic_public" },
+    "risks": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["id", "severity", "description", "detection_signal", "prevention", "gate_or_validator", "evidence_requirement", "recovery_action", "escalation_rule", "owner_role"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "severity": { "enum": ["critical", "high", "medium", "low"] },
+          "description": { "type": "string", "minLength": 1 },
+          "detection_signal": { "type": "string", "minLength": 1 },
+          "prevention": { "type": "string", "minLength": 1 },
+          "gate_or_validator": { "type": "string", "minLength": 1 },
+          "evidence_requirement": { "type": "string", "minLength": 1 },
+          "recovery_action": { "type": "string", "minLength": 1 },
+          "escalation_rule": { "type": "string", "minLength": 1 },
+          "owner_role": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "evidence_refs": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } },
+    "limitations": { "type": "array", "items": { "type": "string" } }
+  }
+}

package/schemas/route-explanation.schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mirai-graph.dev/schemas/route-explanation.schema.json",
+  "title": "Mirai Graph Route Explanation",
+  "type": "object",
+  "additionalProperties": true,
+  "required": [
+    "schema_version",
+    "route_id",
+    "request",
+    "primary_owner",
+    "companion_owners",
+    "routing_reasons",
+    "required_gates",
+    "fallback_required",
+    "canonical_write_allowed"
+  ],
+  "properties": {
+    "schema_version": { "type": "string" },
+    "route_id": { "type": "string", "minLength": 1 },
+    "request": { "type": "string", "minLength": 1 },
+    "primary_owner": { "type": "string", "minLength": 1 },
+    "companion_owners": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "rejected_candidates": {
+      "type": "array",
+      "items": { "type": "object", "additionalProperties": true }
+    },
+    "routing_reasons": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "why_primary": { "type": "string", "minLength": 1 },
+    "why_not_other_candidates": {
+      "type": "array",
+      "items": { "type": "object", "additionalProperties": true }
+    },
+    "required_gates": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "fallback_required": { "type": "boolean" },
+    "risk_class": { "type": "string", "minLength": 1 },
+    "runtime_preflight_ref": { "type": ["string", "null"] },
+    "route_evidence_ref": { "type": "string", "minLength": 1 },
+    "explanation_source": { "type": "string", "minLength": 1 },
+    "canonical_write_allowed": { "const": false }
+  }
+}

package/schemas/route-regression-result.schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mirai-graph.dev/schemas/route-regression-result.schema.json",
+  "title": "Mirai Graph Route Regression Result",
+  "type": "object",
+  "additionalProperties": true,
+  "required": [
+    "schema_version",
+    "run_id",
+    "after_route_result_ref",
+    "diff",
+    "regression_status",
+    "canonical_write_allowed"
+  ],
+  "properties": {
+    "schema_version": { "type": "string" },
+    "run_id": { "type": "string", "minLength": 1 },
+    "before_route_result_ref": { "type": ["string", "null"] },
+    "baseline_route_result_ref": { "type": ["string", "null"] },
+    "after_route_result_ref": { "type": "string", "minLength": 1 },
+    "current_route_result_ref": { "type": "string", "minLength": 1 },
+    "diff": { "type": "object", "additionalProperties": true },
+    "route_diffs": {
+      "type": "array",
+      "items": { "type": "object", "additionalProperties": true }
+    },
+    "regression_status": {
+      "type": "string",
+      "enum": ["improved", "unchanged", "regressed", "blocked", "insufficient_evidence"]
+    },
+    "canonical_write_allowed": { "const": false }
+  }
+}

package/schemas/routing-fixture-run.schema.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mirai-graph.dev/schemas/routing-fixture-run.schema.json",
+  "title": "Mirai Graph Routing Fixture Run",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["schema_version", "run_id", "fixture_set_ref", "summary", "results", "canonical_write_allowed"],
+  "properties": {
+    "schema_version": { "type": "string" },
+    "run_id": { "type": "string", "minLength": 1 },
+    "fixture_set_ref": { "type": "string", "minLength": 1 },
+    "summary": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["fixture_count", "passed", "failed", "blocked"],
+      "properties": {
+        "fixture_count": { "type": "integer", "minimum": 0 },
+        "passed": { "type": "integer", "minimum": 0 },
+        "failed": { "type": "integer", "minimum": 0 },
+        "blocked": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "results": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["fixture_id", "status", "checks"],
+        "properties": {
+          "fixture_id": { "type": "string", "minLength": 1 },
+          "status": { "type": "string", "enum": ["passed", "failed", "blocked"] },
+          "route_result_ref": { "type": "string", "minLength": 1 },
+          "execution_evidence_ref": { "type": "string", "minLength": 1 },
+          "route_explanation_ref": { "type": ["string", "null"] },
+          "high_risk_route": { "type": "boolean" },
+          "checks": {
+            "type": "array",
+            "items": { "type": "object", "additionalProperties": true }
+          }
+        }
+      }
+    },
+    "canonical_write_allowed": { "const": false }
+  }
+}

package/schemas/routing-fixtures.schema.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mirai-graph.dev/schemas/routing-fixtures.schema.json",
+  "title": "Mirai Graph Routing Fixtures",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["schema_version", "fixture_set_id", "fixtures", "canonical_write_allowed"],
+  "properties": {
+    "schema_version": { "type": "string" },
+    "fixture_set_id": { "type": "string", "minLength": 1 },
+    "fixtures": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": [
+          "fixture_id",
+          "user_request",
+          "expected_primary_owner",
+          "expected_companion_owners",
+          "forbidden_route_shapes",
+          "required_gates",
+          "expected_fallback_required"
+        ],
+        "properties": {
+          "fixture_id": { "type": "string", "minLength": 1 },
+          "user_request": { "type": "string", "minLength": 1 },
+          "expected_primary_owner": { "type": "string", "minLength": 1 },
+          "expected_companion_owners": {
+            "type": "array",
+            "items": { "type": "string", "minLength": 1 }
+          },
+          "forbidden_route_shapes": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": true,
+              "required": ["primary_owner", "without_companions"],
+              "properties": {
+                "primary_owner": { "type": "string", "minLength": 1 },
+                "without_companions": {
+                  "type": "array",
+                  "items": { "type": "string", "minLength": 1 }
+                }
+              }
+            }
+          },
+          "required_gates": {
+            "type": "array",
+            "items": { "type": "string", "minLength": 1 }
+          },
+          "expected_fallback_required": { "type": "boolean" },
+          "high_risk_route": { "type": "boolean" }
+        }
+      }
+    },
+    "canonical_write_allowed": { "const": false }
+  }
+}

package/schemas/source-boundary-contract.schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mirai-graph.dev/schemas/source-boundary-contract.schema.json",
+  "title": "Mirai Graph Source Boundary Contract",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["schema_version", "id", "profile", "public_safety", "source_roles", "promotion_rule", "rejected_promotion_targets", "evidence_refs", "limitations"],
+  "properties": {
+    "schema_version": { "type": "string", "minLength": 1 },
+    "id": { "type": "string", "minLength": 1 },
+    "profile": { "const": "implementation_control" },
+    "public_safety": { "const": "synthetic_public" },
+    "source_roles": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["role", "description", "canonical_write_allowed"],
+        "properties": {
+          "role": { "type": "string", "minLength": 1 },
+          "description": { "type": "string", "minLength": 1 },
+          "canonical_write_allowed": { "type": "boolean" }
+        }
+      }
+    },
+    "promotion_rule": { "type": "string", "minLength": 1 },
+    "rejected_promotion_targets": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } },
+    "evidence_refs": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } },
+    "limitations": { "type": "array", "items": { "type": "string" } }
+  }
+}

package/schemas/technology-quality-feedback.schema.json

@@ -0,0 +1,116 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mirai-graph.dev/schemas/technology-quality-feedback.schema.json",
+  "title": "Mirai Graph Technology Quality Feedback",
+  "type": "object",
+  "additionalProperties": true,
+  "required": [
+    "schema_version",
+    "id",
+    "profile",
+    "public_safety",
+    "technology_ref",
+    "process_id",
+    "launch_record_ref",
+    "work_evidence_refs",
+    "required_steps",
+    "completed_steps",
+    "missing_steps",
+    "review_dimensions",
+    "findings",
+    "feedback_classification",
+    "blocking_findings",
+    "verdict",
+    "next_transition",
+    "kaizen_refs",
+    "evidence_refs",
+    "limitations"
+  ],
+  "properties": {
+    "schema_version": { "type": "string", "minLength": 1 },
+    "id": { "type": "string", "minLength": 1 },
+    "profile": { "const": "implementation_control" },
+    "public_safety": { "const": "synthetic_public" },
+    "technology_ref": { "type": "string", "minLength": 1 },
+    "process_id": { "type": "string", "minLength": 1 },
+    "launch_record_ref": { "type": "string", "minLength": 1 },
+    "work_evidence_refs": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "required_steps": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "completed_steps": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "missing_steps": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "review_dimensions": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "dimension",
+          "classification",
+          "severity",
+          "summary",
+          "evidence_refs",
+          "next_route",
+          "blocking"
+        ],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "dimension": { "type": "string", "minLength": 1 },
+          "classification": { "type": "string", "minLength": 1 },
+          "severity": { "type": "string", "minLength": 1 },
+          "summary": { "type": "string", "minLength": 1 },
+          "evidence_refs": {
+            "type": "array",
+            "minItems": 1,
+            "items": { "type": "string", "minLength": 1 }
+          },
+          "next_route": { "type": "string", "minLength": 1 },
+          "blocking": { "type": "boolean" }
+        }
+      }
+    },
+    "feedback_classification": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "blocking_findings": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "verdict": { "type": "string", "minLength": 1 },
+    "next_transition": { "type": "string", "minLength": 1 },
+    "kaizen_refs": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "evidence_refs": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "limitations": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    }
+  }
+}

package/schemas/work-state-machine.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mirai-graph.dev/schemas/work-state-machine.schema.json",
+  "title": "Mirai Graph Work State Machine",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["schema_version", "id", "profile", "public_safety", "states", "transitions", "false_transition_guards", "evidence_refs", "limitations"],
+  "properties": {
+    "schema_version": { "type": "string", "minLength": 1 },
+    "id": { "type": "string", "minLength": 1 },
+    "profile": { "const": "implementation_control" },
+    "public_safety": { "const": "synthetic_public" },
+    "states": { "type": "array", "minItems": 2, "items": { "type": "string", "minLength": 1 } },
+    "terminal_states": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "transitions": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["from", "to", "requires_evidence"],
+        "properties": {
+          "from": { "type": "string", "minLength": 1 },
+          "to": { "type": "string", "minLength": 1 },
+          "requires_evidence": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+          "requires_launch_record": { "type": "boolean" },
+          "terminal_requires_kaizen": { "type": "boolean" }
+        }
+      }
+    },
+    "false_transition_guards": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } },
+    "evidence_refs": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } },
+    "limitations": { "type": "array", "items": { "type": "string" } }
+  }
+}

package/standard/action-runtime-boundary.md

@@ -0,0 +1,99 @@
+# Action Runtime Boundary
+
+Status: alpha standard draft
+
+## Purpose
+
+This section defines the boundary between Mirai Graph canonical state and
+action-capable runtime behavior.
+
+The boundary is required for AI employees, automation systems and any
+Mirai Graph implementation that can affect external systems.
+
+## State Sequence
+
+Action-capable implementations should preserve this sequence:
+
+```text
+canonical graph state
+-> generated context
+-> runtime decision
+-> proposed action
+-> approval gate
+-> executed action
+-> audited result
+```
+
+## Canonical Graph State
+
+Canonical graph state is the source of truth for durable objects, relations,
+policies, evidence, readiness and governance records.
+
+It may say that an AI employee has a role, can use a tool or follows a policy.
+It does not prove that a particular runtime action should execute now.
+
+## Generated Context
+
+Generated context is a task-bounded view derived from canonical state.
+
+It helps a human or AI system reason about a task. It is not authorization.
+
+## Runtime Decision
+
+A runtime decision is a transient conclusion produced by an implementation.
+
+It may recommend an action, escalation, delegation or no-op. It should record
+the context, policy and evidence it used.
+
+## Proposed Action
+
+A proposed action describes what the runtime wants to do before execution.
+
+It should include:
+
+- action id;
+- actor;
+- target system or object;
+- required capability;
+- applicable policy;
+- approval requirement;
+- expected result;
+- rollback or recovery note when relevant.
+
+## Approval Gate
+
+An approval gate decides whether a proposed action may execute.
+
+Approval may be automatic for low-risk actions when policy allows it. It should
+be explicit for external, irreversible, sensitive, permission-changing or
+public-facing actions.
+
+## Executed Action
+
+An executed action records that a runtime operation actually happened.
+
+It should not be represented only as an intended task. It needs execution
+evidence, timestamp or version reference, status and actor/runtime identity
+where available.
+
+## Audited Result
+
+An audited result records the observed outcome and whether it matched the
+expected result.
+
+Results may produce feedback, lessons, risks or follow-up actions. They should
+not silently update canonical behavior without a learning gate.
+
+## Minimum Safety Rule
+
+```text
+generated context != authorization
+runtime decision != executed action
+feedback != canonical update
+```
+
+## Implementation Note
+
+Mirai Graph can model this boundary. The runtime implementation remains
+responsible for authentication, authorization, tool sandboxing, retries,
+timeouts, logging, rollback and operational security.

package/standard/adoption-levels.md

@@ -0,0 +1,69 @@
+# Mirai Graph Adoption Levels
+
+Status: alpha standard section
+
+## Purpose
+
+Mirai Graph adoption is not binary. A repository, project, product, AI employee
+or skill can contain valid graph artifacts without being ready for runtime use
+or source-of-truth migration.
+
+Adoption levels define a staged path from no graph artifacts to a governed
+graph-first source candidate.
+
+## Levels
+
+| Level | Name | Meaning |
+| --- | --- | --- |
+| GGA0 | `not_started` | No Mirai Graph artifacts are present. |
+| GGA1 | `inventoried` | Sources, owner boundaries and target scope are identified. |
+| GGA2 | `seeded` | A Graph Seed exists and validates. |
+| GGA3 | `embryo_reviewable` | Graph Embryo and initial projection views exist. |
+| GGA4 | `scored` | Readiness, quality or control dashboard evidence exists. |
+| GGA5 | `proposal_gated` | Candidate graph changes pass through proposal, review and apply gates. |
+| GGA6 | `semantically_preserved` | Meaning-preservation review passed for the declared scope. |
+| GGA7 | `effectiveness_checked` | Representative tasks show non-regressed or improved operation. |
+| GGA8 | `federation_ready` | Bounded federation export or contract is valid. |
+| GGA9 | `federation_integrated` | The graph participates in a larger graph, skill mesh or service federation. |
+| GGA10 | `graph_first_source_candidate` | A separate decision allows graph-first source planning or dry-run work. |
+
+## Sequential Gate Rule
+
+Later levels should not skip earlier gates. A system should not claim `GGA8`
+if semantic preservation and effectiveness evidence are missing.
+
+`GGA10` does not grant canonical write permission. It only means graph-first
+source planning or dry-run work may start under a separate decision artifact.
+
+## Required Evidence
+
+An adoption report should record:
+
+- target scope;
+- source classes;
+- owner boundary;
+- profile;
+- latest level;
+- level evidence;
+- blockers;
+- next action;
+- gate results;
+- limitations.
+
+## Anti-Claims
+
+Do not claim that a graph is migrated because:
+
+- JSON validates;
+- a seed exists;
+- a context pack was generated;
+- a dashboard is green;
+- a profile conformance fixture passed.
+
+Those are useful signals, not full adoption.
+
+## Limited Claim
+
+Passing a level supports only the claim attached to that level. For example,
+`GGA2` supports the claim that a Graph Seed validates. It does not support a
+claim that the graph preserved domain meaning or improved work.