oaktree-sapling 0.0.1

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "oaktree-sapling",
+  "version": "0.0.1",
+  "description": "White-label journal engine: MyST + GitHub + Zenodo. All platform logic, referenced by version.",
+  "author": "paolo marzolo",
+  "license": "BSD-3-Clause",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pollomarzo/whitelabel.git"
+  },
+  "type": "module",
+  "bin": {
+    "oak": "dist/cli.cjs"
+  },
+  "scripts": {
+    "test": "npm run bundle && vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "bundle": "esbuild src/cli.ts --bundle --platform=node --format=cjs --minify-whitespace --outfile=dist/cli.cjs",
+    "build:fixture": "node scripts/build-fixture.mjs",
+    "docs": "cd docs && npx -y mystmd@1.10.1 start",
+    "docs:build": "cd docs && npx -y mystmd@1.10.1 build --html --strict",
+    "prepack": "npm run typecheck && npm run bundle"
+  },
+  "files": [
+    "dist/cli.cjs",
+    "templates/",
+    "!templates/*/README.md",
+    "ci/",
+    "plugins/",
+    "paper-base.yml",
+    "typst.version"
+  ],
+  "dependencies": {
+    "@curvenote/check-definitions": "^0.16.5",
+    "@curvenote/check-implementations": "^0.16.5",
+    "adm-zip": "^0.5.18",
+    "myst-cli": "^1.10.1",
+    "yaml": "^2.6.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/adm-zip": "^0.5.8",
+    "@types/node": "^22.0.0",
+    "esbuild": "^0.28.1",
+    "js-yaml": "^4.1.0",
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.10"
+  }
+}

package/paper-base.yml

@@ -0,0 +1,29 @@
+version: 1
+
+# Engine-owned base config every paper extends (design §5). Carries ZERO
+# journal-specific bytes — brand, venue, funding, license live in INSTANCE-CONFIG
+# editions/brand.
+#
+# The COMPLETE typst export lives here, not split across paper-base + edition ([R52]):
+# myst merges `exports` by `id`, whole-entry, base-wins with NO field merge, so a
+# skeleton here + `articles:` in the edition would race and drop one set of fields. So
+# the canonical single-article export (index.md, the n=1 default) is declared whole here;
+# editions declare NO exports. It carries no `template:` — compose() injects the
+# engine-pinned zip URL (finding 2 / [R5]) so the template rides the engine tag. A
+# multi-article paper overrides this whole entry in its own myst.yml (own wins by id).
+project:
+  # Fixed thumbnail location, consumed by the gallery plugin.
+  thumbnail: thumbnails/thumbnail.png
+  exports:
+  - format: typst
+    id: typst-pdf
+    articles:
+    - file: index.md
+      level: 0
+  downloads:
+  - id: typst-pdf
+    title: PDF export
+
+site:
+  options:
+    hide_toc: true

package/plugins/gallery.mjs

