@celilo/cli 2.3.0 → 3.1.0

package/src/policy/capability-shape.test.ts

@@ -0,0 +1,105 @@
+/**
+ * The breaking/additive classifier behind the request-contract gate
+ * (capability-shape-drift.test.ts Scan C and the regenerate script's guard).
+ *
+ * celilo#1361 shipped because a request type lost a required field and no
+ * version moved. These tests pin the classification that prevents the next
+ * one: member removal, optional → required, and type changes are BREAKING;
+ * an added optional member is additive.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { type RequestTypeShape, classifyRequestChange, requestTypes } from './capability-shape';
+
+function shape(
+  name: string,
+  members: Array<[name: string, type: string, optional?: boolean]>,
+): RequestTypeShape {
+  return {
+    name,
+    kind: 'interface',
+    members: members.map(([memberName, type, optional]) => ({
+      name: memberName,
+      type,
+      optional: optional ?? false,
+    })),
+  };
+}
+
+describe('classifyRequestChange', () => {
+  test('no members changed → unchanged', () => {
+    const before = [shape('R', [['path', 'string']])];
+    expect(classifyRequestChange(before, structuredClone(before))).toEqual({ kind: 'unchanged' });
+  });
+
+  test('a removed member is breaking', () => {
+    const before = [
+      shape('R', [
+        ['path', 'string'],
+        ['sourceDir', 'string'],
+      ]),
+    ];
+    const after = [shape('R', [['path', 'string']])];
+    const result = classifyRequestChange(before, after);
+    expect(result).toEqual({ kind: 'breaking', reasons: ['R.sourceDir was removed'] });
+  });
+
+  test('optional → required is breaking', () => {
+    const before = [shape('R', [['hostname', 'string', true]])];
+    const after = [shape('R', [['hostname', 'string']])];
+    expect(classifyRequestChange(before, after)).toEqual({
+      kind: 'breaking',
+      reasons: ['R.hostname went optional → required'],
+    });
+  });
+
+  test('a type change is breaking (the diff cannot tell widened from narrowed)', () => {
+    const before = [shape('R', [['port', 'number']])];
+    const after = [shape('R', [['port', 'number | string']])];
+    expect(classifyRequestChange(before, after).kind).toBe('breaking');
+  });
+
+  test('a new REQUIRED member is breaking', () => {
+    const before = [shape('R', [['path', 'string']])];
+    const after = [
+      shape('R', [
+        ['path', 'string'],
+        ['digest', 'string'],
+      ]),
+    ];
+    expect(classifyRequestChange(before, after).kind).toBe('breaking');
+  });
+
+  test('a new optional member is additive', () => {
+    const before = [shape('R', [['path', 'string']])];
+    const after = [
+      shape('R', [
+        ['path', 'string'],
+        ['spaFallback', 'boolean', true],
+      ]),
+    ];
+    const result = classifyRequestChange(before, after);
+    expect(result.kind).toBe('additive');
+    if (result.kind === 'additive') expect(result.note).toContain('spaFallback');
+  });
+
+  test('required → optional is additive', () => {
+    const before = [shape('R', [['hostname', 'string']])];
+    const after = [shape('R', [['hostname', 'string', true]])];
+    expect(classifyRequestChange(before, after).kind).toBe('additive');
+  });
+
+  test('a type leaving the reachable set is an interface change, not a request break', () => {
+    const before = [shape('Old', [['path', 'string']]), shape('New', [['path', 'string']])];
+    const after = [shape('New', [['path', 'string']])];
+    expect(classifyRequestChange(before, after)).toEqual({ kind: 'unchanged' });
+  });
+
+  test('public_web resolves its real request types, sourceDir no longer among them', () => {
+    const publish = requestTypes('public_web').find((t) => t.name === 'PublishStaticSiteRequest');
+    expect(publish).toBeDefined();
+    const names = publish?.members.map((m) => m.name) ?? [];
+    expect(names).toContain('path');
+    expect(names).not.toContain('sourceDir');
+  });
+});

package/src/policy/capability-shape.ts

@@ -11,7 +11,7 @@
  */
 
 import { createHash } from 'node:crypto';
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import type { CapabilityTableDeclaration, CapabilityTables } from '@celilo/capabilities';
 import ts from 'typescript';
@@ -95,6 +95,216 @@ function printedInterface(file: string, typeName: string): string {
   throw new Error(`${typeName} not found in ${file}`);
 }
 
