@starci/hfs 4.7.31 → 4.7.33

package/templates/be/skeleton/src/modules/platform/logging/json-logger.service.ts

@@ -1,6 +1,9 @@
 import type { Writable } from "node:stream"
 import { InjectClock } from "@modules/platform/clock"
 import type { Clock } from "@modules/platform/clock"
+import { InjectIds } from "@modules/platform/ids"
+import type { Ids } from "@modules/platform/ids"
+import { stampLogFields } from "./correlation.policy"
 import { InjectLogErr, InjectLogOut } from "./logging.decorators"
 import type { LogFields, Logger } from "./logging.port"
 
@@ -8,11 +11,17 @@ type Level = "info" | "warn" | "error"
 
 /** The default adapter: one JSON object per line, stamped by the Clock; info goes to `out`, warn and error to `err`. */
 export class JsonLoggerService implements Logger {
+    /** The identity of lines written outside any correlation scope: drawn once, so such lines of one process share it. */
+    private readonly rootId: string
+
     constructor(
         @InjectClock() private readonly clock: Clock,
         @InjectLogOut() private readonly out: Writable,
         @InjectLogErr() private readonly err: Writable,
-    ) {}
+        @InjectIds() ids: Ids,
+    ) {
+        this.rootId = ids.next()
+    }
 
     /** Writes an info line. */
     info(event: string, fields?: LogFields): void {
@@ -35,9 +44,12 @@ export class JsonLoggerService implements Logger {
     }
 
     private write(level: Level, sink: Writable, event: string, fields?: LogFields): void {
-        sink.write(`${JSON.stringify({ ...fields, level, event, time: this.clock.now().toISOString() })}\n`)
+        sink.write(
+            `${JSON.stringify({ ...stampLogFields(fields, this.rootId), level, event, time: this.clock.now().toISOString() })}\n`,
+        )
     }
 }
 
 /** Builds the JSON logger stamping lines with `clock` on stdout and stderr; main.ts uses it before the DI container exists. */
-export const createJsonLogger = (clock: Clock): Logger => new JsonLoggerService(clock, process.stdout, process.stderr)
+export const createJsonLogger = (clock: Clock, ids: Ids): Logger =>
+    new JsonLoggerService(clock, process.stdout, process.stderr, ids)

package/templates/be/skeleton/src/modules/platform/logging/logging.decorators.ts

@@ -2,12 +2,24 @@ import type { Writable } from "node:stream"
 import { injector } from "@modules/platform/composition"
 import type { TypedParameterDecorator } from "@modules/platform/composition"
 import type { Logger } from "./logging.port"
+import type { CorrelationIds, CorrelationRunner } from "./correlation.port"
 
 /** Token of the Logger port. */
 export const LOGGER: unique symbol = Symbol("platform.logging.logger")
 
-/** Injects the Logger port. Parameter type: Logger. */
-export const InjectLogger = (): TypedParameterDecorator<Logger> => injector<Logger>(LOGGER)
+/** Token of the inbound identity resolver. */
+export const CORRELATION_IDS: unique symbol = Symbol("platform.logging.correlation-ids")
+
+/** Token of the logger's async scope runner. */
+export const CORRELATION_RUNNER: unique symbol = Symbol("platform.logging.correlation-runner")
+
+/** Injects explicit inbound identity resolution. Parameter type: CorrelationIds. */
+export const InjectCorrelationIds = (): TypedParameterDecorator<CorrelationIds> =>
+    injector<CorrelationIds>(CORRELATION_IDS)
+
+/** Injects infrastructure logging scopes. Parameter type: CorrelationRunner. */
+export const InjectCorrelationRunner = (): TypedParameterDecorator<CorrelationRunner> =>
+    injector<CorrelationRunner>(CORRELATION_RUNNER)
 
 /** Token of the stream info lines go to. */
 export const LOG_OUT: unique symbol = Symbol("platform.logging.out")
@@ -15,6 +27,9 @@ export const LOG_OUT: unique symbol = Symbol("platform.logging.out")
 /** Token of the stream warn and error lines go to. */
 export const LOG_ERR: unique symbol = Symbol("platform.logging.err")
 