@@ -0,0 +1,224 @@
+/**
+ * gallery.mjs — the journal site's `paper-cards` directive (design §5; [S2]).
+ *
+ * A port of `impact-scholars.github.io/plugins/paper-gallery.mjs`, re-pointed from
+ * `papers.txt` + a hardcoded org constant to the **registry** (`registry/papers.yml`,
+ * design §9). Every URL is derived from a registry entry's `location` — never from an org
+ * constant — so the same plugin serves any tenant.
+ *
+ * This file is ENGINE-owned but is NOT engine TypeScript: myst consumes it at runtime by
+ * tag-pinned raw URL (`project.plugins:` accepts remote `.mjs`, myst-cli `config.ts:415-419`),
+ * so it never enters `dist/cli.cjs` and `myst.ts` stays the only importer of myst-cli.
+ *
+ * WHY IT MUST STAY DEPENDENCY-LIGHT: myst downloads a remote plugin into
+ * `<project>/_build/cache/config-item-<hash>.mjs` and imports it from there, so every bare
+ * import must resolve from the SITE repo's own `node_modules` — the mystmd install (an npx
+ * cache) is not on that resolution path. `js-yaml` is therefore declared in the site
+ * scaffold's `package.json` and installed by the site workflow. Add nothing else here
+ * without adding it there too.
+ *
+ * FAILURE IS HARD, ON PURPOSE. A registry entry whose `myst.yml` will not fetch is a broken
+ * registry: it must be fixed, not papered over. A failed build is not an outage — Pages keeps
+ * serving the last successful deploy, so the live journal stays exactly as it was until the
+ * entry is corrected. Degrading would publish a visibly broken card to readers and bury the
+ * signal in a log nobody reads. Note the division of labour, CORRECTED by a live run ([R80]):
+ * the `throw` below covers PER-PAPER failures (it propagates and crashes the build regardless
+ * of flags); `--strict` covers errors raised while building a page (a bad DOI, a missing
+ * image); and NEITHER covers "the plugin never loaded at all" — myst logs `Unknown plugin` +
+ * `unknown directive` and still exits 0, deploying a gallery-less page over a good one. That
+ * third case is caught in the site workflow by asserting this plugin's `name` appears in the
+ * build log, which is why the name below is load-bearing: do not rename it casually.
+ *
+ * The THUMBNAIL is deliberately not fetched here. This transform runs at `stage: 'document'`
+ * (`process/mdast.ts:224`), i.e. BEFORE `transformImagesToDisk` (`:438`), so the remote URL
+ * emitted below is picked up by `saveImageInStaticFolder` → `downloadAndSaveImage`
+ * (`transforms/images.ts:115-117`) and written into the site's public folder under a content
+ * hash. Three consequences: the published site serves a LOCAL copy rather than hotlinking
+ * `raw.githubusercontent.com`; a broken thumbnail is already an error-kind warning
+ * (`RuleId.imageDownloads`, `images.ts:82-88`, including the HTML-error-page content-type
+ * case), so `--strict` fails the build on it with no extra check here; and caching titles in
+ * the registry could never make the site build hermetic, because N thumbnail downloads would
+ * remain either way.
+ */
+import { readFileSync } from 'node:fs';
+import yaml from 'js-yaml';
+
+/** The registry, relative to the site build root. Fixed, not an option: [S8] fixed the repo
+ *  layout (the site IS the instance-config repo), so a `:registry:` option would be
+ *  configurability for a layout that cannot occur. Adding one later stays compatible. */
+export const REGISTRY_PATH = 'registry/papers.yml';
+
+/** Read + parse the registry. A missing/malformed registry is fatal: without it the page
+ *  would deploy with an empty gallery, which reads as "this journal has no papers". */
+export function loadRegistry(file = REGISTRY_PATH) {
+  let raw;
+  try {
+    raw = readFileSync(file, 'utf8');
+  } catch (err) {
+    throw new Error(
+      `paper-cards: cannot read the paper registry at "${file}" (${err.message}). ` +
+        `The gallery is built from this repo's registry — run the build from the repo root.`,
+    );
+  }
+  const entries = yaml.load(raw) ?? [];
+  if (!Array.isArray(entries)) {
+    throw new Error(`paper-cards: "${file}" must be a LIST of registry entries (design §9).`);
+  }
+  return entries;
+}
+
+/**
+ * The papers a `:::{paper-cards}` block shows, in **registry file order** — the editor
+ * controls sequence by where they insert the entry, which is the one ordering rule that
+ * needs no extra field. `edition` omitted → every registered paper (what the scaffold's
+ * single page uses); a fresh journal has exactly one edition, and a tenant who grows a
+ * second one adds a page and filters it ([S6]).
+ */
+export function selectEntries(registry, opts = {}) {
+  const { edition } = opts;
+  return edition ? registry.filter((entry) => entry.edition === edition) : [...registry];
+}
+
+/** `location.path` as a URL prefix: '.' / '' → '', 'papers/x' → 'papers/x/'. Kept even
+ *  though every entry is `.` today — it is what keeps the repo=journal (n>1) tier reachable
+ *  without touching this plugin ([S7]). */
+function pathPrefix(path) {
+  const trimmed = (path ?? '.').replace(/^\.$/, '').replace(/^\/+|\/+$/g, '');
+  return trimmed ? `${trimmed}/` : '';
+}
+
+/**
+ * The three URLs a card is built from. The ONE place [S4]'s shape shows up, and the one
+ * place that changes if we ever read a built `myst.json` instead of the raw `myst.yml`.
+ *
+ * `site_url` is honored when present (custom domains, non-Pages hosting) and otherwise
+ * derived from `location.repo`. Raw URLs go through **`HEAD`**, not `main`, so a tenant
+ * whose default branch is named otherwise still resolves. The thumbnail path is not a
+ * guess: `paper-base.yml` pins `project.thumbnail: thumbnails/thumbnail.png` for every paper.
+ */
+export function paperUrls(entry) {
+  const repo = entry?.location?.repo;
+  if (typeof repo !== 'string' || !repo.includes('/')) {
+    throw new Error(
+      `paper-cards: registry entry "${entry?.slug ?? entry?.id ?? '?'}" has no valid ` +
+        `location.repo ("owner/name"). Fix the entry in ${REGISTRY_PATH}.`,
+    );
+  }
+  const [owner, name] = repo.split('/');
+  const prefix = pathPrefix(entry.location.path);
+  const raw = `https://raw.githubusercontent.com/${repo}/HEAD/${prefix}`;
+  return {
+    siteUrl: entry.site_url ?? `https://${owner}.github.io/${name}`,
+    configUrl: `${raw}myst.yml`,
+    thumbUrl: `${raw}thumbnails/thumbnail.png`,
+  };
+}
+
+/**
+ * One card node, PURE: (registry entry, that paper's fetched myst config) → mdast. Title and
+ * keywords come from the paper (the registry stays a thin pointer list, [S4]); the DOI comes
+ * from the registry, since that is the one display field the registry actually owns.
+ */
+export function cardFrom(entry, config) {
+  const { siteUrl, thumbUrl } = paperUrls(entry);
+  const project = config?.project ?? {};
+  const title = project.title || entry.slug || entry.id;
+  const keywords = project.keywords ?? [];
+
+  const children = [
+    { type: 'header', children: [{ type: 'text', value: title }] },
+    { type: 'image', url: thumbUrl, alt: title, width: '100%' },
+  ];
+  if (keywords.length > 0) {
+    children.push({ type: 'paragraph', children: [{ type: 'text', value: keywords.join(' | ') }] });
+  }
+  // The DOI is TEXT, deliberately not a link. myst converts any `link` whose url is a DOI
+  // into a `cite` node (`myst-cli/transforms/dois.ts:239-242`, no per-node opt-out), which
+  // on a gallery card is wrong twice over: the card would render a citation label plus a
+  // stray bibliography instead of the identifier, and each card would cost a doi.org
+  // metadata fetch per build — rate-limited upstream, and one unreachable DOI fails the
+  // whole journal under `--strict`. Found on the first live run, with a sandbox DOI.
+  // The card itself already links to the paper, whose own page carries a real DOI link.
+  if (entry.doi) {
+    children.push({
+      type: 'footer',
+      children: [
+        { type: 'paragraph', children: [{ type: 'text', value: `DOI: ${entry.doi}` }] },
+      ],
+    });
+  }
+  return { type: 'card', url: siteUrl, children };
+}
+
+/** Fetch one paper's myst config. Throws naming BOTH the slug and the URL, because the fix
+ *  is a registry edit and the editor needs to know which line to edit. */
+export async function fetchPaperConfig(entry, fetchImpl = fetch) {
+  const { configUrl } = paperUrls(entry);
+  let response;
+  try {
+    response = await fetchImpl(configUrl);
+  } catch (err) {
+    throw new Error(
+      `paper-cards: failed to fetch the config for "${entry.slug ?? entry.id}" from ${configUrl} ` +
+        `(${err.message}). Fix or remove the entry in ${REGISTRY_PATH}.`,
+    );
+  }
+  if (!response.ok) {
+    throw new Error(
+      `paper-cards: failed to fetch the config for "${entry.slug ?? entry.id}" from ${configUrl} ` +
+        `(${response.status} ${response.statusText}). Fix or remove the entry in ${REGISTRY_PATH}.`,
+    );
+  }
+  return yaml.load(await response.text());
+}
+
+const paperCardsDirective = {
+  name: 'paper-cards',
+  doc: 'A gallery of cards, one per registered paper.',
+  options: {
+    edition: {
+      type: String,
+      doc: 'Only show papers whose registry `edition` matches. Omit for every registered paper.',
+    },
+  },
+  run(data) {
+    const entries = selectEntries(loadRegistry(), { edition: data.options?.edition });
+    if (entries.length === 0) {
+      return [{ type: 'paragraph', children: [{ type: 'text', value: 'No papers found.' }] }];
+    }
+    // The directive is sync, so the per-paper fetch happens in the transform below; these
+    // placeholder nodes carry the entry across.
+    return [
+      {
+        type: 'grid',
+        columns: [1, 1, 2, 3],
+        children: entries.map((entry) => ({ type: 'paper-card-ref', entry, children: [] })),
+      },
+    ];
+  },
+};
+
+function paperCardsTransform(opts, utils) {
+  return async (mdast) => {
+    const nodes = utils.selectAll('paper-card-ref', mdast);
+    if (nodes.length === 0) return;
+    await Promise.all(
+      nodes.map(async (node) => {
+        const { entry } = node;
+        const config = await fetchPaperConfig(entry);
+        const card = cardFrom(entry, config);
+        delete node.entry;
+        Object.assign(node, card);
+      }),
+    );
+  };
+}
+
+const plugin = {
+  name: 'Paper Gallery',
+  directives: [paperCardsDirective],
+  // `stage: 'document'` is load-bearing, not incidental — see the thumbnail note at the top.
+  transforms: [{ plugin: paperCardsTransform, stage: 'document' }],
+};
+
+export default plugin;

