fix: make workspace install under npm and enforce real guardrails

Replace pnpm-only workspace: protocol with npm workspace deps, pin BitVid and
BitRoad reference commits, add Node types, and make the reference-import check
scan package graphs and source for forbidden bitvid/bitroad imports.

.gitignore

@@ -0,0 +1,11 @@
+node_modules/
+dist/
+coverage/
+.DS_Store
+*.log
+.env
+.env.*
+.vite/
+.turbo/
+.cache/
+*.tsbuildinfo

docs/checkpoints.md

@@ -0,0 +1,28 @@
+# Checkpoints
+
+## Checkpoint 0 — Repo skeleton (current)
+
+Delivered:
+- npm workspaces monorepo
+- Node 22 + ESM
+- five empty packages under `packages/`
+- Vitest harness
+- TypeScript JSDoc typecheck
+- GitHub Actions CI
+- reference import guard
+- provenance docs
+
+Validation:
+```bash
+npm install
+npm run check:references
+npm run typecheck
+npm test
+npm run build:types
+```
+
+Gate: do not add runtime or BitVid codecs until fixture corpus exists.
+
+## Next checkpoint
+
+Checkpoint 1 — BitVid fixture and conformance corpus only.

docs/license-and-provenance.md

@@ -1,40 +1,46 @@
 # License and Provenance
 
-## Source Licenses
+## Reality check
 
-- **BitVid:** GPL-3.0-or-later
-- **BitRoad:** MIT
+BitVid is GPL-3.0-or-later. Direct ports of BitVid logic or structure into this
+repository create a derivative-work obligation. Do not pretend extracted
+behavior is clean-room MIT unless it truly is independent work.
 
-## Derived Works
+BitRoad is MIT and is used here only as a target/model reference.
 
-This repository combines:
+## Working stance for this repo
 
-1. **Original architectural work** (MIT)
-   - Workspace structure
-   - Core target model
-   - Policy engine design
+Until a lawyer-ready SPDX audit is done, treat the repository as:
 
-2. **GPL-encumbered behavior** (must remain GPL-compatible)
-   - BitVid moderation thresholds
-   - Trust seed behavior
-   - Report aggregation rules
+1. **Tooling / scaffolding** — original workspace layout, CI, docs structure.
+2. **Likely GPL-encumbered governance behavior** — anything characterized from
+   BitVid moderation thresholds, trust seeds, admin lists, report dedupe, mute
+   expiry, and related evaluator precedence.
+3. **MIT-compatible address concepts** — BitRoad coordinate shapes, used as
+   consumer validation cases rather than copied UI/runtime code.
 
-3. **MIT-licensed reference concepts**
-   - BitRoad addressable targets
-   - Storefront/product identifiers
+## Package boundary intention
 
-## Compliance Strategy
+| Package | Intention |
+| --- | --- |
+| `@nostr-governance/core` | Clean API surface + pure evaluator. Avoid BitVid names. |
+| `@nostr-governance/nostr` | Codecs. Legacy BitVid codec is provenance-sensitive. |
+| `@nostr-governance/runtime` | Transport/storage orchestration. |
+| `@nostr-governance/bitvid-compat` | Explicit BitVid-facing adapter. Most provenance-exposed. |
+| `@nostr-governance/testing` | Fakes and fixture loaders. |
 
-- Core policy engine is MIT-licensed original work
-- BitVid-compat adapter is GPL-3.0-or-later
-- Clear separation between:
-  - Generic governance interfaces (MIT)
-  - BitVid-specific behavior (GPL)
+## Rules
 
-## Audit Trails
+- No direct imports from BitVid or BitRoad source trees.
+- Fixtures copied into this repo must record the source commit in README or metadata.
+- If a module is ported from BitVid rather than rewritten cleanly, document it in
+  the PR and keep SPDX compatible with GPL-3.0-or-later.
+- Do not dual-license the whole monorepo casually. Prefer one root LICENSE once
+  chosen, and call out adapter exceptions only if they are scoped carefully.
 
-All extracted behavior is documented in:
+## Open decision (checkpoint 0)
 
