@n8r/surface 0.0.0-stage → 0.1.0-experimental.5

package/examples/researcher/composed.surface.yaml

@@ -0,0 +1,283 @@
+"contract": n8r.surface/0.1
+"id": urn:surface:lumen-with-harbor
+"title": Selected Lumen and Harbor composition
+"revision":
+  "id": r1
+  "parent": null
+  "createdAt": 2026-11-04T09:00:00Z
+  "author": Synthetic researcher
+  "reason": Synthetic user selects a partial composition; no integration has been run
+"scope": Desired composition from supplied fictional documents. Authentication, schemas and effective setup are incomplete.
+"extensions":
+  "https://example.test/selection/v1":
+    "synthetic": true
+    "opaque":
+      "reviewed": true
+"kind": definition
+"records":
+  - "id": urn:research:lumen
+    "revision": r2
+    "digest": sha256:d7384fe64f1140815ddda3c7bbb2fe826a83140b445e70d839b07145c5840aca
+  - "id": urn:research:harbor
+    "revision": r2
+    "digest": sha256:8e5e492f7154b42b250ad3badea95cc73b571c6e22b4120cd957fcd9e57a0f2b
+"vocabularies":
+  - "id": urn:n8r:vocabulary:researcher-example
+    "version": "0.1"
+"nodes":
+  - "id": urn:component:lumen
+    "type":
+      "vocabulary": urn:n8r:vocabulary:researcher-example
+      "term": application
+    "label": Lumen Desk
+    "attributes":
+      "product":
+        "state": known
+        "note": Synthetic product
+        "value": Lumen Desk
+      "version":
+        "state": unknown
+        "note": No deployable revision supplied
+      "retries":
+        "state": omitted
+        "note": Relevant retry policy deliberately left for later research
+      "tenantLabel":
+        "state": redacted
+        "note": Withheld in this synthetic sharing case
+      "embeddedArchive":
+        "state": absent
+        "note": Settings note describes no embedded archive
+      "theme":
+        "state": out-of-scope
+        "note": UI design is outside this investigation
+    "basis":
+      - "record": urn:research:lumen
+        "revision": r2
+        "items":
+          - urn:finding:lumen:delivery
+          - urn:decision:lumen:archive
+    "requirements": []
+  - "id": urn:component:harbor
+    "type":
+      "vocabulary": urn:n8r:vocabulary:researcher-example
+      "term": service
+    "label": Harbor Archive
+    "attributes":
+      "product":
+        "state": known
+        "note": Synthetic product
+        "value": Harbor Archive
+      "version":
+        "state": unknown
+        "note": No implementation revision supplied
+    "basis":
+      - "record": urn:research:harbor
+        "revision": r2
+        "items":
+          - urn:finding:harbor:intake
+          - urn:decision:harbor:archive
+    "requirements": []
+  - "id": urn:component:identity
+    "type":
+      "vocabulary": urn:n8r:vocabulary:researcher-example
+      "term": service
+    "label": Shared identity service
+    "attributes":
+      "product":
+        "state": unknown
+        "note": Human selected a shared role; product unspecified
+    "basis":
+      - "record": urn:research:lumen
+        "revision": r2
+        "items":
+          - urn:finding:lumen:authentication
+          - urn:decision:lumen:identity
+      - "record": urn:research:harbor
+        "revision": r2
+        "items":
+          - urn:finding:harbor:authentication
+          - urn:decision:harbor:identity
+    "requirements":
+      - urn:requirement:identity
+  - "id": urn:component:inference
+    "type":
+      "vocabulary": urn:n8r:vocabulary:researcher-example
+      "term": inference-service
+    "label": Inference service
+    "attributes":
+      "modelVersion":
+        "state": unknown
+        "note": Not established by supplied sources
+    "basis":
+      - "record": urn:research:lumen
+        "revision": r2
+        "items":
+          - urn:finding:lumen:modelVersion
+    "requirements":
+      - urn:requirement:inference
+"relationships":
+  - "id": urn:relationship:documents
+    "from": urn:component:lumen
+    "to": urn:component:harbor
+    "type":
+      "vocabulary": urn:n8r:vocabulary:researcher-example
+      "term": sends-documents
+    "claim": declared
+    "attributes":
+      "batchLimit":
+        "state": unknown
+        "note": Guide says 10; settings note says 25. Conflict remains unresolved.
+      "protocol":
+        "state": known
+        "note": Selected declared protocol
+        "value": HTTP
+    "basis":
+      - "record": urn:research:lumen
+        "revision": r2
+        "items":
+          - urn:finding:lumen:delivery
+          - urn:decision:lumen:archive
+      - "record": urn:research:harbor
+        "revision": r2
+        "items":
+          - urn:finding:harbor:intake
+          - urn:decision:harbor:archive
+      - "record": urn:research:lumen
+        "revision": r2
+        "items":
+          - urn:finding:lumen:batchLimit
+    "requirements":
+      - urn:requirement:archive-token
+      - urn:requirement:payload
+  - "id": urn:relationship:audit
+    "from": urn:component:lumen
+    "to": urn:component:harbor
+    "type":
+      "vocabulary": urn:n8r:vocabulary:researcher-example
+      "term": sends-audit
+    "claim": declared
+    "attributes":
+      "protocol":
+        "state": known
+        "note": Independent parallel route
+        "value": HTTP
+    "basis":
+      - "record": urn:research:lumen
+        "revision": r2
+        "items":
+          - urn:finding:lumen:delivery
+          - urn:decision:lumen:archive
+      - "record": urn:research:harbor
+        "revision": r2
+        "items":
+          - urn:finding:harbor:intake
+          - urn:decision:harbor:archive
+    "requirements":
+      - urn:requirement:archive-token
+      - urn:requirement:payload
+  - "id": urn:relationship:callback
+    "from": urn:component:harbor
+    "to": urn:component:lumen
+    "type":
+      "vocabulary": urn:n8r:vocabulary:researcher-example
+      "term": notifies
+    "claim": declared
+    "attributes":
+      "schema":
+        "state": unknown
+        "note": Both support callback possibilities; exact compatibility not established
+    "basis":
+      - "record": urn:research:lumen
+        "revision": r2
+        "items":
+          - urn:finding:lumen:callback
+          - urn:decision:lumen:callback
+      - "record": urn:research:harbor
+        "revision": r2
+        "items":
+          - urn:finding:harbor:callback
+          - urn:decision:harbor:callback
+    "requirements":
+      - urn:requirement:payload
+  - "id": urn:relationship:lumen-auth
+    "from": urn:component:lumen
+    "to": urn:component:identity
+    "type":
+      "vocabulary": urn:n8r:vocabulary:researcher-example
+      "term": uses-identity
+    "claim": declared
+    "attributes":
+      "protocol":
+        "state": known
+        "note": Selected option
+        "value": OIDC
+    "basis":
+      - "record": urn:research:lumen
+        "revision": r2
+        "items":
+          - urn:finding:lumen:authentication
+          - urn:decision:lumen:identity
+    "requirements":
+      - urn:requirement:identity
+  - "id": urn:relationship:harbor-auth
+    "from": urn:component:harbor
+    "to": urn:component:identity
+    "type":
+      "vocabulary": urn:n8r:vocabulary:researcher-example
+      "term": uses-identity
+    "claim": declared
+    "attributes":
+      "protocol":
+        "state": known
+        "note": Selected option
+        "value": OIDC bearer token
+    "basis":
+      - "record": urn:research:harbor
+        "revision": r2
+        "items":
+          - urn:finding:harbor:authentication
+          - urn:decision:harbor:identity
+    "requirements":
+      - urn:requirement:identity
+  - "id": urn:relationship:inference
+    "from": urn:component:lumen
+    "to": urn:component:inference
+    "type":
+      "vocabulary": urn:n8r:vocabulary:researcher-example
+      "term": uses-inference
+    "claim": declared
+    "attributes":
+      "model":
+        "state": unknown
+        "note": Source does not identify model
+    "basis":
+      - "record": urn:research:lumen
+        "revision": r2
+        "items":
+          - urn:finding:lumen:modelVersion
+    "requirements":
+      - urn:requirement:inference
+"requirements":
+  - "id": urn:requirement:archive-token
+    "kind": secret
+    "description": Recipient supplies an appropriate local token binding; no secret value included.
+    "state": unknown
+  - "id": urn:requirement:identity
+    "kind": configuration
+    "description": Choose shared issuer, audiences and claim checks; selection does not configure a service.
+    "state": unknown
+  - "id": urn:requirement:payload
+    "kind": configuration
+    "description": Agree document/audit/callback schemas and limits.
+    "state": unknown
+  - "id": urn:requirement:inference
+    "kind": resource
+    "description": Select inference implementation, model and local bindings.
+    "state": unknown
+"coverage":
+  - Two fictional products researched from supplied documents.
+  - Shared identity and inference roles remain partial.
+"gaps":
+  - Integration not tested; no reachable or exercised connection evidence.
+  - Batch-limit conflict remains unresolved.
+  - No deployment bindings, effective setup or Experiment Runs supplied.

