@joymerrevent/porters-connect 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -5,6 +5,71 @@
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-08-22
+
+**partition の束ね方を 1 つに絞り、削除済みレコードを判別できるようにした版**です。
+`PortersClient` から `partition` を外した**破壊的変更**を含みます（移行は下記）。
+併せて、削除済みを読めるのに**どれが削除済みか分からなかった**穴を塞ぎました。
+
+### Added
+
+- **削除フラグ `P_Deleted`**（[ADR-0056][adr56]）。データ系 5 リソース（Candidate / Job / Client /
+  Process / Resume）の公開型に加わり、`itemstate: "all"` の結果から削除済みを**判別できる**ようになりました。
+
+  ```ts
+  const page = await t.candidate.search({ itemstate: "all" });
+  const deleted = page.items.filter((c) => c.P_Deleted === "1");
+  ```
+
+  - **値は文字列**の `"0"`（生存）／`"1"`（削除済み）です。`number` でも `boolean` でもありません。
+    PORTERS がこの項目に **Data Type を与えていない**（reference の Field Type / Data Type 欄がともに「ー」）ため、
+    変換の基準がありません。勝手に決めればライブラリの発明になるので、**生の値のまま**返します。
+  - **`condition` にも `order` にも指定できず、Write もできません**（PORTERS の制約）。
+    いずれも型で表現されているので、書くとコンパイルエラーになります。
+  - `field` を省略すれば**自動で要求**されます。自分で `field` を渡すときは
+    `"Person.P_Deleted"` のように接頭辞付きで明示してください。
+  - 削除 API が無い PORTERS では「削除済みを読む」こと自体が運用手段（同期・監査・復元の判断材料）ですが、
+    これまでは**読めるのに解釈できない**状態でした。
+  - 応答での出現条件と値域は**実機で未確認**です（[live-verification][lv] LV-14）。
+
+### Changed
+
+- **（破壊的）`PortersClient` から `partition` を外しました**（[ADR-0055][adr55]）。
+  partition（Company DB）スコープのリソースは **`porters.tenant(id)` 経由でのみ**取得します。
+  **単一テナントでも同じ形**です。
+
+  ```diff
+  - const porters = new PortersClient({ host, appId, appSecret, partition: 123 });
+  - await porters.candidate.search();
+  + const porters = new PortersClient({ host, appId, appSecret });
+  + const t = porters.tenant(123);
+  + await t.candidate.search();
+  ```
+
+  - 影響するのは `candidate` / `job` / `client` / `process` / `resume` / `attachment` /
+    `user` / `field` / `option` の 9 アクセサ。`t` は以降クライアントのように使えるので、
+    **呼び出し側の書き味は変わりません**。
+  - **App レベルのものは `porters` 側に残ります**（いずれも `partition` を取りません）—
+    `porters.auth.*`（OAuth）と `porters.partition.search()`（partition の発見）。
+  - 理由: `partition` 未設定のクライアントは**`partition=0`** を全リクエストに載せていました。
+    `0` は PORTERS のドキュメントに存在しない値で、由来は最初の PoC の穴埋めです。実際には
+    Result Code **404** を招くため、**設定漏れが「サーバーが 404 を返す」形に化け**ていました。
+    `tenant(id)` を唯一の経路にすることで、**「partition を束ね忘れたクライアント」という状態が
+    型として存在しなくなります**。実行時ガードを足すのではなく、設計で防ぐ形にしました。
+  - **pre-1.0 のため minor**。誤った partition を渡すこと自体は妨げません（404 はサーバーが答えます）。
+
+### Fixed
+
+- **`itemstate: "existing"` を明示指定したとき、省略せずそのまま送る**ようになりました
+  （[ADR-0057][adr57]）。**返るデータは変わりません** — 変わるのは送信 URL だけです。
+  - これまでは `existing` が API の既定であることを理由に、明示指定でも param を省いていました。
+    しかし**省略（「既定に委ねる」）と明示（「生存レコードのみが欲しい」）は別の意思表示**です。
+    いま結果が同じなのは PORTERS の既定が `existing` だからで、**もし将来この既定が変われば、
+    生存のみを求めたコードに削除済みが混ざり始めます**（例外も Result Code も出ないので気づけません）。
+  - 生存のみであることが業務上重要なら、省略せず `itemstate: "existing"` と書いてください。
+    省略した場合はこれまでどおり API の既定に従います。
+  - `itemstate=existing` の実機送信実績はまだありません（[live-verification][lv] LV-15）。
+
 ## [0.9.0] - 2026-08-20
 
 **Candidate でメモ・住所詳細が扱えるようになった版**です。標準項目でありながらカタログから漏れていた
