feat: ctx 1.37.0, /bin/link, blind-peer proc gate, and CI/docs follow-ups

- Bump bareOsCtxApiVersion to 1.37.0; sync syscalls.example.json and ctx helper - Add ctx.bareOsReadSnapshotHintsJson mirroring snapshot_hints proc JSON - Gate blind_relay_router / blind_pairing_sketch / relay_geo_hint behind BARE_OS_PROC_BLIND_PEER_RELAY_HINTS; passthrough + env appendix docs - Add POSIX link(1) via coreutils (link.js, man, commands list, kernel bin) - Fix JSDoc in verify-runtime-no-incomplete-markers (avoid */ in glob text) - Align posix-conformance-matrix bareOsSyscallOps with getconf (select, umask) - Add verify-holepunch-clone-drift.mjs (opt-in pretest), holepunch-drift-repos.json, originMainHead in sync-holepunch-clones report - Tests: warm /bin cache clear, blind proc stub, protomux pool schema 2, glob cap - Docs: systemctl man, compatibility matrix boot.policy pins, handbook ch.5 vault/proc note, package-bare-os-booter, kernel-extensions, developer-guide ctx - CHANGELOG and bare-os-ctx.d.ts updates for subprocess bridge and mirror mounts
2026-04-04 23:19:17 -04:00
parent 48f973634a
commit 13a06ea3e9
57 changed files with 3152 additions and 754 deletions
@@ -65,6 +65,12 @@ if (process.env.CHECK_DOC_LINKS === '1') {
 }

 console.log('[release-checklist] done')
+console.log(
+  '[release-checklist] Optional: BARE_OS_HOLEPUNCH_DRIFT_CHECK=1 node scripts/verify-holepunch-clone-drift.mjs after populating docs/audit/holepunch-drift-repos.json and git fetch in each clone.'
+)
+console.log(
+  '[release-checklist] Boot policy: confirm extensionSignerPins / kernelExtensionHashPins in boot.policy.example.json match your governance before tagging.'
+)
 console.log(
  '[release-checklist] Word 6 release notes template: bits6 + BARE_OS_KERNEL_FEATURES_STOCK_WORD_REPLICATION_OPERATOR_SURFACE, ctx API + feature-bits doc from compatibility-matrix, seed RPCs + boot.policy v6, OTel otlSchemaVersion 3, auditSchemaVersion 3, NDJSON lifecycle 5 — see docs/reference/feature-roadmap.md Capability word 6 table'
 )
@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 /**
 * Compare local Holepunch org clones (optional) to workspace bundle sources.
- * Writes docs/audit/holepunch-clone-sync-report.json for operators.
+ * Writes docs/audit/holepunch-clone-sync-report.json for operators (includes
+ * origin/main ref when resolvable — run git fetch in clones for meaningful drift).
 *
 * Env: BARE_OS_HOLEPUNCH_CLONES_ROOT — default ~/dev/pearcli/holepunch-repos/holepunchto_repos
 */
@@ -38,6 +39,18 @@ function gitHead(dir) {
  }
 }

