@joymerrevent/porters-connect 0.16.0 → 0.18.0

package/CHANGELOG.md

@@ -5,6 +5,226 @@
 
 ## [Unreleased]
 
+## [0.18.0] - 2026-09-17
+
+**「どのリソースか」の受け取り方を 1 つの規則に揃えた版**です。**破壊的変更を 4 つ**含みます
+（アクセスポイントの `host` 廃止／束ねた項目は書き込み入力から外れる／Field マスタの Read が
+`of()` 経由に／添付の Read が PORTERS の語彙に）。
+
+PORTERS が `resource=` を **URL パラメータで必須**に要求するエンドポイントは 3 つ（Field / Phase /
+Attachment）あるのに、受け口の形が 3 つとも違っていました。**パラメータのリソースは `of(name)` で
+束ね、項目の値は宣言した Data Type どおり（数値）**という線を引き、3 本とも `of()` に揃えています。
+
+### Added
+
+- **`resourceValueOf` / `resourceNameOf`** — リソース名と数値を相互変換します（[ADR-0079][adr79]）。
+
+  ```ts
+  import {
+    resourceNameOf,
+    resourceValueOf,
+  } from "@joymerrevent/porters-connect";
+
+  await t.activity.create({
+    P_Owner: 5,
+    P_Title: "一次面談",
+    P_Resource: resourceValueOf("candidate"), // 1
+    P_ResourceId: 10001,
+  });
+
+  resourceNameOf(17); // "resume"
+  ```
+
+  PORTERS のリソース番号は**非連続**です（Candidate `1` / Job `3` / Client `5` / Recruiter `9` /
+  Sales `11` / …）。欠番も取り違えも数値リテラルでは気づけないので、名前から引いてください。
+  `resourceNameOf` は**知らない数値をそのまま返します**（`ResourceName | number`）— Resource List は
+  PORTERS のもので増えるため（Contact `27` は後から増えました）、知らない値はエラーにせず
+  データとして通します。
+
+- 公開した型: `AttachmentAccessor` / `FieldAccessor`（`ResourceName` は 0.17.0 から公開済みで、
+  `of()` に渡す名前の型です）。
+
+### Changed
+
+- **（破壊的）アクセスポイントが `hostname` と `port` に分かれました**（[ADR-0078][adr78]）。
+  **`host` は無くなります。**
+
+  ```ts
+  // これまで
+  new PortersClient({ host: "xxxxx.example.com", appId, appSecret });
+  new PortersClient({ host: "127.0.0.1:4010", scheme: "http" });
+
+  // これから
+  new PortersClient({ hostname: "xxxxx.example.com", appId, appSecret });
+  new PortersClient({ hostname: "127.0.0.1", port: 4010, scheme: "http" });
+  ```
+
+  **契約で渡される値にポートは無い**からです。PORTERS の記事は `{Request Host}` を「該当の
+  **サーバー名**を入れてください」と説明し、ポート表記はどの記事にも出てきません。一方 URL 仕様では
+  `host` は**ポートを含む**名前で、含まないのが `hostname` です。名前と中身を揃えました。
+
+  - **`hostname` にポートを書くと構築時に落ちます**（`PortersConfigError`）。素通しすると
+    「指定したつもりで既定ポートに送られる」ので、黙って落とさずに弾きます
+  - **`port` は 1〜65535 の整数**。省略すれば scheme の既定ポートです。使うのはローカルの
+    フェイクサーバーやプロキシに向けるときだけで、PORTERS には要りません
+  - **IPv6 は角括弧付き**で渡します（`hostname: "[::1]"`）
+  - `PortersClient` のゲッターも `host` → **`hostname` / `port`** の 2 本になります
+  - スロットルのバケット（[ADR-0073][adr73]）は**宛先ごと**になりました。同じ名前でもポートが
+    違えば別のバケットです
+
+- **（破壊的）添付ファイルの Read が PORTERS の語彙に揃いました**（[ADR-0081][adr81]）。
+
+  ```ts
+  // これまで
+  await t.attachment.search({ condition: { "ResourceId:eq": "10001" } });
+  await t.attachment.create({ resource: 17, resourceId: 10001, ...file });
+
+  // これから
+  const files = t.attachment.of("resume"); // resource を 1 回束ねる
+  await files.search({ resourceId: 10001 });
+  await files.get(900);
+  await files.create({ resourceId: 10001, ...file }); // resource は束ねた値
+  ```
+
+  PORTERS の `Attachment - Read` が取るのは `requestType` / `resource` / `resourceId` / `id` で、
+  **`field` と `condition` は挙げられていません**。ライブラリは逆で、**必須の 2 つを送らず、
+  記載の無い 2 つを送っていました**。出典どおりなら添付の読み取りは実環境で常に失敗するので、
+  出典に一致する側へ倒しました。
+
+  - `create` の入力から **`resource` が消えました**。付け先を取り違えても添付は消せないので、
+    書ける場所を減らしています
+  - 本体（`content`）を運ぶかは引き続き**メソッドが決めます**（`get` だけが運びます。
+    PORTERS 側では `requestType` です）
+  - **絞れるのは `resourceId`（1 レコードの添付）と `id`（1 件）だけ**で、ファイル名などでの
+    検索はできません（PORTERS が提供していません）。名前で探すときは `searchAll` で歩きながら
+    絞ってください
+  - **出典どおりの形が実機で通るかは未確認**です（契約環境でのみ確かめられます）
+
+- **（破壊的）Field マスタの Read が `of()` でリソースを束ねる形になりました**（[ADR-0080][adr80]）。
+
+  ```ts
+  // これまで
+  await t.field.search({ resource: "candidate", active: 1 });
+
+  // これから
+  await t.field.of("candidate").search({ active: 1 });
+  ```
+
+  同じ形の Phase は以前から `t.phase.of("client")` で束ねていたので、**URL パラメータのリソースは
+  `of()` で束ねる**という 1 つの規則に揃えました。`readCustomCatalog` / `verifyFields` /
+  `generateFieldDecls` の**引数は変わりません**。`porters.partition` / `t.user` / `t.option` も
+  変わりません — この 3 つは `resource=` を取らないためです。
+
+- **（破壊的）アクセサが束ねた項目は、書き込み入力から外れます**。
+
+  `t.phase.of("client")` は「このアクセサは企業の Phase を扱う」という宣言です。これまでは
+  `Resource` を書き込み入力に渡せてしまい、**束ねた値を上書きできました** — `of("client")` から
+  JOB（`3`）の Phase が書ける状態でした。
+
+  ```ts
+  const phase = (await t.phase.of("client").get(10014))!;
+  await t.phase.of("client").create({ ...phase, Date: "2026-09-17T00:00:00Z" });
+  // 読みのレコードは `Resource` を持つため、これまでは束ねた値が黙って上書きされていました
+  ```
+
+  型で外したうえ、キャストで渡した場合も**送信前に** `PortersConfigError` で止めます（黙って
+  捨てません）。Phase に削除 API は無いので、間違ったリソースに付いた履歴は消せません。
+
+- **エンドポイント × 機能のマトリクスのずれが無くなりました**。0.17.0 で起こした表は
+  **4 セルが食い違った状態**で出しましたが（Phase の 2 つ・Attachment の 2 つ）、本版で
+  **すべて解消**しています。パッケージの中身は変わりません。
+
+### Removed
+
+- **`AttachmentMetaField`** — 0.17.0 で公開した型ですが、添付の Read から `field` が無くなった
+  ため役目を終えました（[ADR-0081][adr81]）。
+
+## [0.17.0] - 2026-09-16
+
+**添付ファイルの運び方を決め、出典に無いパラメータを型から外した版**です。**破壊的変更を 2 つ**
+含みます（添付の本体は `get` でだけ取れる／Phase の Read から `keywords` / `itemstate` が消える）。
+
+### Added
+
+- **`t.attachment.searchAll()`** — 200 件を超える添付を、`start` を自分で回さずに順に見られます
+  （[ADR-0075][adr75]）。ほかの 15 エンドポイントと同じ語彙になりました。
+
+  ```ts
+  for await (const a of t.attachment.searchAll({
+    condition: { "Resource:eq": "17" },
+  })) {
+    console.log(a.fileName, a.contentType);
+  }
+  ```
+
+  流れるのは**メタデータだけ**なので、全部を歩いてもファイル本体はダウンロードされません。
+
+- **`createFetchTransport`** — 既定の transport を公開しました（[ADR-0077][adr77]）。
+  1 リクエストのタイムアウト（既定 **30 秒**）を変えられます。
+
+  ```ts
+  import {
+    PortersClient,
+    createFetchTransport,
+  } from "@joymerrevent/porters-connect";
+
+  const porters = new PortersClient({
+    host,
+    appId,
+    appSecret,
+    transport: createFetchTransport({ timeoutMs: 120_000 }), // 2 分
+  });
+  ```
+
+  この 30 秒は**接続から本文の受信完了まで**で、**1 リクエストごと**に数えます（自動リトライを
+  含めると最悪 `maxRetries + 1` 倍）。レートの待ち時間は含みません。`timeoutMs` は**正の整数**だけを
+  受け、`0`（＝即中断で「無制限」ではない）は構築時に `PortersConfigError` で弾きます。
+  これまで変えるには `Transport` の自前実装が必要で、`PortersNetworkError` への分類まで
+  書き直すことになっていました。
+
+- 公開した型: `AttachmentMetaField` / `AttachmentWalkQuery` / `FetchTransportOptions`。
+
+### Changed
+
+- **（破壊的）添付の本体（`content`）は `get` でだけ取れます**（[ADR-0075][adr75]）。
+  `search` / `searchAll` の `field` に `"Content"` は書けません。
+
+  ```ts
+  await t.attachment.search({ field: ["Id", "Content"] });
+  //                                       ^^^^^^^^^ 型エラーになります
+  const file = await t.attachment.get(900); // 本体はこちら
+  ```
+
+  1 ページは最大 200 件で、PORTERS は 1 ファイル 10MB まで許します。本体を混ぜた一覧は
+  **読める大きさを越えることがあります** — 1 ファイル 2MB 超 × 200 件で V8 の文字列上限
+  （536,870,888 文字）に当たり、`RangeError` になって再送しても直りません。しかも Attachment は
+  **ファイルサイズを返さない**ので、「何件までなら安全か」を呼び出し側が判断することもできません。
+  そこで件数ではなく**メソッド**で分けました。型を外して渡した場合も、送信前に
+  `PortersConfigError` で止まります。
+
+- **（破壊的）Phase の Read クエリから `keywords` / `itemstate` が消えました**（[ADR-0076][adr76]）。
+  PORTERS の `Phase - Read` はこの 2 つを Input Variables に挙げていません。Read 記事 17 本を
+  数えると、共通語彙のデータ系 11 本は両方を載せ、**Phase / Attachment / マスタ 4 種は 1 本も
+  載せていません**（11/11 対 0/6）ので、記事側の省略ではなく**エンドポイントごとに取るものが
+  違う**と読めます。出典に無いパラメータは、無視されるのではなく **Read 全体を失敗させうる**
+  （Result Code 100 / 102）ため、型の側で閉じました。
+
+  ```ts
+  await t.phase.of("client").search({ keywords: ["山田"] });
+  //                                  ^^^^^^^^ 型エラーになります
+  ```
+
+  **実行時は変えていません**。cast すれば今までどおり送られます（契約環境で「実は受け付ける」と
+  分かったときに確かめられるように残しました）。
+
+- **エンドポイント × 機能のマトリクスを起こしました**。PORTERS が取るものとライブラリが送るものを
+  表に並べ、**reference ↔ 表 ↔ 実装を両方向で突き合わせる検査**（94 件）を足しています。
+  ずれているセルには必ず根拠（ADR / ライブ検証）が要る形で、今回の 2 つの破壊的変更も
+  この表から出てきました。パッケージの中身は変わりません。
+
+- **既定 30 秒のタイムアウトをドキュメントに明文化しました**（[上限][limits]・[失敗の扱い][failures]）。
+  これまでどこにも書かれていませんでした。パッケージの中身は変わりません。
+
 ## [0.16.0] - 2026-09-15
 
 **カスタム項目を「宣言してから使う」に揃えた版**です。**破壊的変更**（`field` が未宣言の
