@starci/hfs 4.10.1 → 4.11.0

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",
 }

package/templates/be/patterns/jobs/platform-lite/job-tick.service.spec.ts.tpl

@@ -0,0 +1,65 @@
+import { SchedulerRegistry } from "@nestjs/schedule"
+import { Test } from "@nestjs/testing"
+import { FakeClock, fakeTransaction, mockEntityManager } from "@starci/jest-preset"
+import { CLOCK } from "@modules/platform/clock"
+import { LOGGER } from "@modules/platform/logging"
+import { QUEUE_OUTBOX } from "@modules/platform/queue"
+import type { JobTick } from "./job-ticks.contracts"
+import { JOBS_MANAGERS } from "./jobs.decorators"
+import { JobTickService, tickMinute } from "./job-tick.service"
+
+// The statements advisoryXactLock and callDbFunction of platform/database send for one firing.
+const LOCK_TICK = "SELECT pg_advisory_xact_lock(hashtextextended($1, 0))"
+const CLAIM_TICK = "SELECT * FROM job_tick_claim($1, $2)"
+
+const AT = "2026-02-03T04:05:06.000Z"
+const TICK: JobTick = { name: "nightly-digest", cron: "0 2 * * *", timeZone: "UTC", queue: "digests", payload: { kind: "nightly" } }
+
+const build = async (claimed: boolean) => {
+    const transaction = fakeTransaction(mockEntityManager({ query: [[LOCK_TICK, []], [CLAIM_TICK, [{ claimed }]]] }))
+    const outbox = { write: jest.fn().mockResolvedValue(undefined) }
+    const registry = { addCronJob: jest.fn() }
+    const moduleRef = await Test.createTestingModule({
+        providers: [
+            JobTickService,
+            { provide: SchedulerRegistry, useValue: registry },
+            { provide: JOBS_MANAGERS, useValue: [transaction.em] },
+            { provide: QUEUE_OUTBOX, useValue: outbox },
+            { provide: CLOCK, useValue: new FakeClock(AT) },
+            { provide: LOGGER, useValue: { info: jest.fn(), warn: jest.fn(), error: jest.fn() } },
+        ],
+    }).compile()
+    return { ticks: moduleRef.get(JobTickService), transaction, outbox, registry }
+}
+
+describe("JobTickService", () => {
+    it("names a tick's slot by its UTC minute", () => {
+        expect(tickMinute(new Date(AT))).toBe("2026-02-03T04:05")
+    })
+
+    it("locks the tick, claims its minute and enqueues one job in the same transaction", async () => {
+        const { ticks, transaction, outbox } = await build(true)
+
+        await expect(ticks.fire(TICK)).resolves.toBe(true)
+
+        expect(transaction.em.query).toHaveBeenNthCalledWith(1, LOCK_TICK, ["tick:nightly-digest"])
+        expect(transaction.em.query).toHaveBeenNthCalledWith(2, CLAIM_TICK, ["nightly-digest", "2026-02-03T04:05"])
+        expect(outbox.write).toHaveBeenCalledWith(expect.anything(), "digests", { kind: "nightly" }, "tick:nightly-digest:2026-02-03T04:05")
+    })
+
+    it("enqueues nothing when another replica already fired the tick this minute", async () => {
+        const { ticks, outbox } = await build(false)
+
+        await expect(ticks.fire(TICK)).resolves.toBe(false)
+
+        expect(outbox.write).not.toHaveBeenCalled()
+    })
+
+    it("registers no cron job while the tick list is empty", async () => {
+        const { ticks, registry } = await build(true)
+
+        ticks.onApplicationBootstrap()
+
+        expect(registry.addCronJob).not.toHaveBeenCalled()
+    })
+})

package/templates/be/patterns/jobs/platform-lite/job-tick.service.ts.tpl

