graphlin 0.1.0

package/schemas/graph.schema.json

@@ -0,0 +1,449 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Graphlin graph",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": {
+      "const": 1
+    },
+    "revision": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991
+    },
+    "nodes": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/node"
+      },
+      "minItems": 0,
+      "maxItems": 256
+    },
+    "edges": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/edge"
+      },
+      "minItems": 0,
+      "maxItems": 768
+    }
+  },
+  "required": [
+    "schemaVersion",
+    "revision",
+    "nodes",
+    "edges"
+  ],
+  "$defs": {
+    "sourceRef": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "type": {
+              "const": "artifact"
+            },
+            "artifactId": {
+              "type": "string",
+              "pattern": "^(?:[a-z][a-z0-9_]{0,23}-)?[a-f0-9]{24,64}$"
+            },
+            "hash": {
+              "type": "string",
+              "pattern": "^[a-f0-9]{64}$"
+            },
+            "generation": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 9007199254740991
+            }
+          },
+          "required": [
+            "type",
+            "artifactId",
+            "hash",
+            "generation"
+          ]
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "type": {
+              "const": "message"
+            },
+            "messageId": {
+              "type": "string",
+              "pattern": "^(?:[a-z][a-z0-9_]{0,23}-)?[a-f0-9]{24,64}$"
+            },
+            "hash": {
+              "type": "string",
+              "pattern": "^[a-f0-9]{64}$"
+            },
+            "contentVersion": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 9007199254740991
+            }
+          },
+          "required": [
+            "type",
+            "messageId",
+            "hash",
+            "contentVersion"
+          ]
+        }
+      ]
+    },
+    "reference": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "artifactId": {
+          "type": "string",
+          "pattern": "^(?:[a-z][a-z0-9_]{0,23}-)?[a-f0-9]{24,64}$"
+        },
+        "hash": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$"
+        },
+        "generation": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 9007199254740991
+        },
+        "eventId": {
+          "type": "string",
+          "pattern": "^(?:[a-z][a-z0-9_]{0,23}-)?[a-f0-9]{24,64}$"
+        },
+        "startLine": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 10000000
+        },
+        "endLine": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 10000000
+        },
+        "sourceClass": {
+          "enum": [
+            "source",
+            "public_intent"
+          ]
+        },
+        "basis": {
+          "const": "jev_interpretation"
+        },
+        "sourceRef": {
+          "oneOf": [
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "type": {
+                  "const": "artifact"
+                },
+                "artifactId": {
+                  "type": "string",
+                  "pattern": "^(?:[a-z][a-z0-9_]{0,23}-)?[a-f0-9]{24,64}$"
+                },
+                "hash": {
+                  "type": "string",
+                  "pattern": "^[a-f0-9]{64}$"
+                },
+                "generation": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "maximum": 9007199254740991
+                }
+              },
+              "required": [
+                "type",
+                "artifactId",
+                "hash",
+                "generation"
+              ]
+            },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "type": {
+                  "const": "message"
+                },
+                "messageId": {
+                  "type": "string",
+                  "pattern": "^(?:[a-z][a-z0-9_]{0,23}-)?[a-f0-9]{24,64}$"
+                },
+                "hash": {
+                  "type": "string",
+                  "pattern": "^[a-f0-9]{64}$"
+                },
+                "contentVersion": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "maximum": 9007199254740991
+                }
+              },
+              "required": [
+                "type",
+                "messageId",
+                "hash",
+                "contentVersion"
+              ]
+            }
+          ]
+        },
+        "excerpt": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256
+        }
+      },
+      "required": [
+        "artifactId",
+        "hash",
+        "generation",
+        "eventId",
+        "startLine",
+        "endLine",
+        "sourceClass",
+        "basis"
+      ],
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "sourceClass": {
+                "const": "public_intent"
+              }
+            }
+          },
+          "then": {
+            "required": [
+              "sourceRef"
+            ],
+            "properties": {
+              "sourceRef": {
+                "properties": {
+                  "type": {
+                    "const": "message"
+                  }
+                }
+              }
+            }
+          }
+        }
+      ]
+    },
+    "node": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^(?:[a-z][a-z0-9_]{0,23}-)?[a-f0-9]{24,64}$"
+        },
+        "evidenceState": {
+          "enum": [
+            "proposed",
+            "observed",
+            "verified",
+            "removed"
+          ]
+        },
+        "classification": {
+          "enum": [
+            "pending",
+            "accepted",
+            "tentative",
+            "abstained",
+            "stale"
+          ]
+        },
+        "validity": {
+          "enum": [
+            "current",
+            "stale",
+            "retracted"
+          ]
+        },
+        "sourceRefs": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/reference"
+          },
+          "minItems": 1,
+          "maxItems": 8
+        },
+        "confidence": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "label": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 80
+        },
+        "kind": {
+          "enum": [
+            "client",
+            "service",
+            "datastore",
+            "queue",
+            "external",
+            "module",
+            "function",
+            "class",
+            "interface",
+            "event",
+            "configuration",
+            "package"
+          ]
+        },
+        "shape": {
+          "enum": [
+            "rounded_rect",
+            "rect",
+            "cylinder",
+            "cloud",
+            "diamond",
+            "group",
+            "hexagon",
+            "class_box",
+            "interface_box",
+            "document",
+            "parallelogram",
+            "folder",
+            "browser",
+            "component",
+            "queue"
+          ]
+        },
+        "x": {
+          "type": "number",
+          "minimum": -100000,
+          "maximum": 100000
+        },
+        "y": {
+          "type": "number",
+          "minimum": -100000,
+          "maximum": 100000
+        },
+        "activityState": {
+          "enum": [
+            "idle",
+            "pending",
+            "running",
+            "failed",
+            "interrupted",
+            "unknown"
+          ]
+        }
+      },
+      "required": [
+        "id",
+        "evidenceState",
+        "classification",
+        "validity",
+        "sourceRefs",
+        "label",
+        "kind",
+        "shape",
+        "x",
+        "y",
+        "activityState"
+      ]
+    },
+    "edge": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^(?:[a-z][a-z0-9_]{0,23}-)?[a-f0-9]{24,64}$"
+        },
+        "evidenceState": {
+          "enum": [
+            "proposed",
+            "observed",
+            "verified",
+            "removed"
+          ]
+        },
+        "classification": {
+          "enum": [
+            "pending",
+            "accepted",
+            "tentative",
+            "abstained",
+            "stale"
+          ]
+        },
+        "validity": {
+          "enum": [
+            "current",
+            "stale",
+            "retracted"
+          ]
+        },
+        "sourceRefs": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/reference"
+          },
+          "minItems": 1,
+          "maxItems": 8
+        },
+        "confidence": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "source": {
+          "type": "string",
+          "pattern": "^(?:[a-z][a-z0-9_]{0,23}-)?[a-f0-9]{24,64}$"
+        },
+        "target": {
+          "type": "string",
+          "pattern": "^(?:[a-z][a-z0-9_]{0,23}-)?[a-f0-9]{24,64}$"
+        },
+        "relation": {
+          "enum": [
+            "calls",
+            "reads",
+            "writes",
+            "publishes",
+            "consumes",
+            "depends_on"
+          ]
+        },
+        "label": {
+          "enum": [
+            "calls",
+            "reads",
+            "writes",
+            "publishes",
+            "consumes",
+            "depends_on"
+          ]
+        }
+      },
+      "required": [
+        "id",
+        "evidenceState",
+        "classification",
+        "validity",
+        "sourceRefs",
+        "source",
+        "target",
+        "relation",
+        "label"
+      ]
+    }
+  },
+  "$comment": "Runtime additionally enforces canonical source versions, exact labels, provenance, unique IDs, endpoints, relation labels, secret/control filtering, source spans, public-intent state, and serialized UTF-8 size. New compiled graphs: 896 KiB; hard limit: 1 MiB. Invalidation has reserved headroom."
+}

