feat(related-persons): регистърни доказателства за връзките (#279)

.github/workflows/deploy.yml

@@ -145,6 +145,12 @@ jobs:
           pnpm --filter @sigma/web exec wrangler d1 execute "${SIGMA_D1_NAME:-sigma}" \
             --config wrangler.deploy.jsonc --remote --yes \
             --file ../../packages/db/migrations/0003_related_persons_foundation.sql
+          # 0006 attaches the Trade Register evidence seal (#279, ADR-0033). Both migrations are
+          # applied by name here because wrangler's migration ledger is empty on this D1 (the base
+          # schema was created out-of-band), so `d1 migrations apply` would collide on 0000.
+          pnpm --filter @sigma/web exec wrangler d1 execute "${SIGMA_D1_NAME:-sigma}" \
+            --config wrangler.deploy.jsonc --remote --yes \
+            --file ../../packages/db/migrations/0006_interest_link_evidence.sql
       # The base schema was created out-of-band with `d1 execute --file`, so wrangler's migration
       # ledger is empty and `d1 migrations apply` would collide on 0000. Probe the actual table
       # instead. SQLite has no `ADD COLUMN IF NOT EXISTS`; a completion-marker table is created only

.github/workflows/related-persons-data.yml

@@ -16,6 +16,38 @@ name: Related-persons data foundation (build + ship)
 # XML (fetch.mjs skips files already on disk) — it fills gaps, not a from-scratch rebuild unless the cache is cleared.
 
 on:
+  # MONTHLY, and deliberately on the EXISTING workflow rather than a second one. #279 §9 asks for the
+  # publishing decisions to run on a cadence; duplicating the job would create a second ship path with
+  # its own copy of the credential guards, the D1-target guard and the ship floor — and the copy is the
+  # one nobody exercises.
+  #
+  # WHY MONTHLY AND NOT DAILY, which is what §9 and ADR-0033 describe. A decision cannot be recomputed
+  # without the raw deeds — evidenceVerdict's strongest rung matches the declarant's name against the
+  # register's own text — and the raw deeds must not be persisted between runs: they carry the names and
+  # addresses of co-owners and managers who hold no public office, and an Actions cache entry lives on
+  # GitHub's storage under a restore-keys chain where ADR-0033 decision 5's 35-day retention cannot reach
+  # it. So the deeds live and die with one runner, and every run that decides must also crawl. A daily
+  # decision would therefore mean ~400 daily requests against somebody else's register, which is what
+  # spec §3.3 exists to prevent — so the cadence follows the deeds, not the other way round.
+  #
+  # Restoring a daily decision needs the crawl to emit the per-(link, ЕИК) match verdict, so only
+  # booleans cross a run boundary and nothing has to hold a name. That is a design change, not a
+  # schedule change, and it is deliberately not folded in here.
+  #
+  # A scheduled run takes the same path as a manual one, with two differences:
+  #   • it targets STAGING (the environment default below). Production stays manual, so the
+  #     assertD1TargetAuthorized guard keeps a prod write a deliberate act.
+  #   • `full_crawl` is empty and therefore false, so it never crawls the CACBG corpus — it re-runs the
+  #     decisions over the cached corpus, which is exactly what #279 §9 means by a pure, zero-network
+  #     decision. Registry lookups are the one exception and run from inside this job on the 1st of the
+  #     month (see „Decide whether to hit the register"): they cannot be a separate workflow, because the
+  #     raw deeds they fetch carry third-party names and must not be persisted between runners.
+  # If the corpus cache has been evicted, extract yields nothing, the ship floor refuses, and the run
+  # fails loudly rather than wiping the surface.
+  schedule:
+    # 03:00 UTC on the 1st. See the note above: the decision and the crawl are one pass, so the decision
+    # cadence is the crawl cadence — #279 §9's monthly registry rhythm.
+    - cron: '0 3 1 * *'
   workflow_dispatch:
     inputs:
       environment:
@@ -27,34 +59,43 @@ on:
         description: Crawl the CACBG corpus (slow). RESUMES from the cached raw XML — fetch.mjs skips files already on disk, so this fills gaps rather than re-fetching from scratch (clear the cache for a true rebuild). Off = extract from the existing raw cache without crawling.
         type: boolean
         default: false
+      tr_max_age_days:
+        description: Re-fetch deeds older than this many days (default 30). Use a large value to force a full refresh.
+        type: string
+        default: '30'
+      tr_limit:
+        description: Stop after this many registry lookups (blank = all pending). Bound a first run while watching for a 429.
+        type: string
+        default: ''
 
 # Least-privilege: this workflow only reads the repo; it authenticates to Cloudflare with a scoped token.
 permissions:
   contents: read
 
 concurrency:
   # Never let two data-foundation writes to the same environment overlap; do not cancel one in flight.
-  group: related-persons-data-${{ inputs.environment }}
+  group: related-persons-data-${{ inputs.environment || 'staging' }}
   cancel-in-progress: false
 
 jobs:
   build-and-ship:
     runs-on: ubuntu-latest
     # A from-scratch corpus crawl of the whole register is the long pole (all year-folders, politely
-    # throttled) and must fit in ONE job with extract/resolve/audit/ship after it — 120 was too tight and
-    # timed out mid-crawl. 300 leaves headroom under GitHub's 6-hour hard cap. A run past this is wedged
+    # throttled) and must fit in ONE job with the registry lookups, extract/resolve/audit/ship after it —
+    # 120 was too tight and timed out mid-crawl. The Търговски регистър pass adds ~20 minutes on top
+    # (~400 candidates at 1 request / 3 s). 300 leaves headroom under GitHub's 6-hour hard cap. A run past this is wedged
     # (stalled gov-server I/O) — fail rather than burn the slot. The raw corpus is cached (below) so a
     # re-run resumes instead of re-crawling from scratch.
     timeout-minutes: 300
-    environment: ${{ inputs.environment }}
+    environment: ${{ inputs.environment || 'staging' }}
     env:
       CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
       CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
       SIGMA_D1_ID: ${{ secrets.SIGMA_D1_ID }}
       SIGMA_D1_NAME: ${{ vars.SIGMA_D1_NAME }}
       # The DECLARED intended environment — the independent anchor the ship guard checks the (name, id) pair
       # against (T48), so a consistent-but-wrong pair can't wipe the wrong DB. See assertD1TargetAuthorized.
-      SIGMA_SHIP_ENV: ${{ inputs.environment }}
+      SIGMA_SHIP_ENV: ${{ inputs.environment || 'staging' }}
       # Suppression (takedown) list keying — load.mjs fingerprints link-suppressions.jsonl under this salt and
       # refuses to build if the list is non-empty but the salt is unset (fail-closed, ADR-0031). Without this
       # the first suppression entry would break every ship; the key version guards a coordinated salt rotation.
@@ -93,14 +134,14 @@ jobs:
             sigma-blue|sigma-green) IS_PROD_SLOT=1 ;;
             *) IS_PROD_SLOT=0 ;;
           esac
