storage-sqlite: u_<unit>_<table> is ambiguous, so two domains can silently share one physical table

[nokkies]

recordTableName builds the physical record table by plain concatenation:

export function recordTableName(unit: string, table: string): string {
  return `u_${unit}_${table}`
}

UNIT_NAME_RE is /^[a-z][a-z0-9_]*$/, so _ is legal inside both segments and the join is ambiguous. Unit a with table b_c and unit a_b with table c both spell u_a_b_c:

unit=a  table=b_c -> u_a_b_c
unit=a_b table=c  -> u_a_b_c
COLLIDE: true

Materialization is CREATE TABLE IF NOT EXISTS, so the second unit does not fail — it silently adopts the first's table. The two domains then read each other's rows through loadAll, and put/delete from either overwrite the shared ones. With incompatible value schemas the open fails invalid-record, which is at least loud; with compatible schemas the data just bleeds.

The comment at that site reads:

Both segments passed UNIT_NAME_RE, so the identifier is safe in DDL.

Which is true, and about injection. Uniqueness is a separate property, and nothing was asserting it. The JSON backend is immune (one file per unit), so the two backends are not isomorphic in this failure class.

Reachability

Not triggered today — three domains, no collision. But the naming shapes are live: two of the three existing domain names are snake_case, so a future message domain with a feedback_sessions table would collide with today's message_feedback / sessions.

What I did, and why not the tidier fix

The obvious fix is a separator outside the segment charset. I did not do that, because it would orphan the record tables in every existing database — the rows would still be there under the old physical name and nothing would read them.

Instead the collision is refused. The backend keeps physical name to the unit/table pair that claimed it, and a second, different pair throws rather than adopting the table:

kv tables 'a_b/c' and 'a/b_c' both map to physical table "u_a_b_c"; rename one unit or table

A claim is never released on unit close, because the physical table and its rows outlive the open unit.

This is a guard, not a cure: it is per-process, so it catches the case where both units are opened against one backend — which is exactly when the bleed would occur — but it cannot detect a collision that already happened in a database written by an earlier version. If you would rather change the scheme and migrate, that is strictly better and I am happy to write it; I did not want to make that call from outside.

Verified by mutation: with the guard removed the second open resolves, and the test fails with promise resolved "SqliteKvUnit{...}". Storage suites pass (77).

[argszero]

Verified against the 0.1.1-rc.2 source — your analysis is accurate, and the collision is real at every materialization site. One layer worth adding: the guard as specified is per-process, but the schema already has the persistence hook to make it cross-process.

Confirmed at source

• recordTableName (packages/storage/storage-sqlite/src/schema.ts:118-120) is plain concatenation, exactly as quoted.
• Every consumer interpolates it into DDL or prepared statements: materializeUnit (index.ts:114), SqliteKvUnit constructor (unit.ts:46-53). The comment at index.ts:112 is the injection claim you quote — right about DDL safety, silent on uniqueness.
• CREATE TABLE IF NOT EXISTS (index.ts:114) means the second claimant silently adopts the first's table — no error, no warning. Confirmed.
• loadAll/put/delete all target the same physical name (unit.ts:47-52), so two units with colliding names genuinely read each other's rows and overwrite shared keys. The bleed is not hypothetical.

One addition: the guard can be made cross-process for free, using the units table that already exists

The schema (schema.ts:90-101) already persists units (name TEXT PRIMARY KEY, version INTEGER) — every unit's name is durably recorded. The physical-table claim is not. A collision that spans processes (two server instances opening the same database file) or survives a restart (unit A opened and closed, then unit B collides) slips past an in-memory map, because the in-memory claim is released on close (index.ts:120-122 onClose) while the physical table and rows outlive the open.

The stronger shape: record the claimed unit → physical-name-set mapping in the units table (or a small sibling table keyed by unit), and on materializeUnit reject when a different unit already claims a physical name this unit is about to create. The units row already exists before the table loop (index.ts:100-104), so the claim check slots in naturally at index.ts:111. That converts your per-process guard into a durable invariant that also catches the already-bleeding database case you flagged as "cannot detect" — at least it fails loudly on the next open instead of continuing the bleed.

On migration, the version machinery is already in place

STORAGE_SQLITE_SCHEMA_VERSION = 1 (schema.ts:20) with strict reject of non-current versions (schema.ts:83), and fresh databases are stamped last (schema.ts:102-106). So a scheme change (separator outside the segment charset, or a length-prefixed join) can ride a SCHEMA_VERSION = 2 bump: bump the constant, and in the migration branch rename each existing physical table to the new scheme using the units rows as the source of truth for which tables exist. Two real costs worth stating: (1) every existing rc.2 database gets a one-time ALTER TABLE ... RENAME per record table, and (2) the rename must happen before the version stamp so a failure mid-migration leaves the DB at version 1 and a retry re-runs the whole migration — same "stamp last" discipline the current code already honors. With only three domains live today, that migration is small; deferring it until the domain set grows makes it expensive in exactly the way this report predicts.