package/schemas/patch.schema.json

@@ -0,0 +1,111 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Graphlin patch",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": {
+      "const": 1
+    },
+    "id": {
+      "anyOf": [
+        {
+          "type": "string",
+          "pattern": "^(?:[a-z][a-z0-9_]{0,23}-)?[a-f0-9]{24,64}$"
+        },
+        {
+          "const": "restore"
+        }
+      ]
+    },
+    "baseRevision": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991
+    },
+    "revision": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991
+    },
+    "causedBy": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^(?:[a-z][a-z0-9_]{0,23}-)?[a-f0-9]{24,64}$"
+      },
+      "minItems": 0,
+      "maxItems": 12
+    },
+    "operations": {
+      "type": "array",
+      "items": {
+        "oneOf": [
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "op": {
+                "const": "node.upsert"
+              },
+              "node": {
+                "$ref": "graph.schema.json#/$defs/node"
+              }
+            },
+            "required": [
+              "op",
+              "node"
+            ]
+          },
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "op": {
+                "const": "edge.upsert"
+              },
+              "edge": {
+                "$ref": "graph.schema.json#/$defs/edge"
+              }
+            },
+            "required": [
+              "op",
+              "edge"
+            ]
+          },
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "op": {
+                "enum": [
+                  "node.remove",
+                  "edge.remove"
+                ]
+              },
+              "id": {
+                "type": "string",
+                "pattern": "^(?:[a-z][a-z0-9_]{0,23}-)?[a-f0-9]{24,64}$"
+              }
+            },
+            "required": [
+              "op",
+              "id"
+            ]
+          }
+        ]
+      },
+      "minItems": 1,
+      "maxItems": 1024
+    }
+  },
+  "required": [
+    "schemaVersion",
+    "id",
+    "baseRevision",
+    "revision",
+    "causedBy",
+    "operations"
+  ],
+  "$comment": "Runtime enforces revision=baseRevision+1, atomic final graph integrity, cascading node removal, and bounded in-process patch-ID replay history."
+}