-- `fixtures/bitvid/` (input/output pairs)
-- `docs/reference-map.md` (source locations)
-- Commit history (clean room steps)
+Root license has not been finalized in this bootstrap.
+Recommended default for continued extraction work: **GPL-3.0-or-later**.
+
+Decision needed from owner before publishing packages.

docs/reference-map.md

@@ -1,25 +1,39 @@
 # Reference Map
 
-## Pinned Versions
+BitVid and BitRoad are **read-only reference repositories**.
+This repo must not import their source trees.
 
-- **BitVid:** `4525c1c` (2026-07-26)
-- **BitRoad:** `bcd6c8e` (2026-07-26)
+## Pinned reference commits
 
-## Core Module References
+| Repo | Short | Full |
+| --- | --- | --- |
+| BitVid | `726c0d26` | `726c0d26ed98bf08e923ab895d23d0b5ac9ae173` |
+| BitRoad | `bcd6c8e` | `bcd6c8efbd142d8923e7d4110432bdfa0a6cd2a2` |
 
-| Module | BitVid Source | BitRoad Source | Purpose |
-|--------|---------------|----------------|---------|
-| identifiers | - | `src/commerce/address.mjs` | Coordinate parsing |
-| targets | `js/services/moderationUtils.js` | `src/commerce/storefronts.mjs` | Addressable target model |
-| authority | `js/accessControl.js` | - | Role resolution |
-| policy | `js/services/moderationService.js` | - | Threshold handling |
+Pinned on 2026-07-26 from local checkouts under `/home/user/Documents/GitHub/`.
 
-## License Provenance
+## Behavioral references (BitVid)
 
-BitVid is licensed under GPL-3.0-or-later. This repository contains:
+| Topic | BitVid path |
+| --- | --- |
+| Identifier / event ID helpers | `js/adminEventBlacklistHelpers.js` |
+| Access control / roles | `js/accessControl.js` |
+| Admin list persistence | `js/adminListStore.js` |
+| Community blacklist batching | `js/adminListBatch.js` |
+| Trust seeds | `js/services/trustBootstrap.js` |
+| Report / mute aggregation | `js/services/moderationService.js` |
+| Threshold / utility helpers | `js/services/moderationUtils.js` |
+| Video presentation mapping | `js/services/moderationDecorator.js` |
 
-- **Original work:** New architecture, neutral target model
-- **Derivative work:** Behavior extracted from BitVid fixtures
-- **Reference-only:** BitRoad address semantics
+## Structural references (BitRoad)
 
-Consult `docs/license-and-provenance.md` for detailed audit trails.
+| Topic | BitRoad path |
+| --- | --- |
+| Address coordinates | `src/commerce/address.mjs` |
+| Storefront replaceables | `src/commerce/storefronts.mjs` |
+| Product replaceables | `src/commerce/product.mjs` |
+
+## Extraction rule
+
+Copy **behavior via fixtures and characterization**, not live imports.
+Package source that imports BitVid/BitRoad fails `npm run check:references`.

package.json

@@ -6,10 +6,10 @@
   "description": "Headless Nostr governance SDK for decentralized moderation and access control",
   "scripts": {
     "test": "npm run test:unit && npm run test:conformance",
-    "test:unit": "vitest run",
-    "test:conformance": "vitest run tests/conformance",
-    "typecheck": "tsc --noEmit",
-    "build:types": "tsc --emitDeclarationOnly",
+    "test:unit": "vitest run --passWithNoTests",
+    "test:conformance": "vitest run tests/conformance --passWithNoTests",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "build:types": "tsc -p tsconfig.types.json",
     "lint": "npm run check:references && npm run check:types",
     "check:references": "node scripts/verify-no-reference-imports.mjs",
     "check:types": "npm run typecheck"
@@ -21,6 +21,7 @@
     "packages/*"
   ],
   "devDependencies": {
+    "@types/node": "^22.10.0",
     "typescript": "^5.4.5",
     "vitest": "^1.6.0"
   }

packages/bitvid-compat/package.json

@@ -4,12 +4,18 @@
   "type": "module",
   "main": "src/index.js",
   "types": "dist/types/src/index.d.ts",
