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

package/docs/n8r-surface/versioning.md

@@ -0,0 +1,183 @@
+# Package version and release identity
+
+The [approved decision in issue #27](https://github.com/injectionator/n8r-surface/issues/27#issuecomment-6661015093)
+applies to both `@n8r/surface` and `n8r-surface`. Their authoritative version is
+`package.json`; the lockfile must agree. Both packages come from one build of one
+commit. The installed command reads its own manifest for `--version`, regardless
+of the working directory. Package versions do not version the AI Surface Model,
+Researcher skill, or individual saved Surface revisions.
+
+## Compatibility and version changes
+
+Follow [SemVer 2.0.0](https://semver.org/spec/v2.0.0.html) for package releases.
+The compatibility boundary covers documented library exports, supported Node
+majors, command inputs/exit behavior, settings and persisted formats. Provisional
+model semantics remain provisional; a package number does not establish universal
+model conformance. Document migration requirements for breaking changes.
+
+| Stage | Breaking change | Compatible feature | Compatible fix |
+| --- | --- | --- | --- |
+| Before 1.0 | Increment minor, reset patch | Increment minor, reset patch | Increment patch |
+| From 1.0 | Increment major, reset minor/patch | Increment minor, reset patch | Increment patch |
+
+Before 1.0, this is a project compatibility convention stronger than SemVer's
+allowance for initial development. A major release of 1.0 requires an explicit
+compatibility decision, not simply a successful build. Prereleases use a suffix
+such as `-experimental.1` or `-rc.1`; increment it for changed prerelease bytes.
+Never reuse a released number. Release versions exclude `+build` metadata to
+avoid distinct Git tags representing the same npm version identity.
+
+Use `npm version VERSION --no-git-tag-version` for an approved version change,
+then review both manifests in the issue's PR. `npm run check:version` rejects
+invalid versions and drift in either lockfile version. `npm test` and candidate
+packing run that check. A version bump needs no source-code edit for CLI output.
+The maintainer confirmed `0.1.0-experimental.2` and authorized publication on
+5 November 2026. Review/merge and required account actions remain separate. See
+the [first-release procedure](npm-release.md).
+
+npm distribution tags are movable pointers, unlike permanent Git release tags:
+
+- Experimental prereleases use explicit `experimental` on both packages.
+- Release candidates use explicit `next`; they must not update `latest`.
+- Stable releases may use `latest` only after both exact-version routes pass
+  verification and promotion is authorized. Publish initially under `next` to
+  permit independent readback before promotion.
+
+## One version, one commit, one release
+
+After release authorization, use a clean, reviewed commit with the approved
+version. Create one annotated `vVERSION` Git tag pointing to its full commit SHA;
+never move, overwrite or delete a release tag. Create the corresponding GitHub
+Release as a draft with `target_commitish` explicitly set to that SHA and the
+prerelease flag matching the version. Do not use a moving branch as the target.
+
+Enable [GitHub release immutability](https://docs.github.com/en/code-security/how-tos/secure-your-supply-chain/establish-provenance-and-integrity/prevent-release-changes)
+before publishing a release. Attach all evidence before finalizing the draft:
+GitHub then locks its tag and assets. The verifier rejects published releases
+that do not report `immutable: true`. No repository settings are changed by
+these local tools. Review/approval of the selected commit is a maintainer
+prerequisite; the verifier checks identity, not the adequacy of code review.
+
+Retain `candidates.json` and both exact tarballs from the approved build. Each
+report entry has a `releaseAsset` name, respectively
+`n8r-surface-VERSION-scoped.tgz` and `n8r-surface-VERSION-unscoped.tgz`. Copy the
+bytes under those distinct names when uploading release assets, since npm gives
+both original tarballs the same basename. Upload the report too, and retain the
+build environment, test evidence, release notes and per-package registry results.
+SHA-256 identifies bytes; it does not authenticate the builder.
+
+The source packer requires `private: true`. The explicit `--publishable` option
+creates fresh publishable archives at the approved first version; ordinary
+candidates stay private. Use a fresh reviewed commit and build. Do not strip the guard from an old tarball
+and keep its old hash or claim it was built from an unchanged commit. The current
+verifier accepts private artifacts only for draft metadata rehearsals.
+
+## Read-only verification commands
+
+From the clean source checkout corresponding to the retained candidates, with
+Node 22/24/26, Git, POSIX `tar`, and GitHub CLI authenticated for read access:
+
+```sh
+npm run check:version
+npm run check:release -- /path/to/candidates
+```
+
+The second command reads GitHub's release API and resolves the remote tag. It
+checks the source and lockfile versions, clean HEAD, report revision/dirty flag,
+local and remote tag targets, release target SHA and prerelease flag, both archive
+manifests and hashes, and matching uploaded asset names/digests. It fails closed
+on missing data or API errors. A passing JSON result includes the version,
+revision, tag, draft status, `evidence: "GitHub API readback"`, and explicit
+`npmPublication`/`provenance` values of `"not checked"`. No files or remote state
+are changed. Published releases also require immutability and non-private archives.
+
+For offline checking of a previously saved raw GitHub REST release response:
+
+```sh
+npm run check:release -- /path/to/candidates /path/to/release.json
+```
+
+This deliberately reports `evidence: "offline metadata rehearsal"`. It does not
+contact GitHub or verify a remote tag. Handwritten or stale JSON is not live
+release evidence. The report is also not a reproducible-build proof: validating
+its claimed revision cannot prove arbitrary supplied artifacts were built from
+that revision. Authenticated build provenance and registry readback remain
+required. This checker remains read-only. The separate [release workflow](npm-release.md)
+performs explicitly selected publication; registry permissions remain external.
+
+## Authentication, provenance and incomplete releases
+
+Before any first publication, establish the npm account, package ownership and
+`n8r` organization/team rights for both names. The official
+[scoped publication guide](https://docs.npmjs.com/creating-and-publishing-scoped-public-packages/)
+documents public access and direct-publication authentication requirements.
+Its staged first-publication path creates a public placeholder; staging is not
+a read-only readiness check. The maintainer approved this staged route for the
+first release after npm offered stage-only tokens; submit the actual retained
+artifacts, not an empty reservation package. The [procedure](npm-release.md)
+requires maintainer 2FA approval of both real versions.
+
+Prefer [trusted publishing](https://docs.npmjs.com/trusted-publishers/) from the
+public repository using GitHub-hosted runners. Configure each package separately
+for the exact workflow and environment. npm documents Node 22.14+ and npm 11.5.1+
+for trusted publishing; its dist-tag permission is separate and requires newer
+npm (11.21.0+ in the 11 series or 12.2.0+ in the 12 series). A newly configured
+publisher must complete a successful publish within two days or be recreated.
+These are prerequisites to verify during release preparation, not settings this
+increment changes. References checked 5 November 2026.
+
+For each exact installed registry version, run `npm audit signatures` and inspect
+its [provenance](https://docs.npmjs.com/generating-provenance-statements/). Require
+evidence for the package itself, not merely an attested dependency. Compare the
+attestation's source commit/repository and artifact digest with the approved
+release. Also compare registry tarball bytes with the retained SHA-256 and record
+registry `dist.integrity`. A repository URL or locally generated hash is not
+registry provenance. Repeat the [isolated consumer checks](npm-distribution.md#human-verification)
+and documented npm-exec routes for both names.
+
+If one package publishes and the other fails, the release is **incomplete**.
+Retain the exact build and draft GitHub Release. Inspect the existing published
+bytes and evidence, then retry only the missing package using the retained
+artifact after resolving the failure. Never rebuild or overwrite the published
+version. A mismatch requires a new approved version for both names. Promote both
+npm dist-tags and finalize the immutable GitHub Release only after both routes
+pass. If tag promotion partially fails, record that too and repair only the
+missing pointer update; it does not require republishing package bytes.
+
+## Human check for this increment
+
+Maintainer preparation: provide this branch, installed dependencies and the
+candidate setup from [the distribution guide](npm-distribution.md#build-and-inspect-candidates).
+No npm credentials, real Git tag, GitHub Release or global-install change is needed.
+Keep the current terminal with `candidate_run` set by that guide.
+
+- [ ] From the checkout root run `npm run check:version`. Expect
+  `Version consistent: 0.1.0-experimental.2`, exit 0. Inspect `package.json` and
+  both root version fields in `package-lock.json`; they must match.
+- [ ] Follow the [candidate install steps](npm-distribution.md#human-verification)
+  for both names. In each consumer directory run:
+
+  ```sh
+  node -p 'require("./node_modules/@n8r/surface/package.json").version'
+  ./node_modules/.bin/n8r-surface --version
+  ```
+
+  For the alternative use `./node_modules/n8r-surface/package.json`. Expect
+  `0.1.0-experimental.2` and `n8r-surface 0.1.0-experimental.2`, both exit 0.
+- [ ] Inspect `candidates.json`: both entries have distinct `releaseAsset` names,
+  the same report version/revision, and hashes matching the retained tarballs.
+  A clean-commit rehearsal must say `dirty: false`.
+- [ ] Read the compatibility table and release/recovery procedure above. Expect
+  one permanent Git tag and exact commit for both package names; `experimental`
+  and `next` do not silently promote `latest`.
+- [ ] Report **Pass / Fail / Blocked**, Node/npm versions, report revision and
+  both CLI outputs. Version drift or missing artifacts is Fail. Missing real
+  release/authentication is Blocked for live release verification, not a reason
+  to create a tag or publish. Clean up only the temporary consumer directory
+  created by the distribution procedure after retaining needed evidence.
+
+Automated technical evidence: `tests/version.test.mjs` changes a copied installed
+manifest to `0.7.3-rc.2` and asserts CLI readback; `tests/release.test.mjs` uses
+throwaway Git repositories, tags, archives and metadata to exercise success and
+rejection paths. These tests are synthetic, not a real GitHub Release or registry
+publication. Agent rehearsal and human acceptance remain separate.

package/examples/researcher/README.md

@@ -0,0 +1,92 @@
+# Synthetic Researcher acceptance cases
+
+These fictional products and documents exercise the
+[experimental 0.1 contracts](../../docs/n8r-surface/contracts.md). They are not
+LibreChat findings, AI-generated discovery results or a working integration.
+No inference, credentials, network access or running target is needed to check them.
+
+Lumen Desk is a fictional AI support-summary application. Harbor Archive is an
+independent fictional document/event archive. A synthetic human selects a proposed
+composition after researching both. The sources establish possible interfaces;
+payload compatibility and effective configuration remain unverified.
+
+| File | Case |
+| --- | --- |
+| [Lumen guide](sources/lumen-guide.md), [settings](sources/lumen-settings.md) | Conflicting batch limits of 10 and 25; inference model unknown. |
+| [Lumen r1](lumen-r1.research.html) | Initial research; archive/identity selected, callback deferred. |
+| [Pending manual edit](lumen-manual-edit.pending.html) | Deliberately invalid visible edit; embedded data remains r1. |
+| [Lumen r2](lumen-r2.research.html) | Human-reviewed callback selection, preserving findings and opaque extension data. |
+| [Harbor interface notes](sources/harbor-api.md) | Independent product with unknown authentication. |
+| [Harbor r1](harbor-r1.research.html) | Useful incomplete research from one source. |
+| [Harbor authentication note](sources/harbor-auth.md) | Second supplied source establishes an OIDC option. |
+| [Harbor r2](harbor-r2.research.html) | Continuation keeps the authentication finding's identity and records a human selection. |
+| [Selected JSON](composed.surface.json), [selected YAML](composed.surface.yaml) | Same partial graph, referencing the exact r2 records. |
+
+Open a research HTML file in a browser to read its findings and inspect its embedded
+data. The data owns all facts; rendering is a derived view. These checked fixtures
+are inert, but arbitrary imported HTML must be validated before trusted rendering.
+
+## Selected composition
+
+```mermaid
+flowchart LR
+    Lumen[Lumen Desk] -->|documents| Harbor[Harbor Archive]
+    Lumen -->|audit events| Harbor
+    Harbor -->|callback| Lumen
+    Lumen -->|uses identity| Identity[Shared identity service]
+    Harbor -->|uses identity| Identity
+    Lumen -->|uses inference| Inference[Inference service]
+```
+
+The graph has shared identity, a cycle, identified parallel edges and node/edge
+attributes. All edges are declared only. The identity service's product and
+inference version remain unknown. Configuration/secret requirements are explicit
+local references without credential values. Attributes exercise known, unknown,
+omitted, redacted, absent and out-of-scope states. The conflicting batch limit is
+unknown in the selected definition and points back to both research claims.
+
+The example vocabulary `urn:n8r:vocabulary:researcher-example` version `0.1` has
+node terms `application`, `service`, `inference-service` and relationship terms
+`sends-documents`, `sends-audit`, `notifies`, `uses-identity`, `uses-inference`.
+These mean precisely the labeled roles/connections above, with no hidden protocol
+or lifecycle behavior. They are not a general ontology or a consumer capability.
+
+## Manual-edit case
+
+The pending file changes only the visible callback-decision reason. Its original
+embedded decision remains deferred. `readResearchHtml` must reject it as an
+HTML/data conflict. It must not silently choose the old embedded data or assume
+that visible prose establishes a structured decision.
+
+The synthetic review resolves the intended change: include callbacks in the desired
+composition, while retaining compatibility gaps. Lumen r2 records that selection,
+its author/time/reason and a human note, then regenerates the visible projection.
+Its parent digest pins r1; both earlier and pending files remain available.
+This demonstrates a reviewed result, not an implemented automatic reconciliation
+or persistence command.
+
+## Run the checks
+
+From the repository root, with a supported Node.js and npm:
+
+```sh
+npm ci
+npm test
+```
+
+Dependency installation uses the npm registry. The tests themselves are offline.
+They check source-byte hashes, internal references, exact external revisions,
+HTML/data agreement, rejection of the pending edit, successor lineage, unknown
+values and JSON/YAML equality. Semantic assertions verify the competing limits,
+new authentication evidence and selected graph structure. These checks do not
+verify an AI Researcher, facts about a real product or Lab compatibility.
+
+The future #17 runner and external skill must use these same cases, including a
+second source and human correction, and compare facts/choices/gaps rather than
+exact generated wording. Later Lab import/continuation must retain incomplete
+records, IDs, versions, provenance and extensions, and report unsupported meanings.
+
+Machine-readable fixtures and their rendered research HTML use
+[Apache-2.0](../../LICENSE). The synthetic source documents and this guide use
+[CC-BY-4.0](../../LICENSE-DOCS); credit AI Surface Model contributors. All material
+was created for these fixtures; no third-party product documentation is included.