package/templates/instance/brand/brand.yml

@@ -0,0 +1,15 @@
+version: 1
+
+# Brand (design §5) — the journal's visual identity. HTML assets (site.options.logo /
+# favicon) may be absolute URLs; the typst PDF watermark MUST be a REAL local file, which
+# compose() absolutizes (`./logo.svg` → <instanceRoot>/brand/logo.svg). Replace logo.svg
+# with your own mark.
+site:
+  options:
+    logo_text: CHANGE-ME Journal
+    # logo: https://example.org/logo.svg
+    # favicon: https://example.org/logo.svg
+    # logo_url: https://example.org
+project:
+  options:
+    logo: ./logo.svg

package/templates/instance/brand/logo.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="120" height="120" viewBox="0 0 120 120" role="img" aria-label="Journal logo placeholder">
+  <rect width="120" height="120" rx="12" fill="#1a1a1a"/>
+  <text x="60" y="72" font-family="sans-serif" font-size="48" font-weight="700" fill="#ffffff" text-anchor="middle">J</text>
+</svg>

package/templates/instance/editions/edition.yml

@@ -0,0 +1,14 @@
+version: 1
+
+# Edition data (design §5) — venue/license/funding. Declares NO `exports:` ([R52]): the
+# complete typst export lives in the engine's paper-base.yml (myst merges exports by id
+# whole-entry, so splitting fields here would race). Do NOT add `extends:` — compose()
+# assembles the engine‹edition‹brand chain. `oak bootstrap` renames this file to
+# `editions/<edition>.yml`.
+project:
+  subject: Article
+  venue: CHANGE-ME Journal
+  license: CC-BY-4.0
+  open_access: true
+  # funding: |
+  #   Your funder

