mirai-graph 1.3.0 → 2.1.0

package/benchmarks/protocols/measure-convert-optimize.md

@@ -1,131 +0,0 @@
-# Measure-Convert-Optimize Protocol
-
-Status: initial public protocol
-
-## Purpose
-
-Mirai Graph adoption must be measured, not assumed to be better.
-
-This protocol defines how to compare a current workflow with a Mirai Graph-assisted
-workflow.
-
-## Cycle
-
-```text
-freeze benchmark
--> measure current mode
--> convert selected scope to Mirai Graph
--> measure graph mode
--> compare
--> optimize
--> validate
--> scale
-```
-
-## 1. Freeze Benchmark
-
-Before converting a target scope, freeze:
-
-- benchmark suite;
-- dataset;
-- task ids;
-- expected outputs;
-- acceptance criteria;
-- review policy;
-- metrics.
-
-Do not change the suite after current-mode baseline if direct comparison is
-required.
-
-## 2. Measure Current Mode
-
-Record:
-
-- materials read;
-- context size;
-- time to relevant context;
-- time to done;
-- wrong assumptions;
-- missed dependencies;
-- user corrections;
-- rework cycles;
-- evidence references used;
-- final result;
-- reviewer notes.
-
-## 3. Convert Selected Scope
-
-Convert only a small scope first:
-
-- goals;
-- objects;
-- relations;
-- evidence;
-- readiness;
-- governance gates;
-- context-pack boundary.
-
-Do not convert a whole organization before validating a local graph.
-
-## 4. Measure Graph Mode
-
-Record:
-
-- profile;
-- graph depth;
-- objects considered;
-- relations traversed;
-- generated context size;
-- context pack contents;
-- stale findings;
-- warnings;
-- final result;
-- reviewer notes.
-
-## 5. Compare
-
-Compare only when:
-
-- suite version matches;
-- dataset version matches;
-- task list matches;
-- acceptance criteria match;
-- review policy matches.
-
-If these changed, start a new experiment series.
-
-## 6. Optimize
-
-Use comparison results:
-
-- low precision -> improve object selection;
-- low recall -> improve relations or extraction;
-- negative context reduction -> narrow context profile;
-- missed dependencies -> improve impact traversal;
-- high review overhead -> simplify graph granularity;
-- weak evidence coverage -> improve evidence modeling.
-
-## 7. Validate
-
-Use a separate evaluation set where possible.
-
-Do not tune only on the same tasks used for final claims.
-
-## Minimum Metrics
-
-- `time_to_context`;
-- `context_units`;
-- `context_precision`;
-- `missed_dependencies`;
-- `wrong_assumptions`;
-- `rework_cycles`;
-- `evidence_coverage`;
-- `time_to_done`;
-- `manual_review_overhead`.
-
-## Claim Rule
-
-Use results only for claims supported by the protocol.
-
-A local pilot can support local usefulness. It does not prove universal
-validity.

package/benchmarks/synthetic-context-reduction-v0/README.md

@@ -1,70 +0,0 @@
-# Synthetic Mirai Graph Benchmark v0
-
-Status: draft synthetic package for public-method inspection
-
-This package is artificial. It does not contain private project, customer, employee, source-chat or private skill material.
-
-## Purpose
-
-The package demonstrates the structure of the Mirai Graph context-selection
-method on a small synthetic software-specification scenario.
-It is intended for public inspection of the method, not for empirical claims
-about external performance.
-
-## Scenario
-
-A fictional modular publishing platform is planning four related packages:
-
-- identity and access;
-- content workflow;
-- audit events;
-- notification delivery.
-
-Feature notes, graph objects, relations and context-selection tasks are
-provided as small files that mimic the shape of an evolving specification
-workspace.
-
-## Files
-
-- `source-corpus/`: synthetic source notes.
-- `graph/objects.json`: graph objects extracted from the source corpus.
-- `graph/relations.json`: typed relations between graph objects.
-- `tasks/tasks.json`: sample context-selection tasks.
-- `expected/context-pack-compact.md`: expected compact context package for one
-  task.
-- `metrics/example-metrics.json`: illustrative metric calculation.
-- `scripts/calculate-context-reduction.js`: repeatable calculation for the
-  illustrative synthetic metric.
-
-The graph files are normalized to the initial Mirai Graph v0.1 draft object and
-relation shape.
-
-## Limits
-
-This package supports reproducibility of the method structure only. It does not
-validate external generalization, agent safety or task success.
-
-An initial semantic-completeness review is available at:
-
-`reviews/semantic-completeness-review.json`
-
-## Example Calculation
-
-Run from this package directory:
-
-```bash
-node scripts/calculate-context-reduction.js
-```
-
-Expected result:
-
-```json
-{
-  "schema_version": "0.1.0",
-  "task_id": "task.notify_after_approval",
-  "baseline_context_units": 620,
-  "graph_context_units": 270,
-  "total_reduction_percent": 56.4516,
-  "note": "Synthetic demonstration only; do not merge with internal empirical metrics."
-}
-```

