spine-framework 0.3.145 → 0.4.1

package/.framework/tests/unit/ai-interactions.test.ts

@@ -0,0 +1,81 @@
+// CIL[DOC-MACRO purpose="Unit tests for createInteraction's optional type_slug override in ai-interactions.ts"]
+// CIL[DOC-RESPONSIBILITY responsibility="Assert body.type_slug selects the resolved item type (default ai_feedback_record), that a missing type reports the resolved slug in the skip reason, and required-field validation is unchanged"]
+// CIL[DOC-CONTEXT module="ai-interactions.test" layer="test-unit" related_files=".framework/functions/ai-interactions.ts"]
+// CIL[DOC-CONTRACT inputs="mocked middleware/db/resolve-ids/admin-data/audit/funnel" outputs="expect assertions on resolveTypeId args, create payloads, and skip reasons" errors="none" side_effects="registers vi.mock factories"]
+// CIL[DOC-AUDIENCE audience="test"]
+// CIL[DOC-STABILITY stability="stable"]
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+vi.mock('../../functions/_shared/middleware.ts', () => ({
+  createHandler: (fn: any) => fn,
+}))
+vi.mock('../../functions/_shared/db.ts', () => ({
+  adminDb: { from: vi.fn(), rpc: vi.fn() },
+}))
+vi.mock('../../functions/_shared/resolve-ids.ts', () => ({
+  resolveTypeId: vi.fn().mockImplementation((_k: string, slug: string) => Promise.resolve(`t-${slug}`)),
+}))
+vi.mock('../../functions/admin-data.ts', () => ({
+  create: vi.fn().mockResolvedValue({ id: 'created' }),
+  update: vi.fn().mockResolvedValue({ id: 'updated' }),
+}))
+vi.mock('../../functions/_shared/audit.ts', () => ({
+  emitLog: vi.fn().mockResolvedValue(undefined),
+}))
+vi.mock('../../functions/_shared/funnel.ts', () => ({
+  emitSignal: vi.fn().mockResolvedValue(undefined),
+}))
+
+import { resolveTypeId } from '../../functions/_shared/resolve-ids.ts'
+import { create } from '../../functions/admin-data.ts'
+import { createInteraction } from '../../functions/ai-interactions.ts'
+
+function ctx(): any {
+  return {
+    accountId: 'acct-1',
+    principal: { id: 'person-1', type: 'human', roles: ['member'] },
+    requestId: 'req-1',
+  }
+}
+
+describe('createInteraction — optional type_slug', () => {
+  beforeEach(() => vi.clearAllMocks())
+
+  it('defaults to the ai_feedback_record item type', async () => {
+    await createInteraction(ctx(), { thread_id: 'thr-1', kb_candidate: true })
+    expect(resolveTypeId).toHaveBeenCalledWith('item', 'ai_feedback_record')
+    expect(create).toHaveBeenCalledWith(
+      ctx(),
+      expect.objectContaining({ entity: 'items', type_id: 't-ai_feedback_record' })
+    )
+  })
+
+  it('resolves an app-namespaced type when type_slug is provided', async () => {
+    await createInteraction(ctx(), {
+      type_slug: 'demo_feedback_record',
+      thread_id: 'thr-1',
+      ai_message_id: 'm-1',
+      kb_candidate: true,
+    })
+    expect(resolveTypeId).toHaveBeenCalledWith('item', 'demo_feedback_record')
+    const [, payload] = vi.mocked(create).mock.calls[0] as any[]
+    expect(payload.type_id).toBe('t-demo_feedback_record')
+    expect(payload.data.ai_message_id).toBe('m-1')
+    expect(payload.data.kb_candidate).toBe(true)
+  })
+
+  it('reports the resolved slug in the skip reason when the type is missing', async () => {
+    vi.mocked(resolveTypeId).mockRejectedValueOnce(new Error('Type not found: item/demo_feedback_record'))
+    const res = await createInteraction(ctx(), {
+      type_slug: 'demo_feedback_record',
+      thread_id: 'thr-1',
+    })
+    expect(res).toEqual({ skipped: true, reason: 'demo_feedback_record type not found' })
+    expect(create).not.toHaveBeenCalled()
+  })
+
+  it('still requires thread_id or ai_message_id', async () => {
+    await expect(createInteraction(ctx(), { type_slug: 'demo_feedback_record' }))
+      .rejects.toThrow('thread_id or ai_message_id is required')
+  })
+})

package/.framework/tests/unit/app-manifest.test.ts

