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

package/docs/n8r-surface/save-reopen-verification.md

@@ -0,0 +1,152 @@
+# Saved continuation: evidence and limits
+
+Related to [#17](https://github.com/injectionator/n8r-surface/issues/17).
+Use [the short human check](getting-started.md). This increment implements
+SAVE-01 in numbered Markdown; it does not complete structured HTML/JSON/YAML,
+broader host/live trials, Lab integration or registry distribution.
+
+## Current verification
+
+**Pass (agent rehearsal), 5 November 2026. Human acceptance remains pending.**
+The prior conversation increment was user-reported Pass and PR #33 merged at
+`b186050`; the new saved-continuation evidence is recorded separately here.
+
+- Implementation: [`447f440`](https://github.com/injectionator/n8r-surface/commit/447f44058c142d3a49ed827298d922a6458fbcb1).
+  Rehearsal completed while repository HEAD was `b4407aa`, which changes only the
+  offline test driver's prompt matching and plan notes, not product code.
+- Installed tarball SHA-256:
+  `926823a95209ace0183875b2aaa2a3423f46671ad423f38e2b1fcdf885ef9b2d`.
+- Environment: macOS arm64, Node 26.13.0, Codex CLI 0.166.0, existing ChatGPT
+  sign-in, explicit `gpt-6-astra`. A private run under the selected vault held the
+  isolated install, n8r HOME/settings and copied synthetic source. Existing Codex
+  sign-in was reused through CODEX_HOME without copying credentials.
+- Loaded Researcher 0.1.8, combined instruction SHA-256
+  `8af29c3073df9b8210a7dd94ced9700379b0a98f76bd3a2902f9430b93c98a2a`.
+- [Actual sanitized terminal transcripts](save-reopen-transcript.md) retain model
+  messages and source-read activity. Findings and note prose were produced by
+  real Codex, not prewritten by the developing agent.
+
+### Exercised interaction and independent readback
+
+Starting state: copied `lumen-guide.md`, complete configured test vault, no saved
+notes and unchanged version-1 settings. The installed command performed the short
+human walkthrough's source investigation and OIDC decision, `/save`, `/exit`,
+explicit-note reopen with renewed transmission consent, authentication follow-up,
+`/save`, `/exit`. Both processes exited **0**. The original first note remained
+byte-identical after its successor was saved.
+
+A third process tested the user's additional request: append a human edit to the
+older first note, prioritizing session-expiry evidence while retaining the OIDC
+non-selection, then run `reopen --source SOURCE --model gpt-6-astra` without NOTE.
+It suggested the edited `research-001.md`, showed its edit time, and waited for
+selection and transmission consent. The conversation retained that edit and saved
+`research-003.md`, linking the edited first note. It did not overwrite 002 or edit
+001 again. This process also exited **0**.
+
+Independent file reads found all five stable IDs in every note:
+`component:lumen`, `component:inference`, `component:archive`,
+`component:callback`, `component:oidc`. All retained the OIDC decision separately
+from source claims, cited the actual guide, preserved unknowns and included
+recommended next steps. The third retained the session-expiry priority. The first
+note explicitly explains that source references require the accompanying guide.
+No runtime connection or alternative authentication mechanism was invented as fact.
+
+| Readback | SHA-256 / result |
+| --- | --- |
+| Source before and after all processes | `98d3374c79c166b37f0debb4ffb5e457eda1385dd7847b042cbad674cac98693` |
+| Original 001, preserved after saving 002 and referenced by 002 | `9910959c740959e943e7d6cf4e81b1d365468ab33576fb9c83aa9ce25dc054e7` |
+| Deliberately edited 001, preserved after saving 003 and referenced by 003 | `76b6abe6d616b903f641f2b8d52f06777ad5383060701ce49a314d3ff68eca52` |
+| Saved 002 | `927a6a84a810d518b5e7bc8f37df3f29916e353a3bb6817ccf21b2cc36aee265` |
+| Saved 003 | `56f317af8dfd30ea76cbfe0318bf74b226cc3be0ef851e0edc67bcd120d029d6` |
+| n8r settings | Unchanged bytes |
+
+Raw transcripts, saved files and readback report remain under the selected vault's
+runs/ convention. No local vault path or private infrastructure data is published.
+These are agent rehearsals using supplied synthetic human input, not human acceptance.
+
+### Automated verification and review
+
+- 97 Node tests passed on each of Node 22.23.2, 24.22.2 and 26.13.0.
+- Installed-package checks passed on all three runtimes, including 20 offline
+  discovery/save/reopen terminal scenarios. They cover no premature writes,
+  failed and cancelled staged drafts, source scope, latest selection/refusal,
+  changed-source comparisons, preserved predecessors and process cleanup.
+- Storage tests cover edit-time ranking, occupied names, changed predecessors,
+  symlink/replaced-folder refusal, bounded UTF-8 and human edits after metadata.
+- Fresh review found missing historical evidence and incompatible reopen-size
+  limits. Regression tests failed first, then passed after preserving unavailable
+  evidence and using bounded comparison summaries rather than embedded source text.
+- Linux CI exposed a test-driver race: a generic `[y/N]` matcher reused the first
+  prompt's suffix. The driver now waits for the complete transmission prompt.
+  Product code was unchanged; the initial failed CI run remains visible.
+- Python fixture/workflow suite: 24 passed. Shell syntax, Markdownlint 0.24.0,
+  offline Lychee 0.24.2 with fragments, cffconvert 2.0.0 and whitespace passed.
+
+Scripted protocol tests are not AI evidence; fixture integrity is not model
+conformance. The real rehearsal used one synthetic source and unchanged source
+bytes. Broader products, live observations, second-source integration, structured
+HTML/JSON/YAML, named Lab consumers and npm distribution remain open in #17/#27.
+
+## Storage and continuation boundary
+
+`/save` authorizes one numbered Markdown output. A dynamic `research_note` call
+stages a draft in memory only during that host-authorized turn. The host writes
+only after successful turn completion; ordinary conversation and unsolicited tool
+calls cannot write. Natural-language save requests receive `/save` guidance.
+The host shows the destination, appends current source-tool evidence and identified
+Researcher/model metadata, writes a temporary file, publishes by exclusive hard
+link, independently reads it back and prints the saved path and byte digest.
+Predecessors retain their bytes; successors link their name and exact digest.
+A changed predecessor requires reopening its edited version before another save.
+
+Notes have a 256 KiB total limit, with at most 192 KiB of model prose and 1,000
+source evidence entries. They use an experimental host metadata envelope, not
+an AI Surface interchange schema. Model-authored prose and IDs are checked in the
+rehearsal, not mechanically validated for truth. Metadata and human-edited prose
+are untrusted input on reopening; hashes identify bytes, not authenticity.
+
+`reopen [NOTE] --source SOURCE` requires explicit current source selection and
+renewed note/source transmission permission. It starts a new ephemeral Codex
+thread, compares saved evidence hashes with the selected source, reports changed
+or unavailable evidence, and supplies the note plus comparisons as untrusted
+research context. Reopening compares the saved evidence paths, retaining unavailable prior evidence
+for subsequent attempts. Compact comparisons sent to the model are bounded to
+128 KiB with an explicit omitted count; full source text is read on demand through
+the normal tools. Combined context is bounded to 512 KiB. Current source reads retain their normal limits;
+no shell, broad filesystem write or extra execution environment is granted.
+
+Without NOTE, the command suggests the latest filesystem-edited numbered note in
+that source's research folder, showing UTC edit time and requiring acceptance.
+A tied time sorts by filename; an invalid newest note is reported, not skipped.
+Folder naming and edit time do not establish source identity. Explicit NOTE can
+select another folder, and successors remain there. Only this command's metadata
+notes are supported; generic Markdown import is later work.
+
+Destination ancestor identities and predecessor bytes are checked again before
+publishing. Existing names are never replaced. Directory topology must remain
+stable during synchronous filesystem operations; this is not protection against
+an adversarial concurrent directory replacement. An interrupted process can leave
+an unreferenced hidden temporary file; it does not overwrite an earlier note.
+Local storage does not provide backup, encryption or publication.
+
+## Pending-operation indicator follow-up
+
+The user reported long silent waits during `/save` and after questions. Commit
+`a6d11ad` adds a terminal-only spinner with elapsed seconds for connecting,
+answering, reopening and preparing a note. It clears around normal output and
+stops before returning to the prompt, including errors/cancellation. It reports a
+pending request, not known server-side progress; nonterminal output never animates.
+
+An isolated installed candidate was rehearsed with real Codex 0.166.0,
+`gpt-6-astra`, ChatGPT sign-in and Node 26.13.0 on macOS. The same synthetic Lumen
+question/OIDC choice was followed by `/save` and `/exit`. The spinner produced
+162 preparation frames over approximately 40 seconds, cleared before
+**Saved and read back**, and produced no activity after the final `You>` prompt.
+One note was saved, exit was 0, and source/settings bytes remained unchanged.
+Raw terminal output and independent readback remain in the selected vault's runs/.
+Tarball SHA-256: `d90df87bc3f1db05a5de01ee0080d88a599ca4050e63473e548907f53b6dfe3a`.
+
+99 Node tests and the installed-package check passed. Terminal scenarios still
+cover cancellation/failure; focused tests verify repeated activity, clearing around
+output, timer cleanup and nonterminal silence. The six GitHub checks passed on
+`a6d11ad`. The short walkthrough now names the visible labels and expected stop.

package/docs/n8r-surface/security-assurance-strategy.md

@@ -0,0 +1,267 @@
+# Strategic direction: AI Surface security assurance
+
+Agreed direction, 12 November 2026. Tracked in
+[issue #64](https://github.com/injectionator/n8r-surface/issues/64).
+This document captures the destination and proposed delivery milestones. It does
+not claim an implemented framework, accepted assurance levels or runtime results.
+
+## Purpose and primary reader
+
+Provide a practical security assurance framework for people building and operating
+AI Surfaces, supported by professional services, reusable guidance and tools.
+The primary reader is the consultant advising a security engineer or architect,
+who helps the system owner decide what protection is needed and whether the
+evidence supports operation, release or a corrective change.
+
+The consultant must be able to explain the expected security capabilities,
+applicable controls, implementation options, verification procedures and remaining
+risk in language the owner can act on. The owner selects or approves the policy,
+required assurance level and any exceptions with that advice. Assessment records
+identify the assessor and the basis for each judgment; automation supplies evidence
+and repeatable checks without silently making the owner's risk decision.
+
+The intended service is to define the security expected of an AI Surface, discover
+how it is implemented, and demonstrate through observable testing whether the
+running system meets those expectations. Retain the evidence needed to explain
+its posture and verify improvements. A readable framework and a useful assessment
+are deliverables in their own right; the tools support their production and reuse.
+
+This is a strategic use of the independently usable AI Surface Model. There remains
+one model. The framework must work across different compositions, including
+applications, agents, models, tools, data services and their external dependencies.
+Unknown or inaccessible service internals remain explicit coverage limits.
+
+## From policy to implementation and observable verification
+
+| Layer | Required content and intended use |
+| --- | --- |
+| Policy and security objectives | Protected assets, intended users and authority, threats, obligations, scope and acceptable behaviour. |
+| Security capabilities and levels | Human-readable capability areas and versioned L1/L2-style profiles stating which requirements and verification obligations apply. |
+| Controls | Requirement, rationale, applicability, responsible party, protected resources/paths, enforcement points, dependencies and exceptions. |
+| Implementation guidance | Concrete steps and configuration requirements for named component versions and compositions; alternatives that satisfy the same intent. |
+| Verification procedures | Static inspection and live probes/attacks, prerequisites, authorized scope, expected outcomes, required observation points and failure/inconclusive criteria. |
+| Assessment and improvement | Findings, evidence, conformance, coverage, limitations, remediation and repeat verification against an identified successor setup. |
+
+Security capabilities here mean abilities such as enforcing user authority; they
+are not synonymous with a Capability Surface, which describes supported component
+and integration possibilities. L1/L2 are intended framework concepts, not existing
+levels or product ratings. Their control membership, applicability rules and
+verification depth still need definition. Decide explicitly whether a level adds
+controls, stronger evidence or both. Version policies and profiles so later changes
+do not silently change earlier assessments.
+
+Each control entry should let a practitioner answer: what is required, why it
+applies, where it is enforced, how to implement it, how to verify it, and what
+counts as sufficient evidence. A component's controls may depend on controls
+provided by another service. Evaluate complete paths as well as isolated nodes.
+
+## Bidirectional assessment of static and live Surfaces
+
+Work downwards from policy to controls, implementation and tests, and upwards from
+discovered components and behaviour to the requirements they support or violate.
+Neither direction requires a complete inventory before useful work can begin.
+
+Static inputs include repositories, documentation, inventories and configuration
+artifacts. Live inputs include running instances, effective configuration, service
+connections, user/role context, logs and permitted observations or probe results.
+Bind these to the relevant component and relationship identities, source revisions,
+effective setup, time and test Run. Repository configuration can differ from the
+effective running setup; preserve and investigate that disagreement.
+
+Keep these judgments separate:
+
+- **Required:** a policy/profile makes a control applicable to an identified scope.
+- **Claimed or configured:** documentation, code or instance configuration provides
+  evidence about the implementation, with its own limitations.
+- **Demonstrated:** a scoped observation or test supports or contradicts a claim
+  about the running system under stated conditions.
+
+These judgments complement Capability/Bound/Observed evidence distinctions; they
+are not replacements or automatic conversions. Configuration does not establish
+runtime effectiveness. Missing evidence is unknown, not proof of an absent
+control; a supported finding of absence must explain the examined scope.
+
+Link policy requirements to controls; controls to protected nodes, relationships
+and paths; implementations to enforcement components and configuration; and
+verification procedures/results to the exact claims and setup they assess. Users
+must be able to navigate from a component to its controls and tests, or from a
+control to every known implementation, uncovered path and outstanding question.
+
+## Domain, identity and control-aware runtime paths
+
+Assess the paths an LLM can assemble at runtime against the security framework.
+A test needs business meaning: which actor, acting from which context, attempts
+which operation on which resource, under which policy? HR records, CRM accounts,
+financial transactions and clinical data introduce different permissions and
+consequences. Trace authentication, authorization and accounting across the path,
+including changes from the initiating user to delegated or service identities.
+
+The circuit analogy describes how a request can connect tools, data and services
+into an execution path. It is an explanatory view of the same AI Surface Model,
+not a separate model or a claim that the LLM controls every connection. Host logic,
+tool availability, permissions and external systems also determine execution.
+The following synthetic diagram illustrates one candidate path, not live evidence:
+
+```mermaid
+flowchart LR
+    U[User and request context] --> A[Application and LLM]
+    A -->|Proposed tool call| G[Tool gateway]
+    G -->|Executed request| C[Service authorization]
+    C -->|Permitted operation| D[Protected business data]
+    C -->|Denied operation| X[Denial]
+    P[Policy and control requirements] -.-> G
+    P -.-> C
+    G -.-> E[Correlated execution evidence]
+    C -.-> E
+    D -.-> E
+```
+
+The illustrated enforcement points are candidates to investigate; their presence,
+coverage and effectiveness require evidence. A real path may branch, run in
+parallel, retry, loop or invoke further agents. Finite tools do not imply a small
+set of histories: arguments, state and repeated operations can produce an enormous
+or unbounded execution space. Do not promise exhaustive testing of arbitrary
+human inputs or every possible circuit.
+
+Assess the intended protection of each technique against explicit requirements:
+input constraints, actor/task-specific tool access, per-action authorization,
+sequence/state restrictions, approval bound to the executed action, execution/data
+budgets, and detection/interruption. These are candidate control families, not an
+adopted catalog. Input filtering or an LLM guardrail must not receive credit for
+service authorization without evidence that it enforces the relevant requirement.
+Individually permitted operations may combine into a forbidden business outcome.
+
+The assessment must identify which control held or failed. If the model proposes
+a prohibited read and the service denies it, downstream authorization held for
+that attempt even if a guardrail did not. If the model refuses after a tool has
+retrieved protected data, investigate the retrieval and disclosure separately.
+If the response invents a record without retrieval, assess integrity rather than
+claiming demonstrated unauthorized data access. Prompt injection is one means of
+exercising these boundaries; direct requests, retrieved content, tool outputs and
+stateful sequences can test the same business rule. Existing probe engines can
+supply inputs; the framework supplies context, expectations and evidence criteria.
+
+### Proof, counterexamples and bounded tests
+
+| Conclusion | Required basis and limit |
+| --- | --- |
+| Proved within stated assumptions | An identified property and explicit model/scope, justified assumptions and a suitable proof or exhaustive analysis of a bounded state space. Establish how the analyzed model corresponds to the deployed setup; a model proof alone is not proof of the whole live service. |
+| Disproved by a counterexample | A traceable execution violating the exact claim under its applicable conditions. One valid counterexample defeats a universal claim, even if the behavior is intermittent; it does not establish prevalence or failure of unrelated controls. |
+| Supported by bounded testing | Identified cases, repetitions, outcomes and observation coverage. Report the tested conditions and unexplored space; passing samples do not prove all paths safe. |
+| Inconclusive or blocked | Missing prerequisites, ambiguous attribution or insufficient telemetry. State what evidence would resolve the judgment; no observed failure does not imply a pass. |
+
+For probabilistic behavior, retain model/provider version where available, relevant
+settings, prompts and source context subject to privacy rules, initial state,
+identity/role, setup revision, attempts and observed outcomes. Record unknown
+provider details and changes. Repeated trials can characterize the sampled
+conditions; do not infer a general failure probability without a justified sampling
+method. Keep a retained counterexample even if later attempts cannot reproduce it.
+
+### Proposed Labs view: watch and replay the circuit
+
+A proposed n8r-labs consumer capability is to draw observed execution paths as
+events arrive and replay them afterwards. It should help the consultant see the
+initiating and effective identities, proposed versus executed tool calls, data
+movement, control decisions and resulting effects, with links back to the policy
+and evidence. A denied operation may be an exercised enforcement point without
+being a completed data-access path. A configured control without decision evidence
+must not be displayed as an observed successful check.
+
+Such a view depends on sufficiently correlated, authorized telemetry. Make missing
+instrumentation, delayed events, uncertain ordering and inferred links visible;
+chronological proximity alone does not establish causality. Describe observed data
+movement only to the granularity supported by evidence, without exposing protected
+payloads. Preserve the Run and effective setup so replay cannot silently substitute
+today's configuration for the one tested. The visualization is a view onto evidence,
+not proof of complete execution coverage.
+
+This records a consumer outcome and evidence requirements only. Labs UI design,
+instrumentation, event transport/storage and implementation belong in the separate
+n8r-labs repository. A static evidence-linked path is enough for the first framework
+slice; live animation is not a prerequisite for proving a bounded control failure.
+
+## Demonstrating conformance and reporting posture
+
+The distinguishing outcome is observable testing of control effectiveness.
+Probes and attacks must test explicit expected behaviour, including legitimate
+use, and retain enough downstream evidence to explain the result. A model refusal
+alone does not establish that a tool made no prohibited request or disclosed no
+protected data. Correlate initiating and effective identities, executed operations,
+authorization decisions, returned data and effects where relevant.
+
+For example, a tenant-isolation requirement leads to inspection of identity
+propagation and authorization, then authorized cross-user retrieval probes on a
+controlled composition. A successful prohibited read contradicts the control claim
+even if configuration inspection passed. After a defensive change, repeat both
+prohibited and legitimate access and preserve the original setup and evidence.
+A passing test supports the exercised conditions, not every possible attack.
+Missing telemetry or unavailable prerequisites produce an inconclusive or blocked
+verification result, not a pass.
+
+The strategic goal includes scoring a service against an agreed profile. Report
+conformance, assessment coverage, evidence strength/freshness and critical failures
+separately. A score must name its policy/profile version, applicable scope,
+assessment time and evidence basis. Untested controls must not appear as passes;
+exclusions and accepted exceptions must remain visible. Critical failures must not
+be hidden by averaging many easy passes. Numeric formulas, weights, level gates,
+expiry rules and treatment of exceptions remain design work; no current Surface
+artifact earns a framework score merely by validating or being saved.
+
+The consultant's report should show the target level, requirement-by-requirement
+judgments, supporting and contrary evidence, gaps, prioritized corrections and the
+owner's recorded decisions. Use concise defaults with explanations and evidence
+within one request, following the [presentation guidance](product-direction.md#presentation-brief-by-default-explanation-within-reach).
+
+## Existing work and proposed next milestones
+
+Status snapshot: 12 November 2026. Milestones below are a recommended sequence,
+not implementation authorization or release commitments. Close the existing
+acceptance loop while developing the first bounded framework example.
+
+| Work or milestone | Position and contribution | Evidence needed to advance |
+| --- | --- | --- |
+| Discovery and durable descriptions | Capability/Bound contract, standalone skill 0.1.11 and two-product verification merged in #53/#54/#58. These provide identities, relationships, evidence and revision preservation. | Retain the accepted bounded evidence; do not reinterpret it as security-posture acceptance. |
+| Practical consultant intake | Incremental source discovery and fresh-session correction rehearsed in draft #63; installation handoff in draft #62. | User review of the saved brief and useful next enquiries; preserve source/configuration/runtime distinctions. |
+| First framework slice | Next proposed milestone: one security capability, a small explicit control set, a provisional level profile, domain/identity context, implementation guidance and verification procedures with explicit proof/test limits. | A consultant and engineer can trace one policy requirement down to a test and a discovered fact back to the requirement, using a synthetic worked example. Approve the bounded profile before rating against it. |
+| Static and configured assessment | Apply that slice to a known composition using the existing discovery path. LibreChat/VPS/Atlas is an existing motivating path, not a required architecture or verified posture. | Evidence-linked control applicability, implementation claims, gaps and proposed probes; independent source/configuration readback. |
+| Observable runtime proof | Extend the [first value demonstration](product-direction.md#smallest-end-to-end-value-demonstration) with the selected control/profile and assessment record. Fixture and execution owner remain to be selected. | One discovered authority failure, a defensive change, prohibited/legitimate retests, downstream evidence attributing the result to a specific control, a retained runtime path and preserved before/after setup references. |
+| Repeatable assessment and scoring | Derive the initial reporting/rating rules from the worked example, then exercise another composition without product-specific control meanings. | Explicit coverage and critical-failure rules; independent review can reproduce judgments from retained evidence and identify inconclusive cases. |
+| Live path visualization | Proposed Labs consumer outcome: watch/replay observed circuits with identity and control context. No Labs implementation is included here. | Correlated events resolve to the same Run/setup and evidence; proposed/executed/denied actions, inferred links and telemetry gaps remain distinguishable. |
+| Distribution and consumer integration | CLI #59 and scoped candidate #60 remain drafts; #60 is stacked on #59. Labs adaptation belongs in its own repository. | Separate experience acceptance, release decisions and named-consumer evidence; these are delivery channels, not substitutes for assurance proof. |
+
+The narrow runtime demonstration is intended to become the first exercised path
+through the framework, not the whole strategic destination. Broader control coverage, additional levels,
+continuous reassessment and more implementations can follow evidence from that
+path. Existing issues #13/#17/#27 retain their wider remaining scope.
+
+## Standards and delivery boundaries
+
+The separate [CycloneDX adoption direction, #66](https://github.com/injectionator/n8r-surface/issues/66)
+and [draft #67](https://github.com/injectionator/n8r-surface/pull/67) establish the
+inventory/exchange foundation and SBOM-first discovery direction. Inventory,
+assembly and operational records should connect to controls and assessments.
+Their existence alone does not establish effectiveness or conformance.
+
+Investigate bounded mappings to CycloneDX 1.7 definitions/declarations and reference
+mechanisms, and OSCAL control implementation and assessment concepts. CycloneDX
+1.7 defines claims, targets and evidence; OSCAL describes component control
+implementations and assessment records. See the
+[CycloneDX 1.7 reference](https://cyclonedx.org/docs/1.7/proto/)
+and [OSCAL model overview](https://pages.nist.gov/OSCAL/learn/concepts/layer/).
+OSCAL is a mapping candidate, not an adopted dependency. Pin its selected version
+before producing a mapping. Follow the [interoperability evidence requirements](../interoperability.md#evidence-for-compatibility);
+no mapping, round trip or consumer compatibility is established by this strategy.
+
+n8r-surface supplies discovery descriptions and the meanings required to connect
+policy, claims and evidence. Execution owners supply authorized test/probe runs;
+observability supplies correlated evidence. Labs application design remains in
+its separate repository, with Lab-owned configuration and bindings. A manual
+execution handoff can prove the first slice without a general telemetry platform.
+
+The installed skill remains read-only with respect to target systems. This strategy
+does not add runtime collection, attack execution, an Observed Surface contract,
+a control catalog or a scoring engine. Each behavior change needs its own intent,
+installed-product attempt or recorded blocker, implementation and verification.
+Customer configurations, user data and raw telemetry remain in permitted private
+storage; publish only approved sanitized evidence. Framework conformance claims
+must stay within their assessed scope and do not imply certification.

package/docs/n8r-surface/skill-bom-verification.md

@@ -0,0 +1,142 @@
+# Self-contained Surface verification
+
+Issue [#68](https://github.com/injectionator/n8r-surface/issues/68), draft
+[PR #69](https://github.com/injectionator/n8r-surface/pull/69). Candidate 0.1.13.
+This record separates exercised behavior from pending human acceptance.
+
+## Baseline
+
+An actual installed 0.1.12 session inspected its instructions/helpers and ran
+exporter help. It reported that BOM-only recovery was unavailable: native records
+and mapping siblings were required. This was a capability inspection, not a full
+research round trip. No product findings or historical research were supplied.
+
+## Synthetic checks
+
+The new fixture retains four database alternatives, one selected dependency,
+unknown inference, source evidence, a decision and investigation entries in one
+BOM. Tests exercise copied-BOM recovery, selected graph equality, source/evidence
+references, independent observations, hosting distinctions, successor preservation,
+changed-view reconciliation, unsafe directories and HTML escaping. These are
+bounded automated checks, not model conformance or human acceptance.
+
+Sunshine commit `beaab3faf2bab234069a8677fc627de2f0f01a3d` generated HTML with the
+synthetic application, model and services but omitted profile alternatives/evidence
+and investigation entries. It is not the selected investigation renderer.
+
+Browser review of the generated local HTML was blocked by the browser tool's
+`file:` URL policy. No alternate route was attempted. File-level checks do not
+establish visual/browser acceptance.
+
+CycloneDX Python Library 11.12.0 with JSON validation extras accepted the synthetic
+BOM against 1.7 and loaded both components, four services and sixteen properties.
+It exposes no `annotations` attribute in this deserialization API; no complete
+profile round-trip claim is made. The native profile reader checks the complete
+BOM directly, including annotations and references.
+
+## Independent review
+
+Three material findings were reproduced in tests and fixed: BOM-path bypass of
+edited sibling views, disconnected inventory missing from human views, and dropped
+historical observations. The focused suite now has fifteen passing checks.
+
+## Installed assessment
+
+The user explicitly selected a local LibreChat checkout. Sources, transcripts and
+research remain in a new private run, separate from prior historical rehearsal.
+The everyday installation remains unchanged. All sessions used Codex CLI 0.166.0,
+ChatGPT sign-in, configured `gpt-6-astra`, Node 26.13.0 and macOS. No API-key or
+provider/model fallback. The exact initial installation matches `2b2816e`; the
+reviewed candidate used for diversion/continuation matches
+`bd2b8aef4ef7e6154d40c23349a846be69146da8` (24 plugin files).
+
+The harness supplied the installed skill, selected source and writable private
+workspace. Network, memory, unrelated tools and repository instruction loading
+were disabled. Filesystem probes checked denied historical evidence; these
+specific controls are not a general claim of host-memory isolation.
+
+The installed Researcher saved revision 001 with an initial plan before research.
+It independently inspected bounded ranges in fourteen files and saved revision
+002 with twelve nodes, thirteen relationships, twelve evidence records, ten
+journal entries and five gaps. All fourteen source hashes matched independent
+readback. No deployment selections were asserted. Git inspection was blocked
+inside the rehearsal; the Researcher recorded inspected hashes and the limit,
+rather than asserting a clean checkout. Developer-only source identity metadata
+is retained privately and was not supplied as research findings.
+
+The scripted user diversion paused tool/document investigations and prioritized
+authentication. The reviewed candidate inspected two additional files and saved
+revision 003. The BOM retains the rehearsal user decision, seventeen journal
+entries and three deferred paths with reasons. All ten files in revisions 001/002
+remain byte-identical. This is an agent-run user scenario, not human acceptance.
+
+One independent presentation assertion searched for an unescaped setting name in
+Markdown and failed after the successful save. The installed agent normalized
+Markdown-escaped underscores and completed readback; both results are retained.
+No saved files were replaced to make the assertion pass.
+
+For the final continuation, only revision 003's BOM was copied to a new writable
+workspace. The harness confirmed that the old workspace was denied and the prior
+ephemeral thread was unavailable. The reviewed installation recovered the objective,
+authentication-first choice, deferred paths/reasons and uncertainties, then saved
+revision 004 with a brief/map/journal. It did not need native siblings or old chats.
+
+Independent readback found twelve nodes, thirteen unchanged relationships, fifteen
+evidence records, twenty-two journal entries, two scoped rehearsal decisions and
+three deferred paths. All inherited evidence and source-backed claims were unchanged;
+the additional user-basis record describes continuation scope, not a source finding.
+All fifteen files in revisions 001–003 remain byte-identical. Seventeen source
+references across sixteen unique inspected files match their hashes; the original
+checkout's revision and working-tree status remain unchanged.
+
+The developer's first final assertion mistakenly required equality of the whole
+evidence array, rejecting the legitimate appended continuation-scope record. It
+was corrected to require preservation of inherited evidence and equality of all
+non-user source evidence; that check passed. Both attempts are recorded privately.
+
+These are agent rehearsals of the documented interactions. They do not establish
+human acceptance, actual deployment selections, runtime effectiveness or exhaustive
+source coverage. Selected/possible visual semantics are exercised by the synthetic
+fixture; the real assessment appropriately leaves deployment selection unknown.
+
+## Human task list
+
+Prerequisites: candidate 0.1.13 installed, Node 22/24/26 and readable selected
+sources; a new writable Surface folder outside the source checkout. The maintainer
+provides the exact candidate revision/digest and rehearsal output separately.
+
+- [ ] Open a fresh chat with the installed Researcher and the selected source.
+  Ask: “Explain the AI-relevant paths in this source. Save the Surface and maintain
+  an investigation journal in this folder as you go. Show me what to inspect next.”
+  Expect an initial plan, useful partial findings and openable journal/map/brief.
+- [ ] Inspect the map. Possible paths and selected paths must look different.
+  Open a relationship's evidence; unknown selection must not be called absent.
+  Selection must not be called observed runtime use without dated evidence.
+- [ ] Redirect: “Pause that path and investigate authentication first. Keep the
+  deferred work and explain what access would help.” Expect a recorded diversion,
+  deferred reason, new next steps and a new revision preserving earlier files.
+- [ ] In another fresh chat supply only the latest BOM and source access. Ask:
+  “Continue this Surface. What did I choose, what remains uncertain, and what
+  should we investigate next?” Expect recovery of the choices, evidence and
+  investigation state without requiring a native sibling or old chat.
+- [ ] Report **Pass / Fail / Blocked**, the interaction, candidate revision and
+  relevant output paths. Fail for lost decisions, invented bindings, changed old
+  files or missing state; Blocked for inaccessible sources/runtime. Keep source
+  data private. Retain outputs until reviewed; cleanup is only the disposable run.
+
+## Automated checks and retained candidate
+
+- Node 22.23.2, 24.22.2 and 26.13.0: 224 tests and package checks pass on each.
+- Markdown lint 0.24.0, offline lychee 0.24.2 links/anchors, cffconvert 2.0.0,
+  JSON parsing (18 examples), workflow shell syntax and 24 Python tests pass.
+- `npm ci` and `npm cache add yaml@2.9.1` completed; no new runtime dependency.
+- Exact reviewed candidate ZIP retained privately; SHA-256
+  `bdab66880bc1763c73ee30d98d3b188a4c8ae2af410f03b364785fbcc58640dd`.
+  No everyday plugin replacement, release or merge.
+
+The first package check failed because its golden instruction digest still named
+the earlier instructions; the reviewed digest was updated and all three package
+checks passed. Earlier red regression runs are retained as development evidence,
+not counted as final successes. Browser visual review and human acceptance remain
+pending. Structure, byte integrity and named consumer reads do not prove research
+accuracy or deployment behavior.