@joymerrevent/porters-connect 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -5,6 +5,96 @@
 
 ## [Unreleased]
 
+## [0.16.0] - 2026-09-15
+
+**カスタム項目を「宣言してから使う」に揃えた版**です。**破壊的変更**（`field` が未宣言の
+`U_` / `A_` を受け付けなくなります）を含みます。逃げ道として `rawValue` を用意しました。
+
+### Added
+
+- **`rawValue`** — 宣言していない項目の値を、レコードから**そのまま**読み出します（[ADR-0074][adr74]）。
+
+  ```ts
+  import { rawValue } from "@joymerrevent/porters-connect";
+  import type { CandidateSearchQuery } from "@joymerrevent/porters-connect";
+
+  const page = await t.candidate.search({
+    field: ["P_Name", "U_memo"] as CandidateSearchQuery["field"],
+  });
+  const memo = rawValue(page.items[0], "U_memo"); // string | null | undefined
+  ```
+
+  応答に無ければ `undefined`、スカラでなければ（`Option` / `User` / `Image` の入れ子）`null`、
+  あれば生の文字列を返します。**変換はしません**ので、日時は PORTERS の書式
+  （`2026/09/10 12:00:00`）のままです。宣言できる項目は宣言してください — こちらは逃げ道です。
+
+### Changed
+
+- **（破壊的）`field` が未宣言のカスタム項目を受け付けなくなりました**（[ADR-0074][adr74]）。
+  カスタム項目を使う入口は 4 つ（`field` / `condition` / `order` / 書き込み）あり、**`field` だけが
+  宣言なしの `U_` / `A_` を受けていました**。しかも受け取り側の型には出ないため、
+  **要求はできるのに読めない**という非対称が残っていました。
+
+  ```ts
+  await t.candidate.search({ field: ["U_memo"] });
+  //                                 ^^^^^^^^ 型エラーになります
+  ```
+
+  直し方は**宣言**です（`defineFields`）。項目 1 つなら 1 行で済み、テナントの項目からは
+  `generateFieldDecls` で生成できます。宣言すると綴りが検査され、値も宣言した Data Type で
+  変換されます。**実行時の挙動は変えていません** — 型を外せば送れますし、応答に知らない項目が
+  混ざっても落ちません。宣言せずに触る必要があるときは、上記の `rawValue` を使ってください。
+
+- **（型のみ）宣言の違うクライアントを関数に渡せなくなりました**。`TenantScope<typeof fields>` は
+  その宣言のスコープだけを受け取ります。以前は型が通ってしまい、`number` と型が言う値に生の
+  文字列が入ることがありました。どの宣言でも受ける関数は `TenantScope<DeclaredCatalogs>` と
+  書けます（これまでどおり）。
+
+- **使い方ドキュメントで、読み取りと書き込みの非対称を揃えました**。`Option` / `User` /
+  `System[Reference]` / `Image` / `Link` は Read と Write で形が違うため、同じ項目の往復に
+  読み替えが要ります。ガイドと[正典（PORTERS API の事実）][ref]の双方を、出典に突き合わせて
+  埋めました。パッケージの中身は変わりません。
+
+- **`src/fields` が品質ゲートの対象に戻りました**（[RV-44][rv44]）。カバレッジとミューテーションの
+  除外リストに、プレースホルダだった頃の `src/fields/**` が残っていました。宣言 DSL と
+  テナントカタログの照合はすでに実ロジックなので、計測対象に戻し、見つかった抜けを埋めています。
+  こちらもパッケージの中身は変わりません。
+
+## [0.15.1] - 2026-09-13
+
+**開発・CI まわりだけの版**です。**公開されるパッケージの中身（`dist`）は 0.15.0 と同一**で、
+公開 API・型・挙動に変更はありません（既存コードはそのまま動きます）。
+
+### Security
+
+- **開発用依存の既知脆弱性 5 件を解消しました**。いずれもビルド・テスト用ツールの推移依存で、
+  **利用者の実行時には入りません**（`dependencies` は `fast-xml-parser` のみ）。
+  依存の解決を `pnpm.overrides` で固定しています。
+
+  | パッケージ        | 経路                                          | Advisory                                                |
+  | ----------------- | --------------------------------------------- | ------------------------------------------------------- |
+  | `brace-expansion` | `@stryker-mutator/core` > `minimatch`         | [GHSA-mh99-v99m-4gvg][gh1] / [GHSA-rgw5-rvv9-x895][gh2] |
+  | `smol-toml`       | `markdownlint-cli2`                           | [GHSA-7w5x-hrqm-74c2][gh5]                              |
+  | `qs`              | `@stryker-mutator/core` > `typed-rest-client` | [GHSA-x5fp-wj9c-mxmx][gh3] / [GHSA-4mjr-xmp4-gh2g][gh4] |
+
+- **GitHub Actions の書き込み権限を job 単位に絞りました**。タグ作成ワークフローの既定を
+  読み取りのみにし、書き込みは実際に必要な job にだけ与えます。ワークフローが行える操作の範囲は
+  変わりません（最小権限の原則に寄せた整理です）。
+
+### Changed
+
+- **往復・エスケープ・分割の不変条件を property-based テストで検査するようになりました**
+  （[fast-check][fastcheck]）。代表値を 1 点ずつ確かめる形では境界の抜けが見えないため、
+  値を機械に選ばせて不変条件そのものを検査します。対象は 3 つです。
+
+  - 日時: PORTERS 形式 ⇄ ISO 8601 (UTC) の往復と、オフセット表記によらない UTC 正規化
+  - Write XML: エスケープ後に生の `&` `<` `>` が残らないこと、書いて読むと元の値に戻ること
+  - bulk write: 200 件と約 15000 文字の 2 つの上限を、どの入力でも同時に満たすこと
+
+- **生成 API リファレンスの「Defined in」表記を整理しました**。継承元が依存側にある記号
+  （`Error.message` など）のパスから pnpm ストアの版つきディレクトリを落とし、
+  `@types/node/globals.d.ts:67` の形にしています。表示されるメンバーは変わりません。
+
 ## [0.15.0] - 2026-09-13
 
 **宣言と実物のズレを黙って飲み込まなくなった版**です。**破壊的変更**（読み取りの型不一致が
