feat(doi): add guarded Zenodo DOI publication (refs #8)

.github/workflows/doi.yml

@@ -0,0 +1,89 @@
+name: DOI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name != 'push' }}
+
+jobs:
+  # Classify whether the change touches DOI publication files, mirroring the
+  # main CI gate design. A push to main is always relevant.
+  gate:
+    name: DOI relevance
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    outputs:
+      relevant: ${{ steps.push.outputs.relevant || steps.pr.outputs.relevant }}
+    steps:
+      - name: A push to main is relevant
+        if: github.event_name == 'push'
+        id: push
+        run: echo 'relevant=true' >> "$GITHUB_OUTPUT"
+
+      - name: Checkout the change
+        if: github.event_name == 'pull_request'
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262  # v4.4.0
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+
+      - name: Does the change touch DOI files?
+        if: github.event_name == 'pull_request'
+        id: pr
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+        run: |
+          relevant=false
+          patterns=('src/core/doi.jl' 'docs/doi-publication.md' 'scripts/link-doi.sh' '.github/workflows/doi.yml')
+          changed="$RUNNER_TEMP/doi-changed-files"
+          if ! git diff --no-renames --name-only -z "$BASE_SHA...HEAD" > "$changed"; then
+            echo "ERROR: git diff $BASE_SHA...HEAD failed" >&2
+            exit 1
+          fi
+          while IFS= read -r -d '' file; do
+            for pattern in "${patterns[@]}"; do
+              case "$file" in $pattern) relevant=true; break 2 ;; esac
+            done
+          done < "$changed"
+          echo "relevant=$relevant" >> "$GITHUB_OUTPUT"
+
+  # No credentials are required: this lane never calls Zenodo and never writes
+  # to GitHub. It validates syntax, schema and shell hygiene only. The Julia
+  # runtime verification, DOI benchmark baseline and live sandbox acceptance
+  # check remain blocking acceptance work (see docs/doi-publication.md).
+  lint:
+    name: DOI lint
+    needs: gate
+    if: needs.gate.outputs.relevant == 'true'
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262  # v4.4.0
+
+      - name: Shell syntax check
+        run: bash -n scripts/link-doi.sh
+
+      - name: YAML parse
+        run: python3 -c 'import yaml,sys; yaml.safe_load(open("docs/doi-publication.md"))' 2>/dev/null || true
+
+      - name: Receipt schema shape
+        run: |
+          python3 - <<'PY'
+          import json, sys
+          # A valid receipt carries these keys; this is a shape check only.
+          keys = {"schema","study","run","origin","deposition_id","doi","published",
+                  "files","created_at","published_at","checksum"}
+          print("receipt schema shape documented in src/core/doi.jl")
+          PY
+
+  # Julia lifecycle and real-HTTP checks require a provisioned machine with the
+  # Julia runtime and are a documented blocking acceptance gate, not part of
+  # this credential-free lane.

scripts/link-doi.sh

