Make optional workspace dependencies explicit and fail closed

.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

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
 

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"
 }

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
+});

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 });
+}

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"
+  ]
+}