research: freeze context efficiency v3 amendment 001

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -13,7 +13,7 @@ body:
     attributes:
       label: Qarinah version
       description: Output of `npm view qarinah version` and the installed version.
-      placeholder: "0.1.3"
+      placeholder: "0.1.6"
     validations:
       required: true
   - type: dropdown

.github/workflows/ci.yml

@@ -53,6 +53,8 @@ jobs:
         node: [22, 24, 26]
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
       - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version: ${{ matrix.node }}

.github/workflows/deploy-site.yml

@@ -0,0 +1,157 @@
+name: Deploy website
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: Exact published qarinah version to deploy
+        required: true
+        type: string
+      expected_git_commit:
+        description: Exact reviewed lowercase 40-character main commit
+        required: true
+        type: string
+      confirmation:
+        description: Type deploy qarinah@VERSION
+        required: true
+        type: string
+
+permissions:
+  contents: read
+  actions: read
+
+concurrency:
+  group: deploy-qarinah-site
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    name: Build, verify, and deploy exact published site
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    environment:
+      name: website
+      url: https://qarinah.io
+    env:
+      DEPLOY_COMMIT: ${{ inputs.expected_git_commit }}
+      EXPECTED_MANUAL_VERSION: ${{ inputs.version }}
+    steps:
+      - name: Validate trusted trigger
+        shell: bash
+        env:
+          CONFIRMATION: ${{ inputs.confirmation }}
+          EXPECTED_GIT_COMMIT: ${{ inputs.expected_git_commit }}
+        run: |
+          set -euo pipefail
+          [[ "${GITHUB_REPOSITORY}" == "AjnasNB/qarinah" ]] || { echo "Unexpected repository." >&2; exit 1; }
+          [[ "${DEPLOY_COMMIT}" =~ ^[0-9a-f]{40}$ ]] || { echo "Invalid deployment commit." >&2; exit 1; }
+          [[ "${GITHUB_REF}" == "refs/heads/main" ]] || { echo "Manual deployment must run from main." >&2; exit 1; }
+          [[ "${EXPECTED_GIT_COMMIT}" == "${GITHUB_SHA}" ]] || { echo "Manual deployment commit is not the exact selected main commit." >&2; exit 1; }
+          [[ "${CONFIRMATION}" == "deploy qarinah@${EXPECTED_MANUAL_VERSION}" ]] || { echo "Manual confirmation mismatch." >&2; exit 1; }
+
+      - name: Check out the exact published commit
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ env.DEPLOY_COMMIT }}
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Set up Node.js
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 24.15.0
+          registry-url: https://registry.npmjs.org
+          package-manager-cache: false
+
+      - name: Verify checked-out identity
+        shell: bash
+        run: |
+          set -euo pipefail
+          actual_commit="$(git rev-parse HEAD)"
+          [[ "${actual_commit}" == "${DEPLOY_COMMIT}" ]] || { echo "Checked-out commit mismatch." >&2; exit 1; }
+          package_name="$(node -p 'require("./package.json").name')"
+          package_version="$(node -p 'require("./package.json").version')"
+          [[ "${package_name}" == "qarinah" ]] || { echo "Unexpected package name." >&2; exit 1; }
+          [[ "${package_version}" == "${EXPECTED_MANUAL_VERSION}" ]] || { echo "Manual version does not match the reviewed commit." >&2; exit 1; }
+          echo "PACKAGE_VERSION=${package_version}" >> "${GITHUB_ENV}"
+
+      - name: Require a successful trusted publish
+        env:
+          GH_TOKEN: ${{ github.token }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          node --input-type=module <<'NODE'
+          const [owner, repository] = process.env.GITHUB_REPOSITORY.split("/");
+          const url = new URL(`https://api.github.com/repos/${owner}/${repository}/actions/workflows/publish-npm.yml/runs`);
+          url.searchParams.set("event", "workflow_dispatch");
+          url.searchParams.set("status", "success");
+          url.searchParams.set("head_sha", process.env.DEPLOY_COMMIT);
+          url.searchParams.set("per_page", "10");
+
+          const response = await fetch(url, {
+            headers: {
+              Accept: "application/vnd.github+json",
+              Authorization: `Bearer ${process.env.GH_TOKEN}`,
+              "X-GitHub-Api-Version": "2022-11-28"
+            }
+          });
+          if (!response.ok) throw new Error(`Unable to verify trusted publish: GitHub returned ${response.status}.`);
+          const payload = await response.json();
+          const trusted = payload.workflow_runs?.some((run) =>
+            run.head_sha === process.env.DEPLOY_COMMIT
+            && run.head_branch === "main"
+            && run.event === "workflow_dispatch"
+            && run.conclusion === "success"
+            && (run.path === ".github/workflows/publish-npm.yml"
+              || run.path?.startsWith(".github/workflows/publish-npm.yml@"))
+          );
+          if (!trusted) throw new Error("No successful trusted publish exists for the exact deployment commit.");
+          NODE
+
+      - name: Wait for the exact npm package version
+        shell: bash
+        run: |
+          set -euo pipefail
+          retry_delay_seconds() {
+            local attempt="$1"
+            local delay=$((2 ** (attempt - 1)))
+            if (( delay > 30 )); then delay=30; fi
+            printf '%s' "${delay}"
+          }
+
+          published_version=""
+          for attempt in {1..30}; do
+            published_version="$(npm view "qarinah@${PACKAGE_VERSION}" version 2>/dev/null || true)"
+            if [[ "${published_version}" == "${PACKAGE_VERSION}" ]]; then
+              echo "qarinah@${PACKAGE_VERSION} is published; website verification may proceed."
+              break
+            fi
+            if (( attempt < 30 )); then
+              delay="$(retry_delay_seconds "${attempt}")"
+              echo "qarinah@${PACKAGE_VERSION} is not visible yet (attempt ${attempt}/30); retrying in ${delay}s."
+              sleep "${delay}"
+            fi
+          done
+          if [[ "${published_version}" != "${PACKAGE_VERSION}" ]]; then
+            echo "qarinah@${PACKAGE_VERSION} was not available after 30 attempts; refusing to build or deploy the site." >&2
+            exit 1
+          fi
+
+      - name: Install exact dependencies without lifecycle scripts
+        run: npm ci --ignore-scripts
+
+      - name: Build site-dist
+        run: npm run build:site
+
+      - name: Verify site-dist
+        run: npm run check:site
+
+      - name: Deploy checked assets
+        uses: cloudflare/wrangler-action@ebbaa1584979971c8614a24965b4405ff95890e0 # v4.0.0
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          wranglerVersion: "4.120.0"
+          packageManager: npm
+          command: deploy --config wrangler.jsonc

.github/workflows/publish-npm.yml

@@ -6,7 +6,7 @@ on:
       version:
         description: Exact package version to publish
         required: true
-        default: 0.1.3
+        default: 0.1.6
         type: string
       expected_git_commit:
         description: Exact reviewed lowercase 40-character commit SHA
@@ -79,6 +79,7 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           ref: ${{ github.sha }}
+          fetch-depth: 0
           persist-credentials: false
       - name: Set up Node.js
         uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
@@ -203,4 +204,17 @@ jobs:
           npm init --yes >/dev/null
           npm install "qarinah@${EXPECTED_VERSION}" --ignore-scripts
           node --input-type=module -e "await import('qarinah'); await import('qarinah/codex'); await import('qarinah/claude'); await import('qarinah/mcp')"
-          npm audit signatures
+          verified=""
+          for attempt in {1..10}; do
+            if npm audit signatures; then
+              verified="yes"
+              break
+            fi
+            if (( attempt < 10 )); then
+              delay=$((2 ** (attempt - 1)))
+              if (( delay > 30 )); then delay=30; fi
+              echo "Registry signature verification was not ready (attempt ${attempt}/10); retrying in ${delay}s."
+              sleep "${delay}"
+            fi
+          done
+          [[ "${verified}" == "yes" ]] || { echo "Registry signature verification did not succeed." >&2; exit 1; }

.gitignore

@@ -6,3 +6,5 @@ benchmark-results/
 *.tgz
 site-dist/
 tmp/
+__pycache__/
+*.pyc

CONTRIBUTING.md

@@ -24,6 +24,16 @@ npm run check
 
 Run focused tests while iterating, then run `npm run check` before requesting review. A pull request is not release-ready until the full check passes from a clean install.
 
+### White-paper builds
+
+White-paper generation is a repository-maintainer workflow, not a public npm-package command. The Python builders and generated PDF are intentionally excluded from the npm tarball. From a complete source checkout with Python 3 and ReportLab installed, build the current paper directly:
+
+```sh
+python scripts/build-whitepaper-pdf-v1.3.py
+```
+
+The v1.3 source receipt binds `docs/WHITEPAPER.md`, the shared layout engine, and the version-specific wrapper. Its companion build metadata records the Python, ReportLab, platform, and font inputs used for that generated artifact. Never run the historical builder directly to replace a published PDF.
+
 ## Architecture invariants
 
 Qarinah's JSONL event log is the authoritative record. Graphs, indexes, Markdown views, OKF exports, and context packs must remain deterministic derivatives.

README.md

@@ -103,8 +103,8 @@ The JSONL chain remains authoritative. Graph, index, Markdown, dashboard, and OK
 
 <p align="center">
   <a href="docs/WHITEPAPER.md">Technical paper</a>&nbsp;&middot;&nbsp;
-  <a href="https://github.com/AjnasNB/qarinah/blob/main/output/pdf/Qarinah-Technical-White-Paper-v1.2.pdf">Publication PDF</a>&nbsp;&middot;&nbsp;
-  <a href="https://doi.org/10.5281/zenodo.21547684">Zenodo record</a>&nbsp;&middot;&nbsp;
+  <a href="https://github.com/AjnasNB/qarinah/blob/main/output/pdf/Qarinah-Technical-White-Paper-v1.3.pdf">White-paper v1.3 PDF</a>&nbsp;&middot;&nbsp;
+  <a href="https://doi.org/10.5281/zenodo.21843240">White-paper v1.3 DOI</a>&nbsp;&middot;&nbsp;
   <a href="docs/ARCHITECTURE.md">Architecture</a>&nbsp;&middot;&nbsp;
   <a href="docs/DASHBOARD.md">Dashboard</a>&nbsp;&middot;&nbsp;
   <a href="docs/BENCHMARKS.md">Benchmarks</a>&nbsp;&middot;&nbsp;
@@ -359,15 +359,15 @@ The repository also runs `npm run mcp:smoke` against the exact bundled Codex and
 
 ### Install once, initialize each project
 
-Install the reviewed `v0.1.5` plugin once in each host:
+Install the reviewed `v0.1.6` plugin once in each host after that release is published:
 
 ```sh
 # Codex: personal installation, available to opted-in projects.
-codex plugin marketplace add AjnasNB/qarinah --ref v0.1.5
+codex plugin marketplace add AjnasNB/qarinah --ref v0.1.6
 codex plugin add qarinah@qarinah
 
 # Claude Code: personal installation across projects.
-claude plugin marketplace add AjnasNB/qarinah@v0.1.5 --scope user
+claude plugin marketplace add AjnasNB/qarinah@v0.1.6 --scope user
 claude plugin install qarinah@qarinah --scope user
 ```
 
@@ -461,7 +461,9 @@ The long-document evaluator adds a fixed 600-token ceiling over a deterministic
 
 The [cross-session continuation benchmark](docs/CROSS-SESSION-CONTINUATION-BENCHMARK.md) adds a 42-record two-session fixture for context summarization, evidence links, and fresh-session retrieval. Its complete 1,039-token cited audit pack is 89.05% smaller than the 9,489-token full-ledger estimate and preserves all three summary source IDs and hashes. A separate 119-token model-facing capsule points to that verified pack and the selected summary event, reaching 98.75% reduction on the same unchanged fixture without removing the audit trail. The read also leaves deliberately stale derived state unchanged. A separate provider-backed Codex-to-Codex smoke uses distinct ephemeral sessions with native resume disabled, requires the second session to query Qarinah and cite its evidence, and verifies the resulting patch with tests. The provider smoke is product evidence, not a controlled research result.
 
-The separate [real-repository research track](docs/RESEARCH-BENCHMARK.md) pins 300 public SWE-bench Lite tasks into a chronological 60-task warm-up / 240-task development split. Frozen exploratory v0.1 found that BM25 beat the original balanced Qarinah ranker. Admission-first v2 now preserves admitted BM25 ranking while retaining repository, temporal, retention, disclosure, conflict, supersession, provenance, and budget controls; online MRR improves from 0.601 to 0.696 against balanced-v1 under the graded structural development oracle. Graph ranking adds no measured value here. At the conservative v0.3 operating point, the run observed 0/49 static and 0/31 online direct false accepts by abstaining aggressively; exact 95% upper bounds remain 7.25% and 11.22%, and coverage is only 3.33%-5.00%. The [latest development result](docs/RESEARCH-DEVELOPMENT-RESULTS-v0.3.md) also freezes 387 positive tasks, 20 abstention controls, a contamination audit, and a pre-outcome 40-pair power check. This phase does not measure coding-agent task success or provider usage.
+The separate [real-repository research track](docs/RESEARCH-BENCHMARK.md) pins 300 public SWE-bench Lite tasks into a chronological 60-task warm-up / 240-task development split. Frozen exploratory v0.1 found that BM25 beat the original balanced Qarinah ranker. Admission-first v2 preserves admitted BM25 ranking while retaining repository, temporal, retention, disclosure, conflict, supersession, provenance, and budget controls; online MRR improves from 0.601 to 0.696 against balanced-v1 under the graded structural development oracle. Graph ranking adds no measured value here. Historical v0.3 calibrated a conservative decision over frozen v0.2 scores. The immutable [production-bound v0.4 recomputation](docs/RESEARCH-DEVELOPMENT-RESULTS-v0.4.md) uses `evidence-sufficiency-v2`: it observed 10/10 static and 15/15 online direct accepts as structural-oracle positives, with 0/49 and 0/31 false accepts. Exact 95% false-acceptance upper bounds remain 7.25% and 11.22%, and coverage remains deliberately low at 4.17%-6.25%.
+
+A separately authorized [current-product source-bound v0.5 differential reproduction](bench/results/research-retrieval-development-v0.5.json) exactly matched the complete immutable v0.4 `expected` projection on the same inspected development corpus: 3,110,007 canonical bytes with SHA-256 `12f00c2e831e56b26c7eeff13d8b6aed0fee22760d40f5a46a1cb579870b3d0c`. The result is commit `4dba5b667a8c3a135c4574fcfefe12502f792a32`, tag `research-retrieval-development-v0.5-result`, and artifact SHA-256 `38a753e82e1f9e8e0337dca3f764c941a4cf78748c09a7b8341ae08cf7494a94`. This is development-only, non-confirmatory reproduction evidence; it made zero provider calls and does not measure provider tokens, coding-agent task success, latency, or cost. The research package also freezes 387 positive tasks, 20 abstention controls, a contamination audit, and a pre-outcome 40-pair power check.
 
 ## License and ownership