package/templates/instance/journal.yml

@@ -0,0 +1,58 @@
+# INSTANCE-CONFIG manifest (design §3) — the tenant's journal identity. Data only, no
+# engine logic. `oak bootstrap journal` stamps this; additive-only (dec. 24), so an older
+# pinned engine ignores keys it doesn't know. MUST stay in a PUBLIC repo ([R32], dec. 16):
+# Stage-1 fork-PR builds clone it with no token.
+name: CHANGE-ME Journal
+# url: https://example.org
+
+tier: paper
+
+# id policy (design dec. 20). `id_sentinel` is the one id `oak validate` rejects (the
+# template placeholder). `id_pattern` is an anchored regex every real paper id must match —
+# customize to your journal's convention.
+id_sentinel: CHANGE-ME-template-placeholder
+id_pattern: "^[a-z0-9]+-\\d{4}-[a-z0-9-]+$"
+
+# Your journal's typst PDF template. Omit it to use the engine's default template (the
+# usual case — the engine template is already brandable by parameter: watermark, colors).
+#
+# Accepts myst's three template forms, and the difference between two of them is the one
+# thing worth reading twice:
+#
+#   ./typst-template     a PATH, relative to THIS directory (instance-config root)
+#   ../shared/typst      a PATH, relative to this directory
+#   /srv/typst-template  a PATH, absolute
+#   https://…/x.zip      a URL (prefer a tag/release URL; a branch URL floats and warns)
+#   lapreprint-typst     a NAME, looked up against myst's template registry
+#
+# ONLY `./` and `../` mean "a directory in my instance-config". A bare `typst-template`
+# with no `./` is a template NAME, even if a directory of that name sits right next to
+# this file — one string always means one thing, whatever happens to be on disk. If you
+# meant the directory, write `./typst-template`. (`oak validate` warns when a bare value
+# shadows a real directory here, which is the one case you'd guess wrong.)
+#
+# A paper may override this with its own `exports[].template`; that is allowed and
+# applied, and `oak validate` flags it on the PR so the divergence from journal identity
+# is reviewed rather than silent.
+# typst_template: ./typst-template
+
+preview:
+  # 'artifact' degrades to a build-artifact link. Switch to 'cloudflare' + set
+  # cf_project_name once the paper repos carry the CLOUDFLARE_* secrets ([R6]).
+  provider: artifact
+  branch_pattern: paper-{repo}-{pr}
+
+# Optional per-tenant Zenodo config ([R19]) — a fresh journal has neither.
+zenodo: {}
+  # community: your-zenodo-community
+  # description_blurb: >-
+  #   Created as part of the CHANGE-ME Journal.
+
+# Journal-controlled editorial checks (slice 4 Layer B). The author cannot weaken this set —
+# it lives here in instance-config; `oak validate` runs it and the PR check gates on it.
+checks:
+  - id: authors-exist
+  - id: authors-have-orcid
+  - id: authors-have-credit-roles
+  - id: abstract-exists
+  - id: keywords-defined

