@joymerrevent/porters-connect 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -5,6 +5,85 @@
 
 ## [Unreleased]
 
+## [0.11.0] - 2026-08-30
+
+**参照先の項目を 1 往復で読めるようにし、`field` の語彙をクエリ全体と揃えた版**です。
+どちらも「**要求したものが黙って返らない**」を潰す変更で、`field` に接頭辞を書かなくなる
+**破壊的変更**を含みます（移行は接頭辞を消すだけ）。
+
+### Added
+
+- **参照型の展開 `expand`**（[ADR-0058][adr58]）。`System[Reference]` の項目（`Job.P_Client` など）から
+  **参照先の項目そのもの**を取得できるようになりました。これまでは参照先の **ID だけ**を取り出し、
+  入れ子で返ってきた残りを**黙って捨てて**いました。
+
+  ```ts
+  const page = await t.job.search({ expand: { P_Client: ["P_Id", "P_Name"] } });
+  page.items[0]?.P_Client; // { P_Id: number | null; P_Name: string | null } | null
+
+  const plain = await t.job.search();
+  plain.items[0]?.P_Client; // number | null（従来どおり）
+  ```
+
+  - **参照先の接頭辞は書きません**。`condition` / `order` / `field` と同じ素の alias で指定すると、
+    ライブラリが `field=Job.P_Client(Client.P_Id,Client.P_Name)` を組み立てます。
+    Candidate を参照するときの `Person.` も同様です。
+  - **`expand` を書いた項目だけ**戻り型が変わります。基底の型は `number | null` のままなので、
+    **参照を ID として使っているコードは無変更**です。展開しなかった参照も ID のまま返ります。
+  - `search` / `searchAll` / `get(id, { expand })` で使えます。`get` は第 2 引数が増えただけで、
+    既存の `get(id)` はそのままです。
+  - 展開した alias は**素のエントリを置き換えて**送られます。同じ alias を `()` 有り・無しで 2 回送ったとき
+    どちらが優先されるかは PORTERS のドキュメントに記述が無いため、**そもそも送りません**。
+  - 展開できるのは**参照先をライブラリが実装している項目**だけです。`P_Recruiter`（Recruiter は未実装）と
+    カスタム項目（`U_`/`A_`）の参照型は対象外で、**従来どおり ID として読めます**。書くと型エラーです。
+  - `field` に `"Job.P_Client(Client.P_Id)"` のような展開文字列を書くと、送信前に
+    `PortersConfigError` で止まり `expand` を案内します。
+  - `()` の中に付ける参照先の接頭辞と入れ子の形は**実機で未確認**です
+    （[live-verification][lv] LV-10 / LV-16）。応答の解釈はタグ名に依存しない実装です。
+
+- **型の export**: `Expand` / `ExpandedReadRecord` / `ReferenceMap` / `ResourcePageOf` /
+  `ReferenceRecord` / `ReadFieldAlias`。`FieldValue` に `ReferenceRecord`（展開された参照の値）が加わります。
+
+### Changed
+
+- **（破壊的）Read の `field` は接頭辞なしの alias で書きます**（[ADR-0059][adr59]）。
+  接頭辞はリソースごとの定数なので、**ライブラリが付けます**。
+
+  ```diff
+  - field: ["Person.P_Id", "Person.P_Name"]
+  + field: ["P_Id", "P_Name"]
+  ```
+
+  - 移行は**接頭辞を消すだけ**です。送られる URL は従来と同じで、変わるのは書き方と、
+    **どこで間違いに気づけるか**だけです。
+  - `condition` / `order` / `expand` はもともと素の alias を受けていたため、
+    **同じクエリの中で語彙が 2 つあった**状態が解消されます。
+  - **間違いがコンパイルエラーになります** — 綴り間違い（`P_Nmae`）・接頭辞付き（`Person.P_Name`）・
+    リソース名との取り違え（`Candidate.P_Name`。Candidate の接頭辞は `Person` です）・展開文字列。
+    これまでは型（`string[]`）でも送信前ガードでも素通りし、**PORTERS 側で黙って無視される**だけでした。
+  - **未宣言のカスタム項目は引き続き書けます**（`U_` / `A_` で始まる名前）。ただし `U_` 以降の綴りは
+    検査できないので、よく使うものは `defineFields` で宣言してください（宣言すれば綴りも検査されます）。
+  - 実行時は接頭辞付きが来ても**剥がして受けます**（応答側と対称の寛容さ）。cast 経由の古い形も壊れません。
+  - 対象は `SearchQuery.field`（データ 5 リソース）と `UserSearchQuery.field`（マスタ User）。
+    **Attachment は元から接頭辞なし**なので変更ありません。`field: []`（主キーのみ）と
+    省略時の既定 field（[ADR-0020][adr20]）の意味も変わりません。
+  - **pre-1.0 のため minor**（[ADR-0055][adr55] と同じ扱い）。
+
+- **明示した `field` も既定 field と同じ組み立てを通る**ようになりました。`User` 型の項目を
+  `field` で明示すると **4 サブ項目に展開**されます（`Job.P_Owner(User.P_Id,User.P_Type,User.P_Name,User.P_Mail)`）。
+  これまでは `()` 無しで送られ、PORTERS が ID を返すため、**型が `UserRef` を約束するのに実体は `null`**
+  になっていました。
+
+### Fixed
+
+- **参照 ID の読み取りが、リソース名と alias 接頭辞の食い違いで `null` に落ちていました**。
+  入れ子の**包みタグはリソース名**なのに**中の alias は接頭辞付き**で、この 2 つが異なる Candidate
+  （`<Candidate>` に `Person.P_Id`）では従来の照合が外れていました。**素の alias で照合**するようにしたので、
+  どちらの表記でも読めます。
+  - 影響していたのは `Process.P_Candidate` / `Resume.P_Candidate`（Candidate を参照する項目）です。
+    包みタグの実際の値は**実機で未確認**（[live-verification][lv] LV-10）で、フェイクサーバーは
+    これまで中立な包みを返していたため、テストでは露出していませんでした。
+
 ## [0.10.0] - 2026-08-22
 
 **partition の束ね方を 1 つに絞り、削除済みレコードを判別できるようにした版**です。
