How Thegram Vault Stores and Shares .gram Documents

이 상세 자료는 아직 한국어로 번역되지 않아 영문 원문을 표시합니다.

GA 공개 출처와 지원 범위

Status: GA
Component: Thegram Vault
Deployment: Cloud service https://vault.thegram.one/
Applies to version: Latest
출처 확인일: 2026-10-25
Owner: thegram-one/thegram-vault
Public evidence: thegram.one/llms.txt
thegram.one/agent-memory/
Basis: The public product pages direct users and agents to the account-backed Vault and Cloud MCP; no Vault service version is stated.

출처 확인은 실제 계정 설치·기기 동작·서비스 상태의 검증을 뜻하지 않습니다.

Thegram Vault is best understood as a file authority rather than a general-purpose database. Its service authenticates people, authorizes access to shared vaults, validates complete .gram documents, and preserves accepted bytes behind versioned file heads. The native format remains the source of truth; the service adds collaboration, access policy and storage. This division matters: a cloud storage API does not automatically provide every feature of a desktop renderer or local agent.

Request identity is not authorization

A client first establishes identity. The web application uses a hosted sign-in flow; native desktop clients use authorization code with PKCE and present an API access token. The service can also use direct mutual TLS when it terminates TLS itself. Identity middleware resolves the caller, then each requested vault read or write evaluates membership in that vault. Authentication alone does not grant file access. Cookie-authenticated writes to /v1/ require the session CSRF token; bearer-authenticated requests use bearer credentials instead.

A vault has an owner and may have administrators, editors and viewers. Owners control policy and all content. Administrators can manage editor/viewer access and write files; editors can read and write; viewers can read. Unknown and unauthorized vaults are intentionally indistinguishable to callers. A server-side allowlist can restrict who creates a vault, but it is distinct from membership in an existing vault. This layered policy narrows accidental disclosure while preserving a simple collaboration model.

A write is an audited compare-and-swap

Creating a file uses If-None-Match: *; updating it uses the current If-Match generation-and-hash ETag. A client may send an idempotency key so a repeated request can be recognized. Before publishing a new head, the service invokes the pinned Gram Core binary in full-audit mode. Core parses and audits the complete journal, projects the current document and rejects invalid input. A timeout or unavailable validator is a failure, not a successful save. This makes validity an explicit write boundary rather than a best-effort background check.

The service stores accepted bytes without rewriting or normalizing the .gram source. Each accepted update creates a new generation, a retained history entry and a hash-chained audit-log entry. These are related but different records: history preserves prior document versions, while the audit log chains service actions. A conditional request prevents two people editing the same old revision from silently overwriting one another. If a stale update fails, reload the new head, inspect concurrent changes and make a fresh intentional patch. Deletion uses a tombstone head so version history and conflict detection remain coherent.

Drive is a separate storage path

Google Drive authorization is an explicit connection, not an automatic consequence of signing in with Google. The drive.file scope limits visibility to files the app created or that the person opened with it; it is not unrestricted Drive access. A vault owner can instead link a company account or Shared Drive for members acting through vault roles. Cloud-vault files and Drive-backed files are different destinations; an access denial is not a cue to copy the document elsewhere.

Drive updates use the file head revision as a best-effort precondition. Drive does not provide an atomic conditional update here, so another writer can race after the revision is checked. Treat this as weaker concurrency protection than the vault service’s generation-and-hash compare-and-swap. Check the returned synchronization state before saying the Drive write is complete. Operational backups are a third path: nightly local archives are verified before rotation, and optional off-site archives are encrypted before upload. Backup key custody and restore testing remain operational responsibilities, not automatic properties of document history.

A practical conflict example

Suppose a team shares an architecture decision. A maintainer reads its ETag, makes a focused change and submits it conditionally. A teammate publishes a newer version first, so the stale write fails. The maintainer rereads the head, compares the changed passage, reapplies only the still-valid change and submits against the new ETag. This adds a reconciliation step, but avoids silently replacing a colleague’s update. A viewer can inspect the document but cannot mutate it.

The same principle applies to product boundaries. The cloud plugin’s contract describes its own tools and mount behavior; it does not imply that a local project hook, desktop-only visualization or arbitrary app feature runs on the server. Check the active client’s capabilities rather than inferring them from the stored file.

Source and renderer evidence

Canonical source SHA-256: be19a1e1c7948a9e2af6dc0feee274979c22e4de7f7a3e1b5f7aad869bea6e44
Selected revision: r1 · sha256:a7b58f192d6f8d95cf331bcc97d45b9942cf361834212b6dfc77b3277f3a098d
Local renderer: configured local Thegram renderer · API thegram-web-render/1
Core source: git+https://github.com/clab-one/thegram-format.git?rev=b16489e1d0d77d38f82d2f61776524737aa31557#b16489e1d0d77d38f82d2f61776524737aa31557

Canonical source: vault-architecture.gram

안내와 다른 점이 있나요? 문서 오류 신고 · 문제 해결
이메일은 직접 검토해 전송하세요. API key나 비공개 문서 내용은 보내지 마세요.