package/templates/instance/registry/papers.yml

@@ -0,0 +1,20 @@
+# Paper registry (design §9). One entry per paper: {id, slug, location, edition} ([R47]).
+# `id` is the deposit/dedup key (myst-native project.id); `slug` is the URL/thumbnail path;
+# `location` is {repo, path} where the paper lives. Additive-only (dec. 24). Empty until the
+# first paper is registered.
+#
+# Registration is a MANUAL editorial PR ([S5]) — and since the journal site lives in this
+# same repo, that PR is also what redeploys the gallery. The registry stays a thin POINTER
+# list: the gallery fetches each paper's title, keywords and thumbnail from the paper repo
+# itself, so nothing here needs updating when a paper's title changes.
+#
+# - id:       j-2026-example
+#   slug:     example
+#   location: { repo: owner/example-paper, path: . }
+#   edition:  edition
+#   doi:      10.5281/zenodo.1234567     # optional; shown on the card once deposited
+#   site_url: https://journal.example.org/example
+#             # optional. Where the paper is PUBLISHED, when it isn't where we'd guess.
+#             # Omitted → derived as https://<owner>.github.io/<repo-name> from
+#             # location.repo. Set it for a custom domain or non-Pages hosting.
+[]

package/templates/paper/.github/actions/engine/action.yml

