イベントリファレンス

イベント型タクソノミー、全イベント共通の JSON エンベロープ、ブラウザ別の URL 捕捉対応。

Zanei が記録するすべてのイベントは、ソースによらず OS 非依存の JSON エンベロープを共有します。スキーマは安定させる方針です。捕捉バックエンドは OS ごとに変わっても、ツールが消費する形は変わりません。

イベントエンベロープ

生出力（query --format jsonl・record・export）は 1 行 1 イベント（NDJSON）です。

{
  "v": 1,
  "id": "evt_01J...",
  "ts": "2026-08-16T12:34:56.789Z",
  "mono_ns": 128374651234,
  "source": "macos.ax",
  "type": "window.focus",
  "app":    { "name": "Safari", "bundle_id": "com.apple.Safari", "pid": 501 },
  "window": { "title": "Design doc", "id": 42 },
  "element": null,
  "data":   { },
  "truncated": false,
  "redaction": { "applied": true, "rules": ["email"] }
}

Chromium・Electron app など Accessibility の window number を公開しない app は、on-screen bounds により window ID と照合されます。

このエンベロープは機械可読な JSON Schema として /schema/event.schema.json にも公開されています。すべてのインターフェースが共有する単一の契約であり、Rust コアの型はこのファイルとの一致をテストで担保されます。

field の byte 上限

Zanei は normalize 時に UTF-8 byte 数で上限を判定します。上限ちょうどの値は保持し、1 byte でも超えた値は null にします。ui.value.value_len など他の metadata は保持され、event には truncated: true と常時適用の変換ルール size_limit が redaction.rules に記録されます。

同じ上限を key event の coalesce 後と privacy redaction 後にも再検査します。文字列の連結や置換 marker により byte 数が増えるためです。URL が除去された browser event は website filter を評価できないため、filter を迂回させず event 全体を破棄します。

イベント型タクソノミー

現在のイベント型です。権限列は、その型の捕捉に必要な macOS 権限を示します（権限ガイド参照）。

--types フィルタでは、browser.*・ui.*・content.* のように末尾ワイルドカードでファミリー全体を選べます。

type は envelope version ごとの closed enum です。未知の型は拒否され、event type の追加には新しい v と対応する store migration が必要です。

型別ペイロード

各型が data に何を持つか、およびエンベロープの window / element の有無（✓ = あり、— = null）。規範的な定義は JSON Schema の型別条件にあります。

field_kind はフォーカス中の入力フィールドの種別です：text / search / url / email / number / other、テキスト系要素にフォーカスがなければ null。password という値は存在しません。Accessibility が既知の非 secure 入力欄を確認できなければ、input.key.text とペースト本文は null です。

ui.value の詳細

自由入力フィールドの data.text には、認可された入力のあとに増えた差分だけが入ります（text_content が有効なときのみ）。Zanei が記録した打鍵またはペースト（input.key・clipboard.paste）は、同じアプリ・同じフォーカス要素の値変化をそれから 3 秒間認可します。1 つの入力に複数の値変化通知が続くことがありますが、すべて認可の対象です。Zanei が拒否した入力（secure input・除外ウィンドウ・不明または読めないフィールド）は何も認可しません。フィールドの全体値が element.value に入ることはありません。

入力が続いている間は値変化をまとめ、1 秒の間が空いたとき、または最長 5 秒ごと、そしてフォーカス移動時と recorder 停止時に記録します。IME の変換途中でまとまりが区切られることがあり、その場合は未確定の読みの一部が前のイベントに、確定した文字列が次のイベントに入ります。

各イベントが持つのは差分だけなので、ui.value を並べても入力された文章は復元できず、data.text を連結すると本人が入力していない文面ができ上がることがあります。IME は確定時に値の末尾を書き換えるため、後の差分は前の差分の続きではなく、その一部を置き換えたものになります。これらのイベントは「何について書いていたか」の手掛かりとして読み、逐語の記録として扱わないでください。正確な文面が必要な場合は、同じウィンドウの直後の content.snapshot を探します。入力または送信された時点でアプリが可視範囲にその文面を描画するため、引用に適するのはそちらです。ただし利用できるのは capture.content_snapshot が有効で、そのアプリが snapshot のフィルタ範囲内にある場合に限られます。snapshot のトリガーが動く前に離脱した短い滞在では取得されず、取得できるのは可視範囲だけです。

認可する入力のない値変化（別のアプリ、別のフォーカス要素、最後の入力から 3 秒超、本文抑止中の Chrome ウィンドウ）はテキストとして記録しません。data.text は null となり、変化後の value_len だけを記録します。削除の場合も text: null です。音声入力自体は、記録済みの打鍵またはペーストのトリガーを伴わないため認可窓を開きません。ただし、同じアプリ・同じフォーカス要素世代への直前の打鍵またはペーストが開いた 3 秒の窓が有効な間に音声テキストが挿入されると、そのテキストが認可された差分に含まれ得ます。

input.key の詳細

「既定は入力の事実 + フィールド種別、内容は opt-in」の正確な形は次のとおりです。

ショートカットは「内容」ではなく「操作」なので、combo は opt-in なしで記録されます。保存・コミット・タブ切替などタイムラインの主要な材料です。input.key.text には Secure Input が無効、Accessibility field が既知かつ非 secure、Chrome 使用時は window が本文許可済み、という条件も必要です。