@@ -798,11 +1018,22 @@
 [adr69]: docs/adr/0069-tenant-field-catalog-tooling.md
 [adr73]: docs/adr/0073-throttle-sharing.md
 [adr74]: docs/adr/0074-custom-field-declaration-required.md
+[adr75]: docs/adr/0075-attachment-search-all.md
+[adr76]: docs/adr/0076-phase-read-query-surface.md
+[adr77]: docs/adr/0077-fetch-transport-timeout.md
+[adr78]: docs/adr/0078-hostname-port-split.md
+[adr79]: docs/adr/0079-resource-by-name.md
+[adr80]: docs/adr/0080-resource-parameter-binding.md
+[adr81]: docs/adr/0081-attachment-read-parameters.md
+[limits]: docs/usage/concepts/limits.md
+[failures]: docs/usage/howto/handle-failures.md
 [lv]: docs/live-verification.md
 [ref]: docs/usage/reference/README.md
 [kac]: https://keepachangelog.com/en/1.1.0/
 [semver]: https://semver.org/
-[unreleased]: https://github.com/Joymerrevent/porters-connect/compare/v0.16.0...HEAD
+[unreleased]: https://github.com/Joymerrevent/porters-connect/compare/v0.18.0...HEAD
+[0.18.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.17.0...v0.18.0
+[0.17.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.16.0...v0.17.0
 [0.16.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.15.1...v0.16.0
 [0.15.1]: https://github.com/Joymerrevent/porters-connect/compare/v0.15.0...v0.15.1
 [0.15.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.14.0...v0.15.0

package/README.md

@@ -54,7 +54,7 @@ npm i @joymerrevent/porters-connect
 import { PortersClient } from "@joymerrevent/porters-connect";
 
 const porters = new PortersClient({
-  host: process.env.PORTERS_HOST ?? "", // 契約時に通知される値。ハードコード禁止
+  hostname: process.env.PORTERS_HOST ?? "", // 契約時に通知される値。ハードコード禁止
   appId: process.env.PORTERS_APP_ID ?? "",
   appSecret: process.env.PORTERS_APP_SECRET ?? "",
 });

package/dist/index.d.ts

@@ -52,6 +52,26 @@ type PartitionId = number;
  */
 type Scheme = "https" | "http";
 
+type FetchTransportOptions = {
+    /**
+     * How long one request may take, in milliseconds. Default 30,000.
+     *
+     * **It covers the whole exchange** — connect, send, and reading the response body to the end —
+     * because the abort signal is handed to `fetch` itself. A large download therefore hits it even
+     * when the headers came back instantly. It is **per request**, so a retried call can take
+     * `maxRetries + 1` times this (plus backoff), and it does not include waiting for a throttle
+     * slot (throttling sits above the transport).
+     *
+     * Raise it to read large attachments over a slow link; lower it to fail fast in an interactive
+     * tool. Must be a positive integer — `0` would abort every request immediately, which reads
+     * like "no timeout" and is not (ADR-0077).
+     */
+    timeoutMs?: number;
+    /** Injectable fetch (tests / custom dispatcher). Default global fetch. */
+    fetchImpl?: typeof fetch;
+};
+declare const createFetchTransport: (opts?: FetchTransportOptions) => Transport;
+
 /** A mock reply: an XML body string (HTTP 200), or an explicit status + body. */
 type MockReply = string | {
     status?: number;
@@ -638,13 +658,47 @@ type UpdateInput<F extends FieldCatalog> = {
  * {@link EmptyReferences}. With no keys, `ImageReadRecord` collapses back to the record it wrapped.
  */
 type EmptyImages = Record<never, never>;
-type Resource<F extends FieldCatalog, Req extends keyof F, R extends ReferenceMap = EmptyReferences> = {
-    search<const E extends Expand<R> = EmptyReferences, const I extends ImageOption<F> = EmptyImages>(query?: SearchQuery<F, R> & {
+/**
+ * An object with `K` taken out — and **kept out**. `Omit` alone only stops a fresh object literal
+ * (excess-property checking); a variable that happens to carry the key still assigns. Re-declaring
+ * each removed key as `?: never` closes that hole, so the call fails whichever way the object was
+ * built — including `create({ ...recordFromRead })`, which is how the binding actually gets
+ * contradicted in practice (RV-47).
+ *
+ * Used for two different exclusions: query keys the endpoint does not take (`Unsupported` —
+ * ADR-0076) and write aliases the accessor itself fills (`Bound` — ADR-0061 / ADR-0080).
+ * `searchAll` keeps a plain `Omit` for `count` / `start`: those are not "PORTERS does not take
+ * this", they are "the walk decides them", and tightening that is a different decision.
+ */
+type Without<T, K extends keyof T> = Omit<T, K> & {
+    [P in K]?: never;
+};
+type Resource<F extends FieldCatalog, Req extends keyof F, R extends ReferenceMap = EmptyReferences, 
+/**
+ * Query keys **this endpoint does not take** (ADR-0076). The common Read vocabulary is not
+ * universal: PORTERS lists `keywords` / `itemstate` for the 11 common data resources and for
+ * none of the others, so a resource on this factory can say which of them its own endpoint
+ * leaves out. `never` — the default — means "takes the whole vocabulary".
+ *
+ * Sending a parameter the endpoint does not list can fail the *whole* Read (Result Code 100 /
+ * 102), so the safe side is not to offer it. The runtime stays permissive (ADR-0074): a key
+ * forced in through a cast is still sent, which is how a live contract can test whether
+ * PORTERS accepts it at all.
+ */
+Unsupported extends keyof SearchQuery<F, R> = never, 
+/**
+ * Write aliases **the accessor itself fills**, so a caller cannot supply them (ADR-0061 / RV-47).
+ * `t.phase.of("client")` binds `Resource`; passing it again could only mean contradicting the
+ * binding, and a phase written to the wrong resource cannot be deleted (there is no delete API).
+ * `never` — the default — means the caller supplies every writable field.
+ */
+Bound extends WritableKeys<F> = never> = {
+    search<const E extends Expand<R> = EmptyReferences, const I extends ImageOption<F> = EmptyImages>(query?: Without<SearchQuery<F, R>, Unsupported> & {
         expand?: E;
         image?: I;
     }): Promise<ResourcePageOf<ImageReadRecord<ExpandedReadRecord<F, R, E>, I>>>;
     /** Auto-paginating search: yields every matching record (200 per page). */
-    searchAll<const E extends Expand<R> = EmptyReferences, const I extends ImageOption<F> = EmptyImages>(query?: Omit<SearchQuery<F, R>, "count" | "start"> & {
+    searchAll<const E extends Expand<R> = EmptyReferences, const I extends ImageOption<F> = EmptyImages>(query?: Omit<Without<SearchQuery<F, R>, Unsupported>, "count" | "start"> & {
         expand?: E;
         image?: I;
     }): AsyncIterable<ImageReadRecord<ExpandedReadRecord<F, R, E>, I>>;
@@ -658,9 +712,9 @@ type Resource<F extends FieldCatalog, Req extends keyof F, R extends ReferenceMa
         image?: I;
     }): Promise<ImageReadRecord<ExpandedReadRecord<F, R, E>, I> | undefined>;
     /** Create one record; resolves to the newly assigned id. */
-    create(input: CreateInput<F, Req>): Promise<number>;
+    create(input: Without<CreateInput<F, Req>, Extract<Bound, keyof CreateInput<F, Req>>>): Promise<number>;
     /** Update one record by id; resolves to that id. */
-    update(id: number, input: UpdateInput<F>): Promise<number>;
+    update(id: number, input: Without<UpdateInput<F>, Extract<Bound, keyof UpdateInput<F>>>): Promise<number>;
     /**
      * Create many records in one call (ADR-0041 / F-4). Auto-batched to ≤200 records and under the
      * request size cap. **Not atomic** — inspect the {@link BulkWriteResult}: per-record failures are
@@ -668,14 +722,14 @@ type Resource<F extends FieldCatalog, Req extends keyof F, R extends ReferenceMa
      * already-written count). Batching is non-idempotent: a full retry after a mid-run failure may
      * duplicate creates. Empty input sends no request.
      */
-    createMany(inputs: CreateInput<F, Req>[]): Promise<BulkWriteResult>;
+    createMany(inputs: Without<CreateInput<F, Req>, Extract<Bound, keyof CreateInput<F, Req>>>[]): Promise<BulkWriteResult>;
     /**
      * Update many records by id in one call (ADR-0041 / F-4). Auto-batched like {@link createMany};
      * per-record failures are returned in the {@link BulkWriteResult}, not thrown.
      */
     updateMany(items: {
         id: number;
-        fields: UpdateInput<F>;
+        fields: Without<UpdateInput<F>, Extract<Bound, keyof UpdateInput<F>>>;
     }[]): Promise<BulkWriteResult>;
 };
 
@@ -1710,6 +1764,37 @@ declare const RESOURCE_VALUES: {
  * the accessor (`t.client` -> `"client"`), so a typo is a compile error rather than an HTTP 400.
  */
 type ResourceName = keyof typeof RESOURCE_VALUES;
+/**
+ * The number PORTERS knows a resource by (ADR-0079). The library takes **names** where PORTERS
+ * takes a `resource=` parameter, but a *field value* stays the number its Data Type declares —
+ * `Activity.P_Resource`, `Attachment.Resource`, and a `condition` on either.
+ *
+ * Write the name and let this do the lookup; the numbers are non-contiguous
+ * (1/3/5/7/9/11/13/17/19/25/27), so a literal is easy to get wrong and impossible to spot.
+ *
+ * @example
+ * await t.activity.create({
+ *   P_Owner: 5,
+ *   P_Title: "面談",
+ *   P_Resource: resourceValueOf("candidate"), // 1
+ *   P_ResourceId: 10001,
+ * });
+ */
+declare const resourceValueOf: (name: ResourceName) => number;
+/**
+ * The name for a resource number (ADR-0079) — the other direction of {@link resourceValueOf}.
+ * Use it to read a value PORTERS returned: `Activity.P_Resource`, `Field.P_ResourceType`, or a
+ * raw value from {@link rawValue}.
+ *
+ * **A number PORTERS added since this version comes back as the number**, not `undefined` and not
+ * an error. The Resource List belongs to PORTERS and grows (Contact `27` arrived that way), so a
+ * value this library does not know is data, not a fault.
+ *
+ * @example
+ * const a = await t.activity.get(1);
+ * resourceNameOf(a?.P_Resource ?? 0); // "candidate" | … | number
+ */
+declare const resourceNameOf: (value: number) => ResourceName | number;
 
 declare const FIELDS$6: {
     readonly Id: "System[Id]";
@@ -1734,13 +1819,25 @@ declare const REQUIRED_ON_CREATE$2: readonly ["ResourceId"];
 /** A decoded Phase entry: known aliases, each requested field `value | null`. */
 type Phase = ReadRecord<typeof FIELDS$6>;
 type PhasePage = ResourcePage<typeof FIELDS$6>;
-type PhaseSearchQuery = SearchQuery<typeof FIELDS$6>;
+type PhaseUnsupportedQuery = "keywords" | "itemstate";
+/**
+ * Phase's Read query: the common vocabulary **minus `keywords` / `itemstate`**, which
+ * `Phase - Read` does not list (ADR-0076).
+ */
+type PhaseSearchQuery = Omit<SearchQuery<typeof FIELDS$6>, PhaseUnsupportedQuery> & {
+    [K in PhaseUnsupportedQuery]?: never;
+};
 /** Fields for `create`: `ResourceId` required (`Id` and `Resource` are supplied for you). */
 type PhaseCreateInput = CreateInput<typeof FIELDS$6, (typeof REQUIRED_ON_CREATE$2)[number]>;
 /** Fields for `update`: all optional (`null` omits, `""` clears a text field). */
 type PhaseUpdateInput = UpdateInput<typeof FIELDS$6>;
-/** The Phase accessor for one bound resource — same shape as every other resource. */
-type PhaseResource = Resource<typeof FIELDS$6, (typeof REQUIRED_ON_CREATE$2)[number]>;
+/**
+ * The Phase accessor for one bound resource — the same shape as every other resource, except that
+ * `search` / `searchAll` do not take `keywords` / `itemstate` (ADR-0076) and the write inputs do
+ * not take `Resource`: `of()` binds it, and supplying it again could only contradict the binding
+ * (RV-47).
+ */
+type PhaseResource = Resource<typeof FIELDS$6, (typeof REQUIRED_ON_CREATE$2)[number], EmptyReferences, PhaseUnsupportedQuery, "Resource">;
 /**
  * Phase is reached through the resource whose history you want (ADR-0061 案2a):
  *
@@ -2208,19 +2305,22 @@ type AttachmentPage = {
 };
 type AttachmentSearchQuery = {
     /**
-     * Output fields. **Omit** to fetch metadata by default (Id / Resource / ResourceId /
-     * ContentType / FileName) — the large Base64 `Content` is excluded so listing doesn't download
-     * every file body (ADR-0020); request `["Content", …]` or use `get()` for the body. Pass `[]`
-     * for the API-native primary-key-only response. A non-empty list is sent verbatim.
+     * Narrow to one record's attachments — the id **within the bound resource**
+     * (`t.attachment.of("resume")` -> a `Resume.P_Id`). Omit to read the whole resource's
+     * attachments.
      */
-    field?: string[];
-    condition?: Record<string, string>;
+    resourceId?: number;
     count?: number;
     start?: number;
 };
-/** Fields for creating an Attachment. `content` is the Base64 file body. */
+/** A walking Read: `count` / `start` are the walk's to decide. */
+type AttachmentWalkQuery = Omit<AttachmentSearchQuery, "count" | "start">;
+/**
+ * Fields for creating an Attachment. `content` is the Base64 file body; the resource it attaches
+ * to comes from `of(name)` and cannot be given here (ADR-0080 / ADR-0081).
+ */
 type AttachmentCreate = {
-    resource: number;
+    /** The record's id within the bound resource. */
     resourceId: number;
     contentType: string;
     fileName: string;
@@ -2232,8 +2332,33 @@ type AttachmentUpdate = {
     fileName?: string;
     content?: string;
 };
+/**
+ * Attachments are reached through the resource they belong to (ADR-0080 / ADR-0081):
+ *
+ * ```ts
+ * const files = t.attachment.of("resume");
+ * await files.search({ resourceId: 10006 }); // メタデータだけ
+ * await files.get(900); // 本体つき
+ * ```
+ *
+ * PORTERS requires `resource=` on every Attachment Read, and the same value goes into the
+ * `<Resource>` field on write — one binding, both places, exactly like `t.phase.of(...)`.
+ */
+type AttachmentAccessor = {
+    of(resource: ResourceName): AttachmentResource;
+};
 type AttachmentResource = {
     search(query?: AttachmentSearchQuery): Promise<AttachmentPage>;
+    /**
+     * Auto-paginating search: yields every matching attachment (200 per page). Metadata only —
+     * the body stays behind {@link AttachmentResource.get} (ADR-0075), so walking every attachment
+     * in a partition never drags the files along with it.
+     */
+    searchAll(query?: AttachmentWalkQuery): AsyncIterable<Attachment>;
+    /**
+     * Read one attachment **with its body** (`content`). This is the only method that carries it:
+     * one record at a time is a size PORTERS' own 10MB-per-file limit keeps readable (ADR-0075).
+     */
     get(id: number): Promise<Attachment | undefined>;
     /** Create an Attachment; resolves to the newly assigned id. */
     create(input: AttachmentCreate): Promise<number>;
@@ -2336,18 +2461,33 @@ declare const FIELDS$1: {
 /** A decoded Field definition. `P_Required`: 0 = normal, 1 = required. */
 type Field = ReadRecord<typeof FIELDS$1>;
 type FieldPage = ResourcePage<typeof FIELDS$1>;
-/** Field Read query. `resource` selects which resource's fields to read (required). */
+/** Field Read query. The resource itself is bound by `of(name)` (ADR-0080). */
 type FieldSearchQuery = {
-    resource: ResourceType;
     /** -1 = all (default), 0 = unused only, 1 = in-use only. */
     active?: -1 | 0 | 1;
     count?: number;
     start?: number;
 };
+/** The Field accessor for one bound resource. */
 type FieldResource = {
-    search(query: FieldSearchQuery): Promise<FieldPage>;
+    search(query?: FieldSearchQuery): Promise<FieldPage>;
     /** Auto-paginating search: yields every field of the resource. */
-    searchAll(query: Omit<FieldSearchQuery, "count" | "start">): AsyncIterable<Field>;
+    searchAll(query?: Omit<FieldSearchQuery, "count" | "start">): AsyncIterable<Field>;
+};
+/**
+ * Field Read is reached through the resource whose catalog you want (ADR-0080):
+ *
+ * ```ts
+ * const fields = t.field.of("candidate");
+ * for await (const f of fields.searchAll({ active: 1 })) console.log(f.P_Alias);
+ * ```
+ *
+ * The name is the accessor's own spelling ({@link ResourceName}) — `of(1)` and `of("candidat")`
+ * are compile errors. PORTERS requires the `resource=` parameter on every Field Read, so binding
+ * it once means it cannot be forgotten or contradicted.
+ */
+type FieldAccessor = {
+    of(resource: ResourceType): FieldResource;
 };
 
 declare const FIELDS: {
@@ -2453,7 +2593,9 @@ declare const defineFields: <D extends FieldDecls>(decls: D) => DefinedFields<De
  */
 type FieldCatalogSource = {
     readonly field: {
-        searchAll(query: Omit<FieldSearchQuery, "count" | "start">): AsyncIterable<Field>;
+        of(resource: CustomFieldResource): {
+            searchAll(query?: Omit<FieldSearchQuery, "count" | "start">): AsyncIterable<Field>;
+        };
     };
 };
 /** Why a tenant custom field cannot be expressed as a declaration (ADR-0069 論点4). */
@@ -2653,15 +2795,24 @@ declare const assertFieldsMatch: (report: FieldVerification) => void;
 /** Options for constructing a {@link PortersClient}. `C` is inferred from `fields` (ADR-0023). */
 type PortersClientOptions<C extends DeclaredCatalogs = EmptyCatalog> = {
     /**
-     * API host. Required and supplied via `PORTERS_HOST` — never hard-code it.
-     * (A representative value lives in docs/usage/reference.) May carry a port — `localhost:4010`.
+     * API server name. Required and supplied via `PORTERS_HOST` — never hard-code it.
+     * (A representative value lives in docs/usage/reference.)
      *
-     * The **host and nothing else**: no scheme, no path, no userinfo, no whitespace. A value like
-     * `https://xxxxx.example.com` is rejected at construction with a {@link PortersConfigError}
-     * rather than silently addressing a different host (ADR-0048). Any port is fine — including a
-     * redundant `:443` (ADR-0049). Write a non-ASCII host in punycode.
+     * The **name and nothing else**: no port, no scheme, no path, no userinfo, no whitespace
+     * (ADR-0078). PORTERS issues a server name and speaks https, so a port never arrives with it;
+     * when you need one (a local fake, a proxy) pass {@link PortersClientOptions.port}. A value
+     * like `https://xxxxx.example.com` or `a.test:4010` is rejected at construction with a
+     * {@link PortersConfigError} rather than silently addressing something else (ADR-0048).
+     * Write a non-ASCII name in punycode; bracket an IPv6 address (`[::1]`).
+     */
+    hostname: string;
+    /**
+     * Port of the access point (ADR-0078). **Omit it for PORTERS** — the contract gives you a name
+     * and the scheme decides the port. Set it only for a local fake server or a proxy:
+     * `{ hostname: "127.0.0.1", port: 4010, scheme: "http" }`. An integer 1–65535; anything else
+     * is rejected at construction.
      */
-    host: string;
+    port?: number;
     /**
      * URL scheme of the access point (ADR-0047). Defaults to `"https"`. Set `"http"` only for a
      * local fake server or a trusted tunnel: it sends every request — the OAuth token header
@@ -2680,7 +2831,7 @@ type PortersClientOptions<C extends DeclaredCatalogs = EmptyCatalog> = {
     /** Injectable HTTP transport; defaults to a fetch-based transport. */
     transport?: Transport;
     /**
-     * Rate-limit self-restraint (ADR-0073). Defaults to the **process-wide bucket for this host**,
+     * Rate-limit self-restraint (ADR-0073). Defaults to the **process-wide bucket for this destination**,
      * so several clients aimed at the same PORTERS add up to one limit instead of one each.
      *
      * Pass your own to opt out of that sharing, to run different limits, or to coordinate across
@@ -2719,9 +2870,19 @@ type TenantScope<C extends DeclaredCatalogs = EmptyCatalog> = {
     readonly phase: PhaseAccessor;
     readonly process: ProcessResource<CustomFor<C, "process">>;
     readonly resume: ResumeResource<CustomFor<C, "resume">>;
-    readonly attachment: AttachmentResource;
+    /**
+     * Attachments, reached through the resource they belong to: `t.attachment.of("resume")`.
+     * PORTERS requires that `resource` on every Attachment Read, and the same value fills the
+     * `<Resource>` field on write, so it is bound once (ADR-0080 / ADR-0081).
+     */
+    readonly attachment: AttachmentAccessor;
     readonly user: UserResource;
-    readonly field: FieldResource;
+    /**
+     * Field master Read, reached through the resource whose catalog you want:
+     * `t.field.of("candidate")`. PORTERS requires `resource=` on every Field Read, so it is bound
+     * once (ADR-0080).
+     */
+    readonly field: FieldAccessor;
     readonly option: OptionResource;
 };
 /**
@@ -2733,7 +2894,7 @@ type TenantScope<C extends DeclaredCatalogs = EmptyCatalog> = {
  * explicitly, exactly once, so "unbound" is not a state this API can be in.
  *
  * @example
- * const porters = new PortersClient({ host, appId, appSecret });
+ * const porters = new PortersClient({ hostname, appId, appSecret });
  * await porters.auth.ensureAuthenticated();   // App-level
  * const t = porters.tenant(123);              // bind the partition once
  * const page = await t.candidate.search();
@@ -2763,8 +2924,10 @@ declare class PortersClient<C extends DeclaredCatalogs = EmptyCatalog> {
      */
     readonly tenant: (id: PartitionId) => TenantScope<C>;
     constructor(options: PortersClientOptions<C>);
-    /** The configured API host. */
-    get host(): string;
+    /** The configured API server name (no port — see {@link PortersClient.port}). */
+    get hostname(): string;
+    /** The configured port, or `undefined` when the scheme's own port is used (ADR-0078). */
+    get port(): number | undefined;
 }
 
 /** Cross-cutting classification shared by every PORTERS error. */
@@ -2827,4 +2990,4 @@ declare const bytesToBase64: (bytes: Uint8Array) => string;
 /** Decode a Base64 string back to raw bytes. */
 declare const base64ToBytes: (b64: string) => Uint8Array;
 
-export { type Activity, type ActivityCreateInput, type ActivityPage, type ActivityResource, type ActivitySearchQuery, type ActivityUpdateInput, 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 Contact, type ContactCreateInput, type ContactPage, type ContactResource, type ContactSearchQuery, type ContactUpdateInput, type Contract, type ContractCreateInput, type ContractPage, type ContractResource, type ContractSearchQuery, type ContractUpdateInput, type CustomDataType, type CustomFieldResource, type CustomFor, type DeclaredCatalogs, type DefinedFields, type DepartmentRef, type ErrorCategory, type Expand, type ExpandedReadRecord, type Field, type FieldBuilder, type FieldCatalogSource, type FieldDecls, type FieldDef, type FieldPage, type FieldResource, type FieldSearchQuery, type FieldTypeMismatch, type FieldValue, type FieldVerification, type GenerateFieldDeclsOptions, type GetAccessTokenOptions, type ImageContentType, type ImageOption, type ImageReadRecord, type ImageSelectedValue, type ImageSubField, type ImageValue, type ImageWriteValue, type ItemState, type Job, type JobCreateInput, type JobPage, type JobResource, type JobSearchQuery, type JobUpdateInput, type LinkValue, type MissingField, type MockHandler, type MockReply, type MockTransportOptions, type Opportunity, type OpportunityCreateInput, type OpportunityPage, type OpportunityResource, type OpportunitySearchQuery, type OpportunityUpdateInput, type Option, type OptionResource, type OptionSearchQuery, type Order, type Partition, type PartitionId, type PartitionPage, type PartitionResource, type PartitionSearchQuery, type Phase, type PhaseAccessor, type PhaseCreateInput, type PhasePage, type PhaseResource, type PhaseSearchQuery, type PhaseUpdateInput, 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 ReadCustomCatalogOptions, type ReadFieldAlias, type Recruiter, type RecruiterCreateInput, type RecruiterPage, type RecruiterResource, type RecruiterSearchQuery, type RecruiterUpdateInput, type ReferenceMap, type ReferenceRecord, type ResourceName, type ResourcePageOf, type ResourceType, type Resume, type ResumeCreateInput, type ResumePage, type ResumeResource, type ResumeSearchQuery, type ResumeUpdateInput, type RevokeUrlOptions, type Sales, type SalesCreateInput, type SalesPage, type SalesResource, type SalesSearchQuery, type SalesUpdateInput, type Scheme, type Scope, type SearchQuery, type StoredTokens, type TenantCustomCatalog, type TenantScope, type Throttle, type ThrottleOptions, type TokenProvider, type TokenStore, type Transport, type TransportRequest, type TransportResponse, type UndeclarableField, type UndeclarableReason, type UndeclarableTenantField, type UndeclaredField, type UnverifiableResource, type User, type UserPage, type UserRef, type UserResource, type UserSearchQuery, type VerifyFieldsOptions, assertFieldsMatch, base64ToBytes, bytesToBase64, createMockTransport, createThrottle, defineFields, generateFieldDecls, rawValue, readCustomCatalog, verifyFields };
+export { type Activity, type ActivityCreateInput, type ActivityPage, type ActivityResource, type ActivitySearchQuery, type ActivityUpdateInput, type Attachment, type AttachmentAccessor, type AttachmentCreate, type AttachmentPage, type AttachmentResource, type AttachmentSearchQuery, type AttachmentUpdate, type AttachmentWalkQuery, 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 Contact, type ContactCreateInput, type ContactPage, type ContactResource, type ContactSearchQuery, type ContactUpdateInput, type Contract, type ContractCreateInput, type ContractPage, type ContractResource, type ContractSearchQuery, type ContractUpdateInput, type CustomDataType, type CustomFieldResource, type CustomFor, type DeclaredCatalogs, type DefinedFields, type DepartmentRef, type ErrorCategory, type Expand, type ExpandedReadRecord, type FetchTransportOptions, type Field, type FieldAccessor, type FieldBuilder, type FieldCatalogSource, type FieldDecls, type FieldDef, type FieldPage, type FieldResource, type FieldSearchQuery, type FieldTypeMismatch, type FieldValue, type FieldVerification, type GenerateFieldDeclsOptions, type GetAccessTokenOptions, type ImageContentType, type ImageOption, type ImageReadRecord, type ImageSelectedValue, type ImageSubField, type ImageValue, type ImageWriteValue, type ItemState, type Job, type JobCreateInput, type JobPage, type JobResource, type JobSearchQuery, type JobUpdateInput, type LinkValue, type MissingField, type MockHandler, type MockReply, type MockTransportOptions, type Opportunity, type OpportunityCreateInput, type OpportunityPage, type OpportunityResource, type OpportunitySearchQuery, type OpportunityUpdateInput, type Option, type OptionResource, type OptionSearchQuery, type Order, type Partition, type PartitionId, type PartitionPage, type PartitionResource, type PartitionSearchQuery, type Phase, type PhaseAccessor, type PhaseCreateInput, type PhasePage, type PhaseResource, type PhaseSearchQuery, type PhaseUpdateInput, 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 ReadCustomCatalogOptions, type ReadFieldAlias, type Recruiter, type RecruiterCreateInput, type RecruiterPage, type RecruiterResource, type RecruiterSearchQuery, type RecruiterUpdateInput, type ReferenceMap, type ReferenceRecord, type ResourceName, type ResourcePageOf, type ResourceType, type Resume, type ResumeCreateInput, type ResumePage, type ResumeResource, type ResumeSearchQuery, type ResumeUpdateInput, type RevokeUrlOptions, type Sales, type SalesCreateInput, type SalesPage, type SalesResource, type SalesSearchQuery, type SalesUpdateInput, type Scheme, type Scope, type SearchQuery, type StoredTokens, type TenantCustomCatalog, type TenantScope, type Throttle, type ThrottleOptions, type TokenProvider, type TokenStore, type Transport, type TransportRequest, type TransportResponse, type UndeclarableField, type UndeclarableReason, type UndeclarableTenantField, type UndeclaredField, type UnverifiableResource, type User, type UserPage, type UserRef, type UserResource, type UserSearchQuery, type VerifyFieldsOptions, assertFieldsMatch, base64ToBytes, bytesToBase64, createFetchTransport, createMockTransport, createThrottle, defineFields, generateFieldDecls, rawValue, readCustomCatalog, resourceNameOf, resourceValueOf, verifyFields };