@@ -0,0 +1,59 @@
+name: engine
+description: >-
+  Resolve the engine ref from myst.yml, check out the pinned ENGINE repo at that ref,
+  and dispatch a verb to it. The ONE place the pins live (design §6a, §1a). Frozen +
+  CODEOWNERS-gated; all *logic* lives behind the engine version, improvable by a bump.
+
+inputs:
+  args:
+    description: "verb + args for the engine (e.g. 'build', 'release --tag v1.0.0')"
+    required: true
+
+runs:
+  using: composite
+  steps:
+    # --- resolve the engine ref from the paper's own myst.yml (raw, pre-extends) ------
+    # Quoted key form ["oaktree-sapling"] — an unquoted hyphenated key is yq-version
+    # sensitive ([R14]); explicit guard so a missing options block fails LOUDLY, not as a
+    # baffling downstream checkout error.
+    - id: ref
+      shell: bash
+      run: |
+        ref=$(yq '.project.options["oaktree-sapling"].version // ""' myst.yml)
+        if [ -z "$ref" ] || [ "$ref" = "null" ]; then
+          echo "::error::project.options.oaktree-sapling.version missing from myst.yml"
+          exit 1
+        fi
+        echo "ref=$ref" >> "$GITHUB_OUTPUT"
+
+    # --- pins.yml = the single source of truth, read by CI *and* local oak (dec. 21) --
+    - id: pins
+      shell: bash
+      run: |
+        pins=.github/actions/engine/pins.yml
+        echo "engine=$(yq '.engine_repo' "$pins")" >> "$GITHUB_OUTPUT"
+        echo "instance=$(yq '.instance_repo // "."' "$pins")" >> "$GITHUB_OUTPUT"
+
+    # --- check out ENGINE@ref. Pinned `repository:` ⇒ the ref provably resolves inside
+    # the engine repo; only the ref floats (design §6a, [R9]). Ref-class trust (raw SHA /
+    # PR-merge refs from forks) is enforced by `oak validate` inside the engine ([R41]).
+    - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      with:
+        repository: ${{ steps.pins.outputs.engine }}
+        ref: ${{ steps.ref.outputs.ref }}
+        path: .engine
+
+    # --- OPT-IN per-paper execution env only (design §0/[R44]): micromamba iff the paper
+    # ships paper-environment.yml. No file → no Python anywhere.
+    - uses: mamba-org/setup-micromamba@ce51e99f4bb8a82ab7158c4dc59ef4634c59c4f9 # v3.1.0
+      if: ${{ hashFiles('paper-environment.yml') != '' }}
+      with:
+        environment-file: paper-environment.yml
+        cache-environment: true
+
+    # --- dispatch. INSTANCE_REPO comes from pins.yml ('.' when co-located, repo=journal).
+    # Debuggability: run.sh echoes what it resolved at the top of every run.
+    - shell: bash
+      env:
+        INSTANCE_REPO: ${{ steps.pins.outputs.instance }}
+      run: .engine/ci/run.sh ${{ inputs.args }}

package/templates/paper/.github/actions/engine/pins.yml

