test(ai): enforce complete audit assurance gates

.github/workflows/ci.yml

@@ -52,8 +52,8 @@ jobs:
       - name: Enable Corepack
         run: corepack enable
 
-      - name: Install dependencies
-        run: pnpm install --no-frozen-lockfile
+      - name: Install reproducible dependencies
+        run: pnpm install --frozen-lockfile
 
       - name: Check formatting
         run: pnpm format:check

.gitignore

@@ -4,6 +4,7 @@ node_modules/
 .next/
 dist/
 coverage/
+*.tsbuildinfo
 .env
 .env.*
 !.env.example

CHANGELOG.md

@@ -6,6 +6,7 @@ All notable changes to LifeOS are documented in this file.
 
 ### Added
 
+- Executable AI-service JSDoc and exact 100% statement, branch, function, and line coverage gates, with an operator-facing governance assurance boundary.
 - Tenant-safe durable planning search across goals, projects, and tasks, with Unicode-normalized exact, prefix, and whole-token matching.
 - An authenticated same-origin planning-search boundary that signs the session-derived workspace context and forwards no browser credential to planning-service.
 - An accessible quick-capture and search surface that keeps browser-local Today drafts visibly separate from durable workspace records.
@@ -18,6 +19,7 @@ All notable changes to LifeOS are documented in this file.
 
 ### Fixed
 
+- Stale AI proposal revision conflicts now belong to the technology-independent audit domain while the PostgreSQL adapter preserves its compatibility export.
 - Planning search now normalizes browser query text and prevents stale or unmounted requests from replacing the latest visible result state.
 - Reminder fatigue deferral now crosses long IANA offset fallbacks and next-day quiet hours without abandoning the claimed occurrence.
 - Notification workers now recover expired claims and exact delivery replays without creating duplicate inbox messages.

apps/ai-service/package.json

@@ -4,10 +4,11 @@
   "private": true,
   "scripts": {
     "build": "nest build",
-    "dev": "nest start --watch",
-    "lint": "tsc --noEmit",
-    "test": "vitest run --passWithNoTests --no-file-parallelism",
-    "typecheck": "tsc --noEmit"
+    "dev": "nest start --watch --entryFile server",
+    "lint": "tsc --noEmit && prettier --single-quote --check package.json tsconfig.json vitest.config.ts \"src/**/*.ts\" ../../docs/operations/ai-proposal-audit-assurance.md ../../docs/superpowers/specs/2026-08-04-ai-service-quality-gates-design.md ../../docs/superpowers/plans/2026-08-04-ai-service-quality-gates.md",
+    "test": "vitest run --no-file-parallelism --coverage",
+    "typecheck": "tsc --noEmit",
+    "start": "node dist/server.js"
   },
   "dependencies": {
     "@nestjs/common": "^11.1.6",
@@ -21,6 +22,7 @@
     "@nestjs/cli": "^11.0.10",
     "@types/node": "^24.3.0",
     "@types/pg": "^8.20.0",
+    "@vitest/coverage-v8": "^3.2.4",
     "typescript": "^5.9.2",
     "vitest": "^3.2.4"
   }

apps/ai-service/src/ai-runtime.ts

@@ -11,6 +11,7 @@ import { ProposalService, RuleBasedProposalModel } from './proposal-service';
 const MAXIMUM_CONFIGURATION_LENGTH = 8 * 1024;
 const databaseLogger = new Logger('AiDatabasePool');
 
+/** Bounded environment values accepted by the AI production runtime. */
 type RuntimeEnvironment = Readonly<Record<string, string | undefined>>;
 
 /** Bounded PostgreSQL pool boundary used by the AI production runtime. */
