@llm-dev-ops/agentics-cli 2.3.0 → 2.4.0

package/dist/pipeline/auto-chain.js

@@ -87,6 +87,133 @@ function copyDirRecursive(src, dest) {
  * Called after every phase so even if later phases fail, earlier artifacts
  * are still available.
  */
+/**
+ * ADR-PIPELINE-074: scaffold body for `src/logger.ts`.
+ *
+ * Uses `node:async_hooks` AsyncLocalStorage so concurrent Express/Hono
+ * requests NEVER cross-contaminate log lines. The legacy
+ * `let currentCorrelationId` module-level mutable has been removed; any
+ * generator that reintroduces it is caught by PGV-016.
+ *
+ * Exports:
+ *   - `Logger` interface with info/warn/error/child
+ *   - `createLogger(service)` factory
+ *   - `runWithCorrelation(id, fn)` — wraps an async scope with the ID
+ *   - `getCorrelationId()` — returns the ID for the current async scope
+ *   - `setCorrelationId(id)` — legacy shim; mutates the current store
+ */
+export const LOGGER_SCAFFOLD = `// Auto-generated by Agentics pipeline (ADR-PIPELINE-074)
+// Correlation IDs flow through an AsyncLocalStorage so concurrent requests
+// never cross-contaminate log lines. Import runWithCorrelation + createLogger
+// from here; NEVER reach for a module-level mutable to store the ID.
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+export interface Logger {
+  info(event: string, data?: Record<string, unknown>): void;
+  warn(event: string, data?: Record<string, unknown>): void;
+  error(event: string, error: Error, data?: Record<string, unknown>): void;
+  child(bindings: Record<string, unknown>): Logger;
+}
+
+interface LoggerContext {
+  correlationId?: string;
+  bindings: Record<string, unknown>;
+}
+
+const storage = new AsyncLocalStorage<LoggerContext>();
+
+/**
+ * Run \`fn\` with \`correlationId\` installed in the current async scope.
+ * Every log line emitted inside \`fn\` and its async descendants will carry
+ * this ID, and it will NOT leak to other concurrent requests.
+ */
+export function runWithCorrelation<T>(correlationId: string, fn: () => T): T {
+  const parent = storage.getStore();
+  const ctx: LoggerContext = {
+    correlationId,
+    bindings: parent?.bindings ?? {},
+  };
+  return storage.run(ctx, fn);
+}
+
+/** Returns the correlation ID for the current async scope, if any. */
+export function getCorrelationId(): string | undefined {
+  return storage.getStore()?.correlationId;
+}
+
+/**
+ * Back-compat shim — deprecated. Retained for legacy callers, but
+ * SHOULD NOT be used inside request handlers. Use runWithCorrelation.
+ * Under AsyncLocalStorage, this mutates the current store in place;
+ * outside an async scope it is a silent no-op.
+ */
+export function setCorrelationId(id: string | undefined): void {
+  const ctx = storage.getStore();
+  if (ctx) ctx.correlationId = id;
+}
+
+export function createLogger(service: string): Logger {
+  const build = (bindings: Record<string, unknown>): Logger => {
+    const emit = (level: string, event: string, extra?: Record<string, unknown>): void => {
+      const ctx = storage.getStore();
+      const entry = {
+        timestamp: new Date().toISOString(),
+        level,
+        service,
+        event,
+        ...(ctx?.correlationId ? { correlationId: ctx.correlationId } : {}),
+        ...bindings,
+        ...(ctx?.bindings ?? {}),
+        ...extra,
+      };
+      process.stderr.write(JSON.stringify(entry) + '\\n');
+    };
+    return {
+      info: (event, data) => emit('info', event, data),
+      warn: (event, data) => emit('warn', event, data),
+      error: (event, err, data) => emit('error', event, {
+        error: err.message,
+        stack: err.stack,
+        ...data,
+      }),
+      child: (childBindings) => build({ ...bindings, ...childBindings }),
+    };
+  };
+  return build({});
+}
+`;
+/**
+ * ADR-PIPELINE-074: concurrency-correctness test emitted alongside
+ * `src/logger.ts` in every generated project. Fails loudly if
+ * AsyncLocalStorage wiring regresses.
+ */
+export const LOGGER_CONCURRENCY_TEST_SCAFFOLD = `// Auto-generated by Agentics pipeline (ADR-PIPELINE-074)
+// Proves correlation IDs do NOT leak across concurrent async tasks.
+// Works with vitest and jest — both expose describe/it/expect as globals.
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { describe, it, expect } from 'vitest';
+import { runWithCorrelation, getCorrelationId } from './logger.js';
+
+describe('logger correlation-id async scoping (ADR-PIPELINE-074)', () => {
+  it('does not leak correlation IDs across concurrent async tasks', async () => {
+    const results: Array<{ requested: string; observed: string | undefined }> = [];
+    const tasks: Promise<void>[] = [];
+    for (let i = 0; i < 50; i++) {
+      const id = \`req-\${i}\`;
+      tasks.push(
+        runWithCorrelation(id, async () => {
+          await new Promise((r) => setTimeout(r, Math.random() * 10));
+          results.push({ requested: id, observed: getCorrelationId() });
+        }),
+      );
+    }
+    await Promise.all(tasks);
+    for (const r of results) {
+      expect(r.observed).toBe(r.requested);
+    }
+  });
+});
+`;
 /**
  * ADR-PIPELINE-068: scaffold body for `src/simulation-lineage.ts`.
  *
@@ -289,10 +416,796 @@ export class CircuitBreaker {
   getState(): string { return this.state; }
 }
 `;
+/**
+ * ADR-PIPELINE-075: scaffold body for `src/persistence/repository.ts`.
+ *
+ * Defines the `Repository<T>` interface every stateful service should
+ * depend on. Each entity is identified by `idOf(entity)`, validated by a
+ * Zod schema on read, and bound to a table name for the SQLite backend.
+ */
+export const REPOSITORY_SCAFFOLD = `// Auto-generated by Agentics pipeline (ADR-PIPELINE-075)
+// Repository interface every stateful service should depend on.
+// Generators: use this instead of storing state in a Map<string, T>.
+import type { ZodType } from 'zod';
+
+export interface Repository<T> {
+  save(entity: T): Promise<void>;
+  get(id: string): Promise<T | null>;
+  list(filter?: Partial<T>): Promise<readonly T[]>;
+  delete(id: string): Promise<void>;
+}
+
+export interface RepositoryOptions<T> {
+  /** How to extract the primary key from an entity. */
+  readonly idOf: (entity: T) => string;
+  /** Zod schema used to re-validate rows on load (SQLite JSON columns are untrusted). */
+  readonly schema: ZodType<T>;
+  /** Table name for SQLite backend. Must match /^[a-zA-Z_][a-zA-Z0-9_]*$/. */
+  readonly tableName: string;
+}
+
+/** Errors thrown by all Repository implementations. */
+export class RepositoryError extends Error {
+  constructor(message: string, public readonly code: string) {
+    super(\`\${code}: \${message}\`);
+    this.name = 'RepositoryError';
+  }
+}
+`;
+/**
+ * ADR-PIPELINE-075: scaffold body for `src/persistence/in-memory-repository.ts`.
+ *
+ * Test-friendly `Repository<T>` implementation backed by a Map. Validates
+ * on write AND read so test fixtures catch schema drift. Production
+ * services should swap in SqliteRepository via the composition root.
+ */
+export const IN_MEMORY_REPO_SCAFFOLD = `// Auto-generated by Agentics pipeline (ADR-PIPELINE-075)
+// In-memory Repository<T> for tests. Not for production use.
+import type { Repository, RepositoryOptions } from './repository.js';
+
+export class InMemoryRepository<T> implements Repository<T> {
+  private readonly rows = new Map<string, T>();
+  constructor(private readonly options: RepositoryOptions<T>) {}
+
+  async save(entity: T): Promise<void> {
+    const validated = this.options.schema.parse(entity);
+    this.rows.set(this.options.idOf(validated), validated);
+  }
+
+  async get(id: string): Promise<T | null> {
+    const row = this.rows.get(id);
+    return row === undefined ? null : row;
+  }
+
+  async list(filter?: Partial<T>): Promise<readonly T[]> {
+    const all = Array.from(this.rows.values());
+    if (!filter) return all;
+    return all.filter(row =>
+      Object.entries(filter).every(
+        ([k, v]) => (row as Record<string, unknown>)[k] === v,
+      ),
+    );
+  }
+
+  async delete(id: string): Promise<void> {
+    this.rows.delete(id);
+  }
+
+  /** Test helper — never call from production code. */
+  clear(): void {
+    this.rows.clear();
+  }
+
+  /** Test helper — returns the current row count. */
+  get size(): number {
+    return this.rows.size;
+  }
+}
+`;
+/**
+ * ADR-PIPELINE-075: scaffold body for `src/persistence/sqlite-repository.ts`.
+ *
+ * Production `Repository<T>` backed by better-sqlite3. Stores each entity
+ * as a JSON column keyed by its primary key. Zod re-validates on read
+ * because the JSON column is untrusted at runtime.
+ *
+ * Generated projects must add better-sqlite3 + @types/better-sqlite3 to
+ * their package.json — the cross-cutting prompt footer reminds the coding
+ * agent to include these deps.
+ */
+export const SQLITE_REPO_SCAFFOLD = `// Auto-generated by Agentics pipeline (ADR-PIPELINE-075)
+// SQLite-backed Repository<T> using better-sqlite3.
+// Requires: better-sqlite3 in dependencies, @types/better-sqlite3 in devDependencies.
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import type { Repository, RepositoryOptions } from './repository.js';
+import { RepositoryError } from './repository.js';
+
+// Minimal structural type — works with better-sqlite3 without importing it
+// into the scaffold (so the scaffold compiles even when the dependency
+// isn't installed in the pipeline's own test environment).
+export interface BetterSqliteDatabase {
+  exec(sql: string): void;
+  prepare(sql: string): {
+    run(...params: any[]): { changes: number; lastInsertRowid: number | bigint };
+    get(...params: any[]): any;
+    all(...params: any[]): any[];
+  };
+}
+
+export interface SqliteRepositoryDeps {
+  readonly db: BetterSqliteDatabase;
+}
+
+export class SqliteRepository<T> implements Repository<T> {
+  constructor(
+    private readonly deps: SqliteRepositoryDeps,
+    private readonly options: RepositoryOptions<T>,
+  ) {
+    this.assertSafeTableName();
+    this.deps.db.exec(\`
+      CREATE TABLE IF NOT EXISTS \${this.options.tableName} (
+        id TEXT PRIMARY KEY,
+        data TEXT NOT NULL,
+        updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
+      );
+    \`);
+  }
+
+  private assertSafeTableName(): void {
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(this.options.tableName)) {
+      throw new RepositoryError(\`unsafe table name: \${this.options.tableName}\`, 'ECLI-REPO-001');
+    }
+  }
+
+  async save(entity: T): Promise<void> {
+    const validated = this.options.schema.parse(entity);
+    const id = this.options.idOf(validated);
+    const data = JSON.stringify(validated);
+    this.deps.db
+      .prepare(
+        \`INSERT INTO \${this.options.tableName} (id, data) VALUES (?, ?)
+         ON CONFLICT(id) DO UPDATE SET data = excluded.data,
+           updated_at = strftime('%Y-%m-%dT%H:%M:%fZ','now')\`,
+      )
+      .run(id, data);
+  }
+
+  async get(id: string): Promise<T | null> {
+    const row = this.deps.db
+      .prepare(\`SELECT data FROM \${this.options.tableName} WHERE id = ?\`)
+      .get(id) as { data: string } | undefined;
+    if (!row) return null;
+    return this.options.schema.parse(JSON.parse(row.data));
+  }
+
+  async list(filter?: Partial<T>): Promise<readonly T[]> {
+    const rows = this.deps.db
+      .prepare(\`SELECT data FROM \${this.options.tableName}\`)
+      .all() as Array<{ data: string }>;
+    const parsed = rows.map(r => this.options.schema.parse(JSON.parse(r.data)));
+    if (!filter) return parsed;
+    return parsed.filter(row =>
+      Object.entries(filter).every(
+        ([k, v]) => (row as Record<string, unknown>)[k] === v,
+      ),
+    );
+  }
+
+  async delete(id: string): Promise<void> {
+    this.deps.db.prepare(\`DELETE FROM \${this.options.tableName} WHERE id = ?\`).run(id);
+  }
+}
+`;
+/**
+ * ADR-PIPELINE-075: scaffold body for `src/persistence/audit-repository.ts`.
+ *
+ * Append-only audit repository. NO update, NO delete — an audit entry is
+ * committed and lives forever. Services that need to mutate a past entry
+ * have to bypass the repository and talk raw SQL, which PGV and code
+ * review will catch.
+ */
+export const AUDIT_REPO_SCAFFOLD = `// Auto-generated by Agentics pipeline (ADR-PIPELINE-075)
+// Append-only audit repository. No update, no delete by design.
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import type { BetterSqliteDatabase } from './sqlite-repository.js';
+
+export interface AuditEntry {
+  readonly entryId: string;
+  readonly prevHash: string;
+  readonly hash: string;
+  readonly payload: Record<string, unknown>;
+  readonly actor: string;
+  readonly action: string;
+  readonly entityType: string;
+  readonly entityId: string;
+  readonly createdAt: string;
+}
+
+export interface AuditRepositoryDeps {
+  readonly db: BetterSqliteDatabase;
+}
+
+export class AppendOnlyAuditRepository {
+  constructor(private readonly deps: AuditRepositoryDeps) {
+    this.deps.db.exec(\`
+      CREATE TABLE IF NOT EXISTS audit_log (
+        sequence INTEGER PRIMARY KEY AUTOINCREMENT,
+        entry_id TEXT NOT NULL UNIQUE,
+        prev_hash TEXT NOT NULL,
+        hash TEXT NOT NULL,
+        payload TEXT NOT NULL,
+        actor TEXT NOT NULL,
+        action TEXT NOT NULL,
+        entity_type TEXT NOT NULL,
+        entity_id TEXT NOT NULL,
+        created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
+      );
+      CREATE INDEX IF NOT EXISTS idx_audit_log_entity
+        ON audit_log(entity_type, entity_id);
+    \`);
+  }
+
+  append(entry: AuditEntry): void {
+    this.deps.db
+      .prepare(
+        \`INSERT INTO audit_log
+         (entry_id, prev_hash, hash, payload, actor, action, entity_type, entity_id, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)\`,
+      )
+      .run(
+        entry.entryId,
+        entry.prevHash,
+        entry.hash,
+        JSON.stringify(entry.payload),
+        entry.actor,
+        entry.action,
+        entry.entityType,
+        entry.entityId,
+        entry.createdAt,
+      );
+  }
+
+  list(): readonly AuditEntry[] {
+    const rows = this.deps.db
+      .prepare(\`SELECT * FROM audit_log ORDER BY sequence ASC\`)
+      .all() as Array<{
+      entry_id: string;
+      prev_hash: string;
+      hash: string;
+      payload: string;
+      actor: string;
+      action: string;
+      entity_type: string;
+      entity_id: string;
+      created_at: string;
+    }>;
+    return rows.map(r => ({
+      entryId: r.entry_id,
+      prevHash: r.prev_hash,
+      hash: r.hash,
+      payload: JSON.parse(r.payload),
+      actor: r.actor,
+      action: r.action,
+      entityType: r.entity_type,
+      entityId: r.entity_id,
+      createdAt: r.created_at,
+    }));
+  }
+
+  listByEntity(entityType: string, entityId: string): readonly AuditEntry[] {
+    const rows = this.deps.db
+      .prepare(
+        \`SELECT * FROM audit_log
+         WHERE entity_type = ? AND entity_id = ?
+         ORDER BY sequence ASC\`,
+      )
+      .all(entityType, entityId) as Array<{
+      entry_id: string;
+      prev_hash: string;
+      hash: string;
+      payload: string;
+      actor: string;
+      action: string;
+      entity_type: string;
+      entity_id: string;
+      created_at: string;
+    }>;
+    return rows.map(r => ({
+      entryId: r.entry_id,
+      prevHash: r.prev_hash,
+      hash: r.hash,
+      payload: JSON.parse(r.payload),
+      actor: r.actor,
+      action: r.action,
+      entityType: r.entity_type,
+      entityId: r.entity_id,
+      createdAt: r.created_at,
+    }));
+  }
+
+  /** Total row count — used by verify() and reconciliation jobs. */
+  size(): number {
+    const row = this.deps.db
+      .prepare('SELECT COUNT(*) AS n FROM audit_log')
+      .get() as { n: number };
+    return row.n;
+  }
+}
+`;
+/**
+ * ADR-PIPELINE-078: scaffold body for `src/persistence/canonical-json.ts`.
+ *
+ * Deterministic JSON serialization for audit hash chains and idempotency
+ * keys. Follows JCS (RFC 8785) closely enough for the pipeline's needs:
+ * object keys are sorted lexicographically at every depth; arrays preserve
+ * order; strings, numbers, booleans, and null use standard JSON encoding.
+ *
+ * Rejects undefined, BigInt, and circular references. Date objects should
+ * be serialized as ISO strings at the boundary BEFORE passing to this
+ * function.
+ */
+export const CANONICAL_JSON_SCAFFOLD = `// Auto-generated by Agentics pipeline (ADR-PIPELINE-078)
+// Deterministic JSON for audit hash chains. Keys sorted at every depth.
+
+export class CanonicalJsonError extends Error {
+  constructor(message: string) {
+    super(\`ECLI-CJ-078: \${message}\`);
+    this.name = 'CanonicalJsonError';
+  }
+}
+
+/**
+ * Canonicalize \`value\` into a deterministic JSON string. Keys are sorted
+ * at every level; arrays preserve order; primitives use standard encoding.
+ */
+export function canonicalJson(value: unknown): string {
+  const visited = new WeakSet<object>();
+  return serialize(value, visited);
+}
+
+function serialize(value: unknown, visited: WeakSet<object>): string {
+  if (value === undefined) {
+    throw new CanonicalJsonError('undefined is not canonicalizable — pass null instead');
+  }
+  if (value === null) return 'null';
+  if (typeof value === 'boolean') return value ? 'true' : 'false';
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) {
+      throw new CanonicalJsonError(\`non-finite number: \${String(value)}\`);
+    }
+    return JSON.stringify(value);
+  }
+  if (typeof value === 'string') {
+    return JSON.stringify(value);
+  }
+  if (typeof value === 'bigint') {
+    throw new CanonicalJsonError('BigInt is not canonicalizable — convert to string at the boundary');
+  }
+  if (Array.isArray(value)) {
+    if (visited.has(value)) throw new CanonicalJsonError('circular reference in array');
+    visited.add(value);
+    const parts = value.map(item => serialize(item, visited));
+    visited.delete(value);
+    return '[' + parts.join(',') + ']';
+  }
+  if (typeof value === 'object') {
+    if (visited.has(value as object)) throw new CanonicalJsonError('circular reference in object');
+    visited.add(value as object);
+    const record = value as Record<string, unknown>;
+    const keys = Object.keys(record).sort();
+    const pairs: string[] = [];
+    for (const key of keys) {
+      const v = record[key];
+      if (v === undefined) continue;
+      pairs.push(JSON.stringify(key) + ':' + serialize(v, visited));
+    }
+    visited.delete(value as object);
+    return '{' + pairs.join(',') + '}';
+  }
+  throw new CanonicalJsonError(\`unsupported value type: \${typeof value}\`);
+}
+`;
+/**
+ * ADR-PIPELINE-078: scaffold body for `src/persistence/audit-hash.ts`.
+ *
+ * Wraps `canonicalJson` with audit-log-specific conventions. Every
+ * generated `AuditService.append()` method should call `hashAuditEntry`
+ * rather than rolling its own `JSON.stringify + createHash` chain.
+ */
+export const AUDIT_HASH_SCAFFOLD = `// Auto-generated by Agentics pipeline (ADR-PIPELINE-078)
+// Audit hash-chain helper. Import hashAuditEntry instead of hand-rolling
+// createHash('sha256').update(JSON.stringify(...)).
+import { createHash } from 'node:crypto';
+import { canonicalJson } from './canonical-json.js';
+
+export interface HashChainInput {
+  readonly prevHash: string;
+  readonly entryId: string;
+  readonly actor: string;
+  readonly action: string;
+  readonly entityType: string;
+  readonly entityId: string;
+  readonly payload: unknown;
+  readonly createdAt: string;
+}
+
+/**
+ * Deterministically hash an audit entry's content + its link to the
+ * previous entry. Payload keys are sorted at every depth so mutations
+ * at any nesting level change the hash.
+ */
+export function hashAuditEntry(input: HashChainInput): string {
+  const body = canonicalJson({
+    prevHash: input.prevHash,
+    entryId: input.entryId,
+    actor: input.actor,
+    action: input.action,
+    entityType: input.entityType,
+    entityId: input.entityId,
+    payload: input.payload,
+    createdAt: input.createdAt,
+  });
+  return createHash('sha256').update(body).digest('hex');
+}
+`;
+/**
+ * ADR-PIPELINE-077: scaffold body for `src/erp/schema-provenance.ts`.
+ *
+ * Every generated ERP adapter file (schema.ts, <system>-adapter.ts, etc.)
+ * must export an `ERP_SCHEMA_PROVENANCE` constant of type
+ * `ErpSchemaProvenance` declaring whether the schema was invented,
+ * pulled from a catalog, or validated by an SME. Under
+ * `AGENTICS_ERP_STRICT=true`, `assertErpProvenanceOrFail` refuses to
+ * start when source='invented'. PGV-020 enforces presence, PGV-021
+ * enforces reviewer + catalog_version on validated entries.
+ */
+export const ERP_SCHEMA_PROVENANCE_SCAFFOLD = `// Auto-generated by Agentics pipeline (ADR-PIPELINE-077)
+// Provenance tag for generated ERP schemas. MANDATORY on every file
+// under src/erp/ that exports Zod schemas targeting an external ERP.
+
+export type ErpProvenanceSource = 'invented' | 'catalog' | 'validated';
+
+export interface ErpSchemaProvenance {
+  /** Target ERP system — e.g. 'Ramco Aviation', 'Oracle OPERA', 'SAP S/4HANA'. */
+  readonly erp_system: string;
+  /** Specific module the schema targets — 'Flight Catering Order'. */
+  readonly module: string;
+  /** Validation stage: invented (no review), catalog (fields match), validated (SME-reviewed). */
+  readonly source: ErpProvenanceSource;
+  /** Version identifier of the catalog source, when known. */
+  readonly catalog_version: string | null;
+  /** ISO timestamp of SME review when source='validated'. */
+  readonly validated_at: string | null;
+  /** Reviewer name + role when source='validated'. */
+  readonly reviewer: { name: string; role: string } | null;
+  /** Free-text notes visible in startup logs and generated README. */
+  readonly notes: string;
+}
+
+/**
+ * Assert an ERP adapter is allowed to run in the current environment.
+ * Under AGENTICS_ERP_STRICT=true, source='invented' throws ECLI-ERP-077
+ * and the process exits with code 77.
+ */
+export function assertErpProvenanceOrFail(
+  provenance: ErpSchemaProvenance,
+  env: NodeJS.ProcessEnv = process.env,
+): void {
+  const strict = env['AGENTICS_ERP_STRICT'] === 'true';
+  if (strict && provenance.source === 'invented') {
+    throw new Error(
+      \`ECLI-ERP-077: ERP adapter for \${provenance.erp_system}/\${provenance.module} has source='invented' \` +
+      \`and AGENTICS_ERP_STRICT=true. Pilot deployment requires an SME review — set source='validated' \` +
+      \`and provide reviewer + catalog_version before enabling strict mode.\`,
+    );
+  }
+}
+
+/** Console-friendly banner for startup logs + demo output. */
+export function formatProvenanceBanner(provenance: ErpSchemaProvenance): string {
+  const icon = provenance.source === 'validated' ? '✅' :
+               provenance.source === 'catalog'   ? '🟡' :
+                                                    '⚠️ ';
+  const lines: string[] = [
+    \`\${icon} ERP SCHEMA PROVENANCE — \${provenance.erp_system} / \${provenance.module}\`,
+    \`   source: \${provenance.source}\`,
+  ];
+  if (provenance.catalog_version) lines.push(\`   catalog: \${provenance.catalog_version}\`);
+  if (provenance.validated_at) lines.push(\`   validated: \${provenance.validated_at}\`);
+  if (provenance.reviewer) lines.push(\`   reviewer: \${provenance.reviewer.name} (\${provenance.reviewer.role})\`);
+  if (provenance.source === 'invented') {
+    lines.push(
+      '   ',
+      '   WARNING: This schema has not been validated against a real ERP document catalog.',
+      '   Pilot deployment requires an SME review before the first live call.',
+      "   Set AGENTICS_ERP_STRICT=true in production to block runs until source='validated'.",
+    );
+  }
+  return lines.join('\\n');
+}
+
+/** Convenience wrapper — prints the banner to stderr. */
+export function printProvenanceBanner(provenance: ErpSchemaProvenance): void {
+  process.stderr.write(formatProvenanceBanner(provenance) + '\\n');
+}
+`;
+/**
+ * ADR-PIPELINE-076: scaffold body for `src/api/base-app.ts` (Hono variant).
+ *
+ * Ships a wire-complete base app so the coding agent never writes
+ * middleware/metrics/health plumbing from scratch. Generators extend
+ * via `createBaseApp({...}).route('/api/<domain>', yourRouter)` instead
+ * of rebuilding.
+ *
+ * Every generated project that imports `createBaseApp` gets:
+ *   - correlation middleware (AsyncLocalStorage-scoped, ADR-074)
+ *   - request logging with duration histogram
+ *   - GET /health/live       (process up check)
+ *   - GET /health/ready      (every readiness check passes)
+ *   - GET /metrics           (Prometheus text, ADR-051)
+ *   - structured error handler (last)
+ */
+export const BASE_APP_SCAFFOLD_HONO = `// Auto-generated by Agentics pipeline (ADR-PIPELINE-076)
+// Wire-complete Hono app base. DO NOT rewrite — extend via
+// \`createBaseApp(deps).route('/api/...', yourRouter)\` from your routes module.
+import { Hono } from 'hono';
+import { randomUUID } from 'node:crypto';
+import { runWithCorrelation, createLogger } from '../logger.js';
+import { incrementCounter, recordHistogram, metricsHandler } from '../middleware.js';
+
+export interface HealthCheck {
+  readonly name: string;
+  readonly check: () => Promise<{ ok: boolean; detail?: string }>;
+}
+
+export interface BaseAppDeps {
+  readonly serviceName: string;
+  readonly version: string;
+  readonly readiness: readonly HealthCheck[];
+}
+
+export interface BaseAppContextVariables {
+  correlationId: string;
+  startedAt: number;
+}
+
+const baseLogger = createLogger('base-app');
+
+/**
+ * Build the wire-complete base app.
+ *
+ * Returned Hono instance already has:
+ *   - correlation ID middleware (AsyncLocalStorage-scoped)
+ *   - request logging with duration histogram
+ *   - GET /health/live       process-up check
+ *   - GET /health/ready      runs every registered check
+ *   - GET /metrics           Prometheus text format
+ *   - structured error handler
+ *
+ * Add domain routes with \`.route('/api/<domain>', yourRouter)\`.
+ */
+export function createBaseApp(
+  deps: BaseAppDeps,
+): Hono<{ Variables: BaseAppContextVariables }> {
+  const app = new Hono<{ Variables: BaseAppContextVariables }>();
+
+  // Correlation ID — MUST be first so every downstream log carries it
+  app.use('*', async (c, next) => {
+    const id = c.req.header('x-correlation-id') ?? randomUUID();
+    c.set('correlationId', id);
+    c.set('startedAt', Date.now());
+    c.header('X-Correlation-Id', id);
+    await runWithCorrelation(id, async () => {
+      await next();
+    });
+  });
+
+  // Request logging + metrics
+  app.use('*', async (c, next) => {
+    await next();
+    const durationMs = Date.now() - c.get('startedAt');
+    const status = c.res.status;
+    baseLogger.info('http.request', {
+      method: c.req.method,
+      path: c.req.path,
+      status,
+      durationMs,
+    });
+    incrementCounter('http_requests_total', {
+      method: c.req.method,
+      status: String(status),
+    });
+    recordHistogram('http_request_duration_ms', durationMs, {
+      method: c.req.method,
+    });
+  });
+
+  // Liveness — always returns OK if the process is running
+  app.get('/health/live', (c) => {
+    return c.json({
+      status: 'ok',
+      service: deps.serviceName,
+      version: deps.version,
+      uptime_sec: Math.round(process.uptime()),
+    });
+  });
+
+  // Readiness — runs every registered check
+  app.get('/health/ready', async (c) => {
+    const results: Array<{ name: string; ok: boolean; detail?: string }> = [];
+    for (const check of deps.readiness) {
+      try {
+        const r = await check.check();
+        results.push({ name: check.name, ok: r.ok, ...(r.detail ? { detail: r.detail } : {}) });
+      } catch (err) {
+        results.push({
+          name: check.name,
+          ok: false,
+          detail: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+    const allOk = results.every((r) => r.ok);
+    return c.json(
+      { status: allOk ? 'ready' : 'not-ready', checks: results },
+      allOk ? 200 : 503,
+    );
+  });
+
+  // Metrics — Prometheus text format
+  app.get('/metrics', (c) => {
+    return c.text(metricsHandler(), 200, {
+      'Content-Type': 'text/plain; version=0.0.4',
+    });
+  });
+
+  // Error handler — last, so it catches everything above
+  app.onError((err, c) => {
+    baseLogger.error('http.error', err as Error, {
+      method: c.req.method,
+      path: c.req.path,
+    });
+    const status = (err as { httpStatus?: number }).httpStatus ?? 500;
+    return c.json(
+      {
+        error: {
+          message: err.message,
+          code: (err as { code?: string }).code ?? 'INTERNAL_ERROR',
+        },
+      },
+      status as 500,
+    );
+  });
+
+  return app;
+}
+`;
+/**
+ * ADR-PIPELINE-076: scaffold body for `src/api/base-app.ts` (Express variant).
+ *
+ * Used when the generator detects Express in Phase 4. Same guarantees as
+ * the Hono variant — wires correlation / logging / liveness / readiness
+ * / metrics / error handler in the correct order.
+ */
+export const BASE_APP_SCAFFOLD_EXPRESS = `// Auto-generated by Agentics pipeline (ADR-PIPELINE-076)
+// Wire-complete Express app base. DO NOT rewrite — mount your routes
+// onto the returned \`app\` instance instead.
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import express from 'express';
+import { randomUUID } from 'node:crypto';
+import { runWithCorrelation, createLogger } from '../logger.js';
+import { incrementCounter, recordHistogram, metricsHandlerExpress } from '../middleware.js';
+
+export interface HealthCheck {
+  readonly name: string;
+  readonly check: () => Promise<{ ok: boolean; detail?: string }>;
+}
+
+export interface BaseAppDeps {
+  readonly serviceName: string;
+  readonly version: string;
+  readonly readiness: readonly HealthCheck[];
+}
+
+const baseLogger = createLogger('base-app');
+
+export function createBaseApp(deps: BaseAppDeps): express.Express {
+  const app = express();
+  app.use(express.json({ limit: '1mb' }));
+
+  // Correlation ID — AsyncLocalStorage-scoped for the request's
+  // entire async continuation.
+  app.use((req: any, res: any, next: () => void) => {
+    const id = (req.headers['x-correlation-id'] as string) || randomUUID();
+    req.correlationId = id;
+    res.setHeader('X-Correlation-Id', id);
+    runWithCorrelation(id, next);
+  });
+
+  // Request logging + metrics
+  app.use((req: any, res: any, next: () => void) => {
+    const started = Date.now();
+    res.on('finish', () => {
+      const durationMs = Date.now() - started;
+      baseLogger.info('http.request', {
+        method: req.method,
+        path: req.path,
+        status: res.statusCode,
+        durationMs,
+      });
+      incrementCounter('http_requests_total', {
+        method: req.method,
+        status: String(res.statusCode),
+      });
+      recordHistogram('http_request_duration_ms', durationMs, {
+        method: req.method,
+      });
+    });
+    next();
+  });
+
+  app.get('/health/live', (_req, res) => {
+    res.json({
+      status: 'ok',
+      service: deps.serviceName,
+      version: deps.version,
+      uptime_sec: Math.round(process.uptime()),
+    });
+  });
+
+  app.get('/health/ready', async (_req, res) => {
+    const results: Array<{ name: string; ok: boolean; detail?: string }> = [];
+    for (const check of deps.readiness) {
+      try {
+        const r = await check.check();
+        results.push({ name: check.name, ok: r.ok, ...(r.detail ? { detail: r.detail } : {}) });
+      } catch (err) {
+        results.push({
+          name: check.name,
+          ok: false,
+          detail: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+    const allOk = results.every((r) => r.ok);
+    res.status(allOk ? 200 : 503).json({
+      status: allOk ? 'ready' : 'not-ready',
+      checks: results,
+    });
+  });
+
+  app.get('/metrics', metricsHandlerExpress);
+
+  app.use((err: any, req: any, res: any, _next: () => void) => {
+    baseLogger.error('http.error', err as Error, {
+      method: req.method,
+      path: req.path,
+    });
+    const status = err?.httpStatus ?? 500;
+    res.status(status).json({
+      error: {
+        message: err?.message ?? 'Internal error',
+        code: err?.code ?? 'INTERNAL_ERROR',
+      },
+    });
+  });
+
+  return app;
+}
+`;
 export const OWNED_SCAFFOLD_MODULES = [
     {
         path: 'src/logger.ts',
-        exports: ['Logger', 'createLogger', 'setCorrelationId', 'getCorrelationId'],
+        // ADR-PIPELINE-074: runWithCorrelation is now the authoritative
+        // way to scope a correlation ID; setCorrelationId is retained as a
+        // legacy shim but must not be used inside request handlers.
+        exports: [
+            'Logger',
+            'createLogger',
+            'runWithCorrelation',
+            'getCorrelationId',
+            'setCorrelationId',
+        ],
     },
     {
         path: 'src/config.ts',
@@ -304,12 +1217,16 @@ export const OWNED_SCAFFOLD_MODULES = [
     },
     {
         path: 'src/middleware.ts',
+        // ADR-PIPELINE-076: metricsHandler is now a pure renderer; the
+        // Express-compat wrapper is metricsHandlerExpress. The Hono wrapper
+        // lives in the base-app scaffold.
         exports: [
             'correlationId',
             'requestLogger',
             'incrementCounter',
             'recordHistogram',
             'metricsHandler',
+            'metricsHandlerExpress',
         ],
     },
     {
@@ -337,6 +1254,53 @@ export const OWNED_SCAFFOLD_MODULES = [
             'loadSimulationId',
         ],
     },
+    // ADR-PIPELINE-075: scaffolded persistence layer
+    {
+        path: 'src/persistence/repository.ts',
+        exports: ['Repository', 'RepositoryOptions', 'RepositoryError'],
+    },
+    {
+        path: 'src/persistence/in-memory-repository.ts',
+        exports: ['InMemoryRepository'],
+    },
+    {
+        path: 'src/persistence/sqlite-repository.ts',
+        exports: ['SqliteRepository', 'SqliteRepositoryDeps', 'BetterSqliteDatabase'],
+    },
+    {
+        path: 'src/persistence/audit-repository.ts',
+        exports: ['AppendOnlyAuditRepository', 'AuditRepositoryDeps', 'AuditEntry'],
+    },
+    // ADR-PIPELINE-076: wire-complete server scaffold
+    {
+        path: 'src/api/base-app.ts',
+        exports: [
+            'createBaseApp',
+            'BaseAppDeps',
+            'BaseAppContextVariables',
+            'HealthCheck',
+        ],
+    },
+    // ADR-PIPELINE-077: ERP schema provenance tag
+    {
+        path: 'src/erp/schema-provenance.ts',
+        exports: [
+            'ErpProvenanceSource',
+            'ErpSchemaProvenance',
+            'assertErpProvenanceOrFail',
+            'formatProvenanceBanner',
+            'printProvenanceBanner',
+        ],
+    },
+    // ADR-PIPELINE-078: deep canonical JSON for audit hash chains
+    {
+        path: 'src/persistence/canonical-json.ts',
+        exports: ['CanonicalJsonError', 'canonicalJson'],
+    },
+    {
+        path: 'src/persistence/audit-hash.ts',
+        exports: ['HashChainInput', 'hashAuditEntry'],
+    },
 ];
 export function buildOwnedModulesManifest(now = new Date()) {
     return {
@@ -492,33 +1456,16 @@ function copyPlanningArtifacts(runDir, targetRoot) {
         // Instead of hoping the coding agent reads the prompts, we deliver the files.
         const scaffoldDir = path.join(plansDir, 'scaffold', 'src');
         fs.mkdirSync(scaffoldDir, { recursive: true });
-        const loggerCode = `// Auto-generated by Agentics pipeline (ADR-039)
-export interface Logger {
-  info(event: string, data?: Record<string, unknown>): void;
-  warn(event: string, data?: Record<string, unknown>): void;
-  error(event: string, error: Error, data?: Record<string, unknown>): void;
-}
-
-let currentCorrelationId: string | undefined;
-
-export function setCorrelationId(id: string): void { currentCorrelationId = id; }
-export function getCorrelationId(): string | undefined { return currentCorrelationId; }
-
-export function createLogger(service: string): Logger {
-  const emit = (level: string, event: string, extra?: Record<string, unknown>) => {
-    const entry = { timestamp: new Date().toISOString(), level, service, event, ...(currentCorrelationId ? { correlationId: currentCorrelationId } : {}), ...extra };
-    process.stderr.write(JSON.stringify(entry) + '\\n');
-  };
-  return {
-    info: (event, data) => emit('info', event, data),
-    warn: (event, data) => emit('warn', event, data),
-    error: (event, err, data) => emit('error', event, { error: err.message, stack: err.stack, ...data }),
-  };
-}
-`;
-        const configCode = `// Auto-generated by Agentics pipeline (ADR-039)
+        // ADR-PIPELINE-074: logger scaffold now uses AsyncLocalStorage for
+        // concurrent-request correctness. Body lives in LOGGER_SCAFFOLD at
+        // module scope so it can be unit-tested independently.
+        const loggerCode = LOGGER_SCAFFOLD;
+        // ADR-PIPELINE-039 + ADR-PIPELINE-075: AppConfig now includes a `db`
+        // block so the composition root can pick sqlite (production) vs
+        // in-memory (tests) without code changes.
+        const configCode = `// Auto-generated by Agentics pipeline (ADR-039 + ADR-PIPELINE-075)
 export interface AppConfig {
-  env: 'development' | 'staging' | 'production';
+  env: 'development' | 'staging' | 'production' | 'test';
   port: number;
   logLevel: 'debug' | 'info' | 'warn' | 'error';
   erp: {
@@ -527,6 +1474,10 @@ export interface AppConfig {
     timeoutMs: number;
     maxRetries: number;
   };
+  db: {
+    driver: 'sqlite' | 'in-memory';
+    path: string;
+  };
 }
 
 export const config: AppConfig = {
@@ -539,6 +1490,10 @@ export const config: AppConfig = {
     timeoutMs: parseInt(process.env['ERP_TIMEOUT_MS'] ?? '30000', 10),
     maxRetries: parseInt(process.env['ERP_MAX_RETRIES'] ?? '3', 10),
   },
+  db: {
+    driver: (process.env['DB_DRIVER'] ?? 'sqlite') as AppConfig['db']['driver'],
+    path: process.env['DB_PATH'] ?? './data/app.db',
+  },
 };
 `;
         const errorsCode = `// Auto-generated by Agentics pipeline (ADR-039)
@@ -569,21 +1524,49 @@ export class ERPError extends AppError {
 `;
         // TypeScript scaffold (default)
         fs.writeFileSync(path.join(scaffoldDir, 'logger.ts'), loggerCode, 'utf-8');
+        // ADR-PIPELINE-074: ship a concurrency regression test next to the
+        // logger so generated projects fail loudly if someone reintroduces
+        // a module-level correlation-ID store.
+        fs.writeFileSync(path.join(scaffoldDir, 'logger.concurrency.test.ts'), LOGGER_CONCURRENCY_TEST_SCAFFOLD, 'utf-8');
         fs.writeFileSync(path.join(scaffoldDir, 'config.ts'), configCode, 'utf-8');
         fs.writeFileSync(path.join(scaffoldDir, 'errors.ts'), errorsCode, 'utf-8');
-        // ADR-051: Correlation ID middleware + metrics scaffold
-        const middlewareCode = `// Auto-generated by Agentics pipeline (ADR-051)
+        // ADR-PIPELINE-075: Scaffolded persistence layer — Repository<T> +
+        // InMemoryRepository + SqliteRepository + AppendOnlyAuditRepository.
+        // Every stateful service should import these instead of rolling a
+        // Map<string, T> store. PGV-017 flags the anti-pattern at post-gen time.
+        const persistenceDir = path.join(scaffoldDir, 'persistence');
+        fs.mkdirSync(persistenceDir, { recursive: true });
+        fs.writeFileSync(path.join(persistenceDir, 'repository.ts'), REPOSITORY_SCAFFOLD, 'utf-8');
+        fs.writeFileSync(path.join(persistenceDir, 'in-memory-repository.ts'), IN_MEMORY_REPO_SCAFFOLD, 'utf-8');
+        fs.writeFileSync(path.join(persistenceDir, 'sqlite-repository.ts'), SQLITE_REPO_SCAFFOLD, 'utf-8');
+        fs.writeFileSync(path.join(persistenceDir, 'audit-repository.ts'), AUDIT_REPO_SCAFFOLD, 'utf-8');
+        // ADR-PIPELINE-078: deep canonical JSON + audit hash helper.
+        // Every generated AuditService should import hashAuditEntry from this
+        // helper instead of hand-rolling JSON.stringify + createHash chains.
+        // PGV-022 flags the anti-pattern at post-gen time.
+        fs.writeFileSync(path.join(persistenceDir, 'canonical-json.ts'), CANONICAL_JSON_SCAFFOLD, 'utf-8');
+        fs.writeFileSync(path.join(persistenceDir, 'audit-hash.ts'), AUDIT_HASH_SCAFFOLD, 'utf-8');
+        // ADR-051 + ADR-PIPELINE-074: Correlation ID middleware now wraps next()
+        // in runWithCorrelation so the ID lives in AsyncLocalStorage for the
+        // request's entire async continuation. Concurrent requests cannot
+        // cross-contaminate log lines.
+        const middlewareCode = `// Auto-generated by Agentics pipeline (ADR-051 + ADR-PIPELINE-074)
 import { randomUUID } from 'node:crypto';
-import { createLogger } from './logger.js';
+import { createLogger, runWithCorrelation } from './logger.js';
 
 const logger = createLogger('middleware');
 
-/** Correlation ID middleware — attaches to every request, threads through logs */
+/**
+ * Correlation ID middleware — attaches to every request, threads through
+ * logs via AsyncLocalStorage. The request handler + all its async
+ * descendants run inside runWithCorrelation so getCorrelationId() returns
+ * this request's ID, not a sibling's.
+ */
 export function correlationId(req: any, res: any, next: () => void): void {
   const id = (req.headers['x-correlation-id'] as string) || randomUUID();
   req.correlationId = id;
   res.setHeader('X-Correlation-Id', id);
-  next();
+  runWithCorrelation(id, next);
 }
 
 /** Request logging middleware — logs every request with timing */
@@ -613,7 +1596,13 @@ export function recordHistogram(name: string, value: number, labels: Record<stri
   histograms[key]!.push(value);
 }
 
-export function metricsHandler(_req: any, res: any): void {
+/**
+ * ADR-PIPELINE-076: Pure metrics renderer — returns Prometheus text.
+ * Framework-specific wrappers (metricsHandlerExpress, metricsHandlerHono)
+ * delegate here. Call this directly from any framework that isn't
+ * Express or Hono.
+ */
+export function metricsHandler(): string {
   const lines: string[] = [];
   for (const [key, val] of Object.entries(counters)) {
     lines.push(\`# TYPE \${key.split('{')[0]} counter\`);
@@ -626,8 +1615,13 @@ export function metricsHandler(_req: any, res: any): void {
     lines.push(\`\${key}_sum \${sum}\`);
     lines.push(\`\${key}_count \${count}\`);
   }
-  res.setHeader('Content-Type', 'text/plain');
-  res.end(lines.join('\\n'));
+  return lines.join('\\n');
+}
+
+/** Express-compatible metrics handler — wraps metricsHandler(). */
+export function metricsHandlerExpress(_req: any, res: any): void {
+  res.setHeader('Content-Type', 'text/plain; version=0.0.4');
+  res.end(metricsHandler());
 }
 
 // ADR-PIPELINE-069: CircuitBreaker now lives in its own scaffold module.
@@ -642,6 +1636,24 @@ export { CircuitBreaker } from './circuit-breaker.js';
         // middleware.ts. Owned by the scaffold (see OWNED_SCAFFOLD_MODULES).
         fs.writeFileSync(path.join(scaffoldDir, 'circuit-breaker.ts'), CIRCUIT_BREAKER_SCAFFOLD, 'utf-8');
         totalCopied += 1;
+        // ADR-PIPELINE-076: wire-complete Hono base app. Generators extend
+        // via createBaseApp(deps).route('/api/<domain>', router) instead of
+        // rebuilding the middleware/metrics/health plumbing from scratch.
+        // PGV-018 will fail the build if /metrics, /health/live, /health/ready
+        // are missing from the final project tree.
+        const apiDir = path.join(scaffoldDir, 'api');
+        fs.mkdirSync(apiDir, { recursive: true });
+        fs.writeFileSync(path.join(apiDir, 'base-app.ts'), BASE_APP_SCAFFOLD_HONO, 'utf-8');
+        totalCopied += 1;
+        // ADR-PIPELINE-077: ERP schema provenance helper. Every generated
+        // ERP adapter MUST export an ERP_SCHEMA_PROVENANCE constant and call
+        // assertErpProvenanceOrFail at construction so strict-mode deployments
+        // block on unreviewed schemas. PGV-020 enforces presence, PGV-021
+        // enforces reviewer + catalog_version on validated entries.
+        const erpDir = path.join(scaffoldDir, 'erp');
+        fs.mkdirSync(erpDir, { recursive: true });
+        fs.writeFileSync(path.join(erpDir, 'schema-provenance.ts'), ERP_SCHEMA_PROVENANCE_SCAFFOLD, 'utf-8');
+        totalCopied += 1;
         // ADR-PIPELINE-066: unit-economics helper. The demo script calls
         // writeUnitEconomics() to emit a machine-readable manifest that the
         // executive renderer prefers over per-employee heuristics.