@joymerrevent/porters-connect 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -5,6 +5,140 @@
 
 ## [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 つ**
@@ -887,13 +1021,18 @@
 [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

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

@@ -659,16 +659,18 @@ type UpdateInput<F extends FieldCatalog> = {
  */
 type EmptyImages = Record<never, never>;
 /**
- * A query with `K` taken out — and **kept out**. `Omit` alone only stops a fresh object literal
+ * 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 `search(query)` fails whichever way the
- * object was built. The runtime is unaffected: the key can still arrive through a cast (ADR-0074).
+ * 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).
  *
- * Only the **endpoint-level** exclusions (`Unsupported`) get this treatment. `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 from ADR-0076.
+ * 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 WithoutQueryKeys<Q, K extends keyof Q> = Omit<Q, K> & {
+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, 
@@ -683,13 +685,20 @@ type Resource<F extends FieldCatalog, Req extends keyof F, R extends ReferenceMa
  * 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> = {
-    search<const E extends Expand<R> = EmptyReferences, const I extends ImageOption<F> = EmptyImages>(query?: WithoutQueryKeys<SearchQuery<F, R>, Unsupported> & {
+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<WithoutQueryKeys<SearchQuery<F, R>, Unsupported>, "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>>;
@@ -703,9 +712,9 @@ Unsupported extends keyof SearchQuery<F, R> = never> = {
         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
@@ -713,14 +722,14 @@ Unsupported extends keyof SearchQuery<F, R> = never> = {
      * 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>;
 };
 
@@ -1755,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]";
@@ -1793,9 +1833,11 @@ type PhaseCreateInput = CreateInput<typeof FIELDS$6, (typeof REQUIRED_ON_CREATE$
 type PhaseUpdateInput = UpdateInput<typeof FIELDS$6>;
 /**
  * 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).
+ * `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>;
+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):
  *
@@ -2243,11 +2285,6 @@ 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], typeof REFERENCES>;
 
-/**
- * Every Attachment field **except** the body: what a listing may ask for (ADR-0075).
- * These are the aliases `search` / `searchAll` accept.
- */
-type AttachmentMetaField = "Id" | "Resource" | "ResourceId" | "ContentType" | "FileName";
 /** A decoded Attachment. A field is `null` unless it was returned (see `field`). */
 type Attachment = {
     id: number | null;
@@ -2268,22 +2305,22 @@ type AttachmentPage = {
 };
 type AttachmentSearchQuery = {
     /**
-     * Output fields — **metadata only**. Omit for all five (Id / Resource / ResourceId /
-     * ContentType / FileName), or pass `[]` for the API-native primary-key-only response.
-     *
-     * The file body is **not** on this list: a listing never carries it, whatever the count
-     * (ADR-0075). Read a body with {@link AttachmentResource.get}, one record at a time.
+     * 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?: AttachmentMetaField[];
-    condition?: Record<string, string>;
+    resourceId?: number;
     count?: number;
     start?: number;
 };
 /** 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. */
+/**
+ * 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;
@@ -2295,6 +2332,21 @@ 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>;
     /**
@@ -2409,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: {
@@ -2526,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). */
@@ -2726,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
@@ -2753,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
@@ -2792,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;
 };
 /**
@@ -2806,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();
@@ -2836,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. */
@@ -2900,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 AttachmentMetaField, 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 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, 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 };