@@ -0,0 +1,22 @@
+---
+'@objectstack/spec': minor
+'@objectstack/service-datasource': minor
+---
+
+fix(spec)!: a SQLite datasource's `config.filename` must name a database: `''` and a name that starts with `:` without being exactly `:memory:` are refused by the stack parse and the metadata save door, not only by the datasource admin doors
+
+Clause-②: no (narrowing) — `SqliteConfigSchema.filename` and `SqliteWasmConfigSchema.filename` refuse `''` and any `:`-prefixed value other than exactly `:memory:`, so `defineStack` / `os validate` / `os build` and `PUT /api/v1/meta/datasource/NAME` refuse a `sqlite` / `sqlite-wasm` datasource they accepted before. Nothing is widened.
+Metadata-protocol: narrowed
+Skills-docs: none — `skills/**` teaches no SQLite `filename` value, and `content/docs/**` teaches only `:memory:` and file paths, which stay accepted. The prescription ships in the refusal text, the FROM → TO below and the upgrade-guide entry.
+
+<!-- adr-0087: registered sqlite-filename-names-no-database-refused -->
+
+**BREAKING** accept-set narrowing on `SqliteConfigSchema.filename` and `SqliteWasmConfigSchema.filename` (`@objectstack/spec`), and so at every door that judges a datasource against the spec: `defineStack`, `os validate`, `os build` and `PUT /api/v1/meta/datasource/NAME`.
+
+- **Before.** Both schemas typed `filename` as any placeholder-free string. `:memory:/srv/data/parts.db` (the New datasource dialog's prefilled `:memory:` with a path typed after it) and `''` parsed. Every layer reads a name that starts with `:` as fileless, so no file was ever opened: a `sqlite` datasource opened it as a relative path whose directory does not exist and every statement failed, and a `sqlite-wasm` one opened a throwaway in-memory database whose writes were gone at the next connect. The datasource admin doors (Test connection, create, update) already refused both; a datasource declared in a stack or saved through the metadata door was stored anyway, and the admin door's update would not take it back.
+- **Now.** The parse answers one issue at `filename` (`config.filename` on a datasource, `datasources.N.config.filename` in a stack) that names the value, says why and prescribes the fix: `'…' is neither ':memory:' nor a file path. A name that starts with ':' is not read as a file, so this datasource would store nothing: use exactly ':memory:' …`, or `'' is empty and names no database file. …`. `defineStack` raises it as `STACK_SCHEMA_INVALID` (422); the metadata door answers `422 INVALID_METADATA`.
+- **Unchanged.** Exactly `:memory:`, an absent `filename` (still defaulting to `:memory:`), and relative, absolute, Windows-drive and `file:` paths parse as before. Whether a path can be opened or created is still judged only at runtime, by the datasource admin doors; the schema cannot touch the file system.
+- **`@objectstack/service-datasource`.** The admin doors give the same answers as before, word for word. The two arms the string alone decides now come from the driver-contract parse they already run, so `sqlite-database-filename.ts` keeps only its filesystem arm: one definition, in the spec.
+- **`@objectstack/spec`.** The upgrade-guide entry `sqlite-filename-names-no-database-refused` (a semantic migration: no automatic rewrite, because whether the author meant an ephemeral database or the path typed after the prefix is a judgement about the datasource).
+
+**FROM → TO.** `config: { filename: ':memory:/srv/data/parts.db' }` → `filename: '/srv/data/parts.db'` to keep the data in that file, or `filename: ':memory:'` for an ephemeral database; `filename: ''` → `':memory:'` or a file path.
@@ -9,7 +9,8 @@ const IN_MEMORY = ':memory:';
  * [#30331] Why a SQLite datasource's `config.filename` names no database the
  * datasource can use, or `undefined` when it does. The value is either exactly
  * `:memory:` or a file path that exists or can be created; anything else is
- * refused with the value and the reason.
+ * refused with the value and the reason. Precondition: `config` already
+ * passed its driver contract (see "Which arms live here").
  *
  * Judged where the test, the create and the update doors all judge `config`
  * (`DatasourceAdminService.assertValidConfig`), so a draft that tests red is
@@ -43,24 +44,28 @@ const IN_MEMORY = ':memory:';
  *
  * `sqlite` and `sqlite-wasm` only: both open `config.filename`. `turso` names
  * its target as a url, which libSQL parses itself.
+ *
+ * ## Which arms live here
+ *
+ * The filesystem arm only. The two arms the string alone decides (`''`, and a
+ * name that starts with `:` without being exactly `:memory:`) are refined on
+ * `SqliteConfigSchema.filename` / `SqliteWasmConfigSchema.filename` (#30400),
+ * so the build door and `PUT /api/v1/meta/datasource/:name` refuse them too.
+ * `assertValidConfig` runs that driver-contract parse first and calls this only
+ * when it is clean, so those two values arrive here never: ⛔ do not restate
+ * them; the spec is the one copy.
  */
 export async function sqliteDatabaseFilenameIssue(driver: string, config: unknown): Promise<string | undefined> {
   const id = resolveDriverId(driver);
   if (id !== 'sqlite' && id !== 'sqlite-wasm') return undefined;
   const filename = (config as { filename?: unknown } | null | undefined)?.filename;
   // Absent is the schema's own `:memory:` default; a non-string is the
   // driver contract's refusal, already given.
+  // `''` and a `:`-prefixed name other than exactly `:memory:` are the driver
+  // contract's own refusals (#30400, `SqliteConfigSchema.filename`), reported
+  // by the parse that runs before this; `resolveSqliteAbsentFileTarget` reads
+  // both as fileless and answers nothing for them.
   if (typeof filename !== 'string' || filename === IN_MEMORY) return undefined;
-  if (filename === '') {
-    return `config.filename: '' is empty and names no database file. Use '${IN_MEMORY}' for an ephemeral `
-      + 'in-memory database, or the path of a database file.';
-  }
-  if (filename.startsWith(':')) {
-    return `config.filename: '${filename}' is neither '${IN_MEMORY}' nor a file path. `
-      + `A name that starts with ':' is not read as a file, so this datasource would store nothing: `
-      + `use exactly '${IN_MEMORY}' for an ephemeral in-memory database, or the path of a database file `
-      + 'with nothing in front of it.';
-  }
   const { resolveSqliteAbsentFileTarget } = await import('@objectstack/driver-sql');
   try {
     resolveSqliteAbsentFileTarget(filename, 'empty-in-memory');
 
@@ -0,0 +1,205 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * #30400 — a SQLite `filename` must name a database: exactly `:memory:`, or a
+ * file path. `''` and a `:`-prefixed name other than exactly `:memory:` are
+ * refused by `SqliteConfigSchema` and `SqliteWasmConfigSchema`.
+ *
+ * ## What was wrong
+ *
+ * Both schemas typed `filename` as any placeholder-free string. The New
+ * datasource dialog's prefilled `:memory:` with a path typed after it
+ * (`:memory:/srv/data/parts.db`) passed, and every layer reads a leading `:`
+ * as fileless: native sqlite opened it as a relative path whose directory does
+ * not exist (every statement fails), and sqlite-wasm opened a throwaway
+ * in-memory database (writes vanish on reconnect). The datasource admin doors
+ * refuse it at runtime since #30331, but two doors validate against the spec
+ * schema alone and kept storing it:
+ *
+ *   - the build door: `os build` parses the stack with
+ *     `ObjectStackDefinitionSchema` (`packages/cli/src/commands/compile.ts`),
+ *     and `defineStack` raises the same parse as `STACK_SCHEMA_INVALID`;
+ *   - the metadata door: `PUT /api/v1/meta/datasource/:name` judges the item
+ *     with the registered `datasource` type schema
+ *     (`getMetadataTypeSchema('datasource')`, `DatasourceSchema`) and answers
+ *     its issues as `422 INVALID_METADATA`.
+ *
+ * ## What is pinned
+ *
+ *   - refusals on both schemas: one `custom` issue at `filename`, whose message
+ *     names the value, says why, and prescribes the fix; no tracker number;
+ *   - both doors' schemas carry the refusal, located under the datasource;
+ *   - a misspelled alias (`path:`) is still refused as an unknown key pointing
+ *     at `filename`, and the renamed value meets this refusal;
+ *   - CONTROLS: `:memory:`, the default, relative and absolute paths, a
+ *     Windows drive path and a `file:` name still parse unchanged.
+ *
+ * The filesystem arm (a path that can be neither opened nor created) is not
+ * judgeable from the string and stays in the runtime, pinned in
+ * `packages/services/service-datasource/src/__tests__/sqlite-filename-neither-memory-nor-path.test.ts`.
+ */
+import { describe, expect, it } from 'vitest';
+
+import { DatasourceSchema } from '../datasource.zod';
+import { defineStack, ObjectStackDefinitionSchema } from '../../stack.zod';
+import { getMetadataTypeSchema } from '../../kernel/metadata-type-schemas';
+import { getDriverConfigSchema } from './config-registry.zod';
+import { SqliteConfigSchema, SqliteWasmConfigSchema } from './sqlite.zod';
+
+const SCHEMAS = [
+  { driver: 'sqlite', schema: SqliteConfigSchema },
+  { driver: 'sqlite-wasm', schema: SqliteWasmConfigSchema },
+] as const;
+
+/** The refused values, and the sentence each refusal opens with. */
+const REFUSED = [
+  { value: ':memory:/srv/data/parts.db', opens: "':memory:/srv/data/parts.db' is neither ':memory:' nor a file path." },
+  { value: ':memory:parts.db', opens: "':memory:parts.db' is neither ':memory:' nor a file path." },
+  { value: ':mem', opens: "':mem' is neither ':memory:' nor a file path." },
+  { value: '::memory:', opens: "'::memory:' is neither ':memory:' nor a file path." },
+  { value: ':', opens: "':' is neither ':memory:' nor a file path." },
+  { value: '', opens: "'' is empty and names no database file." },
+] as const;
+
+/** The values that name a database, and stay accepted byte for byte. */
+const ACCEPTED = [
+  ':memory:',
+  'data/app.db',
+  './.objectstack/data/dev.db',
+  '/var/lib/objectstack/app.db',
+  'C:\\data\\app.db',
+  'file:app.db',
+  'memory.db',
+] as const;
+
+type Envelope = Error & {
+  code?: string;
+  status?: number;
+  issues?: ReadonlyArray<{ code?: string; path?: readonly PropertyKey[]; message?: string }>;
+};
+
+function refusal(fn: () => unknown): Envelope | null {
+  try {
+    fn();
+    return null;
+  } catch (e) {
+    return e as Envelope;
+  }
+}
+
+const manifest = { id: 'com.example.fx', name: 'fx', version: '1.0.0', type: 'app' as const };
+
+describe('SQLite `filename` refuses a value that names no database', () => {
+  for (const { driver, schema } of SCHEMAS) {
+    describe(driver, () => {
+      it('is the schema the driver registry answers for the driver id', () => {
+        expect(getDriverConfigSchema(driver)).toBe(schema);
+      });
+
+      for (const { value, opens } of REFUSED) {
+        it(`refuses ${JSON.stringify(value)}: one custom issue at \`filename\` naming the value, why, and the fix`, () => {
+          const result = schema.safeParse({ filename: value });
+          expect(result.success).toBe(false);
+          const issues = result.error!.issues;
+          expect(issues).toHaveLength(1);
+          expect(issues[0]!.code).toBe('custom');
+          expect(issues[0]!.path).toEqual(['filename']);
+          const message = issues[0]!.message;
+          expect(message.startsWith(opens), message).toBe(true);
+          // The prescription: `:memory:` for an ephemeral database, or a file path.
+          expect(message).toContain("':memory:' for an ephemeral");
+          expect(message).toContain('the path of a database file');
+          expect(message).not.toMatch(/#\d{3,}/);
+        });
+      }
+
+      it('a `:`-prefixed refusal says why: a leading `:` is not read as a file', () => {
+        const message = schema.safeParse({ filename: ':memory:/tmp/x.db' }).error!.issues[0]!.message;
+        expect(message).toContain("A name that starts with ':' is not read as a file, so this datasource would store nothing");
+        expect(message).toContain("use exactly ':memory:'");
+      });
+
+      it('composes with the placeholder refusal: a `:${…}` value reports both', () => {
+        const result = schema.safeParse({ filename: ':${DATA_DIR}/app.db' });
+        expect(result.success).toBe(false);
+        expect(result.error!.issues).toHaveLength(2);
+        expect(result.error!.issues.every((i) => i.path.join('.') === 'filename')).toBe(true);
+        expect(result.error!.issues.some((i) => i.message.includes('is neither'))).toBe(true);
+      });
+
+      it('a misspelled alias is still refused as an unknown key pointing at `filename`; renamed, it meets the refusal', () => {
+        const aliased = schema.safeParse({ path: ':memory:/tmp/x.db' });
+        expect(aliased.success).toBe(false);
+        expect(aliased.error!.issues).toHaveLength(1);
+        expect(aliased.error!.issues[0]!.code).toBe('unrecognized_keys');
+        expect(aliased.error!.issues[0]!.message).toContain('filename');
+
+        const renamed = schema.safeParse({ filename: ':memory:/tmp/x.db' });
+        expect(renamed.success).toBe(false);
+        expect(renamed.error!.issues[0]!.path).toEqual(['filename']);
+      });
+
+      for (const value of ACCEPTED) {
+        it(`CONTROL: ${JSON.stringify(value)} still parses unchanged`, () => {
+          const result = schema.safeParse({ filename: value });
+          expect(result.success, JSON.stringify(result.error?.issues)).toBe(true);
+          expect(result.data!.filename).toBe(value);
+        });
+      }
+
+      it('CONTROL: an absent `filename` still defaults to `:memory:`', () => {
+        const result = schema.safeParse({});
+        expect(result.success, JSON.stringify(result.error?.issues)).toBe(true);
+        expect(result.data!.filename).toBe(':memory:');
+      });
+    });
+  }
+});
+
+describe('the doors that judge a datasource against the spec alone refuse it', () => {
+  for (const { driver } of SCHEMAS) {
+    const row = (filename: string) => ({ name: 'parts', driver, config: { filename } });
+
+    it(`${driver} · metadata door: the registered \`datasource\` type schema refuses it at config.filename`, () => {
+      const typeSchema = getMetadataTypeSchema('datasource');
+      expect(typeSchema).toBe(DatasourceSchema);
+      const result = typeSchema!.safeParse(row(':memory:/srv/data/parts.db'));
+      expect(result.success).toBe(false);
+      const hits = result.error!.issues.filter((i) => i.path.join('.') === 'config.filename');
+      expect(hits).toHaveLength(1);
+      expect(hits[0]!.code).toBe('custom');
+      expect(hits[0]!.message).toContain("':memory:/srv/data/parts.db' is neither ':memory:' nor a file path");
+
+      const empty = typeSchema!.safeParse(row(''));
+      expect(empty.success).toBe(false);
+      expect(empty.error!.issues.map((i) => i.path.join('.'))).toEqual(['config.filename']);
+    });
+
+    it(`${driver} · build door: the stack parse refuses it at datasources.0.config.filename`, () => {
+      const result = ObjectStackDefinitionSchema.safeParse({ manifest, datasources: [row(':memory:/srv/data/parts.db')] });
+      expect(result.success).toBe(false);
+      const hits = result.error!.issues.filter((i) => i.path.join('.') === 'datasources.0.config.filename');
+      expect(hits).toHaveLength(1);
+      expect(hits[0]!.code).toBe('custom');
+      expect(hits[0]!.message).toContain('is neither');
+    });
+
+    it(`${driver} · build door: defineStack raises STACK_SCHEMA_INVALID / 422 at datasources.0.config.filename`, () => {
+      const refused = refusal(() => defineStack({ manifest, datasources: [row('')] } as never));
+      expect(refused?.code).toBe('STACK_SCHEMA_INVALID');
+      expect(refused?.status).toBe(422);
+      const hits = (refused?.issues ?? []).filter((i) => (i.path ?? []).join('.') === 'datasources.0.config.filename');
+      expect(hits).toHaveLength(1);
+      expect(hits[0]!.message).toContain("'' is empty and names no database file");
+    });
+
+    it(`${driver} · CONTROL: both doors still accept \`:memory:\` and a file path`, () => {
+      for (const filename of [':memory:', 'data/parts.db']) {
+        const meta = getMetadataTypeSchema('datasource')!.safeParse(row(filename));
+        expect(meta.success, `${filename}: ${JSON.stringify(meta.error?.issues)}`).toBe(true);
+        const stack = ObjectStackDefinitionSchema.safeParse({ manifest, datasources: [row(filename)] });
+        expect(stack.success, `${filename}: ${JSON.stringify(stack.error?.issues)}`).toBe(true);
+      }
+    });
+  }
+});