@@ -702,14 +792,19 @@
 [adr63]: docs/adr/0063-idempotency-guard-scope.md
 [rv22]: docs/reviews/rv/0022-ratelimit-create-no-retry.md
 [rv32]: docs/reviews/rv/0032-searchall-query-mutation.md
+[rv44]: docs/reviews/rv/0044-fields-excluded-from-coverage.md
 [write-constraints]: docs/usage/concepts/limits.md
 [adr68]: docs/adr/0068-api-reference-tooling.md
 [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
 [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.14.0...HEAD
+[unreleased]: https://github.com/Joymerrevent/porters-connect/compare/v0.16.0...HEAD
+[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
 [0.14.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.13.0...v0.14.0
 [0.13.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.12.1...v0.13.0
@@ -730,3 +825,9 @@
 [0.2.0]: https://github.com/Joymerrevent/porters-connect/compare/v0.1.1...v0.2.0
 [0.1.1]: https://github.com/Joymerrevent/porters-connect/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/Joymerrevent/porters-connect/releases/tag/v0.1.0
+[gh1]: https://github.com/advisories/GHSA-mh99-v99m-4gvg
+[gh2]: https://github.com/advisories/GHSA-rgw5-rvv9-x895
+[gh3]: https://github.com/advisories/GHSA-x5fp-wj9c-mxmx
+[gh4]: https://github.com/advisories/GHSA-4mjr-xmp4-gh2g
+[gh5]: https://github.com/advisories/GHSA-7w5x-hrqm-74c2
+[fastcheck]: https://github.com/dubzzz/fast-check

package/README.md

@@ -1,6 +1,6 @@
 # @joymerrevent/porters-connect
 
-[![npm version][npm-badge]][npm] [![License: MIT][mit-badge]][mit] ![Node >= 20][node-badge] [![OpenSSF Scorecard][scorecard-badge]][scorecard]
+[![npm version][npm-badge]][npm] [![License: MIT][mit-badge]][mit] ![Node >= 20][node-badge] [![OpenSSF Scorecard][scorecard-badge]][scorecard] [![OpenSSF Best Practices][bp-badge]][bp]
 
 PORTERS Connect API（旧 HRBC）を **TypeScript から型安全・簡単に**扱うための、
 [Joymerrevent（ジョイメリベント）][joymerrevent] 製の **非公式（unofficial）** ラッパーです。
@@ -147,6 +147,8 @@ console.log(page.total, page.items[0]?.P_Name);
 [node-badge]: https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg
 [scorecard]: https://scorecard.dev/viewer/?uri=github.com/Joymerrevent/porters-connect
 [scorecard-badge]: https://api.scorecard.dev/projects/github.com/Joymerrevent/porters-connect/badge
+[bp]: https://www.bestpractices.dev/projects/14611
+[bp-badge]: https://www.bestpractices.dev/projects/14611/badge
 [joymerrevent]: https://github.com/Joymerrevent
 [contributing]: ./CONTRIBUTING.md
 [security]: ./SECURITY.md

package/dist/index.d.ts

@@ -268,13 +268,34 @@ type FieldCatalog = Record<string, DataType | null>;
 type EmptyCatalog = Record<never, never>;
 /**
  * A decoded record: every known field, each `DecodedValue | null`, and **optional** because a
- * field not named in `field` is simply absent (SD-3 "simple" type — ADR-0005/0019). Custom
- * `U_`/`A_` aliases are not in the catalog, so they are not typed here (access via a cast until
- * the declaration DSL lands — ADR-0005 SD-2); at runtime they still pass through as raw values.
+ * field not named in `field` is simply absent (SD-3 "simple" type — ADR-0005/0019). An alias the
+ * catalog does not know is not typed here — declare it with `defineFields` (ADR-0023) to get it
+ * typed and converted. At runtime such a field still passes through as a raw value; read it with
+ * {@link rawValue} (ADR-0074 D2).
  */
 type ReadRecord<F extends FieldCatalog> = {
     [K in keyof F]?: DecodedValue<F[K]> | null;
 };
+/**
+ * Read a field the catalog does not know (ADR-0074 D2) — the named escape hatch for a value that
+ * arrived without a declaration: through a cast in `field`, inside an expanded reference record,
+ * or because PORTERS returned a field that was not asked for.
+ *
+ * Returns what the record actually holds, unconverted:
+ *
+ * - `undefined` — the alias is not on the record (it was never returned)
+ * - `null` — it is there but not a scalar (PORTERS sends a nested node for Option / User / Image)
+ * - `string` — the raw text, exactly as PORTERS sent it
+ *
+ * **No conversion happens.** A date comes back in PORTERS' own format (`2026/09/10 12:00:00`), not
+ * ISO 8601, and a number comes back as text. Declare the field with `defineFields` to get the
+ * converted, typed value instead — this is the escape hatch, not the normal path.
+ *
+ * @example
+ * const page = await t.candidate.search({ field: ["P_Name"] });
+ * const memo = rawValue(page.items[0], "U_memo"); // string | null | undefined
+ */
+declare const rawValue: (record: unknown, alias: string) => string | null | undefined;
 /**
  * A page of decoded records: the standard Read envelope (Total / Count / Start) around whatever
  * the item decoder produced. Parametrised by the *record* rather than the catalog because a read
@@ -288,16 +309,21 @@ type ResourcePageOf<T> = {
 };
 type ResourcePage<F extends FieldCatalog> = ResourcePageOf<ReadRecord<F>>;
 /**
- * What a Read `field` entry may name (ADR-0059): a catalogued alias — every standard `P_` field
- * plus the custom fields declared with `defineFields` (ADR-0023) — or an undeclared tenant custom
- * field, admitted by the `U_`/`A_` naming rule `defineFields` already enforces at runtime.
+ * What a Read `field` entry may name (ADR-0059 / ADR-0074 D1): a **catalogued** alias — every
+ * standard `P_` field plus the custom fields declared with `defineFields` (ADR-0023). An
+ * undeclared `U_`/`A_` alias is **not** accepted: `condition`, `order` and the Write inputs have
+ * always required a declaration, and ADR-0074 D1 brings `field` in line, so custom fields follow
+ * one rule — declare, then use.
  *
  * Aliases are **bare**: the resource's prefix (`Person.` for Candidate) is a constant the
  * descriptor knows, so the library adds it. That makes `condition` / `order` / `field` one
  * vocabulary and turns a typo (`P_Nmae`) or a hand-written prefix into a compile error instead of
  * a request that quietly returns nothing.
+ *
+ * The runtime stays permissive (ADR-0074): an alias that arrives through a cast is still sent, and
+ * a response field the catalog does not know still decodes — read it with {@link rawValue}.
  */
-type ReadFieldAlias<F extends FieldCatalog> = (keyof F & string) | `U_${string}` | `A_${string}`;
+type ReadFieldAlias<F extends FieldCatalog> = keyof F & string;
 
 /**
  * The resource a `System[Reference]` field points at, as far as expansion needs it: its alias
@@ -2801,4 +2827,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, readCustomCatalog, verifyFields };
+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 };

package/dist/index.js

@@ -722,106 +722,6 @@ var isoToPortersDate = (value) => {
   return `${m[1]}/${m[2]}/${m[3]}`;
 };
 
-// src/xml/encode.ts
-var IMAGE_CONTENT_TYPES = [
-  "image/jpeg",
-  "image/gif",
-  "image/png",
-  "image/bmp"
-];
-var escapeXml = (s) => s.replace(
-  /[&<>]/g,
-  (c) => c === "&" ? "&amp;" : c === "<" ? "&lt;" : "&gt;"
-);
-var text = (v) => typeof v === "object" && !Array.isArray(v) ? JSON.stringify(v) : String(v);
-var scalar = (v) => escapeXml(text(v));
-var IMAGE_SUBFIELDS = [
-  "FileName",
-  "ContentType",
-  "Content"
-];
-var imageInner = (value) => {
-  if (typeof value !== "object" || Array.isArray(value)) return scalar(value);
-  const parts = value;
-  return IMAGE_SUBFIELDS.filter((sub) => parts[sub] !== void 0).map((sub) => `<${sub}>${escapeXml(String(parts[sub]))}</${sub}>`).join("");
-};
-var invalidValue = (alias, type, value, cause) => new PortersConfigError(
-  `${alias}: cannot write ${JSON.stringify(value)} as ${type}`,
-  {
-    category: "validation",
-    hint: `${type} values are written in ISO 8601 (e.g. "2026-09-10" / "2026-09-10T12:00:00Z"); the library converts them to PORTERS' format.`,
-    // The underlying RangeError stays on `cause` rather than in the message: the message
-    // already names the field, the value and the type, which is what a reader needs.
-    context: { operation: "encode" },
-    cause
-  }
-);
-var converted = (alias, type, value, convert) => {
-  try {
-    return convert();
-  } catch (cause) {
-    throw invalidValue(alias, type, value, cause);
-  }
-};
-var encodeField = (type, value, alias) => {
-  switch (type) {
-    // Option: the selected aliases as empty child elements. Canonical input is an
-    // array (ADR-0017, symmetric with read); a lone string is wrapped as a 1-element
-    // selection (fail-safe).
-    case "Option":
-      return (Array.isArray(value) ? value : [text(value)]).map((alias2) => `<${alias2}/>`).join("");
-    // System[DateTime] (registration/update) is Write-restricted by PORTERS; we still
-    // serialize it identically — rejecting the write is the input type's job (SD-3).
-    case "DateTime":
-    case "System[DateTime]":
-      return scalar(
-        converted(alias, type, value, () => isoToPortersDateTime(text(value)))
-      );
-    // Age shares Date's wire format (`yyyy/mm/dd`): we write the birthdate.
-    case "Date":
-    case "Age":
-      return scalar(
-        converted(alias, type, value, () => isoToPortersDate(text(value)))
-      );
-    // Image: the three nested sub-elements (ADR-0064 論点3).
-    case "Image":
-      return imageInner(value);
-    // System[Id] / Number / User & System[Reference] / Link (all ID-only) / string Data Types all
-    // serialize as a scalar (the string types stay distinct labels per ADR-0016).
-    // Link の Read は 3 形の union だが、Write は ID ひとつ（`<Alias>10001</Alias>`）＝ User と同じ。
-    // System[Department] は静的な Write 入力から外してあるので、ここに来るのは cast 経由のみ
-    // （System[DateTime] と同じ扱い）。到達したときは User と同じくスカラとして書き出す。
-    case "Link":
-    case "System[Id]":
-    case "Number":
-    case "User":
-    case "System[Reference]":
-    case "System[Department]":
-    case "SinglelineText":
-    case "MultilineText":
-    case "Mail":
-    case "Telephone":
-    case "URL":
-      return scalar(value);
-  }
-};
-var encodeItem = (prefix, fields, item) => {
-  const parts = [];
-  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 || type === null ? scalar(value) : encodeField(type, value, alias);
-    const tag2 = qualify(prefix, alias);
-    parts.push(`<${tag2}>${inner}</${tag2}>`);
-  }
-  return parts.join("");
-};
-var encodeWriteItem = (prefix, fields, item) => `<Item>${encodeItem(prefix, fields, item)}</Item>`;
-var buildWriteXml = (config) => {
-  const items = config.items.map((item) => encodeWriteItem(config.prefix, config.fields, item)).join("");
-  return `<${config.resource}>${items}</${config.resource}>`;
-};
-
 // src/xml/decode.ts
 var bareTag = (key) => key.includes(".") ? key.slice(key.indexOf(".") + 1) : key;
 var pickPrefixed = (obj, prefix, key) => asString(obj[`${prefix}.${key}`]) ?? asString(obj[key]);
@@ -900,7 +800,7 @@ var mismatch = (alias, type, wants) => new PortersResourceError(
     context: { operation: "decode" }
   }
 );
-var converted2 = (alias, type, value, convert) => {
+var converted = (alias, type, value, convert) => {
   try {
     return convert();
   } catch (cause) {
@@ -954,7 +854,7 @@ var decodeField = (type, raw, alias) => {
     // format; System[DateTime] is Write-restricted, but that is a write-time concern.
     case "DateTime":
     case "System[DateTime]":
-      return converted2(
+      return converted(
         alias,
         scalarType,
         value,
@@ -964,7 +864,7 @@ var decodeField = (type, raw, alias) => {
     // and derives the age in its UI, so the faithful value is the date itself.
     case "Date":
     case "Age":
-      return converted2(alias, scalarType, value, () => portersDateToIso(value));
+      return converted(alias, scalarType, value, () => portersDateToIso(value));
   }
 };
 var decodeReferenceRecord = (raw, types) => {
@@ -984,6 +884,12 @@ var decodeReferenceRecord = (raw, types) => {
 };
 
 // src/resources/read-core.ts
+var rawValue = (record, alias) => {
+  const rec = asRecord(record);
+  if (rec === void 0 || !(alias in rec)) return void 0;
+  const value = rec[alias];
+  return typeof value === "string" ? value : null;
+};
 var bareAlias = (key) => key.includes(".") ? key.slice(key.indexOf(".") + 1) : key;
 var USER_SUBFIELDS = ["P_Id", "P_Type", "P_Name", "P_Mail"];
 var readFieldEntry = (prefix, alias, type) => type === "User" ? `${qualify(prefix, alias)}(${USER_SUBFIELDS.map((s) => `User.${s}`).join(",")})` : qualify(prefix, alias);
@@ -1053,6 +959,106 @@ var paginateOnce = async function* (prepare) {
   yield* paginate(prepare());
 };
 
+// src/xml/encode.ts
+var IMAGE_CONTENT_TYPES = [
+  "image/jpeg",
+  "image/gif",
+  "image/png",
+  "image/bmp"
+];
+var escapeXml = (s) => s.replace(
+  /[&<>]/g,
+  (c) => c === "&" ? "&amp;" : c === "<" ? "&lt;" : "&gt;"
+);
+var text = (v) => typeof v === "object" && !Array.isArray(v) ? JSON.stringify(v) : String(v);
+var scalar = (v) => escapeXml(text(v));
+var IMAGE_SUBFIELDS = [
+  "FileName",
+  "ContentType",
+  "Content"
+];
+var imageInner = (value) => {
+  if (typeof value !== "object" || Array.isArray(value)) return scalar(value);
+  const parts = value;
+  return IMAGE_SUBFIELDS.filter((sub) => parts[sub] !== void 0).map((sub) => `<${sub}>${escapeXml(String(parts[sub]))}</${sub}>`).join("");
+};
+var invalidValue = (alias, type, value, cause) => new PortersConfigError(
+  `${alias}: cannot write ${JSON.stringify(value)} as ${type}`,
+  {
+    category: "validation",
+    hint: `${type} values are written in ISO 8601 (e.g. "2026-09-10" / "2026-09-10T12:00:00Z"); the library converts them to PORTERS' format.`,
+    // The underlying RangeError stays on `cause` rather than in the message: the message
+    // already names the field, the value and the type, which is what a reader needs.
+    context: { operation: "encode" },
+    cause
+  }
+);
+var converted2 = (alias, type, value, convert) => {
+  try {
+    return convert();
+  } catch (cause) {
+    throw invalidValue(alias, type, value, cause);
+  }
+};
+var encodeField = (type, value, alias) => {
+  switch (type) {
+    // Option: the selected aliases as empty child elements. Canonical input is an
+    // array (ADR-0017, symmetric with read); a lone string is wrapped as a 1-element
+    // selection (fail-safe).
+    case "Option":
+      return (Array.isArray(value) ? value : [text(value)]).map((alias2) => `<${alias2}/>`).join("");
+    // System[DateTime] (registration/update) is Write-restricted by PORTERS; we still
+    // serialize it identically — rejecting the write is the input type's job (SD-3).
+    case "DateTime":
+    case "System[DateTime]":
+      return scalar(
+        converted2(alias, type, value, () => isoToPortersDateTime(text(value)))
+      );
+    // Age shares Date's wire format (`yyyy/mm/dd`): we write the birthdate.
+    case "Date":
+    case "Age":
+      return scalar(
+        converted2(alias, type, value, () => isoToPortersDate(text(value)))
+      );
+    // Image: the three nested sub-elements (ADR-0064 論点3).
+    case "Image":
+      return imageInner(value);
+    // System[Id] / Number / User & System[Reference] / Link (all ID-only) / string Data Types all
+    // serialize as a scalar (the string types stay distinct labels per ADR-0016).
+    // Link の Read は 3 形の union だが、Write は ID ひとつ（`<Alias>10001</Alias>`）＝ User と同じ。
+    // System[Department] は静的な Write 入力から外してあるので、ここに来るのは cast 経由のみ
+    // （System[DateTime] と同じ扱い）。到達したときは User と同じくスカラとして書き出す。
+    case "Link":
+    case "System[Id]":
+    case "Number":
+    case "User":
+    case "System[Reference]":
+    case "System[Department]":
+    case "SinglelineText":
+    case "MultilineText":
+    case "Mail":
+    case "Telephone":
+    case "URL":
+      return scalar(value);
+  }
+};
+var encodeItem = (prefix, fields, item) => {
+  const parts = [];
+  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 || type === null ? scalar(value) : encodeField(type, value, alias);
+    const tag2 = qualify(prefix, alias);
+    parts.push(`<${tag2}>${inner}</${tag2}>`);
+  }
+  return parts.join("");
+};
+var encodeWriteItem = (prefix, fields, item) => `<Item>${encodeItem(prefix, fields, item)}</Item>`;
+var buildWriteXml = (config) => {
+  const items = config.items.map((item) => encodeWriteItem(config.prefix, config.fields, item)).join("");
+  return `<${config.resource}>${items}</${config.resource}>`;
+};
+
 // src/resources/query.ts
 var KEYWORDS_MAX_CHARS = 100;
 var DELETED_CONDITION_FIELDS = /* @__PURE__ */ new Set([
@@ -2698,6 +2704,7 @@ var CUSTOM_ALIAS = /^[UA]_/;
 var classify = (alias, fieldType) => {
   if (fieldType === null) {
     return {
+      // Stryker disable next-line StringLiteral: equivalent — the caller only tests for "declarable", so any other tag routes the same way
       kind: "undeclarable",
       entry: { alias, fieldType, reason: "unknown-field-type" }
     };
@@ -2706,18 +2713,21 @@ var classify = (alias, fieldType) => {
   const dataType = dataTypeOfFieldType(fieldType);
   if (dataType === void 0) {
     return {
+      // Stryker disable next-line StringLiteral: equivalent — the caller only tests for "declarable", so any other tag routes the same way
       kind: "undeclarable",
       entry: { alias, fieldType, reason: "unknown-field-type" }
     };
   }
   if (dataType === null) {
     return {
+      // Stryker disable next-line StringLiteral: equivalent — the caller only tests for "declarable", so any other tag routes the same way
       kind: "undeclarable",
       entry: { alias, fieldType, label, reason: "no-data-type" }
     };
   }
   if (!isDeclarable(dataType)) {
     return {
+      // Stryker disable next-line StringLiteral: equivalent — the caller only tests for "declarable", so any other tag routes the same way
       kind: "undeclarable",
       entry: { alias, fieldType, label, reason: "not-declarable" }
     };
@@ -2772,7 +2782,10 @@ var undeclarableNote = (entry) => {
 };
 var resourceBlock = (catalog, includeNames) => {
   const entries = Object.entries(catalog.fields).sort(
-    ([a], [b]) => a < b ? -1 : 1
+    ([a], [b]) => (
+      // Stryker disable next-line EqualityOperator: equivalent — object keys are unique, so the tie branch cannot occur
+      a < b ? -1 : 1
+    )
   );
   const declarations = entries.map(([alias, dataType]) => {
     const name = includeNames ? catalog.names[alias] : void 0;
@@ -2909,6 +2922,7 @@ export {
   createThrottle,
   defineFields,
   generateFieldDecls,
+  rawValue,
   readCustomCatalog,
   verifyFields
 };