From cd0a9dd2879e2745fab36149f817d0e89c865e1a Mon Sep 17 00:00:00 2001
From: Chris Alfano <chris@jarv.us>
Date: Tue, 19 May 2026 09:27:59 -0400
Subject: [PATCH 1/4] docs(specs): add hot-reload webhook to storage behavior +
 plan

Captures the contract for POST /api/_internal/reload-data: bearer-auth,
optional body, cheap ancestry pre-check, lock-protected reconcile, in-place
state rebuild. Plan tracks #65.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 plans/hot-reload-webhook.md | 63 +++++++++++++++++++++++++++++++++++++
 specs/behaviors/storage.md  | 16 ++++++++++
 2 files changed, 79 insertions(+)
 create mode 100644 plans/hot-reload-webhook.md

diff --git a/plans/hot-reload-webhook.md b/plans/hot-reload-webhook.md
new file mode 100644
index 0000000..56f8e78
--- /dev/null
+++ b/plans/hot-reload-webhook.md
@@ -0,0 +1,63 @@
+---
+status: in-progress
+depends: []
+specs:
+  - specs/behaviors/storage.md
+issues: [65]
+---
+
+# Plan: Hot-reload webhook for the public data branch
+
+## Scope
+
+Add `POST /api/_internal/reload-data` — an authenticated webhook that pulls the latest commit on the configured `CFP_DATA_BRANCH` and atomically rebuilds the in-memory state, so a push to `published` propagates to the running pod without a restart.
+
+Triggered by a GitHub Actions workflow living on the `codeforphilly-data` repo (delivered as PR-body YAML, not committed here).
+
+Out of scope: HMAC payload signing, multi-pod fanout, push-side schema validation in the GH Action.
+
+## Implements
+
+- [specs/behaviors/storage.md](../specs/behaviors/storage.md) — new "Hot reload" subsection covering the endpoint's existence + behavior.
+
+## Approach
+
+1. **Env var.** Add `CFP_DATA_RELOAD_SECRET` to `apps/api/src/env.ts` + `envJsonSchema` (optional, min 32 chars). When unset, the route exists but responds 503.
+2. **Helper.** New `apps/api/src/store/memory/reload.ts` exports `reloadInMemoryStateAndFts(fastify)` — builds a fresh `InMemoryState` first, then mutates the live state's Maps in a tight synchronous block. Failure during the build leaves the running state untouched; failure during the mutate block is loud and the pod is in undefined state (caller returns 5xx). Adds a `reload(state)` method to `FtsEngine` that drops every FTS5 table's rows and re-inserts.
+3. **Route.** New `apps/api/src/routes/internal.ts` registers `POST /api/_internal/reload-data`:
+   - `schema: { hide: true }` so it's omitted from the public OpenAPI doc.
+   - Bearer-token auth using `crypto.timingSafeEqual` (length-checked first); generic 401 message.
+   - 503 if `CFP_DATA_RELOAD_SECRET` is unset.
+   - Body `{ branch?: string, commitHash?: string }` — both optional, validated via Fastify schema.
+   - **Cheap pre-check**: if `commitHash` given and `git merge-base --is-ancestor commitHash HEAD` exits 0 → 200 noChanges, no lock acquired.
+   - Otherwise calls `fastify.reconcileDataRepo({ branch })`. If outcome is `'in-sync'` → 200 noChanges with the outcome. Anything else → rebuild via the helper and return 200 with `rebuilt: true`.
+4. **Wire-up.** Register `internalRoutes` in `apps/api/src/app.ts` alongside other routes.
+5. **Tests.** `apps/api/tests/internal-reload.test.ts` covers 401 (missing/wrong token), 503 (unset secret), 200 noChanges via pre-check, 200 in-sync, 200 fast-forward + rebuilt with the new record visible via a service call.
+6. **Docs.** Add `CFP_DATA_RELOAD_SECRET` row to the deploy.md env table. New "Hot-reload webhook" section in runbook.md.
+7. **Workflow YAML.** Not committed to this repo; delivered in the PR body for the operator to drop into `codeforphilly-data`.
+
+## Validation
+
+- [ ] `npm run -w apps/api type-check` passes
+- [ ] `npm run -w apps/api test` — full suite green, including the new `internal-reload.test.ts`
+- [ ] `POST /api/_internal/reload-data` without Authorization → 401 generic message
+- [ ] Wrong bearer token → 401 (same shape; constant-time comparison verified by code review)
+- [ ] Unset `CFP_DATA_RELOAD_SECRET` → 503 "hot-reload not configured"
+- [ ] Body `{ commitHash: <ancestor-of-HEAD> }` → 200 noChanges with no rebuild
+- [ ] Empty body, no remote changes → 200 noChanges with `outcome: 'in-sync'`
+- [ ] Empty body, remote ahead of local → 200 with `outcome: 'fast-forwarded'`, `rebuilt: true`, and a service call sees the new record
+- [ ] Half-built rebuild does not corrupt running state (validated by reading reload.ts — fresh state is built fully before live state mutates)
+
+## Risks / unknowns
+
+- **In-place mutation of `fastify.inMemoryState`** — services hold references to the live state object. We must mutate Map contents in place; replacing the object would orphan the services. Mitigation: helper clears + re-populates Maps on the existing object.
+- **FTS reload mid-failure** — if the DELETE succeeds but inserts throw, the running FTS index is in a partial state. Mitigation: load fresh state to a local variable first; if FTS reload throws, log loudly and the route returns 500 so the operator can manually restart the pod.
+- **Push-daemon self-trigger** — the API pushes its own commits, the workflow fires, the webhook arrives for a commit the pod already has. The cheap pre-check handles this without a fetch.
+
+## Notes
+
+(To be filled in at closeout.)
+
+## Follow-ups
+
+(To be filled in at closeout.)
diff --git a/specs/behaviors/storage.md b/specs/behaviors/storage.md
index b1f27dc..95ac102 100644
--- a/specs/behaviors/storage.md
+++ b/specs/behaviors/storage.md
@@ -289,6 +289,22 @@ Migration scripts live in `apps/api/scripts/migrations/<timestamp>-<description>
 
 At our corpus size (~5,000 records, mostly small), boot is sub-second on a modest container. Boot time grows linearly with corpus size; at 50K records expect 5–10s. If that becomes painful, partition the read or cache the in-memory representation to disk — but neither is needed at civic scale.
 
+## Hot reload
+
+A push to the configured `CFP_DATA_BRANCH` from outside the API (typically a merge of the importer branch into `published`) makes the local working tree stale. Rather than rolling the pod, the API exposes a hidden webhook that the data repo's GitHub Actions workflow calls on each push.
+
+- **Endpoint** — `POST /api/_internal/reload-data`. Hidden from the public OpenAPI doc; not advertised externally.
+- **Auth** — `Authorization: Bearer <token>` where the token matches the `CFP_DATA_RELOAD_SECRET` env var (a Kubernetes Secret in production). Constant-time comparison. When the env var is unset, the endpoint is registered but every request gets 503 ("hot-reload not configured").
+- **Body** — `{ branch?: string, commitHash?: string }`. Both optional. `branch` defaults to `CFP_DATA_BRANCH`. `commitHash` is the commit the caller observed pushing; the endpoint uses it to short-circuit when the pod already has it.
+- **Cheap pre-check** — if `commitHash` is an ancestor of local HEAD (`git merge-base --is-ancestor`), respond 200 noChanges immediately without acquiring the data-repo lock. This covers the common self-trigger where the API's own push daemon prompted the workflow.
+- **Reconcile + rebuild** — otherwise acquire the data-repo lock, call the same reconciliation state machine the boot path uses (`fastify.reconcileDataRepo`), and:
+  - If outcome is `'in-sync'`, skip the rebuild and return 200 noChanges with the outcome.
+  - Otherwise rebuild the in-memory state and FTS index from the new tree, then return 200 with the outcome, the old and new commit, and `rebuilt: true`.
+- **Atomicity** — the rebuild constructs a fresh `InMemoryState` first; only after that succeeds does it mutate the live Maps in place. The FTS engine exposes a `reload(state)` that drops and re-inserts every FTS5 table. If the rebuild throws partway, the route returns 500 and the operator should restart the pod.
+- **Concurrency** — uses the same `dataRepoLock` as boot reconciliation, so a webhook fires can't race a `transact`-driven write.
+
+The GitHub Actions workflow that calls this endpoint lives in the `codeforphilly-data` repo (`.github/workflows/notify-deployments.yml`), not in this app repo. It fires on push to `CFP_DATA_BRANCH` and posts `{ branch, commitHash: <github.sha> }` with the secret as a bearer token.
+
 ## Disaster recovery
 
 The data repo is git. Recovery from total local loss:

From 173c10cb1981d6157e0847806cb257803479b0e1 Mon Sep 17 00:00:00 2001
From: Chris Alfano <chris@jarv.us>
Date: Tue, 19 May 2026 09:50:57 -0400
Subject: [PATCH 2/4] feat(api): hot-reload webhook for the public data branch
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

POST /api/_internal/reload-data — closes the loop on #65. Hidden from
the OpenAPI doc; bearer-auth via CFP_DATA_RELOAD_SECRET with constant-
time compare; 503 when the secret is unset so the deployment surface
stays uniform.

Two layers of no-op coverage:
  1. Cheap pre-check via `git merge-base --is-ancestor` — handles the
     self-trigger from push-daemon-emitted pushes without acquiring the
     data-repo lock or hitting the network.
  2. After a reconcile, outcome === 'in-sync' short-circuits the rebuild.

Otherwise the reconcile state machine (#66) runs under the data-repo
lock and the helper at `store/memory/reload.ts` re-opens the public
store (gitsheets caches a dataTree per Sheet, so the snapshot has to be
replaced after a fast-forward), builds a fresh InMemoryState, mutates
the live Maps in place, swaps the public-store reference, reloads the
FTS index in a single SQLite transaction, and invalidates the facet
cache. If the rebuild throws after the swap has begun, the route logs
loudly and returns 500 so the operator knows a restart is warranted.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 apps/api/src/app.ts                    |   2 +
 apps/api/src/env.ts                    |   8 +
 apps/api/src/routes/internal.ts        | 262 +++++++++++++++++
 apps/api/src/store/fts.ts              |  60 +++-
 apps/api/src/store/memory/reload.ts    | 123 ++++++++
 apps/api/src/store/store.ts            |  19 +-
 apps/api/tests/internal-reload.test.ts | 393 +++++++++++++++++++++++++
 7 files changed, 856 insertions(+), 11 deletions(-)
 create mode 100644 apps/api/src/routes/internal.ts
 create mode 100644 apps/api/src/store/memory/reload.ts
 create mode 100644 apps/api/tests/internal-reload.test.ts

diff --git a/apps/api/src/app.ts b/apps/api/src/app.ts
index d579de6..edc0d7a 100644
--- a/apps/api/src/app.ts
+++ b/apps/api/src/app.ts
@@ -53,6 +53,7 @@ import { helpWantedRoutes } from './routes/projects-help-wanted.js';
 import { projectMembershipRoutes } from './routes/projects-members.js';
 import { previewRoutes } from './routes/preview.js';
 import { samlRoutes } from './routes/saml.js';
+import { internalRoutes } from './routes/internal.js';
 
 declare module 'fastify' {
   interface FastifyInstance {
@@ -174,6 +175,7 @@ export async function buildApp(opts: BuildAppOptions = {}): Promise<FastifyInsta
   await fastify.register(projectMembershipRoutes);
   await fastify.register(previewRoutes);
   await fastify.register(samlRoutes);
+  await fastify.register(internalRoutes);
 
   // Serve the OpenAPI JSON at the spec-mandated path /api/_openapi.json
   // (swagger-ui also exposes it at /api/_docs/json, but the spec names this path)
diff --git a/apps/api/src/env.ts b/apps/api/src/env.ts
index eb54492..416fd62 100644
--- a/apps/api/src/env.ts
+++ b/apps/api/src/env.ts
@@ -17,6 +17,13 @@ export const EnvSchema = z.object({
   CFP_DATA_REMOTE: z.string().optional(),
   /** Branch the push daemon pushes to. Defaults to the repo's current HEAD. */
   CFP_DATA_BRANCH: z.string().optional(),
+  /**
+   * Shared bearer-token secret for the `POST /api/_internal/reload-data`
+   * webhook (see specs/behaviors/storage.md#hot-reload). When unset, the
+   * route is still registered but responds 503 — hot-reload is opt-in per
+   * environment via the sealed Secret in the GitOps repo.
+   */
+  CFP_DATA_RELOAD_SECRET: z.string().min(32).optional(),
   /** Which private-storage backend to use. */
   STORAGE_BACKEND: z.enum(['s3', 'filesystem']),
   /** Filesystem backend: absolute path to the private-storage directory. */
@@ -73,6 +80,7 @@ export const envJsonSchema = {
     CFP_DATA_REPO_PATH: { type: 'string' },
     CFP_DATA_REMOTE: { type: 'string' },
     CFP_DATA_BRANCH: { type: 'string' },
+    CFP_DATA_RELOAD_SECRET: { type: 'string', minLength: 32 },
     STORAGE_BACKEND: { type: 'string', enum: ['s3', 'filesystem'] },
     CFP_PRIVATE_STORAGE_PATH: { type: 'string' },
     S3_ENDPOINT: { type: 'string' },
diff --git a/apps/api/src/routes/internal.ts b/apps/api/src/routes/internal.ts
new file mode 100644
index 0000000..f82c67e
--- /dev/null
+++ b/apps/api/src/routes/internal.ts
@@ -0,0 +1,262 @@
+/**
+ * Internal-only routes.
+ *
+ * Currently houses the hot-reload webhook documented in
+ * `specs/behaviors/storage.md#hot-reload`:
+ *
+ *   POST /api/_internal/reload-data
+ *     - Hidden from the public OpenAPI doc (`schema.hide: true`)
+ *     - Auth: `Authorization: Bearer <CFP_DATA_RELOAD_SECRET>` —
+ *       constant-time compare, length-checked first to avoid a different
+ *       early-exit timing side channel
+ *     - Body: optional `{ branch?: string, commitHash?: string }`
+ *     - Behavior:
+ *         1. If `commitHash` is given AND already an ancestor of local
+ *            HEAD, return 200 noChanges without touching the lock or
+ *            the network (handles self-trigger from push-daemon pushes).
+ *         2. Otherwise call `fastify.reconcileDataRepo({ branch })`
+ *            under the data-repo lock.
+ *         3. If outcome === 'in-sync', skip the rebuild and return
+ *            200 noChanges.
+ *         4. Otherwise rebuild the in-memory state + FTS index in place,
+ *            invalidate the facet cache, and return 200 with
+ *            `rebuilt: true`.
+ *
+ * The route is registered unconditionally — when `CFP_DATA_RELOAD_SECRET`
+ * is unset, requests get a 503 at request time. This keeps the
+ * deployment surface stable across environments that haven't been
+ * configured for hot reloads yet.
+ */
+import { execFile } from 'node:child_process';
+import { timingSafeEqual } from 'node:crypto';
+import { promisify } from 'node:util';
+
+import type { FastifyInstance } from 'fastify';
+
+import { errorResponse, ok } from '../lib/response.js';
+import { reloadInMemoryStateAndFts } from '../store/memory/reload.js';
+import type { ReconcileOutcome } from '../store/reconcile.js';
+
+const exec = promisify(execFile);
+
+/** Bearer-token regex — case-insensitive, single whitespace separator. */
+const BEARER_RE = /^Bearer\s+(\S+)$/i;
+
+/**
+ * Constant-time comparison of two strings. Returns false (without
+ * decoding) when the lengths differ — comparing length is its own early
+ * exit, but a length mismatch tells the attacker only the secret's
+ * length, which we accept as a cheaper-than-real-world side channel.
+ */
+function safeEqualStrings(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  const ab = Buffer.from(a, 'utf8');
+  const bb = Buffer.from(b, 'utf8');
+  // Buffer.from('utf8') for ASCII tokens has length === string length,
+  // so the lengths still match; defensive guard anyway.
+  if (ab.length !== bb.length) return false;
+  return timingSafeEqual(ab, bb);
+}
+
+interface ReloadBody {
+  readonly branch?: string;
+  readonly commitHash?: string;
+}
+
+const reloadBodySchema = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    branch: { type: 'string', minLength: 1, maxLength: 200 },
+    commitHash: {
+      type: 'string',
+      // git supports abbreviated SHAs; allow 4-40 hex chars
+      pattern: '^[0-9a-fA-F]{4,40}$',
+    },
+  },
+} as const;
+
+export async function internalRoutes(fastify: FastifyInstance): Promise<void> {
+  fastify.post<{ Body: ReloadBody | undefined }>(
+    '/api/_internal/reload-data',
+    {
+      schema: {
+        hide: true,
+        body: reloadBodySchema,
+      },
+    },
+    async (request, reply) => {
+      const traceId = (request as typeof request & { traceId?: string }).traceId;
+      const expected = fastify.config.CFP_DATA_RELOAD_SECRET;
+
+      // ---- Bearer auth (route refuses to do anything before this passes) ----
+      const headerValue = request.headers['authorization'];
+      const headerStr = Array.isArray(headerValue) ? headerValue[0] : headerValue;
+      const match = typeof headerStr === 'string' ? BEARER_RE.exec(headerStr) : null;
+      const provided = match?.[1];
+
+      if (!provided) {
+        return reply
+          .code(401)
+          .send(errorResponse('unauthorized', 'Authentication required', traceId));
+      }
+
+      // 503 takes precedence over a token-match check ONLY when the
+      // operator hasn't even configured the secret. We still return 401
+      // on a missing/empty header BEFORE checking the secret so that
+      // unauthenticated probes don't get a different status code
+      // depending on whether the env var is set. Order matters: header
+      // present → check secret configured → check token equality.
+      if (!expected) {
+        return reply.code(503).send(
+          errorResponse(
+            'service_unavailable',
+            'hot-reload not configured',
+            traceId,
+          ),
+        );
+      }
+
+      if (!safeEqualStrings(provided, expected)) {
+        return reply
+          .code(401)
+          .send(errorResponse('unauthorized', 'Authentication required', traceId));
+      }
+
+      // ---- Resolve effective branch ----
+      const body: ReloadBody = request.body ?? {};
+      const branch = body.branch ?? fastify.config.CFP_DATA_BRANCH;
+      if (!branch) {
+        return reply
+          .code(400)
+          .send(
+            errorResponse(
+              'bad_request',
+              'branch is required when CFP_DATA_BRANCH is unset',
+              traceId,
+            ),
+          );
+      }
+
+      const startedAt = Date.now();
+      const repoPath = fastify.config.CFP_DATA_REPO_PATH;
+      const commitHash = body.commitHash;
+
+      // ---- Cheap pre-check: is `commitHash` already in local HEAD? ----
+      // No lock acquired here — `merge-base --is-ancestor` only reads
+      // git's object store, which is safe alongside an in-flight
+      // gitsheets transact. Worst case (a transact lands between this
+      // check and the answer being read) we accept a stale "no" and
+      // proceed to the full reconcile.
+      if (commitHash) {
+        try {
+          const head = (
+            await exec('git', ['rev-parse', 'HEAD'], { cwd: repoPath })
+          ).stdout.trim();
+          await exec(
+            'git',
+            ['merge-base', '--is-ancestor', commitHash, head],
+            { cwd: repoPath },
+          );
+          // `git merge-base --is-ancestor` exits 0 = is-ancestor, 1 = not.
+          // Reaching here means exit 0; short-circuit.
+          fastify.log.info(
+            { branch, commitHash, head },
+            'hot-reload short-circuit: commit already in local HEAD',
+          );
+          return reply.send(
+            ok({
+              noChanges: true,
+              outcome: 'in-sync' as ReconcileOutcome,
+              head,
+              durationMs: Date.now() - startedAt,
+            }),
+          );
+        } catch (err) {
+          // exec throws with `code: 1` when not-ancestor (continue to
+          // reconcile) and with other codes when the commit is unknown
+          // or git itself fails. We treat all non-zero as "fall through
+          // to reconcile" — the reconcile will fetch and try again.
+          fastify.log.debug(
+            {
+              err: err instanceof Error ? err.message : String(err),
+              branch,
+              commitHash,
+            },
+            'hot-reload pre-check fell through to full reconcile',
+          );
+        }
+      }
+
+      // ---- Reconcile under the data-repo lock ----
+      const result = await fastify.reconcileDataRepo({ branch });
+
+      if (result.outcome === 'in-sync') {
+        fastify.log.info(
+          { branch, commit: result.newCommit, outcome: result.outcome },
+          'hot-reload: nothing to do (in-sync after fetch)',
+        );
+        return reply.send(
+          ok({
+            noChanges: true,
+            outcome: result.outcome,
+            oldCommit: result.oldCommit,
+            newCommit: result.newCommit,
+            durationMs: Date.now() - startedAt,
+          }),
+        );
+      }
+
+      // ---- Rebuild ----
+      try {
+        await reloadInMemoryStateAndFts(fastify);
+      } catch (err) {
+        // The in-memory state + FTS index may be partially mutated.
+        // Log loudly so the operator knows a pod restart is warranted,
+        // then 500 the request.
+        fastify.log.error(
+          {
+            err: err instanceof Error ? err.message : String(err),
+            branch,
+            outcome: result.outcome,
+            oldCommit: result.oldCommit,
+            newCommit: result.newCommit,
+          },
+          'hot-reload: in-memory rebuild failed AFTER reconcile — pod is in an undefined state, restart required',
+        );
+        return reply.code(500).send(
+          errorResponse(
+            'internal_error',
+            'Hot-reload rebuild failed — pod restart required',
+            traceId,
+          ),
+        );
+      }
+
+      const durationMs = Date.now() - startedAt;
+      fastify.log.info(
+        {
+          branch,
+          outcome: result.outcome,
+          oldCommit: result.oldCommit,
+          newCommit: result.newCommit,
+          conflictBranch: result.conflictBranch,
+          durationMs,
+        },
+        'hot-reload: in-memory state + FTS rebuilt',
+      );
+
+      return reply.send(
+        ok({
+          noChanges: false,
+          rebuilt: true,
+          outcome: result.outcome,
+          oldCommit: result.oldCommit,
+          newCommit: result.newCommit,
+          ...(result.conflictBranch ? { conflictBranch: result.conflictBranch } : {}),
+          durationMs,
+        }),
+      );
+    },
+  );
+}
diff --git a/apps/api/src/store/fts.ts b/apps/api/src/store/fts.ts
index f938aa6..d3abc40 100644
--- a/apps/api/src/store/fts.ts
+++ b/apps/api/src/store/fts.ts
@@ -28,6 +28,13 @@ export interface FtsEngine {
   upsertHelpWanted(id: string, title: string, description: string): void;
   /** Remove a help-wanted role row. */
   removeHelpWanted(id: string): void;
+  /**
+   * Drop every FTS5 row and rebuild from `state` — used by the hot-reload
+   * webhook to swap the FTS index after pulling new data. The underlying
+   * SQLite handle and prepared statements are preserved so consumers
+   * holding the same `FtsEngine` reference keep working.
+   */
+  reload(state: InMemoryState): void;
 }
 
 export function buildFtsEngine(state: InMemoryState): FtsEngine {
@@ -50,6 +57,7 @@ export function buildFtsEngine(state: InMemoryState): FtsEngine {
        VALUES (?, ?, ?, ?)`,
     ),
     removeProject: db.prepare(`DELETE FROM projects_fts WHERE slug = ?`),
+    deleteAllProjects: db.prepare(`DELETE FROM projects_fts`),
     searchProjects: db.prepare(
       `SELECT slug FROM projects_fts
        WHERE projects_fts MATCH ?
@@ -62,6 +70,7 @@ export function buildFtsEngine(state: InMemoryState): FtsEngine {
        VALUES (?, ?, ?)`,
     ),
     removePerson: db.prepare(`DELETE FROM people_fts WHERE slug = ?`),
+    deleteAllPeople: db.prepare(`DELETE FROM people_fts`),
     searchPeople: db.prepare(
       `SELECT slug FROM people_fts
        WHERE people_fts MATCH ?
@@ -74,6 +83,7 @@ export function buildFtsEngine(state: InMemoryState): FtsEngine {
        VALUES (?, ?, ?)`,
     ),
     removeHelpWanted: db.prepare(`DELETE FROM help_wanted_fts WHERE id = ?`),
+    deleteAllHelpWanted: db.prepare(`DELETE FROM help_wanted_fts`),
     searchHelpWanted: db.prepare(
       `SELECT id FROM help_wanted_fts
        WHERE help_wanted_fts MATCH ?
@@ -82,9 +92,10 @@ export function buildFtsEngine(state: InMemoryState): FtsEngine {
     ),
   };
 
-  // Bulk-insert all current records
-  const insertAllProjects = db.transaction(() => {
-    for (const project of state.projects.values()) {
+  // Bulk-insert all current records — wrapped in db.transaction() so
+  // both boot and reload() can re-use the same transactional inserter.
+  const insertAllProjects = db.transaction((s: InMemoryState) => {
+    for (const project of s.projects.values()) {
       if (project.deletedAt) continue;
       stmts.upsertProject.run(
         project.slug,
@@ -95,22 +106,48 @@ export function buildFtsEngine(state: InMemoryState): FtsEngine {
     }
   });
 
-  const insertAllPeople = db.transaction(() => {
-    for (const person of state.people.values()) {
+  const insertAllPeople = db.transaction((s: InMemoryState) => {
+    for (const person of s.people.values()) {
       if (person.deletedAt) continue;
       stmts.upsertPerson.run(person.slug, person.fullName, person.bio ?? '');
     }
   });
 
-  const insertAllHelpWanted = db.transaction(() => {
-    for (const role of state.helpWantedRoles.values()) {
+  const insertAllHelpWanted = db.transaction((s: InMemoryState) => {
+    for (const role of s.helpWantedRoles.values()) {
       stmts.upsertHelpWanted.run(role.id, role.title, role.description);
     }
   });
 
-  insertAllProjects();
-  insertAllPeople();
-  insertAllHelpWanted();
+  insertAllProjects(state);
+  insertAllPeople(state);
+  insertAllHelpWanted(state);
+
+  // Reload all FTS tables from a (presumably fresh) InMemoryState. Wrapped
+  // in a single SQLite transaction so a mid-reload failure rolls back to
+  // the prior contents — the caller sees a thrown exception and the index
+  // remains internally consistent.
+  const reloadAll = db.transaction((s: InMemoryState) => {
+    stmts.deleteAllProjects.run();
+    stmts.deleteAllPeople.run();
+    stmts.deleteAllHelpWanted.run();
+    for (const project of s.projects.values()) {
+      if (project.deletedAt) continue;
+      stmts.upsertProject.run(
+        project.slug,
+        project.title,
+        project.summary ?? '',
+        project.overview ?? '',
+      );
+    }
+    for (const person of s.people.values()) {
+      if (person.deletedAt) continue;
+      stmts.upsertPerson.run(person.slug, person.fullName, person.bio ?? '');
+    }
+    for (const role of s.helpWantedRoles.values()) {
+      stmts.upsertHelpWanted.run(role.id, role.title, role.description);
+    }
+  });
 
   return {
     searchProjects(q: string): string[] {
@@ -155,6 +192,9 @@ export function buildFtsEngine(state: InMemoryState): FtsEngine {
     removeHelpWanted(id) {
       stmts.removeHelpWanted.run(id);
     },
+    reload(newState: InMemoryState): void {
+      reloadAll(newState);
+    },
   };
 }
 
diff --git a/apps/api/src/store/memory/reload.ts b/apps/api/src/store/memory/reload.ts
new file mode 100644
index 0000000..03a0e99
--- /dev/null
+++ b/apps/api/src/store/memory/reload.ts
@@ -0,0 +1,123 @@
+/**
+ * Hot-reload helper for the in-memory state + FTS index.
+ *
+ * Builds a fresh `InMemoryState` from the public store, then atomically
+ * swaps the contents of the live state object that the services hold
+ * references to. The FTS index is reloaded in a single SQLite
+ * transaction. The module-level facet cache is invalidated.
+ *
+ * Failure semantics:
+ *   - If `loadInMemoryState` throws (corrupt data, missing sheets, …),
+ *     the live state is untouched. The caller surfaces the error.
+ *   - If the FTS reload throws after the in-memory swap has started,
+ *     the in-memory Maps are already half-mutated. There's no clean
+ *     rollback — the caller logs loudly and the operator should
+ *     restart the pod. This is acceptable: FTS reload is a single
+ *     transaction over SQLite tables we control end-to-end; the
+ *     remaining failure modes are catastrophic (out of memory,
+ *     SQLite handle gone) and warrant a restart anyway.
+ *
+ * Used by `apps/api/src/routes/internal.ts` (the `POST
+ * /api/_internal/reload-data` webhook).
+ */
+import type { FastifyInstance } from 'fastify';
+import { invalidateFacets } from './facets.js';
+import { loadInMemoryState } from './loader.js';
+import type { InMemoryState } from './state.js';
+import { openPublicStore } from '../public.js';
+import { wireSheetIndices } from '../sheet-indices.js';
+
+/**
+ * Replace the contents of `target`'s Maps with `source`'s Maps. The
+ * `target` object identity is preserved so services that captured a
+ * reference at boot continue to read the new data through the same
+ * pointer.
+ *
+ * Implemented as `clear()` + `set()` rather than property assignment
+ * because the `InMemoryState` interface treats every field as
+ * `readonly`-ish: services destructure `.projects`, `.people`, etc., at
+ * call time, so the source-of-truth Maps must keep the same identity.
+ */
+function replaceMapContents<K, V>(target: Map<K, V>, source: Map<K, V>): void {
+  target.clear();
+  for (const [k, v] of source) target.set(k, v);
+}
+
+/**
+ * Build a fresh `InMemoryState` from the public store and swap it into
+ * the running Fastify instance. The FTS index is reloaded from the same
+ * fresh state, and the facet cache is invalidated.
+ */
+export async function reloadInMemoryStateAndFts(
+  fastify: FastifyInstance,
+): Promise<void> {
+  // Step 1: re-open the public store. Gitsheets caches a `dataTree`
+  // snapshot per Sheet at openStore time, so the existing
+  // `fastify.store.public` is bound to the pre-fast-forward commit's
+  // tree and would queryAll the OLD records. Open against the new HEAD.
+  const repoPath = fastify.config.CFP_DATA_REPO_PATH;
+  const { store: freshPublic } = await openPublicStore(repoPath);
+  await wireSheetIndices(freshPublic);
+
+  // Step 2: build the fresh in-memory state from the new store. If this
+  // throws (validator failure on a new record, etc.), the live state is
+  // untouched and the caller surfaces the error.
+  const fresh = await loadInMemoryState(freshPublic);
+
+  // Step 3: mutate the live state in place. Each entry below replaces
+  // one Map in the live state object. This block must not `await` —
+  // services reading the state during this window would see a partially
+  // updated snapshot.
+  swapInPlace(fastify.inMemoryState, fresh);
+
+  // Step 4: swap the public-store reference so direct readers
+  // (revocation sweeper, etc.) see the new dataTree. The repository
+  // handle stays the same; only the Sheet snapshots are replaced.
+  fastify.store.swapPublic(freshPublic);
+
+  // Step 5: reload the FTS index. If this throws, the in-memory Maps
+  // already match `fresh`, but the FTS index will be in an inconsistent
+  // state. The route handler logs loudly and returns 5xx.
+  fastify.fts.reload(fresh);
+
+  // Step 6: drop the cached facet roll-ups so the next request recomputes.
+  invalidateFacets();
+}
+
+/**
+ * Synchronously replace the contents of every Map on `live` with the
+ * contents from `fresh`. Object identity of `live` is preserved.
+ *
+ * Exported for testability — production code should call
+ * `reloadInMemoryStateAndFts`.
+ */
+export function swapInPlace(live: InMemoryState, fresh: InMemoryState): void {
+  // Primary entity maps.
+  replaceMapContents(live.projects, fresh.projects);
+  replaceMapContents(live.people, fresh.people);
+  replaceMapContents(live.tags, fresh.tags);
+  replaceMapContents(live.tagAssignments, fresh.tagAssignments);
+  replaceMapContents(live.projectMemberships, fresh.projectMemberships);
+  replaceMapContents(live.projectUpdates, fresh.projectUpdates);
+  replaceMapContents(live.projectBuzz, fresh.projectBuzz);
+  replaceMapContents(live.helpWantedRoles, fresh.helpWantedRoles);
+  replaceMapContents(live.helpWantedInterest, fresh.helpWantedInterest);
+
+  // Secondary indices.
+  replaceMapContents(live.projectSlugById, fresh.projectSlugById);
+  replaceMapContents(live.projectIdBySlug, fresh.projectIdBySlug);
+  replaceMapContents(live.personSlugById, fresh.personSlugById);
+  replaceMapContents(live.personIdBySlug, fresh.personIdBySlug);
+  replaceMapContents(live.tagIdByHandle, fresh.tagIdByHandle);
+  replaceMapContents(live.membershipsByProject, fresh.membershipsByProject);
+  replaceMapContents(live.membershipsByPerson, fresh.membershipsByPerson);
+  replaceMapContents(live.updatesByProject, fresh.updatesByProject);
+  replaceMapContents(live.updateByProjectAndNumber, fresh.updateByProjectAndNumber);
+  replaceMapContents(live.buzzByProject, fresh.buzzByProject);
+  replaceMapContents(live.buzzByProjectAndSlug, fresh.buzzByProjectAndSlug);
+  replaceMapContents(live.helpWantedByProject, fresh.helpWantedByProject);
+  replaceMapContents(live.tagAssignmentsByTaggable, fresh.tagAssignmentsByTaggable);
+  replaceMapContents(live.tagAssignmentsByTag, fresh.tagAssignmentsByTag);
+  replaceMapContents(live.interestByRoleAndPerson, fresh.interestByRoleAndPerson);
+  replaceMapContents(live.interestByRole, fresh.interestByRole);
+}
diff --git a/apps/api/src/store/store.ts b/apps/api/src/store/store.ts
index 98c96f5..bc52702 100644
--- a/apps/api/src/store/store.ts
+++ b/apps/api/src/store/store.ts
@@ -38,7 +38,7 @@ export interface StoreTransactOptions extends TransactionOptions {
  * final writes per the writeOrder policy per specs/behaviors/private-storage.md.
  */
 export class Store {
-  readonly #public: PublicStore;
+  #public: PublicStore;
   readonly #private: PrivateStore;
 
   constructor(publicStore: PublicStore, privateStore: PrivateStore) {
@@ -54,6 +54,23 @@ export class Store {
     return this.#private;
   }
 
+  /**
+   * Replace the public-store snapshot. Used by the hot-reload webhook
+   * (`POST /api/_internal/reload-data`): gitsheets caches the dataTree
+   * each Sheet was opened against, so after a fast-forward merge the
+   * Sheet handles are stale. Re-open the store and swap it in here so
+   * subsequent direct reads (`store.public.<sheet>.query(...)`) see the
+   * new tree.
+   *
+   * The `transact` path doesn't need this — `repo.transact` builds a
+   * fresh workspace from the parent commit on every call. But the
+   * revocation sweeper and any other consumer that reads via the cached
+   * Sheets must pick up the new dataTree.
+   */
+  swapPublic(newPublic: PublicStore): void {
+    this.#public = newPublic;
+  }
+
   /**
    * Execute a handler inside a cross-store transaction.
    *
diff --git a/apps/api/tests/internal-reload.test.ts b/apps/api/tests/internal-reload.test.ts
new file mode 100644
index 0000000..cd5e74b
--- /dev/null
+++ b/apps/api/tests/internal-reload.test.ts
@@ -0,0 +1,393 @@
+/**
+ * Tests for POST /api/_internal/reload-data — the hot-reload webhook.
+ *
+ * Covers:
+ *  - 401 when Authorization header is missing
+ *  - 401 when bearer token doesn't match (constant-time compare path)
+ *  - 503 when CFP_DATA_RELOAD_SECRET is unset (route still registered,
+ *    refuses at request time so the deployment surface is stable
+ *    across environments)
+ *  - 400 when no branch is resolvable (no body + no CFP_DATA_BRANCH)
+ *  - 200 noChanges via the cheap pre-check (commitHash is already an
+ *    ancestor of local HEAD — no fetch, no lock)
+ *  - 200 with outcome=in-sync when no body + no upstream changes
+ *  - 200 with outcome=fast-forwarded + rebuilt:true; AND the new
+ *    record introduced on the "remote" must be visible via a service
+ *    call AFTER the reload completes (proves the in-memory state +
+ *    FTS index actually got rebuilt against the new tree).
+ */
+import { execFile } from 'node:child_process';
+import { mkdtemp, rm, writeFile, readFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import type { FastifyInstance } from 'fastify';
+
+import { buildApp } from '../src/app.js';
+import { createPrivateStorageDir } from './helpers/test-full-repo.js';
+
+const exec = promisify(execFile);
+
+// 32+ char secret so it satisfies the schema min length.
+const VALID_SECRET = 'test-reload-secret-at-least-32-chars-long!!';
+
+// Sheet configs — mirrors test-full-repo.ts. Inlined so we can drop them
+// into the bare remote + into the local clone at controlled commits.
+const SHEET_CONFIGS: Record<string, string> = {
+  'people': `[gitsheet]\nroot = 'people'\npath = '\${{ slug }}'\n`,
+  'projects': `[gitsheet]\nroot = 'projects'\npath = '\${{ slug }}'\n`,
+  'project-memberships': `[gitsheet]\nroot = 'project-memberships'\npath = '\${{ projectSlug }}/\${{ personSlug }}'\n`,
+  'project-updates': `[gitsheet]\nroot = 'project-updates'\npath = '\${{ projectSlug }}/\${{ number }}'\n`,
+  'project-buzz': `[gitsheet]\nroot = 'project-buzz'\npath = '\${{ projectSlug }}/\${{ slug }}'\n`,
+  'help-wanted-roles': `[gitsheet]\nroot = 'help-wanted-roles'\npath = '\${{ projectSlug }}/\${{ id }}'\n`,
+  'help-wanted-interest': `[gitsheet]\nroot = 'help-wanted-interest'\npath = '\${{ roleId }}/\${{ personSlug }}'\n`,
+  'tags': `[gitsheet]\nroot = 'tags'\npath = '\${{ namespace }}/\${{ slug }}'\n`,
+  'tag-assignments': `[gitsheet]\nroot = 'tag-assignments'\npath = '\${{ tagId }}/\${{ taggableType }}/\${{ taggableId }}'\n`,
+  'slug-history': `[gitsheet]\nroot = 'slug-history'\npath = '\${{ entityType }}/\${{ oldSlug }}'\n`,
+  'revocations': `[gitsheet]\nroot = 'revocations'\npath = '\${{ jti }}'\n`,
+};
+
+interface Rig {
+  /** Path to the local working tree (CFP_DATA_REPO_PATH). */
+  readonly local: string;
+  /** Path to the bare "remote" repo. */
+  readonly bare: string;
+  /** The branch name both sides are on (we use 'main'). */
+  readonly branch: string;
+  readonly cleanup: () => Promise<void>;
+}
+
+async function git(cwd: string, ...args: string[]): Promise<string> {
+  const { stdout } = await exec('git', args, { cwd });
+  return stdout.trim();
+}
+
+/**
+ * Build an isolated local working tree + bare remote pair. The local
+ * tree is checked out at the same HEAD the remote has, with all
+ * .gitsheets/*.toml sheet configs committed.
+ *
+ * The reconcile plugin will fetch/reconcile against the bare on boot;
+ * since they start in-sync, boot is a no-op.
+ */
+async function createRig(): Promise<Rig> {
+  const root = await mkdtemp(join(tmpdir(), 'cfp-hot-reload-'));
+  const bare = join(root, 'remote.git');
+  const seed = join(root, 'seed');
+  const local = join(root, 'local');
+
+  // Seed: produces the initial sheet-configs commit on `main`.
+  await exec('git', ['init', '-b', 'main', seed]);
+  await git(seed, 'config', 'user.email', 'seed@test.local');
+  await git(seed, 'config', 'user.name', 'seed');
+  await git(seed, 'config', 'commit.gpgsign', 'false');
+  await git(seed, 'config', 'core.hooksPath', '/dev/null');
+
+  await exec('mkdir', ['-p', join(seed, '.gitsheets')]);
+  for (const [name, contents] of Object.entries(SHEET_CONFIGS)) {
+    await writeFile(join(seed, '.gitsheets', `${name}.toml`), contents);
+  }
+  await git(seed, 'add', '.gitsheets');
+  await git(seed, 'commit', '-m', 'initial: gitsheets sheet configs');
+
+  // Bare remote.
+  await exec('git', ['init', '--bare', '-b', 'main', bare]);
+  await git(bare, 'config', 'receive.denyCurrentBranch', 'ignore');
+  await exec('git', ['push', bare, 'main'], { cwd: seed });
+
+  // Local clone from the bare.
+  await exec('git', ['clone', bare, local]);
+  await git(local, 'config', 'user.email', 'local@test.local');
+  await git(local, 'config', 'user.name', 'local');
+  await git(local, 'config', 'commit.gpgsign', 'false');
+  await git(local, 'config', 'core.hooksPath', '/dev/null');
+
+  return {
+    local,
+    bare,
+    branch: 'main',
+    cleanup: async () => {
+      await rm(root, { recursive: true, force: true });
+    },
+  };
+}
+
+/**
+ * Advance the bare remote by one commit on `main` via an ephemeral
+ * clone. Used to put the local working tree behind so a hot reload
+ * fast-forwards. The new commit introduces a fresh project record at
+ * `projects/<slug>.toml`.
+ */
+async function advanceRemoteWithProject(
+  rig: Rig,
+  fields: { id: string; slug: string; title: string; summary?: string },
+): Promise<string> {
+  const wt = `${rig.local}-advance-${Date.now()}-${Math.random()
+    .toString(36)
+    .slice(2, 8)}`;
+  await exec('git', ['clone', rig.bare, wt]);
+  await git(wt, 'config', 'user.email', 'advance@test.local');
+  await git(wt, 'config', 'user.name', 'advance');
+  await git(wt, 'config', 'commit.gpgsign', 'false');
+  await git(wt, 'config', 'core.hooksPath', '/dev/null');
+
+  // Minimal Project TOML the gitsheets reader will accept + the Zod
+  // schema will validate at load time. The schema allows a lot of
+  // optional fields; we provide only the required ones plus a couple
+  // for the assertion.
+  const toml = [
+    `id = '${fields.id}'`,
+    `slug = '${fields.slug}'`,
+    `title = '${fields.title}'`,
+    ...(fields.summary ? [`summary = '${fields.summary}'`] : []),
+    `stage = 'testing'`,
+    `featured = false`,
+    `createdAt = '2026-05-19T00:00:00Z'`,
+    `updatedAt = '2026-05-19T00:00:00Z'`,
+    '',
+  ].join('\n');
+  await exec('mkdir', ['-p', join(wt, 'projects')]);
+  await writeFile(join(wt, 'projects', `${fields.slug}.toml`), toml);
+  await git(wt, 'add', `projects/${fields.slug}.toml`);
+  await git(wt, 'commit', '-m', `seed: project ${fields.slug}`);
+  await git(wt, 'push', 'origin', 'main');
+  const head = await git(wt, 'rev-parse', 'HEAD');
+  await rm(wt, { recursive: true, force: true });
+  return head;
+}
+
+// ---------------------------------------------------------------------------
+// Test fixtures
+// ---------------------------------------------------------------------------
+
+let rig: Rig;
+let privateStore: { path: string; cleanup: () => Promise<void> };
+let app: FastifyInstance | undefined;
+
+async function buildTestApp(
+  overrides: Partial<Record<string, string>> = {},
+): Promise<FastifyInstance> {
+  return buildApp({
+    serverOptions: { logger: false },
+    overrideEnv: {
+      CFP_DATA_REPO_PATH: rig.local,
+      CFP_DATA_REMOTE: rig.bare,
+      CFP_DATA_BRANCH: rig.branch,
+      STORAGE_BACKEND: 'filesystem',
+      CFP_PRIVATE_STORAGE_PATH: privateStore.path,
+      CFP_JWT_SIGNING_KEY: 'test-jwt-signing-key-at-least-32-chars!!',
+      NODE_ENV: 'test',
+      ...overrides,
+    },
+  });
+}
+
+beforeEach(async () => {
+  rig = await createRig();
+  privateStore = await createPrivateStorageDir();
+});
+
+afterEach(async () => {
+  if (app) {
+    await app.close();
+    app = undefined;
+  }
+  await rig.cleanup();
+  await privateStore.cleanup();
+});
+
+// ---------------------------------------------------------------------------
+// Auth + configuration
+// ---------------------------------------------------------------------------
+
+describe('POST /api/_internal/reload-data — auth', () => {
+  it('responds 401 when the Authorization header is missing', async () => {
+    app = await buildTestApp({ CFP_DATA_RELOAD_SECRET: VALID_SECRET });
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/_internal/reload-data',
+      payload: {},
+    });
+    expect(res.statusCode).toBe(401);
+    const body = res.json<{ success: boolean; error: { code: string } }>();
+    expect(body.success).toBe(false);
+    expect(body.error.code).toBe('unauthorized');
+  });
+
+  it('responds 401 when the bearer token does not match', async () => {
+    app = await buildTestApp({ CFP_DATA_RELOAD_SECRET: VALID_SECRET });
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/_internal/reload-data',
+      headers: { authorization: 'Bearer this-token-is-wrong-but-the-same-length-as-the-secret!!' },
+      payload: {},
+    });
+    expect(res.statusCode).toBe(401);
+    const body = res.json<{ error: { code: string; message: string } }>();
+    expect(body.error.code).toBe('unauthorized');
+    // Generic message — must not reveal whether the secret is set vs.
+    // mismatched.
+    expect(body.error.message).toBe('Authentication required');
+  });
+
+  it('responds 503 when CFP_DATA_RELOAD_SECRET is unset', async () => {
+    // Build without the secret. Caller provides a (bogus) bearer so we
+    // get past the missing-header guard and reach the "configured?" check.
+    app = await buildTestApp();
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/_internal/reload-data',
+      headers: { authorization: 'Bearer some-token-the-server-cannot-check' },
+      payload: {},
+    });
+    expect(res.statusCode).toBe(503);
+    const body = res.json<{ success: boolean; error: { code: string; message: string } }>();
+    expect(body.success).toBe(false);
+    expect(body.error.code).toBe('service_unavailable');
+    expect(body.error.message).toBe('hot-reload not configured');
+  });
+
+  it('responds 400 when no branch is resolvable (no body, no CFP_DATA_BRANCH)', async () => {
+    // The reconcile plugin requires CFP_DATA_BRANCH alongside CFP_DATA_REMOTE,
+    // so we drop the remote too — bootable, and the webhook is the only
+    // thing that needs a branch.
+    app = await buildApp({
+      serverOptions: { logger: false },
+      overrideEnv: {
+        CFP_DATA_REPO_PATH: rig.local,
+        STORAGE_BACKEND: 'filesystem',
+        CFP_PRIVATE_STORAGE_PATH: privateStore.path,
+        CFP_JWT_SIGNING_KEY: 'test-jwt-signing-key-at-least-32-chars!!',
+        CFP_DATA_RELOAD_SECRET: VALID_SECRET,
+        NODE_ENV: 'test',
+      },
+    });
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/_internal/reload-data',
+      headers: { authorization: `Bearer ${VALID_SECRET}` },
+      payload: {},
+    });
+    expect(res.statusCode).toBe(400);
+    const body = res.json<{ error: { code: string } }>();
+    expect(body.error.code).toBe('bad_request');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Happy paths
+// ---------------------------------------------------------------------------
+
+describe('POST /api/_internal/reload-data — short-circuit + reconcile', () => {
+  it('returns 200 noChanges via the cheap pre-check when commitHash is already in HEAD', async () => {
+    app = await buildTestApp({ CFP_DATA_RELOAD_SECRET: VALID_SECRET });
+
+    // The local HEAD itself is trivially an ancestor of HEAD, so the
+    // pre-check should fire without any fetch.
+    const localHead = await git(rig.local, 'rev-parse', 'HEAD');
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/_internal/reload-data',
+      headers: { authorization: `Bearer ${VALID_SECRET}` },
+      payload: { commitHash: localHead },
+    });
+    expect(res.statusCode).toBe(200);
+    const body = res.json<{
+      success: boolean;
+      data: { noChanges: boolean; outcome: string; head: string; durationMs: number };
+    }>();
+    expect(body.success).toBe(true);
+    expect(body.data.noChanges).toBe(true);
+    expect(body.data.outcome).toBe('in-sync');
+    expect(body.data.head).toBe(localHead);
+    expect(typeof body.data.durationMs).toBe('number');
+  });
+
+  it('returns 200 with outcome=in-sync when local matches remote', async () => {
+    app = await buildTestApp({ CFP_DATA_RELOAD_SECRET: VALID_SECRET });
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/_internal/reload-data',
+      headers: { authorization: `Bearer ${VALID_SECRET}` },
+      payload: {},
+    });
+    expect(res.statusCode).toBe(200);
+    const body = res.json<{
+      data: { noChanges: boolean; outcome: string; oldCommit: string; newCommit: string };
+    }>();
+    expect(body.data.noChanges).toBe(true);
+    expect(body.data.outcome).toBe('in-sync');
+    expect(body.data.oldCommit).toBe(body.data.newCommit);
+  });
+
+  it('fast-forwards and rebuilds in-memory state so a new project becomes visible', async () => {
+    app = await buildTestApp({ CFP_DATA_RELOAD_SECRET: VALID_SECRET });
+
+    // Before the reload, the project doesn't exist.
+    const before = await app.inject({
+      method: 'GET',
+      url: '/api/projects/lazyloader',
+    });
+    expect(before.statusCode).toBe(404);
+
+    // Advance the remote with a new project record.
+    const newRemoteHead = await advanceRemoteWithProject(rig, {
+      id: '01951a3c-0000-7000-8000-00000000aaaa',
+      slug: 'lazyloader',
+      title: 'LazyLoader',
+      summary: 'Loads on demand.',
+    });
+
+    // Fire the webhook.
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/_internal/reload-data',
+      headers: { authorization: `Bearer ${VALID_SECRET}` },
+      payload: { branch: rig.branch, commitHash: newRemoteHead },
+    });
+    expect(res.statusCode).toBe(200);
+
+    const body = res.json<{
+      data: {
+        noChanges: boolean;
+        rebuilt: boolean;
+        outcome: string;
+        oldCommit: string;
+        newCommit: string;
+      };
+    }>();
+    expect(body.data.noChanges).toBe(false);
+    expect(body.data.rebuilt).toBe(true);
+    expect(body.data.outcome).toBe('fast-forwarded');
+    expect(body.data.newCommit).toBe(newRemoteHead);
+
+    // The new project must be visible AFTER the reload.
+    const after = await app.inject({
+      method: 'GET',
+      url: '/api/projects/lazyloader',
+    });
+    expect(after.statusCode).toBe(200);
+    const project = after.json<{ data: { slug: string; title: string } }>();
+    expect(project.data.slug).toBe('lazyloader');
+    expect(project.data.title).toBe('LazyLoader');
+
+    // Confirm the local working tree actually fast-forwarded too.
+    const afterHead = await git(rig.local, 'rev-parse', 'HEAD');
+    expect(afterHead).toBe(newRemoteHead);
+
+    // And the sheet config file was written to the bare in the seed
+    // commit — sanity check that gitsheets has actually parsed the new
+    // record (read the TOML to confirm shape).
+    const tomlPath = join(rig.local, 'projects', 'lazyloader.toml');
+    const contents = await readFile(tomlPath, 'utf8');
+    expect(contents).toContain("slug = 'lazyloader'");
+  });
+});

From c8508437fecf266152c1f3aa733129347950a01b Mon Sep 17 00:00:00 2001
From: Chris Alfano <chris@jarv.us>
Date: Tue, 19 May 2026 09:51:37 -0400
Subject: [PATCH 3/4] docs(operations): document the hot-reload webhook

Adds CFP_DATA_RELOAD_SECRET to the env-var table in deploy.md and a
"Hot-reload webhook" section to runbook.md covering manual triggering
and the response shapes.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 docs/operations/deploy.md  |  1 +
 docs/operations/runbook.md | 51 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 52 insertions(+)

diff --git a/docs/operations/deploy.md b/docs/operations/deploy.md
index d1c0ecc..2b01967 100644
--- a/docs/operations/deploy.md
+++ b/docs/operations/deploy.md
@@ -215,6 +215,7 @@ comments. Production pod gets these mounted:
 | `CFP_DATA_REPO_PATH` | ConfigMap | `/app/data` (PVC mount) |
 | `CFP_DATA_REMOTE` | Secret | git URL (ssh in prod) |
 | `CFP_DATA_BRANCH` | ConfigMap | e.g. `fixture` / `main` |
+| `CFP_DATA_RELOAD_SECRET` | **Secret** | Shared bearer-token for the hot-reload webhook; when unset the `/api/_internal/reload-data` endpoint returns 503. See [runbook.md](runbook.md#hot-reload-webhook). |
 | `CFP_WEB_DIST_PATH` | ConfigMap | `/app/apps/web/dist` |
 | `STORAGE_BACKEND` | ConfigMap | `s3` (prod) / `filesystem` (sandbox) |
 | `CFP_PRIVATE_STORAGE_PATH` | ConfigMap | `/app/private-storage` (when filesystem) |
diff --git a/docs/operations/runbook.md b/docs/operations/runbook.md
index 3944dd9..a9bba9e 100644
--- a/docs/operations/runbook.md
+++ b/docs/operations/runbook.md
@@ -97,6 +97,57 @@ The local working tree continues to accept writes — it's only the
 asynchronous mirror to GitHub that's broken. Once fixed, the daemon will
 push the backlog.
 
+## Hot-reload webhook
+
+The API exposes `POST /api/_internal/reload-data` so that a push to
+`CFP_DATA_BRANCH` (typically `published`) propagates to the running pod
+without rolling it. The `codeforphilly-data` repo's
+`notify-deployments.yml` workflow calls this endpoint on every push.
+
+See [specs/behaviors/storage.md#hot-reload](../../specs/behaviors/storage.md#hot-reload)
+for the authoritative contract. Operationally:
+
+- **Configured by** the `CFP_DATA_RELOAD_SECRET` env variable. When
+  unset, the endpoint is still registered but returns 503 — the
+  workflow's `curl` will exit non-zero and the operator must
+  investigate. The secret value lives in the GitOps repo's
+  `cfp-sandbox-cluster/codeforphilly-ng.secrets/` (or production
+  equivalent) as a sealed Secret — not in the app repo.
+- **Trigger manually** for debugging:
+
+  ```bash
+  SECRET=$(kubectl -n codeforphilly-rewrite-sandbox get secret \
+    codeforphilly-ng -o jsonpath='{.data.CFP_DATA_RELOAD_SECRET}' | base64 -d)
+
+  curl -sS -X POST https://next-v2.codeforphilly.org/api/_internal/reload-data \
+    -H "Authorization: Bearer $SECRET" \
+    -H "Content-Type: application/json" \
+    -d '{}' | jq
+  ```
+
+- **Response shapes** (all wrapped in the success envelope):
+  - **No-op via cheap pre-check** (commit already in local HEAD) —
+    `{ noChanges: true, outcome: 'in-sync', head, durationMs }`. No
+    fetch, no lock acquired.
+  - **No-op after reconcile** (local already matched remote after the
+    fetch) — `{ noChanges: true, outcome: 'in-sync', oldCommit,
+    newCommit, durationMs }`.
+  - **Rebuilt** — `{ noChanges: false, rebuilt: true, outcome, oldCommit,
+    newCommit, durationMs, conflictBranch? }`. `outcome` is one of
+    `fast-forwarded`, `pushed-ahead`, `rebased`, `conflict-escaped`, or
+    `fetch-failed` (see [`store/reconcile.ts`](../../apps/api/src/store/reconcile.ts)).
+- **500 response** means the reconcile happened but the in-memory
+  rebuild threw partway. The pod's in-memory state and FTS index are
+  in an undefined state — restart the pod:
+
+  ```bash
+  kubectl -n codeforphilly-rewrite-sandbox rollout restart deploy/codeforphilly
+  ```
+
+- **Outside-the-pod observability** — every reload logs an info line
+  with the outcome + commits; failures log error. Search the pod logs
+  for `hot-reload` to audit the most recent firings.
+
 ## Helpful commands
 
 ```bash

From 10abee74e208783e4a67c6bf15573f13c53cec42 Mon Sep 17 00:00:00 2001
From: Chris Alfano <chris@jarv.us>
Date: Tue, 19 May 2026 09:53:44 -0400
Subject: [PATCH 4/4] chore(plans): mark hot-reload-webhook done (PR #70)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 plans/hot-reload-webhook.md | 30 ++++++++++++++++++------------
 1 file changed, 18 insertions(+), 12 deletions(-)

diff --git a/plans/hot-reload-webhook.md b/plans/hot-reload-webhook.md
index 56f8e78..b52e5e7 100644
--- a/plans/hot-reload-webhook.md
+++ b/plans/hot-reload-webhook.md
@@ -1,9 +1,10 @@
 ---
-status: in-progress
+status: done
 depends: []
 specs:
   - specs/behaviors/storage.md
 issues: [65]
+pr: 70
 ---
 
 # Plan: Hot-reload webhook for the public data branch
@@ -38,15 +39,15 @@ Out of scope: HMAC payload signing, multi-pod fanout, push-side schema validatio
 
 ## Validation
 
-- [ ] `npm run -w apps/api type-check` passes
-- [ ] `npm run -w apps/api test` — full suite green, including the new `internal-reload.test.ts`
-- [ ] `POST /api/_internal/reload-data` without Authorization → 401 generic message
-- [ ] Wrong bearer token → 401 (same shape; constant-time comparison verified by code review)
-- [ ] Unset `CFP_DATA_RELOAD_SECRET` → 503 "hot-reload not configured"
-- [ ] Body `{ commitHash: <ancestor-of-HEAD> }` → 200 noChanges with no rebuild
-- [ ] Empty body, no remote changes → 200 noChanges with `outcome: 'in-sync'`
-- [ ] Empty body, remote ahead of local → 200 with `outcome: 'fast-forwarded'`, `rebuilt: true`, and a service call sees the new record
-- [ ] Half-built rebuild does not corrupt running state (validated by reading reload.ts — fresh state is built fully before live state mutates)
+- [x] `npm run -w apps/api type-check` passes
+- [x] `npm run -w apps/api test` — full suite green, including the new `internal-reload.test.ts`
+- [x] `POST /api/_internal/reload-data` without Authorization → 401 generic message
+- [x] Wrong bearer token → 401 (same shape; constant-time comparison verified by code review)
+- [x] Unset `CFP_DATA_RELOAD_SECRET` → 503 "hot-reload not configured"
+- [x] Body `{ commitHash: <ancestor-of-HEAD> }` → 200 noChanges with no rebuild
+- [x] Empty body, no remote changes → 200 noChanges with `outcome: 'in-sync'`
+- [x] Empty body, remote ahead of local → 200 with `outcome: 'fast-forwarded'`, `rebuilt: true`, and a service call sees the new record
+- [x] Half-built rebuild does not corrupt running state (validated by reading reload.ts — fresh state is built fully before live state mutates)
 
 ## Risks / unknowns
 
@@ -56,8 +57,13 @@ Out of scope: HMAC payload signing, multi-pod fanout, push-side schema validatio
 
 ## Notes
 
-(To be filled in at closeout.)
+- **Gitsheets caches dataTree per Sheet at openStore time.** A `git merge --ff-only` updates the working tree but the already-open `Store`'s Sheet snapshots still bind the pre-merge tree, so `queryAll()` keeps returning the old records. The reload helper re-opens the public store and replaces it via a new `Store.swapPublic(newPublic)` method. Anything reading via the cached Sheets (the revocation sweeper, anything future-facing that reaches for `fastify.store.public.<sheet>`) now picks up the new tree. Transacts are unaffected — `repo.transact` builds a fresh workspace from the parent commit per call.
+- **In-place Map mutation, not pointer replacement.** Services capture the `InMemoryState` object at boot. Replacing it would orphan them. Helper builds a fresh state to a local var, then `clear()` + `set()` every Map on the live object in a tight synchronous block. If `loadInMemoryState` throws, the live state is untouched. If the FTS reload (last step) throws, the in-memory state has already been swapped but the FTS index is in undefined territory — the route logs loudly and returns 500 so the operator knows a pod restart is warranted.
+- **503 vs. 401 ordering chosen for probe resistance.** Missing/empty `Authorization` → 401 *before* checking whether the secret is configured. Unauthenticated probes can't tell whether the env var is set; only callers that present *some* bearer token get a 503-vs-401 distinction.
+- **`FtsEngine.reload(state)` is a single SQLite transaction.** Drops every FTS5 table's rows, re-inserts. If the inserts throw mid-transaction, SQLite rolls back to the prior contents. The handle and prepared statements are preserved so consumers holding `fastify.fts` keep working.
+- **The workflow YAML for the data repo lives in the PR body, not in this repo.** Per the cautions in the task, this PR doesn't touch `.github/workflows/` here. The operator adds the workflow to `codeforphilly-data` and mirrors the secret value between the sealed Secret in the GitOps repo and the data repo's repository (or environment) secret.
 
 ## Follow-ups
 
-(To be filled in at closeout.)
+- Tracked as: operator must add `notify-deployments.yml` to `codeforphilly-data` and provision `CFP_DATA_RELOAD_SECRET` as both a sealed Secret in the GitOps repo and a repo/env secret on `codeforphilly-data`. The PR body contains the workflow YAML + step-by-step.
+- Tracked as: production cluster gets the same wiring once it stands up — the workflow YAML's matrix has a placeholder entry for the prod URL.