@@ -0,0 +1,78 @@
+import { Injectable } from "@nestjs/common"
+import type { OnApplicationBootstrap } from "@nestjs/common"
+import { SchedulerRegistry } from "@nestjs/schedule"
+import { CronJob } from "cron"
+import type { EntityManager } from "typeorm"
+import { InjectClock } from "@modules/platform/clock"
+import type { Clock } from "@modules/platform/clock"
+import { advisoryXactLock, callDbFunction } from "@modules/platform/database"
+import { InjectLogger } from "@modules/platform/logging"
+import type { Logger } from "@modules/platform/logging"
+import { InjectQueueOutbox } from "@modules/platform/queue"
+import type { QueueOutbox } from "@modules/platform/queue"
+import { JobsError, JobsErrorCode } from "./errors/jobs.error"
+import { JOB_TICKS } from "./job-ticks.contracts"
+import type { JobTick } from "./job-ticks.contracts"
+import { InjectJobsManagers } from "./jobs.decorators"
+import { JobsLogEvent } from "./jobs.log-events"
+
+/** The record job_tick_claim returns. */
+interface TickClaim {
+    /** True when this firing moved the tick to its minute and must enqueue. */
+    readonly claimed: boolean
+}
+
+/** The UTC minute of `at` (`YYYY-MM-DDTHH:MM`): the slot a tick fires once in. */
+export const tickMinute = (at: Date): string => at.toISOString().slice(0, 16)
+
+@Injectable()
+/**
+ * The one scheduler of the app (R335): @nestjs/schedule fires every tick of JOB_TICKS on every replica, and each firing takes
+ * advisoryXactLock("tick:<name>"), claims the tick's minute through job_tick_claim and, only when it moved the tick, writes one
+ * job into the queue outbox in the same transaction, so the deployment enqueues the tick once per minute.
+ */
+export class JobTickService implements OnApplicationBootstrap {
+    constructor(
+        private readonly registry: SchedulerRegistry,
+        @InjectJobsManagers() private readonly managers: ReadonlyArray<EntityManager>,
+        @InjectQueueOutbox() private readonly outbox: QueueOutbox,
+        @InjectClock() private readonly clock: Clock,
+        @InjectLogger() private readonly logger: Logger,
+    ) {}
+
+    /** Registers one cron job per tick, read in the tick's time zone; a failed firing is logged and the next one runs. */
+    onApplicationBootstrap(): void {
+        for (const tick of JOB_TICKS) {
+            this.registry.addCronJob(tick.name, CronJob.from({
+                cronTime: tick.cron,
+                timeZone: tick.timeZone,
+                onTick: async () => {
+                    await this.fire(tick)
+                },
+                errorHandler: (cause: unknown) => {
+                    this.logger.error(JobsLogEvent.TickFailed, cause, { tick: tick.name })
+                },
+                start: true,
+            }))
+        }
+    }
+
+    /** Fires the tick for the current minute; true when this replica enqueued its job, false when another one already had. */
+    async fire(tick: JobTick): Promise<boolean> {
+        const minute = tickMinute(this.clock.now())
+        return this.writer().transaction(async (tx) => {
+            await advisoryXactLock(tx, `tick:${tick.name}`)
+            const [claim] = await callDbFunction<TickClaim>(tx, "job_tick_claim", [tick.name, minute])
+            if (claim?.claimed !== true) return false
+            await this.outbox.write(tx, tick.queue, tick.payload, `tick:${tick.name}:${minute}`)
+            return true
+        })
+    }
+
+    /** The entity manager of the connection that holds the tick table. */
+    private writer(): EntityManager {
+        const [manager] = this.managers
+        if (manager === undefined) throw new JobsError({ code: JobsErrorCode.ConnectionMissing })
+        return manager
+    }
+}

package/templates/be/patterns/jobs/platform-lite/job-ticks.contracts.ts.tpl

@@ -0,0 +1,16 @@
+/** One recurring tick of platform/jobs: at each minute its cron expression names, one job of `queue` is enqueued with `payload` (R335). */
+export interface JobTick {
+    /** The stable name: the advisory lock key, the minute claim and the correlation id carry it. */
+    readonly name: string
+    /** The five-field cron expression of the minutes the tick fires at. */
+    readonly cron: string
+    /** The time zone the expression is read in; ticks run in UTC. */
+    readonly timeZone: "UTC"
+    /** The queue the tick enqueues one job of. */
+    readonly queue: string
+    /** The payload of that job: ids and literals only. */
+    readonly payload: object
+}
+
+/** The ticks of this app, as data: JobTickService registers one cron job per entry. */
+export const JOB_TICKS: ReadonlyArray<JobTick> = []