+/** Injects the Logger port. Parameter type: Logger. */
+export const InjectLogger = (): TypedParameterDecorator<Logger> => injector<Logger>(LOGGER)
+
 /** Injects the stream info lines go to. Parameter type: Writable. */
 export const InjectLogOut = (): TypedParameterDecorator<Writable> => injector<Writable>(LOG_OUT)
 

package/templates/be/skeleton/src/modules/platform/logging/logging.log-events.ts

@@ -1,4 +1,4 @@
-/** Log events of the process lifecycle: the entry points (main.ts of each app) log these. */
+/** Log events owned by logging: process lifecycle and framework messages routed through the JSON port. */
 export enum LoggingLogEvent {
     /** The HTTP listener is bound and the service answers requests. */
     ServerStarted = "server.started",
@@ -8,4 +8,16 @@ export enum LoggingLogEvent {
     MigrationsApplied = "migrations.applied",
     /** The seed command finished; the seed files it ran ride in the fields, by connection. */
     SeedsApplied = "seeds.applied",
+    /** An ordinary Nest framework lifecycle message. */
+    FrameworkLog = "platform.logging.framework.log",
+    /** A Nest framework warning. */
+    FrameworkWarning = "platform.logging.framework.warning",
+    /** A Nest framework error. */
+    FrameworkError = "platform.logging.framework.error",
+    /** A Nest framework debug message. */
+    FrameworkDebug = "platform.logging.framework.debug",
+    /** A Nest framework verbose message. */
+    FrameworkVerbose = "platform.logging.framework.verbose",
+    /** A fatal Nest framework failure. */
+    FrameworkFatal = "platform.logging.framework.fatal",
 }

package/templates/be/skeleton/src/modules/platform/logging/logging.module.ts

@@ -2,8 +2,11 @@ import { Module } from "@nestjs/common"
 import type { DynamicModule } from "@nestjs/common"
 import { CLOCK } from "@modules/platform/clock"
 import type { Clock } from "@modules/platform/clock"
+import { IDS } from "@modules/platform/ids"
+import type { Ids } from "@modules/platform/ids"
+import { CorrelationService } from "./correlation.service"
 import { createJsonLogger } from "./json-logger.service"
-import { LOGGER } from "./logging.decorators"
+import { CORRELATION_IDS, CORRELATION_RUNNER, LOGGER } from "./logging.decorators"
 import { ConfigurableModuleClass, OPTIONS_TYPE } from "./logging.module-definition"
 
 @Module({})
@@ -16,9 +19,16 @@ export class LoggingModule extends ConfigurableModuleClass {
             ...base,
             providers: [
                 ...(base.providers ?? []),
-                { provide: LOGGER, inject: [CLOCK], useFactory: (clock: Clock) => createJsonLogger(clock) },
+                CorrelationService,
+                { provide: CORRELATION_IDS, useExisting: CorrelationService },
+                { provide: CORRELATION_RUNNER, useExisting: CorrelationService },
+                {
+                    provide: LOGGER,
+                    inject: [CLOCK, IDS],
+                    useFactory: (clock: Clock, ids: Ids) => createJsonLogger(clock, ids),
+                },
             ],
-            exports: [LOGGER],
+            exports: [LOGGER, CORRELATION_IDS, CORRELATION_RUNNER],
         }
     }
 }

package/templates/be/skeleton/src/modules/platform/logging/nest-logger.service.spec.ts

