How Thegram Vault Stores and Shares .gram Documents

@gram 2
doc blog-vault-architecture
t How Thegram Vault Stores and Shares .gram Documents
d Explore Vault identity, permissions, validation, conditional writes, Drive boundaries and recovery without confusing service behavior with the .gram format.
tag architecture
view document
::rich
# How Thegram Vault Stores and Shares .gram Documents

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.

## Further reading

The Vault implementation and deployment sources were reviewed at revision a193a19, and the format contract at 625edec; those internal repositories are not publicly available. The public cloud plugin source provides a separate client-side boundary. Use the source revisions and file paths recorded below as research provenance, not as public links.

[[src-vault-readme]]
[[src-vault-spec]]
[[src-vault-source]]
[[src-format-source]]
[[src-plugin-source]]
[[knowledge-vault-write]]
[[knowledge-vault-drive]]
[[knowledge-vault-scope]]
::end
SRC src-vault-readme
t Thegram Vault service README
d Internal service overview, authentication, storage and configuration inspected at revision a193a19; not publicly available.
SRC src-vault-spec
t Vault service implementation contract
d Internal routes, identity, roles, write, audit and Drive details inspected at revision a193a19; not publicly available.
SRC src-vault-source
t Vault source review provenance
d README.md, docs/SPEC.md and docs/VAULT_SERVICE_DESIGN.md were inspected at revision a193a19 on 2026-10-12; internal source, no public link.
SRC src-format-source
t Thegram format implementation
d Internal Core architecture and persistent format contract inspected at revision 625edec; not publicly available.
SRC src-plugin-source
t Public cloud MCP boundaries
d Cloud client storage and feature boundaries at public plugin revision 1f92e8a.
ref https://github.com/clab-one/thegram-plugin/tree/1f92e8a
K knowledge-vault-write
t Validate and conditionally publish
d Core full-audits the document before publication; clients should reconcile rather than replay stale writes.
source src-vault-spec
K knowledge-vault-drive
t Drive concurrency is best-effort
d Updates use a Drive file-head revision precondition, but there is no atomic conditional update; drive.file is limited to app-created or user-opened files.
source src-vault-spec
K knowledge-vault-scope
t Keep format and service boundaries separate
d Vault service capabilities do not imply local renderer or client-plugin features.
source src-plugin-source