fix(plugin-auth): keep the manager outcome off rows[].code, which the spec ledger does not register

Co-authored-by: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01URLHobLUJB9K1ABV6ofdjj

Author: claude

.changeset/18028-import-users-manager-second-pass.md

@@ -36,12 +36,16 @@ exactly as they are on the endpoint, with the endpoint's own `reason`
 discriminator carried through. There is no second copy of those predicates.
 
 **A manager problem never costs the row its identity.** The user is created
-either way; the failure is reported on that row — `rows[].code` is
-`MANAGER_UNRESOLVED` or `MANAGER_REFUSED` and `rows[].manager` carries the
-machine-readable outcome, in the shape `rows[].delivery` already uses. It is
-⛔ not a whole-import failure and ⛔ not a silent skip, and an engine fault
-while linking is reported the same way rather than turning a 200 that created
-N users into a 500 that reports none of them.
+either way; the failure is reported on that row — `rows[].manager` carries the
+machine-readable outcome in the shape `rows[].delivery` already uses
+(`unresolved`, or the refusal's own `reason`), and `rows[].error` carries the
+sentence. It is ⛔ not a whole-import failure and ⛔ not a silent skip, and an
+engine fault while linking is reported the same way rather than turning a 200
+that created N users into a 500 that reports none of them. No `rows[].code` is
+stamped for a manager outcome: a row-level code would have to be registered in
+the `packages/spec` error-code ledger, which this change is fenced out of, so
+the machine-readable half lives on `rows[].manager` instead of on a code the
+vocabulary does not carry.
 
 **New on the response.** `data.summary.manager` is
 `{ linked, unresolved, refused }`, beside `data.summary.delivery`, and the

packages/plugins/plugin-auth/src/admin-import-users-manager-pass.test.ts

@@ -285,8 +285,13 @@ describe('import-users manager pass — an unresolved key is PER-ROW (#18028)',
     expect(res.status).toBe(200);
     const data = payload(res);
     expect(data.rows[0].manager).toBe('unresolved');
-    expect(data.rows[0].code).toBe('MANAGER_UNRESOLVED');
     expect(String(data.rows[0].error)).toContain('manager_id');
+    // ⛔ No row-level `code`: the obvious `MANAGER_UNRESOLVED` symmetry with
+    // `INVITE_EMAIL_FAILED` needs a `packages/spec` error-code ledger entry
+    // this lane is fenced out of, and `check:dispatcher-error-vocabulary`
+    // refuses an unregistered one. Pinned so the symmetry cannot be restored
+    // without the registration that makes it legal.
+    expect(data.rows[0].code).toBeUndefined();
 
     // Direction 2 — and it is not a whole-import failure. Asserting only the
     // first would pass against an implementation that aborts everything.
@@ -311,7 +316,8 @@ describe('import-users manager pass — an unresolved key is PER-ROW (#18028)',
 
     const data = payload(res);
     expect(data.rows[0].manager).toBe('unresolved');
-    expect(data.rows[0].code).toBe('MANAGER_UNRESOLVED');
+    expect(String(data.rows[0].error)).toContain('phone number');
+    expect(data.rows[0].code).toBeUndefined();
     expect(data.summary.manager.unresolved).toBe(1);
   });
 
@@ -341,6 +347,9 @@ describe('import-users manager pass — an unresolved key is PER-ROW (#18028)',
 
     const data = payload(res);
     expect(data.rows[0].code).toBe('INVITE_EMAIL_FAILED');
+    expect(String(data.rows[0].error)).toContain('invitation email failed');
+    // The delivery report keeps the shared `error` slot; the manager verdict is
+    // still readable on its own field, so neither failure is lost to silence.
     expect(data.rows[0].manager).toBe('unresolved');
     expect(data.summary.manager.unresolved).toBe(1);
   });
@@ -404,7 +413,9 @@ describe('import-users manager pass — the refusals are the DELEGATE\'s (#18028
 
     const data = payload(res);
     expect(data.rows[0].manager).toBe('self_assignment');
-    expect(data.rows[0].code).toBe('MANAGER_REFUSED');
+    // The delegate's own message, carried through rather than re-worded.
+    expect(String(data.rows[0].error)).toContain('cannot be their own manager');
+    expect(data.rows[0].code).toBeUndefined();
     expect(data.summary.manager).toEqual({ linked: 0, unresolved: 0, refused: 1 });
     expect(h.userBy('a@x.co')?.manager_id ?? null).toBeNull();
   });
@@ -424,7 +435,7 @@ describe('import-users manager pass — the refusals are the DELEGATE\'s (#18028
     const data = payload(res);
     expect(data.rows[0].manager).toBe('linked');
     expect(data.rows[1].manager).toBe('cycle');
-    expect(data.rows[1].code).toBe('MANAGER_REFUSED');
+    expect(String(data.rows[1].error)).toContain('loop');
     expect(data.summary.manager).toEqual({ linked: 1, unresolved: 0, refused: 1 });
     expect(h.userBy('b@x.co')?.manager_id ?? null).toBeNull();
   });

packages/plugins/plugin-auth/src/admin-import-users.ts