package/scripts/arguments.mjs

@@ -0,0 +1,37 @@
+export function parseArguments(args, { worker = false } = {}) {
+  const guided = !worker && (!args.length || args[0].startsWith('-'));
+  args = [...args];
+  const values = { projectRoot: process.cwd(), allowSource: worker ? false : undefined,
+    persistEvidence: worker ? false : undefined, displayEvidence: worker ? true : undefined, background: false };
+  const command = worker ? null : args[0] && !args[0].startsWith('-') ? args.shift() : 'start';
+  const strings = new Map([['--project', 'projectRoot'], ['--data-dir', 'dataDir']]);
+  if (!worker && (command === 'init' || command === 'uninstall' || guided)) strings.set('--host', 'host');
+  if (!worker && command === 'logs') strings.set('--file', 'file');
+  if (worker) strings.set('--mode', 'mode');
+  const seen = new Set();
+  while (args.length) {
+    const argument = args.shift();
+    if (seen.has(argument)) throw new Error('duplicate_argument');
+    seen.add(argument);
+    if (strings.has(argument)) {
+      const value = args.shift();
+      if (!value || value.startsWith('--') || value.length > 4096) throw new Error('invalid_argument');
+      values[strings.get(argument)] = value;
+    } else if (argument === '--port') {
+      const value = args.shift();
+      if (!/^\d{1,5}$/.test(value ?? '') || Number(value) > 65535) throw new Error('invalid_port');
+      values.port = Number(value);
+    } else if (argument === '--allow-source' || argument === '--no-source' && !worker) {
+      if (seen.has(argument === '--allow-source' ? '--no-source' : '--allow-source')) throw new Error('conflicting_arguments');
+      values.allowSource = argument === '--allow-source';
+    }
+    else if (argument === '--persist-evidence') values.persistEvidence = true;
+    else if (argument === '--no-display-evidence') values.displayEvidence = false;
+    else if (argument === '--background' && !worker && ['start', 'demo'].includes(command)) values.background = true;
+    else if (argument === '--no-open' && !worker && ['start', 'demo', 'open'].includes(command)) values.openBrowser = false;
+    else if (argument === '--replace-key' && !worker && command === 'init') values.replaceKey = true;
+    else throw new Error('unknown_argument');
+  }
+  if (values.host !== undefined && !['claude', 'codex', 'both'].includes(values.host)) throw new Error('invalid_host');
+  return { command, ...(!worker ? { guided: Boolean(guided) } : {}), ...values };
+}