@ttctl/core 0.1.0-rc.3 → 0.1.0-rc.5

package/dist/services/profile/employment/index.d.ts

@@ -1,3 +1,4 @@
+import type { DryRunPreview } from "../../../transport.js";
 /**
  * `Employment` row as ttctl exposes it. Trimmed read-side projection of
  * the `Employment` GraphQL fragment (see
@@ -38,6 +39,22 @@ export interface Employment {
         code: string | null;
         name: string | null;
     } | null;
+    /**
+     * The catalog id of the resolved employer (#394 — surfaced read-side so
+     * `update()` can echo it back through the merge; the wire's
+     * `UpdateEmploymentInput` requires `employerId` even when the caller
+     * only supplies `position`, and the read-side previously hid the id).
+     */
+    employerId: string | null;
+    /**
+     * Catalog skills attached to the row (#394 — surfaced read-side so
+     * `update()` can preserve them through the merge; the wire requires
+     * `skills` to be non-empty on update).
+     */
+    skills: {
+        id: string;
+        name: string;
+    }[];
 }
 /**
  * Fields editable on an Employment row. Mirrors `EmploymentInput` per the
@@ -51,9 +68,21 @@ export interface Employment {
  * fields (employerId, engagementId, industryIds, managementExperience,
  * primaryGeographyId, reportingTo, skills, …) are exposed at the type
  * level so future leaves can grow without churning callers.
+ *
+ * `employerId` is the server-side catalog identifier for the employer
+ * record (e.g. "V1-Employer-1234"). `add()` requires EITHER an explicit
+ * `employerId`, a `company` that resolves to exactly one autocomplete
+ * match (see {@link add} for the resolution policy), OR the
+ * {@link EmploymentFields.noEmployer} signal for a custom (non-catalog)
+ * workplace — which sends `employerId: null` with the free-text
+ * `company` verbatim. `employerId` and `noWebsite` are ORTHOGONAL axes
+ * (#401): a custom workplace may still carry a website. The earlier
+ * "nullable only when noWebsite" note was a single-capture
+ * over-inference, not the wire contract.
  */
 export interface EmploymentFields {
     company?: string;
+    employerId?: string;
     position?: string;
     companyWebsite?: string | null;
     noWebsite?: boolean;
@@ -67,8 +96,63 @@ export interface EmploymentFields {
     industryIds?: string[];
     primaryGeographyId?: string | null;
     reportingTo?: string | null;
-    skills?: string[];
+    /**
+     * Catalog skill refs (wire shape: `SkillRefInput[]` = `{ id, name }[]`,
+     * not the `string[]` originally declared — corrected #394 after the
+     * live capture showed the live mutation accepts the object form and
+     * rejects empty arrays on update).
+     */
+    skills?: {
+        id: string;
+        name: string;
+    }[];
+    noEmployer?: boolean;
+}
+/**
+ * Options accepted by {@link add}. `dryRun` mirrors the option-shape
+ * established by `basic.set` (#393 / SetOptions) so the cross-service
+ * surface stays uniform — callers that branch on the outcome's `kind`
+ * discriminator can use the same code path regardless of which
+ * mutation they're invoking.
+ *
+ * The `dryRun` path fires the employer autocomplete read so the preview
+ * shows the resolved `employerId` (not the raw `company` string). This
+ * departs from `basic.set`'s zero-network dry-run by design (#395):
+ * the alternative — placeholder employerId — would misrepresent the
+ * wire shape, since the server-side input requires the resolved id, not
+ * the company name. EXCEPTION (#401): the custom-workplace path
+ * (`fields.noEmployer === true`) skips resolution entirely, so dry-run
+ * there fires ZERO network — `employerId: null` needs no lookup. The
+ * mutation transport is still NEVER fired in `dryRun` mode.
+ */
+export interface AddOptions {
+    dryRun?: boolean;
+}
+/**
+ * Discriminated outcome of an {@link add} call when the apply-path
+ * succeeded — the newly created {@link Employment} row.
+ */
+export interface AddOutcomeCreated {
+    kind: "created";
+    result: Employment;
+}
+/**
+ * Discriminated outcome of an {@link add} call invoked with
+ * `dryRun: true` — the structured preview of the request that WOULD
+ * have been sent. The `employersAutocomplete` read query MAY have been
+ * fired during dry-run to resolve `employerId`; the `CreateEmployment`
+ * mutation transport was NOT fired.
+ */
+export interface AddOutcomePreview {
+    kind: "preview";
+    preview: DryRunPreview;
 }
+/**
+ * Discriminated-union return type for {@link add}. Apply-path callers
+ * branch on `outcome.kind === "created"`; dry-run callers branch on
+ * `"preview"`. Symmetric with `basic.set`'s {@link SetOutcome} (#393).
+ */
+export type AddOutcome = AddOutcomeCreated | AddOutcomePreview;
 /**
  * Lightweight `Employer` reference returned by
  * `employer-autocomplete`. Mirrors the read-side `Employer` fragment
@@ -97,12 +181,117 @@ export declare function list(token: string): Promise<Employment[]>;
 export declare function show(token: string, id: string): Promise<Employment>;
 /**
  * Create a new employment row. Wire format per Pattern 2: `{ profileId,
- * employment: EmploymentInput }`. `company` and `position` are required.
+ * employment: EmploymentInput }`.
+ *
+ * **employerId resolution (#395)**: the live `talent_profile/graphql`
+ * server requires `employment.employerId` (the catalog identifier),
+ * NOT the free-text `company` string. Pre-#395, `add({company, role,
+ * …})` sent only the company string and was rejected with
+ * `USER_ERROR: employment add rejected (employerId): You can't leave
+ * this empty`. The fix:
+ *
+ *   1. If `fields.employerId` is supplied → use it verbatim. This is
+ *      the explicit-bypass path (`--employer-id` on CLI,
+ *      `employerId` on MCP) — useful for replay scripts, the
+ *      disambiguation fallback, or known-good ids.
+ *   2. Otherwise, fire {@link employerAutocomplete} against
+ *      `fields.company`. Toptal's autocomplete is fuzzy / prefix-
+ *      search (typing "Anthropic" returns 10 partial matches), so the
+ *      practical cardinality is on EXACT NAME MATCH (case-insensitive
+ *      trim):
+ *        - exactly 1 exact match → use its id transparently
+ *        - 2+ exact matches (catalog duplicates — e.g. multiple
+ *          regional subsidiaries with the same display name) →
+ *          `VALIDATION_ERROR` listing the duplicates + `--employer-id`
+ *          nudge
+ *        - 0 exact, 0 fuzzy → `VALIDATION_ERROR` nudging to the
+ *          autocomplete CLI command or `--employer-id` bypass
+ *        - 0 exact, ≥1 fuzzy → `VALIDATION_ERROR` listing the top-N
+ *          closest candidates with `--employer-id` nudge (the user
+ *          typed a prefix; surface the catalog's actual names)
+ *
+ * The static defaults at `experienceItems: []`, `skills: []`,
+ * `showViaToptal: true` are retained pre-#395 — they were established
+ * empirically via the #344 E2E to satisfy "Expected value to not be
+ * null" on those required fields. Reviewing them in this PR would
+ * be premature without a fresh live capture; they may be revisited in
+ * a follow-up that mirrors the basic.set #393 read-merge pattern for
+ * employment.add.
+ *
+ * **Dry-run path (#395)**: when `options.dryRun === true`, the
+ * employer resolution still runs (fires `employersAutocomplete` if
+ * `employerId` is absent — except on the #401 custom-workplace path;
+ * see **Custom-workplace path (#401)** below) so the preview's
+ * `variables.input.employment`
+ * carries the resolved `employerId`, matching the wire shape the live
+ * mutation would transmit. The `CreateEmployment` mutation transport
+ * is NOT invoked. The placeholder
+ * {@link DRY_RUN_PROFILE_ID_PLACEHOLDER} stands in for `profileId`
+ * (which the apply-path resolves via `extractProfileId`).
+ *
+ * **Custom-workplace path (#401)**: when `fields.noEmployer === true`,
+ * `resolveEmployerId()` is skipped entirely — NO `employersAutocomplete`
+ * call in EITHER the apply or dry-run path — and `employerId: null` is
+ * sent with the free-text `company`. Mutually exclusive with an explicit
+ * `fields.employerId` (→ `VALIDATION_ERROR`). Orthogonal to `noWebsite`.
+ */
+export declare function add(token: string, fields: EmploymentFields, options?: AddOptions): Promise<AddOutcome>;
+/**
+ * Placeholder string substituted into a dry-run `UpdateEmployment`
+ * preview's variables payload for fields that the apply-path resolves by
+ * reading the current row (`experienceItems`, `position`, `skills`,
+ * `showViaToptal`, `startDate` — the five required-non-null fields
+ * injected by the read-current+merge logic, #394 + #407 for `position`).
+ * Surfaced verbatim so MCP consumers can
+ * see the structural shape of what will be sent without TTCtl having
+ * fired the read transport. Same posture as `basic.set`'s
+ * {@link DRY_RUN_PROFILE_ID_PLACEHOLDER} — preserves the zero-transport-
+ * in-dry-run invariant (#165 / #379) while honoring #394's AC that the
+ * preview shows the full merged shape.
+ */
+export declare const DRY_RUN_EMPLOYMENT_MERGE_PLACEHOLDER: "<resolved at send-time by reading current state>";
+/**
+ * Build the merged `EmploymentInput` to send for an `UpdateEmployment`
+ * mutation by reading the current row and overlaying user-supplied fields.
+ *
+ * The `talent_profile/graphql` server treats five `EmploymentInput` fields
+ * as required non-null on `UpdateEmployment` and rejects the whole
+ * variables payload with `"Expected value to not be null"` when they are
+ * absent (#394 + #407 for `position` — wire-broke meta-class #392). The
+ * five fields are `experienceItems`, `position`, `showViaToptal`,
+ * `startDate`, and `skills`. This helper injects them from the current
+ * state where the EMPLOYMENT_FRAGMENT surfaces them (`experienceItems`,
+ * `position`, `showViaToptal`, `startDate`) and defaults `skills: []`
+ * because the fragment does not currently select the read-side `skills`
+ * connection. Other fields are left undefined and omitted from the wire
+ * payload — the server keeps the existing value for any field absent
+ * from the input (the omission-is-preservation half of the merge
+ * contract; only the five required-non-null fields force-echo).
+ *
+ * **Known limitation (#394)**: `skills` defaults to `[]` because the
+ * current read fragment does not surface skills. Calling `update()` on a
+ * row that has skills will reset them to empty. A follow-up will extend
+ * the fragment to read skills and preserve them through the merge; for
+ * the test-account this is acceptable, and the bug fix here is for the
+ * minimal `{id, role}` repro that previously failed at the wire layer
+ * regardless of skills state.
+ *
+ * Exported so the MCP layer can build the same merged input for the
+ * dry-run preview (AC: "Dry-run preview shows the full merged input").
+ *
+ * @throws `ProfileError("VALIDATION_ERROR")` when `fields` is empty.
+ * @throws `ProfileError("VALIDATION_ERROR")` when `current.startDate` is
+ *   `null` and the caller did not supply a `startDate` override — the
+ *   wire requires a non-null `startDate` and we have nothing to send.
  */
-export declare function add(token: string, fields: EmploymentFields): Promise<Employment>;
+export declare function buildUpdateEmploymentInput(current: Employment, fields: EmploymentFields): EmploymentFields;
 /**
  * Update an existing employment row. Wire format per Pattern 1:
  * `{ employmentId, employment: EmploymentInput }`.
+ *
+ * Reads the current row first and merges the five required-non-null
+ * fields onto the wire input (see {@link buildUpdateEmploymentInput} for
+ * the merge contract and #394 + #407 for the originating wire-broke incidents).
  */
 export declare function update(token: string, id: string, fields: EmploymentFields): Promise<Employment>;
 /**

package/dist/services/profile/employment/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/services/profile/employment/index.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,eAAe,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IACjC,SAAS,EAAE,OAAO,CAAC;IACnB,aAAa,EAAE,OAAO,CAAC;IACvB,aAAa,EAAE,OAAO,CAAC;IACvB,uEAAuE;IACvE,iBAAiB,EAAE,OAAO,GAAG,IAAI,CAAC;IAClC,mDAAmD;IACnD,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,sDAAsD;IACtD,UAAU,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC3C,8DAA8D;IAC9D,gBAAgB,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;CACnF;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAyJD;;;;;;GAMG;AACH,wBAAsB,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAG/D;AAqBD;;;GAGG;AACH,wBAAsB,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAOzE;AAED;;;GAGG;AACH,wBAAsB,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC,CAmCtF;AAED;;;GAGG;AACH,wBAAsB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC,CAoBrG;AAED;;GAEG;AACH,wBAAsB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAUvE;AAED;;;GAGG;AACH,wBAAsB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,UAAO,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAAC,CAiBpH;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAgBnH"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/services/profile/employment/index.ts"],"names":[],"mappings":"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"}

package/dist/services/profile/employment/index.js

@@ -1,7 +1,8 @@
 // SPDX-License-Identifier: AGPL-3.0-only
 // Copyright (C) 2026 Oleksii PELYKH
-import { ProfileError } from "../basic/index.js";
+import { DRY_RUN_PROFILE_ID_PLACEHOLDER, ProfileError } from "../basic/index.js";
 import { applyUserErrorsAndSuccess, callTalentProfile, ensureNoTopLevelErrors, extractProfileId } from "../shared.js";
+import { buildDryRunPreview } from "../../../transport.js";
 const EMPLOYMENT_FRAGMENT = `fragment Employment on Employment {
   id
   company
@@ -18,6 +19,8 @@ const EMPLOYMENT_FRAGMENT = `fragment Employment on Employment {
   reportingTo
   industries { nodes { id name } }
   primaryGeography { id code name }
+  employer { id }
+  skills { nodes { id name } }
 }`;
 const GET_WORK_EXPERIENCE_QUERY = `query GET_WORK_EXPERIENCE($profileId: ID!) {
   profile(id: $profileId) {
@@ -92,6 +95,12 @@ function mapEmploymentNode(node) {
             name: typeof geoRaw.name === "string" ? geoRaw.name : null,
         }
         : null;
+    const employerRaw = node["employer"];
+    const employerId = employerRaw && typeof employerRaw.id === "string" ? employerRaw.id : null;
+    const skillsConn = node["skills"];
+    const skills = Array.isArray(skillsConn?.nodes)
+        ? skillsConn.nodes.flatMap((s) => typeof s.id === "string" && typeof s.name === "string" ? [{ id: s.id, name: s.name }] : [])
+        : [];
     const rawItems = node["experienceItems"];
     return {
         id: typeof node["id"] === "string" ? node["id"] : "",
@@ -111,6 +120,8 @@ function mapEmploymentNode(node) {
         reportingTo: node["reportingTo"] ?? null,
         industries,
         primaryGeography,
+        employerId,
+        skills,
     };
 }
 /**
@@ -151,27 +162,125 @@ export async function show(token, id) {
 }
 /**
  * Create a new employment row. Wire format per Pattern 2: `{ profileId,
- * employment: EmploymentInput }`. `company` and `position` are required.
+ * employment: EmploymentInput }`.
+ *
+ * **employerId resolution (#395)**: the live `talent_profile/graphql`
+ * server requires `employment.employerId` (the catalog identifier),
+ * NOT the free-text `company` string. Pre-#395, `add({company, role,
+ * …})` sent only the company string and was rejected with
+ * `USER_ERROR: employment add rejected (employerId): You can't leave
+ * this empty`. The fix:
+ *
+ *   1. If `fields.employerId` is supplied → use it verbatim. This is
+ *      the explicit-bypass path (`--employer-id` on CLI,
+ *      `employerId` on MCP) — useful for replay scripts, the
+ *      disambiguation fallback, or known-good ids.
+ *   2. Otherwise, fire {@link employerAutocomplete} against
+ *      `fields.company`. Toptal's autocomplete is fuzzy / prefix-
+ *      search (typing "Anthropic" returns 10 partial matches), so the
+ *      practical cardinality is on EXACT NAME MATCH (case-insensitive
+ *      trim):
+ *        - exactly 1 exact match → use its id transparently
+ *        - 2+ exact matches (catalog duplicates — e.g. multiple
+ *          regional subsidiaries with the same display name) →
+ *          `VALIDATION_ERROR` listing the duplicates + `--employer-id`
+ *          nudge
+ *        - 0 exact, 0 fuzzy → `VALIDATION_ERROR` nudging to the
+ *          autocomplete CLI command or `--employer-id` bypass
+ *        - 0 exact, ≥1 fuzzy → `VALIDATION_ERROR` listing the top-N
+ *          closest candidates with `--employer-id` nudge (the user
+ *          typed a prefix; surface the catalog's actual names)
+ *
+ * The static defaults at `experienceItems: []`, `skills: []`,
+ * `showViaToptal: true` are retained pre-#395 — they were established
+ * empirically via the #344 E2E to satisfy "Expected value to not be
+ * null" on those required fields. Reviewing them in this PR would
+ * be premature without a fresh live capture; they may be revisited in
+ * a follow-up that mirrors the basic.set #393 read-merge pattern for
+ * employment.add.
+ *
+ * **Dry-run path (#395)**: when `options.dryRun === true`, the
+ * employer resolution still runs (fires `employersAutocomplete` if
+ * `employerId` is absent — except on the #401 custom-workplace path;
+ * see **Custom-workplace path (#401)** below) so the preview's
+ * `variables.input.employment`
+ * carries the resolved `employerId`, matching the wire shape the live
+ * mutation would transmit. The `CreateEmployment` mutation transport
+ * is NOT invoked. The placeholder
+ * {@link DRY_RUN_PROFILE_ID_PLACEHOLDER} stands in for `profileId`
+ * (which the apply-path resolves via `extractProfileId`).
+ *
+ * **Custom-workplace path (#401)**: when `fields.noEmployer === true`,
+ * `resolveEmployerId()` is skipped entirely — NO `employersAutocomplete`
+ * call in EITHER the apply or dry-run path — and `employerId: null` is
+ * sent with the free-text `company`. Mutually exclusive with an explicit
+ * `fields.employerId` (→ `VALIDATION_ERROR`). Orthogonal to `noWebsite`.
  */
-export async function add(token, fields) {
+export async function add(token, fields, options = {}) {
     if (!fields.company || !fields.position) {
         throw new ProfileError("VALIDATION_ERROR", "employment add requires --company and --role.");
     }
-    const profileId = await extractProfileId(token);
-    const before = await listByProfileId(token, profileId);
-    const beforeIds = new Set(before.map((e) => e.id));
-    // The wire requires `experienceItems`, `skills`, and `showViaToptal` to
-    // be non-null on `CreateEmployment` (live API rejects with
-    // "Expected value to not be null" otherwise). The synthesized SDL marks
-    // `CreateEmploymentInput` as `{ _placeholder: String }` — these defaults
-    // were established empirically via the #344 E2E. Callers may still
-    // override.
+    // Custom (non-catalog) workplace path (#401): when `noEmployer` is
+    // set, the Toptal "Add as new: <name>" behaviour applies — the wire
+    // takes `employerId: null` with the free-text `company` verbatim
+    // (there is no `CreateEmployer` mutation anywhere in the schema). It
+    // is orthogonal to `noWebsite` (a custom workplace may still have a
+    // website) and mutually exclusive with an explicit `employerId` (a
+    // catalog id and "not in the catalog" are contradictory).
+    if (fields.noEmployer === true && fields.employerId !== undefined && fields.employerId !== "") {
+        throw new ProfileError("VALIDATION_ERROR", "employment add: a custom workplace (--no-employer) cannot also pass --employer-id (a catalog id). Use one or the other.");
+    }
+    // Resolve employerId BEFORE branching on dryRun so the preview's wire
+    // shape matches what the live mutation would transmit (#395 explicit
+    // AC). The autocomplete query is a read, not a mutation — it fires in
+    // both dry-run and apply paths. The custom-workplace path (#401) skips
+    // resolution entirely: NO autocomplete network call in EITHER path
+    // (apply or dry-run), and `employerId: null` goes on the wire.
+    const { noEmployer, ...wireFields } = fields;
+    const employerId = noEmployer === true ? null : await resolveEmployerId(token, wireFields);
+    // The wire requires several non-null fields on `CreateEmployment`
+    // (live API rejects with "Expected value to not be null" / "You can't
+    // leave this empty" otherwise). The defaults below were established
+    // empirically through E2E iteration — DO NOT add pre-emptive defaults
+    // for fields the server hasn't explicitly demanded, since
+    // `CreateEmploymentInput` rejects unknown fields with
+    // "Field is not defined on EmploymentInput" (e.g. `toptalRelated`,
+    // `highlight` are valid on `UpdateEmploymentInput` but NOT on
+    // `CreateEmploymentInput`). The request-shaping `noEmployer` signal is
+    // destructured out above for the same reason — it is not an
+    // `EmploymentInput` field.
+    //   - `experienceItems`, `skills`, `showViaToptal` — via the #344 E2E
+    //   - `publicationPermit` — server treats Boolean `false` as blank
+    //     (USER_ERROR "publicationPermit: You can't leave this empty");
+    //     default to `true` to satisfy the Rails `.blank?` gate. Mirrors the
+    //     `buildUpdateEmploymentInput` fallback (`current.publicationPermit
+    //     ?? true`) so add/update agree on the no-caller-input semantics.
+    // Callers may still override.
     const employment = {
         experienceItems: [],
         skills: [],
         showViaToptal: true,
-        ...fields,
+        publicationPermit: true,
+        ...wireFields,
+        employerId,
     };
+    if (options.dryRun === true) {
+        return {
+            kind: "preview",
+            preview: buildDryRunPreview({
+                surface: "talent-profile",
+                authToken: token,
+                body: {
+                    operationName: "CreateEmployment",
+                    query: CREATE_EMPLOYMENT_MUTATION,
+                    variables: { input: { profileId: DRY_RUN_PROFILE_ID_PLACEHOLDER, employment } },
+                },
+            }),
+        };
+    }
+    const profileId = await extractProfileId(token);
+    const before = await listByProfileId(token, profileId);
+    const beforeIds = new Set(before.map((e) => e.id));
     const res = await callTalentProfile(token, "CreateEmployment", CREATE_EMPLOYMENT_MUTATION, { input: { profileId, employment } }, "employment add");
     const payload = unwrapMutation(res, "createEmployment", "employment add");
     const after = payload.profile?.employments.nodes.filter((n) => n !== null).map(mapEmploymentNode) ??
@@ -180,17 +289,204 @@ export async function add(token, fields) {
     if (!created) {
         throw new ProfileError("UNKNOWN", "employment add returned success but no new row was found in the response.");
     }
-    return created;
+    return { kind: "created", result: created };
+}
+/**
+ * Resolve `fields.employerId` for the create-employment flow (#395).
+ *
+ *   - Explicit `fields.employerId` → returned verbatim (bypass).
+ *   - Otherwise call {@link employerAutocomplete}; Toptal's autocomplete
+ *     is fuzzy / prefix-search, so the practical cardinality is on
+ *     **exact name match** (case-insensitive, trimmed):
+ *       - 1 exact match → transparent use
+ *       - 0 exact, 0 fuzzy → "No employer matched" nudge
+ *       - 0 exact, ≥1 fuzzy → "No exact match; closest candidates"
+ *         listing + `--employer-id` nudge (the user typed a prefix /
+ *         substring; we surface the catalog's actual names so they can
+ *         pick an id)
+ *       - 2+ exact → disambiguation listing of the duplicates (the
+ *         catalog has multiple records with the same display name —
+ *         common for companies with city subsidiaries; the user must
+ *         pick one)
+ *
+ * Errors all surface as `VALIDATION_ERROR` with actionable recovery
+ * text so the CLI / MCP layer can render them as user-facing
+ * messages without further classification.
+ */
+async function resolveEmployerId(token, fields) {
+    if (fields.employerId !== undefined && fields.employerId !== "") {
+        return fields.employerId;
+    }
+    // `fields.company` is asserted non-empty by the caller (the add()
+    // pre-flight rejects an empty company / position).
+    const company = fields.company ?? "";
+    const matches = await employerAutocomplete(token, company);
+    const norm = company.trim().toLowerCase();
+    const exact = matches.filter((m) => m.name.trim().toLowerCase() === norm);
+    if (exact.length === 1) {
+        const only = exact[0];
+        if (only === undefined) {
+            // Defensive: exact.length === 1 but indexed read is undefined —
+            // a TypeScript noUncheckedIndexedAccess guard. Unreachable at
+            // runtime.
+            throw new ProfileError("UNKNOWN", "employer-autocomplete returned 1 exact match but indexing it yielded undefined.");
+        }
+        return only.id;
+    }
+    if (exact.length >= 2) {
+        // Multiple catalog records share the user-supplied exact name
+        // (common for global companies with regional subsidiaries listed
+        // separately). Surface only the exact-name duplicates — the fuzzy
+        // siblings would just add noise.
+        const list = exact.map(formatCandidate).join("\n");
+        throw new ProfileError("VALIDATION_ERROR", `Multiple employers matched "${company}" exactly (${exact.length.toString()} duplicates in the catalog):\n` +
+            `${list}\n` +
+            `Pass \`--employer-id <id>\` to disambiguate.`);
+    }
+    // exact.length === 0
+    if (matches.length === 0) {
+        throw new ProfileError("VALIDATION_ERROR", `No employer matched "${company}". Use ` +
+            `\`ttctl profile employment employer-autocomplete <query>\` to search the catalog, ` +
+            `or pass \`--employer-id <id>\` to bypass autocomplete.`);
+    }
+    // 0 exact, ≥1 fuzzy. Surface the catalog's actual names so the user
+    // can refine (or pick an id directly).
+    const top = matches.slice(0, 5);
+    const list = top.map(formatCandidate).join("\n");
+    throw new ProfileError("VALIDATION_ERROR", `No exact match for "${company}" in the employer catalog ` +
+        `(${matches.length.toString()} fuzzy match${matches.length === 1 ? "" : "es"}; showing top ${top.length.toString()}):\n` +
+        `${list}\n` +
+        `Refine the company string to the exact catalog name, or pass \`--employer-id <id>\` to bypass autocomplete.`);
+}
+function formatCandidate(m) {
+    const loc = [m.city, m.country].filter((v) => v !== null && v !== "").join(", ");
+    return `  - ${m.id}  ${m.name}${loc ? ` (${loc})` : ""}`;
+}
+/**
+ * Placeholder string substituted into a dry-run `UpdateEmployment`
+ * preview's variables payload for fields that the apply-path resolves by
+ * reading the current row (`experienceItems`, `position`, `skills`,
+ * `showViaToptal`, `startDate` — the five required-non-null fields
+ * injected by the read-current+merge logic, #394 + #407 for `position`).
+ * Surfaced verbatim so MCP consumers can
+ * see the structural shape of what will be sent without TTCtl having
+ * fired the read transport. Same posture as `basic.set`'s
+ * {@link DRY_RUN_PROFILE_ID_PLACEHOLDER} — preserves the zero-transport-
+ * in-dry-run invariant (#165 / #379) while honoring #394's AC that the
+ * preview shows the full merged shape.
+ */
+export const DRY_RUN_EMPLOYMENT_MERGE_PLACEHOLDER = "<resolved at send-time by reading current state>";
+/**
+ * Build the merged `EmploymentInput` to send for an `UpdateEmployment`
+ * mutation by reading the current row and overlaying user-supplied fields.
+ *
+ * The `talent_profile/graphql` server treats five `EmploymentInput` fields
+ * as required non-null on `UpdateEmployment` and rejects the whole
+ * variables payload with `"Expected value to not be null"` when they are
+ * absent (#394 + #407 for `position` — wire-broke meta-class #392). The
+ * five fields are `experienceItems`, `position`, `showViaToptal`,
+ * `startDate`, and `skills`. This helper injects them from the current
+ * state where the EMPLOYMENT_FRAGMENT surfaces them (`experienceItems`,
+ * `position`, `showViaToptal`, `startDate`) and defaults `skills: []`
+ * because the fragment does not currently select the read-side `skills`
+ * connection. Other fields are left undefined and omitted from the wire
+ * payload — the server keeps the existing value for any field absent
+ * from the input (the omission-is-preservation half of the merge
+ * contract; only the five required-non-null fields force-echo).
+ *
+ * **Known limitation (#394)**: `skills` defaults to `[]` because the
+ * current read fragment does not surface skills. Calling `update()` on a
+ * row that has skills will reset them to empty. A follow-up will extend
+ * the fragment to read skills and preserve them through the merge; for
+ * the test-account this is acceptable, and the bug fix here is for the
+ * minimal `{id, role}` repro that previously failed at the wire layer
+ * regardless of skills state.
+ *
+ * Exported so the MCP layer can build the same merged input for the
+ * dry-run preview (AC: "Dry-run preview shows the full merged input").
+ *
+ * @throws `ProfileError("VALIDATION_ERROR")` when `fields` is empty.
+ * @throws `ProfileError("VALIDATION_ERROR")` when `current.startDate` is
+ *   `null` and the caller did not supply a `startDate` override — the
+ *   wire requires a non-null `startDate` and we have nothing to send.
+ */
+export function buildUpdateEmploymentInput(current, fields) {
+    if (Object.keys(fields).length === 0) {
+        throw new ProfileError("VALIDATION_ERROR", "employment update requires at least one field flag.");
+    }
+    const startDate = fields.startDate ?? current.startDate;
+    if (startDate === null) {
+        throw new ProfileError("VALIDATION_ERROR", `Cannot update employment "${current.id}": startDate is required and current value is null. Supply --from to set a year.`);
+    }
+    // Server-side Rails `.blank?` gates (USER_ERROR "You can't leave this
+    // empty") — surfaced by the #394 live capture (2026-05-19): when the
+    // caller omits these, the wire layer accepts the partial input but
+    // the Rails apply path rejects it. Inject from the current row so
+    // user-supplied fields can still override. Optional pass-throughs
+    // (employerId / primaryGeographyId / reportingTo) are only set when
+    // the current row has a non-null value — sending an explicit null
+    // would change the row's state, which would defeat "merge".
+    //
+    // #401 WORM limitation (2026-05-19 live capture): the UpdateEmployment
+    // wire treats BOTH absence AND explicit null of `employerId` as Rails
+    // `.blank?` and rejects with "employerId: You can't leave this
+    // empty". Custom workplaces (CreateEmployment with `employerId: null`)
+    // therefore CANNOT be updated via this surface — they are write-once-
+    // read-many on Toptal. The "omit when null" branch below reflects
+    // this honestly: there is no employerId payload we can send that
+    // satisfies the wire for a null-employerId row. update() on such a
+    // row will surface the USER_ERROR verbatim. See
+    // `research/notes/15-employment-custom-workplace-worm.md` and #401.
+    const merged = {
+        // Wire-required non-null (GraphQL `Expected value to not be null`):
+        experienceItems: current.experienceItems ?? [],
+        // #407 — same wire-required non-null class: server rejects with
+        // `Expected value to not be null` for `employment.position` on any
+        // partial update that omits it. EMPLOYMENT_FRAGMENT selects `position`
+        // so `current.position` is always available to thread through.
+        position: current.position,
+        // Preserve current row's skills through the merge — server rejects
+        // `skills: []` with "is too short (minimum is 1 character)" on
+        // update (#394 live-capture finding 2026-05-19). The EMPLOYMENT_FRAGMENT
+        // now selects `skills { nodes { id name } }` so `current.skills` is
+        // populated; pre-#394 it was always `[]` and update() defaulted to
+        // empty, which is what the live wire was rejecting.
+        skills: current.skills,
+        showViaToptal: current.showViaToptal,
+        startDate,
+        // Rails `.blank?` gates:
+        company: current.company,
+        publicationPermit: current.publicationPermit ?? true,
+        // industryIds: catalog refs the wire requires present and non-empty
+        // on the apply path.
+        industryIds: current.industries.map((i) => i.id),
+    };
+    if (current.employerId !== null) {
+        merged.employerId = current.employerId;
+    }
+    if (current.primaryGeography !== null) {
+        merged.primaryGeographyId = current.primaryGeography.id;
+    }
+    if (current.reportingTo !== null) {
+        merged.reportingTo = current.reportingTo;
+    }
+    return { ...merged, ...fields };
 }
 /**
  * Update an existing employment row. Wire format per Pattern 1:
  * `{ employmentId, employment: EmploymentInput }`.
+ *
+ * Reads the current row first and merges the five required-non-null
+ * fields onto the wire input (see {@link buildUpdateEmploymentInput} for
+ * the merge contract and #394 + #407 for the originating wire-broke incidents).
  */
 export async function update(token, id, fields) {
     if (Object.keys(fields).length === 0) {
         throw new ProfileError("VALIDATION_ERROR", "employment update requires at least one field flag.");
     }
-    const res = await callTalentProfile(token, "UpdateEmployment", UPDATE_EMPLOYMENT_MUTATION, { input: { employmentId: id, employment: fields } }, "employment update");
+    const current = await show(token, id);
+    const employment = buildUpdateEmploymentInput(current, fields);
+    const res = await callTalentProfile(token, "UpdateEmployment", UPDATE_EMPLOYMENT_MUTATION, { input: { employmentId: id, employment } }, "employment update");
     const payload = unwrapMutation(res, "updateEmployment", "employment update");
     const updated = payload.profile?.employments.nodes
         .filter((n) => n !== null)