-  "files": ["dist"],
+  "files": ["src", "dist"],
+  "exports": {
+    ".": {
+      "types": "./dist/types/src/index.d.ts",
+      "import": "./src/index.js"
+    }
+  },
   "scripts": {
     "test": "vitest run"
   },
   "dependencies": {
-    "@nostr-governance/core": "workspace:*",
-    "@nostr-governance/nostr": "workspace:*"
+    "@nostr-governance/core": "*",
+    "@nostr-governance/nostr": "*"
   }
 }

packages/core/package.json

@@ -4,7 +4,13 @@
   "type": "module",
   "main": "src/index.js",
   "types": "dist/types/src/index.d.ts",
-  "files": ["dist"],
+  "files": ["src", "dist"],
+  "exports": {
+    ".": {
+      "types": "./dist/types/src/index.d.ts",
+      "import": "./src/index.js"
+    }
+  },
   "scripts": {
     "test": "vitest run"
   },

packages/core/test/smoke.test.js

@@ -0,0 +1,8 @@
+import { describe, it, expect } from "vitest";
+
+describe("@nostr-governance/core smoke", () => {
+  it("loads the package entrypoint", async () => {
+    const mod = await import("../src/index.js");
+    expect(mod).toBeTypeOf("object");
+  });
+});

packages/nostr/package.json

@@ -4,11 +4,17 @@
   "type": "module",
   "main": "src/index.js",
   "types": "dist/types/src/index.d.ts",
-  "files": ["dist"],
+  "files": ["src", "dist"],
+  "exports": {
+    ".": {
+      "types": "./dist/types/src/index.d.ts",
+      "import": "./src/index.js"
+    }
+  },
   "scripts": {
     "test": "vitest run"
   },
   "dependencies": {
-    "@nostr-governance/core": "workspace:*"
+    "@nostr-governance/core": "*"
   }
 }

packages/runtime/package.json

@@ -4,12 +4,18 @@
   "type": "module",
   "main": "src/index.js",
   "types": "dist/types/src/index.d.ts",
-  "files": ["dist"],
+  "files": ["src", "dist"],
+  "exports": {
+    ".": {
+      "types": "./dist/types/src/index.d.ts",
+      "import": "./src/index.js"
+    }
+  },
   "scripts": {
     "test": "vitest run"
   },
   "dependencies": {
-    "@nostr-governance/core": "workspace:*",
-    "@nostr-governance/nostr": "workspace:*"
+    "@nostr-governance/core": "*",
+    "@nostr-governance/nostr": "*"
   }
 }

packages/testing/package.json

@@ -4,11 +4,17 @@
   "type": "module",
   "main": "src/index.js",
   "types": "dist/types/src/index.d.ts",
-  "files": ["dist"],
+  "files": ["src", "dist"],
+  "exports": {
+    ".": {
+      "types": "./dist/types/src/index.d.ts",
+      "import": "./src/index.js"
+    }
+  },
   "scripts": {
     "test": "vitest run"
   },
   "dependencies": {
-    "@nostr-governance/core": "workspace:*"
+    "@nostr-governance/core": "*"
   }
 }

scripts/verify-no-reference-imports.mjs

@@ -1,42 +1,204 @@
 #!/usr/bin/env node
+/**
+ * Fail if packages import BitVid/BitRoad source or depend on those trees.
+ * BitVid and BitRoad are read-only reference repos only.
+ */
+import { readdir, readFile, stat } from "node:fs/promises";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
 
-import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { fileURLToPath } from 'node:url';
+const __filename = fileURLToPath(import.meta.url);
+const ROOT = dirname(dirname(__filename));
 
