Analyzer/Resources/Init.sql has genuinely good comments documenting the schema — the id vs object_id distinction, how CAB- file names are derived, what crc32 covers, why archives.name is UNIQUE, etc.
None of that reaches users: SQLite only preserves the text of the CREATE statement itself in sqlite_master, and comments preceding a statement are dropped. So .schema objects on a produced database shows bare column names, and anyone (human or AI agent) working from the database artifact never sees the documentation. Today the views are the only in-database self-documentation.
Two options:
Option A — make the docs the canonical home. Ensure everything in the Init.sql comments is covered in Documentation/analyzer.md (much of it already is), and treat Init.sql comments as internal. Cheapest; but the artifact itself stays undocumented, and binary-only users need the URL.
Option B — move the comments inside the CREATE TABLE ( ... ) parentheses. Comments placed inside the statement (e.g. after each column definition) are preserved verbatim in sqlite_master, so .schema on any produced database self-documents. Best for agents working from just a .db file; slightly noisier .schema output, and Init.sql needs reformatting.
These aren't mutually exclusive (B for the key per-column facts, A for the longer prose), but we should decide deliberately rather than leaving the comments somewhere they help nobody.
Analyzer/Resources/Init.sqlhas genuinely good comments documenting the schema — theidvsobject_iddistinction, how CAB- file names are derived, whatcrc32covers, whyarchives.nameis UNIQUE, etc.None of that reaches users: SQLite only preserves the text of the
CREATEstatement itself insqlite_master, and comments preceding a statement are dropped. So.schema objectson a produced database shows bare column names, and anyone (human or AI agent) working from the database artifact never sees the documentation. Today the views are the only in-database self-documentation.Two options:
Option A — make the docs the canonical home. Ensure everything in the Init.sql comments is covered in
Documentation/analyzer.md(much of it already is), and treat Init.sql comments as internal. Cheapest; but the artifact itself stays undocumented, and binary-only users need the URL.Option B — move the comments inside the
CREATE TABLE ( ... )parentheses. Comments placed inside the statement (e.g. after each column definition) are preserved verbatim insqlite_master, so.schemaon any produced database self-documents. Best for agents working from just a.dbfile; slightly noisier.schemaoutput, and Init.sql needs reformatting.These aren't mutually exclusive (B for the key per-column facts, A for the longer prose), but we should decide deliberately rather than leaving the comments somewhere they help nobody.