package/benchmarks/synthetic-context-reduction-v0/RESULT.md

@@ -1,52 +0,0 @@
-# Synthetic Context-Reduction Benchmark Result
-
-Status: reproducibility smoke test
-
-## Command
-
-Run from this directory:
-
-```bash
-node scripts/calculate-context-reduction.js
-```
-
-## Output
-
-```json
-{
-  "schema_version": "0.1.0",
-  "task_id": "task.notify_after_approval",
-  "baseline_context_units": 620,
-  "graph_context_units": 270,
-  "total_reduction_percent": 56.4516,
-  "note": "Synthetic demonstration only; do not merge with internal empirical metrics."
-}
-```
-
-## Verdict
-
-`pass_with_limitations`
-
-The benchmark reproduces the expected arithmetic calculation for the synthetic
-context-reduction example.
-
-## Interpretation
-
-This result shows that the public synthetic package is executable and that its
-stored metric inputs reproduce the documented reduction value.
-
-It does not show:
-
-- semantic completeness;
-- external validity;
-- real-world task performance;
-- agent safety;
-- superiority over other methods.
-
-## Next Improvements
-
-- Add more synthetic tasks.
-- Add deterministic context-unit counting.
-- Add semantic-completeness review rubrics.
-- Add negative examples.
-- Add a benchmark runner that writes machine-readable result files.

package/benchmarks/synthetic-context-reduction-v0/expected/context-pack-compact.md

@@ -1,31 +0,0 @@
-# Compact Context Pack: Notifications After Approval
-
-Task: prepare implementation context for sending notifications after content
-approval.
-
-## Required Objects
-
-- `pkg.content_workflow`: owns draft/review/approved/published states and
-  records transition metadata.
-- `feature.workflow_transition`: stores actor, timestamp, previous state, next
-  state and reason.
-- `pkg.audit_events`: stores append-only event records for workflow
-  transitions.
-- `constraint.audit_before_notify`: notification must wait until the triggering
-  workflow event has been audited.
-- `pkg.notification_delivery`: sends email/webhook messages for important
-  workflow events.
-- `feature.scoped_api_token`: delivery workers must use scoped tokens.
-- `risk.duplicate_notifications`: retries must not duplicate notifications for
-  the same transition.
-
-## Implementation Boundary
-
-Do not implement notification delivery as an isolated package decision. The
-feature crosses content workflow, audit events and identity/access.
-
-## Review Gates
-
-- Audit persistence before notification enqueue.
-- Scoped token usage for workers.
-- Idempotency key or correlation identifier for retry handling.

package/benchmarks/synthetic-context-reduction-v0/gates/results.json

@@ -1,12 +0,0 @@
-[
-  {
-    "id": "gate_result.synthetic_context_reduction_v0.public_safety",
-    "gate_id": "gate.public_safety",
-    "target_id": "package.synthetic_context_reduction_v0",
-    "verdict": "pass_with_notes",
-    "summary": "The benchmark is synthetic and public-safe, but it supports method inspection only.",
-    "evidence": ["source.identity_access", "source.content_workflow", "source.audit_events", "source.notification_delivery"],
-    "reviewed_at": "2026-05-28",
-    "reviewer": "Mirai Graph maintainers"
-  }
-]

package/benchmarks/synthetic-context-reduction-v0/graph/objects.json