@@ -0,0 +1,359 @@
+// CIL[BEGIN stable_id="~/.framework/tests/unit/app-manifest.test.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/tests/unit/app-manifest.test.ts"]
+// CIL[DOC-MACRO purpose="Import Vitest, filesystem fixture utilities, and both manifest implementations."]
+// CIL[DOC-RESPONSIBILITY responsibility="Import Vitest, filesystem fixture utilities, and both manifest implementations."]
+// CIL[DOC-CONTEXT module="tests/unit" layer="test-unit" related_files=".framework/functions/_shared/app-manifest.ts,.framework/mcp/shared/app-manifest.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Import Vitest, filesystem fixture utilities, and both manifest implementations." notable_decisions=""]
+// CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="experimental"]
+// CIL[DOC-AUDIENCE audience="framework contributors"]
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, symlinkSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, relative } from 'node:path'
+import * as runtimeMod from '../../functions/_shared/app-manifest.ts'
+import * as mcpMod from '../../../.framework/mcp/shared/app-manifest.ts'
+// CIL[END stable_id="~/.framework/tests/unit/app-manifest.test.ts:module_header:module_header"]
+
+// CIL[BEGIN stable_id="~/.framework/tests/unit/app-manifest.test.ts:modules:constant" type="constant" identity="modules" parent="none"]
+// CIL[DOC-MACRO purpose="Pair runtime and MCP manifest implementations for identical behavior tests."]
+// CIL[DOC-RESPONSIBILITY responsibility="Pair runtime and MCP manifest implementations for identical behavior tests."]
+// CIL[DOC-CONTEXT module="tests/unit" layer="test-unit" related_files=".framework/functions/_shared/app-manifest.ts,.framework/mcp/shared/app-manifest.ts"]
+// CIL[DOC-CONTRACT inputs="Imported runtimeMod and mcpMod modules" outputs="Readonly module-label pairs" errors="Assertion or fixture failures propagate to Vitest" side_effects="Initializes a module-local constant"]
+// CIL[DOC-MICRO logic_summary="Pair runtime and MCP manifest implementations for identical behavior tests." notable_decisions=""]
+// CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="experimental"]
+// CIL[DOC-AUDIENCE audience="framework contributors"]
+const modules = [
+  ['runtime .framework/functions/_shared/app-manifest.ts', runtimeMod],
+  ['mcp .framework/mcp/shared/app-manifest.ts', mcpMod],
+] as const
+// CIL[END stable_id="~/.framework/tests/unit/app-manifest.test.ts:modules:constant"]
+
+// CIL[BEGIN stable_id="~/.framework/tests/unit/app-manifest.test.ts:root:variable" type="variable" identity="root" parent="none"]
+// CIL[DOC-MACRO purpose="Declare the temporary repository root used by fixture hooks."]
+// CIL[DOC-RESPONSIBILITY responsibility="Declare the temporary repository root used by fixture hooks."]
+// CIL[DOC-CONTEXT module="tests/unit" layer="test-unit" related_files=".framework/functions/_shared/app-manifest.ts,.framework/mcp/shared/app-manifest.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Mutable root path" errors="Assertion or fixture failures propagate to Vitest" side_effects="Declares module-local fixture state"]
+// CIL[DOC-MICRO logic_summary="Declare the temporary repository root used by fixture hooks." notable_decisions=""]
+// CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="experimental"]
+// CIL[DOC-AUDIENCE audience="framework contributors"]
+let root: string
+// CIL[END stable_id="~/.framework/tests/unit/app-manifest.test.ts:root:variable"]
+// CIL[BEGIN stable_id="~/.framework/tests/unit/app-manifest.test.ts:savedrepopath:variable" type="variable" identity="savedRepoPath" parent="none"]
+// CIL[DOC-MACRO purpose="Declare the saved REPO_PATH value restored after each fixture."]
+// CIL[DOC-RESPONSIBILITY responsibility="Declare the saved REPO_PATH value restored after each fixture."]
+// CIL[DOC-CONTEXT module="tests/unit" layer="test-unit" related_files=".framework/functions/_shared/app-manifest.ts,.framework/mcp/shared/app-manifest.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Optional saved environment value" errors="Assertion or fixture failures propagate to Vitest" side_effects="Declares module-local fixture state"]
+// CIL[DOC-MICRO logic_summary="Declare the saved REPO_PATH value restored after each fixture." notable_decisions=""]
+// CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="experimental"]
+// CIL[DOC-AUDIENCE audience="framework contributors"]
+let savedRepoPath: string | undefined
+// CIL[END stable_id="~/.framework/tests/unit/app-manifest.test.ts:savedrepopath:variable"]
+
+// CIL[BEGIN stable_id="~/.framework/tests/unit/app-manifest.test.ts:fixture_setup:block" type="block" identity="fixture_setup" parent="none"]
+// CIL[DOC-MACRO purpose="Register a beforeEach hook that creates a temporary repo and saves REPO_PATH."]
+// CIL[DOC-RESPONSIBILITY responsibility="Register a beforeEach hook that creates a temporary repo and saves REPO_PATH."]
+// CIL[DOC-CONTEXT module="tests/unit" layer="test-unit" related_files=".framework/functions/_shared/app-manifest.ts,.framework/mcp/shared/app-manifest.ts"]
+// CIL[DOC-CONTRACT inputs="Vitest beforeEach lifecycle" outputs="Temporary root and saved environment state" errors="Assertion or fixture failures propagate to Vitest" side_effects="Registers a fixture hook; the hook creates a temporary directory"]
+// CIL[DOC-MICRO logic_summary="Register a beforeEach hook that creates a temporary repo and saves REPO_PATH." notable_decisions=""]
+// CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="experimental"]
+// CIL[DOC-AUDIENCE audience="framework contributors"]
+beforeEach(() => {
+  root = mkdtempSync(join(tmpdir(), 'spine-app-manifest-'))
+  savedRepoPath = process.env.REPO_PATH
+})
+// CIL[END stable_id="~/.framework/tests/unit/app-manifest.test.ts:fixture_setup:block"]
+
+// CIL[BEGIN stable_id="~/.framework/tests/unit/app-manifest.test.ts:fixture_cleanup:block" type="block" identity="fixture_cleanup" parent="none"]
+// CIL[DOC-MACRO purpose="Register an afterEach hook that removes the fixture repo and restores REPO_PATH."]
+// CIL[DOC-RESPONSIBILITY responsibility="Register an afterEach hook that removes the fixture repo and restores REPO_PATH."]
+// CIL[DOC-CONTEXT module="tests/unit" layer="test-unit" related_files=".framework/functions/_shared/app-manifest.ts,.framework/mcp/shared/app-manifest.ts"]
+// CIL[DOC-CONTRACT inputs="Fixture root and savedRepoPath" outputs="Cleaned fixture and restored environment" errors="Assertion or fixture failures propagate to Vitest" side_effects="Registers a hook that removes only the created directory and restores an environment variable"]
+// CIL[DOC-MICRO logic_summary="Register an afterEach hook that removes the fixture repo and restores REPO_PATH." notable_decisions=""]
+// CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="experimental"]
+// CIL[DOC-AUDIENCE audience="framework contributors"]
+afterEach(() => {
+  rmSync(root, { recursive: true, force: true })
+  if (savedRepoPath === undefined) delete process.env.REPO_PATH
+  else process.env.REPO_PATH = savedRepoPath
+})
+// CIL[END stable_id="~/.framework/tests/unit/app-manifest.test.ts:fixture_cleanup:block"]
+
+// CIL[BEGIN stable_id="~/.framework/tests/unit/app-manifest.test.ts:writejson:function" type="function" identity="writeJson" parent="none"]
+// CIL[DOC-MACRO purpose="Create a fixture directory and write supplied JSON or raw text to its named file."]
+// CIL[DOC-RESPONSIBILITY responsibility="Create a fixture directory and write supplied JSON or raw text to its named file."]
+// CIL[DOC-CONTEXT module="tests/unit" layer="test-unit" related_files=".framework/functions/_shared/app-manifest.ts,.framework/mcp/shared/app-manifest.ts"]
+// CIL[DOC-CONTRACT inputs="dir: string, data: unknown, file: string default manifest.json" outputs="void" errors="Assertion or fixture failures propagate to Vitest" side_effects="Creates fixture directories and writes a fixture file"]
+// CIL[DOC-MICRO logic_summary="Create a fixture directory and write supplied JSON or raw text to its named file." notable_decisions=""]
+// CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="experimental"]
+// CIL[DOC-AUDIENCE audience="framework contributors"]
+function writeJson(dir: string, data: unknown, file = 'manifest.json'): void {
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(join(dir, file), typeof data === 'string' ? data : JSON.stringify(data))
+}
+// CIL[END stable_id="~/.framework/tests/unit/app-manifest.test.ts:writejson:function"]
+
+// CIL[BEGIN stable_id="~/.framework/tests/unit/app-manifest.test.ts:valid:constant" type="constant" identity="VALID" parent="none"]
+// CIL[DOC-MACRO purpose="Define minimal valid app manifest data for isolated tests."]
+// CIL[DOC-RESPONSIBILITY responsibility="Define minimal valid app manifest data for isolated tests."]
+// CIL[DOC-CONTEXT module="tests/unit" layer="test-unit" related_files=".framework/functions/_shared/app-manifest.ts,.framework/mcp/shared/app-manifest.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Fixture manifest with name, slug, routes, and nav_items" errors="Assertion or fixture failures propagate to Vitest" side_effects="Initializes a module-local constant"]
+// CIL[DOC-MICRO logic_summary="Define minimal valid app manifest data for isolated tests." notable_decisions=""]
+// CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="experimental"]
+// CIL[DOC-AUDIENCE audience="framework contributors"]
+const VALID = {
+  name: 'Test App',
+  slug: 'test-app',
+  routes: ['/x'],
+  nav_items: [],
+}
+// CIL[END stable_id="~/.framework/tests/unit/app-manifest.test.ts:valid:constant"]
+
+// CIL[BEGIN stable_id="~/.framework/tests/unit/app-manifest.test.ts:manifest_behavior_suites:block" type="block" identity="manifest_behavior_suites" parent="none"]
+// CIL[DOC-MACRO purpose="Register the same loader and merger assertions for runtime and MCP implementations."]
+// CIL[DOC-RESPONSIBILITY responsibility="Register the same loader and merger assertions for runtime and MCP implementations."]
+// CIL[DOC-CONTEXT module="tests/unit" layer="test-unit" related_files=".framework/functions/_shared/app-manifest.ts,.framework/mcp/shared/app-manifest.ts"]
+// CIL[DOC-CONTRACT inputs="modules, fixture state, VALID, writeJson" outputs="Vitest loader and merger test cases" errors="Assertion or fixture failures propagate to Vitest" side_effects="Registers test cases that read and write temporary files and temporarily select REPO_PATH"]
+// CIL[DOC-MICRO logic_summary="Register the same loader and merger assertions for runtime and MCP implementations." notable_decisions=""]
+// CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="experimental"]
+// CIL[DOC-AUDIENCE audience="framework contributors"]
+for (const [label, mod] of modules) {
+  describe(`loadManifest (${label})`, () => {
+    beforeEach(() => mod.clearManifestCache())
+
+    it('returns null for a missing file', () => {
+      expect(mod.loadManifest('custom/apps/none/manifest.json', root)).toBeNull()
+    })
+
+    it('returns null for malformed JSON', () => {
+      writeJson(root, '{not json')
+      expect(mod.loadManifest('manifest.json', root)).toBeNull()
+    })
+
+    it('returns null for JSON null', () => {
+      writeJson(root, 'null')
+      expect(mod.loadManifest('manifest.json', root)).toBeNull()
+    })
+
+    it('returns null for a JSON array root', () => {
+      writeJson(root, [{ slug: 'x', name: 'x' }])
+      expect(mod.loadManifest('manifest.json', root)).toBeNull()
+    })
+
+    it('returns null for a JSON primitive root', () => {
+      for (const body of ['"x"', '7', 'true']) {
+        writeJson(root, body)
+        expect(mod.loadManifest('manifest.json', root), body).toBeNull()
+      }
+    })
+
+    it('returns null when name or slug is missing or not a nonempty string', () => {
+      writeJson(root, { name: 'x' })
+      expect(mod.loadManifest('manifest.json', root)).toBeNull()
+      writeJson(root, { slug: 'x' })
+      expect(mod.loadManifest('manifest.json', root)).toBeNull()
+      writeJson(root, { slug: '', name: 'x' })
+      expect(mod.loadManifest('manifest.json', root)).toBeNull()
+      writeJson(root, { slug: 7, name: 'x' })
+      expect(mod.loadManifest('manifest.json', root)).toBeNull()
+      writeJson(root, { slug: 'x', name: '   ' })
+      expect(mod.loadManifest('manifest.json', root)).toBeNull()
+    })
+
+    it('returns null for a slug outside the allowed charset', () => {
+      for (const slug of ['Demo-App', 'demo_app', '9demo', '-demo', 'demo app']) {
+        writeJson(root, { ...VALID, slug })
+        expect(mod.loadManifest('manifest.json', root), slug).toBeNull()
+      }
+    })
+
+    it('returns null when required_roles is not an array of nonempty strings', () => {
+      for (const rr of ['member', ['member', 5], ['member', ''], [null], ['member', '   ']]) {
+        writeJson(root, { ...VALID, required_roles: rr })
+        expect(mod.loadManifest('manifest.json', root), JSON.stringify(rr)).toBeNull()
+      }
+    })
+
+    it('defaults required_roles to [] when absent and loads a valid manifest', () => {
+      writeJson(root, VALID)
+      const m = mod.loadManifest('manifest.json', root)
+      expect(m).not.toBeNull()
+      expect(m!.slug).toBe('test-app')
+      expect(m!.required_roles).toEqual([])
+    })
+
+    it('keeps an OR-role array verbatim', () => {
+      writeJson(root, { ...VALID, required_roles: ['member', 'member_admin'] })
+      const m = mod.loadManifest('manifest.json', root)
+      expect(m!.required_roles).toEqual(['member', 'member_admin'])
+    })
+
+    it('rejects a lexical path escaping the project root', () => {
+      const outside = mkdtempSync(join(tmpdir(), 'spine-outside-'))
+      try {
+        writeJson(outside, VALID)
+        expect(mod.loadManifest(relative(root, join(outside, 'manifest.json')), root)).toBeNull()
+        expect(mod.loadManifest(join(outside, 'manifest.json'), root)).toBeNull()
+      } finally {
+        rmSync(outside, { recursive: true, force: true })
+      }
+    })
+
+    it('rejects a manifest that is an external symlink', () => {
+      const outside = mkdtempSync(join(tmpdir(), 'spine-outside-'))
+      try {
+        writeJson(outside, VALID)
+        mkdirSync(join(root, 'custom/apps/ext'), { recursive: true })
+        symlinkSync(join(outside, 'manifest.json'), join(root, 'custom/apps/ext/manifest.json'))
+        expect(mod.loadManifest('custom/apps/ext/manifest.json', root)).toBeNull()
+      } finally {
+        rmSync(outside, { recursive: true, force: true })
+      }
+    })
+
+    it('caches by canonical path so the same relative path in different roots never collides', () => {
+      const rootB = mkdtempSync(join(tmpdir(), 'spine-app-manifest-b-'))
+      try {
+        writeJson(join(root, 'custom/apps/a'), { ...VALID, slug: 'a-one' })
+        writeJson(join(rootB, 'custom/apps/a'), { ...VALID, slug: 'a-two' })
+        const m1 = mod.loadManifest('custom/apps/a/manifest.json', root)
+        const m2 = mod.loadManifest('custom/apps/a/manifest.json', rootB)
+        const m1Again = mod.loadManifest('custom/apps/a/manifest.json', root)
+        expect(m1!.slug).toBe('a-one')
+        expect(m2!.slug).toBe('a-two')
+        expect(m1Again!.slug).toBe('a-one')
+      } finally {
+        rmSync(rootB, { recursive: true, force: true })
+      }
+    })
+  })
+
+  describe(`mergeWithManifest (${label})`, () => {
+    beforeEach(() => {
+      mod.clearManifestCache()
+      process.env.REPO_PATH = root
+    })
+
+    const dbRecord = {
+      id: 'db-1',
+      slug: 'db-slug',
+      config_source: 'manifest',
+      manifest_path: 'custom/apps/test-app/manifest.json',
+      route_prefix: '/test-app',
+      renderer: 'custom',
+      config: { knowledge: { account: true } },
+      required_roles: ['db_role_a', 'db_role_b'],
+      is_active: true,
+      is_system: false,
+      account_id: 'acct-1',
+      ownership: 'account',
+    }
+
+    it('manifest role array wins and db route_prefix/renderer/config are retained', () => {
+      writeJson(join(root, 'custom/apps/test-app'), { ...VALID, required_roles: ['member', 'member_admin'] })
+      const merged = mod.mergeWithManifest(dbRecord)
+      expect(merged.required_roles).toEqual(['member', 'member_admin'])
+      expect(merged.route_prefix).toBe('/test-app')
+      expect(merged.renderer).toBe('custom')
+      expect(merged.config).toEqual({ knowledge: { account: true } })
+      expect(merged._source).toBe('manifest')
+      expect(merged.id).toBe('db-1')
+    })
+
+    it('keeps an empty manifest role array verbatim', () => {
+      writeJson(join(root, 'custom/apps/test-app'), { ...VALID, required_roles: [] })
+      const merged = mod.mergeWithManifest(dbRecord)
+      expect(merged.required_roles).toEqual([])
+      expect(merged.min_role).toBeNull()
+    })
+
+    it('falls back to the db record preserving an existing required_roles array including empty', () => {
+      const merged = mod.mergeWithManifest({ slug: 'x', config_source: 'database', required_roles: [], min_role: 'member' })
+      expect(merged.required_roles).toEqual([])
+      expect(merged._source).toBe('database')
+      const merged2 = mod.mergeWithManifest({ slug: 'x', config_source: 'database', required_roles: ['a', 'b'] })
+      expect(merged2.required_roles).toEqual(['a', 'b'])
+    })
+
+    it('derives required_roles from min_role only when db.required_roles is absent', () => {
+      const merged = mod.mergeWithManifest({ slug: 'x', config_source: 'database', min_role: 'member' })
+      expect(merged.required_roles).toEqual(['member'])
+      const merged2 = mod.mergeWithManifest({ slug: 'x', config_source: 'database' })
+      expect(merged2.required_roles).toEqual([])
+    })
+
+    it('returns the db fallback tagged database when the manifest cannot be loaded', () => {
+      const merged = mod.mergeWithManifest({ ...dbRecord, manifest_path: 'custom/apps/missing/manifest.json' })
+      expect(merged._source).toBe('database (manifest missing)')
+      expect(merged.required_roles).toEqual(['db_role_a', 'db_role_b'])
+    })
+
+    it('returns null for a falsy record', () => {
+      expect(mod.mergeWithManifest(null)).toBeNull()
+    })
+  })
+}
+// CIL[END stable_id="~/.framework/tests/unit/app-manifest.test.ts:manifest_behavior_suites:block"]
+
+// CIL[BEGIN stable_id="~/.framework/tests/unit/app-manifest.test.ts:discovery_suite:block" type="block" identity="discovery_suite" parent="none"]
+// CIL[DOC-MACRO purpose="Register discovery tests for sorted arbitrary apps, absent workspaces, slug mismatch, and safe symlinks."]
+// CIL[DOC-RESPONSIBILITY responsibility="Register discovery tests for sorted arbitrary apps, absent workspaces, slug mismatch, and safe symlinks."]
+// CIL[DOC-CONTEXT module="tests/unit" layer="test-unit" related_files=".framework/functions/_shared/app-manifest.ts,.framework/mcp/shared/app-manifest.ts"]
+// CIL[DOC-CONTRACT inputs="runtimeMod and temporary fixture state" outputs="Vitest discovery test cases" errors="Assertion or fixture failures propagate to Vitest" side_effects="Registers tests using temporary directories and symlinks"]
+// CIL[DOC-MICRO logic_summary="Register discovery tests for sorted arbitrary apps, absent workspaces, slug mismatch, and safe symlinks." notable_decisions=""]
+// CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="experimental"]
+// CIL[DOC-AUDIENCE audience="framework contributors"]
+describe('discoverManifests (runtime)', () => {
+  beforeEach(() => runtimeMod.clearManifestCache())
+
+  it('enumerates custom/apps children sorted lexically', () => {
+    writeJson(join(root, 'custom/apps/zeta'), { ...VALID, slug: 'zeta' })
+    writeJson(join(root, 'custom/apps/alpha'), { ...VALID, slug: 'alpha' })
+    writeJson(join(root, 'custom/apps/mid'), { ...VALID, slug: 'mid' })
+    const found = runtimeMod.discoverManifests(root)
+    expect(found).toEqual([
+      { slug: 'alpha', path: 'custom/apps/alpha/manifest.json' },
+      { slug: 'mid', path: 'custom/apps/mid/manifest.json' },
+      { slug: 'zeta', path: 'custom/apps/zeta/manifest.json' },
+    ])
+  })
+
+  it('returns [] when custom/apps is absent', () => {
+    expect(runtimeMod.discoverManifests(root)).toEqual([])
+  })
+
+  it('skips a directory whose name does not match the manifest slug', () => {
+    writeJson(join(root, 'custom/apps/renamed'), { ...VALID, slug: 'other-slug' })
+    writeJson(join(root, 'custom/apps/good'), { ...VALID, slug: 'good' })
+    const found = runtimeMod.discoverManifests(root)
+    expect(found).toEqual([{ slug: 'good', path: 'custom/apps/good/manifest.json' }])
+  })
+
+  it('skips an external symlink app dir but inspects an internal symlink dir', () => {
+    const outside = mkdtempSync(join(tmpdir(), 'spine-outside-'))
+    try {
+      writeJson(outside, { ...VALID, slug: 'external' })
+      mkdirSync(join(root, 'custom/apps'), { recursive: true })
+      symlinkSync(outside, join(root, 'custom/apps/external'))
+
+      const internalTarget = join(root, 'internal-target/linked')
+      writeJson(internalTarget, { ...VALID, slug: 'linked' })
+      symlinkSync(internalTarget, join(root, 'custom/apps/linked'))
+
+      const found = runtimeMod.discoverManifests(root)
+      expect(found).toEqual([{ slug: 'linked', path: 'custom/apps/linked/manifest.json' }])
+    } finally {
+      rmSync(outside, { recursive: true, force: true })
+    }
+  })
+})
+// CIL[END stable_id="~/.framework/tests/unit/app-manifest.test.ts:discovery_suite:block"]

