# Living Atlas

[![CI](https://github.com/ProvisioInsights/LivingAtlas/actions/workflows/ci.yml/badge.svg)](https://github.com/ProvisioInsights/LivingAtlas/actions/workflows/ci.yml)

Living Atlas is a private-first knowledge graph system for a
Logseq/Obsidian-inspired graph. It stores complete graph bytes in a Cloudflare
deployment for anywhere access, keeps sensitive plaintext available only to
local/keyholding clients, and exposes policy-scoped MCP surfaces so local tools
can see the full authorized graph while remote AI providers only see approved
remote-readable data.

## System Layers

Living Atlas has two tightly linked halves:

- **Runtime architecture:** storage, Cloudflare/local materialization,
  encryption, sync, MCP access, CRUD, audit, conflict handling, and privacy
  boundaries.
- **Knowledge semantics:** nodes, edges, predicates, events, bitemporal dates,
  relationship vocabulary, and Logseq/Obsidian migration semantics.

They are one product. If the two tracks appear to conflict, runtime/security
architecture controls where data lives and who can access it; temporal-edge
docs control what graph facts mean.

## Document Map

- [**Getting Started**](docs/getting-started.md) - **start here**: install, configure an encrypted local replica, and connect an MCP client (Claude Desktop/Code/Codex) to your graph.
- [PRD](docs/product/prd.md) - product goals, users, requirements, non-goals.
- [Architecture Requirements](docs/architecture/ard-0001-system-architecture.md) - system shape and constraints.
- [V1 Architecture Decisions](docs/architecture/v1-architecture-decisions.md) - accepted V1 runtime and privacy decisions.
- [Knowledge Schema Runtime Integration](docs/architecture/knowledge-schema-runtime-integration.md) - how temporal-edge semantics map onto the runtime/storage architecture.
- [ADR 0001](docs/architecture/adr-0001-local-first-host-blind-sync.md) - Cloudflare byte custody with local-key sensitive sync.
- [ADR 0002](docs/architecture/adr-0002-policy-scoped-mcp.md) - separate local and remote MCP authority. **Superseded by ADR 0015 and ADR 0017.**
- [ADR 0003](docs/architecture/adr-0003-append-only-crud-ledger.md) - visible, auditable CRUD history.
- [Runtime Topology Options](docs/architecture/runtime-topology-options.md) - chosen V1 topology plus alternate deployment profiles.
- [Cloudflare-First Bootstrap And Local Sync](docs/architecture/cloudflare-first-bootstrap-and-local-sync.md) - first deployment, safe authority claim, browser-keyed setup, local link, and sync.
- [Public Repo And Personal Cloudflare Deployment](docs/architecture/public-repo-personal-cloudflare-deployment.md) - public template/repo boundaries, Terraform/Wrangler split, and private personal deployment state.
- [Remote-Primary With Local Sensitive Path](docs/architecture/remote-primary-local-sensitive-federation.md) - remote MCP for normal work, local/keyholding path for sensitive plaintext, and future federation hooks.
- [Local MCP Boundary](docs/architecture/local-mcp-boundary.md) - local MCP as private authority and release producer, not a remote-call backend. **Superseded by ADR 0017.**
- [Complete Cloudflare Custody Diagram](docs/architecture/complete-cloudflare-custody-diagram.md) - Cloudflare stores the complete graph while sensitive content remains local-key-only.
- [Live Graph Activity And Audit](docs/architecture/live-graph-activity-and-audit.md) - near-live graph firing view plus repeatable CRUD audit/replay.
- [100M Scale Plan](docs/architecture/scale-plan-100m.md) - segmented storage, indexes, compaction, and sync design for large graphs.
- [Offline Sync And Conflict Resolution](docs/architecture/offline-sync-and-conflict-resolution.md) - continuous sync, offline queues, generations, and conflict handling.
- [Key Management](docs/architecture/key-management.md) - KEK/DEK hierarchy, envelopes, device enrollment, revocation, and release keys.
- [Access Modes](docs/architecture/access-modes.md) - remote-safe, cloud-unlock session, and local-keyholding security modes.
- [Identity, Configuration, And Key Control Plane](docs/architecture/identity-configuration-control-plane.md) - user/device/client setup, capability grants, key config, recovery, and admin surfaces.
- [Event Subsystems](docs/architecture/event-subsystems.md) - sync change log, durable audit ledger, and live activity stream.
- [Knowledge Contract](docs/contract/atlas-knowledge-contract-2026.08.1.md) - the published consumer tool contract: record schemas, the graph vocabulary, limits, coverage reporting, and the requirements register. The frozen prior revision is [2026.08.0](docs/contract/atlas-knowledge-contract-2026.08.0.md).
- [Metadata Leakage Budget](docs/architecture/metadata-leakage-budget.md) - Cloudflare-visible metadata and path/index constraints.
- [Compaction And Retention](docs/architecture/compaction-and-retention.md) - tombstones, snapshots, long-offline clients, and erasure.
- [Local MCP Authentication](docs/architecture/local-mcp-authentication.md) - local auth, capabilities, admin mode, and localhost threat model. **Superseded by ADR 0015 and ADR 0017.**
- [ADR 0014](docs/architecture/adr-0014-consumer-mcp-server-and-mrtr-escalation.md) - the consumer MCP server, protocol gating, and multi-round-trip reveal.
- [ADR 0015](docs/architecture/adr-0015-operator-plane-and-capability-grants.md) - the operator plane and per-request capability grants.
- [ADR 0017](docs/architecture/adr-0017-retiring-the-legacy-local-surface.md) - retirement of the 30-tool local surface and the review site, and the read-only migration source.
- [Security and Access Model](docs/architecture/security-and-access-model.md) - trust tiers, encryption, policy enforcement.
- [CRUD Observability](docs/architecture/crud-observability.md) - how create/read/update/delete activity is seen and audited.
- [Implementation Plan](docs/implementation-plan.md) - build phases and validation gates.
- [Development Readiness Checklist](docs/development-readiness.md) - first build slice, pre-deploy gates, and before-real-data tests.
- [Data Source Intake](docs/data-source-intake.md) - public-safe rules for notes, travel, commerce, connector exports, review packets, and provider data requests.
- [Private Cloudflare Deployment Overlay](docs/deployment/private-cloudflare-overlay-repo.md) - recommended private repo pattern for account-specific Cloudflare deployment state.
- [Temporal Edge Model](docs/temporal-edge-model/README.md) - schema package entrypoint for edge/event ontology and migration semantics.
- [Contributing](CONTRIBUTING.md), [Security](SECURITY.md), and [Code of Conduct](CODE_OF_CONDUCT.md) - public collaboration and reporting policies.

## Working Thesis

Living Atlas is not a single hosted plaintext brain. It is one knowledge graph
with Cloudflare complete custody, a local complete replica, access-classed
objects, and separate capability surfaces:

- Cloudflare custody: complete graph bytes, including sensitive ciphertext.
- Remote MCP: Cloudflare-hosted CRUD for remote-readable data.
- Local replica: complete graph bytes plus local decrypted/indexed views.
- Local MCP: full authorized graph CRUD with local keys.
- Cloud-unlock session: optional remote convenience mode where a transient key
  may unlock sensitive content in the cloud runtime, without key persistence,
  when runtime-memory exposure is acceptable.
- Sensitive objects: plaintext CRUD only through keyholding client/local path.
- Praxis-facing contracts: headless activity, audit, replay, and graph APIs
  that a UI or operator runtime can consume without moving UI code into Atlas.

## Current Status

Phase 1 scaffold exists as a TypeScript workspace. It includes contracts,
synthetic fixtures, access policy evaluation, metadata leakage scanning,
readiness check commands, Cloudflare first-claim bootstrap, fixture-backed local
MCP tools, a sealed local keyring, an encrypted local graph store, sync batch
persistence for remote-readable plaintext and sensitive ciphertext envelopes,
envelope pull/replay, a token-gated remote MCP with
remote-readable graph CRUD, edge CRUD, deterministic text search, bounded graph
traversal, timeline queries, cloud-unlock decrypt for v1 AES-GCM inline
ciphertext envelopes, and hash-only replay reporting over audit/activity/
operational events. It also includes a token-gated usage/budget endpoint that
reports provider-neutral observed usage against configurable limits. It does
not import real graph data or deploy personal Cloudflare resources.

## Development

For the complete first-run runbook, see
[Development Readiness Checklist](docs/development-readiness.md).

First-run synthetic sequence:

```bash
npx pnpm@11.8.0 install
npm run check
npm run smoke:local
npm run local:deploy-synthetic
npm run cloudflare:wrangler-smoke
npm run preflight:synthetic
```

These commands use synthetic fixtures and public-safe templates. They must not
import real graph data, claim a real authority, publish personal Cloudflare
values, or replace placeholder config with private deployment state.

Install with the pinned package manager:

```bash
npx pnpm@11.8.0 install
```

Run the local gate:

```bash
npm run check
```

Run the two synthetic local smoke flows:

```bash
npm run smoke:local
```

`local:install-smoke` exercises the local install mode: it creates a sealed
local control store and sealed local keyring, opens an encrypted local graph
replica, runs the local graph commands (read, create, update, tombstone, plus a
local-private plaintext draft), and checks the activity log and the encrypted
graph files for token/sensitive-bait/plaintext leakage.
`cloudflare:local-smoke` exercises the Worker bootstrap and sync routes
in-process with fake D1/R2 bindings.

Run the full synthetic local deployment exercise before looking at Cloudflare:

```bash
npm run local:deploy-synthetic
```

This creates a temporary local profile, writes an encrypted local control
store, performs synthetic read/create/update/tombstone operations through the
local graph commands, boots the local Worker harness, claims bootstrap, pushes
and pulls ciphertext sync batches through the sync daemon, checks stale and
bad-token-binding rejection, and scans the resulting local artifacts for
token/sensitive-bait leakage.

Run the local stress gate when changing CRUD, policy, sync, or leakage code:

```bash
npm run stress:local
```

Real Logseq semantic review runs can also use a local-private resolution map.
Generate a review packet outside the repo, review each unresolved target, then
set `LIVING_ATLAS_LOGSEQ_SEMANTIC_REVIEW_RESOLUTION_PATH` to a private JSON
file before rerunning the local semantic import. Only high-confidence
hash-addressed decisions promote edges; deferred or missing entries remain
encrypted quarantine records. Explicit `defer` decisions are treated as
reviewed quarantine: the source stays accounted for and withheld, but it no
longer appears as open review work. Keep the packet and resolution map out of
the public repo.

## Connecting an MCP Client

The consumer plane is `packages/atlas-mcp`. It speaks MCP revision
**2026-07-28 only** — `serveStdio` runs `legacy: 'reject'`, so a client that
opens with a 2025-era `initialize` is refused with `-32022` rather than served
something it cannot validate. See
[ADR 0014](docs/architecture/adr-0014-consumer-mcp-server-and-mrtr-escalation.md)
for the server and [ADR 0015](docs/architecture/adr-0015-operator-plane-and-capability-grants.md)
for the operator plane and capability grants.

With no store named, both stdio entry points serve the SURFACE — the consumer
over an empty in-memory graph, the operator over a synthetic operational source:

```bash
npm run atlas-mcp:consumer -- --audit-log /path/to/audit.jsonl
npm run atlas-mcp:operator -- --audit-log /path/to/operator-audit.jsonl
```

`LIVING_ATLAS_STORE_DIR` points either plane at a durable store that already
exists, holding `assertions/` and `identity/` segment logs. It is opened
**read-only** unless `LIVING_ATLAS_STORE_MODE=read-write` says otherwise, because
new-format backup does not exist yet — anything written into the new store is
unprotected until it lands. A directory that is not there is a startup failure,
never an empty graph. See
[ADR 0028](docs/architecture/adr-0028-serving-a-durable-store-from-a-directory.md).

```bash
LIVING_ATLAS_STORE_DIR=/path/to/store \
  npm run atlas-mcp:consumer -- --audit-log /path/to/audit.jsonl
```

The 30-tool local surface these replace — its daemon, its Unix-socket proxy, and
its loopback Streamable HTTP listener — is retired. See
[ADR 0017](docs/architecture/adr-0017-retiring-the-legacy-local-surface.md) for
what was removed, what was kept, and why.

Topic review can use the same private-map pattern. For a conservative first
pass, generate a curated draft that promotes only recurring wikilink tag groups
as controlled topics and defers plain tags, hash tags, and one-off wikilink
tags:

```bash
LIVING_ATLAS_LOGSEQ_TOPIC_REVIEW_CURATED_DRAFT_ACK=write-local-private-topic-review-curated-draft \
LIVING_ATLAS_LOGSEQ_TOPIC_REVIEW_PACKET_PATH=/private/topic-review-packet.json \
LIVING_ATLAS_LOGSEQ_TOPIC_REVIEW_RESOLUTION_PATH=/private/topic-review-resolutions-curated.json \
npm run logseq:semantic-topic-review-curated-draft
```

The curated draft command prints only counts and reason-code buckets. The
private resolution map contains topic labels and must stay outside the repo.
Set `LIVING_ATLAS_LOGSEQ_TOPIC_REVIEW_CURATED_PROMOTE_REASONS` only when a
local operator has decided additional explicit tag classes are high confidence.

Check deployed synthetic usage before running any live Cloudflare stress:

```bash
npm run cloudflare:live-usage-gate
npm run cloudflare:live-ops-report
npm run cloudflare:live-crud-tiny
```

This performs hundreds of synthetic local CRUD operations in one run, including
duplicate creates, stale updates, invalid versions, empty patches, oversized
objects, store-limit enforcement, tombstones, audit/activity checks, and leakage
scans. It also pushes many one-generation ciphertext sync batches through the
local Worker harness, verifies D1/R2 counts, pulls the batch summaries back, and
checks malformed, stale, generation-gap, replay, bad-token, bad-binding,
query-token, and invalid-pull behavior.

Run the full synthetic preflight before any Cloudflare deployment work:

```bash
npm run preflight:synthetic
```

This runs the repo gate, the full synthetic local deployment exercise, the
local stress gate, the Wrangler dry-run smoke, Terraform/OpenTofu formatting,
and Terraform/OpenTofu validation against public-safe example inputs.

`npm run check` runs the repo-safety/leakage check, the anti-drift gates, the
TypeScript typecheck, and the Vitest suite. The check CLI's default `all` mode
runs:

- `local`: contract, policy, leakage, path opacity, and repo-safety checks.
- `cloudflare-deploy-readiness`: synthetic public-template deploy readiness,
  including placeholder Cloudflare bindings, no private deploy values, complete
  fixture manifest coverage, opaque paths, and no sensitive bait in Cloudflare
  metadata.
- `first-run-guardrails`: synthetic bootstrap checks for sealed/unclaimed
  first-run behavior, token-required claim, token burn, concurrent first-claim
  lock behavior, and token-in-query guard coverage.

### Anti-drift gates

```bash
npm run gates
```

Five build failures that stop a published contract from changing without saying
so. Each has permanent negative controls in `packages/atlas-gates/src/*.test.ts`,
so every one of them is known to fail on the defect it exists to catch.

- **Single source.** A tool's shape, its existence, and the set it belongs to
  have exactly one home. Fails on a tool-name set declared outside the contract,
  on one limit written twice and chosen by transport, on an input shape authored
  twice, and on a tool the catalog advertises that nothing serves.
- **Golden fixtures.** One recorded response per published tool, matched against
  the recorded bytes and validated against that tool's own published output
  schema.
- **Answer reproducibility.** A frozen synthetic graph and pinned
  `(subject, as_of_valid, as_of_recorded)` queries with recorded answers. Any
  change to an answer fails and is classified breaking: the remedy is a new
  contract revision, not a re-recorded file.
- **Released revisions are immutable.** Any change under a released
  `schema/<revision>/` fails unconditionally, by content digest and again by
  working-tree diff. A change is a new directory.
- **Literal-constant lint.** Published counts and limits are generated into
  `packages/atlas-gates/baseline/` from the published schemas and read from
  there, never restated in code.

Recording is a separate command from checking, deliberately:

```bash
npm run gates -- --write-baseline --write-goldens --write-corpus
npm run gates -- --freeze-revision
```

`--freeze-revision` only ever adds a revision the lock has never seen. There is
no flag that unfreezes one.

See [ADR 0016](docs/architecture/adr-0016-anti-drift-build-gates.md) for the
drift these were built against and the quarantine ledger that covers the surface
being demolished.

Run individual checks while iterating:

```bash
npx tsx packages/check/src/cli.ts local
npx tsx packages/check/src/cli.ts cloudflare-deploy-readiness
npx tsx packages/check/src/cli.ts first-run-guardrails
npx tsx packages/check/src/cli.ts wrangler-local-runtime
```

`npx pnpm@11.8.0 check` works too and uses the same underlying gate.

Aggregate local-only Logseq migration proof can include supplemental semantic
repair/enrichment ledgers without re-counting source coverage:

```bash
LIVING_ATLAS_LOGSEQ_SEMANTIC_AGGREGATE_MANIFEST_PATHS=/private/semantic-manifest.json,/private/extensionless-manifest.json \
LIVING_ATLAS_LOGSEQ_SEMANTIC_AGGREGATE_LEDGER_PATHS=/private/semantic-ledger.jsonl,/private/extensionless-ledger.jsonl \
LIVING_ATLAS_LOGSEQ_SEMANTIC_SUPPLEMENTAL_LEDGER_PATHS=/private/reviewed-edge-ledger.jsonl \
LIVING_ATLAS_LOGSEQ_SEMANTIC_COMPLETION_MODE=local \
npm run logseq:semantic-corpus-report
```

The report prints counts, hashes, status flags, and decision categories only.
Supplemental ledgers are reported separately from source coverage so repeated
local enhancement passes do not inflate migrated file counts.

Generate the full local real-data readiness rollup after semantic import,
topic review, and connector enrichment artifacts exist in private storage:

```bash
LIVING_ATLAS_LOGSEQ_SEMANTIC_AGGREGATE_MANIFEST_PATHS=/private/semantic-manifest.json \
LIVING_ATLAS_LOGSEQ_SEMANTIC_AGGREGATE_LEDGER_PATHS=/private/semantic-ledger.jsonl \
LIVING_ATLAS_LOGSEQ_SEMANTIC_SUPPLEMENTAL_LEDGER_PATHS=/private/reviewed-edge-ledger.jsonl \
LIVING_ATLAS_LOGSEQ_TOPIC_REVIEW_PACKET_PATH=/private/topic-review-packet.json \
LIVING_ATLAS_LOGSEQ_TOPIC_REVIEW_RESOLUTION_PATH=/private/topic-review-resolutions.json \
LIVING_ATLAS_LOGSEQ_TOPIC_REVIEW_LEDGER_PATH=/private/topic-review-local-ledger.json \
LIVING_ATLAS_CONNECTOR_COVERAGE_MANIFEST_PATH=/private/connector-coverage.json \
LIVING_ATLAS_CONNECTOR_ENRICHMENT_LEDGER_PATHS=/private/connector-enrichment-ledger.json \
LIVING_ATLAS_REAL_DATA_LOCAL_READINESS_REQUIRED_COMPONENTS=topic-review,topic-local-import,connector-coverage,connector-enrichment \
LIVING_ATLAS_REAL_DATA_LOCAL_READINESS_REQUIRE_COMPLETE=1 \
npm run real-data:local-readiness-report
```

The readiness rollup emits only counts, hashes, status flags, and known gaps.
It fails complete mode if required artifact families are missing, source
coverage is incomplete, review work is unresolved, local persistence was not
encrypted, connector imports failed, connector probes mutated data, or any
local real-data artifact shows a Cloudflare sync attempt.

When a private review packet is regenerated with a new path-redaction secret,
previous high-confidence review decisions can be re-keyed by matching normalized
review target values inside private packets:

```bash
LIVING_ATLAS_LOGSEQ_SEMANTIC_REKEY_RESOLUTIONS_ACK=write-local-private-review-resolution-map \
LIVING_ATLAS_LOGSEQ_SEMANTIC_OLD_REVIEW_PACKET_PATH=/private/old-review-packet.json \
LIVING_ATLAS_LOGSEQ_SEMANTIC_OLD_REVIEW_RESOLUTION_PATH=/private/old-review-resolutions.json \
LIVING_ATLAS_LOGSEQ_SEMANTIC_NEW_REVIEW_PACKET_PATH=/private/new-review-packet.json \
LIVING_ATLAS_LOGSEQ_SEMANTIC_REKEYED_RESOLUTION_PATH=/private/new-review-resolutions.json \
npm run logseq:semantic-review-rekey
```

The rekey command writes the new private resolution map outside the repository
and prints count-only diagnostics.

After applying review resolutions, generate a count-only knowledge summary for
node and edge type coverage:

```bash
LIVING_ATLAS_REAL_MARKDOWN_ROOT=/private/logseq-root \
LIVING_ATLAS_REAL_DATA_PATH_REDACTION_SECRET=from-private-env \
LIVING_ATLAS_LOGSEQ_SEMANTIC_SOURCE_MODE=logseq-notes \
LIVING_ATLAS_LOGSEQ_SEMANTIC_REVIEW_RESOLUTION_PATH=/private/review-resolutions.json \
npm run logseq:semantic-knowledge-report
```

This report recomputes the semantic draft plan and emits endpoint type counts,
occurrence/topic totals, edge predicate counts, and quarantine reason counts
without source paths or plaintext values.

Validate the Cloudflare infrastructure skeleton:

```bash
npm run infra:fmt
npm run infra:validate
```

Build the Worker example without deploying:

```bash
npx wrangler@4.103.0 deploy --dry-run \
  --config packages/cloudflare-worker/wrangler.example.jsonc \
  --outdir /tmp/living-atlas-worker-dry-run
```

This dry run is synthetic-only. It should validate the public Worker template,
not claim an authority, upload real graph data, or publish personal Cloudflare
account values. A real deployment uses a private/ignored overlay for the
Cloudflare account, resource ids, deploy token, bootstrap claim-token hash, sync
token hash, domains, and state.

Workspace packages:

- `@living-atlas/contracts`: object envelopes, identity/config records,
  capability types, temporal edge/event validators, audit/change contracts, and
  operational observability events.
- `@living-atlas/fixtures`: synthetic-only fixture graph with sensitive bait and
  remote-safe content.
- `@living-atlas/policy`: capability-bound policy evaluator and output filters.
- `@living-atlas/leakage`: bait-string scanner, opaque Cloudflare path helpers,
  and public-repo safety scanner.
- `@living-atlas/check`: local scaffold verification CLI.
- `@living-atlas/cloudflare-worker`: Cloudflare Worker routes and Durable
  Object first-claim bootstrap lock skeleton, plus token-gated sync batch
  persistence/status, envelope pull through R2/D1 bindings, remote MCP
  remote-readable graph CRUD/search/traversal/timeline/edge tools, and redacted
  structured request observability.
- `@living-atlas/local-control-store`: encrypted local authority/control-plane
  state store, local profile path helpers, and fixture generation tooling.
- `@living-atlas/local-keyring`: sealed local keyring and AES-GCM payload
  encryption helpers for local install mode.
- `@living-atlas/local-graph-store`: durable snapshot/journal graph replica for
  local CRUD and sync replay, with redacted or local-keyring-encrypted
  persistence by policy.
- `@living-atlas/atlas-mcp`: the consumer and operator MCP servers on protocol
  revision 2026-07-28, with per-request capability grants, one audit event per
  call, and multi-round-trip reveal for sensitive disclosure.
- `@living-atlas/local-mcp`: the local graph-command library the retired 30-tool
  surface was built on — bearer token capability checks, sealed control-store
  loading, graph status/list/read plus CRUD backed by in-memory fixtures or the
  durable local graph store, redacted audit events, and optional durable
  mutation outbox files for bidirectional sync daemon pickup. It no longer
  registers or serves any MCP tool (ADR 0017); it is retained because the
  migration tooling in `packages/check` commits through it.
- `@living-atlas/sync-agent`: local sync-agent that builds ciphertext batches,
  drains durable local MCP outbox files through a bidirectional push handshake,
  submits to the Worker sync route, fetches remote summaries/envelopes, and
  applies pulled envelopes into the local graph store with version-conflict
  reporting and bounded conflict samples.
- `@living-atlas/atlas-client`: dependency-light TypeScript client helpers for
  Praxis and other consumers calling remote MCP, activity, and usage surfaces
  with token headers and redacted error details.
- `@living-atlas/activity-replay`: hash-only replay inspection and reporting
  over durable audit, live activity, and operational observability events.
- `@living-atlas/cloudflare-worker` also exposes `/api/usage/status` for
  health-token-gated observed usage and configurable budget ratios. The
  response shape is generic so non-Cloudflare deployments can implement the
  same contract with provider-specific collectors.
- The Worker and remote MCP also expose a `living-atlas-usage-gate:v1`
  safe-to-test/stop-testing decision. The gate is tunable per deployment and is
  intended to fail closed before live synthetic stress runs.
- `cloudflare:live-ops-report` adds a compact operator report over the gate and
  provider-side inventory available through bound Cloudflare services, including
  R2 object count/byte reconciliation.
- `cloudflare:live-local-outbox-drain` runs one live local replica outbox drain
  through the bidirectional push handshake after the deployed usage gate passes
  and the explicit mutation acknowledgement is set.

Semantic Logseq migration uses bounded, plaintext-free planning and ledger
commands:

```bash
npm run logseq:semantic-manifest
npm run logseq:semantic-estimate
npm run logseq:semantic-inventory
npm run logseq:semantic-batch-plan
npm run logseq:semantic-local
npm run logseq:semantic-parity
npm run logseq:semantic-ledger-report
npm run logseq:semantic-review-report
npm run logseq:semantic-review-packet
npm run logseq:semantic-topic-review-packet
npm run logseq:semantic-topic-review-report
npm run logseq:semantic-topic-review-resolution-draft
npm run logseq:semantic-topic-review-local
npm run logseq:offering-item-review-packet
npm run logseq:offering-item-review-groups
npm run logseq:offering-item-review-report
npm run logseq:offering-item-review-resolution-draft
npm run logseq:offering-item-review-local
npm run logseq:semantic-corpus-report
npm run connector:enrichment-report
npm run connector:enrichment-local
npm run connector:enrichment-corpus-report
npm run connector:coverage-report
```

`logseq:semantic-manifest` creates a plaintext-free corpus manifest with one
entry per discovered file, including readable, empty, oversized, and ignored
files. `logseq:semantic-batch-plan` reads a configured private markdown root and
emits only counts, offsets, object totals, and opaque root refs.
`logseq:semantic-estimate` scans the selected source mode and emits counts-only
object and sync-batch estimates before any live mutation.
`logseq:semantic-inventory` emits a plaintext-free inventory of schema-relevant
property keys, accepted endpoint type counts, rejected type values, date-like
properties, wikilinks, tags, block refs, asset refs, and topic-candidate source
counts. Tags and hash tags are counted as candidate topic signals only; they
are not auto-promoted into controlled `topic` nodes. Unknown property keys are
hashed with the path redaction secret instead of printed.
`logseq:semantic-local` preserves each original file as an encrypted source
capsule, preserves normalized encrypted page/block/reference-index objects,
promotes explicit
`type:: person|organization|project|location|occurrence|topic|offering|item`
pages into encrypted endpoint records, maps schema-defined endpoint fields such
as aliases, dates, timezone, recurrence, and explicit wikilink refs when they
validate, applies conservative endpoint type aliases such as `org` to
`organization` and occurrence-like page categories to `occurrence`, runs local
CRUD/leakage proof, and promotes high-confidence property-derived temporal
edges for explicit wikilink relationship fields such as location, topic parent,
`org`/employer affiliation, acquisition, customer, spouse, and estrangement
relationships. It can also promote a non-wikilink property target only when
that value exactly matches one unique typed endpoint title or explicit endpoint
alias of the required type inside the same import batch; wrong-type, duplicate,
fuzzy, or unresolved targets stay in encrypted review. It then
also promotes exact high-confidence suffix tags such as past employer,
education, cohort, revenue, and past advisory markers when endpoint direction is
schema-safe; ambiguous weak-tie and direction-sensitive relationship suffixes
are preserved as encrypted source data and also become encrypted quarantine
review candidates instead of typed edges. Relationship-like properties with
plain-text targets that do not meet the exact typed-title rule, such as
unresolved locations or affiliations, are also captured as encrypted review
candidates rather than guessed into nodes. It then
writes per-file parity refs into the durable ledger without Cloudflare sync.
`logseq:semantic-cloudflare` uses the
same parity path but requires an explicit sync mode plus mutation
acknowledgement before it can split and submit live Cloudflare sync batches.
`logseq:semantic-ledger-report`
can run as a hard completion gate with
`LIVING_ATLAS_LOGSEQ_SEMANTIC_REQUIRE_COMPLETE=1`. Manifest entries with a
terminal `skipped` or `quarantined` decision are reported as terminal accounting
outcomes; they do not require ledger objects unless they were readable semantic
markdown entries.
`logseq:semantic-review-report` reads a semantic ledger and emits a
plaintext-free review queue summary: review reason counts, quarantine totals,
batch windows, and opaque source refs for follow-up.
`logseq:semantic-review-packet` is an opt-in local-private helper that
reconstructs unresolved review targets from the source graph and writes
actionable plaintext values to a caller-supplied path outside the repository.
It requires an explicit acknowledgement and a stable path redaction secret; its
stdout summary remains counts-only. When
`LIVING_ATLAS_LOGSEQ_SEMANTIC_REVIEW_RESOLUTION_PATH` is set, the packet
suppresses targets already handled by high-confidence resolution entries,
including explicit deferrals, so residual review counts match the resolved
ledger.
`logseq:semantic-topic-review-packet` is a separate opt-in local-private helper
for controlled topic curation. It groups tag-derived topic candidates from
plain `tags::` values, hash tags, and wikilink tag values into a private packet
outside the repository. Stdout remains count-only, suffix tags used for edge
semantics are excluded from topic candidates, and no `topic` endpoint is
created until a human-reviewed high-confidence resolution/import path promotes
it.
`logseq:semantic-topic-review-report` validates that private topic packet plus
an optional private resolution map and emits only counts: promoted topics,
deferred candidates, rejected candidates, unknown resolution targets, duplicate
resolutions, unresolved groups, and unresolved candidate occurrences.
`review_complete` is false until every grouped candidate has a terminal
decision. Set `LIVING_ATLAS_LOGSEQ_TOPIC_REVIEW_REQUIRE_COMPLETE=1` when every
grouped topic candidate must have a terminal review decision before proceeding.
`logseq:offering-item-review-packet` is an opt-in local-private helper for
commerce, travel, reservation, product/service, and created-work extraction. It
scans private notes for explicit `offering`/`item` properties and prose
signals such as purchases, payments, reservations, flights, hotel stays,
tickets, seats, rooms, products, subscriptions, deliverables, and provider/model
links. The command writes plaintext snippets only to a caller-supplied path
outside the repository and prints counts only. High-confidence structured
fields may become reviewable offering/item endpoints and commerce/creation
edges; prose-derived candidates require human review before import.
`logseq:offering-item-review-groups` reads that private packet and writes a
second local-private grouped packet outside the repository. It groups related
candidates by kind, proposed node/edge shape, and normalized snippet tokens so
review can happen by clustered evidence rather than line by line. The grouped
packet may contain representative plaintext snippets; stdout remains
hash/count-only.
`logseq:offering-item-review-report` validates grouped offering/item review
coverage with an optional private resolution map and emits only counts and
hashes. `logseq:offering-item-review-resolution-draft` creates a conservative
private all-defer resolution map for every unresolved group. It is useful when
unreviewed commerce/travel/creation candidates should be terminally accounted
for without promoting guessed facts. `logseq:offering-item-review-local`
consumes the grouped packet and private resolution map, then writes promoted
normalized endpoint/edge facts or terminal quarantine records as encrypted
local graph objects only. It never attempts Cloudflare sync.
`logseq:semantic-topic-review-resolution-draft` writes a conservative private
resolution map that defers every grouped topic candidate. It is useful when
unreviewed tag-derived candidates should be terminally accounted for without
creating topic nodes. It does not promote topics; edit the private resolution
map manually for high-confidence `promote-topic` decisions before local import.
`logseq:semantic-topic-review-local` consumes the private packet plus a private
high-confidence resolution map and writes encrypted local graph objects only.
`promote-topic` decisions become encrypted `local-private` topic endpoint
objects; `defer` and `reject` decisions become encrypted `quarantine` terminal
decision records. The command requires an explicit local-write acknowledgement,
an unlocked local keyring, and a local graph directory; it never attempts
Cloudflare sync and emits a hash/count-only ledger.
`logseq:semantic-corpus-report` combines multiple manifest/ledger pairs, such
as separate `markdown-only` and `logseq-extensionless-only` runs, into one
plaintext-free local or synced completion gate. Configure it with comma-separated
`LIVING_ATLAS_LOGSEQ_SEMANTIC_AGGREGATE_MANIFEST_PATHS` and
`LIVING_ATLAS_LOGSEQ_SEMANTIC_AGGREGATE_LEDGER_PATHS`. The default completion
mode is `local`, which accepts local-verified encrypted batches and still fails
on uncovered pending manifest entries, duplicate source refs, CRUD failures,
blocked files, source-mode mismatches, or coverage gaps. It reports legacy
manifest/ledger root-ref mismatches as a count because older ledgers used a
different opaque root-ref ordering while preserving the same per-file refs and
hashes. Set
`LIVING_ATLAS_LOGSEQ_SEMANTIC_COMPLETION_MODE=synced` when Cloudflare parity is
the required proof.

`connector:enrichment-report` validates a local-private connector enrichment
packet from approved sources such as email, calendar, meeting, chat, document,
or manual-file review workflows, then emits only counts and hash-addressed
categories. The packet may contain plaintext evidence and local-private
proposed fact payloads, and must stay outside the repository. The report is the
public-safe gate before any connector-derived facts are promoted into the graph:
only `decision: promote` plus `confidence: high` is counted as promote-ready;
proposed, deferred, rejected, or lower-confidence candidates stay held for local
review.
`connector:enrichment-local` consumes the same packet with an explicit local
write acknowledgement, an unlocked local keyring, and a local graph directory.
It writes promote-ready candidates as encrypted `local-private` graph objects,
writes held candidates as encrypted `quarantine` graph objects, and emits a
plaintext-free ledger. It never attempts Cloudflare sync. Existing connector
object ids are skipped by default for idempotency; an explicit update-existing
acknowledgement is required for a local repair pass.
`connector:enrichment-corpus-report` combines one or more plaintext-free
connector import ledgers into a counts-only completion report. It dedupes by
packet hash, uses the latest ledger for each packet, fails completion on failed
imports, non-encrypted local persistence, or accidental sync attempts, and can
run as a hard gate with
`LIVING_ATLAS_CONNECTOR_ENRICHMENT_REQUIRE_COMPLETE=1`.
`connector:coverage-report` validates a local-private connector coverage
manifest and emits only counts by connector, query kind, status, evidence kind,
and terminal reason code. Use it before or alongside enrichment packets to
prove which authorized connector surfaces were queried, limited, unavailable,
skipped, or failed. The manifest must use hashed query refs only, must stay
outside the repository, and read-only coverage probes with `status: failed`
make the report incomplete. Mutating probes and private query-text fields are
schema-invalid.

`LIVING_ATLAS_LOGSEQ_SEMANTIC_SYNC_MODE` defaults to `local-only`. Cloudflare
sync is paused unless `LIVING_ATLAS_LOGSEQ_SEMANTIC_SYNC_MODE=cloudflare` and
`LIVING_ATLAS_LOGSEQ_SEMANTIC_SYNC_ACK=sync-semantic-ciphertext-to-cloudflare`
are both set. Local-only mode rejects stale sync/backfill acknowledgements so a
shell with old mutation env vars cannot accidentally push. Local-only mode can
use larger bounded windows via `LIVING_ATLAS_LOGSEQ_SEMANTIC_FILE_COUNT`; live
Cloudflare and backfill modes stay capped to smaller mutation-safe windows.

Set `LIVING_ATLAS_LOGSEQ_SEMANTIC_SOURCE_MODE` to choose the corpus slice:

- `markdown-only`: only `.md` / `.markdown` files.
- `logseq-notes`: markdown files plus extensionless Logseq `pages/` and
  `journals/` notes.
- `logseq-extensionless-only`: only extensionless Logseq `pages/` and
  `journals/` notes.

Use separate ledger paths for materially different source modes. Offsets are
relative to the selected source mode and must not be mixed across ledgers.
Hidden filesystem artifacts and dotfiles, including `.fuse_hidden*` files, are
excluded from semantic source discovery.

For legacy semantic imports that already synced the graph objects before
source-capsule refs existed, set
`LIVING_ATLAS_LOGSEQ_SEMANTIC_SYNC_MODE=cloudflare` plus
`LIVING_ATLAS_LOGSEQ_SEMANTIC_SYNC_SCOPE=source-capsules-only` with the live
sync acknowledgement. That pushes only the encrypted source capsules and marks
the batch complete only when the old synced object count plus the new capsules
matches the recomputed plan.

Create an encrypted synthetic local control store for local development:

```bash
LIVING_ATLAS_LOCAL_CONTROL_STORE=/tmp/living-atlas-control-store.json \
LIVING_ATLAS_LOCAL_CONTROL_STORE_PASSPHRASE='replace-with-local-dev-passphrase' \
LIVING_ATLAS_LOCAL_MCP_TOKEN='replace-with-local-dev-token' \
npm run local-control:fixture-store
```

Cloudflare templates:

- `packages/cloudflare-worker/wrangler.example.jsonc`: public-safe Worker
  config example with placeholder bindings and no bootstrap secret.
- `infra/cloudflare/modules/living-atlas-single-authority`: reusable
  Terraform/OpenTofu module for R2, D1, and KV resources.
- `infra/cloudflare/examples/single-authority`: public-safe validation example
  that expects the Cloudflare account id from private environment input.

Cloudflare is the complete graph byte custodian, not the plaintext authority.
Sensitive/local-private graph content is stored in Cloudflare as ciphertext and
opaque metadata; only local or browser keyholding clients decrypt it and build
full private indexes. Remote MCP may serve explicitly remote-readable
projections, but that is separate from the private graph ciphertext source of
truth.