@@ -44,6 +45,7 @@ export function createAiPoolErrorListener(
 
 /** Adapts node-postgres to the minimal pool contract required by the AI service. */
 class NodePostgresAiPool implements AiPool {
+  /** Creates the bounded adapter around one owned node-postgres pool. */
   constructor(private readonly pool: Pool) {}
 
   /** Executes SQL without exposing the wider node-postgres client surface. */
@@ -63,6 +65,7 @@ class NodePostgresAiPool implements AiPool {
 
 /** Narrows the runtime pool to the repository's parameterized SQL contract. */
 class NodePostgresProposalAuditSqlClient implements ProposalAuditSqlClient {
+  /** Creates the repository SQL adapter over the runtime-owned pool. */
   constructor(private readonly pool: AiPool) {}
 
   /** Delegates one parameterized query through the bounded pool interface. */

apps/ai-service/src/docstring-coverage.test.ts

@@ -0,0 +1,163 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import * as ts from 'typescript';
+import { describe, expect, it } from 'vitest';
+
+/** One production declaration missing an explanatory JSDoc block. */
+interface UndocumentedDeclaration {
+  readonly file: string;
+  readonly line: number;
+  readonly declaration: string;
+}
+
+/** Reports whether the declaration's leading trivia ends with one JSDoc block. */
+function hasJSDoc(node: ts.Node, sourceFile: ts.SourceFile): boolean {
+  const leadingTrivia = sourceFile.text.slice(
+    node.getFullStart(),
+    node.getStart(sourceFile),
+  );
+  return /\/\*\*[\s\S]*?\*\/\s*$/u.test(leadingTrivia);
+}
+
+/** Maps a callable variable declaration to the owning statement carrying JSDoc. */
+function documentationOwner(node: ts.Node): ts.Node {
+  if (
+    ts.isVariableDeclaration(node) &&
+    ts.isVariableDeclarationList(node.parent) &&
+    ts.isVariableStatement(node.parent.parent)
+  ) {
+    return node.parent.parent;
+  }
+  return node;
+}
+
+/** Identifies callable variable or property initializers that require documentation. */
+function hasCallableInitializer(
+  node: ts.VariableDeclaration | ts.PropertyDeclaration,
+): boolean {
+  return (
+    node.initializer !== undefined &&
+    (ts.isArrowFunction(node.initializer) ||
+      ts.isFunctionExpression(node.initializer))
+  );
+}
+
+/** Produces a stable human-readable name for a documentation failure. */
+function declarationName(node: ts.Node): string {
+  if (ts.isConstructorDeclaration(node)) {
+    const parent = node.parent;
+    return ts.isClassDeclaration(parent) && parent.name
+      ? `${parent.name.text}.constructor`
+      : 'constructor';
+  }
+  if (
+    ts.isVariableDeclaration(node) ||
+    ts.isPropertyDeclaration(node) ||
+    ts.isFunctionDeclaration(node) ||
+    ts.isClassDeclaration(node) ||
+    ts.isInterfaceDeclaration(node) ||
+    ts.isTypeAliasDeclaration(node) ||
+    ts.isMethodDeclaration(node) ||
+    ts.isMethodSignature(node)
+  ) {
+    return node.name?.getText() ?? node.kind.toString();
+  }
+  return node.kind.toString();
+}
+
+/** Identifies production declaration kinds that require explanatory JSDoc. */
+function requiresJSDoc(node: ts.Node): boolean {
+  return (
+    ts.isFunctionDeclaration(node) ||
+    ts.isClassDeclaration(node) ||
+    ts.isInterfaceDeclaration(node) ||
+    ts.isTypeAliasDeclaration(node) ||
+    ts.isMethodDeclaration(node) ||
+    ts.isMethodSignature(node) ||
+    ts.isConstructorDeclaration(node) ||
+    (ts.isVariableDeclaration(node) && hasCallableInitializer(node)) ||
+    (ts.isPropertyDeclaration(node) && hasCallableInitializer(node))
+  );
+}
+
+/** Restricts the contract to top-level declarations and class/interface members. */
+function isDocumentedScope(node: ts.Node, sourceFile: ts.SourceFile): boolean {
+  const owner = documentationOwner(node);
+  return (
+    owner.parent === sourceFile ||
+    ts.isClassDeclaration(node.parent) ||
+    ts.isInterfaceDeclaration(node.parent)
+  );
+}
+
+/** Collects every undocumented production declaration from one TypeScript source. */
+function collectUndocumentedDeclarations(
+  file: string,
+  source: string,
+): UndocumentedDeclaration[] {
+  const sourceFile = ts.createSourceFile(
+    file,
+    source,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TS,
+  );
+  const missing: UndocumentedDeclaration[] = [];
+
+  /** Visits one syntax node and records any in-scope documentation failure. */
+  function visit(node: ts.Node): void {
+    if (
+      requiresJSDoc(node) &&
+      isDocumentedScope(node, sourceFile) &&
+      !hasJSDoc(documentationOwner(node), sourceFile)
+    ) {
+      const position = sourceFile.getLineAndCharacterOfPosition(
+        node.getStart(sourceFile),
+      );
+      missing.push({
+        file,
+        line: position.line + 1,
+        declaration: declarationName(node),
+      });
+    }
+    ts.forEachChild(node, visit);
+  }
+
+  visit(sourceFile);
+  return missing;
+}
+
+/** Discovers production TypeScript sources while excluding all test fixtures. */
+async function discoverSourceFiles(directory: string): Promise<string[]> {
+  const entries = await readdir(directory, { withFileTypes: true });
+  const files = await Promise.all(
+    entries.map(async (entry) => {
+      const path = resolve(directory, entry.name);
+      if (entry.isDirectory()) {
+        return await discoverSourceFiles(path);
+      }
+      return entry.isFile() &&
+        entry.name.endsWith('.ts') &&
+        !entry.name.endsWith('.test.ts')
+        ? [path]
+        : [];
+    }),
+  );
+  return files.flat().sort();
+}
+
+describe('ai-service source documentation', () => {
+  it('documents every production declaration with JSDoc', async () => {
+    const sourceFiles = await discoverSourceFiles(__dirname);
+    const missing = (
+      await Promise.all(
+        sourceFiles.map(async (path) => {
+          const source = await readFile(path, 'utf8');
+          return collectUndocumentedDeclarations(path, source);
+        }),
+      )
+    ).flat();
+
+    expect(missing).toEqual([]);
+  });
+});

apps/ai-service/src/main.ts

@@ -21,6 +21,7 @@ import {
 import {
   type ProposalAuditRecord,
   ProposalAuditValidationError,
+  ProposalDigestMismatchError,
   type ProposalDecisionEvent,
 } from './proposal-audit-domain';
 import {
@@ -34,7 +35,6 @@ import {
 import {
   ProposalAuditPersistenceError,
   ProposalDecisionConflictError,
-  ProposalDigestMismatchError,
 } from './postgres-proposal-audit-repository';
 
 /** Injection token for the narrowed inert proposal-generation contract. */
@@ -47,7 +47,7 @@ export const AI_RUNTIME = Symbol('AI_RUNTIME');
 const auditLogger = new Logger('AiProposalAudit');
 
 /** Narrow read-only proposal-generation contract exposed to the legacy controller. */
-interface ProposalGenerator {
+export interface ProposalGenerator {
   /** Generates an inert proposal without executing any proposed operation. */
   generateProposal(
     workspaceId: string,
@@ -273,13 +273,41 @@ export class AiAppModule {}
 })
 export class AiProductionModule {}
 
-/** Boots the production AI process with exactly-once shutdown hooks. */
-async function bootstrap(): Promise<void> {
-  const app = await NestFactory.create(AiProductionModule);
-  app.enableShutdownHooks();
-  await app.listen(Number(process.env.AI_SERVICE_PORT ?? 4105), '0.0.0.0');
+/** Minimal Nest application behavior needed by the AI process bootstrap. */
+export interface AiBootstrapApplication {
+  /** Enables Nest-managed lifecycle shutdown hooks. */
+  enableShutdownHooks(): void;
+  /** Starts the HTTP server on one validated port and fixed host. */
+  listen(port: number, host: string): Promise<unknown>;
+}
+
+/** Factory used to construct the production Nest application. */
+export type AiApplicationFactory = () => Promise<AiBootstrapApplication>;
+
+/** Creates the production Nest application without starting its listener. */
+export async function createAiApplication(): Promise<AiBootstrapApplication> {
+  return await NestFactory.create(AiProductionModule);
 }
 
-if (require.main === module) {
-  void bootstrap();
+/** Parses the optional AI service port into the supported TCP range. */
+export function resolveAiServicePort(value: string | undefined): number {
+  if (value === undefined || value.trim() === '') {
+    return 4_105;
+  }
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed < 1 || parsed > 65_535) {
+    throw new Error('AI service port is invalid');
+  }
+  return parsed;
+}
+
+/** Boots the production AI process with exactly-once shutdown hooks. */
+export async function bootstrapAiService(
+  environment: Readonly<Record<string, string | undefined>> = process.env,
+  applicationFactory: AiApplicationFactory = createAiApplication,
+): Promise<void> {
+  const port = resolveAiServicePort(environment.AI_SERVICE_PORT);
+  const app = await applicationFactory();
+  app.enableShutdownHooks();
+  await app.listen(port, '0.0.0.0');
 }