@aiquants/daily-report 0.13.0 → 0.14.1

package/README.md

@@ -151,6 +151,9 @@ createDailyReportServer({
 - **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.
 - **Matching** is case-insensitive on both the JS and SQL sides (both fold to lower case), so it does not depend on the database collation. Surrounding whitespace is trimmed from the *tokens you return* but never from the stored column value — the two sides fold identically, and a padded stored value is simply invisible (fail-closed) rather than visible on one path and hidden on the other.
 - **Where it applies**: the SQL predicate is injected in the service layer, so it holds for every delivery path (including attachment bytes) rather than only the HTTP handlers. It also gates the mutations that act on someone else's report (`addComment`, `deleteComment`, star, read); a hidden report is reported as `404`, never `403`.
+- **How it reaches the service**: the resolved set is wrapped in a `DailyReportViewerScope` and passed as the **first** argument of every gated service method.
+  The class is nominal (it holds a private field), so `{ visible: null }`, `{ ...scope, visible: null }` and `new DailyReportViewerScope(...)` are all type errors — the only ways to obtain one are `DailyReportViewerScope.restrictTo(tokens)` — which accepts `readonly string[]` only, so it cannot be handed a nullish value and quietly widen — and `DailyReportViewerScope.unrestricted(auditReason)`.
+  Because a bare `null` is not spellable as a visibility value, `grep -rn "DailyReportViewerScope.unrestricted("` enumerates every unfiltered read in a codebase, each carrying a written reason.
 - **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.
 

package/dist/server.d.mts

@@ -1610,14 +1610,75 @@ declare function deniesEverySourceType(set: VisibleSourceTypeSet): boolean;
  */
 declare function buildVisibleSourceTypeCondition(sourceTypeColumn: AnyMsSqlColumn, set: VisibleSourceTypeSet): SQL | undefined;
 /**
- * Computes a stable, bounded, collision-free cache-key digest of the set.
- * 可視集合から安定・有界・衝突不能なキャッシュキー用ダイジェストを算出する処理。
+ * Request-scoped viewer scope carrying the normalized visible source-type set.
+ * 正規化済みの可視 sourceType 集合を運ぶ、リクエストスコープの閲覧範囲。
  *
- * 無制限は `"all"`、空集合は `"none"`、それ以外は**畳み込み済みトークンを昇順にそのまま連結**する。
- * 生連結のため、論理的に等価な集合は必ず同一の、論理的に異なる集合は必ず別のダイジェストになる
- * (ハッシュ衝突で別権限のキャッシュ行を配信する事故が原理的に起きない)。権限が安定している間は
- * キーが不変になるため、キャッシュは完全に再利用される (性能無退行)。
- * 区分数が異常に多い場合だけキー長を抑えるため FNV-1a 32bit へ退避し、`h:` 接頭辞で生連結と区別する。
+ * このクラスは private フィールドを持つことで**名目型**になっており、`{ visible: null }` のような
+ * 構造的偽造も、`{ ...scope, visible: null }` のようなスプレッドによる widening も型が拒否する
+ * (`unique symbol` ブランドでは後者を防げないことを実測で確認済み)。
+ *
+ * 生成経路は {@link DailyReportViewerScope.restrictTo} と {@link DailyReportViewerScope.unrestricted}
+ * の 2 つだけであり、`null` を「可視性」としてそのまま綴ることはできない。結果として、
+ * **絞り込まれない読み取りは必ず `unrestricted(理由)` として現れる**ため、
+ * `grep -rn "DailyReportViewerScope.unrestricted("` が fail-open の全数リストになる。
+ */
+declare class DailyReportViewerScope {
+    #private;
+    private constructor();
+    /** 正規化済みの可視集合。`null` は無制限、空集合は 0 件 (fail-close)。 */
+    get visible(): VisibleSourceTypeSet;
+    /**
+     * Builds a scope restricted to the given source types (empty input = zero rows).
+     * 指定した sourceType へ限定した閲覧範囲を生成する処理 (空入力は 0 件)。
+     *
+     * 入力は {@link normalizeVisibleSourceTypes} を通るため、大小文字・前後空白・重複・非文字列は
+     * ここで吸収される。
+     *
+     * ❗ 引数は `readonly string[]` に**狭めてある**。`null` / `undefined` を受け付けると、
+     * 「restrict」という名前のまま無制限スコープを生む第 2 の入口になり、
+     * 「絞り込まれない読み取りは必ず {@link DailyReportViewerScope.unrestricted} に現れる」
+     * という監査不変条件が崩れる。無制限は必ず理由付きで明示すること。
+     *
+     * @param sourceTypes Visible source-type tokens. 可視 sourceType のトークン群。
+     * @returns The scope. 生成した閲覧範囲。
+     */
+    static restrictTo(sourceTypes: readonly string[]): DailyReportViewerScope;
+    /**
+     * Builds an unrestricted scope; every call site is an audited fail-open.
+     * 無制限の閲覧範囲を生成する処理。全呼び出し箇所が監査対象の fail-open となる。
+     *
+     * ❗ 理由文字列は必須。読み捨てるが、呼び出し箇所の全数列挙と「なぜここは絞らなくてよいか」の
+     * 記録を強制するために受け取る。
+     *
+     * @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.
+ * 閲覧範囲全体からキャッシュキー用ダイジェストを算出する処理。
+ *
+ * スコープに次元が増えてもキャッシュキーの生成点を 1 つに保つための入口。
+ *
+ * @param scope Viewer scope. 閲覧範囲。
+ * @returns Digest usable as a cache-key component. キャッシュキー構成要素として使えるダイジェスト。
+ */
+declare function computeViewerScopeDigest(scope: DailyReportViewerScope): string;
+/**
+ * Computes a stable and bounded cache-key digest of the set.
+ * 可視集合から安定・有界なキャッシュキー用ダイジェストを算出する処理。
+ *
+ * 無制限は `"all"`、空集合は `"none"`、それ以外は `s:` 名前空間の下へ**長さ接頭辞付きトークンを昇順連結**する。
+ * 連結は長さ接頭辞付きなので**単射**であり、通常経路 (`s:`) では論理的に等価な集合が必ず同一の、
+ * 異なる集合が必ず別のダイジェストになる。sentinel (`all` / `none`) とも名前空間が分かれるため、
+ * 限定集合が無制限 / 全拒否と同じバケットを共有することはない。権限が安定している間はキーが
+ * 不変になるため、キャッシュは完全に再利用される (性能無退行)。
+ *
+ * ❗ 区分数が異常に多い場合だけキー長を抑えるため FNV-1a 32bit へ退避し `sh:` 接頭辞を付ける。
+ * **この退避経路に限り理論上の衝突がありうる** (32bit)。衝突しても影響は同一ユーザーの
+ * キャッシュ再利用に留まり、認可判定そのものは SQL 述語が担うため漏洩には至らない。
+ * 通常の区分数 (数個) では到達しない。
  *
  * @param set Normalized visible set. 正規化済みの可視集合。
  * @returns Digest usable as a cache-key component. キャッシュキー構成要素として使えるダイジェスト。
@@ -1782,15 +1843,15 @@ declare function createDailyReportService(config: DailyReportServiceConfig): {
     clearCache: () => Promise<void>;
     invalidateHubReadCaches: (hubIds: readonly number[], businessDates: readonly string[]) => Promise<void>;
     getUserIdByExternalId: (externalId: string) => Promise<number | null>;
-    getDailyReportIdsByExternalId: (externalId: string, { forceRefresh, snapshot, ttlMsOverride }: SqlResultCacheQueryOptions | undefined, visible: VisibleSourceTypeSet) => Promise<DailyReportItem[]>;
-    getDailyReportIdsFirstPageByExternalId: (externalId: string, limit: number, visible: VisibleSourceTypeSet) => Promise<DailyReportItem[]>;
-    getDailyReportsByBusinessDate: (businessDate: string, { forceRefresh, snapshot, ttlMsOverride }?: SqlResultCacheQueryOptions) => Promise<DailyReportDetail[]>;
-    getDailyReportsByBusinessDateByExternalId: (businessDate: string, externalId: string, { forceRefresh, snapshot, ttlMsOverride }: SqlResultCacheQueryOptions | undefined, visible: VisibleSourceTypeSet) => Promise<DailyReportDetail[]>;
-    getDailyReportDetailById: (reportHubId: number, userId: number, { forceRefresh, snapshot, ttlMsOverride }: SqlResultCacheQueryOptions | undefined, visible: VisibleSourceTypeSet) => Promise<DailyReportDetail | null>;
-    getDailyReportDetailByIdByExternalId: (reportHubId: number, externalId: string, options: SqlResultCacheQueryOptions | undefined, visible: VisibleSourceTypeSet) => Promise<DailyReportDetail | null>;
+    getDailyReportIdsByExternalId: (scope: DailyReportViewerScope, externalId: string, { forceRefresh, snapshot, ttlMsOverride }?: SqlResultCacheQueryOptions) => Promise<DailyReportItem[]>;
+    getDailyReportIdsFirstPageByExternalId: (scope: DailyReportViewerScope, externalId: string, limit: number) => Promise<DailyReportItem[]>;
+    getDailyReportsByBusinessDate: (scope: DailyReportViewerScope, businessDate: string, { forceRefresh, snapshot, ttlMsOverride }?: SqlResultCacheQueryOptions) => Promise<DailyReportDetail[]>;
+    getDailyReportsByBusinessDateByExternalId: (scope: DailyReportViewerScope, businessDate: string, externalId: string, { forceRefresh, snapshot, ttlMsOverride }?: SqlResultCacheQueryOptions) => Promise<DailyReportDetail[]>;
+    getDailyReportDetailById: (scope: DailyReportViewerScope, reportHubId: number, userId: number, { forceRefresh, snapshot, ttlMsOverride }?: SqlResultCacheQueryOptions) => Promise<DailyReportDetail | null>;
+    getDailyReportDetailByIdByExternalId: (scope: DailyReportViewerScope, reportHubId: number, externalId: string, options?: SqlResultCacheQueryOptions) => Promise<DailyReportDetail | null>;
     getDraftLabelId: () => Promise<number | null>;
     getAttachmentsByHubIds: (hubIds: number[]) => Promise<Map<number, DailyReportAttachmentSummary[]>>;
-    getAttachmentForUser: (attachmentId: number, userId: number, visible: VisibleSourceTypeSet) => Promise<{
+    getAttachmentForUser: (scope: DailyReportViewerScope, attachmentId: number, userId: number) => Promise<{
         fileName: string;
         filePath: string;
         fileType: string | null;
@@ -1798,10 +1859,10 @@ declare function createDailyReportService(config: DailyReportServiceConfig): {
     } | null>;
     markAttachmentMissing: (attachmentId: number) => Promise<void>;
     markAttachmentPresent: (attachmentId: number) => Promise<void>;
-    setStarStatus: (userId: number, reportHubId: number, businessDate: string | null, isStarred: boolean, clientTempId: string, visible: VisibleSourceTypeSet) => Promise<DailyReportUserStatusRow>;
-    setReadStatus: (userId: number, reportHubId: number, businessDate: string | null, isRead: boolean, clientTempId: string, visible: VisibleSourceTypeSet) => Promise<DailyReportUserStatusRow>;
-    addComment: (userId: number, reportHubId: number, content: string, businessDate: string | null, clientTempId: string, visible: VisibleSourceTypeSet) => Promise<DailyReportCommentItem>;
-    deleteComment: (userId: number, reportHubId: number, commentId: number, businessDate: string | null, clientTempId: string, visible: VisibleSourceTypeSet) => Promise<void>;
+    setStarStatus: (scope: DailyReportViewerScope, userId: number, reportHubId: number, businessDate: string | null, isStarred: boolean, clientTempId: string) => Promise<DailyReportUserStatusRow>;
+    setReadStatus: (scope: DailyReportViewerScope, userId: number, reportHubId: number, businessDate: string | null, isRead: boolean, clientTempId: string) => Promise<DailyReportUserStatusRow>;
+    addComment: (scope: DailyReportViewerScope, userId: number, reportHubId: number, content: string, businessDate: string | null, clientTempId: string) => Promise<DailyReportCommentItem>;
+    deleteComment: (scope: DailyReportViewerScope, userId: number, reportHubId: number, commentId: number, businessDate: string | null, clientTempId: string) => Promise<void>;
     createDailyReport: (userId: number, businessDate: string, clientTempId: string) => Promise<DailyReportDetail>;
     updateDailyReport: (reportHubId: number, userId: number, data: {
         title?: string;
@@ -2141,15 +2202,15 @@ declare function createDailyReportServer(config: DailyReportServerConfig): {
         clearCache: () => Promise<void>;
         invalidateHubReadCaches: (hubIds: readonly number[], businessDates: readonly string[]) => Promise<void>;
         getUserIdByExternalId: (externalId: string) => Promise<number | null>;
-        getDailyReportIdsByExternalId: (externalId: string, { forceRefresh, snapshot, ttlMsOverride }: SqlResultCacheQueryOptions | undefined, visible: VisibleSourceTypeSet) => Promise<DailyReportItem[]>;
-        getDailyReportIdsFirstPageByExternalId: (externalId: string, limit: number, visible: VisibleSourceTypeSet) => Promise<DailyReportItem[]>;
-        getDailyReportsByBusinessDate: (businessDate: string, { forceRefresh, snapshot, ttlMsOverride }?: SqlResultCacheQueryOptions) => Promise<DailyReportDetail[]>;
-        getDailyReportsByBusinessDateByExternalId: (businessDate: string, externalId: string, { forceRefresh, snapshot, ttlMsOverride }: SqlResultCacheQueryOptions | undefined, visible: VisibleSourceTypeSet) => Promise<DailyReportDetail[]>;
-        getDailyReportDetailById: (reportHubId: number, userId: number, { forceRefresh, snapshot, ttlMsOverride }: SqlResultCacheQueryOptions | undefined, visible: VisibleSourceTypeSet) => Promise<DailyReportDetail | null>;
-        getDailyReportDetailByIdByExternalId: (reportHubId: number, externalId: string, options: SqlResultCacheQueryOptions | undefined, visible: VisibleSourceTypeSet) => Promise<DailyReportDetail | null>;
+        getDailyReportIdsByExternalId: (scope: DailyReportViewerScope, externalId: string, { forceRefresh, snapshot, ttlMsOverride }?: SqlResultCacheQueryOptions) => Promise<DailyReportItem[]>;
+        getDailyReportIdsFirstPageByExternalId: (scope: DailyReportViewerScope, externalId: string, limit: number) => Promise<DailyReportItem[]>;
+        getDailyReportsByBusinessDate: (scope: DailyReportViewerScope, businessDate: string, { forceRefresh, snapshot, ttlMsOverride }?: SqlResultCacheQueryOptions) => Promise<DailyReportDetail[]>;
+        getDailyReportsByBusinessDateByExternalId: (scope: DailyReportViewerScope, businessDate: string, externalId: string, { forceRefresh, snapshot, ttlMsOverride }?: SqlResultCacheQueryOptions) => Promise<DailyReportDetail[]>;
+        getDailyReportDetailById: (scope: DailyReportViewerScope, reportHubId: number, userId: number, { forceRefresh, snapshot, ttlMsOverride }?: SqlResultCacheQueryOptions) => Promise<DailyReportDetail | null>;
+        getDailyReportDetailByIdByExternalId: (scope: DailyReportViewerScope, reportHubId: number, externalId: string, options?: SqlResultCacheQueryOptions) => Promise<DailyReportDetail | null>;
         getDraftLabelId: () => Promise<number | null>;
         getAttachmentsByHubIds: (hubIds: number[]) => Promise<Map<number, DailyReportAttachmentSummary[]>>;
-        getAttachmentForUser: (attachmentId: number, userId: number, visible: VisibleSourceTypeSet) => Promise<{
+        getAttachmentForUser: (scope: DailyReportViewerScope, attachmentId: number, userId: number) => Promise<{
             fileName: string;
             filePath: string;
             fileType: string | null;
@@ -2157,10 +2218,10 @@ declare function createDailyReportServer(config: DailyReportServerConfig): {
         } | null>;
         markAttachmentMissing: (attachmentId: number) => Promise<void>;
         markAttachmentPresent: (attachmentId: number) => Promise<void>;
-        setStarStatus: (userId: number, reportHubId: number, businessDate: string | null, isStarred: boolean, clientTempId: string, visible: VisibleSourceTypeSet) => Promise<DailyReportUserStatusRow>;
-        setReadStatus: (userId: number, reportHubId: number, businessDate: string | null, isRead: boolean, clientTempId: string, visible: VisibleSourceTypeSet) => Promise<DailyReportUserStatusRow>;
-        addComment: (userId: number, reportHubId: number, content: string, businessDate: string | null, clientTempId: string, visible: VisibleSourceTypeSet) => Promise<DailyReportCommentItem>;
-        deleteComment: (userId: number, reportHubId: number, commentId: number, businessDate: string | null, clientTempId: string, visible: VisibleSourceTypeSet) => Promise<void>;
+        setStarStatus: (scope: DailyReportViewerScope, userId: number, reportHubId: number, businessDate: string | null, isStarred: boolean, clientTempId: string) => Promise<DailyReportUserStatusRow>;
+        setReadStatus: (scope: DailyReportViewerScope, userId: number, reportHubId: number, businessDate: string | null, isRead: boolean, clientTempId: string) => Promise<DailyReportUserStatusRow>;
+        addComment: (scope: DailyReportViewerScope, userId: number, reportHubId: number, content: string, businessDate: string | null, clientTempId: string) => Promise<DailyReportCommentItem>;
+        deleteComment: (scope: DailyReportViewerScope, userId: number, reportHubId: number, commentId: number, businessDate: string | null, clientTempId: string) => Promise<void>;
         createDailyReport: (userId: number, businessDate: string, clientTempId: string) => Promise<DailyReportDetail>;
         updateDailyReport: (reportHubId: number, userId: number, data: {
             title?: string;
@@ -2193,4 +2254,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, type DailyReportVisibilityResolveContext, type DailyReportVisibilityResolveReason, type DailyReportVisibleSourceTypes, type EpochStore, type ExternalReportFields, type RedisStreamMessage, SqlResultCache, type SqlResultCacheQueryOptions, type StreamEntry, type VisibleSourceTypeSet, asciiFallbackFileName, buildVisibleSourceTypeCondition, computeSourceTypeDigest, 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 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

@@ -1610,14 +1610,75 @@ declare function deniesEverySourceType(set: VisibleSourceTypeSet): boolean;
  */
 declare function buildVisibleSourceTypeCondition(sourceTypeColumn: AnyMsSqlColumn, set: VisibleSourceTypeSet): SQL | undefined;
 /**
- * Computes a stable, bounded, collision-free cache-key digest of the set.
- * 可視集合から安定・有界・衝突不能なキャッシュキー用ダイジェストを算出する処理。
+ * Request-scoped viewer scope carrying the normalized visible source-type set.
+ * 正規化済みの可視 sourceType 集合を運ぶ、リクエストスコープの閲覧範囲。
  *
- * 無制限は `"all"`、空集合は `"none"`、それ以外は**畳み込み済みトークンを昇順にそのまま連結**する。
- * 生連結のため、論理的に等価な集合は必ず同一の、論理的に異なる集合は必ず別のダイジェストになる
- * (ハッシュ衝突で別権限のキャッシュ行を配信する事故が原理的に起きない)。権限が安定している間は
- * キーが不変になるため、キャッシュは完全に再利用される (性能無退行)。
- * 区分数が異常に多い場合だけキー長を抑えるため FNV-1a 32bit へ退避し、`h:` 接頭辞で生連結と区別する。
+ * このクラスは private フィールドを持つことで**名目型**になっており、`{ visible: null }` のような
+ * 構造的偽造も、`{ ...scope, visible: null }` のようなスプレッドによる widening も型が拒否する
+ * (`unique symbol` ブランドでは後者を防げないことを実測で確認済み)。
+ *
+ * 生成経路は {@link DailyReportViewerScope.restrictTo} と {@link DailyReportViewerScope.unrestricted}
+ * の 2 つだけであり、`null` を「可視性」としてそのまま綴ることはできない。結果として、
+ * **絞り込まれない読み取りは必ず `unrestricted(理由)` として現れる**ため、
+ * `grep -rn "DailyReportViewerScope.unrestricted("` が fail-open の全数リストになる。
+ */
+declare class DailyReportViewerScope {
+    #private;
+    private constructor();
+    /** 正規化済みの可視集合。`null` は無制限、空集合は 0 件 (fail-close)。 */
+    get visible(): VisibleSourceTypeSet;
+    /**
+     * Builds a scope restricted to the given source types (empty input = zero rows).
+     * 指定した sourceType へ限定した閲覧範囲を生成する処理 (空入力は 0 件)。
+     *
+     * 入力は {@link normalizeVisibleSourceTypes} を通るため、大小文字・前後空白・重複・非文字列は
+     * ここで吸収される。
+     *
+     * ❗ 引数は `readonly string[]` に**狭めてある**。`null` / `undefined` を受け付けると、
+     * 「restrict」という名前のまま無制限スコープを生む第 2 の入口になり、
+     * 「絞り込まれない読み取りは必ず {@link DailyReportViewerScope.unrestricted} に現れる」
+     * という監査不変条件が崩れる。無制限は必ず理由付きで明示すること。
+     *
+     * @param sourceTypes Visible source-type tokens. 可視 sourceType のトークン群。
+     * @returns The scope. 生成した閲覧範囲。
+     */
+    static restrictTo(sourceTypes: readonly string[]): DailyReportViewerScope;
+    /**
+     * Builds an unrestricted scope; every call site is an audited fail-open.
+     * 無制限の閲覧範囲を生成する処理。全呼び出し箇所が監査対象の fail-open となる。
+     *
+     * ❗ 理由文字列は必須。読み捨てるが、呼び出し箇所の全数列挙と「なぜここは絞らなくてよいか」の
+     * 記録を強制するために受け取る。
+     *
+     * @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.
+ * 閲覧範囲全体からキャッシュキー用ダイジェストを算出する処理。
+ *
+ * スコープに次元が増えてもキャッシュキーの生成点を 1 つに保つための入口。
+ *
+ * @param scope Viewer scope. 閲覧範囲。
+ * @returns Digest usable as a cache-key component. キャッシュキー構成要素として使えるダイジェスト。
+ */
+declare function computeViewerScopeDigest(scope: DailyReportViewerScope): string;
+/**
+ * Computes a stable and bounded cache-key digest of the set.
+ * 可視集合から安定・有界なキャッシュキー用ダイジェストを算出する処理。
+ *
+ * 無制限は `"all"`、空集合は `"none"`、それ以外は `s:` 名前空間の下へ**長さ接頭辞付きトークンを昇順連結**する。
+ * 連結は長さ接頭辞付きなので**単射**であり、通常経路 (`s:`) では論理的に等価な集合が必ず同一の、
+ * 異なる集合が必ず別のダイジェストになる。sentinel (`all` / `none`) とも名前空間が分かれるため、
+ * 限定集合が無制限 / 全拒否と同じバケットを共有することはない。権限が安定している間はキーが
+ * 不変になるため、キャッシュは完全に再利用される (性能無退行)。
+ *
+ * ❗ 区分数が異常に多い場合だけキー長を抑えるため FNV-1a 32bit へ退避し `sh:` 接頭辞を付ける。
+ * **この退避経路に限り理論上の衝突がありうる** (32bit)。衝突しても影響は同一ユーザーの
+ * キャッシュ再利用に留まり、認可判定そのものは SQL 述語が担うため漏洩には至らない。
+ * 通常の区分数 (数個) では到達しない。
  *
  * @param set Normalized visible set. 正規化済みの可視集合。
  * @returns Digest usable as a cache-key component. キャッシュキー構成要素として使えるダイジェスト。
@@ -1782,15 +1843,15 @@ declare function createDailyReportService(config: DailyReportServiceConfig): {
     clearCache: () => Promise<void>;
     invalidateHubReadCaches: (hubIds: readonly number[], businessDates: readonly string[]) => Promise<void>;
     getUserIdByExternalId: (externalId: string) => Promise<number | null>;
-    getDailyReportIdsByExternalId: (externalId: string, { forceRefresh, snapshot, ttlMsOverride }: SqlResultCacheQueryOptions | undefined, visible: VisibleSourceTypeSet) => Promise<DailyReportItem[]>;
-    getDailyReportIdsFirstPageByExternalId: (externalId: string, limit: number, visible: VisibleSourceTypeSet) => Promise<DailyReportItem[]>;
-    getDailyReportsByBusinessDate: (businessDate: string, { forceRefresh, snapshot, ttlMsOverride }?: SqlResultCacheQueryOptions) => Promise<DailyReportDetail[]>;
-    getDailyReportsByBusinessDateByExternalId: (businessDate: string, externalId: string, { forceRefresh, snapshot, ttlMsOverride }: SqlResultCacheQueryOptions | undefined, visible: VisibleSourceTypeSet) => Promise<DailyReportDetail[]>;
-    getDailyReportDetailById: (reportHubId: number, userId: number, { forceRefresh, snapshot, ttlMsOverride }: SqlResultCacheQueryOptions | undefined, visible: VisibleSourceTypeSet) => Promise<DailyReportDetail | null>;
-    getDailyReportDetailByIdByExternalId: (reportHubId: number, externalId: string, options: SqlResultCacheQueryOptions | undefined, visible: VisibleSourceTypeSet) => Promise<DailyReportDetail | null>;
+    getDailyReportIdsByExternalId: (scope: DailyReportViewerScope, externalId: string, { forceRefresh, snapshot, ttlMsOverride }?: SqlResultCacheQueryOptions) => Promise<DailyReportItem[]>;
+    getDailyReportIdsFirstPageByExternalId: (scope: DailyReportViewerScope, externalId: string, limit: number) => Promise<DailyReportItem[]>;
+    getDailyReportsByBusinessDate: (scope: DailyReportViewerScope, businessDate: string, { forceRefresh, snapshot, ttlMsOverride }?: SqlResultCacheQueryOptions) => Promise<DailyReportDetail[]>;
+    getDailyReportsByBusinessDateByExternalId: (scope: DailyReportViewerScope, businessDate: string, externalId: string, { forceRefresh, snapshot, ttlMsOverride }?: SqlResultCacheQueryOptions) => Promise<DailyReportDetail[]>;
+    getDailyReportDetailById: (scope: DailyReportViewerScope, reportHubId: number, userId: number, { forceRefresh, snapshot, ttlMsOverride }?: SqlResultCacheQueryOptions) => Promise<DailyReportDetail | null>;
+    getDailyReportDetailByIdByExternalId: (scope: DailyReportViewerScope, reportHubId: number, externalId: string, options?: SqlResultCacheQueryOptions) => Promise<DailyReportDetail | null>;
     getDraftLabelId: () => Promise<number | null>;
     getAttachmentsByHubIds: (hubIds: number[]) => Promise<Map<number, DailyReportAttachmentSummary[]>>;
-    getAttachmentForUser: (attachmentId: number, userId: number, visible: VisibleSourceTypeSet) => Promise<{
+    getAttachmentForUser: (scope: DailyReportViewerScope, attachmentId: number, userId: number) => Promise<{
         fileName: string;
         filePath: string;
         fileType: string | null;
@@ -1798,10 +1859,10 @@ declare function createDailyReportService(config: DailyReportServiceConfig): {
     } | null>;
     markAttachmentMissing: (attachmentId: number) => Promise<void>;
     markAttachmentPresent: (attachmentId: number) => Promise<void>;
-    setStarStatus: (userId: number, reportHubId: number, businessDate: string | null, isStarred: boolean, clientTempId: string, visible: VisibleSourceTypeSet) => Promise<DailyReportUserStatusRow>;
-    setReadStatus: (userId: number, reportHubId: number, businessDate: string | null, isRead: boolean, clientTempId: string, visible: VisibleSourceTypeSet) => Promise<DailyReportUserStatusRow>;
-    addComment: (userId: number, reportHubId: number, content: string, businessDate: string | null, clientTempId: string, visible: VisibleSourceTypeSet) => Promise<DailyReportCommentItem>;
-    deleteComment: (userId: number, reportHubId: number, commentId: number, businessDate: string | null, clientTempId: string, visible: VisibleSourceTypeSet) => Promise<void>;
+    setStarStatus: (scope: DailyReportViewerScope, userId: number, reportHubId: number, businessDate: string | null, isStarred: boolean, clientTempId: string) => Promise<DailyReportUserStatusRow>;
+    setReadStatus: (scope: DailyReportViewerScope, userId: number, reportHubId: number, businessDate: string | null, isRead: boolean, clientTempId: string) => Promise<DailyReportUserStatusRow>;
+    addComment: (scope: DailyReportViewerScope, userId: number, reportHubId: number, content: string, businessDate: string | null, clientTempId: string) => Promise<DailyReportCommentItem>;
+    deleteComment: (scope: DailyReportViewerScope, userId: number, reportHubId: number, commentId: number, businessDate: string | null, clientTempId: string) => Promise<void>;
     createDailyReport: (userId: number, businessDate: string, clientTempId: string) => Promise<DailyReportDetail>;
     updateDailyReport: (reportHubId: number, userId: number, data: {
         title?: string;
@@ -2141,15 +2202,15 @@ declare function createDailyReportServer(config: DailyReportServerConfig): {
         clearCache: () => Promise<void>;
         invalidateHubReadCaches: (hubIds: readonly number[], businessDates: readonly string[]) => Promise<void>;
         getUserIdByExternalId: (externalId: string) => Promise<number | null>;
-        getDailyReportIdsByExternalId: (externalId: string, { forceRefresh, snapshot, ttlMsOverride }: SqlResultCacheQueryOptions | undefined, visible: VisibleSourceTypeSet) => Promise<DailyReportItem[]>;
-        getDailyReportIdsFirstPageByExternalId: (externalId: string, limit: number, visible: VisibleSourceTypeSet) => Promise<DailyReportItem[]>;
-        getDailyReportsByBusinessDate: (businessDate: string, { forceRefresh, snapshot, ttlMsOverride }?: SqlResultCacheQueryOptions) => Promise<DailyReportDetail[]>;
-        getDailyReportsByBusinessDateByExternalId: (businessDate: string, externalId: string, { forceRefresh, snapshot, ttlMsOverride }: SqlResultCacheQueryOptions | undefined, visible: VisibleSourceTypeSet) => Promise<DailyReportDetail[]>;
-        getDailyReportDetailById: (reportHubId: number, userId: number, { forceRefresh, snapshot, ttlMsOverride }: SqlResultCacheQueryOptions | undefined, visible: VisibleSourceTypeSet) => Promise<DailyReportDetail | null>;
-        getDailyReportDetailByIdByExternalId: (reportHubId: number, externalId: string, options: SqlResultCacheQueryOptions | undefined, visible: VisibleSourceTypeSet) => Promise<DailyReportDetail | null>;
+        getDailyReportIdsByExternalId: (scope: DailyReportViewerScope, externalId: string, { forceRefresh, snapshot, ttlMsOverride }?: SqlResultCacheQueryOptions) => Promise<DailyReportItem[]>;
+        getDailyReportIdsFirstPageByExternalId: (scope: DailyReportViewerScope, externalId: string, limit: number) => Promise<DailyReportItem[]>;
+        getDailyReportsByBusinessDate: (scope: DailyReportViewerScope, businessDate: string, { forceRefresh, snapshot, ttlMsOverride }?: SqlResultCacheQueryOptions) => Promise<DailyReportDetail[]>;
+        getDailyReportsByBusinessDateByExternalId: (scope: DailyReportViewerScope, businessDate: string, externalId: string, { forceRefresh, snapshot, ttlMsOverride }?: SqlResultCacheQueryOptions) => Promise<DailyReportDetail[]>;
+        getDailyReportDetailById: (scope: DailyReportViewerScope, reportHubId: number, userId: number, { forceRefresh, snapshot, ttlMsOverride }?: SqlResultCacheQueryOptions) => Promise<DailyReportDetail | null>;
+        getDailyReportDetailByIdByExternalId: (scope: DailyReportViewerScope, reportHubId: number, externalId: string, options?: SqlResultCacheQueryOptions) => Promise<DailyReportDetail | null>;
         getDraftLabelId: () => Promise<number | null>;
         getAttachmentsByHubIds: (hubIds: number[]) => Promise<Map<number, DailyReportAttachmentSummary[]>>;
-        getAttachmentForUser: (attachmentId: number, userId: number, visible: VisibleSourceTypeSet) => Promise<{
+        getAttachmentForUser: (scope: DailyReportViewerScope, attachmentId: number, userId: number) => Promise<{
             fileName: string;
             filePath: string;
             fileType: string | null;
@@ -2157,10 +2218,10 @@ declare function createDailyReportServer(config: DailyReportServerConfig): {
         } | null>;
         markAttachmentMissing: (attachmentId: number) => Promise<void>;
         markAttachmentPresent: (attachmentId: number) => Promise<void>;
-        setStarStatus: (userId: number, reportHubId: number, businessDate: string | null, isStarred: boolean, clientTempId: string, visible: VisibleSourceTypeSet) => Promise<DailyReportUserStatusRow>;
-        setReadStatus: (userId: number, reportHubId: number, businessDate: string | null, isRead: boolean, clientTempId: string, visible: VisibleSourceTypeSet) => Promise<DailyReportUserStatusRow>;
-        addComment: (userId: number, reportHubId: number, content: string, businessDate: string | null, clientTempId: string, visible: VisibleSourceTypeSet) => Promise<DailyReportCommentItem>;
-        deleteComment: (userId: number, reportHubId: number, commentId: number, businessDate: string | null, clientTempId: string, visible: VisibleSourceTypeSet) => Promise<void>;
+        setStarStatus: (scope: DailyReportViewerScope, userId: number, reportHubId: number, businessDate: string | null, isStarred: boolean, clientTempId: string) => Promise<DailyReportUserStatusRow>;
+        setReadStatus: (scope: DailyReportViewerScope, userId: number, reportHubId: number, businessDate: string | null, isRead: boolean, clientTempId: string) => Promise<DailyReportUserStatusRow>;
+        addComment: (scope: DailyReportViewerScope, userId: number, reportHubId: number, content: string, businessDate: string | null, clientTempId: string) => Promise<DailyReportCommentItem>;
+        deleteComment: (scope: DailyReportViewerScope, userId: number, reportHubId: number, commentId: number, businessDate: string | null, clientTempId: string) => Promise<void>;
         createDailyReport: (userId: number, businessDate: string, clientTempId: string) => Promise<DailyReportDetail>;
         updateDailyReport: (reportHubId: number, userId: number, data: {
             title?: string;
@@ -2193,4 +2254,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, type DailyReportVisibilityResolveContext, type DailyReportVisibilityResolveReason, type DailyReportVisibleSourceTypes, type EpochStore, type ExternalReportFields, type RedisStreamMessage, SqlResultCache, type SqlResultCacheQueryOptions, type StreamEntry, type VisibleSourceTypeSet, asciiFallbackFileName, buildVisibleSourceTypeCondition, computeSourceTypeDigest, 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 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 };