{
"markdown": "# CASK — Content Addressable Store Kit\n\n[](https://github.com/dmundt/go-cask/actions/workflows/ci.yml)\n[](https://github.com/dmundt/go-cask)\n[](LICENSE)\n\nA generic, Git-like **content-addressable store** for Go: store any bytes once under the hash of their content, reference them by\nhash, and build typed object graphs on top — reusable across apps and\ndomains.\n\n- **Content-addressable** — same bytes ⇒ same hash ⇒ stored once (dedup).\n- **Immutable & verifiable** — objects never change; `Verify` detects any\n corruption.\n- **Generic core, typed apps** — the `cas` core knows nothing about your\n types; each app layers its own `Object[T]` model on top (the `gitlike`\n package is the reference example).\n- **Pluggable** — hash algorithms, codecs, and storage backends (filesystem\n and memory ship; more plug in behind one `Backend` contract).\n- **Simple, fast, powerful** — lock-free reads, streaming I/O,\n multi-process-safe writers, semver-versioned object models, GC from roots\n with a Git-style grace period — no over-engineering.\n\n## Design principles & grounding\n\ngo-cask is a **single-host content-addressable store kit**. The durable\ndecisions that shape the repo (each named spec is the normative contract):\n\n- **No network surface ships.** The product has no CAS JSON API, no client\n SDK, and no server binary — it is `cas` + the CLI + the embedded viewer.\n HTTP exposure is an app-author pattern, demonstrated by `examples/api`\n (backend-architecture §1).\n- **The viewer is a byte-layer admin tool.** It shows objects, bytes, and\n integrity — never typed references or graphs — and product code never\n imports `examples/` (viewer-design §7, coding-guidelines §9).\n- **Dependencies are one-directional.** `cas`/`internal`/`cmd` never import\n `examples/`; examples never import `internal/` and are self-contained\n except the `gitlike` shared reference library (examples §2 rule 11).\n- **Lean generic core with reference implementations.** `cas` stays\n app-agnostic; each pluggable seam ships one reference (`sha1`/`sha256`,\n `MemoryBackend`, `JSONCodec`), and only the cas-core §7.1 surface is\n stable — speculative surface is cut, not kept.\n- **The byte layer is policy-free.** GC/prune take app-supplied roots;\n roots are pins (there is no per-object pinned property); the store never\n interprets typed references (consistency §4).\n- **Concurrent by construction.** Object writes are safe across processes\n (unique per-writer temps + atomic rename); maintenance sweeps\n (`gc`/`prune`/`clean`) take an exclusive lock and reclaim only objects\n older than their `--min-age` grace, so a concurrent writer's fresh\n objects always survive (cas-core §6).\n- **Examples teach, never ship.** `gitlike` is the shared reference object\n model; `artifacts` shows the compression-codec seam; `api` shows how an\n app exposes a store over HTTP.\n\n## Repository layout\n\n```text\ncas/ core library (package cas) — generic, app-agnostic, public\ninternal/ implementation detail: web (the viewer), index\nexamples/ runnable example programs (incl. the gitlike reference object model)\ncmd/ entry point: cask (CLI store ops; `cask web` starts the embedded viewer)\ndocs/specs/ the specification set (19 specs + AGENT.md)\ndocs/design/ non-normative design docs (core-overview pointer, viewer-brief)\nAGENTS.md the agent aggregator at the repo root\n.github/ CI only\n```\n\n## Core interfaces at a glance\n\n`cas` is layered: a non-generic **byte layer** (`Hash`, `Backend` + backends)\nbelow a generic, constrained **typed layer** (`Object[T]`, `Codec[T]`,\n`Store[T]`, `Walker[T]`), with caching wrappers on top. The typed layer\ndepends only on the byte layer; apps build their own `Object[T]` models on\n`Store[T]`.\n\nArchitecture layers:\n\n```mermaid\nflowchart TB\n APP[\"Application layer
(per app — gitlike, notes, files, …)\"]\n TYPED[\"Typed layer
(generic cas core — Store[T], caches)\"]\n BYTE[\"Byte layer
(Hash · Backend · backends)\"]\n APP -->|\"depends on\"| TYPED\n TYPED -->|\"depends on\"| BYTE\n```\n\nInterface detail:\n\n```mermaid\nclassDiagram\n direction LR\n\n class Hash {\n <>\n +Algorithm() string\n +String() string\n +Equal(other Hash) bool\n }\n class Backend {\n <>\n +Put(ctx, h, r) error\n +Get(ctx, h) io.ReadCloser\n +Exists(ctx, h) (bool, error)\n +Delete(ctx, h) error\n +List(ctx, algo) []Hash\n }\n class FSBackend {\n <>\n }\n class MemoryBackend {\n <>\n }\n Backend <|.. FSBackend : implements\n Backend <|.. MemoryBackend : implements\n\n class Object~T~ {\n <>\n +Type() string\n +References() []Hash\n }\n class Codec~T~ {\n <>\n +Encode(v T) ([]byte, error)\n +Decode(data []byte) (T, error)\n }\n class Store~T~ {\n +Put(ctx, obj T) (Hash, error)\n +Get(ctx, h) (T, error)\n +Delete(ctx, h) error\n }\n class Walker~T~ {\n +Walk(ctx, h) error\n }\n Store~T~ o-- Backend : raw\n Store~T~ o-- Codec~T~ : codec\n Store~T~ ..> Object~T~ : stores\n Walker~T~ ..> Store~T~ : reads via Get\n\n class CachedStore~T~\n class LRUCache~T~\n CachedStore~T~ o-- Store~T~ : wraps\n LRUCache~T~ --|> CachedStore~T~ : extends\n```\n\n## Quick start\n\n```go\nimport (\n \"github.com/dmundt/go-cask/cas\"\n \"github.com/dmundt/go-cask/examples/gitlike\"\n)\n\nraw, _ := cas.NewFSBackend(\"./objects\") // backend\nrepo, _ := gitlike.NewRepository(raw, \"sha256\") // typed layer on top\nh, _ := repo.Blobs.Put(ctx, &gitlike.Blob{Data: []byte(\"hello\")})\nblob, _ := repo.Blobs.Get(ctx, h) // *gitlike.Blob\n```\n\nFor tests and ephemeral use, swap the backend:\n\n```go\nraw := cas.NewMemoryBackend() // fast, deterministic, not persistent\n```\n\n## The specification set\n\nThis project is specified, not guessed: `docs/specs/` contains the\ncomplete design contract — core architecture (`cas-core`), coding guidelines,\nlibrary design, performance, testing, consistency (GC/pruning), the viewer\nHTTP surface, viewer design & security, versioning, defaults, examples,\nand extensions. `docs/specs/AGENT.md` in that folder is the\nmeta-guide; read it before editing any spec. The full inventory is in\n`AGENT.md` §10. Non-normative design material lives in `docs/design/`\n(the core-overview pointer and the viewer design brief). AI agents working\nin this repo auto-load the repo-root `AGENTS.md`, which points at the full\nset.\n\n## Building & testing\n\n```text\ngo build ./...\ngo vet ./...\ngo test -race ./...\ngofmt -l .\n```\n\nRequires Go 1.27 (toolchain self-managing; library baseline Go 1.22+). See `CONTRIBUTING.md` for the\ndevelopment workflow, and `docs/benchmarks.md` for how to run and read the\nbenchmarks (the regular perf suite and the on-demand scale probes).\n\n## License\n\nMIT — see [LICENSE](LICENSE). Copyright (c) 2026 Daniel Mundt.\n",
"bytes": 7130,
"sha": "ae414fce8c2efd944fd1a50386b969e39d465954a7c866d8242960039e82287f",
"repo_slug": "dmundt/go-cask",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/okf_dmundt_go_cask_docs_design_index_md_2584863f/readme"
}