+// --- REQUEST / RESULT TYPES -------------------------------------------------
+//
+// The interface hash above references its request and result types by NAME
+// only, so an edit to `PublishStaticSiteRequest` never moved a hash. That is
+// the exact hole celilo#1361 fell through: `sourceDir` was removed from three
+// request types, no contract version moved, and every new consumer build died
+// against the deployed providers. Everything below resolves those types and
+// hashes their members, so a request-contract change trips the gate like any
+// interface change — and the recorded member text lets the regenerate script
+// tell a breaking member diff (bump the MAJOR) from an additive one (minor).
+
+interface DeclaredType {
+  file: string;
+  decl: ts.InterfaceDeclaration | ts.TypeAliasDeclaration;
+  source: ts.SourceFile;
+}
+
+/** All interface and type-alias declarations in one capabilities src file. */
+function declaredTypes(file: string): Map<string, DeclaredType> {
+  const out = new Map<string, DeclaredType>();
+  if (!existsSync(file)) return out;
+  const source = parse(file);
+  for (const statement of source.statements) {
+    if (ts.isInterfaceDeclaration(statement) || ts.isTypeAliasDeclaration(statement)) {
+      out.set(statement.name.text, { file, decl: statement, source });
+    }
+  }
+  return out;
+}
+
+/** Named relative imports of one file: local name → the file it came from. */
+function importsOf(file: string): Map<string, string> {
+  const out = new Map<string, string>();
+  if (!existsSync(file)) return out;
+  const source = parse(file);
+  for (const statement of source.statements) {
+    if (!ts.isImportDeclaration(statement)) continue;
+    const specifier = (statement.moduleSpecifier as ts.StringLiteral).text;
+    if (!specifier.startsWith('./')) continue;
+    const target = join(CAPABILITIES_SRC, `${specifier.replace('./', '')}.ts`);
+    const bindings = statement.importClause?.namedBindings;
+    if (!bindings || !ts.isNamedImports(bindings)) continue;
+    for (const element of bindings.elements) {
+      out.set(element.name.text, target);
+    }
+  }
+  return out;
+}
+
+/** Type-reference identifiers reachable from one declaration. */
+function referencedTypeNames(decl: ts.Declaration): Set<string> {
+  const out = new Set<string>();
+  const walk = (node: ts.Node): void => {
+    if (ts.isTypeReferenceNode(node)) {
+      if (ts.isIdentifier(node.typeName)) out.add(node.typeName.text);
+    } else if (ts.isExpressionWithTypeArguments(node)) {
+      if (ts.isIdentifier(node.expression)) out.add(node.expression.text);
+    }
+    ts.forEachChild(node, (child) => walk(child));
+  };
+  walk(decl);
+  return out;
+}
+
+const shapePrinter = ts.createPrinter({ removeComments: true });
+
+/** One member of a request type, in the form the baseline records and diffs. */
+export interface RequestMemberShape {
+  name: string;
+  optional: boolean;
+  /** Printed member type, comments stripped. */
+  type: string;
+}
+
+/** One request or result type a capability's interface can reach. */
+export interface RequestTypeShape {
+  name: string;
+  /** 'alias' types hash as one synthetic `_self` member. */
+  kind: 'interface' | 'alias';
+  members: RequestMemberShape[];
+}
+
+function membersOfDecl(decl: DeclaredType): RequestMemberShape[] {
+  if (ts.isTypeAliasDeclaration(decl.decl)) {
+    return [
+      {
+        name: '_self',
+        optional: false,
+        type: shapePrinter.printNode(ts.EmitHint.Unspecified, decl.decl.type, decl.source),
+      },
+    ];
+  }
+  const members: RequestMemberShape[] = [];
+  for (const member of decl.decl.members) {
+    if (!member.name) continue;
+    const typeNode =
+      ts.isPropertySignature(member) || ts.isMethodSignature(member) ? member.type : undefined;
+    members.push({
+      name: member.name.getText(decl.source),
+      optional: Boolean(member.questionToken),
+      type: typeNode
+        ? shapePrinter.printNode(ts.EmitHint.Unspecified, typeNode, decl.source)
+        : shapePrinter.printNode(ts.EmitHint.Unspecified, member, decl.source),
+    });
+  }
+  return members.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+const declsCache = new Map<string, Map<string, DeclaredType>>();
+
+function declsOf(file: string): Map<string, DeclaredType> {
+  let cached = declsCache.get(file);
+  if (!cached) {
+    cached = declaredTypes(file);
+    declsCache.set(file, cached);
+  }
+  return cached;
+}
+
+function allSrcFiles(): string[] {
+  return readdirSync(CAPABILITIES_SRC)
+    .filter((f) => f.endsWith('.ts') && !f.endsWith('.test.ts'))
+    .map((name) => join(CAPABILITIES_SRC, name));
+}
+
+/**
+ * Resolve a referenced type name from the file that references it: the file's
+ * own declarations first, then its named imports, then a unique export
+ * anywhere in packages/capabilities/src. An unresolved name is not contract
+ * surface this repo owns (primitives, DOM types) and is ignored; an ambiguous
+ * one would hash the wrong declaration, so it refuses rather than guessing.
+ */
+function resolveName(name: string, fromFile: string): DeclaredType | undefined {
+  const local = declsOf(fromFile).get(name);
+  if (local) return local;
+  const imported = importsOf(fromFile).get(name);
+  if (imported) {
+    const found = declsOf(imported).get(name);
+    if (found) return found;
+  }
+  const hits: DeclaredType[] = [];
+  for (const file of allSrcFiles()) {
+    const found = declsOf(file).get(name);
+    const exported = found?.decl.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
+    if (found && exported) hits.push(found);
+  }
+  if (hits.length === 1) return hits[0];
+  if (hits.length > 1) {
+    throw new Error(
+      `capability-shape: type name '${name}' is declared in ${hits.length} files (${hits.map((h) => h.file).join(', ')}), so its request shape cannot be resolved unambiguously. Rename one of them.`,
+    );
+  }
+  return undefined;
+}
+
+/**
+ * Every request/result type reachable from a capability's interface. Names
+ * that resolve to nothing in packages/capabilities/src (primitives, DOM
+ * types) are ignored — they are not contract surface this repo owns.
+ */
+export function requestTypes(capability: string): RequestTypeShape[] {
+  const subject = capabilitySubjects().get(capability);
+  if (!subject) throw new Error(`${capability} is not in CapabilityRegistry`);
+
+  const start = parse(subject.file);
+  let iface: ts.InterfaceDeclaration | undefined;
+  for (const statement of start.statements) {
+    if (ts.isInterfaceDeclaration(statement) && statement.name.text === subject.typeName) {
+      iface = statement;
+    }
+  }
+  if (!iface) throw new Error(`${subject.typeName} not found in ${subject.file}`);
+
+  const visited = new Set<string>();
+  const shapes: RequestTypeShape[] = [];
+  const queue: Array<{ name: string; fromFile: string }> = [
+    { name: subject.typeName, fromFile: subject.file },
+  ];
+  while (queue.length > 0) {
+    const { name, fromFile } = queue.pop() as { name: string; fromFile: string };
+    if (visited.has(name)) continue;
+    visited.add(name);
+    const decl = resolveName(name, fromFile);
+    if (!decl) continue;
+    const members = membersOfDecl(decl);
+    shapes.push({
+      name,
+      kind: ts.isTypeAliasDeclaration(decl.decl) ? 'alias' : 'interface',
+      members,
+    });
+    const refs = referencedTypeNames(decl.decl);
+    for (const ref of refs) {
+      if (visited.has(ref)) continue;
+      const resolved = resolveName(ref, decl.file);
+      if (resolved) queue.push({ name: ref, fromFile: resolved.file });
+      else visited.add(ref);
+    }
+  }
+  return shapes.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * The canonical request-shape text: the baseline's `requests` field, the diff
+ * input for the regenerate guard, and part of the shape hash. Sorted so member
+ * or type reordering is not a shape change.
+ */
+export function requestsKey(capability: string): string {
+  return canonical(requestTypes(capability));
+}
+
 /** Every `* satisfies CapabilityTables` const exported from a capability's module. */
 export async function tablesOf(file: string): Promise<CapabilityTables> {
   const loaded = (await import(file)) as Record<string, unknown>;
@@ -125,5 +335,76 @@ export async function shapeHash(capability: string): Promise<string> {
   if (!subject) throw new Error(`${capability} is not in CapabilityRegistry`);
   const iface = printedInterface(subject.file, subject.typeName);
   const tables = canonical(await tablesOf(subject.file));
-  return createHash('sha256').update(`${iface}\n--tables--\n${tables}`).digest('hex');
+  // Requests fold into the SAME hash as the interface: a request-contract
+  // change must move the version exactly like an interface change, and the
+  // regenerate script records `requests` beside the hash so it can tell the
+  // breaking member diff from an additive one (see classifyRequestChange).
+  const requests = requestsKey(capability);
+  return createHash('sha256')
+    .update(`${iface}\n--tables--\n${tables}\n--requests--\n${requests}`)
+    .digest('hex');
+}
+
+/** How a capability's request-shape text changed from one recording to the next. */
+export type RequestChangeClassification =
+  | { kind: 'unchanged' }
+  | { kind: 'additive'; note: string }
+  | { kind: 'breaking'; reasons: string[] };
+
+/**
+ * Classify a request-shape change between a baseline recording and the
+ * current code. ONLY these are breaking (the bump rule in
+ * capability-contract.ts):
+ *   - a member was removed (old providers reject the request; old consumers
+ *     stop compiling)
+ *   - a member went optional → required (consumers that omitted it break)
+ *   - a member's type changed (cannot tell widened from narrowed here, so
+ *     treated as breaking; pass --non-breaking to the regenerate script
+ *     when review agrees the widening is safe)
+ * Everything else — adding an optional member, relaxing required → optional —
+ * is additive and takes a minor per the bump rules.
+ */
+export function classifyRequestChange(
+  before: RequestTypeShape[],
+  after: RequestTypeShape[],
+): RequestChangeClassification {
+  const beforeByName = new Map(before.map((t) => [t.name, t]));
+  const afterByName = new Map(after.map((t) => [t.name, t]));
+  const reasons: string[] = [];
+  const additions: string[] = [];
+  for (const [name, oldType] of beforeByName) {
+    const newType = afterByName.get(name);
+    if (!newType) {
+      // A type leaving the reachable set is an interface change, which the
+      // interface hash and its own bump cover. Not a request-level break.
+      continue;
+    }
+    const oldMembers = new Map(oldType.members.map((m) => [m.name, m]));
+    const newMembers = new Map(newType.members.map((m) => [m.name, m]));
+    for (const [memberName, oldMember] of oldMembers) {
+      const newMember = newMembers.get(memberName);
+      if (!newMember) {
+        reasons.push(`${name}.${memberName} was removed`);
+      } else {
+        if (!oldMember.optional && newMember.optional) {
+          additions.push(`${name}.${memberName} became optional`);
+        } else if (oldMember.optional && !newMember.optional) {
+          reasons.push(`${name}.${memberName} went optional → required`);
+        } else if (oldMember.type !== newMember.type) {
+          reasons.push(
+            `${name}.${memberName} changed type (${oldMember.type} → ${newMember.type})`,
+          );
+        }
+      }
+    }
+    for (const newMember of newMembers.values()) {
+      if (!oldMembers.has(newMember.name)) {
+        if (newMember.optional) additions.push(`${name}.${newMember.name} added (optional)`);
+        else reasons.push(`${name}.${newMember.name} added as REQUIRED`);
+      }
+    }
+  }
+  if (reasons.length > 0) return { kind: 'breaking', reasons };
+  if (additions.length > 0) return { kind: 'additive', note: additions.join('; ') };
+  return { kind: 'unchanged' };
 }

package/src/policy/module-business-baseline.ts

@@ -99,6 +99,12 @@ export const CAPABILITY_NAME_BASELINE: readonly CapabilityNameRow[] = [
     count: 4,
     why: 'PERMANENT — a provider VIEW, not a module-provided capability. The name was registered so it stops being invisible to audits (celilo#1007); these references predate that and are framework plumbing, not core branching on a provider',
   },
+  {
+    file: 'apps/celilo/src/hooks/capability-loader.ts',
+    capability: 'provider_converge',
+    count: 2,
+    why: 'PERMANENT — a provider VIEW, not a module-provided capability. Core injects the generic converge every provider renders through; naming it is framework plumbing, not core branching on a provider (providers-converge-declared-state)',
+  },
   {
     file: 'apps/celilo/src/db/schema.ts',
     capability: 'web_routes',
@@ -129,6 +135,12 @@ export const CAPABILITY_NAME_BASELINE: readonly CapabilityNameRow[] = [
     count: 1,
     why: 'PERMANENT — a contract declaration with no implementation; this is the package doing its job',
   },
+  {
+    file: 'packages/capabilities/src/capability-contract.ts',
+    capability: 'provider_converge',
+    count: 1,
+    why: 'PERMANENT — a contract declaration with no implementation; this is the package doing its job',
+  },
   {
     file: 'apps/celilo/src/capabilities/well-known.ts',
     capability: 'dhcp_server',
@@ -466,6 +478,11 @@ export const SERVICE_FILENAME_BASELINE: readonly ServiceFilenameRow[] = [
     capability: 'cross_module_read',
     why: 'PERMANENT — cross_module_read is a framework privilege, not a module capability',
   },
+  {
+    file: 'apps/celilo/src/services/provider-converge.ts',
+    capability: 'provider_converge',
+    why: 'PERMANENT — provider_converge is a framework-granted view, not a module capability, and this service IS the generic mechanism it grants: it carries what a provider rendered and runs that provider own role. Naming it for one provider is what the scan exists to catch; naming it for the mechanism is the fix the scan asks for (providers-converge-declared-state)',
+  },
   {
     file: 'apps/celilo/src/services/dns-internal-records.ts',
     capability: 'dns_internal',

package/src/registry/client.test.ts

@@ -228,6 +228,71 @@ describe('RegistryClient.publish — Cargo binary protocol', () => {
   });
 });
 
+// ── RegistryClient.publish — failure bodies (ce-sxb3, celilo#1370) ───────────
+
+describe('RegistryClient.publish — failure bodies (ce-sxb3)', () => {
+  let tmpFile: string;
+  let server: ReturnType<typeof Bun.serve> | undefined;
+
+  beforeEach(async () => {
+    tmpFile = `/tmp/test-publish-ce-sxb3-${Date.now()}.netapp`;
+    await Bun.write(tmpFile, 'fake netapp content');
+  });
+
+  afterEach(async () => {
+    server?.stop(true);
+    if (await Bun.file(tmpFile).exists()) await Bun.write(tmpFile, '');
+  });
+
+  function startStubServer(body: string | null, status: number, contentType?: string): string {
+    server = Bun.serve({
+      port: 0,
+      fetch: () =>
+        new Response(body, {
+          status,
+          ...(contentType ? { headers: { 'Content-Type': contentType } } : {}),
+        }),
+    });
+    return `http://localhost:${server.port}`;
+  }
+
+  test('JSON error body reports the refusal detail and the HTTP status', async () => {
+    const client = new RegistryClient(
+      startStubServer(
+        JSON.stringify({ errors: [{ detail: 'version already exists' }] }),
+        409,
+        'application/json',
+      ),
+    );
+    await expect(
+      client.publish({ name: 'mod', version: '1.0.0+1', netappPath: tmpFile, token: 'tok' }),
+    ).rejects.toThrow('version already exists (HTTP 409)');
+  });
+
+  test('JSON null body names the HTTP status instead of crashing on err.errors', async () => {
+    const client = new RegistryClient(startStubServer('null', 500, 'application/json'));
+    await expect(
+      client.publish({ name: 'mod', version: '1.0.0+1', netappPath: tmpFile, token: 'tok' }),
+    ).rejects.toThrow('HTTP 500');
+  });
+
+  test('non-JSON body names the HTTP status', async () => {
+    const client = new RegistryClient(
+      startStubServer('<html>bad gateway</html>', 502, 'text/html'),
+    );
+    await expect(
+      client.publish({ name: 'mod', version: '1.0.0+1', netappPath: tmpFile, token: 'tok' }),
+    ).rejects.toThrow('HTTP 502');
+  });
+
+  test('empty body names the HTTP status', async () => {
+    const client = new RegistryClient(startStubServer(null, 403));
+    await expect(
+      client.publish({ name: 'mod', version: '1.0.0+1', netappPath: tmpFile, token: 'tok' }),
+    ).rejects.toThrow('HTTP 403');
+  });
+});
+
 // ── module-owner admin endpoints (ce-1ch) ─────────────────────────────────────
 
 describe('RegistryClient owner methods', () => {

package/src/registry/client.ts

@@ -305,10 +305,7 @@ export class RegistryClient {
     });
 
     if (!resp.ok) {
-      const err = (await resp.json().catch(() => ({ errors: [{ detail: resp.statusText }] }))) as {
-        errors: Array<{ detail: string }>;
-      };
-      throw new Error(err.errors?.[0]?.detail ?? `HTTP ${resp.status}`);
+      throw new Error(await this.errorDetail(resp));
     }
 
     return resp.json() as Promise<{ ok: boolean; name: string; vers: string }>;
@@ -364,10 +361,13 @@ export class RegistryClient {
 
   /** Extract `errors[0].detail` from a Cargo-protocol error body, or fall back to the status. */
   private async errorDetail(resp: Response): Promise<string> {
-    const body = (await resp.json().catch(() => ({}))) as {
+    // The body can be a JSON error object, JSON null, prose, or nothing. Only
+    // the first carries a detail; everything else falls back to the status.
+    const body = (await resp.json().catch(() => null)) as {
       errors?: Array<{ detail: string }>;
-    };
-    return body.errors?.[0]?.detail ?? `HTTP ${resp.status}`;
+    } | null;
+    const detail = body?.errors?.[0]?.detail;
+    return detail ? `${detail} (HTTP ${resp.status})` : `HTTP ${resp.status}`;
   }
 
   private async get(url: string): Promise<Response> {

package/src/secrets/storage.test.ts

@@ -7,13 +7,20 @@ import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
 import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { eq } from 'drizzle-orm';
+import { and, eq } from 'drizzle-orm';
 import { drizzle } from 'drizzle-orm/bun-sqlite';
 import { migrate } from 'drizzle-orm/bun-sqlite/migrator';
 import type { DbClient } from '../db/client';
 import * as schema from '../db/schema';
-import { systemSecrets } from '../db/schema';
-import { getSystemSecret, storeSystemSecret, systemSecretExists } from './storage';
+import { secrets, systemSecrets } from '../db/schema';
+import { decryptSecret } from './encryption';
+import { getOrCreateMasterKey } from './master-key';
+import {
+  getSystemSecret,
+  recordProviderSecret,
+  storeSystemSecret,
+  systemSecretExists,
+} from './storage';
 
 describe('secret storage', () => {
   let testDir: string;
@@ -112,4 +119,63 @@ describe('secret storage', () => {
     const decrypted = await getSystemSecret('test.long', testDb);
     expect(decrypted).toBe(longSecret);
   });
+
+  describe('recordProviderSecret (hook-owned-state D3)', () => {
+    const providerRow = (moduleId: string, name: string) =>
+      testDb
+        .select()
+        .from(secrets)
+        .where(and(eq(secrets.moduleId, moduleId), eq(secrets.name, name)))
+        .get();
+
+    const decryptRow = async (moduleId: string, name: string) => {
+      const row = providerRow(moduleId, name);
+      expect(row).toBeDefined();
+      if (!row) throw new Error('provider secret row missing');
+      const mk = await getOrCreateMasterKey();
+      return decryptSecret(
+        { encryptedValue: row.encryptedValue, iv: row.iv, authTag: row.authTag },
+        mk,
+      );
+    };
+
+    test('records an encrypted secret onto the provider module', async () => {
+      await recordProviderSecret(testDb, 'some-provider', 'api_key', 'minted-value');
+
+      expect(await decryptRow('some-provider', 'api_key')).toBe('minted-value');
+      // Encrypted on disk, never the plaintext.
+      const row = providerRow('some-provider', 'api_key');
+      expect(row && row.encryptedValue !== 'minted-value').toBe(true);
+    });
+
+    test('upserts on (moduleId, name) instead of duplicating', async () => {
+      await recordProviderSecret(testDb, 'some-provider', 'api_key', 'first');
+      await recordProviderSecret(testDb, 'some-provider', 'api_key', 'second');
+
+      const rows = testDb.select().from(secrets).all();
+      expect(rows).toHaveLength(1);
+      expect(await decryptRow('some-provider', 'api_key')).toBe('second');
+    });
+
+    test('keeps two providers with the same secret name distinct', async () => {
+      await recordProviderSecret(testDb, 'provider-a', 'api_key', 'value-a');
+      await recordProviderSecret(testDb, 'provider-b', 'api_key', 'value-b');
+
+      const rows = testDb.select().from(secrets).all();
+      expect(rows).toHaveLength(2);
+    });
+
+    test('refuses an empty module id, name, or value', async () => {
+      await expect(recordProviderSecret(testDb, '', 'api_key', 'v')).rejects.toThrow(
+        'providerModuleId is required',
+      );
+      await expect(recordProviderSecret(testDb, 'p', '  ', 'v')).rejects.toThrow(
+        'name is required',
+      );
+      await expect(recordProviderSecret(testDb, 'p', 'api_key', '')).rejects.toThrow(
+        'value is required',
+      );
+      expect(testDb.select().from(secrets).all()).toHaveLength(0);
+    });
+  });
 });