+function gitOriginMain(dir) {
+  try {
+    return execSync('git rev-parse origin/main', {
+      cwd: dir,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore']
+    }).trim()
+  } catch {
+    return ''
+  }
+}
+
 function main() {
  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'))
  const entries = Array.isArray(manifest.entries) ? manifest.entries : []
@@ -75,7 +88,8 @@ function main() {
      clonePath: cloneDir,
      cloneExists: exists,
      packageJsonVersion: pkgVersion,
-      gitHead: exists ? gitHead(cloneDir) : ''
+      gitHead: exists ? gitHead(cloneDir) : '',
+      originMainHead: exists ? gitOriginMain(cloneDir) : ''
    })
  }
  const report = {
@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 /**
- * CI: flag vendored IIFE bundles that contain Error throws with incomplete-implementation
- * messages (complements verify-bundle-markers.mjs). Allowlist entries carry rationale.
+ * CI: flag **vendored** IIFE bundles under kernel/lib/bare/bundles for Error throws whose messages
+ * look like incomplete implementations (complements verify-bundle-markers.mjs). Allowlist entries
+ * carry rationale. This is **not** the same gate as verify-runtime-no-incomplete-markers.mjs, which
+ * applies only to first-party kernel + booter sources — see developer-guide/node-to-bare-modules.md.
 *
 * Matches: throw new Error("…"), cb(new Error("…")), emit("error", new Error("…")), etc.
 */
@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+/**
+ * Optional release gate: ensure listed Holepunch clones are not behind origin/main.
+ * No-op unless BARE_OS_HOLEPUNCH_DRIFT_CHECK=1 (keeps default pretest fast and offline).
+ *
+ * Prereq: `git fetch origin main` in each clone so origin/main is meaningful.
+ * Config: docs/audit/holepunch-drift-repos.json → { repos: ["name", ...] }
+ * Clones root: BARE_OS_HOLEPUNCH_CLONES_ROOT (same default as sync-holepunch-clones.mjs)
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import process from 'node:process'
+import { fileURLToPath } from 'node:url'
+import { execSync } from 'node:child_process'
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const configPath = path.join(root, 'docs/audit/holepunch-drift-repos.json')
+
+const defaultClones = path.join(
+  process.env.HOME || '',
+  'dev/pearcli/holepunch-repos/holepunchto_repos'
+)
+const clonesRoot = String(
+  process.env.BARE_OS_HOLEPUNCH_CLONES_ROOT || defaultClones
+).trim()
+
+function gitOk(cmd, cwd) {
+  try {
+    execSync(cmd, {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore']
+    })
+    return true
+  } catch {
+    return false
+  }
+}
+
+function main() {
+  if (process.env.BARE_OS_HOLEPUNCH_DRIFT_CHECK !== '1') {
+    console.log('verify-holepunch-clone-drift: skip (set BARE_OS_HOLEPUNCH_DRIFT_CHECK=1)')
+    return
+  }
+  if (!fs.existsSync(configPath)) {
+    console.error('verify-holepunch-clone-drift: missing', configPath)
+    process.exit(1)
+  }
+  let cfg
+  try {
+    cfg = JSON.parse(fs.readFileSync(configPath, 'utf8'))
+  } catch (e) {
+    console.error('verify-holepunch-clone-drift: parse config failed', e)
+    process.exit(1)
+  }
+  const repos = Array.isArray(cfg.repos) ? cfg.repos.map((r) => String(r).trim()).filter(Boolean) : []
+  if (!repos.length) {
+    console.log('verify-holepunch-clone-drift: repos[] empty — nothing to check')
+    return
+  }
+  let failed = false
+  for (const name of repos) {
+    const dir = path.join(clonesRoot, name)
+    if (!fs.existsSync(dir)) {
+      console.warn(
+        'verify-holepunch-clone-drift: skip missing clone',
+        path.relative(root, dir)
+      )
+      continue
+    }
+    if (!gitOk('git rev-parse --git-dir', dir)) {
+      console.warn('verify-holepunch-clone-drift: skip non-git', name)
+      continue
+    }
+    const hasOriginMain = gitOk('git rev-parse --verify origin/main', dir)
+    if (!hasOriginMain) {
+      console.warn(
+        'verify-holepunch-clone-drift: no origin/main in',
+        name,
+        '(run git fetch origin main)'
+      )
+      continue
+    }
+    const upToDate = gitOk(
+      'git merge-base --is-ancestor origin/main HEAD',
+      dir
+    )
+    if (!upToDate) {
+      console.error(
+        'verify-holepunch-clone-drift: clone is behind origin/main:',
+        name
+      )
+      failed = true
+    }
+  }
+  if (failed) {
+    console.error(
+      'verify-holepunch-clone-drift: FAIL — pull or fetch listed clones, or trim docs/audit/holepunch-drift-repos.json'
+    )
+    process.exit(1)
+  }
+  console.log('verify-holepunch-clone-drift: OK')
+}
+
+main()
@@ -31,7 +31,39 @@ function walkFiles(dir, base) {
  return out
 }

+/** Ensure kernel/init.js equals sorted kernel/lib/boot/*.js + kernel/lib/init/init-main.js (see bundle-kernel-init.mjs). */
+function assertInitJsMatchesBundleRecipe() {
+  const bootDir = path.join(canonical, 'lib', 'boot')
+  const mainPath = path.join(canonical, 'lib', 'init', 'init-main.js')
+  const outPath = path.join(canonical, 'init.js')
+  if (!fs.existsSync(mainPath)) {
+    console.error('verify-kernel-seeder-parity: missing', mainPath)
+    process.exit(1)
+  }
+  const parts = []
+  if (fs.existsSync(bootDir)) {
+    const names = fs
+      .readdirSync(bootDir)
+      .filter((n) => n.endsWith('.js'))
+      .sort()
+    for (const n of names) {
+      parts.push(fs.readFileSync(path.join(bootDir, n), 'utf8').trimEnd())
+    }
+  }
+  const main = fs.readFileSync(mainPath, 'utf8')
+  const expected = (parts.length ? parts.join('\n\n') + '\n\n' : '') + main
+  const actual = fs.readFileSync(outPath, 'utf8')
+  if (actual !== expected) {
+    console.error(
+      'kernel/init.js does not match bundle recipe (lib/boot/*.js + lib/init/init-main.js).',
+      'Run: node scripts/bundle-kernel-init.mjs'
+    )
+    process.exit(1)
+  }
+}
+
 function main() {
+  assertInitJsMatchesBundleRecipe()
  const a = new Set(walkFiles(canonical, canonical))
  const b = new Set(walkFiles(vendored, vendored))
  const onlyA = [...a].filter((x) => !b.has(x)).sort()
@@ -66,6 +98,19 @@ function main() {
    )
    process.exit(1)
  }
+  const required = [
+    'init.js',
+    'lib/init/init-main.js',
+    'lib/bare/manifest.json',
+    'lib/bare/bare-module-manifest.json'
+  ]
+  for (const rel of required) {
+    const pa = path.join(canonical, rel)
+    if (!fs.existsSync(pa)) {
+      console.error('verify-kernel-seeder-parity: required file missing in kernel/:', rel)
+      process.exit(1)
+    }
+  }
  /** Staged /bin scripts must carry the BARE_OS_BIN_API pragma (see coreutils runtime). */
  const badBin = []
  for (const rel of [...a].sort()) {
@@ -1,7 +1,11 @@
 #!/usr/bin/env node
 /**
- * CI: forbid incomplete-implementation markers in hand-authored kernel + booter runtime sources.
- * Excludes vendored bundles, generated kernel/bin, and test harness files.
+ * CI: forbid incomplete-implementation markers in first-party kernel + booter runtime sources only.
+ *
+ * Scanned: kernel/init.js, kernel/lib/init/init-main.js, all kernel/lib/boot/*.js (walk skips bundles),
+ * packages/bare-os-booter/index.js, packages/bare-os-booter/lib (recursive .js).
+ * Not scanned: kernel/lib/bare/bundles (vendored IIFEs — verify-bundle-markers.mjs,
+ * verify-bundle-throws.mjs, docs/audit allowlists). See developer-guide/node-to-bare-modules.md.
 */
 import fs from 'node:fs'
 import path from 'node:path'