Понятия и решения
Понятия проекта и принятые решения — с тем, что было отвергнуто.
Tables declared as data
Each repository declares its tables in a small readable file - fields, types, required, allowed values, patterns - and tad checks every row against it. The same declaration serves ocoeco's shared shapes, and others to come.
Three ways into the same data
A tad dataset is files you can read and diff, text you can reshape with jq and Miller, and a database you can query with SQL and joins - one dataset, with every change brought back to the same canonical files.
A tad dataset is DuckDB's EXPORT DATABASE folder - one JSON-lines file per table - edited with SQL and brought back to canonical, diffable files; jq and Miller work on the same files.
Everything queryable, versioned and diffable in one place; measured in the spike: a no-op round trip leaves zero diff at 200,000 rows, one changed row is one changed line.
Отвергнуто: Doltgres and Dolt (history where a pull request cannot show it); gitsheets (no SQL, no joins); GlueSQL (an engine reinvented, without ALTER TABLE); SQLite with sqlite-diffable.
2026-09-21
tad was extracted from a repository that already worked (the software-engineering canon), not designed first in the abstract.
An abstraction is right only once it has met a real case; designing first risked assumptions that would not survive real content.
Отвергнуто: Designing the template first.
2026-09-21
Each repository vendored the engine as a git subrepo at .tad/, pinned in a readable .gitrepo, one commit per sync. Superseded 2026-11-11: copies drifted (three of four older); tad is now called, not copied - released binaries, pinned per repository, moved weekly (2026-11-11-one-release-path, 2026-11-11-pins-moved-by-the-lab).
Tested against git subtree on a real update: subrepo writes one commit per sync instead of two and states the pinned commit plainly.
Отвергнуто: git subtree (two commits per sync, the pin buried in a commit trailer).
2026-09-22
tad is released by release-please (versions and changelog from conventional commits) with the package conveyor building binaries in the same run; the tag-triggered workflow is gone.
One release path, no manual version bumps; a tag made with GitHub's own token cannot start another workflow, so the binaries are built in the same run.
Отвергнуто: Tagging by hand with land --tag as the release path; keeping both paths.
2026-11-11
The lab machine moves each repository's tad pin (bin/update-pins.sh, weekly), landing through land so each repository's CI decides.
A pull request opened by a workflow with GitHub's own token starts no CI, so a pure-GitHub updater would open unchecked pull requests; the lab machine already holds a token and lands through checks.
Отвергнуто: A GitHub workflow with GitHub's token (its pull requests start no CI); the author's personal token as a secret in four repositories (spreads the key); a GitHub App (the clean CI-native way - needs the author's setup; a later upgrade).
2026-11-11
tad in Rust: tables declared as data (after Frictionless Table Schema); one tool - check, canonical form, row edits with a check, documents rendered from data; proven equal to the Python version on all four repositories (same verdicts, same documents) before any switch; delivered by the package conveyor instead of vendored; ocoeco's shapes become a tad declaration. The tool is delivered by the package conveyor (for CI and machines); the library is taken as a Rhizoid cutting where a project builds on it (ocoeco) - as tad's own path already says, a rhizcut in every repository. Corrected 2026-11-12 by 2026-11-12-sql-again: SQL is not optional - tad answers real SQL through an embedded SQLite.
The author: tad stays general and Python leaves. The four schemas need no database engine: their 41 tables use only patterns, allowed values, required fields and one list column.
Отвергнуто: Rust bindings to DuckDB keeping schema.sql (a database engine to validate text); Dolt (a separate store); keeping the vendored copies.
2026-11-11
When the four repositories switch to tad, their documents are re-rendered by today's renderer; the canon's and Rhizoid's change visibly, and that is said in the switch's own change.
Their vendored copies are older; the switch is the first time they get today's renderer. A change people did not expect should be announced, not discovered.
Отвергнуто: Porting the older renderers too, to switch without visible change.
2026-11-11
tad's SQL engine is a port in tad's own words (load the declared tables, run a statement, give the tables back), and its adapter today is DuckDB's pinned standalone binary, checked by fingerprint and installed beside tad; a stand-in serves the tests; an embedded DuckDB stays possible as another adapter if it ever builds statically.
Measured (carrying-duckdb): embedding costs six minutes per build, 66 MB, and no static release; the standalone binary is fast, published for both architectures and already trusted by the feeds.
Отвергнуто: Embedding DuckDB now (no static build, slow builds, a large binary).
2026-11-12
How pages read is declared in tables.toml ([site] and [pages.<table>]) and rendered by tad; no repository keeps a renderer of its own. Refined the same day by 2026-11-12-tad-is-text-as-data: presentation stays declared as data, but in the renderer's own file, not in tables.toml, and the renderer leaves tad.
The canon kept its own renderer only for its presentation; declared as data, its seven pages came out identical but for the notice line, and any repository can say how it reads.
Отвергнуто: A renderer per repository (code each must keep, and DuckDB with it in the canon's case).
2026-11-12
tad answers real SQL again: tad sql runs a statement over the declared tables through an embedded SQLite - a query reads them, a change is checked by tad (every row and rule) before the tables are written back in canonical form, as the Python version did with DuckDB. Proven equal on the four repositories' own queries before anyone relies on it. Superseded the same day by 2026-11-12-sql-is-duckdb: the original 2026-09 research had already weighed SQLite and chosen DuckDB.
The author, 2026-11-12: the whole point of tad is that it can be used with real SQL; and lab-agent's journal will be tad tables that must be queried. The Rust rewrite had dropped SQL as optional - that was wrong.
Отвергнуто: No SQL (the rewrite's choice - it left tad unable to answer questions about its own data); GlueSQL (pure Rust, storage as a trait, but younger and a smaller dialect); DataFusion (built for analytics at scale, heavy for this); DuckDB again (a large engine to embed, and the declaration already gives the types).
2026-11-11
tad sql runs on DuckDB, as the original research decided: the declared tables are read into DuckDB, the statement runs, and the tables come back through tad's checks and canonical form; whether DuckDB is embedded in tad or called as its pinned standalone binary (as the phone project's feeds already do) is settled by measuring both on the release build.
The author, 2026-11-12: SQL was the whole point of tad, researched with prior art before tad existed (why-tad-exists). The 2026-11-12 choice of SQLite contradicted that research, which had weighed SQLite with sqlite-diffable and chosen DuckDB for its native file layout, rich types and measured zero-diff round trip.
Отвергнуто: SQLite (weighed in 2026-09, and DuckDB chosen); no SQL (the 2026-11-11 rewrite's mistake).
2026-11-11
tad installs its own SQL engine: tad engine fetches DuckDB's pinned binary for this machine into tad's own folder and checks its fingerprint before unpacking; tad sql uses the one named in TAD_DUCKDB, else tad's own, else one on the PATH. The pin lives in the adapter that owns it and moves with tad's releases.
An install script copied into each repository is what drifted before (delivering-tad); the DuckDB adapter owns where its engine comes from.
Отвергнуто: A copied install-duckdb script in each repository (copies drift); asking each person to install DuckDB themselves (no pin, no fingerprint).
2026-11-12
tad's concern is text as data and nothing else: declare the tables, keep them checked and canonical, and make them easy to create, read, update and delete through files, text tools and SQL. Rendering is a use of the data, so it leaves tad for a small tool of its own that consumes tad, taking the presentation declaration ([site], [pages]) out of tables.toml with it; the four repositories' pages are proven byte-identical before tad drops render. tad grows only where working with the data is inconvenient.
The author, 2026-11-12: rendering, or any other use of the data, is not tad's concern; it was added in the Python days, before there was anywhere else for it. Half of tad's code (1,288 of 2,601 lines) is rendering; ocoeco uses only tad's check. The renderer becomes its own tool, not part of the observatory's engine, because no project may need the observatory to work: a project draws its own pages.
Отвергнуто: Keeping rendering in tad (two concerns in one tool, and presentation mixed into the data's declaration); moving it into the observatory's engine (projects would need the observatory to show their own pages).
2026-11-12
When rendering has left, this repository is renamed tad: it then holds only tad. The names tad-engine and text-as-data-template are artifacts of the vendoring era, when the engine was split out to be copied into each repository - an early, hand-made form of what Rhizoid's cuttings are for. text-as-data-template, which still carries the Python engine, is retired with a pointer once nothing starts from it: a new repository starts with ocoeco init and a tables.toml.
The author, 2026-11-12: tad and tad-engine come from the old era, explored before rhizoid and rhizcut existed; the template mixed rendering in, and the engine was what tad should be. Correction, 2026-11-12: it was said here that no repository was ever made from the template. One was: linux-phone-oco/docs, on 2026-11-04 - found when its release proposed the template's version. The decision stands - a repository made from a template is an independent copy, so retiring the template takes nothing from it - but its reasoning is corrected.
Отвергнуто: Keeping both names (they describe how tad used to be copied, not what it is); renaming before rendering leaves (the repository would still hold two concerns).
2026-11-12
tad's command line is declared with argenv (the commons' own crate) instead of clap: one contract gives the parsing, the help, completions for bash, zsh, fish and nushell, and the man page. A named statement's parameters are read by tad against the statement's own header; set's repeated --key and --set are collected by tad, since argenv keeps the last of a repeated flag that is not a list of known tokens.
The author asked for it on 2026-11-17; and the practice is to build on the commons' own crates first (argenv, tad, ocoeco). argenv gained completion values asked of the program at Tab time (argenv-resolve 0.4) so that statement names come from the place being worked in.
Отвергнуто: Keeping clap (a second way of declaring a command line in the commons, and no completions for nushell); completions written by hand (they drift from what tad accepts); completing statement names from a list baked into the completion script (each place has its own).
2026-11-17
A place keeps the SQL it runs as named statements beside its tables: queries/NAME.sql read, records/NAME.sql write, each with typed parameters declared in its leading comment as they are given on the command line (-- --project string). tad runs them by name - tad query NAME --project x, tad record NAME ... (q and r for short) - writing each value as a SQL literal of its type, never as spliced text. A query that would change a table is refused; what a record writes is kept only if every rule holds, as with tad sql. tad statements lists them, and the shell completions ask it for their names as they complete.
The author, 2026-11-17, for linux-phone-oco: everything goes through tad in one database, and the SQL that writes it should be named and reviewable where the data is. SQL had been kept as loose files run three ways (feeds by DuckDB directly, derivations by tad sql --file, devlab's filing statement built in Rust), each splicing values into text by hand. A file per statement is a diff in the same change as the work that needs it, with no release of tad.
Отвергнуто: Queries compiled into tad (each new one would need a release of tad); a second CLI over the same database, such as an 'ocotad' (two tools, one database); keeping SQL as unnamed files run with tad sql --file (no parameters, so values were spliced as text); the verbs run or exec (they do not say whether the data changes), call (a stored procedure's word, and SQL's stored procedures live in the engine, not beside the data), select/insert (SQL's own keywords, narrower than what a statement does), ask/tell (unclear to a reader who knows SQL), get/put (they suggest one row by key, which tad set already is).
2026-11-17
Starting a bare database is tad's own: tad init DIR writes tables.toml with no table, data/, bin/install-tad.sh pinned to the release of tad that ran it (checked against the release's checksums), .github/workflows/tad.yml (check, canonical, pages fresh) and the pages of the empty declaration, so the check holds from the first commit; it writes nothing where any of those is there. It holds nothing of a domain: the standing tables of a knowledge base, the about link and the named queries are grenudi/ideal-knowledge-base's, which starts from tad init. It replaces text-as-data-template's scaffold, which is retired.
linux-phone-oco/docs decision 2026-11-17-ideal-knowledge-base, accepted by the author on 2026-11-17: tad stays a database and gains a way to start one; the knowledge-base layer goes on top, in its own repository. The template was the scaffold of the vendoring era (a Python .tad/ copied in by git subrepo, three of four copies drifted - 2026-09-22-vendored-as-a-subrepo); since 2026-11-11 tad is called, not copied, so a start needs only the pin and the check. Declared with argenv like every tad command (practice 43): init and its DIR are in contract.rs, so the help, completions and man page say them.
Отвергнуто: Keeping the template as the way to start (it still carries the Python engine and a domain's example rows); renaming the template into the knowledge base (it would fold a database's scaffold into a knowledge base - the author's correction); ocoeco init as the start (it writes an ocoeco place's mark and records, not a database; the-repository-is-tad named it before tad could start one); a start with a Makefile (the CI says tad's commands itself, a base adds make if it wants); a GitHub template repository (a copy that drifts, as this one did); init with no DIR meaning here (a command that writes needs its place said - practice 8); writing a Pages layout (how pages look for people is the face's, not the database's - the template's RFC-like style stays in its history).
2026-11-17