@aiquants/daily-report 0.14.1 → 0.15.0

package/README.md

@@ -144,8 +144,10 @@ createDailyReportServer({
 | Return value | Meaning |
 | --- | --- |
 | `undefined` / `null` | Unrestricted — every source type (the default when the port is not injected). |
-| `["legacy", "Internal"]` | Only those source types are visible. |
+| `["legacy", "Internal"]` | Only those source types are visible (bodies **and** comments). |
 | `[]` | Nothing is visible (zero rows) — **not** the same as `null`. |
+| `{ read: [...] }` | Same as returning the bare array — the comment dimension follows `read`. |
+| `{ read: [...], comment: [...] }` | Bodies and comments restricted independently. See [Comment visibility](#comment-visibility). |
 | throws | Treated as `[]` (deny all). The failure is logged; an authorization-store outage never falls open. |
 
 - **Vocabulary**: the strings are `DailyReportHub.source_type` **values** — the `sourceType` of each entry you registered in `externalSources`, plus `"Internal"` which the package writes for reports it creates. They are *not* your authorization resource keys; mapping a resource key (e.g. `report_legacy`) onto a source type (e.g. `legacy`) is the consuming app's job. Read the canonical set at boot from `dailyReportServer.knownSourceTypes` and assert your mapping against it — an unknown token silently matches zero rows.
@@ -157,6 +159,33 @@ createDailyReportServer({
 - **Performance**: the port is called once per request on the critical path (cache keys incorporate the resolved set), so keep it fast — cache grants per session/user with a short TTL (≤ 60s). A live SSE connection re-resolves on its existing keep-alive tick (~60s) to bound how long a revoked grant keeps streaming; that call passes `reason: "refresh"` and reuses the connection's original `Request`, so a cache keyed on request identity **must** be bypassed when `reason === "refresh"` or the re-check silently returns the stale set.
 - **SSE latency**: because a live connection re-resolves periodically, a grant change (in either direction) takes effect for the stream within ~60s. Events dropped before a widening are not replayed; the next read (which re-resolves per request) restores them.
 
+### Comment visibility
+
+Return `{ read, comment }` from the same port to restrict **reading and writing comments** independently of the report bodies — this is what connects a per-category comment permission (e.g. `daily_report_legacy_comment`) to actual access control.
+
+```ts
+resolveVisibleSourceTypes: async (request, { reason }) => {
+  const grants = await yourAuthz.grantsFor(request, { skipCache: reason === "refresh" })
+  return {
+    read: grants.readableSourceTypes,        // e.g. ["legacy", "Internal"]
+    comment: grants.commentableSourceTypes,  // e.g. ["Internal"] — omit the key to follow `read`
+  }
+},
+```
+
+| `comment` | Meaning |
+| --- | --- |
+| omitted | Follows `read` — identical to returning a bare array. This is the default and the only spelling for "same as bodies". |
+| `[]` | Comments are invisible and cannot be written, while the bodies stay readable. |
+| `["Internal"]` | Only those source types' comments are visible/writable. Narrowed to `read ∩ comment` at construction, since comments only ever ship inside an already-read-filtered report. |
+
+- **`null` is rejected by the type system** — a second spelling for "follow `read`" would make the dimension four-state and reintroduce exactly the unrestricted-vs-deny-all confusion the tri-state contract exists to prevent. A `null` that slips through at runtime fails **closed**.
+- **What it covers**: `DailyReportDetail` carries comments in **two** structurally different fields — `commentItems` (the package's own comment table) and `comments` (legacy JSON supplied by an `externalSources` adapter). Both are gated. They are emptied, never omitted: the keys are required by the SSE schema, and dropping them would make a receiver discard the whole message.
+- **Live events**: `comment-add` / `comment-delete` are judged on the comment dimension, and the report payload embedded in `report-create` / `report-update` / `report-publish` has its two comment arrays emptied per viewer at delivery time.
+- **Your own comments are always visible and always deletable** (`commentItems` only — the legacy `comments` array carries no user identity, so it is all-or-nothing per source type). Hiding them would strand existing comments as undeletable the moment a grant is revoked, with no security gain.
+- **Writing to external sources remains impossible regardless** — `addComment` rejects any non-`Internal` source type outright, so for external categories the comment dimension effectively controls *reading*.
+- **Cache**: the dimension is folded into the cache-key digest, so revoking only the comment grant invalidates immediately. When `comment` follows `read` (the default) the digest is byte-identical to before, so existing deployments see no cache churn.
+
 ## Client wiring
 
 ```tsx

package/dist/server.d.mts

@@ -73,16 +73,42 @@ type DailyReportAuthenticate = (request: Request, options: {
 } | {
     failureRedirect: null;
 }) => Promise<DailyReportAuthResult>;
+/**
+ * Per-dimension visible source types (report body vs. comments).
+ * 次元ごとの可視 sourceType (本文とコメント)。
+ *
+ * コメントの閲覧・記入を本文の可視性から独立して絞るための形。
+ *
+ * - `read`: 本文 (日報行) を閲覧してよい sourceType。**空配列は 0 件**。
+ * - `comment` **省略**: コメント次元は `read` に従う (単一次元と同義・現行互換)。
+ * - `comment: []`: コメント 0 件かつ記入不可。
+ *
+ * ❗ `comment` に `null` は受け付けない。「`read` に従う」の綴りを 2 つ作ると、
+ *   ポート全体の nullish (= 無制限) と次元レベルの nullish が混ざって 4 状態になり、
+ *   本ファイルが一貫して避けている「無制限と全拒否の取り違え」を次元単位で再発させる。
+ *
+ * ❗ `read` の外側にあるコメントトークンは意味を持たない (コメントは必ず read で絞られた
+ *   詳細の内側にしか載らない)。`DailyReportViewerScope.restrictTo` が構築時に
+ *   `read` との積集合へ狭めるため、設定ミスは黙って安全側へ倒れる。
+ */
+type DailyReportVisibilityDimensions = {
+    /** 本文を閲覧してよい sourceType。空配列は 0 件。 */
+    read: readonly string[];
+    /** コメントを閲覧・記入してよい sourceType。省略時は `read` に従う。空配列は 0 件かつ記入不可。 */
+    comment?: readonly string[];
+};
 /**
  * Raw return of the visible-source-type resolver.
  * 可視 sourceType リゾルバの生戻り値。
  *
  * - `undefined` / `null`: 無制限 (全件)。ポート未注入時と同じ既定の意味。
- * - `string[]`: その集合に限定。要素は `DailyReportHub.sourceType` の値であり、**空配列は 0 件**。
+ * - `string[]`: 本文・コメントの双方をその集合に限定。要素は `DailyReportHub.sourceType` の値であり、
+ *   **空配列は 0 件**。`{ read: <配列> }` と完全に同義。
+ * - `{ read, comment? }`: 次元ごとに指定する ({@link DailyReportVisibilityDimensions})。
  *
- * 中立契約: いかなる認可パッケージの型 (`PermissionView` 等) にも依存しない素の文字列配列。
+ * 中立契約: いかなる認可パッケージの型 (`PermissionView` 等) にも依存しない素の文字列と配列のみ。
  */
-type DailyReportVisibleSourceTypes = readonly string[] | null | undefined;
+type DailyReportVisibleSourceTypes = readonly string[] | DailyReportVisibilityDimensions | null | undefined;
 /**
  * Why the visible-source-type resolver is being called.
  * 可視 sourceType リゾルバが呼ばれた理由。
@@ -1547,6 +1573,15 @@ declare function defineDailyReportSchema<S extends string>(schemaName: S, opts:
  *
  * この 2 状態の取り違えは情報漏洩か機能停止に直結するため、判定・畳み込み・キー生成を
  * 本ファイルへ一元化し、ハンドラ層とサービス層の双方がここだけを参照する。
+ *
+ * 閲覧範囲は**次元ごと**にこの 2 状態を持つ:
+ *
+ * - `visible`    = 本文 (日報行) を閲覧してよい区分。
+ * - `commentable` = コメントを閲覧・記入してよい区分。常に `visible` の部分集合。
+ *
+ * 次元が増えても状態数は増やさない。「もう一方の次元に従う」は
+ * {@link DailyReportViewerScope.restrictTo} が**構築時に解決**するため、各次元は最後まで
+ * 厳密に 2 状態であり、本ファイルの判定ヘルパーは次元を問わずそのまま適用できる。
  */
 
 /**
@@ -1562,10 +1597,19 @@ type VisibleSourceTypeSet = ReadonlySet<string> | null;
  * `Set` 化する。**空配列は空 `Set` (0 件) を返し、`null` (無制限) へは決して倒さない** —
  * この取り違えが情報漏洩か機能停止に直結するため。
  *
- * @param raw Raw resolver return value. ポートの生戻り値。
+ * ❗ 引数は**単一次元のトークン配列に限る**。次元別オブジェクト
+ * ({@link DailyReportVisibilityDimensions}) をここへ渡すと配列ガードに掛かって全拒否になるため、
+ * 次元の解体は {@link DailyReportViewerScope.restrictTo} が行い、ここには常に配列だけが届く。
+ *
+ * ❗ オーバーロードで「**配列を渡した場合は決して `null` (無制限) を返さない**」という不変条件を
+ * 型に載せている。これは実装の偶然ではなく本ファイルの中核契約 (空配列は 0 件であって無制限では
+ * ない) そのものであり、呼び出し側が `null` 分岐を書いて無制限へ倒す余地を型で塞ぐ。
+ *
+ * @param raw Raw single-dimension resolver value. 単一次元の生値。
  * @returns Normalized visible set. 正規化済みの可視集合。
  */
-declare function normalizeVisibleSourceTypes(raw: DailyReportVisibleSourceTypes): VisibleSourceTypeSet;
+declare function normalizeVisibleSourceTypes(raw: readonly string[]): ReadonlySet<string>;
+declare function normalizeVisibleSourceTypes(raw: readonly string[] | null | undefined): VisibleSourceTypeSet;
 /**
  * Tests whether a report's sourceType is visible under the given set.
  * ある日報の sourceType が可視集合に含まれるかの三値判定。
@@ -1625,24 +1669,36 @@ declare function buildVisibleSourceTypeCondition(sourceTypeColumn: AnyMsSqlColum
 declare class DailyReportViewerScope {
     #private;
     private constructor();
-    /** 正規化済みの可視集合。`null` は無制限、空集合は 0 件 (fail-close)。 */
+    /** 正規化済みの本文可視集合。`null` は無制限、空集合は 0 件 (fail-close)。 */
     get visible(): VisibleSourceTypeSet;
+    /**
+     * 正規化済みのコメント可視集合。`null` は無制限、空集合は 0 件 (fail-close)。
+     *
+     * 常に `visible` の部分集合である (構築時に積集合を取っているため)。
+     */
+    get commentable(): VisibleSourceTypeSet;
     /**
      * Builds a scope restricted to the given source types (empty input = zero rows).
      * 指定した sourceType へ限定した閲覧範囲を生成する処理 (空入力は 0 件)。
      *
      * 入力は {@link normalizeVisibleSourceTypes} を通るため、大小文字・前後空白・重複・非文字列は
-     * ここで吸収される。
+     * ここで吸収される。素の配列は `{ read: <配列> }` と同義で、コメント次元は `read` に従う。
      *
-     * ❗ 引数は `readonly string[]` に**狭めてある**。`null` / `undefined` を受け付けると、
-     * 「restrict」という名前のまま無制限スコープを生む第 2 の入口になり、
-     * 「絞り込まれない読み取りは必ず {@link DailyReportViewerScope.unrestricted} に現れる」
-     * という監査不変条件が崩れる。無制限は必ず理由付きで明示すること。
+     * ❗ 引数は `null` / `undefined` を**受け付けない**。受け付けると「restrict」という名前のまま
+     * 無制限スコープを生む第 2 の入口になり、「絞り込まれない読み取りは必ず
+     * {@link DailyReportViewerScope.unrestricted} に現れる」という監査不変条件が崩れる。
+     * 無制限は必ず理由付きで明示すること。
      *
-     * @param sourceTypes Visible source-type tokens. 可視 sourceType のトークン群。
+     * ❗ 判別に `Array.isArray` を使ってはならない。型述語が `arg is any[]` であり
+     * `readonly string[]` を負の分岐から除去できないため、`.read` 参照が TS2339 になる
+     * (実測済み)。`"read" in input` で判別する。文字列など object でない契約違反入力は
+     * `in` が実行時に throw するので、先に `typeof` で弾いてから
+     * {@link normalizeVisibleSourceTypes} の fail-close 経路へ落とす。
+     *
+     * @param input Visible source-type tokens, or per-dimension sets. 可視 sourceType のトークン群、または次元別の集合。
      * @returns The scope. 生成した閲覧範囲。
      */
-    static restrictTo(sourceTypes: readonly string[]): DailyReportViewerScope;
+    static restrictTo(input: readonly string[] | DailyReportVisibilityDimensions): DailyReportViewerScope;
     /**
      * Builds an unrestricted scope; every call site is an audited fail-open.
      * 無制限の閲覧範囲を生成する処理。全呼び出し箇所が監査対象の fail-open となる。
@@ -1650,17 +1706,29 @@ declare class DailyReportViewerScope {
      * ❗ 理由文字列は必須。読み捨てるが、呼び出し箇所の全数列挙と「なぜここは絞らなくてよいか」の
      * 記録を強制するために受け取る。
      *
+     * ❗ **両次元**を無制限にする。片方だけ残すと「無制限」という名前が嘘になり、監査 grep の
+     * 結果が「絞られていない読み取りの全数」でなくなる。
+     *
      * @param auditReason Why unrestricted access is correct here. なぜここで無制限が正当かの理由。
      * @returns The unrestricted scope. 無制限の閲覧範囲。
      */
     static unrestricted(auditReason: string): DailyReportViewerScope;
 }
 /**
- * Computes the cache-key digest for a whole viewer scope.
- * 閲覧範囲全体からキャッシュキー用ダイジェストを算出する処理。
+ * Computes the cache-key digest for a whole viewer scope (all dimensions).
+ * 閲覧範囲全体 (全次元) からキャッシュキー用ダイジェストを算出する処理。
  *
  * スコープに次元が増えてもキャッシュキーの生成点を 1 つに保つための入口。
  *
+ * ❗ **必ず全次元を畳み込むこと。** 本文次元だけを畳み込むと、コメント権限だけを剥奪された
+ * 同一ユーザーが剥奪前のキャッシュバケットを共有し続け、TTL の間コメント本文入りの詳細を
+ * 受け取り続ける (キーが変わらないため無効化も走らない)。
+ *
+ * 両次元が一致する既定形 (コメント次元が `read` に従う) では**本文のみのダイジェストと同一値**を
+ * 返す。既存配備のキャッシュキーは 1 文字も変わらず、キャッシュ再利用率は無退行となる。
+ * 次元が分かれるときだけ `d:` 名前空間の下へ**長さ接頭辞付きで連結**するため、写像は単射であり
+ * sentinel (`all` / `none`) や単一次元表記 (`s:` / `sh:`) と衝突しない。
+ *
  * @param scope Viewer scope. 閲覧範囲。
  * @returns Digest usable as a cache-key component. キャッシュキー構成要素として使えるダイジェスト。
  */
@@ -2254,4 +2322,4 @@ declare function createDailyReportServer(config: DailyReportServerConfig): {
     knownSourceTypes: readonly string[];
 };
 
-export { type AuthzResourceItem, type DailyReportAttachmentBytes, type DailyReportAttachmentError, type DailyReportAttachmentFailure, type DailyReportAttachmentTable, type DailyReportAuthResult, type DailyReportAuthenticate, type DailyReportCommentRow, type DailyReportCommentTable, type DailyReportDb, type DailyReportEncodeUserId, type DailyReportExternalSource, type DailyReportHandlersConfig, type DailyReportHubLabelTable, type DailyReportHubRow, type DailyReportHubTable, type DailyReportIdCodec, type DailyReportInternalRow, type DailyReportInternalTable, type DailyReportLabelTable, type DailyReportReadAttachment, type DailyReportRedisBlockingClient, type DailyReportRedisClient, type DailyReportRedisProvider, type DailyReportResolveUserId, type DailyReportResolveVisibleSourceTypes, type DailyReportServerConfig, type DailyReportService, type DailyReportServiceConfig, type DailyReportSourceTypeInput, DailyReportSseReader, type DailyReportSseReaderConfig, type DailyReportTables, type DailyReportUserStatusRow, type DailyReportUserStatusTable, type DailyReportUserTable, DailyReportViewerScope, type DailyReportVisibilityResolveContext, type DailyReportVisibilityResolveReason, type DailyReportVisibleSourceTypes, type EpochStore, type ExternalReportFields, type RedisStreamMessage, SqlResultCache, type SqlResultCacheQueryOptions, type StreamEntry, type VisibleSourceTypeSet, asciiFallbackFileName, buildVisibleSourceTypeCondition, computeSourceTypeDigest, computeViewerScopeDigest, createDailyReportHandlers, createDailyReportServer, createDailyReportService, createEpochStore, defineDailyReportAuthzResources, defineDailyReportSchema, deniesEverySourceType, encodeRfc8187, formatDateValue, generateETag, isSourceTypeVisible, isStreamIdLte, jsonResponseWithETag, normalizeVisibleSourceTypes, sanitizeMediaType, seedDailyReportAuthzResources, transformJsonArray };
+export { type AuthzResourceItem, type DailyReportAttachmentBytes, type DailyReportAttachmentError, type DailyReportAttachmentFailure, type DailyReportAttachmentTable, type DailyReportAuthResult, type DailyReportAuthenticate, type DailyReportCommentRow, type DailyReportCommentTable, type DailyReportDb, type DailyReportEncodeUserId, type DailyReportExternalSource, type DailyReportHandlersConfig, type DailyReportHubLabelTable, type DailyReportHubRow, type DailyReportHubTable, type DailyReportIdCodec, type DailyReportInternalRow, type DailyReportInternalTable, type DailyReportLabelTable, type DailyReportReadAttachment, type DailyReportRedisBlockingClient, type DailyReportRedisClient, type DailyReportRedisProvider, type DailyReportResolveUserId, type DailyReportResolveVisibleSourceTypes, type DailyReportServerConfig, type DailyReportService, type DailyReportServiceConfig, type DailyReportSourceTypeInput, DailyReportSseReader, type DailyReportSseReaderConfig, type DailyReportTables, type DailyReportUserStatusRow, type DailyReportUserStatusTable, type DailyReportUserTable, DailyReportViewerScope, type DailyReportVisibilityDimensions, type DailyReportVisibilityResolveContext, type DailyReportVisibilityResolveReason, type DailyReportVisibleSourceTypes, type EpochStore, type ExternalReportFields, type RedisStreamMessage, SqlResultCache, type SqlResultCacheQueryOptions, type StreamEntry, type VisibleSourceTypeSet, asciiFallbackFileName, buildVisibleSourceTypeCondition, computeSourceTypeDigest, computeViewerScopeDigest, createDailyReportHandlers, createDailyReportServer, createDailyReportService, createEpochStore, defineDailyReportAuthzResources, defineDailyReportSchema, deniesEverySourceType, encodeRfc8187, formatDateValue, generateETag, isSourceTypeVisible, isStreamIdLte, jsonResponseWithETag, normalizeVisibleSourceTypes, sanitizeMediaType, seedDailyReportAuthzResources, transformJsonArray };

package/dist/server.d.ts

@@ -73,16 +73,42 @@ type DailyReportAuthenticate = (request: Request, options: {
 } | {
     failureRedirect: null;
 }) => Promise<DailyReportAuthResult>;
+/**
+ * Per-dimension visible source types (report body vs. comments).
+ * 次元ごとの可視 sourceType (本文とコメント)。
+ *
+ * コメントの閲覧・記入を本文の可視性から独立して絞るための形。
+ *
+ * - `read`: 本文 (日報行) を閲覧してよい sourceType。**空配列は 0 件**。
+ * - `comment` **省略**: コメント次元は `read` に従う (単一次元と同義・現行互換)。
+ * - `comment: []`: コメント 0 件かつ記入不可。
+ *
+ * ❗ `comment` に `null` は受け付けない。「`read` に従う」の綴りを 2 つ作ると、
+ *   ポート全体の nullish (= 無制限) と次元レベルの nullish が混ざって 4 状態になり、
+ *   本ファイルが一貫して避けている「無制限と全拒否の取り違え」を次元単位で再発させる。
+ *
+ * ❗ `read` の外側にあるコメントトークンは意味を持たない (コメントは必ず read で絞られた
+ *   詳細の内側にしか載らない)。`DailyReportViewerScope.restrictTo` が構築時に
+ *   `read` との積集合へ狭めるため、設定ミスは黙って安全側へ倒れる。
+ */
+type DailyReportVisibilityDimensions = {
+    /** 本文を閲覧してよい sourceType。空配列は 0 件。 */
+    read: readonly string[];
+    /** コメントを閲覧・記入してよい sourceType。省略時は `read` に従う。空配列は 0 件かつ記入不可。 */
+    comment?: readonly string[];
+};
 /**
  * Raw return of the visible-source-type resolver.
  * 可視 sourceType リゾルバの生戻り値。
  *
  * - `undefined` / `null`: 無制限 (全件)。ポート未注入時と同じ既定の意味。
- * - `string[]`: その集合に限定。要素は `DailyReportHub.sourceType` の値であり、**空配列は 0 件**。
+ * - `string[]`: 本文・コメントの双方をその集合に限定。要素は `DailyReportHub.sourceType` の値であり、
+ *   **空配列は 0 件**。`{ read: <配列> }` と完全に同義。
+ * - `{ read, comment? }`: 次元ごとに指定する ({@link DailyReportVisibilityDimensions})。
  *
- * 中立契約: いかなる認可パッケージの型 (`PermissionView` 等) にも依存しない素の文字列配列。
+ * 中立契約: いかなる認可パッケージの型 (`PermissionView` 等) にも依存しない素の文字列と配列のみ。
  */
-type DailyReportVisibleSourceTypes = readonly string[] | null | undefined;
+type DailyReportVisibleSourceTypes = readonly string[] | DailyReportVisibilityDimensions | null | undefined;
 /**
  * Why the visible-source-type resolver is being called.
  * 可視 sourceType リゾルバが呼ばれた理由。
@@ -1547,6 +1573,15 @@ declare function defineDailyReportSchema<S extends string>(schemaName: S, opts:
  *
  * この 2 状態の取り違えは情報漏洩か機能停止に直結するため、判定・畳み込み・キー生成を
  * 本ファイルへ一元化し、ハンドラ層とサービス層の双方がここだけを参照する。
+ *
+ * 閲覧範囲は**次元ごと**にこの 2 状態を持つ:
+ *
+ * - `visible`    = 本文 (日報行) を閲覧してよい区分。
+ * - `commentable` = コメントを閲覧・記入してよい区分。常に `visible` の部分集合。
+ *
+ * 次元が増えても状態数は増やさない。「もう一方の次元に従う」は
+ * {@link DailyReportViewerScope.restrictTo} が**構築時に解決**するため、各次元は最後まで
+ * 厳密に 2 状態であり、本ファイルの判定ヘルパーは次元を問わずそのまま適用できる。
  */
 
 /**
@@ -1562,10 +1597,19 @@ type VisibleSourceTypeSet = ReadonlySet<string> | null;
  * `Set` 化する。**空配列は空 `Set` (0 件) を返し、`null` (無制限) へは決して倒さない** —
  * この取り違えが情報漏洩か機能停止に直結するため。
  *
- * @param raw Raw resolver return value. ポートの生戻り値。
+ * ❗ 引数は**単一次元のトークン配列に限る**。次元別オブジェクト
+ * ({@link DailyReportVisibilityDimensions}) をここへ渡すと配列ガードに掛かって全拒否になるため、
+ * 次元の解体は {@link DailyReportViewerScope.restrictTo} が行い、ここには常に配列だけが届く。
+ *
+ * ❗ オーバーロードで「**配列を渡した場合は決して `null` (無制限) を返さない**」という不変条件を
+ * 型に載せている。これは実装の偶然ではなく本ファイルの中核契約 (空配列は 0 件であって無制限では
+ * ない) そのものであり、呼び出し側が `null` 分岐を書いて無制限へ倒す余地を型で塞ぐ。
+ *
+ * @param raw Raw single-dimension resolver value. 単一次元の生値。
  * @returns Normalized visible set. 正規化済みの可視集合。
  */
-declare function normalizeVisibleSourceTypes(raw: DailyReportVisibleSourceTypes): VisibleSourceTypeSet;
+declare function normalizeVisibleSourceTypes(raw: readonly string[]): ReadonlySet<string>;
+declare function normalizeVisibleSourceTypes(raw: readonly string[] | null | undefined): VisibleSourceTypeSet;
 /**
  * Tests whether a report's sourceType is visible under the given set.
  * ある日報の sourceType が可視集合に含まれるかの三値判定。
@@ -1625,24 +1669,36 @@ declare function buildVisibleSourceTypeCondition(sourceTypeColumn: AnyMsSqlColum
 declare class DailyReportViewerScope {
     #private;
     private constructor();
-    /** 正規化済みの可視集合。`null` は無制限、空集合は 0 件 (fail-close)。 */
+    /** 正規化済みの本文可視集合。`null` は無制限、空集合は 0 件 (fail-close)。 */
     get visible(): VisibleSourceTypeSet;
+    /**
+     * 正規化済みのコメント可視集合。`null` は無制限、空集合は 0 件 (fail-close)。
+     *
+     * 常に `visible` の部分集合である (構築時に積集合を取っているため)。
+     */
+    get commentable(): VisibleSourceTypeSet;
     /**
      * Builds a scope restricted to the given source types (empty input = zero rows).
      * 指定した sourceType へ限定した閲覧範囲を生成する処理 (空入力は 0 件)。
      *
      * 入力は {@link normalizeVisibleSourceTypes} を通るため、大小文字・前後空白・重複・非文字列は
-     * ここで吸収される。
+     * ここで吸収される。素の配列は `{ read: <配列> }` と同義で、コメント次元は `read` に従う。
      *
-     * ❗ 引数は `readonly string[]` に**狭めてある**。`null` / `undefined` を受け付けると、
-     * 「restrict」という名前のまま無制限スコープを生む第 2 の入口になり、
-     * 「絞り込まれない読み取りは必ず {@link DailyReportViewerScope.unrestricted} に現れる」
-     * という監査不変条件が崩れる。無制限は必ず理由付きで明示すること。
+     * ❗ 引数は `null` / `undefined` を**受け付けない**。受け付けると「restrict」という名前のまま
+     * 無制限スコープを生む第 2 の入口になり、「絞り込まれない読み取りは必ず
+     * {@link DailyReportViewerScope.unrestricted} に現れる」という監査不変条件が崩れる。
+     * 無制限は必ず理由付きで明示すること。
      *
-     * @param sourceTypes Visible source-type tokens. 可視 sourceType のトークン群。
+     * ❗ 判別に `Array.isArray` を使ってはならない。型述語が `arg is any[]` であり
+     * `readonly string[]` を負の分岐から除去できないため、`.read` 参照が TS2339 になる
+     * (実測済み)。`"read" in input` で判別する。文字列など object でない契約違反入力は
+     * `in` が実行時に throw するので、先に `typeof` で弾いてから
+     * {@link normalizeVisibleSourceTypes} の fail-close 経路へ落とす。
+     *
+     * @param input Visible source-type tokens, or per-dimension sets. 可視 sourceType のトークン群、または次元別の集合。
      * @returns The scope. 生成した閲覧範囲。
      */
-    static restrictTo(sourceTypes: readonly string[]): DailyReportViewerScope;
+    static restrictTo(input: readonly string[] | DailyReportVisibilityDimensions): DailyReportViewerScope;
     /**
      * Builds an unrestricted scope; every call site is an audited fail-open.
      * 無制限の閲覧範囲を生成する処理。全呼び出し箇所が監査対象の fail-open となる。
@@ -1650,17 +1706,29 @@ declare class DailyReportViewerScope {
      * ❗ 理由文字列は必須。読み捨てるが、呼び出し箇所の全数列挙と「なぜここは絞らなくてよいか」の
      * 記録を強制するために受け取る。
      *
+     * ❗ **両次元**を無制限にする。片方だけ残すと「無制限」という名前が嘘になり、監査 grep の
+     * 結果が「絞られていない読み取りの全数」でなくなる。
+     *
      * @param auditReason Why unrestricted access is correct here. なぜここで無制限が正当かの理由。
      * @returns The unrestricted scope. 無制限の閲覧範囲。
      */
     static unrestricted(auditReason: string): DailyReportViewerScope;
 }
 /**
- * Computes the cache-key digest for a whole viewer scope.
- * 閲覧範囲全体からキャッシュキー用ダイジェストを算出する処理。
+ * Computes the cache-key digest for a whole viewer scope (all dimensions).
+ * 閲覧範囲全体 (全次元) からキャッシュキー用ダイジェストを算出する処理。
  *
  * スコープに次元が増えてもキャッシュキーの生成点を 1 つに保つための入口。
  *
+ * ❗ **必ず全次元を畳み込むこと。** 本文次元だけを畳み込むと、コメント権限だけを剥奪された
+ * 同一ユーザーが剥奪前のキャッシュバケットを共有し続け、TTL の間コメント本文入りの詳細を
+ * 受け取り続ける (キーが変わらないため無効化も走らない)。
+ *
+ * 両次元が一致する既定形 (コメント次元が `read` に従う) では**本文のみのダイジェストと同一値**を
+ * 返す。既存配備のキャッシュキーは 1 文字も変わらず、キャッシュ再利用率は無退行となる。
+ * 次元が分かれるときだけ `d:` 名前空間の下へ**長さ接頭辞付きで連結**するため、写像は単射であり
+ * sentinel (`all` / `none`) や単一次元表記 (`s:` / `sh:`) と衝突しない。
+ *
  * @param scope Viewer scope. 閲覧範囲。
  * @returns Digest usable as a cache-key component. キャッシュキー構成要素として使えるダイジェスト。
  */
@@ -2254,4 +2322,4 @@ declare function createDailyReportServer(config: DailyReportServerConfig): {
     knownSourceTypes: readonly string[];
 };
 
-export { type AuthzResourceItem, type DailyReportAttachmentBytes, type DailyReportAttachmentError, type DailyReportAttachmentFailure, type DailyReportAttachmentTable, type DailyReportAuthResult, type DailyReportAuthenticate, type DailyReportCommentRow, type DailyReportCommentTable, type DailyReportDb, type DailyReportEncodeUserId, type DailyReportExternalSource, type DailyReportHandlersConfig, type DailyReportHubLabelTable, type DailyReportHubRow, type DailyReportHubTable, type DailyReportIdCodec, type DailyReportInternalRow, type DailyReportInternalTable, type DailyReportLabelTable, type DailyReportReadAttachment, type DailyReportRedisBlockingClient, type DailyReportRedisClient, type DailyReportRedisProvider, type DailyReportResolveUserId, type DailyReportResolveVisibleSourceTypes, type DailyReportServerConfig, type DailyReportService, type DailyReportServiceConfig, type DailyReportSourceTypeInput, DailyReportSseReader, type DailyReportSseReaderConfig, type DailyReportTables, type DailyReportUserStatusRow, type DailyReportUserStatusTable, type DailyReportUserTable, DailyReportViewerScope, type DailyReportVisibilityResolveContext, type DailyReportVisibilityResolveReason, type DailyReportVisibleSourceTypes, type EpochStore, type ExternalReportFields, type RedisStreamMessage, SqlResultCache, type SqlResultCacheQueryOptions, type StreamEntry, type VisibleSourceTypeSet, asciiFallbackFileName, buildVisibleSourceTypeCondition, computeSourceTypeDigest, computeViewerScopeDigest, createDailyReportHandlers, createDailyReportServer, createDailyReportService, createEpochStore, defineDailyReportAuthzResources, defineDailyReportSchema, deniesEverySourceType, encodeRfc8187, formatDateValue, generateETag, isSourceTypeVisible, isStreamIdLte, jsonResponseWithETag, normalizeVisibleSourceTypes, sanitizeMediaType, seedDailyReportAuthzResources, transformJsonArray };
+export { type AuthzResourceItem, type DailyReportAttachmentBytes, type DailyReportAttachmentError, type DailyReportAttachmentFailure, type DailyReportAttachmentTable, type DailyReportAuthResult, type DailyReportAuthenticate, type DailyReportCommentRow, type DailyReportCommentTable, type DailyReportDb, type DailyReportEncodeUserId, type DailyReportExternalSource, type DailyReportHandlersConfig, type DailyReportHubLabelTable, type DailyReportHubRow, type DailyReportHubTable, type DailyReportIdCodec, type DailyReportInternalRow, type DailyReportInternalTable, type DailyReportLabelTable, type DailyReportReadAttachment, type DailyReportRedisBlockingClient, type DailyReportRedisClient, type DailyReportRedisProvider, type DailyReportResolveUserId, type DailyReportResolveVisibleSourceTypes, type DailyReportServerConfig, type DailyReportService, type DailyReportServiceConfig, type DailyReportSourceTypeInput, DailyReportSseReader, type DailyReportSseReaderConfig, type DailyReportTables, type DailyReportUserStatusRow, type DailyReportUserStatusTable, type DailyReportUserTable, DailyReportViewerScope, type DailyReportVisibilityDimensions, type DailyReportVisibilityResolveContext, type DailyReportVisibilityResolveReason, type DailyReportVisibleSourceTypes, type EpochStore, type ExternalReportFields, type RedisStreamMessage, SqlResultCache, type SqlResultCacheQueryOptions, type StreamEntry, type VisibleSourceTypeSet, asciiFallbackFileName, buildVisibleSourceTypeCondition, computeSourceTypeDigest, computeViewerScopeDigest, createDailyReportHandlers, createDailyReportServer, createDailyReportService, createEpochStore, defineDailyReportAuthzResources, defineDailyReportSchema, deniesEverySourceType, encodeRfc8187, formatDateValue, generateETag, isSourceTypeVisible, isStreamIdLte, jsonResponseWithETag, normalizeVisibleSourceTypes, sanitizeMediaType, seedDailyReportAuthzResources, transformJsonArray };