@everystack/server 0.4.27 → 0.4.28

package/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to `@everystack/server` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.4.28] - 2026-09-02
+
+### Added
+
+- wire proveDescent into db:apply — ledger read shares the lock session
+- retire --force-descent for the git-native escape + a proven-lineage-lost attestation
+- the stage lane's fast-forward rule is structurally non-droppable (q1-fail-closed)
+- version the db:apply wire contract, both directions (q1-contract-version)
+
+### Fixed
+
+- split-brain belt + correct the version-skew remedy (closing gate)
+
+### Changed
+
+- delete the orphaned recompile-descent helpers, rewire the illusion of coverage (F1)
+
 ## [0.4.26] - 2026-08-15
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/server",
-  "version": "0.4.27",
+  "version": "0.4.28",
   "description": "Server runtime primitives for Lambda — event adapters, routing, SSR, image processing",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -187,7 +187,7 @@
     "sst": "4.13.1",
     "ts-jest": "29.4.9",
     "typescript": "5.9.3",
-    "@everystack/cli": "0.4.67",
+    "@everystack/cli": "0.4.70",
     "@everystack/auth": "0.4.4"
   },
   "scripts": {

package/src/plugin.ts

@@ -12,6 +12,18 @@ import type {
   APIGatewayProxyEventV2,
   APIGatewayProxyStructuredResultV2,
 } from 'aws-lambda';
+import type { ApplyPlanOptions } from '@everystack/cli/apply';
+
+/**
+ * The stage lane's apply options, with `checkDescent` made REQUIRED. The fast-forward rule is the
+ * one gate that crosses the wire on every stage apply (additive included); typing it non-optional
+ * here forbids the conditional spread that once let a missing descent verdict silently skip it.
+ * verifyAuthority/verifySnapshot stay optional — they are destructive-only, and the stage lane
+ * refuses destructive plans outright, so they never arise on this lane.
+ */
+type StageApplyOptions = ApplyPlanOptions & {
+  checkDescent: NonNullable<ApplyPlanOptions['checkDescent']>;
+};
 import {
   createRouter,
   eventToRequest,
@@ -191,11 +203,17 @@ export function createPluginLambdaHandler(
       // the action lookup (it must answer even when initialization itself is the failure) and
       // reserved: an app action named `_health` is never reached.
       if (event._action === '_health') {
+        // q1-contract-version direction B: advertise the db:apply wire-contract version so a NEWER
+        // CLI detects an OLDER deployed stage BEFORE it dispatches a write (prevention, not a
+        // post-write alarm). Stamped on BOTH branches, so a stage whose DB init is failing still
+        // tells the CLI its contract — an absent field means the deployed server predates the
+        // handshake. Old servers simply omit it; the CLI reads absent as "redeploy the stage".
+        const { APPLY_CONTRACT_VERSION } = await import('@everystack/cli/apply');
         try {
           const { actions } = await ensureInitialized();
-          return { ok: true, mode: httpEnabled ? 'http' : 'ops', actions: Object.keys(actions).sort() };
+          return { ok: true, mode: httpEnabled ? 'http' : 'ops', actions: Object.keys(actions).sort(), applyContract: APPLY_CONTRACT_VERSION };
         } catch (error) {
-          return { ok: false, error: String(error) };
+          return { ok: false, error: String(error), applyContract: APPLY_CONTRACT_VERSION };
         }
       }
       const { ctx, actions } = await ensureInitialized();
@@ -958,12 +976,21 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
     // direct --database-url path runs, only here the connection never leaves the
     // Lambda. A destructive plan snapshots first (db:backup), in order.
     actions['db:apply'] = async (payload, ctx) => {
-      const { plan, actor, gitRef, descentVerdict, authorityVerdict, stage, snapshotRef } =
+      const { plan, contractVersion, actor, gitRef, dirty, descentVerdict, descentAttested, authorityVerdict, stage, snapshotRef } =
         (payload ?? {}) as {
           plan?: any;
+          /** The CLI's db:apply wire-contract version. Checked for EXACT equality against this
+           *  server's APPLY_CONTRACT_VERSION — a skew refuses before any write (direction A). */
+          contractVersion?: number;
           actor?: string | null;
           gitRef?: string | null;
+          /** The CLI applied from a dirty worktree — recorded on the schema_log witness so a
+           *  later descent ignores this row's git_ref. */
+          dirty?: boolean;
           descentVerdict?: { ok: boolean; reason?: string };
+          /** When the CLI honoured a --attest-lineage-lost waiver, the note to record in the
+           *  schema_log outcome — the durable audit of the deliberate descent waiver. */
+          descentAttested?: string;
           authorityVerdict?: { ok: boolean; reason?: string };
           stage?: string;
           /** An explicit backup id to verify; absent → the gate auto-resolves the stage's newest. */
@@ -972,10 +999,29 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
       if (!plan || typeof plan !== 'object' || !Array.isArray(plan.statements)) {
         return { error: 'db:apply requires { plan } — a reviewed edge minted by db:plan' };
       }
-      const { executeApplyPlan, PLAN_VERSION } = await import('@everystack/cli/apply');
+      const { executeApplyPlan, PLAN_VERSION, APPLY_CONTRACT_VERSION } = await import('@everystack/cli/apply');
       if (plan.v !== PLAN_VERSION) {
         return { error: `plan version ${plan.v} is not this server's ${PLAN_VERSION} — re-mint with a matching db:plan` };
       }
+      // q1-contract-version direction A: the db:apply WIRE CONTRACT (payload keys + the gates this
+      // server runs from them) is versioned apart from the plan. An exact-equality mismatch — an
+      // older CLI that declares none, or a bumped one — refuses before any write, so a renamed or
+      // dropped payload key can never ride through as a silently skipped gate. Redeploying the
+      // stage's ops Lambda ships the matching cli it bundles, so the versions realign together.
+      if (contractVersion !== APPLY_CONTRACT_VERSION) {
+        // This fires only for an OLDER CLI: a current CLI catches the skew at the _health handshake and
+        // never dispatches. So the remedy leads with upgrading the CLI, not redeploying the (current) stage.
+        return { error: `this db:apply payload declares apply-contract v${contractVersion ?? '(none)'} but this stage's ops Lambda enforces v${APPLY_CONTRACT_VERSION} — your everystack CLI is older than the deployed stage. Upgrade the CLI to match (or, if the stage was rolled back, redeploy it); nothing was applied.` };
+      }
+      // q1-fail-closed: descent (the fast-forward rule) is the one gate that crosses the wire on
+      // EVERY stage apply, additive included. It is NOT waivable by omission. A payload with no
+      // well-formed descent verdict is an older CLI or a malformed client — refuse before any write,
+      // never silently skip the rule. (The conditional-spread that let a missing verdict skip
+      // checkDescent was the INFO-1 bug; StageApplyOptions now forbids dropping the hook, and this
+      // guards the evidence that feeds it.)
+      if (!descentVerdict || typeof descentVerdict.ok !== 'boolean') {
+        return { error: 'this db:apply payload carries no descent verdict — the fast-forward rule cannot be waived by omission. Upgrade the everystack CLI (an older CLI omits it), or this is a client bug.' };
+      }
 
       const { sql } = await import('drizzle-orm');
       const runner = async (query: string): Promise<any[]> => {
@@ -995,14 +1041,17 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
       const SNAPSHOT_FRESHNESS_MS = 60 * 60_000;
       let snapshotId: string | undefined;
       try {
-        const result = await executeApplyPlan(runner, session, plan, {
+        // checkDescent is REQUIRED by StageApplyOptions — no conditional spread can drop it. The
+        // verdict is guaranteed well-formed by the guard above; the hook enforces + records it here,
+        // in order, atomic with the lock. Authority/snapshot stay conditional (destructive-only, and
+        // the stage lane refuses destructive outright, so they never light up on this lane).
+        const applyOptions: StageApplyOptions = {
           actor: actor ?? null,
           gitRef: gitRef ?? null,
-          // Descent/authority are decided by the CLI (checkout + caller identity)
-          // and enforced + recorded here, in order, atomic with the lock.
-          ...(descentVerdict
-            ? { verifyDescent: async () => (descentVerdict.ok ? { ok: true as const } : { ok: false as const, reason: descentVerdict.reason ?? 'descent refused' }) }
-            : {}),
+          dirty: dirty === true,
+          checkDescent: async () => (descentVerdict.ok ? { ok: true as const } : { ok: false as const, reason: descentVerdict.reason ?? 'descent refused' }),
+          // A honoured --attest-lineage-lost waiver is recorded in the schema_log outcome.
+          ...(descentAttested ? { descentNote: () => descentAttested } : {}),
           ...(destructive && authorityVerdict
             ? { verifyAuthority: async () => (authorityVerdict.ok ? { ok: true as const } : { ok: false as const, reason: authorityVerdict.reason ?? 'authority refused' }) }
             : {}),
@@ -1030,8 +1079,11 @@ export function dbPlugin(options: DbPluginOptions): Plugin {
                 },
               }
             : {}),
-        });
-        return snapshotId ? { ...result, snapshotId } : result;
+        };
+        const result = await executeApplyPlan(runner, session, plan, applyOptions);
+        // Echo the contract version the write ran under (SHOULD, legibility — the safety mechanism is
+        // the pre-transaction refusal above, not this field).
+        return { ...result, contractVersion: APPLY_CONTRACT_VERSION, ...(snapshotId ? { snapshotId } : {}) };
       } catch (err: any) {
         return { error: err?.message || String(err) };
       }