@@ -0,0 +1,69 @@
+import { FakeClock, fakeIds, mock } from "@starci/jest-preset"
+import { Test } from "@nestjs/testing"
+import { runWithCorrelation } from "./correlation.policy"
+import { createJsonLogger } from "./json-logger.service"
+import { LoggingLogEvent } from "./logging.log-events"
+import type { Logger } from "./logging.port"
+import { LOGGER } from "./logging.decorators"
+import { createNestLogger, NestLoggerService } from "./nest-logger.service"
+
+const build = async () => {
+    const logger = mock<Logger>()
+    const moduleRef = await Test.createTestingModule({
+        providers: [NestLoggerService, { provide: LOGGER, useValue: logger }],
+    }).compile()
+    return { logger, adapter: moduleRef.get<NestLoggerService>(NestLoggerService) }
+}
+
+describe("NestLoggerService", () => {
+    it("maps all framework levels to owned enum identities through the logging port", async () => {
+        const { logger, adapter } = await build()
+        const failure = new Error("bootstrap failed")
+
+        adapter.log("started", "NestApplication")
+        adapter.warn("recovering", "Injector")
+        adapter.debug(42)
+        adapter.verbose({ operation: "bootstrap" }, { ignored: "unstructured" })
+        adapter.error(failure, failure.stack, "ExceptionHandler")
+        adapter.fatal("stopping")
+
+        expect(logger.info).toHaveBeenNthCalledWith(1, LoggingLogEvent.FrameworkLog, {
+            message: "started",
+            context: "NestApplication",
+        })
+        expect(logger.info).toHaveBeenNthCalledWith(2, LoggingLogEvent.FrameworkDebug, { message: "42" })
+        expect(logger.info).toHaveBeenNthCalledWith(3, LoggingLogEvent.FrameworkVerbose, { message: "[object Object]" })
+        expect(logger.warn).toHaveBeenCalledWith(LoggingLogEvent.FrameworkWarning, {
+            message: "recovering",
+            context: "Injector",
+        })
+        expect(logger.error).toHaveBeenNthCalledWith(1, LoggingLogEvent.FrameworkError, failure, {
+            message: "Error: bootstrap failed",
+            context: "ExceptionHandler",
+        })
+        expect(logger.error).toHaveBeenNthCalledWith(2, LoggingLogEvent.FrameworkFatal, "stopping", {
+            message: "stopping",
+        })
+    })
+
+    it("stamps bootstrap lines and uses the active request identity during framework logging", () => {
+        const lines: Array<string> = []
+        const output = jest.spyOn(process.stdout, "write").mockImplementation((chunk) => lines.push(String(chunk)) > 0)
+        try {
+            const adapter = createNestLogger(createJsonLogger(new FakeClock("2026-10-24T00:00:00Z"), fakeIds()))
+            adapter.log("booting", "NestFactory")
+            runWithCorrelation("request-id", () => {
+                adapter.log("handling", "Router")
+            })
+
+            expect(lines).toHaveLength(2)
+            expect(lines[0]).toContain('"correlationId":"00000000-0000-4000-8000-000000000001"')
+            expect(lines[1]).toContain('"correlationId":"request-id"')
+            expect(lines[0]).toContain('"context":"NestFactory"')
+            expect(lines[1]).toContain('"context":"Router"')
+            expect(lines.every((line) => line.includes(`"event":"${LoggingLogEvent.FrameworkLog}"`))).toBe(true)
+        } finally {
+            output.mockRestore()
+        }
+    })
+})

package/templates/be/skeleton/src/modules/platform/logging/nest-logger.service.ts

@@ -0,0 +1,48 @@
+import type { LoggerService } from "@nestjs/common"
+import { InjectLogger } from "./logging.decorators"
+import { LoggingLogEvent } from "./logging.log-events"
+import type { LogFields, Logger } from "./logging.port"
+
+/** Keeps the framework's message and optional textual context without dumping unstructured extra arguments. */
+const fieldsOf = (message: unknown, optionalParams: ReadonlyArray<unknown>): LogFields => {
+    const context = optionalParams.at(-1)
+    return { message: String(message), ...(typeof context === "string" ? { context } : {}) }
+}
+
+/** Routes Nest's own bootstrap and runtime messages through the app's correlation-stamped logging port. */
+export class NestLoggerService implements LoggerService {
+    constructor(@InjectLogger() private readonly logger: Logger) {}
+
+    /** Records an ordinary framework lifecycle message. */
+    log(message: unknown, ...optionalParams: Array<unknown>): void {
+        this.logger.info(LoggingLogEvent.FrameworkLog, fieldsOf(message, optionalParams))
+    }
+
+    /** Keeps the framework's error as the cause for the logging adapter's structured serialization. */
+    error(message: unknown, ...optionalParams: Array<unknown>): void {
+        this.logger.error(LoggingLogEvent.FrameworkError, message, fieldsOf(message, optionalParams))
+    }
+
+    /** Records a recoverable framework warning. */
+    warn(message: unknown, ...optionalParams: Array<unknown>): void {
+        this.logger.warn(LoggingLogEvent.FrameworkWarning, fieldsOf(message, optionalParams))
+    }
+
+    /** Preserves debug identity on the JSON port's informational stream. */
+    debug(message: unknown, ...optionalParams: Array<unknown>): void {
+        this.logger.info(LoggingLogEvent.FrameworkDebug, fieldsOf(message, optionalParams))
+    }
+
+    /** Preserves verbose identity on the JSON port's informational stream. */
+    verbose(message: unknown, ...optionalParams: Array<unknown>): void {
+        this.logger.info(LoggingLogEvent.FrameworkVerbose, fieldsOf(message, optionalParams))
+    }
+
+    /** Records a fatal framework failure through the error stream. */
+    fatal(message: unknown, ...optionalParams: Array<unknown>): void {
+        this.logger.error(LoggingLogEvent.FrameworkFatal, message, fieldsOf(message, optionalParams))
+    }
+}
+
+/** Supplies NestFactory or CommandFactory with the same Logger port used by application code. */
+export const createNestLogger = (logger: Logger): LoggerService => new NestLoggerService(logger)