package/examples/researcher/cyclonedx/configured/README.md

@@ -0,0 +1,7 @@
+# CycloneDX exchange
+
+CycloneDX 1.7 · BOM version 1 · bound Surface.
+
+Open surface.cdx.json in a compatible consumer. Keep surface-records.json and mapping.json with it: they preserve the native evidence and explain the projection/losses. Configured dependencies do not establish runtime use. Coverage remains unknown.
+
+Use the standalone helper read operation to verify this directory before continuation. Prior files must stay unchanged.

package/examples/researcher/cyclonedx/configured/manifest.json

@@ -0,0 +1,10 @@
+{
+  "version": 1,
+  "predecessor": null,
+  "files": {
+    "surface.cdx.json": "sha256:fe84d5b0fa769d2c96710cdd627434b88cd1b6ce740b412ae492d51156f27a17",
+    "surface-records.json": "sha256:795a7b1fb33980888110f8ea0e67a67de5f98227b39f3104cfa7ed38fddba2a6",
+    "mapping.json": "sha256:65f69a776524ffc4d910b0199930e17b5b78ceb92e8dff45cd0fd8601578856d",
+    "README.md": "sha256:eb76d9f5cae1dce2d42d13239d011520c355695b1b3e23d15d78ae09704413e8"
+  }
+}