@@ -288,9 +353,14 @@
 [adr35]: docs/adr/0035-usage-documentation-structure.md
 [custom-fields-guide]: docs/guide/custom-fields.md
 [read-query-guide]: docs/guide/read-query.md
+[adr55]: docs/adr/0055-partition-binding-guard.md
+[adr56]: docs/adr/0056-deleted-flag-typing.md
+[adr57]: docs/adr/0057-itemstate-existing-explicit.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.9.0...HEAD
+[unreleased]: https://github.com/Joymerrevent/porters-connect/compare/v0.10.0...HEAD
+[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
 [0.7.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.6.2...v0.7.0

package/README.md

@@ -58,15 +58,14 @@ const porters = new PortersClient({
   scheme: process.env.PORTERS_SCHEME === "http" ? "http" : undefined,
   appId: process.env.PORTERS_APP_ID!,
   appSecret: process.env.PORTERS_APP_SECRET!,
-  partition: 123, // 既定 Partition（Company DB）Id
 });
 
-// 複数 partition を 1 つの App で扱う SaaS は porters.tenant(id) で束ねる
+// partition（Company DB）は tenant で一度だけ束ねる。**単一テナントでもこの形**
+// 以降は `t` をクライアントのように使う（client 直下には auth と partition マスタだけ）
 const t = porters.tenant(456);
-await t.candidate.search({ condition: { P_Name: { part: "鈴木" } } }); // partition=456
 
 // 検索（最大 200 件/ページ）。condition は項目の Data Type ごとに型付き
-const page = await porters.candidate.search({
+const page = await t.candidate.search({
   condition: { P_Name: { part: "山田" } }, // テキストは part（部分一致）/ full（完全一致）
   order: [{ P_UpdateDate: "desc" }], // 並び順（数値・日時・System のみ）
   count: 50,
@@ -74,18 +73,21 @@ const page = await porters.candidate.search({
 console.log(page.total, page.items.length);
 
 // 1 件取得
-const one = await porters.candidate.get(10001);
+const one = await t.candidate.get(10001);
 console.log(one?.P_Name);
 
 // 全件を自動ページング（200 件刻み）
-for await (const c of porters.candidate.searchAll({
+for await (const c of t.candidate.searchAll({
   condition: { P_Prefecture: { full: "東京都" } },
 })) {
   // c は 1 件ずつ
 }
 ```
 
-> 複数 partition を 1 つの App で扱う（マルチテナント SaaS）場合の `porters.tenant(id)` スコープ・テナント別 client・partition 発見は [マルチテナント ガイド][multi-tenancy] にまとめています。
+> **`partition` はクライアントに持たせません**（ADR-0055）。PORTERS は partition スコープの全リクエストで
+> `partition` を要求するので、`tenant(id)` で**明示的に一度だけ**束ねる形にしています。
+> 複数 partition を 1 つの App で扱う場合・テナント別 client・partition の発見は
+> [マルチテナント ガイド][multi-tenancy] にまとめています。
 >
 > 認証情報やホスト名は**コミットしない**でください。`.env.example` を参考に `.env` で渡します。
 
@@ -103,7 +105,6 @@ const porters = new PortersClient({
   host: "sandbox.invalid",
   appId: "demo",
   appSecret: "demo",
-  partition: 1,
   transport: createMockTransport((req) =>
     req.url.includes("/v1/candidate")
       ? `<Candidate Total="1" Count="1" Start="0"><Code>0</Code><Item><Person.P_Id>1</Person.P_Id><Person.P_Name>山田 太郎</Person.P_Name></Item></Candidate>`
@@ -111,7 +112,7 @@ const porters = new PortersClient({
   ), // 未モックのリクエストは明示エラー（フェイルセーフ）
 });
 
-const page = await porters.candidate.search();
+const page = await t.candidate.search();
 console.log(page.items[0]?.P_Name); // 山田 太郎
 ```
 
@@ -141,7 +142,7 @@ const tokenStore: TokenStore = {
     /* 破棄 */
   },
 };
-new PortersClient({ host, appId, appSecret, partition, tokenStore });
+new PortersClient({ host, appId, appSecret, tokenStore });
 ```
 
 `transport`（HTTP 注入）や `auth`（独自 `TokenProvider`）も差し替え可能です。
@@ -166,14 +167,14 @@ await porters.auth.exchangeAuthorizationCode(code);
 
 すべてのデータ系リソースは同じ形のアクセサを持ちます。
 
-| アクセサ             | リソース     | メソッド                                             |
-| -------------------- | ------------ | ---------------------------------------------------- |
-| `porters.candidate`  | 個人連絡先   | `search` / `searchAll` / `get` / `create` / `update` |
-| `porters.job`        | JOB          | `search` / `searchAll` / `get` / `create` / `update` |
-| `porters.client`     | 企業         | `search` / `searchAll` / `get` / `create` / `update` |
-| `porters.process`    | 選考プロセス | `search` / `searchAll` / `get` / `create` / `update` |
-| `porters.resume`     | レジュメ     | `search` / `searchAll` / `get` / `create` / `update` |
-| `porters.attachment` | 添付ファイル | `search` / `get` / `create` / `update`               |
+| アクセサ       | リソース     | メソッド                                             |
+| -------------- | ------------ | ---------------------------------------------------- |
+| `t.candidate`  | 個人連絡先   | `search` / `searchAll` / `get` / `create` / `update` |
+| `t.job`        | JOB          | `search` / `searchAll` / `get` / `create` / `update` |
+| `t.client`     | 企業         | `search` / `searchAll` / `get` / `create` / `update` |
+| `t.process`    | 選考プロセス | `search` / `searchAll` / `get` / `create` / `update` |
+| `t.resume`     | レジュメ     | `search` / `searchAll` / `get` / `create` / `update` |
+| `t.attachment` | 添付ファイル | `search` / `get` / `create` / `update`               |
 
 - `search(query?)` → `{ items, total, count, start }`（オフセット式ページング）。
 - `searchAll(query?)` → `AsyncIterable`（200 件刻みで全件 yield）。
@@ -214,11 +215,10 @@ const porters = new PortersClient({
   host,
   appId,
   appSecret,
-  partition,
   fields,
 });
 
-const one = await porters.candidate.get(10001);
+const one = await t.candidate.get(10001);
 one?.U_score; // number | null | undefined
 ```
 
@@ -234,25 +234,25 @@ one?.U_score; // number | null | undefined
 | アクセサ            | リソース          | メソッド                           | 主なクエリ                                |
 | ------------------- | ----------------- | ---------------------------------- | ----------------------------------------- |
 | `porters.partition` | Partition         | `search` / `searchAll`             | `requestType`（1=アクセス可能一覧・既定） |
-| `porters.user`      | User              | `search` / `searchAll` / `current` | `requestType` / `userType` / `field`      |
-| `porters.field`     | Field（項目定義） | `search` / `searchAll`             | `resource`（必須）/ `active`              |
-| `porters.option`    | Option（選択肢）  | `search`                           | `alias` / `level` / `enabled`             |
+| `t.user`            | User              | `search` / `searchAll` / `current` | `requestType` / `userType` / `field`      |
+| `t.field`           | Field（項目定義） | `search` / `searchAll`             | `resource`（必須）/ `active`              |
+| `t.option`          | Option（選択肢）  | `search`                           | `alias` / `level` / `enabled`             |
 
 ```ts
 // アクセス可能な Partition（Company DB）を発見
 const partitions = await porters.partition.search();
 
 // 現在の API ユーザー（code_direct ではアプリ自身の User）＝自己同定
-const me = await porters.user.current();
+const me = await t.user.current();
 
 // Job リソースの項目定義（U_/A_ カスタム項目を含む）を取得
-const fields = await porters.field.search({ resource: "job" });
+const fields = await t.field.search({ resource: "job" });
 
 // 選択肢マスタをフラットな配列で取得（親子は P_ParentId で復元）
-const options = await porters.option.search({ alias: "Option.P_Gender" });
+const options = await t.option.search({ alias: "Option.P_Gender" });
 ```
 
-- `porters.option.search()` は入れ子の選択肢ツリーを**深さ優先でフラット化**して返します（全ノード・`P_ParentId`/`P_Order` で階層復元可）。`start` が無いため `searchAll` はありません。
+- `t.option.search()` は入れ子の選択肢ツリーを**深さ優先でフラット化**して返します（全ノード・`P_ParentId`/`P_Order` で階層復元可）。`start` が無いため `searchAll` はありません。
 - `porters.partition.current()` は提供しません（`request_type=0` は既定の `code_direct` 認証では 403 になるため）。一覧は `search()`（既定 `requestType: 1`）で取得します。
 
 ## 読み取り値の表現
@@ -272,7 +272,7 @@ PORTERS の Field Type に応じてデコードされます。
 | 空・未設定                                          | `null`                                          |
 
 ```ts
-const c = await porters.candidate.get(10001);
+const c = await t.candidate.get(10001);
 c?.P_Id; // number
 c?.P_Name; // string | null
 c?.P_RegistrationDate; // "2026-01-02T03:04:05Z" | null
@@ -295,17 +295,17 @@ c?.P_Owner; // { P_Id, P_Name, ... } | null
 
 ```ts
 // 作成（新規）
-const newId = await porters.candidate.create({
+const newId = await t.candidate.create({
   P_Owner: 5, // User 項目は id
   P_Name: "鈴木 一郎",
   P_Reading: "すずき いちろう",
 });
 
 // 更新
-await porters.candidate.update(newId, { P_Mail: "ichiro@example.com" });
+await t.candidate.update(newId, { P_Mail: "ichiro@example.com" });
 
 // 選考プロセス（関連 id を指定）
-await porters.process.create({
+await t.process.create({
   P_Owner: 1,
   P_Client: 100,
   P_Recruiter: 200,
@@ -315,7 +315,7 @@ await porters.process.create({
 });
 
 // 一括作成／更新（200 件＋サイズで自動分割・部分成功を返す）
-const bulk = await porters.candidate.createMany([
+const bulk = await t.candidate.createMany([
   { P_Owner: 5, P_Name: "山田 太郎" },
   { P_Owner: 5, P_Name: "鈴木 花子" },
 ]);
@@ -331,7 +331,7 @@ if (bulk.hasFailures) console.warn(bulk.failed); // per-item は throw せず結
 ```ts
 import { bytesToBase64 } from "@joymerrevent/porters-connect";
 
-const id = await porters.attachment.create({
+const id = await t.attachment.create({
   resource: 17, // 関連リソース種別コード（Resource List 参照）
   resourceId: 10001, // 関連レコードの id
   contentType: "application/pdf",
@@ -351,7 +351,7 @@ const id = await porters.attachment.create({
 import { PortersError } from "@joymerrevent/porters-connect";
 
 try {
-  await porters.candidate.get(1);
+  await t.candidate.get(1);
 } catch (e) {
   if (e instanceof PortersError) {
     e.category; // "auth" | "permission" | "notFound" | "conflict" | "network" | ...
@@ -365,7 +365,7 @@ try {
 
 - トークン失効は内側で自動回復します。設定ミスは `PortersConfigError` で早期に落とします。
 - **`Promise` を返す公開メソッドは同期 throw しません**（[ADR-0046][adr46]）。設定ミスも含め常に **reject** で届くので、
-  `porters.candidate.search(q).catch(handler)` でも捕まえられます（`string` を返す `auth.authorizationUrl` や
+  `t.candidate.search(q).catch(handler)` でも捕まえられます（`string` を返す `auth.authorizationUrl` や
   コンストラクタなど、Promise を返さない API は同期 throw のままです）。
 - 一時エラー・ネットワークは内蔵リトライ。非冪等な `create` はネットワーク不確実時に握り潰さず表面化します。
 - レート制限超過時、PORTERS は判別可能なコードを返さず接続を切るため、`PortersNetworkError`（category `"network"`）として表面化します。

package/dist/index.d.ts

@@ -138,12 +138,12 @@ type UserRef = {
     P_Mail: string | null;
 };
 type FieldValue = string | number | string[] | UserRef | null;
-type DecodedValue<D extends DataType> = D extends "System[Id]" | "Number" | "System[Reference]" ? number : D extends "User" ? UserRef : D extends "Option" ? string[] : string;
+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]">;
-type WriteValueOf<D extends DataType> = D extends "User" | "System[Reference]" | "Number" ? number : D extends "Option" ? string[] : string;
+type WriteValueOf<D extends DataType | null> = D extends null ? never : D extends "User" | "System[Reference]" | "Number" ? number : D extends "Option" ? string[] : string;
 
-type FieldCatalog = Record<string, DataType>;
+type FieldCatalog = Record<string, DataType | null>;
 /**
  * "No custom fields": the intersection-identity default for the generic catalog params (ADR-0023).
  * A bare `{}` is flagged by `no-empty-object-type`; `Record<never, never>` is the same empty object,
@@ -208,8 +208,12 @@ type ReferenceCondition = {
     or?: number[];
     and?: number[];
 };
-/** The condition-operator object a field of Data Type `D` accepts. */
-type ConditionFor<D extends DataType> = D extends "System[Id]" ? IdCondition : D extends "Number" ? NumberCondition : D extends "DateTime" | "System[DateTime]" | "Date" | "Age" ? TemporalCondition : D extends "SinglelineText" | "MultilineText" | "Mail" | "Telephone" | "URL" ? TextCondition : D extends "Option" ? OptionCondition : D extends "User" | "System[Reference]" ? ReferenceCondition : never;
+/**
+ * The condition-operator object a field of Data Type `D` accepts. A field PORTERS gives no Data
+ * Type (`null` — ADR-0056) falls through to the closing `never`, which is exactly right: the
+ * reference says such a field cannot appear in `condition` at all.
+ */
+type ConditionFor<D extends DataType | null> = D extends "System[Id]" ? IdCondition : D extends "Number" ? NumberCondition : D extends "DateTime" | "System[DateTime]" | "Date" | "Age" ? TemporalCondition : D extends "SinglelineText" | "MultilineText" | "Mail" | "Telephone" | "URL" ? TextCondition : D extends "Option" ? OptionCondition : D extends "User" | "System[Reference]" ? ReferenceCondition : never;
 /**
  * A typed search condition over a catalog: each field maps to the operator object its Data Type
  * allows (ADR-0038 案1a). Multiple fields are AND-joined (reference). Unknown aliases / wrong
@@ -229,10 +233,15 @@ type OrderableKeys<F extends FieldCatalog> = {
  */
 type Order<F extends FieldCatalog> = Array<Partial<Record<OrderableKeys<F>, "asc" | "desc">>>;
 /**
- * Which delete state to read. Omitting (or `existing`) reads live data; `deleted`/`all` read deleted
- * records — the only way to read deleted data, since there is no delete API. When `deleted`/`all`,
- * condition is restricted to `P_Id` / `P_UpdateDate` / `P_UpdatedBy` and PORTERS auto-adds a
- * "updated within 90 days" filter (`P_UpdateDate` = the delete time, `P_UpdatedBy` = the last editor).
+ * Which delete state to read. `existing` reads live data, `deleted`/`all` read deleted records —
+ * the only way to read deleted data, since there is no delete API. When `deleted`/`all`, condition
+ * is restricted to `P_Id` / `P_UpdateDate` / `P_UpdatedBy` and PORTERS auto-adds a "updated within
+ * 90 days" filter (`P_UpdateDate` = the delete time, `P_UpdatedBy` = the last editor).
+ *
+ * **Omitting the field is not the same as passing `existing`** (ADR-0057). Omitting defers to the
+ * API's own default (today: `existing`); passing `existing` states that you want live records only,
+ * and is sent as such. Both read live data now, but only the explicit form keeps doing so if PORTERS
+ * 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> = {
@@ -346,6 +355,7 @@ declare const FIELDS$8: {
     readonly P_City: "SinglelineText";
     readonly P_Street: "MultilineText";
     readonly P_Zipcode: "SinglelineText";
+    readonly P_Deleted: null;
 };
 declare const REQUIRED_ON_CREATE$4: readonly ["P_Owner"];
 /** A decoded Candidate: known `P_` fields, each requested field `value | null`. */
@@ -394,6 +404,7 @@ declare const FIELDS$7: {
     readonly P_CapitalText: "SinglelineText";
     readonly P_EmploymentType: "Option";
     readonly P_ExpectedAgeReason: "Option";
+    readonly P_Deleted: null;
 };
 declare const REQUIRED_ON_CREATE$3: readonly ["P_Owner", "P_Client", "P_Recruiter"];
 /** A decoded Job: known `P_` fields, each requested field `value | null`. */
@@ -426,6 +437,7 @@ declare const FIELDS$6: {
     readonly P_Zipcode: "SinglelineText";
     readonly P_Telephone: "Telephone";
     readonly P_Fax: "Telephone";
+    readonly P_Deleted: null;
 };
 declare const REQUIRED_ON_CREATE$2: readonly ["P_Owner"];
 /** A decoded Client (company): known `P_` fields, each requested field `value | null`. */
@@ -458,6 +470,7 @@ declare const FIELDS$5: {
     readonly P_CloseReason: "Option";
     readonly P_ExpectedSalesAmount: "Number";
     readonly P_ExpectedClosingDate: "Date";
+    readonly P_Deleted: null;
 };
 declare const REQUIRED_ON_CREATE$1: readonly ["P_Owner", "P_Client", "P_Recruiter", "P_Job", "P_Candidate", "P_Resume"];
 /** A decoded Process (a Candidate's progress through a Job): known `P_` fields, each
@@ -503,6 +516,7 @@ declare const FIELDS$4: {
     readonly P_ExpectSalary: "Number";
     readonly P_DesiredHourlyRate: "Number";
     readonly P_HourlyRate: "Number";
+    readonly P_Deleted: null;
 };
 declare const REQUIRED_ON_CREATE: readonly ["P_Owner", "P_Candidate"];
 /** A decoded Resume (a Candidate's CV / profile): known `P_` fields, each requested field
@@ -779,12 +793,6 @@ type PortersClientOptions<C extends DeclaredCatalogs = EmptyCatalog> = {
     appId?: string;
     appSecret?: string;
     scopes?: Scope[];
-    /**
-     * Default partition (Company DB) for every call. For multi-tenant routing, bind a partition
-     * per call with {@link PortersClient.tenant} (ADR-0040 / F-3); for a fully separated per-partition
-     * token, construct a dedicated client per tenant instead (ADR-0008 案3).
-     */
-    partition?: PartitionId;
     /** Custom auth strategy; defaults to the transparent code_direct strategy. */
     auth?: TokenProvider;
     /** Token persistence; defaults to in-memory. */
@@ -800,8 +808,10 @@ type PortersClientOptions<C extends DeclaredCatalogs = EmptyCatalog> = {
 };
 /**
  * The partition-bound resource accessors returned by {@link PortersClient.tenant} (ADR-0040 / F-3).
- * Every accessor here routes to the bound tenant's partition. `auth` (App-level), the `partition`
- * master (discovery — partition-less), and `tenant` itself (no nesting) are deliberately absent.
+ * **This is the only way to reach a partition-scoped resource** (ADR-0055): PORTERS requires
+ * `partition` on every one of these calls, so the API makes you supply it exactly once, explicitly.
+ * `auth` (App-level), the `partition` master (discovery — partition-less), and `tenant` itself
+ * (no nesting) are deliberately absent: none of them takes a partition.
  */
 type TenantScope<C extends DeclaredCatalogs = EmptyCatalog> = {
     readonly candidate: CandidateResource<CustomFor<C, "candidate">>;
@@ -815,36 +825,41 @@ type TenantScope<C extends DeclaredCatalogs = EmptyCatalog> = {
     readonly option: OptionResource;
 };
 /**
- * Entry point of the library. Wires the default transport / auth / throttle /
- * requester and exposes namespaced resource accessors such as `candidate`
- * (ADR-0005).
+ * Entry point of the library. Wires the default transport / auth / throttle / requester and exposes
+ * the **App-level** surface: `auth`, the `partition` master (discovery), and {@link PortersClient.tenant}.
+ *
+ * Everything that PORTERS scopes to a partition (Company DB) lives behind `tenant(id)` — see
+ * {@link TenantScope}. The client holds no default partition (ADR-0055): a partition is bound
+ * explicitly, exactly once, so "unbound" is not a state this API can be in.
+ *
+ * @example
+ * const porters = new PortersClient({ host, appId, appSecret });
+ * await porters.auth.ensureAuthenticated();   // App-level
+ * const t = porters.tenant(123);              // bind the partition once
+ * const page = await t.candidate.search();
  */
 declare class PortersClient<C extends DeclaredCatalogs = EmptyCatalog> {
     #private;
-    readonly candidate: CandidateResource<CustomFor<C, "candidate">>;
-    readonly job: JobResource<CustomFor<C, "job">>;
-    readonly client: ClientResource<CustomFor<C, "client">>;
-    readonly process: ProcessResource<CustomFor<C, "process">>;
-    readonly resume: ResumeResource<CustomFor<C, "resume">>;
-    readonly attachment: AttachmentResource;
     /** OAuth surface: initial browser grant, token warm-up/inspection, local revoke (ADR-0007/0034). */
     readonly auth: AuthApi;
-    /** Master Read: accessible partitions (ADR-0021/0022). */
+    /**
+     * Master Read: the partitions this App can reach (ADR-0021/0022). Takes no `partition` itself —
+     * it is how you *discover* the ids to pass to {@link PortersClient.tenant}.
+     */
     readonly partition: PartitionResource;
-    /** Master Read: users, plus `current()` self-identification (ADR-0021/0022). */
-    readonly user: UserResource;
-    /** Master Read: a resource's field catalog (ADR-0021/0022). */
-    readonly field: FieldResource;
-    /** Master Read: a tenant's choice (option) master (ADR-0021/0022). */
-    readonly option: OptionResource;
     /**
-     * Bind a tenant's partition (Company DB) once and route every call through it — the multi-tenant
-     * scope (ADR-0008 案2 / renamed in ADR-0021 / implemented in ADR-0040 F-3).
-     * `porters.tenant(123).candidate.search(...)` sends `partition=123` without repeating it, overriding
-     * the client-default `partition`. Returns the partition-bound accessors (data + attachment + master
-     * User/Field/Option); `auth` (App-level), the `partition` master (discovery — takes no partition),
-     * and `tenant` itself (no nesting) are intentionally omitted. For a fully separated per-partition
-     * token, construct a dedicated {@link PortersClient} per tenant instead (ADR-0008 案3).
+     * Bind a partition (Company DB) and get the accessors that route through it (ADR-0040 F-3).
+     * **Single-tenant apps use this too** — it is the only path to a partition-scoped resource
+     * (ADR-0055). Hold the scope once and use it like a client:
+     *
+     * ```ts
+     * const t = porters.tenant(123);
+     * await t.candidate.search();
+     * ```
+     *
+     * `auth` (App-level), the `partition` master (discovery — takes no partition), and `tenant`
+     * itself (no nesting) are intentionally absent from the returned scope. For a fully separated
+     * per-partition token, construct a dedicated {@link PortersClient} per tenant (ADR-0008 案3).
      */
     readonly tenant: (id: PartitionId) => TenantScope<C>;
     constructor(options: PortersClientOptions<C>);

package/dist/index.js

@@ -740,7 +740,7 @@ var encodeItem = (prefix, fields, item) => {
   for (const [alias, value] of Object.entries(item)) {
     if (value === null || value === void 0) continue;
     const type = fields.get(alias);
-    const inner = type === void 0 ? scalar(value) : encodeField(type, value);
+    const inner = type === void 0 || type === null ? scalar(value) : encodeField(type, value);
     parts.push(`<${prefix}.${alias}>${inner}</${prefix}.${alias}>`);
   }
   return parts.join("");
@@ -786,6 +786,7 @@ var decodeReference = (raw) => {
 };
 var decodeField = (type, raw) => {
   if (raw === "" || raw === void 0 || raw === null) return null;
+  if (type === null) return asString(raw) ?? null;
   switch (type) {
     case "System[Id]":
     case "Number": {
@@ -832,7 +833,7 @@ var decoderFor = (fields) => {
     for (const [key, raw] of Object.entries(item)) {
       const alias = bareAlias(key);
       const type = fieldMap.get(alias);
-      out[alias] = type ? decodeField(type, raw) : typeof raw === "string" ? raw : null;
+      out[alias] = type === void 0 ? typeof raw === "string" ? raw : null : decodeField(type, raw);
     }
     return out;
   };
@@ -946,9 +947,7 @@ var appendReadQuery = (p, q, ctx) => {
     }
     p.set("keywords", kw);
   }
-  if (q.itemstate !== void 0 && q.itemstate !== "existing") {
-    p.set("itemstate", q.itemstate);
-  }
+  if (q.itemstate !== void 0) p.set("itemstate", q.itemstate);
 };
 
 // src/resources/bulk-write.ts
@@ -1069,7 +1068,9 @@ var buildWriteUrl = (accessPoint, partition, path) => apiUrl(
   new URLSearchParams({ partition: String(partition) })
 );
 var createResource = (config, deps) => {
-  const fieldMap = new Map(Object.entries(config.fields));
+  const fieldMap = new Map(
+    Object.entries(config.fields)
+  );
   const decode = decoderFor(config.fields);
   const defaultFields = defaultFieldList(config.prefix, config.fields);
   const readUrl = (q) => buildReadUrl(deps.accessPoint, deps.partition, config.path, q, {
@@ -1151,7 +1152,12 @@ var FIELDS = {
   P_Prefecture: "SinglelineText",
   P_City: "SinglelineText",
   P_Street: "MultilineText",
-  P_Zipcode: "SinglelineText"
+  P_Zipcode: "SinglelineText",
+  // 削除状態（"0" 生存 / "1" 削除済み）。PORTERS はこの項目に Data Type を与えていない
+  // （reference の Field Type / Data Type とも「ー」）ので `null`＝型が無いことを記録する（ADR-0056）。
+  // 「未設定」でも「不明」でもない。null は condition / order / Write の型から自動的に外れる＝
+  // reference の「Read の field でのみ指定可」がそのまま型で守られる。
+  P_Deleted: null
 };
 var REQUIRED_ON_CREATE = [
   "P_Owner"
@@ -1206,7 +1212,10 @@ var FIELDS2 = {
   P_EstablishmentDateText: "SinglelineText",
   P_CapitalText: "SinglelineText",
   P_EmploymentType: "Option",
-  P_ExpectedAgeReason: "Option"
+  P_ExpectedAgeReason: "Option",
+  // 削除状態（"0" / "1"）。PORTERS が Data Type を与えていない項目＝`null`（ADR-0056。
+  // 詳細は candidate.ts のコメント）。Read の field でのみ指定でき、型もそう振る舞う。
+  P_Deleted: null
 };
 var REQUIRED_ON_CREATE2 = [
   "P_Owner",
@@ -1246,7 +1255,10 @@ var FIELDS3 = {
   P_Street: "MultilineText",
   P_Zipcode: "SinglelineText",
   P_Telephone: "Telephone",
-  P_Fax: "Telephone"
+  P_Fax: "Telephone",
+  // 削除状態（"0" / "1"）。PORTERS が Data Type を与えていない項目＝`null`（ADR-0056。
+  // 詳細は candidate.ts のコメント）。Read の field でのみ指定でき、型もそう振る舞う。
+  P_Deleted: null
 };
 var REQUIRED_ON_CREATE3 = [
   "P_Owner"
@@ -1284,7 +1296,10 @@ var FIELDS4 = {
   P_Close: "Option",
   P_CloseReason: "Option",
   P_ExpectedSalesAmount: "Number",
-  P_ExpectedClosingDate: "Date"
+  P_ExpectedClosingDate: "Date",
+  // 削除状態（"0" / "1"）。PORTERS が Data Type を与えていない項目＝`null`（ADR-0056。
+  // 詳細は candidate.ts のコメント）。Read の field でのみ指定でき、型もそう振る舞う。
+  P_Deleted: null
 };
 var REQUIRED_ON_CREATE4 = [
   "P_Owner",
@@ -1339,7 +1354,10 @@ var FIELDS5 = {
   P_ExpectCondition: "MultilineText",
   P_ExpectSalary: "Number",
   P_DesiredHourlyRate: "Number",
-  P_HourlyRate: "Number"
+  P_HourlyRate: "Number",
+  // 削除状態（"0" / "1"）。PORTERS が Data Type を与えていない項目＝`null`（ADR-0056。
+  // 詳細は candidate.ts のコメント）。Read の field でのみ指定でき、型もそう振る舞う。
+  P_Deleted: null
 };
 var REQUIRED_ON_CREATE5 = [
   "P_Owner",
@@ -1637,30 +1655,26 @@ var createOptionResource = (deps) => {
 
 // src/client.ts
 var PortersClient = class {
-  candidate;
-  job;
-  client;
-  process;
-  resume;
-  attachment;
   /** OAuth surface: initial browser grant, token warm-up/inspection, local revoke (ADR-0007/0034). */
   auth;
-  /** Master Read: accessible partitions (ADR-0021/0022). */
+  /**
+   * Master Read: the partitions this App can reach (ADR-0021/0022). Takes no `partition` itself —
+   * it is how you *discover* the ids to pass to {@link PortersClient.tenant}.
+   */
   partition;
-  /** Master Read: users, plus `current()` self-identification (ADR-0021/0022). */
-  user;
-  /** Master Read: a resource's field catalog (ADR-0021/0022). */
-  field;
-  /** Master Read: a tenant's choice (option) master (ADR-0021/0022). */
-  option;
   /**
-   * Bind a tenant's partition (Company DB) once and route every call through it — the multi-tenant
-   * scope (ADR-0008 案2 / renamed in ADR-0021 / implemented in ADR-0040 F-3).
-   * `porters.tenant(123).candidate.search(...)` sends `partition=123` without repeating it, overriding
-   * the client-default `partition`. Returns the partition-bound accessors (data + attachment + master
-   * User/Field/Option); `auth` (App-level), the `partition` master (discovery — takes no partition),
-   * and `tenant` itself (no nesting) are intentionally omitted. For a fully separated per-partition
-   * token, construct a dedicated {@link PortersClient} per tenant instead (ADR-0008 案3).
+   * Bind a partition (Company DB) and get the accessors that route through it (ADR-0040 F-3).
+   * **Single-tenant apps use this too** — it is the only path to a partition-scoped resource
+   * (ADR-0055). Hold the scope once and use it like a client:
+   *
+   * ```ts
+   * const t = porters.tenant(123);
+   * await t.candidate.search();
+   * ```
+   *
+   * `auth` (App-level), the `partition` master (discovery — takes no partition), and `tenant`
+   * itself (no nesting) are intentionally absent from the returned scope. For a fully separated
+   * per-partition token, construct a dedicated {@link PortersClient} per tenant (ADR-0008 案3).
    */
   tenant;
   #accessPoint;
@@ -1719,16 +1733,6 @@ var PortersClient = class {
       };
     };
     this.tenant = buildScope;
-    const root = buildScope(options.partition ?? 0);
-    this.candidate = root.candidate;
-    this.job = root.job;
-    this.client = root.client;
-    this.process = root.process;
-    this.resume = root.resume;
-    this.attachment = root.attachment;
-    this.user = root.user;
-    this.field = root.field;
-    this.option = root.option;
     this.partition = createPartitionResource({ requester, accessPoint });
   }
   /** The configured API host. */