package/templates/be/skeleton/src/modules/platform/primitives/index.ts

@@ -1,3 +1,4 @@
 export type { Outcome } from "./outcome.contracts"
 export { ok, refused, unwrapOutcome } from "./outcome.mapper"
 export { eachInOrder } from "./sequence.policy"
+export { isRecord } from "./record.policy"

package/templates/be/skeleton/src/modules/platform/primitives/record.policy.spec.ts

@@ -0,0 +1,12 @@
+import { isRecord } from "./record.policy"
+
+describe("isRecord", () => {
+    it("narrows non-null objects before provider fields are read", () => {
+        expect(isRecord({ status: 200 })).toBe(true)
+        expect(isRecord([])).toBe(true)
+        expect(isRecord(null)).toBe(false)
+        expect(isRecord(undefined)).toBe(false)
+        expect(isRecord("response")).toBe(false)
+        expect(isRecord(200)).toBe(false)
+    })
+})

package/templates/be/skeleton/src/modules/platform/primitives/record.policy.ts

@@ -0,0 +1,3 @@
+/** True for a non-null object, so untrusted parsed data can be narrowed before any key is read. */
+export const isRecord = (value: unknown): value is Record<string, unknown> =>
+    typeof value === "object" && value !== null

package/templates/be/skeleton-lite/apps/api/src/compose/platform.ts

@@ -8,6 +8,8 @@ import { DATABASE_ERROR_KINDS, DatabaseModule } from "@modules/platform/database
 import { ERRORS_MESSAGES, ErrorsModule } from "@modules/platform/errors"
 import { HTTP_SECURITY_ERROR_KINDS, HTTP_SECURITY_MESSAGES, HttpSecurityModule } from "@modules/platform/http-security"
 import { I18nModule } from "@modules/platform/i18n"
+import { IdsModule } from "@modules/platform/ids"
+import { HTTP_ERROR_KINDS, HTTP_MESSAGES, HttpModule } from "@modules/platform/http"
 import { LoggingModule } from "@modules/platform/logging"
 import { RetryModule } from "@modules/platform/retry"
 import type { ApiOptions } from "../api.options"
