genesis-compiler 1.2.6 → 1.2.7

package/src/index/stack-catalog.js

@@ -1,6 +1,6 @@
+import { createRequire } from 'node:module';
 import { readdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 
 import { GenesisError } from './errors.js';
 import {
@@ -8,54 +8,138 @@ import {
   parseStackPieceSource,
 } from './stack-piece.js';
 
-const catalogRoot = fileURLToPath(new URL('../../stacks/pieces/', import.meta.url));
-function builtinStackPiecePath(id) {
-  return path.join(catalogRoot, `${id}.md`);
+const require = createRequire(import.meta.url);
+const PACKAGE_NAME = /^(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+$/u;
+
+export function normalizeStackPackageName(value) {
+  const name = String(value ?? '').trim();
+  if (!PACKAGE_NAME.test(name)) {
+    throw new GenesisError(
+      'STACK_PACKAGE_INVALID',
+      'Stack package names must be ordinary npm package names.',
+      { package: value },
+    );
+  }
+  return name;
+}
+
+async function packageDirectory(packageName, projectRoot) {
+  const roots = [
+    ...(projectRoot ? createRequire(path.join(projectRoot, 'package.json')).resolve.paths(packageName) || [] : []),
+    ...(require.resolve.paths(packageName) || []),
+  ];
+  for (const modulesRoot of [...new Set(roots)]) {
+    const manifest = path.join(modulesRoot, packageName, 'package.json');
+    try {
+      const value = JSON.parse(await readFile(manifest, 'utf8'));
+      if (value?.name === packageName) return { directory: path.dirname(manifest), manifest: value };
+    } catch (error) {
+      if (!['ENOENT', 'ENOTDIR'].includes(error?.code)) {
+        throw new GenesisError(
+          'STACK_PACKAGE_INVALID',
+          `Cannot read Stack package ${packageName}: ${error.message}.`,
+          { package: packageName },
+        );
+      }
+    }
+  }
+  throw new GenesisError(
+    'STACK_PACKAGE_UNAVAILABLE',
+    `Selected Stack package is unavailable: ${packageName}. Install it beside Genesis or in the project.`,
+    { package: packageName },
+  );
 }
 
-export async function readBuiltinStackCatalog() {
+async function readPieceDirectory(
+  directory,
+  sourcePrefix,
+  stackPackage = null,
+  stackPackageRoot = null,
+) {
   let entries;
   try {
-    entries = await readdir(catalogRoot, { withFileTypes: true });
+    entries = await readdir(directory, { withFileTypes: true });
   } catch (error) {
-    if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') {
+    if (['ENOENT', 'ENOTDIR'].includes(error?.code)) {
       throw new GenesisError(
         'STACK_CATALOG_INVALID',
-        'The installed Genesis package is missing its built-in stack catalog.',
-        { catalogRoot },
+        `Stack catalog is missing its pieces directory: ${sourcePrefix}.`,
+        { directory, package: stackPackage },
       );
     }
     throw error;
   }
-
   const files = entries
     .filter((entry) => entry.isFile() && entry.name.endsWith('.md'))
     .map((entry) => entry.name)
     .sort();
-  const pieces = await Promise.all(files.map(async (file) => {
+  if (files.length === 0) {
+    throw new GenesisError(
+      'STACK_CATALOG_INVALID',
+      `Stack catalog contains no pieces: ${sourcePrefix}.`,
+      { directory, package: stackPackage },
+    );
+  }
+  return Promise.all(files.map(async (file) => {
     const id = normalizeStackPieceId(file.slice(0, -3));
-    const source = await readFile(builtinStackPiecePath(id), 'utf8');
-    return parseStackPieceSource(source, {
-      expectedId: id,
-      path: `builtin:${id}`,
-    });
+    const source = await readFile(path.join(directory, file), 'utf8');
+    const piece = parseStackPieceSource(source, { expectedId: id, path: `${sourcePrefix}:${id}` });
+    return {
+      ...piece,
+      skill: piece.skill === null ? null : { ...piece.skill, resolveFrom: stackPackageRoot },
+      stackPackage,
+    };
   }));
+}
+
+async function readExternalStackPieces(packageName, projectRoot) {
+  const resolved = await packageDirectory(packageName, projectRoot);
+  const relative = resolved.manifest?.genesis?.stackPieces;
+  if (
+    typeof relative !== 'string'
+    || !relative
+    || relative.includes('\\')
+    || path.isAbsolute(relative)
+    || relative.split('/').some((part) => !part || ['.', '..'].includes(part))
+  ) {
+    throw new GenesisError(
+      'STACK_PACKAGE_INVALID',
+      `Stack package ${packageName} must declare one safe genesis.stackPieces directory.`,
+      { package: packageName },
+    );
+  }
+  return readPieceDirectory(
+    path.join(resolved.directory, relative),
+    `npm:${packageName}`,
+    packageName,
+    resolved.directory,
+  );
+}
+
+export async function readStackCatalog({ projectRoot, stackPackages = [] } = {}) {
   const catalog = new Map();
-  for (const piece of pieces) {
-    if (catalog.has(piece.id)) {
-      throw new GenesisError(
-        'STACK_CATALOG_INVALID',
-        `The built-in stack catalog contains duplicate piece ${piece.id}.`,
-        { piece: piece.id },
-      );
+  const packages = [...new Set(stackPackages.map(normalizeStackPackageName))].sort();
+  for (const packageName of packages) {
+    for (const piece of await readExternalStackPieces(packageName, projectRoot)) {
+      const previous = catalog.get(piece.id);
+      if (previous) {
+        throw new GenesisError(
+          'STACK_CATALOG_COLLISION',
+          `Stack package ${packageName} collides with installed piece ${piece.id}.`,
+          {
+            piece: piece.id,
+            packages: [previous.stackPackage || 'genesis-compiler', packageName],
+          },
+        );
+      }
+      catalog.set(piece.id, piece);
     }
-    catalog.set(piece.id, piece);
   }
   return catalog;
 }
 
-export async function listBuiltinStackPieces() {
-  return [...(await readBuiltinStackCatalog()).values()]
+export async function listStackCatalogPieces(options = {}) {
+  return [...(await readStackCatalog(options)).values()]
     .sort((left, right) => left.id.localeCompare(right.id))
     .map((piece) => ({
       id: piece.id,
@@ -71,6 +155,7 @@ export async function listBuiltinStackPieces() {
       launchTargets: piece.launchTargets.map(({ id }) => id),
       workspaceSetup: piece.workspaceSetupSteps,
       skill: piece.skill === null ? null : piece.skill.path,
+      stackPackage: piece.stackPackage,
       resources: piece.resources.map(({ id }) => id),
     }));
 }

package/src/index/stack.js

@@ -3,7 +3,10 @@ import path from 'node:path';
 
 import { syncProjectSkills } from './agent-skills.js';
 import { GenesisError } from './errors.js';
-import { readBuiltinStackCatalog } from './stack-catalog.js';
+import {
+  normalizeStackPackageName,
+  readStackCatalog,
+} from './stack-catalog.js';
 import { parseStackCommandLines } from './stack-command.js';
 import { composeStackCityPresentation } from './stack-city-presentation.js';
 import { composeStackDeployment, parseStackDeploymentLines } from './stack-deployment.js';
@@ -31,8 +34,10 @@ import { STACK_PATH } from './paths.js';
 import { sha256, stableJson, writeFileAtomic } from './utils.js';
 
 const COMPONENT_LINE = /^- `([a-z0-9]+(?:-[a-z0-9]+)*)`$/u;
+const STACK_PACKAGE_LINE = /^- `((?:@[a-z0-9._-]+\/)?[a-z0-9._-]+)`$/u;
 export const EMPTY_STACK_SOURCE = '# Stack\n\n## Components\n';
 const STACK_SECTIONS = new Set([
+  'Stack packages',
   'Components',
   'Resources',
   'Environment defaults',
@@ -86,6 +91,27 @@ function componentIds(sections) {
   return ids;
 }
 
+function stackPackageNames(sections) {
+  const lines = (sections.get('Stack packages') || []).filter((line) => line.trim());
+  const names = lines.map((line) => {
+    const match = line.trim().match(STACK_PACKAGE_LINE);
+    if (!match) {
+      throw new GenesisError(
+        'STACK_INVALID',
+        'Each Stack package must be exactly one bullet containing its backticked npm package name.',
+        { path: STACK_PATH, observed: line },
+      );
+    }
+    return normalizeStackPackageName(match[1]);
+  });
+  if (new Set(names).size !== names.length) {
+    throw new GenesisError('STACK_INVALID', 'Stack contains a duplicate Stack package.', {
+      path: STACK_PATH,
+    });
+  }
+  return names;
+}
+
 function knownPieces(resolution) {
   if (resolution.unknown.length > 0) {
     throw new GenesisError(
@@ -112,10 +138,14 @@ function renderStack({
   environmentFileLines = null,
   launchLines = null,
   resourceLines = null,
+  stackPackages = [],
   workspaceSetupLines = null,
 }) {
   return [
     '# Stack',
+    ...(stackPackages.length > 0
+      ? ['', '## Stack packages', ...stackPackages.map((name) => `- \`${name}\``)]
+      : []),
     '',
     '## Components',
     ...componentIdsValue.map((id) => `- \`${id}\``),
@@ -140,7 +170,7 @@ function renderStack({
   ].join('\n');
 }
 
-export async function addStackPieces({ pieces, projectRoot }) {
+export async function addStackPieces({ pieces, projectRoot, stackPackages = [] }) {
   if (!Array.isArray(pieces) || pieces.length === 0) {
     throw new GenesisError('STACK_PIECE_REQUIRED', 'genesis stack add requires at least one component.');
   }
@@ -158,11 +188,21 @@ export async function addStackPieces({ pieces, projectRoot }) {
   }
   const sections = parseSections(source);
   const existing = componentIds(sections);
-  const catalog = await readBuiltinStackCatalog();
-  const selected = (await Promise.all(
+  const declaredPackages = stackPackageNames(sections);
+  const availablePackages = [...new Set([
+    ...declaredPackages,
+    ...stackPackages.map(normalizeStackPackageName),
+  ])].sort();
+  const catalog = await readStackCatalog({ projectRoot, stackPackages: availablePackages });
+  const selectedPieces = await Promise.all(
     knownPieces(resolveStackPieces({ catalog, existing, requested }))
       .map((piece) => customizePiece(projectRoot, piece)),
-  )).map(({ id }) => id);
+  );
+  const selected = selectedPieces.map(({ id }) => id);
+  const selectedPackages = [...new Set([
+    ...declaredPackages,
+    ...selectedPieces.map(({ stackPackage }) => stackPackage).filter(Boolean),
+  ])].sort();
   const commandLines = parseStackCommandLines(sections.get('Commands') || [], { path: STACK_PATH })
     .map(({ label, argv }) => `- Verify \`${label}\`: ${argv.map((value) => `\`${value}\``).join(' ')}`);
   const resourceLines = sections.has('Resources') ? sections.get('Resources') : null;
@@ -203,11 +243,15 @@ export async function addStackPieces({ pieces, projectRoot }) {
     environmentFileLines,
     launchLines,
     resourceLines,
+    stackPackages: selectedPackages,
     workspaceSetupLines,
   });
   const stackChanged = rendered !== source;
   if (stackChanged) await writeFileAtomic(location, rendered);
-  const skills = await syncProjectSkills({ projectRoot, stack: await readStack(projectRoot) });
+  const skills = await syncProjectSkills({
+    projectRoot,
+    stack: await readStack(projectRoot, { stackPackages: availablePackages }),
+  });
   const changedFiles = [
     ...(stackChanged ? [STACK_PATH] : []),
     ...skills.changedFiles,
@@ -262,7 +306,7 @@ async function customizePiece(projectRoot, piece) {
   }));
 }
 
-export async function readStack(projectRoot) {
+export async function readStack(projectRoot, { stackPackages = [] } = {}) {
   const location = path.join(projectRoot, STACK_PATH);
   let source;
   try {
@@ -277,7 +321,12 @@ export async function readStack(projectRoot) {
     throw error;
   }
   const sections = parseSections(source);
-  const catalog = await readBuiltinStackCatalog();
+  const declaredPackages = stackPackageNames(sections);
+  const availablePackages = [...new Set([
+    ...declaredPackages,
+    ...stackPackages.map(normalizeStackPackageName),
+  ])].sort();
+  const catalog = await readStackCatalog({ projectRoot, stackPackages: availablePackages });
   const components = await Promise.all(knownPieces(resolveStackPieces({
     catalog,
     requested: componentIds(sections),
@@ -325,6 +374,7 @@ export async function readStack(projectRoot) {
   return {
     path: STACK_PATH,
     identityHash: sha256(stableJson({
+      stackPackages: declaredPackages,
       components: components.map(({ id }) => id),
       cityExclusions: cityPresentation.exclusions,
       cityRegions: cityPresentation.regions,
@@ -337,6 +387,7 @@ export async function readStack(projectRoot) {
       workspaceSetup,
     })),
     components,
+    stackPackages: declaredPackages,
     cityExclusions: cityPresentation.exclusions,
     cityRegions: cityPresentation.regions,
     commands,
@@ -354,6 +405,7 @@ export async function readStack(projectRoot) {
 
 export function stackPromptContext(stack) {
   return {
+    stackPackages: stack.stackPackages,
     components: stack.components.map((piece) => ({
       id: piece.id,
       description: piece.description,

package/src/index/verification.js

@@ -20,10 +20,11 @@ export async function verifyProject({
   processRunner = runProcess,
   projectRoot,
   signal,
+  stackPackages = [],
   timeoutMs = DEFAULT_FINITE_COMMAND_TIMEOUT_MS,
 } = {}) {
   const root = (await gitContext(projectRoot)).repositoryRoot;
-  const stack = await readStack(root);
+  const stack = await readStack(root, { stackPackages });
   const workspaceSetup = await inspectWorkspaceSetupForStack({ projectRoot: root, stack });
   if (workspaceSetup.status === 'blocked') {
     return {

package/src/index/workspace-setup.js

@@ -74,9 +74,10 @@ export async function inspectWorkspaceSetupForStack({ projectRoot: root, stack }
 /** Read the Stack's workspace preparation recipe without executing it. */
 export async function inspectProjectWorkspaceSetup({
   projectRoot,
+  stackPackages = [],
 } = {}) {
   const root = (await gitContext(projectRoot)).repositoryRoot;
-  const stack = await readStack(root);
+  const stack = await readStack(root, { stackPackages });
   return inspectWorkspaceSetupForStack({ projectRoot: root, stack });
 }
 
@@ -87,10 +88,11 @@ export async function prepareProjectWorkspace({
   processRunner = runProcess,
   projectRoot,
   signal,
+  stackPackages = [],
   timeoutMs = DEFAULT_FINITE_COMMAND_TIMEOUT_MS,
 } = {}) {
   const root = (await gitContext(projectRoot)).repositoryRoot;
-  const stack = await readStack(root);
+  const stack = await readStack(root, { stackPackages });
   const setup = await inspectWorkspaceSetupForStack({ projectRoot: root, stack });
   if (setup.status !== 'ready') {
     const summary = setup.diagnostics.map(({ message }) => message).join(' ')

package/src/index.js

@@ -9,7 +9,7 @@ import { installCodexPlugin } from './index/codex-plugin.js';
 import { inspectProjectEnvironment } from './index/environment-files.js';
 import { inspectProjectDeployment } from './index/deployment.js';
 import { inspectProjectLaunch } from './index/launch.js';
-import { listBuiltinStackPieces } from './index/stack-catalog.js';
+import { listStackCatalogPieces } from './index/stack-catalog.js';
 import { addStackPieces } from './index/stack.js';
 import { verifyProject } from './index/verification.js';
 import {
@@ -31,21 +31,26 @@ function withIndexResult(result, index) {
   };
 }
 
-async function initializeWithIndex(projectRoot) {
-  const initialized = await initializeProject({ projectRoot });
-  const index = await buildProjectIndex({ projectRoot });
+async function initializeWithIndex(projectRoot, stackPackages = []) {
+  const initialized = await initializeProject({ projectRoot, stackPackages });
+  const index = await buildProjectIndex({ projectRoot, stackPackages });
   return withIndexResult(initialized, index);
 }
 
-export function initialize({ projectRoot = process.cwd() } = {}) {
-  return initializeWithIndex(projectRoot);
+export function initialize({ projectRoot = process.cwd(), stackPackages = [] } = {}) {
+  return initializeWithIndex(projectRoot, stackPackages);
 }
 
-export async function adoptProject({ projectRoot = process.cwd(), request = '' } = {}) {
-  const initialized = await initializeWithIndex(projectRoot);
+export async function adoptProject({
+  projectRoot = process.cwd(),
+  request = '',
+  stackPackages = [],
+} = {}) {
+  const initialized = await initializeWithIndex(projectRoot, stackPackages);
   const description = await generateProjectPrompt({
     projectRoot,
     request,
+    stackPackages,
     task: 'adopt',
   });
   return {
@@ -64,15 +69,15 @@ export function installCodex({ environment = process.env } = {}) {
   return installCodexPlugin({ environment });
 }
 
-export async function addStack({ pieces, projectRoot = process.cwd() } = {}) {
+export async function addStack({ pieces, projectRoot = process.cwd(), stackPackages = [] } = {}) {
   const root = path.resolve(projectRoot);
-  const selected = await addStackPieces({ pieces, projectRoot: root });
-  const index = await buildProjectIndex({ projectRoot: root });
+  const selected = await addStackPieces({ pieces, projectRoot: root, stackPackages });
+  const index = await buildProjectIndex({ projectRoot: root, stackPackages });
   return withIndexResult(selected, index);
 }
 
-export function listStackPieces() {
-  return listBuiltinStackPieces();
+export function listStackPieces(options = {}) {
+  return listStackCatalogPieces(options);
 }
 
 export function inspectLaunch(options) {
@@ -99,12 +104,17 @@ export function generatePrompt(options) {
   return generateProjectPrompt(options);
 }
 
-export function getContext({ paths, projectRoot = process.cwd() } = {}) {
-  return contextForProjectPaths({ paths, projectRoot });
+export function getContext({ paths, projectRoot = process.cwd(), stackPackages = [] } = {}) {
+  return contextForProjectPaths({ paths, projectRoot, stackPackages });
 }
 
-export function indexCodebase({ projectRoot = process.cwd(), queries = [], write = true } = {}) {
-  return buildProjectIndex({ projectRoot, queries, write });
+export function indexCodebase({
+  projectRoot = process.cwd(),
+  queries = [],
+  stackPackages = [],
+  write = true,
+} = {}) {
+  return buildProjectIndex({ projectRoot, queries, stackPackages, write });
 }
 
 export function verify(options) {

package/stacks/pieces/cpp.md

@@ -1,34 +0,0 @@
-# Stack piece: cpp
-
-## Description
-
-C and C++ translation-unit, header, callable, ownership, build, and test conventions.
-
-## Requires
-
-- Nothing.
-
-## Indexers
-
-- `cpp`
-
-## Adoption
-
-- Identify the actual build system and presets, compiler and language level,
-  package/runtime dependencies, generated-source steps, and supported build
-  configurations without substituting a preferred CMake or Meson layout.
-- Record exact configure/build/test commands and the executable argv, workdir,
-  host/port handling, HTTP readiness predicate, and signal/shutdown contract for
-  every web-service target.
-- Preserve public headers, ABI and platform assumptions. Treat databases,
-  queues, TLS material, and external service credentials as explicit Resources,
-  not implicit properties of the native binary.
-
-## Deslop
-
-- Preserve public header boundaries, ABI expectations, build configuration,
-  const correctness, lifetime ownership, and the codebase's C or C++ level.
-- Keep file-local helpers internal and near their callers. Consolidate repeated
-  allocation, cleanup, conversion, and error paths with explicit ownership.
-- Remove unused wrappers, speculative templates, duplicate overload plumbing,
-  and abstractions that obscure control flow without protecting a real boundary.

package/stacks/pieces/csharp.md

@@ -1,22 +0,0 @@
-# Stack piece: csharp
-
-## Description
-
-C# namespace, public type, dependency, lifecycle, and test conventions.
-
-## Requires
-
-- Nothing.
-
-## Indexers
-
-- `csharp`
-
-## Deslop
-
-- Preserve established namespaces, public contracts, dependency injection,
-  async ownership, disposal, nullable annotations, and project conventions.
-- Keep private helpers with their owning type. Consolidate repeated mapping,
-  validation, and error translation at an existing application boundary.
-- Remove redundant service wrappers, interfaces with no useful substitution
-  boundary, and extension methods that only rename direct framework behavior.

package/stacks/pieces/go.md

@@ -1,22 +0,0 @@
-# Stack piece: go
-
-## Description
-
-Go package, exported callable, interface, concurrency, resource, and test conventions.
-
-## Requires
-
-- Nothing.
-
-## Indexers
-
-- `go`
-
-## Deslop
-
-- Preserve package ownership, exported APIs, context propagation, error
-  wrapping, goroutine lifetime, and standard Go tooling conventions.
-- Keep unexported helpers close to their caller. Consolidate repeated setup,
-  validation, cleanup, and conversion only at a clear package boundary.
-- Remove unnecessary interfaces, constructor wrappers, channels, and generic
-  helpers that make direct control flow harder to follow.

package/stacks/pieces/java.md

@@ -1,22 +0,0 @@
-# Stack piece: java
-
-## Description
-
-Java package, public type, dependency, lifecycle, and test conventions.
-
-## Requires
-
-- Nothing.
-
-## Indexers
-
-- `java`
-
-## Deslop
-
-- Preserve established packages, public interfaces, dependency injection,
-  lifecycle ownership, checked-error policy, and build-tool conventions.
-- Keep private helpers with their owning class. Consolidate repeated mapping,
-  validation, and resource handling at an existing service or domain boundary.
-- Remove empty facades, single-implementation abstractions, and builder or DTO
-  layers that do not protect a real public or compatibility boundary.

package/stacks/pieces/jskit-mysql.md

@@ -1,56 +0,0 @@
-# Stack piece: jskit-mysql
-
-## Description
-
-JSKIT MySQL runtime, live-schema CRUD generation, and persistence conventions.
-
-## Requires
-
-- `jskit`
-- `mysql`
-
-## Conflicts
-
-- `jskit-postgresql`
-
-## Environment defaults
-
-- Default `DB_CLIENT`: `mysql2`
-
-## Resources
-
-```json genesis-resource
-{
-  "id": "database",
-  "kind": "mysql",
-  "environmentAlternatives": [
-    {
-      "required": ["DATABASE_URL"]
-    },
-    {
-      "required": ["DB_HOST", "DB_PORT", "DB_NAME", "DB_USER", "DB_PASSWORD"],
-      "allowEmpty": ["DB_PASSWORD"]
-    }
-  ]
-}
-```
-
-## Adoption
-
-- Confirm that the application's effective MySQL environment alternatives and
-  driver match this Resource declaration; add a project Resource contract when
-  the existing application legitimately differs.
-- Verify from source that the database preparation path discovers every
-  package-owned migration, preserves the existing ledger, orders cross-package
-  constraints safely, and invokes an app-owned idempotent seed. Do not execute
-  it during adoption.
-
-## Deslop
-
-- Use the installed JSKIT database runtime and generated resource/repository
-  seams; do not add a second client, connection factory, CRUD transport, or
-  file-persistence fallback.
-- Keep environment normalization, transactions, row mapping, and database
-  error translation at one established persistence boundary.
-- Never compete with or rewrite a generator-owned baseline migration. Preserve
-  retained migration history and data semantics.

package/stacks/pieces/jskit-postgresql.md

@@ -1,56 +0,0 @@
-# Stack piece: jskit-postgresql
-
-## Description
-
-JSKIT PostgreSQL runtime, live-schema CRUD generation, and persistence conventions.
-
-## Requires
-
-- `jskit`
-- `postgresql`
-
-## Conflicts
-
-- `jskit-mysql`
-
-## Environment defaults
-
-- Default `DB_CLIENT`: `pg`
-
-## Resources
-
-```json genesis-resource
-{
-  "id": "database",
-  "kind": "postgresql",
-  "environmentAlternatives": [
-    {
-      "required": ["DATABASE_URL"]
-    },
-    {
-      "required": ["DB_HOST", "DB_PORT", "DB_NAME", "DB_USER", "DB_PASSWORD"],
-      "allowEmpty": ["DB_PASSWORD"]
-    }
-  ]
-}
-```
-
-## Adoption
-
-- Confirm that the application's effective PostgreSQL environment alternatives
-  and driver match this Resource declaration; add a project Resource contract
-  when the existing application legitimately differs.
-- Verify from source that the database preparation path discovers every
-  package-owned migration, preserves the existing ledger, orders cross-package
-  constraints safely, and invokes an app-owned idempotent seed. Do not execute
-  it during adoption.
-
-## Deslop
-
-- Use the installed JSKIT database runtime and generated resource/repository
-  seams; do not add a second client, connection factory, CRUD transport, or
-  file-persistence fallback.
-- Keep environment normalization, transactions, row mapping, and database
-  error translation at one established persistence boundary.
-- Never compete with or rewrite a generator-owned baseline migration. Preserve
-  retained migration history and data semantics.