fix(cli): keep pure-v2 tables on the v2 ladder (#787 review)

The `unresolvedHint` fail-closed added for #772 finding 7 had no
`candidates.length > 0` guard, so it fired on pure EQL v2 tables too.

`encrypt backfill` records `encryptedColumn` in migrations.json
unconditionally, v2 included. On a pure-v2 table `listEncryptedColumns`
returns [] (the classifier recognises `eql_v3_*` only), so the hint failed
to resolve, `columnExists` found the real `eql_v2_encrypted` column, and
`cutover` / `drop` exited 1 — telling users to downgrade for a lifecycle
this same build still fully implements in cutover.ts / drop.ts.

Gate the fail-closed on a non-empty candidate list. Finding 7's protection
is unchanged: the mixed table it targets always has candidates. Order
`explainUnresolved`'s empty-candidates fall-through ahead of the hint
branch so both agree for direct callers.

Also drop the "this release no longer manages that lifecycle" claim from
the cutover/drop `via: 'sole'` messages — the build does still implement
it; the command simply resolves EQL v3 counterparts only.

Tests cover the previously untested shape: candidates [] + a recorded hint.

Review follow-ups:
- Extend the placeholder-table guard to `encrypt backfill` via
  loadEncryptionContext; correct the changeset/skill wording to name the
  commands that actually refuse (cutover/drop never read the client file).
- Alias `@cipherstash/migrate` to source in the CLI unit vitest config, so
  `pnpm --filter stash test` no longer needs a prior workspace build
  (verified: 888 tests pass with packages/migrate/dist removed).
- Revert the unrelated em-dash re-encoding in packages/cli/package.json.

Author: tobyhede

.changeset/encrypt-lifecycle-mixed-table.md

@@ -35,5 +35,10 @@ all now fixed:
   column that actually encrypts the named one, and says explicitly not to record
   the guess.
 
-Pure-v2 and pure-v3 tables are unaffected, as are tables with two or more EQL v3
-columns (resolution already failed closed there).
+The new refusal is scoped to the mixed table it was written for: it applies only
+when the table actually holds EQL v3 columns that a guess could wrongly claim. A
+pure-v2 table has none, so it still falls through to the EQL v2 lifecycle exactly
+as before — including when `encrypt backfill` recorded an `encryptedColumn` for
+it, which it does for v2 columns too. Pure-v2 and pure-v3 tables are therefore
+unaffected, as are tables with two or more EQL v3 columns (resolution already
+failed closed there).

.changeset/init-scaffold-compiles.md

@@ -13,9 +13,12 @@ whose looser bound accepted `[]`; collapsing that into an alias of `Encryption`
 tightened it.)
 
 The scaffold now declares a single sentinel table, `__stash_placeholder__`, so
-the file typechecks as written. `stash encrypt` commands refuse to run while
-that table is still the only one declared, and say so — rather than failing
-later with a confusing "table not found".
+the file typechecks as written. Every command that reads the encryption client
+— `stash db push`, `stash db validate`, and `stash encrypt backfill` — refuses
+to run while that table is still the only one declared, and names it, rather
+than failing later with a confusing "table not found". (`stash encrypt cutover`
+and `stash encrypt drop` do not read the client file at all; they resolve
+against the database.)
 
 Nothing in the repo compiled this output before: `packages/cli` has no
 typecheck step, the codegen tests only string-match fragments of the template,

packages/cli/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "stash",
 	"version": "1.0.0-rc.4",
-	"description": "CipherStash CLI \u2014 the one stash command for auth, init, encryption schema, database setup, and secrets.",
+	"description": "CipherStash CLI — the one stash command for auth, init, encryption schema, database setup, and secrets.",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/cipherstash/stack.git",
@@ -57,7 +57,7 @@
 		"posthog-node": "^5.41.0",
 		"zod": "^3.25.76"
 	},