package/templates/be/patterns/jobs/platform-lite/jobs.module.ts.tpl

@@ -0,0 +1,40 @@
+import { Module } from "@nestjs/common"
+import type { DynamicModule } from "@nestjs/common"
+import { ScheduleModule } from "@nestjs/schedule"
+import type { EntityManager } from "typeorm"
+import { JOB_CLAIMS, JOB_PROCESSOR_REGISTRY, JOBS_MANAGERS } from "./jobs.decorators"
+import { ConfigurableModuleClass, OPTIONS_TYPE } from "./jobs.module-definition"
+import { JobClaimService } from "./job-claim.service"
+import { JobRunnerService } from "./job-runner.service"
+import { JobTickService } from "./job-tick.service"
+
+@Module({})
+/**
+ * The fenced jobs of a service: the claim service that owns the job row, the runner that subscribes processors to their queues and
+ * the one tick scheduler (R335), which composes @nestjs/schedule here and nowhere else. Needs the queue capability registered in
+ * the same app.
+ */
+export class JobsModule extends ConfigurableModuleClass {
+    /** Registers the capability once per app that runs jobs. */
+    static register(options: typeof OPTIONS_TYPE): DynamicModule {
+        const base = super.register(options)
+        return {
+            ...base,
+            imports: [...(base.imports ?? []), ScheduleModule.forRoot()],
+            providers: [
+                ...(base.providers ?? []),
+                {
+                    provide: JOBS_MANAGERS,
+                    useFactory: (manager: EntityManager) => [manager],
+                    inject: [options.connection],
+                },
+                JobClaimService,
+                JobRunnerService,
+                JobTickService,
+                { provide: JOB_CLAIMS, useExisting: JobClaimService },
+                { provide: JOB_PROCESSOR_REGISTRY, useExisting: JobRunnerService },
+            ],
+            exports: [JOB_CLAIMS, JOB_PROCESSOR_REGISTRY],
+        }
+    }
+}

package/templates/be/patterns/jobs/platform-lite/jobs.sql.tpl

@@ -93,3 +93,47 @@ revoke all on function public.job_complete(uuid, bigint, timestamptz) from publi
 grant execute on function public.job_complete(uuid, bigint, timestamptz) to app_be;
 revoke all on function public.job_fail(uuid, bigint, text, timestamptz) from public;
 grant execute on function public.job_fail(uuid, bigint, text, timestamptz) to app_be;
+
+-- The scheduler ticks of platform/jobs (R335): one row per tick holds the last UTC minute it fired. Every replica's
+-- @nestjs/schedule fires the tick; under advisoryXactLock('tick:<name>') job_tick_claim moves the row to the new minute and
+-- answers claimed, so exactly one replica enqueues the tick's job per minute and a replica that comes later answers not claimed.
+create table public.job_ticks (
+    name varchar(200) not null,
+    minute varchar(16) not null,
+    constraint job_ticks_pkey primary key (name)
+);
+
+alter table public.job_ticks enable row level security;
+alter table public.job_ticks force row level security;
+
+create policy job_ticks_app_be_select
+on public.job_ticks for select to app_be
+using (name is not null);
+
+create policy job_ticks_app_be_insert
+on public.job_ticks for insert to app_be
+with check (name is not null);
+
+create policy job_ticks_app_be_update
+on public.job_ticks for update to app_be
+using (name is not null)
+with check (name is not null);
+
+revoke all on table public.job_ticks from public, anon, authenticated;
+grant select, insert, update on table public.job_ticks to app_be;
+
+create function public.job_tick_claim(p_name varchar, p_minute varchar)
+returns table (claimed boolean)
+language sql
+as $$
+    with moved as (
+        insert into public.job_ticks as t (name, minute) values (p_name, p_minute)
+        on conflict (name) do update set minute = excluded.minute
+         where t.minute < excluded.minute
+        returning true as claimed
+    )
+    select coalesce((select m.claimed from moved as m), false)
+$$;
+
+revoke all on function public.job_tick_claim(varchar, varchar) from public;
+grant execute on function public.job_tick_claim(varchar, varchar) to app_be;