@n8r/surface 0.1.0-experimental.2 → 0.1.0-experimental.5

package/examples/researcher/relationships/research-r2.json

@@ -0,0 +1,304 @@
+{
+  "id": "urn:demo:relationship-research",
+  "title": "Synthetic relationship evidence",
+  "scope": "Synthetic role/product identities only; runtime unverified.",
+  "revision": {
+    "id": "r2",
+    "parent": {
+      "id": "urn:demo:relationship-research",
+      "revision": "r1",
+      "digest": "sha256:615bc6f8f443b986f78a46414faf97822206bcfcc9781e8d7c03d2dcb83940a0"
+    },
+    "createdAt": "2026-11-08T00:00:00Z",
+    "author": "Synthetic author",
+    "reason": "Changed configured database target"
+  },
+  "extensions": {},
+  "contract": "n8r.research/0.1",
+  "sources": [
+    {
+      "id": "urn:source:summary",
+      "location": "sources.md",
+      "version": "synthetic-relationships-1",
+      "digest": "sha256:cb9498a53d65fb16c16b7ac297b84b2d14a825297012bec9ac07df083e3c5647",
+      "inspectedAt": "2026-11-08T00:00:00Z",
+      "coverage": [
+        {
+          "path": "sources.md",
+          "status": "inspected",
+          "note": "Sanitized synthetic source pack, not raw configuration."
+        }
+      ]
+    },
+    {
+      "id": "urn:source:config",
+      "location": "config/assistant.env.example",
+      "version": "synthetic-1",
+      "digest": "sha256:d575d918e3e60fa1bf4490f7d6ceddafdcf0dba56b41b0e566a3adc8d88fe256",
+      "inspectedAt": "2026-11-08T00:00:00Z",
+      "coverage": [
+        {
+          "path": "config/assistant.env.example",
+          "status": "inspected",
+          "note": "Synthetic setting-name documentation only."
+        }
+      ]
+    }
+  ],
+  "findings": [
+    {
+      "id": "urn:f:database",
+      "subject": "urn:node:app",
+      "property": "supports",
+      "state": "known",
+      "note": "Synthetic source assertion; not runtime evidence.",
+      "claims": [
+        {
+          "value": "urn:node:mongodb",
+          "evidence": [
+            {
+              "source": "urn:source:summary",
+              "locator": "Product guide"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "urn:f:oidc",
+      "subject": "urn:node:app",
+      "property": "supports",
+      "state": "known",
+      "note": "Synthetic source assertion; not runtime evidence.",
+      "claims": [
+        {
+          "value": "urn:node:oidc",
+          "evidence": [
+            {
+              "source": "urn:source:summary",
+              "locator": "Product guide"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "urn:f:saml",
+      "subject": "urn:node:app",
+      "property": "supports",
+      "state": "known",
+      "note": "Synthetic source assertion; not runtime evidence.",
+      "claims": [
+        {
+          "value": "urn:node:saml",
+          "evidence": [
+            {
+              "source": "urn:source:summary",
+              "locator": "Product guide"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "urn:f:database-bound",
+      "subject": "urn:instance:demo",
+      "property": "urn:cap:database",
+      "state": "known",
+      "note": "Synthetic source assertion; not runtime evidence.",
+      "claims": [
+        {
+          "value": "urn:target:mongodb",
+          "evidence": [
+            {
+              "source": "urn:source:summary",
+              "locator": "Sanitized instance configuration summary, revision 2"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "urn:f:identity",
+      "subject": "urn:instance:demo",
+      "property": "urn:cap:oidc",
+      "state": "conflicting",
+      "note": "Synthetic source assertion; not runtime evidence.",
+      "claims": [
+        {
+          "value": "urn:target:oidc",
+          "evidence": [
+            {
+              "source": "urn:source:summary",
+              "locator": "Sanitized instance configuration summary, revision 1"
+            }
+          ]
+        },
+        {
+          "value": "urn:target:saml",
+          "evidence": [
+            {
+              "source": "urn:source:summary",
+              "locator": "Sanitized instance configuration summary, revision 1"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "urn:f:database-purpose",
+      "subject": "urn:cap:database",
+      "property": "purpose",
+      "state": "known",
+      "note": "Synthetic source statement; no actual settings.",
+      "claims": [
+        {
+          "value": "Persist conversation history and user profiles.",
+          "evidence": [
+            {
+              "source": "urn:source:summary",
+              "locator": "Database integration"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "urn:f:database-integration",
+      "subject": "urn:cap:database",
+      "property": "integration",
+      "state": "known",
+      "note": "Synthetic source statement; no actual settings.",
+      "claims": [
+        {
+          "value": "MongoDB client driver using the MongoDB wire protocol.",
+          "evidence": [
+            {
+              "source": "urn:source:summary",
+              "locator": "Database integration"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "urn:f:database-configuration",
+      "subject": "urn:cap:database",
+      "property": "configuration",
+      "state": "known",
+      "note": "Synthetic source statement; no actual settings.",
+      "claims": [
+        {
+          "value": [
+            {
+              "owner": "urn:node:app",
+              "mechanism": "environment-variable",
+              "key": "CHAT_STORE_URI",
+              "location": "config/assistant.env.example"
+            }
+          ],
+          "evidence": [
+            {
+              "source": "urn:source:config",
+              "locator": "CHAT_STORE_URI comment"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "urn:f:oidc-purpose",
+      "subject": "urn:cap:oidc",
+      "property": "purpose",
+      "state": "known",
+      "note": "Synthetic source statement; no actual settings.",
+      "claims": [
+        {
+          "value": "Authenticate users through an identity service.",
+          "evidence": [
+            {
+              "source": "urn:source:summary",
+              "locator": "Authentication integration"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "urn:f:oidc-integration",
+      "subject": "urn:cap:oidc",
+      "property": "integration",
+      "state": "known",
+      "note": "Synthetic source statement; no actual settings.",
+      "claims": [
+        {
+          "value": "OpenID Connect",
+          "evidence": [
+            {
+              "source": "urn:source:summary",
+              "locator": "Authentication integration"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "urn:f:saml-purpose",
+      "subject": "urn:cap:saml",
+      "property": "purpose",
+      "state": "known",
+      "note": "Synthetic source statement; no actual settings.",
+      "claims": [
+        {
+          "value": "Authenticate users through an identity service.",
+          "evidence": [
+            {
+              "source": "urn:source:summary",
+              "locator": "Authentication integration"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "urn:f:saml-integration",
+      "subject": "urn:cap:saml",
+      "property": "integration",
+      "state": "known",
+      "note": "Synthetic source statement; no actual settings.",
+      "claims": [
+        {
+          "value": "SAML 2.0",
+          "evidence": [
+            {
+              "source": "urn:source:summary",
+              "locator": "Authentication integration"
+            }
+          ]
+        }
+      ]
+    }
+  ],
+  "alternatives": [
+    {
+      "id": "urn:option:oidc",
+      "title": "Prefer OIDC",
+      "findings": [
+        "urn:f:identity"
+      ],
+      "requirements": []
+    }
+  ],
+  "decisions": [
+    {
+      "id": "urn:decision:oidc",
+      "alternative": "urn:option:oidc",
+      "choice": "selected",
+      "reason": "Synthetic human preference; conflict unresolved.",
+      "by": "Synthetic reviewer",
+      "at": "2026-11-08T00:00:00Z"
+    }
+  ],
+  "questions": [],
+  "notes": []
+}

package/examples/researcher/relationships/sources.md

@@ -0,0 +1,38 @@
+# Fictional assistant source pack
+
+## Product guide
+
+The assistant supports MongoDB storage, OIDC authentication, and SAML authentication.
+OIDC and SAML are mutually exclusive for this example instance. Inference support
+has not been researched.
+
+## Sanitized instance configuration summary, revision 1
+
+The database relationship is configured for MongoDB Atlas. No endpoint, username,
+password or key is included. The two permitted summaries disagree about identity:
+one identifies the OIDC service, the other the SAML service. Neither establishes
+runtime use. Inference binding evidence is missing.
+
+## Human decision
+
+A synthetic reviewer prefers OIDC. This decision does not resolve the contradictory
+configuration summaries.
+
+## Sanitized instance configuration summary, revision 2
+
+The database relationship is now configured for a self-hosted MongoDB service.
+The other evidence remains unchanged. No actual setting values are supplied.
+
+## Database integration
+
+The fictional assistant persists conversation history and user profiles in MongoDB.
+It connects using a MongoDB client driver and the MongoDB wire protocol.
+The assistant owns the CHAT_STORE_URI environment variable, documented in
+config/assistant.env.example. Only the setting name and relative documentation
+location are retained here; no configured value is included.
+
+## Authentication integration
+
+The assistant authenticates users through an identity service. OIDC uses the
+OpenID Connect protocol; SAML uses SAML 2.0. Configuration locations have not been
+researched and must remain unknown, not absent.

package/examples/researcher/surface-bom/README.md

@@ -0,0 +1,17 @@
+# Synthetic Surface BOM
+
+`initial.cdx.json` is a fictional assistant with four database alternatives, one
+selected dependency, an unknown inference connection, evidence, a user decision
+and an investigation plan. It makes no claim about LibreChat or any deployment.
+The repeated evidence hash is a synthetic placeholder, not a real inspected file.
+
+Read the [profile](../../../plugins/n8r-surface/skills/research/references/cyclonedx.md)
+and [mapping limits](../../../docs/n8r-surface/skill-cyclonedx.md).
+From the repository root with Node 22/24/26:
+
+```sh
+node plugins/n8r-surface/skills/research/scripts/surface.mjs check examples/researcher/surface-bom/initial.cdx.json
+```
+
+Expect exit 0 and `checked`, five relationships and three investigation entries.
+This checks structure/references only, not actual product evidence.

package/examples/researcher/surface-bom/initial.cdx.json

@@ -0,0 +1,188 @@
+{
+  "bomFormat": "CycloneDX",
+  "specVersion": "1.7",
+  "serialNumber": "urn:uuid:94141625-a8d3-4cec-984a-c46be305058d",
+  "version": 1,
+  "metadata": {
+    "timestamp": "2026-11-13T12:00:00Z"
+  },
+  "components": [
+    {
+      "bom-ref": "app",
+      "type": "application",
+      "name": "Synthetic Assistant"
+    },
+    {
+      "bom-ref": "model",
+      "type": "machine-learning-model",
+      "name": "Synthetic Model"
+    }
+  ],
+  "services": [
+    {
+      "bom-ref": "db-a",
+      "name": "Database A"
+    },
+    {
+      "bom-ref": "db-b",
+      "name": "Database B"
+    },
+    {
+      "bom-ref": "db-c",
+      "name": "Database C"
+    },
+    {
+      "bom-ref": "db-d",
+      "name": "Database D"
+    }
+  ],
+  "dependencies": [
+    {
+      "ref": "app",
+      "dependsOn": [
+        "db-b"
+      ]
+    }
+  ],
+  "compositions": [
+    {
+      "aggregate": "unknown"
+    }
+  ],
+  "annotations": [
+    {
+      "bom-ref": "evidence-support",
+      "subjects": [
+        "app",
+        "db-a",
+        "db-b",
+        "db-c",
+        "db-d"
+      ],
+      "annotator": {
+        "individual": {
+          "name": "Researcher"
+        }
+      },
+      "timestamp": "2026-11-13T12:00:00Z",
+      "text": "The synthetic source describes four supported database alternatives. This does not establish a selected deployment."
+    },
+    {
+      "bom-ref": "evidence-selection",
+      "subjects": [
+        "app",
+        "db-b"
+      ],
+      "annotator": {
+        "individual": {
+          "name": "Researcher"
+        }
+      },
+      "timestamp": "2026-11-13T12:00:00Z",
+      "text": "A synthetic safe configuration projection identifies database B; connection values were not retained."
+    },
+    {
+      "bom-ref": "decision-1",
+      "subjects": [
+        "app"
+      ],
+      "annotator": {
+        "individual": {
+          "name": "User"
+        }
+      },
+      "timestamp": "2026-11-13T12:00:00Z",
+      "text": "Investigate storage before model hosting."
+    }
+  ],
+  "externalReferences": [
+    {
+      "type": "evidence",
+      "url": "synthetic-source-pack",
+      "comment": "Synthetic source pack; version 1; inspected support and safe projection only.",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+        }
+      ]
+    }
+  ],
+  "citations": [
+    {
+      "bom-ref": "citation-1",
+      "pointers": [
+        "/annotations/0/text"
+      ],
+      "timestamp": "2026-11-13T12:00:00Z",
+      "attributedTo": "app",
+      "note": "Synthetic fixture attribution, not real product evidence."
+    }
+  ],
+  "properties": [
+    {
+      "name": "n8r:surface:profile",
+      "value": "1"
+    },
+    {
+      "name": "n8r:surface:objective",
+      "value": "Understand storage choices and the selected connection."
+    },
+    {
+      "name": "n8r:surface:scope",
+      "value": "Synthetic assistant; no live runtime access."
+    },
+    {
+      "name": "n8r:surface:relationship",
+      "value": "{\"id\":\"storage-a\",\"from\":\"app\",\"to\":\"db-a\",\"kind\":\"dependency\",\"optionality\":\"alternative\",\"group\":\"storage\",\"support\":\"supported\",\"selection\":\"unknown\",\"observations\":[],\"evidence\":[\"evidence-support\"],\"selectionEvidence\":[],\"purpose\":\"Persist conversation state\",\"mechanism\":\"Database driver\",\"configuration\":[],\"conditions\":[],\"note\":\"Supported alternative; selection of other targets is unestablished.\"}"
+    },
+    {
+      "name": "n8r:surface:relationship",
+      "value": "{\"id\":\"storage-b\",\"from\":\"app\",\"to\":\"db-b\",\"kind\":\"dependency\",\"optionality\":\"alternative\",\"group\":\"storage\",\"support\":\"supported\",\"selection\":\"selected\",\"observations\":[],\"evidence\":[\"evidence-support\"],\"selectionEvidence\":[\"evidence-selection\"],\"purpose\":\"Persist conversation state\",\"mechanism\":\"Database driver\",\"configuration\":[\"safe-projection.json: database-kind\"],\"conditions\":[],\"note\":\"Supported alternative; selection of other targets is unestablished.\"}"
+    },
+    {
+      "name": "n8r:surface:relationship",
+      "value": "{\"id\":\"storage-c\",\"from\":\"app\",\"to\":\"db-c\",\"kind\":\"dependency\",\"optionality\":\"alternative\",\"group\":\"storage\",\"support\":\"supported\",\"selection\":\"unknown\",\"observations\":[],\"evidence\":[\"evidence-support\"],\"selectionEvidence\":[],\"purpose\":\"Persist conversation state\",\"mechanism\":\"Database driver\",\"configuration\":[],\"conditions\":[],\"note\":\"Supported alternative; selection of other targets is unestablished.\"}"
+    },
+    {
+      "name": "n8r:surface:relationship",
+      "value": "{\"id\":\"storage-d\",\"from\":\"app\",\"to\":\"db-d\",\"kind\":\"dependency\",\"optionality\":\"alternative\",\"group\":\"storage\",\"support\":\"supported\",\"selection\":\"unknown\",\"observations\":[],\"evidence\":[\"evidence-support\"],\"selectionEvidence\":[],\"purpose\":\"Persist conversation state\",\"mechanism\":\"Database driver\",\"configuration\":[],\"conditions\":[],\"note\":\"Supported alternative; selection of other targets is unestablished.\"}"
+    },
+    {
+      "name": "n8r:surface:relationship",
+      "value": "{\"id\":\"inference\",\"from\":\"app\",\"to\":\"model\",\"kind\":\"integration\",\"optionality\":\"unknown\",\"group\":\"\",\"support\":\"unknown\",\"selection\":\"unknown\",\"observations\":[],\"evidence\":[],\"selectionEvidence\":[],\"purpose\":\"Generate a response\",\"mechanism\":\"Unknown\",\"configuration\":[],\"conditions\":[],\"note\":\"Model serving connection remains uninvestigated.\"}"
+    },
+    {
+      "name": "n8r:surface:entry",
+      "value": "{\"id\":\"plan-1\",\"kind\":\"next\",\"title\":\"Inspect storage selection\",\"text\":\"Establish the selected database from a safe configuration projection.\",\"status\":\"done\",\"reason\":\"Projection supplied in this synthetic example.\",\"access\":\"Safe configuration projection\",\"evidence\":[\"evidence-selection\"],\"at\":\"2026-11-13T12:00:00Z\"}"
+    },
+    {
+      "name": "n8r:surface:entry",
+      "value": "{\"id\":\"choice-1\",\"kind\":\"decision\",\"title\":\"Storage first\",\"text\":\"Investigate storage before model hosting.\",\"status\":\"active\",\"reason\":\"User priority\",\"access\":\"None\",\"evidence\":[\"decision-1\"],\"at\":\"2026-11-13T12:00:00Z\"}"
+    },
+    {
+      "name": "n8r:surface:entry",
+      "value": "{\"id\":\"question-1\",\"kind\":\"question\",\"title\":\"Which service hosts inference?\",\"text\":\"Inspect the serving configuration to identify the model endpoint role.\",\"status\":\"open\",\"reason\":\"Source does not establish this connection.\",\"access\":\"Safe inference configuration\",\"evidence\":[],\"at\":\"2026-11-13T12:00:00Z\"}"
+    },
+    {
+      "name": "n8r:surface:coverage",
+      "value": "Only synthetic support and selection sources inspected."
+    },
+    {
+      "name": "n8r:surface:gap",
+      "value": "Runtime use has not been observed."
+    },
+    {
+      "name": "n8r:surface:evidence",
+      "value": "{\"id\": \"evidence-support\", \"basis\": \"source\", \"sources\": [{\"index\": 0, \"locator\": \"support.md:1-20\"}], \"applicability\": \"Synthetic fixture only.\"}"
+    },
+    {
+      "name": "n8r:surface:evidence",
+      "value": "{\"id\": \"evidence-selection\", \"basis\": \"configuration\", \"sources\": [{\"index\": 0, \"locator\": \"safe-projection.json: database-kind\"}], \"applicability\": \"Synthetic fixture only.\"}"
+    },
+    {
+      "name": "n8r:surface:evidence",
+      "value": "{\"id\": \"decision-1\", \"basis\": \"user\", \"sources\": [], \"applicability\": \"Synthetic fixture only.\"}"
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@n8r/surface",
-  "version": "0.1.0-experimental.2",
+  "version": "0.1.0-experimental.5",
   "private": false,
   "description": "Experimental AI Surface Model library and Codex research command",
   "bin": {

package/plugins/n8r-surface/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "n8r-surface",
-  "version": "0.1.8",
+  "version": "0.1.16",
   "description": "Discover and reconcile AI-relevant components and connections using source evidence and permitted live settings. Experimental working notes; no deployment or compatibility claims.",
   "author": {
     "name": "AI Surface Model contributors",
@@ -19,7 +19,7 @@
   "interface": {
     "displayName": "n8r-surface Researcher",
     "shortDescription": "Research AI system components",
-    "longDescription": "Build partial AI Surface graphs from supplied sources, prior descriptions and permitted live observations using the current host. Retain evidence, decisions and gaps in working notes. This experimental skill does not change deployments or produce validated n8r research/Surface artefacts. Access and saving depend on the host tools.",
+    "longDescription": "Build partial AI Surface graphs from supplied sources, prior descriptions and permitted live observations using the current host. Retain evidence, decisions and gaps in working notes. This experimental skill can save a self-contained Surface with an investigation journal and visual using bundled resources; it does not change deployments. Access and saving depend on the host tools.",
     "developerName": "AI Surface Model contributors",
     "category": "Developer Tools",
     "capabilities": [],

package/plugins/n8r-surface/LICENSING.md

@@ -34,3 +34,6 @@ Copied project examples remain subject to their applicable licence.
 
 Third-party material retains its own applicable terms and attribution. The
 project licences do not relicense third-party components described in a Surface.
+
+The bundled `skills/research/scripts/artifacts.mjs` includes yaml 2.9.1 under
+its ISC licence; see `skills/research/scripts/THIRD-PARTY-NOTICES.txt`.

package/plugins/n8r-surface/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "n8r-surface",
-  "version": "0.1.8",
+  "version": "0.1.16",
   "description": "Discover and reconcile AI-relevant components and connections using source evidence and permitted live settings. Experimental working notes; no deployment or compatibility claims.",
   "author": {"name": "AI Surface Model contributors", "url": "https://github.com/injectionator/n8r-surface"},
   "homepage": "https://github.com/injectionator/n8r-surface",
@@ -13,7 +13,7 @@
       "interface": {
         "displayName": "n8r-surface Researcher",
         "shortDescription": "Research AI system components",
-        "longDescription": "Build partial AI Surface graphs from supplied sources, prior descriptions and permitted live observations using the current host. Retain evidence, decisions and gaps in working notes. This experimental skill does not change deployments or produce validated n8r research/Surface artefacts. Access and saving depend on the host tools.",
+        "longDescription": "Build partial AI Surface graphs from supplied sources, prior descriptions and permitted live observations using the current host. Retain evidence, decisions and gaps in working notes. This experimental skill can save a self-contained Surface with an investigation journal and visual using bundled resources; it does not change deployments. Access and saving depend on the host tools.",
         "developerName": "AI Surface Model contributors",
         "category": "Developer Tools",
         "capabilities": [],