@@ -1,114 +0,0 @@
-[
-  {
-    "id": "source.identity_access",
-    "kind": "evidence",
-    "title": "Identity access source note",
-    "summary": "Synthetic source note describing account registration, role assignment and scoped API tokens.",
-    "readiness": "accepted",
-    "evidence": [],
-    "profile": "software_specification",
-    "source_path": "source-corpus/identity-access.md"
-  },
-  {
-    "id": "source.content_workflow",
-    "kind": "evidence",
-    "title": "Content workflow source note",
-    "summary": "Synthetic source note describing content review and approval workflow behavior.",
-    "readiness": "accepted",
-    "evidence": [],
-    "profile": "software_specification",
-    "source_path": "source-corpus/content-workflow.md"
-  },
-  {
-    "id": "source.audit_events",
-    "kind": "evidence",
-    "title": "Audit events source note",
-    "summary": "Synthetic source note describing audit recording expectations.",
-    "readiness": "accepted",
-    "evidence": [],
-    "profile": "software_specification",
-    "source_path": "source-corpus/audit-events.md"
-  },
-  {
-    "id": "source.notification_delivery",
-    "kind": "evidence",
-    "title": "Notification delivery source note",
-    "summary": "Synthetic source note describing notification workers, scoped tokens and delivery risks.",
-    "readiness": "accepted",
-    "evidence": [],
-    "profile": "software_specification",
-    "source_path": "source-corpus/notification-delivery.md"
-  },
-  {
-    "id": "pkg.identity_access",
-    "kind": "package",
-    "title": "Identity And Access",
-    "summary": "Synthetic package responsible for identities, roles and scoped API tokens.",
-    "readiness": "draft",
-    "evidence": ["source.identity_access"],
-    "profile": "software_specification"
-  },
-  {
-    "id": "pkg.content_workflow",
-    "kind": "package",
-    "title": "Content Workflow",
-    "summary": "Synthetic package responsible for review and approval workflow transitions.",
-    "readiness": "draft",
-    "evidence": ["source.content_workflow"],
-    "profile": "software_specification"
-  },
-  {
-    "id": "pkg.audit_events",
-    "kind": "package",
-    "title": "Audit Events",
-    "summary": "Synthetic package responsible for recording audit events.",
-    "readiness": "draft",
-    "evidence": ["source.audit_events"],
-    "profile": "software_specification"
-  },
-  {
-    "id": "pkg.notification_delivery",
-    "kind": "package",
-    "title": "Notification Delivery",
-    "summary": "Synthetic package responsible for sending notifications after workflow events.",
-    "readiness": "draft",
-    "evidence": ["source.notification_delivery"],
-    "profile": "software_specification"
-  },
-  {
-    "id": "feature.workflow_transition",
-    "kind": "feature",
-    "title": "Workflow Transition",
-    "summary": "A content workflow transition that can trigger downstream behavior.",
-    "readiness": "review_ready",
-    "evidence": ["source.content_workflow"],
-    "profile": "software_specification"
-  },
-  {
-    "id": "feature.scoped_api_token",
-    "kind": "feature",
-    "title": "Scoped API Token",
-    "summary": "A scoped token used by delivery workers when acting on workflow events.",
-    "readiness": "review_ready",
-    "evidence": ["source.identity_access", "source.notification_delivery"],
-    "profile": "software_specification"
-  },
-  {
-    "id": "constraint.audit_before_notify",
-    "kind": "constraint",
-    "title": "Audit Before Notify",
-    "summary": "A notification should not be sent before the approval transition is recorded in the audit log.",
-    "readiness": "blocked",
-    "evidence": ["source.content_workflow", "source.notification_delivery"],
-    "profile": "software_specification"
-  },
-  {
-    "id": "risk.duplicate_notifications",
-    "kind": "risk",
-    "title": "Duplicate Notifications",
-    "summary": "Retry behavior may create duplicate notifications if idempotency is not defined.",
-    "readiness": "draft",
-    "evidence": ["source.notification_delivery"],
-    "profile": "software_specification"
-  }
-]

package/benchmarks/synthetic-context-reduction-v0/graph/relations.json

@@ -1,74 +0,0 @@
-[
-  {
-    "id": "relation.pkg.content_workflow.implements.feature.workflow_transition",
-    "source": "pkg.content_workflow",
-    "type": "implements",
-    "target": "feature.workflow_transition",
-    "readiness": "draft",
-    "evidence": ["source.content_workflow"],
-    "profile": "software_specification"
-  },
-  {
-    "id": "relation.pkg.identity_access.implements.feature.scoped_api_token",
-    "source": "pkg.identity_access",
-    "type": "implements",
-    "target": "feature.scoped_api_token",
-    "readiness": "draft",
-    "evidence": ["source.identity_access"],
-    "profile": "software_specification"
-  },
-  {
-    "id": "relation.pkg.notification_delivery.depends_on.feature.scoped_api_token",
-    "source": "pkg.notification_delivery",
-    "type": "depends_on",
-    "target": "feature.scoped_api_token",
-    "readiness": "draft",
-    "evidence": ["source.notification_delivery"],
-    "profile": "software_specification"
-  },
-  {
-    "id": "relation.pkg.audit_events.evidences.feature.workflow_transition",
-    "source": "pkg.audit_events",
-    "type": "evidences",
-    "target": "feature.workflow_transition",
-    "readiness": "draft",
-    "evidence": ["source.audit_events", "source.content_workflow"],
-    "profile": "software_specification"
-  },
-  {
-    "id": "relation.pkg.notification_delivery.blocks.constraint.audit_before_notify",
-    "source": "pkg.notification_delivery",
-    "type": "blocks",
-    "target": "constraint.audit_before_notify",
-    "readiness": "draft",
-    "evidence": ["source.notification_delivery"],
-    "profile": "software_specification"
-  },
-  {
-    "id": "relation.constraint.audit_before_notify.depends_on.pkg.audit_events",
-    "source": "constraint.audit_before_notify",
-    "type": "depends_on",
-    "target": "pkg.audit_events",
-    "readiness": "draft",
-    "evidence": ["source.content_workflow", "source.notification_delivery"],
-    "profile": "software_specification"
-  },
-  {
-    "id": "relation.feature.workflow_transition.generates.pkg.notification_delivery",
-    "source": "feature.workflow_transition",
-    "type": "generates",
-    "target": "pkg.notification_delivery",
-    "readiness": "draft",
-    "evidence": ["source.content_workflow"],
-    "profile": "software_specification"
-  },
-  {
-    "id": "relation.pkg.notification_delivery.related_to.risk.duplicate_notifications",
-    "source": "pkg.notification_delivery",
-    "type": "related_to",
-    "target": "risk.duplicate_notifications",
-    "readiness": "draft",
-    "evidence": ["source.notification_delivery"],
-    "profile": "software_specification"
-  }
-]

