共通（Common）
すべてのドメインが共有する横断的なプリミティブ — 設定可能な企業／ドメインプロファイル、決定的な機密度分類、ディメンション用語集、プライバシーに配慮した可観測性、そしてグローバルパス定数。
common ドメインは、他のすべてのドメインが依存する横断的なプリミティブを保持します： 設定可能な企業／ドメインプロファイル（特定の企業が決してハードコードされないように）、 決定的な機密度モデル、ディメンション用語集、プライバシーに配慮した可観測性、 そしてグローバルパスの唯一の信頼できる情報源です。これらはシステムの他の部分への依存を 一切持たず、import グラフの土台となっています。
パッケージ: src/ragspine/common/。契約: src/ragspine/common/CLAUDE.md。
レイアウト
企業／ドメインプロファイル
company_profile.py は、RAGSpine をハードコードされた財務アプリではなく、汎用的な
経営コパイロットにするための仕組みです。アイデンティティ、同義語、ディメンション、
競合他社リストはすべて TOML ファイル（config/company.toml）から読み込まれます。
ファイルが存在しない場合は、組み込みの ACME デフォルトに黙ってフォールバックします。
プロファイルはイミュータブルな frozen dataclass です。CompanyProfile は同じ
DomainProfile クラスに対するモジュールレベルのエイリアスであり、isinstance
チェックでもコンストラクタでも、どちらの名前も使えます。
プロパティ
型
宣言される各ディメンションはイミュータブルな DimensionSpec です（ADR 0004）：name、
label、kind（categorical / temporal / measure）、synonyms、units、labels、
default、required、clarify（ask_first / assume / none）、identity、expand、
derived_from / derivation、および捏造防止ホワイトリストのフラグ。デフォルトの
プロファイルは 5 つのディメンションを宣言します — metric、entity、period（temporal）、
channel（デフォルト TOTAL、非展開）、geography（identity=False、entity から導出）。
from ragspine.common.company_profile import load_company_profile
profile = load_company_profile() # explicit path > $RAGSPINE_COMPANY_CONFIG > config/company.toml
print(profile.home_entity_code) # 'ACME_GROUP' by defaultload_company_profile(path=None) は設定パスを解決し（明示的な引数 →
RAGSPINE_COMPANY_CONFIG 環境変数 → config/company.toml）、tomllib/tomli で
パースします。ファイルが存在しない、あるいはパースできない場合は組み込みのデフォルトに
フォールバックし、例外を送出することも、何かを出力することも決してありません。
設定駆動であり、企業のハードコードは禁止。 アイデンティティ、指標、競合他社はプロファイル
から供給されます。external_entities マップ（競合他社のエイリアス → 表示名）は、エージェントが
スコープ外の競合他社に関する質問を認識するための仕組みです。どこにも特定の企業をハードコード
しないでください。
機密度
sensitivity.py は決定的なデータ分類レイヤーであり、ナラティブ取り込み
パスで適用され、下流の RESTRICTED 分離 が
これに依存します。レベルは単純な文字列であり、enum は存在しません。唯一の名前付き定数は
RESTRICTED = "RESTRICTED" で、マークされていない場合のデフォルトは "INTERNAL" です。
ルールはイミュータブルな SensitivityPolicy に保持されます（[sensitivity] 設定
セクションから読み込まれ、企業固有の単語はハードコードされません）：
プロパティ
型
classify_sensitivity(filename, text, policy) -> str は純粋関数（外部呼び出しゼロ）で、
以下の優先順位で最初にマッチしたレベルを返します：
restricted_filename_patterns のエントリにマッチ → RESTRICTEDrestricted_keywords のエントリにマッチ → RESTRICTEDescalate_unknown_to_restricted が True → RESTRICTEDpolicy.default_level を返す（デフォルト "INTERNAL"）セキュリティ上の立場：マークされていないドキュメントはデフォルトで INTERNAL となり、
シグナルにヒットすると RESTRICTED にエスカレートします。「不明なものすべて → RESTRICTED」
という一括の挙動はオプトインの厳格スイッチであり、デフォルトではオフです。
用語集
glossary.py は自由形式のディメンション同義語を管理されたコードへと正規化します。
クラスは存在せず、モジュールレベルの関数と、読み込まれたプロファイルから導出された
辞書で構成されます。認識できない入力には None を返し、決して推測しません。
| 関数 | マッピング内容 |
|---|---|
normalize_metric(raw) -> str | None | 指標の同義語 → metric_code |
normalize_entity(raw) -> str | None | エンティティの同義語 → entity_code |
resolve_external_entity(text) -> str | None | 競合他社への言及 → 表示名（最長一致） |
geography_for_entity(entity_code) -> str | None | エンティティのデフォルト地域 |
unit_for_metric(metric_code) -> str | None | 指標のデフォルト単位 |
normalize_period(raw) -> tuple[str, str] | None | 絶対期間 → (period_type, period) |
resolve_relative_period(raw, reference_date=None) -> tuple[str, str] | None | 相対期間（今年/去年/上季度…）→ (period_type, period) |
期間の正規化は、ファクトストアで使われるものと
同じ period_type 値を生成します：FY（FY2024 / 2024）、HY（2024H1）、
QUARTER（2025Q1）。
from ragspine.common.glossary import normalize_metric, normalize_period
normalize_metric("营收") # 'REVENUE'
normalize_period("FY 2024") # ('FY', '2024')
normalize_metric("not a metric") # None — never guesses可観測性
observability.py は 2 つの小さなプリミティブです：
new_request_id() -> str— 12 文字のuuid416 進ショートコード。emit_trace(logger=None, **fields) -> None— 固定メッセージ"trace"で 1 件の INFO レコードをログし、extra=を介して**fieldsをログレコードに添付します。stdlib のloggingのみを使用し（basicConfigは呼びません）、ハンドラーの設定はホストまたは テストが行います。ロガー名はTRACE_LOGGER_NAME = "ragspine.trace"です。
プライバシーに配慮したトレース。 ログは Restricted として扱われます。emit_trace が
運ぶのは機密でないメタデータのみです — request_id、ルート、管理されたコード（metric / entity /
period / channel）、ステータスカウント、スコア、boolean フラグ、所要時間、トークン使用量 —
そして生の回答テキスト、ファクト値、チャンクテキストは決して含めません。
Core — グローバル定数
core.py はパスの唯一の信頼できる情報源であり、__file__ から導出されます（cwd や
rootutils への依存はなく、import 時の副作用はゼロです）：
| 定数 | 値 |
|---|---|
REPO_ROOT | リポジトリルート（Path(__file__).parents[3] から導出） |
DATA_DIR | REPO_ROOT / "data" |
DEFAULT_FACT_DB | data/fact_metric.db — ファクトテーブルおよびナラティブチャンクテーブル（同一の sqlite） |
DEFAULT_MAPPING_DB | data/color_mapping.db — カラーマッピングレジストリ |
DEFAULT_REVIEW_QUEUE_DB | data/review_queue.db — SME レビューキュー |
このドメインが守る不変条件
- 設定駆動 — アイデンティティ／指標／競合他社は
CompanyProfileから供給されます。 特定の企業を決してハードコードしません。 - プライバシーに配慮したトレース —
observabilityが記録するのはコード／カウント／ 所要時間のみで、回答、ファクト値、チャンクテキストは決して記録しません。 - 決定的で、決して推測しない正規化 — 用語集と機密度分類器は純粋関数であり、
認識できない入力には
None／デフォルトレベルを返します。