@starci/hfs 4.10.0 → 4.11.0

package/runtime/scripts/hfs/architecture/owners.mjs

@@ -4,6 +4,7 @@ import { relativePath, workspaceExportSources } from './typescript.mjs';
 import { sourceLocation } from '../../lib/ts-ast.mjs';
 import { globExpression } from '../../lib/glob.mjs';
 import { posixPath } from '../../lib/path-key.mjs';
+import { registryImporter, registrySlot } from './entity-registry.mjs';
 
 function absolute(root, relative) {
   return canonical(path.resolve(root, ...relative.split('/')));
@@ -68,6 +69,15 @@ function arrangesSchema(config, from, to) {
     && resolver.classifyPath(relativePath(config.root, to)).slot === 'be.persistence';
 }
 
+/**
+ * The entity registry (slot role entity-registry, entity-registry.mjs) is imported by deep path, and only from the files its slot's
+ * `importedBy` names: app composition and the test world. Any other importer goes through the owner's entry, which never exports it.
+ */
+function importsRegistry(config, from, to) {
+  const slot = registrySlot(config.hfs, relativePath(config.root, to));
+  return slot !== null && registryImporter(config.hfs, slot, relativePath(config.root, from));
+}
+
 function publicEntryViolations(config, context, owners, sourceFiles) {
   const violations = [];
   for (const owner of owners) {
@@ -104,6 +114,7 @@ function ownerImportViolations(config, context, owners) {
       const bypass = privateOwnerChain(context, owners, edge);
       if (!bypass) continue;
       if (arrangesSchema(config, from, bypass.chain.at(-1))) continue;
+      if (bypass.chain.length === 2 && importsRegistry(config, from, bypass.chain.at(-1))) continue;
       violations.push({
         ruleId: 'ARCH_OWNER_EXPORT_BYPASS',
         path: relativePath(config.root, from),

package/runtime/scripts/hfs/architecture/tiers.mjs

@@ -1,4 +1,5 @@
 import { byCodeUnit } from '../../lib/list.mjs';
+import { registryListImport, registrySlot } from './entity-registry.mjs';
 
 /**
  * HFS checks 1 and 2 (knowledge/hfs/slots.yaml `tiers`):
@@ -8,7 +9,9 @@ import { byCodeUnit } from '../../lib/list.mjs';
  *      kind (slot field `trigger`: api, webhooks, realtime, saga, reactors, jobs, cli) importing a feature of another is
  *      BE_KIND_ISOLATION, whose fix is the event bus,
  *      an app never imports another app (BE_SERVICE_ISOLATION / FE_APP_ISOLATION), and a component layer imports only the layers after it;
- *   2. owner cycles: a strongly connected component of the owner graph, type-only imports included (ARCH_OWNER_CYCLE),
+ *      the entity registry naming a capability's `<c>Entities` from its public entry is the one platform-to-domain edge (entity-registry.mjs);
+ *   2. owner cycles: a strongly connected component of the owner graph, type-only imports included (ARCH_OWNER_CYCLE), the entity
+ *      registry counted as a unit of its own,
  *      reported with the cycle path and the import that closes each hop.
  * Importing inside one owner is always allowed; the public-entry rule stays with owners.mjs (ARCH_OWNER_EXPORT_BYPASS).
  */
@@ -138,15 +141,23 @@ function inspectTierEdge(graph, edge, tierRule, counts, violations, coverage) {
     return;
   }
   coverage.edgesChecked += 1;
+  if (verdict.reason === 'tierDirection' && registryListImport(graph.resolver, edge)) return;
   reportReasonedTierViolation(graph, edge, verdict, tierRule, counts, violations);
 }
 
+/**
+ * The cycle unit of a file: its owner unit, except the entity registry (entity-registry.mjs), which is a unit of its own. It sits in
+ * platform/database but is composition-level by role (it imports every capability's `<c>Entities`), so it never closes a cycle
+ * among capabilities through the owner it lives in.
+ */
+const cycleUnit = (graph, resolver, rel) => (registrySlot(resolver, rel) ? `entity-registry:${rel}` : graph.unit(rel));
+
 function ownerAdjacency(graph, resolver) {
   const adjacency = new Map();
   const witness = new Map();
   for (const edge of graph.edges) {
-    const a = graph.unit(edge.from);
-    const b = graph.unit(edge.to);
+    const a = cycleUnit(graph, resolver, edge.from);
+    const b = cycleUnit(graph, resolver, edge.to);
     if (!a || !b || a === b) continue;
     if (resolver.tierOf(edge.from) === 'none' || resolver.tierOf(edge.to) === 'none') continue;
     if (!adjacency.has(a)) adjacency.set(a, new Set());

package/runtime/scripts/hfs/db-baseline-verb.mjs

@@ -42,15 +42,34 @@ export function dbAppRoot(cwd, opts) {
   return root;
 }
 
-/** Immediate SQL files only, never secrets or credential files. */
+/** A refusal that lists every offending file with the rule it broke, one distinct `<file>: <reason>` line each. */
+const offendersError = (heading, offenders) => new DbVerbError(`${heading}:\n${[...new Set(offenders)].map((line) => `  ${line}`).join('\n')}`);
+
+/** One rule finding as an offender line: its file, its message and its code. */
+const findingLine = (item) => `${item.message.startsWith(item.path) ? item.message : `${item.path}: ${item.message}`} (${item.code})`;
+
+/**
+ * Why one SQL filename cannot join its chain, or null. The active chain holds R213 (`<ts14>_<kebab>.sql`, a valid UTC
+ * stamp; a stamp after now is no breach). The archive is frozen history (R257): it needs only the leading stamp that
+ * orders it, so snake_case names, impossible times and shared stamps of a retired chain stay as they were committed.
+ */
+function chainProblem(directory, name) {
+  const match = /^(\d{14})_/.exec(name);
+  if (directory === MIGRATIONS_ARCHIVE_DIR) return match ? null : 'an archived name starts with its 14-digit stamp and an underscore (R257)';
+  if (!isMigrationName(name)) return 'name is not <ts14>_<kebab>.sql (R213)';
+  if (migrationStamp(match[1]) === null) return `stamp ${match[1]} is no valid UTC time (R213)`;
+  return null;
+}
+
+/** Immediate SQL files only, never secrets or credential files, sorted by full name; every offender is named before the refusal. */
 export function dbSqlFiles(root, directory = MIGRATIONS_DIR) {
   const dir = path.join(root, directory);
   if (!fs.existsSync(dir)) return [];
-  return fs.readdirSync(dir, { withFileTypes: true }).filter((entry) => entry.isFile() && entry.name.endsWith('.sql')).map((entry) => {
-    const match = /^(\d{14})_/.exec(entry.name);
-    if (!isMigrationName(entry.name) || !match || migrationStamp(match[1]) === null) throw new DbVerbError('migration filenames must carry valid UTC stamps');
-    return { file: `${directory}/${entry.name}`, name: entry.name, stamp: match[1] };
-  }).sort((left, right) => left.name < right.name ? -1 : Number(left.name > right.name));
+  const sqlNames = fs.readdirSync(dir, { withFileTypes: true }).filter((entry) => entry.isFile() && entry.name.endsWith('.sql')).map((entry) => entry.name);
+  const offenders = sqlNames.flatMap((name) => { const problem = chainProblem(directory, name); return problem ? [`${directory}/${name}: ${problem}`] : []; });
+  if (offenders.length) throw offendersError('migration filenames break their chain rules', offenders.sort());
+  return sqlNames.map((name) => ({ file: `${directory}/${name}`, name, stamp: name.slice(0, 14) }))
+    .sort((left, right) => left.name < right.name ? -1 : Number(left.name > right.name));
 }
 
 /** The database of `--url-env` (default DATABASE_URL): the URL without its password and the password for PGPASSWORD. */
@@ -103,12 +122,17 @@ function baselinePlan(root, opts, now) {
   const active = dbSqlFiles(root);
   if (!active.length) throw new DbVerbError('baseline requires an existing active migration chain');
   const archived = dbSqlFiles(root, MIGRATIONS_ARCHIVE_DIR);
-  const oldStamps = [...active, ...archived].map((entry) => entry.stamp);
-  const last = oldStamps.toSorted((left, right) => left.localeCompare(right)).at(-1);
+  const archivedNames = new Set(archived.map((entry) => entry.name));
+  const twice = active.filter((entry) => archivedNames.has(entry.name)).map((entry) => `${entry.file}: also archived as ${MIGRATIONS_ARCHIVE_DIR}/${entry.name}; a migration is active or archived, never both (R257)`);
+  if (twice.length) throw offendersError('baseline would overwrite an existing migration', twice);
+  const chain = [...active, ...archived].sort((left, right) => left.stamp < right.stamp ? -1 : Number(left.stamp > right.stamp) || (left.name < right.name ? -1 : Number(left.name > right.name)));
+  // The new version sorts after every file; the header names the last valid stamp, the boundary R257 judges.
+  const boundary = chain.at(-1);
+  const last = chain.filter((entry) => migrationStamp(entry.stamp) !== null).at(-1)?.stamp ?? boundary.stamp;
   const stamp = opts.stamp ?? now().toISOString().replace(/\D/g, '').slice(0, 14);
-  if (!/^\d{14}$/.test(stamp) || migrationStamp(stamp) === null || stamp <= last) throw new DbVerbError('--stamp must be a valid UTC version after the archive boundary');
+  if (!/^\d{14}$/.test(stamp) || migrationStamp(stamp) === null || stamp <= boundary.stamp) throw new DbVerbError(`--stamp must be a valid UTC version after the archive boundary ${boundary.stamp} (${boundary.file})`);
   const file = `${MIGRATIONS_DIR}/${stamp}_baseline.sql`;
-  if (fs.existsSync(path.join(root, file)) || active.some((entry) => fs.existsSync(path.join(root, MIGRATIONS_ARCHIVE_DIR, entry.name)))) throw new DbVerbError('baseline would overwrite an existing migration');
+  if (fs.existsSync(path.join(root, file))) throw new DbVerbError(`baseline would overwrite an existing migration: ${file}`);
   return { active, last, stamp, file };
 }
 
@@ -255,12 +279,19 @@ function baselineStatement(state, stmt, sql) {
 
 function baselineMetadata(root, plan, files) {
   const queues = databaseQueueDeclarations({ repoRoot: root, files, all: files });
-  if (queues.findings.length) throw new DbVerbError('baseline requires valid migration-owned queues, grants and cron declarations');
+  if (queues.findings.length) throw offendersError('baseline requires valid migration-owned queues, grants and cron declarations', queues.findings.map(findingLine));
   const state = { roles: new Map(), extensions: new Map() };
+  const offenders = [];
   for (const migration of plan.active) {
     const text = fs.readFileSync(path.join(root, migration.file), 'utf8');
-    for (const entry of parsed(text).stmts ?? []) baselineStatement(state, entry.stmt, statementSql(text, entry));
+    try {
+      for (const entry of parsed(text).stmts ?? []) baselineStatement(state, entry.stmt, statementSql(text, entry));
+    } catch (error) {
+      if (!(error instanceof DbVerbError)) throw error;
+      offenders.push(`${migration.file}: ${error.message}`);
+    }
   }
+  if (offenders.length) throw offendersError('baseline cannot rebuild the active chain from a schema-only dump', offenders);
   return { ...queues, roles: [...state.roles.values()].flat().join(''), extensions: [...state.extensions.values()].join('') };
 }
 
@@ -279,7 +310,8 @@ export function dbBaselineMain(argv, { cwd = invocationDir(), stdout = (text) =>
     const root = dbAppRoot(cwd, opts);
     const plan = baselinePlan(root, opts, now);
     const files = baselineFiles(root);
-    if (baselineSourceFindings({ repoRoot: root, files, all: files, git: ports.git }).length) throw new DbVerbError('baseline sources and archives must match committed migration history');
+    const sourceFindings = baselineSourceFindings({ repoRoot: root, files, all: files, git: ports.git });
+    if (sourceFindings.length) throw offendersError('baseline sources and archives must match committed migration history', sourceFindings.map(findingLine));
     const metadata = baselineMetadata(root, plan, files);
     if (dbPlanMain(['--json', '--url-env', urlEnv], { ...ports, cwd: root, stdout: () => {}, stderr: () => {} }) !== 0) throw new DbVerbError('baseline requires a clean database plan with every migration already applied');
     const schema = runDbPostgres(root, { kind: 'dump' }, ports, urlEnv);

package/runtime/scripts/hfs/manifest-shape.mjs

@@ -87,7 +87,9 @@ export const MANIFEST_KINDS = [APP_KIND, RUNTIME_KIND];
 export const manifestKind = (m) => (isPlainObject(m) && m.kind !== undefined ? m.kind : APP_KIND);
 const strList = (v) => stringList(v);
 
-const APP_SLOT_KEYS = ['id', 'profiles', 'path', 'presence', 'tracked', 'tier', 'tests', 'owner', 'appKind', 'minInstances', 'requiredWhen', 'requiredInstances', 'requires', 'pattern', 'trigger', 'allows', 'forbids', 'layers', 'kinds', 'roles', 'composedBy', 'budget', 'managedBy', 'liteManagedBy', 'rules', 'goesTo', 'why', 'since', 'perConnection', 'parent', 'editions', 'editionWhy', 'litePresence', 'lite', 'provider', 'coverage', 'entries', 'outcomeHome', 'templateNa', 'exemplifiedBy', 'rewrittenBy'];
+const APP_SLOT_KEYS = ['id', 'profiles', 'path', 'presence', 'tracked', 'tier', 'tests', 'owner', 'appKind', 'minInstances', 'requiredWhen', 'requiredInstances', 'requires', 'pattern', 'trigger', 'allows', 'forbids', 'layers', 'kinds', 'roles', 'composedBy', 'budget', 'managedBy', 'liteManagedBy', 'rules', 'goesTo', 'why', 'since', 'perConnection', 'parent', 'editions', 'editionWhy', 'litePresence', 'lite', 'provider', 'coverage', 'entries', 'outcomeHome', 'templateNa', 'exemplifiedBy', 'role', 'importedBy', 'rewrittenBy'];
+/** The roles a file slot may play that a rule reads (`role`): the entity registry of persistence.md BE-PERSISTENCE-3 (architecture/entity-registry.mjs). */
+const SLOT_ROLES = ['entity-registry'];
 /** The fields a slot's `lite` overlay may hold: the same keys it would carry in the slot body, resolved under edition lite. */
 const LITE_OVERLAY_KEYS = ['path', 'requires', 'allows', 'forbids', 'minInstances', 'requiredInstances', 'why'];
 /** A runtime slot has no app kind, side composition, layer or managed template; it may name the generator of a generated copy. */
@@ -250,6 +252,8 @@ function slotEntryProblems(slot, at) {
     else if (Array.isArray(slot.allows) && slot.entries.some((entry) => !slot.allows.includes(entry))) bad.push(`${at}: every entry must be one of the names the slot allows`);
   }
   if (slot.outcomeHome !== undefined && !(slot.outcomeHome === true && typeof slot.path === 'string' && slot.path && !slot.path.endsWith('/'))) bad.push(`${at}: outcomeHome is true and belongs to a file slot (the one file that declares the repository's Outcome union)`);
+  if (slot.role !== undefined && !(SLOT_ROLES.includes(slot.role) && typeof slot.path === 'string' && slot.path && !slot.path.endsWith('/'))) bad.push(`${at}: role is one of ${SLOT_ROLES.join(', ')} and belongs to a file slot`);
+  if (slot.importedBy !== undefined && !(slot.role !== undefined && strList(slot.importedBy) && slot.importedBy.length && new Set(slot.importedBy).size === slot.importedBy.length && slot.importedBy.every(relPath))) bad.push(`${at}: importedBy is a non-empty list of unique relative path patterns of the only files that import the slot's file by deep path, on a slot with a role`);
   return bad;
 }
 

package/runtime/scripts/hfs/rules/database-config.mjs

@@ -7,7 +7,7 @@ import {
 import { databaseExecutableTokens, databaseSqlStatements, databaseSqlTokens, destructiveMigrationFindings } from './database-migrations.mjs';
 import { byCodeUnit } from '../../lib/list.mjs';
 
-const DEFAULT_EXTENSIONS = ['pgmq', 'pg_cron', 'pgcrypto', 'pg_trgm', 'vector', 'uuid-ossp', 'pg_net', 'supabase_vault', 'unaccent'];
+const DEFAULT_EXTENSIONS = ['pgcrypto', 'pg_trgm', 'vector', 'uuid-ossp', 'unaccent', 'btree_gist'];
 const word = (token, value) => token?.t === 'word' && token.v === value;
 const identifier = (token) => token && ['word', 'ident'].includes(token.t) ? token.v : null;
 

package/runtime/scripts/hfs/rules/stacks-lite-backing.mjs

@@ -1,10 +1,9 @@
-// R276: lite runs exactly its own PostgreSQL (the db component, image supabase/postgres) with pgvector, admits only the backing services available to its edition,
+// R276: lite runs exactly its own PostgreSQL (the db component, the image its managed db/Dockerfile builds) with pgvector, admits only the backing services available to its edition,
 // and runs a declared Redis as one service with AOF fsynced at least every second on a named volume and no eviction
 // (ruling:R212/case-10, owner:lite-vector-is-pgvector); sidecar SQLite persists on declared named volumes.
 import { isPlainObject as plain } from '../../../engine/plain-object.mjs';
 import { composeEntries } from '../../lib/compose-values.mjs';
 import { repositoryOf } from '../../lib/stack-services.mjs';
-import { isLiteDatabaseImage } from '../../lib/swarm-stack.mjs';
 import { loadSlotManifest } from '../slots.mjs';
 import { judgedInEdition } from '../edition-slots.mjs';
 import { readJson } from './read.mjs';
@@ -44,9 +43,9 @@ function imageIssues(components, services, { catalog, declared }) {
     for (const [id, entry] of Object.entries(inventory)) {
       if (!present(entry?.image)) continue;
       const service = serviceOfImage(catalog, entry.image);
-      if (DATABASE_IMAGE.test(repositoryOf(entry.image)) && !isLiteDatabaseImage(entry.image))
+      if (DATABASE_IMAGE.test(repositoryOf(entry.image)))
         errors.push({ code: 'STACKS_LITE_SELFHOSTED_DB', at: `${prefix}.${id}.image`,
-          message: 'lite runs one database, the db component of image supabase/postgres; no other Postgres or Mongo image' });
+          message: 'lite runs one database, the db component of the image db/Dockerfile builds (the official postgres image plus pgvector); no other Postgres or Mongo image' });
       else if (service !== null && !judgedInEdition(catalog[service], 'lite'))
         errors.push({ code: 'STACKS_LITE_SELFHOSTED_DB', at: `${prefix}.${id}.image`,
           message: `lite must not run ${service}; vector search uses pgvector in the db service (owner:lite-vector-is-pgvector)` });

package/runtime/scripts/lib/swarm-stack.mjs

@@ -11,8 +11,6 @@ const BACKING_IMAGE_BROKERS_AND_OTHERS = '(?:cp-)?kafka(?:-native)?|keycloak|min
 const BACKING_IMAGE = new RegExp(`^(?:${BACKING_IMAGE_SQL_AND_CACHE}|${BACKING_IMAGE_BROKERS_AND_OTHERS})$`, 'i');
 const mapping = value => plain(value) ? value : {};
 
-/** True for the one database image a lite app runs (its db component): supabase/postgres, pinned by digest. */
-export const isLiteDatabaseImage = image => typeof image === 'string' && /^supabase\/postgres(?::[^@]+)?@sha256:[a-f0-9]{64}$/i.test(image);
 const present = value => typeof value === 'string' && Boolean(value.trim());
 const configured = value => Object.keys(mapping(value)).length > 0;
 const schedulerImage = image => present(image) && /(?:^|\/)swarm-cronjob(?:[:@]|$)/.test(image);
@@ -52,8 +50,8 @@ export function swarmInventoryIssues({ components, lite = false }) {
   const add = (at, message) => errors.push({ at, message });
   for (const [id, entry] of Object.entries(catalog)) {
     const component = mapping(entry);
-    if (lite && present(component.image) && BACKING_IMAGE.test(repositoryOf(component.image)) && !isLiteDatabaseImage(component.image))
-      add(`components.${id}.image`, 'lite runs no backing image but its db component (supabase/postgres); storage is the external S3 endpoint, identity the API');
+    if (lite && present(component.image) && BACKING_IMAGE.test(repositoryOf(component.image)))
+      add(`components.${id}.image`, 'lite runs no backing image; its db component runs the image db/Dockerfile builds, storage is the external S3 endpoint, identity the API');
     jobDeclarationIssues(id, component, catalog, add);
   }
   return errors;
@@ -120,8 +118,8 @@ export function swarmModelIssues({ model, components, bindings, lite = false })
       add(`services.${id}.ports`, 'Swarm ports must be an array of published port definitions');
     else if (service.ports?.length && component.role !== 'ingress')
       add(`services.${id}.ports`, 'only a component with role ingress may publish Swarm ports');
-    if (lite && present(service.image) && BACKING_IMAGE.test(repositoryOf(service.image)) && !isLiteDatabaseImage(service.image))
-      add(`services.${id}.image`, 'lite stack runs no backing image but its db service (supabase/postgres)');
+    if (lite && present(service.image) && BACKING_IMAGE.test(repositoryOf(service.image)))
+      add(`services.${id}.image`, 'lite stack runs no backing image; its db service runs the image db/Dockerfile builds');
     jobServiceIssues(id, service, component, services, bound, add);
   }
   for (const id of Object.keys(bound)) {

package/scaffold/add-queue-lite.mjs

@@ -39,8 +39,23 @@ const LITE_TEMPLATES = Object.freeze({
   'jobs/platform/jobs.index.ts.tpl': 'jobs/platform-lite/jobs.index.ts.tpl',
   'jobs/platform/job-claim.service.ts.tpl': 'jobs/platform-lite/job-claim.service.ts.tpl',
   'jobs/platform/job-claim.service.spec.ts.tpl': 'jobs/platform-lite/job-claim.service.spec.ts.tpl',
+  // The jobs module composes the one tick scheduler (R335, ruling:lite-official-postgres-image): ScheduleModule.forRoot() and JobTickService.
+  'jobs/platform/jobs.module.ts.tpl': 'jobs/platform-lite/jobs.module.ts.tpl',
 });
 
+/** The tick scheduler of platform/jobs the lite jobs capability adds beside full's tree: the ticks as data, the scheduler and its spec (R335). */
+const TICK_FILES = Object.freeze([
+  ['be/src/modules/platform/jobs/job-ticks.contracts.ts', 'jobs/platform-lite/job-ticks.contracts.ts.tpl'],
+  ['be/src/modules/platform/jobs/job-tick.service.ts', 'jobs/platform-lite/job-tick.service.ts.tpl'],
+  ['be/src/modules/platform/jobs/job-tick.service.spec.ts', 'jobs/platform-lite/job-tick.service.spec.ts.tpl'],
+]);
+
+/** The tick files of a jobs capability the verb adds for the first time; an app that already has platform/jobs keeps its own. */
+function tickFiles({ beRoot, patterns }) {
+  if (!patterns.includes('fenced-job') || fs.existsSync(path.join(beRoot, 'src', 'modules', 'platform', 'jobs', 'index.ts'))) return [];
+  return TICK_FILES.map(([relative, source]) => ({ relative, text: template(`be/patterns/${source}`) }));
+}
+
 /**
  * The persistence files lite leaves out: the TypeORM schema (its authority is db/migrations) and the SQL text and row files (the
  * statements are database functions of the lite migration, called through callDbFunction; R334 and the be.persistence lite overlay).
@@ -102,20 +117,24 @@ function migrationFiles({ repoRoot, beRoot, patterns, now }) {
 
 /** The queue imports bullmq, which loads ioredis as an optional peer and cannot connect without it. */
 const QUEUE_CLIENTS = Object.freeze(['bullmq', 'ioredis']);
+/** The jobs capability's tick scheduler imports @nestjs/schedule and its CronJob (R335). */
+const SCHEDULER_CLIENTS = Object.freeze(['@nestjs/schedule', 'cron']);
 
 /**
- * hfs.json declares redis in sides.be.backing; the package.json gains the queue's clients at their canon pins, and the managed
+ * hfs.json declares redis in sides.be.backing; the package.json gains the queue's clients (and, for fenced-job, the tick
+ * scheduler's) at their canon pins, and the managed
  * development scripts of the declared Redis that `starci app sync` renders for it. Each is added when it is missing, so a Redis an
  * earlier capability declared (a cache on ioredis) still gains bullmq; a file already complete is left alone.
  */
-function declarationPatches(repoRoot, project) {
+function declarationPatches(repoRoot, project, patterns) {
   const file = path.join(repoRoot, 'hfs.json');
   const declaration = JSON.parse(read(file));
   declaration.sides.be.backing = [...new Set([...(declaration.sides.be.backing ?? []), 'redis'])].sort(byCodeUnit);
   const packageFile = path.join(repoRoot, 'package.json');
   const pkg = JSON.parse(read(packageFile));
   const pins = bundledPins();
-  const missing = QUEUE_CLIENTS.filter((name) => typeof pkg.dependencies?.[name] !== 'string');
+  const clients = [...QUEUE_CLIENTS, ...(patterns.includes('fenced-job') ? SCHEDULER_CLIENTS : [])];
+  const missing = clients.filter((name) => typeof pkg.dependencies?.[name] !== 'string');
   for (const name of missing) if (!pins[name]) throw new ScaffoldError('HFS_SCAFFOLD_PIN_MISSING', `${name} has no canon pin in knowledge/hfs/canon-pins.yaml`);
   if (missing.length)
     pkg.dependencies = Object.fromEntries(Object.entries({ ...pkg.dependencies, ...Object.fromEntries(missing.map((name) => [name, pins[name].version])) }).sort(([a], [b]) => a.localeCompare(b)));
@@ -331,9 +350,9 @@ export function planLiteQueue({ repoRoot, repo, noun, patterns, now }) {
   const beRoot = path.join(repoRoot, 'be');
   const migrations = migrationFiles({ repoRoot, beRoot, patterns, now });
   const database = skeletonFiles(repoRoot);
-  const declaration = declarationPatches(repoRoot, repo.project);
+  const declaration = declarationPatches(repoRoot, repo.project, patterns);
   const stack = stackFiles(repoRoot, { project: repo.project, consumers: queueServicesOf(repo) });
-  const created = [...migrations, ...database.created, ...stack.created];
+  const created = [...migrations, ...tickFiles({ beRoot, patterns }), ...database.created, ...stack.created];
   const patches = [...database.patches, ...declaration, ...stack.patches];
   const clashes = created.filter((entry) => fs.existsSync(path.join(repoRoot, ...entry.relative.split('/')))).map((entry) => entry.relative);
   if (clashes.length) throw new ScaffoldError('HFS_ADD_EXISTS', `add ${noun} would overwrite ${clashes.join(', ')}`);

package/stack/build.mjs

@@ -13,6 +13,7 @@ import { buildArgs } from './build-args.mjs';
 import { firstLine, lines as splitLines, tool } from './context.mjs';
 import { failure, refusal } from './errors.mjs';
 import { requireAgeIdentity } from './sealed.mjs';
+import { DB_DOCKERFILE, DB_IMAGE_APP } from '../db/image.mjs';
 import { scanImage } from './image-scan.mjs';
 
 const RELEASE_TAG = /^v\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/u;
@@ -44,8 +45,9 @@ function ownerOf(ctx, config) {
   return match[1].toLowerCase();
 }
 
-/** The Dockerfile of an app: be/apps/<app>/Dockerfile or fe/apps/<app>/Dockerfile; ambiguity and absence are refusals. */
+/** The Dockerfile of an app: be/apps/<app>/Dockerfile or fe/apps/<app>/Dockerfile, or db/Dockerfile for the db image; ambiguity and absence are refusals. */
 function dockerfileOf(config, app) {
+  if (app === DB_IMAGE_APP && fs.existsSync(path.join(config.repoRoot, DB_DOCKERFILE))) return DB_DOCKERFILE;
   const found = SIDES.map((side) => `${side}/apps/${app}/Dockerfile`).filter((file) => fs.existsSync(path.join(config.repoRoot, file)));
   if (found.length === 0) throw refusal('STACK_BUILD_NO_DOCKERFILE', `no Dockerfile for app ${app} (be/apps/${app}/Dockerfile or fe/apps/${app}/Dockerfile)`);
   if (found.length > 1) throw refusal('STACK_BUILD_AMBIGUOUS', `app ${app} has a Dockerfile on both sides: ${found.join(', ')}`);

package/sync/index.mjs

@@ -30,6 +30,7 @@ import { DEFAULT_PORT, NODE_IMAGE, dockerfilePath } from '../runtime/scripts/hfs
 import { isFile } from '../runtime/scripts/lib/fs-kind.mjs';
 import { readDeclaredSonarKey } from './sonar-key.mjs';
 import { readDeclaredStack, stackWorkflowVariables } from './stack-images.mjs';
+import { DB_DOCKERFILE, DB_IMAGE_APP } from '../db/image.mjs';
 import { byCodeUnit } from '../report/order.mjs';
 import { isRuntimeExampleApp } from '../runtime/scripts/lib/runtime-example.mjs';
 import { ciWorkflowCommands } from './ci-commands.mjs';
@@ -156,9 +157,16 @@ function trailingNewline(text) {
   return text.slice(0, end) + '\n';
 }
 
+/**
+ * The base image of a lite app's managed db/Dockerfile (contexts/stack/pins.yaml images postgres, ruling:lite-official-postgres-image): the
+ * Docker Official postgres image by digest, to which the Dockerfile adds only PGVECTOR_PACKAGE from PGDG.
+ */
+export const DB_BASE_IMAGE = 'postgres:17.11@sha256:31ba9c94a03ada9988f2bb493a22a75eef3a185884533e5cdbcd498ea835b08f';
+/** The PGDG package of pgvector at the exact version the db image installs (the one extension the image does not ship). */
+export const PGVECTOR_PACKAGE = 'postgresql-17-pgvector=0.8.7-1.pgdg13+1';
+/** The local tag the development db container and the drift scratch database run, built from the app's db/Dockerfile. */
+export const dbLocalImage = project => `${project}-db:local`;
 /** The digest-pinned image of a lite app's declared Redis, in every environment that runs it (ruling:R212/case-10). */
-/** The pinned image of a lite app's db service (contexts/stack/pins.yaml images): PostgreSQL with pg_cron, pg_net, pgmq and pgvector. */
-export const DB_IMAGE = 'supabase/postgres:17.11.0.006@sha256:c141fd17ac6a76c4323e90b3aee8ff1a23d2e89e547c2b963cfadc309c079cc2';
 export const REDIS_IMAGE = 'redis:7@sha256:c6eabf748fc7a61dbb5a705c78bcf3d6377b1127a97d0ce965c11c44ba46896f';
 
 const redisDevText = project => render(readBundled('app/package-scripts/redis-dev.json'), { project, redisImage: REDIS_IMAGE });
@@ -322,17 +330,19 @@ function imageEntries(app, source) {
 }
 
 /**
- * The build matrix of the images workflow: one entry per declared app (be then fe), each with the image name and its Dockerfile. The workflow
+ * The build matrix of the images workflow: one entry per declared app (be then fe, then a lite app's db image), each with the image name and its Dockerfile. The workflow
  * runs on the release tag, so every image is built there; no path filter narrows it. A YAML block mapping per entry, indented for
  * `strategy.matrix.include`.
  */
 export function imageMatrix(app, source) {
   const entry = (side, item) => `          - name: ${item.name}\n            file: ${dockerfilePath(side, item.name)}`;
-  return imageEntries(app, source).map(image => entry(image.side, image.entry)).join('\n');
+  const db = app.edition === 'lite' ? [`          - name: ${DB_IMAGE_APP}\n            file: ${DB_DOCKERFILE}`] : [];
+  return [...imageEntries(app, source).map(image => entry(image.side, image.entry)), ...db].join('\n');
 }
 
-/** The Dockerfile of the app a deploy image names (be first, then fe); an app hfs.json does not declare cannot be built by the managed workflow. */
+/** The Dockerfile of the app a deploy image names (be first, then fe, then a lite app's db image); an app hfs.json does not declare cannot be built by the managed workflow. */
 function stackDockerfile(app, name) {
+  if (app.edition === 'lite' && name === DB_IMAGE_APP) return DB_DOCKERFILE;
   const side = ['be', 'fe'].find(which => app.sides[which].apps.some(entry => entry.name === name));
   if (!side) throw new SyncError('HFS_SYNC_STACK_IMAGE', `deploy.images names the app ${name}, which hfs.json does not declare under be or fe`);
   return dockerfilePath(side, name);
@@ -375,8 +385,10 @@ export function variables(app, scope, presets, sonarKey, manifest = loadSlotMani
     project: app.project,
     appBinary: APP_BINARY,
     appScripts: appScripts(app, source),
-    // A lite app's own database runs in development as one container of the pinned db image (ruling:lite-self-hosted-postgres-passport-minio).
-    dbImage: DB_IMAGE,
+    // A lite app's own database runs in development as one container of the image its db/Dockerfile builds (ruling:lite-official-postgres-image).
+    dbImage: dbLocalImage(app.project),
+    dbBaseImage: DB_BASE_IMAGE,
+    pgvectorPackage: PGVECTOR_PACKAGE,
     // A lite app's declared Redis (sides.be.backing, ruling:R212/case-10) runs in development as one container of its pinned image.
     backingScripts: lite && (app.sides.be.backing ?? []).includes('redis') ? redisDevText(app.project) : '',
     // turbo builds every fe app workspace; ^build (turbo.json) builds the packages each app imports first, and caches both.

package/templates/app/db-bootstrap/db/bootstrap.sql

@@ -1,16 +1,16 @@
 -- Managed by starci app sync (slot app.db.bootstrap); do not edit: run "npx starci app sync --write".
--- The pre-migration bootstrap of a lite app's self-hosted PostgreSQL (ruling lite-self-hosted-postgres-passport-minio). Migrations written
--- for Supabase reference objects GoTrue and Supabase Storage created: the browser roles, the `auth` schema (auth.users, auth.identities,
--- auth.sessions, auth.uid/jwt/role) and the `storage` schema (storage.buckets, storage.objects). The supabase/postgres image ships only a partial
--- copy of them, and a lite app runs neither GoTrue nor storage-api: auth is the app's own (integrations/passport) and storage is the S3 endpoint
--- of integrations/object-storage. This file gives the migrations those objects, EMPTY, and nothing else. It is idempotent; `starci app db migrate`
+-- The pre-migration bootstrap of a lite app's self-hosted PostgreSQL (ruling lite-self-hosted-postgres-passport-minio), run on the official
+-- postgres image of db/Dockerfile (ruling lite-official-postgres-image). Migrations written for Supabase reference objects GoTrue and Supabase
+-- Storage created: the browser roles, the `auth` schema (auth.users, auth.identities, auth.sessions, auth.uid/jwt/role) and the `storage`
+-- schema (storage.buckets, storage.objects). A lite app runs neither GoTrue nor storage-api: auth is the app's own (integrations/passport) and
+-- storage is the S3 endpoint of integrations/object-storage. This file gives the migrations those objects, EMPTY, and nothing else; nothing
+-- else of Supabase (supabase_admin, the `extensions` schema, the realtime publication) exists. It is idempotent; `starci app db migrate`
 -- applies it as the database owner before the first migration of an empty database.
 --
 -- auth.users keeps the GoTrue column set so restored rows and foreign keys from public tables stay valid; encrypted_password holds bcrypt hashes.
 -- auth.uid(), auth.role() and auth.jwt() read the request.jwt.claims setting; the API connects as app_be and sets none, so they return NULL and
 -- every policy that names them denies the browser roles, which have no door in lite.
 
-create schema if not exists extensions;
 create schema if not exists auth;
 create schema if not exists storage;
 
@@ -23,9 +23,8 @@ end
 $roles$;
 
 grant usage on schema auth, storage to anon, authenticated, service_role;
-grant usage on schema extensions to anon, authenticated, service_role;
 
--- auth.users: the full GoTrue column set (the image's old copy is extended in place).
+-- auth.users: the full GoTrue column set (a copy an earlier database carries is extended in place).
 create table if not exists auth.users (id uuid primary key);
 alter table auth.users
     add column if not exists instance_id uuid,
@@ -130,10 +129,3 @@ alter table storage.buckets enable row level security;
 
 grant select, insert, update, delete on storage.objects, storage.buckets to authenticated, service_role;
 grant select on storage.objects, storage.buckets to anon;
-
--- Replication publication the baseline adds tables to (the image ships it; a bare PostgreSQL does not).
-do $pub$
-begin
-    if not exists (select 1 from pg_publication where pubname = 'supabase_realtime') then create publication supabase_realtime; end if;
-end
-$pub$;

package/templates/app/db-image/db/Dockerfile

@@ -0,0 +1,8 @@
+# Managed by starci app sync (slot app.db.image); do not edit: run "npx starci app sync --write".
+# The image of the db service of a lite app (ruling lite-official-postgres-image): the Docker Official postgres image, pinned by
+# digest, plus pgvector from the PGDG repository the image already configures. The contrib extensions (pgcrypto, pg_trgm, unaccent,
+# uuid-ossp, btree_gist) ship in the image. The stack's db service, `npm run db:create` and `starci app db drift` all build this file.
+FROM {{dbBaseImage}}
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends {{pgvectorPackage}} \
+    && rm -rf /var/lib/apt/lists/*

package/templates/app/package-scripts/db.json

@@ -1,4 +1,5 @@
-    "db:create": "docker create --name {{project}}-dev-db -p 127.0.0.1:54322:5432 -e POSTGRES_HOST_AUTH_METHOD=trust -v {{project}}-dev-db-data:/var/lib/postgresql/data {{dbImage}}",
+    "db:image": "docker build --tag {{dbImage}} db",
+    "db:create": "npm run db:image && docker create --name {{project}}-dev-db -p 127.0.0.1:54322:5432 -e POSTGRES_HOST_AUTH_METHOD=trust -v {{project}}-dev-db-data:/var/lib/postgresql/data {{dbImage}}",
     "db:start": "docker start {{project}}-dev-db",
     "db:stop": "docker stop {{project}}-dev-db",
     "db:reset": "docker rm -f {{project}}-dev-db && docker volume rm {{project}}-dev-db-data && npm run db:create && npm run db:start",

package/templates/app/skeleton-lite/.starcistacks/application-stacks.yaml

@@ -27,9 +27,9 @@ components:
     role: service
     stateful: true
     volumes: [db-data]
-    image: "supabase/postgres:17.11.0.006@sha256:c141fd17ac6a76c4323e90b3aee8ff1a23d2e89e547c2b963cfadc309c079cc2"
+    image: "{{project}}/db:v0.0.0@sha256:0000000000000000000000000000000000000000000000000000000000000000"
     compose: infra/swarm/stack.yaml
-    purpose: The app's own PostgreSQL (pg_cron, pg_net, pgmq, vector), migrated by starci app db migrate.
+    purpose: The app's own PostgreSQL, the official postgres image plus pgvector built from db/Dockerfile, migrated by starci app db migrate.
     required: true
   ingress:
     role: ingress
@@ -203,6 +203,8 @@ environments:
       images:
         api:
           app: api
+        db:
+          app: db
         web:
           app: web
           # Public browser configuration; replace these placeholders before deployment.

package/templates/app/skeleton-lite/.starcistacks/dev/README.md

@@ -1,6 +1,6 @@
 # Development stack
 
-Every development dependency runs in Docker Linux containers. The `db` service (image supabase/postgres: PostgreSQL with pg_cron, pg_net, pgmq and pgvector) starts with `npm run db:start` and takes the migrations with `npm run db:push`; storage is the S3-compatible MinIO the environment names. Every other declared dependency, such as Redis, starts through its managed `<dep>:create`, `<dep>:start` and `<dep>:stop` scripts or the declared container model; Compose is an implementation detail. The app services may run in the local Docker Swarm model or through a declared native development profile while dependencies stay in Docker.
+Every development dependency runs in Docker Linux containers. The `db` service (the official postgres image plus pgvector, built from `db/Dockerfile`) starts with `npm run db:start` and takes the migrations with `npm run db:push`; storage is the S3-compatible MinIO the environment names. Every other declared dependency, such as Redis, starts through its managed `<dep>:create`, `<dep>:start` and `<dep>:stop` scripts or the declared container model; Compose is an implementation detail. The app services may run in the local Docker Swarm model or through a declared native development profile while dependencies stay in Docker.
 The application image references contain illustrative all-zero digests. Replace them with verified published release digests in the manifest, model and `.starcistacks/dev/infra/swarm/releases/images.lock.yaml` before starting the container model. Seal the local database connection and the integration credentials; a container cannot use the host's loopback address without owner-configured networking. Local source development remains available through the app scripts.
 
 The runtime template tracks no encrypted members. Scaffolding generates the six declared members with placeholder values encrypted to this app's own recipient in `.sops.yaml`. Replace those values with `starci app secret set dev` using the matching host age identity in untracked local custody. Existing generated envelopes are decryptable with that app identity and can be updated in place. Each Docker secret contains the corresponding key's real value, and the API receives it through its declared mounted file.

package/templates/app/skeleton-lite/.starcistacks/dev/infra/swarm/stack.yaml

@@ -83,7 +83,7 @@ services:
         condition: on-failure
         delay: 5s
   db:
-    image: "supabase/postgres:17.11.0.006@sha256:c141fd17ac6a76c4323e90b3aee8ff1a23d2e89e547c2b963cfadc309c079cc2"
+    image: "{{project}}/db:v0.0.0@sha256:0000000000000000000000000000000000000000000000000000000000000000"
     environment:
       POSTGRES_DB: postgres
       POSTGRES_PASSWORD_FILE: /run/secrets/db-password

package/templates/app/skeleton-lite/.starcistacks/production/README.md

@@ -1,7 +1,7 @@
 # Production stack
 
 The tracked model declares Docker Swarm application services and one digest-pinned Caddy ingress.
-The `db` service (image supabase/postgres) supplies PostgreSQL with pg_cron, pg_net, pgmq and pgvector on a named volume; sign-in is the API's own (Passport) and storage is the S3-compatible MinIO the environment names. The app and its dependencies run on Docker Swarm. A Redis service runs only when `hfs.json` `sides.be.backing` declares it for a capability that needs it: one stateful replica with a digest-pinned image, a named volume with a backup entry and its password as a sealed member granted as a Swarm secret (Redis runs `--appendonly yes` with the volume at `/data`). The scaffold declares none; `starci app add queue|job` declares Redis and renders it here.
+The `db` service (the official postgres image plus pgvector, built from `db/Dockerfile` and pushed with the release images) supplies PostgreSQL on a named volume; sign-in is the API's own (Passport) and storage is the S3-compatible MinIO the environment names. The app and its dependencies run on Docker Swarm. A Redis service runs only when `hfs.json` `sides.be.backing` declares it for a capability that needs it: one stateful replica with a digest-pinned image, a named volume with a backup entry and its password as a sealed member granted as a Swarm secret (Redis runs `--appendonly yes` with the volume at `/data`). The scaffold declares none; `starci app add queue|job` declares Redis and renders it here.
 The model is a deployment declaration. It contains no owner credentials, real DNS receipt, completed release or restore proof. Public records under `.starcistacks/production/infra/swarm/` explicitly mark those owner-run operations as pending.
 Its application image references contain illustrative all-zero digests; they identify no published image and must be replaced before deployment.
 

package/templates/app/skeleton-lite/.starcistacks/production/infra/swarm/stack.yaml

@@ -83,7 +83,7 @@ services:
         condition: on-failure
         delay: 5s
   db:
-    image: "supabase/postgres:17.11.0.006@sha256:c141fd17ac6a76c4323e90b3aee8ff1a23d2e89e547c2b963cfadc309c079cc2"
+    image: "{{project}}/db:v0.0.0@sha256:0000000000000000000000000000000000000000000000000000000000000000"
     environment:
       POSTGRES_DB: postgres
       POSTGRES_PASSWORD_FILE: /run/secrets/db-password

package/templates/app/skeleton-lite/README.md

@@ -8,7 +8,7 @@ The starter keeps one deployable API and one web app, with the same code structu
 
 ## Stack
 
-TypeScript everywhere, NestJS in `be/`, Next.js with next-intl in `fe/`, PostgreSQL (the `db` service, image supabase/postgres), Passport for Google and password sign-in, S3-compatible storage (MinIO), npm workspaces, and Turbo for front-end tasks.
+TypeScript everywhere, NestJS in `be/`, Next.js with next-intl in `fe/`, PostgreSQL (the `db` service: the official postgres image plus pgvector, built from `db/Dockerfile`), Passport for Google and password sign-in, S3-compatible storage (MinIO), npm workspaces, and Turbo for front-end tasks.
 
 ## Repository layout
 
@@ -24,7 +24,7 @@ Declare `ci.github.repository` and `ci.github.defaultBranch` in `.starcistacks/a
 
 ## Development
 
-Every development dependency runs in Docker Linux containers. Create the local database once with `npm run db:create`, start it with `npm run db:start` (one container of the pinned `db` image, on 127.0.0.1:54322), export `DATABASE_URL=postgresql://supabase_admin@127.0.0.1:54322/postgres` and apply `db/bootstrap.sql` and the migrations with `npm run db:push`; start any other declared dependency through its managed `<dep>:create`, `<dep>:start` and `<dep>:stop` scripts or the declared container model. Compose is an implementation detail. Configure the local environment and start the API and web app using the package scripts for the declared development profile. In production, the app and its dependencies, the database included, run on Docker Swarm; pgvector owns vector search.
+Every development dependency runs in Docker Linux containers. Create the local database once with `npm run db:create`, start it with `npm run db:start` (one container of the image `db/Dockerfile` builds, on 127.0.0.1:54322), export `DATABASE_URL=postgresql://postgres@127.0.0.1:54322/postgres` and apply `db/bootstrap.sql` and the migrations with `npm run db:push`; start any other declared dependency through its managed `<dep>:create`, `<dep>:start` and `<dep>:stop` scripts or the declared container model. Compose is an implementation detail. Configure the local environment and start the API and web app using the package scripts for the declared development profile. In production, the app and its dependencies, the database included, run on Docker Swarm; pgvector owns vector search.
 
 ```sh
 npm install

package/templates/be/patterns/jobs/platform/jobs.log-events.ts.tpl

@@ -6,4 +6,6 @@ export enum JobsLogEvent {
     DeliveryFailed = "jobs.delivery.failed",
     /** A failed delivery could not even be recorded as failed; the lease will expire and the job will be claimed again. */
     FailureNotRecorded = "jobs.delivery.failure-not-recorded",
+    /** A scheduler tick failed to fire; the next firing claims its own minute (lite, R335). */
+    TickFailed = "jobs.tick.failed",
 }