文書とバージョン
文書は単一 API のホスト表現です。組織内のプロジェクトに属し、上書きではなく時間とともにバージョンを蓄積します。
階層
Organization -> Project -> Document -> Versions
文書は組織直下かプロジェクト内に作成でき、プロジェクトと組織ごとに列挙されます。
状態ライフサイクル
文書は 4 状態を経ます。
| 状態 | 意味 | 公開サービス |
|---|---|---|
ACTIVE | オンライン | ドキュメントと MCP 提供（各有効マーカーに従う） |
PAUSED | 一時停止 | 公開サービス利用不可 |
ARCHIVED | 保持するが現行でない | 提供しない |
DELETED | ソフト削除 | 提供しない |
許可される遷移は:
pause: ACTIVE -> PAUSED
resume: PAUSED -> ACTIVE
archive: ACTIVE / PAUSED -> ARCHIVED
restore: ARCHIVED -> ACTIVE
delete: ACTIVE / PAUSED / ARCHIVED -> DELETED
一時停止は文書を落として再開する最速の方法で、アーカイブは履歴は保つが現行として扱いません。削除はソフト削除で、コアデータが即破棄されません。
バージョンは不変
仕様が変わると新バージョンを作ります。元内容は決して置換されません。
v1 -> v2 -> v3 -> v4
各バージョンは記録します。
- ファイルのオブジェクトストレージ内ストレージキー。
- SHA-256 チェックサム。
- コンテンツタイプ、サイズ、作成時刻。
これは履歴、ロールバック、比較、特定バージョンに対するドキュメント/MCP 再生成を支えます。
現在リンクとバージョン固定リンク
- 現在文書を指すリンクは最新版に追従。
- バージョン固定リンクは特定版を参照し、読者の足下で変わらない。
リリースノートや契約で不変参照が欲しいときは固定リンク、常に最新が欲しいときは現在リンクを使います。
ソース
文書内容はあるソースから来て、アップロードと Git が文書モデルにハードコードされないよう抽象化されています。
- Upload——ファイルを直接追加。
- Git——URL、ブランチ、ファイルパスでリポジトリを接続。
Git ソースは同期有効かと最終同期時刻を追跡します。
- リポジトリ URL とファイルパス必須で接続（ブランチは任意）。
- オンデマンドで同期し、最新内容を新バージョンとして取り込む。
ソースメタデータは文書とともに保持されるため、アップロードかリポジトリかを常に判断でき、最終同期を確認できます。
ストレージ
実ファイルは組織/文書/バージョンの配置でオブジェクトストレージにあり、データベースはメタデータ（ストレージキー、チェックサム、コンテンツタイプ、サイズ）だけを持ちます。ファイルはストレージから既定で公開読み取り不可で、公開アクセスは文書の発行ルートを通ります。
なぜ重要か
不変バージョンとソフト削除ライフサイクルの組み合わせで、履歴を失わず速く反復でき、止めたかった文書を 誤って公開しません。一時的に落とすなら一時停止、長期保存ならアーカイブ、安定性が重要ならリンク固定です。