kuda

Appearance

Reference: card schema ​

Two artifact files, both committed YAML under .kuda/ (location configurable via [cards].dir).

.kuda/index.yaml — the L0 repo card ​

yaml
name: kuda                     # repo display name
root: /abs/path/to/repo
purpose: ''                    # manifest/tagline — human-editable
modules:                       # sorted module names
- kuda-core
- kuda-store
commands:                      # detected verify/build commands
- cargo check
- cargo test --workspace
tree_digest: 93183a1c…         # sha1 over sorted path:hash lines —
                               # every walked file, one line
files_total: 12401             # walked-file count (diagnostic)
provenance:
  files: [Cargo.toml, crates/kuda-store/Cargo.toml, README.md]
  hashes: [sha1, ...]          # card inputs only: manifests + README
  commit_sha: af26b8c…
  generated_at: '1712345678'   # unix seconds
  generator: kuda/0.1.0

provenance.files on the L0 card is deliberately bounded — manifests decide module identity, the README feeds purpose, and tree_digest/files_total fingerprint the rest. Embedding the full walked set put ~10k rows in the always-load card; per-file hash lists still live on the L1 module cards where status actually checks them.

.kuda/modules/<name>.yaml — an L1 module card ​

yaml
name: kuda-store
path: crates/kuda-store/Cargo.toml
purpose: Store port — IndexStore trait          # manifest description
api:                           # extracted public symbols — bounded:
- IndexStore                   # `_`-privates dropped, sorted, capped
- SqliteStore                  # at 40 entries
api_omitted: 217               # symbols beyond the cap ("+N more")
deps:                          # outgoing edges
- from: kuda-store
  to: kuda-core
  kind: PackageDep
notes: ''                      # HUMAN-OWNED — preserved on regen
verify:                        # files to open before trusting —
- crates/kuda-store/src/lib.rs # entry points first, capped at 10
provenance:
  files: [...]
  hashes: [...]
  commit_sha: …
  generated_at: '…'
  generator: kuda-template/0.1.0

Provenance semantics ​

files + hashes are git hash-object digests of the card's inputs at sync time. kuda status (and mimus audit) re-hash the same files and compare — a mismatch marks the card drifted. commit_sha records the index point in history; generator records which adapter produced the card so format drift is auditable.

Ownership ​

Machine fields (api, deps, provenance) are regenerated on every sync. notes: and purpose: (when hand-edited past the manifest default) are the human regions — a real merge story is a TODO; today regen overwrites purpose only when it still equals the old machine value.