# Audit Cloud Sync

> Audit Astra edge/cloud synchronization using local journals/checkpoints and current MatrixOne projection tables. Use for event ingestion gaps, restore/checkpoint mismatch, Work projection drift, and skill/learning visibility issues.

- Skill: `matrixorigin/audit-cloud-sync` (Agent Skill)
- Install (CLI): `npx skillmds@latest add matrixorigin/audit-cloud-sync`
- Raw SKILL.md: https://api.skillmd.com/api/skills/matrixorigin/audit-cloud-sync/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: matrixorigin (https://skillmd.com/u/matrixorigin)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/matrixorigin/audit-cloud-sync

---


# Audit Cloud Sync

Audit current evidence, not a presumed sync diagram. Confirm the live schema and
service owner first, then compare local artifacts with MatrixOne projections.

## Task

$ARGUMENTS

## Phase 1: Confirm Current Owners

Before querying data, confirm table names and owner modules from the repo:

```bash
rg -n "CREATE TABLE IF NOT EXISTS (agent_events|agent_sessions|session_checkpoints|run_checkpoints|user_preferences|skills_registry)" crates/services/src/storage.rs
rg -n "CREATE TABLE IF NOT EXISTS work_(items|branches|check_runs|acceptance_decisions|events|runtime_event_outbox)" crates/services/src/work.rs
rg -n "HybridRestoreService|RestoredSession|restore_recent_tools|session_checkpoints|run_checkpoints|learning_snapshots|skills_registry" crates/services crates/runtime crates/astra-cli --glob '!target/**'
```

Reference document when the issue involves restore, checkpoints, or skill paths:
`docs/architecture/edge-cloud-sync-architecture.md`, especially section 8.

Important current facts:

- `agent_events` and `agent_sessions` are core projection tables.
- `session_checkpoints` stores session checkpoints; `run_checkpoints` stores run checkpoint payloads.
- `work_items`, `work_branches`, `work_check_runs`, and `work_acceptance_decisions` cover durable Work declaration and verification state.
- `skills_registry` is the database-backed skill catalog for web/runtime skills.
- `user_preferences` is current; `session_sync_log` is intentionally dropped in schema setup and must not be used as proof of current sync health.

## Phase 2: Locate Local Evidence

Resolve the target:

```bash
ls -lt ~/.astra/sessions/*.jsonl 2>/dev/null | head
astra journal digest last --format json
astra journal digest <SESSION_ID> --format json
find ~/.astra/sessions/<SESSION_ID> -maxdepth 3 -type f | sort
```

Local evidence to collect:

| Evidence | Path |
| --- | --- |
| Event stream | `~/.astra/sessions/<session_id>.jsonl` |
| Digest summary | `astra journal digest <session_id> --format json` |
| Step checkpoints | `~/.astra/sessions/<session_id>/step_checkpoints/` |
| Composite snapshot index | `~/.astra/sessions/<session_id>/step_checkpoints/composite_snapshots.json` |
| Local workspace restore metadata | `~/.astra/sessions/<session_id>/workspace.yaml` when present |

## Phase 3: Query Cloud Evidence Only When Configured

Use the project's configured MatrixOne connection. Do not hardcode database names;
the service code resolves them through `astra_core::resolve_database_name`.

Suggested query dimensions:

| Aspect | Tables / predicates |
| --- | --- |
| Events | `agent_events` by `user_id`, `session_id`, `event_type`, `turn_id`, `run_id` |
| Session projection | `agent_sessions` by `user_id`, `session_id`, `event_count`, status fields |
| Session checkpoints | `session_checkpoints` by `user_id`, `session_id`, `number`, `turn` |
| Run checkpoints | `run_checkpoints` by `user_id`, `session_id`, `run_id`, `checkpoint_kind` |
| Durable Work | `work_items`, `work_branches`, `work_check_runs`, `work_acceptance_decisions`, `work_events` |
| Skills | `skills_registry` plus runtime/API `GET /skills` path if testing web visibility |
| Preferences | `user_preferences` |

If DB access is unavailable, produce a local-only audit and explicitly label cloud
evidence as skipped.

## Phase 4: Compare Invariants

Events:

- Local journal event count should explain `agent_sessions.event_count`; account for projection filtering before calling it loss.
- Critical trace events should appear in `agent_events` with owner-bound identity (`user_id`, event/run/session fields).
- Repeated local events missing in cloud usually indicate ingestion, ownership, or idempotency issues.

Checkpoints:

- Local checkpoint files and `session_checkpoints` should agree on session, turn, and summary/state availability.
- `run_checkpoints` should be used for run-scoped recovery, not confused with session rewind checkpoints.
- For restore bugs, compare `astra_services::session_restore::RestoredSession` with runtime step restore data; they are distinct layers.

Work:

- Work item revisions, check runs, acceptance decisions, and Work events must refer to compatible goal, graph, and criteria revisions.
- A delivered Work branch without current check and acceptance evidence is a Work lifecycle issue, not just sync lag.

Skills:

- Filesystem skills in `.claude/skills` or `.agent/skills` are local/catalog inputs.
- Web/runtime database-visible skills flow through `skills_registry` and capability selection.
- Do not assume a local filesystem skill is visible to remote runtime unless the code path loads that source.

## Output Contract

```text
Scope:
- target=<session/run/work>, aspect=<aspect>, mode=<local-only|local+cloud>

Evidence:
- local: <journal/checkpoint/digest facts>
- cloud: <table/query facts or skipped reason>

Mismatches:
- <only concrete mismatches with owner table/module>

Likely owner:
- <storage/service/runtime/cli file>

Next fix:
- <one actionable change or verification command>
```