監査証跡

このキットのすべての変更系契約 — ワークフロー遷移、 インライン編集、 一括操作 — はコミットの瞬間にひとつの問いに答えます。監査証跡は、その問いが 発せられたことの記録です。コンポーネントではなく (hc-timelineは 出荷済み)、単一のエンドポイントでもない(そう装えるレシピは ありません): これはドクトリンなので、ここに置きます。

行

コミットされた変更 1 件につき、追記される行は 1 つ:

カラム	規則
actor	セッションから。フォームからは決して取らない — 「誰が操作したか」のブラウザの主張は証拠になりません
verb	ドメインの動詞(approve、price-change、import)— HTTP メソッドではない
entity、entity_id	何が変わったか
at	サーバの時計 — クライアントの時計は表示用(ローカライズされたタイムスタンプ)であって記録ではない
request_id	ログとエントリを突き合わせる
summary	サーバが描画する一文 — 証跡は人間が読むもの
before → after	変わったフィールドのみ。大きなペイロードは構造化データで持ち、要求時に diff として描画

いつ書くか — 出荷済み契約への対応表

書き込みポイントはレシピが既に定義しているコミットポイントその ものです。そこから重要な規則が導かれます: コミットが exactly-once だから、証跡も exactly-once。

• ワークフロー遷移は 1 エントリを書く。409 の敗者は何も書かない — 何も変えて いないからです。
• インライン編集や データグリッド編集の コミットは 1 エントリ。422 は何も書かない。
• 一括操作は 変更された行ごとに 1 エントリ、プラスバッチに 1 エントリ (バッチのエントリが件数を持つ — CSV インポートの レポートと同型)。
• 削除の取り消しは 削除と復元の両方を書く — undo は 2 つ目の変更であって、 1 つ目の抹消ではありません。
• 冪等キーの リプレイは 2 つ目のエントリを書かない — リプレイされた レスポンスはストレージから来たもので、二度コミットされたものは 何もありません。

追記専用

UPDATE なし、DELETE なし。訂正は「訂正である」と summary が 語る新しいエントリです。間違ったエントリは残ります — 「私たちは かつて X と信じていた」も記録の一部だからです。保持期間は宣言 ポリシー(冪等キーの TTL 方針のアーカイブ時間スケール版)— 失効はポリシーによる掃除であって、編集では決してありません。

読み取り側

hc-timelineが 表示契約です — サーバ描画、新しい順、警告(return・reject)や 失敗を表すアイテムには data-variant:

<ol class="hc-timeline">
  <li class="hc-timeline__item" data-variant="success">
    <span class="hc-timeline__marker" aria-hidden="true"></span>
    <div class="hc-timeline__content">
      <time class="hc-timeline__time" datetime="2026-08-29T09:14:00Z"
            data-hc-time>2026-08-29 09:14</time>
      <p class="hc-timeline__title">Tanaka approved purchase request REQ-58214</p>
      <p class="hc-timeline__description">Amount ¥48,000 · request j_8f3k2</p>
    </div>
  </li>
  …
</ol>

• <time datetime> + data-hc-time でローカライズされた相対日時 (installTime())。 ワイヤ上は ISO のままです。
• レコードページでは レイジーパネルで 読み込む — ほとんどの訪問は証跡を開きません。開かれないものに コストを払わない。
• ページングは data-hx-swap="beforeend" の「さらに読み込む」 (timeline コンポーネントの htmx セクション)。
• グリッドでは証跡は 行から詳細への 素材です — レコードのページがその履歴を所有します。
• 大きな before → after ペイロードは要求時に hc-code の unified diff として描画 — タイムラインのエントリはリンクするだけで、 インラインには決して展開しません。

意図的にやらないこと

• クライアント側のイベント捕捉はしない。 サーバは自分が コミットしたものから証跡を書きます。ブラウザが起きたと主張 するものからではありません — クライアントイベントから組み立てた 証跡は願望であって記録ではない。
• undo はしない。 削除の取り消しは 契約、証跡は記録です。証跡を読んで状態を再構築するのはイベント ソーシング — 別のアーキテクチャであり、意図的にスコープ外です。
• 自明を超える PII 助言はしない: 証跡もデータです。保持 ポリシーは他のテーブルと同様に適用されます。「追記専用」は削除 法制の適用除外ではなく、個人データはエンティティ側に置き証跡は それを参照するよう行を設計する理由です。