-	"//optionalDependencies": "@cipherstash/auth ships per-platform native bindings as optional peerDependencies. pnpm does not auto-install platform-matched optional peer deps, so we declare them here as optionalDependencies \u2014 pnpm then picks the binary matching the host's os/cpu (from each sub-package's own package.json) and ignores the rest. All seven names share a single catalog entry to keep them in lockstep.",
+	"//optionalDependencies": "@cipherstash/auth ships per-platform native bindings as optional peerDependencies. pnpm does not auto-install platform-matched optional peer deps, so we declare them here as optionalDependencies — pnpm then picks the binary matching the host's os/cpu (from each sub-package's own package.json) and ignores the rest. All seven names share a single catalog entry to keep them in lockstep.",
 	"optionalDependencies": {
 		"@cipherstash/auth-darwin-arm64": "catalog:repo",
 		"@cipherstash/auth-darwin-x64": "catalog:repo",

packages/cli/src/commands/encrypt/__tests__/context-placeholder.test.ts

@@ -0,0 +1,89 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { PLACEHOLDER_TABLE_NAME } from '@/config/index.js'
+
+/**
+ * `stash encrypt` does not load its client through `loadEncryptConfig`, so the
+ * placeholder guard that command group needs lives in `loadEncryptionContext`.
+ * Both must refuse the un-replaced scaffold; otherwise `requireTable` reports
+ * `Table "users" was not found … Available: __stash_placeholder__`, which names
+ * the symptom instead of the cause (#787 review).
+ *
+ * Runs against the real jiti runtime — the guard reads the tables harvested
+ * from an actually-evaluated client module, which is the part worth pinning.
+ */
+describe('loadEncryptionContext — the un-replaced init scaffold', () => {
+  let tmpDir: string
+  let originalCwd: () => string
+
+  const writeProject = (clientBody: string) => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'stash.config.ts'),
+      `export default {
+         databaseUrl: 'postgresql://u:p@127.0.0.1:5432/db',
+         client: './client.ts',
+       }`,
+    )
+    fs.writeFileSync(path.join(tmpDir, 'client.ts'), clientBody)
+    process.cwd = () => tmpDir
+  }
+
+  /**
+   * The duck-typed shapes `loadEncryptionContext` harvests: any export with a
+   * `getEncryptConfig()` method is the client, and any with `tableName` +
+   * `build()` is a table. Hand-rolled rather than imported from
+   * `@cipherstash/stack` so the test needs no native module.
+   */
+  const table = (name: string) =>
+    `{ tableName: '${name}', build: () => ({ tableName: '${name}', columns: {} }) }`
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'stash-encrypt-ctx-'))
+    originalCwd = process.cwd
+  })
+
+  afterEach(() => {
+    process.cwd = originalCwd
+    vi.restoreAllMocks()
+    if (tmpDir && fs.existsSync(tmpDir)) {
+      fs.rmSync(tmpDir, { recursive: true, force: true })
+    }
+  })
+
+  it('exits 1 naming the sentinel when it is the only table declared', async () => {
+    writeProject(
+      `export const encryptionClient = { getEncryptConfig: () => ({}) }
+       export const placeholderTable = ${table(PLACEHOLDER_TABLE_NAME)}`,
+    )
+    const error = vi.spyOn(console, 'error').mockImplementation(() => {})
+    vi.spyOn(process, 'exit').mockImplementation(() => {
+      throw new Error('process.exit')
+    })
+
+    const { loadEncryptionContext } = await import('../context.js')
+    await expect(loadEncryptionContext()).rejects.toThrow('process.exit')
+
+    const message = error.mock.calls.flat().join('\n')
+    expect(message).toContain(PLACEHOLDER_TABLE_NAME)
+    // Names the cause, not `requireTable`'s "table not found" symptom.
+    expect(message).toContain('still contains the placeholder table')
+    expect(message).not.toContain('was not found in the encryption client')
+  })
+
+  it('allows the sentinel through once a real table sits alongside it', async () => {
+    // Only the SOLE-placeholder case is the un-replaced scaffold. A user who
+    // has added real tables must not be blocked by a leftover sentinel export.
+    writeProject(
+      `export const encryptionClient = { getEncryptConfig: () => ({}) }
+       export const placeholderTable = ${table(PLACEHOLDER_TABLE_NAME)}
+       export const users = ${table('users')}`,
+    )
+
+    const { loadEncryptionContext } = await import('../context.js')
+    const ctx = await loadEncryptionContext()
+
+    expect(ctx.tables.has('users')).toBe(true)
+  })
+})

packages/cli/src/commands/encrypt/context.ts