@@ -88,10 +88,11 @@
  *    identity are that function's to answer, and the refusal it returns is
  *    reported on the row rather than re-worded here.
  *  - **A manager problem never costs the row its identity.** The user is
- *    created either way and the failure rides `rows[].code` / `rows[].error`,
- *    exactly like the sibling post-write `INVITE_EMAIL_FAILED`; `rows[].manager`
- *    carries the machine-readable outcome in `rows[].delivery`'s shape. ⛔ Not a
- *    whole-import failure, and ⛔ not a silent skip.
+ *    created either way; `rows[].manager` carries the machine-readable outcome
+ *    in `rows[].delivery`'s shape and `rows[].error` carries the sentence.
+ *    ⛔ Not a whole-import failure, and ⛔ not a silent skip. ⛔ And no
+ *    `rows[].code` — see {@link noteManagerFailure} for why that half is fenced
+ *    out of this lane rather than forgotten.
  *  - **The pass does not run on `dryRun`.** It is a post-write pass like
  *    delivery: with nothing created there are no ids to link, and the five
  *    refusals cannot be evaluated against rows that do not exist. A dry run
@@ -331,23 +332,36 @@ export interface IdentityImportRowResult extends ImportRowResult {
 /**
  * Stamp a row's manager failure.
  *
- * `manager` is ALWAYS set — that is this outcome's own channel. `code`/`error`
- * is the SHARED row error channel the sibling `INVITE_EMAIL_FAILED` also writes
- * to, so it is claimed only when free: a row whose invitation already failed
- * keeps that report and still carries its manager verdict on `manager`,
- * ⛔ rather than one of the two failures overwriting the other into silence.
+ * `manager` is ALWAYS set — that is this outcome's own channel, and it is the
+ * machine-readable one: `'unresolved'` and each refusal `reason` are distinct
+ * members of {@link ImportManagerOutcome}, so a caller discriminates on one
+ * field without parsing a sentence.
+ *
+ * ⛔ NO `rows[].code` IS STAMPED, and that is a fence rather than an oversight.
+ * The sibling post-write failure writes `code: 'INVITE_EMAIL_FAILED'`, and a
+ * matching `MANAGER_UNRESOLVED` / `MANAGER_REFUSED` pair would read as the
+ * obvious symmetry — but `check:dispatcher-error-vocabulary` refuses a code
+ * this package's `packages/spec` ledger entry does not register, and
+ * registering one is a `packages/spec` edit this lane is fenced out of
+ * (the closed-vocabulary question for this endpoint's refusals is already
+ * carried by #17995). So the failure rides `error` — the human half — and
+ * `manager` — the machine half — and the row-level code is left to the seat
+ * that owns the vocabulary. ⛔ Reaching for an already-registered code whose
+ * meaning is something else would be the lenient alias Prime Directive #12
+ * refuses.
+ *
+ * `error` is the SHARED row channel that sibling also writes to, so it is
+ * claimed only when free: a row whose invitation already failed keeps that
+ * report and still carries its manager verdict on `manager`, ⛔ rather than one
+ * of the two failures overwriting the other into silence.
  */
 function noteManagerFailure(
   row: IdentityImportRowResult,
   outcome: ImportManagerOutcome,
-  code: string,
   message: string,
 ): void {
   row.manager = outcome;
-  if (row.code === undefined) {
-    row.code = code;
-    row.error = message;
-  }
+  if (row.error === undefined) row.error = message;
 }
 
 /**
@@ -724,7 +738,6 @@ export async function runAdminImportUsers(
           noteManagerFailure(
             r,
             'unresolved',
-            'MANAGER_UNRESOLVED',
             `The ${MANAGER_COLUMN} cell is neither an email address nor a phone number this deployment `
               + 'can read, so it names no identity. This row landed; only its manager link did not.',
           );
@@ -763,7 +776,6 @@ export async function runAdminImportUsers(
           noteManagerFailure(
             r,
             'unresolved',
-            'MANAGER_UNRESOLVED',
             `No user matches this row's ${MANAGER_COLUMN} key, in this import or already in the `
               + 'directory, so the manager link was not written. The rest of this row landed.',
           );
@@ -786,15 +798,14 @@ export async function runAdminImportUsers(
           noteManagerFailure(
             r,
             'unresolved',
-            'MANAGER_UNRESOLVED',
             `The manager link could not be written: ${(e as Error)?.message ?? String(e)}. `
               + 'This row itself landed.',
           );
           managerLinks.unresolved++;
           continue;
         }
         if (refusal) {
-          noteManagerFailure(r, refusal.reason, 'MANAGER_REFUSED', refusal.message);
+          noteManagerFailure(r, refusal.reason, refusal.message);
           managerLinks.refused++;
           continue;
         }

scripts/engine-double-contract.pinned.json

@@ -2376,6 +2376,11 @@
       "verb": "update",
       "pinned": 1
     },
+    {
+      "file": "packages/plugins/plugin-auth/src/admin-import-users-manager-pass.test.ts",
+      "verb": "update",
+      "pinned": 2
+    },
     {
       "file": "packages/plugins/plugin-auth/src/admin-import-users.test.ts",
       "verb": "update",