-          if [ "${{ inputs.environment }}" = "production" ]; then
+          if [ "${{ inputs.environment || 'staging' }}" = "production" ]; then
             if [ "$IS_PROD_SLOT" != "1" ]; then
               echo "::error::production requires SIGMA_D1_NAME to be a prod slot (sigma-blue|sigma-green), got '${SIGMA_D1_NAME}' — refusing to ship."
               exit 1
             fi
           else
             if [ "$IS_PROD_SLOT" = "1" ]; then
-              echo "::error::SIGMA_D1_NAME='${SIGMA_D1_NAME}' (a PRODUCTION slot) on a '${{ inputs.environment }}' run — a rebuild would WIPE prod. Set a non-production SIGMA_D1_NAME variable for this Environment."
+              echo "::error::SIGMA_D1_NAME='${SIGMA_D1_NAME}' (a PRODUCTION slot) on a '${{ inputs.environment || 'staging' }}' run — a rebuild would WIPE prod. Set a non-production SIGMA_D1_NAME variable for this Environment."
               exit 1
             fi
           fi
@@ -151,11 +192,29 @@ jobs:
           work="$GITHUB_WORKSPACE/data/work"
           mkdir -p "$work"
           rm -f "$work/eop.sql" "$work/backfill.sqlite"
+          # interest_links + interest_link_evidence come along too, and NOT for the resolver's benefit —
+          # load.mjs drops and rebuilds them. They are the input to the monotonicity gate: load.mjs
+          # exports the currently-published set BEFORE the wipe, and audit.mjs fails the run on a link
+          # that was published last time, under an unchanged rules_version, and is not published now.
+          # Without them the work DB starts with no interest_links at all, the pre-wipe export reads
+          # „no such table", the snapshot is [] on every run, and the gate protects nothing.
+          # They are absent on a first run (0003/0006 not yet applied), which is why they are exported
+          # separately and tolerated as missing rather than folded into the parity loop below.
           pnpm --filter @sigma/web exec wrangler d1 export "$SIGMA_D1_NAME" \
             --config wrangler.deploy.jsonc --remote -y \
             --table bidders --table contracts --table tenders --table authorities \
             --output "$work/eop.sql"
           sqlite3 "$work/backfill.sqlite" < "$work/eop.sql"
