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

package/examples/researcher/cyclonedx/configured/surface.cdx.json

@@ -0,0 +1,79 @@
+{
+  "bomFormat": "CycloneDX",
+  "specVersion": "1.7",
+  "serialNumber": "urn:uuid:32c19d86-ecb9-59e9-ad1f-edc951a2819f",
+  "version": 1,
+  "metadata": {
+    "timestamp": "2026-11-08T00:00:00Z"
+  },
+  "components": [
+    {
+      "bom-ref": "urn:node:app",
+      "name": "Assistant",
+      "description": "bound Surface node; classification: Synthetic consumer rehearsal classification. This inventory does not establish deployment or runtime use.",
+      "type": "application"
+    }
+  ],
+  "services": [
+    {
+      "bom-ref": "urn:node:mongodb",
+      "name": "MongoDB",
+      "description": "bound Surface node; classification: Synthetic consumer rehearsal classification. This inventory does not establish deployment or runtime use."
+    },
+    {
+      "bom-ref": "urn:node:oidc",
+      "name": "OIDC",
+      "description": "bound Surface node; classification: Synthetic consumer rehearsal classification. This inventory does not establish deployment or runtime use."
+    },
+    {
+      "bom-ref": "urn:node:saml",
+      "name": "SAML",
+      "description": "bound Surface node; classification: Synthetic consumer rehearsal classification. This inventory does not establish deployment or runtime use."
+    },
+    {
+      "bom-ref": "urn:node:inference",
+      "name": "Inference service",
+      "description": "bound Surface node; classification: Synthetic consumer rehearsal classification. This inventory does not establish deployment or runtime use."
+    },
+    {
+      "bom-ref": "urn:target:atlas",
+      "name": "MongoDB Atlas",
+      "description": "bound Surface node; classification: Synthetic consumer rehearsal classification. This inventory does not establish deployment or runtime use."
+    },
+    {
+      "bom-ref": "urn:target:oidc",
+      "name": "OIDC service",
+      "description": "bound Surface node; classification: Synthetic consumer rehearsal classification. This inventory does not establish deployment or runtime use."
+    },
+    {
+      "bom-ref": "urn:target:saml",
+      "name": "SAML service",
+      "description": "bound Surface node; classification: Synthetic consumer rehearsal classification. This inventory does not establish deployment or runtime use."
+    }
+  ],
+  "dependencies": [
+    {
+      "ref": "urn:node:app",
+      "dependsOn": [
+        "urn:target:atlas"
+      ]
+    }
+  ],
+  "compositions": [
+    {
+      "aggregate": "unknown"
+    }
+  ],
+  "externalReferences": [
+    {
+      "type": "other",
+      "url": "surface-records.json",
+      "comment": "Exact checked native research/Surface snapshot. Required for evidence and Surface meanings."
+    },
+    {
+      "type": "other",
+      "url": "mapping.json",
+      "comment": "Mapping and explicit semantic losses; not a lossless BOM-only representation."
+    }
+  ]
+}

package/examples/researcher/descriptions/README.md