@@ -0,0 +1,16 @@
+# Pins — the trust boundary (design §6a, dec. 21, [R37]). The engine repo (org/repo) is
+# pinned here; only the *ref* (project.options.oaktree-sapling.version in myst.yml) floats.
+# Read by BOTH the CI shim (yq, in action.yml) and local `oak`, so CI and local share one
+# source of truth and can't drift. Covered by the broad `.github/` CODEOWNERS gate — no
+# new gated path. `oak bootstrap` / copier fills these; editing them is CODEOWNERS-gated
+# because an instance/edition config can name MyST plugins (JS run at build time), so the
+# instance repo is a code-adjacent source (same trust argument as the engine source).
+
+# INTERIM home: the engine is developed on a personal account first; it moves to
+# open-scholar-nexus/oaktree-sapling later via replayed commits ([R56]). Because this is
+# the only place the home is named, the move is a one-line owner swap here.
+engine_repo: pollomarzo/whitelabel
+
+# owner/repo of INSTANCE-CONFIG. Set to "." (or omit) when instance-config is co-located
+# in this repo (repo=journal). copier replaces the placeholder below at bootstrap.
+instance_repo: pollomarzo/CHANGE-ME-instance-config

package/templates/paper/.github/workflows/check-post.yml

@@ -0,0 +1,79 @@
+name: Journal checks post
+
+# Stage 2 of the two-stage journal-checks flow (slice 4b). POST only, trusted: runs in
+# BASE-repo context after "Journal checks" (check.yml) completes, so it holds the write token
+# that fork PRs never get — the same split preview-deploy.yml uses. It ONLY downloads Stage
+# 1's precomputed report artifact and posts it; it NEVER re-runs validate or rebuilds paper
+# content (that would reopen the injection hole through the shim's back door). The engine ref
+# + action code come from the BASE default branch (guaranteed by workflow_run).
+#
+# Posts BOTH a first-class "Journal checks" Check Run on the PR HEAD (gates merge + annotates)
+# and an always-on sticky PR comment (visibility — authors rarely click the Check Run
+# "Details"). On a `push` to main it posts the success Check Run with no comment (no PR).
+
+on:
+  workflow_run:
+    workflows: ["Journal checks"]
+    types: [completed]
+
+permissions:
+  contents: read # checkout the base default branch (engine ref + action code)
+  actions: read # download the cross-run artifact
+  checks: write # post the "Journal checks" Check Run
+  pull-requests: write # upsert the sticky checks comment
+
+concurrency:
+  # Key on head repo + branch so two forks PRing from `main` don't cancel each other ([R15]).
+  group: check-post-${{ github.event.workflow_run.head_repository.full_name }}-${{ github.event.workflow_run.head_branch }}
+  cancel-in-progress: true
+
+jobs:
+  post:
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 — BASE default branch ⇒ engine ref AND action code from base
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: journal-checks
+          path: journal-checks
+          run-id: ${{ github.event.workflow_run.id }}
+          github-token: ${{ github.token }}
+
+      # The artifact comes from the untrusted Stage-1 job; head-sha/pr-number flow from here into
+      # the `args:` string spliced into a shell in ./.github/actions/engine. Validate shape and
+      # fail CLOSED before they leave this step — a git sha is [0-9a-f]{7,40}, a PR number is
+      # digits — so no newline (GITHUB_OUTPUT injection) or shell metacharacter can ride through
+      # even if Stage 1 gets attacker bytes into the files.
+      - id: meta
+        run: |
+          sha=$(cat journal-checks/head-sha)
+          if ! printf '%s' "$sha" | grep -qE '^[0-9a-f]{7,40}$'; then
+            echo "::error::head-sha in artifact is not a valid git sha; refusing to post"
+            exit 1
+          fi
+          echo "sha=$sha" >> "$GITHUB_OUTPUT"
+          if [ -f journal-checks/pr-number ]; then
+            pr=$(cat journal-checks/pr-number)
+            if ! printf '%s' "$pr" | grep -qE '^[0-9]{1,10}$'; then
+              echo "::error::pr-number in artifact is not a valid number; refusing to post"
+              exit 1
+            fi
+            echo "pr=$pr" >> "$GITHUB_OUTPUT"
+          fi
+
+      # Posts the precomputed report — the Check Run on the PR HEAD sha and, when a PR, the
+      # sticky comment. Best-effort inside the engine: a post failure degrades to a
+      # `::warning::`, never fails this job.
+      - uses: ./.github/actions/engine
+        with:
+          args: >-
+            check-post
+            --report journal-checks/report.json
+            --repo ${{ github.repository }}
+            --sha ${{ steps.meta.outputs.sha }}
+            --base ${{ github.event.repository.default_branch }}
+            --verified-head ${{ github.event.workflow_run.head_sha }}
+            ${{ steps.meta.outputs.pr && format('--pr {0}', steps.meta.outputs.pr) || '' }}
+        env:
+          GH_TOKEN: ${{ github.token }}