@@ -1,7 +1,11 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import type { EncryptionClient } from '@cipherstash/stack/encryption'
-import { loadStashConfig, type ResolvedStashConfig } from '@/config/index.js'
+import {
+  loadStashConfig,
+  PLACEHOLDER_TABLE_NAME,
+  type ResolvedStashConfig,
+} from '@/config/index.js'
 
 /**
  * Structural shape of `@cipherstash/stack`'s `EncryptedTable` class.
@@ -138,6 +142,20 @@ export async function loadEncryptionContext(): Promise<EncryptionContext> {
     process.exit(1)
   }
 
+  // Same guard `loadEncryptConfig` applies for `stash db push` / `db validate`,
+  // repeated here because `stash encrypt` does not go through that loader. The
+  // scaffold `stash init` writes declares one sentinel table so the file
+  // compiles; reaching here with only that table means it was never replaced.
+  // Without this, `requireTable` reported `Table "users" was not found …
+  // Available: __stash_placeholder__`, which names the symptom and not the
+  // cause (#787 review).
+  if (tables.size === 1 && tables.has(PLACEHOLDER_TABLE_NAME)) {
+    console.error(
+      `Error: ${stashConfig.client} still contains the placeholder table \`${PLACEHOLDER_TABLE_NAME}\` that \`stash init\` wrote.\n\nDeclare your encrypted columns and pass those tables to Encryption({ schemas: [...] }) in that file, then re-run this command.`,
+    )
+    process.exit(1)
+  }
+
   return { stashConfig, client, tables }
 }
 

packages/cli/src/commands/encrypt/cutover.ts

@@ -107,7 +107,7 @@ export async function cutoverCommand(options: CutoverCommandOptions) {
       // the same reason (#772 review, finding 7).
       if (info.via === 'sole') {
         p.log.error(
-          `${options.table}.${encryptedColumn} (${info.domain}) is the table's only EQL v3 column, but nothing confirms it encrypts "${options.column}" — refusing to report a cut-over outcome on that guess. If "${options.column}" pairs with a legacy eql_v2_encrypted column, this release no longer manages that lifecycle. Otherwise record the pairing: re-run \`stash encrypt backfill --table ${options.table} --column ${options.column} --encrypted-column <the column that actually encrypts ${options.column}>\`.`,
+          `${options.table}.${encryptedColumn} (${info.domain}) is the table's only EQL v3 column, but nothing confirms it encrypts "${options.column}" — refusing to report a cut-over outcome on that guess. If "${options.column}" pairs with a legacy eql_v2_encrypted column, resolution cannot see it (this command resolves EQL v3 counterparts only) — drive that column's v2 lifecycle against its own encrypted column directly. Otherwise record the pairing: re-run \`stash encrypt backfill --table ${options.table} --column ${options.column} --encrypted-column <the column that actually encrypts ${options.column}>\`.`,
         )
         exitCode = 1
         return

packages/cli/src/commands/encrypt/drop.ts

@@ -113,7 +113,7 @@ export async function dropCommand(options: DropCommandOptions) {
     // live `DROP COLUMN` on the plaintext at exit 0 (#772 review, finding 7).
     if (info?.via === 'sole') {
       p.log.error(
-        `${options.table}.${info.column} (${info.domain}) is the table's only encrypted column, but nothing confirms it encrypts "${options.column}" — refusing to generate an irreversible drop on that guess. Identify the column that actually encrypts "${options.column}" and record that pairing: re-run \`stash encrypt backfill --table ${options.table} --column ${options.column} --encrypted-column <name>\` (which writes it to the manifest), or set "encryptedColumn" for this column in .cipherstash/migrations.json. If "${options.column}" pairs with a legacy eql_v2_encrypted column, this release no longer manages that lifecycle — do not record ${info.column}.`,
+        `${options.table}.${info.column} (${info.domain}) is the table's only encrypted column, but nothing confirms it encrypts "${options.column}" — refusing to generate an irreversible drop on that guess. Identify the column that actually encrypts "${options.column}" and record that pairing: re-run \`stash encrypt backfill --table ${options.table} --column ${options.column} --encrypted-column <name>\` (which writes it to the manifest), or set "encryptedColumn" for this column in .cipherstash/migrations.json. If "${options.column}" pairs with a legacy eql_v2_encrypted column, resolution cannot see it (this command resolves EQL v3 counterparts only) — drive that column's v2 lifecycle against its own encrypted column directly, and do not record ${info.column}.`,
       )
       exitCode = 1
       return

packages/cli/src/commands/encrypt/lib/__tests__/resolve-eql.test.ts

@@ -4,12 +4,17 @@
  *
  * `listEncryptedColumns` can no longer emit `version: 2` — a legacy
  * `eql_v2_encrypted` column is not classified as an EQL column at all, so it
- * never reaches this function as a candidate. The post-cutover v2 state (the
- * ciphertext renamed onto the plaintext column's own name) therefore arrives
- * here as an EMPTY candidate list, which the first guard already falls through
- * on. These tests exist so removing the now-unreachable `version === 2` branch
- * is provably behaviour-preserving, and so a future v2 sweep cannot delete the
- * empty-list guard the v2 lifecycle actually depends on.
+ * never reaches this function as a candidate. Every pure-v2 table therefore
+ * arrives here as an EMPTY candidate list, both pre-cutover (`<col>` /
+ * `<col>_encrypted`) and post-cutover (the ciphertext renamed onto the
+ * plaintext column's own name), and the first guard falls through on it.
+ *
+ * These tests exist so removing the now-unreachable `version === 2` branch is
+ * provably behaviour-preserving, and so a future v2 sweep cannot delete the
+ * empty-list guard the v2 lifecycle actually depends on. That guard has to hold
+ * even when the manifest recorded an `encryptedColumn` — `backfill` records one
+ * for v2 columns too — which is the `candidates.length > 0` gate on the
+ * fail-closed path (#787 review).
  */
 
 import type { EncryptedColumnInfo } from '@cipherstash/migrate'
