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

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

@@ -0,0 +1,153 @@
+{
+  "id": "urn:demo:research",
+  "title": "Synthetic capability and binding evidence",
+  "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.research/0.1",
+  "sources": [
+    {
+      "id": "urn:source:summary",
+      "location": "sources.md",
+      "version": "synthetic-1",
+      "digest": "sha256:892be031542be26860afe70102a0293aa30b6cfaf15d091e95549c0e11277e49",
+      "inspectedAt": "2026-11-08T00:00:00Z",
+      "coverage": [
+        {
+          "path": "sources.md",
+          "status": "inspected",
+          "note": "Sanitized synthetic source pack, not raw configuration."
+        }
+      ]
+    }
+  ],
+  "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:atlas",
+          "evidence": [
+            {
+              "source": "urn:source:summary",
+              "locator": "Sanitized instance configuration summary, revision 1"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "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"
+            }
+          ]
+        }
+      ]
+    }
+  ],
+  "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/descriptions/research-r2.json

@@ -0,0 +1,157 @@
+{
+  "id": "urn:demo:research",
+  "title": "Synthetic capability and binding evidence",
+  "scope": "Synthetic role/product identities only; runtime unverified.",
+  "revision": {
+    "id": "r2",
+    "parent": {
+      "id": "urn:demo:research",
+      "revision": "r1",
+      "digest": "sha256:628d3c612d4afbb09852ec51436cf8b51f4fb96f02407c2b99e45dc06a3dfec0"
+    },
+    "createdAt": "2026-11-08T00:00:00Z",
+    "author": "Synthetic author",
+    "reason": "Changed database binding evidence"
+  },
+  "extensions": {},
+  "contract": "n8r.research/0.1",
+  "sources": [
+    {
+      "id": "urn:source:summary",
+      "location": "sources.md",
+      "version": "synthetic-1",
+      "digest": "sha256:892be031542be26860afe70102a0293aa30b6cfaf15d091e95549c0e11277e49",
+      "inspectedAt": "2026-11-08T00:00:00Z",
+      "coverage": [
+        {
+          "path": "sources.md",
+          "status": "inspected",
+          "note": "Sanitized synthetic source pack, not raw configuration."
+        }
+      ]
+    }
+  ],
+  "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"
+            }
+          ]
+        }
+      ]
+    }
+  ],
+  "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/descriptions/sources.md

@@ -0,0 +1,24 @@
+# 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.

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>