diff --git a/.claude/hooks/block-db-writes.sh b/.claude/hooks/block-db-writes.sh new file mode 100755 index 00000000..c7dc779e --- /dev/null +++ b/.claude/hooks/block-db-writes.sh @@ -0,0 +1,71 @@ +#!/bin/sh +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# block-db-writes.sh — Claude Code PreToolUse hook for nextgen-databases. +# +# nextgen-databases is a COORDINATION repo. Per-database code/docs belong in each +# database's own repo (see REGISTRY.adoc). This hook blocks creation of a NEW file +# inside a legacy per-database directory (that is the misplacement we are stopping), +# while still allowing edits to files that already exist during the transition. +# +# Reads the hook payload (JSON) on stdin. Exit 2 = BLOCK (reason on stderr); 0 = ALLOW. + +set -u + +payload="$(cat)" +root="${CLAUDE_PROJECT_DIR:-$(pwd)}" + +# --- extract a leaf value from the JSON payload ------------------------------ +extract() { # $1 = jq path, e.g. .tool_input.file_path + if command -v jq >/dev/null 2>&1; then + printf '%s' "$payload" | jq -r "$1 // empty" 2>/dev/null + else + leaf="${1##*.}" + printf '%s' "$payload" | tr ',{}' '\n\n\n' \ + | sed -n "s/.*\"${leaf}\"[[:space:]]*:[[:space:]]*\"\([^\"]*\)\".*/\1/p" | head -n1 + fi +} + +tool="$(extract .tool_name)" +fp="$(extract .tool_input.file_path)" + +# Only police file-writing tools. +case "$tool" in + Write|Edit|MultiEdit|NotebookEdit) ;; + *) exit 0 ;; +esac + +[ -n "$fp" ] || exit 0 + +# Normalise to a repo-relative path. +rel="$fp" +case "$fp" in + "$root"/*) rel="${fp#"$root"/}" ;; + /*) exit 0 ;; # absolute path outside the project — not ours to police +esac + +# Map a legacy database directory to its destination repo (for a helpful message). +dest="" +case "$rel" in + verisimdb/*) dest="hyperpolymath/verisimdb" ;; + lithoglyph/glyphbase/*) dest="hyperpolymath/glyphbase" ;; + lithoglyph/gql-dt/*) dest="hyperpolymath/gnpl" ;; + lithoglyph/*) dest="hyperpolymath/lithoglyph" ;; + quandledb/*) dest="hyperpolymath/quandledb" ;; + nqc/*) dest="hyperpolymath/nqc" ;; + typeql-experimental/*) dest="hyperpolymath/vcl-ut" ;; + verisim-core/*) dest="hyperpolymath/verisim-core (or fold into verisimdb)" ;; + verisim-modular-experiment/*) dest="" ;; # research-only — allowed for now +esac + +# Block creation of a NEW file in a database directory; allow edits to existing files. +if [ -n "$dest" ] && [ ! -e "$fp" ]; then + printf '%s\n' "BLOCKED: nextgen-databases is a COORDINATION repo — do not add new per-database content here." 1>&2 + printf '%s\n' " New file: $rel" 1>&2 + printf '%s\n' " This belongs in: $dest (see REGISTRY.adoc)" 1>&2 + printf '%s\n' " If this really is coordination content, place it outside the database directories." 1>&2 + exit 2 +fi + +exit 0 diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 00000000..29fa937d --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,15 @@ +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Write|Edit|MultiEdit|NotebookEdit", + "hooks": [ + { + "type": "command", + "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/block-db-writes.sh" + } + ] + } + ] + } +} diff --git a/.github/workflows/placement-guard.yml b/.github/workflows/placement-guard.yml new file mode 100644 index 00000000..ede90a38 --- /dev/null +++ b/.github/workflows/placement-guard.yml @@ -0,0 +1,88 @@ +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# placement-guard.yml — Coordination-repo content placement guard. +# nextgen-databases is a COORDINATION repo: per-database implementation content belongs +# in each database's own repo (see REGISTRY.adoc), not here. This gate FAILS a PR/push +# that ADDS files outside the allowed coordination paths. +name: Placement Guard + +on: + pull_request: + branches: ['**'] + push: + branches: [main, master] + +permissions: + contents: read + +jobs: + placement: + name: Content placement check + runs-on: ubuntu-latest + timeout-minutes: 10 + + steps: + - name: Checkout repository + uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 + with: + fetch-depth: 0 + + - name: Determine added files + id: diff + run: | + set -uo pipefail + if [ "${{ github.event_name }}" = "pull_request" ]; then + git fetch --no-tags origin "${{ github.base_ref }}" || true + BASE="origin/${{ github.base_ref }}" + else + BASE="${{ github.event.before }}" + case "$BASE" in + 0000000000000000000000000000000000000000|"") BASE="$(git rev-parse HEAD~1 2>/dev/null || echo origin/main)" ;; + esac + fi + echo "Comparing against: $BASE" + git diff --name-only --diff-filter=A "$BASE...HEAD" > /tmp/added.txt 2>/dev/null \ + || git diff --name-only --diff-filter=A "$BASE" HEAD > /tmp/added.txt + echo "Added files:"; cat /tmp/added.txt || true + + - name: Check placement + run: | + set -uo pipefail + + # Allowed coordination paths (regex, anchored at repo root). + ALLOW='^(README|EXPLAINME|TOPOLOGY|ROADMAP|TOOLING-STATUS|REGISTRY|CONTRIBUTING|CODE_OF_CONDUCT|SECURITY|MAINTAINERS|NOTICE|LICENSE|PROOF-NEEDS|TEST-NEEDS|QUICKSTART-[A-Z]+|0-AI-MANIFEST|CLAUDE|AGENTS|llm-warmup-[a-z]+)\.[A-Za-z0-9]+$' + ALLOW="$ALLOW"'|^(docs|tests|scripts|\.github|\.claude|\.machine_readable|\.bot_directives|\.well-known|\.hypatia|LICENSES|contractiles)/' + ALLOW="$ALLOW"'|^(flake\.nix|guix\.scm|Justfile|contractile\.just|stapeln\.toml|opsm\.toml|setup\.sh|\.gitignore|\.gitattributes|\.editorconfig|\.gitlab-ci\.yml|\.nojekyll)$' + + # Legacy per-database dirs (grandfathered: warn, do not fail — being extracted). + GRANDFATHER='^(verisimdb|lithoglyph|quandledb|nqc|typeql-experimental|verisim-core|verisim-modular-experiment)/' + + FAIL=0 + while IFS= read -r f; do + [ -z "$f" ] && continue + if echo "$f" | grep -Eq "$ALLOW"; then + continue + fi + if echo "$f" | grep -Eq "$GRANDFATHER"; then + echo "::warning file=${f}::Added inside a legacy database directory. This content should live in its own repo (see REGISTRY.adoc); these directories are being extracted." + continue + fi + echo "::error file=${f}::Misplaced content. nextgen-databases is a coordination repo — this belongs in a database/language repo. See REGISTRY.adoc." + FAIL=1 + done < /tmp/added.txt + + { + echo "## Placement Guard" + echo "" + if [ "$FAIL" -eq 0 ]; then + echo ":white_check_mark: No misplaced new content detected." + else + echo ":x: New files were added outside the allowed coordination paths." + echo "" + echo "\`nextgen-databases\` is a **coordination repo**. Per-database code, schemas," + echo "docs, and query languages belong in their own repos — see \`REGISTRY.adoc\`." + fi + } >> "$GITHUB_STEP_SUMMARY" + + exit $FAIL diff --git a/.machine_readable/6a2/AGENTIC.a2ml b/.machine_readable/6a2/AGENTIC.a2ml index 4a989762..77b37b0d 100644 --- a/.machine_readable/6a2/AGENTIC.a2ml +++ b/.machine_readable/6a2/AGENTIC.a2ml @@ -22,3 +22,6 @@ can-create-files = true # - Never use banned languages (TypeScript, Python, Go, etc.) # - Never place state files in repository root (must be in .machine_readable/) # - Never use AGPL license (use PMPL-1.0-or-later) +# - Never add per-database implementation content (source, schemas, migrations, +# per-database docs, query-language implementations) to this COORDINATION repo; +# it belongs in that database's own repo (see REGISTRY.adoc) diff --git a/0-AI-MANIFEST.a2ml b/0-AI-MANIFEST.a2ml index 136e4230..24f93473 100644 --- a/0-AI-MANIFEST.a2ml +++ b/0-AI-MANIFEST.a2ml @@ -40,37 +40,43 @@ Bot-specific instructions for: ## CORE INVARIANTS -1. **No SCM duplication** - Root must NOT contain .machine_readable/6a2/STATE.a2ml, .machine_readable/6a2/META.a2ml, etc. -2. **Single source of truth** - `.machine_readable/` is authoritative -3. **No stale metadata** - If root SCMs exist, they are OUT OF DATE -4. **License consistency** - All code PMPL-1.0-or-later unless platform requires MPL-2.0 -5. **Author attribution** - Always "Jonathan D.A. Jewell " +1. **Coordination only — no implementation** - This repo coordinates a portfolio of + databases. Per-database source, schemas, migrations, query-language implementations, + and per-database docs MUST live in that database's own repo (see `REGISTRY.adoc`). + Adding per-database implementation content here is an ERROR. +2. **No SCM duplication** - Root must NOT contain .machine_readable/6a2/STATE.a2ml, .machine_readable/6a2/META.a2ml, etc. +3. **Single source of truth** - `.machine_readable/` is authoritative +4. **No stale metadata** - If root SCMs exist, they are OUT OF DATE +5. **License consistency** - All code PMPL-1.0-or-later unless platform requires MPL-2.0 +6. **Author attribution** - Always "Jonathan D.A. Jewell " ## REPOSITORY STRUCTURE - - -This repo contains: +This is a **coordination repo**. Intended (target) contents: ``` nextgen-databases/ -├── 0-AI-MANIFEST.a2ml # THIS FILE (start here) -├── README.adoc # Database portfolio overview -├── .machine_readable/ # SCM files (6 files) -│ ├── .machine_readable/6a2/STATE.a2ml -│ ├── .machine_readable/6a2/META.a2ml -│ ├── .machine_readable/6a2/ECOSYSTEM.a2ml -│ ├── .machine_readable/6a2/AGENTIC.a2ml -│ ├── .machine_readable/6a2/NEUROSYM.a2ml -│ └── .machine_readable/6a2/PLAYBOOK.a2ml -├── .bot_directives/ # Bot instructions -└── contractiles/ # Contractiles +├── 0-AI-MANIFEST.a2ml # THIS FILE (start here) +├── CLAUDE.md / AGENTS.md # Agent guardrails (coordination-only) +├── REGISTRY.adoc # Authoritative map: database/language -> its own repo +├── README.adoc / EXPLAINME.adoc / TOPOLOGY.md / ROADMAP.adoc # Portfolio docs +├── tests/ # CROSS-database integration tests only +├── docs/ # Coordination docs (incl. migration runbooks) +├── .machine_readable/ # Canonical SCM metadata +├── .github/ .well-known/ LICENSES/ # Governance, protocols, licenses +└── flake.nix / Justfile / stapeln.toml / opsm.toml # Shared env & orchestration ``` +LEGACY (being extracted to their own repos — see +`docs/migration/RESITE-DATABASES-TO-OWN-REPOS.adoc` and `REGISTRY.adoc`): +`verisimdb/`, `lithoglyph/`, `quandledb/`, `nqc/`, `typeql-experimental/`, +`verisim-core/`, `verisim-modular-experiment/`. **Do NOT add new content to these.** + ## KEY RELATIONSHIPS -This is a **parent/tracking repository** — no implementation code. -Satellite repos: quandledb, verisimdb, lithoglyph, glyphbase +This is a **parent/tracking (coordination) repository** — no implementation code. +Satellite repos (authoritative list in `REGISTRY.adoc`): verisimdb, lithoglyph, +glyphbase, quandledb, gnpl, vcl-ut, krl, nqc. ## SESSION STARTUP CHECKLIST diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..a9e4a845 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,13 @@ + +# AGENTS.md + +This is the **nextgen-databases coordination repo** — it does **not** hold database +implementations. Per-database code, schemas, docs, and query languages each live in +their **own repo** (see `REGISTRY.adoc`). + +**Do not add per-database implementation content here.** If you are about to add database +source, schemas, migrations, a query-language implementation, or per-database docs, it +belongs in that database's own repo — not here. + +Full guidance: **`CLAUDE.md`** (same directory). Universal AI entry point: +**`0-AI-MANIFEST.a2ml`**. Authoritative repo map: **`REGISTRY.adoc`**. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..b7ad6028 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,52 @@ + +# CLAUDE.md — nextgen-databases (COORDINATION REPO) + +## CRITICAL: This is a coordination repo. No database implementation lives here. (Read First) + +`nextgen-databases` **coordinates** a portfolio of database projects. It does **not** +hold their implementations. Each database and each query language has its **own repo** +(see `REGISTRY.adoc`). + +**Before you create or edit a file here, STOP and ask: is this coordination, or is it +about one specific database?** If it is about one database, it belongs in that database's +own repo. + +### NEVER (in this repo) + +1. **NEVER** add per-database source code, schemas, migrations, storage engines, or + query-language implementations here. +2. **NEVER** add per-database design docs, whitepapers, benchmarks, or datasets here. +3. **NEVER** create a new top-level directory for a database or language — create or + extend its own repo instead (`REGISTRY.adoc`). +4. **NEVER** "just put it here for now." That is exactly the drift this repo is + recovering from. + +### ALWAYS (what DOES belong here) + +1. **Portfolio coordination**: `README.adoc`, `TOPOLOGY.md`, `ROADMAP.adoc`, + `EXPLAINME.adoc`. +2. **The registry** of databases/languages → their repos: `REGISTRY.adoc`. +3. **Cross-database** integration tests (`tests/`) and shared infrastructure + (`flake.nix`, `Justfile`, `stapeln.toml`, `opsm.toml`). +4. **Governance & metadata**: `.github/`, `.machine_readable/`, `.well-known/`, + `LICENSES/`, `CONTRIBUTING.md`, `SECURITY.md`, `0-AI-MANIFEST.a2ml`. + +### Where database content goes + +See **`REGISTRY.adoc`** for the authoritative map. Examples: VeriSimDB → +`hyperpolymath/verisimdb`; Lithoglyph → `hyperpolymath/lithoglyph`; Glyphbase → +`hyperpolymath/glyphbase`; the Glyph query language → `hyperpolymath/gnpl`; NQC → +`hyperpolymath/nqc`. + +### Transitional note + +The directories `verisimdb/`, `lithoglyph/`, `quandledb/`, `nqc/`, +`typeql-experimental/`, `verisim-core/`, and `verisim-modular-experiment/` are **legacy +content being extracted** to their own repos — see +`docs/migration/RESITE-DATABASES-TO-OWN-REPOS.adoc`. **Do not grow them.** A CI guard +(`.github/workflows/placement-guard.yml`) and a local pre-write hook +(`.claude/hooks/block-db-writes.sh`) enforce this: creating a *new* file inside those +directories is blocked, because it belongs in that database's own repo. + +--- +*Also read `0-AI-MANIFEST.a2ml` (universal AI entry point) and `AGENTS.md`.* diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bd6f5a5e..7ee55411 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,35 +16,34 @@ just test # Run test suite ``` ### Repository Structure + +`nextgen-databases` is a **coordination repo** — it does not hold database +implementations. Each database and query language has its own repo (see `REGISTRY.adoc`). + ``` nextgen-databases/ -├── src/ # Source code (Perimeter 1-2) -├── lib/ # Library code (Perimeter 1-2) -├── extensions/ # Extensions (Perimeter 2) -├── plugins/ # Plugins (Perimeter 2) -├── tools/ # Tooling (Perimeter 2) -├── docs/ # Documentation (Perimeter 3) -│ ├── architecture/ # ADRs, specs (Perimeter 2) -│ └── proposals/ # RFCs (Perimeter 3) -├── examples/ # Examples (Perimeter 3) -├── spec/ # Spec tests (Perimeter 3) -├── tests/ # Test suite (Perimeter 2-3) -├── .well-known/ # Protocol files (Perimeter 1-3) -├── .github/ # GitHub config (Perimeter 1) -│ ├── ISSUE_TEMPLATE/ -│ └── workflows/ -├── CHANGELOG.md -├── CODE_OF_CONDUCT.md -├── CONTRIBUTING.md # This file -├── GOVERNANCE.md -├── LICENSE -├── MAINTAINERS.md -├── README.adoc -├── SECURITY.md -├── flake.nix # Nix flake (Perimeter 1) -└── Justfile # Task runner (Perimeter 1) +├── README.adoc / EXPLAINME.adoc / TOPOLOGY.md / ROADMAP.adoc # Portfolio docs +├── REGISTRY.adoc # Authoritative map: database/language -> its own repo +├── CLAUDE.md / AGENTS.md / 0-AI-MANIFEST.a2ml # Agent guardrails +├── docs/ # Coordination docs (incl. migration runbooks) +├── tests/ # CROSS-database integration tests only +├── .machine_readable/ # Canonical SCM metadata +├── .github/ # CI/CD, issue templates, governance +├── .well-known/ LICENSES/ +└── flake.nix / Justfile / stapeln.toml / opsm.toml # Shared env & orchestration ``` +#### What belongs here vs. in a database repo + +- ✅ **Here**: portfolio docs, the registry, cross-database integration tests, shared + infrastructure/orchestration, governance and machine-readable metadata. +- ❌ **Not here — use the database's own repo**: per-database source code, schemas, + migrations, storage engines, query-language implementations, per-database design docs, + whitepapers, benchmarks, and datasets. See `REGISTRY.adoc` for the destination repo. + +A CI guard (`.github/workflows/placement-guard.yml`) and a local pre-write hook +(`.claude/hooks/block-db-writes.sh`) enforce this. + --- ## How to Contribute diff --git a/REGISTRY.adoc b/REGISTRY.adoc new file mode 100644 index 00000000..88fea24a --- /dev/null +++ b/REGISTRY.adoc @@ -0,0 +1,58 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) 2026 Jonathan D.A. Jewell += Database & Query-Language Registry — where each thing lives +:toc: + +This is the *authoritative map* of the Next-Gen Databases portfolio to the standalone +repositories that own each database and each query language. `nextgen-databases` is a +*coordination repo*: implementation content belongs in the repos below, *not* here. + +Registered in the estate clade registry: https://github.com/hyperpolymath/gv-clade-index +(see `.machine_readable/CLADE.a2ml`). + +== Databases + +[cols="1,2,1,2",options=header] +|=== +| Database | Repository | Status | Query language (repo) +| VeriSimDB (cross-modal consistency) | hyperpolymath/verisimdb | exists | VCL — in-repo (`verisimdb/src/vcl/`) +| Lithoglyph (narrative-first) | hyperpolymath/lithoglyph | to create | GQL/GNPL — hyperpolymath/gnpl +| Glyphbase (Lithoglyph web UI) | hyperpolymath/glyphbase | to create | — +| QuandleDB (knot-theory) | hyperpolymath/quandledb | exists (stub) | KRL — hyperpolymath/krl +|=== + +== Query languages + +[cols="1,2,1,2",options=header] +|=== +| Language | Repository | Status | Notes +| VCL (Verified Consonance Language) | (in hyperpolymath/verisimdb) | exists | Production; stays nested in verisimdb +| VCL-UT (usage-tracked extension) | hyperpolymath/vcl-ut | exists | Maps to `typeql-experimental/`; standalone-vs-fold DECISION pending +| GNPL / GQL (Glyph query language) | hyperpolymath/gnpl | to create | From `lithoglyph/gql-dt/` + `lithoglyph/core-factor/gql/` +| KRL (Knot query language) | hyperpolymath/krl | exists | Implementation not present in this monorepo +| NQC (Nested Query Calculus) | hyperpolymath/nqc | to create | Already standalone in `nqc/` (Gleam) +|=== + +== Undecided / research (see runbook) + +[cols="1,2",options=header] +|=== +| Component | Disposition +| `verisim-core/` (slim Julia identity-core) | Own repo `verisim-core` *or* fold into verisimdb — DECISION +| `verisim-modular-experiment/` (research-experiment) | Move to a research repo *or* keep as a documented exception — DECISION +|=== + +== What belongs in *this* (coordination) repo + +* Portfolio docs: `README.adoc`, `TOPOLOGY.md`, `ROADMAP.adoc`, `EXPLAINME.adoc` +* This registry (`REGISTRY.adoc`) +* Cross-database integration tests (`tests/`) +* Shared infra & environment (`flake.nix`, `guix.scm`, `Justfile`, `stapeln.toml`, `opsm.toml`) +* Governance & metadata (`.github/`, `.machine_readable/`, `.well-known/`, `LICENSES/`, + `CONTRIBUTING.md`, `SECURITY.md`, `0-AI-MANIFEST.a2ml`) + +[NOTE] +==== +The per-database directories currently in this repo are *legacy* and are being extracted +— see `docs/migration/RESITE-DATABASES-TO-OWN-REPOS.adoc`. Do not add new content to them. +==== diff --git a/docs/migration/RESITE-DATABASES-TO-OWN-REPOS.adoc b/docs/migration/RESITE-DATABASES-TO-OWN-REPOS.adoc new file mode 100644 index 00000000..2a6772ac --- /dev/null +++ b/docs/migration/RESITE-DATABASES-TO-OWN-REPOS.adoc @@ -0,0 +1,104 @@ +// SPDX-License-Identifier: MPL-2.0 +// Copyright (c) 2026 Jonathan D.A. Jewell += Resite databases to their own repos — Migration Runbook +:toc: left + +Status: PLAN (prevention landed; extraction pending approval + GitHub scope). +Baseline: main @ 1913dde (branch: claude/ecstatic-turing-u5649q). + +== Why +`nextgen-databases` is a coordination repo (see `EXPLAINME.adoc`, `0-AI-MANIFEST.a2ml`), +but it physically contains full database implementations (~16,000 files). LLMs keep +adding per-database content here because the code lives here and there was no top-level +guardrail. This runbook extracts each database / query language to its own repo so the +coordination repo becomes thin, while the prevention layer (placement guard + pre-write +hook + agent instructions) keeps it that way. + +== Mapping (source -> destination) +Authoritative table: `REGISTRY.adoc`. Summary: + +[cols="2,2,1,2",options=header] +|=== +| Source | Destination repo | Exists? | Action +| `verisimdb/` (incl. `src/vcl/`) | hyperpolymath/verisimdb | yes | extract; VCL stays nested +| `lithoglyph/` (minus glyphbase, gql) | hyperpolymath/lithoglyph | create | extract slimmed parent +| `lithoglyph/glyphbase/` | hyperpolymath/glyphbase | create | un-nest +| `lithoglyph/gql-dt/` (+ `core-factor/gql/`) | hyperpolymath/gnpl | create | un-nest (confirm name) +| `nqc/` | hyperpolymath/nqc | create | extract as-is (already standalone) +| `typeql-experimental/` | hyperpolymath/vcl-ut | yes | DECISION: standalone vs fold into verisimdb +| `quandledb/` | hyperpolymath/quandledb | yes (stub) | extract stub +| (KRL) | hyperpolymath/krl | yes | nothing here to move +| `verisim-core/` | verisim-core OR verisimdb | ? | DECISION +| `verisim-modular-experiment/` | research repo OR keep as exception | ? | DECISION +|=== + +== Open decisions (resolve before extracting the affected item) +. `typeql-experimental` -> standalone `vcl-ut`, or fold into `verisimdb`? +. `verisim-core` -> own repo, or fold into `verisimdb`? +. `verisim-modular-experiment` (research) -> research repo, or documented exception kept here? +. `gnpl` -> confirm name + that GQL/GQL-DT should be un-nested now (deep storage coupling). +. New repos visibility (public/private); existing repos empty vs already populated. +. Thinned repo: reference extracted repos via git submodules, or via `REGISTRY.adoc` only? + +== Strategy +. *One repo at a time*, never big-bang. Start with the cleanest/smallest to prove the + pattern: `quandledb` (stub) or `nqc` (already standalone). +. *Un-nest languages/UIs first* where applicable (`glyphbase`, `gql-dt` -> `gnpl`) before + slimming the parent database. +. *Preserve history* per path with `git filter-repo` (preferred) or `git subtree split`. +. *Register* each new repo in https://github.com/hyperpolymath/gv-clade-index. +. *Replace, then thin*: only after the destination repo is verified, remove the directory + here and add/confirm its `REGISTRY.adoc` entry (and submodule, if chosen). +. *Shrink the guard*: remove each extracted dir from the placement-guard grandfather list + and from the pre-write hook map as it leaves. + +== Procedure (per database/language) +Helper: `scripts/resite/extract-subdir.sh` wraps the history-preserving steps (it does +not push). + +[source,sh] +---- +# 0. Pre-req: git-filter-repo installed; push rights to the destination repo; this +# session's GitHub scope includes the destination repo. + +# 1. Fresh clone of the coordination repo (never operate on your working clone). +git clone --no-local . /tmp/extract && cd /tmp/extract + +# 2. Reduce history to the subdir, rewriting it to repo root (history preserved). +git filter-repo --path verisimdb/ --path-rename verisimdb/: # example: verisimdb + +# 3. Point at the destination and push (empty repo shown; else coordinate a merge). +git remote add dest https://github.com/hyperpolymath/verisimdb.git +git push dest HEAD:main + +# 4. Verify the destination builds/tests and has SCM metadata + 0-AI-MANIFEST.a2ml. + +# 5. Back in the coordination repo: remove the extracted directory and thin. +git rm -r verisimdb +# git submodule add https://github.com/hyperpolymath/verisimdb.git verisimdb # optional +# Update REGISTRY.adoc, placement-guard grandfather list, and block-db-writes.sh map. +git commit -m "chore(resite): extract verisimdb to its own repo; thin coordination repo" +---- + +For *un-nesting* (e.g. glyphbase out of lithoglyph), filter the nested path first: +[source,sh] +---- +git filter-repo --path lithoglyph/glyphbase/ --path-rename lithoglyph/glyphbase/: +---- +then separately extract the slimmed `lithoglyph/` after removing `glyphbase/` and the +GQL paths. + +== Blockers +. *GitHub scope*: this session is limited to `hyperpolymath/nextgen-databases`; extraction + needs scope expanded to each destination repo. +. *Repos to create*: `lithoglyph`, `glyphbase`, `gnpl`, `nqc` do not exist yet. +. *`git-filter-repo`* availability in the execution environment. +. The *open decisions* above for `vcl-ut`, `verisim-core`, `verisim-modular-experiment`. + +== Next concrete steps +. Resolve the open decisions (update `REGISTRY.adoc`). +. Approve scope expansion + create the new repos (with chosen visibility). +. Dry-run extraction on the smallest target (`quandledb` or `nqc`) and verify before + pushing. +. Proceed one repo at a time, thinning the coordination repo and shrinking the guard as + you go. diff --git a/scripts/resite/extract-subdir.sh b/scripts/resite/extract-subdir.sh new file mode 100755 index 00000000..6ad2f855 --- /dev/null +++ b/scripts/resite/extract-subdir.sh @@ -0,0 +1,55 @@ +#!/bin/sh +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# extract-subdir.sh — history-preserving extraction of a subdirectory into a new repo. +# Part of the resite runbook: docs/migration/RESITE-DATABASES-TO-OWN-REPOS.adoc +# +# This DOES NOT push and DOES NOT modify your working clone. It produces a rewritten +# clone in a temp directory for review. +# +# Usage: +# scripts/resite/extract-subdir.sh [dest-git-url] +# Example: +# scripts/resite/extract-subdir.sh nqc/ https://github.com/hyperpolymath/nqc.git +# +# Requires: git, git-filter-repo (https://github.com/newren/git-filter-repo). + +set -eu + +SUBDIR="${1:-}" +DEST_URL="${2:-}" + +if [ -z "$SUBDIR" ]; then + echo "usage: $0 [dest-git-url]" 1>&2 + exit 64 +fi + +# Normalise trailing slash. +case "$SUBDIR" in */) ;; *) SUBDIR="$SUBDIR/" ;; esac + +if ! git filter-repo --help >/dev/null 2>&1; then + echo "error: git-filter-repo is required." 1>&2 + echo " install: https://github.com/newren/git-filter-repo" 1>&2 + exit 69 +fi + +SRC_ROOT="$(git rev-parse --show-toplevel)" +WORK="$(mktemp -d)/extract" + +echo ">> Cloning coordination repo into $WORK (local history copy)" +git clone --no-local "$SRC_ROOT" "$WORK" +cd "$WORK" + +echo ">> Rewriting history to '$SUBDIR' (moved to repo root; history preserved)" +git filter-repo --path "$SUBDIR" --path-rename "$SUBDIR:" + +echo ">> Done. Rewritten repo is at: $WORK" +echo " Review it, then to publish:" +if [ -n "$DEST_URL" ]; then + echo " cd $WORK && git remote add dest $DEST_URL && git push dest HEAD:main" +else + echo " cd $WORK && git remote add dest && git push dest HEAD:main" +fi +echo ">> NOTE: nothing was pushed. Removing '$SUBDIR' from the coordination repo is a" +echo " separate, manual step (see the runbook)."