@productbrain/cli 0.1.0-beta.1125 → 0.1.0-beta.11259

package/dist/__tests__/update.test.js

@@ -4,7 +4,9 @@
  */
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { runUpdate } from '../commands/update.js';
-import { CLIError } from '../lib/errors.js';
+import { CLIError, ErrorCode } from '../lib/errors.js';
+import { isJsonMode } from '../lib/runner.js';
+const mockIsJsonMode = vi.mocked(isJsonMode);
 const kernelCallWithSessionMock = vi.fn();
 const kernelCallMock = vi.fn();
 vi.mock('../lib/client.js', () => ({
@@ -36,9 +38,10 @@ function makeMcpError(message, code, details) {
 vi.mock('../lib/config.js', () => ({
     getConfigOrGuide: vi.fn(() => Promise.resolve({ apiKey: 'pb_sk_test', siteUrl: 'https://test.convex.site' })),
 }));
-// Force pretty mode for all tests so formatUpdateReceipt output is tested (not JSON)
+// Defaults to pretty mode so formatUpdateReceipt output is tested (not JSON); individual
+// tests override with mockIsJsonMode.mockReturnValue(true) to exercise the JSON branch.
 vi.mock('../lib/runner.js', () => ({
-    isJsonMode: () => false,
+    isJsonMode: vi.fn(() => false),
 }));
 // Session mock — controlled per test
 let mockSession = { sessionId: 'sess-test' };
@@ -84,7 +87,7 @@ describe('runUpdate', () => {
         await runUpdate({
             entryId: 'TEN-703',
             name: 'New name',
-            status: 'active',
+            status: 'archived',
             note: 'Resolved',
         });
         writeSpy.mockRestore();
@@ -92,10 +95,33 @@ describe('runUpdate', () => {
             entryId: 'TEN-703',
             changedBy: 'agent:sess-test',
             name: 'New name',
-            status: 'active',
+            status: 'archived',
             changeNote: 'Resolved',
         });
     });
+    // T8 (TASK-393, WP-779): --status is validated client-side against the generated write
+    // vocabulary (kernel/entries/statusCategories.ts) before the round trip.
+    it('refuses a legacy status word via --status', async () => {
+        const err = await runUpdate({ entryId: 'TEN-703', status: 'active' }).catch((e) => e);
+        expect(err).toBeInstanceOf(CLIError);
+        expect(err.code).toBe(ErrorCode.VALIDATION_FAILED);
+        expect(kernelCallWithSessionMock).not.toHaveBeenCalled();
+    });
+    it('refuses an unknown status word via --status', async () => {
+        const err = await runUpdate({ entryId: 'TEN-703', status: 'not-a-real-status' }).catch((e) => e);
+        expect(err).toBeInstanceOf(CLIError);
+        expect(err.code).toBe(ErrorCode.VALIDATION_FAILED);
+        expect(kernelCallWithSessionMock).not.toHaveBeenCalled();
+    });
+    // Round-1 review (Codex P2, PRRT_kwDORS4ils6mPBU8): `--status ""` is PROVIDED but blank, not
+    // ABSENT — a truthiness check let it skip the vocabulary check entirely and silently drop the
+    // status while other fields still applied (same class of bug PR #622 already fixed for --type).
+    it('refuses a blank --status "" instead of silently dropping it', async () => {
+        const err = await runUpdate({ entryId: 'TEN-703', status: '', name: 'New name' }).catch((e) => e);
+        expect(err).toBeInstanceOf(CLIError);
+        expect(err.code).toBe(ErrorCode.VALIDATION_FAILED);
+        expect(kernelCallWithSessionMock).not.toHaveBeenCalled();
+    });
     it('passes workflowStatus as root-level arg when provided', async () => {
         const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
         await runUpdate({
@@ -109,6 +135,16 @@ describe('runUpdate', () => {
             workflowStatus: 'shipped',
         });
     });
+    // SHOULD-FIX 4 (fix round): `--workflow-status` alone applied nothing the OLD receipt's field
+    // set could name (it only ever checked name/status) — pre-fix this printed "Updated BET-271: "
+    // with an empty list for a write that genuinely succeeded.
+    it('workflowStatus alone produces a non-empty receipt naming it (SHOULD-FIX 4)', async () => {
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runUpdate({ entryId: 'BET-271', workflowStatus: 'shipped' });
+        const output = writeSpy.mock.calls.map(c => String(c[0])).join('');
+        writeSpy.mockRestore();
+        expect(output).toContain('Updated BET-271: workflowStatus → shipped');
+    });
     it('handles --field values containing = signs', async () => {
         const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
         await runUpdate({
@@ -159,6 +195,40 @@ describe('runUpdate', () => {
         expect(err).toBeInstanceOf(CLIError);
         expect(err.message).toContain('Entry not found.');
     });
+    it('preserves a server authority refusal as machine-readable AUTH_DENIED', async () => {
+        kernelCallWithSessionMock.mockRejectedValue(makeMcpError('This record belongs to another team.', 'AUTHZ_PERMISSION_DENIED'));
+        const err = await runUpdate({ entryId: 'WP-OTHER-TEAM', field: ['description=no'] }).catch((e) => e);
+        expect(err).toBeInstanceOf(CLIError);
+        expect(err.code).toBe(ErrorCode.AUTH_DENIED);
+        expect(err.category).toBe('auth');
+    });
+    it('preserves a returned organisational refusal and its truthful next action', async () => {
+        kernelCallWithSessionMock.mockResolvedValue({
+            outcome: 'refused',
+            refusal: {
+                category: 'auth',
+                code: 'role_not_owner',
+                reason: 'This person does not hold this record’s exact owning role in its owning team.',
+                requiredAction: 'Route this change to a holder of the record’s exact owning role, or ask the relevant Team Lead to change its ownership.',
+            },
+        });
+        const err = await runUpdate({ entryId: 'WP-OTHER-TEAM', field: ['description=no'] }).catch((e) => e);
+        expect(err).toBeInstanceOf(CLIError);
+        expect(err.code).toBe(ErrorCode.AUTH_DENIED);
+        expect(err.category).toBe('auth');
+        expect(err.guidance).toBe('Route this change to a holder of the record’s exact owning role, or ask the relevant Team Lead to change its ownership.');
+    });
+    it('keeps a returned coherency refusal classified as validation', async () => {
+        kernelCallWithSessionMock.mockResolvedValue({
+            outcome: 'refused',
+            refusal: { code: 'COHERENCY_REFUSED', reason: 'This entry is not linked to the strategic spine.' },
+        });
+        const err = await runUpdate({ entryId: 'WP-UNLINKED', field: ['description=no'] }).catch((e) => e);
+        expect(err).toBeInstanceOf(CLIError);
+        expect(err.code).toBe(ErrorCode.VALIDATION_FAILED);
+        expect(err.category).toBe('validation');
+        expect(err.guidance).toContain('strategic spine');
+    });
     // ── Slice 3: post-update refresh ─────────────────────────────────────────
     it('calls chain.getEntry after successful update and includes entry in output', async () => {
         kernelCallMock.mockResolvedValue({
@@ -166,6 +236,17 @@ describe('runUpdate', () => {
             name: 'My Bet',
             status: 'active',
         });
+        // PR B: the receipt now reflects the SERVER's applied set, not the raw --field list — the
+        // default beforeEach mock's empty `accepted` (a realistic "nothing accepted" shape) would no
+        // longer produce a receipt here at all, so this happy-path fixture must say the server
+        // actually kept `description`, matching what the test claims to simulate.
+        kernelCallWithSessionMock.mockResolvedValue({
+            id: 'j571abc123def456',
+            warnings: [],
+            normalization: { remapped: {}, rejected: [], accepted: ['description'] },
+            normalizationWarnings: [],
+            validationWarnings: [],
+        });
         const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
         await runUpdate({ entryId: 'BET-151', field: ['description=new'] });
         const output = writeSpy.mock.calls.map(c => String(c[0])).join('');
@@ -173,10 +254,20 @@ describe('runUpdate', () => {
         expect(kernelCallMock).toHaveBeenCalledWith('chain.getEntry', { entryId: 'BET-151' });
         // Pretty output: receipt then entry block
         expect(output).toContain('Updated BET-151');
+        expect(output).toContain('description');
         expect(output).toContain('My Bet');
     });
     it('still shows update receipt when post-update getEntry fails (graceful degradation)', async () => {
         kernelCallMock.mockRejectedValue(new Error('network error'));
+        // PR B: same fixture correction as above — the receipt is built from the server's applied
+        // set, so this "successful update, degraded refresh" scenario needs a realistic accepted list.
+        kernelCallWithSessionMock.mockResolvedValue({
+            id: 'j571abc123def456',
+            warnings: [],
+            normalization: { remapped: {}, rejected: [], accepted: ['description'] },
+            normalizationWarnings: [],
+            validationWarnings: [],
+        });
         const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
         await runUpdate({ entryId: 'BET-151', field: ['description=new'] });
         const output = writeSpy.mock.calls.map(c => String(c[0])).join('');
@@ -186,25 +277,147 @@ describe('runUpdate', () => {
         // No crash — process still completes without error
     });
     // ── BET-192 / FEAT-575: Normalization warning tests ──────────────────────
-    it('throws CLIError when fields are rejected (BET-192, BET-271)', async () => {
+    // PR B (WP-757): every field this call named was rejected — normalization.accepted is
+    // correctly EMPTY here (the caller only ever asked for `foo`, and the server dropped it;
+    // `description` was never part of this call's own request, so a realistic server response
+    // never lists it as accepted). The receipt must print NOTHING — no false "Updated" line —
+    // only the rejection error.
+    it('every named field rejected: no "Updated" receipt at all, error only (BET-192, BET-271)', async () => {
         kernelCallWithSessionMock.mockResolvedValue({
             id: 'j571abc123def456',
             warnings: ['Unknown field "foo" dropped. Available fields: description, doneWhen'],
-            normalization: { remapped: {}, rejected: ['foo'], accepted: ['description'] },
+            normalization: { remapped: {}, rejected: ['foo'], accepted: [] },
             normalizationWarnings: ['Unknown field "foo" dropped. Available fields: description, doneWhen'],
             validationWarnings: [],
         });
+        kernelCallMock.mockResolvedValue({ entryId: 'BET-192', name: 'Bet', status: 'active', collectionSlug: 'bets' });
         const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
         const err = await runUpdate({
             entryId: 'BET-192',
             field: ['foo=bar'],
         }).catch((e) => e);
+        const output = writeSpy.mock.calls.map(c => String(c[0])).join('');
+        writeSpy.mockRestore();
         // BET-271 S1: throws CLIError when fields rejected, with `pb fields` suggestion
         expect(err).toBeInstanceOf(CLIError);
         expect(err.message).toContain('Fields rejected');
         expect(err.message).toContain('foo');
-        expect(err.guidance).toContain('pb fields');
+        // TEN-4332: the hint names the entry's collection, so the command it gives works.
+        expect(err.guidance).toBe('Run `pb fields bets` to see valid fields.');
+        // PR B: the receipt line never printed — nothing was actually applied.
+        expect(output).not.toContain('Updated BET-192');
+        expect(output).not.toContain('View: pb get');
+    });
+    // TASK-603 (WP-802, TEN-4332): a partial strip — one field kept, one dropped. The write landed, so the
+    // command exits 0: the receipt names ONLY the applied field and carries the kernel's
+    // "Unknown fields dropped" warning with a `pb fields <collection>` hint. Before this it threw
+    // "Fields rejected" after the write, and agents retried an update that had already landed.
+    it('partial strip: a landed update exits 0, names only the applied field and the dropped one in a warning', async () => {
+        kernelCallWithSessionMock.mockResolvedValue({
+            id: 'j571abc123def456',
+            warnings: ['Unknown field "foo" dropped. Available fields: description, doneWhen'],
+            normalization: { remapped: {}, rejected: ['foo'], accepted: ['description'] },
+            normalizationWarnings: ['Unknown fields dropped: foo. Expected: description (string), doneWhen (string).'],
+            validationWarnings: [],
+        });
+        kernelCallMock.mockResolvedValue({ entryId: 'BET-192', name: 'Bet', status: 'active', collectionSlug: 'bets' });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        const err = await runUpdate({
+            entryId: 'BET-192',
+            field: ['description=new value', 'foo=bar'],
+        }).catch((e) => e);
+        const output = writeSpy.mock.calls.map(c => String(c[0])).join('');
+        writeSpy.mockRestore();
+        expect(err).toBeUndefined();
+        expect(output).not.toContain('Fields rejected');
+        expect(output).toContain('Unknown fields dropped: foo.');
+        expect(output).toContain('Run `pb fields bets` to see valid fields.');
+        // The receipt WAS printed (something applied) and names the applied field.
+        expect(output).toContain('Updated BET-192');
+        expect(output).toContain('description');
+        // The dropped field never appears in the "Updated: ..." summary line — only in the warning.
+        const summaryLine = output.split('\n').find((line) => line.startsWith('Updated BET-192'));
+        expect(summaryLine).toBeDefined();
+        expect(summaryLine).not.toContain('foo');
+    });
+    it('partial strip in JSON mode: exits 0 with droppedFields naming only the dropped field (TEN-4332)', async () => {
+        mockIsJsonMode.mockReturnValue(true);
+        kernelCallWithSessionMock.mockResolvedValue({
+            id: 'j571abc123def456',
+            warnings: [],
+            normalization: { remapped: {}, rejected: ['foo'], accepted: ['description'] },
+            normalizationWarnings: ['Unknown fields dropped: foo. Expected: description (string).'],
+            validationWarnings: [],
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        const err = await runUpdate({ entryId: 'BET-192', field: ['description=new', 'foo=bar'] }).catch((e) => e);
+        const output = writeSpy.mock.calls.map(c => String(c[0])).join('');
         writeSpy.mockRestore();
+        mockIsJsonMode.mockReturnValue(false);
+        expect(err).toBeUndefined();
+        const parsed = JSON.parse(output.trim().split('\n').pop());
+        expect(parsed.droppedFields).toEqual(['foo']);
+        expect(parsed.fieldsRejected).toBe(true);
+    });
+    // PR B fix round (BLOCKING 1): a caller-supplied allowed system key (e.g. `source`) is a
+    // real applied change — it lands in kernel/entries/normalize.ts's `accepted`, not just
+    // `systemKeys`. Pre-fix, `pb update X --field source=manual` wrote the field but printed
+    // no receipt and exited 0 (silently), since accepted was empty for a call that only ever
+    // touched a system key.
+    it('a caller-supplied system key (source) is reported as applied, not silently dropped from the receipt', async () => {
+        kernelCallWithSessionMock.mockResolvedValue({
+            id: 'j571abc123def456',
+            warnings: [],
+            normalization: { remapped: {}, rejected: [], accepted: ['source'] },
+            normalizationWarnings: [],
+            validationWarnings: [],
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runUpdate({ entryId: 'BET-193', field: ['source=manual'] });
+        const output = writeSpy.mock.calls.map(c => String(c[0])).join('');
+        writeSpy.mockRestore();
+        expect(output).toContain('Updated BET-193');
+        expect(output).toContain('source');
+    });
+    // ── WP-475 E1 (FEAT-1346): coaching verdict in the update receipt ─────────
+    it('renders the coaching section when the write response carries a verdict (WP-475 E1)', async () => {
+        kernelCallWithSessionMock.mockResolvedValue({
+            id: 'j571abc123def456',
+            warnings: [],
+            normalization: { remapped: {}, rejected: [], accepted: ['description'] },
+            normalizationWarnings: [],
+            validationWarnings: [],
+            coaching: {
+                source: 'heuristic',
+                verdict: {
+                    entryId: 'DEC-77',
+                    canonicalKey: 'decision',
+                    tier: 'assertive',
+                    context: 'capture',
+                    passed: false,
+                    criteria: [
+                        { id: 'has_rationale', passed: true, weight: 3, hint: 'State why.', questionTemplate: 'Why this?' },
+                        { id: 'specificity', passed: false, weight: 2, hint: 'Be specific.', questionTemplate: 'What exactly?' },
+                    ],
+                    weakest: { criterion: 'specificity', hint: 'Be specific.', questionTemplate: 'What exactly?' },
+                },
+            },
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runUpdate({ entryId: 'DEC-77', field: ['rationale=better reason'] });
+        const output = writeSpy.mock.calls.map(c => String(c[0])).join('');
+        writeSpy.mockRestore();
+        expect(output).toContain('Semantic quality: 1/2 criteria pass for decision (assertive tier)');
+        expect(output).toContain('[ ] specificity — Be specific.');
+        expect(output).toContain('Coaching hint: Be specific.');
+        expect(output).toContain('Consider: What exactly?');
+    });
+    it('renders no coaching section when the write response has none (backward compat)', async () => {
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runUpdate({ entryId: 'BET-151', field: ['description=new'] });
+        const output = writeSpy.mock.calls.map(c => String(c[0])).join('');
+        writeSpy.mockRestore();
+        expect(output).not.toContain('Semantic quality');
     });
     it('displays no warnings when all fields are valid (BET-192)', async () => {
         kernelCallWithSessionMock.mockResolvedValue({
@@ -224,5 +437,254 @@ describe('runUpdate', () => {
         expect(output).not.toContain('Normalization warnings');
         expect(output).not.toContain('Validation warnings');
     });
+    // #1026 round 3 (Codex, 2 P3 findings): the SHOULD-FIX 3 dedup filter this test used to pin
+    // drew a THIRD round of findings (comma-splitting the rewritten regex, and stale filter
+    // ordering) and is deleted outright, not patched again. Server normalizationWarnings now
+    // render verbatim and are not parsed (TEN-4332: a landed update exits 0, so the kernel's
+    // warning is the one statement of what was dropped).
+    it('renders every normalization warning verbatim, including one that repeats the rejected field', async () => {
+        kernelCallWithSessionMock.mockResolvedValue({
+            id: 'j571abc123def456',
+            warnings: [],
+            normalization: { remapped: {}, rejected: ['foo'], accepted: ['description'] },
+            normalizationWarnings: [
+                'Unknown fields dropped: foo. Expected: description (string), doneWhen (string).',
+                'Remapped "desc" to "description".',
+            ],
+            validationWarnings: [],
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        const err = await runUpdate({
+            entryId: 'BET-194',
+            field: ['description=new value', 'foo=bar'],
+        }).catch((e) => e);
+        const output = writeSpy.mock.calls.map(c => String(c[0])).join('');
+        writeSpy.mockRestore();
+        // TEN-4332: something applied, so the landed write exits 0.
+        expect(err).toBeUndefined();
+        expect(output).toContain('Unknown fields dropped: foo. Expected: description (string), doneWhen (string).');
+        expect(output).toContain('Remapped "desc" to "description"');
+    });
+    // #1026 round 3 (Codex P2): a platform-owned data key (e.g. `seederId` on a schemaless
+    // collection) is accepted by normalization, then reverted by preservePlatformOwnedDataKeys —
+    // the CLI must not print "Updated ... seederId" when nothing was actually written, and must
+    // name the revert instead (mirrors the MCP surface's own consumption of the server field).
+    it('excludes a server-reverted data key from the printed receipt and renders it under Fields reverted', async () => {
+        kernelCallWithSessionMock.mockResolvedValue({
+            id: 'j571abc123def456',
+            warnings: [],
+            normalization: { remapped: {}, rejected: [], accepted: ['seederId', 'description'] },
+            normalizationWarnings: [],
+            validationWarnings: [],
+            revertedFields: ['seederId'],
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runUpdate({
+            entryId: 'BET-194',
+            field: ['description=new value', 'seederId=forged'],
+        });
+        const output = writeSpy.mock.calls.map(c => String(c[0])).join('');
+        writeSpy.mockRestore();
+        const summaryLine = output.split('\n').find((line) => line.startsWith('Updated'));
+        expect(summaryLine).not.toContain('seederId');
+        expect(summaryLine).toContain('description');
+        expect(output).toContain('⚠ Fields reverted (platform-owned or write-once): seederId');
+    });
+    // #1026 round 4 (Codex): a call whose ONLY named field was accepted then reverted, with no
+    // other arg applied, used to print nothing and exit 0 — a fully-failed write read as success.
+    it('all fields reverted, nothing else applied: fails with a "Fields reverted" line, not silent success', async () => {
+        kernelCallWithSessionMock.mockResolvedValue({
+            id: 'j571abc123def456',
+            warnings: [],
+            normalization: { remapped: {}, rejected: [], accepted: ['seederId'] },
+            normalizationWarnings: [],
+            validationWarnings: [],
+            revertedFields: ['seederId'],
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        const err = await runUpdate({
+            entryId: 'BET-195',
+            field: ['seederId=forged'],
+        }).catch((e) => e);
+        const output = writeSpy.mock.calls.map(c => String(c[0])).join('');
+        writeSpy.mockRestore();
+        expect(err).toBeInstanceOf(CLIError);
+        expect(err.code).toBe(ErrorCode.VALIDATION_FAILED);
+        expect(err.message).toContain('Fields reverted');
+        expect(err.message).toContain('seederId');
+        expect(err.guidance).toBeTruthy();
+        // No false "Updated" line — nothing was actually written.
+        expect(output).not.toContain('Updated BET-195');
+    });
+    // #1026 round 4 (Codex): same all-reverted case in JSON mode — the receipt must carry
+    // ok:false rather than reading as a plain successful update.
+    it('all fields reverted in JSON mode: receipt carries ok:false and the call still fails', async () => {
+        mockIsJsonMode.mockReturnValueOnce(true);
+        kernelCallWithSessionMock.mockResolvedValue({
+            id: 'j571abc123def456',
+            warnings: [],
+            normalization: { remapped: {}, rejected: [], accepted: ['seederId'] },
+            normalizationWarnings: [],
+            validationWarnings: [],
+            revertedFields: ['seederId'],
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        const err = await runUpdate({
+            entryId: 'BET-196',
+            field: ['seederId=forged'],
+        }).catch((e) => e);
+        const output = writeSpy.mock.calls.map(c => String(c[0])).join('');
+        writeSpy.mockRestore();
+        expect(err).toBeInstanceOf(CLIError);
+        expect(err.code).toBe(ErrorCode.VALIDATION_FAILED);
+        const parsed = JSON.parse(output.trim());
+        expect(parsed.ok).toBe(false);
+        expect(parsed.revertedFields).toEqual(['seederId']);
+    });
+    it('prints the kernel receipt first when a draft team is discarded with the drafts inside it (TASK-773)', async () => {
+        const receipt = 'Discarded Growth and the 4 drafts inside it (1 made by others).';
+        kernelCallWithSessionMock.mockResolvedValueOnce({
+            id: 'j571abc123def456', warnings: [], normalization: { remapped: {}, rejected: [], accepted: [] },
+            normalizationWarnings: [], validationWarnings: [], receipt,
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runUpdate({ entryId: 'TEAM-9', status: 'archived', archiveIntent: 'discard' });
+        const output = writeSpy.mock.calls.map((call) => String(call[0])).join('');
+        writeSpy.mockRestore();
+        expect(output).toContain(`\n${receipt}\n`);
+        expect(output.indexOf(receipt)).toBeLessThan(output.indexOf('TEAM-9', output.indexOf(receipt)));
+    });
+});
+/**
+ * S5 of WP-634 (TASK-45) — `pb update --type <key>` threads a canonicalKey reclassification
+ * through the EXISTING `chain.updateEntry` door (convex/agentKnowledge/entries.ts:1462, arg
+ * `canonicalKey` at :1471). No new server validation: the typeMap check, BR-55, the cardinality
+ * guards and the post-commit immutability guard (convex/lib/guards.ts:190-200) all already run
+ * there, and their refusal text must reach the operator verbatim rather than being reworded or
+ * pre-empted by a client-side copy of the rule.
+ */
+describe('runUpdate --type (S5 of WP-634, TASK-45)', () => {
+    // Its OWN seeding, mirroring the `runUpdate` suite above (PR #622 review). This block is a
+    // SIBLING of that suite, so its beforeEach never ran here: the tests passed only in a
+    // whole-file run, riding whatever mock state the previous suite's last test left behind, and
+    // failed in isolation with "Cannot read properties of undefined (reading 'outcome')" — a test
+    // that depends on execution order is not a test.
+    beforeEach(() => {
+        vi.clearAllMocks();
+        mockSession = { sessionId: 'sess-test' };
+        kernelCallWithSessionMock.mockResolvedValue({
+            id: 'j571abc123def456',
+            warnings: [],
+            normalization: { remapped: {}, rejected: [], accepted: [] },
+            normalizationWarnings: [],
+            validationWarnings: [],
+        });
+        kernelCallMock.mockResolvedValue({
+            entryId: 'INS-900',
+            name: 'Test Entry',
+            status: 'draft',
+        });
+    });
+    it('relays --type as the canonicalKey arg on chain.updateEntry', async () => {
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runUpdate({ entryId: 'INS-900', type: 'decision' });
+        writeSpy.mockRestore();
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.updateEntry', {
+            entryId: 'INS-900',
+            changedBy: 'agent:sess-test',
+            canonicalKey: 'decision',
+        });
+    });
+    it('counts as something to update on its own — --type alone is a valid write', async () => {
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await expect(runUpdate({ entryId: 'INS-900', type: 'decision' })).resolves.toBeUndefined();
+        writeSpy.mockRestore();
+        // The point is that --type alone clears the "Nothing to update" arity check and actually
+        // reaches the write door — not a total call count, which includes other session traffic.
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.updateEntry', expect.objectContaining({
+            canonicalKey: 'decision',
+        }));
+    });
+    it('combines with other updates in one call', async () => {
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runUpdate({ entryId: 'INS-900', type: 'decision', name: 'Renamed', note: 'Reclassified' });
+        writeSpy.mockRestore();
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.updateEntry', {
+            entryId: 'INS-900',
+            changedBy: 'agent:sess-test',
+            name: 'Renamed',
+            canonicalKey: 'decision',
+            changeNote: 'Reclassified',
+        });
+    });
+    it('trims the value — a padded --type must not reach the server as an unmatched key', async () => {
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runUpdate({ entryId: 'INS-900', type: '  decision  ' });
+        writeSpy.mockRestore();
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.updateEntry', {
+            entryId: 'INS-900',
+            changedBy: 'agent:sess-test',
+            canonicalKey: 'decision',
+        });
+    });
+    /**
+     * PROVIDED-but-blank must fail loudly, never be treated as ABSENT (PR #622 review). The
+     * whitespace case is the dangerous one: paired with another flag it used to report a
+     * successful rename while silently discarding the reclassification.
+     */
+    it('refuses a whitespace-only --type instead of silently dropping it alongside another update', async () => {
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await expect(runUpdate({ entryId: 'INS-900', name: 'Renamed', type: '   ' }))
+            .rejects.toThrow('--type was provided but empty.');
+        writeSpy.mockRestore();
+        expect(kernelCallWithSessionMock).not.toHaveBeenCalled(); // refused BEFORE any relay
+    });
+    it('refuses a whitespace-only --type on its own rather than reporting "Nothing to update"', async () => {
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await expect(runUpdate({ entryId: 'INS-900', type: '   ' }))
+            .rejects.toThrow('--type was provided but empty.');
+        writeSpy.mockRestore();
+    });
+    it('refuses an empty-string --type', async () => {
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await expect(runUpdate({ entryId: 'INS-900', type: '' }))
+            .rejects.toThrow('--type was provided but empty.');
+        writeSpy.mockRestore();
+    });
+    it('omits canonicalKey entirely when --type is not passed', async () => {
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runUpdate({ entryId: 'INS-900', name: 'Just a rename' });
+        writeSpy.mockRestore();
+        const args = kernelCallWithSessionMock.mock.calls[0][1];
+        expect(args).not.toHaveProperty('canonicalKey');
+    });
+    /**
+     * The two guard texts are the deliverable, so they must arrive UNREWORDED. The CLI must not
+     * carry its own copy of "committed entries cannot be retyped" or of BR-55 — a client-side
+     * pre-check would drift from the server rule and is exactly what "no new server-side
+     * validation, existing guard text verbatim" rules out.
+     */
+    it('surfaces the post-commit immutability guard text verbatim', async () => {
+        const guardText = 'canonicalKey cannot be changed after an entry has been committed. '
+            + 'To reclassify, create a new entry and supersede this one.';
+        kernelCallWithSessionMock.mockRejectedValueOnce(makeMcpError(guardText, 'VALIDATION_FAILED'));
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await expect(runUpdate({ entryId: 'DEC-1', type: 'insight' })).rejects.toThrow(guardText);
+        writeSpy.mockRestore();
+    });
+    it('surfaces the BR-55 out-of-collection refusal verbatim', async () => {
+        const br55 = 'Vision and purpose entries must be in the strategy collection. This entry is in "insights".';
+        kernelCallWithSessionMock.mockRejectedValueOnce(makeMcpError(br55, 'VALIDATION_FAILED'));
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await expect(runUpdate({ entryId: 'INS-900', type: 'vision' })).rejects.toThrow(br55);
+        writeSpy.mockRestore();
+    });
+    it('surfaces the invalid-type refusal verbatim', async () => {
+        const invalid = 'Invalid canonical key "nonsense". Must be one of the 42 canonical types or null/undefined.';
+        kernelCallWithSessionMock.mockRejectedValueOnce(makeMcpError(invalid, 'VALIDATION_FAILED'));
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await expect(runUpdate({ entryId: 'INS-900', type: 'nonsense' })).rejects.toThrow(invalid);
+        writeSpy.mockRestore();
+    });
 });
 //# sourceMappingURL=update.test.js.map