@@ -0,0 +1,29 @@
+# Synthetic Capability and Bound descriptions
+
+These are developer-written fixtures for [contract 0.2](../../../docs/n8r-surface/surface-description-contract.md),
+not AI findings or a real deployment. The example vocabulary `urn:v:demo` version
+`1` uses `component` for nodes and `uses` for possible directed relationships.
+These terms describe roles only, not protocol compatibility.
+
+| File | Inspect for |
+| --- | --- |
+| [Source pack](sources.md) | Synthetic product support, sanitized configuration summaries and a separate human preference. |
+| [Research r1](research-r1.json) | Exact source hash, source locators, known/conflicting findings and human decision. |
+| [Capability](capability.json) | Possible MongoDB/OIDC/SAML relationships, exclusive authentication options, unknown inference. |
+| [Bound r1](bound-r1.json) | Configured Atlas, conflicting authentication and unknown inference; pinned Capability revision. |
+| [Research r2](research-r2.json) | Changed database evidence with the original research as predecessor. |
+| [Bound r2](bound-r2.json) | Same instance and binding slot, new MongoDB target, pinned predecessor; unchanged Capability revision. |
+
+All source/settings content is synthetic and sanitized at origin; there are no
+actual endpoints, accounts or secrets to recover. Configuration claims do not
+prove runtime use. A conflicting target does not assert that its protocol fits
+the possible connection; it records source disagreement requiring investigation.
+Missing evidence does not mean unbound.
+
+Follow the [human inspection and runnable readback](../../../docs/n8r-surface/surface-description-contract.md#human-verification-task-list).
+`npm test` checks exact hashes, local/external references and revisions; it does
+not establish research quality, installed-skill acceptance or model conformance.
+
+Machine-readable fixtures use [Apache-2.0](../../../LICENSE). This guide and the
+synthetic source pack use [CC-BY-4.0](../../../LICENSE-DOCS); credit AI Surface
+Model contributors. No third-party source material is included.

package/examples/researcher/descriptions/bound-r1.json

@@ -0,0 +1,141 @@
+{
+  "id": "urn:demo:bound",
+  "title": "Synthetic Bound Surface",
+  "scope": "Synthetic role/product identities only; runtime unverified.",
+  "revision": {
+    "id": "r1",
+    "parent": null,
+    "createdAt": "2026-11-08T00:00:00Z",
+    "author": "Synthetic author",
+    "reason": "Initial synthetic example"
+  },
+  "extensions": {},
+  "contract": "n8r.surface/0.2",
+  "kind": "bound",
+  "capability": {
+    "id": "urn:demo:capability",
+    "revision": "r1",
+    "digest": "sha256:9e1602e468cec7eff8e945007b7e40e0534bf1ba2f80cb679b92099a720c619b"
+  },
+  "instance": {
+    "id": "urn:instance:demo",
+    "label": "Synthetic instance"
+  },
+  "records": [
+    {
+      "id": "urn:demo:research",
+      "revision": "r1",
+      "digest": "sha256:628d3c612d4afbb09852ec51436cf8b51f4fb96f02407c2b99e45dc06a3dfec0"
+    }
+  ],
+  "vocabularies": [
+    {
+      "id": "urn:v:demo",
+      "version": "1"
+    }
+  ],
+  "nodes": [
+    {
+      "id": "urn:target:atlas",
+      "label": "MongoDB Atlas",
+      "type": {
+        "vocabulary": "urn:v:demo",
+        "term": "component"
+      }
+    },
+    {
+      "id": "urn:target:oidc",
+      "label": "OIDC service",
+      "type": {
+        "vocabulary": "urn:v:demo",
+        "term": "component"
+      }
+    },
+    {
+      "id": "urn:target:saml",
+      "label": "SAML service",
+      "type": {
+        "vocabulary": "urn:v:demo",
+        "term": "component"
+      }
+    }
+  ],
+  "bindings": [
+    {
+      "id": "urn:binding:database",
+      "capability": "urn:cap:database",
+      "state": "configured",
+      "claims": [
+        {
+          "target": "urn:target:atlas",
+          "basis": [
+            {
+              "record": "urn:demo:research",
+              "revision": "r1",
+              "items": [
+                "urn:f:database-bound"
+              ]
+            }
+          ]
+        }
+      ],
+      "decisions": [],
+      "note": "Configuration sufficient; runtime unverified"
+    },
+    {
+      "id": "urn:binding:identity",
+      "capability": "urn:cap:oidc",
+      "state": "conflicting",
+      "claims": [
+        {
+          "target": "urn:target:oidc",
+          "basis": [
+            {
+              "record": "urn:demo:research",
+              "revision": "r1",
+              "items": [
+                "urn:f:identity"
+              ]
+            }
+          ]
+        },
+        {
+          "target": "urn:target:saml",
+          "basis": [
+            {
+              "record": "urn:demo:research",
+              "revision": "r1",
+              "items": [
+                "urn:f:identity"
+              ]
+            }
+          ]
+        }
+      ],
+      "decisions": [
+        {
+          "record": "urn:demo:research",
+          "revision": "r1",
+          "items": [
+            "urn:decision:oidc"
+          ]
+        }
+      ],
+      "note": "Preference retained separately; configuration sources disagree"
+    },
+    {
+      "id": "urn:binding:inference",
+      "capability": "urn:cap:inference",
+      "state": "unknown",
+      "claims": [],
+      "decisions": [],
+      "note": "Missing evidence is not unbound"
+    }
+  ],
+  "coverage": [
+    "Sanitized configuration summary"
+  ],
+  "gaps": [
+    "Authentication conflict; inference unknown; runtime unverified"
+  ]
+}

package/examples/researcher/descriptions/bound-r2.json

@@ -0,0 +1,153 @@
+{
+  "id": "urn:demo:bound",
+  "title": "Synthetic Bound Surface",
+  "scope": "Synthetic role/product identities only; runtime unverified.",
+  "revision": {
+    "id": "r2",
+    "parent": {
+      "id": "urn:demo:bound",
+      "revision": "r1",
+      "digest": "sha256:c29b9f93f2be80b0a2f2465e3494de7ce346ff68942dd52ad6e8877c1f7cbbfb"
+    },
+    "createdAt": "2026-11-08T00:00:00Z",
+    "author": "Synthetic author",
+    "reason": "Database target changed"
+  },
+  "extensions": {},
+  "contract": "n8r.surface/0.2",
+  "kind": "bound",
+  "capability": {
+    "id": "urn:demo:capability",
+    "revision": "r1",
+    "digest": "sha256:9e1602e468cec7eff8e945007b7e40e0534bf1ba2f80cb679b92099a720c619b"
+  },
+  "instance": {
+    "id": "urn:instance:demo",
+    "label": "Synthetic instance"
+  },
+  "records": [
+    {
+      "id": "urn:demo:research",
+      "revision": "r2",
+      "digest": "sha256:974a8670519fb59a95ddd8cd62db7bd4d43cb1794d042f89c09b012484c095db"
+    }
+  ],
+  "vocabularies": [
+    {
+      "id": "urn:v:demo",
+      "version": "1"
+    }
+  ],
+  "nodes": [
+    {
+      "id": "urn:target:atlas",
+      "label": "MongoDB Atlas",
+      "type": {
+        "vocabulary": "urn:v:demo",
+        "term": "component"
+      }
+    },
+    {
+      "id": "urn:target:oidc",
+      "label": "OIDC service",
+      "type": {
+        "vocabulary": "urn:v:demo",
+        "term": "component"
+      }
+    },
+    {
+      "id": "urn:target:saml",
+      "label": "SAML service",
+      "type": {
+        "vocabulary": "urn:v:demo",
+        "term": "component"
+      }
+    },
+    {
+      "id": "urn:target:mongodb",
+      "label": "Self-hosted MongoDB",
+      "type": {
+        "vocabulary": "urn:v:demo",
+        "term": "component"
+      }
+    }
+  ],
+  "bindings": [
+    {
+      "id": "urn:binding:database",
+      "capability": "urn:cap:database",
+      "state": "configured",
+      "claims": [
+        {
+          "target": "urn:target:mongodb",
+          "basis": [
+            {
+              "record": "urn:demo:research",
+              "revision": "r2",
+              "items": [
+                "urn:f:database-bound"
+              ]
+            }
+          ]
+        }
+      ],
+      "decisions": [],
+      "note": "Configuration sufficient; runtime unverified"
+    },
+    {
+      "id": "urn:binding:identity",
+      "capability": "urn:cap:oidc",
+      "state": "conflicting",
+      "claims": [
+        {
+          "target": "urn:target:oidc",
+          "basis": [
+            {
+              "record": "urn:demo:research",
+              "revision": "r2",
+              "items": [
+                "urn:f:identity"
+              ]
+            }
+          ]
+        },
+        {
+          "target": "urn:target:saml",
+          "basis": [
+            {
+              "record": "urn:demo:research",
+              "revision": "r2",
+              "items": [
+                "urn:f:identity"
+              ]
+            }
+          ]
+        }
+      ],
+      "decisions": [
+        {
+          "record": "urn:demo:research",
+          "revision": "r2",
+          "items": [
+            "urn:decision:oidc"
+          ]
+        }
+      ],
+      "note": "Preference retained separately; configuration sources disagree"
+    },
+    {
+      "id": "urn:binding:inference",
+      "capability": "urn:cap:inference",
+      "state": "unknown",
+      "claims": [],
+      "decisions": [],
+      "note": "Missing evidence is not unbound"
+    }
+  ],
+  "coverage": [
+    "Sanitized configuration summary"
+  ],
+  "gaps": [
+    "Authentication conflict; inference unknown; runtime unverified"
+  ]
+}

package/examples/researcher/descriptions/capability.json

@@ -0,0 +1,167 @@
+{
+  "id": "urn:demo:capability",
+  "title": "Synthetic Capability Surface",
+  "scope": "Synthetic role/product identities only; runtime unverified.",
+  "revision": {
+    "id": "r1",
+    "parent": null,
+    "createdAt": "2026-11-08T00:00:00Z",
+    "author": "Synthetic author",
+    "reason": "Initial synthetic example"
+  },
+  "extensions": {},
+  "contract": "n8r.surface/0.2",
+  "kind": "capability",
+  "records": [
+    {
+      "id": "urn:demo:research",
+      "revision": "r1",
+      "digest": "sha256:628d3c612d4afbb09852ec51436cf8b51f4fb96f02407c2b99e45dc06a3dfec0"
+    }
+  ],
+  "vocabularies": [
+    {
+      "id": "urn:v:demo",
+      "version": "1"
+    }
+  ],
+  "nodes": [
+    {
+      "id": "urn:node:app",
+      "label": "Assistant",
+      "type": {
+        "vocabulary": "urn:v:demo",
+        "term": "component"
+      }
+    },
+    {
+      "id": "urn:node:mongodb",
+      "label": "MongoDB",
+      "type": {
+        "vocabulary": "urn:v:demo",
+        "term": "component"
+      }
+    },
+    {
+      "id": "urn:node:oidc",
+      "label": "OIDC",
+      "type": {
+        "vocabulary": "urn:v:demo",
+        "term": "component"
+      }
+    },
+    {
+      "id": "urn:node:saml",
+      "label": "SAML",
+      "type": {
+        "vocabulary": "urn:v:demo",
+        "term": "component"
+      }
+    },
+    {
+      "id": "urn:node:inference",
+      "label": "Inference service",
+      "type": {
+        "vocabulary": "urn:v:demo",
+        "term": "component"
+      }
+    }
+  ],
+  "capabilities": [
+    {
+      "id": "urn:cap:database",
+      "from": "urn:node:app",
+      "to": "urn:node:mongodb",
+      "type": {
+        "vocabulary": "urn:v:demo",
+        "term": "uses"
+      },
+      "state": "possible",
+      "basis": [
+        {
+          "record": "urn:demo:research",
+          "revision": "r1",
+          "items": [
+            "urn:f:database"
+          ]
+        }
+      ],
+      "conditions": [],
+      "note": "Supported possibility, not a selected composition"
+    },
+    {
+      "id": "urn:cap:oidc",
+      "from": "urn:node:app",
+      "to": "urn:node:oidc",
+      "type": {
+        "vocabulary": "urn:v:demo",
+        "term": "uses"
+      },
+      "state": "possible",
+      "basis": [
+        {
+          "record": "urn:demo:research",
+          "revision": "r1",
+          "items": [
+            "urn:f:oidc"
+          ]
+        }
+      ],
+      "conditions": [
+        "OIDC and SAML are alternatives"
+      ],
+      "note": "Supported possibility, not a selected composition"
+    },
+    {
+      "id": "urn:cap:saml",
+      "from": "urn:node:app",
+      "to": "urn:node:saml",
+      "type": {
+        "vocabulary": "urn:v:demo",
+        "term": "uses"
+      },
+      "state": "possible",
+      "basis": [
+        {
+          "record": "urn:demo:research",
+          "revision": "r1",
+          "items": [
+            "urn:f:saml"
+          ]
+        }
+      ],
+      "conditions": [
+        "OIDC and SAML are alternatives"
+      ],
+      "note": "Supported possibility, not a selected composition"
+    },
+    {
+      "id": "urn:cap:inference",
+      "from": "urn:node:app",
+      "to": "urn:node:inference",
+      "type": {
+        "vocabulary": "urn:v:demo",
+        "term": "uses"
+      },
+      "state": "unknown",
+      "basis": [],
+      "conditions": [],
+      "note": "Unknown support"
+    }
+  ],
+  "exclusiveGroups": [
+    {
+      "id": "urn:group:authentication",
+      "members": [
+        "urn:cap:oidc",
+        "urn:cap:saml"
+      ]
+    }
+  ],
+  "coverage": [
+    "One synthetic product guide"
+  ],
+  "gaps": [
+    "Inference support unknown"
+  ]
+}