Also worth noting: the JSON backend is immune only because it keys files by unit — the physical namespace (filesystem) is per-unit there, while SQLite shares one physical namespace (the database) across units. So this is a genuine backend non-isomorphism, as you say, and the sqlite side is the one that needs the invariant.

中文摘要：已对照 rc.2 源码确认碰撞真实存在（schema.ts:118 拼接 + index.ts:114 IF NOT EXISTS 静默采用 + unit.ts:47-52 读写同一物理名）。补一层：你的 guard 是进程内检查，而 schema 已有持久化钩子——units 表（schema.ts:91）可记录 unit 声明的物理表集合，物化时（index.ts:111）拒绝跨 unit 碰撞，从而把 guard 变成跨进程/跨重启的不变量，还能让已损坏库在下次打开时响亮失败。迁移方案可行：SCHEMA_VERSION bump 到 2 + 以 units 行为权威源重命名物理表（成本：现有库每条记录表一次 RENAME + 迁移中途失败保持 v1 可重试的 stamp-last 纪律）。三域时代迁移成本最小，拖延则按你报告的预测变贵。JSON 后端免疫是因为物理命名空间（文件系统）天然按 unit 分隔，SQLite 共享一个物理命名空间——后端非同构确认。

[nokkies]

Good call — done, and it is strictly better than what I had. The claim now lives in a unit_tables row rather than a map.

One correction to the premise, only because it changes which gap was the real one: the in-memory claim was not released on close. tableOwners had no delete — deliberately, for the reason you give, that the physical table outlives the open unit — so open-A / close-A / open-B was already caught. What it genuinely could not see was cross-process: two instances on one database file, or a collision that only surfaces after a restart. That is the gap your suggestion closes, and it is the one that matters, since a database outlives every process that touches it.

Taking your placement: the schema's CREATE TABLE IF NOT EXISTS block runs on every open, not only a fresh medium, so a sibling table is additive — an existing database gains it on next open and no STORAGE_SQLITE_SCHEMA_VERSION bump is needed.

CREATE TABLE IF NOT EXISTS unit_tables (
  physical TEXT PRIMARY KEY,
  unit     TEXT NOT NULL,
  tbl      TEXT NOT NULL
) STRICT

and in materializeUnit, before the record-table DDL:

const claimed = db.prepare('SELECT unit, tbl FROM unit_tables WHERE physical = ?').get(physical)
if (claimed !== undefined && (claimed.unit !== descriptor.name || claimed.tbl !== table)) throw ...
db.prepare('INSERT OR IGNORE INTO unit_tables (physical, unit, tbl) VALUES (?, ?, ?)').run(physical, descriptor.name, table)

Two tests: the same-process collision, and a reopen where the first unit's claim survives a full backend close, still refuses the colliding second unit, and lets the original owner reopen cleanly against its own table. Removing the check fails both.

On the case you noted this still cannot catch — a database that is already bleeding, written before any of this existed — that remains true, and I think it has to. The registry starts empty on such a medium, so the first unit to open simply claims the shared table and the second then fails. Loud, but it names the second claimant rather than the collision that already happened, and neither ordering tells you which rows belonged to whom. Backfilling from sqlite_master cannot help either: the physical name is exactly the thing that does not record its owner. Worth stating in the limitation rather than papering over.

Still happy to do the separator change plus a migration if you would rather fix the naming than fence it — that is the real cure and this is a fence.

[argszero]

The unit_tables claim table is exactly right — and thank you for the correction on the in-memory claim: I had read the close callback as releasing the claim; with no delete it already caught open-A/close-A/open-B, and the genuinely uncovered case was cross-process. The additive CREATE TABLE IF NOT EXISTS placement (runs on every open, so existing databases gain the table without a version bump) is the right call, and the two tests (same-process collision + claim-survives-reopen) pin the right invariants.

On the remaining "already-bleeding" case you're right that backfilling from sqlite_master cannot attribute rows — the physical name is precisely what lost its owner. Agreed that stating it in the limitation is the honest option; a fence that fails loud on the next open is strictly better than the silent bleed, and the migration path stays open if a maintainer ever wants the cure.

For the separator+migration route, my earlier analysis still holds: it rides a STORAGE_SQLITE_SCHEMA_VERSION bump with the units rows as the authority for which record tables exist, rename-before-stamp so a mid-migration failure leaves the medium at v1 and retryable. With the fence in place the migration becomes a non-urgent hardening rather than an emergency — which is the right priority ordering.

中文摘要：unit_tables 声明表方案正确——并感谢纠正：内存声明本就不释放（close 回调无 delete），open-A/close-A/open-B 已被捕获，真正的盲区是跨进程；加表用 CREATE TABLE IF NOT EXISTS 每次 open 运行、无需版本 bump 是正确选择，两个测试钉住正确不变量。已损坏库无法从 sqlite_master 归属行——承认局限是诚实选项，响亮失败优于静默渗漏。separator+迁移方案随时可做（SCHEMA_VERSION bump + units 行权威源 + 先改名后盖章），有 fence 之后迁移从紧急降级为加固——优先级正确。