+          if pnpm --filter @sigma/web exec wrangler d1 export "$SIGMA_D1_NAME" \
+               --config wrangler.deploy.jsonc --remote -y \
+               --table interest_links --table interest_link_evidence \
+               --output "$work/prior-links.sql"; then
+            sqlite3 "$work/backfill.sqlite" < "$work/prior-links.sql"
+            echo "  prior surface: $(sqlite3 "$work/backfill.sqlite" \
+              "SELECT COUNT(*) FROM interest_links WHERE status='published';") published link(s)"
+          else
+            echo "::notice::No prior interest_links on this D1 (first run) — the monotonicity gate has no baseline yet."
+          fi
           for t in bidders contracts tenders authorities; do
             local_n=$(sqlite3 "$work/backfill.sqlite" "SELECT COUNT(*) FROM $t;")
             remote_json=$(pnpm --filter @sigma/web exec wrangler d1 execute "$SIGMA_D1_NAME" \
@@ -169,9 +228,60 @@ jobs:
             fi
           done
 
+      # ── Trade Register lookups ────────────────────────────────────────────────────────────────────
+      # In THIS job, deliberately, and not in a workflow of their own. The decision run needs the raw
+      # deeds (evidenceVerdict matches declarant names against the register's own text, which is exactly
+      # the data the index refuses to store), and those deeds carry the names and addresses of co-owners
+      # and managers who hold no public office. Handing them between runners means persisting them —
+      # an Actions cache entry survives on GitHub's storage under a restore-keys chain, where the 35-day
+      # retention ADR-0033 decision 5 promises cannot reach it. Same runner, same job, deleted with it.
+      #
+      # The previous split also could not work on its own terms: the crawl job gated on a candidate list
+      # only the decision job produced, the decision job refused without a cache only the crawl job
+      # produced, and neither persisted its half. Both were permanently green no-ops.
+      - name: Emit the candidate ЕИК list for the crawler
+        run: node --import ./scripts/cacbg/register-ts.mjs scripts/cacbg/load.mjs --emit-candidates
+
+      # ALWAYS, on every run that reaches here — not conditionally. The deeds do not survive the runner,
+      # so „decide without crawling" is not a state this job can be in: load.mjs's coverage gate below
+      # would refuse the empty cache and the run would fail. Skipping the crawl is only meaningful once
+      # the crawl emits verdicts rather than deeds (see the note on the schedule above).
+      #
+      # Pace and refusals live in scripts/tr/fetch-deeds.mjs and are not configurable here on purpose:
+      # 1 request / 3 s, sequential, a closed candidate set, and a 429 ends the run without marking
+      # anything. Spec §3.3 permits a bounded per-ЕИК lookup and forbids bulk scraping; the limiter is
+      # the operator's only way to state a rate preference, so we do not tune around it.
+      - name: Refresh the Trade Register deed cache
+        env:
+          MAX_AGE: ${{ inputs.tr_max_age_days || '30' }}
+          LIMIT: ${{ inputs.tr_limit }}
+        run: |
+          set -euo pipefail
+          ARGS=(--eiks-file scratch/cacbg/staging/candidate-eiks.txt --max-age-days "$MAX_AGE")
+          [ -n "$LIMIT" ] && ARGS+=(--limit "$LIMIT")
+          set +e
+          node scripts/tr/fetch-deeds.mjs "${ARGS[@]}"
+          code=$?
+          set -e
+          # Exit 2 is the rate limiter, and it is NOT a build failure: the run stopped politely, marked
+          # nothing, and the partial cache is valid. It is not a licence to publish either — load.mjs's
+          # coverage gate below refuses a partial cache on its own, which is where that decision belongs.
+          if [ "$code" -eq 2 ]; then
+            echo "::warning::The register rate-limited us; the crawl stopped and the cache is resumable."
+            exit 0
+          fi
+          exit "$code"
+
       - name: Resolve → build domain in a work sqlite (libel gate must pass)
         run: node --import ./scripts/cacbg/register-ts.mjs scripts/cacbg/load.mjs
 
+      # The raw deeds are third-party personal data and exist only to produce booleans. They are deleted
+      # with the runner regardless; deleting them explicitly means a failure AFTER this point cannot
+      # leave them sitting in a job artifact or a debug upload someone adds later.
+      - name: Delete the raw deeds
+        if: always()
+        run: rm -rf scratch/tr/deeds
+
       - name: Audit published links (fails the run on any libel-invariant violation)
         run: node --import ./scripts/cacbg/register-ts.mjs scripts/cacbg/audit.mjs
 
@@ -185,6 +295,12 @@ jobs:
           pnpm --filter @sigma/web exec wrangler d1 execute "$SIGMA_D1_NAME" \
             --config wrangler.deploy.jsonc --remote --yes \
             --file ../../packages/db/migrations/0003_related_persons_foundation.sql
+          # 0006 attaches the Trade Register evidence seal (#279, ADR-0033). Both migrations are
+          # applied by name here because wrangler's migration ledger is empty on this D1 (the base
+          # schema was created out-of-band), so `d1 migrations apply` would collide on 0000.
+          pnpm --filter @sigma/web exec wrangler d1 execute "$SIGMA_D1_NAME" \
+            --config wrangler.deploy.jsonc --remote --yes \
+            --file ../../packages/db/migrations/0006_interest_link_evidence.sql
 
       - name: Ship свързани-лица tables → D1
         # ship-related-persons.mjs shells out to `wrangler d1 execute` with cwd=apps/web. Two things it
@@ -198,7 +314,14 @@ jobs:
           node scripts/wrangler-render.mjs apps/web/wrangler.jsonc
           cp apps/web/wrangler.deploy.jsonc apps/web/wrangler.jsonc
           export PATH="$GITHUB_WORKSPACE/apps/web/node_modules/.bin:$GITHUB_WORKSPACE/node_modules/.bin:$PATH"
-          node scripts/ship-related-persons.mjs --work-db data/work/backfill.sqlite --remote --yes
+          # --min-links is passed EXPLICITLY, not left at its default of 50. Under #279 the surface is
+          # measured at ~329 links, so 50 no longer protects anything: a partially-restored Trade
+          # Register cache yields roughly 80 published links, which clears a floor of 50, ships a
+          # decimated surface and wipes the rest. The loader's coverage gate is the first defence and
+          # this is the second (ADR-0033 decision 7). Lower it deliberately, in a PR, if a genuinely
+          # smaller surface is ever expected.
+          node scripts/ship-related-persons.mjs --work-db data/work/backfill.sqlite --remote --yes \
+            --min-links 250
 
       - name: Reindex search projection → officials searchable (same batch the cron runs)
         # ship writes ONLY the свързани-лица domain tables (interest_links, persons, …), NOT search_index.

.github/workflows/scripts-test.yml

@@ -28,10 +28,11 @@ jobs:
       # so no `pnpm install` is required.
       - run: node --test scripts/*.test.mjs
 
-  # свързани-лица CACBG pipeline tests (parse/classify/load/audit/tr-census/extract). These use
-  # node:sqlite (DatabaseSync) and import the shared companyNameKey .ts via the register-ts resolve
-  # hook, so they need Node 24 (node:sqlite + native TS type-stripping, no experimental flag) rather
-  # than the Node 22 above. The libel-critical resolution logic gates merges here.
+  # свързани-лица pipeline tests — the CACBG leg (parse/classify/load/audit/extract) and the
+  # Търговски регистър leg (scripts/tr: ЕИК checksum, HTTP client, deed cache). These use node:sqlite
+  # (DatabaseSync) and import the shared companyNameKey .ts via the register-ts resolve hook, so they
+  # need Node 24 (node:sqlite + native TS type-stripping, no experimental flag) rather than the Node 22
+  # above. The libel-critical resolution logic gates merges here.
   cacbg:
     runs-on: ubuntu-latest
     timeout-minutes: 10
@@ -47,4 +48,6 @@ jobs:
       # parse.mjs imports fast-xml-parser (a workspace dep), so this job needs node_modules — unlike
       # the plain-node scripts above. Install before the scraper tests run.
       - run: pnpm install --frozen-lockfile
-      - run: node --import ./scripts/cacbg/register-ts.mjs --test scripts/cacbg/*.test.mjs
+      # Both legs, or the glob silently excludes a whole module: scripts/tr/*.test.mjs matched NO job
+      # until this line existed, so every test in it would have been decorative.
+      - run: node --import ./scripts/cacbg/register-ts.mjs --test scripts/cacbg/*.test.mjs scripts/tr/*.test.mjs

apps/web/app/components/ConflictCards.tsx

@@ -20,6 +20,7 @@ import {
   officialHref,
   partitionContracts,
   relationLabel,
+  registryEvidenceLabel,
   temporalLabel,
 } from '../lib/conflicts';
 
@@ -181,6 +182,21 @@ function ConflictCard({
               )}
             </dd>
           </div>
+          {/* The Trade Register fact the link's identity rests on (#279, ADR-0033). This is what makes
+              „every shown link explains itself" true rather than a promise: a reader can open the same act
+              we read and check it. The wording is careful — the register records a ROLE, it does not
+              certify the ownership claim, which comes from the official's own declaration. */}
+          <div className="cc-stat">
+            <dt>Регистър</dt>
+            <dd>
+              <ExternalEikLink eik={l.eik} />
+              <span className="small muted cc-evidence">
+                {registryEvidenceLabel(l)}
+                {l.registryEntryDate ? ` · вписване ${l.registryEntryDate}` : ''}
+                {l.registryLookupDate ? ` · справка ${l.registryLookupDate}` : ''}
+              </span>
+            </dd>
+          </div>
         </dl>
 
         {l.contractCount > 0 && (