docs(proposal): rewrite foundations — manifesto, architecture, plan

[JesuFemi-O]

Refs #79

Summary

Draft proposal for rewriting the Tycoon CLI's ingestion layer (and laying foundations for the rest of the control plane) under a new set of abstractions. This PR is the artifact — three documents and an index — not an implementation. Discussion happens on the accompanying issue; reviewers point here for detail.

The proposal pursues a stack-aware control plane positioning (BYOS, agent-latchable, deliberately not a platform). Adjacent tools in the category are platform-shaped; the proposal makes the control-plane vs. platform distinction load-bearing and uses it to constrain every subsequent design choice.

What's in this PR

File	What it is
docs/proposals/_tycoon/MANIFESTO.md	Philosophy and shape — control plane vs. platform, BYOS, the nine compartments (Source / Runtime / Destination / Transformation / Semantics / Presentation / Metadata / Catalog / Surface), progressive disclosure, the scaffolding charter
docs/proposals/_tycoon/ARCHITECTURE.md	C4-shaped structure: System Context → Containers → Components → Code. Adapter interface sketches, layering rules, proposed source tree
docs/proposals/_tycoon/PLAN.md	Execution plan: rewrite-not-refactor decision, naming (_tycoon during rewrite window, tycli entrypoint, cutover criteria), four-step sequencing, port list and don't-port list, risks
docs/proposals/_tycoon/README.md	Index pointing readers at the three docs in reading order

The decisions this proposal asks reviewers to react to

1. Positioning — control plane, not platform (MANIFESTO §1)
2. BYOS — meet existing stacks where they live (MANIFESTO §2)
3. POC scope — dlt + Fivetran as two Runtime adapters, three modes (MANIFESTO §8)
4. Rewrite path — extract a new package at src/_tycoon/, port four named patterns from src/tycoon/, cutover when Fivetran adapter lands with zero core changes (PLAN §D1)
5. CLI shape — thin shell over a typed programmatic API, every command emits the same model to humans and agents (PLAN §D3)

What this PR does not do

• No code changes outside the docs folder
• No changes to the existing src/tycoon/ package
• No changes to existing entrypoints or PyPI distribution

Status

Draft. Iterating in response to issue discussion. Marked ready-for-review once the proposal stabilizes; merged once the team aligns on direction. Implementation work happens in subsequent PRs, scoped against PLAN.md's four-step sequencing.

Naming note

The author used dbty / dbty-cli in conversation as personal shorthand for Database Tycoon (the company). All three documents preserve that shorthand where rewriting would obscure the original framing. The tool itself is the Tycoon CLI (repo tycoon-cli, PyPI database-tycoon). The README and the top of each document make this explicit.

Test plan

• Files render correctly on GitHub (no broken Markdown or ASCII diagrams)
• Internal links between the three docs resolve
• Naming-note callouts at the top of each doc are visible and unambiguous

---

^{Need help on this PR? Tag /codesmith with what you need. Autofix is disabled.}

[db-tycoon-stephen]

Review of the rewrite proposal — direction is right; go in-place, keep dbt, reconcile some naming

Strong proposal. The layered structure (manifesto → architecture → plan) reads well, the C4 framing fits, and the control-plane-vs-platform distinction is applied consistently rather than just asserted. I'm aligned on the positioning, BYOS, the typed-API-with-thin-CLI commitment (D3), and the dlt+Fivetran POC pairing. Two scope calls and a handful of internal contradictions to settle, then this is good to go.

1. Rewrite in-place — drop the _tycoon package and the tycli entrypoint.
The rewrite verdict stands (clean rebuild against the new abstractions, not an in-place refactor of the existing modules), but the parallel-package + shadow-entrypoint + cutover-rename machinery isn't worth its weight. With ~17 downloads/day and no production users — a fact the proposal itself cites — keeping the old CLI "working untouched" buys safety nobody needs. So: drop all of D2 (no tycli, no _tycoon import path) and D1's mechanism (no parallel package, no cutover PR). Do the rewrite directly against src/tycoon/ on a long-lived feature branch merged at parity — that preserves the clean-room property D1 wanted without a second package name living in the tree.

2. dbt (Transformation) stays in POC scope; web server / Dagster / ask are cut.
PLAN D5 de-scopes Transformation, but ARCHITECTURE already names transformations/dbt.py as the POC adapter — they contradict each other. Resolve it in favor of ARCHITECTURE: dbt stays in. Bonus: it means the POC exercises a second adapter shape (Transformation, not just Runtime), which is exactly the "is this abstraction real or coincidence" check the design rests on.

The rest of the don't-port list is confirmed dropped — FastAPI server (start/stop/services), Dagster orchestration, and nao-core ask go for good. Semantics, Presentation (Rill), and MCP/TUI surfaces stay deferred post-POC as planned.

So POC scope = three runtime modes (dlt-native, dlt-project, fivetran) + the dbt Transformation adapter. Note register dlt (#75) is folded in here as dlt-project mode rather than shipping standalone.

3. Internal contradictions to reconcile (objective, not preferences):

• Command name: MANIFESTO/ARCHITECTURE show the user typing dbty …; PLAN says tycli. Going in-place, the command is just tycoon — make every example consistent.
• Package path: ARCHITECTURE Level 4 roots the tree at src/dbty/; PLAN says _tycoon. In-place means src/tycoon/ throughout.
• Metadata file path: .dbty/ (ARCHITECTURE) vs .tycoon/ (PLAN Step 2) vs .tycli/ (PLAN open-Q). Pick one.
• The dbty shorthand pervades both prose docs despite the naming note disowning it — worth a global pass now that the names are settling.

One suggestion, not a blocker: the "add Fivetran with zero core changes" acceptance test is the right centerpiece. Make it explicitly check the one failure mode most likely to slip through — dlt emits a live event stream while Fivetran can only poll; if that push-vs-pull difference leaks into core/ as a Fivetran special-case, the abstraction quietly failed even though the code "works."

Net: green light on direction. Update the plan for the two scope calls + the naming reconciliation and I think we're there.