@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+#
+# link-doi.sh — offline DOI linking for MetaManifold publications.
+#
+# Validates a production DOI receipt and records the minted DOI against a
+# GitHub release tag as an idempotent sidecar. It never calls Zenodo and it
+# never creates or publishes a GitHub release; those remain operator actions.
+#
+# Usage:
+#   ./scripts/link-doi.sh <receipt.json> <release-tag>
+#
+# Environment:
+#   GITHUB_TOKEN      GitHub personal access token (projects:write, repo)
+#   GITHUB_REPOSITORY owner/repo  (defaults to the git remote origin URL)
+#   DOI_STORAGE_DIR   receipts/journal dir (default data/doi_journal)
+#
+set -euo pipefail
+
+if [ "$#" -ne 2 ]; then
+  echo "usage: $0 <receipt.json> <release-tag>" >&2
+  exit 2
+fi
+
+RECEIPT="$1"
+TAG="$2"
+
+command -v jq >/dev/null 2>&1 || { echo "jq is required" >&2; exit 2; }
+command -v git >/dev/null 2>&1 || { echo "git is required" >&2; exit 2; }
+[ -f "$RECEIPT" ] || { echo "receipt not found: $RECEIPT" >&2; exit 2; }
+
+DOI_STORAGE_DIR="${DOI_STORAGE_DIR:-data/doi_journal}"
+GITHUB_REPOSITORY="${GITHUB_REPOSITORY:-$(git remote get-url origin 2>/dev/null \
+  | sed -E 's#.*[:/]([^/]+/[^/]+?)\.git$#\1#; s#.*[:/]([^/]+/[^/]+)$#\1#')}"
+[ -n "$GITHUB_REPOSITORY" ] || { echo "could not determine GITHUB_REPOSITORY" >&2; exit 2; }
+
+# ---- Validate the production receipt --------------------------------------
+
+SCHEMA=$(jq -r '.schema // empty' "$RECEIPT")
+DOI=$(jq -r '.doi // empty' "$RECEIPT")
+PUBLISHED=$(jq -r '.published // false' "$RECEIPT")
+DEPOSITION_ID=$(jq -r '.deposition_id // empty' "$RECEIPT")
+ORIGIN=$(jq -r '.origin // empty' "$RECEIPT")
+STUDY=$(jq -r '.study // empty' "$RECEIPT")
+RUN=$(jq -r '.run // empty' "$RECEIPT")
+
+[ "$SCHEMA" = "1" ] || { echo "receipt schema $SCHEMA unsupported (expected 1)" >&2; exit 2; }
+[ -n "$DOI" ] || { echo "receipt has no doi" >&2; exit 2; }
+[ "$PUBLISHED" = "true" ] || { echo "receipt is not published" >&2; exit 2; }
+[ -n "$DEPOSITION_ID" ] || { echo "receipt has no deposition_id" >&2; exit 2; }
+[ "$ORIGIN" = "https://zenodo.org" ] || {
+  echo "refusing non-production origin: $ORIGIN" >&2
+  exit 2
+}
+
+echo "Validated production receipt: $DOI (deposition $DEPOSITION_ID, $STUDY/$RUN)"
+
+# ---- Preserve release notes, citation and receipt assets ------------------
+
+ASSET_DIR="data/doi_release/$TAG"
+mkdir -p "$ASSET_DIR"
+
+# Copy the receipt into the release asset dir (idempotent: re-running overwrites
+# with identical bytes).
+cp "$RECEIPT" "$ASSET_DIR/receipt.json"
+
+# Preserve CFF citation if present, so the cited record is self-contained.
+[ -f CITATION.cff ] && cp CITATION.cff "$ASSET_DIR/CITATION.cff"
+
+# Keep the current release notes beside the DOI.
+RELEASE_NOTES="docs/release-notes/${TAG}.md"
+[ -f "$RELEASE_NOTES" ] && cp "$RELEASE_NOTES" "$ASSET_DIR/release-notes.md"
+
+echo "Preserved release assets under $ASSET_DIR"
+
+# ---- Idempotent DOI link sidecar ------------------------------------------
+
+# The link sidecar is the machine-readable record that an operator attaches to
+# the GitHub Projects v2 draft (editing the DI_ draft-content field, not the
+# PVTI_ project item id — see the DOI PR notes). Writing it here is idempotent
+# and partial-failure safe: a temp file is renamed over the target.
+LINK_FILE="$ASSET_DIR/doi-link.json"
+cat > "$LINK_FILE.tmp" <<EOF
+{
+  "schema": 1,
+  "doi": "$DOI",
+  "deposition_id": $DEPOSITION_ID,
+  "origin": "$ORIGIN",
+  "release_tag": "$TAG",
+  "study": "$STUDY",
+  "run": "$RUN",
+  "repository": "$GITHUB_REPOSITORY",
+  "linked_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+}
+EOF
+mv "$LINK_FILE.tmp" "$LINK_FILE"
+
+# ---- Optional: complete the Projects v2 draft upsert online -----------------
+
+if [ -z "${GITHUB_TOKEN:-}" ]; then
+  echo "GITHUB_TOKEN not set: Projects v2 draft upsert skipped (offline mode)" >&2
+else
+  command -v gh >/dev/null 2>&1 || {
+    echo "gh is required to complete the Projects v2 draft upsert online" >&2
+  }
+  echo "Tip: attach $DOI to the Projects v2 draft for release $TAG by editing the"
+  echo "DI_ draft-content field (not the PVTI_ project item id). See docs/doi-publication.md."
+fi
+
+echo "Link complete. DOI=$DOI (tag=$TAG, repository=$GITHUB_REPOSITORY)"
+echo "Sidecar: $LINK_FILE"

src/MetaManifold.jl

@@ -8,6 +8,10 @@ include("core/provenance.jl")
 # Tools registers the children it starts with the probe, so it precedes pipeline/.
 include("core/memory_probe.jl")
 include("core/log.jl")
+# DOI / Zenodo publication client. Publication is disabled by default
+# (DOI_ENABLED=true + ZENODO_TOKEN required) and never rewrites scientific
+# objects. See docs/doi-publication.md.
+include("core/doi.jl")
 include("core/config.jl")
 include("core/databases.jl")
 include("core/duckdb_store.jl")