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

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/harbor-r1.research.html

@@ -0,0 +1,193 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'">
+<title>Harbor Archive research</title>
+<style>body{font:17px/1.55 system-ui,sans-serif;max-width:72rem;margin:3rem auto;padding:0 1.5rem;color:#18252d;background:#faf9f5}h1{line-height:1.2}h2{font-size:1.2rem;border-bottom:1px solid #b8c8c9;padding-bottom:.3rem}section{margin:2rem 0}dt{font-weight:650;color:#234c54}dd{margin:0 0 .6rem 1.3rem}li{margin:.75rem 0}span{white-space:pre-wrap;overflow-wrap:anywhere}.empty{color:#56656c;font-style:italic}header p{max-width:55rem}</style>
+</head>
+<body>
+<header><p>Research record · experimental 0.1</p><h1>Harbor Archive research</h1><p>Source research describes possibilities. It does not establish a running integration. The embedded data owns the facts; visible edits require review before continuation.</p></header>
+<section><h2>contract</h2><span>n8r.research/0.1</span></section>
+<section><h2>id</h2><span>urn:research:harbor</span></section>
+<section><h2>revision</h2><dl><dt>id</dt><dd><span>r1</span></dd><dt>parent</dt><dd><span>null</span></dd><dt>createdAt</dt><dd><span>2026-11-04T09:00:00Z</span></dd><dt>author</dt><dd><span>Synthetic researcher</span></dd><dt>reason</dt><dd><span>Inspect supplied fictional documents</span></dd></dl></section>
+<section><h2>scope</h2><span>Only the named synthetic documents; source research provides no runtime evidence.</span></section>
+<section><h2>extensions</h2><dl><dt>https://example.test/research-context/v1</dt><dd><dl><dt>synthetic</dt><dd><span>true</span></dd><dt>preserve</dt><dd><ol><li><span>unrecognized metadata</span></li><li><span>null</span></li><li><span>1</span></li></ol></dd></dl></dd></dl></section>
+<section><h2>sources</h2><ol><li><dl><dt>id</dt><dd><span>urn:source:harbor-api</span></dd><dt>location</dt><dd><span>sources/harbor-api.md</span></dd><dt>version</dt><dd><span>fixture-1</span></dd><dt>digest</dt><dd><span>sha256:b2b87be7df05374c4cc574a1f308bd3b3444f63cd95e894121b9ea1e7be3d681</span></dd><dt>inspectedAt</dt><dd><span>2026-11-04T09:00:00Z</span></dd><dt>coverage</dt><dd><ol><li><dl><dt>path</dt><dd><span>harbor-api.md</span></dd><dt>status</dt><dd><span>inspected</span></dd><dt>note</dt><dd><span>Whole supplied synthetic document; no repository or runtime inspected.</span></dd></dl></li></ol></dd></dl></li></ol></section>
+<section><h2>findings</h2><ol><li><dl><dt>id</dt><dd><span>urn:finding:harbor:intake</span></dd><dt>subject</dt><dd><span>urn:component:harbor</span></dd><dt>property</dt><dd><span>intake</span></dd><dt>state</dt><dd><span>known</span></dd><dt>claims</dt><dd><ol><li><dl><dt>value</dt><dd><ol><li><span>document HTTP route</span></li><li><span>audit HTTP route</span></li></ol></dd><dt>evidence</dt><dd><ol><li><dl><dt>source</dt><dd><span>urn:source:harbor-api</span></dd><dt>locator</dt><dd><span>Intake</span></dd></dl></li></ol></dd></dl></li></ol></dd><dt>note</dt><dd><span>Possible JSON routes; request schema unknown.</span></dd></dl></li><li><dl><dt>id</dt><dd><span>urn:finding:harbor:callback</span></dd><dt>subject</dt><dd><span>urn:component:harbor</span></dd><dt>property</dt><dd><span>callback</span></dd><dt>state</dt><dd><span>known</span></dd><dt>claims</dt><dd><ol><li><dl><dt>value</dt><dd><span>optional outbound HTTP callback</span></dd><dt>evidence</dt><dd><ol><li><dl><dt>source</dt><dd><span>urn:source:harbor-api</span></dd><dt>locator</dt><dd><span>Notifications</span></dd></dl></li></ol></dd></dl></li></ol></dd><dt>note</dt><dd><span>No compatibility claim.</span></dd></dl></li><li><dl><dt>id</dt><dd><span>urn:finding:harbor:authentication</span></dd><dt>subject</dt><dd><span>urn:component:harbor</span></dd><dt>property</dt><dd><span>authentication</span></dd><dt>state</dt><dd><span>unknown</span></dd><dt>claims</dt><dd><p class="empty">No entries recorded.</p></dd><dt>note</dt><dd><span>Initial interface note does not establish authentication.</span></dd></dl></li></ol></section>
+<section><h2>alternatives</h2><ol><li><dl><dt>id</dt><dd><span>urn:option:harbor:archive</span></dd><dt>title</dt><dd><span>Receive document and audit requests</span></dd><dt>findings</dt><dd><ol><li><span>urn:finding:harbor:intake</span></li></ol></dd><dt>requirements</dt><dd><ol><li><span>Agree payloads, limits and authentication</span></li></ol></dd></dl></li><li><dl><dt>id</dt><dd><span>urn:option:harbor:callback</span></dd><dt>title</dt><dd><span>Notify an HTTP receiver</span></dd><dt>findings</dt><dd><ol><li><span>urn:finding:harbor:callback</span></li></ol></dd><dt>requirements</dt><dd><ol><li><span>Configure receiver and callback validation</span></li></ol></dd></dl></li><li><dl><dt>id</dt><dd><span>urn:option:harbor:identity</span></dd><dt>title</dt><dd><span>Investigate shared identity</span></dd><dt>findings</dt><dd><ol><li><span>urn:finding:harbor:authentication</span></li></ol></dd><dt>requirements</dt><dd><ol><li><span>Obtain an authentication source</span></li></ol></dd></dl></li></ol></section>
+<section><h2>decisions</h2><ol><li><dl><dt>id</dt><dd><span>urn:decision:harbor:archive</span></dd><dt>alternative</dt><dd><span>urn:option:harbor:archive</span></dd><dt>choice</dt><dd><span>selected</span></dd><dt>reason</dt><dd><span>Synthetic user selects the archive role, pending interface checks.</span></dd><dt>by</dt><dd><span>Synthetic user</span></dd><dt>at</dt><dd><span>2026-11-04T09:00:00Z</span></dd></dl></li><li><dl><dt>id</dt><dd><span>urn:decision:harbor:callback</span></dd><dt>alternative</dt><dd><span>urn:option:harbor:callback</span></dd><dt>choice</dt><dd><span>selected</span></dd><dt>reason</dt><dd><span>Synthetic user requests archival notifications.</span></dd><dt>by</dt><dd><span>Synthetic user</span></dd><dt>at</dt><dd><span>2026-11-04T09:00:00Z</span></dd></dl></li><li><dl><dt>id</dt><dd><span>urn:decision:harbor:identity</span></dd><dt>alternative</dt><dd><span>urn:option:harbor:identity</span></dd><dt>choice</dt><dd><span>deferred</span></dd><dt>reason</dt><dd><span>Source evidence is incomplete.</span></dd><dt>by</dt><dd><span>Synthetic user</span></dd><dt>at</dt><dd><span>2026-11-04T09:00:00Z</span></dd></dl></li></ol></section>
+<section><h2>questions</h2><ol><li><dl><dt>id</dt><dd><span>urn:question:harbor:auth</span></dd><dt>text</dt><dd><span>What authentication does intake support?</span></dd><dt>findings</dt><dd><ol><li><span>urn:finding:harbor:authentication</span></li></ol></dd></dl></li><li><dl><dt>id</dt><dd><span>urn:question:harbor:schema</span></dd><dt>text</dt><dd><span>Can these routes accept Lumen output after explicit mapping?</span></dd><dt>findings</dt><dd><ol><li><span>urn:finding:harbor:intake</span></li></ol></dd></dl></li></ol></section>
+<section><h2>notes</h2><ol><li><dl><dt>by</dt><dd><span>Synthetic researcher</span></dd><dt>at</dt><dd><span>2026-11-04T09:00:00Z</span></dd><dt>text</dt><dd><span>Keep the two products independent until a human selects a composition.</span></dd></dl></li></ol></section>
+<script type="application/json" id="n8r-record">{
+  "contract": "n8r.research/0.1",
+  "id": "urn:research:harbor",
+  "title": "Harbor Archive research",
+  "revision": {
+    "id": "r1",
+    "parent": null,
+    "createdAt": "2026-11-04T09:00:00Z",
+    "author": "Synthetic researcher",
+    "reason": "Inspect supplied fictional documents"
+  },
+  "scope": "Only the named synthetic documents; source research provides no runtime evidence.",
+  "extensions": {
+    "https://example.test/research-context/v1": {
+      "synthetic": true,
+      "preserve": [
+        "unrecognized metadata",
+        null,
+        1
+      ]
+    }
+  },
+  "sources": [
+    {
+      "id": "urn:source:harbor-api",
+      "location": "sources/harbor-api.md",
+      "version": "fixture-1",
+      "digest": "sha256:b2b87be7df05374c4cc574a1f308bd3b3444f63cd95e894121b9ea1e7be3d681",
+      "inspectedAt": "2026-11-04T09:00:00Z",
+      "coverage": [
+        {
+          "path": "harbor-api.md",
+          "status": "inspected",
+          "note": "Whole supplied synthetic document; no repository or runtime inspected."
+        }
+      ]
+    }
+  ],
+  "findings": [
+    {
+      "id": "urn:finding:harbor:intake",
+      "subject": "urn:component:harbor",
+      "property": "intake",
+      "state": "known",
+      "claims": [
+        {
+          "value": [
+            "document HTTP route",
+            "audit HTTP route"
+          ],
+          "evidence": [
+            {
+              "source": "urn:source:harbor-api",
+              "locator": "Intake"
+            }
+          ]
+        }
+      ],
+      "note": "Possible JSON routes; request schema unknown."
+    },
+    {
+      "id": "urn:finding:harbor:callback",
+      "subject": "urn:component:harbor",
+      "property": "callback",
+      "state": "known",
+      "claims": [
+        {
+          "value": "optional outbound HTTP callback",
+          "evidence": [
+            {
+              "source": "urn:source:harbor-api",
+              "locator": "Notifications"
+            }
+          ]
+        }
+      ],
+      "note": "No compatibility claim."
+    },
+    {
+      "id": "urn:finding:harbor:authentication",
+      "subject": "urn:component:harbor",
+      "property": "authentication",
+      "state": "unknown",
+      "claims": [],
+      "note": "Initial interface note does not establish authentication."
+    }
+  ],
+  "alternatives": [
+    {
+      "id": "urn:option:harbor:archive",
+      "title": "Receive document and audit requests",
+      "findings": [
+        "urn:finding:harbor:intake"
+      ],
+      "requirements": [
+        "Agree payloads, limits and authentication"
+      ]
+    },
+    {
+      "id": "urn:option:harbor:callback",
+      "title": "Notify an HTTP receiver",
+      "findings": [
+        "urn:finding:harbor:callback"
+      ],
+      "requirements": [
+        "Configure receiver and callback validation"
+      ]
+    },
+    {
+      "id": "urn:option:harbor:identity",
+      "title": "Investigate shared identity",
+      "findings": [
+        "urn:finding:harbor:authentication"
+      ],
+      "requirements": [
+        "Obtain an authentication source"
+      ]
+    }
+  ],
+  "decisions": [
+    {
+      "id": "urn:decision:harbor:archive",
+      "alternative": "urn:option:harbor:archive",
+      "choice": "selected",
+      "reason": "Synthetic user selects the archive role, pending interface checks.",
+      "by": "Synthetic user",
+      "at": "2026-11-04T09:00:00Z"
+    },
+    {
+      "id": "urn:decision:harbor:callback",
+      "alternative": "urn:option:harbor:callback",
+      "choice": "selected",
+      "reason": "Synthetic user requests archival notifications.",
+      "by": "Synthetic user",
+      "at": "2026-11-04T09:00:00Z"
+    },
+    {
+      "id": "urn:decision:harbor:identity",
+      "alternative": "urn:option:harbor:identity",
+      "choice": "deferred",
+      "reason": "Source evidence is incomplete.",
+      "by": "Synthetic user",
+      "at": "2026-11-04T09:00:00Z"
+    }
+  ],
+  "questions": [
+    {
+      "id": "urn:question:harbor:auth",
+      "text": "What authentication does intake support?",
+      "findings": [
+        "urn:finding:harbor:authentication"
+      ]
+    },
+    {
+      "id": "urn:question:harbor:schema",
+      "text": "Can these routes accept Lumen output after explicit mapping?",
+      "findings": [
+        "urn:finding:harbor:intake"
+      ]
+    }
+  ],
+  "notes": [
+    {
+      "by": "Synthetic researcher",
+      "at": "2026-11-04T09:00:00Z",
+      "text": "Keep the two products independent until a human selects a composition."
+    }
+  ]
+}</script>
+</body>
+</html>