From 430abfb82b35b1ab862a99fba950e4d96996bc06 Mon Sep 17 00:00:00 2001 From: Riverbraid Date: Mon, 27 Jul 2026 13:28:16 -0400 Subject: [PATCH 1/6] Add explicit optional workspace dependency contract --- workspace-dependency-contract.json | 52 ++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 workspace-dependency-contract.json diff --git a/workspace-dependency-contract.json b/workspace-dependency-contract.json new file mode 100644 index 0000000..a4e93c7 --- /dev/null +++ b/workspace-dependency-contract.json @@ -0,0 +1,52 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "record_id": "RB-GOLD-V2-WORKSPACE-DEPENDENCY-CONTRACT-001", + "version": "1.0.0-candidate", + "status": "OPTIONAL_WORKSPACE_ONLY", + "repository": "Riverbraid/Riverbraid-Gold-V2", + "default_workspace_root": "PARENT_OF_REPOSITORY", + "commands": { + "check": { + "local_precommand": null, + "dependency": "riverbraid-tsh", + "executable": "cargo", + "arguments": ["check"] + }, + "test": { + "local_precommand": null, + "dependency": "riverbraid-tsh", + "executable": "cargo", + "arguments": ["test"] + }, + "build": { + "local_precommand": { + "executable": "npm", + "arguments": ["run", "build"] + }, + "dependency": "riverbraid-wasm-bridge", + "executable": "wasm-pack", + "arguments": ["build"] + } + }, + "outcomes": { + "dependency_missing_exit_code": 2, + "dependency_missing_status": "WORKSPACE_DEPENDENCY_UNAVAILABLE", + "command_failure_status": "WORKSPACE_COMMAND_FAILED", + "success_status": "WORKSPACE_COMMAND_CONDITIONS_MET" + }, + "claim_effect": "The rb-* commands require an explicitly prepared neighboring workspace. They are not part of the repository's self-contained default verification path.", + "nonclaims": [ + "This contract does not establish that the sibling repositories are present.", + "This contract does not pin sibling source commits.", + "This contract does not establish integrated F3 behavior.", + "This contract does not make Gold V2 a canonical Evaluation Kit route.", + "A successful local repository verifier does not establish workspace-command success." + ], + "review_triggers": [ + "sibling repository rename or path change", + "workspace command change", + "F3 profile membership decision", + "portable workspace profile adoption", + "replacement of sibling coupling with package or artifact dependencies" + ] +} From 1fe54dc140dd797c3cd6a0b33099e12cd9b939b6 Mon Sep 17 00:00:00 2001 From: Riverbraid Date: Mon, 27 Jul 2026 13:28:34 -0400 Subject: [PATCH 2/6] Add fail-closed workspace command runner --- scripts/run-workspace-command.mjs | 86 +++++++++++++++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 scripts/run-workspace-command.mjs diff --git a/scripts/run-workspace-command.mjs b/scripts/run-workspace-command.mjs new file mode 100644 index 0000000..7d22667 --- /dev/null +++ b/scripts/run-workspace-command.mjs @@ -0,0 +1,86 @@ +import fs from "node:fs"; +import path from "node:path"; +import { spawnSync } from "node:child_process"; + +const commandName = process.argv[2]; +const contract = JSON.parse(fs.readFileSync("workspace-dependency-contract.json", "utf8")); +const command = contract.commands?.[commandName]; + +function emit(status, details = {}) { + console.log(JSON.stringify({ + status, + command: commandName ?? null, + contract_id: contract.record_id, + contract_version: contract.version, + ...details + }, null, 2)); +} + +if (!command) { + emit("INVALID_WORKSPACE_COMMAND", { + allowed_commands: Object.keys(contract.commands ?? {}) + }); + process.exit(64); +} + +const workspaceRoot = process.env.RIVERBRAID_WORKSPACE_ROOT + ? path.resolve(process.env.RIVERBRAID_WORKSPACE_ROOT) + : path.resolve(process.cwd(), ".."); +const dependencyPath = path.join(workspaceRoot, command.dependency); + +if (!fs.existsSync(dependencyPath) || !fs.statSync(dependencyPath).isDirectory()) { + emit(contract.outcomes.dependency_missing_status, { + dependency: command.dependency, + workspace_root: workspaceRoot, + dependency_path: dependencyPath, + claim_effect: contract.claim_effect + }); + process.exit(contract.outcomes.dependency_missing_exit_code); +} + +function run(executable, args, cwd, phase) { + const result = spawnSync(executable, args, { + cwd, + stdio: "inherit", + shell: false + }); + + if (result.error) { + emit(contract.outcomes.command_failure_status, { + phase, + executable, + arguments: args, + cwd, + error: result.error.message + }); + process.exit(1); + } + + if (result.status !== 0) { + emit(contract.outcomes.command_failure_status, { + phase, + executable, + arguments: args, + cwd, + exit_code: result.status + }); + process.exit(result.status ?? 1); + } +} + +if (command.local_precommand) { + run( + command.local_precommand.executable, + command.local_precommand.arguments, + process.cwd(), + "LOCAL_PRECOMMAND" + ); +} + +run(command.executable, command.arguments, dependencyPath, "WORKSPACE_DEPENDENCY_COMMAND"); + +emit(contract.outcomes.success_status, { + dependency: command.dependency, + workspace_root: workspaceRoot, + dependency_path: dependencyPath +}); From 3e55ea3c5c6e41259d7db114cbc4bfa8d2509dda Mon Sep 17 00:00:00 2001 From: Riverbraid Date: Mon, 27 Jul 2026 13:29:08 -0400 Subject: [PATCH 3/6] Add deterministic missing-workspace boundary test --- tests/workspace-boundary.mjs | 41 ++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 tests/workspace-boundary.mjs diff --git a/tests/workspace-boundary.mjs b/tests/workspace-boundary.mjs new file mode 100644 index 0000000..577f128 --- /dev/null +++ b/tests/workspace-boundary.mjs @@ -0,0 +1,41 @@ +import assert from "node:assert/strict"; +import fs from "node:fs"; +import os from "node:os"; +import path from "node:path"; +import { spawnSync } from "node:child_process"; + +const contract = JSON.parse(fs.readFileSync("workspace-dependency-contract.json", "utf8")); + +assert.equal(contract.status, "OPTIONAL_WORKSPACE_ONLY"); +assert.deepEqual(Object.keys(contract.commands).sort(), ["build", "check", "test"]); +assert.equal(contract.outcomes.dependency_missing_exit_code, 2); +assert.equal(contract.outcomes.dependency_missing_status, "WORKSPACE_DEPENDENCY_UNAVAILABLE"); + +const emptyWorkspace = fs.mkdtempSync(path.join(os.tmpdir(), "riverbraid-gold-v2-empty-workspace-")); + +try { + for (const command of Object.keys(contract.commands)) { + const result = spawnSync(process.execPath, ["scripts/run-workspace-command.mjs", command], { + cwd: process.cwd(), + env: { + ...process.env, + RIVERBRAID_WORKSPACE_ROOT: emptyWorkspace + }, + encoding: "utf8" + }); + + assert.equal(result.status, 2, `${command} should return the declared unavailable exit code`); + + const output = JSON.parse(result.stdout); + assert.equal(output.status, "WORKSPACE_DEPENDENCY_UNAVAILABLE"); + assert.equal(output.command, command); + assert.equal(output.contract_id, contract.record_id); + assert.equal(output.workspace_root, emptyWorkspace); + assert.equal(typeof output.dependency, "string"); + assert.equal(output.dependency.length > 0, true); + } + + console.log("GOLD_V2_WORKSPACE_BOUNDARY_PASS"); +} finally { + fs.rmSync(emptyWorkspace, { recursive: true, force: true }); +} From 410dbf5479a1ae976a583e1cc8d5a8fe0e6b6597 Mon Sep 17 00:00:00 2001 From: Riverbraid Date: Mon, 27 Jul 2026 13:29:29 -0400 Subject: [PATCH 4/6] Route sibling scripts through explicit workspace contract --- package.json | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/package.json b/package.json index f22696f..c52478a 100644 --- a/package.json +++ b/package.json @@ -8,13 +8,14 @@ "build": "tsc && vite build", "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0", "preview": "vite preview", - "rb-check": "tsc && cd ../riverbraid-tsh && cargo check", - "rb-test": "cd ../riverbraid-tsh && cargo test", - "rb-build": "npm run build && cd ../riverbraid-wasm-bridge && wasm-pack build", - "test": "node verify.mjs", + "rb-check": "node scripts/run-workspace-command.mjs check", + "rb-test": "node scripts/run-workspace-command.mjs test", + "rb-build": "node scripts/run-workspace-command.mjs build", + "test": "node verify.mjs && node tests/workspace-boundary.mjs", + "verify": "node verify.mjs", + "verify:workspace-boundary": "node tests/workspace-boundary.mjs", "verify:feature-flow": "node verify-feature-flow.cjs", - "test:legacy": "npm run verify:feature-flow", - "verify": "node verify.mjs" + "test:legacy": "npm run verify:feature-flow" }, "dependencies": { "react": "^18.2.0", @@ -32,7 +33,12 @@ "typescript": "^5.2.2", "vite": "^5.2.0" }, - "description": "Riverbraid Gold petal for deterministic stationarity verification.", + "engines": { + "node": "20.11.0", + "npm": "10.2.4" + }, + "packageManager": "npm@10.2.4", + "description": "Riverbraid experimental Gold V2 concept and demo surface with bounded local and optional workspace verification paths.", "main": "index.js", "license": "MIT" } From 63852fe4de7cc2e17e1e1672b5c06161361a3ed5 Mon Sep 17 00:00:00 2001 From: Riverbraid Date: Mon, 27 Jul 2026 13:29:54 -0400 Subject: [PATCH 5/6] Verify local build and workspace dependency boundary --- .github/workflows/verify.yml | 45 +++++++++++++++++------------------- 1 file changed, 21 insertions(+), 24 deletions(-) diff --git a/.github/workflows/verify.yml b/.github/workflows/verify.yml index d091911..be68cd8 100644 --- a/.github/workflows/verify.yml +++ b/.github/workflows/verify.yml @@ -1,38 +1,35 @@ name: Riverbraid Verification Gate + on: push: - branches: [ main ] + branches: [main] pull_request: - branches: [ main ] + branches: [main] workflow_dispatch: + permissions: contents: read + jobs: verify: - runs-on: ubuntu-latest + runs-on: ubuntu-24.04 steps: - name: Checkout Repository - uses: actions/checkout@v4 + uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 + - name: Setup Node.js - uses: actions/setup-node@v4 + uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 with: node-version: '20.11.0' - - name: Install Dependencies If Lockfile Is Present - run: | - if [ -f package-lock.json ] && [ -f package.json ]; then - npm ci - else - echo "No package-lock.json/package.json pair found. Skipping dependency install." - fi - - name: Execute Riverbraid Verifier - run: | - if [ -f verify.mjs ]; then - node verify.mjs - elif [ -f package.json ] && grep -q '"verify":' package.json 2>/dev/null; then - npm run verify - elif [ -f package.json ] && grep -q '"test":' package.json 2>/dev/null; then - npm test - else - echo "Error: No standard verifier found." - exit 1 - fi + + - name: Install locked dependencies with lifecycle scripts denied + run: npm ci --ignore-scripts + + - name: Execute local repository verifier + run: npm run verify + + - name: Verify optional workspace dependency boundary + run: npm run verify:workspace-boundary + + - name: Build local demo surface + run: npm run build From 9124578dbc7ec1285accc7098df6453fbbab51ec Mon Sep 17 00:00:00 2001 From: Riverbraid Date: Mon, 27 Jul 2026 13:30:19 -0400 Subject: [PATCH 6/6] Document local and optional workspace execution boundaries --- README.md | 78 +++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 62 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 0b273bb..767966c 100644 --- a/README.md +++ b/README.md @@ -1,49 +1,95 @@ # Riverbraid-Gold-V2 -**Lifecycle category:** experimental concept/demo surface -**Normative source:** Riverbraid-Core +**Lifecycle category:** experimental concept/demo surface +**Normative source:** Riverbraid-Core **Claim boundary:** Declared Conditions Only ## Role in Riverbraid Riverbraid-Gold-V2 is an experimental next-generation concept and demo surface for Riverbraid interface, ledger, and verification ideas. -This repository is not a canonical Evaluation Kit proof route unless a current registry and evidence surface explicitly say so. +This repository is not a canonical Evaluation Kit route unless a current registry and evidence surface explicitly say so. ## Public verification boundary Local verifier output, demo behavior, and UI behavior must not be treated as canonical registry verification. -Package scripts in this repository may reference neighboring repositories. Those references are dependency-boundary surfaces and should not be treated as self-contained proof unless the full workspace layout and evidence surface are checked. +The repository has two deliberately separate execution surfaces: -Primary public entry point: -https://github.com/Riverbraid/Riverbraid-Evaluation-Kit +1. **Repository-local surface** — `npm run verify`, `npm test`, and `npm run build` operate within this repository. +2. **Optional workspace surface** — `npm run rb-check`, `npm run rb-test`, and `npm run rb-build` require declared neighboring repositories and tools. -Documentation hub: -https://github.com/Riverbraid/Riverbraid-Documentation +`workspace-dependency-contract.json` is the machine-readable boundary for the optional workspace commands. `scripts/run-workspace-command.mjs` executes those commands without shell-string `cd` coupling. -## Evidence boundary +When a required sibling is absent, the runner emits: -This repository does not claim certification, legal approval, production readiness, absolute security, external audit, complete AI safety, adoption, registry freshness, or absence of defects. +```text +WORKSPACE_DEPENDENCY_UNAVAILABLE +``` -## Authority boundary +and exits with code `2`. That is a classified unavailable state, not a self-contained test failure and not a PASS. -Riverbraid-Core remains the normative source for protocol semantics. This repository does not override Core, the Evaluation Kit registry, workflow evidence, release state, or external review. +The current contract does not pin sibling source commits and does not establish integrated F3 behavior. + +## Primary public routes + +- Evaluation Kit: https://github.com/Riverbraid/Riverbraid-Evaluation-Kit +- Documentation: https://github.com/Riverbraid/Riverbraid-Documentation ## Local use +Install the exact lockfile dependency set with package lifecycle scripts denied: + +```bash +npm ci --ignore-scripts +``` + +Run the local demo: + ```bash -npm install npm run dev ``` -## Verification +Build the local demo: + +```bash +npm run build +``` + +## Local verification ```bash -node verify.mjs +npm run verify +npm run verify:workspace-boundary ``` -This command currently represents local repository verification only unless stronger evidence is explicitly provided. +The first command evaluates the repository-local stationary surface. The second confirms that optional workspace dependencies are represented and that missing siblings produce the declared unavailable outcome. + +A successful local verifier does not establish success of the optional workspace commands. + +## Optional prepared-workspace commands + +The default workspace root is the parent directory of this repository. It may be overridden explicitly: + +```bash +RIVERBRAID_WORKSPACE_ROOT=/path/to/workspace npm run rb-check +``` + +Commands: + +- `npm run rb-check` — requires `riverbraid-tsh` and runs `cargo check`; +- `npm run rb-test` — requires `riverbraid-tsh` and runs `cargo test`; +- `npm run rb-build` — runs the local build, then requires `riverbraid-wasm-bridge` and runs `wasm-pack build`. + +The prepared workspace must identify and verify its own sibling source states. Directory proximity does not establish compatibility or profile membership. + +## Evidence boundary + +This repository does not claim certification, legal approval, production readiness, absolute security, external audit, complete AI safety, adoption, registry freshness, integrated F3 operation, workspace portability, or absence of defects. + +## Authority boundary + +Riverbraid-Core remains the normative source for protocol semantics. This repository does not override Core, the Evaluation Kit registry, workflow evidence, release state, or external review. ## License