docs(#769): start KBN-100 schema migration

CLAUDE.md

@@ -26,10 +26,9 @@ pnpm test             # Vitest (all packages)
 pnpm build            # Build all packages
 
 # Database
-pnpm --filter @mosaicstack/db db:generate  # Offline migration artifact generation
+pnpm --filter @mosaicstack/db db:push      # Push schema to PG (dev)
-mosaic-db-migrator --run                   # Sole PostgreSQL DDL runner
+pnpm --filter @mosaicstack/db db:generate  # Generate migrations
-mosaic-db-migrator --verify                # Verified readiness; no URL/SQL/schema/role argv
+pnpm --filter @mosaicstack/db db:migrate   # Run migrations
-# db:push is disposable-local-only; db:migrate/storage migrate --run must delegate only to the runner.
 
 # Dev
 docker compose up -d                  # Start PG, Valkey, OTEL, Jaeger

README.md

@@ -157,10 +157,7 @@ mosaic storage status
 mosaic storage tier
 mosaic storage export
 mosaic storage import
-# `mosaic storage migrate --run` is a schema-wrapper compatibility command only;
+mosaic storage migrate
-# it delegates solely to mosaic-db-migrator and is not tier data copy.
-# Tier data copy is the KBN-101 secure migrate-tier route after activation, with
-# --target-url-file and --target-attestation-file references only.
 ```
 
 ### Telemetry
@@ -201,9 +198,8 @@ docker compose up -d
 # Install dependencies
 pnpm install
 
-# Run PostgreSQL migrations (sole DDL control plane)
+# Run migrations
-mosaic-db-migrator --run
+pnpm --filter @mosaicstack/db run db:migrate
-mosaic-db-migrator --verify
 
 # Start all services in dev mode
 pnpm dev

apps/gateway/src/agent/agent.module.ts

@@ -21,12 +21,6 @@ import { LogModule } from '../log/log.module.js';
 import { CommandsModule } from '../commands/commands.module.js';
 import { CommandRuntimeApprovalVerifier } from '../commands/runtime-approval-verifier.js';
 import { GatewayHermesRuntimeTransport } from './hermes-runtime.transport.js';
-import { ConnectorLeaseRepository } from './connector-lease.repository.js';
-import {
-  CONNECTOR_LEASE_POLICY,
-  ConnectorLeaseService,
-  DenyConnectorLeasePolicy,
-} from './connector-lease.service.js';
 import {
   AGENT_RUNTIME_PROVIDER_REGISTRY,
   RUNTIME_APPROVAL_VERIFIER,
@@ -52,13 +46,6 @@ export function createGatewayRuntimeProviderRegistry(): AgentRuntimeProviderRegi
     SkillLoaderService,
     DurableSessionRepository,
     DurableSessionService,
-    ConnectorLeaseRepository,
-    DenyConnectorLeasePolicy,
-    {
-      provide: CONNECTOR_LEASE_POLICY,
-      useExisting: DenyConnectorLeasePolicy,
-    },
-    ConnectorLeaseService,
     {
       provide: AGENT_RUNTIME_PROVIDER_REGISTRY,
       useFactory: createGatewayRuntimeProviderRegistry,
@@ -91,7 +78,6 @@ export function createGatewayRuntimeProviderRegistry(): AgentRuntimeProviderRegi
     SkillLoaderService,
     DurableSessionService,
     RuntimeProviderService,
-    ConnectorLeaseService,
     AGENT_RUNTIME_PROVIDER_REGISTRY,
   ],
 })

apps/gateway/src/agent/connector-lease.integration.test.ts

@@ -1,341 +0,0 @@
-import { mkdtemp, rm } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
-import { Test, type TestingModule } from '@nestjs/testing';
-import {
-  connectorLeaseAuditLog,
-  createPgliteDb,
-  eq,
-  runPgliteMigrations,
-  type DbHandle,
-} from '@mosaicstack/db';
-import type { ConnectorExecutionContext, FencedConnectorAdapter } from '@mosaicstack/types';
-import { DB } from '../database/database.module.js';
-import { ConnectorLeaseRepository } from './connector-lease.repository.js';
-import {
-  CONNECTOR_LEASE_POLICY,
-  ConnectorLeaseService,
-  type ConnectorLeasePolicy,
-  type ConnectorLeasePolicySubject,
-} from './connector-lease.service.js';
-
-const authorize = vi.fn().mockResolvedValue(true);
-const policy: ConnectorLeasePolicy = { authorize };
-const context = {
-  actorScope: { userId: 'operator-a', tenantId: 'tenant-a' },
-  correlationId: 'correlation-acquire',
-};
-
-describe('gateway connector lease fencing integration', (): void => {
-  let dataDir: string;
-  let handle: DbHandle;
-  let moduleRef: TestingModule;
-  let service: ConnectorLeaseService;
-  let repository: ConnectorLeaseRepository;
-
-  beforeAll(async (): Promise<void> => {
-    vi.useFakeTimers();
-    vi.setSystemTime(new Date('2026-07-14T17:00:00.000Z'));
-    dataDir = await mkdtemp(join(tmpdir(), 'mosaic-gateway-connector-lease-'));
-    handle = createPgliteDb(dataDir);
-    await runPgliteMigrations(handle);
-    moduleRef = await Test.createTestingModule({
-      providers: [
-        ConnectorLeaseRepository,
-        ConnectorLeaseService,
-        { provide: DB, useValue: handle.db },
-        { provide: CONNECTOR_LEASE_POLICY, useValue: policy },
-      ],
-    }).compile();
-    service = moduleRef.get(ConnectorLeaseService);
-    repository = moduleRef.get(ConnectorLeaseRepository);
-  });
-
-  afterAll(async (): Promise<void> => {
-    vi.useRealTimers();
-    await moduleRef.close();
-    await handle.close();
-    await rm(dataDir, { recursive: true, force: true });
-  });
-
-  it('derives tenant authority at the gateway and validates a grant before side effects', async (): Promise<void> => {
-    const lease = await service.acquire(
-      {
-        logicalAgentId: 'Mos',
-        bindingId: 'operator-chat',
-        connectorId: 'pi-worker-a',
-        scopes: ['runtime.send'],
-        ttlMs: 60_000,
-      },
-      context,
-    );
-    const grant = await service.issueGrant(
-      { lease, scopes: ['runtime.send'], ttlMs: 30_000 },
-      { ...context, correlationId: 'correlation-grant' },
-    );
-    const execute = vi.fn(async (_message: string, leaseContext: ConnectorExecutionContext) => {
-      return leaseContext.leaseEpoch;
-    });
-    const adapter: FencedConnectorAdapter<string, string> = { execute };
-
-    await expect(service.executeGrant(grant, 'runtime.send', 'hello', adapter)).resolves.toBe('1');
-    expect(execute).toHaveBeenCalledOnce();
-    expect(authorize).toHaveBeenCalledWith(
-      expect.objectContaining({
-        action: 'grant.issue',
-        requestedScopes: ['runtime.send'],
-        requestedTtlMs: 30_000,
-      }),
-    );
-    expect(execute.mock.calls[0]?.[1]).toMatchObject({
-      identity: { tenantId: 'tenant-a', logicalAgentId: 'mos' },
-      bindingId: 'operator-chat',
-      connectorId: 'pi-worker-a',
-    });
-  });
-
-  it('normalizes lease-derived policy subjects before authorization', async (): Promise<void> => {
-    const lease = await service.acquire(
-      {
-        logicalAgentId: 'mos',
-        bindingId: 'operator-chat-policy',
-        connectorId: 'pi-worker-a',
-        scopes: ['runtime.send'],
-        ttlMs: 60_000,
-      },
-      { ...context, correlationId: 'correlation-policy-setup' },
-    );
-    const aliasedLease = {
-      ...lease,
-      identity: { ...lease.identity, logicalAgentId: ' MOS ' },
-      bindingId: ' Operator-Chat-Policy ',
-      connectorId: ' PI-Worker-A ',
-      scopes: [' Runtime.Send '],
-      leaseEpoch: `00${lease.leaseEpoch}`,
-    };
-
-    await service.heartbeat(aliasedLease, 30_000, {
-      ...context,
-      correlationId: 'correlation-policy-heartbeat',
-    });
-    expect(authorize).toHaveBeenLastCalledWith(
-      expect.objectContaining({
-        action: 'lease.heartbeat',
-        logicalAgentId: 'mos',
-        bindingId: 'operator-chat-policy',
-        connectorId: 'pi-worker-a',
-        requestedScopes: ['runtime.send'],
-      }),
-    );
-
-    await service.issueGrant(
-      { lease: aliasedLease, scopes: [' Runtime.Send '], ttlMs: 1_000 },
-      { ...context, correlationId: 'correlation-policy-grant' },
-    );
-    expect(authorize).toHaveBeenLastCalledWith(
-      expect.objectContaining({
-        action: 'grant.issue',
-        logicalAgentId: 'mos',
-        bindingId: 'operator-chat-policy',
-        connectorId: 'pi-worker-a',
-        requestedScopes: ['runtime.send'],
-      }),
-    );
-
-    await service.release(aliasedLease, {
-      ...context,
-      correlationId: 'correlation-policy-release',
-    });
-    expect(authorize).toHaveBeenLastCalledWith(
-      expect.objectContaining({
-        action: 'lease.release',
-        logicalAgentId: 'mos',
-        bindingId: 'operator-chat-policy',
-        connectorId: 'pi-worker-a',
-        requestedScopes: ['runtime.send'],
-      }),
-    );
-  });
-
-  it('denies stale, forged, expired, cross-tenant, and cross-binding grants before effects', async (): Promise<void> => {
-    const bindingId = 'operator-chat-denials';
-    const current = await service.acquire(
-      {
-        logicalAgentId: 'mos',
-        bindingId,
-        connectorId: 'pi-worker-a',
-        scopes: ['runtime.send'],
-        ttlMs: 60_000,
-      },
-      { ...context, correlationId: 'correlation-denial-setup' },
-    );
-    const stale = await service.issueGrant(
-      { lease: current, scopes: ['runtime.send'], ttlMs: 30_000 },
-      { ...context, correlationId: 'correlation-stale' },
-    );
-    await service.takeover(
-      {
-        logicalAgentId: 'mos',
-        bindingId,
-        connectorId: 'pi-worker-b',
-        scopes: ['runtime.send'],
-        ttlMs: 60_000,
-        expectedEpoch: current.leaseEpoch,
-      },
-      { ...context, correlationId: 'correlation-takeover' },
-    );
-    const adapter = { execute: vi.fn().mockResolvedValue(undefined) };
-
-    await expect(service.executeGrant(stale, 'runtime.send', undefined, adapter)).rejects.toThrow();
-
-    const active = await service.current('mos', bindingId, context);
-    if (!active) throw new Error('active lease fixture is unavailable');
-    const grant = await service.issueGrant(
-      { lease: active, scopes: ['runtime.send'], ttlMs: 1_000 },
-      { ...context, correlationId: 'correlation-active' },
-    );
-    await expect(
-      service.executeGrant({ ...grant }, 'runtime.send', undefined, adapter),
-    ).rejects.toThrow();
-    await expect(
-      service.executeGrant(
-        { ...grant, bindingId: 'other-binding' },
-        'runtime.send',
-        undefined,
-        adapter,
-      ),
-    ).rejects.toThrow();
-    await expect(
-      service.issueGrant(
-        { lease: active, scopes: ['runtime.send'], ttlMs: 30_000 },
-        {
-          actorScope: { userId: 'operator-b', tenantId: 'tenant-b' },
-          correlationId: 'correlation-cross-tenant',
-        },
-      ),
-    ).rejects.toThrow();
-    const crossTenantAudit = await handle.db
-      .select()
-      .from(connectorLeaseAuditLog)
-      .where(eq(connectorLeaseAuditLog.correlationId, 'correlation-cross-tenant'));
-    expect(crossTenantAudit).toHaveLength(1);
-    expect(crossTenantAudit[0]).toMatchObject({
-      tenantId: 'tenant-b',
-      logicalAgentId: 'untrusted',
-      bindingId: 'untrusted',
-      connectorId: 'untrusted',
-      reason: 'policy_denied',
-    });
-
-    vi.setSystemTime(new Date('2026-07-14T17:00:02.000Z'));
-    await expect(service.executeGrant(grant, 'runtime.send', undefined, adapter)).rejects.toThrow();
-    expect(adapter.execute).not.toHaveBeenCalled();
-  });
-
-  it('rejects submitted lifecycle scopes that differ from durable authority before policy or mutation', async (): Promise<void> => {
-    authorize.mockResolvedValue(true);
-    const heartbeatLease = await service.acquire(
-      {
-        logicalAgentId: 'mos',
-        bindingId: 'operator-chat-heartbeat-scope',
-        connectorId: 'pi-worker-a',
-        scopes: ['runtime.send'],
-        ttlMs: 60_000,
-      },
-      { ...context, correlationId: 'correlation-heartbeat-scope-setup' },
-    );
-    const releaseLease = await service.acquire(
-      {
-        logicalAgentId: 'mos',
-        bindingId: 'operator-chat-release-scope',
-        connectorId: 'pi-worker-a',
-        scopes: ['runtime.send'],
-        ttlMs: 60_000,
-      },
-      { ...context, correlationId: 'correlation-release-scope-setup' },
-    );
-    const forgedHeartbeat = { ...heartbeatLease, scopes: ['tool.execute'] };
-    const forgedRelease = { ...releaseLease, scopes: ['tool.execute'] };
-
-    authorize.mockImplementation(async (subject: ConnectorLeasePolicySubject) => {
-      return subject.requestedScopes.length === 1 && subject.requestedScopes[0] === 'tool.execute';
-    });
-    authorize.mockClear();
-
-    await expect(
-      service.heartbeat(forgedHeartbeat, 30_000, {
-        ...context,
-        correlationId: 'correlation-heartbeat-scope-forgery',
-      }),
-    ).rejects.toThrow('Connector authority policy denied');
-    await expect(
-      service.release(forgedRelease, {
-        ...context,
-        correlationId: 'correlation-release-scope-forgery',
-      }),
-    ).rejects.toThrow('Connector authority policy denied');
-    expect(authorize).not.toHaveBeenCalled();
-
-    const currentHeartbeat = await repository.findCurrent({
-      identity: heartbeatLease.identity,
-      bindingId: heartbeatLease.bindingId,
-    });
-    const currentRelease = await repository.findCurrent({
-      identity: releaseLease.identity,
-      bindingId: releaseLease.bindingId,
-    });
-    expect(currentHeartbeat).toMatchObject({
-      leaseId: heartbeatLease.leaseId,
-      scopes: ['runtime.send'],
-      heartbeatAt: heartbeatLease.heartbeatAt,
-      expiresAt: heartbeatLease.expiresAt,
-    });
-    expect(currentRelease).toMatchObject({
-      leaseId: releaseLease.leaseId,
-      scopes: ['runtime.send'],
-    });
-    expect(currentRelease?.releasedAt).toBeUndefined();
-
-    const forgedAudits = await handle.db
-      .select()
-      .from(connectorLeaseAuditLog)
-      .where(eq(connectorLeaseAuditLog.correlationId, 'correlation-heartbeat-scope-forgery'));
-    expect(forgedAudits).toHaveLength(1);
-    expect(forgedAudits[0]).toMatchObject({
-      bindingId: heartbeatLease.bindingId,
-      connectorId: heartbeatLease.connectorId,
-      event: 'reject',
-      outcome: 'denied',
-      reason: 'policy_denied',
-    });
-    const forgedReleaseAudits = await handle.db
-      .select()
-      .from(connectorLeaseAuditLog)
-      .where(eq(connectorLeaseAuditLog.correlationId, 'correlation-release-scope-forgery'));
-    expect(forgedReleaseAudits).toHaveLength(1);
-    expect(forgedReleaseAudits[0]).toMatchObject({
-      bindingId: releaseLease.bindingId,
-      connectorId: releaseLease.connectorId,
-      event: 'reject',
-      outcome: 'denied',
-      reason: 'policy_denied',
-    });
-
-    authorize.mockImplementation(async (subject: ConnectorLeasePolicySubject) => {
-      return subject.requestedScopes.length === 1 && subject.requestedScopes[0] === 'runtime.send';
-    });
-    await expect(
-      service.heartbeat(heartbeatLease, 30_000, {
-        ...context,
-        correlationId: 'correlation-heartbeat-scope-canonical',
-      }),
-    ).resolves.toMatchObject({ scopes: ['runtime.send'] });
-    await expect(
-      service.release(releaseLease, {
-        ...context,
-        correlationId: 'correlation-release-scope-canonical',
-      }),
-    ).resolves.toBeUndefined();
-  });
-});

apps/gateway/src/agent/connector-lease.postgres.integration.test.ts

@@ -1,76 +0,0 @@
-import { randomUUID } from 'node:crypto';
-import { afterAll, beforeAll, describe, expect, it } from 'vitest';
-import {
-  connectorLeaseAuditLog,
-  createDb,
-  eq,
-  logicalAgentConnectorLeases,
-  type DbHandle,
-} from '@mosaicstack/db';
-import { ConnectorLeaseCoordinator } from '@mosaicstack/agent';
-import { ConnectorLeaseRepository } from './connector-lease.repository.js';
-
-const hasPostgres = Boolean(process.env['DATABASE_URL']);
-const tenantId = `lease-test-${randomUUID()}`;
-const identity = { tenantId, logicalAgentId: 'mos' } as const;
-
-describe.skipIf(!hasPostgres)('ConnectorLeaseRepository real PostgreSQL integration', (): void => {
-  let handle: DbHandle;
-
-  beforeAll((): void => {
-    handle = createDb(process.env['DATABASE_URL']);
-  });
-
-  afterAll(async (): Promise<void> => {
-    if (!handle) return;
-    await handle.db
-      .delete(connectorLeaseAuditLog)
-      .where(eq(connectorLeaseAuditLog.tenantId, tenantId));
-    await handle.db
-      .delete(logicalAgentConnectorLeases)
-      .where(eq(logicalAgentConnectorLeases.tenantId, tenantId));
-    await handle.close();
-  });
-
-  it('preserves the exclusive CAS fence across a real pool close/reopen', async (): Promise<void> => {
-    const command = {
-      identity,
-      bindingId: 'operator-chat',
-      scopes: ['runtime.send'],
-      ttlMs: 60_000,
-    } as const;
-    const firstCoordinator = new ConnectorLeaseCoordinator(new ConnectorLeaseRepository(handle.db));
-    const contenders = await Promise.allSettled([
-      firstCoordinator.acquire({
-        ...command,
-        connectorId: 'connector-a',
-        correlationId: 'postgres-acquire-a',
-      }),
-      firstCoordinator.acquire({
-        ...command,
-        connectorId: 'connector-b',
-        correlationId: 'postgres-acquire-b',
-      }),
-    ]);
-    const acquired = contenders.find((result) => result.status === 'fulfilled');
-    if (!acquired || acquired.status !== 'fulfilled') throw new Error('no lease contender won');
-    expect(contenders.filter((result) => result.status === 'fulfilled')).toHaveLength(1);
-
-    await handle.close();
-    handle = createDb(process.env['DATABASE_URL']);
-    const reopened = new ConnectorLeaseCoordinator(new ConnectorLeaseRepository(handle.db));
-    const persisted = await reopened.current({ identity, bindingId: 'operator-chat' });
-    expect(persisted).toMatchObject({
-      leaseId: acquired.value.leaseId,
-      leaseEpoch: '1',
-    });
-
-    const takeover = await reopened.takeover({
-      ...command,
-      connectorId: 'connector-c',
-      correlationId: 'postgres-takeover',
-      expectedEpoch: acquired.value.leaseEpoch,
-    });
-    expect(takeover).toMatchObject({ connectorId: 'connector-c', leaseEpoch: '2' });
-  });
-});

apps/gateway/src/agent/connector-lease.repository.test.ts

@@ -1,149 +0,0 @@
-import { mkdtemp, rm } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-import {
-  connectorLeaseAuditLog,
-  createPgliteDb,
-  eq,
-  runPgliteMigrations,
-  type DbHandle,
-} from '@mosaicstack/db';
-import { ConnectorLeaseCoordinator, ConnectorLeaseError } from '@mosaicstack/agent';
-import { ConnectorLeaseRepository } from './connector-lease.repository.js';
-
-const identity = { tenantId: 'tenant-a', logicalAgentId: 'mos' } as const;
-
-function acquireCommand(connectorId: string, correlationId: string) {
-  return {
-    identity,
-    bindingId: 'operator-chat',
-    connectorId,
-    scopes: ['runtime.send', 'tool.execute'],
-    ttlMs: 60_000,
-    correlationId,
-  };
-}
-
-describe('ConnectorLeaseRepository PostgreSQL semantics', (): void => {
-  let dataDir: string;
-  let handle: DbHandle;
-  let now: Date;
-  let coordinator: ConnectorLeaseCoordinator;
-
-  beforeEach(async (): Promise<void> => {
-    dataDir = await mkdtemp(join(tmpdir(), 'mosaic-connector-lease-'));
-    handle = createPgliteDb(dataDir);
-    await runPgliteMigrations(handle);
-    now = new Date('2026-07-14T17:00:00.000Z');
-    coordinator = new ConnectorLeaseCoordinator(new ConnectorLeaseRepository(handle.db), {
-      now: (): Date => now,
-    });
-  });
-
-  afterEach(async (): Promise<void> => {
-    await handle.close();
-    await rm(dataDir, { recursive: true, force: true });
-  });
-
-  it('allows only one concurrent contender to acquire a binding', async (): Promise<void> => {
-    const outcomes = await Promise.allSettled([
-      coordinator.acquire(acquireCommand('connector-a', 'correlation-a')),
-      coordinator.acquire(acquireCommand('connector-b', 'correlation-b')),
-    ]);
-
-    expect(outcomes.filter((result) => result.status === 'fulfilled')).toHaveLength(1);
-    const rejected = outcomes.find((result) => result.status === 'rejected');
-    expect(rejected).toMatchObject({
-      reason: { code: 'lease_held' } satisfies Partial<ConnectorLeaseError>,
-    });
-  });
-
-  it('uses compare-and-swap takeover and increments the fencing epoch monotonically', async (): Promise<void> => {
-    const acquired = await coordinator.acquire(acquireCommand('connector-a', 'correlation-a'));
-    const results = await Promise.allSettled([
-      coordinator.takeover({
-        ...acquireCommand('connector-b', 'correlation-b'),
-        expectedEpoch: acquired.leaseEpoch,
-      }),
-      coordinator.takeover({
-        ...acquireCommand('connector-c', 'correlation-c'),
-        expectedEpoch: acquired.leaseEpoch,
-      }),
-    ]);
-    const winner = results.find((result) => result.status === 'fulfilled');
-
-    expect(results.filter((result) => result.status === 'fulfilled')).toHaveLength(1);
-    expect(winner?.status === 'fulfilled' ? winner.value.leaseEpoch : null).toBe('2');
-    expect(results.find((result) => result.status === 'rejected')).toMatchObject({
-      reason: { code: 'cas_mismatch' } satisfies Partial<ConnectorLeaseError>,
-    });
-  });
-
-  it('heartbeats and releases only the current connector epoch', async (): Promise<void> => {
-    const acquired = await coordinator.acquire(acquireCommand('connector-a', 'correlation-a'));
-    now = new Date('2026-07-14T17:00:30.000Z');
-    const renewed = await coordinator.heartbeat({
-      lease: acquired,
-      ttlMs: 120_000,
-      correlationId: 'correlation-renew',
-    });
-    expect(renewed.expiresAt).toBe('2026-07-14T17:02:30.000Z');
-
-    await coordinator.release({ lease: renewed, correlationId: 'correlation-release' });
-    await expect(
-      coordinator.heartbeat({
-        lease: renewed,
-        ttlMs: 120_000,
-        correlationId: 'correlation-stale',
-      }),
-    ).rejects.toMatchObject({ code: 'lease_released' } satisfies Partial<ConnectorLeaseError>);
-  });
-
-  it('survives close/reopen and requires CAS takeover to recover an expired lease', async (): Promise<void> => {
-    const acquired = await coordinator.acquire(acquireCommand('connector-a', 'correlation-a'));
-    await handle.close();
-
-    now = new Date('2026-07-14T17:02:00.000Z');
-    handle = createPgliteDb(dataDir);
-    await runPgliteMigrations(handle);
-    coordinator = new ConnectorLeaseCoordinator(new ConnectorLeaseRepository(handle.db), {
-      now: (): Date => now,
-    });
-
-    await expect(
-      coordinator.acquire(acquireCommand('connector-b', 'correlation-plain-acquire')),
-    ).rejects.toMatchObject({ code: 'takeover_required' } satisfies Partial<ConnectorLeaseError>);
-    const recovered = await coordinator.takeover({
-      ...acquireCommand('connector-b', 'correlation-takeover'),
-      expectedEpoch: acquired.leaseEpoch,
-    });
-    expect(recovered).toMatchObject({ connectorId: 'connector-b', leaseEpoch: '2' });
-  });
-
-  it('writes credential-safe lifecycle and rejection audit records', async (): Promise<void> => {
-    const acquired = await coordinator.acquire(acquireCommand('connector-a', 'correlation-a'));
-    await coordinator.heartbeat({
-      lease: acquired,
-      ttlMs: 60_000,
-      correlationId: 'correlation-renew',
-    });
-    await expect(
-      coordinator.acquire(acquireCommand('connector-b', 'correlation-reject')),
-    ).rejects.toBeInstanceOf(ConnectorLeaseError);
-
-    const rows = await handle.db
-      .select()
-      .from(connectorLeaseAuditLog)
-      .where(eq(connectorLeaseAuditLog.tenantId, identity.tenantId));
-    expect(rows.map((row) => row.event)).toEqual(
-      expect.arrayContaining(['acquire', 'renew', 'reject']),
-    );
-    const serialized = JSON.stringify(rows, (_key: string, value: unknown): unknown =>
-      typeof value === 'bigint' ? value.toString(10) : value,
-    );
-    expect(serialized).not.toContain('tool.execute');
-    expect(serialized).not.toContain('runtime.send');
-    expect(serialized).not.toMatch(/token|secret|credential/i);
-  });
-});

apps/gateway/src/agent/connector-lease.repository.ts

@@ -1,354 +0,0 @@
-import { Inject, Injectable } from '@nestjs/common';
-import {
-  and,
-  connectorLeaseAuditLog,
-  eq,
-  gt,
-  isNull,
-  logicalAgentConnectorLeases,
-  sql,
-  type Db,
-} from '@mosaicstack/db';
-import { ConnectorLeaseError } from '@mosaicstack/agent';
-import type {
-  ConnectorLease,
-  ConnectorLeaseAcquireMutation,
-  ConnectorLeaseAuditEvent,
-  ConnectorLeaseHeartbeatMutation,
-  ConnectorLeaseRejectReason,
-  ConnectorLeaseReleaseMutation,
-  ConnectorLeaseStore,
-  ConnectorLeaseTakeoverMutation,
-  LogicalAgentBinding,
-} from '@mosaicstack/types';
-import { DB } from '../database/database.module.js';
-
-interface SuccessfulMutation {
-  readonly ok: true;
-  readonly lease: ConnectorLease;
-}
-
-interface FailedMutation {
-  readonly ok: false;
-  readonly reason: ConnectorLeaseRejectReason;
-}
-
-type MutationResult = SuccessfulMutation | FailedMutation;
-
-@Injectable()
-export class ConnectorLeaseRepository implements ConnectorLeaseStore {
-  constructor(@Inject(DB) private readonly db: Db) {}
-
-  async acquire(input: ConnectorLeaseAcquireMutation): Promise<ConnectorLease> {
-    const result: MutationResult = await this.db.transaction(
-      async (tx): Promise<MutationResult> => {
-        const inserted = await tx
-          .insert(logicalAgentConnectorLeases)
-          .values({
-            leaseId: input.leaseId,
-            tenantId: input.identity.tenantId,
-            logicalAgentId: input.identity.logicalAgentId,
-            bindingId: input.bindingId,
-            connectorId: input.connectorId,
-            scopes: [...input.scopes],
-            leaseEpoch: 1n,
-            acquiredAt: new Date(input.now),
-            heartbeatAt: new Date(input.now),
-            expiresAt: new Date(input.expiresAt),
-            updatedAt: new Date(input.now),
-          })
-          .onConflictDoNothing()
-          .returning();
-        const row = inserted[0];
-        if (row) {
-          const lease = toLease(row);
-          await insertAudit(tx, lifecycleAudit(input, lease, 'acquire'));
-          return { ok: true, lease };
-        }
-
-        const current = await findRow(tx, input);
-        if (current && current.expiresAt <= new Date(input.now) && !current.releasedAt) {
-          await insertAudit(tx, lifecycleAudit(input, toLease(current), 'expiry'));
-        }
-        const reason: ConnectorLeaseRejectReason =
-          current && (current.releasedAt || current.expiresAt <= new Date(input.now))
-            ? 'takeover_required'
-            : 'lease_held';
-        await insertAudit(tx, rejectionAudit(input, current ? toLease(current) : null, reason));
-        return { ok: false, reason };
-      },
-    );
-    return unwrap(result);
-  }
-
-  async takeover(input: ConnectorLeaseTakeoverMutation): Promise<ConnectorLease> {
-    const result: MutationResult = await this.db.transaction(
-      async (tx): Promise<MutationResult> => {
-        const current = await findRow(tx, input);
-        if (!current || current.leaseEpoch.toString(10) !== input.expectedEpoch) {
-          await insertAudit(
-            tx,
-            rejectionAudit(input, current ? toLease(current) : null, 'cas_mismatch'),
-          );
-          return { ok: false, reason: 'cas_mismatch' };
-        }
-        if (current.expiresAt <= new Date(input.now) && !current.releasedAt) {
-          await insertAudit(tx, lifecycleAudit(input, toLease(current), 'expiry'));
-        }
-        const updated = await tx
-          .update(logicalAgentConnectorLeases)
-          .set({
-            leaseId: input.leaseId,
-            connectorId: input.connectorId,
-            scopes: [...input.scopes],
-            leaseEpoch: sql`${logicalAgentConnectorLeases.leaseEpoch} + 1`,
-            acquiredAt: new Date(input.now),
-            heartbeatAt: new Date(input.now),
-            expiresAt: new Date(input.expiresAt),
-            releasedAt: null,
-            updatedAt: new Date(input.now),
-          })
-          .where(
-            and(
-              bindingPredicate(input),
-              eq(logicalAgentConnectorLeases.leaseId, current.leaseId),
-              eq(logicalAgentConnectorLeases.leaseEpoch, BigInt(input.expectedEpoch)),
-            ),
-          )
-          .returning();
-        const row = updated[0];
-        if (!row) {
-          await insertAudit(tx, rejectionAudit(input, toLease(current), 'cas_mismatch'));
-          return { ok: false, reason: 'cas_mismatch' };
-        }
-        const lease = toLease(row);
-        await insertAudit(tx, lifecycleAudit(input, lease, 'takeover'));
-        return { ok: true, lease };
-      },
-    );
-    return unwrap(result);
-  }
-
-  async heartbeat(input: ConnectorLeaseHeartbeatMutation): Promise<ConnectorLease> {
-    const result: MutationResult = await this.db.transaction(
-      async (tx): Promise<MutationResult> => {
-        const updated = await tx
-          .update(logicalAgentConnectorLeases)
-          .set({
-            heartbeatAt: new Date(input.now),
-            expiresAt: new Date(input.expiresAt),
-            updatedAt: new Date(input.now),
-          })
-          .where(
-            and(
-              bindingPredicate(input.lease),
-              eq(logicalAgentConnectorLeases.leaseId, input.lease.leaseId),
-              eq(logicalAgentConnectorLeases.connectorId, input.lease.connectorId),
-              eq(logicalAgentConnectorLeases.leaseEpoch, BigInt(input.lease.leaseEpoch)),
-              isNull(logicalAgentConnectorLeases.releasedAt),
-              gt(logicalAgentConnectorLeases.expiresAt, new Date(input.now)),
-            ),
-          )
-          .returning();
-        const row = updated[0];
-        if (row) {
-          const lease = toLease(row);
-          await insertAudit(tx, lifecycleAudit(input, lease, 'renew'));
-          return { ok: true, lease };
-        }
-        const current = await findRow(tx, input.lease);
-        const reason = classifyAuthorityFailure(
-          current ? toLease(current) : null,
-          input.lease,
-          input.now,
-        );
-        if (reason === 'lease_expired' && current) {
-          await insertAudit(tx, lifecycleAudit(input, toLease(current), 'expiry'));
-        }
-        await insertAudit(
-          tx,
-          rejectionAudit(
-            { ...input.lease, correlationId: input.correlationId, now: input.now },
-            current ? toLease(current) : null,
-            reason,
-          ),
-        );
-        return { ok: false, reason };
-      },
-    );
-    return unwrap(result);
-  }
-
-  async release(input: ConnectorLeaseReleaseMutation): Promise<void> {
-    const result: MutationResult = await this.db.transaction(
-      async (tx): Promise<MutationResult> => {
-        const updated = await tx
-          .update(logicalAgentConnectorLeases)
-          .set({
-            releasedAt: new Date(input.now),
-            expiresAt: new Date(input.now),
-            updatedAt: new Date(input.now),
-          })
-          .where(
-            and(
-              bindingPredicate(input.lease),
-              eq(logicalAgentConnectorLeases.leaseId, input.lease.leaseId),
-              eq(logicalAgentConnectorLeases.connectorId, input.lease.connectorId),
-              eq(logicalAgentConnectorLeases.leaseEpoch, BigInt(input.lease.leaseEpoch)),
-              isNull(logicalAgentConnectorLeases.releasedAt),
-              gt(logicalAgentConnectorLeases.expiresAt, new Date(input.now)),
-            ),
-          )
-          .returning();
-        const row = updated[0];
-        if (row) {
-          const lease = toLease(row);
-          await insertAudit(tx, lifecycleAudit(input, lease, 'release'));
-          return { ok: true, lease };
-        }
-        const current = await findRow(tx, input.lease);
-        const reason = classifyAuthorityFailure(
-          current ? toLease(current) : null,
-          input.lease,
-          input.now,
-        );
-        if (reason === 'lease_expired' && current) {
-          await insertAudit(tx, lifecycleAudit(input, toLease(current), 'expiry'));
-        }
-        await insertAudit(
-          tx,
-          rejectionAudit(
-            { ...input.lease, correlationId: input.correlationId, now: input.now },
-            current ? toLease(current) : null,
-            reason,
-          ),
-        );
-        return { ok: false, reason };
-      },
-    );
-    unwrap(result);
-  }
-
-  async findCurrent(binding: LogicalAgentBinding): Promise<ConnectorLease | null> {
-    const row = await findRow(this.db, binding);
-    return row ? toLease(row) : null;
-  }
-
-  async recordAudit(event: ConnectorLeaseAuditEvent): Promise<void> {
-    await insertAudit(this.db, event);
-  }
-}
-
-function unwrap(result: MutationResult): ConnectorLease {
-  if (!result.ok) throw new ConnectorLeaseError(result.reason, safeErrorMessage(result.reason));
-  return result.lease;
-}
-
-function safeErrorMessage(reason: ConnectorLeaseRejectReason): string {
-  return `Connector lease mutation denied: ${reason}`;
-}
-
-function bindingPredicate(binding: LogicalAgentBinding) {
-  return and(
-    eq(logicalAgentConnectorLeases.tenantId, binding.identity.tenantId),
-    eq(logicalAgentConnectorLeases.logicalAgentId, binding.identity.logicalAgentId),
-    eq(logicalAgentConnectorLeases.bindingId, binding.bindingId),
-  );
-}
-
-async function findRow(
-  db: Pick<Db, 'select'>,
-  binding: LogicalAgentBinding,
-): Promise<typeof logicalAgentConnectorLeases.$inferSelect | null> {
-  const rows = await db
-    .select()
-    .from(logicalAgentConnectorLeases)
-    .where(bindingPredicate(binding))
-    .limit(1);
-  return rows[0] ?? null;
-}
-
-function toLease(row: typeof logicalAgentConnectorLeases.$inferSelect): ConnectorLease {
-  return Object.freeze({
-    identity: Object.freeze({ tenantId: row.tenantId, logicalAgentId: row.logicalAgentId }),
-    bindingId: row.bindingId,
-    leaseId: row.leaseId,
-    connectorId: row.connectorId,
-    scopes: Object.freeze([...row.scopes]),
-    leaseEpoch: row.leaseEpoch.toString(10),
-    acquiredAt: row.acquiredAt.toISOString(),
-    heartbeatAt: row.heartbeatAt.toISOString(),
-    expiresAt: row.expiresAt.toISOString(),
-    ...(row.releasedAt ? { releasedAt: row.releasedAt.toISOString() } : {}),
-  });
-}
-
-function classifyAuthorityFailure(
-  current: ConnectorLease | null,
-  claimed: ConnectorLease,
-  now: string,
-): ConnectorLeaseRejectReason {
-  if (!current) return 'lease_missing';
-  if (current.releasedAt) return 'lease_released';
-  if (new Date(current.expiresAt) <= new Date(now)) return 'lease_expired';
-  if (current.leaseEpoch !== claimed.leaseEpoch) return 'stale_epoch';
-  return 'connector_mismatch';
-}
-
-function lifecycleAudit(
-  input: { readonly correlationId: string; readonly now: string },
-  lease: ConnectorLease,
-  event: Exclude<ConnectorLeaseAuditEvent['event'], 'reject'>,
-): ConnectorLeaseAuditEvent {
-  return {
-    identity: lease.identity,
-    bindingId: lease.bindingId,
-    connectorId: lease.connectorId,
-    leaseId: lease.leaseId,
-    leaseEpoch: lease.leaseEpoch,
-    event,
-    outcome: 'succeeded',
-    correlationId: input.correlationId,
-    occurredAt: input.now,
-  };
-}
-
-function rejectionAudit(
-  input: {
-    readonly identity: ConnectorLease['identity'];
-    readonly bindingId: string;
-    readonly connectorId: string;
-    readonly correlationId: string;
-    readonly now: string;
-  },
-  current: ConnectorLease | null,
-  reason: ConnectorLeaseRejectReason,
-): ConnectorLeaseAuditEvent {
-  return {
-    identity: input.identity,
-    bindingId: input.bindingId,
-    connectorId: input.connectorId,
-    event: 'reject',
-    outcome: 'denied',
-    correlationId: input.correlationId,
-    occurredAt: input.now,
-    ...(current ? { leaseId: current.leaseId, leaseEpoch: current.leaseEpoch } : {}),
-    reason,
-  };
-}
-
-async function insertAudit(db: Pick<Db, 'insert'>, event: ConnectorLeaseAuditEvent): Promise<void> {
-  await db.insert(connectorLeaseAuditLog).values({
-    tenantId: event.identity.tenantId,
-    logicalAgentId: event.identity.logicalAgentId,
-    bindingId: event.bindingId,
-    connectorId: event.connectorId,
-    ...(event.leaseId ? { leaseId: event.leaseId } : {}),
-    ...(event.leaseEpoch ? { leaseEpoch: BigInt(event.leaseEpoch) } : {}),
-    event: event.event,
-    outcome: event.outcome,
-    ...(event.reason ? { reason: event.reason } : {}),
-    correlationId: event.correlationId,
-    occurredAt: new Date(event.occurredAt),
-  });
-}

apps/gateway/src/agent/connector-lease.service.ts

@@ -1,285 +0,0 @@
-import { ForbiddenException, Inject, Injectable } from '@nestjs/common';
-import { ConnectorLeaseCoordinator, normalizeConnectorLease } from '@mosaicstack/agent';
-import {
-  normalizeConnectorId,
-  normalizeConnectorScopes,
-  normalizeCorrelationId,
-  normalizeLogicalAgentIdentity,
-  normalizeLogicalBindingId,
-  type AcquireConnectorLeaseInput,
-  type ConnectorExecutionGrant,
-  type ConnectorLease,
-  type ConnectorLeaseAuditEvent,
-  type FencedConnectorAdapter,
-} from '@mosaicstack/types';
-import type { ActorTenantScope } from '../auth/session-scope.js';
-import { ConnectorLeaseRepository } from './connector-lease.repository.js';
-
-export const CONNECTOR_LEASE_POLICY = Symbol('CONNECTOR_LEASE_POLICY');
-
-export type ConnectorLeasePolicyAction =
-  | 'lease.acquire'
-  | 'lease.takeover'
-  | 'lease.heartbeat'
-  | 'lease.release'
-  | 'lease.read'
-  | 'grant.issue';
-
-export interface ConnectorLeaseRequestContext {
-  readonly actorScope: ActorTenantScope;
-  readonly correlationId: string;
-}
-
-export interface GatewayConnectorLeaseRequest {
-  readonly logicalAgentId: string;
-  readonly bindingId: string;
-  readonly connectorId: string;
-  readonly scopes: readonly string[];
-  readonly ttlMs: number;
-}
-
-export interface GatewayConnectorLeaseTakeoverRequest extends GatewayConnectorLeaseRequest {
-  readonly expectedEpoch: string;
-}
-
-export interface GatewayConnectorGrantRequest {
-  readonly lease: ConnectorLease;
-  readonly scopes: readonly string[];
-  readonly ttlMs: number;
-}
-
-export interface ConnectorLeasePolicySubject {
-  readonly action: ConnectorLeasePolicyAction;
-  readonly actorId: string;
-  readonly tenantId: string;
-  readonly logicalAgentId: string;
-  readonly bindingId: string;
-  readonly connectorId: string;
-  readonly requestedScopes: readonly string[];
-  readonly requestedTtlMs: number | null;
-}
-
-export interface ConnectorLeasePolicy {
-  authorize(subject: ConnectorLeasePolicySubject): Promise<boolean>;
-}
-
-/** M1 has no concrete cutover policy: unconfigured production use fails closed. */
-@Injectable()
-export class DenyConnectorLeasePolicy implements ConnectorLeasePolicy {
-  async authorize(_subject: ConnectorLeasePolicySubject): Promise<boolean> {
-    return false;
-  }
-}
-
-/** Gateway-owned policy surface for durable connector authority and fenced effects. */
-@Injectable()
-export class ConnectorLeaseService {
-  private readonly coordinator: ConnectorLeaseCoordinator;
-
-  constructor(
-    @Inject(ConnectorLeaseRepository) private readonly repository: ConnectorLeaseRepository,
-    @Inject(CONNECTOR_LEASE_POLICY) private readonly policy: ConnectorLeasePolicy,
-  ) {
-    this.coordinator = new ConnectorLeaseCoordinator(repository);
-  }
-
-  async acquire(
-    request: GatewayConnectorLeaseRequest,
-    context: ConnectorLeaseRequestContext,
-  ): Promise<ConnectorLease> {
-    const command = this.command(request, context);
-    await this.assertPolicy('lease.acquire', command, context, command.scopes, command.ttlMs);
-    return this.coordinator.acquire({ ...command, correlationId: this.correlation(context) });
-  }
-
-  async takeover(
-    request: GatewayConnectorLeaseTakeoverRequest,
-    context: ConnectorLeaseRequestContext,
-  ): Promise<ConnectorLease> {
-    const command = this.command(request, context);
-    await this.assertPolicy('lease.takeover', command, context, command.scopes, command.ttlMs);
-    return this.coordinator.takeover({
-      ...command,
-      expectedEpoch: request.expectedEpoch,
-      correlationId: this.correlation(context),
-    });
-  }
-
-  async heartbeat(
-    lease: ConnectorLease,
-    ttlMs: number,
-    context: ConnectorLeaseRequestContext,
-  ): Promise<ConnectorLease> {
-    const normalizedLease = normalizeConnectorLease(lease);
-    const durableLease = await this.durableLifecycleLease(normalizedLease, context);
-    await this.assertPolicy('lease.heartbeat', durableLease, context, durableLease.scopes, ttlMs);
-    return this.coordinator.heartbeat({
-      lease: durableLease,
-      ttlMs,
-      correlationId: this.correlation(context),
-    });
-  }
-
-  async release(lease: ConnectorLease, context: ConnectorLeaseRequestContext): Promise<void> {
-    const normalizedLease = normalizeConnectorLease(lease);
-    const durableLease = await this.durableLifecycleLease(normalizedLease, context);
-    await this.assertPolicy('lease.release', durableLease, context, durableLease.scopes, null);
-    await this.coordinator.release({
-      lease: durableLease,
-      correlationId: this.correlation(context),
-    });
-  }
-
-  async current(
-    logicalAgentId: string,
-    bindingId: string,
-    context: ConnectorLeaseRequestContext,
-  ): Promise<ConnectorLease | null> {
-    const binding = {
-      identity: normalizeLogicalAgentIdentity({
-        tenantId: context.actorScope.tenantId,
-        logicalAgentId,
-      }),
-      bindingId: normalizeLogicalBindingId(bindingId),
-      connectorId: 'gateway',
-    };
-    await this.assertPolicy('lease.read', binding, context, [], null);
-    return this.coordinator.current(binding);
-  }
-
-  async issueGrant(
-    request: GatewayConnectorGrantRequest,
-    context: ConnectorLeaseRequestContext,
-  ): Promise<ConnectorExecutionGrant> {
-    const lease = normalizeConnectorLease(request.lease);
-    await this.assertTenant(lease, context);
-    const scopes = normalizeConnectorScopes(request.scopes);
-    await this.assertPolicy('grant.issue', lease, context, scopes, request.ttlMs);
-    return this.coordinator.issueGrant({
-      lease,
-      scopes,
-      ttlMs: request.ttlMs,
-      correlationId: this.correlation(context),
-    });
-  }
-
-  async executeGrant<TInput, TOutput>(
-    grant: ConnectorExecutionGrant,
-    requiredScope: string,
-    input: TInput,
-    adapter: FencedConnectorAdapter<TInput, TOutput>,
-  ): Promise<TOutput> {
-    return this.coordinator.executeGrant(grant, requiredScope, input, adapter);
-  }
-
-  private command(
-    request: GatewayConnectorLeaseRequest,
-    context: ConnectorLeaseRequestContext,
-  ): Omit<AcquireConnectorLeaseInput, 'correlationId'> {
-    return {
-      identity: normalizeLogicalAgentIdentity({
-        tenantId: context.actorScope.tenantId,
-        logicalAgentId: request.logicalAgentId,
-      }),
-      bindingId: normalizeLogicalBindingId(request.bindingId),
-      connectorId: normalizeConnectorId(request.connectorId),
-      scopes: normalizeConnectorScopes(request.scopes),
-      ttlMs: request.ttlMs,
-    };
-  }
-
-  private async assertTenant(
-    lease: Pick<ConnectorLease, 'identity' | 'bindingId' | 'connectorId'>,
-    context: ConnectorLeaseRequestContext,
-  ): Promise<void> {
-    if (lease.identity.tenantId !== context.actorScope.tenantId) {
-      await this.recordPolicyDenial(
-        {
-          identity: {
-            tenantId: context.actorScope.tenantId,
-            logicalAgentId: 'untrusted',
-          },
-          bindingId: 'untrusted',
-          connectorId: 'untrusted',
-        },
-        context,
-      );
-      throw new ForbiddenException('Connector authority tenant scope denied');
-    }
-  }
-
-  private async durableLifecycleLease(
-    submittedLease: ConnectorLease,
-    context: ConnectorLeaseRequestContext,
-  ): Promise<ConnectorLease> {
-    await this.assertTenant(submittedLease, context);
-    const durableLease = await this.coordinator.current(submittedLease);
-    if (!durableLease || !hasSameLifecycleAuthority(submittedLease, durableLease)) {
-      await this.recordPolicyDenial(durableLease ?? submittedLease, context);
-      throw new ForbiddenException('Connector authority policy denied');
-    }
-    return durableLease;
-  }
-
-  private async assertPolicy(
-    action: ConnectorLeasePolicyAction,
-    subject: Pick<ConnectorLease, 'identity' | 'bindingId' | 'connectorId'>,
-    context: ConnectorLeaseRequestContext,
-    requestedScopes: readonly string[],
-    requestedTtlMs: number | null,
-  ): Promise<void> {
-    const allowed = await this.policy.authorize({
-      action,
-      actorId: context.actorScope.userId,
-      tenantId: subject.identity.tenantId,
-      logicalAgentId: subject.identity.logicalAgentId,
-      bindingId: subject.bindingId,
-      connectorId: subject.connectorId,
-      requestedScopes: Object.freeze([...requestedScopes]),
-      requestedTtlMs,
-    });
-    if (!allowed) {
-      await this.recordPolicyDenial(subject, context);
-      throw new ForbiddenException('Connector authority policy denied');
-    }
-  }
-
-  private async recordPolicyDenial(
-    subject: Pick<ConnectorLease, 'identity' | 'bindingId' | 'connectorId'>,
-    context: ConnectorLeaseRequestContext,
-  ): Promise<void> {
-    const event: ConnectorLeaseAuditEvent = {
-      identity: subject.identity,
-      bindingId: subject.bindingId,
-      connectorId: subject.connectorId,
-      event: 'reject',
-      outcome: 'denied',
-      reason: 'policy_denied',
-      correlationId: this.correlation(context),
-      occurredAt: new Date().toISOString(),
-    };
-    await this.repository.recordAudit(event);
-  }
-
-  private correlation(context: ConnectorLeaseRequestContext): string {
-    return normalizeCorrelationId(context.correlationId);
-  }
-}
-
-function hasSameLifecycleAuthority(
-  submittedLease: ConnectorLease,
-  durableLease: ConnectorLease,
-): boolean {
-  return (
-    submittedLease.identity.tenantId === durableLease.identity.tenantId &&
-    submittedLease.identity.logicalAgentId === durableLease.identity.logicalAgentId &&
-    submittedLease.bindingId === durableLease.bindingId &&
-    submittedLease.leaseId === durableLease.leaseId &&
-    submittedLease.connectorId === durableLease.connectorId &&
-    submittedLease.leaseEpoch === durableLease.leaseEpoch &&
-    submittedLease.scopes.length === durableLease.scopes.length &&
-    submittedLease.scopes.every((scope: string, index: number): boolean => {
-      return scope === durableLease.scopes[index];
-    })
-  );
-}

docs/PERFORMANCE.md

@@ -152,10 +152,11 @@ for any `<Image>` components added in the future.
 ## How to Apply
 
 ```bash
-# PostgreSQL migration is a dedicated pre-runtime phase.
+# Run the DB migration (requires a live DB)
-# Deployment injects migration-only credentials/TLS material; Gateway startup only verifies readiness.
+pnpm --filter @mosaicstack/db exec drizzle-kit migrate
-mosaic-db-migrator --run
+
-mosaic-db-migrator --verify
+# Or, in Docker/Swarm — migrations run automatically on gateway startup
+# via runMigrations() in packages/db/src/migrate.ts
 ```
 
 ---

docs/PRD.md

@@ -125,35 +125,6 @@ are defined in [docs/TASKS.md](./TASKS.md) and must remain one card/one PR.
 
 ---
 
-## KBN-101 Database Runtime/Migration Role Split (#771)
-
-### Problem and objective
-
-PostgreSQL Gateway/storage currently uses one `DATABASE_URL` for runtime queries and migrations. That makes the deployed application identity an owner and prevents certification that KBN immutable event, artifact, checkpoint, and evidence relations reject runtime `UPDATE`/`DELETE`. KBN-101 freezes a least-privilege runtime/migration split before KBN-100 schema work.
-
-### Normative requirements
-
-1. `K101-REQ-01`: `DATABASE_URL` SHALL be the non-owner PostgreSQL runtime connection and `DATABASE_MIGRATION_URL` SHALL be the migration-only owner/migrator connection. They are required respectively for runtime and the dedicated `mosaic-db-migrator --run|--verify` phase in `standalone`/`federated`; local PGlite is the explicit exception. The published `@mosaicstack/db` bin maps exactly `mosaic-db-migrator` to `./dist/cli.js`, its image entrypoint is exactly `mosaic-db-migrator`, accepts no URL/SQL/schema/role argv, and returns stable sanitized exits. Every current/future PostgreSQL DDL entrypoint SHALL route to that runner or be denied, and SHALL reject `DATABASE_URL`-only execution before connection/DDL. Data migration may connect only after the runner prepares and verifies the PostgreSQL target, through dedicated non-DDL `mosaic_data_importer` and exactly `--target-url-file /run/secrets/mosaic_migrate_target_url` plus `--target-attestation-file /run/mosaic-attestations/migrate-target.v1.json`. The trusted runner verifies TLS/identity/manifest, reads the exact importer URL file only after strict safety checks, and signs a credential-free JCS/Ed25519 attestation using its runner-only fixed root-owned private-key file; no signing key reaches importer/runtime. The artifact binds secret version and SHA-256 of exact high-entropy credential-file bytes, canonical TLS host/port/database, CA/SPKI, PostgreSQL system identifier/database OID, importer role, manifest/schema fingerprints, producer invocation/build/image digest, issued/expires/nonce, and correlation. Before target connection the importer validates files/signature/key/expiry/replay/secret/digest/bindings; after verified TLS and before DML it validates server/database/role/CA/schema identity, with same-fd/in-memory-byte TOCTOU protection, rotation/revocation, atomic artifacts, and sanitized errors. Raw `--target-url`, `DATABASE_URL` fallback, runtime-owner use, missing/unsafe/substituted files, stale/replayed/tampered/wrong-key attestation, wrong binding, and DDL attempt fail before target connection/DDL; post-connect mismatch closes with zero DML/DDL. A reviewed finite classifier inventories executable current source/scripts/package bins, operator docs, deploy manifests, and exact normative contracts by path; active secure records pin both options/files, producer/key/bindings/tests, while normative contracts cannot mask instructions. Unknown active commands, duplicate-owner, ownerless, missing-path, and historical/status-only masking hits fail. `db:push` is forbidden outside an explicitly disposable local developer database and cannot accept a production-like URL.
-2. `K101-REQ-02`: Gateway runtime/replicas SHALL not execute migrations or DDL. The runner SHALL hold one `max:1` session and fixed two-int advisory namespace `1297044289` (`MOSA`), `1262636593` (`KBN1`) across preflight, reconciliation, migration, verification, and release. It SHALL compare the versioned canonical manifest v1 tuple (journal logical index/tag plus exact SQL-byte SHA-256) to the complete observed ledger mapping; count/set-only, timestamps, and physical insertion order are non-normative and insufficient.
-3. `K101-REQ-03`: PostgreSQL SHALL separate non-login platform database owner, non-login schema owner, dedicated `NOLOGIN SUPERUSER` `mosaic_extension_owner`, login migrator, dedicated login non-DDL data importer, non-login runtime capability, and login runtime roles. For PostgreSQL 17 + pgvector 0.8.2, `vector` is untrusted (`trusted` is absent and `relocatable=true`): only an externally controlled audited platform-bootstrap superuser session may `SET ROLE mosaic_extension_owner` for CREATE/UPDATE/SET SCHEMA, then `RESET ROLE`; the role has `rolcanlogin=false`, `rolsuper=true`, zero members, no runtime credential/Vault secret, and is never provided to app containers. It owns `mosaic_extensions`, fresh `vector`, and owner-bearing extension members, while `mosaic_schema_owner` receives only `USAGE` for type resolution and never ownership/`CREATE`/`ALTER`/`DROP`/member-change/default-privilege authority there. Superuser cannot be constrained by `GRANT`/`REVOKE`; this is identity/non-login/no-membership/external-control/audit isolation, not a false least-privilege claim. Extension operations require control-plane change, independent review, backup/rollback, maintenance window, and audit evidence. Managed targets that cannot establish this exact role are ineligible until an independently approved versioned provider-owned extension-owner profile exists; app/migrator ownership is never silently retained. Existing approved-owner extension relocation validates exact `pg_namespace.nspowner`, `pg_extension.extowner`, member ownership/schema/version, while legacy runtime-owned extension fails closed to a controlled shadow-database migration—never unsupported ownership alteration, catalog mutation, ownership adoption, or `DROP CASCADE`. Runtime, migrator, schema owner, importer, and all service roles must fail `SET ROLE`, catalog/direct `ALTER`/`UPDATE`/`DROP`/membership-change denial, role ownership, superuser/role-creation/schema-creation/TEMPORARY, unsafe membership, untrusted search path, missing grants, unauthenticated TLS, and immutable privilege drift checks. Application schema is fixed `mosaic` with exact `pg_catalog,mosaic` session path; historical public migrations remain byte-immutable legacy bootstrap only, every future Drizzle application declaration targets `mosaic`, and `vector` is explicitly qualified from non-writable `mosaic_extensions`. No config-derived SQL identifier is permitted.
-4. `K101-REQ-04`: `mosaicstack/stack` KBN-101-00 SHALL exclusively own `infra/pg-bootstrap/roles.sql`, `infra/pg-bootstrap/extensions.sql`, `infra/pg-bootstrap/README.md`, and bootstrap tests; KBN-101-05 SHALL exclusively own `tools/db/render-postgres-secrets.ts`, its tests, and current Compose/Portainer/two-gateway deployment declarations, consuming the versioned bootstrap interface without overlap. Environment IaC/Vault is named input and Mosaic deployment control plane/Jason is activation authority. Distinct runtime/migrator URL, CA, Gateway leaf, and PostgreSQL server key/certificate secrets are provisioned before a production-like database starts; runtime and migrator require mounted CA plus `sslmode=verify-full`. Exact UID/GID/mode/rendering, service-DNS SANs, Vault/compose/Swarm consumer isolation, two-gateway pair ordering, server activation, pre-enforcement legacy-client drain and `hostssl` zero-plaintext-session proof, fresh/existing transition, CA-overlap rotation, TLS-only rollback, and standalone/federated/Swarm/two-gateway positive/negative TLS evidence are required. No application-generated production certificate or plaintext bootstrap exception is permitted.
-5. `K101-REQ-05`: KBN immutable relations SHALL permit the real runtime role INSERT/SELECT only and deny UPDATE/DELETE; parent retention remains RESTRICT/no-cascade. Role/password/Vault creation is external platform control, never application migration/source.
-6. `K101-REQ-06`: N-1 single-URL compatibility, rollout/rollback, Vault ownership/rotation/redaction, CI, installer, compose/Portainer, observability, and deployment handoffs SHALL be separately bounded one-card/one-PR work. Prepared slices remain inactive while current owner-runtime deployments stay N-1; Mosaic control plane/Jason alone authorizes one final atomic activation or rollback, with no force-on-red/bypass. KBN-101 planning itself SHALL not mutate production.
-7. `K101-REQ-07`: KBN-100 SHALL begin only after the KBN-101 foundation role/schema-boundary certificate; it SHALL rebase on that main head, restore generated Drizzle declaration/snapshot/journal consistency, and bound procedural immutable-table grant/trigger/backfill additions to its schema slice. KBN-101 real deployed-role immutable-operation certification SHALL complete after KBN-100 creates those relations and before KBN-105.
-
-### Acceptance criteria
-
-1. `AC-K101-01`: DTO/command-matrix tests prove required modes, PGlite exception, `mosaic-db-migrator --help|--run|--verify`/stable exits/argv refusal, public-import negative, every finite classified DDL/static-bypass inventory path and both harness pairs reject `DATABASE_URL`-only before connection/DDL, no migration-to-runtime fallback, and `db:push` refusal outside an allowlisted disposable DB. The active `docs/guides/migrate-tier.md` route is inventoried to KBN-101-07 and proves runner-produced `--target-url-file /run/secrets/mosaic_migrate_target_url` plus `--target-attestation-file /run/mosaic-attestations/migrate-target.v1.json`; runner-only signing/private-key isolation; JCS/Ed25519 signature/key rotation/revocation, atomic artifact, expiry/replay, secret-version/digest, canonical TLS/CA/server/database/role/manifest/schema bindings, same-fd TOCTOU defense, dedicated non-DDL importer, and exact no-connection versus zero-DML rejection for missing/wrong/stale/replayed/tampered/wrong-key/substituted/binding-mismatched inputs. The full current non-normative docs inventory—including user guide and federation historical task status—has an exact safe disposition, and normative-contract classification cannot hide an instruction.
-2. `AC-K101-02`: Fixed namespace lock contention/crash/readiness/non-interference and exact manifest-v1 reconciliation tests prove no replica race/runtime auto-migration and fail closed on every missing/unknown/duplicate/ambiguous/corrupt/stale ledger state.
-3. `AC-K101-03`: Actual PostgreSQL 17 + pgvector 0.8.2 control-file, catalog, Drizzle-generation, vector-query/operator, fresh/approved-owner/legacy-shadow/partial/resume/rollback/N-1, and real deployed-role tests prove `trusted` absent/untrusted plus relocatability, external-superuser `SET ROLE` create/update/`RESET ROLE` audit, exact `rolcanlogin=false`/`rolsuper=true`/zero-membership/no-runtime-secret state, platform/schema/extension-owner/migrator/importer/runtime separation, `pg_extension.extowner` plus owner-bearing extension-member/schema/version assertions, and runtime/migrator/schema-owner/importer/all-service-role `SET ROLE`/ALTER/DROP/member-update denial. They also prove `pg_catalog,mosaic` per-session pool safety, `mosaic_extensions` qualification, identifier injection denial, ownership/membership/ledger-read/TEMP/default grants, and unsafe privilege denial.
-4. `AC-K101-04`: Disposable standalone, federated/Swarm, and two-gateway verified-TLS positives plus for both pairs missing CA/wrong CA/wrong SAN/sslmode downgrade, server/Gateway key mode, UID/GID, secret-consumer isolation, and legacy-drain/`hostssl` negatives prove server bootstrap, ordering, and readiness; PGlite is expressly excluded from this PostgreSQL evidence.
-5. `AC-K101-05`: Real runtime-role evidence proves INSERT/SELECT succeeds and UPDATE/DELETE fails for every frozen immutable KBN relation.
-6. `AC-K101-06`: N-1/atomic activation/rollback, Vault/CA-overlap rotation/redaction, health/operator behavior, CI/deployment handoff, independent exact-head security review, and terminal-green CI evidence the foundation before KBN-100; after KBN-100, the real deployed-role immutable-operation certificate and Ultron approval release KBN-105.
-
-**Normative implementation contract:** [`docs/native-kanban-sot/KBN-101-DB-ROLE-SPLIT.md`](./native-kanban-sot/KBN-101-DB-ROLE-SPLIT.md). `ASSUMPTION:` existing `standalone` and `federated` are all PostgreSQL production-like modes; any new PostgreSQL tier inherits these requirements until an explicit versioned amendment.
-
----
-
 ## Tess Interaction Agent Workstream (TESS)
 
 ### Problem and Objective
@@ -313,37 +284,6 @@ Use TDD for remote-ingress routing and permission boundaries. Required evidence
 
 ---
 
-## Mos Runtime Portability Workstream (MOS-PORT)
-
-### Problem and Objective
-
-Mos is currently identified partly by a harness-native session and communication process. Replacement/rebinding exists, but no gateway-enforced logical identity or fencing prevents a stale harness from continuing to reply or execute effects after takeover.
-
-The objective is to make Mos a server-derived logical Mosaic identity whose authority can move safely among runtime connectors. The gateway owns identity, lease, policy, and audit; harnesses remain replaceable adapters.
-
-### M1 Requirements
-
-1. `MOS-PORT-ID-001`: Define a normalized logical-agent identity independent of Claude Code, Pi, Codex, tmux, Matrix, and provider-native session IDs.
-2. `MOS-PORT-LEASE-001`: Persist one exclusive connector lease per tenant/logical-agent/binding with CAS acquisition, monotonic fencing epoch, TTL, heartbeat, explicit release, and takeover.
-3. `MOS-PORT-FENCE-001`: Bind every connector dispatch/execution grant to the current server-derived tenant, logical identity, binding, connector, scopes, expiry, and lease epoch.
-4. `MOS-PORT-FENCE-002`: Reject and audit stale, expired, forged, cross-tenant, cross-binding, and unauthorized grants before connector, channel, provider, or tool side effects.
-5. `MOS-PORT-OBS-001`: Emit credential-safe correlation/audit events for lease acquire, renew, takeover, reject, release, and expiry.
-6. `MOS-PORT-ARCH-001`: Runtime/provider adapters consume normalized lease context without adding harness-native schemas to Mosaic core.
-
-### M1 Acceptance Criteria
-
-1. `AC-MOS-PORT-01`: Two contenders for one binding cannot simultaneously hold current authority under concurrency.
-2. `AC-MOS-PORT-02`: Successful takeover increments the fencing epoch and every operation from the old epoch fails closed before side effects.
-3. `AC-MOS-PORT-03`: Gateway/database restart preserves lease and epoch state; expired leases can be recovered only through the authorized takeover path.
-4. `AC-MOS-PORT-04`: Cross-tenant, cross-agent, cross-binding, forged, and expired lease/grant cases are denied and audited.
-5. `AC-MOS-PORT-05`: Unit, migration, repository close/reopen, concurrency, abuse, gateway integration, independent security review, CI, and documentation gates pass.
-
-### Deferred to Later #754 Milestones
-
-Canonical checkpoint/handoff payloads, exactly-once connector receipts, concrete Claude/Pi/Codex adapters, channel cutover, and full cross-harness failover/rollback E2E are explicitly out of M1 scope.
-
----
-
 ## Architecture
 
 ### High-Level System Diagram

docs/SITEMAP.md

@@ -14,10 +14,7 @@
 - [Workstream index](native-kanban-sot/INDEX.md) — artifact map, lane partition, and delivery order.
 - [Mission manifest](native-kanban-sot/MISSION-MANIFEST.md) — scope, authority, invariants, and gate model.
 - [Task decomposition](native-kanban-sot/TASKS.md) — dependency-ordered implementation slices and ownership boundaries.
-- [KBN-101 database role split](native-kanban-sot/KBN-101-DB-ROLE-SPLIT.md) — rc.11 runner-signed target-bound importer attestation, complete operator-route inventory, PostgreSQL-valid pgvector owner exception, disjoint card manifests, classifier, runner, verified TLS, activation, and certification prerequisite.
-- [Federated tier data migration](guides/migrate-tier.md) — active KBN-101-07 operator route: runner-produced target attestation, dedicated non-DDL importer, and paired credential-/attestation-file references only.
 - [Frozen shared contract](native-kanban-sot/SHARED-CONTRACT.md) — schema, API, Coordinator, health, recovery, and migration contracts.
-- [KBN-101 exact-head security review](reports/native-kanban-sot/kbn-101-contract-security-review-82ce325.md) — retained prior REQUEST CHANGES evidence for `da742ca`; rc.11 awaits independent exact-head re-review after closing the target-attestation and operator-inventory HIGH findings.
 - [Initial independent review](reports/native-kanban-sot/canon-initial-review-no-go.md) — KCR-001–016 findings that blocked the first draft.
 - [Final independent re-review](reports/native-kanban-sot/canon-final-rereview-go.md) — closure evidence and GO verdict.
 - [Ultron final gate](reports/native-kanban-sot/ultron-final-go.md) — final requirements, authority, schema, migration, recovery, and evidence review.
@@ -59,5 +56,3 @@
 - [Optional AI egress gateway ADR](architecture/ADR-MOS-EGRESS-GATEWAYS.md) — placement and gates for LiteLLM, Bifrost, and purpose-built translation proxies.
 - [Runtime-neutral Mos identity and failover mission](https://git.mosaicstack.dev/mosaicstack/stack/issues/754)
 - [Logical identity and connector lease/fencing implementation](https://git.mosaicstack.dev/mosaicstack/stack/issues/755)
-- [M1 logical identity and fencing architecture](architecture/mos-runtime-portability-m1.md)
-- [M1 connector lease operations](guides/mos-connector-lease-operations.md)

docs/TASKS.md

@@ -52,20 +52,20 @@ Active workstream is **W1 — Federation v1**. Workers should:
 > the repository quality gates, independent code and security review, terminal-green CI, and
 > the applicable acceptance evidence before merge. Issue #758 remains open until M5 closes.
 
-| id         | status      | description                                                                                                                                                            | issue | agent         | repo              | branch                                  | depends_on                                     | estimate | notes                                                                                                                    |
+| id         | status      | description                                                                                                                                                            | issue | agent  | repo              | branch                                  | depends_on                                     | estimate | notes                                                                                                            |
-| ---------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ------------- | ----------------- | --------------------------------------- | ---------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
+| ---------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ------ | ----------------- | --------------------------------------- | ---------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
-| FCM-M0-001 | done        | Publish normative PRD requirements/acceptance criteria, this M0–M5 DAG, docs-IA checklist, and legacy example/profile disposition inventory; no implementation changes | #758  | sonnet        | mosaicstack/stack | `docs/758-fleet-config-management`      | —                                              | 18K      | Merged via #760 (`c32d85a`); parent #758 intentionally remains open through M5                                           |
+| FCM-M0-001 | in-progress | Publish normative PRD requirements/acceptance criteria, this M0–M5 DAG, docs-IA checklist, and legacy example/profile disposition inventory; no implementation changes | #758  | sonnet | mosaicstack/stack | `docs/758-fleet-config-management`      | —                                              | 18K      | M0 exit: approved docs; every shipped example/profile/service preset classified; docs-only PR                    |
-| FCM-M1-001 | done        | Implement narrow local-tmux v2 roster structural contract/compiler with YAML/JSON canonicalization and schema/parser parity tests                                      | #758  | coder0        | mosaicstack/stack | `feat/758-roster-v2-compiler`           | FCM-M0-001                                     | 30K      | #764 squash `aa5b43b`; exact-head RoR and PR/main terminal-green CI; no lifecycle or live mutation                       |
+| FCM-M1-001 | not-started | Implement narrow local-tmux v2 roster structural contract/compiler with YAML/JSON canonicalization and schema/parser parity tests                                      | #758  | codex  | mosaicstack/stack | `feat/758-roster-v2-compiler`           | FCM-M0-001                                     | 30K      | No lifecycle, remote, connector, secret, channel, or gateway work                                                |
-| FCM-M1-002 | in-progress | Reuse existing profile/persona/provision resolver for roster semantics; add canonical class/authority validation and approved aliases                                  | #758  | native-sonnet | mosaicstack/stack | `feat/758-shared-role-resolution`       | FCM-M0-001                                     | 25K      | Started 2026-07-14 from `aa5b43b`; one shared resolver only; validator certificate-only; merge-gate sole merge authority |
+| FCM-M1-002 | not-started | Reuse existing profile/persona/provision resolver for roster semantics; add canonical class/authority validation and approved aliases                                  | #758  | codex  | mosaicstack/stack | `feat/758-shared-role-resolution`       | FCM-M0-001                                     | 25K      | Validator is certificate-only; merge-gate remains sole merge authority                                           |
-| FCM-M1-003 | not-started | Convert the M0 legacy inventory into executable example/profile/service-preset validation and explicit v1-version/retirement checks                                    | #758  | codex         | mosaicstack/stack | `test/758-example-profile-dispositions` | FCM-M1-001, FCM-M1-002                         | 20K      | Every shipped artifact must validate, be versioned v1, or be retired with replacement                                    |
+| FCM-M1-003 | not-started | Convert the M0 legacy inventory into executable example/profile/service-preset validation and explicit v1-version/retirement checks                                    | #758  | codex  | mosaicstack/stack | `test/758-example-profile-dispositions` | FCM-M1-001, FCM-M1-002                         | 20K      | Every shipped artifact must validate, be versioned v1, or be retired with replacement                            |
-| FCM-M2-001 | not-started | Migrate generic launch chain to deterministic `.env.generated` plus strict data-only `.env.local`; quarantine forbidden legacy keys                                    | #758  | codex         | mosaicstack/stack | `feat/758-generated-env-boundary`       | FCM-M1-001, FCM-M1-002                         | 30K      | No arbitrary command compatibility path; diagnostics expose key names/hashes only                                        |
+| FCM-M2-001 | not-started | Migrate generic launch chain to deterministic `.env.generated` plus strict data-only `.env.local`; quarantine forbidden legacy keys                                    | #758  | codex  | mosaicstack/stack | `feat/758-generated-env-boundary`       | FCM-M1-001, FCM-M1-002                         | 30K      | No arbitrary command compatibility path; diagnostics expose key names/hashes only                                |
-| FCM-M2-002 | not-started | Add generation-guarded local fleet agent create/get/update/delete mutations with plan/dry-run, atomic roster writes, and recovery output                               | #758  | codex         | mosaicstack/stack | `feat/758-fleet-agent-crud`             | FCM-M1-001, FCM-M2-001                         | 30K      | Fresh create persists stopped unless explicit persisted start                                                            |
+| FCM-M2-002 | not-started | Add generation-guarded local fleet agent create/get/update/delete mutations with plan/dry-run, atomic roster writes, and recovery output                               | #758  | codex  | mosaicstack/stack | `feat/758-fleet-agent-crud`             | FCM-M1-001, FCM-M2-001                         | 30K      | Fresh create persists stopped unless explicit persisted start                                                    |
-| FCM-M3-001 | not-started | Implement local roster-owned reconcile/apply plus lifecycle/status/verify/doctor contracts and stable JSON/exit codes                                                  | #758  | codex         | mosaicstack/stack | `feat/758-local-reconciler`             | FCM-M2-001, FCM-M2-002                         | 35K      | Exact systemd/tmux ownership; remote/schema-only entries are inventory only                                              |
+| FCM-M3-001 | not-started | Implement local roster-owned reconcile/apply plus lifecycle/status/verify/doctor contracts and stable JSON/exit codes                                                  | #758  | codex  | mosaicstack/stack | `feat/758-local-reconciler`             | FCM-M2-001, FCM-M2-002                         | 35K      | Exact systemd/tmux ownership; remote/schema-only entries are inventory only                                      |
-| FCM-M3-002 | not-started | Add isolated systemd/tmux lifecycle, drift, socket, unmanaged-session, crash, and rollback acceptance coverage                                                         | #758  | sonnet        | mosaicstack/stack | `test/758-reconciler-lifecycle-gates`   | FCM-M3-001                                     | 25K      | Proves stopped-state preservation and zero fuzzy destructive targeting                                                   |
+| FCM-M3-002 | not-started | Add isolated systemd/tmux lifecycle, drift, socket, unmanaged-session, crash, and rollback acceptance coverage                                                         | #758  | sonnet | mosaicstack/stack | `test/758-reconciler-lifecycle-gates`   | FCM-M3-001                                     | 25K      | Proves stopped-state preservation and zero fuzzy destructive targeting                                           |
-| FCM-M4-001 | not-started | Implement field-complete v1-to-v2 inventory/preview/migrator with alias, lifecycle, env-quarantine, and remote/connector disposition evidence                          | #758  | codex         | mosaicstack/stack | `feat/758-v1-v2-migrator`               | FCM-M1-003, FCM-M3-001                         | 35K      | Preview first; no unreviewed lifecycle inference                                                                         |
+| FCM-M4-001 | not-started | Implement field-complete v1-to-v2 inventory/preview/migrator with alias, lifecycle, env-quarantine, and remote/connector disposition evidence                          | #758  | codex  | mosaicstack/stack | `feat/758-v1-v2-migrator`               | FCM-M1-003, FCM-M3-001                         | 35K      | Preview first; no unreviewed lifecycle inference                                                                 |
-| FCM-M4-002 | not-started | Add reversible canary migration, rollback, stale-projection/orphan classification, and current-host 9-managed/3-unmanaged fixture coverage                             | #758  | sonnet        | mosaicstack/stack | `test/758-migration-rollback-gates`     | FCM-M4-001, FCM-M3-002                         | 25K      | Never starts a previously stopped agent or kills an unproven unmanaged session                                           |
+| FCM-M4-002 | not-started | Add reversible canary migration, rollback, stale-projection/orphan classification, and current-host 9-managed/3-unmanaged fixture coverage                             | #758  | sonnet | mosaicstack/stack | `test/758-migration-rollback-gates`     | FCM-M4-001, FCM-M3-002                         | 25K      | Never starts a previously stopped agent or kills an unproven unmanaged session                                   |
-| FCM-M5-001 | not-started | Deliver the accepted fleet documentation IA, how-to/operations/migration references, and link/example validation                                                       | #758  | haiku         | mosaicstack/stack | `docs/758-fleet-config-operator-docs`   | FCM-M1-003, FCM-M2-002, FCM-M3-001, FCM-M4-001 | 24K      | Must close every checklist item or record an approved deferral                                                           |
+| FCM-M5-001 | not-started | Deliver the accepted fleet documentation IA, how-to/operations/migration references, and link/example validation                                                       | #758  | haiku  | mosaicstack/stack | `docs/758-fleet-config-operator-docs`   | FCM-M1-003, FCM-M2-002, FCM-M3-001, FCM-M4-001 | 24K      | Must close every checklist item or record an approved deferral                                                   |
-| FCM-M5-002 | not-started | Package/update asset-drift checks, rolling local canary, independent validation certificate, and release evidence                                                      | #758  | sonnet        | mosaicstack/stack | `feat/758-fleet-config-release-gate`    | FCM-M3-002, FCM-M4-002, FCM-M5-001             | 30K      | Final #758 gate: quality, independent code/security review, validator certificate, merge-gate approval, green CI         |
+| FCM-M5-002 | not-started | Package/update asset-drift checks, rolling local canary, independent validation certificate, and release evidence                                                      | #758  | sonnet | mosaicstack/stack | `feat/758-fleet-config-release-gate`    | FCM-M3-002, FCM-M4-002, FCM-M5-001             | 30K      | Final #758 gate: quality, independent code/security review, validator certificate, merge-gate approval, green CI |
 
 ## Thin-core prompt diet (#528) — feat/contract-thin-core
 

docs/architecture/mos-runtime-portability-m1.md

@@ -1,49 +0,0 @@
-# Mos Runtime Portability M1 — Logical Identity and Fencing
-
-## Boundary
-
-M1 separates the logical Mosaic agent from any Claude, Pi, Codex, tmux, Matrix, or provider-native session. The normalized identity is:
-
-```text
-(tenant_id, logical_agent_id, binding_id)
-```
-
-`logical_agent_id` is a server-owned stable identifier. A connector is a replaceable holder of a lease for one binding; it is not the agent identity.
-
-## Durable lease model
-
-PostgreSQL table `logical_agent_connector_leases` has one unique row per identity/binding tuple. The current row records:
-
-- an opaque lease UUID;
-- connector ID and normalized allowed scopes;
-- a positive decimal fencing epoch stored as PostgreSQL `bigint`;
-- acquired, heartbeat, expiry, release, and update timestamps.
-
-Initial acquisition is insert-only. An existing active row causes `lease_held`. An expired or released row causes `takeover_required`; ordinary acquisition cannot recover it. Authorized takeover uses compare-and-swap against the expected epoch, rotates the lease UUID, and increments the epoch atomically. Heartbeat and release match the full identity, binding, connector, lease UUID, and epoch.
-
-The companion `connector_lease_audit_log` is append-only metadata. It stores lifecycle event, outcome/reason, identity/binding/connector, epoch, correlation ID, and timestamp. It deliberately excludes scopes, grant objects, payloads, approval references, tokens, and credentials.
-
-## Execution grants
-
-`ConnectorLeaseCoordinator` issues a short-lived internal grant only after rereading the durable current lease. Defense-in-depth caps leases at 5 minutes and grants at 30 seconds by default; constructor options may tighten these limits. A grant is bound to tenant, logical agent, binding, connector, lease UUID, scope subset, expiry, and epoch.
-
-Validation occurs immediately before adapter invocation and rereads PostgreSQL. The adapter receives only `ConnectorExecutionContext`; harness-native schemas remain behind the adapter. Validation denies:
-
-- grants not minted by the current gateway process (including cloned/forged objects);
-- expired grants or leases;
-- released leases;
-- stale epochs or replaced connector/lease UUIDs;
-- missing/cross-tenant/cross-agent/cross-binding leases;
-- scopes not authorized by both grant and current lease.
-
-A gateway restart intentionally invalidates process-local grants. The durable lease and epoch survive, and a fresh grant may be issued only after current-lease and gateway-policy validation.
-
-## Concurrency and side-effect rule
-
-The database CAS determines the sole current holder. A successful takeover makes every old-epoch validation fail. Connector adapters must consume and propagate the normalized lease epoch/context so downstream effect boundaries can also fence races that occur after gateway validation.
-
-M1 does not provide exactly-once receipts or a side-effect journal. Those remain later #754 work; callers must not infer exactly-once delivery from lease fencing.
-
-## Extension boundary
-
-`ConnectorLeaseService` is the gateway-owned policy surface. Every policy decision receives the normalized requested scopes and TTL (or explicit `null` where no TTL applies), so a concrete policy can enforce least privilege and duration limits. Its production default policy denies every lease/grant operation until a server-configured connector policy is supplied. No M1 HTTP endpoint accepts caller-controlled tenant or logical identity, and no concrete Claude/Pi/Codex adapter or channel cutover is included.

docs/design/storage-abstraction-middleware.md

@@ -70,10 +70,6 @@ export function createQueue(config?: QueueConfig): QueueHandle {
 
 ### `@mosaicstack/db` (packages/db/src/client.ts)
 
-> **Historical design specimen — status-only, not an operator instruction.** KBN-101 supersedes
-> this pre-split `DATABASE_URL` fallback shape; it cannot authorize runtime migration, DDL, or a
-> connection-string fallback. See the KBN-101 runner/role contract for the produced interface.
-
 ```typescript
 import { drizzle, type PostgresJsDatabase } from 'drizzle-orm/postgres-js';
 import postgres from 'postgres';

docs/federation/SETUP.md

@@ -30,11 +30,22 @@ Expected output shows `postgres-federated` and `valkey-federated` both healthy.
 
 ## Configure mosaic for federated tier
 
-KBN-101 supersedes the former inline federated database configuration. Do not put a DSN in
+Create or update your `mosaic.config.json`:
-`mosaic.config.json` or export one in a shell. The reviewed deployment renderer mounts the
+
-runtime secret only to Gateway and the migration secret only to the one-shot runner; the runtime
+```json
-uses verified TLS and the runner verifies schema readiness before Gateway starts. Queue
+{
-configuration remains deployment-owned.
+  "tier": "federated",
+  "database": "postgresql://mosaic:mosaic@localhost:5433/mosaic",
+  "queue": "redis://localhost:6380"
+}
+```
+
+If you're using environment variables instead:
+
+```bash
+export DATABASE_URL="postgresql://mosaic:mosaic@localhost:5433/mosaic"
+export REDIS_URL="redis://localhost:6380"
+```
 
 ## Verify health
 
@@ -179,8 +190,11 @@ PG_FEDERATED_HOST_PORT=5434 VALKEY_FEDERATED_HOST_PORT=6381 \
 docker compose -f docker-compose.federated.yml logs postgres-federated | grep -i vector
 ```
 
-Do not create it manually. A missing extension is a failed reviewed bootstrap/runner
+If missing, exec into the container and create it manually:
-precondition: stop the stack and remediate through the KBN-101 external bootstrap control plane.
+
+```bash
+docker exec <postgres-federated-id> psql -U mosaic -d mosaic -c "CREATE EXTENSION vector;"
+```
 
 ### Valkey connection refused
 

docs/federation/TASKS.md

@@ -15,20 +15,20 @@
 
 Goal: Gateway runs in `federated` tier with containerized PG+pgvector+Valkey. No federation logic yet. Existing standalone behavior does not regress.
 
-| id        | status | description                                                                                                                                                                                                        | issue | agent  | branch                             | depends_on | estimate | notes                                                                                                                                                                                                                                                 |
+| id        | status | description                                                                                                                                                                                                        | issue | agent  | branch                             | depends_on | estimate | notes                                                                                                                                            |
-| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | ------ | ---------------------------------- | ---------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | ------ | ---------------------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| FED-M1-01 | done   | Extend `mosaic.config.json` schema: add `"federated"` to `tier` enum in validator + TS types. Keep `local` and `standalone` working. Update schema docs/README where referenced.                                   | #460  | sonnet | feat/federation-m1-tier-config     | —          | 4K       | Shipped in PR #470. Renamed `team` → `standalone`; added `team` deprecation alias; added `DEFAULT_FEDERATED_CONFIG`.                                                                                                                                  |
+| FED-M1-01 | done   | Extend `mosaic.config.json` schema: add `"federated"` to `tier` enum in validator + TS types. Keep `local` and `standalone` working. Update schema docs/README where referenced.                                   | #460  | sonnet | feat/federation-m1-tier-config     | —          | 4K       | Shipped in PR #470. Renamed `team` → `standalone`; added `team` deprecation alias; added `DEFAULT_FEDERATED_CONFIG`.                             |
-| FED-M1-02 | done   | Author `docker-compose.federated.yml` as an overlay profile: Postgres 17 + pgvector extension (port 5433), Valkey (6380), named volumes, healthchecks. Compose-up should boot cleanly on a clean machine.          | #460  | sonnet | feat/federation-m1-compose         | FED-M1-01  | 5K       | Shipped in PR #471. Overlay defines `postgres-federated`/`valkey-federated`, profile-gated, with pg-init for pgvector extension.                                                                                                                      |
+| FED-M1-02 | done   | Author `docker-compose.federated.yml` as an overlay profile: Postgres 17 + pgvector extension (port 5433), Valkey (6380), named volumes, healthchecks. Compose-up should boot cleanly on a clean machine.          | #460  | sonnet | feat/federation-m1-compose         | FED-M1-01  | 5K       | Shipped in PR #471. Overlay defines `postgres-federated`/`valkey-federated`, profile-gated, with pg-init for pgvector extension.                 |
-| FED-M1-03 | done   | Historical shipped-status record: add pgvector support to `packages/storage/src/adapters/postgres.ts`; no adapter changes for non-federated tiers.                                                                 | #460  | sonnet | feat/federation-m1-pgvector        | FED-M1-02  | 8K       | Shipped in PR #472 status only. **KBN-101 supersedes this behavior:** it cannot authorize current runtime extension creation or any DDL; only the runner/external bootstrap contract may do so.                                                       |
+| FED-M1-03 | done   | Add pgvector support to `packages/storage/src/adapters/postgres.ts`: create extension on init (idempotent), expose vector column type in schema helpers. No adapter changes for non-federated tiers.               | #460  | sonnet | feat/federation-m1-pgvector        | FED-M1-02  | 8K       | Shipped in PR #472. `enableVector` flag on postgres StorageConfig; idempotent CREATE EXTENSION before migrations.                                |
-| FED-M1-04 | done   | Implement `apps/gateway/src/bootstrap/tier-detector.ts`: reads config, asserts PG/Valkey/pgvector reachable for `federated`, fail-fast with actionable error message on failure. Unit tests for each failure mode. | #460  | sonnet | feat/federation-m1-detector        | FED-M1-03  | 8K       | Shipped in PR #473. 12 tests; 5s timeouts on probes; pgvector library/permission discrimination; rejects non-bullmq for federated.                                                                                                                    |
+| FED-M1-04 | done   | Implement `apps/gateway/src/bootstrap/tier-detector.ts`: reads config, asserts PG/Valkey/pgvector reachable for `federated`, fail-fast with actionable error message on failure. Unit tests for each failure mode. | #460  | sonnet | feat/federation-m1-detector        | FED-M1-03  | 8K       | Shipped in PR #473. 12 tests; 5s timeouts on probes; pgvector library/permission discrimination; rejects non-bullmq for federated.               |
-| FED-M1-05 | done   | Historical shipped-status record: prior tier migration implementation.                                                                                                                                             | #460  | sonnet | feat/federation-m1-migrate         | FED-M1-04  | 10K      | Shipped in PR #474 status only. **KBN-101 supersedes this route:** it cannot authorize current credentials, target connection, or DDL. The future active route requires runner verification plus target URL-file and signed attestation-file binding. |
+| FED-M1-05 | done   | Write `scripts/migrate-to-federated.ts`: one-way migration from `local` (PGlite) / `standalone` (PG without pgvector) → `federated`. Dumps, transforms, loads; dry-run + confirm UX. Idempotent on re-run.         | #460  | sonnet | feat/federation-m1-migrate         | FED-M1-04  | 10K      | Shipped in PR #474. `mosaic storage migrate-tier`; DrizzleMigrationSource (corrects P0 found in review); 32 tests; idempotent.                   |
-| FED-M1-06 | done   | Update `mosaic doctor`: report current tier, required services, actual health per service, pgvector presence, overall green/yellow/red. Machine-readable JSON output flag for CI use.                              | #460  | sonnet | feat/federation-m1-doctor          | FED-M1-04  | 6K       | Shipped in PR #475 as `mosaic gateway doctor`. Probes lifted to @mosaicstack/storage; structural TierConfig breaks dep cycle.                                                                                                                         |
+| FED-M1-06 | done   | Update `mosaic doctor`: report current tier, required services, actual health per service, pgvector presence, overall green/yellow/red. Machine-readable JSON output flag for CI use.                              | #460  | sonnet | feat/federation-m1-doctor          | FED-M1-04  | 6K       | Shipped in PR #475 as `mosaic gateway doctor`. Probes lifted to @mosaicstack/storage; structural TierConfig breaks dep cycle.                    |
-| FED-M1-07 | done   | Integration test: gateway boots in `federated` tier with docker-compose `federated` profile; refuses to boot when PG unreachable (asserts fail-fast); pgvector extension query succeeds.                           | #460  | sonnet | feat/federation-m1-integration     | FED-M1-04  | 8K       | Shipped in PR #476. 3 test files, 4 tests, gated by FEDERATED_INTEGRATION=1; reserved-port helper avoids host collisions.                                                                                                                             |
+| FED-M1-07 | done   | Integration test: gateway boots in `federated` tier with docker-compose `federated` profile; refuses to boot when PG unreachable (asserts fail-fast); pgvector extension query succeeds.                           | #460  | sonnet | feat/federation-m1-integration     | FED-M1-04  | 8K       | Shipped in PR #476. 3 test files, 4 tests, gated by FEDERATED_INTEGRATION=1; reserved-port helper avoids host collisions.                        |
-| FED-M1-08 | done   | Integration test for migration script: seed a local PGlite with representative data (tasks, notes, users, teams), run migration, assert row counts + key samples equal on federated PG.                            | #460  | sonnet | feat/federation-m1-migrate-test    | FED-M1-05  | 6K       | Shipped in PR #477. Caught P0 in M1-05 (camelCase→snake_case) missed by mocked unit tests; fix in same PR.                                                                                                                                            |
+| FED-M1-08 | done   | Integration test for migration script: seed a local PGlite with representative data (tasks, notes, users, teams), run migration, assert row counts + key samples equal on federated PG.                            | #460  | sonnet | feat/federation-m1-migrate-test    | FED-M1-05  | 6K       | Shipped in PR #477. Caught P0 in M1-05 (camelCase→snake_case) missed by mocked unit tests; fix in same PR.                                       |
-| FED-M1-09 | done   | Standalone regression: full agent-session E2E on existing `standalone` tier with a gateway built from this branch. Must pass without referencing any federation module.                                            | #460  | sonnet | feat/federation-m1-regression      | FED-M1-07  | 4K       | Clean canary. 351 gateway tests + 85 storage unit tests + full pnpm test all green; only FEDERATED_INTEGRATION-gated tests skip.                                                                                                                      |
+| FED-M1-09 | done   | Standalone regression: full agent-session E2E on existing `standalone` tier with a gateway built from this branch. Must pass without referencing any federation module.                                            | #460  | sonnet | feat/federation-m1-regression      | FED-M1-07  | 4K       | Clean canary. 351 gateway tests + 85 storage unit tests + full pnpm test all green; only FEDERATED_INTEGRATION-gated tests skip.                 |
-| FED-M1-10 | done   | Code review pass: security-focused on the migration script (data-at-rest during migration) + tier detector (error-message sensitivity leakage). Independent reviewer, not authors of tasks 01-09.                  | #460  | sonnet | feat/federation-m1-security-review | FED-M1-09  | 8K       | 2 review rounds caught 7 issues: credential leak in pg/valkey/pgvector errors + redact-error util; missing advisory lock; SKIP_TABLES rationale.                                                                                                      |
+| FED-M1-10 | done   | Code review pass: security-focused on the migration script (data-at-rest during migration) + tier detector (error-message sensitivity leakage). Independent reviewer, not authors of tasks 01-09.                  | #460  | sonnet | feat/federation-m1-security-review | FED-M1-09  | 8K       | 2 review rounds caught 7 issues: credential leak in pg/valkey/pgvector errors + redact-error util; missing advisory lock; SKIP_TABLES rationale. |
-| FED-M1-11 | done   | Docs update: `docs/federation/` operator notes for tier setup; README blurb on federated tier; `docs/guides/` entry for migration. Do NOT touch runbook yet (deferred to FED-M7).                                  | #460  | haiku  | feat/federation-m1-docs            | FED-M1-10  | 4K       | Shipped: `docs/federation/SETUP.md` (119 lines), `docs/guides/migrate-tier.md` (147 lines), README Configuration blurb.                                                                                                                               |
+| FED-M1-11 | done   | Docs update: `docs/federation/` operator notes for tier setup; README blurb on federated tier; `docs/guides/` entry for migration. Do NOT touch runbook yet (deferred to FED-M7).                                  | #460  | haiku  | feat/federation-m1-docs            | FED-M1-10  | 4K       | Shipped: `docs/federation/SETUP.md` (119 lines), `docs/guides/migrate-tier.md` (147 lines), README Configuration blurb.                          |
-| FED-M1-12 | done   | PR, CI green, merge to main, close #460.                                                                                                                                                                           | #460  | sonnet | feat/federation-m1-close           | FED-M1-11  | 3K       | M1 closed. PRs #470-#480 merged across 11 tasks. Issue #460 closed; release tag `fed-v0.1.0-m1` published.                                                                                                                                            |
+| FED-M1-12 | done   | PR, CI green, merge to main, close #460.                                                                                                                                                                           | #460  | sonnet | feat/federation-m1-close           | FED-M1-11  | 3K       | M1 closed. PRs #470-#480 merged across 11 tasks. Issue #460 closed; release tag `fed-v0.1.0-m1` published.                                       |
 
 **M1 total estimate:** ~74K tokens (over-budget vs 20K PRD estimate — explanation below)
 

docs/fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md

@@ -7,8 +7,7 @@ The v2 compiler may not silently accept an unresolved class. Before M1 exits, ev
 below must be either migrated and executable, retained as an explicitly versioned v1 fixture, or
 retired with a replacement/deprecation note. Class resolution must use the existing
 profile/persona/provision baseline-plus-`roles.local` resolver; this inventory does not create a
-parallel resolver. The current executable implementation and per-artifact outcomes are recorded in
+parallel resolver.
-[the disposition evidence](./migration/example-profile-disposition.md).
 
 ## Examples
 

docs/fleet/backlog-conventions.md

@@ -14,17 +14,18 @@ and surfaced as `mosaic fleet backlog <sub> --json`.
 The backlog uses the existing Mosaic storage layer; there is **no** new database
 engine (no sqlite, no raw client).
 
-| Condition                          | Tier                 | Data location                                                    |
+| Condition                      | Tier                 | Data location                    |
-| ---------------------------------- | -------------------- | ---------------------------------------------------------------- |
+| ------------------------------ | -------------------- | -------------------------------- |
-| `DATABASE_URL` injected at runtime | Full server Postgres | the verified runtime database; it never authorizes migration/DDL |
+| `DATABASE_URL` set             | Full server Postgres | the configured database          |
-| `PGLITE_DATA_DIR` set (no URL)     | Embedded PGlite      | that directory                                                   |
+| `PGLITE_DATA_DIR` set (no URL) | Embedded PGlite      | that directory                   |
-| neither (default)                  | Embedded PGlite      | `~/.config/mosaic/fleet/backlog`                                 |
+| neither (default)              | Embedded PGlite      | `~/.config/mosaic/fleet/backlog` |
 
 PGlite is real Postgres semantics in-process — including the row locks the atomic
 claim relies on — so the **same code** runs on a laptop (embedded, single-host
 default) and on a full Postgres deployment. Switching tiers is config-only.
 
-For embedded PGlite only, the local backlog routine may prepare its local schema on first use. PostgreSQL never migrates on CLI first use: it requires the dedicated `mosaic-db-migrator --run` phase and its read-only runtime readiness check before `mosaic fleet backlog` connects.
+The schema (`backlog` table) is created automatically on first CLI use:
+`runMigrations()` for Postgres, `runPgliteMigrations()` for embedded PGlite.
 
 ### Update safety
 

docs/fleet/how-to/customize-roles.md

@@ -1,54 +0,0 @@
-# Customize Fleet Roles
-
-Mosaic resolves persona contracts through two layers:
-
-1. `fleet/roles/<canonical-class>.md` — seeded baseline contract.
-2. `fleet/roles.local/<canonical-class>.md` — operator override or custom role; this layer wins.
-
-The same shared resolver is used by profile validation, provisioning, roster-v2 semantic validation,
-and launch-time persona injection.
-
-## Override a baseline role
-
-Create a readable Markdown contract under `roles.local` with the canonical filename and class marker:
-
-```markdown
-# Code — local role definition
-
-The local code role (`class: code`) follows the operator's repository conventions.
-```
-
-Save it as `fleet/roles.local/code.md`. Do not edit generated or seeded baseline assets when the goal
-is a durable local customization.
-
-Legacy aliases canonicalize before lookup. Therefore `roles.local/implementer.md` does not override
-`code`; use `roles.local/code.md`. See [Legacy Fleet Class Aliases](../migration/legacy-class-aliases.md).
-
-## Add a custom class
-
-A custom class remains supported when a readable contract exists for the exact identifier:
-
-```markdown
-# Release notes — local role definition
-
-The release-notes role (`class: release-notes`) prepares operator-reviewed release copy.
-```
-
-Save it as `fleet/roles.local/release-notes.md`, then reference `class: release-notes` and a matching
-`tool_policy: release-notes` in roster v2. Adding only a `LIBRARY.md` row is insufficient.
-
-Names such as `worker`, `analyst`, and `canary` are not built-in aliases; they need genuine custom
-contracts. `agents[].alias`, Tess, and Ultron are display names and cannot select a class.
-
-## Validation and authority boundaries
-
-Semantic validation reads the winning contract and rejects missing, unreadable, or empty files.
-Protected authority is derived from canonical class metadata in code, never from role prose. A custom
-contract cannot claim merge, validation-certificate, orchestration, lease, or interaction authority.
-
-Roster v2 also fails closed when a protected class and tool policy do not match after canonicalization,
-or when an unprotected class claims a protected tool policy. The legacy `operator-interaction` policy
-canonicalizes to `interaction`.
-
-Role customization does not issue leases, store validation certificates, mutate credentials, or
-change lifecycle state.

docs/fleet/migration/example-profile-disposition.md

@@ -1,52 +0,0 @@
-# Executable Fleet Example, Profile, and Service-Preset Dispositions
-
-**Issue:** #758 · **Card:** FCM-M1-003 · **Status:** M1 executable disposition evidence
-
-This document records the executable disposition for every currently shipped fleet YAML artifact.
-The authoritative baseline classification remains the
-[legacy inventory](../LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md). The executable guard is
-`packages/mosaic/src/fleet/example-profile-dispositions.ts`; its test fails if a shipped YAML
-artifact is added, removed, or left without one of the dispositions below.
-
-## Disposition rules
-
-- **Explicit v1 fixture:** the artifact is loaded through the existing v1 roster parser and must
-  declare `version: 1`. It remains a compatibility fixture; it is not silently treated as a v2
-  roster or given inferred aliases.
-- **Canonical profile:** the artifact is loaded through `loadProfiles`, which uses the shared
-  baseline-plus-`roles.local` persona resolver and rejects unreadable or unresolved classes.
-- **Canonical service policy:** the artifact is loaded through the operator-interaction service
-  policy reader and provisioned with a generic supplied identity. It validates its runtime, model,
-  reasoning, and legacy tool-policy compatibility without hardcoding a product identity.
-
-No artifact is retired in this card. A later retirement requires both a replacement link and a
-visible deprecation note; the executable guard must then record the new disposition before the
-artifact can be removed.
-
-## Shipped artifacts
-
-| Artifact                             | Disposition              | Executable path                   | Compatibility notes                                                                              |
-| ------------------------------------ | ------------------------ | --------------------------------- | ------------------------------------------------------------------------------------------------ |
-| `examples/coding.yaml`               | Explicit v1 fixture      | v1 roster parser                  | Retains approved `implementer` and `reviewer` compatibility inputs.                              |
-| `examples/general.yaml`              | Explicit v1 fixture      | v1 roster parser                  | Retains unresolved `worker` without an inferred canonical role.                                  |
-| `examples/hybrid.yaml`               | Explicit v1 fixture      | v1 roster parser                  | Retains `implementer`, `reviewer`, and resolver-dependent `researcher`.                          |
-| `examples/local-canary.yaml`         | Explicit v1 fixture      | v1 roster parser                  | Retains the local-tmux canary topology.                                                          |
-| `examples/minimal.yaml`              | Explicit v1 fixture      | v1 roster parser                  | Retains `canary` without an inferred canonical role.                                             |
-| `examples/operator-interaction.yaml` | Explicit v1 fixture      | v1 roster parser                  | Keeps Tess only as an example instance name; `operator-interaction` remains compatibility input. |
-| `examples/research.yaml`             | Explicit v1 fixture      | v1 roster parser                  | Retains resolver-dependent `researcher` and `analyst`.                                           |
-| `profiles/business.yaml`             | Canonical profile        | shared profile/persona resolver   | Every referenced business class must resolve to a readable contract.                             |
-| `profiles/marketing.yaml`            | Canonical profile        | shared profile/persona resolver   | Every referenced marketing class must resolve to a readable contract.                            |
-| `profiles/personal-assistant.yaml`   | Canonical profile        | shared profile/persona resolver   | No interaction equivalence is inferred.                                                          |
-| `profiles/research.yaml`             | Canonical profile        | shared profile/persona resolver   | Every research class must resolve to a readable contract.                                        |
-| `profiles/software-delivery.yaml`    | Canonical profile        | shared profile/persona resolver   | Retains the governance profile; authority validation remains FCM-M1-002 evidence.                |
-| `services/operator-interaction.yaml` | Canonical service policy | service-policy reader/provisioner | Generic provisioning supplies the instance name; the policy itself never names Tess.             |
-
-## Running the guard
-
-```bash
-pnpm --filter @mosaicstack/mosaic test -- example-profile-dispositions.spec.ts
-```
-
-The guard is intentionally limited to shipped assets and validation. It does not generate
-environment files, mutate a roster, reconcile a fleet, migrate an installed roster, or launch an
-agent.

docs/fleet/migration/legacy-class-aliases.md

@@ -1,40 +0,0 @@
-# Legacy Fleet Class Aliases
-
-Fleet class compatibility is intentionally narrow. The shared resolver accepts exactly three legacy
-class names and converts them to canonical classes before persona lookup:
-
-| Legacy value           | Canonical value | Migration action                                                                                                       |
-| ---------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| `implementer`          | `code`          | Replace class and tool-policy references with `code`.                                                                  |
-| `reviewer`             | `review`        | Replace class and tool-policy references with `review`.                                                                |
-| `operator-interaction` | `interaction`   | Replace class and roster-v2 tool-policy references with `interaction`. The legacy service artifact remains compatible. |
-
-Alias support preserves existing inputs while provisioning and typed semantic output use canonical
-identities. Requested and canonical class values remain separately observable during semantic
-validation.
-
-## Lookup and override behavior
-
-Canonicalization precedes baseline and `roles.local` lookup. A legacy-named override such as
-`roles.local/implementer.md` is not a separate authority and is not selected for an `implementer`
-request. Customize the canonical role instead, for example `roles.local/code.md`.
-
-The compatibility file `operator-interaction.md` remains shipped, but `interaction` is the canonical
-role class. Tess is an example display name only.
-
-## Unresolved and custom classes
-
-No names are inferred from historical usage, instance names, or similar wording. `worker`, `analyst`,
-`canary`, Tess, and Ultron are not aliases. An otherwise unknown class is accepted only if the shared
-resolver can read an actual baseline or `roles.local` contract for that exact class. A `LIBRARY.md`
-row without a readable contract fails semantic validation.
-
-Custom classes receive no protected authority implicitly. Protected class/tool-policy mismatches
-fail closed.
-
-## Retirement guidance
-
-New configuration should emit canonical values. Existing inputs may use the three aliases during the
-compatibility period, but operators should migrate class and tool-policy fields together. Do not
-create new legacy-named role overrides; move their intended content to the canonical filename and
-validate the roster/profile before removing the old artifact.

docs/fleet/reference/role-classes.md

@@ -1,45 +0,0 @@
-# Fleet Role Classes and Authority
-
-A fleet role class is a machine identity resolved from the persona library. Resolution uses the
-canonical class before consulting the baseline `fleet/roles/` and operator `fleet/roles.local/`
-layers. A readable role contract is required; an index entry alone is not semantic success.
-
-## Canonicalization
-
-Only these legacy class aliases are recognized:
-
-| Requested class        | Canonical class |
-| ---------------------- | --------------- |
-| `implementer`          | `code`          |
-| `reviewer`             | `review`        |
-| `operator-interaction` | `interaction`   |
-
-No other alias is inferred. In particular, `worker`, `analyst`, and `canary` are custom classes only
-when an operator supplies a readable contract for that exact class. Tess and Ultron are instance
-names, not classes. `agents[].alias` is display-only and cannot grant authority.
-
-Canonicalization happens before role lookup. For example, requesting `implementer` resolves
-`code.md`; a separate `roles.local/implementer.md` cannot redefine the legacy alias. A canonical
-`roles.local/code.md` still overrides the baseline `roles/code.md` contract.
-
-## Protected authority
-
-Protected authority is immutable metadata derived only from canonical class. Role prose, instance
-name, display alias, tool policy, runtime, and custom role files cannot grant it.
-
-| Canonical class   | Granted authority                                  | Explicit limits                                                                   |
-| ----------------- | -------------------------------------------------- | --------------------------------------------------------------------------------- |
-| `merge-gate`      | Sole approve-to-land and merge authority           | No authority is inferred by similarly named custom roles or policies.             |
-| `validator`       | May issue a validation certificate                 | Cannot approve-to-land or merge.                                                  |
-| `orchestrator`    | May orchestrate, manage topology, and issue leases | Cannot approve-to-land or merge.                                                  |
-| `team-leader`     | May use orchestrator-leased capacity               | Cannot issue leases or mutate roster, configuration, credentials, or merge state. |
-| `interaction`     | Request and status surface                         | Cannot orchestrate, issue leases, mutate roster/configuration, or merge.          |
-| all other classes | No protected authority implicitly                  | Custom contracts do not acquire protected powers from prose.                      |
-
-Roster-v2 semantic validation requires a protected class and its canonical tool policy to match. It
-also rejects an unprotected class paired with a protected tool policy. The legacy tool-policy name
-`operator-interaction` canonicalizes to `interaction`.
-
-This mapping describes authority metadata only. Lease issuance, validation-certificate storage or
-workflow, lifecycle reconciliation, credentials, roster mutation, and merge execution are outside
-this resolver contract.

docs/fleet/reference/roster-v2-fields.md

@@ -81,35 +81,6 @@ agents:
 | `agents[].lifecycle.desired_state`                   | yes      | `running` or `stopped`                                                                               |
 | `agents[].launch.yolo`                               | yes      | boolean; structured data only, not an arbitrary command escape hatch                                 |
 
-## Semantic handoff
-
-`parseRosterV2` and `normalizeRosterV2` remain synchronous and structural. After structural success,
-call the asynchronous `validateRosterV2Semantics` handoff before using persona identity or authority.
-That validator batches the baseline `fleet/roles/` and operator `fleet/roles.local/` scans, then
-delegates every agent to the shared persona resolver.
-
-Semantic validation:
-
-- requires the winning role contract to be readable and non-empty; `LIBRARY.md` membership alone does
-  not resolve a class;
-- retains `requestedClass` separately from `canonicalClass` in typed output;
-- canonicalizes only `implementer` to `code`, `reviewer` to `review`, and
-  `operator-interaction` to `interaction`;
-- canonicalizes `tool_policy` with the same exact alias table;
-- rejects protected class/tool-policy mismatches in either direction, while accepting
-  `class: operator-interaction` with `tool_policy: operator-interaction` as canonical
-  `interaction`;
-- derives immutable protected authority only from canonical class; and
-- accepts custom baseline or `roles.local` classes without granting protected authority.
-
-`agents[].alias` remains display-only. Tess and Ultron are instance names, never semantic classes.
-Canonicalization happens before role-layer lookup, so a legacy-named override cannot redefine an
-alias as separate authority. See [Role Classes and Authority](./role-classes.md) and
-[Customize Fleet Roles](../how-to/customize-roles.md).
-
-This handoff performs no filesystem, systemd, tmux, roster, credential, lease, certificate, or
-lifecycle mutation.
-
 ## Fail-closed boundary
 
 Every object is `additionalProperties: false`. The compiler rejects unknown, missing, malformed,

docs/guides/admin-guide.md

@@ -223,10 +223,10 @@ external clients. Authentication requires a valid BetterAuth session (cookie or
 
 ### Required
 
-| Variable             | Description                                                                                                 |
+| Variable             | Description                                                                               |
-| -------------------- | ----------------------------------------------------------------------------------------------------------- |
+| -------------------- | ----------------------------------------------------------------------------------------- |
-| `BETTER_AUTH_SECRET` | Secret key for BetterAuth session signing. Must be set or gateway will not start.                           |
+| `BETTER_AUTH_SECRET` | Secret key for BetterAuth session signing. Must be set or gateway will not start.         |
-| `DATABASE_URL`       | Runtime-only PostgreSQL connection injected from the dedicated deployment secret; no default or inline DSN. |
+| `DATABASE_URL`       | PostgreSQL connection string. Default: `postgresql://mosaic:mosaic@localhost:5433/mosaic` |
 
 ### Gateway
 

docs/guides/deployment.md

@@ -61,13 +61,9 @@ pnpm install
 ### 4. Initialize the database
 
 ```bash
-mosaic-db-migrator --run
+pnpm --filter @mosaicstack/db db:migrate
-mosaic-db-migrator --verify
 ```
 
-This is the sole PostgreSQL DDL/readiness control plane. It receives migration-only credentials
-through deployment secret mounts and accepts no URL, SQL, schema, or role argv.
-
 ### 5. Build all packages
 
 ```bash
@@ -122,25 +118,34 @@ sudo apt-get install -y postgresql-17 postgresql-17-pgvector
 # Follow https://valkey.io/download/ for your distribution
 ```
 
-### Step 2 — Provision the database
+### Step 2 — Create the database
 
-Do not run ad hoc SQL, create application roles, or create extensions from this guide. The
+```sql
-external reviewed bootstrap artifact provisions roles/pgvector, then the migration Job runs
+-- Run as the postgres superuser
-`mosaic-db-migrator --run` and `mosaic-db-migrator --verify` over verified TLS. This guide does
+CREATE USER mosaic WITH PASSWORD 'change-me';
-not authorize a plaintext, owner-runtime, or manual-extension bootstrap.
+CREATE DATABASE mosaic OWNER mosaic;
+\c mosaic
+CREATE EXTENSION IF NOT EXISTS vector;
+```
 
 ### Step 3 — Clone and configure
 
 ```bash
 git clone <repo-url> /opt/mosaic
 cd /opt/mosaic
+cp .env.example .env
 ```
 
-Production deployment does **not** read a committed or local `.env` file. Use the reviewed
+Edit `/opt/mosaic/.env`. Required fields:
-secret renderer/deployment control plane: it injects runtime secrets only at process exec,
+
-migration secrets only to the one-shot runner, and non-secret endpoint configuration separately.
+```dotenv
-Validate required values at startup; never write a DSN or BetterAuth secret into this guide or a
+DATABASE_URL=postgresql://mosaic:<password>@localhost:5432/mosaic
-production filesystem `.env`.
+VALKEY_URL=redis://localhost:6379
+BETTER_AUTH_SECRET=<openssl rand -base64 32>
+BETTER_AUTH_URL=https://your-domain.example.com
+GATEWAY_CORS_ORIGIN=https://your-domain.example.com
+NEXT_PUBLIC_GATEWAY_URL=https://your-domain.example.com
+```
 
 ### Step 4 — Install dependencies and build
 
@@ -152,12 +157,9 @@ pnpm build
 ### Step 5 — Run database migrations
 
 ```bash
-mosaic-db-migrator --run
+pnpm --filter @mosaicstack/db db:migrate
-mosaic-db-migrator --verify
 ```
 
-The one-shot migrator alone receives the migration secret; Gateway/runtime never receives it.
-
 ### Step 6 — Start the gateway
 
 ```bash
@@ -338,12 +340,20 @@ MaxRetentionSec=30day
 
 `BETTER_AUTH_SECRET` is missing or empty. Set it in `.env` and restart.
 
-### Runtime database connection refused
+### `DATABASE_URL` connection refused
 
-Verify PostgreSQL service/TLS readiness and the deployment-mounted runtime secret reference. Do
+Verify PostgreSQL is running and the port matches. The Docker Compose default is `5433`; bare-metal typically uses `5432`.
-not print or test a DSN from a shell. Run the sanitized `mosaic-db-migrator --verify` readiness
+
-procedure; if pgvector or schema verification fails, stop and remediate through the reviewed
+```bash
-bootstrap/runner control plane. Manual extension SQL is unavailable.
+psql "$DATABASE_URL" -c '\conninfo'
+```
+
+### pgvector extension missing
+
+```sql
+\c mosaic
+CREATE EXTENSION IF NOT EXISTS vector;
+```
 
 ### Valkey / Redis connection refused
 

docs/guides/dev-guide.md

@@ -106,8 +106,7 @@ This starts:
 Create a `.env` file in the monorepo root:
 
 ```env
-# Runtime database connection (local-development placeholder only; never a production secret)
+# Database (matches docker-compose defaults)
-# KBN-101 production-like runtime injects DATABASE_URL from its dedicated secret mount.
 DATABASE_URL=postgresql://mosaic:mosaic@localhost:5433/mosaic
 
 # Auth (required — generate a random 32+ char string)
@@ -128,16 +127,14 @@ OLLAMA_MODELS=llama3.2
 The gateway loads `.env` from the monorepo root via `dotenv` at startup
 (`apps/gateway/src/main.ts`).
 
-### 4. Prepare the PostgreSQL Schema
+### 4. Push the Database Schema
 
 ```bash
-mosaic-db-migrator --run
+pnpm --filter @mosaicstack/db db:push
-mosaic-db-migrator --verify
 ```
 
-KBN-101 makes this the sole PostgreSQL DDL/readiness sequence. Direct schema push is not an
+This applies the Drizzle schema directly to the database (development only; use
-operator workflow; a disposable local experiment is separately guarded and cannot use a
+migrations in production).
-production-like tier or URL.
 
 ### 5. Start the Gateway
 
@@ -358,13 +355,12 @@ The schema lives in a single file:
 
 The `insights` table uses a `vector(1536)` column (pgvector) for semantic search.
 
-### Development: Prepare Schema
+### Development: Push Schema
 
-Prepare a PostgreSQL development target through the same sole runner:
+Apply schema changes directly to the dev database (no migration files created):
 
 ```bash
-mosaic-db-migrator --run
+pnpm --filter @mosaicstack/db db:push
-mosaic-db-migrator --verify
 ```
 
 ### Generating Migrations
@@ -380,8 +376,7 @@ This creates a new SQL migration file in `packages/db/drizzle/`.
 ### Running Migrations
 
 ```bash
-mosaic-db-migrator --run
+pnpm --filter @mosaicstack/db db:migrate
-mosaic-db-migrator --verify
 ```
 
 ### Drizzle Config
@@ -393,9 +388,9 @@ directory are defined there.
 
 1. Add the table definition to `packages/db/src/schema.ts`.
 2. Export it from `packages/db/src/index.ts`.
-3. Generate the offline artifact with `pnpm --filter @mosaicstack/db db:generate`, then run
+3. Run `pnpm --filter @mosaicstack/db db:push` (dev) or
-   `mosaic-db-migrator --run` and `mosaic-db-migrator --verify`. Direct schema push is not a
+   `pnpm --filter @mosaicstack/db db:generate && pnpm --filter @mosaicstack/db db:migrate`
-   production-like workflow and the migration runner accepts no URL/SQL/schema/role argv.
+   (production).
 
 ---
 

docs/guides/migrate-tier.md

@@ -1,86 +1,39 @@
 # Migrating to the Federated Tier
 
-> **KBN-101-07 ownership:** this is an **active** operator guide, exclusively owned by
+Step-by-step guide to migrate from `local` (PGlite) or `standalone` (PostgreSQL without pgvector) to `federated` (PostgreSQL 17 + pgvector + Valkey).
-> KBN-101-07. It is not a historical document. The KBN-101-06 finite operator-document
-> inventory records this route and its secure-interface fields.
 
-This guide is active documentation but a **non-operative KBN-101 contract** until
+## When to migrate
-KBN-101-02, -03, and -06 land and KBN-101-08 activates the reviewed artifacts. The command
-blocks below specify the produced interface; they are not available on the current branch and
-MUST NOT be attempted until the activation certificate names the exact release. Until then, do
-not use a direct PostgreSQL target URL, raw SQL, or any legacy storage migration command as a
-production procedure.
 
-## Non-negotiable boundary
+Migrate to federated tier when:
 
-The PostgreSQL destination schema is prepared separately before data migration:
+- Scaling from single-user to multi-user deployments
-
+- Adding vector embeddings or RAG features
-1. The dedicated DDL runner executes `mosaic-db-migrator --run` using its migration-only
+- Running Mosaic across multiple hosts
-   identity.
+- Requires distributed task queueing and caching
-2. The same runner succeeds at `mosaic-db-migrator --verify` against the exact destination and,
+- Moving to production with high availability
-   only then, emits a signed target-bound attestation.
-3. Only then may `mosaic storage migrate-tier` verify that attestation and connect as dedicated
-   non-DDL `mosaic_data_importer` to copy data.
-
-The data migration never executes DDL or changes PostgreSQL roles, memberships, schemas,
-extensions, extension members, system catalogs, or the Drizzle ledger. Its only target writes are
-an allowlisted data-copy DML registry: inserts and idempotent conflict updates on declared mutable
-application tables. It has no DML grant for immutable KBN relations, extension/catalog objects, or
-any schema authority. It is not a schema bootstrap, extension installer, or repair procedure.
-PostgreSQL is always pre-migrated and runner-verified, including when the source is PGlite.
 
 ## Prerequisites
 
-- Federated stack is running and healthy (see [Federated Tier Setup](../federation/SETUP.md)).
+- Federated stack running and healthy (see [Federated Tier Setup](../federation/SETUP.md))
-- An approved source backup exists and the target is identified in the KBN-101 change record.
+- Source database accessible and empty target database at the federated URL
-- The target passed the runner `--run` and `--verify` sequence above; `--verify` is the only
+- Backup of source database (recommended before any migration)
-  trusted attestation producer after verified TLS, identity, manifest, and schema checks.
-- The operator has an approved, dedicated high-entropy importer credential file at
-  `/run/secrets/mosaic_migrate_target_url` and its paired non-secret attestation artifact at
-  `/run/mosaic-attestations/migrate-target.v1.json`. Neither file contents are printed, copied,
-  committed, or placed on argv.
-- KBN-101-02 validates both references before any target connection: each is a regular,
-  non-symlink file with the exact required owner/mode. The importer gets only pinned public
-  verification key(s) and the attestation; the runner-only Ed25519 private key never reaches
-  importer/runtime. The URL file is opened, digested, parsed, and connected from the same
-  in-memory bytes with no reread.
-
-### Source modes
-
-- **Local PGlite:** the source is the explicit `PGLITE_DATA_DIR`; it does not read or
-  interpret a PostgreSQL URL.
-- **PostgreSQL source:** this active route does not accept `DATABASE_URL` as a source or
-  target fallback. A PostgreSQL-source procedure needs its own independently approved,
-  non-secret credential-reference contract before it is enabled.
 
 ## Dry-run first
 
-Run the migration only after the target schema is prepared and verified:
+Always run a dry-run to validate the migration:
 
 ```bash
-mosaic-db-migrator --run
-mosaic-db-migrator --verify
 mosaic storage migrate-tier --to federated \
-  --target-url-file /run/secrets/mosaic_migrate_target_url \
+  --target-url postgresql://mosaic:mosaic@localhost:5433/mosaic \
-  --target-attestation-file /run/mosaic-attestations/migrate-target.v1.json \
   --dry-run
 ```
 
-The frozen KBN-101-02 options are exactly
+Expected output (partial example):
-`--target-url-file /run/secrets/mosaic_migrate_target_url` and
-`--target-attestation-file /run/mosaic-attestations/migrate-target.v1.json`. They are
-non-secret file references, not URL options. The runner and importer use distinct connections:
-the runner has migration DDL authority; the importer has only approved data-copy DML authority.
 
-Expected dry-run output is sanitized and contains no connection string, username, host,
+```
-database name, SQL, or credential value:
+[migrate-tier] Analyzing source tier: pglite
-
+[migrate-tier] Analyzing target tier: federated
-```text
+[migrate-tier] Precondition: target is empty ✓
-[migrate-tier] Source tier: pglite
-[migrate-tier] Target tier: federated
-[migrate-tier] Target schema: verified by mosaic-db-migrator
-[migrate-tier] Target connection: dedicated importer
-[migrate-tier] Precondition: target is ready
   users: 5 rows
   teams: 2 rows
   conversations: 12 rows
@@ -90,64 +43,26 @@ database name, SQL, or credential value:
 [migrate-tier] DRY-RUN COMPLETE (no data written). 206 total rows would be migrated.
 ```
 
-Review the output. If it reports a failed runner verification, unexpected role, unsafe
+Review the output. If it shows an error (e.g., target not empty), address it before proceeding.
-secret-file owner/mode, non-empty target, or any connection/DDL precondition error, stop
-and remediate through the KBN-101 control plane.
 
-## Run the data migration
+## Run the migration
 
-After a reviewed dry-run, repeat the same verified route with `--yes`:
+When ready, run without `--dry-run`:
 
 ```bash
-mosaic-db-migrator --verify
 mosaic storage migrate-tier --to federated \
-  --target-url-file /run/secrets/mosaic_migrate_target_url \
+  --target-url postgresql://mosaic:mosaic@localhost:5433/mosaic \
-  --target-attestation-file /run/mosaic-attestations/migrate-target.v1.json \
   --yes
 ```
 
-`--yes` only confirms data copy in non-TTY automation. It does not bypass schema
+The `--yes` flag skips the confirmation prompt (required in non-TTY environments like CI).
-verification, target-file validation, role checks, redaction, or the no-DDL boundary.
 
 The command will:
 
-1. Before target connection, validate both files, JCS/Ed25519 signature and pinned key ID,
+1. Acquire an advisory lock (blocks concurrent invocations)
-   expiry, nonce replay, secret version/digest, canonical TLS host/port/database, CA/SPKI,
+2. Copy data from source to target in dependency order
-   expected importer role, and manifest/schema bindings.
+3. Report rows migrated per table
-2. Connect only from the once-opened in-memory URL bytes, then before transaction/DML compare
+4. Display any warnings (e.g., null vector embeddings)
-   PostgreSQL system identifier, database OID, `current_user`, CA/SPKI, and manifest/schema
-   fingerprints to the attestation; mismatch closes with zero DML/DDL.
-3. Copy data in dependency order without DDL.
-4. Report sanitized row counts and warnings.
-
-## Rejected interfaces and failure-before-connect rules
-
-KBN-101-02 and KBN-101-06 must prove these failures occur before a target connection or
-DDL attempt:
-
-- Raw `--target-url` or any URL/credential value on argv.
-- `DATABASE_URL` as a target or source fallback.
-- A runtime owner, migrator, schema owner, or extension owner used as the data importer.
-- Missing, non-regular, symlinked, wrong-owner, wrong-mode, substituted, or changed-after-check
-  credential file.
-- Missing, stale, replayed, tampered, wrong-key, revoked-key, expired, malformed, or wrong-binding
-  attestation file.
-- Wrong host, database, CA/SPKI, PostgreSQL system identifier, database OID, importer role,
-  manifest, schema, or credential secret-version/digest.
-- Any mode other than the runner-prepared/verified PostgreSQL destination route.
-- Any direct DDL attempt by the migration command or its target connection.
-
-The signed attestation has canonical UTF-8/JCS bytes and detached Ed25519 signature. Its
-credential-free v1 payload binds format/version/key ID; issued/expiry/nonce; exact credential
-secret version and SHA-256; canonical TLS host/port/database; CA/SPKI; PostgreSQL system
-identifier/database OID; importer role; manifest/schema; and producer invocation/build/image/
-correlation. Artifacts are atomically written/renamed `0444`; the replay cache survives until
-expiry; public-key overlap/revocation and credential rotation force a fresh runner verification.
-
-KBN-101-02 SHALL add `packages/storage/src/migrate-tier.spec.ts::secureTargetRouteAndAttestation`
-and its integration counterpart. They prove zero target connection for pre-connect failures and
-zero DML/DDL for post-connect identity mismatch. The finite operator-document scanner rejects an
-unowned route or a guide that reintroduces a credential-bearing command.
 
 ## What gets migrated
 
@@ -173,28 +88,60 @@ Three tables are intentionally not migrated:
 | **verifications** | One-time tokens (email verify, password reset) that have either expired or been consumed        |
 | **admin_tokens**  | Hashed tokens bound to the old environment's secret keys; must be re-issued                     |
 
-**Note on accounts and provider_credentials:** These durable credentials are migrated because
+**Note on accounts and provider_credentials:** These durable credentials ARE migrated because they are user-bound and required for resuming agent work on the target environment. After migration to a multi-tenant federated deployment, operators may want to audit or wipe these if users are untrusted or credentials should not be shared.
-they are user-bound and required for resuming agent work on the target. After migration to a
-multi-tenant federated deployment, operators may want to audit or wipe these if users are
-untrusted or credentials should not be shared.
 
-## Idempotency, concurrency, and verification
+## Idempotency and concurrency
 
-The data copy is idempotent and uses an importer-scoped advisory lock. It may be retried only
+The migration is **idempotent**:
-through the same runner-verified, file-reference route. Do not inspect, unlock, or repair the
-target with ad hoc SQL; a failed or ambiguous run is a control-plane incident with backup and
-rollback evidence.
 
-After a successful migration, use the KBN-101-approved sanitized verification command or
+- Re-running is safe (uses `ON CONFLICT DO UPDATE` internally)
-read-only operator report. Do not paste a target connection string into a shell command,
+- Ideal for retries on transient failures
-terminal history, ticket, or documentation.
+- Concurrent invocations are blocked by a Postgres advisory lock; the second caller will wait
+
+If a previous run is stuck, check for advisory locks:
+
+```sql
+SELECT * FROM pg_locks WHERE locktype='advisory';
+```
+
+If you need to force-unlock (dangerous):
+
+```sql
+SELECT pg_advisory_unlock(<lock_id>);
+```
+
+## Verify the migration
+
+After migration completes, spot-check the target:
+
+```bash
+# Count rows on a few critical tables
+psql postgresql://mosaic:mosaic@localhost:5433/mosaic -c \
+  "SELECT 'users' as table, COUNT(*) FROM users UNION ALL
+   SELECT 'conversations' as table, COUNT(*) FROM conversations UNION ALL
+   SELECT 'messages' as table, COUNT(*) FROM messages;"
+```
+
+Verify a known user or project exists by ID:
+
+```bash
+psql postgresql://mosaic:mosaic@localhost:5433/mosaic -c \
+  "SELECT id, email FROM users WHERE email='<your-email>';"
+```
+
+Ensure vector embeddings are NULL (if source was PGlite) or populated (if source was postgres + pgvector):
+
+```bash
+psql postgresql://mosaic:mosaic@localhost:5433/mosaic -c \
+  "SELECT embedding IS NOT NULL as has_vector FROM insights LIMIT 5;"
+```
 
 ## Rollback
 
-There is no in-place rollback. If data migration fails:
+There is no in-place rollback. If the migration fails:
 
-1. Keep the previous target state and restore the approved pre-migration backup where required.
+1. Restore the target database from a pre-migration backup
-2. Preserve sanitized failure and audit evidence; do not expose the credential file or contents.
+2. Investigate the failure logs
-3. Investigate through the KBN-101 control plane and rerun only after independent review.
+3. Rerun the migration
 
-Always rehearse this route in a staging environment first.
+Always test migrations in a staging environment first.

docs/guides/mos-connector-lease-operations.md

@@ -1,43 +0,0 @@
-# Mos Connector Lease Operations — M1
-
-## Operational status
-
-M1 installs the durable schema and gateway policy/adapter boundary. It does **not** activate a connector, expose a lease administration endpoint, or cut over a channel. The default gateway connector-lease policy is deny-all until a later work package supplies an authorized server-side policy and concrete adapter.
-
-## Events to monitor
-
-Use correlation IDs to follow `connector_lease_audit_log` events:
-
-| Event      | Meaning                                                               |
-| ---------- | --------------------------------------------------------------------- |
-| `acquire`  | First holder inserted for an unused binding                           |
-| `renew`    | Current holder heartbeat extended the TTL                             |
-| `takeover` | Authorized CAS replaced the holder and incremented epoch              |
-| `release`  | Current holder explicitly relinquished authority                      |
-| `expiry`   | An expired current lease was observed                                 |
-| `reject`   | Policy, CAS, expiry, scope, or fencing validation denied an operation |
-
-Audit data is metadata-only. Raw grant objects, connector payloads, scopes, tokens, approval references, and credentials must never be added to audit output.
-
-## Incident checks
-
-For suspected duplicate/stale connector effects:
-
-1. Correlate the attempted operation with its `reject`, `takeover`, or `expiry` event.
-2. Compare the current row's connector ID, lease UUID, epoch, expiry, and release time with the adapter's normalized execution context.
-3. Treat an old epoch, old lease UUID, expired lease, or released lease as non-authoritative. Do not retry it as the old holder.
-4. Recovery uses the authorized takeover path with the observed expected epoch. Ordinary acquire is intentionally rejected for expired/released rows.
-5. If an external effect may already have happened, preserve evidence and do not assume lease fencing provides exactly-once replay safety.
-
-## Migration and rollback safety
-
-Migration `0016_salty_morlocks.sql` is additive: it creates two new tables and indexes without modifying existing authorization/session tables. Before rollout, normal database backup and migration verification still apply. Rolling application code back leaves unused additive tables in place; dropping tables is not part of automated rollback because it would destroy lease/audit evidence.
-
-## Security constraints
-
-- Tenant comes from authenticated gateway context, never a connector request field.
-- Logical agent, binding, connector, and scope identifiers use normalized constrained forms.
-- Takeover requires explicit gateway policy authorization and an expected epoch.
-- Default defense-in-depth TTL caps are 5 minutes for leases and 30 seconds for grants; policy may enforce stricter limits.
-- Validation and rejection audit complete before adapter side effects.
-- Existing authz and exact-action approval controls remain additional required gates; a valid connector lease does not bypass them.

docs/guides/user-guide.md

@@ -522,13 +522,8 @@ mosaic storage export --bucket agent-artifacts --output ./artifacts.tar.gz
 # Import data into storage
 mosaic storage import --bucket agent-artifacts --input ./artifacts.tar.gz
 
-# Schema migration (compatibility wrapper only; not a tier data copy)
+# Migrate data between tiers
-mosaic storage migrate --run  # delegates only to mosaic-db-migrator
+mosaic storage migrate --from hot --to cold --older-than 30d
-
-# Tier data copy is unavailable until KBN-101 activation. Its only produced interface is:
-# mosaic storage migrate-tier --target-url-file /run/secrets/mosaic_migrate_target_url \
-#   --target-attestation-file /run/mosaic-attestations/migrate-target.v1.json
-# Never use a legacy --from/--to storage-migrate command or pass a credential on argv.
 ```
 
 ---

docs/native-kanban-sot/INDEX.md

@@ -1,28 +1,26 @@
 # Native Kanban/SOT Canon
 
-**Status:** KCR-001–016 independently cleared; KBN-101 rc.11 target-attestation/operator-inventory remediation awaits independent exact-head re-review under issue [#771](https://git.mosaicstack.dev/mosaicstack/stack/issues/771)
+**Status:** KCR-001–016 independently cleared; canonical publication is in progress under issue [#751](https://git.mosaicstack.dev/mosaicstack/stack/issues/751)
 **Date:** 2026-07-14
 **Implementation hold:** no feature implementation starts until this canon is squash-merged to `main` with terminal-green CI; after merge, every slice remains held until its KBN prerequisite graph is satisfied.
 
 ## Artifacts
 
-| Artifact                                                                                                       | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| Artifact                                                                                 | Purpose                                                                                                                                                                                               |
-| -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [Canonical requirements](../requirements/native-kanban-sot.md)                                                 | Canonical P0–P3 requirements, all seven ratified decisions, fixed invariants, thin MVP, recovery tiers, non-goals, and per-requirement acceptance criteria                                                                                                                                                                                                                                                                                           |
+| [Canonical requirements](../requirements/native-kanban-sot.md)                           | Canonical P0–P3 requirements, all seven ratified decisions, fixed invariants, thin MVP, recovery tiers, non-goals, and per-requirement acceptance criteria                                            |
-| [`MISSION-MANIFEST.md`](./MISSION-MANIFEST.md)                                                                 | Mission/authority boundaries, exact role chain, gate model, mandatory SecReview triggers, Certifier final/no-merge rule, and collision-free slice ownership                                                                                                                                                                                                                                                                                          |
+| [`MISSION-MANIFEST.md`](./MISSION-MANIFEST.md)                                           | Mission/authority boundaries, exact role chain, gate model, mandatory SecReview triggers, Certifier final/no-merge rule, and collision-free slice ownership                                           |
-| [`TASKS.md`](./TASKS.md)                                                                                       | Dependency-ordered, bounded P0–P3 slices with IN/OUT scope, dependencies, shared contracts, file ownership, evidence, and USC coder2/3/4/5 parallelization                                                                                                                                                                                                                                                                                           |
+| [`TASKS.md`](./TASKS.md)                                                                 | Dependency-ordered, bounded P0–P3 slices with IN/OUT scope, dependencies, shared contracts, file ownership, evidence, and USC coder2/3/4/5 parallelization                                            |
-| [`KBN-101-DB-ROLE-SPLIT.md`](./KBN-101-DB-ROLE-SPLIT.md)                                                       | rc.11 PostgreSQL-valid pgvector owner exception; runner-signed target-bound importer attestation with file/digest/TLS/server/role/manifest binding; exhaustive operator-route inventory; exact disjoint card manifests, mechanical DDL classifier, executable `mosaic-db-migrator`, two-gateway TLS/bootstrap, role/search-path, atomic activation, and certification contract; foundation prerequisite of KBN-100 and real-role gate before KBN-105 |
+| [`SHARED-CONTRACT.md`](./SHARED-CONTRACT.md)                                             | Remediated v1 integration contract: proof authority, exact failures/routes/DTOs/MCP ownership, concrete current-main field migration map, relational invariants, Coordinator split, recovery delivery |
-| [`SHARED-CONTRACT.md`](./SHARED-CONTRACT.md)                                                                   | Remediated v1 integration contract: proof authority, exact failures/routes/DTOs/MCP ownership, concrete current-main field migration map, relational invariants, Coordinator split, recovery delivery                                                                                                                                                                                                                                                |
+| [`contracts/kanban-schema.v1.ts`](./contracts/kanban-schema.v1.ts)                       | Drizzle target declarations including exact owner/principal membership, project congruence, tags/archive, proposals, persisted assignments, monotonic fences, durable retry, immutable evidence/audit |
-| [`contracts/kanban-schema.v1.ts`](./contracts/kanban-schema.v1.ts)                                             | Drizzle target declarations including exact owner/principal membership, project congruence, tags/archive, proposals, persisted assignments, monotonic fences, durable retry, immutable evidence/audit                                                                                                                                                                                                                                                |
+| [`contracts/mechanical-coordinator.v1.ts`](./contracts/mechanical-coordinator.v1.ts)     | Pure snapshot decision engine separated from persistence/service adapter; ID-bound approvals, bigint-safe fences, durable retry/quarantine, artifact-backed checkpoints, exact failures               |
-| [`contracts/mechanical-coordinator.v1.ts`](./contracts/mechanical-coordinator.v1.ts)                           | Pure snapshot decision engine separated from persistence/service adapter; ID-bound approvals, bigint-safe fences, durable retry/quarantine, artifact-backed checkpoints, exact failures                                                                                                                                                                                                                                                              |
+| [`contracts/health-state.v1.ts`](./contracts/health-state.v1.ts)                         | Discriminated public health, separate branded transaction-local write proof, and non-overlapping denial/transport/version-conflict mappings                                                           |
-| [`contracts/health-state.v1.ts`](./contracts/health-state.v1.ts)                                               | Discriminated public health, separate branded transaction-local write proof, and non-overlapping denial/transport/version-conflict mappings                                                                                                                                                                                                                                                                                                          |
+| [`contracts/recovery-posture.v1.ts`](./contracts/recovery-posture.v1.ts)                 | Provider-neutral shape schema plus normative runtime refinement, cross-field constraints, and Lite/Standard/High-assurance defaults                                                                   |
-| [`contracts/recovery-posture.v1.ts`](./contracts/recovery-posture.v1.ts)                                       | Provider-neutral shape schema plus normative runtime refinement, cross-field constraints, and Lite/Standard/High-assurance defaults                                                                                                                                                                                                                                                                                                                  |
+| [`tsconfig.json`](./tsconfig.json)                                                       | Strict no-emit project scope for linting and compiling the four frozen TypeScript contracts against the current Stack Drizzle declarations                                                            |
-| [`tsconfig.json`](./tsconfig.json)                                                                             | Strict no-emit project scope for linting and compiling the four frozen TypeScript contracts against the current Stack Drizzle declarations                                                                                                                                                                                                                                                                                                           |
+| [`DOCUMENTATION-CHECKLIST.md`](./DOCUMENTATION-CHECKLIST.md)                             | Publication documentation gate and implementation-slice deferrals                                                                                                                                     |
-| [`DOCUMENTATION-CHECKLIST.md`](./DOCUMENTATION-CHECKLIST.md)                                                   | Publication documentation gate and implementation-slice deferrals                                                                                                                                                                                                                                                                                                                                                                                    |
+| [Initial independent review](../reports/native-kanban-sot/canon-initial-review-no-go.md) | KCR-001–016 findings that blocked the first draft                                                                                                                                                     |
-| [KBN-101 exact-head security review](../reports/native-kanban-sot/kbn-101-contract-security-review-82ce325.md) | Historical `da742ca` REQUEST CHANGES report retained as prior closure evidence; rc.11 awaits independent exact-head re-review after closing the target-attestation and operator-inventory HIGH findings                                                                                                                                                                                                                                              |
+| [Final independent re-review](../reports/native-kanban-sot/canon-final-rereview-go.md)   | Closure matrix, reproducible validation evidence, and GO verdict                                                                                                                                      |
-| [Initial independent review](../reports/native-kanban-sot/canon-initial-review-no-go.md)                       | KCR-001–016 findings that blocked the first draft                                                                                                                                                                                                                                                                                                                                                                                                    |
+| [Ultron final gate](../reports/native-kanban-sot/ultron-final-go.md)                     | Final requirements, authority, schema, migration, recovery, decomposition, and evidence review GO                                                                                                     |
-| [Final independent re-review](../reports/native-kanban-sot/canon-final-rereview-go.md)                         | Closure matrix, reproducible validation evidence, and GO verdict                                                                                                                                                                                                                                                                                                                                                                                     |
-| [Ultron final gate](../reports/native-kanban-sot/ultron-final-go.md)                                           | Final requirements, authority, schema, migration, recovery, decomposition, and evidence review GO                                                                                                                                                                                                                                                                                                                                                    |
 
 ## Recommended USC lane partition
 
@@ -34,7 +32,7 @@
 | **coder5** | Web                                  | Tasks/Projects Kanban/List/detail and later Coordinator/migration-review UI                                                                             |
 | **Mos**    | Serialized integration               | Canon publication, frozen-contract changes, shared-root/exports, integration gates, merge authority                                                     |
 
-The safe order is KBN-010 → KBN-101 foundation → KBN-100 → KBN-101 deployed-role immutable-operation certificate → KBN-105, then coder3 Gateway/MCP server, coder4 CLI/projection, coder5 web, and coder2 recovery can proceed on disjoint files. KBN-100 is blocked on the KBN-101 foundation; real deployed-role certification—not synthetic test roles—is required before KBN-105. coder4 then runs pure Coordinator → importer → cutover tooling serially. No two active slices edit the same files.
+The safe order is KBN-010 → KBN-100 → KBN-105, then coder3 Gateway/MCP server, coder4 CLI/projection, coder5 web, and coder2 recovery can proceed on disjoint files. coder4 then runs pure Coordinator → importer → cutover tooling serially. No two active slices edit the same files.
 
 ## Recovery defaults
 

docs/native-kanban-sot/KBN-101-DB-ROLE-SPLIT.md

@@ -1,252 +0,0 @@
-# KBN-101 — Database Runtime/Migration Role Split
-
-**Status:** frozen implementation contract; rc.11 closes the target-bound importer-attestation and complete operator-document-inventory HIGH findings, awaiting independent exact-head re-review for [#771](https://git.mosaicstack.dev/mosaicstack/stack/issues/771)
-
-**Version:** 1.0.0-rc.11
-
-**Dependency:** KBN-010 → **KBN-101 foundation** → KBN-100 → **KBN-101 deployed-role certification** → KBN-105
-**Scope:** PostgreSQL standalone/federated runtime identity, the sole application DDL runner, TLS bootstrap, readiness, deployment handoff, and evidence. This documentation card changes no database, secret, deployment, CI, runtime, migration, or compose artifact.
-
-## 1. Decision, modes, and non-negotiable boundaries
-
-Current `main` has one `DATABASE_URL` path in `packages/db/src/client.ts`, `migrate.ts`, `drizzle.config.ts`, storage adapters/CLI, Gateway startup, fleet-backlog, CI, installer output, compose, and Portainer. It also has PostgreSQL DDL outside a controlled migration phase: direct Drizzle scripts, `CREATE EXTENSION` probes, a direct-DDL federated integration test, and platform init SQL. None of those current paths is certified by this contract; every implementation card below must close its listed path.
-
-| Item          | Exact name / shape                     | Rule                                                                                                                                                                                    |
-| ------------- | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Runtime URL   | `DATABASE_URL`                         | PostgreSQL **non-owner runtime** connection. Required only by runtime services in `standalone`/`federated`; those services never receive `DATABASE_MIGRATION_URL`.                      |
-| Migration URL | `DATABASE_MIGRATION_URL`               | Required only by `mosaic-db-migrator`, the dedicated one-shot runner/Job. It is forbidden in Gateway, storage runtime, fleet, and ordinary CLI environments.                            |
-| Runtime DTO   | `DatabaseRuntimeConnectionConfigDto`   | `tier`, `databaseUrl`, `runtimeMode`; maps only `DATABASE_URL`. It is not constructible from migration configuration.                                                                   |
-| Migration DTO | `DatabaseMigrationConnectionConfigDto` | `tier`, `migrationDatabaseUrl`, `migrationMode`; maps only `DATABASE_MIGRATION_URL`, is accepted only by `mosaic-db-migrator`, and has no runtime-bootstrap import path.                |
-| TLS DTO       | `DatabaseTlsConfigDto`                 | `caCertificatePath`, `rejectUnauthorized: true`, `serverName`; validates the mounted CA without serializing its bytes. `serverName` is derived only from the validated connection host. |
-| Readiness DTO | `DatabaseSchemaReadinessDto`           | `state`, `expectedSchemaVersion`, `observedSchemaVersion`, `migrationRequired`, `roleCheck`, `checkedAt`; no URL, user, host, database name, or secret.                                 |
-| Modes         | `local`, `standalone`, `federated`     | `local` is the explicit PGlite-only exception. `standalone` and `federated` are production-like PostgreSQL modes.                                                                       |
-
-**No fallback or plaintext:** in production-like modes, missing `DATABASE_URL`, `DATABASE_MIGRATION_URL`, or `DATABASE_TLS_CA_CERT_PATH` is a phase-specific error. No command may substitute a runtime URL, config-file URL, default URL, inferred URL, or hard-coded URL. PostgreSQL URLs must use `sslmode=verify-full` with `rejectUnauthorized: true`; `disable`, `allow`, `prefer`, `require`, `no-verify`, an absent CA, a wrong CA, an unverified certificate, or host/SAN mismatch fails before readiness. PGlite uses only its configured local data directory and explicit PGlite routine; it neither reads nor interprets PostgreSQL URL/TLS variables.
-
-**ASSUMPTION K101-A1:** `standalone` and `federated` are the complete current PostgreSQL production-like modes. A future PostgreSQL tier inherits this contract until a versioned amendment names its DNS, secrets, bootstrap, and evidence.
-
-## 2. The sole PostgreSQL DDL control plane
-
-`mosaic-db-migrator` is the **only application/CI/test command that may connect with DDL authority to PostgreSQL**. It owns, in one `max: 1` PostgreSQL session: migration-DTO parse, TLS/identity/search-path preflight, advisory-lock acquisition, manifest/ledger reconciliation, migration execution, postflight/readiness verification, lock release, and session close. It rejects `DATABASE_URL`-only invocation **before opening a connection or emitting DDL**. The only exception is the external privileged platform/IaC bootstrap actor (§4/§7), which is not an application command, never receives either application URL, and executes only the fixed bootstrap artifact.
-
-**Executable contract (KBN-101-03 exclusive):** `packages/db/package.json` publishes the exact mapping `"mosaic-db-migrator": "./dist/cli.js"`; `packages/db/src/cli.ts` compiles to that target. `docker/db-migrator.Dockerfile` builds that package and has the exact image entrypoint `ENTRYPOINT ["mosaic-db-migrator"]`. KBN-101-03 alone owns package/bin/build/pack/discovery tests that execute this compiled bin and image as `mosaic-db-migrator --help|--run|--verify`. The CLI imports only private implementation modules in `packages/db/src/migrator/`; package root exports do **not** expose `runMigrations`, and no other programmatic migration API is public. The sole typed programmatic runner is private to the package/CLI boundary and accepts the typed migration DTO, never a URL/string/SQL/schema/role argument.
-
-The exact user-facing interface is `mosaic-db-migrator --run` and `mosaic-db-migrator --verify`. `--help` is required and is the only discovery mode. Both commands use the fixed packaged migration folder and accept only `DATABASE_MIGRATION_URL`, `DATABASE_TLS_CA_CERT_PATH`, and non-secret `MOSAIC_DATABASE_TIER`/correlation input from the environment. They reject `DATABASE_URL` as fallback and reject URL, SQL, schema, role, database, migration-folder, and identifier arguments in argv. Stable sanitized process exits are: `0` success; `64` configuration; `65` TLS; `66` unsafe identity; `67` ledger/schema; `68` lock contention; `69` migration failure. CI, Compose, Swarm, and each two-gateway migration Job invoke the immutable db-migrator image with exactly `mosaic-db-migrator --run`; their readiness verification invokes exactly `mosaic-db-migrator --verify`. Required tests cover `--help`, argv rejection, runtime-only refusal before connect, migration-only success, each sanitized error/lock exit, and ordered `postgres-a → mosaic-db-migrator-a → gateway-a` plus `postgres-b → mosaic-db-migrator-b → gateway-b` execution.
-
-The implementation must inventory and close every present and future entrypoint as follows:
-
-| Current entrypoint                                                                                                                                                                                                                                                                                                                    | Required rc.11 disposition                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `packages/db/src/migrate.ts:runMigrations()`                                                                                                                                                                                                                                                                                          | Remove its optional URL, `DATABASE_URL`, and default fallback API from public/runtime exports. Its PostgreSQL behavior moves behind `mosaic-db-migrator`; callers cannot invoke it with an arbitrary URL.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `packages/db/src/index.ts`                                                                                                                                                                                                                                                                                                            | `KBN-101-03` removes the public `runMigrations` re-export; only the explicit PGlite-local API remains as separately typed local behavior. A compile/import-negative proves `@mosaicstack/db` cannot directly import `runMigrations`; a `DATABASE_URL`-only direct-library attempt fails before connect.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `packages/db/drizzle.config.ts` and direct `drizzle-kit migrate`                                                                                                                                                                                                                                                                      | A database-connecting Drizzle configuration reads only `DATABASE_MIGRATION_URL` through the migration DTO and rejects its absence before connection. Replace direct `drizzle-kit migrate` exposure with `mosaic-db-migrator`. `db:generate` is an offline schema artifact command and must neither resolve nor connect to a URL.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `pnpm --filter @mosaicstack/db db:migrate` and CI invocation                                                                                                                                                                                                                                                                          | Make it a thin `mosaic-db-migrator` wrapper; no direct Drizzle migrator invocation remains. CI supplies an isolated disposable migration URL only to that job.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `db:push` / direct `drizzle-kit push`                                                                                                                                                                                                                                                                                                 | Forbidden for standalone, federated, CI production-like, Portainer, and any URL outside a disposable developer database. If retained for local experimentation, a wrapper requires `MOSAIC_DISPOSABLE_DEVELOPER_DB=1`, a locally allowlisted disposable target, `DATABASE_MIGRATION_URL`, verified TLS when PostgreSQL is used, and rejects `DATABASE_URL`, any production-like tier, and every non-allowlisted host/database before connection. It is never a release, repair, or migration procedure.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `mosaic storage migrate --run`                                                                                                                                                                                                                                                                                                        | Delegates only to `mosaic-db-migrator`; it rejects `DATABASE_URL`-only execution before spawning or connecting. Its PGlite form remains explicitly local-only.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `PostgresAdapter.migrate()`, Gateway `DatabaseModule`/startup, and PostgreSQL adapter factories                                                                                                                                                                                                                                       | Runtime PostgreSQL migration is removed: no `runMigrations`, DDL, `CREATE EXTENSION`, or migration-compatible handle is reachable from startup. Gateway performs read-only identity, TLS, `search_path`, and manifest-ledger readiness checks only.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `packages/mosaic/src/commands/fleet-backlog.ts`                                                                                                                                                                                                                                                                                       | PostgreSQL fleet backlog never migrates or creates tables. It consumes a ready runtime connection; PGlite may use only its explicit local migration routine.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `packages/storage/src/{adapters/postgres,tier-detection}.ts` extension work and `infra/pg-init/01-extensions.sql`                                                                                                                                                                                                                     | Runtime probes become read-only catalog/extension-presence checks. Extension provisioning is a fixed external bootstrap prerequisite or a reviewed runner migration where the migrator has the required scoped authority; it is never a probe side effect or a reason to grant runtime database CREATE.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `packages/db/src/federation.integration.test.ts` direct type/table/index DDL                                                                                                                                                                                                                                                          | `KBN-101-02` replaces it with a pre-migrated disposable database created by `mosaic-db-migrator`, or makes the test invoke that runner. The test itself has runtime credentials and no direct DDL.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `apps/gateway/src/__tests__/integration/federated-pgvector.integration.test.ts` `CREATE TEMP TABLE`                                                                                                                                                                                                                                   | `KBN-101-02` replaces the temporary runtime DDL with a runner-prepared disposable **persistent** `mosaic.federated_pgvector_fixture` database/table. The test receives only its runtime URL/CA and performs read/query-only qualified-vector assertions (including the selected vector operator); it has no setup hook, temporary privilege, or DDL. Runtime `TEMPORARY` remains denied.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `docker/init-db.sql` and `infra/pg-init/01-extensions.sql`                                                                                                                                                                                                                                                                            | `KBN-101-02` retires these duplicate tracked init artifacts; neither may remain as a hidden extension authority. The sole extension action is the fixed external bootstrap artifact described in §4/§5, or the runner only when its reviewed implementation card explicitly grants that authority.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `packages/storage/src/{cli,migrate-tier}.ts` operator/runtime command closure                                                                                                                                                                                                                                                         | `KBN-101-02` alone replaces raw SQL/DDL behavior with delegation to `mosaic-db-migrator --run` (or the explicit PGlite-local path). Data copy requires the exact paired non-secret argv references `--target-url-file /run/secrets/mosaic_migrate_target_url` and `--target-attestation-file /run/mosaic-attestations/migrate-target.v1.json`. The trusted `mosaic-db-migrator --verify` producer reads the exact importer target-secret file only to bind and attest it; it never uses importer credentials for DDL/DML. Before target connection the importer verifies strict files, signed target attestation, credential-file digest/version, canonical TLS/database binding, role, manifest, expiry, and replay; after verified TLS but before transaction/DML it verifies server/database identity and schema. It opens only a dedicated non-DDL `mosaic_data_importer` target connection. Its DML registry is limited to declared mutable application tables and excludes schemas, roles, memberships, extensions, extension/catalog objects, Drizzle ledger, and immutable KBN relations. Raw `--target-url`, `DATABASE_URL` fallback, runtime-owner/importer role confusion, missing/unsafe/substituted files, stale/replayed/tampered/wrong-key attestation, wrong binding, and any DDL attempt fail before target connection/DDL or copy. KBN-101-07 documents that produced interface but owns neither source file. |
-| `tools/federation-harness/docker-compose.two-gateways.yml`                                                                                                                                                                                                                                                                            | Active topology; `KBN-101-05` migrates it rather than retires it. It must contain `postgres-a`, `postgres-b`, `mosaic-db-migrator-a`, `mosaic-db-migrator-b`, `gateway-a`, and `gateway-b`; each database has separate runtime/migrator URL and CA consumers, TLS server material, verified-TLS readiness, and runner-before-Gateway ordering. Its existing plaintext URLs/init mount are forbidden.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `docs/fleet/backlog-conventions.md`                                                                                                                                                                                                                                                                                                   | `KBN-101-07` removes the current automatic first-use PostgreSQL `runMigrations()` claim. It points PostgreSQL operators to the sole runner/readiness sequence and labels only the PGlite routine as local-only. A documentation-route `DATABASE_URL`-only test asserts no first-use/migration instruction is executable before connect.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `docs/PERFORMANCE.md`                                                                                                                                                                                                                                                                                                                 | `KBN-101-07` removes direct `drizzle-kit migrate` and Gateway-startup `runMigrations()` instructions. It points to the sole runner/readiness sequence. A documentation-route `DATABASE_URL`-only test asserts neither direct command nor Gateway fallback remains.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `README.md`, `CLAUDE.md`, `docs/guides/{admin-guide,dev-guide,deployment,migrate-tier,user-guide}.md`, `docs/federation/{SETUP,TASKS}.md`, `docs/fleet/backlog-conventions.md`, `docs/PERFORMANCE.md`, `docs/design/storage-abstraction-middleware.md`, and `docs/plans/2026-03-15-agent-platform-architecture.md` documentation hits | `KBN-101-07` owns the non-normative disposition inventory in §2.2. It replaces, retires, or labels status-only every direct `db:migrate`, `db:push`, `CREATE EXTENSION`, first-use migration, Gateway-startup migration, and generic `mosaic storage migrate` instruction with the runner/bootstrap or secure `migrate-tier` route. The architecture plan explicitly marks direct `db:migrate` superseded. Historical shipped-status language is adjacent to an exact non-authorizing KBN-101 note. Documentation is a DDL entrypoint and cannot advertise a bypass.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| New package scripts, test helpers, setup hooks, CLI commands, installers, CI steps, adapters, or operator docs                                                                                                                                                                                                                        | A repository check rejects any new PostgreSQL DDL-capable entrypoint or instruction unless it is the dedicated runner or the named external bootstrap artifact. No future script may accept a URL parameter or `DATABASE_URL` as a DDL escape hatch.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-
-The runner must run the original migration bytes, including shipped `0009`; no migration command may repair a ledger by manual insertion, adoption, `db:push`, or schema diff. Tests requiring PostgreSQL schema consume a pre-migrated disposable database or invoke this exact runner.
-
-`KBN-101-06` alone owns `.woodpecker/ci.yml`, `tools/ci/kbn101-ddl-inventory.ts`, `tools/ci/kbn101-ddl-inventory.spec.ts`, `tools/ci/fixtures/kbn101-ddl-inventory.json`, `tools/ci/kbn101-entrypoint-matrix.ts`, and `tools/ci/kbn101-entrypoint-matrix.spec.ts`. The scanner inventory is canonical JSON whose every record has exactly `path`, `class`, `ownerCard`, `disposition`, `allowedTokens`, `rationale`, `expiry`, and `reviewRevision`. `class` is one of `executable-source`, `script-or-package-bin`, `operator-document`, `deploy-manifest`, or `normative-contract`; `ownerCard` is one KBN-101 card; `disposition` is one of `runner`, `delegate`, `deny`, `retire`, `superseded-document`, `active-secure-data-migration`, `status-only`, or `allowlisted`; and `allowedTokens` is a nonempty subset of the fixed rules below only for `allowlisted` or `superseded-document`. `normative-contract` is excluded from **operator execution**, never from scanning: it is valid only for the exact KBN PRD/contract/shared/task canonical paths, must carry declarative requirements rather than an executable shell instruction, and a fenced executable instruction or an imperative bypass in that class fails rather than being masked. An `active-secure-data-migration` record has empty `allowedTokens` and additionally pins `route`, `targetCredentialOption`, `targetCredentialFile`, `targetAttestationOption`, `targetAttestationFile`, `attestationProducer`, `attestationKeyIds`, `attestationBindings`, `targetSchemaPrerequisite`, `targetConnectionRole`, `forbiddenInputs`, and `routeTest`; its parser rejects a missing field, a route that accepts a credential value on argv, an attestation missing any canonical binding, or a target that is not runner-prepared/verified. The latter `superseded-document` disposition is allowed only for the exact architecture-plan path when adjacent text says the direct command is superseded/MUST NOT run and names `mosaic-db-migrator --run`. The scanner rejects duplicate path owners, ownerless non-allowlisted rows, missing paths, malformed fields, an inventory path outside its declared class, and every unrecognized active command. The classifier's exact case-insensitive token/rule set is: `runMigrations\\s*\\(`; `drizzle-kit\\s+(?:migrate|push)`; `\\bdb:(?:migrate|push)\\b`; `mosaic\\s+storage\\s+migrate`; `CREATE\\s+(?:TEMP(?:ORARY)?\\s+)?(?:EXTENSION|TABLE|TYPE|INDEX|SCHEMA)`; `ALTER\\s+(?:EXTENSION|TABLE|TYPE|SCHEMA)`; `DROP\\s+(?:EXTENSION|TABLE|TYPE|INDEX|SCHEMA)`; and `DATABASE_URL` when it occurs in the same file as any preceding rule. It scans exact-path current executable source/scripts/package bins, operator documents, deploy manifests, and named normative contracts; any hit not represented by a permitted inventory record fails. The matrix harness invokes the compiled runner/package/image and produced deployment artifacts; it edits no producer file.
-
-The canonical inventory includes this active—not historical—operator route record: `path=docs/guides/migrate-tier.md`, `class=operator-document`, `ownerCard=KBN-101-07`, `disposition=active-secure-data-migration`, `allowedTokens=[]`, `route=mosaic storage migrate-tier`, `targetCredentialOption=--target-url-file`, `targetCredentialFile=/run/secrets/mosaic_migrate_target_url`, `targetAttestationOption=--target-attestation-file`, `targetAttestationFile=/run/mosaic-attestations/migrate-target.v1.json`, `attestationProducer=mosaic-db-migrator --verify`, `attestationKeyIds=[migrate-target-v1-active,migrate-target-v1-overlap]`, `attestationBindings=[credentialSecretVersion,credentialFileSha256,tlsHostPortDatabase,caSpkiFingerprint,postgresSystemIdentifier,databaseOid,expectedImporterRole,manifestFingerprint,schemaFingerprint]`, `targetSchemaPrerequisite=mosaic-db-migrator --verify`, `targetConnectionRole=mosaic_data_importer`, `forbiddenInputs=[--target-url,DATABASE_URL,runtime-owner,signing-key]`, and `routeTest=packages/storage/src/migrate-tier.spec.ts::secureTargetRouteAndAttestation`. The -06 scanner/matrix must reject a changed/missing field, any `--target-url` or credential-bearing argv, a `DATABASE_URL` target fallback, a missing/unsafe/substituted credential file, missing/stale/replayed/tampered/wrong-key attestation, wrong binding, wrong mode, runtime-owner/importer confusion, target connection before attestation verification, or any DDL attempt before target connection/DDL.
-
-### 2.1 Target-bound importer attestation v1
-
-`mosaic-db-migrator --verify` is the trusted producer only after its verified-TLS identity, manifest/ledger, and schema checks pass. Its root-owned launch wrapper is the sole reader of the fixed `MOSAIC_DB_ATTESTATION_SIGNING_KEY_FILE=/run/secrets/mosaic-db-migrate-target-ed25519` reference: that regular, non-symlink `root:root` `0400` Ed25519 private-key file is mounted only to the one-shot runner. It opens the key once, passes signing capability only in memory to `mosaic-db-migrator`, and never mounts, forwards, logs, prints, or otherwise exposes the private key to the importer, runtime, or an application container. KBN-101-05 renders both that runner-only secret and the importer-only pinned public-key/key-ring mount; an alternative env path, unsafe key file, or key material in importer/runtime is a hard failure.
-
-After verification the runner atomically emits the credential-free, non-secret `0444` controlled artifact `/run/mosaic-attestations/migrate-target.v1.json`: write a same-directory `0600` temporary file, write canonical bytes, `fsync` file and directory, set final owner/mode, and rename atomically. The single JSON envelope carries an RFC 8785 JCS canonical UTF-8 `attestation` payload plus a detached Ed25519 `signature` envelope (`algorithm`, `keyId`, base64 signature); the signature covers only the canonical payload bytes, never a reformatted document. The v1 payload fields are exactly `format`, `version`, `keyId`, `issuedAt`, `expiresAt`, `nonce`, `targetCredentialSecretVersion`, `targetCredentialFileSha256`, `tlsHost`, `tlsPort`, `database`, `caSpkiFingerprint`, `postgresSystemIdentifier`, `databaseOid`, `expectedImporterRole`, `manifestFingerprint`, `schemaFingerprint`, `producerInvocation`, `producerBuildDigest`, `producerImageDigest`, and `correlationId`. It contains no URL/DSN, username, password, private key, or credential bytes. The target credential must be a high-entropy DSN secret because its SHA-256 is non-secret binding evidence, never a substitute secret.
-
-For binding, the runner receives and reads the exact importer target-secret file only after `lstat` regular-file/no-symlink/owner/mode checks. It derives the secret version and SHA-256 from those exact bytes, parses only canonical TLS host/port/database without retaining username/password, verifies that tuple plus CA/SPKI, PostgreSQL system identifier, database OID, manifest/schema fingerprints, and expected `mosaic_data_importer` role against its verified target, then signs. The runner uses `DATABASE_MIGRATION_URL` for its verification connection; it does not use importer credentials for DDL or DML.
-
-`mosaic storage migrate-tier` accepts exactly `--target-url-file /run/secrets/mosaic_migrate_target_url` and `--target-attestation-file /run/mosaic-attestations/migrate-target.v1.json`. Before **any** target connection it `lstat`s both files; validates the pinned public key/key ID, signature, JCS canonicality, expiry, nonce replay cache, secret version, target-file digest, canonical host/port/database, CA binding, expected importer role, and manifest/schema fields; then opens the validated URL fd once, digests and parses those in-memory bytes, and connects from those same bytes with no reread. Missing, substituted, changed-after-check, stale, replayed, tampered, wrong-key, or wrong-binding inputs return stable sanitized attestation errors with **zero target connection and zero DDL**. The nonce replay cache is durable through the artifact expiry window and atomically claims `(keyId, nonce, credentialFileSha256)` before connecting; a replay is terminal. New active and overlap public keys are pinned by key ID; rotation accepts only the bounded overlap, revocation removes a key immediately, and any credential secret-version rotation invalidates prior artifacts and requires a fresh runner verification/signature.
-
-Only after verified TLS connection and before transaction/DML, the importer compares server system identifier, database OID, `current_user`, CA/SPKI, and manifest/schema fingerprint with the attestation. A mismatch closes the connection with **zero DML/DDL**. Its grants and statement classifier make DDL impossible. KBN-101-02 tests missing/wrong/stale/replayed/tampered attestation, wrong/revoked key, substituted URL file, file changed after check, wrong host/database/CA/role/manifest/system ID, digest/version mismatch, and both `zero target connection` versus `connection then zero DML` outcomes. KBN-101-03 tests JCS/signing/atomic producer semantics; KBN-101-05 tests private/public key and artifact mounts/rendering; KBN-101-06 invokes the complete matrix; KBN-101-07 owns the operator guide only.
-
-### 2.2 Complete current documentation disposition inventory
-
-The KBN-101-06 fixture records these exact non-normative paths: `README.md`, `CLAUDE.md`, `docs/federation/SETUP.md`, `docs/guides/admin-guide.md`, `docs/guides/dev-guide.md`, `docs/guides/deployment.md`, `docs/guides/migrate-tier.md`, `docs/guides/user-guide.md`, `docs/fleet/backlog-conventions.md`, `docs/PERFORMANCE.md`, `docs/plans/2026-03-15-agent-platform-architecture.md`, and `docs/design/storage-abstraction-middleware.md` as `operator-document`; each is runner/delegate/deny/superseded/active-secure as adjacent text specifies. `docs/federation/TASKS.md` is an exact `operator-document` `status-only` historical record: its shipped M1 language is superseded and cannot authorize current DDL, extension creation, or importer execution. `docs/PRD.md`, this contract, `SHARED-CONTRACT.md`, and `native-kanban-sot/TASKS.md` are exact `normative-contract` records; their declarative KBN requirements are scan-visible but excluded from operator execution and cannot mask an instruction. The full-doc scanner must fail an unknown active command, a missing record, or a status-only/normative path containing executable bypass guidance.
-
-The only allowlist categories are `historical-sql` (`packages/db/drizzle/**`, byte-immutable runner input only), `pglite-local` (an explicitly PGlite-only source/test path), `negative-test-literal` (a focused negative test), `vendored-generated` (a generated or vendored artifact), and `historical-review-report` (`docs/reports/**` only). Every allowed record names its exact path, token(s), rationale, expiry, and review revision. No allowlist category is valid for an executable current source/script/package bin, operator document, deploy manifest, `README.md`, `CLAUDE.md`, `docs/plans/**`, or `docs/guides/**`; `historical-review-report` cannot contain an operative command. Scanner self-tests place each token in an unowned current path, prove duplicate-owner/ownerless/path-existence failure, and prove an operative `db:migrate` instruction in a path labeled historical fails rather than being masked. The scanner is a classifier plus path inventory and review—not a naive token scan alone—and never by itself proves DDL authority. For every non-allowlisted inventory row and `gateway-a`/`gateway-b`, the matrix proves `DATABASE_URL`-only, missing migration URL, direct library import, direct Drizzle, `db:push`, init artifact, operator route, runtime-only fixture/test, and each harness migration Job/Gateway fail before connection/DDL as applicable. The `db:push` negatives also cover production-like tier and production-like URL rejection.
-
-## 3. Exact migration manifest, ledger, and lock
-
-### 3.1 Manifest v1
-
-The runner generates and verifies a source-controlled **migration manifest v1** from the shipped Drizzle journal and SQL files. A record has exactly:
-
-```text
-logicalIndex: non-negative integer from journal array position
-journalTag: exact journal `tag` string
-migrationSha256: lowercase SHA-256 of the exact migration `.sql` file bytes
-```
-
-The canonical SQL bytes are the raw Git blob bytes at the signed source-release commit, not workstation checkout bytes. KBN-101-03 adds/validates an LF-pinning `.gitattributes` rule for `packages/db/drizzle/**/*.sql`, generates the source-controlled manifest from those canonical blobs in CI, and makes the runner verify deployed file bytes against the manifest before DDL. No newline, Unicode, whitespace, SQL, or line-ending normalization is applied. Manifest canonical serialization is UTF-8 bytes of:
-
-```text
-mosaic-drizzle-manifest-v1\n
-<logicalIndex>\t<JSON.stringify(journalTag)>\t<migrationSha256>\n
-... in ascending logicalIndex with no omitted index
-```
-
-`manifestSha256` is SHA-256 of those canonical bytes. The manifest has no timestamp-derived ordering; `folderMillis`, legacy ledger `id`, and `created_at` are diagnostic only. KBN-101-03 corrects journal **logical** order metadata (including the current `0008`/`0009` anomaly) without changing shipped `0009` bytes.
-
-The runner stores certification in `drizzle.__mosaic_migration_manifest` with exactly one active v1 row (`manifest_version=1`, `manifest_sha256`, `certified_at`). It is owned by `mosaic_schema_owner`; only the migrator after `SET ROLE mosaic_schema_owner` may insert/update it; runtime gets `SELECT` only, and `PUBLIC` gets no schema/table privilege. Existing databases receive this table through the runner after backup/preflight; it is not created by Gateway, a test, or manual SQL.
-
-### 3.2 Reconciliation and 0009 transition
-
-The expected ledger is the ordered list of v1 manifest tuples. The runner reads every observed `drizzle.__drizzle_migrations.hash`, maps **each observed hash to exactly one** manifest tuple, and rejects a missing, unknown, duplicate, ambiguous, corrupt, or stale-replica mapping. Equality is tuple-complete: every expected tuple occurs once, no additional tuple occurs, and the manifest digest matches. A count comparison or hash-set comparison is forbidden. Physical legacy insertion `id`, insertion timestamp, and order are expressly non-normative.
-
-For an existing database:
-
-1. take the KBN-101-07 approved backup and capture a read-only inventory before changing anything;
-2. if `0009` is missing **and** its effects are absent, run the original shipped `0009` through `mosaic-db-migrator` and record it normally;
-3. if the `0009` hash is present but physically late, accept it when its one-to-one tuple mapping is exact;
-4. if an expected hash is missing while its effects are partial or complete, or catalog/ledger evidence conflicts, fail closed as `DATABASE_MIGRATION_RECONCILIATION_AMBIGUOUS`. Recovery is backup restoration or an explicit separately reviewed repair artifact with its own owner, tests, backup, rollback, and approval—not manual ledger insertion/adoption; and
-5. write/update the v1 certification row only after exact reconciliation and final catalog/readiness verification.
-
-Required runner tests cover clean, pre-0009, skipped-0009/effects-absent, applied-late, duplicate, unknown, missing, corrupt tuple-pair, partial/full-effect ambiguity, stale replica, backup/restore, and rerun idempotence. The tests prove the `0009` SQL bytes are unchanged and logical journal ordering—not physical ledger order—controls reconciliation.
-
-### 3.3 Fixed advisory-lock namespace
-
-Before any preflight that can decide migration state, `mosaic-db-migrator` acquires `pg_try_advisory_lock(1297044289, 1262636593)`. The constants are signed-int4-safe fixed namespace values: class `1297044289` (`MOSA`) and object `1262636593` (`KBN1`). The same `max: 1` session retains it for preflight, reconcile, migrate, verify, release, and close. Failure returns `DATABASE_MIGRATION_LOCKED` immediately; a process crash releases it when the PostgreSQL connection closes. Runtime readiness remains unready while a holder is active and never waits by running migrations. Tests prove concurrent contention, crash/connection-loss release, readiness while held, and non-interference from an unrelated advisory key.
-
-## 4. PostgreSQL roles, identifiers, and trusted sessions
-
-Role creation, passwords, membership, database ownership, certificates, and Vault values are platform/IaC/operator work—not Drizzle/application migrations. Application SQL must not issue credential/role management statements or embed credentials.
-
-| Role                              | Attributes and ownership                                                                                                                                                                                                                                                    | Membership / session use                                                                                                                                                                                                                                                                                                                                                                                                             |
-| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `mosaic_platform_database_owner`  | `NOLOGIN NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION NOBYPASSRLS`; platform-only database owner after bootstrap.                                                                                                                                                      | Never granted to application roles.                                                                                                                                                                                                                                                                                                                                                                                                  |
-| external platform bootstrap actor | Provider/operator/IaC-controlled, externally audited **superuser** identity outside the Mosaic role graph and Vault/application configuration.                                                                                                                              | Creates/transitions the database and roles, then retires from application use. It alone `SET ROLE`s the extension owner for `CREATE EXTENSION`, `ALTER EXTENSION ... UPDATE`, or `ALTER EXTENSION ... SET SCHEMA`, records the action, and `RESET ROLE`s.                                                                                                                                                                            |
-| `mosaic_schema_owner`             | `NOLOGIN NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION NOBYPASSRLS`; owns only `mosaic`/`drizzle` schemas and application/ledger objects. It has only `USAGE` on `mosaic_extensions` for fixed legacy type resolution.                                                  | Never an application login; no ownership, `CREATE`, `ALTER`, `DROP`, extension/member-change, or default-privilege authority in `mosaic_extensions`; its migrator subphase never receives temporary `CREATE` there.                                                                                                                                                                                                                  |
-| `mosaic_extension_owner`          | Dedicated `NOLOGIN SUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION NOBYPASSRLS` extension owner, distinct from platform/schema/migrator/runtime. It is used solely to own/maintain untrusted `vector`, `mosaic_extensions`, and every owner-bearing extension member there. | `rolcanlogin=false`, `rolsuper=true`, and **zero members** are catalog-proven. No application role has membership, `SET ROLE`, credential, or inheritable grant. An externally controlled, audited platform-bootstrap **superuser** session alone executes `SET ROLE mosaic_extension_owner` for fresh creation, approved-owner update/relocation, or shadow bootstrap, then `RESET ROLE`; no persistent membership is ever granted. |
-| `mosaic_migrator`                 | `LOGIN NOINHERIT NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION NOBYPASSRLS`.                                                                                                                                                                                            | Only `mosaic_schema_owner`; runner verifies `session_user=mosaic_migrator`, `SET ROLE mosaic_schema_owner`, then `current_user=mosaic_schema_owner`.                                                                                                                                                                                                                                                                                 |
-| `mosaic_data_importer`            | `LOGIN NOINHERIT NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION NOBYPASSRLS`; dedicated data-copy identity, not a DDL or schema owner.                                                                                                                                   | It is used only after runner preparation/verification through the KBN-101-02 file-reference interface. It has no owner/migrator/extension membership and cannot `SET ROLE mosaic_extension_owner`, or `ALTER`/catalog-or-extension-member `UPDATE`/`DROP`/change extension membership. Its bounded data-copy DML is not extension authority.                                                                                         |
-| `mosaic_runtime_capability`       | `NOLOGIN` and no ownership/administrative attributes.                                                                                                                                                                                                                       | Holds only named runtime grants.                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `mosaic_runtime`                  | `LOGIN INHERIT` with no ownership/administrative attributes.                                                                                                                                                                                                                | Only `mosaic_runtime_capability WITH INHERIT TRUE, SET FALSE, ADMIN FALSE`; never owner/migrator member.                                                                                                                                                                                                                                                                                                                             |
-
-The fixed application/runtime schema is **`mosaic`**. Every application/runtime pooled connection executes and verifies exactly `SET search_path TO pg_catalog, mosaic` before its first application query; connection checkout repeats this after reset/reconnect. Transactional application operations use `SET LOCAL search_path TO pg_catalog, mosaic` and verify it before query execution. `public` and `$user` are forbidden in all runtime paths.
-
-The sole runner has one narrowly bounded **legacy-history bootstrap subphase** for the immutable current journal: before it runs, external bootstrap revokes `CREATE` on `public` from `PUBLIC`, temporarily assigns its ownership to `mosaic_schema_owner`, and denies all runtime connections. The externally controlled audited bootstrap-superuser session first executes `SET ROLE mosaic_extension_owner` to create/own `mosaic_extensions` and fresh `vector`, or to perform approved-owner relocation/update, records that control-plane action, and executes `RESET ROLE`; it receives no membership because a superuser can assume the role without one. In its locked `max:1` migration session only, after `SET ROLE mosaic_schema_owner`, the runner has only `USAGE` (not ownership or `CREATE`) on `mosaic_extensions` and uses the fixed legacy-only `SET LOCAL search_path TO pg_catalog, public, mosaic_extensions` solely so immutable `0001` resolves its unqualified existing `vector` type. It cannot create, alter, drop, reassign, or change a member there. The preflight catalogs `pg_namespace.nspowner`, schema ACL/default ACLs, `pg_extension.extowner`, and member owners, then directly proves `CREATE`/`ALTER`/`DROP`/member-change denial for runtime, migrator, and schema owner. After relocation/catalog verification and before manifest certification or any runtime readiness, the runner transfers `public` ownership to `mosaic_platform_database_owner`, revokes application `USAGE`/`CREATE`, and restores `pg_catalog,mosaic`. This compatibility subphase is not a runtime/operator option, accepts no configuration identifier, has no fallback, and is removed/disabled before KBN-101-08.
-
-`KBN-101-03` exclusively owns `packages/db/src/schema.ts`, `packages/db/drizzle/meta/*`, `packages/db/drizzle/meta/_journal.json`, the generated relocation migration, and exact database/Drizzle tests. It freezes one exported `export const mosaic = pgSchema('mosaic')`; every application `pgTable` and every application `pgEnum` must be declared through that export. The generated snapshot/journal and future `db:generate` output must target `mosaic` only; a static declaration/SQL test rejects a default-schema application `pgTable`/`pgEnum`, `public` application declaration, or future generated application DDL outside `mosaic`. Historical `0000` through current SQL and the shipped journal provenance are byte-immutable and execute only in the trusted legacy-`public` subphase; they are never rewritten to claim they originally targeted `mosaic`.
-
-### 4.1 pgvector ownership and supported transition
-
-The selected extension policy is fixed for PostgreSQL 17 + pgvector 0.8.2. Its actual target-image `vector.control` evidence must show `relocatable = true` and no `trusted = true` or `superuser = false` setting: `vector` is therefore untrusted and creation requires superuser authority. Fresh databases: the external audited bootstrap-superuser session executes `SET ROLE mosaic_extension_owner`, creates and owns `mosaic_extensions`, then creates `vector` as `CREATE EXTENSION vector WITH SCHEMA mosaic_extensions`; it records the control-plane action and executes `RESET ROLE`. Under that role it revokes default `TABLES`, `SEQUENCES`, `FUNCTIONS`, `TYPES`, and `SCHEMAS` privileges from `PUBLIC`, `mosaic_schema_owner`, `mosaic_migrator`, `mosaic_data_importer`, and `mosaic_runtime`, then grants only the explicitly required read/type/function privileges. It validates `rolcanlogin=false`, `rolsuper=true`, zero role members, `pg_namespace.nspowner`, `pg_extension.extowner`, and owner-bearing extension-member ownership/schema/version (ownerless PostgreSQL catalog member classes are verified as ownerless, never falsely assigned), schema/default privileges, `RESET ROLE`, and the external audit record. Approved-owner update/relocation is likewise performed only by that external session while set to `mosaic_extension_owner`; the existing path is eligible only when `extowner` is already exact. `mosaic_extensions` remains non-writable by runtime, migrator, schema owner, importer, and every service role. They have no membership in `mosaic_extension_owner` and must fail catalog assertions plus `SET ROLE`, `CREATE`/`ALTER`/`DROP EXTENSION`, extension-member `UPDATE`/DDL, and role-membership change denials. Shadow migration and rollback repeat these owner/default-privilege/preflight assertions before copying, before atomic switch, after resume, and before read-only rollback.
-
-PostgreSQL has **no supported** `ALTER EXTENSION ... OWNER TO`. No card may invent it, mutate system catalogs, use `DROP ... CASCADE`, or adopt legacy extension ownership. An existing `vector` is eligible for the clean in-place path only when `pg_extension.extowner` already resolves to the approved `mosaic_extension_owner`; after exact supported-version, `extrelocatable=true`, dependency, and complete expected member-set checks, the bootstrap actor may perform the tested `ALTER EXTENSION vector SET SCHEMA mosaic_extensions`. The same postflight verifies `extowner`, each member owner/schema, version, dependency inventory, and denial for runtime/migrator/schema owner.
-
-A `vector` extension owned by a legacy runtime/single login is **not activated in place**. It fails closed before activation and requires this controlled shadow-database migration: (1) approved backup and read-only inventory; (2) create new database/roles; (3) the audited external bootstrap-superuser session `SET ROLE mosaic_extension_owner`, creates `mosaic_extensions`/`vector`, records the audit event, and `RESET ROLE`; (4) sole runner applies migrations and relocation; (5) copy data with vector dimensions, row counts, checksums, FK, and sequence evidence; (6) quiesce/drain writers; (7) apply and verify final delta; (8) prove role/TLS/readiness; (9) atomically switch connections; and (10) retain the old database read-only for the approved rollback window. Partial/cancel/resume and rollback preserve the old read-only source until the switch; no target unable to shadow-migrate is eligible until separately reviewed. Required tests cover fresh, approved-owner clean existing relocation, legacy-owner shadow path, partial/resume/rollback, N-1, exact `extowner`/member/schema/version assertions, and `SET ROLE`/ALTER/DROP/member-update denials for runtime, migrator, schema owner, importer, and all service roles.
-
-**Superuser exception and threat boundary:** PostgreSQL superuser authority cannot be privilege-limited by `GRANT`/`REVOKE`; this is deliberately **not** a least-privilege claim for `mosaic_extension_owner`. The containment is its dedicated identity, `NOLOGIN`, zero membership, absence from runtime credentials/Vault/application containers, external control-plane-only audited use, and independent review. Any extension create/update/schema operation is a control-plane change requiring independent review, approved backup/rollback, maintenance window, and audit evidence. A managed target that cannot establish this exact `NOLOGIN SUPERUSER`, zero-member, externally controlled role is ineligible until an independently approved, versioned provider-owned extension-owner profile exists; it must not silently retain app/migrator ownership.
-
-`schema.ts` must emit `mosaic_extensions.vector(...)`, and all vector casts/operators/functions in runner, application queries, fixtures, and generated SQL must explicitly qualify `mosaic_extensions` (for example `OPERATOR(mosaic_extensions.<->)`); `mosaic_extensions` is deliberately **not** added to runtime `search_path`.
-
-Before relocation, the runner records a parameterized catalog inventory and dependency graph. It must classify, in dependency order, application enum/domain/base types; owned and identity sequences; application tables; table columns/defaults; functions/procedures; views/materialized views; extension-owned objects; then triggers, constraints/FKs, indexes, and dependent rules/policies. It moves base types, sequences, tables, and functions as required; OID-bound constraints/indexes follow their owning objects and are catalog-verified rather than recreated blindly. Every object must be expected exactly once and be in either the immutable legacy/bootstrap allowlist, the `mosaic` application allowlist, or the selected `mosaic_extensions` extension membership; unknown, extra, duplicate, cross-schema, dependency-cycle, or partial-resume state fails closed. No raw client-side identifier interpolation is allowed.
-
-`KBN-101-00` owns bootstrap-role/schema/extension/default-privilege and direct-denial tests. `KBN-101-03` owns the runner integration tests that consume those bootstrap fixtures: approved-owner existing relocation, legacy-owner shadow migration, interrupted/partial relocation resume, partial/cancel shadow resume, and pre-activation reverse rollback-before-activation. Reverse rollback is allowed only before KBN-101-08 and restores the approved backup or the reviewed inverse relocation, never a runtime `search_path` bypass. Its N-1 order is: current legacy release → inactive bootstrap/runner and `mosaic` declarations → catalog relocation/generated-artifact verification or approved shadow migration → verified non-owner runtime activation. The combined evidence includes byte-immutable historical execution, no public application objects/declarations/future SQL, vector type/cast/operator query success under fixed `pg_catalog,mosaic`, exact extension-owner/member/schema/version assertions, catalog and direct ALTER/DROP/member-change denials for runtime/migrator/schema owner, and all extension eligibility negatives.
-
-No SQL identifier may come from URL/config/environment/operator input. Catalog comparisons use parameter values. The fixed identifiers above are constants; the external bootstrap artifact alone may use server-side `format('%I', fixed_allowlisted_identifier)` after allowlist validation. Raw client-side interpolation for identifiers, `SET search_path`, database, schema, role, table, or extension names is forbidden. Tests include injection-shaped values, a poisoned pooled-session reset, and transaction `SET LOCAL` restoration negatives.
-
-External bootstrap executes `REVOKE CONNECT, TEMPORARY ON DATABASE <fixed_database> FROM PUBLIC`, then grants `CONNECT` only to `mosaic_runtime`, `mosaic_migrator`, and the time-bounded external bootstrap actor while it is required. Certification fails if an unrelated login retains `CONNECT` or either application login retains `TEMPORARY`. Runtime receives `USAGE` on `mosaic`, named table/sequence grants through `mosaic_runtime_capability`, and `USAGE` on `drizzle` plus `SELECT` only on `drizzle.__drizzle_migrations` and `drizzle.__mosaic_migration_manifest`. `INSERT`, `UPDATE`, `DELETE`, `TRUNCATE`, and DDL rights on ledger/manifest are revoked. Revoke public CREATE and function EXECUTE; `SECURITY DEFINER` is forbidden unless a separately reviewed exception pins trusted path and grants only the capability role. Database TEMPORARY, role management, extension, schema, and object ownership are denied.
-
-Immutable KBN relations, after KBN-100 creates them, grant runtime only `SELECT, INSERT` and explicitly deny `UPDATE, DELETE, TRUNCATE, REFERENCES, TRIGGER`: `task_events`, `artifacts`, `task_checkpoints`, `task_checkpoint_artifacts`, and `approval_decision_artifacts`. KBN-100 retains RESTRICT/no-cascade semantics. Foundation certification verifies the role/schema boundary only; post-KBN-100 certification verifies this real deployed-role matrix.
-
-## 5. Deployable verified-TLS bootstrap
-
-`mosaicstack/stack` is the named repository/control plane. Ownership is intentionally non-overlapping: **KBN-101-00 exclusively owns** the versioned external bootstrap interface `infra/pg-bootstrap/roles.sql`, `infra/pg-bootstrap/extensions.sql`, and `infra/pg-bootstrap/README.md`, plus its bootstrap tests—roles, extension-owner transition, and no renderer/deployment manifests. **KBN-101-05 exclusively owns** `tools/db/render-postgres-secrets.ts`, its tests, the current `docker-compose.yml`, `docker-compose.federated.yml`, `deploy/portainer/federated-test.stack.yml`, `tools/federation-harness/docker-compose.two-gateways.yml`, and `apps/gateway/Dockerfile`; it consumes the versioned KBN-101-00 bootstrap interface and owns no bootstrap SQL. The named **Mosaic deployment control plane / Jason** is activation authority; the environment-specific IaC/Vault owner supplies only approved input secret versions and may not substitute an unreviewed current-repository artifact. The KBN-101-05 renderer is the only deployment handoff: it reads secret-provider references, validates owners/modes/digests/SANs, writes each output atomically (`mkstemp` on the target tmpfs, `fsync`, `chmod`/`chown`, atomic rename), and records only secret-version identifiers and hashes.
-
-`KBN-101-05` changes the Gateway image to fixed non-root `USER 10001:10001`. Gateway CA and Gateway leaf-certificate mounts, and its own Gateway private key only when it terminates its HTTPS listener, must be readable by `10001:10001`; PostgreSQL private keys and migration-only material are never mounted there, and no secret is world-readable. PostgreSQL is not assigned a guessed UID/GID: its image must first be pinned by digest, and an image-inspection plus rendered Compose/Swarm test freezes the image's effective PostgreSQL UID:GID before the renderer selects mount owner/group. A digest, service UID/GID, rendered secret `uid`/`gid`/`mode`, or container `USER` mismatch is a KBN-101-05 failure. Mosaic applications never generate, self-sign, copy, or persist production certificates; the external bootstrap actor receives them only through the deployment secret mechanism and no plaintext development exception exists for production-like modes.
-
-| Material                    | Vault target / deployment secret                                                                                        | Mount, injection, and authorized consumer                                                                                                                                                                                                                         |
-| --------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Runtime URL                 | `secret-{env}/mosaic-stack/database/runtime` (`url`) → `mosaic-db-runtime-url-v1`                                       | Gateway only: `/run/secrets/mosaic-db-runtime-url`, `0600`, `10001:10001`; entrypoint maps it to `DATABASE_URL` only at process exec. It is denied to every migrator, storage runtime, fleet, ordinary CLI, and test except an explicit runtime-negative fixture. |
-| Migration URL               | `secret-{env}/mosaic-stack/database/migrator` (`url`) → `mosaic-db-migrator-url-v1`                                     | Each one-shot migrator only: `/run/secrets/mosaic-db-migrator-url`, `0600`, fixed migrator UID:GID asserted by the image/render test; entrypoint maps it only to `DATABASE_MIGRATION_URL`. It is denied to Gateway, storage runtime, fleet, and ordinary CLI.     |
-| Attestation signing key     | `secret-{env}/mosaic-stack/database/migrate-target-attestation` (`private_key`) → `mosaic-db-migrate-target-ed25519-v1` | Runner root-wrapper only: fixed `/run/secrets/mosaic-db-migrate-target-ed25519`, `root:root` `0400`, referenced only by `MOSAIC_DB_ATTESTATION_SIGNING_KEY_FILE`; no importer/runtime/Gateway mount or log/export is permitted.                                   |
-| Attestation public key ring | versioned deployment public-key bundle → `mosaic-db-migrate-target-ed25519-public-v1`                                   | Importer only: pinned `/run/mosaic-attestations/migrate-target.ed25519.pub`, `0444`; active/overlap key IDs are explicit and revoked IDs fail closed. It contains no private key.                                                                                 |
-| Target attestation artifact | runner-produced non-secret file                                                                                         | Controlled shared mount `/run/mosaic-attestations/migrate-target.v1.json`, `0444`, atomic write/rename only; importer may read it but cannot write it.                                                                                                            |
-| CA bundle                   | `secret-{env}/mosaic-stack/database/tls-ca` (`certificate`) → `mosaic-db-ca-v1`                                         | Gateway/migrator: `/run/secrets/mosaic-db-ca.crt`, `0444`, owned by the consuming UID:GID; CA is public trust material. PostgreSQL receives a distinct read-only CA copy only when client-cert validation is enabled.                                             |
-| Gateway leaf certificate    | `secret-{env}/mosaic-stack/federation/gateway-server-tls` (`certificate`) → `mosaic-gateway-server-cert-v1`             | Gateway only: `/run/secrets/mosaic-gateway-server.crt`, `0444`, `10001:10001`; renderer emits this exact Compose and Swarm target and validates it before start.                                                                                                  |
-| Gateway private key         | same Vault record (`private_key`) → `mosaic-gateway-server-key-v1`                                                      | Gateway only: `/run/secrets/mosaic-gateway-server.key`, `0400`, `10001:10001`; not mounted to migrator or PostgreSQL and never world-readable.                                                                                                                    |
-| PostgreSQL leaf certificate | `secret-{env}/mosaic-stack/database/postgres-server-tls` (`certificate`) → `mosaic-postgres-server-cert-v1`             | PostgreSQL only: `/run/secrets/mosaic-postgres-server.crt`, `0444`, frozen verified postgres UID:GID.                                                                                                                                                             |
-| PostgreSQL private key      | same Vault record (`private_key`) → `mosaic-postgres-server-key-v1`                                                     | PostgreSQL only: `/run/secrets/mosaic-postgres-server.key`, `0400`, frozen verified postgres UID:GID; never mounted to Gateway or migrator.                                                                                                                       |
-
-Compose uses identically named local **secret references** rendered by the named renderer into non-repository tmpfs paths; Swarm declares the same secrets and target paths with the tested `uid`, `gid`, and mode. KBN-101-05 rejects bind-mounted committed cert/key files, environment-encoded PEM, missing secrets, non-atomic renderer output, private-key access outside its named consumer (Gateway for Gateway key; PostgreSQL for PostgreSQL key), and any world-readable URL/key. The existing target Vault names are planned canonical paths and must be verified/provisioned by the deployment-owner input; the planning card does not claim they exist.
-
-The server leaf SANs are frozen to actual connection DNS names, not a configurable alias:
-
-| topology                             | PostgreSQL service DNS names that must be SANs                                                     | Gateway leaf SANs / consumers                                                                                                                                                       |
-| ------------------------------------ | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| standalone compose                   | `DNS:postgres`, `DNS:localhost` (only for the documented host-port disposable test path)           | `DNS:gateway`; its Gateway process consumes runtime URL + CA + Gateway leaf/key only                                                                                                |
-| federated compose                    | `DNS:postgres-federated`, `DNS:localhost` (only for the documented host-port disposable test path) | `DNS:gateway-federated`; runtime/migrator consume only their database-specific material                                                                                             |
-| Portainer/Swarm federated test stack | `DNS:postgres` (the in-stack service endpoint used by Gateway and migrator)                        | `DNS:gateway`; same consumer isolation                                                                                                                                              |
-| two-gateway harness                  | `DNS:postgres-a`, `DNS:postgres-b`                                                                 | `DNS:gateway-a`, `DNS:gateway-b`; each Gateway gets only its own runtime URL, CA, and Gateway leaf/key; each `mosaic-db-migrator-{a,b}` gets only the matching migration URL and CA |
-
-A new topology requires a versioned amendment before issuance. The PostgreSQL container activation artifact sets `ssl=on`, `ssl_cert_file`, and `ssl_key_file` to those paths, uses a locked-down `postgresql.conf` include, and verifies file ownership/mode before start. The server health/readiness gate makes a `verify-full` CA/SAN-validated connection as the approved runtime/migrator identity; `pg_isready` alone is insufficient. Migration Job starts only after server TLS readiness. Gateway replicas start only after a successful runner result and independently pass verified-TLS, identity, search-path, and ledger readiness. In the two-gateway harness this ordering occurs independently as `postgres-a → mosaic-db-migrator-a → gateway-a` and `postgres-b → mosaic-db-migrator-b → gateway-b`; no Gateway starts against its database before its own runner certificate succeeds.
-
-**Fresh DB:** provision CA/leaf/secrets and server TLS configuration before initial database bootstrap; bootstrap/extension prerequisites run, then the runner migrates over verified TLS, then runtime deploys. **Existing DB:** take the approved backup, provision/mount TLS material, and **drain/scale to zero every N-1 runtime, worker, CLI maintenance process, and replica before TLS enforcement**. Enable server TLS, terminate any residual non-TLS PostgreSQL backend sessions, set `pg_hba.conf` to `hostssl` for all application/migrator CIDRs with no matching `host` rule, reload/restart as required, and prove the non-TLS session count is zero. Only then prove `verify-full` through the existing endpoint, run reconciliation/migration, and roll the non-owner TLS runtime. There is no plaintext transition interval.
-
-**Rotation/rollback:** stage a CA bundle containing old+new trust roots to runtime/migrator, validate a new server leaf with exact SANs, restart PostgreSQL and validate it, roll consumers, then remove the old root only after evidence. Credential rotation remains independent and never mounts migration material into Gateway. Before expiry, rollback restores the prior known-valid leaf/key and overlapping CA bundle, restarts PostgreSQL, enforces `hostssl`, terminates residual non-TLS sessions, and verifies `verify-full`; it never downgrades `sslmode`, restores a plaintext-only N-1 runtime after enforcement, or accepts plaintext. A pre-enforcement abort may restore the backed-up N-1 state only before `hostssl` is enabled and is recorded as an aborted—not activated—release. The runbook records expiry windows, secret versions, backup ID, drained-service/session evidence, activation actor, and validation result—not secret values.
-
-Required disposable tests cover standalone compose, federated/Swarm, and the two-gateway harness positives using verified TLS, plus for **both** gateway/database pairs: missing CA, wrong CA, wrong PostgreSQL SAN, wrong Gateway SAN, `sslmode` downgrade, missing/mispermissioned server or Gateway key, runtime-with-migrator-secret, cross-pair secret leakage, rendered secret-consumer/UID/GID/mode isolation, legacy plaintext drain/termination/`hostssl` enforcement, and readiness-before-migration negatives. PGlite local tests are explicitly classified as non-PostgreSQL and do not satisfy a PostgreSQL TLS test.
-
-## 6. Runtime verification and sanitized failures
-
-Before accepting traffic, runtime queries only parameterized/sanitized identity and privilege metadata on its already-open verified-TLS connection. It fails closed for owner/migrator identity or assumability; superuser/CREATEROLE/CREATEDB/BYPASSRLS; object/schema/database ownership; TEMPORARY; unexpected function execute; missing inherited capability/sequence/ledger grants; any non-exact search path; wrong schema/database target; bad TLS; or manifest/ledger mismatch. After KBN-100 it also checks every immutable grant/denial and relation presence.
-
-The runner performs reciprocal preflight under the same session/lock: dedicated migration DTO only, verified TLS, exact allowlisted target, migrator `session_user`, schema-owner `current_user`, exact trusted search path, and no unsafe attributes. It fails before DDL otherwise.
-
-Stable sanitized codes are `DATABASE_RUNTIME_URL_REQUIRED`, `DATABASE_MIGRATION_URL_REQUIRED`, `DATABASE_TLS_REQUIRED`, `DATABASE_TLS_VERIFICATION_FAILED`, `DATABASE_ROLE_UNSAFE`, `DATABASE_ROLE_GRANT_MISMATCH`, `DATABASE_SEARCH_PATH_UNSAFE`, `DATABASE_SCHEMA_MISMATCH`, `DATABASE_MIGRATION_RECONCILIATION_AMBIGUOUS`, `DATABASE_MIGRATION_LOCKED`, `DATABASE_MIGRATION_IDENTITY_UNSAFE`, `MIGRATE_TARGET_ATTESTATION_REQUIRED`, `MIGRATE_TARGET_ATTESTATION_INVALID`, `MIGRATE_TARGET_ATTESTATION_EXPIRED`, `MIGRATE_TARGET_ATTESTATION_REPLAYED`, and `MIGRATE_TARGET_BINDING_MISMATCH`. Logs/metrics may contain code, tier, manifest fingerprint, role class, and correlation ID only; never DSN, username, host, database name, SQL parameter, secret, or raw catalog result. External health exposes only unavailable/not-ready.
-
-## 7. Safe DAG, activation, and rollback authority
-
-Every KBN-101 card remains one PR with exclusive ownership. Cards `00`–`07` may merge only as **prepared, inactive capability**: no current owner-runtime deployment consumes their image/config, and no compatibility switch is exposed to a runtime operator. They must not retain `ALLOW_LEGACY_*`, runtime DDL, `DATABASE_URL` migration fallback, plaintext TLS, direct Drizzle, or test-only bypass flags. Current owner-runtime deployments remain on their known N-1 release until final activation.
-
-| Card                                                                    | Depends on  | Complete, disjoint file/glob manifest and required test/evidence paths                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| ----------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `KBN-101-00` platform bootstrap / IaC                                   | contract    | **Only:** `infra/pg-bootstrap/roles.sql`, `infra/pg-bootstrap/extensions.sql`, `infra/pg-bootstrap/README.md`, `infra/pg-bootstrap/tests/**`. It creates the extension-owner role/schema/extension interface and proves fresh, approved-owner, legacy-shadow, catalog/default-privilege, and direct-denial bootstrap cases. No renderer, runner, Compose, CI, or deployment path.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `KBN-101-01` typed runtime config and verifier                          | 00          | **Only:** `packages/config/src/index.ts`, `packages/config/src/mosaic-config.ts`, `packages/config/src/mosaic-config.spec.ts`; `packages/db/src/client.ts`, `packages/db/src/defaults.ts`, `packages/db/src/connection-identity.ts`, `packages/db/src/client.spec.ts`, `packages/db/src/defaults.spec.ts`, `packages/db/src/connection-identity.spec.ts`; `apps/gateway/src/database/database.module.ts`, `apps/gateway/src/database/database.module.spec.ts`. It supplies runtime/migration/TLS DTO parsing plus runtime identity/search-path/readiness verification. No migrator, storage, installer, deploy, or CI path.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `KBN-101-03` sole runner, manifest, and schema foundation               | 00,01       | **Only:** `.gitattributes`; `packages/db/package.json`; `packages/db/drizzle.config.ts`; `packages/db/src/cli.ts`, `packages/db/src/cli.spec.ts`, `packages/db/src/index.ts`, `packages/db/src/index.import-negative.spec.ts`, `packages/db/src/migrate.ts`, `packages/db/src/migrate.test.ts`, `packages/db/src/schema.ts`, `packages/db/src/schema.spec.ts`; `packages/db/src/migrator/**`; `packages/db/drizzle/*.sql`, `packages/db/drizzle/meta/*.json`; `docker/db-migrator.Dockerfile`, `docker/db-migrator.Dockerfile.spec.ts`; `packages/db/package-bin.spec.ts`. It alone publishes `"mosaic-db-migrator": "./dist/cli.js"`, verifies source/build/pack/discovery, and sets `ENTRYPOINT ["mosaic-db-migrator"]`; it exclusively owns `packages/db/src/migrator/target-attestation.dto.ts`, `target-attestation-signer.ts`, and their specs: fixed-key reference validation, JCS canonical payload, Ed25519 signing, producer TLS/identity/manifest binding, atomic artifact emission, and producer tests. It owns journal/manifest/ledger/lock/relocation/shadow tests. Shipped `0009` bytes stay unchanged.                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `KBN-101-02` runtime DDL closure                                        | 01,03       | **Only:** `docker/init-db.sql`, `infra/pg-init/01-extensions.sql`; `packages/storage/src/adapters/postgres.ts`, `packages/storage/src/adapters/postgres.spec.ts`, `packages/storage/src/factory.ts`, `packages/storage/src/factory.spec.ts`, `packages/storage/src/types.ts`, `packages/storage/src/tier-detection.ts`, `packages/storage/src/tier-detection.spec.ts`, `packages/storage/src/cli.ts`, `packages/storage/src/cli.spec.ts`, `packages/storage/src/migrate-tier.ts`, `packages/storage/src/migrate-tier.spec.ts`, `packages/storage/src/migrate-tier.integration.test.ts`; `apps/gateway/src/main.ts`, `apps/gateway/src/__tests__/integration/federated-boot.pg-unreachable.integration.test.ts`, `apps/gateway/src/__tests__/integration/federated-boot.success.integration.test.ts`, `apps/gateway/src/__tests__/integration/federated-pgvector.integration.test.ts`; `packages/db/src/federation.integration.test.ts`; `packages/mosaic/src/commands/fleet-backlog.ts`, `packages/mosaic/src/commands/fleet-backlog.spec.ts`. It consumes the -03 runner and exclusively owns importer verification/interface in `packages/storage/src/{cli,migrate-tier}.ts` and the named unit/integration specs: paired URL/attestation options, file/fd/TOCTOU checks, signature/key/expiry/replay/secret/digest/binding validation, post-TLS zero-DML comparison, and DDL classifier. It closes runtime/retired-init DDL only and excludes every -03 signer/runner, index, migrate, and Drizzle-config asset, and every deployment/CI/doc path. |
-| `KBN-101-04` installer/wizard                                           | 01          | **Only:** `packages/mosaic/src/stages/gateway-config.ts`, `packages/mosaic/src/stages/gateway-config.spec.ts`, `packages/mosaic/src/stages/gateway-config-cors.spec.ts`, `packages/mosaic/src/stages/wizard-menu.spec.ts`, `packages/mosaic/src/wizard.ts`. It persists only non-secret references/injected-variable contracts; source inspection excludes `tools/install.sh`, which does not read/write the database DSN.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `KBN-101-05` renderer and deployment                                    | 00,03       | **Only:** `tools/db/render-postgres-secrets.ts`, `tools/db/render-postgres-secrets.spec.ts`; `apps/gateway/Dockerfile`, `apps/gateway/Dockerfile.spec.ts`; `docker-compose.yml`, `docker-compose.spec.ts`; `docker-compose.federated.yml`, `docker-compose.federated.spec.ts`; `deploy/portainer/federated-test.stack.yml`, `deploy/portainer/federated-test.stack.spec.ts`; `tools/federation-harness/docker-compose.two-gateways.yml`, `tools/federation-harness/docker-compose.two-gateways.spec.ts`. It consumes the -00 bootstrap interface and -03 immutable runner image, and exclusively renders/tests runner-only root-owned signing-key reference, importer-only public-key/key-ring, and controlled `0444` attestation artifact mount; it owns no bootstrap, runner, config, storage, or CI file.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `KBN-101-07` operator/runbook/docs                                      | 02,03,04,05 | **Only:** `README.md`, `CLAUDE.md`, `docs/guides/admin-guide.md`, `docs/guides/dev-guide.md`, `docs/guides/deployment.md`, **`docs/guides/migrate-tier.md`**, `docs/guides/user-guide.md`, `docs/federation/SETUP.md`, `docs/federation/TASKS.md`, `docs/fleet/backlog-conventions.md`, `docs/PERFORMANCE.md`, `docs/design/storage-abstraction-middleware.md`, `docs/plans/2026-03-15-agent-platform-architecture.md`, `docs/runbooks/kbn-101-database-role-split.md`, `docs/reports/native-kanban-sot/kbn-101-operator-readiness-report.md`, `docs/native-kanban-sot/tests/kbn-101-operator-docs.spec.ts`. It exclusively owns the active migrate-tier operator route and documents the interfaces produced by -02/-03/-04/-05, including both file references, signing-key isolation, attestation bindings, rotation/replay, and no-connection/no-DML errors; it owns no source, storage, CLI, runner, or CI file.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `KBN-101-06` CI classifier and command matrix                           | 02,03,05,07 | **Only:** `.woodpecker/ci.yml`, `tools/ci/kbn101-ddl-inventory.ts`, `tools/ci/kbn101-ddl-inventory.spec.ts`, `tools/ci/fixtures/kbn101-ddl-inventory.json`, `tools/ci/kbn101-entrypoint-matrix.ts`, `tools/ci/kbn101-entrypoint-matrix.spec.ts`. It invokes the already-produced bin/image/deployment/doc artifacts and edits no producer file. Its inventory test enforces manifest overlap, ownerless, duplicate-owner, path-existence, allowlist, active-route field completeness, finite operator-document inventory, normative-contract non-masking, unknown-command, and historical/status-only masking failures; its matrix invokes the -02 secure target route and verifies every declared attestation refusal before target connection/DDL and post-connect mismatch with zero DML.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `KBN-101-08` foundation certification and **atomic activation release** | 00…07       | **Only evidence:** `docs/reports/native-kanban-sot/kbn-101-foundation-activation-certificate.md`, `docs/reports/native-kanban-sot/kbn-101-foundation-activation-evidence.json`. It changes no implementation path. Independent review and terminal-green CI must verify prepared artifacts before Mosaic control plane/Jason authorizes backup → drain/scale-zero N-1 → TLS → roles → runner → verified readiness → rolling runtime; any red result aborts.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `KBN-101-09` post-KBN-100 certification                                 | KBN-100,08  | **Only evidence:** `docs/reports/native-kanban-sot/kbn-101-immutable-role-certificate.md`, `docs/reports/native-kanban-sot/kbn-101-immutable-role-evidence.json`. It changes no implementation path and records real deployed runtime INSERT/SELECT plus UPDATE/DELETE-denial evidence and independent security/Ultron approval.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-
-The manifests above are the complete ownership universe for KBN-101 implementation paths; the KBN-101-06 inventory test fails on overlap, an ownerless in-scope path, or a nonexistent declared path. Cards `00`–`07` are prepared artifacts, not independently deployed releases: the immutable N-1 owner-runtime image stays live until KBN-101-08 control-plane atomic activation. No activation card edits a source-changing path, and no runtime bypass or broken deployed intermediate exists.
-
-**Authority:** Mosaic control plane/Jason is the sole activation and rollback authority. CI, Gateway, migrator, Coordinator, and Certifier cannot activate, waive a red result, or force release. Before an incompatible KBN-100 switch, the authority stops/scales runtime, uses the approved backup/restore or separately reviewed runner artifact, restores only a known TLS-compatible runtime with its runtime secret after `hostssl` enforcement, and verifies no plaintext sessions plus TLS/readiness. Migration URL is never injected into Gateway to enable rollback. KBN-100 starts only after KBN-101-08; KBN-105 starts only after KBN-101-09.
-
-**ASSUMPTION K101-A2:** every eligible production-like deployment can schedule a dedicated migration Job/one-shot command and an operator/IaC-controlled TLS bootstrap. A target that cannot do both is ineligible for KBN certification.
-
-## 8. Acceptance traceability
-
-| Requirement / acceptance criterion | Required implementation evidence                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| K101-REQ-01 / AC-K101-01           | DTO/command matrix covers local/PGlite, standalone, federated, and both harness pairs; every finite classified §2 path rejects `DATABASE_URL`-only before connection/DDL; no runtime fallback/default; `--help`, argv, import-compile, and live-operator-route negatives pass. The active migrate-tier route proves runner-produced JCS/Ed25519 attestation, root-owned signing/private-key and importer-public-key isolation, atomic artifact, exact `--target-url-file /run/secrets/mosaic_migrate_target_url` plus `--target-attestation-file /run/mosaic-attestations/migrate-target.v1.json`, secret-version/digest/TLS/CA/server/database/role/manifest/schema bindings, expiry/replay/rotation/TOCTOU checks, bounded non-DDL importer DML, and missing/wrong/stale/replayed/tampered/substituted/mismatched no-connection versus zero-DML refusal. |
-| K101-REQ-02 / AC-K101-02           | KBN-101-03 one-session fixed two-int lock, `--run`/`--verify` exit-code, contention/crash/readiness/unrelated-key tests; manifest-v1 canonical bytes/digest and all reconciliation states; Gateway/replica DDL impossibility.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| K101-REQ-03 / AC-K101-03           | KBN-101-00 bootstrap schema/extension-owner/default-privilege and direct-denial proof against actual PostgreSQL 17 + pgvector 0.8.2 control metadata (`trusted` absent/untrusted, `relocatable=true`); external-superuser `SET ROLE` create/update/`RESET ROLE` audit proof; `rolcanlogin=false`, `rolsuper=true`, zero members/no runtime credential proof; KBN-101-03 catalog relocation and future-Drizzle-only-`mosaic` proof plus approved-owner/shadow runner integration; `pg_namespace.nspowner`, `pg_extension.extowner`, owner-bearing member/schema/version, and runtime/migrator/schema-owner/importer/all-service-role catalog plus `SET ROLE`/ALTER/DROP/member-update denials; KBN-101-01/03 role, path, TEMP, ledger/default-grant, and pool-reset tests.                                                                                  |
-| K101-REQ-04 / AC-K101-04           | KBN-101-00 bootstrap-interface and KBN-101-05 renderer/deployment tests; immutable-image exact Job commands and runner-before-readiness order; fresh/existing verified-TLS Compose/Swarm/two-gateway positives; both-pair CA/SAN/downgrade/key-permission negatives; exact UID/GID/mode and runtime/migrator secret-consumer rendering/CI negatives.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| K101-REQ-05 / AC-K101-05           | KBN-101-09 after KBN-100: real deployed runtime INSERT/SELECT success and UPDATE/DELETE denial for each frozen relation, with RESTRICT retention evidence.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| K101-REQ-06 / AC-K101-06           | KBN-101-00…08 prepared-card/no-intermediate-deploy evidence; one final activation authority record; N-1 drain/zero-plaintext-session/`hostssl`, backup/restore, CA overlap rotation, TLS-only rollback, Vault/redaction, and no-force-on-red evidence.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| K101-REQ-07 / KBN sequence         | KBN-101-08 foundation certificate before KBN-100, KBN-101-09 real immutable-role certificate plus Ultron approval before KBN-105; KBN-100 rebases/restores Drizzle consistency and never bypasses the serial gates.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| Delivery integrity                 | One-card/one-PR DAG, exact file ownership, docs/link/contract checks, independent author≠reviewer re-review on the pushed exact head, and terminal-green CI for implementation cards.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-
-## 9. Non-goals and residual authority
-
-KBN-101 planning does not create roles, certificates, Vault paths, migrations, deployment artifacts, or a deployed certificate. It does not replace KBN-100’s data migration, immutable retention, tenant constraints, or KBN-105 endpoint freeze. A PostgreSQL superuser/break-glass operator—including the deliberately isolated extension owner—remains outside application containment: `GRANT`/`REVOKE` cannot constrain that authority. Separate identity/non-login/zero-membership/external-control/audit controls, independent review, maintenance windows, backup/rollback evidence, and drills are mandatory.

docs/native-kanban-sot/SHARED-CONTRACT.md

@@ -1,65 +1,14 @@
 # Native Kanban/SOT — Remediated Shared Contract v1
 
-**Status:** CONTROL-PLANE rc.11 KBN-101 target-bound importer-attestation and complete operator-inventory remediation complete; awaiting independent exact-head re-review. Prior KCR-001–016 and rc.4 SI-001 decisions retained; KBN-101 foundation certification precedes KBN-100 and real immutable-operation certification precedes KBN-105
+**Status:** CONTROL-PLANE SI-001 AMENDMENT AUTHORIZED; prior KCR-001–016 independent-review GO retained; rc.4 requires independent schema/SecReview before KBN-100
-**Version:** 1.0.0-rc.11
+**Version:** 1.0.0-rc.4
-**Date:** 2026-07-15
+**Date:** 2026-07-14
 **Change authority:** Mosaic control plane/Jason only
 **SI-001 amendment authority:** `web1:mosaic-100` control-plane decision under issue #753
 
 ## Amendment record
 
-### 1.0.0-rc.11 — Target-bound importer attestation and exhaustive operator-route closure
+### 1.0.0-rc.4 — KBN010-SI-001
-
-- **Target-bound proof:** trusted `mosaic-db-migrator --verify` now produces the atomic, credential-free `migrate-target.v1.json` JCS/Ed25519 artifact from a runner-only root-owned signing-key reference; the importer receives only pinned public verification keys and the artifact. Its signed v1 fields bind issued/expiry/nonce, exact secret version and SHA-256 of high-entropy target-file bytes, canonical TLS host/port/database, CA/SPKI, PostgreSQL system identifier/database OID, expected importer role, manifest/schema fingerprints, and producer invocation/build/image/correlation. No DSN, username, password, credential bytes, or signing key enters the artifact, importer, runtime, logs, or output.
-- **Fail-closed importer:** `mosaic storage migrate-tier` requires both `--target-url-file /run/secrets/mosaic_migrate_target_url` and `--target-attestation-file /run/mosaic-attestations/migrate-target.v1.json`. Before target connection it validates files, signature/key/expiry/replay, secret version/digest, TLS/CA/role/manifest bindings and opens/digests/connects from the same in-memory URL bytes. After verified TLS but before transaction/DML it matches server ID, database OID, `current_user`, CA/SPKI, and manifest/schema; failure distinguishes zero connection from connection/zero-DML and DDL remains impossible. Rotation overlap/revocation, atomic rename, replay cache, secret rotation invalidation, and wrong/substituted/stale/tampered/file-change tests are mandatory.
-- **Closed documentation surface:** KBN-101-06 inventories every current non-normative scanner hit, including `docs/guides/user-guide.md` and status-only `docs/federation/TASKS.md`; the latter is historical and cannot authorize DDL. The legacy `storage migrate` tier-copy syntax is unavailable. `storage migrate` is schema-wrapper delegation only; secure tier data copy is `migrate-tier`. Exact KBN PRD/contract/shared/task paths may be `normative-contract` scan class but are still scanned and cannot mask executable instructions. The normative detail remains [`KBN-101-DB-ROLE-SPLIT.md`](./KBN-101-DB-ROLE-SPLIT.md).
-- **Non-effect:** pgvector closure, manifest, lock, role graph, TLS, activation, and KBN-100/KBN-105 serial gates are unchanged.
-
-### 1.0.0-rc.10 — PostgreSQL-valid untrusted pgvector owner and active migrate-tier closure
-
-- **Valid extension authority:** PostgreSQL 17 + pgvector 0.8.2 `vector` is untrusted (`trusted` absent; `relocatable=true`), so `mosaic_extension_owner` is exactly `NOLOGIN SUPERUSER`, not `NOSUPERUSER`. It is dedicated solely to `mosaic_extensions`, `vector`, and owner-bearing extension members; `rolcanlogin=false`, `rolsuper=true`, zero members, no runtime credential/Vault secret, and no app-container delivery are catalog and deployment proof. An externally controlled audited bootstrap-superuser session alone `SET ROLE`s for extension CREATE/UPDATE/SET SCHEMA, then `RESET ROLE`; fresh and shadow paths do so, while in-place existing work requires exact pre-existing `extowner`.
-- **Explicit superuser exception:** `GRANT`/`REVOKE` cannot privilege-limit a superuser. The containment is dedicated identity, no login, no membership, external control plane, audit, independent review, backup/rollback, and maintenance window—not a false least-privilege claim. Runtime, migrator, schema owner, importer, and every service role cannot assume the role or alter/update/drop/change extension membership. Managed targets without this exact role are ineligible unless a versioned provider-owned extension-owner profile is independently approved.
-- **Active secure data-migration route:** `docs/guides/migrate-tier.md` is exclusively KBN-101-07, is active rather than historical, and specifies runner-prepared/verified PostgreSQL destination plus a dedicated non-DDL importer. KBN-101-02 freezes `--target-url-file /run/secrets/mosaic_migrate_target_url`, never credential argv; raw `--target-url`, `DATABASE_URL` fallback, runtime owner, missing/unsafe file, wrong mode, and DDL all fail before target connection/DDL. KBN-101-06 inventory/matrix records the route and exact secure fields, then tests its finite operator-document closure.
-- **Non-effect:** manifest, lock, `mosaic` application schema, TLS, activation, and KBN-100/KBN-105 serial gates remain unchanged. The normative detail remains [`KBN-101-DB-ROLE-SPLIT.md`](./KBN-101-DB-ROLE-SPLIT.md).
-
-### 1.0.0-rc.9 — KBN-101 extension-schema boundary, disjoint manifests, and scanner mechanics
-
-- **Extension schema owner:** `mosaic_extension_owner`, not `mosaic_schema_owner`, creates and owns `mosaic_extensions`, `vector`, and extension-member objects. The external bootstrap actor `SET ROLE`s for fresh creation or approved-owner relocation, then `RESET ROLE`s; rc.10 replaces the earlier membership wording with the PostgreSQL-valid zero-member superuser exception. Schema owner has only `USAGE` for legacy type resolution—never ownership, `CREATE`, `ALTER`, `DROP`, member change, or default-privilege authority. Runtime, migrator, and schema owner must fail catalog and direct DDL denials; shadow/resume/rollback repeat the owner/default-privilege proof.
-- **Exclusive delivery DAG:** KBN-101-00…09 now has a complete, nonoverlapping exact file/glob manifest with named tests/evidence. The runner mapping is exactly `"mosaic-db-migrator": "./dist/cli.js"` and image `ENTRYPOINT ["mosaic-db-migrator"]`; `packages/storage/src/{cli,migrate-tier}.ts` belongs only to -02, and -07 is documentation only. -08/-09 own evidence paths only. -00…07 are prepared artifacts; the immutable N-1 image remains live until -08 atomic activation, so no independently deployed intermediate can bypass runtime controls.
-- **Mechanical classifier:** -06 owns the exact scanner, inventory fixture, command-matrix harness, and CI wiring. Inventory records pin path/class/owner/disposition/allowed tokens/rationale/expiry/review revision; unknown, duplicate-owner, ownerless, missing-path, invalid allowlist, and historical-category masking fail. The architecture plan's operative direct `db:migrate` is replaced by sole-runner guidance rather than hidden under a historical category.
-- **Non-effect:** manifest v1, lock, `mosaic` application-schema ownership, TLS, activation, KBN-100/KBN-105 serial gates, and all earlier canon decisions remain unchanged. The normative detail remains [`KBN-101-DB-ROLE-SPLIT.md`](./KBN-101-DB-ROLE-SPLIT.md).
-
-### 1.0.0-rc.8 — KBN-101 finite authority, executable runner, and pgvector-owner remediation
-
-- **Finite authority closure:** KBN-101-06 classifies every current executable source/script/package bin, operator document, and deploy manifest by exact path; unclassified current hits fail. Byte-immutable historical SQL, PGlite-only routines, negative-test literals, vendored/generated artifacts, and clearly labeled historical reports are exact-path/category reviewed allowlists only. `packages/db/src/index.ts` loses its public `runMigrations` export with a direct-import/compile negative; `docs/fleet/backlog-conventions.md` and `docs/PERFORMANCE.md` lose first-use/direct-Drizzle/Gateway-startup migration instructions and carry runner/readiness route negatives. A token scan is only input to the classifier, never proof of authority.
-- **Executable exclusive cards:** KBN-101-03 alone publishes `mosaic-db-migrator` from `packages/db/package.json`/`src/cli.ts`, owns `docker/db-migrator.Dockerfile`, and keeps `{runner,config.dto,manifest,identity,tls}` private, with exact `--run|--verify|--help`, env-only input, stable exits, and command tests. KBN-101-00 alone owns `infra/pg-bootstrap/roles.sql`, `infra/pg-bootstrap/extensions.sql`, `infra/pg-bootstrap/README.md`, plus bootstrap tests. KBN-101-05 alone owns `tools/db/render-postgres-secrets.ts`, renderer tests, and Compose/Portainer/Swarm/two-gateway declarations, consuming the versioned bootstrap interface. No card overlaps renderer/bootstrap/deployment ownership.
-- **Extension-owner transition:** `mosaic_extension_owner` is a dedicated NOLOGIN role whose membership/credentials never reach services; the external bootstrap actor alone may `SET ROLE` during bootstrap. Fresh vector and member objects retain that owner. PostgreSQL has no supported extension-owner alteration: approved-owner existing extension relocation validates `pg_extension.extowner`, members/schema/version and uses tested `ALTER EXTENSION ... SET SCHEMA`; legacy runtime-owned extension fails closed to a controlled shadow database migration with backup, evidence, quiesce/final delta, atomic switch, and read-only rollback window. No catalog mutation, ownership adoption, or `DROP CASCADE` is permitted. Runtime/migrator/schema-owner extension ALTER/DROP/member-update denial is mandatory.
-- **Non-effect:** manifest v1, lock namespace, role/search-path, relocation/TLS/activation, KBN-100/KBN-105 serial gates, and all retained canon decisions are strengthened, not weakened. The normative detail remains [`KBN-101-DB-ROLE-SPLIT.md`](./KBN-101-DB-ROLE-SPLIT.md).
-
-### 1.0.0-rc.7 — KBN-101 complete current-path, relocation, and two-gateway remediation
-
-- **Finite current-path closure:** static inventory and the `DATABASE_URL`-only-before-connect/DDL denial matrix now explicitly include Gateway's former temporary-table pgvector test (runner-prepared persistent read/query-only fixture), `docker/init-db.sql` retirement, `migrate-tier.ts` runner/bootstrap-only guidance, and the active two-gateway harness. The harness is migrated, not retired: `postgres-a/b → mosaic-db-migrator-a/b → gateway-a/b`, each with isolated URL/CA material, verified readiness, SANs, and positive/negative TLS evidence.
-- **Executable relocation:** KBN-101-03 exclusively owns `schema.ts`, Drizzle snapshots/journal/generated relocation and exact tests. All future application declarations use exported `pgSchema('mosaic')`; immutable historical SQL runs only in trusted legacy `public`. `vector` is fixed in non-writable `mosaic_extensions`, with exact catalog relocatability/version eligibility, explicit type/operator qualification, catalog-class ordering, unknown-object fail-closed behavior, clean/current-public/partial/reverse rollback tests, and an N-1 release order.
-- **Bound deployment ownership:** `mosaicstack/stack` KBN-101-00/05 owns current Compose, Portainer, two-gateway, bootstrap renderer/templates, UID/GID declarations, and rendered validation. Gateway is fixed to `10001:10001`; PostgreSQL UID/GID is image-inspected and frozen only after digest pinning. Exact secret paths, atomic renderer behavior, Compose/Swarm targets/modes, Gateway/PostgreSQL leaf separation, and two-pair TLS failure evidence are required. Mosaic deployment control plane/Jason is the named activation authority; environment IaC/Vault supplies versioned input only.
-- **Correct traceability:** REQ-03 maps to role/schema/search-path, REQ-04 to TLS, REQ-05 to post-KBN-100 immutability, REQ-06 to rollout/rollback, and REQ-07 to the KBN-101 → KBN-100 → KBN-101 → KBN-105 sequence. No prior manifest/lock/role/DAG/activation decision is weakened.
-
-### 1.0.0-rc.6 — KBN-101 closed DDL/TLS/ledger activation remediation
-
-- **Choice:** `mosaic-db-migrator` is the sole application/CI/test PostgreSQL DDL control plane. Every legacy entrypoint is routed or denied, rejects `DATABASE_URL`-only before connection/DDL, and `db:push` is unavailable outside an allowlisted disposable developer target. The runner holds one `max:1` session with fixed `pg_try_advisory_lock(1297044289,1262636593)` across preflight through release.
-- **Exact ledger:** manifest v1 canonically serializes journal logical index/tag and SHA-256 of exact shipped migration bytes. It maps each observed ledger hash to one tuple; physical insertion order is non-normative, while missing/unknown/duplicate/ambiguous/corrupt/stale states fail closed. Shipped `0009` bytes remain unchanged; a missing/effects-absent `0009` runs normally, an applied-late hash maps normally, and partial/full effects with missing hash require backup restoration or separately reviewed repair—not manual adoption.
-- **TLS/search path:** operator/IaC owns CA and server leaf lifecycle, exact compose/Swarm secret mounts, server TLS activation, service-DNS SANs, verified-TLS readiness, transition, CA overlap rotation, and rollback. Runtime/migrator use `verify-full`; PGlite is not PostgreSQL TLS evidence. Application sessions use only `pg_catalog,mosaic`; no URL/config-derived identifier reaches SQL.
-- **Safe release:** cards 00–07 land prepared but inactive; owner-runtime deployments remain N-1. Mosaic control plane/Jason alone authorizes one atomic TLS/roles → runner → readiness → runtime activation or rollback. No runtime-operator compatibility switch, bypass, plaintext interval, or force-on-red exists; all temporary support is removed before KBN-101-08.
-- **Non-effect:** role graph, immutable certification after KBN-100, KBN-105 gate, rc.5’s preserved rc.4 SI-001 invariants, and all KCR-001–016 decisions remain unchanged. Exact detail is normative in [`KBN-101-DB-ROLE-SPLIT.md`](./KBN-101-DB-ROLE-SPLIT.md).
-
-### 1.0.0-rc.5 — KBN-101 role/connection split
-
-- **Choice:** PostgreSQL `standalone` and `federated` runtime uses `DATABASE_URL` only as a non-owner `mosaic_runtime` login; an explicit migration phase uses `DATABASE_MIGRATION_URL` only as `mosaic_migrator`, which `SET ROLE`s to non-login `mosaic_schema_owner` for DDL. Local PGlite remains an explicit embedded exception.
-- **No fallback / no startup DDL:** missing migration URL fails the migration phase; it never falls back to runtime URL/default/config. Gateway replicas do not run migrations. An advisory-locked migration phase verifies the exact ordered Drizzle ledger fingerprint before replicas may become ready.
-- **Privilege model:** non-login `mosaic_platform_database_owner` is outside application paths; `mosaic_schema_owner` owns only application/ledger schemas. `mosaic_runtime` has only `mosaic_runtime_capability`, owns no object/schema, cannot assume owner/migrator, has no TEMPORARY privilege, has only read access to the Drizzle ledger, and must fail startup if effective identity, unsafe attributes, authenticated TLS, search path, schema version, grants, or immutable relation privileges differ from the frozen contract. `task_events`, `artifacts`, `task_checkpoints`, `task_checkpoint_artifacts`, and `approval_decision_artifacts` grant runtime only INSERT/SELECT; KBN-100 retains RESTRICT/no-cascade semantics.
-- **Non-effect:** rc.4 SI-001 candidate-key/FK order and all KCR-001–016 tenancy, SOT, proposal-audit, approval, fence, recovery, no-cascade, endpoint, and wire invariants are unchanged. This amendment neither creates roles/secrets nor changes production deployment.
-- **Gate:** KBN-101’s role/schema-boundary foundation certificate, Vault/redaction/rotation, N-1/rollback, and independent security GO are mandatory before KBN-100. After KBN-100 creates the immutable relations, KBN-101 real deployed-role immutable-operation certification plus Ultron GO is mandatory before KBN-105; synthetic test-role success alone is insufficient. Exact implementation detail is normative in [`KBN-101-DB-ROLE-SPLIT.md`](./KBN-101-DB-ROLE-SPLIT.md).
-
-### 1.0.0-rc.4 — KBN010-SI-001 (preserved)
 
 - **Choice:** add the explicitly named, non-partial unique candidate key `missions_workspace_id_uidx` on `missions(workspace_id, id)` and retain `missions_workspace_project_id_uidx` on `(workspace_id, project_id, id)`.
 - **Rationale:** mission `id` remains globally unique, while the composite candidate key makes the frozen tenant-safe generic mission relations valid. `artifacts` and `approval_decisions` are polymorphic exactly-one-target records and do not consistently carry `project_id`; widening both children would unnecessarily broaden v1 and its target semantics.
@@ -70,7 +19,7 @@
 
 ## 1. Authority
 
-Concrete contracts are the four `contracts/*.v1.ts` files. PostgreSQL/current-main Drizzle is the sole writable SOT. In PostgreSQL standalone/federated deployments, KBN-101 rc.11 DDL/ledger/TLS/role/attestation separation is a precondition to schema implementation and certification. Public health, Valkey, files, exports, providers, browser state, and outage notes cannot authorize/reconstruct writes. Mechanical Coordinator is non-LLM with no scope/gate/certification/merge authority. Certifier is final independent gate with no merge authority. No feature lane starts until this canon merges and the KBN-010/KBN-105 prerequisites are satisfied.
+Concrete contracts are the four `contracts/*.v1.ts` files. PostgreSQL/current-main Drizzle is the sole writable SOT. Public health, Valkey, files, exports, providers, browser state, and outage notes cannot authorize/reconstruct writes. Mechanical Coordinator is non-LLM with no scope/gate/certification/merge authority. Certifier is final independent gate with no merge authority. No feature lane starts until this canon merges and the KBN-010/KBN-105 prerequisites are satisfied.
 
 ## 2. Health proof and exact failures
 
@@ -155,7 +104,7 @@ The candidate key is intentionally redundant with globally unique `missions.id`,
 
 ### 5.3 New audit/proposal DDL order
 
-KBN-100 migration DDL may begin only after KBN-101 foundation role/schema-boundary certification. It runs in the explicit migrator/owner phase—not Gateway startup—and its generated Drizzle declaration/snapshot/journal must be mutually consistent. It must execute in this order:
+KBN-100 migration DDL must execute in this order:
 
 1. create `task_events` and its unique `(workspace_id, id)` key;
 2. create `change_proposals` with nullable acceptance-event ID and required submission-event ID;
@@ -294,7 +243,7 @@ KBN-115/coder2 owns `packages/config/src/recovery-posture.ts`, tests, and recove
 
 ## 9. Integration, security, and hold
 
-Required release evidence includes KBN-101 foundation role/schema-boundary and post-KBN-100 real immutable-operation deployed-role certificates (not synthetic roles), empty/prod/partial/rollback/N-1 migration tests; cross-workspace and same-workspace wrong-project negatives; active-membership owners/principals; proposal inertness/normal acceptance; exact failure mapping; concurrent monotonic bigint fences; relational lease/checkpoint/evidence mismatch; immutability privileges/RESTRICT; recovery validation/mechanism evidence; endpoint registry alignment; accessible web journeys; author≠reviewer; mandatory SecReview; final Certifier pass/no merge authority.
+Required release evidence includes empty/prod/partial/rollback/N-1 migration tests; cross-workspace and same-workspace wrong-project negatives; active-membership owners/principals; proposal inertness/normal acceptance; exact failure mapping; concurrent monotonic bigint fences; relational lease/checkpoint/evidence mismatch; immutability privileges/RESTRICT; recovery validation/mechanism evidence; endpoint registry alignment; accessible web journeys; author≠reviewer; mandatory SecReview; final Certifier pass/no merge authority.
 
 ### 9.1 SI-001 amendment gate and #757 boundary
 

docs/native-kanban-sot/TASKS.md

@@ -43,14 +43,12 @@ Shared roots, package exports/manifests, lockfiles, and generated artifacts are
 ```text
 KBN-000 canon remediation
   -> KBN-010 threat/auth/constraint-impact gate (MUST COMPLETE)
-      -> KBN-101 foundation role/schema-boundary certificate (SERIAL)
+      -> KBN-100 schema + concrete N-1 migration implementation
-          -> KBN-100 schema + concrete N-1 migration implementation
+          ├─ KBN-105 exact endpoint/DTO/error/registry freeze (SERIAL)
-              ├─ KBN-101 post-KBN-100 deployed-role immutable-operation certificate (SERIAL)
+          │    ├─ KBN-110 domain + Gateway + MCP server implementation
-              │    -> KBN-105 exact endpoint/DTO/error/registry freeze (SERIAL)
+          │    ├─ KBN-120 CLI/projection implementation [coder4 first]
-              │        ├─ KBN-110 domain + Gateway + MCP server implementation
+          │    └─ KBN-130 web MVP implementation
-              │        ├─ KBN-120 CLI/projection implementation [coder4 first]
+          └─ KBN-115 recovery parser/mechanism slice [coder2 lane-serial]
-              │        └─ KBN-130 web MVP implementation
-              └─ KBN-115 recovery parser/mechanism slice [coder2 lane-serial]
 KBN-110 + KBN-120 + KBN-130 + KBN-115
   -> KBN-140 P1 integration/SIT
       -> KBN-200 pure decision engine [coder4 after KBN-120]
@@ -66,7 +64,7 @@ KBN-310 + KBN-320
       -> KBN-340 owner-gated cutover/stabilization
 ```
 
-No consumer implementation begins before KBN-105. No schema work begins before KBN-010 completes and the KBN-101 foundation role/schema-boundary certificate passes; the real immutable-operation certificate follows KBN-100 and blocks KBN-105. The coder4 order is always KBN-120 → KBN-200 → KBN-300 → KBN-320.
+No consumer implementation begins before KBN-105. No schema work begins before KBN-010 completes. The coder4 order is always KBN-120 → KBN-200 → KBN-300 → KBN-320.
 
 ## 4. P0 — Canon, threat gate, schema, and exact API freeze
 
@@ -83,9 +81,9 @@ No consumer implementation begins before KBN-105. No schema work begins before K
 
 ### KBN-010 — Threat, authorization, and constraint-impact gate
 
-- **Status:** IN PROGRESS — issue [#753](https://git.mosaicstack.dev/mosaicstack/stack/issues/753).
+- **Status:** COMPLETE — PR #765 squash-merged as `2e228007`; issue #753 closed; post-merge pipeline #1813 terminal success.
-- **Owner:** `kbn-coder3`; independent `secrev`.
+- **Owner:** `kbn-coder3`; independent Homelab schema/SecReview and `web1:coder0` Codex-Ultron review.
-- **Mode:** SERIAL prerequisite of KBN-100.
+- **Mode:** SERIAL prerequisite of KBN-100; completed.
 - **Exclusive files:** `docs/native-kanban-sot/KBN-010-THREAT-AUTH-CONSTRAINT-GATE.md` and task scratchpad only.
 - **IN:** Cross-workspace owners/principals/evidence; active membership; stale/forged health; approval forgery; fence monotonicity; audit retention; proposal target/audit-event forgery; service tokens; DB/Valkey outage.
 - **OUT:** Runtime/schema edits.
@@ -93,27 +91,17 @@ No consumer implementation begins before KBN-105. No schema work begins before K
 - **Contract surfaces:** schema constraints, health proof, exact errors, command-family authorization.
 - **Evidence:** signed constraint-impact matrix; no unresolved schema-impact finding; SecReview pass.
 
-### KBN-101 — PostgreSQL runtime/migration role split and deployed-role certification
-
-- **Status:** IN PROGRESS — issue [#771](https://git.mosaicstack.dev/mosaicstack/stack/issues/771); rc.11 closes the two exact-head re-review HIGH findings: trusted runner-produced target-bound Ed25519 importer attestation and complete finite operator-document disposition including the user guide. It awaits independent exact-head re-review; implementation remains held.
-- **Owner:** Mos integration control plane; independently reviewed by security/Ultron.
-- **Mode:** SERIAL foundation certificate blocks KBN-100; its post-KBN-100 real immutable-operation certificate blocks KBN-105.
-- **IN:** Exact `DATABASE_URL` non-owner runtime versus `DATABASE_MIGRATION_URL` owner/migrator connection contract; sole published `mosaic-db-migrator --run|--verify` PostgreSQL DDL path and all legacy/future entrypoint closure; active migrate-tier destination only after runner prepare/verify through exact `--target-url-file /run/secrets/mosaic_migrate_target_url` plus signed `--target-attestation-file /run/mosaic-attestations/migrate-target.v1.json`, runner-only signing key/public-key isolation, target secret/TLS/CA/server/database/role/manifest/schema binding, expiry/replay/rotation/TOCTOU/no-DML controls, and dedicated non-DDL importer; finite exact-path scanner/allowlist/active-route review and every-path before-connect denial matrix; `DATABASE_TLS_CA_CERT_PATH` plus operator/IaC CA/server-key/cert lifecycle, exact service-DNS SANs, Vault/compose/Swarm mount modes, TLS server/bootstrap/rotation/rollback; PGlite exception; fixed two-int advisory lock; manifest-v1 logical-index/tag/exact-byte-SHA-256 ledger reconciliation including safe `0009`; fixed `mosaic` schema and exact `pg_catalog,mosaic` pooled session path; platform/schema/`NOLOGIN SUPERUSER` extension-owner/migrator/importer/runtime roles; approved-owner versus legacy-owner shadow pgvector transition; ownership, zero membership/no runtime secret, TEMP/ledger-read/default privilege and immutable grant proof; N-1 inactive prepared cards then atomic activation/rollback authority; Vault/redaction/observability/operator runbooks; one-card/one-PR implementation DAG.
-- **OUT:** Production mutation in this planning card; KBN-100 tables/data backfill; application API behavior; KBN-105 route/DTO freeze.
-- **Depends on:** KBN-010 completed.
-- **Contract surfaces:** [`KBN-101-DB-ROLE-SPLIT.md`](./KBN-101-DB-ROLE-SPLIT.md); `SHARED-CONTRACT.md` rc.11 amendment.
-- **Evidence:** foundation: exact `--help|--run|--verify`/exit/argv/import-negative plus DTO entrypoint negatives for every finite classified current DDL/static-bypass path (including `DATABASE_URL`-only, runner fixture, retired init, sanitized current operator guidance, both harness pairs, and `db:push` refusal); active migrate-tier paired URL-file/attestation-file, signing/public-key isolation, atomic JCS/Ed25519, secret-version/digest/TLS/CA/server/database/role/manifest/schema binding, expiry/replay/rotation/TOCTOU, zero-connection versus zero-DML, prepared-target/importer/no-DDL negatives; clean/pre-0009/skipped/applied-late/duplicate/unknown/missing/corrupt/stale/backup plus public-to-`mosaic`/partial/reverse runner proof; fixed-lock contention/crash/readiness/unrelated-key tests; runtime cannot invoke migrations/DDL/TEMP; actual pgvector 0.8.2 control metadata, fresh/approved-owner existing/legacy-owner shadow/partial-resume-rollback/N-1 pgvector evidence with `rolcanlogin=false`, `rolsuper=true`, zero members, external-superuser `SET ROLE`/`RESET ROLE` audit, `pg_extension.extowner`, owner-bearing member/schema/version and runtime/migrator/schema-owner/importer/all-service-role `SET ROLE`/ALTER/DROP/member-update denial; disposable standalone, federated/Swarm, and two-gateway verified-TLS positives plus both-pair CA/SAN/downgrade/key mode/UID-GID/URL-secret consumer-isolation and legacy-drain/`hostssl` zero-plaintext negatives; exclusive bootstrap/renderer/manifest ownership test; catalog relocation/vector-query/operator/Drizzle-only-`mosaic`, role/grant/search-path/pool-reset/identifier checks; N-1/atomic TLS-only rollback/no-force-on-red rehearsal; named Vault/bootstrap-control-plane/CA-overlap/redaction/operator evidence; independent author≠reviewer security GO. Post-KBN-100: real deployed non-owner INSERT/SELECT and UPDATE/DELETE denial for immutable event/artifact/evidence relations plus Ultron GO.
-
 ### KBN-100 — Unified Drizzle schema and concrete N-1 migration
 
-- **Owner:** **coder2**.
+- **Status:** IN PROGRESS — issue [#769](https://git.mosaicstack.dev/mosaicstack/stack/issues/769); implementation held until tracking commit and baseline evidence are pushed.
+- **Owner:** **`web1:kbn-schema-coder2`** author lane; independent DB reviewer, SecReview, and Codex-Ultron required.
 - **Mode:** SERIAL.
 - **Exclusive files:** `packages/db/src/schema.ts`, `packages/db/drizzle/**`, DB tests.
 - **IN:** All frozen tables/joins/enums; workspace/project-congruent constraints; owners/principals; tags/archive; change proposals with both workspace-aware task-event composite FKs and frozen event-before-proposal DDL order; assignment approvals; durable execution/quarantine; monotonic bigint fence; exact checkpoint/evidence joins; RESTRICT/immutability; concrete current-main expand/backfill/switch/contract map.
 - **OUT:** Repositories, Gateway, Coordinator behavior, UI, importer.
-- **Depends on:** **KBN-010 completed and KBN-101 foundation role/schema-boundary certificate PASS**. KBN-100 is blocked until both are terminal; it rebases on KBN-101 main, restores generated Drizzle declaration/snapshot/journal consistency, and confines procedural immutable-table grant/trigger/backfill work to its schema ownership. Its new relations are then subject to KBN-101 post-KBN-100 deployed-role certification.
+- **Depends on:** **KBN-010 completed**.
 - **Contract surfaces:** `kanban-schema.v1.ts`; SHARED-CONTRACT current-main delta map.
-- **Evidence:** reviewed SQL; empty/prod-shape/partial-resume/rollback tests; N-1 app safety; legacy columns remain declared; workspace/project mismatch negatives; proposal event-FK missing/foreign-workspace tests; one active lease; monotonic fence; parent-delete RESTRICT; immutability privileges; SecReview.
+- **Evidence:** TDD RED/GREEN; reviewed generated SQL/journal; real PostgreSQL empty/prod-shape/partial-resume/rollback tests; N-1 startup/read/write safety; legacy columns remain declared; workspace/project mismatch negatives; N100-01..50 including rc.4 candidate-before-FK and two-child foreign-workspace tests; proposal event-FK missing/foreign/unrelated tests; one active lease; monotonic fence; parent-delete RESTRICT; immutability privileges; independent DB review, SecReview, Codex-Ultron, terminal-green PR/main CI.
 
 ### KBN-105 — Exact Gateway/MCP endpoint, DTO, and error freeze
 
@@ -122,7 +110,7 @@ No consumer implementation begins before KBN-105. No schema work begins before K
 - **Exclusive files:** canonical endpoint-registry/DTO contract docs; no implementation.
 - **IN:** Exact routes and methods from SHARED-CONTRACT §8; request/success/error fields; status codes; pagination/filter/revision envelopes; idempotency/expected-version headers/fields; proposal commands; health proof exclusion from public DTOs; MCP tool-to-route map.
 - **OUT:** Controller/service/client implementation.
-- **Depends on:** KBN-100 and KBN-101 post-KBN-100 deployed-role immutable-operation certification PASS.
+- **Depends on:** KBN-100.
 - **Contract surfaces:** health/error unions; schema IDs/statuses; Gateway DTO freeze.
 - **Evidence:** every FE/CLI/MCP call maps 1:1 to a route; 503/502-504/409 non-cross-map fixtures; contract digest published.
 
@@ -264,15 +252,13 @@ No consumer implementation begins before KBN-105. No schema work begins before K
 
 ## 8. Consistent USC wave schedule
 
-| Wave | coder2                                    | coder3                                                                               | coder4                         | coder5                         |
+| Wave | coder2                    | coder3                                 | coder4                         | coder5                         |
-| ---- | ----------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------ | ------------------------------ |
+| ---- | ------------------------- | -------------------------------------- | ------------------------------ | ------------------------------ |
-| 0    | Wait                                      | **KBN-010**                                                                          | Wait                           | Wait                           |
+| 0    | Wait                      | **KBN-010**                            | Wait                           | Wait                           |
-| 0.5  | Wait                                      | **KBN-101 foundation** Mos-controlled role/connection contract and certificate       | Wait                           | Wait                           |
+| 1    | **KBN-100**               | Review constraint implementation       | Wait                           | Wait                           |
-| 1    | **KBN-100** after KBN-101 foundation PASS | Review bounded schema/grant implementation                                           | Wait                           | Wait                           |
+| 2    | **KBN-115** after KBN-100 | **KBN-105** exact freeze, then KBN-110 | **KBN-120** only after KBN-105 | **KBN-130** only after KBN-105 |
-| 1.5  | Certification support                     | **KBN-101 post-KBN-100 deployed-role immutable-operation certificate**, then KBN-105 | Wait                           | Wait                           |
+| 3    | Review support            | Finish KBN-110                         | **KBN-200 after KBN-120**      | Finish KBN-130                 |
-| 2    | **KBN-115** after KBN-100                 | **KBN-105** exact freeze, then KBN-110                                               | **KBN-120** only after KBN-105 | **KBN-130** only after KBN-105 |
+| 4    | —                         | **KBN-210 after KBN-200**              | Review/support                 | **KBN-220 after KBN-210 DTOs** |
-| 3    | Review support                            | Finish KBN-110                                                                       | **KBN-200 after KBN-120**      | Finish KBN-130                 |
+| 5    | —                         | P2 remediation                         | **KBN-300 then KBN-320**       | **KBN-310**                    |
-| 4    | —                                         | **KBN-210 after KBN-200**                                                            | Review/support                 | **KBN-220 after KBN-210 DTOs** |
-| 5    | —                                         | P2 remediation                                                                       | **KBN-300 then KBN-320**       | **KBN-310**                    |
 
 Mos alone releases slices and lifts the build hold after independent re-review GO.

docs/plans/2026-03-15-agent-platform-architecture.md

@@ -1464,11 +1464,9 @@ Generate and apply:
 
 ```bash
 pnpm --filter @mosaicstack/db db:generate  # generates migration SQL
-mosaic-db-migrator --run                   # sole PostgreSQL migration runner
+pnpm --filter @mosaicstack/db db:migrate   # applies to PG
 ```
 
-> **KBN-101 supersession:** `pnpm --filter @mosaicstack/db db:migrate` is superseded and MUST NOT be used. The runner receives only deployment-injected migration credentials; it accepts no URL, SQL, schema, or role argv.
-
 Platform enforcement keys (seeded with `mutable = false` by gateway `PreferencesService.onModuleInit()`):
 
 | Key                       | Category | Reason                                    |

docs/reports/native-kanban-sot/kbn-101-contract-security-review-82ce325.md

@@ -1,109 +0,0 @@
-# KBN-101 contract independent security/architecture review
-
-**Verdict: REQUEST CHANGES**
-
-## Review identity and scope
-
-- **Exact reviewed head:** `da742ca2da4a2ff466916c818fe275c4f7ffd384` (`docs(#771): record role-split review evidence`)
-- **Required comparison:** `origin/main...da742ca2da4a2ff466916c818fe275c4f7ffd384`
-- **Range:** `82ce3252df38a687c50485f8d048b53ca8db5989` is an ancestor of the reviewed head; the final head adds the scratchpad evidence commit and was reviewed.
-- **Changed docs:** `docs/PRD.md`, `docs/SITEMAP.md`, `docs/native-kanban-sot/{INDEX.md,KBN-101-DB-ROLE-SPLIT.md,SHARED-CONTRACT.md,TASKS.md}`, and `docs/scratchpads/771-kbn101-db-role-split.md` (300 additions / 25 deletions).
-- **Reviewed inputs:** issue #771; current DB/Gateway/storage/config/wizard/installer/compose/Portainer/CI sources; all current migration/DDL references; KBN-010, rc.4/rc.5 shared contract, requirements/canon, KBN-100 #769 branch context, and the final scratchpad.
-- **Repository/provider state:** not modified. The pre-existing `.mosaic/orchestrator/*` dirt was not touched.
-
-The role graph itself is sound in principle: a NOLOGIN platform database owner, separate NOLOGIN schema owner, NOINHERIT migrator which explicitly `SET ROLE`s, and runtime membership only in a capability role with `SET FALSE` does not create circular privilege or application-created login roles. The split of foundation certification before KBN-100 and immutable-operation certification after KBN-100 is also correctly ordered.
-
-## Findings
-
-### HIGH — DDL/migration control plane is not closed at every current entrypoint
-
-The contract requires an explicit, locked migration phase and forbids Gateway/runtime DDL (`KBN-101-DB-ROLE-SPLIT.md:34-39`), but its KBN-101-02 result merely says migration-capable commands use the migration DTO (`:109`). It does not prohibit or route every existing bypass through that one command.
-
-Current bypasses include:
-
-- `runMigrations()` falls back from an argument to `DATABASE_URL` and a hard-coded URL (`packages/db/src/migrate.ts:24-35`), while `drizzle.config.ts` likewise uses `DATABASE_URL` plus a default (`packages/db/drizzle.config.ts:3-9`).
-- Package scripts expose direct `drizzle-kit migrate` **and** `drizzle-kit push` (`packages/db/package.json:23-26`); `db:push` bypasses the planned journal/fingerprint/lock entirely.
-- `mosaic storage migrate --run` shells out to the direct `db:migrate` script (`packages/storage/src/cli.ts:413-452`).
-- The federated integration test can create types, tables, and indexes directly against `DATABASE_URL` and intentionally operates without a Drizzle ledger (`packages/db/src/federation.integration.test.ts:28-30,46-134`).
-
-**Failure mode:** a runtime or CI environment with only `DATABASE_URL`, or an operator invoking an existing command, can apply unverified DDL outside the lock, `SET ROLE` preflight, exact-ledger gate, and deployment sequencing. This breaks the requested fail-closed split even if Gateway startup is repaired.
-
-**Required remediation:** amend KBN-101-02/03/06 to enumerate these entrypoints and make the dedicated migrator runner the only PostgreSQL DDL path. Production-like `db:push` must be removed/blocked; `db:migrate`, `storage migrate --run`, and migration tests must invoke the same migration runner with `DATABASE_MIGRATION_URL`, lock, identity preflight, and ledger verification. Tests needing schema must consume a pre-migrated disposable database, or be explicitly run only by that migration phase. Add negative tests showing each command refuses `DATABASE_URL`-only execution and cannot reach DDL.
-
-### HIGH — TLS requirement has no deployable server/bootstrap contract
-
-The contract correctly requires a mounted CA and hostname-verified TLS (`KBN-101-DB-ROLE-SPLIT.md:25,28,93-95`). However KBN-101-05 promises only a “migration phase and secret binding boundary” (`:112`), not PostgreSQL server TLS, certificate issuance/SANs, CA distribution, startup ordering, or the fresh/existing-database bootstrap trust path.
-
-Current standalone and federated compose expose plain PostgreSQL with no server TLS configuration or CA mount (`docker-compose.yml:2-14`; `docker-compose.federated.yml:27-44`). The Portainer test stack passes a single plaintext in-network URL and uses the same database login for Gateway and database bootstrap (`deploy/portainer/federated-test.stack.yml:51-60,110-117`).
-
-**Failure mode:** enforcing the mandatory CA makes current local standalone/federated topologies unable to start; relaxing it to make bootstrap work silently violates K101-REQ-03. A first database cannot be safely migrated until the server certificate, its SAN for the actual service/DNS name, and trusted CA are provisioned, but this lifecycle is not owned or tested.
-
-**Required remediation:** add a concrete KBN-101-00/05 TLS bootstrap sub-contract: issuer/CA owner; server key/cert and SAN inputs; secure storage/mount permissions; `postgresql.conf`/container TLS enablement; migration and runtime CA mounts; hostname used by each compose/Swarm service; readiness only after TLS authentication; CA overlap rotation; and an existing-database transition. Require a disposable standalone and federated/Swarm test to prove verified TLS succeeds and missing CA, wrong CA, wrong SAN, and `sslmode` downgrade fail before readiness. Do not merge KBN-101-05 with an implicit plaintext exception.
-
-### HIGH — exact ledger fingerprint and historical 0009 repair are underspecified for existing databases
-
-The contract requires an “ordered complete set” and rejection of out-of-order rows (`KBN-101-DB-ROLE-SPLIT.md:36-38`), but does not define the canonical serialized tuple, ledger ordering source, or safe upgrade rule for a historical ledger. The current ledger stores only `id`, `hash`, and `created_at` (`packages/db/src/migrate.ts:70-82,105-107`). Its journal is demonstrably non-monotonic: `0008` has `when=1776822435828`, followed by `0009` at `1745280000000` (`packages/db/drizzle/meta/_journal.json:62-79`); the existing PostgreSQL runner documents that this causes skipping (`packages/db/src/migrate.ts:29-35`).
-
-**Failure mode:** an implementation can either reject a legitimate historical database after correcting 0009, or accept a reordered/duplicated ledger because no precise comparison rule exists. A count/hash-set implementation would fail to detect the condition that this contract explicitly calls unsafe; physical `id` order is not an adequate substitute after historical repair.
-
-**Required remediation:** freeze a versioned manifest algorithm before implementation: canonical record fields (at least journal index/tag, corrected logical order, migration content hash, and an explicit migration-manifest version), canonical byte serialization, SHA-256 input, and exact observed-ledger mapping. State whether physical ledger insertion order is normative; if not, compare hash-to-manifest tuples rather than timestamps. Add an idempotent migrator-only 0009 existing-database remediation/reconciliation procedure with backup/rollback evidence. Require clean, pre-0009, 0009-skipped, 0009-applied-late, duplicate, unknown, missing, corrupt-pair, and stale-replica cases. No manual ledger insertion is an acceptable production recovery path.
-
-### MEDIUM — advisory-lock namespace is collision-prone and lacks a fixed identifier contract
-
-The specified lock is `pg_try_advisory_lock(hashtext('mosaic-schema-migration-v1'))` (`KBN-101-DB-ROLE-SPLIT.md:34`). `hashtext` produces a 32-bit key. Session ownership/crash behavior is otherwise correctly stated (one session, same-session release, connection-close release), but an unrelated database user can accidentally collide or deliberately hold the key and force `DATABASE_MIGRATION_LOCKED`.
-
-**Failure mode:** avoidable migration denial of service in a shared PostgreSQL database. The current repository already uses separate `hashtext` advisory-lock names for migrate-tier, demonstrating the need for a documented namespace rather than a collision-prone implicit one.
-
-**Required remediation:** freeze a two-int advisory-lock namespace (fixed documented class/object values) or a documented 64-bit `hashtextextended` key with fixed seed; keep acquisition, migration, verification, and release on the single `max:1` migrator session. Add tests for concurrent migration, connection loss/crash release, readiness while the lock holder is active, and an unrelated lock-key non-interference case.
-
-### MEDIUM — identifier safety and `search_path` verification need executable constraints
-
-The contract rightly requires `pg_catalog, <mosaic_application_schema>` and rejects writable paths (`KBN-101-DB-ROLE-SPLIT.md:54,70-77`), but uses dynamic placeholders for database/schema and does not state how migration/bootstrap SQL will avoid identifier interpolation. Existing code has raw-SQL facilities (`packages/storage/src/migrate-tier.ts` uses `.unsafe`), so this is not merely theoretical.
-
-**Failure mode:** a future operator-configured database/schema value that reaches bootstrap or `SET search_path` through raw string construction can inject DDL, or a pooled connection can retain a mutable search path.
-
-**Required remediation:** require fixed allowlisted identifiers or server-side identifier quoting (`format('%I', ...)`) only; never interpolate URL/config values into SQL. Set and verify the trusted path per connection/session before any query (`SET LOCAL` inside transactions where applicable), forbid `public`/`$user` additions, and add injection-shaped identifier and pooled-connection reset negatives. Include this in KBN-101-00/01 tests.
-
-## Acceptance and threat traceability
-
-| Requirement / threat | Review result | Evidence or blocking finding |
-| --- | --- | --- |
-| K101-REQ-01 / AC-K101-01 split runtime/migration URLs | Partial | Role/DTO boundary is coherent; HIGH DDL-path finding requires all current commands to be closed. |
-| K101-REQ-02 / AC-K101-02 explicit migration/readiness | Blocked | HIGH ledger definition and HIGH DDL-bypass findings. |
-| K101-REQ-03 / AC-K101-03 least privilege, TLS, grants | Partial | Role model, default privileges, ledger read-only, TEMP/function checks are well specified (`KBN-101...:47-56,70-79`); HIGH TLS bootstrap and MEDIUM identifier constraints remain. |
-| K101-REQ-04 / AC-K101-04 immutable relations | Correctly deferred | KBN-101-09 after KBN-100 is the correct serial gate (`KBN-101...:58-66,115-118`); no synthetic-only certification claim found. |
-| K101-REQ-05 / AC-K101-05 N-1, secrets, rollback | Partial | No owner-runtime exception and rollback keeps migration URL out of Gateway (`:83-95`); deployable TLS and full command inventory are missing. |
-| K101-REQ-06 / AC-K101-07 KBN gates and DAG | Structurally sound | DAG is acyclic: 00→01/{03}; 02→06; 00/01/03→05; 00/04/05/06→07→08→KBN-100→09→KBN-105. KBN-100’s current branch contains docs-only baseline tracking, not schema implementation. |
-| T: runtime DDL / migration fallback | Blocked | HIGH finding 1. Current Gateway/storage, CLI, direct Drizzle scripts, and integration DDL require explicit closure. |
-| T: race/crash/readiness | Partial | Same-session nonblocking lock and replica-unready rules are present (`:34-38`); lock namespace remediation required. |
-| T: immutable evidence rewrite | Correctly staged | Explicit INSERT/SELECT-only matrix and RESTRICT retention are retained; proof is properly after table creation. |
-| T: secret leakage / TLS downgrade | Partial | Redaction and distinct Vault paths are specified (`:93-97`), but no server TLS/bootstrap implementation contract exists. |
-
-## Unresolved assumptions
-
-1. `standalone` and `federated` are the complete PostgreSQL production-like set (K101-A1).
-2. Each eligible deployment can execute a dedicated migration Job/one-shot phase (K101-A2).
-3. Vault path names are targets, not verified existing paths; deployment ownership remains to be established.
-4. PostgreSQL 17 is available for the selected membership and advisory-lock implementation.
-5. The required server-side TLS issuer/certificate lifecycle and Swarm/compose secret transport have not been decided; this is blocking, not a permissible implicit plaintext bootstrap.
-6. Historical databases containing the 0009 journal/ledger anomaly have no frozen reconciliation procedure.
-
-## Independent test and consistency evidence
-
-Read-only checks run in this review:
-
-| Check | Result |
-| --- | --- |
-| `git diff --check origin/main...da742ca2...` | PASS |
-| `pnpm exec prettier --check` on all seven changed docs | PASS |
-| `pnpm exec tsc --noEmit -p docs/native-kanban-sot/tsconfig.json` | PASS |
-| `docker compose -f docker-compose.yml config --quiet` (isolated test ports) | PASS |
-| `docker compose -f docker-compose.federated.yml --profile federated config --quiet` (isolated test ports) | PASS |
-| Static journal inspection | FAILS the required monotonic ordering premise: 0008 → 0009 `when` decreases; current runner documents skipping behavior. |
-| Static DDL-entrypoint inventory | Found direct Drizzle scripts, storage CLI shell-out, runtime extension/migration calls, fleet backlog migration, tier probe extension creation, and a direct-DLL federated integration test. |
-
-No live database, Vault, CI, deployment, issue, PR, or repository mutation was performed. The pass results validate documentation syntax/contract compilation and compose syntax only; they do **not** certify the proposed security behavior.
-
-## Conclusion
-
-Do not merge this frozen contract as implementation-ready until the HIGH findings are corrected and independently re-reviewed. The central role ownership/default-privilege design, immutable-table staging, and KBN-100/KBN-105 serial gating should be retained; they are not the reason for this REQUEST CHANGES verdict.

docs/scratchpads/755-mos-logical-identity-fencing.md

@@ -1,148 +0,0 @@
-# Issue #755 — Logical Mos identity and connector lease fencing
-
-- Task: `MOS-PORT-M1-001`
-- Branch: `feat/mos-logical-identity-fencing`
-- Base: `origin/main`
-- Started: 2026-07-14
-- Working budget: 38K tokens (task ledger estimate); one implementation lane, bounded to M1.
-
-## Objective
-
-Implement the first runtime-portability security boundary: normalized logical-agent identity plus a PostgreSQL-durable exclusive connector lease and server-validated fencing grants.
-
-## Scope
-
-- Normalized identity contract independent of harness/provider-native session IDs.
-- DB migration/schema/repository for one lease per tenant/logical-agent/binding.
-- CAS acquire/takeover, monotonic epoch, TTL, heartbeat, release, expiry handling.
-- Server-derived grants bound to tenant, logical agent, binding, connector, scopes, expiry, and lease epoch.
-- Reject and credential-safely audit stale, expired, forged, unauthorized, cross-tenant, and cross-binding grants before adapter side effects.
-- Runtime adapter boundary consumes normalized lease context.
-- Unit, migration, close/reopen, concurrency, abuse, and gateway integration tests.
-- Required developer/operations documentation for schema and security behavior.
-
-## Explicit exclusions
-
-No checkpoint/handoff payloads, exactly-once journal/receipts, concrete Claude/Pi/Codex harness adapter, channel cutover, or full cross-harness failover E2E.
-
-## Reconciliation baseline
-
-- Prospective remediation handoff: `web1:coder1`; PR [#757](https://git.mosaicstack.dev/mosaicstack/stack/pulls/757), issue [#755](https://git.mosaicstack.dev/mosaicstack/stack/issues/755).
-- Before rebase: `dff8ce4f79ef90370c29d925002118a708010091`; required base: `origin/main` at `2e2280070ae67288be45f41743cf67052a8ca5a6`; original branch base: `d0771835542deab048ad8e79f271e3abdb6151f7`.
-- Provider metadata: #757 is open, targets `main`, head is `feat/mos-logical-identity-fencing`, prior CI is green, and the provider reports it is not mergeable because of conflicts.
-- Affected delivery paths: `apps/gateway/src/agent/agent.module.ts`; connector-lease gateway repository/service and three focused tests; `packages/agent/src/connector-lease.ts` plus test/export; `packages/types/src/agent/connector-lease.dto.ts` plus test/export; `packages/db/src/schema.ts`, migration `0016_salty_morlocks.sql`, Drizzle snapshot/journal; `docs/PRD.md`, `docs/SITEMAP.md`, MOS architecture/operations pages, this scratchpad, and `docs/tess/TASKS.md`.
-- Read-only merge-tree inspection found only `docs/PRD.md` and `docs/SITEMAP.md` conflicts. Current-main #756 channel contracts, #758 roster-v2 structural compiler, and Native Kanban SOT use distinct contract domains; no substantive architecture collision was identified before mechanical reconciliation.
-- Reconciliation constraints: retain all current-main #752/#756/#758/KBN content; add only nonduplicative #755 references; do not alter semantics or conflate connector leases/grants with Kanban task leases/fences, local Fleet leases, auth sessions, ResetSession generations, or federation grants.
-
-## Plan (TDD RED → GREEN → REFACTOR)
-
-1. Map existing contracts, DB/migration conventions, gateway authorization/audit boundaries, and test infrastructure.
-2. Add failing contract/repository/concurrency/restart/abuse/gateway tests and capture RED evidence.
-3. Implement the smallest normalized contracts, schema/migration/repository, grant validator, audit sink, and gateway service/adapter boundary needed to pass.
-4. Refactor for clear invariants and credential-safe observability; rerun focused suites.
-5. Run package/repo typecheck, lint, format, and appropriate tests.
-6. Run independent code + security review, remediate, and re-review.
-7. Inspect the final diff for security/scope drift; commit; queue guard; push; open PR with `Refs #755` and exact verification; stop without merge/issue closure.
-
-## Constraints and safety notes
-
-- `docs/tess/TASKS.md` is orchestrator-only and will not be edited.
-- Existing dirty `.mosaic/orchestrator/mission.json` and `.mosaic/orchestrator/session.lock` are launcher/orchestrator state and will not be staged or altered intentionally.
-- No client-supplied identity may confer authority.
-- No credential, token, or raw grant material may be persisted to audit/log output.
-- Existing authorization checks remain intact; fencing is an additional fail-closed layer.
-
-## Assumptions resolved from existing architecture
-
-- `ASSUMPTION:` M1 exposes no public lease endpoint. The gateway service is an internal policy surface with deny-all default policy because concrete connector activation/cutover is explicitly deferred.
-- `ASSUMPTION:` Fencing epochs use PostgreSQL `bigint` and cross-module decimal strings, preserving JSON portability without JavaScript number precision loss.
-- `ASSUMPTION:` Process-local grant provenance intentionally fails closed across restart; durable lease/epoch state survives and fresh grants require current policy + lease validation.
-
-## TDD evidence
-
-RED observed before implementation:
-
-- `corepack pnpm --filter @mosaicstack/types exec vitest run src/agent/connector-lease.dto.spec.ts` → failed to load missing `connector-lease.dto.js`.
-- `corepack pnpm --filter @mosaicstack/agent exec vitest run src/connector-lease.test.ts` → failed to load missing `connector-lease.js`.
-- Gateway focused tests failed before implementation because the new repository/service boundaries did not exist (workspace dependencies were then built before behavioral GREEN runs).
-
-GREEN to date:
-
-- Types contract: 6/6 passed.
-- Agent grant/fencing unit suite: 5/5 passed.
-- Gateway PGlite repository + policy/side-effect integration: 7/7 passed; 1 real-PostgreSQL test skipped when `DATABASE_URL` absent.
-- Real PostgreSQL focused run with configured `DATABASE_URL`: 1/1 passed (credential value not emitted in reports).
-
-## Documentation checklist
-
-- [x] `docs/PRD.md` contains current MOS-PORT M1 scope and acceptance criteria.
-- [x] Developer architecture: `docs/architecture/mos-runtime-portability-m1.md`.
-- [x] Admin/operations guidance: `docs/guides/mos-connector-lease-operations.md`.
-- [x] `docs/SITEMAP.md` links both pages.
-- [x] No user-guide change: M1 exposes no user-facing flow or channel cutover.
-- [x] No OpenAPI/endpoint-index change: M1 adds no HTTP endpoint.
-- [x] Migration/restart/rollback safety and credential-safe audit constraints documented.
-- [x] Canonical source remains in-repo; no external publishing action is in scope.
-- [x] Independent review confirms documentation matches implementation; implementation-specific findings were remediated.
-
-## Independent review and remediation
-
-Codex code/security review ran in multiple rounds. Findings and root-cause remediations:
-
-1. Policy could not inspect requested scope/TTL → policy subject now receives normalized requested scopes and explicit requested TTL.
-2. Unbounded authority lifetime → hard defaults cap leases at 5 minutes and grants at 30 seconds; overrides may only tighten; over-limit tests added.
-3. Cross-tenant denial could audit under submitted tenant → mismatch audit uses authenticated tenant plus sanitized `untrusted` target metadata; integration assertion added.
-4. Malformed forged grant could break the denial/audit path → runtime-safe shape validation with sanitized fallback audit; malformed-input test added.
-5. Gateway integration test depended on prior test state → denial test now seeds a unique binding itself; isolated `-t` run passed.
-6. Reviewer repeatedly identified launcher-generated `.mosaic/orchestrator/*` state; those files remain unstaged and excluded from the implementation commit.
-
-Latest independent security review: no critical/high/medium/low findings. Final commit-level code review remains to run after the intended diff is committed without launcher state.
-
-## Verification evidence
-
-- Focused contracts/fencing: types 6/6; agent 9/9.
-- Gateway focused PGlite repository/policy integration: 7/7; isolated denial test 1/1.
-- Real PostgreSQL close/reopen/CAS test: 1/1 with configured `DATABASE_URL`.
-- Root `corepack pnpm typecheck`: 42/42 Turbo tasks passed.
-- Root `corepack pnpm lint`: 23/23 Turbo tasks passed.
-- Root `corepack pnpm format:check`: all matched files passed.
-- Root `corepack pnpm test`: 42/42 Turbo tasks passed; gateway 616 passed / 12 environment-gated skipped; DB 19 passed / 7 environment-gated skipped; Mosaic 650 passed.
-
-## Known residual risks
-
-- Concrete connector policies and Claude/Pi/Codex adapters are intentionally deferred; production policy defaults deny-all.
-- Gateway pre-side-effect validation cannot make an external system exactly-once. Adapters must propagate/enforce the epoch at downstream effect boundaries; receipts/journaling are later #754 scope.
-- Migration rollback is additive-only; dropping lease/audit tables is intentionally manual to avoid destroying authority/audit evidence.
-
-## Commit-level review remediation
-
-- Commit-level Codex code review found one `should-fix`: heartbeat, release, and grant issuance authorized caller-supplied lease fields before canonical normalization.
-- TDD RED: the isolated gateway policy-boundary test showed mixed-case/padded logical agent, binding, connector, scope, and epoch values reaching policy unchanged.
-- Remediation: exported the coordinator's canonical lease normalizer and applied it at the gateway boundary before tenant/policy checks and coordinator dispatch for heartbeat, release, and grant issuance.
-- GREEN: isolated policy test 1/1; focused types 6/6, agent 9/9, gateway 8/8; root typecheck 42/42, lint 23/23, format check passed, and root tests 42/42 (gateway 617 passed / 12 environment-gated skipped).
-- Commit-level security review remained clean: no critical/high/medium/low findings.
-
-## Durable grant-expiry review remediation
-
-- Final commit review found a second `should-fix`: grant expiry was capped against submitted lease metadata after current-authority validation, rather than the durable lease row.
-- TDD RED: a crafted same-authority lease with a later submitted expiry produced a grant expiring after the durable row.
-- Remediation: grant authority fields and expiry now derive from the durable current lease; submitted scopes remain an additional narrowing constraint.
-- GREEN: focused agent fencing suite 10/10.
-
-## Current-main reconciliation (2026-07-14)
-
-- Rebased the existing PR branch from `dff8ce4f79ef90370c29d925002118a708010091` (old base `d0771835542deab048ad8e79f271e3abdb6151f7`) onto `origin/main` `2e2280070ae67288be45f41743cf67052a8ca5a6`; current uncommitted reconciliation head is `d190732a550918161b91d3eb54640f4ea0e2e499`.
-- Resolved only `docs/PRD.md` and `docs/SITEMAP.md`: preserved current-main #752 Native Kanban, #756 official-channel, and #758 FCM material; retained the nonduplicative #755 M1 workstream and placed its two documentation links in the existing Runtime-neutral Mos section. No #755 source semantics changed.
-- Compatibility review confirmed separate authority domains: connector lease/epoch/grant remains distinct from KBN task leases/fences, local Fleet roster lifecycle, auth sessions, ResetSession context, and federation grants. No channel cutover, adapter activation, checkpoint/exactly-once behavior, UI convergence, or #754 expansion was added.
-- Focused verification after building the required workspace dependencies: types contract 6/6; agent fencing/grant 10/10; gateway repository/PGlite and policy integration 8/8. The focused real-PostgreSQL test was skipped because `DATABASE_URL` was not configured; no credentials were inspected or emitted.
-- Generated schema check: `pnpm --filter @mosaicstack/db db:generate` reported no schema changes; migration `0016_salty_morlocks`, snapshot, and journal were unchanged by generation.
-- Full verification: `pnpm typecheck` 42/42; `pnpm lint` 23/23; `pnpm format:check` passed; `pnpm test` 42/42 (gateway 627 passed / 12 environment-gated skipped). Scoped diff check and local documentation-link scan passed.
-- Pending only: commit this reconciliation record, queue guard, force-with-lease push of the rebased existing branch, then fresh independent DB/code/security review and Ultron. Do not claim merge or issue closure.
-
-## Durable lifecycle-authority remediation (2026-07-14)
-
-- Independent review found that heartbeat and release authorized the submitted lease, allowing forged lifecycle scope data to influence policy before the durable row was consulted.
-- Remediation: lifecycle operations tenant-check the submitted lease, load the durable current lease, compare tenant, logical agent, binding, lease UUID, connector, epoch, and canonical ordered scopes, audit and deny any absent/mismatched authority, then run policy and coordinator lifecycle calls with the durable lease. Coordinator CAS/fencing checks remain unchanged.
-- Adversarial gateway integration coverage proves forged `tool.execute` scopes on a durable `runtime.send` lease deny before policy or mutation, preserve heartbeat/release state, and write a denial audit for both lifecycle actions; canonical heartbeat and release remain accepted.
-- Verification: focused types 6/6; agent 10/10; gateway PGlite integration/repository 9/9 with one `DATABASE_URL`-gated PostgreSQL test skipped; Drizzle check passed; root typecheck 42/42; lint 23/23; format check passed; root test 42/42 (gateway 628 passed / 12 environment-gated skipped).
-- Pending: commit, queue-guard, force-with-lease push, then independent DB/code/security rereview and CI. Do not merge or close #755.

docs/scratchpads/758-fcm-m1-002-shared-role-resolution.md

@@ -1,148 +0,0 @@
-# FCM-M1-002 — Shared role resolution
-
-- **Task:** `FCM-M1-002`
-- **Issue:** `mosaicstack/stack#758`
-- **Branch:** `feat/758-shared-role-resolution`
-- **Starting head:** `32e75c67b094de443d37fe7d5ff8d25cdfc8b39d`
-- **Role:** implementation worker; independent review and merge remain outside this worker
-
-## Objective
-
-Reuse the existing baseline-plus-`roles.local` persona resolver as the sole class authority for roster-v2 semantics, profile validation, provisioning, and launch/persona resolution. Add exact approved alias canonicalization, fail-closed semantic validation, immutable canonical-class authority contracts, required baseline roles, and operator documentation without implementing lifecycle, mutation, credentials, certificate workflow, or later FCM cards.
-
-## Budget
-
-- Soft budget: **25K tokens**.
-- Strategy: inspect once, implement in small TDD units, run focused suites before the full package gate, and avoid unrelated refactors or M1-003/M2/M4 scope.
-
-## Plan
-
-1. Map the existing persona resolver, roster-v2 compiler, profile/provision consumers, launch resolution, role library, and focused tests.
-2. Write denial/invariant tests first for aliases, canonicalization-before-override, unreadable roles, authority boundaries, policy mismatch, canonical provision output, and resolver parity.
-3. Run the focused suites and record the expected red evidence.
-4. Implement one shared canonical resolution and authority contract in/through `fleet-personas.ts`; delegate roster semantic validation and profile/provision paths to it.
-5. Add baseline `validator`, `team-leader`, and `interaction` role contracts plus `LIBRARY.md` entries while retaining `operator-interaction` compatibility.
-6. Add the required role reference, alias migration, customization guide, and roster-v2 semantic handoff documentation.
-7. Run focused tests, the full `@mosaicstack/mosaic` suite, typecheck, lint, Prettier, `git diff --check`, situational verification, independent code/security review, and remediation.
-8. Commit with the required co-author trailer, run the CI queue guard, push the existing branch, and create/update exactly one PR to `main` with `Refs #758`.
-
-## TDD evidence
-
-### Red
-
-After installing worktree-local dependencies and building `@mosaicstack/db`, the pre-implementation
-focused run collected the intended tests and failed as expected:
-
-```text
-2 test files failed; 32 tests failed; 32 tests passed
-```
-
-Expected failures named the missing `canonicalizeRoleClass`,
-`authorityForCanonicalClass`, and `validateRosterV2Semantics` APIs, absent requested/canonical typed
-output, and unresolved required canonical role contracts. An earlier run that failed before test
-collection on an unresolved `yaml` dependency was treated as environment setup, not TDD evidence.
-
-### Green
-
-Focused role-resolution and affected service fixtures:
-
-```text
-6 test files passed; 109 tests passed
-```
-
-The focused set covers personas, profiles, provision, launch persona contract, roster-v2 semantics,
-and the operator-interaction service fixture. The final profile tests also cover readable lead/floor
-compatibility and canonical collision denial.
-
-## Tests and gates
-
-- Focused suites: pass, **6 files / 109 tests**.
-- Full `@mosaicstack/mosaic` suite: pass, **50 files / 713 tests**. Workspace package build outputs
-  were prepared first because a clean worktree has no dependency `dist` entries.
-- `pnpm --filter @mosaicstack/mosaic typecheck`: pass.
-- `pnpm --filter @mosaicstack/mosaic lint`: pass.
-- Prettier check over every changed file: pass.
-- `git diff --check`: pass.
-- Runtime/file-boundary evidence: real role library, profile/provision filesystem integration,
-  launch-time synchronous contract injection, v1 roster parser round-trip, roster-v2 semantic
-  filesystem checks, and operator-interaction service fixtures all pass without live mutation.
-- Independent code review: **APPROVE**, no blocking or non-blocking findings; reviewed complete
-  tracked/untracked delta including the canonical collision guard. Residual: roster-v2 semantic
-  validation is an explicit async handoff with production caller wiring owned by later work.
-- Independent security review: **APPROVE**, no verified authority/security findings on the final
-  delta.
-
-### Post-PR fail-closed remediation
-
-Independent rereview found resolver fail-open edges that the original green PR head did not cover. The
-remediation remained uncommitted until every finding was reproduced red-first and the same reviewer
-approved the complete two-file delta.
-
-Final regression evidence:
-
-```text
-persona resolver: 47/47
-focused affected suites: 6 files / 138 tests
-root-container resolver suites: 86/86
-full canonical run: 42/42 Turbo tasks; Mosaic 50 files / 733 tests
-```
-
-DB migration, typecheck, lint, Prettier, and `git diff --check` also passed. Coverage now proves:
-
-- unreadable, unscannable, direct-dangling, ancestor-dangling, and literal `..` traversal override paths
-  fail closed across async, sync, listing, and status APIs;
-- genuinely missing override directories still permit baseline fallback;
-- cached missing scans are revalidated before fallback;
-- marker-defined identity and domain metadata are revalidated on the second read;
-- `LIBRARY.md` rows and incidental later markers cannot define, shadow, or advertise personas.
-
-Exact-head pipeline `1819` passed for rebased head `4d990eee…`, but the independent reviewer-of-record
-returned **REQUEST CHANGES** after reproducing three additional edge failures: a canonical filename could
-inherit protected authority despite a conflicting explicit first marker, cached `scanned` absence could
-miss an override created before baseline fallback, and inherited plain-object names such as `constructor`
-could corrupt alias/authority lookup. Merge remained held.
-
-Each failure was reproduced red-first in the persona suite (4 failing assertions), then remediated without
-expanding card scope. Explicit first markers now own identity and filename fallback applies only to
-markerless contracts; every second read rejects a newly introduced conflicting marker regardless of
-cached classification; cached async resolution re-scans the override layer immediately before every
-baseline fallback; alias and authority registries require own-property matches. Current uncommitted
-evidence is persona **52/52**, focused affected suites **6 files / 143 tests**, and full Mosaic package
-**50 files / 738 tests**, plus typecheck, lint, Prettier, and `git diff --check`. Independent
-finding-specific rereview **APPROVED** the complete uncommitted three-file remediation after direct
-adversarial reproduction of all three findings and the follow-up markerless TOCTOU. All post-commit
-exact-head gates remain required.
-
-## Risks and boundaries
-
-- **Security-sensitive authority:** authority must derive only from canonical class, never role prose, aliases, display names, or tool-policy text.
-- **Resolver divergence:** no second regex, registry, scanner, or prose parser may be introduced.
-- **Alias capture:** aliases must canonicalize before baseline/`roles.local` lookup so local files cannot redefine legacy aliases as separate authority.
-- **Readable persona requirement:** semantic success requires a resolved readable persona, not class-set membership.
-- **Scope control:** no roster mutation, lifecycle, lease issuance, certificate workflow/storage, credentials, remote reconciliation, provision-v2 conversion, or shipped-example disposition execution.
-- **Coordination:** `docs/TASKS.md` is read-only and remains orchestrator-owned.
-
-## Acceptance-evidence mapping
-
-| Requirement / criterion | Verification evidence |
-| --- | --- |
-| `FCM-REQ-02` shared semantic resolver | Async/sync resolver parity; roster-v2 delegates batched scans and resolution; profiles/provision and launch reuse `fleet-personas.ts`; no second scanner or class-marker regex added. |
-| `FCM-REQ-07` canonical classes and authority boundaries | Exact alias and non-alias tests; immutable authority invariant tests; all required canonical contracts resolve through the real role library. |
-| `AC-FCM-01` structural + semantic roster validation | Synchronous parser/normalizer tests remain intact; async semantic tests cover aliases, custom roles, unreadable/unresolved roles, `LIBRARY`-only rejection, and bidirectional protected policy mismatch. |
-| `AC-FCM-07` protected authority invariants | Denial tests prove merge-gate-only merge, validator certificate-only, orchestrator/team-leader/interaction limits, no implicit custom-role authority, and canonical tool-policy matching. |
-
-## Documentation
-
-- `docs/fleet/reference/role-classes.md`
-- `docs/fleet/migration/legacy-class-aliases.md`
-- `docs/fleet/how-to/customize-roles.md`
-- `docs/fleet/reference/roster-v2-fields.md` semantic handoff
-- Baseline role contracts and `LIBRARY.md` rows for `validator`, `team-leader`, and `interaction`
-
-## Residual risks
-
-- Provisioning remains intentionally v1 and does not emit `reports_to`; canonical topology is retained
-  in its typed seat/summary path only, matching the existing v1 parser boundary.
-- Alias support remains for compatibility; new configuration should emit canonical identities.
-- This card defines authority metadata and validation only. Enforcement workflows for leases,
-  certificates, lifecycle, and mutation remain owned by later FCM cards.

docs/scratchpads/758-fcm-m1-003-example-profile-dispositions.md

@@ -1,37 +0,0 @@
-# FCM-M1-003 — Executable example/profile/service-preset dispositions
-
-- **Task / issue:** FCM-M1-003 / #758
-- **Branch / base:** `test/758-example-profile-dispositions` from `origin/main` `a5e8e554012f27898e035d2882a8e47e1a02fe97`
-- **Objective:** Make every artifact in the M0 legacy disposition inventory executable evidence: it must validate canonically, be explicitly retained as a v1 fixture, or be retired with a replacement/deprecation link.
-- **Scope:** Validation and explicit version/retirement metadata only for shipped examples, profiles, and the operator-interaction service preset. Reuse the central resolver and existing v2 roster compiler.
-- **Out of scope:** Generated environment boundaries, CRUD, reconciliation/apply, migration, live fleet mutation, and `docs/TASKS.md`.
-- **Budget:** 20K card allocation; use focused package tests before full package validation.
-
-## Plan
-
-1. Inventory exact shipped artifacts and existing compiler/resolver/profile tests.
-2. Add failing behavior tests covering all listed artifacts and their documented disposition.
-3. Implement minimal declarative fixture/disposition validation; do not add a role/class resolver.
-4. Run focused and package quality gates; obtain independent code and security review.
-5. Commit, queue-guard, push, open one `main` PR with `Refs #758`.
-
-## Progress
-
-- Intake complete: verified no branch, worktree, or open PR for this card before creating this isolated worktree.
-- Requirements read: FCM PRD, FCM-M1-003 task row, M0 disposition inventory, delivery/QA/documentation guides.
-- TDD: RED recorded with `pnpm --filter @mosaicstack/mosaic test -- example-profile-dispositions.spec.ts` failing because the new module did not exist; GREEN recorded after the minimal guard implementation. The focused suite now has 4 passing tests, including undeclared-artifact and missing-explicit-v1-version denials.
-- Independent review: initial code review found the service policy path was hardcoded; remediation iterates declared `canonical-service-policy` artifacts. Exact-head code review approved and exact-head security review found no issues.
-
-## Risks / decisions
-
-- The M0 inventory permits unresolved legacy roles only when explicitly v1-versioned or retired. Do not infer aliases beyond the three approved by FCM-M1-002.
-- `docs/TASKS.md` is orchestrator-owned and will not be edited.
-
-## Verification evidence
-
-- Focused TDD guard: `pnpm --filter @mosaicstack/mosaic test -- example-profile-dispositions.spec.ts` — PASS (4 tests).
-- Full package suite: `pnpm --filter @mosaicstack/mosaic test` — PASS (51 files, 742 tests).
-- Static gates: `pnpm --filter @mosaicstack/mosaic typecheck`, `pnpm --filter @mosaicstack/mosaic lint`, and `pnpm format:check` — PASS.
-- Diff gate: `git diff --check` — PASS.
-- Exact-head reviews: `codex-code-review.sh --uncommitted` — APPROVE; `codex-security-review.sh --uncommitted` — no findings.
-- Delivery: committed as `9a9ad1a`, pushed after `ci-queue-wait.sh --purpose push`, and opened PR [#770](https://git.mosaicstack.dev/mosaicstack/stack/pulls/770) to `main` with `Refs #758`. `pr-ci-wait.sh -n 770` reported terminal-green Woodpecker pipeline [#1823](https://ci.mosaicstack.dev/repos/47/pipeline/1823/1).

docs/scratchpads/769-kbn100-schema-migration.md

@@ -0,0 +1,52 @@
+# Issue #769 — KBN-100 unified schema and N-1 migration
+
+## Status
+
+IN PROGRESS — tracking and baseline gate. No schema or migration implementation is authorized until this scratchpad and `docs/native-kanban-sot/TASKS.md` are committed/pushed and baseline evidence is recorded.
+
+## Requirement authority
+
+- Provider issue: <https://git.mosaicstack.dev/mosaicstack/stack/issues/769>
+- Canonical requirements: `docs/requirements/native-kanban-sot.md`
+- Frozen integration contract: `docs/native-kanban-sot/SHARED-CONTRACT.md` v1.0.0-rc.4
+- Frozen target schema: `docs/native-kanban-sot/contracts/kanban-schema.v1.ts`
+- Threat/auth/constraint gate: `docs/native-kanban-sot/KBN-010-THREAT-AUTH-CONSTRAINT-GATE.md`
+- Dependency evidence: PR #765 merge `2e228007`, issue #753 closed, post-main pipeline #1813 terminal success.
+
+## Fixed decisions
+
+1. PostgreSQL is the sole writable project/task/orchestration SOT; generated projections and external transports are never import/write authority.
+2. Expand is additive and N-1-safe. Do not drop, rename, narrow, or reinterpret legacy data during this card.
+3. Backfill is bounded, idempotent, resumable, checksummed, and quarantines ambiguity rather than guessing.
+4. rc.4 SI-001 creates `missions_workspace_id_uidx(workspace_id,id)` before both dependent artifact/approval FKs while retaining global and project-congruent keys.
+5. Runtime repositories, Gateway/MCP, Coordinator behavior, clients, fleet, channels, connector fencing, deployment, and production migration execution are out of scope.
+6. Critical schema/data behavior uses TDD RED/GREEN and real PostgreSQL integration evidence; PGlite-only evidence cannot certify the migration.
+
+## Authorized paths
+
+- `packages/db/src/schema.ts`
+- `packages/db/drizzle/**`
+- DB-package tests/config files explicitly enumerated by the author before first edit
+- `docs/native-kanban-sot/TASKS.md`
+- this scratchpad
+
+Any additional path requires control-plane approval before edit.
+
+## Delivery cycle
+
+`baseline -> test design/RED -> schema+migration GREEN -> focused tests -> real PostgreSQL migration matrix -> full gates -> independent DB review -> SecReview -> remediate/rereview -> Codex-Ultron -> PR CI -> squash merge -> post-main CI -> issue close`
+
+## Baseline evidence
+
+Pending fresh author-lane intake and baseline test run.
+
+## Collision boundaries
+
+- #758 owns generic local Fleet configuration/lifecycle cards.
+- #757/#755 owns logical-agent connector identity/lease/fencing.
+- #756 channel foundation is merged and remains separate.
+- KBN-105 and all KBN consumers remain held until #769 completes.
+
+## Completion evidence
+
+Pending implementation, reviews, PR, merge, terminal-green main CI, and issue closure.

docs/scratchpads/771-kbn101-db-role-split.md

@@ -1,138 +0,0 @@
-# Scratchpad — KBN-101 DB runtime/migration role split (#771)
-
-- **Branch:** `docs/771-kbn101-db-role-split`
-- **Base:** `main` `e9c4aa3`
-- **Scope:** planning/documentation only; authorized files are PRD, Native Kanban task/shared/index docs, sitemap, this scratchpad, and the new KBN-101 contract.
-- **Explicit exclusions:** source/runtime/config/deployment/secret/migration/compose/CI/lock/package/KBN-100 branch edits; no production mutation.
-
-## Objective
-
-Freeze an implementation-ready PostgreSQL role/connection split so the Gateway uses a non-owner runtime identity and only a dedicated migration phase uses an owner/migrator identity. Make real deployed-role certification—not synthetic role tests—a serial prerequisite of KBN-100 and KBN-105.
-
-## Intake and current-state evidence
-
-- Mission MVP is active; W3 Native Kanban/SOT is planning-complete. The task state shows KBN-010 as the predecessor and KBN-100 as the current schema slice.
-- Current branch started at `e9c4aa3`; `.mosaic/orchestrator/{mission.json,session.lock}` were already runtime-modified and remain untouched.
-- `packages/db/src/client.ts`, `migrate.ts`, and `drizzle.config.ts` resolve one `DATABASE_URL` (with default fallback). `packages/storage/src/adapters/postgres.ts` calls `runMigrations(this.url)`.
-- `apps/gateway/src/database/database.module.ts` calls `storageAdapter.migrate()` at startup for PostgreSQL; this is the owner-runtime defect to remove in KBN-101 implementation.
-- `packages/config/src/mosaic-config.ts`, installer wizard, local/federated compose, Portainer test stack, and `.woodpecker/ci.yml` currently expose one URL. PGlite has an existing explicit local migration path.
-- Current KBN contract requires immutable events/checkpoints/artifacts/evidence, `RESTRICT`, and KBN-100 generated Drizzle consistency. It did not establish a deployable runtime identity split.
-
-## Frozen decisions
-
-1. `DATABASE_URL` is the non-owner runtime URL; `DATABASE_MIGRATION_URL` is migration-only. Both are required in their respective PostgreSQL phases; PGlite is the explicit local exception; migration never falls back to runtime/default/config URL.
-2. PostgreSQL Gateway runtime never auto-runs migration/DDL. Dedicated migrator uses `pg_try_advisory_lock(hashtext('mosaic-schema-migration-v1'))`; replicas only check exact ordered Drizzle-ledger readiness and fail closed.
-3. Roles are non-login `mosaic_platform_database_owner`, non-login `mosaic_schema_owner`, login/noinherit `mosaic_migrator`, non-login `mosaic_runtime_capability`, and login/inherit `mosaic_runtime`. Runtime inherits only its capability role with SET/ADMIN denied, has no owner/migrator membership, no unsafe attributes/ownership/DDL authority, and an explicit trusted search path.
-4. Runtime gets mutable DML only as needed, but INSERT/SELECT only on `task_events`, `artifacts`, `task_checkpoints`, `task_checkpoint_artifacts`, and `approval_decision_artifacts`. KBN-100 still enforces RESTRICT/no-cascade.
-5. Startup verifies effective role/ownership/attributes/inherited capability/TEMP/function-execute/ledger grants/search path/immutable denials/schema fingerprint without DSN exposure. It also requires authenticated CA/hostname-verified TLS. Stable sanitized errors and redaction rules are required.
-6. N-1 retains single runtime URL only as a non-certified compatibility release; staged role provisioning/migration/runtime deployment then enforces the split. Rollback never injects migration URL into Gateway.
-7. Vault target paths, rotation, deployment injection, CI, installer, compose, Portainer, and observability are separate one-card/one-PR handoffs. The migration-only file manifest includes `packages/db/drizzle.config.ts`; KBN-101 repairs the known PostgreSQL runner/journal ordering defect and proves a clean database applies every hash once before its foundation certificate. No application migration creates roles/passwords or hardcodes credentials.
-8. KBN-101 foundation merges/certifies first. KBN-100 then rebases, restores Drizzle declaration/snapshot/journal consistency, and bounds procedural immutable-table grant/trigger/backfill work to its own slice. Because those immutable relations do not exist until KBN-100, KBN-101’s real deployed-role immutable-operation certificate follows KBN-100 and is the serial gate before KBN-105.
-
-## Assumptions
-
-- `standalone` and `federated` are all current PostgreSQL production-like modes; a future PostgreSQL tier inherits this contract unless versioned otherwise.
-- Deployment will support a dedicated migration Job/one-shot command. A target that cannot run it cannot receive production/federated KBN certification.
-- Canonical Vault target paths require deployment-owner verification before provisioning; the planning document does not claim they already exist.
-
-## Documentation produced
-
-- `docs/PRD.md`: bounded KBN-101 requirements and acceptance criteria.
-- `docs/native-kanban-sot/KBN-101-DB-ROLE-SPLIT.md`: normative rc.5 implementation, threat, migration/rollback, evidence, and exact file DAG contract.
-- `docs/native-kanban-sot/SHARED-CONTRACT.md`: rc.5 amendment preserving rc.4.
-- `docs/native-kanban-sot/TASKS.md`: KBN-101 inserted before and blocks KBN-100; KBN-105 held.
-- Native Kanban index and root sitemap links.
-
-## Validation plan
-
-1. Prettier only for changed Markdown.
-2. Markdown link target/check checks scoped to modified docs.
-3. Strict contract check with `pnpm exec tsc --noEmit -p docs/native-kanban-sot/tsconfig.json` (the frozen TypeScript contracts remain unchanged).
-4. Diff allowlist proves only authorized documentation files changed, apart from pre-existing Mosaic runtime state.
-5. Independent documentation/security self-review: role escalation, fallback, startup DDL, schema readiness, grants/default privileges, immutable tables, secret leakage, deployment and KBN-100 boundaries.
-
-## Review corrections
-
-Independent Codex review found two blockers and security review found two medium defects; all were remediated in the frozen contract:
-
-1. Split the KBN-101 certificate into a foundation role/schema-boundary certificate (before KBN-100) and real immutable-operation certificate (after KBN-100, before KBN-105). This preserves the requested KBN-100 block without requiring evidence for tables not yet created.
-2. Removed the legacy owner-runtime exception. N-1 compatibility preserves variable/config shape only; the KBN-101 runtime refuses owner/migrator identity and current single-URL installs remain on their previous release until role cutover.
-3. Introduced `mosaic_platform_database_owner` as a separate non-login platform role. `mosaic_schema_owner` owns application/ledger schemas only, not the database and has no database CREATE/ALTER/extension authority.
-4. Replaced blocking `pg_advisory_lock` with `pg_try_advisory_lock` and the deterministic `DATABASE_MIGRATION_LOCKED` failure.
-5. Review also flagged active `.mosaic/orchestrator` state. It was pre-existing launcher state and remains unstaged/uncommitted.
-6. Second review added `packages/db/drizzle.config.ts` to the migration-only slice, mandates `DATABASE_MIGRATION_URL` with a missing-variable negative, grants runtime only `USAGE` plus `SELECT` on `drizzle.__drizzle_migrations`, and verifies/revokes its ledger writes.
-7. Security review added `DATABASE_TLS_CA_CERT_PATH` / `DatabaseTlsConfigDto` with authenticated TLS and hostname/CA verification in production-like modes, explicit database `TEMPORARY` revocation/catalog denial testing, and default-PUBLIC function EXECUTE revocation with SECURITY DEFINER prohibited by default.
-8. Final review corrected the runtime login to inherit only its capability role with SET/ADMIN denied, and moved the known hash-complete migration-runner/journal repair into KBN-101-03 before the foundation certificate.
-9. Final manifest review added all live runtime DDL paths (`packages/storage/src/tier-detection.ts`, Gateway startup, and `fleet-backlog`) to KBN-101-02, requiring read-only extension probes and no PostgreSQL runtime auto-migration. It also requires KBN-101-04 to stop persisting either DSN into generated `.env`/`mosaic.config.json`, using only Vault/deployment references and injected variables.
-10. Provisioning review separated the external privileged platform bootstrap actor from the NOCREATEDB database-owner role and added KBN-101-00. That IaC/bootstrap card owns fresh/existing database role/ownership/grant/Vault transition evidence and is a foundation-certificate dependency.
-
-## Results
-
-- `pnpm exec prettier --check` on every authorized Markdown file: PASS.
-- Markdown link and whitespace checker on all seven authorized Markdown files: PASS.
-- `pnpm exec tsc --noEmit -p docs/native-kanban-sot/tsconfig.json`: PASS (frozen strict contracts unchanged).
-- Codex code review iterated through role inheritability, hash-complete migration ordering, all reachable runtime DDL entrypoints, installer DSN persistence, and platform-bootstrap ownership; each finding was incorporated into the final frozen contract/DAG. The last security review found no new KBN-101 vulnerability; its sole low finding is the pre-existing unstaged Mosaic session-lock metadata, which is excluded from this commit.
-- Commit: `82ce3252df38a687c50485f8d048b53ca8db5989` (`docs(#771): freeze database runtime role split`).
-- Pre-push queue guard: `ci-queue-wait.sh --purpose push -B main` returned `state=unknown` without failure. The push hook ran repository `pnpm typecheck`, `pnpm lint`, and `pnpm format:check`: PASS.
-- Pushed branch `docs/771-kbn101-db-role-split` at the exact commit above; no PR was opened, merged, or closed. `web1:mosaic-100` received the handoff with head, decisions, DAG, and validation.
-- Awaiting independent security/Ultron review.
-
-## 2026-07-15 — rc.6 exact-head remediation session
-
-- **Objective / correction:** Replace the prior planning-author handoff and close every finding in the [independent exact-head report](../reports/native-kanban-sot/kbn-101-contract-security-review-82ce325.md) against `da742ca2da4a2ff466916c818fe275c4f7ffd384`. The report is a verbatim durable copy of the task-supplied review artifact; scope remains documentation-only, `.mosaic` is excluded, and source/config/compose/CI/deployment/secrets/migrations remain untouched.
-- **Finding 1 — closed DDL control plane:** rc.6 names `mosaic-db-migrator` as the sole application/CI/test PostgreSQL DDL runner, requires `DATABASE_MIGRATION_URL` before connection/DDL, inventories `runMigrations`, Drizzle config/scripts, `db:push`, storage CLI, adapter/Gateway startup, fleet-backlog, extension probes/bootstrap, direct federated integration DDL, CI, and future scripts, and specifies route/deny/test disposition for each. Tests use runner-prepared disposable PostgreSQL or invoke that runner; `db:push` is local-disposable-only and rejects production-like URLs.
-- **Finding 2 — deployable TLS:** rc.6 freezes distinct runtime/migrator URL and CA/server leaf Vault/compose/Swarm secret identifiers, `0400` key and `0600` URL/cert/CA mount requirements, actual compose/Swarm service-DNS SANs, PostgreSQL TLS settings, legacy-client drain/termination plus `hostssl` enforcement, verified-TLS readiness ordering, fresh/existing transition, CA-overlap rotation/TLS-only rollback, and standalone plus federated/Swarm positive and missing/wrong CA/SAN/downgrade negatives. PGlite is explicitly non-PostgreSQL evidence.
-- **Finding 3 — manifest/0009:** rc.6 defines manifest v1 canonical UTF-8 serialization and raw SQL-byte SHA-256, logical journal order, manifest ownership/grants, exact one-to-one observed hash tuple mapping, non-normative physical insertion order, safe original-0009 conditions, ambiguous-effect fail-closed recovery, and the full required reconciliation/backup test matrix. It preserves shipped 0009 bytes and forbids manual ledger adoption/insertion.
-- **Finding 4 — advisory lock:** replaced `hashtext` with fixed signed-int4-safe `(1297044289,1262636593)` (`MOSA`,`KBN1`), one `max:1` runner session, close-on-crash semantics, and contention/crash/readiness/unrelated-key evidence.
-- **Finding 5 — identifiers/search path:** selects `mosaic`, exact `pg_catalog,mosaic` per pooled connection and `SET LOCAL` transactions, plans audited public-object/extension/Drizzle relocation, forbids config-derived identifiers, limits bootstrap quoting to server-side `%I` on fixed allowlist, and requires injection/pool-reset negatives.
-- **Finding 6 — safe DAG:** cards 00–07 are inactive prepared capability while owner-runtime remains N-1; KBN-101-08 is the one atomic activation release after platform roles/TLS and compatible code. Mosaic control plane/Jason alone can activate/rollback; no force-on-red, runtime bypass, or temporary compatibility survives the gate. The approved role graph, post-KBN-100 immutable certification, and KBN-105 gate remain unchanged.
-- **Review remediation:** Codex review found the legacy plaintext cutover gap, missing URL-secret bindings, historical `public` migration incompatibility, non-reproducible checkout-byte hashing, CONNECT allowlisting regression, and undocumented direct-DDL operator instructions. rc.6 now requires drain/scale-to-zero, residual non-TLS session termination, `hostssl` with no `host` rule, zero plaintext-session proof, TLS-only post-enforcement rollback, distinct named runtime/migrator secret consumers, canonical Git-blob/LF manifest bytes, a runner-only owner-controlled legacy-public bootstrap followed by `mosaic` relocation, explicit CONNECT/TEMP revocation, and KBN-101-07 replacement of direct-DDL documentation. It also required the durable exact-head report link above. Pre-existing `.mosaic` runtime state remains excluded.
-- **Validation:** Prettier on all changed Markdown, repository Markdown link/whitespace check, and strict native-kanban contract TypeScript passed before final staging; the final staged diff excludes `.mosaic`. No source-code TDD applies because this is contract-only remediation.
-
-## 2026-07-15 — rc.7 residual remediation session
-
-- **Objective / correction:** Close every residual in the independent exact-head rc.6 re-review at `/home/hermes/agent-work/reviews/771-kbn101-contract-rereview-45ba3d6.md` for `45ba3d6ad4d5383f457a303c05bc816144cfa48a`, without changing source, compose, CI, deployment, migration, or secret artifacts. Only the existing authorized planning/documentation paths are eligible; pre-existing `.mosaic` state remains excluded.
-- **Source-backed scope confirmed:** the active `federated-pgvector.integration.test.ts` executes `CREATE TEMP TABLE`; tracked `docker/init-db.sql` and `infra/pg-init/01-extensions.sql` both create `vector`; `migrate-tier.ts` advertises raw `CREATE EXTENSION`; and `tools/federation-harness/docker-compose.two-gateways.yml` is current plaintext two-PostgreSQL/two-Gateway topology. Current `schema.ts` has 36 default-schema `pgTable` declarations, 6 default `pgEnum` declarations, and an unqualified `vector` custom type; historical migrations contain `public` references.
-- **Plan:** (1) make the finite DDL/static-bypass inventory and `DATABASE_URL`-only denial matrix exact, including the runner-prepared persistent pgvector fixture and migrated two-gateway harness; (2) freeze executable `public`-to-`mosaic` and `mosaic_extensions` transition, Drizzle ownership, object-catalog classes/order, eligibility and rollback tests; (3) bind repository/control-plane ownership, UID/GID validation, exact artifact/mount rules, and both gateway TLS topology; (4) correct PRD acceptance mapping and cross-document rc.7 status; then run formatting, link/contract, source-path, diff, review, commit, queue guard, and push.
-- **Independent review closure:** initial Codex review found Gateway-key consumer wording, `CLAUDE.md` omission, final schema-owner set, and placeholder SANs; all are now explicit. Re-review found the legacy `0001` vector-type resolution problem and `docs/federation/SETUP.md` raw-DDL instruction; the legacy runner now uses only its fixed non-writable `pg_catalog,public,mosaic_extensions` history path, while runtime remains `pg_catalog,mosaic`, and the federation setup path is assigned to KBN-101-07/static inventory. Security review final verdict: no confident vulnerability. The review also repeated the pre-existing tracked `.mosaic` session-state concern; it remains deliberately unstaged/excluded by this task.
-- **Completion evidence:** changed Markdown is Prettier-formatted; local links and strict native-kanban TypeScript passed; source-path inventory confirmed all current referenced paths (the new `apps/gateway/Dockerfile` is explicitly a planned KBN-101-05 artifact); diff check and authorized-doc allowlist passed. No source-code TDD applies to this documentation-only remediation.
-
-## 2026-07-15 — rc.8 exact residual remediation session
-
-- **Objective / correction:** Close all three HIGH findings in the independent rc.7 exact-head re-review at `/home/hermes/agent-work/reviews/771-kbn101-contract-rereview2-0778eba.md` for `0778eba2db3c2dfbaca3af352b12ba0389d3552b`. Scope remains documentation-only: no source, config, Compose, CI, deployment, secret, or migration artifact changed; pre-existing `.mosaic/orchestrator` state remains excluded.
-- **Finite authority closure:** KBN-101-06 now classifies exact current source/scripts/package bins, operator docs, and deploy manifests. `packages/db/src/index.ts` has explicit removal/compile-import negative ownership; `docs/fleet/backlog-conventions.md` and `docs/PERFORMANCE.md` now remove first-use/direct-Drizzle/Gateway-startup migration instructions and point to sole runner/readiness. Byte-immutable historical SQL, PGlite-only routines, negative-test literals, vendored/generated artifacts, and labeled historical reports are exact-path/category reviewed allowlists; unknown hits fail. The contract explicitly rejects relying on a naive token scan alone.
-- **Executable and exclusive handoff closure:** KBN-101-03 exclusively owns the published `mosaic-db-migrator` bin, `packages/db/src/cli.ts`, private migrator modules, `docker/db-migrator.Dockerfile`, exact `--run|--verify|--help`, environment/argv limits, sanitized exits, and command/order tests. KBN-101-00 exclusively owns `infra/pg-bootstrap/roles.sql`, `infra/pg-bootstrap/extensions.sql`, `infra/pg-bootstrap/README.md`, and bootstrap tests. KBN-101-05 exclusively owns `tools/db/render-postgres-secrets.ts`, its tests, and deployment declarations, consuming the versioned bootstrap interface without overlap.
-- **pgvector owner closure:** `mosaic_extension_owner` is dedicated NOLOGIN, available only to the external bootstrap actor during bootstrap; fresh vector/member ownership remains there. The contract records PostgreSQL's unsupported extension-owner transfer and forbids catalog mutation, ownership adoption, and `DROP CASCADE`. Approved-owner existing extensions use verified `ALTER EXTENSION ... SET SCHEMA`; legacy runtime-owned extensions fail closed to a controlled backup/shadow/runner/copy-evidence/quiesce/final-delta/atomic-switch/read-only-rollback migration. It requires `pg_extension.extowner`, member/schema/version, and runtime/migrator/schema-owner ALTER/DROP/member-update denial tests across clean, approved-owner, legacy shadow, partial/resume/rollback, and N-1.
-- **Cross-document state:** PRD, KBN contract, shared contract, task decomposition, index, sitemap, current operator docs, and this scratchpad are rc.8-consistent. The only intended next action is a fresh independent exact-head re-review after validation/push.
-- **Validation / review:** Prettier passed for all nine changed Markdown documents; local links passed (9 documents); `pnpm exec tsc --noEmit -p docs/native-kanban-sot/tsconfig.json` passed; source-path inventory passed (20 paths: 8 current, 12 explicitly planned); finite-authority requirement checklist and `git diff --check` passed. Manual documentation/security review checked the three requested paths, private-only runner boundary/exit contract, non-overlapping 00/03/05 ownership, extension-owner denial and shadow path, and `.mosaic` exclusion. No source-code TDD applies because this is contract-only remediation.
-- **Delivery evidence:** committed `1423c2ad02b5471eab006fb4c878808e5b29c387` as `docs(#771): close role split rc.8 residuals`. Push queue guard returned `state=unknown` without error; push hook ran repository `pnpm typecheck`, `pnpm lint`, and `pnpm format:check`, all PASS; branch push succeeded. This final evidence append is committed next, then the exact remote head is verified. The only intended next action is a fresh independent exact-head re-review.
-
-## 2026-07-15 — rc.9 final residual remediation session
-
-- **Objective / correction:** Close the three findings in `/home/hermes/agent-work/reviews/771-kbn101-contract-rereview3-9cf5d2f.md` against exact head `9cf5d2f6641b14082dc3294e2a84d1fb4ccc019d`: move `mosaic_extensions` schema ownership to `mosaic_extension_owner`; replace all broad/conflicting KBN-101 card ownership with a complete disjoint exact-path/test manifest; and classify the current architecture-plan `db:migrate` instruction with pinned scanner mechanics. Scope remains documentation-only; no source/config/Compose/CI/deployment/secret/migration artifact and no `.mosaic` path may be modified.
-- **Plan:** inspect current tracked source topology to name only existing paths; update the normative contract first and synchronize PRD/shared/task/index/sitemap/version language; run Prettier, changed-doc links, strict contract TypeScript, source/path and manifest-overlap checks, diff allowlist, independent documentation/security review; then stage docs only, commit, queue-guard, push, and verify exact remote SHA. No source-code TDD applies because this is contract-only remediation.
-- **Closure implemented:** rc.9 makes `mosaic_extension_owner` create and own `mosaic_extensions`, `vector`, and members; the external bootstrap actor alone temporarily `SET ROLE`s for fresh/approved-owner work, while schema owner has only `USAGE` for legacy type resolution and never temporary `CREATE`. Catalog/default-ACL plus direct DDL/member denials now cover runtime, migrator, and schema owner through fresh, relocation, shadow/resume, and rollback evidence.
-- **Delivery decomposition:** Replaced broad ownership with complete disjoint 00–09 manifests, exact tests/evidence, producer-before-consumer edges, and an explicit no-intermediate-deploy N-1 activation statement. `packages/storage/src/{cli,migrate-tier}.ts` belongs only to -02; the current tracked init artifacts are retired by -02 as direct-DLL closure; -03 owns all runner/index/migrate/config/schema assets and exact compiled-bin/image mapping; -07 owns docs only; -08/-09 own evidence only.
-- **Classifier closure:** -06 has exact scanner/inventory/matrix paths, canonical inventory fields, classes/dispositions, fixed token/rule set, exact allowlist categories/restrictions, and self-test requirements for unknown, duplicate-owner, ownerless, missing-path, and historical masking cases. The architecture plan now marks direct `db:migrate` superseded and uses `mosaic-db-migrator --run`.
-- **Validation:** Prettier check, strict native-kanban contract TypeScript, changed-document local-link resolution, `git diff --check`, and an automated manifest-overlap/owner/current-source-path check passed. Targeted documentation/security review verified role ownership/default privileges/search path/preflight/legacy/shadow/rollback consistency, disjoint manifests/DAG/activation, scanner mechanics, exact bin/entrypoint, and no `.mosaic` staging intent. No source-code TDD applies because this is documentation-only remediation.
-- **Next:** stage documentation only, commit, queue-guard, push, verify exact remote SHA, then wait for fresh exact-head review.
-- **Delivery evidence:** committed `8cbad2bcd9bc7507052f74f35670ef7c8e39e44e` as `docs(#771): close role split rc.9 residuals`; `ci-queue-wait.sh --purpose push -B main` returned `state=unknown` without error; push-hook `pnpm typecheck`, `pnpm lint`, and `pnpm format:check` all passed; push succeeded and `origin/docs/771-kbn101-db-role-split` resolved to that exact SHA. Pre-existing `.mosaic/orchestrator/{mission.json,session.lock}` remains modified but intentionally unstaged/excluded. The only next action is a fresh independent exact-head re-review.
-
-## 2026-07-15 — rc.10 Ultron NO-GO remediation intake
-
-- **Objective / scope:** Close only HIGH-1 and HIGH-2 in `/home/hermes/agent-work/reviews/771-kbn101-ultron-11f09a1.md` against exact head `11f09a15e43e72afda6a0374668996b4bda9e536`. Documentation only: preserve approved content; no source/config/Compose/CI/deploy/secret/migration edits and no `.mosaic` staging.
-- **Plan:** (1) replace the impossible `NOLOGIN NOSUPERUSER` extension owner with the exact non-login, zero-member `NOLOGIN SUPERUSER` external-control exception and document the non-delegable superuser residual; (2) require the audited external superuser session to `SET ROLE`/`RESET ROLE` for fresh, approved-owner, and shadow extension work, then prove catalog ownership and all service-role denial; (3) assign the active migrate-tier guide exclusively to KBN-101-07, add its active secure route to the -06 inventory/matrix/scanner schema, and freeze `--target-url-file /run/secrets/mosaic_migrate_target_url` plus pre-migrated target/dedicated non-DDL importer requirements; (4) synchronize PRD/shared/tasks/index/sitemap/guide and rc.10 status; (5) validate formatting, links, contracts, source paths, finite operator inventory, diff, review, commit, queue guard, push, and exact remote SHA.
-- **Target-image evidence before edits:** local `pgvector/pgvector:pg17` control file reports `default_version = '0.8.2'`, `relocatable = true`, and no `trusted`/`superuser` override (untrusted PostgreSQL extension). An isolated PostgreSQL 17 container proved a `NOLOGIN SUPERUSER` `mosaic_extension_owner` can create `mosaic_extensions` and `vector` under external-superuser `SET ROLE`, returns to the external session after `RESET ROLE`, has `rolcanlogin=false`, `rolsuper=true`, zero role members, exact extension/schema and owner-bearing-member ownership, and denies `SET ROLE`, `ALTER EXTENSION`, `DROP EXTENSION`, and schema ownership changes to runtime, migrator, schema owner, and data importer. Ownerless PostgreSQL catalog member classes (`pg_am`, `pg_cast`) were intentionally not misrepresented as ownable members.
-- **TDD decision:** skipped as not applicable: this is a documentation-only contract remediation. Future KBN-101-00/-02/-06 tests are specified as the situational evidence; no source/test artifact is permitted in this task.
-- **Final scope correction:** Per control-plane direction, remediation remains bounded to the two Ultron findings. The active guide is explicitly a non-operative KBN-101 contract until its owned implementation/activation lands; no additional design, source, CI, deployment, secret, or test artifact was added.
-- **Validation evidence:** target-image/container role proof PASS (pgvector `0.8.2`, `relocatable=true`, trusted absent/untrusted; external-superuser `SET ROLE`/`RESET ROLE`; exact extension/schema/owner-bearing-member ownership; zero membership and service-role denials). Changed-doc Prettier, strict native-kanban contract TypeScript, local-link resolver (8 docs), finite operator-doc inventory (one active KBN-101-07 route with no credential argv in executable blocks), source-path check (6 current paths), and `git diff --check` PASS. Pre-existing `.mosaic/orchestrator/{mission.json,session.lock}` remains intentionally excluded.
-
-## 2026-07-15 — rc.11 exact-head re-review remediation intake
-
-- **Objective / scope:** Close only HIGH-1 and HIGH-2 in `/home/hermes/agent-work/reviews/771-kbn101-contract-rereview5-f60144e.md` against `f60144eb3eab6234ab01bda592052081c777897e`: target-bind the non-DDL tier importer with a runner-produced signed attestation, and disposition every current non-normative documentation scanner hit, including the active user-guide route and federation historical status. Documentation only; no source/config/Compose/CI/deployment/secret/migration edits and no `.mosaic` staging.
-- **Frozen decision:** `mosaic-db-migrator --verify` is trusted only after TLS/identity/manifest/schema verification and signs a credential-free JCS/Ed25519 v1 artifact from a runner-only fixed root-owned private-key file. The artifact binds secret version/exact URL-file digest, canonical TLS/CA/SPKI/server/database/importer/manifest/schema identity, issued/expiry/nonce, and producer build/correlation; importer gets pinned public key plus artifact only. It validates both files and all bindings before target connection, opens/digests/connects from one in-memory URL read, validates server identity before DML, and distinguishes zero connection from zero DML. Key overlap/revocation, secret-rotation invalidation, replay cache, atomic rename, and sanitized errors are mandatory.
-- **Ownership:** -03 owns producer/signing DTO/tests; -02 importer interface/verification tests; -05 key/artifact mounts/render tests; -06 inventory/matrix and non-masking scanner tests; -07 operator guide. The exact manifests remain disjoint.
-- **Operator correction:** `storage migrate` is schema-wrapper delegation only; legacy `--from hot --to cold` tier-copy guidance is unavailable. Secure tier copy is `migrate-tier` with `--target-url-file` plus `--target-attestation-file`. Federation M1 task language is status-only and adjacent KBN-101 text says it authorizes no current DDL.
-- **TDD decision:** skipped as not applicable: this bounded task changes documentation only. Future -02/-03/-05/-06 tests are specified as the required implementation evidence.
-- **Validation / review:** Prettier PASS on all 18 changed Markdown/root-doc files; `pnpm exec tsc --noEmit -p docs/native-kanban-sot/tsconfig.json` PASS; changed-doc local-link resolver PASS (71 links); full current docs scanner/disposition PASS (10 non-normative paths, 4 normative-contract paths; no unknown active command); legacy `storage migrate --from` and raw target-URL bypass scan PASS; attestation field/interface assertion PASS; exact source ownership/manifest-overlap assertion PASS; `git diff --check`, docs-only scope, and secret-leak scan PASS. Manual documentation/security review verified key isolation, JCS/detached signature, secret-file hash as non-secret evidence, verification ordering/TOCTOU/replay/rotation, no connection vs zero DML, non-masking scanner class, status-only federation history, and no regression to pgvector closure. No source-code TDD applies.
-- **Delivery evidence:** committed `6227f076c819bd124383851633b16d4ef9c88a98` as `docs(#771): bind tier importer to verified target`; staged scope was 18 documentation files only and excluded `.mosaic`. Pre-push queue guard returned `state=unknown` without failure. Push hook ran repository `pnpm typecheck`, `pnpm lint`, and `pnpm format:check`: PASS. Branch push succeeded. Verify the exact remote SHA after this final delivery-evidence append, then idle for independent exact-head re-review and Ultron reverify. `.mosaic/orchestrator/{mission.json,session.lock}` remains pre-existing and excluded.

docs/tess/TASKS.md

@@ -43,4 +43,3 @@
 | TESS-M5-002 | done | Complete migration inventory, cutover, rollback, retention and deprecation evidence | #711 | coder3 | docs/tess | feat/tess-migration-docs | TESS-M4-V | 18K | TESS-MIG-001. **Mos-DISPATCHED to coder3 2026-07-13** ("M4 complete; advancing to M5") — dispatched AHEAD of TESS-M4-V passing; the M4-V-status-vs-#710-CLOSED dependency reconciliation is pending Mos ruling (tracked, not orchestrator-decided). **DELIVERED as PR #742** — 4 new files docs/tess/M5-MIGRATION-{INVENTORY,CUTOVER,ROLLBACK,RETENTION-DEPRECATION}.md, base main b7b0f508, frozen head b5e9d0e528a50aae2e916cc7202bacc2e8db67dd. Docs-only; tracking-control trio (MISSION-MANIFEST/TASKS/VERIFICATION-MATRIX) UNTOUCHED; command-authz byte-identical a9f829e7; no live creds. **CI pipeline 1773 SUCCESS** (repo 47, refs/pull/742/head, commit==head). **Independent non-author ROR COMPLETE: reviewer VERIFIED APPROVE at exact head b5e9d0e528a50aae2e916cc7202bacc2e8db67dd (Gitea comment 17108)** — evidence claims verified to trace to landed Hermes adapter / capability matrix, gateway registry/reachability, operator-memory scope path, Mos coordination boundary; docs do NOT over-claim transcript/profile import, schema migration, unsupported-capability enablement, production cutover, or deprecation completion. Head independently verified UNMOVED at b5e9d0e528a5 post-ROR (live Gitea), base main, mergeable=true. **#742 MERGED by Mos → main 5789711e. Deliverable docs LANDED. GATE: TESS-M4-V/M5-V verification-gate reconciliation remains Mos-owned/pending (this row was dispatched ahead of M4-V passing).** |
 | TESS-M5-003 | done | Complete OpenAPI, user/admin/developer/plugin/operations docs and checklist | #711 | codex | docs | feat/tess-docs | TESS-M5-001,TESS-M5-002 | 22K | Documentation hard gate. **DELIVERED as PR #746** (branch feat/tess-docs, base main, 7 docs-only files: docs/openapi-tess.yaml + docs/tess/{ADMIN,DEVELOPER,OPERATIONS,PLUGIN,USER}-GUIDE.md + M5-003-DOCUMENTATION-CHECKLIST.md). 4-round revise-loop (heads 470eb911→c9f69300→7aea94e2→25b9d642) converged: OpenAPI covers interaction routes + SSE /sessions/{sessionId}/stream + Mos coord (/api/coord/mos/handoff,/observe,/result) + memory preferences/insights/search; request-body schemas aligned to real DTOs (Send requires content+idempotencyKey, Stop requires approvalRef, Insight requires only content, MosHandoff body requires idempotencyKey+summary); checklist accurate. **CI pipeline 1786 SUCCESS** (repo 47, refs/pull/746/head, commit==head 25b9d642). **Independent non-author ROR COMPLETE: reviewer VERIFIED APPROVE at exact head 25b9d642b939014b3efd61826e7524cafc6ffc2e (Gitea comment 17170)** — docs-only, tracking-trio untouched, command-authz byte-identical a9f829e7, no false coverage claims. Head verified UNMOVED at 25b9d642 (live Gitea, not worker-reported), base main, mergeable=true. **#746 MERGED by Mos → main bc8016c8314ec3a4b6ebc2fec5d9f276fca3327a. Documentation gate LANDED.** GATE: TESS-M4-V/M5-V verification-gate reconciliation remains Mos-owned/pending. |
 | TESS-M5-V | not-started | Full baseline, contract, integration, Discord/CLI E2E, security review, recovery drill and rollback qualification | #711 | sonnet | apps/gateway, packages/agent, plugins/discord, packages/mosaic | review/tess-final | TESS-M5-003 | 35K | Maps AC-TESS-01..11 to evidence |
-| MOS-PORT-M1-001 | in-progress | Implement logical Mos identity, PostgreSQL connector lease, monotonic fencing, server-bound execution grants, audit, migrations, concurrency/restart/abuse/integration tests | #755 | codex | packages/types, packages/agent, packages/db, apps/gateway | feat/mos-logical-identity-fencing | — | 38K | Requirements MOS-PORT-ID-001, MOS-PORT-LEASE-001, MOS-PORT-FENCE-001..002, MOS-PORT-OBS-001, MOS-PORT-ARCH-001. One Sol/Pi worker; TDD; PR-open STOP; worker must not edit this ledger. |

packages/agent/src/connector-lease.test.ts

@@ -1,261 +0,0 @@
-import { describe, expect, it, vi } from 'vitest';
-import type {
-  ConnectorExecutionContext,
-  ConnectorExecutionGrant,
-  ConnectorLease,
-  ConnectorLeaseAuditEvent,
-  ConnectorLeaseStore,
-  FencedConnectorAdapter,
-  LogicalAgentBinding,
-} from '@mosaicstack/types';
-import {
-  ConnectorLeaseCoordinator,
-  MAX_CONNECTOR_GRANT_TTL_MS,
-  MAX_CONNECTOR_LEASE_TTL_MS,
-} from './connector-lease.js';
-import type { ConnectorLeaseError } from './connector-lease.js';
-
-const identity = { tenantId: 'tenant-a', logicalAgentId: 'mos' } as const;
-const binding: LogicalAgentBinding = { identity, bindingId: 'operator-chat' };
-const activeLease: ConnectorLease = {
-  ...binding,
-  leaseId: '00000000-0000-4000-8000-000000000001',
-  connectorId: 'connector-a',
-  scopes: ['runtime.send', 'tool.execute'],
-  leaseEpoch: '3',
-  acquiredAt: '2026-07-14T17:00:00.000Z',
-  heartbeatAt: '2026-07-14T17:00:00.000Z',
-  expiresAt: '2026-07-14T17:10:00.000Z',
-};
-
-class FakeLeaseStore implements ConnectorLeaseStore {
-  lease: ConnectorLease | null = activeLease;
-  readonly audits: ConnectorLeaseAuditEvent[] = [];
-
-  async acquire(): Promise<ConnectorLease> {
-    if (!this.lease) throw new Error('fixture has no lease');
-    return this.lease;
-  }
-
-  async takeover(): Promise<ConnectorLease> {
-    if (!this.lease) throw new Error('fixture has no lease');
-    return this.lease;
-  }
-
-  async heartbeat(): Promise<ConnectorLease> {
-    if (!this.lease) throw new Error('fixture has no lease');
-    return this.lease;
-  }
-
-  async release(): Promise<void> {}
-
-  async findCurrent(): Promise<ConnectorLease | null> {
-    return this.lease;
-  }
-
-  async recordAudit(event: ConnectorLeaseAuditEvent): Promise<void> {
-    this.audits.push(event);
-  }
-}
-
-describe('ConnectorLeaseCoordinator fencing', (): void => {
-  it('validates a server-minted grant immediately before invoking an adapter side effect', async (): Promise<void> => {
-    const store = new FakeLeaseStore();
-    const coordinator = new ConnectorLeaseCoordinator(store, {
-      now: (): Date => new Date('2026-07-14T17:01:00.000Z'),
-    });
-    const grant = await coordinator.issueGrant({
-      lease: activeLease,
-      scopes: ['runtime.send'],
-      ttlMs: 30_000,
-      correlationId: 'correlation-1',
-    });
-    const execute = vi.fn(async (_input: string, context: ConnectorExecutionContext) => context);
-    const adapter: FencedConnectorAdapter<string, ConnectorExecutionContext> = { execute };
-
-    const context = await coordinator.executeGrant(grant, 'runtime.send', 'hello', adapter);
-
-    expect(execute).toHaveBeenCalledOnce();
-    expect(context).toMatchObject({
-      identity,
-      bindingId: 'operator-chat',
-      connectorId: 'connector-a',
-      leaseEpoch: '3',
-      scopes: ['runtime.send'],
-    });
-  });
-
-  it('caps grant expiry to the durable current lease instead of submitted metadata', async (): Promise<void> => {
-    const store = new FakeLeaseStore();
-    store.lease = { ...activeLease, expiresAt: '2026-07-14T17:01:05.000Z' };
-    const coordinator = new ConnectorLeaseCoordinator(store, {
-      now: (): Date => new Date('2026-07-14T17:01:00.000Z'),
-    });
-
-    const grant = await coordinator.issueGrant({
-      lease: { ...activeLease, expiresAt: '2026-07-14T18:00:00.000Z' },
-      scopes: ['runtime.send'],
-      ttlMs: 30_000,
-      correlationId: 'correlation-durable-expiry',
-    });
-
-    expect(grant.expiresAt).toBe('2026-07-14T17:01:05.000Z');
-  });
-
-  it.each([
-    ['forged clone', (grant: ConnectorExecutionGrant): ConnectorExecutionGrant => ({ ...grant })],
-    [
-      'cross-tenant clone',
-      (grant: ConnectorExecutionGrant): ConnectorExecutionGrant => ({
-        ...grant,
-        identity: { ...grant.identity, tenantId: 'tenant-b' },
-      }),
-    ],
-    [
-      'cross-agent clone',
-      (grant: ConnectorExecutionGrant): ConnectorExecutionGrant => ({
-        ...grant,
-        identity: { ...grant.identity, logicalAgentId: 'other-agent' },
-      }),
-    ],
-    [
-      'cross-binding clone',
-      (grant: ConnectorExecutionGrant): ConnectorExecutionGrant => ({
-        ...grant,
-        bindingId: 'other-binding',
-      }),
-    ],
-    [
-      'cross-connector clone',
-      (grant: ConnectorExecutionGrant): ConnectorExecutionGrant => ({
-        ...grant,
-        connectorId: 'connector-b',
-      }),
-    ],
-  ])('denies and audits a %s before adapter invocation', async (_label, forge): Promise<void> => {
-    const store = new FakeLeaseStore();
-    const coordinator = new ConnectorLeaseCoordinator(store, {
-      now: (): Date => new Date('2026-07-14T17:01:00.000Z'),
-    });
-    const grant = await coordinator.issueGrant({
-      lease: activeLease,
-      scopes: ['runtime.send'],
-      ttlMs: 30_000,
-      correlationId: 'correlation-forged',
-    });
-    const adapter = { execute: vi.fn().mockResolvedValue(undefined) };
-
-    await expect(
-      coordinator.executeGrant(forge(grant), 'runtime.send', undefined, adapter),
-    ).rejects.toMatchObject({ code: 'forged_grant' } satisfies Partial<ConnectorLeaseError>);
-    expect(adapter.execute).not.toHaveBeenCalled();
-    expect(store.audits.at(-1)).toMatchObject({
-      event: 'reject',
-      outcome: 'denied',
-      reason: 'forged_grant',
-      correlationId: 'correlation-forged',
-    });
-  });
-
-  it('denies malformed forged grants with sanitized audit metadata', async (): Promise<void> => {
-    const store = new FakeLeaseStore();
-    const coordinator = new ConnectorLeaseCoordinator(store, {
-      now: (): Date => new Date('2026-07-14T17:01:00.000Z'),
-    });
-    const adapter = { execute: vi.fn().mockResolvedValue(undefined) };
-
-    await expect(
-      coordinator.executeGrant(
-        // @ts-expect-error Deliberately exercise malformed runtime input at the trust boundary.
-        {},
-        'runtime.send',
-        undefined,
-        adapter,
-      ),
-    ).rejects.toMatchObject({ code: 'forged_grant' } satisfies Partial<ConnectorLeaseError>);
-    expect(adapter.execute).not.toHaveBeenCalled();
-    expect(store.audits).toContainEqual(
-      expect.objectContaining({
-        identity: { tenantId: 'untrusted', logicalAgentId: 'untrusted' },
-        bindingId: 'untrusted',
-        connectorId: 'untrusted',
-        correlationId: 'untrusted',
-        reason: 'forged_grant',
-      }),
-    );
-  });
-
-  it('rejects lease and grant TTLs above server-side safety caps', async (): Promise<void> => {
-    const store = new FakeLeaseStore();
-    const coordinator = new ConnectorLeaseCoordinator(store, {
-      now: (): Date => new Date('2026-07-14T17:01:00.000Z'),
-    });
-    expect(
-      () =>
-        new ConnectorLeaseCoordinator(store, {
-          maxLeaseTtlMs: MAX_CONNECTOR_LEASE_TTL_MS + 1,
-        }),
-    ).toThrow(/no greater than/);
-
-    await expect(
-      coordinator.acquire({
-        identity,
-        bindingId: 'operator-chat',
-        connectorId: 'connector-a',
-        scopes: ['runtime.send'],
-        ttlMs: MAX_CONNECTOR_LEASE_TTL_MS + 1,
-        correlationId: 'correlation-ttl',
-      }),
-    ).rejects.toThrow(/no greater than/);
-    await expect(
-      coordinator.issueGrant({
-        lease: activeLease,
-        scopes: ['runtime.send'],
-        ttlMs: MAX_CONNECTOR_GRANT_TTL_MS + 1,
-        correlationId: 'correlation-ttl',
-      }),
-    ).rejects.toThrow(/no greater than/);
-  });
-
-  it('denies stale epoch, expired grant, and unauthorized scope before side effects', async (): Promise<void> => {
-    let now = new Date('2026-07-14T17:01:00.000Z');
-    const store = new FakeLeaseStore();
-    const coordinator = new ConnectorLeaseCoordinator(store, { now: (): Date => now });
-    const stale = await coordinator.issueGrant({
-      lease: activeLease,
-      scopes: ['runtime.send'],
-      ttlMs: 30_000,
-      correlationId: 'correlation-stale',
-    });
-    store.lease = { ...activeLease, leaseEpoch: '4', connectorId: 'connector-b' };
-    const adapter = { execute: vi.fn().mockResolvedValue(undefined) };
-
-    await expect(
-      coordinator.executeGrant(stale, 'runtime.send', undefined, adapter),
-    ).rejects.toMatchObject({ code: 'stale_epoch' } satisfies Partial<ConnectorLeaseError>);
-
-    store.lease = activeLease;
-    const expiring = await coordinator.issueGrant({
-      lease: activeLease,
-      scopes: ['runtime.send'],
-      ttlMs: 1_000,
-      correlationId: 'correlation-expired',
-    });
-    now = new Date('2026-07-14T17:01:02.000Z');
-    await expect(
-      coordinator.executeGrant(expiring, 'runtime.send', undefined, adapter),
-    ).rejects.toMatchObject({ code: 'grant_expired' } satisfies Partial<ConnectorLeaseError>);
-
-    now = new Date('2026-07-14T17:01:00.000Z');
-    const scoped = await coordinator.issueGrant({
-      lease: activeLease,
-      scopes: ['runtime.send'],
-      ttlMs: 30_000,
-      correlationId: 'correlation-scope',
-    });
-    await expect(
-      coordinator.executeGrant(scoped, 'tool.execute', undefined, adapter),
-    ).rejects.toMatchObject({ code: 'scope_denied' } satisfies Partial<ConnectorLeaseError>);
-    expect(adapter.execute).not.toHaveBeenCalled();
-  });
-});

packages/agent/src/connector-lease.ts

@@ -1,381 +0,0 @@
-import { randomUUID } from 'node:crypto';
-import {
-  normalizeConnectorId,
-  normalizeConnectorScope,
-  normalizeConnectorScopes,
-  normalizeCorrelationId,
-  normalizeLeaseEpoch,
-  normalizeLogicalAgentIdentity,
-  normalizeLogicalBindingId,
-  type AcquireConnectorLeaseInput,
-  type ConnectorExecutionContext,
-  type ConnectorExecutionGrant,
-  type ConnectorLease,
-  type ConnectorLeaseAuditEvent,
-  type ConnectorLeaseRejectReason,
-  type ConnectorLeaseStore,
-  type FencedConnectorAdapter,
-  type HeartbeatConnectorLeaseInput,
-  type IssueConnectorExecutionGrantInput,
-  type LogicalAgentBinding,
-  type ReleaseConnectorLeaseInput,
-  type TakeoverConnectorLeaseInput,
-} from '@mosaicstack/types';
-
-export const MAX_CONNECTOR_LEASE_TTL_MS = 5 * 60 * 1000;
-export const MAX_CONNECTOR_GRANT_TTL_MS = 30 * 1000;
-
-export interface ConnectorLeaseCoordinatorOptions {
-  readonly now?: () => Date;
-  readonly maxLeaseTtlMs?: number;
-  readonly maxGrantTtlMs?: number;
-}
-
-export class ConnectorLeaseError extends Error {
-  constructor(
-    readonly code: ConnectorLeaseRejectReason,
-    message: string,
-  ) {
-    super(message);
-    this.name = ConnectorLeaseError.name;
-  }
-}
-
-/**
- * Runtime-neutral lease coordinator. Durable CAS lives in the store adapter;
- * grant provenance remains process-local so a restart fails closed and mints
- * fresh grants from the durable current lease.
- */
-export class ConnectorLeaseCoordinator {
-  private readonly issuedGrants = new WeakSet<object>();
-  private readonly now: () => Date;
-  private readonly maxLeaseTtlMs: number;
-  private readonly maxGrantTtlMs: number;
-
-  constructor(
-    private readonly store: ConnectorLeaseStore,
-    options: ConnectorLeaseCoordinatorOptions = {},
-  ) {
-    this.now = options.now ?? (() => new Date());
-    this.maxLeaseTtlMs = normalizeTtlLimit(
-      options.maxLeaseTtlMs ?? MAX_CONNECTOR_LEASE_TTL_MS,
-      MAX_CONNECTOR_LEASE_TTL_MS,
-      'lease',
-    );
-    this.maxGrantTtlMs = normalizeTtlLimit(
-      options.maxGrantTtlMs ?? MAX_CONNECTOR_GRANT_TTL_MS,
-      MAX_CONNECTOR_GRANT_TTL_MS,
-      'grant',
-    );
-  }
-
-  async acquire(input: AcquireConnectorLeaseInput): Promise<ConnectorLease> {
-    const command = normalizeAcquireInput(input, this.maxLeaseTtlMs);
-    const now = this.now();
-    return this.store.acquire({
-      ...command,
-      leaseId: randomUUID(),
-      now: now.toISOString(),
-      expiresAt: expiresAt(now, command.ttlMs),
-    });
-  }
-
-  async takeover(input: TakeoverConnectorLeaseInput): Promise<ConnectorLease> {
-    const command = normalizeAcquireInput(input, this.maxLeaseTtlMs);
-    const now = this.now();
-    return this.store.takeover({
-      ...command,
-      expectedEpoch: normalizeLeaseEpoch(input.expectedEpoch),
-      leaseId: randomUUID(),
-      now: now.toISOString(),
-      expiresAt: expiresAt(now, command.ttlMs),
-    });
-  }
-
-  async heartbeat(input: HeartbeatConnectorLeaseInput): Promise<ConnectorLease> {
-    const now = this.now();
-    const lease = normalizeConnectorLease(input.lease);
-    const ttlMs = normalizeTtl(input.ttlMs, this.maxLeaseTtlMs, 'lease');
-    return this.store.heartbeat({
-      lease,
-      ttlMs,
-      correlationId: normalizeCorrelationId(input.correlationId),
-      now: now.toISOString(),
-      expiresAt: expiresAt(now, ttlMs),
-    });
-  }
-
-  async release(input: ReleaseConnectorLeaseInput): Promise<void> {
-    await this.store.release({
-      lease: normalizeConnectorLease(input.lease),
-      correlationId: normalizeCorrelationId(input.correlationId),
-      now: this.now().toISOString(),
-    });
-  }
-
-  async current(binding: LogicalAgentBinding): Promise<ConnectorLease | null> {
-    return this.store.findCurrent(normalizeBinding(binding));
-  }
-
-  async issueGrant(input: IssueConnectorExecutionGrantInput): Promise<ConnectorExecutionGrant> {
-    const now = this.now();
-    const lease = normalizeConnectorLease(input.lease);
-    const scopes = normalizeConnectorScopes(input.scopes);
-    const correlationId = normalizeCorrelationId(input.correlationId);
-    const ttlMs = normalizeTtl(input.ttlMs, this.maxGrantTtlMs, 'grant');
-    const current = await this.store.findCurrent(lease);
-    await this.assertCurrentLease(current, lease, now, correlationId);
-    if (!current) throw new ConnectorLeaseError('lease_missing', 'Connector lease is unavailable');
-    if (!isScopeSubset(scopes, lease.scopes) || !isScopeSubset(scopes, current.scopes)) {
-      await this.reject(lease, correlationId, now, 'scope_denied');
-    }
-    const requestedExpiry = new Date(now.getTime() + ttlMs);
-    const leaseExpiry = new Date(current.expiresAt);
-    const grantExpiry = requestedExpiry < leaseExpiry ? requestedExpiry : leaseExpiry;
-    const grant: ConnectorExecutionGrant = Object.freeze({
-      identity: current.identity,
-      bindingId: current.bindingId,
-      leaseId: current.leaseId,
-      connectorId: current.connectorId,
-      scopes,
-      leaseEpoch: current.leaseEpoch,
-      issuedAt: now.toISOString(),
-      expiresAt: grantExpiry.toISOString(),
-      correlationId,
-    });
-    this.issuedGrants.add(grant);
-    return grant;
-  }
-
-  async executeGrant<TInput, TOutput>(
-    grant: ConnectorExecutionGrant,
-    requiredScope: string,
-    input: TInput,
-    adapter: FencedConnectorAdapter<TInput, TOutput>,
-  ): Promise<TOutput> {
-    const now = this.now();
-    const normalizedScope = normalizeConnectorScope(requiredScope);
-    if (!this.issuedGrants.has(grant)) {
-      await this.rejectForgedGrant(grant, now);
-    }
-    if (new Date(grant.expiresAt) <= now) {
-      await this.rejectGrant(grant, now, 'grant_expired');
-    }
-    const current = await this.store.findCurrent(normalizeBinding(grant));
-    await this.assertCurrentLease(current, grant, now, grant.correlationId);
-    if (!grant.scopes.includes(normalizedScope) || !current?.scopes.includes(normalizedScope)) {
-      await this.rejectGrant(grant, now, 'scope_denied');
-    }
-    if (!current) throw new ConnectorLeaseError('lease_missing', 'Connector lease is unavailable');
-    const context: ConnectorExecutionContext = Object.freeze({
-      identity: current.identity,
-      bindingId: current.bindingId,
-      leaseId: current.leaseId,
-      connectorId: current.connectorId,
-      scopes: Object.freeze([...grant.scopes]),
-      leaseEpoch: current.leaseEpoch,
-      correlationId: grant.correlationId,
-      grantExpiresAt: grant.expiresAt,
-    });
-    return adapter.execute(input, context);
-  }
-
-  private async assertCurrentLease(
-    current: ConnectorLease | null,
-    authority: ConnectorLease | ConnectorExecutionGrant,
-    now: Date,
-    correlationId: string,
-  ): Promise<void> {
-    if (!current) await this.reject(authority, correlationId, now, 'lease_missing');
-    if (!current) throw new ConnectorLeaseError('lease_missing', 'Connector lease is unavailable');
-    if (current.releasedAt) await this.reject(authority, correlationId, now, 'lease_released');
-    if (new Date(current.expiresAt) <= now) {
-      await this.store.recordAudit(auditEvent(current, correlationId, now, 'expiry', 'succeeded'));
-      await this.reject(authority, correlationId, now, 'lease_expired');
-    }
-    if (current.leaseEpoch !== authority.leaseEpoch) {
-      await this.reject(authority, correlationId, now, 'stale_epoch');
-    }
-    if (current.leaseId !== authority.leaseId || current.connectorId !== authority.connectorId) {
-      await this.reject(authority, correlationId, now, 'connector_mismatch');
-    }
-  }
-
-  private async rejectGrant(
-    grant: ConnectorExecutionGrant,
-    now: Date,
-    reason: ConnectorLeaseRejectReason,
-  ): Promise<never> {
-    return this.reject(grant, grant.correlationId, now, reason);
-  }
-
-  private async rejectForgedGrant(grant: unknown, now: Date): Promise<never> {
-    const event = safeForgedGrantAudit(grant, now);
-    await this.store.recordAudit(event);
-    throw new ConnectorLeaseError('forged_grant', safeReasonMessage('forged_grant'));
-  }
-
-  private async reject(
-    authority: LogicalAgentBinding & {
-      readonly connectorId: string;
-      readonly leaseId?: string;
-      readonly leaseEpoch?: string;
-    },
-    correlationId: string,
-    now: Date,
-    reason: ConnectorLeaseRejectReason,
-  ): Promise<never> {
-    await this.store.recordAudit(
-      auditEvent(authority, correlationId, now, 'reject', 'denied', reason),
-    );
-    throw new ConnectorLeaseError(reason, safeReasonMessage(reason));
-  }
-}
-
-function normalizeAcquireInput(
-  input: AcquireConnectorLeaseInput,
-  maxLeaseTtlMs: number,
-): AcquireConnectorLeaseInput {
-  return {
-    identity: normalizeLogicalAgentIdentity(input.identity),
-    bindingId: normalizeLogicalBindingId(input.bindingId),
-    connectorId: normalizeConnectorId(input.connectorId),
-    scopes: normalizeConnectorScopes(input.scopes),
-    ttlMs: normalizeTtl(input.ttlMs, maxLeaseTtlMs, 'lease'),
-    correlationId: normalizeCorrelationId(input.correlationId),
-  };
-}
-
-function normalizeBinding(input: LogicalAgentBinding): LogicalAgentBinding {
-  return {
-    identity: normalizeLogicalAgentIdentity(input.identity),
-    bindingId: normalizeLogicalBindingId(input.bindingId),
-  };
-}
-
-export function normalizeConnectorLease(lease: ConnectorLease): ConnectorLease {
-  const binding = normalizeBinding(lease);
-  return Object.freeze({
-    ...binding,
-    leaseId: lease.leaseId,
-    connectorId: normalizeConnectorId(lease.connectorId),
-    scopes: normalizeConnectorScopes(lease.scopes),
-    leaseEpoch: normalizeLeaseEpoch(lease.leaseEpoch),
-    acquiredAt: normalizeTimestamp(lease.acquiredAt, 'lease acquisition'),
-    heartbeatAt: normalizeTimestamp(lease.heartbeatAt, 'lease heartbeat'),
-    expiresAt: normalizeTimestamp(lease.expiresAt, 'lease expiry'),
-    ...(lease.releasedAt
-      ? { releasedAt: normalizeTimestamp(lease.releasedAt, 'lease release') }
-      : {}),
-  });
-}
-
-function normalizeTtl(ttlMs: number, maximum: number, kind: 'lease' | 'grant'): number {
-  if (!Number.isSafeInteger(ttlMs) || ttlMs <= 0 || ttlMs > maximum) {
-    throw new Error(
-      `Connector ${kind} TTL must be a positive safe integer no greater than ${maximum}ms`,
-    );
-  }
-  return ttlMs;
-}
-
-function normalizeTtlLimit(ttlMs: number, hardMaximum: number, kind: 'lease' | 'grant'): number {
-  if (!Number.isSafeInteger(ttlMs) || ttlMs <= 0 || ttlMs > hardMaximum) {
-    throw new Error(
-      `Maximum connector ${kind} TTL must be a positive safe integer no greater than ${hardMaximum}ms`,
-    );
-  }
-  return ttlMs;
-}
-
-function normalizeTimestamp(value: string, label: string): string {
-  const date = new Date(value);
-  if (Number.isNaN(date.getTime())) throw new Error(`${label} timestamp is invalid`);
-  return date.toISOString();
-}
-
-function expiresAt(now: Date, ttlMs: number): string {
-  const expiry = new Date(now.getTime() + ttlMs);
-  if (Number.isNaN(expiry.getTime())) throw new Error('Connector lease TTL exceeds date range');
-  return expiry.toISOString();
-}
-
-function isScopeSubset(requested: readonly string[], allowed: readonly string[]): boolean {
-  return requested.every((scope) => allowed.includes(scope));
-}
-
-function auditEvent(
-  authority: LogicalAgentBinding & {
-    readonly connectorId: string;
-    readonly leaseId?: string;
-    readonly leaseEpoch?: string;
-  },
-  correlationId: string,
-  now: Date,
-  event: ConnectorLeaseAuditEvent['event'],
-  outcome: ConnectorLeaseAuditEvent['outcome'],
-  reason?: ConnectorLeaseRejectReason,
-): ConnectorLeaseAuditEvent {
-  return {
-    identity: authority.identity,
-    bindingId: authority.bindingId,
-    connectorId: authority.connectorId,
-    correlationId,
-    occurredAt: now.toISOString(),
-    event,
-    outcome,
-    ...(authority.leaseId ? { leaseId: authority.leaseId } : {}),
-    ...(authority.leaseEpoch ? { leaseEpoch: authority.leaseEpoch } : {}),
-    ...(reason ? { reason } : {}),
-  };
-}
-
-function safeForgedGrantAudit(grant: unknown, now: Date): ConnectorLeaseAuditEvent {
-  const fallback: ConnectorLeaseAuditEvent = {
-    identity: { tenantId: 'untrusted', logicalAgentId: 'untrusted' },
-    bindingId: 'untrusted',
-    connectorId: 'untrusted',
-    correlationId: 'untrusted',
-    occurredAt: now.toISOString(),
-    event: 'reject',
-    outcome: 'denied',
-    reason: 'forged_grant',
-  };
-  if (typeof grant !== 'object' || grant === null || !('identity' in grant)) return fallback;
-  const identity = grant.identity;
-  if (typeof identity !== 'object' || identity === null) return fallback;
-  if (!('tenantId' in identity) || !('logicalAgentId' in identity)) return fallback;
-  if (!('bindingId' in grant) || !('connectorId' in grant) || !('correlationId' in grant)) {
-    return fallback;
-  }
-  if (
-    typeof identity.tenantId !== 'string' ||
-    typeof identity.logicalAgentId !== 'string' ||
-    typeof grant.bindingId !== 'string' ||
-    typeof grant.connectorId !== 'string' ||
-    typeof grant.correlationId !== 'string'
-  ) {
-    return fallback;
-  }
-  try {
-    return {
-      identity: normalizeLogicalAgentIdentity({
-        tenantId: identity.tenantId,
-        logicalAgentId: identity.logicalAgentId,
-      }),
-      bindingId: normalizeLogicalBindingId(grant.bindingId),
-      connectorId: normalizeConnectorId(grant.connectorId),
-      correlationId: normalizeCorrelationId(grant.correlationId),
-      occurredAt: now.toISOString(),
-      event: 'reject',
-      outcome: 'denied',
-      reason: 'forged_grant',
-    };
-  } catch {
-    return fallback;
-  }
-}
-
-function safeReasonMessage(reason: ConnectorLeaseRejectReason): string {
-  return `Connector authority denied: ${reason}`;
-}

packages/agent/src/index.ts

@@ -5,4 +5,3 @@ export * from './tmux-fleet-runtime-provider.js';
 export * from './hermes-runtime-provider.js';
 export * from './matrix-native-runtime-provider.js';
 export * from './durable-session.js';
-export * from './connector-lease.js';

packages/db/drizzle/0016_salty_morlocks.sql

@@ -1,36 +0,0 @@
-CREATE TABLE "connector_lease_audit_log" (
-	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
-	"tenant_id" text NOT NULL,
-	"logical_agent_id" text NOT NULL,
-	"binding_id" text NOT NULL,
-	"connector_id" text NOT NULL,
-	"lease_id" uuid,
-	"lease_epoch" bigint,
-	"event" text NOT NULL,
-	"outcome" text NOT NULL,
-	"reason" text,
-	"correlation_id" text NOT NULL,
-	"occurred_at" timestamp with time zone NOT NULL
-);
---> statement-breakpoint
-CREATE TABLE "logical_agent_connector_leases" (
-	"lease_id" uuid PRIMARY KEY NOT NULL,
-	"tenant_id" text NOT NULL,
-	"logical_agent_id" text NOT NULL,
-	"binding_id" text NOT NULL,
-	"connector_id" text NOT NULL,
-	"scopes" jsonb NOT NULL,
-	"lease_epoch" bigint NOT NULL,
-	"acquired_at" timestamp with time zone NOT NULL,
-	"heartbeat_at" timestamp with time zone NOT NULL,
-	"expires_at" timestamp with time zone NOT NULL,
-	"released_at" timestamp with time zone,
-	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
-	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
-);
---> statement-breakpoint
-CREATE INDEX "connector_lease_audit_binding_occurred_idx" ON "connector_lease_audit_log" USING btree ("tenant_id","logical_agent_id","binding_id","occurred_at" DESC NULLS LAST);--> statement-breakpoint
-CREATE INDEX "connector_lease_audit_correlation_idx" ON "connector_lease_audit_log" USING btree ("correlation_id");--> statement-breakpoint
-CREATE UNIQUE INDEX "logical_agent_connector_lease_binding_idx" ON "logical_agent_connector_leases" USING btree ("tenant_id","logical_agent_id","binding_id");--> statement-breakpoint
-CREATE INDEX "logical_agent_connector_lease_expiry_idx" ON "logical_agent_connector_leases" USING btree ("expires_at");--> statement-breakpoint
-CREATE INDEX "logical_agent_connector_lease_connector_idx" ON "logical_agent_connector_leases" USING btree ("connector_id");

packages/db/drizzle/meta/_journal.json

@@ -113,13 +113,6 @@
       "when": 1783942610000,
       "tag": "0015_interaction_checkpoint_payload_digest",
       "breakpoints": true
-    },
-    {
-      "idx": 16,
-      "version": "7",
-      "when": 1784050648841,
-      "tag": "0016_salty_morlocks",
-      "breakpoints": true
     }
   ]
 }

packages/db/src/schema.ts

@@ -15,7 +15,6 @@ import {
   uniqueIndex,
   real,
   integer,
-  bigint,
   customType,
 } from 'drizzle-orm/pg-core';
 
@@ -488,68 +487,6 @@ export const agentLogs = pgTable(
   ],
 );
 
-// ─── Logical agent connector authority ──────────────────────────────────────
-// One durable row is the current authority for a tenant/logical-agent/binding.
-// Runtime-native session identifiers never enter these core tables.
-
-export const logicalAgentConnectorLeases = pgTable(
-  'logical_agent_connector_leases',
-  {
-    leaseId: uuid('lease_id').primaryKey(),
-    tenantId: text('tenant_id').notNull(),
-    logicalAgentId: text('logical_agent_id').notNull(),
-    bindingId: text('binding_id').notNull(),
-    connectorId: text('connector_id').notNull(),
-    scopes: jsonb('scopes').notNull().$type<string[]>(),
-    leaseEpoch: bigint('lease_epoch', { mode: 'bigint' }).notNull(),
-    acquiredAt: timestamp('acquired_at', { withTimezone: true }).notNull(),
-    heartbeatAt: timestamp('heartbeat_at', { withTimezone: true }).notNull(),
-    expiresAt: timestamp('expires_at', { withTimezone: true }).notNull(),
-    releasedAt: timestamp('released_at', { withTimezone: true }),
-    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
-    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
-  },
-  (t) => [
-    uniqueIndex('logical_agent_connector_lease_binding_idx').on(
-      t.tenantId,
-      t.logicalAgentId,
-      t.bindingId,
-    ),
-    index('logical_agent_connector_lease_expiry_idx').on(t.expiresAt),
-    index('logical_agent_connector_lease_connector_idx').on(t.connectorId),
-  ],
-);
-
-/** Append-only, credential-safe lease lifecycle and fencing denial metadata. */
-export const connectorLeaseAuditLog = pgTable(
-  'connector_lease_audit_log',
-  {
-    id: uuid('id').primaryKey().defaultRandom(),
-    tenantId: text('tenant_id').notNull(),
-    logicalAgentId: text('logical_agent_id').notNull(),
-    bindingId: text('binding_id').notNull(),
-    connectorId: text('connector_id').notNull(),
-    leaseId: uuid('lease_id'),
-    leaseEpoch: bigint('lease_epoch', { mode: 'bigint' }),
-    event: text('event', {
-      enum: ['acquire', 'renew', 'takeover', 'reject', 'release', 'expiry'],
-    }).notNull(),
-    outcome: text('outcome', { enum: ['succeeded', 'denied'] }).notNull(),
-    reason: text('reason'),
-    correlationId: text('correlation_id').notNull(),
-    occurredAt: timestamp('occurred_at', { withTimezone: true }).notNull(),
-  },
-  (t) => [
-    index('connector_lease_audit_binding_occurred_idx').on(
-      t.tenantId,
-      t.logicalAgentId,
-      t.bindingId,
-      t.occurredAt.desc(),
-    ),
-    index('connector_lease_audit_correlation_idx').on(t.correlationId),
-  ],
-);
-
 // ─── Tess durable session state ─────────────────────────────────────────────
 // PostgreSQL is canonical for restart-safe Tess session recovery. The state
 // machine lives in @mosaicstack/agent; these records are its durable adapter.

packages/mosaic/framework/fleet/roles/LIBRARY.md

@@ -12,22 +12,19 @@ on demand. Engineering personas have no explicit `domain:` marker (they are the
 implicit `engineering` domain); cross-domain personas carry a `domain:` key in
 their intro so tooling can group them.
 
-> This file is an index, not an authority source. The fleet persona resolver reads
+> This file is an index only — no code imports it. To add a persona, drop a new
-> its rows for discovery compatibility, then requires a readable `*.md` contract;
+> `*.md` next to the others (mirroring the existing structure) and add a row here.
-> authority is derived from canonical class metadata in code, never from this prose.
 
 ## engineering
 
 | Persona         | Purpose                                                                        |
 | --------------- | ------------------------------------------------------------------------------ |
 | orchestrator    | Always-on coordinator — runs the supervisor loop, dispatches ready work        |
-| team-leader     | Coordinates only orchestrator-leased capacity for one bounded project          |
 | board           | Multi-lens deliberation panel; owns the mission's direction, not its execution |
 | planner         | Turns ratified objectives into a phased FR plan wired into a `depends_on` DAG  |
 | decomposition   | Splits FRs into one-PR-each cards wired with `depends_on` edges                |
 | code            | Primary executor — one card, one branch, one PR to green CI                    |
 | review          | Correctness reviewer — judges an open PR on correctness, scope, and coverage   |
-| validator       | Independent final evidence certificate; never approves-to-land or merges       |
 | security-review | Second line of review — secrets, auth, and forbidden-path safety               |
 | site-tester     | Runtime verifier — runs the change and checks behavior vs. acceptance criteria |
 | documentation   | Prose maintainer — keeps human-facing docs and projections in sync             |
@@ -36,7 +33,6 @@ their intro so tooling can group them.
 | operator        | Escalation and control surface — owns exceptions and the fleet pause switch    |
 | session-review  | Post-task retrospective — turns finished work into improvement signals         |
 | enhancer        | Continuous-improvement loop — upgrades the fleet's tools, skills, and harness  |
-| interaction     | Operator request/status surface; routes orchestration and merge decisions      |
 
 ## executive
 

packages/mosaic/framework/fleet/roles/interaction.md

@@ -1,16 +0,0 @@
-# Interaction — fleet role definition
-
-The **interaction** role (`class: interaction`) is the operator-facing request and status surface for Mosaic.
-
-## Mandate
-
-1. Receive operator requests and present observable fleet or runtime status.
-2. Route orchestration requests to the orchestrator and merge decisions to the merge-gate.
-3. Report supported actions and their outcomes without claiming another role's authority.
-
-## Boundaries
-
-- Request/status only; it does not orchestrate, issue leases, approve-to-land, or merge.
-- It does not mutate roster configuration, role authority, or credentials.
-- A configured instance name such as Tess is display data, never a class or authority source.
-- `operator-interaction` remains a compatibility alias for this canonical class.

packages/mosaic/framework/fleet/roles/team-leader.md

@@ -1,16 +0,0 @@
-# Team leader — fleet role definition
-
-The **team-leader** (`class: team-leader`) coordinates a bounded project team using only capacity granted by an orchestrator-issued lease.
-
-## Mandate
-
-1. Direct the leased coder, reviewer, and validator capacity for the assigned project scope.
-2. Track delivery status and return results or blockers to the orchestrator.
-3. Stop using capacity when the lease or assignment ends.
-
-## Boundaries
-
-- Leased capacity only; this role does not issue or expand its own lease.
-- It cannot change fleet roster membership, role authority, fleet configuration, or credentials.
-- It cannot approve-to-land or merge.
-- It does not displace the orchestrator's topology and lease authority.

packages/mosaic/framework/fleet/roles/validator.md

@@ -1,16 +0,0 @@
-# Validator — fleet role definition
-
-The **validator** (`class: validator`) is the independent final evidence seat. It examines the accepted requirements, test evidence, review record, and candidate head and may issue a validation certificate for that exact evidence set.
-
-## Mandate
-
-1. Validate acceptance evidence independently from the implementation author.
-2. Issue or withhold a final validation certificate for the reviewed candidate.
-3. Report missing, stale, or contradictory evidence without altering it.
-
-## Boundaries
-
-- **Certificate only:** the validator does not approve-to-land or merge.
-- It does not replace correctness or security review.
-- It does not write product code, mutate the roster, issue leases, or access credentials.
-- A configured instance name such as Ultron is display data, never a class or authority source.

packages/mosaic/src/commands/fleet-personas.spec.ts

@@ -1,18 +1,13 @@
-import { cp, mkdir, mkdtemp, rm, symlink, writeFile } from 'node:fs/promises';
+import { cp, mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
-import { dirname, join, relative, resolve } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import {
-  authorityForCanonicalClass,
-  canonicalizeRoleClass,
   extractClassesFromDir,
-  extractClassesFromDirSync,
   listPersonaClasses,
   personaStatus,
   resolvePersona,
-  resolvePersonaFrom,
-  resolvePersonaSync,
 } from './fleet-personas.js';
 import { loadProfiles, validateProfile, type FleetProfile } from './fleet-profiles.js';
 
@@ -59,156 +54,13 @@ afterEach(async () => {
   await rm(tmp, { recursive: true, force: true });
 });
 
-describe('FCM class canonicalization and authority', () => {
-  it.each([
-    ['implementer', 'code'],
-    ['reviewer', 'review'],
-    ['operator-interaction', 'interaction'],
-  ])('canonicalizes the approved alias %s to %s', (requested: string, canonical: string) => {
-    expect(canonicalizeRoleClass(requested)).toEqual({
-      requestedClass: requested,
-      canonicalClass: canonical,
-    });
-  });
-
-  it.each(['worker', 'analyst', 'canary', 'tess', 'ultron', 'constructor'])(
-    'does not infer an alias for %s',
-    (requested: string) => {
-      expect(canonicalizeRoleClass(requested)).toEqual({
-        requestedClass: requested,
-        canonicalClass: requested,
-      });
-    },
-  );
-
-  it('resolves inherited-property class names without granting protected authority', async () => {
-    await mkdir(overrideDir, { recursive: true });
-    await writeFile(
-      join(overrideDir, 'constructor.md'),
-      overridePersona('constructor', 'custom'),
-      'utf8',
-    );
-
-    const resolved = await resolvePersona('constructor', { rolesDir, overrideDir });
-    expect(resolved).toMatchObject({
-      requestedClass: 'constructor',
-      canonicalClass: 'constructor',
-      klass: 'constructor',
-      layer: 'override',
-    });
-    expect(authorityForCanonicalClass('constructor')).toMatchObject({
-      mayMerge: false,
-      mayIssueValidationCertificate: false,
-      mayOrchestrate: false,
-    });
-  });
-
-  it('canonicalizes before override lookup and lets the canonical override win', async () => {
-    await mkdir(overrideDir, { recursive: true });
-    await writeFile(
-      join(overrideDir, 'implementer.md'),
-      overridePersona('implementer', 'legacy'),
-      'utf8',
-    );
-    await writeFile(
-      join(overrideDir, 'code.md'),
-      overridePersona('code', 'engineering', 'CANONICAL-OVERRIDE'),
-      'utf8',
-    );
-
-    const resolved = await resolvePersona('implementer', { rolesDir, overrideDir });
-    expect(resolved).toMatchObject({
-      requestedClass: 'implementer',
-      canonicalClass: 'code',
-      klass: 'code',
-      layer: 'override',
-    });
-    expect(resolved?.content).toContain('CANONICAL-OVERRIDE');
-    expect(resolved?.content).not.toContain('legacy');
-  });
-
-  it('keeps sync and async resolution equivalent for aliases and canonical overrides', async () => {
-    await mkdir(overrideDir, { recursive: true });
-    await writeFile(
-      join(overrideDir, 'code.md'),
-      overridePersona('code', 'engineering', 'CANONICAL-OVERRIDE'),
-      'utf8',
-    );
-
-    const asyncResolution = await resolvePersona('implementer', { rolesDir, overrideDir });
-    const syncResolution = resolvePersonaSync('implementer', { rolesDir, overrideDir });
-    expect(syncResolution).toEqual(asyncResolution);
-  });
-
-  it('derives immutable protected authority only from the canonical class', () => {
-    expect(authorityForCanonicalClass('merge-gate')).toMatchObject({ mayMerge: true });
-    for (const klass of [
-      'validator',
-      'orchestrator',
-      'team-leader',
-      'interaction',
-      'code',
-      'custom-role',
-    ]) {
-      expect(authorityForCanonicalClass(klass).mayMerge).toBe(false);
-    }
-    expect(authorityForCanonicalClass('validator')).toMatchObject({
-      mayIssueValidationCertificate: true,
-      mayMerge: false,
-    });
-    expect(authorityForCanonicalClass('orchestrator')).toMatchObject({
-      mayOrchestrate: true,
-      mayIssueLeases: true,
-      mayMerge: false,
-    });
-    expect(authorityForCanonicalClass('team-leader')).toMatchObject({
-      leasedCapacityOnly: true,
-      mayMutateRoster: false,
-      mayAccessCredentials: false,
-      mayMerge: false,
-    });
-    expect(authorityForCanonicalClass('interaction')).toMatchObject({
-      requestStatusOnly: true,
-      mayOrchestrate: false,
-      mayMerge: false,
-    });
-    expect(Object.isFrozen(authorityForCanonicalClass('merge-gate'))).toBe(true);
-  });
-});
-
-describe('required FCM role library', () => {
-  it.each([
-    'code',
-    'review',
-    'validator',
-    'orchestrator',
-    'team-leader',
-    'enhancer',
-    'interaction',
-    'merge-gate',
-  ])('resolves %s through the real framework role library', async (klass: string) => {
-    const resolved = await resolvePersona(klass, {
-      rolesDir: realRolesDir,
-      overrideDir: join(tmp, 'none'),
-    });
-    expect(resolved).not.toBeNull();
-    expect(resolved?.canonicalClass).toBe(klass);
-    expect(resolved?.content.trim()).not.toBe('');
-  });
-});
-
 describe('extractClassesFromDir (shared extraction)', () => {
-  it('records class + domain and distinguishes scanned from missing directories', async () => {
+  it('records class + domain from inline markers and degrades on missing dir', async () => {
     const base = await extractClassesFromDir(rolesDir);
-    expect(base.scanState).toBe('scanned');
     expect(base.classes.has('ceo')).toBe(true);
     expect(base.byClass.get('ceo')?.domain).toBe('executive');
-
+    const missing = await extractClassesFromDir(join(tmp, 'nope'));
-    const missingDir = join(tmp, 'nope');
-    const missing = await extractClassesFromDir(missingDir);
-    expect(missing.scanState).toBe('missing');
     expect(missing.classes.size).toBe(0);
-    expect(extractClassesFromDirSync(missingDir).scanState).toBe('missing');
   });
 });
 
@@ -229,287 +81,6 @@ describe('resolvePersona — override wins', () => {
     expect(resolved?.content).toContain('BASELINE');
   });
 
-  it('does not let a LIBRARY-only row shadow a readable baseline persona', async () => {
-    await mkdir(overrideDir, { recursive: true });
-    await writeFile(
-      join(overrideDir, 'LIBRARY.md'),
-      '| Persona | Purpose |\n| --- | --- |\n| code | Index only |\n',
-      'utf8',
-    );
-
-    const resolved = await resolvePersona('code', { rolesDir, overrideDir });
-    expect(resolved?.layer).toBe('baseline');
-    expect(resolved?.content).toContain('BASELINE');
-    expect((await listPersonaClasses({ rolesDir, overrideDir })).has('code')).toBe(true);
-    expect(
-      (await personaStatus({ rolesDir, overrideDir })).find(({ klass }) => klass === 'code')
-        ?.status,
-    ).toBe('baseline');
-  });
-
-  it('does not let an incidental later class marker shadow a readable baseline persona', async () => {
-    await mkdir(overrideDir, { recursive: true });
-    await writeFile(
-      join(overrideDir, 'mascot.md'),
-      '# mascot\n\n(`class: mascot`)\n\nSee also (`class: code`).\n',
-      'utf8',
-    );
-
-    const resolved = await resolvePersona('code', { rolesDir, overrideDir });
-    expect(resolved?.layer).toBe('baseline');
-    expect(resolved?.content).toContain('BASELINE');
-    expect((await listPersonaClasses({ rolesDir, overrideDir })).has('code')).toBe(true);
-    expect((await listPersonaClasses({ rolesDir, overrideDir })).has('mascot')).toBe(true);
-    expect(
-      (await personaStatus({ rolesDir, overrideDir })).find(({ klass }) => klass === 'code')
-        ?.status,
-    ).toBe('baseline');
-  });
-
-  it('does not advertise an incidental-only class through listing or status APIs', async () => {
-    await mkdir(overrideDir, { recursive: true });
-    await writeFile(
-      join(overrideDir, 'mascot.md'),
-      '# mascot\n\n(`class: mascot`)\n\nSee also (`class: phantom`).\n',
-      'utf8',
-    );
-
-    expect((await listPersonaClasses({ rolesDir, overrideDir })).has('phantom')).toBe(false);
-    expect(
-      (await personaStatus({ rolesDir, overrideDir })).some(({ klass }) => klass === 'phantom'),
-    ).toBe(false);
-  });
-
-  it('rejects a canonical filename whose explicit marker names another class', async () => {
-    await mkdir(overrideDir, { recursive: true });
-    await writeFile(join(overrideDir, 'merge-gate.md'), overridePersona('mascot', 'fun'), 'utf8');
-    await writeFile(
-      join(rolesDir, 'merge-gate.md'),
-      baselinePersona('merge-gate', 'governance'),
-      'utf8',
-    );
-
-    expect(await resolvePersona('merge-gate', { rolesDir, overrideDir })).toBeNull();
-    expect(resolvePersonaSync('merge-gate', { rolesDir, overrideDir })).toBeNull();
-    expect((await listPersonaClasses({ rolesDir, overrideDir })).has('merge-gate')).toBe(false);
-    expect(
-      (await personaStatus({ rolesDir, overrideDir })).some(({ klass }) => klass === 'merge-gate'),
-    ).toBe(false);
-  });
-
-  it('fails closed if a marker-defined override becomes unreadable after extraction', async () => {
-    await mkdir(overrideDir, { recursive: true });
-    const overrideFile = join(overrideDir, 'engineering.md');
-    await writeFile(overrideFile, overridePersona('code', 'engineering'), 'utf8');
-    const [base, over] = await Promise.all([
-      extractClassesFromDir(rolesDir),
-      extractClassesFromDir(overrideDir),
-    ]);
-    await rm(overrideFile);
-    await mkdir(overrideFile);
-
-    expect(await resolvePersonaFrom('code', { rolesDir, overrideDir, base, over })).toBeNull();
-  });
-
-  it('fails closed if a marker-defined override changes identity after extraction', async () => {
-    await mkdir(overrideDir, { recursive: true });
-    const overrideFile = join(overrideDir, 'engineering.md');
-    await writeFile(overrideFile, overridePersona('code', 'engineering'), 'utf8');
-    const [base, over] = await Promise.all([
-      extractClassesFromDir(rolesDir),
-      extractClassesFromDir(overrideDir),
-    ]);
-    await writeFile(overrideFile, overridePersona('mascot', 'fun'), 'utf8');
-
-    expect(await resolvePersonaFrom('code', { rolesDir, overrideDir, base, over })).toBeNull();
-
-    const classes = await listPersonaClasses({ rolesDir, overrideDir });
-    expect(classes.has('code')).toBe(true);
-    expect(classes.has('mascot')).toBe(true);
-    const status = new Map(
-      (await personaStatus({ rolesDir, overrideDir })).map((entry) => [entry.klass, entry]),
-    );
-    expect(status.get('code')?.status).toBe('baseline');
-    expect(status.get('mascot')?.status).toBe('custom');
-  });
-
-  it('fails closed if a markerless cached override gains a conflicting marker', async () => {
-    await mkdir(overrideDir, { recursive: true });
-    const overrideFile = join(overrideDir, 'merge-gate.md');
-    await writeFile(overrideFile, '# markerless merge gate\n', 'utf8');
-    await writeFile(
-      join(rolesDir, 'merge-gate.md'),
-      baselinePersona('merge-gate', 'governance'),
-      'utf8',
-    );
-    const [base, over] = await Promise.all([
-      extractClassesFromDir(rolesDir),
-      extractClassesFromDir(overrideDir),
-    ]);
-    await writeFile(overrideFile, overridePersona('mascot', 'fun'), 'utf8');
-
-    expect(
-      await resolvePersonaFrom('merge-gate', { rolesDir, overrideDir, base, over }),
-    ).toBeNull();
-  });
-
-  it('fails closed asynchronously when the override directory cannot be scanned', async () => {
-    await writeFile(overrideDir, 'not a directory', 'utf8');
-    expect(await resolvePersona('code', { rolesDir, overrideDir })).toBeNull();
-  });
-
-  it('fails closed synchronously when the override directory cannot be scanned', async () => {
-    await writeFile(overrideDir, 'not a directory', 'utf8');
-    expect(resolvePersonaSync('code', { rolesDir, overrideDir })).toBeNull();
-  });
-
-  it('fails closed asynchronously and synchronously for a dangling override-directory symlink', async () => {
-    await symlink(join(tmp, 'missing-override-target'), overrideDir, 'dir');
-
-    expect(await resolvePersona('code', { rolesDir, overrideDir })).toBeNull();
-    expect(resolvePersonaSync('code', { rolesDir, overrideDir })).toBeNull();
-  });
-
-  it('fails closed asynchronously and synchronously when an override ancestor is a dangling symlink', async () => {
-    const danglingAncestor = join(tmp, 'dangling-ancestor');
-    await symlink(join(tmp, 'missing-ancestor-target'), danglingAncestor, 'dir');
-    overrideDir = join(danglingAncestor, 'nested', 'roles.local');
-
-    expect(await resolvePersona('code', { rolesDir, overrideDir })).toBeNull();
-    expect(resolvePersonaSync('code', { rolesDir, overrideDir })).toBeNull();
-    expect(await listPersonaClasses({ rolesDir, overrideDir })).toEqual(new Set());
-    expect(await personaStatus({ rolesDir, overrideDir })).toEqual([]);
-  });
-
-  it('fails closed when dot-dot traversal crosses a dangling override ancestor', async () => {
-    const danglingAncestor = join(tmp, 'dangling-dotdot-ancestor');
-    await symlink(join(tmp, 'missing-dotdot-target'), danglingAncestor, 'dir');
-    overrideDir = `${danglingAncestor}/../roles.local`;
-
-    expect(await resolvePersona('code', { rolesDir, overrideDir })).toBeNull();
-    expect(resolvePersonaSync('code', { rolesDir, overrideDir })).toBeNull();
-    expect(await listPersonaClasses({ rolesDir, overrideDir })).toEqual(new Set());
-    expect(await personaStatus({ rolesDir, overrideDir })).toEqual([]);
-  });
-
-  it('fails closed when relative dot-dot traversal crosses a dangling override ancestor', async () => {
-    const danglingAncestor = join(tmp, 'relative-dangling-ancestor');
-    await symlink(join(tmp, 'missing-relative-target'), danglingAncestor, 'dir');
-    overrideDir = `${relative(process.cwd(), danglingAncestor)}/../roles.local`;
-    expect(overrideDir.startsWith('/')).toBe(false);
-
-    expect(await resolvePersona('code', { rolesDir, overrideDir })).toBeNull();
-    expect(resolvePersonaSync('code', { rolesDir, overrideDir })).toBeNull();
-    expect(await listPersonaClasses({ rolesDir, overrideDir })).toEqual(new Set());
-    expect(await personaStatus({ rolesDir, overrideDir })).toEqual([]);
-  });
-
-  it('revalidates a cached missing override before baseline fallback', async () => {
-    const cachedOverrideDir = join(tmp, 'mutable-ancestor', 'roles.local');
-    const [base, over] = await Promise.all([
-      extractClassesFromDir(rolesDir),
-      extractClassesFromDir(cachedOverrideDir),
-    ]);
-    expect(over.scanState).toBe('missing');
-    await symlink(join(tmp, 'missing-mutable-target'), join(tmp, 'mutable-ancestor'), 'dir');
-
-    expect(
-      await resolvePersonaFrom('code', {
-        rolesDir,
-        overrideDir: cachedOverrideDir,
-        base,
-        over,
-      }),
-    ).toBeNull();
-  });
-
-  it('revalidates a cached scanned override before baseline fallback', async () => {
-    await mkdir(overrideDir, { recursive: true });
-    const [base, over] = await Promise.all([
-      extractClassesFromDir(rolesDir),
-      extractClassesFromDir(overrideDir),
-    ]);
-    expect(over.scanState).toBe('scanned');
-    expect(over.classes.size).toBe(0);
-
-    await writeFile(join(overrideDir, 'engineering.md'), overridePersona('code', 'engineering'));
-
-    const resolved = await resolvePersonaFrom('code', {
-      rolesDir,
-      overrideDir,
-      base,
-      over,
-    });
-    expect(resolved?.layer).toBe('override');
-    expect(resolved?.file).toBe(join(overrideDir, 'engineering.md'));
-  });
-
-  it('falls back to baseline asynchronously and synchronously when override directory is missing', async () => {
-    const asyncResolution = await resolvePersona('code', { rolesDir, overrideDir });
-    const syncResolution = resolvePersonaSync('code', { rolesDir, overrideDir });
-    expect(asyncResolution?.layer).toBe('baseline');
-    expect(syncResolution?.layer).toBe('baseline');
-  });
-
-  it('fails closed asynchronously when the canonical override exists but is unreadable', async () => {
-    await mkdir(overrideDir, { recursive: true });
-    await mkdir(join(overrideDir, 'code.md'));
-
-    expect(await resolvePersona('code', { rolesDir, overrideDir })).toBeNull();
-  });
-
-  it('does not advertise a shadowed baseline whose canonical override is unreadable', async () => {
-    await mkdir(overrideDir, { recursive: true });
-    await mkdir(join(overrideDir, 'code.md'));
-
-    expect((await listPersonaClasses({ rolesDir, overrideDir })).has('code')).toBe(false);
-    expect(
-      (await personaStatus({ rolesDir, overrideDir })).some(({ klass }) => klass === 'code'),
-    ).toBe(false);
-  });
-
-  it('does not advertise baseline personas when the override directory is unscannable', async () => {
-    await writeFile(overrideDir, 'not a directory', 'utf8');
-
-    expect(await listPersonaClasses({ rolesDir, overrideDir })).toEqual(new Set());
-    expect(await personaStatus({ rolesDir, overrideDir })).toEqual([]);
-  });
-
-  it('does not advertise baseline personas through a dangling override-directory symlink', async () => {
-    await symlink(join(tmp, 'missing-override-target'), overrideDir, 'dir');
-
-    expect(await listPersonaClasses({ rolesDir, overrideDir })).toEqual(new Set());
-    expect(await personaStatus({ rolesDir, overrideDir })).toEqual([]);
-  });
-
-  it('preserves baseline listings when the override directory is missing', async () => {
-    expect((await listPersonaClasses({ rolesDir, overrideDir })).has('code')).toBe(true);
-    expect(
-      (await personaStatus({ rolesDir, overrideDir })).find(({ klass }) => klass === 'code')
-        ?.status,
-    ).toBe('baseline');
-  });
-
-  it('does not advertise an unreadable custom override as a valid persona class or status', async () => {
-    await mkdir(overrideDir, { recursive: true });
-    await mkdir(join(overrideDir, 'ghost.md'));
-
-    const extracted = await extractClassesFromDir(overrideDir);
-    expect(extracted.fileStems.has('ghost')).toBe(true);
-    expect(extracted.classes.has('ghost')).toBe(false);
-    expect((await listPersonaClasses({ rolesDir, overrideDir })).has('ghost')).toBe(false);
-    expect(
-      (await personaStatus({ rolesDir, overrideDir })).some(({ klass }) => klass === 'ghost'),
-    ).toBe(false);
-  });
-
-  it('fails closed synchronously when the canonical override exists but is unreadable', async () => {
-    await mkdir(overrideDir, { recursive: true });
-    await mkdir(join(overrideDir, 'code.md'));
-
-    expect(resolvePersonaSync('code', { rolesDir, overrideDir })).toBeNull();
-  });
-
   it('returns null for an unknown class', async () => {
     expect(await resolvePersona('does-not-exist', { rolesDir, overrideDir })).toBeNull();
   });

packages/mosaic/src/commands/fleet-personas.ts

@@ -25,10 +25,10 @@
  * can reference a customized or user-added persona.
  */
 
-import { lstatSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { readFileSync, readdirSync } from 'node:fs';
-import { lstat, readFile, readdir, stat } from 'node:fs/promises';
+import { readFile, readdir } from 'node:fs/promises';
 import { homedir } from 'node:os';
-import { basename, isAbsolute, join, sep } from 'node:path';
+import { basename, join } from 'node:path';
 import type { Command } from 'commander';
 
 function defaultMosaicHome(): string {
@@ -53,136 +53,52 @@ export function defaultOverrideDir(mosaicHome = defaultMosaicHome()): string {
 const CLASS_MARKER = /`?class:\s*\n?\s*([a-z][a-z0-9-]*)`?/g;
 /** Optional `domain: Y` marker that travels alongside the class in the prose. */
 const DOMAIN_MARKER = /`?domain:\s*\n?\s*([a-z][a-z0-9-]*)`?/;
+/** LIBRARY.md persona rows: the first table cell is the persona name. */
+const LIBRARY_ROW = /^\|\s*([a-z][a-z0-9-]*)\s*\|/gm;
 
 /** Where a resolved persona's definition came from. */
 export type PersonaLayer = 'baseline' | 'override';
 
-export const ROLE_CLASS_ALIASES = Object.freeze({
-  implementer: 'code',
-  reviewer: 'review',
-  'operator-interaction': 'interaction',
-} as const);
-
-export interface CanonicalRoleClass {
-  readonly requestedClass: string;
-  readonly canonicalClass: string;
-}
-
-/** Canonicalize only the three explicitly approved compatibility aliases. */
-export function canonicalizeRoleClass(requestedClass: string): CanonicalRoleClass {
-  const requested = requestedClass.trim();
-  const canonical = Object.hasOwn(ROLE_CLASS_ALIASES, requested)
-    ? ROLE_CLASS_ALIASES[requested as keyof typeof ROLE_CLASS_ALIASES]
-    : requested;
-  return Object.freeze({ requestedClass: requested, canonicalClass: canonical });
-}
-
-export interface RoleAuthority {
-  readonly mayMerge: boolean;
-  readonly mayIssueValidationCertificate: boolean;
-  readonly mayOrchestrate: boolean;
-  readonly mayManageTopology: boolean;
-  readonly mayIssueLeases: boolean;
-  readonly leasedCapacityOnly: boolean;
-  readonly requestStatusOnly: boolean;
-  readonly mayMutateRoster: boolean;
-  readonly mayMutateConfiguration: boolean;
-  readonly mayAccessCredentials: boolean;
-}
-
-const NO_PROTECTED_AUTHORITY: RoleAuthority = Object.freeze({
-  mayMerge: false,
-  mayIssueValidationCertificate: false,
-  mayOrchestrate: false,
-  mayManageTopology: false,
-  mayIssueLeases: false,
-  leasedCapacityOnly: false,
-  requestStatusOnly: false,
-  mayMutateRoster: false,
-  mayMutateConfiguration: false,
-  mayAccessCredentials: false,
-});
-
-/** Immutable authority contracts keyed only by canonical class identity. */
-export const ROLE_AUTHORITY_BY_CANONICAL_CLASS: Readonly<Record<string, RoleAuthority>> =
-  Object.freeze({
-    'merge-gate': Object.freeze({ ...NO_PROTECTED_AUTHORITY, mayMerge: true }),
-    validator: Object.freeze({
-      ...NO_PROTECTED_AUTHORITY,
-      mayIssueValidationCertificate: true,
-    }),
-    orchestrator: Object.freeze({
-      ...NO_PROTECTED_AUTHORITY,
-      mayOrchestrate: true,
-      mayManageTopology: true,
-      mayIssueLeases: true,
-    }),
-    'team-leader': Object.freeze({ ...NO_PROTECTED_AUTHORITY, leasedCapacityOnly: true }),
-    interaction: Object.freeze({ ...NO_PROTECTED_AUTHORITY, requestStatusOnly: true }),
-  });
-
-/** Return protected authority for an already-canonical class; custom classes get none. */
-export function authorityForCanonicalClass(canonicalClass: string): RoleAuthority {
-  return Object.hasOwn(ROLE_AUTHORITY_BY_CANONICAL_CLASS, canonicalClass)
-    ? ROLE_AUTHORITY_BY_CANONICAL_CLASS[canonicalClass]!
-    : NO_PROTECTED_AUTHORITY;
-}
-
 /** One discovered persona file (a single role contract on disk). */
 export interface PersonaFile {
   klass: string;
   /** The markdown file the class was found in. */
   file: string;
-  /** True when the first class marker, rather than filename, defined this mapping. */
-  markerDefined?: boolean;
   domain?: string;
 }
 
-export type DirScanState = 'scanned' | 'missing' | 'error';
-
 /** The set of persona classes a directory of role contracts defines. */
 export interface DirClasses {
-  /** Whether the directory was scanned, absent, or present-but-unscannable. */
+  /** Every class name the dir contributes (markers + filenames + LIBRARY rows). */
-  scanState: DirScanState;
-  /** Every readable class name the directory contributes by filename or first marker. */
   classes: Set<string>;
-  /** Filename stems present on disk, retained even when a markdown entry is unreadable. */
-  fileStems: Set<string>;
   /** For classes whose file carries a marker, the file + domain that defined it. */
   byClass: Map<string, PersonaFile>;
 }
 
 /**
- * Scan one directory of role contracts and extract readable persona identities.
+ * Scan one directory of role contracts and extract the persona classes it
- * Valid identities come only from a successfully read non-LIBRARY filename and
+ * defines. THIS is the shared extraction both fleet-personas and fleet-profiles
- * that file's first `class:` marker. LIBRARY rows and later prose mentions are
+ * rely on. Sources, unioned (each needed — see module doc):
- * index/reference data, not independently readable role contracts.
+ *   1. inline `class: X` markers in roles/*.md (primary; may wrap a newline),
+ *   2. persona-name cells from LIBRARY.md index tables,
+ *   3. the role filename stem (covers marker-less alias docs like planner).
  *
- * Missing directories are distinguished from present-but-unscannable paths.
+ * Missing dir / unreadable files degrade gracefully to whatever was found.
- * `byClass` records the first marker-defined file+domain so the resolver can map
+ * `byClass` records the defining file+domain for marker-bearing classes so the
- * a class back to its contract; marker-less readable files map by filename.
+ * resolver can map a class back to its file; filename-only and LIBRARY-only
+ * classes still appear in `classes` for membership checks.
  */
 export async function extractClassesFromDir(dir: string): Promise<DirClasses> {
-  const acc: DirClasses = {
+  const acc: DirClasses = { classes: new Set<string>(), byClass: new Map<string, PersonaFile>() };
-    scanState: 'scanned',
-    classes: new Set<string>(),
-    fileStems: new Set<string>(),
-    byClass: new Map<string, PersonaFile>(),
-  };
   let entries: string[];
   try {
     entries = await readdir(dir);
-  } catch (error) {
+  } catch {
-    acc.scanState = await classifyScanFailure(dir, error);
     return acc;
   }
 
   for (const entry of entries) {
     if (!entry.endsWith('.md')) continue;
-    // Preserve entry presence separately from valid readable classes. Resolvers
-    // use it to fail closed on an explicit unreadable canonical override without
-    // advertising that override through class listing/status APIs.
-    if (entry !== 'LIBRARY.md') acc.fileStems.add(basename(entry, '.md'));
     let text: string;
     try {
       text = await readFile(join(dir, entry), 'utf8');
@@ -201,25 +117,16 @@ export async function extractClassesFromDir(dir: string): Promise<DirClasses> {
  * cannot await. Missing dir / unreadable files degrade gracefully.
  */
 export function extractClassesFromDirSync(dir: string): DirClasses {
-  const acc: DirClasses = {
+  const acc: DirClasses = { classes: new Set<string>(), byClass: new Map<string, PersonaFile>() };
-    scanState: 'scanned',
-    classes: new Set<string>(),
-    fileStems: new Set<string>(),
-    byClass: new Map<string, PersonaFile>(),
-  };
   let entries: string[];
   try {
     entries = readdirSync(dir);
-  } catch (error) {
+  } catch {
-    acc.scanState = classifyScanFailureSync(dir, error);
     return acc;
   }
 
   for (const entry of entries) {
     if (!entry.endsWith('.md')) continue;
-    // Keep sync extraction equivalent to the async scanner, including unreadable
-    // filename presence kept separate from valid readable classes.
-    if (entry !== 'LIBRARY.md') acc.fileStems.add(basename(entry, '.md'));
     let text: string;
     try {
       text = readFileSync(join(dir, entry), 'utf8');
@@ -231,74 +138,6 @@ export function extractClassesFromDirSync(dir: string): DirClasses {
   return acc;
 }
 
-async function classifyScanFailure(dir: string, error: unknown): Promise<DirScanState> {
-  if (!isMissingPathError(error)) return 'error';
-  return (await hasBrokenSymlinkInPath(dir)) ? 'error' : 'missing';
-}
-
-function classifyScanFailureSync(dir: string, error: unknown): DirScanState {
-  if (!isMissingPathError(error)) return 'error';
-  return hasBrokenSymlinkInPathSync(dir) ? 'error' : 'missing';
-}
-
-function traversalPrefixes(path: string): string[] {
-  const absolute = isAbsolute(path) ? path : `${process.cwd()}${sep}${path}`;
-  const parts = absolute.split(sep);
-  const prefixes: string[] = [];
-  let current: string = sep;
-  for (const part of parts) {
-    if (!part) continue;
-    current = current === sep ? `${sep}${part}` : `${current}${sep}${part}`;
-    prefixes.push(current);
-  }
-  return prefixes;
-}
-
-async function hasBrokenSymlinkInPath(path: string): Promise<boolean> {
-  for (const current of traversalPrefixes(path)) {
-    try {
-      const entry = await lstat(current);
-      if (entry.isSymbolicLink()) {
-        try {
-          await stat(current);
-        } catch {
-          return true;
-        }
-      }
-    } catch (error) {
-      if (!isMissingPathError(error)) return true;
-    }
-  }
-  return false;
-}
-
-function hasBrokenSymlinkInPathSync(path: string): boolean {
-  for (const current of traversalPrefixes(path)) {
-    try {
-      const entry = lstatSync(current);
-      if (entry.isSymbolicLink()) {
-        try {
-          statSync(current);
-        } catch {
-          return true;
-        }
-      }
-    } catch (error) {
-      if (!isMissingPathError(error)) return true;
-    }
-  }
-  return false;
-}
-
-function isMissingPathError(error: unknown): boolean {
-  return (
-    typeof error === 'object' &&
-    error !== null &&
-    'code' in error &&
-    (error as { code?: unknown }).code === 'ENOENT'
-  );
-}
-
 /**
  * Apply the class-extraction rules for ONE role file's text into `acc`. Pure
  * over already-read content, so the async and sync directory scanners share a
@@ -307,26 +146,33 @@ function isMissingPathError(error: unknown): boolean {
  */
 function accumulateEntry(acc: DirClasses, dir: string, entry: string, text: string): void {
   const { classes, byClass } = acc;
-  if (entry === 'LIBRARY.md') return;
+  if (entry === 'LIBRARY.md') {
-
+    for (const m of text.matchAll(LIBRARY_ROW)) {
-  // An explicit first marker owns identity. Filename identity is a fallback only
+      const name = m[1];
-  // for markerless compatibility contracts such as planner.md.
+      if (name && name !== 'persona') classes.add(name);
+    }
+    return;
+  }
+  // The filename stem is itself a valid class (covers marker-less alias docs).
   const stem = basename(entry, '.md');
+  classes.add(stem);
   const domainMatch = DOMAIN_MARKER.exec(text);
   const domain = domainMatch?.[1];
-  const firstMarker = text.matchAll(CLASS_MARKER).next().value as RegExpExecArray | undefined;
+  let markedClassForFile: string | undefined;
-  const markedClassForFile = firstMarker?.[1];
+  for (const m of text.matchAll(CLASS_MARKER)) {
-  if (markedClassForFile) {
+    const klass = m[1];
-    classes.add(markedClassForFile);
+    if (!klass) continue;
-    byClass.set(markedClassForFile, {
+    classes.add(klass);
-      klass: markedClassForFile,
+    // Record the FIRST marker as the file's defining class (the prose names
-      file: join(dir, entry),
+    // the persona's own class up top; later mentions reference siblings).
-      markerDefined: true,
+    if (!markedClassForFile) {
-      ...(domain ? { domain } : {}),
+      markedClassForFile = klass;
-    });
+      byClass.set(klass, { klass, file: join(dir, entry), ...(domain ? { domain } : {}) });
-  } else {
+    }
-    classes.add(stem);
+  }
-    if (!byClass.has(stem)) byClass.set(stem, { klass: stem, file: join(dir, entry) });
+  // A marker-less file still maps its stem to itself (no domain known).
+  if (!markedClassForFile && !byClass.has(stem)) {
+    byClass.set(stem, { klass: stem, file: join(dir, entry) });
   }
 }
 
@@ -347,19 +193,24 @@ function resolveDirs(opts: PersonaDirs): { rolesDir: string; overrideDir: string
 }
 
 /**
- * Every class with an actually readable winning contract. Discovery applies the
+ * UNION of baseline classes and override classes. Overrides may ADD entirely new
- * same override shadow/fail-closed semantics as resolution, so callers never
+ * classes not present in the baseline, so callers (e.g. profile roster
- * advertise a class that cannot be used.
+ * validation) treat a user-added persona as a real class.
  */
 export async function listPersonaClasses(opts: PersonaDirs = {}): Promise<Set<string>> {
-  const { personas } = await collectUsablePersonas(opts);
+  const { rolesDir, overrideDir } = resolveDirs(opts);
-  return new Set(personas.keys());
+  const [base, over] = await Promise.all([
+    extractClassesFromDir(rolesDir),
+    extractClassesFromDir(overrideDir),
+  ]);
+  const union = new Set<string>(base.classes);
+  for (const c of over.classes) union.add(c);
+  return union;
 }
 
 export type PersonaStatus = 'baseline' | 'overridden' | 'custom';
 
-export interface PersonaResolution extends CanonicalRoleClass {
+export interface PersonaResolution {
-  /** Compatibility name for the canonical class. */
   klass: string;
   layer: PersonaLayer;
   /** The file the resolved persona was read from (override wins). */
@@ -368,118 +219,6 @@ export interface PersonaResolution extends CanonicalRoleClass {
   domain?: string;
 }
 
-async function readPersonaFromLayer(
-  requestedClass: string,
-  canonicalClass: string,
-  dir: string,
-  extracted: DirClasses,
-  layer: PersonaLayer,
-): Promise<PersonaResolution | null> {
-  const pf = extracted.byClass.get(canonicalClass);
-  if (!pf) {
-    if (!extracted.classes.has(canonicalClass)) return null;
-    const byName = join(dir, `${canonicalClass}.md`);
-    try {
-      const content = await readFile(byName, 'utf8');
-      const currentMarker = content.matchAll(CLASS_MARKER).next().value as
-        | RegExpExecArray
-        | undefined;
-      if (currentMarker && currentMarker[1] !== canonicalClass) return null;
-      const dm = DOMAIN_MARKER.exec(content);
-      return {
-        requestedClass,
-        canonicalClass,
-        klass: canonicalClass,
-        layer,
-        file: byName,
-        content,
-        ...(dm?.[1] ? { domain: dm[1] } : {}),
-      };
-    } catch {
-      return null;
-    }
-  }
-  try {
-    const content = await readFile(pf.file, 'utf8');
-    const currentMarker = content.matchAll(CLASS_MARKER).next().value as
-      | RegExpExecArray
-      | undefined;
-    if (currentMarker && currentMarker[1] !== canonicalClass) return null;
-    const dm = DOMAIN_MARKER.exec(content);
-    return {
-      requestedClass,
-      canonicalClass,
-      klass: canonicalClass,
-      layer,
-      file: pf.file,
-      content,
-      ...(dm?.[1] ? { domain: dm[1] } : {}),
-    };
-  } catch {
-    return null;
-  }
-}
-
-function overrideShadowsBaseline(over: DirClasses, canonicalClass: string): boolean {
-  return (
-    over.scanState === 'error' ||
-    over.fileStems.has(canonicalClass) ||
-    over.byClass.has(canonicalClass)
-  );
-}
-
-function readPersonaFromLayerSync(
-  requestedClass: string,
-  canonicalClass: string,
-  dir: string,
-  extracted: DirClasses,
-  layer: PersonaLayer,
-): PersonaResolution | null {
-  const pf = extracted.byClass.get(canonicalClass);
-  if (!pf) {
-    if (!extracted.classes.has(canonicalClass)) return null;
-    const byName = join(dir, `${canonicalClass}.md`);
-    try {
-      const content = readFileSync(byName, 'utf8');
-      const currentMarker = content.matchAll(CLASS_MARKER).next().value as
-        | RegExpExecArray
-        | undefined;
-      if (currentMarker && currentMarker[1] !== canonicalClass) return null;
-      const dm = DOMAIN_MARKER.exec(content);
-      return {
-        requestedClass,
-        canonicalClass,
-        klass: canonicalClass,
-        layer,
-        file: byName,
-        content,
-        ...(dm?.[1] ? { domain: dm[1] } : {}),
-      };
-    } catch {
-      return null;
-    }
-  }
-  try {
-    const content = readFileSync(pf.file, 'utf8');
-    const currentMarker = content.matchAll(CLASS_MARKER).next().value as
-      | RegExpExecArray
-      | undefined;
-    if (currentMarker && currentMarker[1] !== canonicalClass) return null;
-    const dm = DOMAIN_MARKER.exec(content);
-    return {
-      requestedClass,
-      canonicalClass,
-      klass: canonicalClass,
-      layer,
-      file: pf.file,
-      content,
-      ...(dm?.[1] ? { domain: dm[1] } : {}),
-    };
-  } catch {
-    return null;
-  }
-}
-
 /**
  * Resolve a persona class to its winning definition: the override file if
  * roles.local/ defines that class, else the baseline. Match by inline `class:`
@@ -506,32 +245,42 @@ export async function resolvePersona(
  * is identical to {@link resolvePersona}: override layer wins, then baseline.
  */
 export async function resolvePersonaFrom(
-  requestedClass: string,
+  klass: string,
   layers: { rolesDir: string; overrideDir: string; base: DirClasses; over: DirClasses },
 ): Promise<PersonaResolution | null> {
-  const { requestedClass: requested, canonicalClass: klass } =
-    canonicalizeRoleClass(requestedClass);
   const { rolesDir, overrideDir, base, over } = layers;
 
-  const override = await readPersonaFromLayer(requested, klass, overrideDir, over, 'override');
+  const fromLayer = async (
-  if (override) return override;
+    dir: string,
-  // An observed explicit override that cannot resolve/read shadows the baseline.
+    extracted: DirClasses,
-  if (overrideShadowsBaseline(over, klass)) return null;
+    layer: PersonaLayer,
+  ): Promise<PersonaResolution | null> => {
+    // Prefer the marker-defined file; fall back to the filename stem.
+    let pf = extracted.byClass.get(klass);
+    if (!pf) {
+      const byName = join(dir, `${klass}.md`);
+      if (!extracted.classes.has(klass)) return null;
+      // Class known only via filename/LIBRARY: read the stem file if present.
+      try {
+        const content = await readFile(byName, 'utf8');
+        const dm = DOMAIN_MARKER.exec(content);
+        return { klass, layer, file: byName, content, ...(dm?.[1] ? { domain: dm[1] } : {}) };
+      } catch {
+        return null;
+      }
+    }
+    try {
+      const content = await readFile(pf.file, 'utf8');
+      return { klass, layer, file: pf.file, content, ...(pf.domain ? { domain: pf.domain } : {}) };
+    } catch {
+      return null;
+    }
+  };
 
-  // Cached scans are only snapshots. Re-scan immediately before baseline fallback
+  return (
-  // so a newly created canonical or marker-defined override cannot be skipped.
+    (await fromLayer(overrideDir, over, 'override')) ??
-  const currentOver = await extractClassesFromDir(overrideDir);
+    (await fromLayer(rolesDir, base, 'baseline'))
-  const currentOverride = await readPersonaFromLayer(
-    requested,
-    klass,
-    overrideDir,
-    currentOver,
-    'override',
   );
-  if (currentOverride) return currentOverride;
-  if (overrideShadowsBaseline(currentOver, klass)) return null;
-  if (currentOver.scanState === 'error') return null;
-  return readPersonaFromLayer(requested, klass, rolesDir, base, 'baseline');
 }
 
 /**
@@ -543,55 +292,40 @@ export async function resolvePersonaFrom(
  * one module so the launch-time and command-time resolutions never diverge.
  */
 export function resolvePersonaSync(
-  requestedClass: string,
+  klass: string,
   opts: PersonaDirs = {},
 ): PersonaResolution | null {
-  const { requestedClass: requested, canonicalClass: klass } =
-    canonicalizeRoleClass(requestedClass);
   const { rolesDir, overrideDir } = resolveDirs(opts);
   const base = extractClassesFromDirSync(rolesDir);
   const over = extractClassesFromDirSync(overrideDir);
 
-  const override = readPersonaFromLayerSync(requested, klass, overrideDir, over, 'override');
+  const fromLayer = (
-  if (override) return override;
+    dir: string,
-  if (overrideShadowsBaseline(over, klass)) return null;
+    extracted: DirClasses,
-  return readPersonaFromLayerSync(requested, klass, rolesDir, base, 'baseline');
+    layer: PersonaLayer,
-}
+  ): PersonaResolution | null => {
+    // Prefer the marker-defined file; fall back to the filename stem.
+    const pf = extracted.byClass.get(klass);
+    if (!pf) {
+      if (!extracted.classes.has(klass)) return null;
+      const byName = join(dir, `${klass}.md`);
+      try {
+        const content = readFileSync(byName, 'utf8');
+        const dm = DOMAIN_MARKER.exec(content);
+        return { klass, layer, file: byName, content, ...(dm?.[1] ? { domain: dm[1] } : {}) };
+      } catch {
+        return null;
+      }
+    }
+    try {
+      const content = readFileSync(pf.file, 'utf8');
+      return { klass, layer, file: pf.file, content, ...(pf.domain ? { domain: pf.domain } : {}) };
+    } catch {
+      return null;
+    }
+  };
 
-interface UsablePersonaIndex {
+  return fromLayer(overrideDir, over, 'override') ?? fromLayer(rolesDir, base, 'baseline');
-  personas: Map<string, PersonaResolution>;
-  readableBaseline: Set<string>;
-}
-
-async function collectUsablePersonas(opts: PersonaDirs): Promise<UsablePersonaIndex> {
-  const { rolesDir, overrideDir } = resolveDirs(opts);
-  const [base, over] = await Promise.all([
-    extractClassesFromDir(rolesDir),
-    extractClassesFromDir(overrideDir),
-  ]);
-  if (over.scanState === 'error') {
-    return { personas: new Map(), readableBaseline: new Set() };
-  }
-
-  const candidates = new Set<string>([...base.classes, ...over.classes]);
-  const checked = await Promise.all(
-    [...candidates].map(async (requestedClass) => {
-      const { canonicalClass } = canonicalizeRoleClass(requestedClass);
-      const [persona, baseline] = await Promise.all([
-        resolvePersonaFrom(requestedClass, { rolesDir, overrideDir, base, over }),
-        readPersonaFromLayer(requestedClass, canonicalClass, rolesDir, base, 'baseline'),
-      ]);
-      return { requestedClass, persona, baseline };
-    }),
-  );
-
-  const personas = new Map<string, PersonaResolution>();
-  const readableBaseline = new Set<string>();
-  for (const { requestedClass, persona, baseline } of checked) {
-    if (persona) personas.set(requestedClass, persona);
-    if (baseline) readableBaseline.add(requestedClass);
-  }
-  return { personas, readableBaseline };
 }
 
 export interface PersonaStatusEntry {
@@ -608,20 +342,24 @@ export interface PersonaStatusEntry {
  * Domain is taken from the WINNING layer (override domain wins if present).
  */
 export async function personaStatus(opts: PersonaDirs = {}): Promise<PersonaStatusEntry[]> {
-  const { personas, readableBaseline } = await collectUsablePersonas(opts);
+  const { rolesDir, overrideDir } = resolveDirs(opts);
-  const entries = [...personas.entries()].map(([klass, persona]): PersonaStatusEntry => {
+  const [base, over] = await Promise.all([
-    const status: PersonaStatus =
+    extractClassesFromDir(rolesDir),
-      persona.layer === 'baseline'
+    extractClassesFromDir(overrideDir),
-        ? 'baseline'
+  ]);
-        : readableBaseline.has(klass)
+
-          ? 'overridden'
+  const all = new Set<string>([...base.classes, ...over.classes]);
-          : 'custom';
+  const domainOf = (extracted: DirClasses, klass: string): string | undefined =>
-    return {
+    extracted.byClass.get(klass)?.domain;
-      klass,
+
-      status,
+  const entries: PersonaStatusEntry[] = [];
-      ...(persona.domain ? { domain: persona.domain } : {}),
+  for (const klass of all) {
-    };
+    const inBase = base.classes.has(klass);
-  });
+    const inOver = over.classes.has(klass);
+    const status: PersonaStatus = inOver ? (inBase ? 'overridden' : 'custom') : 'baseline';
+    const domain = (inOver ? domainOf(over, klass) : undefined) ?? domainOf(base, klass);
+    entries.push({ klass, status, ...(domain ? { domain } : {}) });
+  }
   entries.sort((a, b) => a.klass.localeCompare(b.klass));
   return entries;
 }

packages/mosaic/src/commands/fleet-profiles.spec.ts

@@ -203,91 +203,6 @@ describe('loadProfiles with a temp override dir', () => {
     await rm(dir, { recursive: true, force: true });
   });
 
-  it('canonicalizes approved aliases across lead, floor, roster, and topology', async () => {
-    await writeFile(
-      join(dir, 'aliases.yaml'),
-      [
-        'id: aliases',
-        'title: Aliases',
-        'description: legacy class compatibility',
-        'lead: operator-interaction',
-        'floor: [operator-interaction]',
-        'roster:',
-        '  - class: operator-interaction',
-        '  - class: implementer',
-        '    reports_to: operator-interaction',
-        '  - class: reviewer',
-        '    reports_to: operator-interaction',
-        '',
-      ].join('\n'),
-    );
-
-    const profile = await loadProfile('aliases', {
-      profilesDir: dir,
-      rolesDir,
-      overrideDir: join(dir, 'roles.local'),
-    });
-    expect(profile.lead).toBe('interaction');
-    expect(profile.floor).toEqual(['interaction']);
-    expect(profile.roster).toEqual([
-      { class: 'interaction', multiplicity: 1 },
-      { class: 'code', reportsTo: 'interaction', multiplicity: 1 },
-      { class: 'review', reportsTo: 'interaction', multiplicity: 1 },
-    ]);
-  });
-
-  it('rejects roster entries that collapse to the same canonical class', async () => {
-    await writeFile(
-      join(dir, 'alias-collision.yaml'),
-      [
-        'id: alias-collision',
-        'title: Alias collision',
-        'description: ambiguous canonical topology',
-        'lead: orchestrator',
-        'floor: [orchestrator]',
-        'roster:',
-        '  - class: orchestrator',
-        '  - class: code',
-        '    reports_to: orchestrator',
-        '  - class: implementer',
-        '    reports_to: orchestrator',
-        '',
-      ].join('\n'),
-    );
-
-    await expect(
-      loadProfile('alias-collision', {
-        profilesDir: dir,
-        rolesDir,
-        overrideDir: join(dir, 'roles.local'),
-      }),
-    ).rejects.toThrow(/duplicate classes after canonicalization/);
-  });
-
-  it('allows a readable lead or floor persona that is not itself a roster seat', async () => {
-    await writeFile(
-      join(dir, 'external-topology.yaml'),
-      [
-        'id: external-topology',
-        'title: External topology',
-        'description: structural compatibility',
-        'lead: orchestrator',
-        'floor: [enhancer]',
-        'roster:',
-        '  - class: code',
-        '',
-      ].join('\n'),
-    );
-
-    const profile = await loadProfile('external-topology', {
-      profilesDir: dir,
-      rolesDir,
-      overrideDir: join(dir, 'roles.local'),
-    });
-    expect(profile.lead).toBe('orchestrator');
-    expect(profile.floor).toEqual(['enhancer']);
-  });
-
   it('throws when a profile references an unknown class (validated against real roles)', async () => {
     await writeFile(
       join(dir, 'bad.yaml'),

packages/mosaic/src/commands/fleet-profiles.ts

@@ -29,7 +29,6 @@ import {
   defaultOverrideDir,
   extractClassesFromDir,
   listPersonaClasses as listOverrideAwarePersonaClasses,
-  resolvePersonaFrom,
 } from './fleet-personas.js';
 
 function defaultMosaicHome(): string {
@@ -200,61 +199,6 @@ export function validateProfile(profile: FleetProfile, validClasses: Set<string>
   return problems;
 }
 
-export async function resolveProfilePersonas(
-  profile: FleetProfile,
-  rolesDir: string,
-  overrideDir: string,
-): Promise<FleetProfile> {
-  const [base, over] = await Promise.all([
-    extractClassesFromDir(rolesDir),
-    extractClassesFromDir(overrideDir),
-  ]);
-  const requestedClasses = new Set<string>([
-    profile.lead,
-    ...profile.floor,
-    ...profile.roster.flatMap((entry: ProfileRosterEntry): string[] =>
-      entry.reportsTo ? [entry.class, entry.reportsTo] : [entry.class],
-    ),
-  ]);
-  const canonicalByRequested = new Map<string, string>();
-  for (const requestedClass of requestedClasses) {
-    const resolved = await resolvePersonaFrom(requestedClass, {
-      rolesDir,
-      overrideDir,
-      base,
-      over,
-    });
-    if (!resolved || resolved.content.trim() === '') {
-      throw new Error(`persona class "${requestedClass}" does not resolve to a readable persona`);
-    }
-    canonicalByRequested.set(requestedClass, resolved.canonicalClass);
-  }
-  const canonical = (requestedClass: string): string =>
-    canonicalByRequested.get(requestedClass) ?? requestedClass;
-  const roster = profile.roster.map(
-    (entry: ProfileRosterEntry): ProfileRosterEntry => ({
-      class: canonical(entry.class),
-      multiplicity: entry.multiplicity,
-      ...(entry.reportsTo ? { reportsTo: canonical(entry.reportsTo) } : {}),
-    }),
-  );
-  const canonicalRosterClasses = roster.map((entry: ProfileRosterEntry): string => entry.class);
-  if (new Set(canonicalRosterClasses).size !== canonicalRosterClasses.length) {
-    throw new Error('profile roster contains duplicate classes after canonicalization');
-  }
-  const resolvedProfile: FleetProfile = {
-    ...profile,
-    lead: canonical(profile.lead),
-    floor: profile.floor.map(canonical),
-    roster,
-  };
-  const problems = validateProfile(resolvedProfile, new Set(canonicalByRequested.values()));
-  if (problems.length > 0) {
-    throw new Error(problems.join('\n  - '));
-  }
-  return resolvedProfile;
-}
-
 export interface LoadProfilesOptions {
   /** Override the profiles dir (tests). Defaults to <mosaicHome>/fleet/profiles. */
   profilesDir?: string;
@@ -293,8 +237,10 @@ export async function loadProfiles(opts: LoadProfilesOptions = {}): Promise<Flee
   }
   files.sort();
 
-  // Validation resolves each reference to an actually readable winning persona;
+  // Override-aware: a profile may reference a user-customized or user-ADDED
-  // LIBRARY membership alone is not semantic success.
+  // persona living in the roles.local/ layer (H4), so validate against the
+  // baseline ⊕ override union, not the baseline alone.
+  const validClasses = await listPersonaClassesWithOverrides(rolesDir, overrideDir);
   const profiles: FleetProfile[] = [];
   const seen = new Map<string, string>();
 
@@ -309,14 +255,11 @@ export async function loadProfiles(opts: LoadProfilesOptions = {}): Promise<Flee
     }
     seen.set(profile.id, file);
 
-    let resolvedProfile: FleetProfile;
+    const problems = validateProfile(profile, validClasses);
-    try {
+    if (problems.length > 0) {
-      resolvedProfile = await resolveProfilePersonas(profile, rolesDir, overrideDir);
+      throw new Error(`Profile ${file} is invalid:\n  - ${problems.join('\n  - ')}`);
-    } catch (error: unknown) {
-      const detail = error instanceof Error ? error.message : String(error);
-      throw new Error(`Profile ${file} is invalid:\n  - ${detail}`);
     }
-    profiles.push(resolvedProfile);
+    profiles.push(profile);
   }
   return profiles;
 }

packages/mosaic/src/commands/fleet-provision.spec.ts

@@ -172,46 +172,6 @@ describe('override-aware persona validation', () => {
     expect(result.summary).toContain('persona=override');
   });
 
-  it('canonicalizes aliased profile classes and topology identities before emission', async () => {
-    const overrideDir = join(dir, 'roles.local');
-    const customProfilesDir = join(dir, 'profiles');
-    await mkdir(overrideDir, { recursive: true });
-    await mkdir(customProfilesDir, { recursive: true });
-    await writeFile(
-      join(customProfilesDir, 'aliases.yaml'),
-      [
-        'id: aliases',
-        'title: Aliases',
-        'description: legacy aliases',
-        'lead: operator-interaction',
-        'floor: [operator-interaction]',
-        'roster:',
-        '  - class: operator-interaction',
-        '  - class: implementer',
-        '    reports_to: operator-interaction',
-        '  - class: reviewer',
-        '    reports_to: operator-interaction',
-        '',
-      ].join('\n'),
-    );
-
-    const result = await runProvision('aliases', {
-      mosaicHome: dir,
-      profilesDir: customProfilesDir,
-      rolesDir,
-      overrideDir,
-      full: true,
-    });
-    expect(result.yaml).toContain('name: interaction');
-    expect(result.yaml).toContain('class: interaction');
-    expect(result.yaml).toContain('name: code');
-    expect(result.yaml).toContain('class: code');
-    expect(result.yaml).toContain('name: review');
-    expect(result.yaml).toContain('class: review');
-    expect(result.yaml).not.toContain('class: implementer');
-    expect(result.summary).toContain('reports_to=interaction');
-  });
-
   it('FAILS with a clear message when a profile references a bogus class', async () => {
     const customProfilesDir = join(dir, 'profiles');
     await mkdir(customProfilesDir, { recursive: true });

packages/mosaic/src/commands/fleet-provision.ts

@@ -26,11 +26,12 @@ import type { Command } from 'commander';
 import YAML from 'yaml';
 import {
   loadProfile,
+  validateProfile,
   type FleetProfile,
   type ProfileRosterEntry,
   defaultProfilesDir,
   defaultRolesDir,
-  resolveProfilePersonas,
+  listPersonaClassesWithOverrides,
 } from './fleet-profiles.js';
 import {
   defaultOverrideDir,
@@ -200,35 +201,18 @@ export async function generateRoster(
       );
     }
 
-    const canonicalEntry: ProfileRosterEntry = {
+    const runtimeChoice = resolveSeatRuntime(entry.class, isFloor, isLead);
-      class: resolved.canonicalClass,
+    for (const name of seatNames(entry)) {
-      multiplicity: entry.multiplicity,
-      ...(entry.reportsTo
-        ? {
-            reportsTo:
-              (
-                await resolvePersonaFrom(entry.reportsTo, {
-                  rolesDir,
-                  overrideDir,
-                  base,
-                  over,
-                })
-              )?.canonicalClass ?? entry.reportsTo,
-          }
-        : {}),
-    };
-    const runtimeChoice = resolveSeatRuntime(resolved.canonicalClass, isFloor, isLead);
-    for (const name of seatNames(canonicalEntry)) {
       const seat: GeneratedSeat = {
         name,
-        className: resolved.canonicalClass,
+        className: entry.class,
         runtime: runtimeChoice.runtime,
         personaLayer: resolved.layer,
       };
       if (runtimeChoice.modelHint) seat.modelHint = runtimeChoice.modelHint;
       if (isFloor || isLead) seat.persistentPersona = true;
       if (!isFloor && !isLead) seat.resetBetweenTasks = true;
-      if (canonicalEntry.reportsTo) seat.reportsTo = canonicalEntry.reportsTo;
+      if (entry.reportsTo) seat.reportsTo = entry.reportsTo;
       seats.push(seat);
     }
   }
@@ -295,7 +279,13 @@ export async function validateProfileForProvision(
   opts: ProvisionOptions,
 ): Promise<void> {
   const { rolesDir, overrideDir } = resolveDirs(opts);
-  await resolveProfilePersonas(profile, rolesDir, overrideDir);
+  const validClasses = await listPersonaClassesWithOverrides(rolesDir, overrideDir);
+  const problems = validateProfile(profile, validClasses);
+  if (problems.length > 0) {
+    throw new Error(
+      `Profile "${profile.id}" is invalid; cannot provision:\n  - ${problems.join('\n  - ')}`,
+    );
+  }
 }
 
 // ---------------------------------------------------------------------------

packages/mosaic/src/fleet/example-profile-dispositions.spec.ts

@@ -1,90 +0,0 @@
-import { cp, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { afterEach, describe, expect, it } from 'vitest';
-import {
-  SHIPPED_FLEET_ARTIFACT_DISPOSITIONS,
-  validateShippedFleetArtifactDispositions,
-} from './example-profile-dispositions.js';
-
-const frameworkFleet = resolve(
-  dirname(fileURLToPath(import.meta.url)),
-  '..',
-  '..',
-  'framework',
-  'fleet',
-);
-
-const EXPECTED_DISPOSITIONS = [
-  'examples/coding.yaml:v1-fixture',
-  'examples/general.yaml:v1-fixture',
-  'examples/hybrid.yaml:v1-fixture',
-  'examples/local-canary.yaml:v1-fixture',
-  'examples/minimal.yaml:v1-fixture',
-  'examples/operator-interaction.yaml:v1-fixture',
-  'examples/research.yaml:v1-fixture',
-  'profiles/business.yaml:canonical-profile',
-  'profiles/marketing.yaml:canonical-profile',
-  'profiles/personal-assistant.yaml:canonical-profile',
-  'profiles/research.yaml:canonical-profile',
-  'profiles/software-delivery.yaml:canonical-profile',
-  'services/operator-interaction.yaml:canonical-service-policy',
-];
-
-const declared = SHIPPED_FLEET_ARTIFACT_DISPOSITIONS.map(
-  ({ path, disposition }): string => `${path}:${disposition}`,
-);
-
-describe('shipped fleet example/profile/service disposition validation', (): void => {
-  it('enumerates every inventory artifact with an explicit executable disposition', (): void => {
-    expect(declared).toEqual(EXPECTED_DISPOSITIONS);
-  });
-
-  it('validates every shipped artifact through its declared v1 or canonical path', async (): Promise<void> => {
-    const results = await validateShippedFleetArtifactDispositions({ frameworkFleet });
-
-    expect(results.map(({ path, disposition }): string => `${path}:${disposition}`)).toEqual(
-      EXPECTED_DISPOSITIONS,
-    );
-    expect(results.filter(({ disposition }): boolean => disposition === 'v1-fixture')).toHaveLength(
-      7,
-    );
-    expect(
-      results.filter(({ disposition }): boolean => disposition === 'canonical-profile'),
-    ).toHaveLength(5);
-    expect(
-      results.find(({ path }): boolean => path === 'services/operator-interaction.yaml'),
-    ).toMatchObject({
-      disposition: 'canonical-service-policy',
-    });
-  });
-
-  let temporaryFleet: string | undefined;
-  afterEach(async (): Promise<void> => {
-    if (temporaryFleet) await rm(temporaryFleet, { recursive: true, force: true });
-    temporaryFleet = undefined;
-  });
-
-  it('fails closed when a shipped artifact lacks a declared disposition', async (): Promise<void> => {
-    temporaryFleet = await mkdtemp(join(tmpdir(), 'mosaic-dispositions-'));
-    await cp(frameworkFleet, temporaryFleet, { recursive: true });
-    await writeFile(join(temporaryFleet, 'examples', 'undeclared.yaml'), 'version: 1\n');
-
-    await expect(
-      validateShippedFleetArtifactDispositions({ frameworkFleet: temporaryFleet }),
-    ).rejects.toThrow(/undeclared shipped fleet artifact.*examples\/undeclared.yaml/i);
-  });
-
-  it('rejects a v1 fixture when its explicit version declaration is removed', async (): Promise<void> => {
-    temporaryFleet = await mkdtemp(join(tmpdir(), 'mosaic-dispositions-'));
-    await cp(frameworkFleet, temporaryFleet, { recursive: true });
-    const fixturePath = join(temporaryFleet, 'examples', 'coding.yaml');
-    const fixture = await readFile(fixturePath, 'utf8');
-    await writeFile(fixturePath, fixture.replace(/^version: 1\n/, ''));
-
-    await expect(
-      validateShippedFleetArtifactDispositions({ frameworkFleet: temporaryFleet }),
-    ).rejects.toThrow(/Fleet roster version must be 1/);
-  });
-});

packages/mosaic/src/fleet/example-profile-dispositions.ts

@@ -1,121 +0,0 @@
-import { readdir } from 'node:fs/promises';
-import { basename, join } from 'node:path';
-import { loadFleetRoster } from '../commands/fleet.js';
-import { loadProfiles } from '../commands/fleet-profiles.js';
-import {
-  provisionInteractionService,
-  readInteractionServiceProfile,
-} from './interaction-service-profile.js';
-
-export type FleetArtifactDisposition =
-  | 'v1-fixture'
-  | 'canonical-profile'
-  | 'canonical-service-policy';
-
-export interface ShippedFleetArtifactDisposition {
-  readonly path: string;
-  readonly disposition: FleetArtifactDisposition;
-}
-
-export interface ValidateShippedFleetArtifactDispositionsOptions {
-  readonly frameworkFleet: string;
-  readonly rolesDir?: string;
-  readonly overrideDir?: string;
-}
-
-/**
- * The M0 inventory in executable form. Every shipped fleet YAML asset is either
- * a deliberately retained v1 fixture or validated through its canonical loader.
- */
-export const SHIPPED_FLEET_ARTIFACT_DISPOSITIONS: readonly ShippedFleetArtifactDisposition[] = [
-  { path: 'examples/coding.yaml', disposition: 'v1-fixture' },
-  { path: 'examples/general.yaml', disposition: 'v1-fixture' },
-  { path: 'examples/hybrid.yaml', disposition: 'v1-fixture' },
-  { path: 'examples/local-canary.yaml', disposition: 'v1-fixture' },
-  { path: 'examples/minimal.yaml', disposition: 'v1-fixture' },
-  { path: 'examples/operator-interaction.yaml', disposition: 'v1-fixture' },
-  { path: 'examples/research.yaml', disposition: 'v1-fixture' },
-  { path: 'profiles/business.yaml', disposition: 'canonical-profile' },
-  { path: 'profiles/marketing.yaml', disposition: 'canonical-profile' },
-  { path: 'profiles/personal-assistant.yaml', disposition: 'canonical-profile' },
-  { path: 'profiles/research.yaml', disposition: 'canonical-profile' },
-  { path: 'profiles/software-delivery.yaml', disposition: 'canonical-profile' },
-  { path: 'services/operator-interaction.yaml', disposition: 'canonical-service-policy' },
-];
-
-/**
- * Fail closed when a fleet YAML asset is added or removed without a disposition.
- * This keeps legacy v1 compatibility explicit instead of silently accepting new
- * unresolved classes outside the shared resolver.
- */
-export async function validateShippedFleetArtifactDispositions(
-  options: ValidateShippedFleetArtifactDispositionsOptions,
-): Promise<readonly ShippedFleetArtifactDisposition[]> {
-  await assertEveryShippedArtifactIsDeclared(options.frameworkFleet);
-
-  const examples = SHIPPED_FLEET_ARTIFACT_DISPOSITIONS.filter(
-    ({ disposition }): boolean => disposition === 'v1-fixture',
-  );
-  for (const artifact of examples) {
-    const roster = await loadFleetRoster(join(options.frameworkFleet, artifact.path));
-    if (roster.version !== 1) {
-      throw new Error(`v1 fixture ${artifact.path} must declare version: 1`);
-    }
-  }
-
-  const profilesDir = join(options.frameworkFleet, 'profiles');
-  const profiles = await loadProfiles({
-    profilesDir,
-    rolesDir: options.rolesDir ?? join(options.frameworkFleet, 'roles'),
-    overrideDir: options.overrideDir ?? join(options.frameworkFleet, 'roles.local'),
-  });
-  const declaredProfiles = SHIPPED_FLEET_ARTIFACT_DISPOSITIONS.filter(
-    ({ disposition }): boolean => disposition === 'canonical-profile',
-  ).map(({ path }): string => basename(path, '.yaml'));
-  const resolvedProfiles = new Set(profiles.map(({ id }): string => id));
-  for (const profileId of declaredProfiles) {
-    if (!resolvedProfiles.has(profileId)) {
-      throw new Error(`declared canonical profile ${profileId} did not resolve`);
-    }
-  }
-
-  const servicePolicies = SHIPPED_FLEET_ARTIFACT_DISPOSITIONS.filter(
-    ({ disposition }): boolean => disposition === 'canonical-service-policy',
-  );
-  for (const artifact of servicePolicies) {
-    const serviceProfile = await readInteractionServiceProfile(
-      join(options.frameworkFleet, artifact.path),
-    );
-    provisionInteractionService(serviceProfile, { agentName: 'interaction-example' });
-  }
-
-  return SHIPPED_FLEET_ARTIFACT_DISPOSITIONS;
-}
-
-async function assertEveryShippedArtifactIsDeclared(frameworkFleet: string): Promise<void> {
-  const declared = new Set(SHIPPED_FLEET_ARTIFACT_DISPOSITIONS.map(({ path }): string => path));
-  const shipped = await listShippedFleetArtifactPaths(frameworkFleet);
-
-  for (const path of shipped) {
-    if (!declared.has(path)) {
-      throw new Error(`undeclared shipped fleet artifact: ${path}`);
-    }
-  }
-  for (const path of declared) {
-    if (!shipped.has(path)) {
-      throw new Error(`declared shipped fleet artifact is missing: ${path}`);
-    }
-  }
-}
-
-async function listShippedFleetArtifactPaths(frameworkFleet: string): Promise<Set<string>> {
-  const directories = ['examples', 'profiles', 'services'];
-  const paths = new Set<string>();
-  for (const directory of directories) {
-    const files = await readdir(join(frameworkFleet, directory));
-    for (const file of files) {
-      if (file.endsWith('.yaml') || file.endsWith('.yml')) paths.add(`${directory}/${file}`);
-    }
-  }
-  return paths;
-}

packages/mosaic/src/fleet/persona-contract.spec.ts

@@ -77,25 +77,12 @@ describe('readPersonaContractBlock — launch-time persona injection (A3b)', ()
   });
 
   it('injects an override-only (user-added) persona with no baseline at all', () => {
-    seedOverride(home, 'mascot', '# Mascot\n\n(`class: mascot`)\n\nCUSTOM-ROLE.\n');
+    seedOverride(home, 'reviewer', '# Reviewer\n\n(`class: reviewer`)\n\nCUSTOM-ROLE.\n');
-    const block = readPersonaContractBlock(home, 'mascot');
+    const block = readPersonaContractBlock(home, 'reviewer');
-    expect(block).toContain('# Persona Contract (mascot)');
+    expect(block).toContain('# Persona Contract (reviewer)');
     expect(block).toContain('CUSTOM-ROLE');
   });
 
-  it('canonicalizes an approved alias before launch-time override lookup', () => {
-    seedBaseline(home, 'code', '# Code\n\n(`class: code`)\n\nCANONICAL-CODE.\n');
-    seedOverride(
-      home,
-      'implementer',
-      '# Legacy implementer\n\n(`class: implementer`)\n\nLEGACY-OVERRIDE.\n',
-    );
-    const block = readPersonaContractBlock(home, 'implementer');
-    expect(block).toContain('# Persona Contract (code)');
-    expect(block).toContain('CANONICAL-CODE');
-    expect(block).not.toContain('LEGACY-OVERRIDE');
-  });
-
   it('no-ops (empty string) when the class is undefined', () => {
     seedBaseline(home, 'coder', BASELINE_CODER);
     expect(readPersonaContractBlock(home, undefined)).toBe('');

packages/mosaic/src/fleet/roster-v2.spec.ts

@@ -1,14 +1,11 @@
-import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { readFile } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { afterEach, describe, expect, it } from 'vitest';
+import { describe, expect, it } from 'vitest';
 import {
   ROSTER_V2_JSON_SCHEMA,
   RosterV2ValidationError,
   parseRosterV2,
   renderRosterV2Yaml,
-  validateRosterV2Semantics,
 } from './roster-v2.js';
 
 const validRoster = `
@@ -43,127 +40,6 @@ agents:
       yolo: true
 `;
 
-let semanticTmp: string | undefined;
-
-afterEach(async (): Promise<void> => {
-  if (semanticTmp) await rm(semanticTmp, { recursive: true, force: true });
-  semanticTmp = undefined;
-});
-
-async function semanticDirs(): Promise<{ rolesDir: string; overrideDir: string }> {
-  semanticTmp = await mkdtemp(join(tmpdir(), 'roster-v2-semantics-'));
-  const rolesDir = join(semanticTmp, 'roles');
-  const overrideDir = join(semanticTmp, 'roles.local');
-  await mkdir(rolesDir, { recursive: true });
-  await mkdir(overrideDir, { recursive: true });
-  for (const klass of [
-    'code',
-    'review',
-    'interaction',
-    'orchestrator',
-    'merge-gate',
-    'validator',
-    'team-leader',
-  ]) {
-    await writeFile(join(rolesDir, `${klass}.md`), `# ${klass}\n\n(\`class: ${klass}\`)\n`, 'utf8');
-  }
-  return { rolesDir, overrideDir };
-}
-
-function rosterWithClass(klass: string, toolPolicy = klass): string {
-  return validRoster
-    .replace('class: code', `class: ${klass}`)
-    .replace('tool_policy: code', `tool_policy: ${toolPolicy}`);
-}
-
-describe('roster v2 semantic validation', (): void => {
-  it.each([
-    ['implementer', 'code'],
-    ['reviewer', 'review'],
-    ['operator-interaction', 'interaction'],
-  ])(
-    'canonicalizes requested alias %s while retaining requested and canonical class',
-    async (requested: string, canonical: string) => {
-      const dirs = await semanticDirs();
-      const roster = parseRosterV2(rosterWithClass(requested, requested), 'yaml');
-      const validated = await validateRosterV2Semantics(roster, dirs);
-      expect(validated.agents[0]).toMatchObject({
-        requestedClass: requested,
-        canonicalClass: canonical,
-        canonicalToolPolicy: canonical,
-      });
-    },
-  );
-
-  it.each(['worker', 'analyst', 'canary'])(
-    'rejects %s when no genuine custom role exists',
-    async (klass: string) => {
-      const dirs = await semanticDirs();
-      await expect(
-        validateRosterV2Semantics(parseRosterV2(rosterWithClass(klass), 'yaml'), dirs),
-      ).rejects.toThrow(/unresolved|readable persona/i);
-    },
-  );
-
-  it('accepts a genuine custom roles.local class without protected authority', async () => {
-    const dirs = await semanticDirs();
-    await writeFile(join(dirs.overrideDir, 'worker.md'), '# worker\n\n(`class: worker`)\n', 'utf8');
-    const validated = await validateRosterV2Semantics(
-      parseRosterV2(rosterWithClass('worker'), 'yaml'),
-      dirs,
-    );
-    expect(validated.agents[0]?.authority).toMatchObject({
-      mayMerge: false,
-      mayOrchestrate: false,
-    });
-  });
-
-  it('rejects a LIBRARY-only class with no readable resolved persona', async () => {
-    const dirs = await semanticDirs();
-    await writeFile(
-      join(dirs.rolesDir, 'LIBRARY.md'),
-      '| Persona | Purpose |\n| --- | --- |\n| phantom | Missing |\n',
-      'utf8',
-    );
-    await expect(
-      validateRosterV2Semantics(parseRosterV2(rosterWithClass('phantom'), 'yaml'), dirs),
-    ).rejects.toThrow(/readable persona/i);
-  });
-
-  it('rejects an unreadable resolved persona', async () => {
-    const dirs = await semanticDirs();
-    await mkdir(join(dirs.overrideDir, 'worker.md'));
-    await expect(
-      validateRosterV2Semantics(parseRosterV2(rosterWithClass('worker'), 'yaml'), dirs),
-    ).rejects.toThrow(/readable persona/i);
-  });
-
-  it.each([
-    ['merge-gate', 'code'],
-    ['validator', 'merge-gate'],
-    ['orchestrator', 'interaction'],
-    ['team-leader', 'orchestrator'],
-    ['interaction', 'orchestrator'],
-    ['code', 'merge-gate'],
-    ['worker', 'validator'],
-  ])(
-    'denies protected class/tool-policy mismatch %s with %s',
-    async (klass: string, toolPolicy: string) => {
-      const dirs = await semanticDirs();
-      if (klass === 'worker') {
-        await writeFile(
-          join(dirs.overrideDir, 'worker.md'),
-          '# worker\n\n(`class: worker`)\n',
-          'utf8',
-        );
-      }
-      await expect(
-        validateRosterV2Semantics(parseRosterV2(rosterWithClass(klass, toolPolicy), 'yaml'), dirs),
-      ).rejects.toThrow(/tool policy.*must match|mismatch/i);
-    },
-  );
-});
-
 describe('roster v2 structural compiler', (): void => {
   it('parses YAML into a normalized typed model and renders canonical YAML', (): void => {
     const roster = parseRosterV2(validRoster, 'yaml');

packages/mosaic/src/fleet/roster-v2.ts

@@ -1,15 +1,4 @@
 import YAML from 'yaml';
-import {
-  authorityForCanonicalClass,
-  canonicalizeRoleClass,
-  defaultOverrideDir,
-  defaultRolesDir,
-  extractClassesFromDir,
-  resolvePersonaFrom,
-  type PersonaDirs,
-  type PersonaResolution,
-  type RoleAuthority,
-} from '../commands/fleet-personas.js';
 
 export const ROSTER_V2_SUPPORTED_RUNTIMES = ['claude', 'codex', 'opencode', 'pi'] as const;
 export const ROSTER_V2_REASONING_LEVELS = ['low', 'medium', 'high'] as const;
@@ -69,80 +58,6 @@ export interface FleetRosterV2 {
   readonly agents: readonly FleetRosterV2Agent[];
 }
 
-export interface SemanticallyValidatedRosterV2Agent extends FleetRosterV2Agent {
-  readonly requestedClass: string;
-  readonly canonicalClass: string;
-  readonly canonicalToolPolicy: string;
-  readonly persona: PersonaResolution;
-  readonly authority: RoleAuthority;
-}
-
-export interface SemanticallyValidatedRosterV2 extends Omit<FleetRosterV2, 'agents'> {
-  readonly agents: readonly SemanticallyValidatedRosterV2Agent[];
-}
-
-const PROTECTED_TOOL_POLICY_CLASSES = new Set([
-  'merge-gate',
-  'validator',
-  'orchestrator',
-  'team-leader',
-  'interaction',
-]);
-
-/**
- * Validate filesystem-backed roster semantics after synchronous structural parsing.
- * Directory scans are batched once and every class must resolve to readable content.
- */
-export async function validateRosterV2Semantics(
-  roster: FleetRosterV2,
-  opts: PersonaDirs = {},
-): Promise<SemanticallyValidatedRosterV2> {
-  const rolesDir = opts.rolesDir ?? defaultRolesDir(opts.mosaicHome);
-  const overrideDir = opts.overrideDir ?? defaultOverrideDir(opts.mosaicHome);
-  const [base, over] = await Promise.all([
-    extractClassesFromDir(rolesDir),
-    extractClassesFromDir(overrideDir),
-  ]);
-
-  const agents: SemanticallyValidatedRosterV2Agent[] = [];
-  for (const agent of roster.agents) {
-    const requestedClass = agent.className;
-    const { canonicalClass } = canonicalizeRoleClass(requestedClass);
-    const canonicalToolPolicy = canonicalizeRoleClass(agent.toolPolicy).canonicalClass;
-    const persona = await resolvePersonaFrom(requestedClass, {
-      rolesDir,
-      overrideDir,
-      base,
-      over,
-    });
-    if (!persona || persona.content.trim() === '') {
-      throw new RosterV2ValidationError(
-        `Roster v2 agent "${agent.name}" class "${requestedClass}" does not resolve to a readable persona.`,
-      );
-    }
-    if (
-      (PROTECTED_TOOL_POLICY_CLASSES.has(canonicalClass) ||
-        PROTECTED_TOOL_POLICY_CLASSES.has(canonicalToolPolicy)) &&
-      canonicalToolPolicy !== canonicalClass
-    ) {
-      throw new RosterV2ValidationError(
-        `Roster v2 agent "${agent.name}" protected class "${canonicalClass}" tool policy must match its canonical class; received "${agent.toolPolicy}".`,
-      );
-    }
-    agents.push(
-      Object.freeze({
-        ...agent,
-        requestedClass,
-        canonicalClass,
-        canonicalToolPolicy,
-        persona,
-        authority: authorityForCanonicalClass(canonicalClass),
-      }),
-    );
-  }
-  return Object.freeze({ ...roster, agents: Object.freeze(agents) });
-}
-
 export class RosterV2ValidationError extends Error {
   constructor(message: string) {
     super(message);

packages/types/src/agent/connector-lease.dto.spec.ts

@@ -1,59 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import {
-  normalizeConnectorId,
-  normalizeConnectorScopes,
-  normalizeLeaseEpoch,
-  normalizeLogicalAgentIdentity,
-  normalizeLogicalBindingId,
-  type ConnectorExecutionContext,
-  type LogicalAgentIdentity,
-} from './connector-lease.dto.js';
-
-describe('logical agent connector lease contract', (): void => {
-  it('normalizes a runtime-neutral logical identity and binding vocabulary', (): void => {
-    const identity = normalizeLogicalAgentIdentity({
-      tenantId: ' tenant-01 ',
-      logicalAgentId: ' MOS.Primary ',
-    });
-
-    expect(identity).toEqual({ tenantId: 'tenant-01', logicalAgentId: 'mos.primary' });
-    expect(normalizeLogicalBindingId(' Discord:Operations ')).toBe('discord:operations');
-    expect(normalizeConnectorId(' PI.Worker-01 ')).toBe('pi.worker-01');
-    expect(Object.isFrozen(identity)).toBe(true);
-    expect(Object.keys(identity).sort()).toEqual(['logicalAgentId', 'tenantId']);
-  });
-
-  it('canonicalizes scopes and decimal fencing epochs', (): void => {
-    expect(normalizeConnectorScopes([' Runtime.Send ', 'tool.execute', 'runtime.send'])).toEqual([
-      'runtime.send',
-      'tool.execute',
-    ]);
-    expect(normalizeLeaseEpoch('00042')).toBe('42');
-  });
-
-  it.each([
-    ['', 'mos'],
-    ['tenant', ''],
-    ['tenant', 'claude session/123'],
-  ])('rejects ambiguous identity values tenant=%j agent=%j', (tenantId, logicalAgentId): void => {
-    expect(() => normalizeLogicalAgentIdentity({ tenantId, logicalAgentId })).toThrow();
-  });
-
-  it('defines an adapter context without harness-native identity fields', (): void => {
-    const identity: LogicalAgentIdentity = { tenantId: 'tenant-01', logicalAgentId: 'mos' };
-    const context: ConnectorExecutionContext = {
-      identity,
-      bindingId: 'operator-chat',
-      connectorId: 'connector-a',
-      leaseId: '00000000-0000-4000-8000-000000000001',
-      leaseEpoch: '7',
-      scopes: ['runtime.send'],
-      correlationId: 'correlation-1',
-      grantExpiresAt: '2026-07-14T18:00:00.000Z',
-    };
-
-    expect(context).not.toHaveProperty('sessionId');
-    expect(context).not.toHaveProperty('tmuxSession');
-    expect(context).not.toHaveProperty('providerSessionId');
-  });
-});

packages/types/src/agent/connector-lease.dto.ts

@@ -1,199 +0,0 @@
-const ID_PATTERN = /^[a-z0-9][a-z0-9._:@-]{0,127}$/;
-const TENANT_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:@-]{0,127}$/;
-const SCOPE_PATTERN = /^[a-z][a-z0-9._:-]{0,127}$/;
-
-/** Stable Mosaic identity. It intentionally contains no runtime/provider session identifier. */
-export interface LogicalAgentIdentity {
-  readonly tenantId: string;
-  readonly logicalAgentId: string;
-}
-
-export interface LogicalAgentBinding {
-  readonly identity: LogicalAgentIdentity;
-  readonly bindingId: string;
-}
-
-export interface ConnectorLease extends LogicalAgentBinding {
-  readonly leaseId: string;
-  readonly connectorId: string;
-  readonly scopes: readonly string[];
-  readonly leaseEpoch: string;
-  readonly acquiredAt: string;
-  readonly heartbeatAt: string;
-  readonly expiresAt: string;
-  readonly releasedAt?: string;
-}
-
-export interface AcquireConnectorLeaseInput {
-  readonly identity: LogicalAgentIdentity;
-  readonly bindingId: string;
-  readonly connectorId: string;
-  readonly scopes: readonly string[];
-  readonly ttlMs: number;
-  readonly correlationId: string;
-}
-
-export interface TakeoverConnectorLeaseInput extends AcquireConnectorLeaseInput {
-  readonly expectedEpoch: string;
-}
-
-export interface HeartbeatConnectorLeaseInput {
-  readonly lease: ConnectorLease;
-  readonly ttlMs: number;
-  readonly correlationId: string;
-}
-
-export interface ReleaseConnectorLeaseInput {
-  readonly lease: ConnectorLease;
-  readonly correlationId: string;
-}
-
-export interface IssueConnectorExecutionGrantInput {
-  readonly lease: ConnectorLease;
-  readonly scopes: readonly string[];
-  readonly ttlMs: number;
-  readonly correlationId: string;
-}
-
-/** Internal server grant. Object provenance is checked in addition to these fields. */
-export interface ConnectorExecutionGrant extends LogicalAgentBinding {
-  readonly leaseId: string;
-  readonly connectorId: string;
-  readonly scopes: readonly string[];
-  readonly leaseEpoch: string;
-  readonly issuedAt: string;
-  readonly expiresAt: string;
-  readonly correlationId: string;
-}
-
-/** Normalized context passed to an adapter only after current-lease validation. */
-export interface ConnectorExecutionContext extends LogicalAgentBinding {
-  readonly leaseId: string;
-  readonly connectorId: string;
-  readonly scopes: readonly string[];
-  readonly leaseEpoch: string;
-  readonly correlationId: string;
-  readonly grantExpiresAt: string;
-}
-
-export interface FencedConnectorAdapter<TInput, TOutput> {
-  execute(input: TInput, context: ConnectorExecutionContext): Promise<TOutput>;
-}
-
-export type ConnectorLeaseAuditEventType =
-  | 'acquire'
-  | 'renew'
-  | 'takeover'
-  | 'reject'
-  | 'release'
-  | 'expiry';
-export type ConnectorLeaseAuditOutcome = 'succeeded' | 'denied';
-export type ConnectorLeaseRejectReason =
-  | 'policy_denied'
-  | 'lease_held'
-  | 'takeover_required'
-  | 'cas_mismatch'
-  | 'lease_missing'
-  | 'lease_released'
-  | 'lease_expired'
-  | 'stale_epoch'
-  | 'connector_mismatch'
-  | 'scope_denied'
-  | 'forged_grant'
-  | 'grant_expired';
-
-/** Credential-safe metadata only: no grant object, scope set, payload, token, or approval ref. */
-export interface ConnectorLeaseAuditEvent extends LogicalAgentBinding {
-  readonly event: ConnectorLeaseAuditEventType;
-  readonly outcome: ConnectorLeaseAuditOutcome;
-  readonly connectorId: string;
-  readonly correlationId: string;
-  readonly occurredAt: string;
-  readonly leaseId?: string;
-  readonly leaseEpoch?: string;
-  readonly reason?: ConnectorLeaseRejectReason;
-}
-
-export interface ConnectorLeaseAcquireMutation extends AcquireConnectorLeaseInput {
-  readonly leaseId: string;
-  readonly now: string;
-  readonly expiresAt: string;
-}
-
-export interface ConnectorLeaseTakeoverMutation extends TakeoverConnectorLeaseInput {
-  readonly leaseId: string;
-  readonly now: string;
-  readonly expiresAt: string;
-}
-
-export interface ConnectorLeaseHeartbeatMutation extends HeartbeatConnectorLeaseInput {
-  readonly now: string;
-  readonly expiresAt: string;
-}
-
-export interface ConnectorLeaseReleaseMutation extends ReleaseConnectorLeaseInput {
-  readonly now: string;
-}
-
-export interface ConnectorLeaseStore {
-  acquire(input: ConnectorLeaseAcquireMutation): Promise<ConnectorLease>;
-  takeover(input: ConnectorLeaseTakeoverMutation): Promise<ConnectorLease>;
-  heartbeat(input: ConnectorLeaseHeartbeatMutation): Promise<ConnectorLease>;
-  release(input: ConnectorLeaseReleaseMutation): Promise<void>;
-  findCurrent(binding: LogicalAgentBinding): Promise<ConnectorLease | null>;
-  recordAudit(event: ConnectorLeaseAuditEvent): Promise<void>;
-}
-
-export function normalizeLogicalAgentIdentity(input: LogicalAgentIdentity): LogicalAgentIdentity {
-  const tenantId = requiredIdentifier(input.tenantId, 'tenant ID', TENANT_PATTERN, false);
-  const logicalAgentId = requiredIdentifier(
-    input.logicalAgentId,
-    'logical agent ID',
-    ID_PATTERN,
-    true,
-  );
-  return Object.freeze({ tenantId, logicalAgentId });
-}
-
-export function normalizeLogicalBindingId(value: string): string {
-  return requiredIdentifier(value, 'logical binding ID', ID_PATTERN, true);
-}
-
-export function normalizeConnectorId(value: string): string {
-  return requiredIdentifier(value, 'connector ID', ID_PATTERN, true);
-}
-
-export function normalizeCorrelationId(value: string): string {
-  return requiredIdentifier(value, 'correlation ID', TENANT_PATTERN, false);
-}
-
-export function normalizeConnectorScope(value: string): string {
-  return requiredIdentifier(value, 'connector scope', SCOPE_PATTERN, true);
-}
-
-export function normalizeConnectorScopes(values: readonly string[]): readonly string[] {
-  if (values.length === 0) throw new Error('At least one connector scope is required');
-  return Object.freeze(Array.from(new Set(values.map(normalizeConnectorScope))).sort());
-}
-
-export function normalizeLeaseEpoch(value: string): string {
-  const trimmed = value.trim();
-  if (!/^\d+$/.test(trimmed)) throw new Error('Lease epoch must be a positive decimal integer');
-  const epoch = BigInt(trimmed);
-  if (epoch < 1n) throw new Error('Lease epoch must be a positive decimal integer');
-  return epoch.toString(10);
-}
-
-function requiredIdentifier(
-  value: string,
-  label: string,
-  pattern: RegExp,
-  lowerCase: boolean,
-): string {
-  const trimmed = value.trim();
-  const normalized = lowerCase ? trimmed.toLowerCase() : trimmed;
-  if (!pattern.test(normalized)) {
-    throw new Error(`${label} has an invalid normalized format`);
-  }
-  return normalized;
-}

packages/types/src/agent/index.ts

@@ -4,4 +4,3 @@ export interface AgentSessionHandle {
 }
 
 export * from './agent-runtime-provider.js';
-export * from './connector-lease.dto.js';