-const FORBIDDEN_PATHS = [
-  '/home/user/Documents/GitHub/bitvid',
-  '/home/user/Documents/GitHub/bitroad'
+const FORBIDDEN_PATH_FRAGMENTS = [
+  "/Documents/GitHub/bitvid",
+  "/Documents/GitHub/bitroad",
+  "Documents/GitHub/bitvid",
+  "Documents/GitHub/bitroad",
 ];
 
-async function checkImports(rootPath) {
-  const pkgPath = join(rootPath, 'package.json');
-  const pkg = JSON.parse(await readFile(pkgPath, 'utf-8'));
+const FORBIDDEN_PACKAGE_NAMES = ["bitvid", "bitroad"];
 
+const FORBIDDEN_IMPORT_RE =
+  /(?:from\s+|import\s*\(|require\s*\()\s*['"]([^'"]+)['"]/g;
+
+const TEXT_EXTENSIONS = new Set([
+  ".js",
+  ".mjs",
+  ".cjs",
+  ".ts",
+  ".tsx",
+  ".jsx",
+  ".json",
+  ".md",
+]);
+
+/** @param {string} dir */
+async function walk(dir) {
+  /** @type {string[]} */
+  const files = [];
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return files;
+  }
+
+  for (const entry of entries) {
+    if (
+      entry.name === "node_modules" ||
+      entry.name === ".git" ||
+      entry.name === "dist" ||
+      entry.name === "coverage"
+    ) {
+      continue;
+    }
+
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...(await walk(full)));
+      continue;
+    }
+
+    const ext = entry.name.includes(".")
+      ? `.${entry.name.split(".").pop()}`
+      : "";
+    if (TEXT_EXTENSIONS.has(ext)) {
+      files.push(full);
+    }
+  }
+  return files;
+}
+
+/**
+ * @param {string} value
+ * @returns {boolean}
+ */
+function isForbiddenImportSource(value) {
+  const normalized = value.replace(/\\/g, "/");
+
+  if (
+    normalized === "bitvid" ||
+    normalized === "bitroad" ||
+    normalized.startsWith("bitvid/") ||
+    normalized.startsWith("bitroad/")
+  ) {
+    return true;
+  }
+
+  for (const fragment of FORBIDDEN_PATH_FRAGMENTS) {
+    if (normalized.includes(fragment)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * @param {Record<string, string> | undefined} deps
+ * @param {string} location
+ * @param {string[]} violations
+ */
+function checkDeps(deps, location, violations) {
+  for (const [name, version] of Object.entries(deps || {})) {
+    if (FORBIDDEN_PACKAGE_NAMES.includes(name) || isForbiddenImportSource(name)) {
+      violations.push(`${location}: forbidden dependency "${name}"`);
+    }
+    if (typeof version === "string" && isForbiddenImportSource(version)) {
+      violations.push(
+        `${location}: forbidden dependency version for "${name}": ${version}`,
+      );
+    }
+  }
+}
+
+async function main() {
+  const rootPkgPath = join(ROOT, "package.json");
+  await stat(rootPkgPath);
+
+  /** @type {string[]} */
   const violations = [];
 
-  for (const workspace of pkg.workspaces || []) {
-    const workspacePath = join(rootPath, workspace);
-    const workspacePkgPath = join(workspacePath, 'package.json');
-    const workspacePkg = JSON.parse(await readFile(workspacePkgPath, 'utf-8'));
+  const rootPkg = JSON.parse(await readFile(rootPkgPath, "utf8"));
+  checkDeps(rootPkg.dependencies, "package.json", violations);
+  checkDeps(rootPkg.devDependencies, "package.json", violations);
+  checkDeps(rootPkg.optionalDependencies, "package.json", violations);
+  checkDeps(rootPkg.peerDependencies, "package.json", violations);
 
-    for (const dep of Object.keys(workspacePkg.dependencies || {})) {
-      if (FORBIDDEN_PATHS.some(path => dep.startsWith(path))) {
-        violations.push(`Workspace ${workspace} depends on forbidden path: ${dep}`);
+  const packagesDir = join(ROOT, "packages");
+  let packageDirs = [];
+  try {
+    packageDirs = (await readdir(packagesDir, { withFileTypes: true }))
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => join(packagesDir, entry.name));
+  } catch {
+    packageDirs = [];
+  }
+
+  for (const packageDir of packageDirs) {
+    const pkgPath = join(packageDir, "package.json");
+    let pkg;
+    try {
+      pkg = JSON.parse(await readFile(pkgPath, "utf8"));
+    } catch {
+      continue;
+    }
+
+    const rel = relative(ROOT, pkgPath);
+    checkDeps(pkg.dependencies, rel, violations);
+    checkDeps(pkg.devDependencies, rel, violations);
+    checkDeps(pkg.optionalDependencies, rel, violations);
+    checkDeps(pkg.peerDependencies, rel, violations);
+  }
+
+  const scanRoots = [
+    join(ROOT, "packages"),
+    join(ROOT, "scripts"),
+    join(ROOT, "tests"),
+    join(ROOT, "examples"),
+  ];
+
+  for (const scanRoot of scanRoots) {
+    const files = await walk(scanRoot);
+    for (const file of files) {
+      // Allow the guard script itself to mention forbidden path fragments.
+      if (file === __filename) {
+        continue;
+      }
+
+      const content = await readFile(file, "utf8");
+      const rel = relative(ROOT, file);
+
+      for (const match of content.matchAll(FORBIDDEN_IMPORT_RE)) {
+        const source = match[1];
+        if (isForbiddenImportSource(source)) {
+          violations.push(`${rel}: forbidden import of "${source}"`);
+        }
+      }
+
+      // Catch file: / link: absolute path deps written into package.json files.
+      if (file.endsWith("package.json") && isForbiddenImportSource(content)) {
+        // Already covered via dependency version checks; keep for raw path mentions.
       }
     }
   }
 
   if (violations.length > 0) {
-    console.error('\nReference import violations detected:');
-    violations.forEach(v => console.error(`- ${v}`));
+    console.error("Reference import guard failed:\n");
+    for (const violation of violations) {
+      console.error(`- ${violation}`);
+    }
+    console.error(
+      "\nBitVid and BitRoad are read-only reference repositories. Do not import from them.",
+    );
     process.exit(1);
   }
 
-  console.log('✓ No forbidden imports detected');
+  console.log("✓ No forbidden BitVid/BitRoad imports detected");
 }
 
-checkImports(fileURLToPath(new URL('.', import.meta.url))).catch(err => {
-  console.error('Check failed:', err);
+main().catch((error) => {
+  console.error("check:references failed:", error);
   process.exit(1);
 });

tsconfig.json

@@ -1,15 +1,29 @@
 {
   "compilerOptions": {
-    "module": "ESNext",
-    "moduleResolution": "Bundler",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
     "target": "ES2022",
+    "lib": ["ES2022"],
     "strict": true,
     "skipLibCheck": true,
     "noEmit": true,
     "allowJs": true,
     "checkJs": true,
-    "types": ["vitest/globals"]
+    "noImplicitAny": false,
+    "resolveJsonModule": true,
+    "types": ["node", "vitest/globals"]
   },
-  "include": ["**/*.js"],
-  "exclude": ["node_modules"]
+  "include": [
+    "packages/**/src/**/*.js",
+    "packages/**/test/**/*.js",
+    "tests/**/*.js",
+    "vitest.config.js"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist",
+    "coverage",
+    "**/dist/**",
+    "scripts/**"
+  ]
 }

tsconfig.types.json

@@ -1,9 +1,21 @@
 {
   "extends": "./tsconfig.json",
   "compilerOptions": {
+    "noEmit": false,
     "emitDeclarationOnly": true,
     "declaration": true,
-    "outDir": "dist/types"
+    "declarationMap": true,
+    "outDir": "dist/types",
+    "rootDir": "."
   },
-  "include": ["packages/**/src/*.js"]
+  "include": [
+    "packages/**/src/**/*.js"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist",
+    "coverage",
+    "**/test/**",
+    "**/*.test.js"
+  ]
 }

vitest.config.js

@@ -1,12 +1,12 @@
-import { defineConfig } from 'vitest/config';
+import { defineConfig } from "vitest/config";
 
 export default defineConfig({
   test: {
-    include: ['**/*.test.js'],
-    environment: 'node',
-    coverage: {
-      provider: 'v8',
-      reporter: ['text', 'json-summary']
-    }
-  }
+    include: [
+      "packages/**/test/**/*.test.js",
+      "tests/**/*.test.js",
+    ],
+    environment: "node",
+    passWithNoTests: true,
+  },
 });