v0.1 architecture: seams and surfaces

[thorwhalen]

The architecture for v0.1, decided before the first commit (per the architecture-first practice: boundaries now, so later iterations add at a seam that already exists). Also kept at the top of .claude/CLAUDE.md.

Seams

#	Seam	v0.1 default (no new dependency)	Replacement you can point at
1	where records live: Store(files=)	dol.TextFiles under the data root (ACQUAINT_DATA_DIR → ~/.config/acquaint/config.toml → ~/.local/share/acquaint)	any MutableMapping[str, str]: a dict (tests), sshdol / s3dol stores
2	the sync remote: sync_init(remote_url=)	the private GitHub repo's SSH URL, read from gh	a gcrypt:: URL (git-remote-gcrypt encrypts file names and history too); a local bare repo (tests)
3	how git / gh run: run= in acquaint.sync	subprocess.run	the scripted fake runner in the sync tests
4	the tells catalogue: catalog= in acquaint.deslop	acquaint/data/deslop/tells.yaml	an over-representation list computed from the operator's own writing, or the Vale signs-of-ai-writing rules

Surfaces for v0.1: CLI + shipped skills/agents + MCP stdio (py2mcp string refs); remote MCP / HTTP asked, not built
NOT seams: layout and file names, slug rule, the [source: …] tag grammar, PROFILE section names, reach precedence order, catalogue file schema, CLI rendering, the pre-push hook body, commit-message format, config file format

Would each surface need the core to change?

• CLI (cw): no. Tools take flat arguments and return JSON-ready dicts; rendering lives in the adapter.
• MCP (py2mcp string refs): no. Every tool has a stable name, a typed signature and a docstring. Its side-effect class is recorded next to the tool list, so operator-only operations (rename, forget, sync) can be left out of the MCP surface.
• Agent skills: no. Each verb has a one-sentence trigger.
• HTTP / remote MCP: no. Every tool takes data_dir, so there is no module-level state to make per-request. Not built: profiles are not exposed to hosted assistants for now.
• Frontend: not planned.

Provisional defaults

• The tells catalogue is a fixed list with tiered thresholds. The research behind it says thresholds should be relative to the operator's own writing. That needs a corpus of the operator's messages, which arrives with mining (a later issue).
• resolve is deterministic normalisation. Probabilistic matching (Fellegi–Sunter, e.g. Splink) only matters for bulk imports, so it is not a seam yet.
• Consolidation (turning observations into profile facts) is skill-driven and done by hand in v0.1. It is not a tool yet.

Deliberate deviation

Data and config directories are resolved with the standard library rather than config2py, because importing config2py costs about 128 ms and a one-field lookup has to stay cheaper than guessing.

[thorwhalen]

Update after two independent reviews of #12 (merged).

• Seam 2 (the sync remote): the replacement named here, a gcrypt:: URL, needs the pre-push guard to recognise git-remote-gcrypt's own push before it can work. Until then sync init refuses gcrypt:: URLs; tracked in Support git-remote-gcrypt remotes in sync #13. The seam itself (sync.init(remote_url=)) is unchanged, so support is an addition at it.
• Settled during review, and now pinned by tests: the six accepted GitHub URL forms are spelled identically in Python and in the hook; origin must have exactly one URL with no pushurl or pushInsteadOf redirect; lint checks links against an index built once instead of searching the store per link.
• The other seams, the surfaces and the NOT-seams line are unchanged.