package/templates/paper/.github/workflows/check.yml

@@ -0,0 +1,72 @@
+name: Journal checks
+
+# Stage 1 of the two-stage journal-checks flow (slice 4b). COMPUTE only, untrusted: runs on
+# the `pull_request` event with a read-only, secret-less token — safe for fork content, which
+# `oak validate` only READS. It writes the check report to an artifact and NEVER posts to the
+# PR. All PR write-back (the Check Run + the sticky comment) happens in Stage 2
+# (check-post.yml, a `workflow_run` job in base context), exactly like the preview split
+# (ci.yml → preview-deploy.yml): fork + same-repo PRs take the identical path, and the step
+# that runs untrusted paper content never holds a writable token.
+#
+# This job SUCCEEDS whenever a valid report was produced — even when checks FAIL — so Stage 2
+# always fires and posts the (failing) Check Run that gates the merge. Only a genuine engine
+# crash (no report / invalid JSON) fails this job.
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read # checkout only; the untrusted compute job holds nothing else
+
+concurrency:
+  group: ${{ github.event_name == 'pull_request' && format('check-{0}', github.head_ref) || 'check-main' }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      # `oak validate` exits 1 on a blocking failure (its contract, used by the merge gate +
+      # local runs). Here that must NOT fail Stage 1 — we only need the report file. So the
+      # step tolerates a nonzero exit; the guard below re-imposes "fail on a genuine crash".
+      - id: validate
+        continue-on-error: true
+        uses: ./.github/actions/engine
+        with:
+          args: validate --report report.json
+
+      # Last resort only: `oak validate` writes a failing report even for a usage error or an
+      # unexpected throw, so reaching this branch means the engine died before it could write
+      # anything at all. Point at the step that holds the real message rather than restating
+      # "crash" — a bare "no valid report" told the author nothing about what to fix.
+      - name: Ensure a valid report was produced
+        run: |
+          if ! jq -e '.checkRun.conclusion' report.json >/dev/null 2>&1; then
+            echo "::error::oak validate wrote no report at all — the engine died before it could report. The real error is in the '${{ steps.validate.outcome }}' validate step's log above; nothing was posted to the PR."
+            exit 1
+          fi
+          echo "report ok — conclusion: $(jq -r '.checkRun.conclusion' report.json)"
+
+      # Stash the PR HEAD sha (GITHUB_SHA is the ephemeral merge commit on a PR — a Check Run
+      # there never surfaces on the PR) and the PR number (workflow_run.pull_requests is EMPTY
+      # for forks). Stage 2 reads both from the artifact.
+      - name: Record head sha + PR number
+        run: |
+          echo "${{ github.event.pull_request.head.sha || github.sha }}" > head-sha
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            echo "${{ github.event.pull_request.number }}" > pr-number
+          fi
+
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: journal-checks
+          path: |
+            report.json
+            head-sha
+            pr-number
+          if-no-files-found: error