Module sidecar 

On-disk sidecar for the “git roundtrip” promise.

ASD’s live state lives in a SQLite-backed ASG repository. The sidecar mirrors the current-state subset of that data to a .asd/v1/ tree inside the project root so it travels with git clone and can hydrate a fresh machine without a network registry.

Two entry points:

• sync_to_dir: ASG -> disk. Walks the /asd/v1/ ASG tree and emits one JSON file per effect/ledger entry/symbol under <dir>/.asd/v1/, plus a plaintext meta/schema-version.
• hydrate_from_dir: disk -> ASG. Reads the sidecar back and writes via the existing AsgIndexStore, AsgEffectStore, AsgLedgerStore traits, producing equivalent state to what was synced.

What the sidecar does NOT carry

Per DESIGN.md’s three-tier split: the sidecar is current-state only. ASG commit metadata (per-edit intent/confidence/authority) lives in the full-fidelity ASG and is lost on hydrate — that tier is what an opt-in ASG registry would restore. Speculative branches, transitive caches, traces, and the semantic index are also excluded: they’re either regenerable (asd index, asd verify-effects) or registry- only. Effect verification fields rehydrate as-is; no re-verification runs during hydrate.

Orphan handling

Sync writes files whose keys are present in ASG and leaves other files untouched. If a symbol is removed from the index, its sidecar files become orphans on disk. M10 accepts this; asd sync --prune is a follow-up. (See DEFERRED.md § Miscellaneous.)

Filename safety

Python qnames (payments.charge_card) and TypeScript qnames (driver.main) are filesystem-safe on macOS and Linux: no slashes, no colons. On Windows there could be conflicts with reserved device names (COM1, LPT1, NUL, CON, etc.). M10 ignores that; a follow-up should sanitize or hash Windows-reserved filenames.

Structs

HydrateSummary

Result of hydrate_from_dir. missing_schema_version is true when the sidecar exists but has no meta/schema-version file; hydrate still proceeds but callers should surface the mismatch.

SyncSummary

Result of sync_to_dir. Counts what was written; the schema version is always stamped.

Enums

SidecarState

Observable lifecycle state of the on-disk sidecar.

Functions

hydrate_from_dir

Read a .asd/v1/ sidecar under dir and write its contents back into the ASG repo via the existing stores.

hydrate_from_dir_with_cache

hydrate_from_dir, also writing the ledger entries it loads into the ledger cache, which answers list_entries.

mark_fresh_reset

Write the meta/fresh-reset sentinel so agents know a deliberate reset occurred. Call this when asd init --reset or an equivalent wipe operation runs.

outdated_hooks

A warning when the project under root runs git hooks from before Plan B, which reload the whole ledger from .asd/v1/ with asd hydrate on every checkout and merge. On a store that holds more than the sidecar — anything since the last asd sync — that rewrote every entry each time, and before v1.4.7 it re-filed moved entries under their old symbols. asd init installs the current hooks, which import committed conclusions instead.

prune_sidecar

Remove orphaned .asd/v1/ sidecar files — files whose keys no longer exist in the live ASG index. Returns the number of files/dirs removed.

sidecar_lifecycle_state

Inspect the on-disk sidecar under dir and return its lifecycle state.

sync_to_dir

Mirror live ASG state into the .asd/v1/ sidecar under dir.