クリップボードの帰属

clipboard.copy が本文を持つのは、pasteboard 変更が同じプロセスで観測した Command-C と 500 ミリ秒以内に対応するときだけです。それ以外は origin: "unknown"、app 帰属なし、本文 null のイベントとして残ります。copy/paste 本文には Secure Input が無効であることが必要で、paste は既知の非 secure Accessibility field も必要です。Chrome incognito・サイト除外中は両方の本文が null です。

coalesce の保証

イベントはストアに届く前に coalesce されるため、consumer はキー連打やスクロールを生のまま受け取りません。

ショートカットと ui.click は coalesce しません（1 操作 = 1 イベント）。core 側の coalesce バッファは pause・stop・batch flush 時に吐き出されます。collector 側の ui.value バッファは、最後の観測から 1 秒後、または最初の pending 観測から 5 秒後の早い方で flush し、フォーカス変更時と collector 停止時にも flush します。

SQLite writer は、設定された interval・512 events・serialize 済み event data 4 MiB（4,194,304 bytes）のうち最初に到達した条件で batch を flush します。byte 上限により、通常より大きい有効 event が含まれても transaction と保持 memory のコストを制限します。

events_dropped は、本来記録対象だったが、backpressure・queue full・切断などの配送障害で実際に失われたイベントだけを数えます。app または window に帰属できず記録対象外となる入力は数えません。

pause・stop・処理対象の終了シグナル（SIGTERM / SIGINT）では、メモリ上の channel を drain し、coalesce 状態と SQLite batch を flush します。process crash または SIGKILL はこの shutdown path を通らないため、これらの buffer に残るデータは失われ、events_dropped にも計上されません。store が healthy なら、この loss window のうち SQLite batch は上記の flush 条件の最初の到達点までに制限されますが、write backoff 中は保持 batch が batch_interval_s を超えてメモリに残ることがあります。

text_content で変わるもの

opt-in なのは「内容」（打った・コピーした文字列）だけです。「操作の事実」（ショートカット・クリック・URL・タイトル）は既定で記録されます。

スキーマのバージョニング

envelope version は出力全体ではなく event type と payload ごとに決まります。既存 13 type は v: 1、現在の content.snapshot event は v: 3 が必要です。v: 2 の旧 content.snapshot event も有効なまま保持し、query・export・MCP query_events は打ち切り理由を捏造せず、complete field を持つ v2 のまま欠落なく返します。v: 2 だけを理解する consumer は v: 3 event を受理する必要がありません。envelope・event taxonomy・context・version 別 payload は closed です。content.snapshot の v: 1、cutoff を持つ v2、complete を持つ v3、snapshot 以外の既存 type の v2 / v3、未知の field・event type は不正です。type の追加には新しい最小 v と対応する store migration が必要です。

store reader は未知の event type を含む行を skip し、read 全体は失敗させません。CLI の query と export は JSON array の形を維持し、skip 件数を stderr に warning として出します。--quiet で抑止できます。MCP query_events、timeline --format json、structured MCP get_timeline は既存の result object に skipped_unknown_types を返します。

Content snapshot の読み取り

query と MCP query_events は type filter 未指定なら content.* を返しません。snapshot 本文を読むときは content.snapshot または content.* を明示し、狭い時間範囲と小さい limit を使ってください。他の event family と併記できます。export は backup surface なので、全形式で既定ですべての type を含み、--types で絞ります。

timeline は snapshot 本文を inline しません。各 session は snapshot 件数だけを示します。Markdown は activity 行の後に Content snapshots: N を追加し、0 件なら省略します。JSON は 0 を含めて常に content_snapshots を出します。

ブラウザの URL 捕捉

browser.navigate（URL 捕捉）はChromeとSafariに対応します。単体利用と組み込み利用で同じブラウザ収集経路を使います。Chromium は AppleScript でウィンドウのモード（normal / incognito）を返します。incognito は URL イベントを生成せず、本文も設定なしで null のままです。共有イベント契約では、プライバシーモードを判定できない観測を mode: "unknown" で表せます。この観測を normal として扱うことはありません。

navigation はタブ・ウィンドウ・タイトル・ページ読み込みの変化時に観測します。タイトルもフォーカスも変化しないページ内 navigation では browser.navigate が生成されない場合があります。

SafariのURL取得とサイトフィルタに、組み込み専用の設定は不要です。Safariにもアプリ・サイトの除外設定を適用し、入力本文・snapshotの既定除外は維持します。Safariはプライベート閲覧を確実に識別できないため、本文収集を有効にするとプライベート閲覧の本文も含まれ得ます。URL取得にはrecorderプロセスへのSafari Automation権限が必要です。FirefoxのURL取得は引き続き非対応です。

データの 2 層

• 生イベント層 — 完全・機械可読。query・record・export が返すもの。
• タイムライン層 — 人間 / LLM 可読。セッション分割・重複除去・coalesce・token budget 付き serialize。timeline と get_timeline が返すもの。

タイムラインの各セッションは背後の生イベントへの event_ids 逆参照を持ちます。JSON 出力では 1 セッション最大 100 ID で、超過時は event_ids_truncated: true になります。この field は false の場合も常に出力され、token budget をなお超える場合は session を削除する前に全 event_ids が省略されます。