package/benchmarks/synthetic-context-reduction-v0/graph.json

@@ -1,37 +0,0 @@
-{
-  "$schema": "https://mirai-graph.dev/schemas/graph-manifest.schema.json",
-  "format": "mirai-graph",
-  "schema_version": "2.0.0",
-  "id": "package.synthetic_context_reduction_v0",
-  "aliases": [],
-  "title": "Synthetic Context-Reduction Benchmark v0",
-  "scope": "package",
-  "kind": "graph_package",
-  "owner": "mirai-graph",
-  "profiles": [
-    "software_specification"
-  ],
-  "graph": {
-    "root": "graph",
-    "source_of_truth": [
-      "graph"
-    ],
-    "objects": [
-      "graph/objects.json"
-    ],
-    "relations": [
-      "graph/relations.json"
-    ],
-    "schemas": [],
-    "generated": [],
-    "raw_sources": [
-      "README.md"
-    ]
-  },
-  "imports": [],
-  "version": "0.1.0",
-  "conformance_level": "level_1",
-  "description": "A public-safe synthetic benchmark for inspecting Mirai Graph context-selection structure.",
-  "license": "CC-BY-4.0",
-  "public_safety": "synthetic_public"
-}

package/benchmarks/synthetic-context-reduction-v0/metrics/example-metrics.json

@@ -1,22 +0,0 @@
-{
-  "task_id": "task.notify_after_approval",
-  "metric_status": "illustrative_synthetic_example",
-  "baseline": {
-    "source_files": 4,
-    "estimated_context_units": 620
-  },
-  "graph_context": {
-    "objects": 7,
-    "relations": 8,
-    "estimated_context_units": 270
-  },
-  "calculation": {
-    "formula": "(baseline - graph_context) / baseline * 100",
-    "total_reduction_percent": 56.4516
-  },
-  "limitations": [
-    "Synthetic unit counts are illustrative.",
-    "This file demonstrates calculation format only.",
-    "Do not merge this synthetic metric with internal empirical metrics."
-  ]
-}

package/benchmarks/synthetic-context-reduction-v0/results/baseline-comparison-result.json

@@ -1,42 +0,0 @@
-{
-  "schema_version": "0.1.0",
-  "id": "baseline_comparison.synthetic_notify_after_approval",
-  "public_safety": "synthetic_public",
-  "comparison_type": "baseline_vs_mirai_graph",
-  "task_id": "task.notify_after_approval",
-  "baseline": {
-    "mode": "baseline_documents_and_notes",
-    "context_units": 620,
-    "missed_dependencies": 2,
-    "unsupported_assumptions": 2,
-    "evidence_coverage_percent": 58,
-    "false_progress_claims": 1
-  },
-  "mirai_graph": {
-    "mode": "mirai_graph_context_pack_and_process_control",
-    "context_units": 270,
-    "missed_dependencies": 0,
-    "unsupported_assumptions": 0,
-    "evidence_coverage_percent": 92,
-    "false_progress_claims": 0
-  },
-  "outcome": {
-    "context_reduction_percent": 56.4516,
-    "improved_metrics": [
-      "context_units",
-      "missed_dependencies",
-      "unsupported_assumptions",
-      "evidence_coverage_percent",
-      "false_progress_claims"
-    ],
-    "regressed_metrics": [],
-    "verdict": "synthetic_mirai_graph_result_stronger_with_limits"
-  },
-  "limitations": [
-    "Synthetic comparison demonstrates measurement shape, not broad scientific proof.",
-    "Metrics are fixed fixture values and require independent replication.",
-    "Passing validators do not prove semantic completeness."
-  ],
-  "claim_boundary": "This result supports only a public-safe synthetic comparison claim for the alpha fixture."
-}
-