@n8r/surface 0.0.0-stage → 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/sources/harbor-api.md

@@ -0,0 +1,16 @@
+# Harbor Archive — fictional interface notes, fixture-1
+
+Harbor Archive is a synthetic document and event archival product. It is
+independent of Lumen Desk and has no built-in knowledge of summarization or AI.
+
+## Intake
+
+Harbor offers separate HTTP routes for storing documents and appending audit
+events. JSON request payloads are supported. Exact payload fields, limits and
+authentication are not specified by this document.
+
+## Notifications
+
+An optional outbound HTTP callback reports archival events. Its exact payload
+and the receiver's compatibility need investigation. No integration with Lumen
+Desk has been tested. No deployment or exercised request trace is supplied.

package/examples/researcher/sources/harbor-auth.md

@@ -0,0 +1,8 @@
+# Harbor Archive — fictional authentication note, fixture-2
+
+This second source supplements fixture-1's interface notes. Harbor accepts OIDC
+bearer tokens from a configured issuer. The issuer's identity, expected audience,
+claim checks and credential bindings remain local configuration requirements.
+
+This document establishes a supported option, not a selected issuer, successful
+sign-in, reachable endpoint or exercised archival operation.

package/examples/researcher/sources/lumen-guide.md

@@ -0,0 +1,28 @@
+# Lumen Desk — fictional guide, fixture-1
+
+Lumen Desk is a synthetic support-summary application. No real product or
+installation is described. This document is evidence only within this fixture.
+
+## Components
+
+A configured inference endpoint generates summaries. The model and its version
+are not specified here. Lumen can use an external OIDC identity service.
+
+## Delivery options
+
+Lumen can send summary documents and audit events to separate HTTP routes on a
+configured archive service. The request schema and authentication configuration
+must be agreed separately; this is not a tested Harbor Archive integration.
+The guide says each delivery batch contains at most 10 documents.
+
+## Callback option
+
+An optional callback receiver can accept archive notifications. It is disabled
+until a user selects and configures it. The guide does not describe validation,
+retry behavior or a tested callback protocol.
+
+## Exclusions
+
+No deployment, endpoint credentials, model weights or runtime observations are
+supplied. The literal text `<script>alert("source text only")</script>` is an
+inert sample string, never an instruction to execute source content.

package/examples/researcher/sources/lumen-settings.md

@@ -0,0 +1,9 @@
+# Lumen Desk — fictional settings note, fixture-1
+
+This is a separate synthetic document with no established precedence over the
+guide. It states that the maximum delivery batch contains 25 documents.
+The discrepancy with the guide is unresolved; both claims must be retained.
+
+No inference model version is given. There is no embedded archive database in
+the composition described by this note; storage is delegated to an external
+service. This scoped absence is not a claim about every possible Lumen setup.

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,47 @@
 {
   "name": "@n8r/surface",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-experimental.5",
+  "private": false,
+  "description": "Experimental AI Surface Model library and Codex research command",
+  "bin": {
+    "n8r-surface": "./dist/cli.js"
+  },
+  "type": "module",
+  "license": "Apache-2.0 AND CC-BY-4.0",
+  "engines": {
+    "node": "^22.0.0 || ^24.0.0 || ^26.0.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./examples/*": "./examples/researcher/*",
+    "./contracts/*": "./docs/n8r-surface/*"
+  },
+  "files": [
+    "dist",
+    "docs/n8r-surface",
+    "examples/researcher",
+    "LICENSE",
+    "LICENSE-DOCS",
+    "LICENSING.md",
+    "plugins/n8r-surface"
+  ],
+  "dependencies": {
+    "yaml": "2.9.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/injectionator/n8r-surface.git"
+  },
+  "homepage": "https://github.com/injectionator/n8r-surface#readme",
+  "bugs": {
+    "url": "https://github.com/injectionator/n8r-surface/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org",
+    "tag": "experimental"
+  }
+}