package/.framework/tests/unit/assembly-scripts.test.ts

@@ -0,0 +1,172 @@
+// CIL[BEGIN stable_id="~/.framework/tests/unit/assembly-scripts.test.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/tests/unit/assembly-scripts.test.ts"]
+// CIL[DOC-MACRO purpose="Fixture-based invariants for the assemble scripts: per-app layout, public-asset collision detection, duplicate-handler detection, dev-alias symlink handling."]
+// CIL[DOC-RESPONSIBILITY responsibility="Run scripts/assemble-frontend.sh and scripts/assemble-functions.sh against fixture project roots and assert layout + collision semantics."]
+// CIL[DOC-CONTEXT module="assembly-scripts.test" layer="test" related_files="scripts/assemble-frontend.sh,scripts/assemble-functions.sh"]
+// CIL[DOC-CONTRACT inputs="fixture roots under os.tmpdir() via SPINE_PROJECT_ROOT" outputs="exit-code + file-existence assertions" errors="none" side_effects="creates+removes temp dirs"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-NOTE type="harness" content="Both scripts honour SPINE_PROJECT_ROOT so tests never touch the real .assembled tree. NB: .framework/scripts/ holds stale packaged copies — tests must point at /scripts."]
+// CIL[END stable_id="~/.framework/tests/unit/assembly-scripts.test.ts:module_header:module_header"]
+import { describe, it, expect, afterEach } from 'vitest'
+import {
+  mkdtempSync, mkdirSync, writeFileSync, symlinkSync,
+  existsSync, rmSync, readFileSync,
+} from 'fs'
+import { tmpdir } from 'os'
+import { join, resolve } from 'path'
+import { spawnSync } from 'child_process'
+
+// NB: .framework/scripts/ contains stale packaged copies of these scripts —
+// the tests must run the live ones at repo root /scripts.
+const REPO = resolve(__dirname, '../../..')
+const FRONTEND_SCRIPT = join(REPO, 'scripts/assemble-frontend.sh')
+const FUNCTIONS_SCRIPT = join(REPO, 'scripts/assemble-functions.sh')
+
+const roots: string[] = []
+
+function makeRoot(): string {
+  const root = mkdtempSync(join(tmpdir(), 'spine-asm-'))
+  roots.push(root)
+  mkdirSync(join(root, '.framework/src'), { recursive: true })
+  writeFileSync(join(root, '.framework/src/main.tsx'), 'export {}')
+  mkdirSync(join(root, '.framework/functions'), { recursive: true })
+  writeFileSync(join(root, '.framework/functions/handler.ts'), 'export const framework = true\n')
+  mkdirSync(join(root, 'custom/apps'), { recursive: true })
+  return root
+}
+
+function addApp(root: string, slug: string, files: Record<string, string>) {
+  for (const [rel, content] of Object.entries(files)) {
+    const p = join(root, 'custom/apps', slug, rel)
+    mkdirSync(join(p, '..'), { recursive: true })
+    writeFileSync(p, content)
+  }
+}
+
+function run(script: string, root: string) {
+  return spawnSync('bash', [script], {
+    env: { ...process.env, SPINE_PROJECT_ROOT: root },
+    encoding: 'utf8',
+    timeout: 60_000,
+  })
+}
+
+afterEach(() => {
+  while (roots.length) rmSync(roots.pop()!, { recursive: true, force: true })
+})
+
+describe('assemble-frontend.sh', () => {
+  it('lays out each app under src/<slug>/ with no basename flattening', () => {
+    const root = makeRoot()
+    addApp(root, 'appone', {
+      'index.tsx': 'export {}',
+      'components/widget.tsx': 'export {}',
+      'functions/fn.ts': 'export {}',
+      'seed/types.json': '{}',
+      'public/icon.svg': '<svg/>',
+      '.hidden': 'x',
+    })
+    const r = run(FRONTEND_SCRIPT, root)
+    expect(r.status, r.stderr).toBe(0)
+    const src = join(root, '.assembled/src')
+    expect(existsSync(join(src, 'appone/index.tsx'))).toBe(true)
+    expect(existsSync(join(src, 'appone/components/widget.tsx'))).toBe(true)
+    // no flattening: app's components must not appear at src root
+    expect(existsSync(join(src, 'components/widget.tsx'))).toBe(false)
+    // exclusions
+    expect(existsSync(join(src, 'appone/functions'))).toBe(false)
+    expect(existsSync(join(src, 'appone/seed'))).toBe(false)
+    expect(existsSync(join(src, 'appone/.hidden'))).toBe(false)
+    // public assets merge into project public/
+    expect(existsSync(join(root, 'public/icon.svg'))).toBe(true)
+  })
+
+  it('hard-errors when two apps publish the same public path with different content', () => {
+    const root = makeRoot()
+    addApp(root, 'appone', { 'public/x.txt': 'one' })
+    addApp(root, 'apptwo', { 'public/x.txt': 'two' })
+    const r = run(FRONTEND_SCRIPT, root)
+    expect(r.status).not.toBe(0)
+    expect(r.stderr).toContain('x.txt')
+    expect(r.stderr).toContain('appone')
+    expect(r.stderr).toContain('apptwo')
+  })
+
+  it('also catches app-vs-framework public collisions', () => {
+    const root = makeRoot()
+    mkdirSync(join(root, '.framework/public'), { recursive: true })
+    writeFileSync(join(root, '.framework/public/logo.svg'), 'framework')
+    addApp(root, 'appone', { 'public/logo.svg': 'app' })
+    const r = run(FRONTEND_SCRIPT, root)
+    expect(r.status).not.toBe(0)
+    expect(r.stderr).toContain('logo.svg')
+  })
+
+  it('tolerates identical duplicate public assets', () => {
+    const root = makeRoot()
+    addApp(root, 'appone', { 'public/x.txt': 'same-bytes' })
+    addApp(root, 'apptwo', { 'public/x.txt': 'same-bytes' })
+    const r = run(FRONTEND_SCRIPT, root)
+    expect(r.status, r.stderr).toBe(0)
+    expect(readFileSync(join(root, 'public/x.txt'), 'utf8')).toBe('same-bytes')
+  })
+})
+
+describe('assemble-functions.sh', () => {
+  it('hard-errors when a custom function basename collides with a staged file', () => {
+    const root = makeRoot()
+    addApp(root, 'appone', { 'functions/handler.ts': 'export const app = true\n' })
+    const r = run(FUNCTIONS_SCRIPT, root)
+    expect(r.status).not.toBe(0)
+    expect(r.stderr).toContain('handler.ts')
+    expect(r.stderr).toContain('appone')
+  })
+
+  it('hard-errors on app-vs-app basename collisions', () => {
+    const root = makeRoot()
+    addApp(root, 'appone', { 'functions/dup.ts': 'export {}' })
+    addApp(root, 'apptwo', { 'functions/dup.ts': 'export {}' })
+    const r = run(FUNCTIONS_SCRIPT, root)
+    expect(r.status).not.toBe(0)
+    expect(r.stderr).toContain('dup.ts')
+    expect(r.stderr).toContain('appone')
+    expect(r.stderr).toContain('apptwo')
+  })
+
+  it('silently skips symlink dev-aliases into .framework/functions', () => {
+    const root = makeRoot()
+    const appFns = join(root, 'custom/apps/appone/functions')
+    mkdirSync(appFns, { recursive: true })
+    symlinkSync(
+      '../../../../.framework/functions/handler.ts',
+      join(appFns, 'handler.ts')
+    )
+    const r = run(FUNCTIONS_SCRIPT, root)
+    expect(r.status, r.stderr).toBe(0)
+    // staged file is the framework copy, not the alias
+    expect(
+      readFileSync(join(root, '.assembled/netlify/functions/handler.ts'), 'utf8')
+    ).toContain('framework')
+  })
+
+  it('still hard-errors on symlinks that resolve outside .framework/functions', () => {
+    const root = makeRoot()
+    const appFns = join(root, 'custom/apps/appone/functions')
+    mkdirSync(appFns, { recursive: true })
+    writeFileSync(join(root, 'custom/apps/appone/real-handler.ts'), 'export {}')
+    symlinkSync('../real-handler.ts', join(appFns, 'handler.ts'))
+    const r = run(FUNCTIONS_SCRIPT, root)
+    expect(r.status).not.toBe(0)
+    expect(r.stderr).toContain('handler.ts')
+  })
+
+  it('stages non-colliding custom functions normally', () => {
+    const root = makeRoot()
+    addApp(root, 'appone', { 'functions/custom_thing.ts': 'export {}' })
+    const r = run(FUNCTIONS_SCRIPT, root)
+    expect(r.status, r.stderr).toBe(0)
+    expect(
+      existsSync(join(root, '.assembled/netlify/functions/custom_thing.ts'))
+    ).toBe(true)
+  })
+})