@@ -20,14 +22,17 @@ import type { ApiOptions } from "../api.options"
 export const platformModules = (options: ApiOptions): Array<DynamicModule> => [
     ClockModule.register({ isGlobal: true }),
     RetryModule.register({ isGlobal: true }),
+    IdsModule.register({ isGlobal: true }),
     LoggingModule.register({ isGlobal: true }),
+    HttpModule.register({ isGlobal: true }),
     I18nModule.register({
         isGlobal: true,
-        bundles: [ERRORS_MESSAGES, HTTP_SECURITY_MESSAGES, IDENTITY_MESSAGES],
+        bundles: [HTTP_MESSAGES, ERRORS_MESSAGES, HTTP_SECURITY_MESSAGES, IDENTITY_MESSAGES],
     }),
     ErrorsModule.register({
         isGlobal: true,
         kinds: [
+            HTTP_ERROR_KINDS,
             CONFIG_ERROR_KINDS,
             DATABASE_ERROR_KINDS,
             HTTP_SECURITY_ERROR_KINDS,

package/templates/be/skeleton-lite/apps/cli/src/compose/platform.ts

@@ -1,12 +1,16 @@
 import type { DynamicModule } from "@nestjs/common"
 import { ClockModule } from "@modules/platform/clock"
 import { DatabaseModule } from "@modules/platform/database"
+import { IdsModule } from "@modules/platform/ids"
+import { HTTP_ERROR_KINDS, HTTP_MESSAGES, HttpModule } from "@modules/platform/http"
 import { LoggingModule } from "@modules/platform/logging"
 import type { CliAppOptions } from "../cli.options"
 
 /** The shared clock, logger and least-privilege connection used by Supabase CLI commands. */
 export const platformModules = (options: CliAppOptions): Array<DynamicModule> => [
     ClockModule.register({ isGlobal: true }),
+    IdsModule.register({ isGlobal: true }),
     LoggingModule.register({ isGlobal: true }),
+    HttpModule.register({ isGlobal: true }),
     DatabaseModule.register({ isGlobal: true, connections: options.connections }),
 ]

package/templates/be/skeleton-lite/src/modules/platform/database/index.ts

@@ -5,3 +5,4 @@ export type { DatabaseConnectionOptions } from "./database.options"
 export { PRIMARY_DATA_SOURCE } from "./database.port"
 export { DATABASE_ERROR_KINDS } from "./errors/database.error"
 export { parsePrimaryDatabaseConfig } from "./primary.config"
+export { BATCH_ROWS } from "./database.sql"

package/templates/be/skeleton-lite/src/modules/platform/logging/index.ts

@@ -1,5 +1,18 @@
 export { createJsonLogger } from "./json-logger.service"
-export { InjectLogger, LOGGER } from "./logging.decorators"
+export {
+    InjectLogger,
+    LOGGER,
+    CORRELATION_IDS,
+    CORRELATION_RUNNER,
+    InjectCorrelationIds,
+    InjectCorrelationRunner,
+} from "./logging.decorators"
+export { applyCorrelation, correlationMiddleware } from "./correlation-request.policy"
+export type { CorrelationIds, CorrelationRunner } from "./correlation.port"
+export type { CorrelationHeaders, CorrelationRequest } from "./correlation.contracts"
+export { createCorrelationRunner } from "./correlation.service"
+export { isCorrelationId } from "./correlation.policy"
 export { LoggingLogEvent } from "./logging.log-events"
 export { LoggingModule } from "./logging.module"
 export type { Logger } from "./logging.port"
+export { createNestLogger } from "./nest-logger.service"

package/templates/be/skeleton-lite/src/modules/platform/logging/logging.log-events.ts

@@ -4,4 +4,16 @@ export enum LoggingLogEvent {
     ServerStarted = "server.started",
     /** The service failed before it could serve; the process exits non-zero. */
     StartupFailed = "server.startup_failed",
+    /** An ordinary Nest framework lifecycle message. */
+    FrameworkLog = "platform.logging.framework.log",
+    /** A Nest framework warning. */
+    FrameworkWarning = "platform.logging.framework.warning",
+    /** A Nest framework error. */
+    FrameworkError = "platform.logging.framework.error",
+    /** A Nest framework debug message. */
+    FrameworkDebug = "platform.logging.framework.debug",
+    /** A Nest framework verbose message. */
+    FrameworkVerbose = "platform.logging.framework.verbose",
+    /** A fatal Nest framework failure. */
+    FrameworkFatal = "platform.logging.framework.fatal",
 }

package/templates/be/skeleton-lite/src/modules/platform/primitives/index.ts

@@ -1,2 +1,4 @@
 export type { Outcome } from "./outcome.contracts"
 export { ok, refused, unwrapOutcome } from "./outcome.mapper"
+export { eachInOrder } from "./sequence.policy"
+export { isRecord } from "./record.policy"

package/templates/be/test-world/world/test-apps.options.ts.tpl

@@ -11,6 +11,7 @@ import { EnvSource } from "@modules/platform/config"
 import { DatabaseModule, MigrationRunnerService } from "@modules/platform/database"
 import { parseHttpSecurityConfig } from "@modules/platform/http-security"
 import type { HttpSecurityOptions } from "@modules/platform/http-security"
+import { IdsModule } from "@modules/platform/ids"
 import { LoggingModule } from "@modules/platform/logging"
 import { RetryModule } from "@modules/platform/retry"
 import { AppModule as CliApp } from "../../../apps/cli/src/app.module"
@@ -54,6 +55,7 @@ export const migrateCli = async (options: CliAppOptions): Promise<void> => {
 export const platformBase = (w: AppWiring): ReadonlyArray<DynamicModule> => [
     ClockModule.register({ isGlobal: true }),
     RetryModule.register({ isGlobal: true }),
+    IdsModule.register({ isGlobal: true }),
     LoggingModule.register({ isGlobal: true }),
     DatabaseModule.register({
         isGlobal: true,

package/templates/be/test-world/world/test-world.config.ts.tpl

@@ -3,6 +3,7 @@
  * definition (`.starcistacks/dev`); the library runs the Postgres of every connection real behind toxiproxy, migrates it once per
  * run through the cli app and boots the api apps in process.
  */
+import { applyCorrelation } from "@modules/platform/logging"
 import { defineTestWorld } from "@starci/test-world"
 {{appModuleImports}}
 import { {{optionsImports}} } from "./test-apps.options"

package/upgrade/check.mjs

@@ -1,139 +1,16 @@
-// The `starci app check --edition full` view of a lite app. The app stays byte-for-byte untouched: its declaration is cloned without
-// `edition`, then passed to the existing slot resolver, rule filter and architecture engine as an injected declaration.
-import fs from "node:fs";
-import path from "node:path";
-import { checkArchitecture } from "../runtime/scripts/hfs/architecture/index.mjs";
-import {
-  checkDatabase,
-  checkRepo,
-  trackedFiles,
-} from "../runtime/scripts/hfs/check.mjs";
-import { loadSlotManifest, openHfs } from "../runtime/scripts/hfs/slots.mjs";
-import { formatFindings } from "../sync/format.mjs";
-import {
-  appSource,
-  checkTargets,
-  loadHfs,
-  renderTargets,
-} from "../sync/index.mjs";
-import { readDeclaredStack } from "../sync/stack-images.mjs";
-import {
-  UPGRADE_PRESETS,
-  UpgradeError,
-  fullEditionDeclaration,
-} from "./index.mjs";
+// The edition selector of `starci app check --edition <edition>`. Editions are fixed at scaffold: the selector names the edition hfs.json
+// declares or the check refuses. There is no preview of a lite app as a full one.
+import { loadSlotManifest } from "../runtime/scripts/hfs/slots.mjs";
+import { loadHfs } from "../sync/index.mjs";
+import { UpgradeError } from "./index.mjs";
 
-const ONE_LINER = new Set(["eslint.config.mjs", "stylelint.config.mjs"]);
-
-function fullManagedFindings(repoRoot, targets) {
-  const findings = [];
-  for (const result of checkTargets(repoRoot, targets)) {
-    if (
-      result.status === "ok" ||
-      !fs.existsSync(path.join(repoRoot, ...result.path.split("/")))
-    )
-      continue;
-    const target = targets.find((candidate) => candidate.path === result.path);
-    const code =
-      target.mode === "block"
-        ? "HFS_GITIGNORE_BLOCK_DRIFT"
-        : ONE_LINER.has(path.posix.basename(result.path))
-          ? "HFS_RULE_OFF_WITHOUT_REPLACEMENT"
-          : result.path === "sonar-project.properties"
-            ? "HFS_SONAR_CONFIG"
-            : "HFS_MANAGED_FILE_DRIFT";
-    findings.push({
-      code,
-      level: "error",
-      path: result.path,
-      message: `${result.path} is not its full-edition render (expected sha256 ${result.expectedHash.slice(0, 12)}${result.actualHash ? `, found ${result.actualHash.slice(0, 12)}` : ""}); run starci app upgrade --edition full`,
-    });
-  }
-  return findings;
-}
-
-const machineFinding = (side, item) => ({
-  code: item.ruleId,
-  level: "error",
-  ...(item.path ? { path: `${side}/${item.path}` } : {}),
-  ...(item.line ? { line: item.line, column: item.column } : {}),
-  source: "machine",
-  message: `${item.path ? `${side}/${item.path}${item.line ? `:${item.line}` : ""}: ` : ""}${item.message}`,
-});
-
-/**
- * Runs the normal check when the requested edition matches hfs.json. The sole override is lite -> full; every other mismatch is
- * a usage refusal. `normal` is the CLI's ordinary check closure, which keeps the existing full and lite paths unchanged.
- */
-export async function checkEdition({
-  repoRoot,
-  edition,
-  normal,
-  presets,
-  prettier,
-  manifest = loadSlotManifest(),
-}) {
+/** Runs the normal check when the requested edition is the declared one; any other edition is a usage refusal. `normal` is the CLI's ordinary check closure. */
+export async function checkEdition({ repoRoot, edition, normal, manifest = loadSlotManifest() }) {
   if (edition === undefined) return normal();
   if (!["full", "lite"].includes(edition))
-    throw new UpgradeError(
-      "HFS_EDITION_INVALID",
-      `--edition is ${JSON.stringify(edition)}; expected full or lite`,
-    );
-  const declaration = loadHfs(repoRoot, manifest);
-  const actual = declaration.edition ?? "full";
-  if (edition === actual) return normal();
-  if (!(actual === "lite" && edition === "full"))
-    throw new UpgradeError(
-      "HFS_EDITION_INVALID",
-      `hfs.json edition is ${actual}; check may override only an edition lite app to full`,
-    );
-
-  const full = fullEditionDeclaration(declaration, manifest);
-  const tracked = trackedFiles(repoRoot);
-  // A lite app scaffolded before the 2026-10-12 ruling has no Jest preset installed. The upgrade model carries the preset's public sync inputs
-  // specifically so both the dry full-edition view and the upgrade plan render the same targets before dependencies are added.
-  const resolvedPresets = presets ?? UPGRADE_PRESETS;
-  const managed = renderTargets(full, resolvedPresets, { manifest, source: { ...appSource(repoRoot), stack: readDeclaredStack(repoRoot) } });
-  const extra = [
-    ...fullManagedFindings(repoRoot, managed),
-    ...(await checkDatabase({ repoRoot, files: tracked })),
-    ...(await formatFindings({ repoRoot, files: tracked, prettier })),
-  ];
-  const runs = [];
-  for (const side of ["be", "fe"]) {
-    const report = checkArchitecture({
-      repositoryRoot: path.join(repoRoot, side),
-      hfs: openHfs({ manifest, declaration: full, side }),
-      surface: "check",
-    });
-    runs.push({
-      side,
-      status: "ran",
-      files: report.files,
-      kinds: report.kinds,
-    });
-    extra.push(
-      ...report.errors.map((item) => machineFinding(side, item)),
-      ...report.violations.map((item) => machineFinding(side, item)),
-    );
-  }
-  const result = checkRepo({
-    repoRoot,
-    declaration: full,
-    files: tracked,
-    extraFindings: extra,
-    manifest,
-    surface: "check",
-    tree: true,
-  });
-  return {
-    ...result,
-    machine: {
-      status: "ran",
-      files: runs.reduce((sum, run) => sum + run.files, 0),
-      kinds: [...new Set(runs.flatMap((run) => run.kinds))],
-      sides: runs,
-    },
-    editionOverride: { declared: actual, judged: edition },
-  };
+    throw new UpgradeError("HFS_EDITION_INVALID", `--edition is ${JSON.stringify(edition)}; expected full or lite`);
+  const actual = loadHfs(repoRoot, manifest).edition ?? "full";
+  if (edition !== actual)
+    throw new UpgradeError("HFS_EDITION_INVALID", `hfs.json edition is ${actual}; editions are fixed at scaffold, so check judges only the declared edition`);
+  return normal();
 }

package/upgrade/file-state.mjs

@@ -1,21 +1,6 @@
-// Authored-file preservation, snapshots and rollback for an additive edition upgrade.
+// Snapshots and rollback for the additive completion of a full app.
 import fs from "node:fs";
 import path from "node:path";
-import { dockerfilePath } from "../runtime/scripts/hfs/rules/docker.mjs";
-
-/** App-owned additions are preserved; only declared regular optional front-end images receive that treatment. */
-export function authoredAdditionReasons(declaration, source) {
-  const reasons = new Map([[
-    ".starcistacks/application-stacks.yaml",
-    "The app already declares its stacks; the declaration stays as the app wrote it.",
-  ]]);
-  for (const app of declaration.sides.fe.apps) {
-    const file = dockerfilePath("fe", app.name);
-    if (source.hasImage(file)) reasons.set(file,
-      "The lite app already authors this optional front-end image; its Dockerfile stays as the app wrote it.");
-  }
-  return reasons;
-}
 
 export function remember(snapshot, target) {
   if (snapshot.has(target)) return;