package/examples/researcher/cyclonedx/configured/mapping.json

@@ -0,0 +1,323 @@
+{
+  "profile": "n8r.cyclonedx-exchange/1",
+  "standard": "CycloneDX 1.7",
+  "surface": {
+    "id": "urn:demo:relationship-bound",
+    "revision": "r1",
+    "digest": "sha256:21eda5c348102d1ceea09f202c645a3184cba240316344b2a034a681730a636b",
+    "kind": "bound"
+  },
+  "research": {
+    "id": "urn:demo:relationship-research",
+    "revision": "r1",
+    "digest": "sha256:615bc6f8f443b986f78a46414faf97822206bcfcc9781e8d7c03d2dcb83940a0"
+  },
+  "mapping": {
+    "nodes": [
+      {
+        "id": "urn:node:app",
+        "kind": "component",
+        "type": "application",
+        "rationale": "Synthetic consumer rehearsal classification."
+      },
+      {
+        "id": "urn:node:mongodb",
+        "kind": "service",
+        "rationale": "Synthetic consumer rehearsal classification."
+      },
+      {
+        "id": "urn:node:oidc",
+        "kind": "service",
+        "rationale": "Synthetic consumer rehearsal classification."
+      },
+      {
+        "id": "urn:node:saml",
+        "kind": "service",
+        "rationale": "Synthetic consumer rehearsal classification."
+      },
+      {
+        "id": "urn:node:inference",
+        "kind": "service",
+        "rationale": "Synthetic consumer rehearsal classification."
+      },
+      {
+        "id": "urn:target:atlas",
+        "kind": "service",
+        "rationale": "Synthetic consumer rehearsal classification."
+      },
+      {
+        "id": "urn:target:oidc",
+        "kind": "service",
+        "rationale": "Synthetic consumer rehearsal classification."
+      },
+      {
+        "id": "urn:target:saml",
+        "kind": "service",
+        "rationale": "Synthetic consumer rehearsal classification."
+      }
+    ],
+    "dependencies": [
+      "urn:cap:database"
+    ]
+  },
+  "relationships": [
+    {
+      "id": "urn:cap:database",
+      "projected": true,
+      "reason": "Explicit configured dependency projection; detailed semantics retained in native snapshot.",
+      "relationship": {
+        "id": "urn:cap:database",
+        "from": "urn:node:app",
+        "to": "urn:node:mongodb",
+        "type": {
+          "vocabulary": "urn:v:demo",
+          "term": "persists-data"
+        },
+        "basis": [
+          {
+            "record": "urn:demo:relationship-research",
+            "revision": "r1",
+            "items": [
+              "urn:f:database"
+            ]
+          }
+        ],
+        "conditions": [],
+        "note": "Supported possibility, not a selected composition",
+        "purpose": {
+          "state": "known",
+          "claims": [
+            {
+              "value": "Persist conversation history and user profiles.",
+              "basis": [
+                {
+                  "record": "urn:demo:relationship-research",
+                  "revision": "r1",
+                  "items": [
+                    "urn:f:database-purpose"
+                  ]
+                }
+              ]
+            }
+          ],
+          "note": "Supported by synthetic source pack."
+        },
+        "integration": {
+          "state": "known",
+          "claims": [
+            {
+              "value": "MongoDB client driver using the MongoDB wire protocol.",
+              "basis": [
+                {
+                  "record": "urn:demo:relationship-research",
+                  "revision": "r1",
+                  "items": [
+                    "urn:f:database-integration"
+                  ]
+                }
+              ]
+            }
+          ],
+          "note": "Supported by synthetic source pack."
+        },
+        "configuration": {
+          "state": "known",
+          "claims": [
+            {
+              "value": [
+                {
+                  "owner": "urn:node:app",
+                  "mechanism": "environment-variable",
+                  "key": "CHAT_STORE_URI",
+                  "location": "config/assistant.env.example"
+                }
+              ],
+              "basis": [
+                {
+                  "record": "urn:demo:relationship-research",
+                  "revision": "r1",
+                  "items": [
+                    "urn:f:database-configuration"
+                  ]
+                }
+              ]
+            }
+          ],
+          "note": "Supported by synthetic source pack."
+        },
+        "binding": {
+          "state": "configured",
+          "claims": [
+            {
+              "target": "urn:target:atlas",
+              "basis": [
+                {
+                  "record": "urn:demo:relationship-research",
+                  "revision": "r1",
+                  "items": [
+                    "urn:f:database-bound"
+                  ]
+                }
+              ]
+            }
+          ],
+          "decisions": [],
+          "note": "Configuration sufficient; runtime unverified"
+        }
+      }
+    },
+    {
+      "id": "urn:cap:oidc",
+      "projected": false,
+      "reason": "Not projected as a dependency; see native relationship and evidence.",
+      "relationship": {
+        "id": "urn:cap:oidc",
+        "from": "urn:node:app",
+        "to": "urn:node:oidc",
+        "type": {
+          "vocabulary": "urn:v:demo",
+          "term": "authenticates-via"
+        },
+        "basis": [
+          {
+            "record": "urn:demo:relationship-research",
+            "revision": "r1",
+            "items": [
+              "urn:f:oidc"
+            ]
+          }
+        ],
+        "conditions": [
+          "OIDC and SAML are alternatives"
+        ],
+        "note": "Supported possibility, not a selected composition",
+        "purpose": {
+          "state": "known",
+          "claims": [
+            {
+              "value": "Authenticate users through an identity service.",
+              "basis": [
+                {
+                  "record": "urn:demo:relationship-research",
+                  "revision": "r1",
+                  "items": [
+                    "urn:f:oidc-purpose"
+                  ]
+                }
+              ]
+            }
+          ],
+          "note": "Supported by synthetic source pack."
+        },
+        "integration": {
+          "state": "known",
+          "claims": [
+            {
+              "value": "OpenID Connect",
+              "basis": [
+                {
+                  "record": "urn:demo:relationship-research",
+                  "revision": "r1",
+                  "items": [
+                    "urn:f:oidc-integration"
+                  ]
+                }
+              ]
+            }
+          ],
+          "note": "Supported by synthetic source pack."
+        },
+        "configuration": {
+          "state": "unknown",
+          "claims": [],
+          "note": "Not researched; no absence assertion."
+        },
+        "binding": {
+          "state": "conflicting",
+          "claims": [
+            {
+              "target": "urn:target:oidc",
+              "basis": [
+                {
+                  "record": "urn:demo:relationship-research",
+                  "revision": "r1",
+                  "items": [
+                    "urn:f:identity"
+                  ]
+                }
+              ]
+            },
+            {
+              "target": "urn:target:saml",
+              "basis": [
+                {
+                  "record": "urn:demo:relationship-research",
+                  "revision": "r1",
+                  "items": [
+                    "urn:f:identity"
+                  ]
+                }
+              ]
+            }
+          ],
+          "decisions": [
+            {
+              "record": "urn:demo:relationship-research",
+              "revision": "r1",
+              "items": [
+                "urn:decision:oidc"
+              ]
+            }
+          ],
+          "note": "Preference retained separately; configuration sources disagree"
+        }
+      }
+    },
+    {
+      "id": "urn:cap:inference",
+      "projected": false,
+      "reason": "Not projected as a dependency; see native relationship and evidence.",
+      "relationship": {
+        "id": "urn:cap:inference",
+        "from": "urn:node:app",
+        "to": "urn:node:inference",
+        "type": {
+          "vocabulary": "urn:v:demo",
+          "term": "uses"
+        },
+        "basis": [],
+        "conditions": [],
+        "note": "Unknown support",
+        "purpose": {
+          "state": "unknown",
+          "claims": [],
+          "note": "Not researched; no absence assertion."
+        },
+        "integration": {
+          "state": "unknown",
+          "claims": [],
+          "note": "Not researched; no absence assertion."
+        },
+        "configuration": {
+          "state": "unknown",
+          "claims": [],
+          "note": "Not researched; no absence assertion."
+        },
+        "binding": {
+          "state": "unknown",
+          "claims": [],
+          "decisions": [],
+          "note": "Missing evidence is not unbound"
+        }
+      }
+    }
+  ],
+  "losses": [
+    "Dependency projection does not encode purpose, integration mechanism, configuration evidence, binding states, alternatives or decisions; retained in surface-records.json and relationship report.",
+    "Node versions, package identifiers, upstream SBOM contents and transitive dependency completeness are not inferred from labels.",
+    "No runtime, control conformance, complete inventory or round-trip compatibility claim. Native records remain authoritative."
+  ],
+  "gaps": [
+    "Authentication conflict; inference unknown; runtime unverified"
+  ]
+}