@@ -356,10 +435,13 @@
 [adr55]: docs/adr/0055-partition-binding-guard.md
 [adr56]: docs/adr/0056-deleted-flag-typing.md
 [adr57]: docs/adr/0057-itemstate-existing-explicit.md
+[adr58]: docs/adr/0058-reference-expansion-read.md
+[adr59]: docs/adr/0059-read-field-bare-alias.md
 [lv]: docs/live-verification.md
 [kac]: https://keepachangelog.com/en/1.1.0/
 [semver]: https://semver.org/
-[unreleased]: https://github.com/Joymerrevent/porters-connect/compare/v0.10.0...HEAD
+[unreleased]: https://github.com/Joymerrevent/porters-connect/compare/v0.11.0...HEAD
+[0.11.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.10.0...v0.11.0
 [0.10.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.9.0...v0.10.0
 [0.9.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.8.0...v0.9.0
 [0.8.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.7.0...v0.8.0

package/README.md

@@ -178,15 +178,18 @@ await porters.auth.exchangeAuthorizationCode(code);
 
 - `search(query?)` → `{ items, total, count, start }`（オフセット式ページング）。
 - `searchAll(query?)` → `AsyncIterable`（200 件刻みで全件 yield）。
-- `get(id)` → 1 件 or `undefined`。
+- `get(id, options?)` → 1 件 or `undefined`（`options.expand` で参照先の項目も読めます）。
 - `create(input)` → 採番された **id（number）**。
 - `update(id, input)` → その **id**。
 
 **検索クエリ**（`query`）の主なキー（すべて型安全。**項目の Data Type が許す演算子だけ**を受けます）：
 
-- `field`：取得する項目（接頭辞付き alias の配列。例 `["Person.P_Id", "Person.P_Name"]`）。
+- `field`：取得する項目（**接頭辞なし**の alias の配列。例 `["P_Id", "P_Name"]`。接頭辞はライブラリが付けます）。
+  綴り間違いや接頭辞付きは**コンパイルエラー**になります。
   **省略するとカタログ上の全項目を既定取得**します（PORTERS は field 未指定だと主キーのみ返すため、
   ライブラリが既定 field を補います）。`field: []`（空配列）を渡すと API 仕様どおり**主キーのみ**を返します（件数取得など）。
+- `expand`：参照型（`System[Reference]`）の項目について、**参照先の項目も読む**（`{ P_Client: ["P_Id", "P_Name"] }`）。
+  書かなければ従来どおり**参照先の ID**が返り、**書いた項目だけ**戻り型が参照レコードに変わります。1 往復で済みます。
 - `condition`：検索条件。`{ 項目: { 演算子: 値 } }` 形式（複数項目は AND）。演算子は Data Type ごとに
   `eq`/`gt`/`ge`/`le`/`lt`（数値・日時・Id）、`part`/`full`（テキスト）、`or`/`and`（Option・参照/ユーザー型は ID）。
   **日時の値は ISO 8601（UTC `…Z`）**で渡すと PORTERS 形式へ自動変換します。
@@ -198,8 +201,9 @@ await porters.auth.exchangeAuthorizationCode(code);
 > **削除 API はありません**（PORTERS 仕様）。`delete()` メソッドは提供しません。削除済みは `itemstate: "deleted"` で読みます
 > （`condition` は `P_Id` / `P_UpdateDate` / `P_UpdatedBy` に限られ、更新日は 90 日以内）。
 >
-> `field` の 3 通りの意味（省略＝全項目 / `[]`＝主キーのみ / 明示）、Data Type ごとの演算子一覧、
-> 削除済み Read の制約、送信前に落ちる条件は [Read クエリ ガイド][read-query-guide] にまとめています。
+> `field` の 3 通りの意味（省略＝全項目 / `[]`＝主キーのみ / 明示）、`expand` で展開できる項目、
+> Data Type ごとの演算子一覧、削除済み Read の制約、送信前に落ちる条件は
+> [Read クエリ ガイド][read-query-guide] にまとめています。
 
 ### カスタム項目（`U_` / `A_`）
 

package/dist/index.d.ts

@@ -137,7 +137,15 @@ type UserRef = {
     P_Name: string | null;
     P_Mail: string | null;
 };
-type FieldValue = string | number | string[] | UserRef | null;
+/**
+ * An **expanded** `System[Reference]` value: the referenced record's requested fields, decoded by
+ * the referenced resource's own catalog (ADR-0058). Only a read that asked for the expansion
+ * (`expand`) produces one — without it a reference decodes to the referenced id (`number`).
+ */
+type ReferenceRecord = {
+    [alias: string]: FieldValue;
+};
+type FieldValue = string | number | string[] | UserRef | ReferenceRecord | null;
 type DecodedValue<D extends DataType | null> = D extends null ? string : D extends "System[Id]" | "Number" | "System[Reference]" ? number : D extends "User" ? UserRef : D extends "Option" ? string[] : string;
 
 type WritableDataType = Exclude<DataType, "System[Id]" | "System[DateTime]">;
@@ -160,12 +168,92 @@ type EmptyCatalog = Record<never, never>;
 type ReadRecord<F extends FieldCatalog> = {
     [K in keyof F]?: DecodedValue<F[K]> | null;
 };
-type ResourcePage<F extends FieldCatalog> = {
-    items: ReadRecord<F>[];
+/**
+ * A page of decoded records: the standard Read envelope (Total / Count / Start) around whatever
+ * the item decoder produced. Parametrised by the *record* rather than the catalog because a read
+ * that expands references returns a wider record than the catalog alone describes (ADR-0058).
+ */
+type ResourcePageOf<T> = {
+    items: T[];
     total: number;
     count: number;
     start: number;
 };
+type ResourcePage<F extends FieldCatalog> = ResourcePageOf<ReadRecord<F>>;
+/**
+ * What a Read `field` entry may name (ADR-0059): a catalogued alias — every standard `P_` field
+ * plus the custom fields declared with `defineFields` (ADR-0023) — or an undeclared tenant custom
+ * field, admitted by the `U_`/`A_` naming rule `defineFields` already enforces at runtime.
+ *
+ * Aliases are **bare**: the resource's prefix (`Person.` for Candidate) is a constant the
+ * descriptor knows, so the library adds it. That makes `condition` / `order` / `field` one
+ * vocabulary and turns a typo (`P_Nmae`) or a hand-written prefix into a compile error instead of
+ * a request that quietly returns nothing.
+ */
+type ReadFieldAlias<F extends FieldCatalog> = (keyof F & string) | `U_${string}` | `A_${string}`;
+
+/**
+ * The resource a `System[Reference]` field points at, as far as expansion needs it: its alias
+ * prefix (what goes inside the `()`) and its Data-Type catalog (what decodes the answer).
+ *
+ * Structurally a {@link ResourceDescriptor}, spelled out here so the two types do not reference
+ * each other in a circle. Descriptors are passed in directly — the referenced prefix is **not**
+ * the resource name for Candidate (`Person`), which is exactly the trap this removes from callers.
+ */
+type ReferenceTarget = {
+    name: string;
+    path: string;
+    prefix: string;
+    fields: FieldCatalog;
+};
+/**
+ * A resource's expandable reference fields: bare alias -> the referenced resource's descriptor.
+ * Only catalogued `System[Reference]` fields whose target the library implements appear here;
+ * anything absent simply cannot be expanded (it still reads as the referenced id).
+ */
+type ReferenceMap = Readonly<Record<string, ReferenceTarget>>;
+/**
+ * "Nothing to expand": the identity default for the reference generic, mirroring
+ * {@link EmptyCatalog}. `Record<never, never>` keeps `keyof` empty, so every derived type
+ * collapses back to the un-expanded shape.
+ */
+type EmptyReferences = Record<never, never>;
+/** The catalog of a reference target — the type its expanded values decode by. */
+type CatalogOf$1<T> = T extends {
+    fields: infer F extends FieldCatalog;
+} ? F : never;
+/**
+ * What `expand` accepts: for each expandable reference field, the **bare aliases** to read from
+ * the referenced record. The referenced prefix is never written by the caller — the descriptor
+ * has it (ADR-0058). Only catalogued aliases of the target are allowed: an alias outside its
+ * catalog has no Data Type here, so nothing could type or decode it.
+ */
+type Expand<R extends ReferenceMap> = {
+    [K in keyof R]?: readonly (keyof CatalogOf$1<R[K]> & string)[];
+};
+/**
+ * The value an expanded reference field reads back as: the selected aliases, each decoded by the
+ * referenced catalog's Data Type.
+ *
+ * `[S] extends [...]` is deliberately **non-distributive**. A caller who declares their query as
+ * the loose `SearchQuery` type passes `S = readonly (...)[] | undefined`, which is not a promise
+ * that anything was expanded — that falls through to the un-expanded `number`, so naming the
+ * query type never changes what the record claims to hold.
+ */
+type ExpandedValue<T extends ReferenceTarget, S> = [S] extends [
+    readonly (infer A extends keyof CatalogOf$1<T> & string)[]
+] ? {
+    [K in A]?: DecodedValue<CatalogOf$1<T>[K]> | null;
+} : DecodedValue<"System[Reference]">;
+/**
+ * The read record for a query that expanded some references: the plain {@link ReadRecord}, with
+ * each expanded field's value replaced by the referenced record's own shape. Fields left out of
+ * `expand` keep the referenced id (`number`), so a caller who expands one relation pays no type
+ * cost on the others — that asymmetry is the point of `expand` over widening the base type.
+ */
+type ExpandedReadRecord<F extends FieldCatalog, R extends ReferenceMap, E> = Omit<ReadRecord<F>, keyof E> & {
+    [K in keyof E & keyof R]?: ExpandedValue<R[K], E[K]> | null;
+};
 
 /** Comparable ops for numeric Ids (System[Id]); `or` matches a set of Resource Ids (`P_Id:or=1:2`). */
 type IdCondition = {
@@ -244,14 +332,31 @@ type Order<F extends FieldCatalog> = Array<Partial<Record<OrderableKeys<F>, "asc
  * ever changes that default. Use `itemstate: "existing"` when live-only actually matters to you.
  */
 type ItemState = "existing" | "deleted" | "all";
-type SearchQuery<F extends FieldCatalog = FieldCatalog> = {
+type SearchQuery<F extends FieldCatalog = FieldCatalog, R extends ReferenceMap = EmptyReferences> = {
     /**
-     * Output fields as prefixed aliases (e.g. `Person.P_Name`). **Omit** to fetch every catalogued
+     * Output fields as **bare aliases** (e.g. `P_Name`) — the same vocabulary as `condition` and
+     * `order`; the library adds the resource's prefix (ADR-0059). **Omit** to fetch every catalogued
      * field by default (ADR-0020): PORTERS returns only the primary key for a fieldless request, so
      * the library sends a catalog-derived default field set instead. Pass `[]` to opt into that
-     * API-native "primary key only" response (e.g. counting). A non-empty list is sent verbatim.
+     * API-native "primary key only" response (e.g. counting).
      */
-    field?: string[];
+    field?: ReadFieldAlias<F>[];
+    /**
+     * Read the *fields* of a referenced record, not just its id (ADR-0058): map an expandable
+     * `System[Reference]` field to the bare aliases you want from the resource it points at. The
+     * referenced prefix is supplied by the library, and the expanded fields come back decoded by
+     * that resource's own Data Types.
+     *
+     * ```ts
+     * const page = await t.job.search({ expand: { P_Client: ["P_Id", "P_Name"] } });
+     * page.items[0]?.P_Client; // { P_Id: number | null; P_Name: string | null } | null
+     * ```
+     *
+     * A field left out of `expand` still reads as the referenced id — expanding one relation costs
+     * nothing on the others. An expanded alias replaces its plain `field` entry, so nothing is
+     * requested twice.
+     */
+    expand?: Expand<R>;
     /** Typed AND-conditions; each field's operators derive from its Data Type (ADR-0038). */
     condition?: Condition<F>;
     /** Sort order; orderable Data Types only (Number/Date/DateTime/Age/System). */
@@ -305,11 +410,18 @@ type CreateInput<F extends FieldCatalog, Req extends keyof F> = {
 type UpdateInput<F extends FieldCatalog> = {
     [K in WritableKeys<F>]?: WriteValueOf<F[K]> | null;
 };
-type Resource<F extends FieldCatalog, Req extends keyof F> = {
-    search(query?: SearchQuery<F>): Promise<ResourcePage<F>>;
+type Resource<F extends FieldCatalog, Req extends keyof F, R extends ReferenceMap = EmptyReferences> = {
+    search<const E extends Expand<R> = EmptyReferences>(query?: SearchQuery<F, R> & {
+        expand?: E;
+    }): Promise<ResourcePageOf<ExpandedReadRecord<F, R, E>>>;
     /** Auto-paginating search: yields every matching record (200 per page). */
-    searchAll(query?: Omit<SearchQuery<F>, "count" | "start">): AsyncIterable<ReadRecord<F>>;
-    get(id: number): Promise<ReadRecord<F> | undefined>;
+    searchAll<const E extends Expand<R> = EmptyReferences>(query?: Omit<SearchQuery<F, R>, "count" | "start"> & {
+        expand?: E;
+    }): AsyncIterable<ExpandedReadRecord<F, R, E>>;
+    /** Read one record by id. `expand` reads referenced records too (ADR-0058). */
+    get<const E extends Expand<R> = EmptyReferences>(id: number, options?: {
+        expand?: E;
+    }): Promise<ExpandedReadRecord<F, R, E> | undefined>;
     /** Create one record; resolves to the newly assigned id. */
     create(input: CreateInput<F, Req>): Promise<number>;
     /** Update one record by id; resolves to that id. */
@@ -407,16 +519,44 @@ declare const FIELDS$7: {
     readonly P_Deleted: null;
 };
 declare const REQUIRED_ON_CREATE$3: readonly ["P_Owner", "P_Client", "P_Recruiter"];
+declare const REFERENCES$2: {
+    readonly P_Client: {
+        readonly name: "Client";
+        readonly path: "client";
+        readonly prefix: "Client";
+        readonly fields: {
+            readonly P_Id: "System[Id]";
+            readonly P_Owner: "User";
+            readonly P_RegistrationDate: "System[DateTime]";
+            readonly P_RegisteredBy: "User";
+            readonly P_UpdateDate: "System[DateTime]";
+            readonly P_UpdatedBy: "User";
+            readonly P_Phase: "Option";
+            readonly P_PhaseDate: "DateTime";
+            readonly P_PhaseMemo: "MultilineText";
+            readonly P_Name: "SinglelineText";
+            readonly P_Memo: "MultilineText";
+            readonly P_Country: "SinglelineText";
+            readonly P_Prefecture: "SinglelineText";
+            readonly P_City: "SinglelineText";
+            readonly P_Street: "MultilineText";
+            readonly P_Zipcode: "SinglelineText";
+            readonly P_Telephone: "Telephone";
+            readonly P_Fax: "Telephone";
+            readonly P_Deleted: null;
+        };
+    };
+};
 /** A decoded Job: known `P_` fields, each requested field `value | null`. */
 type Job = ReadRecord<typeof FIELDS$7>;
 type JobPage = ResourcePage<typeof FIELDS$7>;
-type JobSearchQuery = SearchQuery<typeof FIELDS$7>;
+type JobSearchQuery = SearchQuery<typeof FIELDS$7, typeof REFERENCES$2>;
 /** Fields for `create`: `P_Owner` required; `P_Id` / system timestamps are not settable. */
 type JobCreateInput = CreateInput<typeof FIELDS$7, (typeof REQUIRED_ON_CREATE$3)[number]>;
 /** Fields for `update`: all optional (`null` omits, `""` clears a text field). */
 type JobUpdateInput = UpdateInput<typeof FIELDS$7>;
 /** The Job accessor; `C` is the declared custom-field catalog merged on (ADR-0023). */
-type JobResource<C extends FieldCatalog = EmptyCatalog> = Resource<typeof FIELDS$7 & C, (typeof REQUIRED_ON_CREATE$3)[number]>;
+type JobResource<C extends FieldCatalog = EmptyCatalog> = Resource<typeof FIELDS$7 & C, (typeof REQUIRED_ON_CREATE$3)[number], typeof REFERENCES$2>;
 
 declare const FIELDS$6: {
     readonly P_Id: "System[Id]";
@@ -473,17 +613,215 @@ declare const FIELDS$5: {
     readonly P_Deleted: null;
 };
 declare const REQUIRED_ON_CREATE$1: readonly ["P_Owner", "P_Client", "P_Recruiter", "P_Job", "P_Candidate", "P_Resume"];
+declare const REFERENCES$1: {
+    readonly P_Client: {
+        readonly name: "Client";
+        readonly path: "client";
+        readonly prefix: "Client";
+        readonly fields: {
+            readonly P_Id: "System[Id]";
+            readonly P_Owner: "User";
+            readonly P_RegistrationDate: "System[DateTime]";
+            readonly P_RegisteredBy: "User";
+            readonly P_UpdateDate: "System[DateTime]";
+            readonly P_UpdatedBy: "User";
+            readonly P_Phase: "Option";
+            readonly P_PhaseDate: "DateTime";
+            readonly P_PhaseMemo: "MultilineText";
+            readonly P_Name: "SinglelineText";
+            readonly P_Memo: "MultilineText";
+            readonly P_Country: "SinglelineText";
+            readonly P_Prefecture: "SinglelineText";
+            readonly P_City: "SinglelineText";
+            readonly P_Street: "MultilineText";
+            readonly P_Zipcode: "SinglelineText";
+            readonly P_Telephone: "Telephone";
+            readonly P_Fax: "Telephone";
+            readonly P_Deleted: null;
+        };
+    };
+    readonly P_Job: {
+        readonly name: "Job";
+        readonly path: "job";
+        readonly prefix: "Job";
+        readonly fields: {
+            readonly P_Id: "System[Id]";
+            readonly P_Owner: "User";
+            readonly P_Client: "System[Reference]";
+            readonly P_Recruiter: "System[Reference]";
+            readonly P_RegistrationDate: "System[DateTime]";
+            readonly P_RegisteredBy: "User";
+            readonly P_UpdateDate: "System[DateTime]";
+            readonly P_UpdatedBy: "User";
+            readonly P_Phase: "Option";
+            readonly P_PhaseDate: "DateTime";
+            readonly P_PhaseMemo: "MultilineText";
+            readonly P_Position: "SinglelineText";
+            readonly P_Publish: "Option";
+            readonly P_JobCategorySummary: "MultilineText";
+            readonly P_JobCategory: "Option";
+            readonly P_IndustrySummary: "MultilineText";
+            readonly P_Industry: "Option";
+            readonly P_SalarySummary: "MultilineText";
+            readonly P_MinSalary: "Number";
+            readonly P_MaxSalary: "Number";
+            readonly P_AreaSummary: "MultilineText";
+            readonly P_Area: "Option";
+            readonly P_PayrollsText: "SinglelineText";
+            readonly P_Memo: "MultilineText";
+            readonly P_EmploymentPeriod: "MultilineText";
+            readonly P_WokingHours: "MultilineText";
+            readonly P_Holidays: "MultilineText";
+            readonly P_Benefits: "MultilineText";
+            readonly P_PubliclyTraded: "Option";
+            readonly P_SalesAmountText: "SinglelineText";
+            readonly P_EstablishmentDateText: "SinglelineText";
+            readonly P_CapitalText: "SinglelineText";
+            readonly P_EmploymentType: "Option";
+            readonly P_ExpectedAgeReason: "Option";
+            readonly P_Deleted: null;
+        };
+        readonly references: {
+            readonly P_Client: {
+                readonly name: "Client";
+                readonly path: "client";
+                readonly prefix: "Client";
+                readonly fields: {
+                    readonly P_Id: "System[Id]";
+                    readonly P_Owner: "User";
+                    readonly P_RegistrationDate: "System[DateTime]";
+                    readonly P_RegisteredBy: "User";
+                    readonly P_UpdateDate: "System[DateTime]";
+                    readonly P_UpdatedBy: "User";
+                    readonly P_Phase: "Option";
+                    readonly P_PhaseDate: "DateTime";
+                    readonly P_PhaseMemo: "MultilineText";
+                    readonly P_Name: "SinglelineText";
+                    readonly P_Memo: "MultilineText";
+                    readonly P_Country: "SinglelineText";
+                    readonly P_Prefecture: "SinglelineText";
+                    readonly P_City: "SinglelineText";
+                    readonly P_Street: "MultilineText";
+                    readonly P_Zipcode: "SinglelineText";
+                    readonly P_Telephone: "Telephone";
+                    readonly P_Fax: "Telephone";
+                    readonly P_Deleted: null;
+                };
+            };
+        };
+    };
+    readonly P_Candidate: {
+        readonly name: "Candidate";
+        readonly path: "candidate";
+        readonly prefix: "Person";
+        readonly fields: {
+            readonly P_Id: "System[Id]";
+            readonly P_Owner: "User";
+            readonly P_RegistrationDate: "System[DateTime]";
+            readonly P_RegisteredBy: "User";
+            readonly P_UpdateDate: "System[DateTime]";
+            readonly P_UpdatedBy: "User";
+            readonly P_Phase: "Option";
+            readonly P_PhaseDate: "DateTime";
+            readonly P_PhaseMemo: "MultilineText";
+            readonly P_Name: "SinglelineText";
+            readonly P_Reading: "SinglelineText";
+            readonly P_Memo: "MultilineText";
+            readonly P_Mail: "Mail";
+            readonly P_MobileMail: "Mail";
+            readonly P_Telephone: "Telephone";
+            readonly P_Mobile: "Telephone";
+            readonly P_Fax: "Telephone";
+            readonly P_Country: "SinglelineText";
+            readonly P_Prefecture: "SinglelineText";
+            readonly P_City: "SinglelineText";
+            readonly P_Street: "MultilineText";
+            readonly P_Zipcode: "SinglelineText";
+            readonly P_Deleted: null;
+        };
+    };
+    readonly P_Resume: {
+        readonly name: "Resume";
+        readonly path: "resume";
+        readonly prefix: "Resume";
+        readonly fields: {
+            readonly P_Id: "System[Id]";
+            readonly P_Owner: "User";
+            readonly P_Candidate: "System[Reference]";
+            readonly P_RegistrationDate: "System[DateTime]";
+            readonly P_RegisteredBy: "User";
+            readonly P_UpdateDate: "System[DateTime]";
+            readonly P_UpdatedBy: "User";
+            readonly P_Phase: "Option";
+            readonly P_PhaseDate: "DateTime";
+            readonly P_PhaseMemo: "MultilineText";
+            readonly P_Name: "SinglelineText";
+            readonly P_RegisterChannel: "Option";
+            readonly P_Memo: "MultilineText";
+            readonly P_CurrentStatus: "Option";
+            readonly P_Education: "MultilineText";
+            readonly P_CarrierSummary: "MultilineText";
+            readonly P_CurrentSalary: "Number";
+            readonly P_ExperiencedJobCategory: "Option";
+            readonly P_ExperiencedIndustry: "Option";
+            readonly P_ChangeJobsCount: "Number";
+            readonly P_Gender: "Option";
+            readonly P_DateOfBirth: "Age";
+            readonly P_ExpectEmploymentType: "Option";
+            readonly P_ExpectArea: "Option";
+            readonly P_ExpectJobCategory: "Option";
+            readonly P_ExpectIndustry: "Option";
+            readonly P_ExpectCondition: "MultilineText";
+            readonly P_ExpectSalary: "Number";
+            readonly P_DesiredHourlyRate: "Number";
+            readonly P_HourlyRate: "Number";
+            readonly P_Deleted: null;
+        };
+        readonly references: {
+            readonly P_Candidate: {
+                readonly name: "Candidate";
+                readonly path: "candidate";
+                readonly prefix: "Person";
+                readonly fields: {
+                    readonly P_Id: "System[Id]";
+                    readonly P_Owner: "User";
+                    readonly P_RegistrationDate: "System[DateTime]";
+                    readonly P_RegisteredBy: "User";
+                    readonly P_UpdateDate: "System[DateTime]";
+                    readonly P_UpdatedBy: "User";
+                    readonly P_Phase: "Option";
+                    readonly P_PhaseDate: "DateTime";
+                    readonly P_PhaseMemo: "MultilineText";
+                    readonly P_Name: "SinglelineText";
+                    readonly P_Reading: "SinglelineText";
+                    readonly P_Memo: "MultilineText";
+                    readonly P_Mail: "Mail";
+                    readonly P_MobileMail: "Mail";
+                    readonly P_Telephone: "Telephone";
+                    readonly P_Mobile: "Telephone";
+                    readonly P_Fax: "Telephone";
+                    readonly P_Country: "SinglelineText";
+                    readonly P_Prefecture: "SinglelineText";
+                    readonly P_City: "SinglelineText";
+                    readonly P_Street: "MultilineText";
+                    readonly P_Zipcode: "SinglelineText";
+                    readonly P_Deleted: null;
+                };
+            };
+        };
+    };
+};
 /** A decoded Process (a Candidate's progress through a Job): known `P_` fields, each
  *  requested field `value | null`. */
 type Process = ReadRecord<typeof FIELDS$5>;
 type ProcessPage = ResourcePage<typeof FIELDS$5>;
-type ProcessSearchQuery = SearchQuery<typeof FIELDS$5>;
+type ProcessSearchQuery = SearchQuery<typeof FIELDS$5, typeof REFERENCES$1>;
 /** Fields for `create`: `P_Owner` required; `P_Id` / system timestamps are not settable. */
 type ProcessCreateInput = CreateInput<typeof FIELDS$5, (typeof REQUIRED_ON_CREATE$1)[number]>;
 /** Fields for `update`: all optional (`null` omits, `""` clears a text field). */
 type ProcessUpdateInput = UpdateInput<typeof FIELDS$5>;
 /** The Process accessor; `C` is the declared custom-field catalog merged on (ADR-0023). */
-type ProcessResource<C extends FieldCatalog = EmptyCatalog> = Resource<typeof FIELDS$5 & C, (typeof REQUIRED_ON_CREATE$1)[number]>;
+type ProcessResource<C extends FieldCatalog = EmptyCatalog> = Resource<typeof FIELDS$5 & C, (typeof REQUIRED_ON_CREATE$1)[number], typeof REFERENCES$1>;
 
 declare const FIELDS$4: {
     readonly P_Id: "System[Id]";
@@ -519,17 +857,49 @@ declare const FIELDS$4: {
     readonly P_Deleted: null;
 };
 declare const REQUIRED_ON_CREATE: readonly ["P_Owner", "P_Candidate"];
+declare const REFERENCES: {
+    readonly P_Candidate: {
+        readonly name: "Candidate";
+        readonly path: "candidate";
+        readonly prefix: "Person";
+        readonly fields: {
+            readonly P_Id: "System[Id]";
+            readonly P_Owner: "User";
+            readonly P_RegistrationDate: "System[DateTime]";
+            readonly P_RegisteredBy: "User";
+            readonly P_UpdateDate: "System[DateTime]";
+            readonly P_UpdatedBy: "User";
+            readonly P_Phase: "Option";
+            readonly P_PhaseDate: "DateTime";
+            readonly P_PhaseMemo: "MultilineText";
+            readonly P_Name: "SinglelineText";
+            readonly P_Reading: "SinglelineText";
+            readonly P_Memo: "MultilineText";
+            readonly P_Mail: "Mail";
+            readonly P_MobileMail: "Mail";
+            readonly P_Telephone: "Telephone";
+            readonly P_Mobile: "Telephone";
+            readonly P_Fax: "Telephone";
+            readonly P_Country: "SinglelineText";
+            readonly P_Prefecture: "SinglelineText";
+            readonly P_City: "SinglelineText";
+            readonly P_Street: "MultilineText";
+            readonly P_Zipcode: "SinglelineText";
+            readonly P_Deleted: null;
+        };
+    };
+};
 /** A decoded Resume (a Candidate's CV / profile): known `P_` fields, each requested field
  *  `value | null`. */
 type Resume = ReadRecord<typeof FIELDS$4>;
 type ResumePage = ResourcePage<typeof FIELDS$4>;
-type ResumeSearchQuery = SearchQuery<typeof FIELDS$4>;
+type ResumeSearchQuery = SearchQuery<typeof FIELDS$4, typeof REFERENCES>;
 /** Fields for `create`: `P_Owner` required; `P_Id` / system timestamps are not settable. */
 type ResumeCreateInput = CreateInput<typeof FIELDS$4, (typeof REQUIRED_ON_CREATE)[number]>;
 /** Fields for `update`: all optional (`null` omits, `""` clears a text field). */
 type ResumeUpdateInput = UpdateInput<typeof FIELDS$4>;
 /** The Resume accessor; `C` is the declared custom-field catalog merged on (ADR-0023). */
-type ResumeResource<C extends FieldCatalog = EmptyCatalog> = Resource<typeof FIELDS$4 & C, (typeof REQUIRED_ON_CREATE)[number]>;
+type ResumeResource<C extends FieldCatalog = EmptyCatalog> = Resource<typeof FIELDS$4 & C, (typeof REQUIRED_ON_CREATE)[number], typeof REFERENCES>;
 
 /** A decoded Attachment. A field is `null` unless it was returned (see `field`). */
 type Attachment = {
@@ -620,8 +990,11 @@ type UserSearchQuery = {
     requestType?: 0 | 1;
     /** -1 = any (default), 0 = system admins, 1 = standard users. */
     userType?: -1 | 0 | 1;
-    /** Output fields (prefixed aliases). Omit to get the 4 core fields (this catalog). */
-    field?: string[];
+    /**
+     * Output fields as **bare aliases** (`P_Name`); the library adds the `User.` prefix (ADR-0059).
+     * Omit to get the 4 core fields (this catalog).
+     */
+    field?: ReadFieldAlias<typeof FIELDS$2>[];
     count?: number;
     start?: number;
 };
@@ -920,4 +1293,4 @@ declare const bytesToBase64: (bytes: Uint8Array) => string;
 /** Decode a Base64 string back to raw bytes. */
 declare const base64ToBytes: (b64: string) => Uint8Array;
 
-export { type Attachment, type AttachmentCreate, type AttachmentPage, type AttachmentResource, type AttachmentSearchQuery, type AttachmentUpdate, type AuthApi, type AuthorizationUrlOptions, type BulkWriteResult, type BulkWriteResultItem, type Candidate, type CandidateCreateInput, type CandidatePage, type CandidateResource, type CandidateSearchQuery, type CandidateUpdateInput, type Client, type ClientCreateInput, type ClientPage, type ClientResource, type ClientSearchQuery, type ClientUpdateInput, type Condition, type CustomDataType, type CustomFieldResource, type CustomFor, type DeclaredCatalogs, type DefinedFields, type ErrorCategory, type Field, type FieldBuilder, type FieldDecls, type FieldDef, type FieldPage, type FieldResource, type FieldSearchQuery, type FieldValue, type GetAccessTokenOptions, type ItemState, type Job, type JobCreateInput, type JobPage, type JobResource, type JobSearchQuery, type JobUpdateInput, type MockHandler, type MockReply, type MockTransportOptions, type Option, type OptionResource, type OptionSearchQuery, type Order, type Partition, type PartitionId, type PartitionPage, type PartitionResource, type PartitionSearchQuery, PortersAuthError, PortersClient, type PortersClientOptions, PortersConfigError, PortersError, type PortersErrorContext, type PortersErrorOptions, PortersNetworkError, PortersResourceError, type Process, type ProcessCreateInput, type ProcessPage, type ProcessResource, type ProcessSearchQuery, type ProcessUpdateInput, type ResourceType, type Resume, type ResumeCreateInput, type ResumePage, type ResumeResource, type ResumeSearchQuery, type ResumeUpdateInput, type RevokeUrlOptions, type Scheme, type Scope, type SearchQuery, type StoredTokens, type TenantScope, type TokenProvider, type TokenStore, type Transport, type TransportRequest, type TransportResponse, type User, type UserPage, type UserRef, type UserResource, type UserSearchQuery, base64ToBytes, bytesToBase64, createMockTransport, defineFields };
+export { type Attachment, type AttachmentCreate, type AttachmentPage, type AttachmentResource, type AttachmentSearchQuery, type AttachmentUpdate, type AuthApi, type AuthorizationUrlOptions, type BulkWriteResult, type BulkWriteResultItem, type Candidate, type CandidateCreateInput, type CandidatePage, type CandidateResource, type CandidateSearchQuery, type CandidateUpdateInput, type Client, type ClientCreateInput, type ClientPage, type ClientResource, type ClientSearchQuery, type ClientUpdateInput, type Condition, type CustomDataType, type CustomFieldResource, type CustomFor, type DeclaredCatalogs, type DefinedFields, type ErrorCategory, type Expand, type ExpandedReadRecord, type Field, type FieldBuilder, type FieldDecls, type FieldDef, type FieldPage, type FieldResource, type FieldSearchQuery, type FieldValue, type GetAccessTokenOptions, type ItemState, type Job, type JobCreateInput, type JobPage, type JobResource, type JobSearchQuery, type JobUpdateInput, type MockHandler, type MockReply, type MockTransportOptions, type Option, type OptionResource, type OptionSearchQuery, type Order, type Partition, type PartitionId, type PartitionPage, type PartitionResource, type PartitionSearchQuery, PortersAuthError, PortersClient, type PortersClientOptions, PortersConfigError, PortersError, type PortersErrorContext, type PortersErrorOptions, PortersNetworkError, PortersResourceError, type Process, type ProcessCreateInput, type ProcessPage, type ProcessResource, type ProcessSearchQuery, type ProcessUpdateInput, type ReadFieldAlias, type ReferenceMap, type ReferenceRecord, type ResourcePageOf, type ResourceType, type Resume, type ResumeCreateInput, type ResumePage, type ResumeResource, type ResumeSearchQuery, type ResumeUpdateInput, type RevokeUrlOptions, type Scheme, type Scope, type SearchQuery, type StoredTokens, type TenantScope, type TokenProvider, type TokenStore, type Transport, type TransportRequest, type TransportResponse, type User, type UserPage, type UserRef, type UserResource, type UserSearchQuery, base64ToBytes, bytesToBase64, createMockTransport, defineFields };