@@ -64,6 +69,15 @@ describe('explainUnresolved', () => {
     expect(explainUnresolved('users', 'email', [])).toBeNull()
   })
 
+  it('still falls through when no EQL v3 columns exist BUT a hint was recorded', () => {
+    // The pure-v2 table. `encrypt backfill` records `encryptedColumn` for v2
+    // columns too, so a hint is present on every table backfilled with this
+    // release — it must not flip the empty-candidate fall-through into a
+    // refusal, because `cutover` / `drop` in this same build still implement
+    // the v2 ladder this falls through to (#787 review).
+    expect(explainUnresolved('users', 'ssn', [], 'ssn_encrypted')).toBeNull()
+  })
+
   it('fails closed, naming every candidate, when none is identifiable', () => {
     const message = explainUnresolved('users', 'email', [
       v3('a_enc'),
@@ -133,6 +147,36 @@ describe('resolveColumnLifecycle — a recorded hint that is not a v3 candidate'
     expect(unresolvedHint).toBe('ssn_encrypted')
   })
 
+  // The pure-v2 shape, and the regression the `candidates.length > 0` gate
+  // exists to prevent (#787 review). `backfill` records `encryptedColumn`
+  // unconditionally — v2 included — so EVERY pure-v2 table backfilled with this
+  // release carries a hint naming a real, existing, non-v3 column. Without the
+  // gate, `columnExists` returned true, `unresolvedHint` was set, and
+  // `cutover` / `drop` refused a lifecycle this same build still performs.
+  it('does not fail closed on a pure-v2 table, where no v3 column can be mis-claimed', async () => {
+    // No v3 columns at all: just the `ssn` / `ssn_encrypted` v2 pair, which the
+    // classifier does not see.
+    listEncryptedColumns.mockResolvedValue([])
+    readManifest.mockResolvedValue({
+      tables: { users: [{ column: 'ssn', encryptedColumn: 'ssn_encrypted' }] },
+    })
+
+    const { info, candidates, unresolvedHint } = await resolveColumnLifecycle(
+      clientWithColumns('ssn', 'ssn_encrypted'),
+      'users',
+      'ssn',
+    )
+
+    expect(info).toBeNull()
+    expect(candidates).toEqual([])
+    // The fall-through signal: no hint reported, so `explainUnresolved` returns
+    // null and the caller reaches its own v2 preconditions.
+    expect(unresolvedHint).toBeUndefined()
+    expect(
+      explainUnresolved('users', 'ssn', candidates, unresolvedHint),
+    ).toBeNull()
+  })
+
   it('explains the recorded counterpart by name rather than listing candidates', async () => {
     const message = explainUnresolved(
       'users',