@futdevpro/nts-dynamo 1.15.141 → 1.15.144

package/src/_modules/artifact-compiler/_enums/artifact-compile-stage.type-enum.ts

@@ -0,0 +1,8 @@
+/** Content-free stage identifiers for artifact compiler findings. */
+export enum DyNTS_ArtifactCompileStage_Type {
+  request = 'request',
+  sourcePolicy = 'source-policy',
+  resolve = 'resolve',
+  compile = 'compile',
+  output = 'output',
+}

package/src/_modules/artifact-compiler/_enums/artifact-retry-class.type-enum.ts

@@ -0,0 +1,6 @@
+/** Stable remediation classification for artifact compiler findings. */
+export enum DyNTS_ArtifactRetryClass_Type {
+  agentFixable = 'agent-fixable',
+  deterministicToolFixable = 'deterministic-tool-fixable',
+  terminal = 'terminal',
+}

package/src/_modules/artifact-compiler/_models/artifact-compile.interface.ts

@@ -0,0 +1,35 @@
+import { DyNTS_ArtifactCompileOutcome_Type } from '../_enums/artifact-compile-outcome.type-enum';
+import { DyNTS_ArtifactCompileStage_Type } from '../_enums/artifact-compile-stage.type-enum';
+import { DyNTS_ArtifactRetryClass_Type } from '../_enums/artifact-retry-class.type-enum';
+
+/** Versioned input for the deterministic TypeScript-to-browser bundle compiler. */
+export interface DyNTS_ArtifactCompileRequest_Interface {
+  contractVersion: 'dynts-artifact-compiler/1';
+  source: string;
+  sourceFileName: string;
+  resolveDirectory: string;
+  allowedPackages: string[];
+  maxSourceBytes: number;
+  maxOutputBytes: number;
+}
+
+/** Content-free compiler finding. Source text and dependency paths are deliberately excluded. */
+export interface DyNTS_ArtifactCompileFinding_Interface {
+  code: string;
+  stage: DyNTS_ArtifactCompileStage_Type;
+  line: number | null;
+  column: number | null;
+  retryClass: DyNTS_ArtifactRetryClass_Type;
+}
+
+/** One self-contained JavaScript output or a fail-closed, content-free rejection. */
+export interface DyNTS_ArtifactCompileResult_Interface {
+  contractVersion: 'dynts-artifact-compiler/1';
+  outcome: DyNTS_ArtifactCompileOutcome_Type;
+  code: string;
+  sourceChecksum: string;
+  bundleChecksum: string;
+  outputBytes: number;
+  bundleSource: string | null;
+  findings: DyNTS_ArtifactCompileFinding_Interface[];
+}

package/src/_modules/artifact-compiler/artifact-compiler.control-service.spec.ts

@@ -0,0 +1,151 @@
+import path from 'node:path';
+
+import { DyNTS_ArtifactCompileOutcome_Type } from './_enums/artifact-compile-outcome.type-enum';
+import {
+  DyNTS_ArtifactCompileRequest_Interface,
+  DyNTS_ArtifactCompileResult_Interface
+} from './_models/artifact-compile.interface';
+import { DyNTS_ArtifactCompiler_ControlService } from './artifact-compiler.control-service';
+
+describe('| DyNTS_ArtifactCompiler_ControlService', (): void => {
+  const compiler_CS: DyNTS_ArtifactCompiler_ControlService = new DyNTS_ArtifactCompiler_ControlService();
+
+  it('| emits one deterministic self-contained classic-worker bundle without filesystem output', async (
+  ): Promise<void> => {
+    const request: DyNTS_ArtifactCompileRequest_Interface = buildRequest(workerSource());
+    const first: DyNTS_ArtifactCompileResult_Interface = await compiler_CS.compile(request);
+    const second: DyNTS_ArtifactCompileResult_Interface = await compiler_CS.compile(request);
+
+    expect(first.outcome).toBe(DyNTS_ArtifactCompileOutcome_Type.compiled);
+    expect(first.bundleSource).toContain('self.onmessage');
+    expect(first.bundleSource).not.toContain('sourceMappingURL');
+    expect(first.bundleSource).not.toContain('dynts-in-memory-output');
+    expect(first.bundleChecksum).toMatch(/^[a-f0-9]{64}$/);
+    expect(first.outputBytes).toBeGreaterThan(0);
+    expect(second).toEqual(first);
+  });
+
+  it('| bundles an explicitly allowed installed package into the output', async (): Promise<void> => {
+    const source: string = `import Decimal from 'decimal.js';
+self.onmessage = (): void => {
+  const value: string = new Decimal(1).plus(2).toString();
+  const output: ArrayBuffer = new TextEncoder().encode(value).buffer;
+  self.postMessage({ type: 'complete', output: output }, [ output ]);
+};`;
+    const request: DyNTS_ArtifactCompileRequest_Interface = buildRequest(source);
+
+    request.allowedPackages = [ 'decimal.js' ];
+
+    const result: DyNTS_ArtifactCompileResult_Interface = await compiler_CS.compile(request);
+
+    expect(result.outcome).toBe(DyNTS_ArtifactCompileOutcome_Type.compiled);
+    expect(result.bundleSource).not.toContain('from\'decimal.js\'');
+    expect(result.outputBytes).toBeGreaterThan(1_000);
+  });
+
+  it('| rejects non-allowlisted direct imports without reflecting the source canary', async (): Promise<void> => {
+    const canary: string = 'SOURCE-CANARY-MUST-NOT-RETURN';
+    const request: DyNTS_ArtifactCompileRequest_Interface = buildRequest(
+      `import fs from 'node:fs';\nconst secret = '${canary}';\n${workerSource()}`
+    );
+    const result: DyNTS_ArtifactCompileResult_Interface = await compiler_CS.compile(request);
+
+    expect(result.outcome).toBe(DyNTS_ArtifactCompileOutcome_Type.rejected);
+    expect(result.findings[0].code).toBe('DYNTS|ARTIFACT_COMPILER|IMPORT_NOT_ALLOWED');
+    expect(JSON.stringify(result)).not.toContain(canary);
+    expect(result.bundleSource).toBeNull();
+  });
+
+  it('| rejects re-exports, import-equals, require and dynamic import syntax before bundling', async (
+  ): Promise<void> => {
+    const sources: string[] = [
+      'export { readFile } from \'node:fs\';',
+      'import fs = require(\'node:fs\');',
+      'const fs = require(\'node:fs\');',
+      'void import(\'decimal.js\');',
+    ];
+
+    for (const source of sources) {
+      const result: DyNTS_ArtifactCompileResult_Interface = await compiler_CS.compile(buildRequest(source));
+
+      expect(result.code).toBe('DYNTS|ARTIFACT_COMPILER|IMPORT_REJECTED');
+      expect(result.findings[0].stage).toBe('source-policy');
+    }
+  });
+
+  it('| returns content-free compile diagnostics for invalid TypeScript', async (): Promise<void> => {
+    const canary: string = 'INVALID-CANARY-MUST-NOT-RETURN';
+    const result: DyNTS_ArtifactCompileResult_Interface = await compiler_CS.compile(
+      buildRequest(`const ${canary}: = ;`)
+    );
+
+    expect(result.outcome).toBe(DyNTS_ArtifactCompileOutcome_Type.rejected);
+    expect(result.findings[0].code).toBe('DYNTS|ARTIFACT_COMPILER|COMPILE_ERROR');
+    expect(result.findings[0].line).toBe(1);
+    expect(JSON.stringify(result)).not.toContain(canary);
+  });
+
+  it('| rejects invalid contracts, duplicate packages and unsafe resolve inputs', async (): Promise<void> => {
+    const request: DyNTS_ArtifactCompileRequest_Interface = buildRequest(workerSource());
+
+    request.allowedPackages = [ 'decimal.js', 'decimal.js' ];
+    request.resolveDirectory = 'relative/path';
+    request.maxOutputBytes = 20_000_000;
+
+    const result: DyNTS_ArtifactCompileResult_Interface = await compiler_CS.compile(request);
+
+    expect(result.code).toBe('DYNTS|ARTIFACT_COMPILER|REQUEST_INVALID');
+    expect(result.findings[0].stage).toBe('request');
+  });
+
+  it('| bounds allowlist cardinality and request path lengths', async (): Promise<void> => {
+    const packageLimited: DyNTS_ArtifactCompileRequest_Interface = buildRequest(workerSource());
+    const pathLimited: DyNTS_ArtifactCompileRequest_Interface = buildRequest(workerSource());
+
+    packageLimited.allowedPackages = Array.from({ length: 65 }, (_value: unknown, index: number): string =>
+      `package-${index}`);
+    pathLimited.sourceFileName = `${'a'.repeat(128)}.ts`;
+
+    const packageResult: DyNTS_ArtifactCompileResult_Interface = await compiler_CS.compile(packageLimited);
+    const pathResult: DyNTS_ArtifactCompileResult_Interface = await compiler_CS.compile(pathLimited);
+
+    expect(packageResult.code).toBe('DYNTS|ARTIFACT_COMPILER|REQUEST_INVALID');
+    expect(pathResult.code).toBe('DYNTS|ARTIFACT_COMPILER|REQUEST_INVALID');
+  });
+
+  it('| enforces source and output byte budgets before returning bundle content', async (): Promise<void> => {
+    const sourceLimited: DyNTS_ArtifactCompileRequest_Interface = buildRequest(workerSource());
+    const outputLimited: DyNTS_ArtifactCompileRequest_Interface = buildRequest(workerSource());
+
+    sourceLimited.maxSourceBytes = 1;
+    outputLimited.maxOutputBytes = 1;
+
+    const sourceResult: DyNTS_ArtifactCompileResult_Interface = await compiler_CS.compile(sourceLimited);
+    const outputResult: DyNTS_ArtifactCompileResult_Interface = await compiler_CS.compile(outputLimited);
+
+    expect(sourceResult.code).toBe('DYNTS|ARTIFACT_COMPILER|REQUEST_INVALID');
+    expect(outputResult.code).toBe('DYNTS|ARTIFACT_COMPILER|OUTPUT_LIMIT');
+    expect(outputResult.bundleSource).toBeNull();
+  });
+
+  /** Builds a valid request resolved against this package's installed dependencies. */
+  function buildRequest(source: string): DyNTS_ArtifactCompileRequest_Interface {
+    return {
+      contractVersion: 'dynts-artifact-compiler/1',
+      source: source,
+      sourceFileName: 'candidate.ts',
+      resolveDirectory: path.resolve(process.cwd()),
+      allowedPackages: [],
+      maxSourceBytes: 512_000,
+      maxOutputBytes: 8_000_000,
+    };
+  }
+
+  /** Returns a minimal classic Worker contract. */
+  function workerSource(): string {
+    return `self.onmessage = (event: MessageEvent<{ input: ArrayBuffer }>): void => {
+  const output: ArrayBuffer = event.data.input;
+  self.postMessage({ type: 'complete', output: output }, [ output ]);
+};`;
+  }
+});

package/src/_modules/artifact-compiler/artifact-compiler.control-service.ts

@@ -0,0 +1,356 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+
+import {
+  BuildFailure,
+  BuildOptions,
+  BuildResult,
+  Message,
+  OnLoadResult,
+  OnResolveArgs,
+  OnResolveResult,
+  OutputFile,
+  Plugin,
+  PluginBuild,
+  build
+} from 'esbuild';
+import ts from 'typescript';
+
+import { DyNTS_ArtifactCompileOutcome_Type } from './_enums/artifact-compile-outcome.type-enum';
+import { DyNTS_ArtifactCompileStage_Type } from './_enums/artifact-compile-stage.type-enum';
+import { DyNTS_ArtifactRetryClass_Type } from './_enums/artifact-retry-class.type-enum';
+import {
+  DyNTS_ArtifactCompileFinding_Interface,
+  DyNTS_ArtifactCompileRequest_Interface,
+  DyNTS_ArtifactCompileResult_Interface
+} from './_models/artifact-compile.interface';
+
+/**
+ * Deterministically bundles one in-memory TypeScript program for a classic browser Worker.
+ * This compiler is not a sandbox: consumers must validate source policy before compilation and execute the result
+ * inside a separately enforced runtime boundary.
+ */
+export class DyNTS_ArtifactCompiler_ControlService {
+  public static readonly contractVersion: 'dynts-artifact-compiler/1' = 'dynts-artifact-compiler/1';
+  private readonly absoluteMaxSourceBytes: number = 1_048_576;
+  private readonly absoluteMaxOutputBytes: number = 16_777_216;
+  private readonly absoluteMaxAllowedPackages: number = 64;
+  private readonly absoluteMaxPackageNameLength: number = 128;
+  private readonly absoluteMaxSourceFileNameLength: number = 128;
+  private readonly absoluteMaxResolveDirectoryLength: number = 1_024;
+  private readonly packageNamePattern: RegExp =
+    /^(?:@[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*|[a-z0-9][a-z0-9._-]*)$/;
+  private readonly sourceFileNamePattern: RegExp = /^[a-z0-9][a-z0-9._-]*\.ts$/;
+
+  /** Compiles without writing source, sourcemaps, metadata or output files to disk. */
+  public async compile(
+    request: DyNTS_ArtifactCompileRequest_Interface
+  ): Promise<DyNTS_ArtifactCompileResult_Interface> {
+    const sourceChecksum: string = this.checksum(typeof request?.source === 'string' ? request.source : '');
+    const requestFinding: DyNTS_ArtifactCompileFinding_Interface | null = this.validateRequest(request);
+
+    if (requestFinding) {
+      return this.rejected(sourceChecksum, 'DYNTS|ARTIFACT_COMPILER|REQUEST_INVALID', [ requestFinding ]);
+    }
+
+    const importFinding: DyNTS_ArtifactCompileFinding_Interface | null = this.validateDirectImports(request);
+
+    if (importFinding) {
+      return this.rejected(sourceChecksum, 'DYNTS|ARTIFACT_COMPILER|IMPORT_REJECTED', [ importFinding ]);
+    }
+
+    try {
+      const result: BuildResult = await build(this.buildOptions(request));
+      const outputFiles: OutputFile[] = result.outputFiles ?? [];
+
+      if (outputFiles.length !== 1 || !outputFiles[0].path.endsWith('.js')) {
+        return this.rejected(sourceChecksum, 'DYNTS|ARTIFACT_COMPILER|OUTPUT_INVALID', [{
+          code: 'DYNTS|ARTIFACT_COMPILER|OUTPUT_COUNT',
+          stage: DyNTS_ArtifactCompileStage_Type.output,
+          line: null,
+          column: null,
+          retryClass: DyNTS_ArtifactRetryClass_Type.deterministicToolFixable,
+        }]);
+      }
+
+      const bundleSource: string = outputFiles[0].text;
+      const outputBytes: number = Buffer.byteLength(bundleSource, 'utf8');
+
+      if (!outputBytes || outputBytes > request.maxOutputBytes) {
+        return this.rejected(sourceChecksum, 'DYNTS|ARTIFACT_COMPILER|OUTPUT_LIMIT', [{
+          code: 'DYNTS|ARTIFACT_COMPILER|OUTPUT_SIZE',
+          stage: DyNTS_ArtifactCompileStage_Type.output,
+          line: null,
+          column: null,
+          retryClass: DyNTS_ArtifactRetryClass_Type.agentFixable,
+        }]);
+      }
+
+      return {
+        contractVersion: DyNTS_ArtifactCompiler_ControlService.contractVersion,
+        outcome: DyNTS_ArtifactCompileOutcome_Type.compiled,
+        code: 'DYNTS|ARTIFACT_COMPILER|COMPILED',
+        sourceChecksum: sourceChecksum,
+        bundleChecksum: this.checksum(bundleSource),
+        outputBytes: outputBytes,
+        bundleSource: bundleSource,
+        findings: [],
+      };
+    } catch (error: unknown) {
+      return this.rejected(sourceChecksum, 'DYNTS|ARTIFACT_COMPILER|BUILD_FAILED', this.buildFindings(error));
+    }
+  }
+
+  private validateRequest(
+    request: DyNTS_ArtifactCompileRequest_Interface
+  ): DyNTS_ArtifactCompileFinding_Interface | null {
+    const sourceBytes: number = typeof request?.source === 'string'
+      ? Buffer.byteLength(request.source, 'utf8')
+      : 0;
+    const allowedPackages: string[] = Array.isArray(request?.allowedPackages) ? request.allowedPackages : [];
+    const uniquePackages: Set<string> = new Set<string>(allowedPackages);
+    const isPackageSetValid: boolean = allowedPackages.length <= this.absoluteMaxAllowedPackages
+      && uniquePackages.size === allowedPackages.length
+      && allowedPackages.every((packageName: string): boolean => packageName.length <= this.absoluteMaxPackageNameLength
+        && this.packageNamePattern.test(packageName));
+
+    if (
+      request?.contractVersion !== DyNTS_ArtifactCompiler_ControlService.contractVersion
+      || !sourceBytes
+      || !Number.isInteger(request.maxSourceBytes)
+      || request.maxSourceBytes < 1
+      || request.maxSourceBytes > this.absoluteMaxSourceBytes
+      || sourceBytes > request.maxSourceBytes
+      || !Number.isInteger(request.maxOutputBytes)
+      || request.maxOutputBytes < 1
+      || request.maxOutputBytes > this.absoluteMaxOutputBytes
+      || typeof request.sourceFileName !== 'string'
+      || request.sourceFileName.length > this.absoluteMaxSourceFileNameLength
+      || !this.sourceFileNamePattern.test(request.sourceFileName)
+      || typeof request.resolveDirectory !== 'string'
+      || request.resolveDirectory.length > this.absoluteMaxResolveDirectoryLength
+      || !path.isAbsolute(request.resolveDirectory)
+      || !isPackageSetValid
+    ) {
+      return {
+        code: 'DYNTS|ARTIFACT_COMPILER|REQUEST_CONTRACT',
+        stage: DyNTS_ArtifactCompileStage_Type.request,
+        line: null,
+        column: null,
+        retryClass: DyNTS_ArtifactRetryClass_Type.deterministicToolFixable,
+      };
+    }
+
+    return null;
+  }
+
+  private buildOptions(request: DyNTS_ArtifactCompileRequest_Interface): BuildOptions {
+    return {
+      absWorkingDir: request.resolveDirectory,
+      bundle: true,
+      charset: 'utf8',
+      conditions: [ 'browser', 'default' ],
+      entryPoints: [ 'dynts-entry:candidate' ],
+      format: 'iife',
+      legalComments: 'none',
+      logLevel: 'silent',
+      mainFields: [ 'browser', 'module', 'main' ],
+      metafile: false,
+      minify: true,
+      outdir: 'dynts-in-memory-output',
+      platform: 'browser',
+      plugins: [ this.allowlistedEntryPlugin(request) ],
+      sourcemap: false,
+      target: [ 'es2022' ],
+      treeShaking: true,
+      write: false,
+    };
+  }
+
+  /**
+   * Validates every syntactic import before esbuild can tree-shake it. The plugin below is a second resolution gate,
+   * but it cannot be the only policy boundary because unused imports need not reach package resolution.
+   */
+  private validateDirectImports(
+    request: DyNTS_ArtifactCompileRequest_Interface
+  ): DyNTS_ArtifactCompileFinding_Interface | null {
+    const sourceFile: ts.SourceFile = ts.createSourceFile(
+      request.sourceFileName,
+      request.source,
+      ts.ScriptTarget.ES2022,
+      true,
+      ts.ScriptKind.TS
+    );
+    const allowedPackages: ReadonlySet<string> = new Set<string>(request.allowedPackages);
+    let finding: DyNTS_ArtifactCompileFinding_Interface | null = null;
+
+    /** Traverses the parsed source once and stops at the first forbidden module load. */
+    const inspectNode: (node: ts.Node) => void = (node: ts.Node): void => {
+      if (finding) {
+        return;
+      }
+
+      const moduleName: string | null = this.moduleName(node);
+
+      if (moduleName !== null && !allowedPackages.has(this.packageRoot(moduleName))) {
+        finding = this.importFinding(sourceFile, node);
+
+        return;
+      }
+
+      if (this.isDynamicModuleLoad(node)) {
+        finding = this.importFinding(sourceFile, node);
+
+        return;
+      }
+
+      ts.forEachChild(node, inspectNode);
+    };
+
+    inspectNode(sourceFile);
+
+    return finding;
+  }
+
+  private moduleName(node: ts.Node): string | null {
+    if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier) {
+      return ts.isStringLiteral(node.moduleSpecifier) ? node.moduleSpecifier.text : '';
+    }
+
+    if (
+      ts.isImportEqualsDeclaration(node)
+      && ts.isExternalModuleReference(node.moduleReference)
+      && node.moduleReference.expression
+    ) {
+      return ts.isStringLiteral(node.moduleReference.expression) ? node.moduleReference.expression.text : '';
+    }
+
+    return null;
+  }
+
+  private isDynamicModuleLoad(node: ts.Node): boolean {
+    return ts.isCallExpression(node)
+      && (node.expression.kind === ts.SyntaxKind.ImportKeyword
+        || (ts.isIdentifier(node.expression) && node.expression.text === 'require'));
+  }
+
+  private importFinding(
+    sourceFile: ts.SourceFile,
+    node: ts.Node
+  ): DyNTS_ArtifactCompileFinding_Interface {
+    const location: ts.LineAndCharacter = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+
+    return {
+      code: 'DYNTS|ARTIFACT_COMPILER|IMPORT_NOT_ALLOWED',
+      stage: DyNTS_ArtifactCompileStage_Type.sourcePolicy,
+      line: location.line + 1,
+      column: location.character + 1,
+      retryClass: DyNTS_ArtifactRetryClass_Type.terminal,
+    };
+  }
+
+  private allowlistedEntryPlugin(request: DyNTS_ArtifactCompileRequest_Interface): Plugin {
+    const allowedPackages: ReadonlySet<string> = new Set<string>(request.allowedPackages);
+
+    return {
+      name: 'dynts-allowlisted-in-memory-entry',
+      setup: (pluginBuild: PluginBuild): void => {
+        pluginBuild.onResolve({ filter: /^dynts-entry:candidate$/ }, (): OnResolveResult => ({
+          path: 'candidate',
+          namespace: 'dynts-entry',
+        }));
+        pluginBuild.onLoad({ filter: /^candidate$/, namespace: 'dynts-entry' }, (): OnLoadResult => ({
+          contents: request.source,
+          loader: 'ts',
+          resolveDir: request.resolveDirectory,
+        }));
+        pluginBuild.onResolve({ filter: /.*/, namespace: 'dynts-entry' }, async (
+          args: OnResolveArgs
+        ): Promise<OnResolveResult> => {
+          if (!allowedPackages.has(this.packageRoot(args.path))) {
+            return {
+              errors: [{ text: 'DYNTS|ARTIFACT_COMPILER|IMPORT_NOT_ALLOWED' }],
+            };
+          }
+
+          return pluginBuild.resolve(args.path, {
+            importer: args.importer,
+            kind: args.kind,
+            namespace: 'file',
+            resolveDir: request.resolveDirectory,
+          });
+        });
+      },
+    };
+  }
+
+  private buildFindings(error: unknown): DyNTS_ArtifactCompileFinding_Interface[] {
+    if (!this.isBuildFailure(error)) {
+      return [ this.genericBuildFinding() ];
+    }
+
+    const findings: DyNTS_ArtifactCompileFinding_Interface[] = error.errors.map((message: Message):
+      DyNTS_ArtifactCompileFinding_Interface => ({
+      code: message.text === 'DYNTS|ARTIFACT_COMPILER|IMPORT_NOT_ALLOWED'
+        ? message.text
+        : 'DYNTS|ARTIFACT_COMPILER|COMPILE_ERROR',
+      stage: message.text === 'DYNTS|ARTIFACT_COMPILER|IMPORT_NOT_ALLOWED'
+        ? DyNTS_ArtifactCompileStage_Type.resolve
+        : DyNTS_ArtifactCompileStage_Type.compile,
+      line: message.location?.line ?? null,
+      column: message.location ? message.location.column + 1 : null,
+      retryClass: message.text === 'DYNTS|ARTIFACT_COMPILER|IMPORT_NOT_ALLOWED'
+        ? DyNTS_ArtifactRetryClass_Type.terminal
+        : DyNTS_ArtifactRetryClass_Type.agentFixable,
+    }));
+
+    return findings.length ? findings : [ this.genericBuildFinding() ];
+  }
+
+  private isBuildFailure(error: unknown): error is BuildFailure {
+    if (!error || typeof error !== 'object') {
+      return false;
+    }
+
+    return 'errors' in error && Array.isArray(error.errors);
+  }
+
+  private genericBuildFinding(): DyNTS_ArtifactCompileFinding_Interface {
+    return {
+      code: 'DYNTS|ARTIFACT_COMPILER|COMPILE_ERROR',
+      stage: DyNTS_ArtifactCompileStage_Type.compile,
+      line: null,
+      column: null,
+      retryClass: DyNTS_ArtifactRetryClass_Type.agentFixable,
+    };
+  }
+
+  private rejected(
+    sourceChecksum: string,
+    code: string,
+    findings: DyNTS_ArtifactCompileFinding_Interface[]
+  ): DyNTS_ArtifactCompileResult_Interface {
+    return {
+      contractVersion: DyNTS_ArtifactCompiler_ControlService.contractVersion,
+      outcome: DyNTS_ArtifactCompileOutcome_Type.rejected,
+      code: code,
+      sourceChecksum: sourceChecksum,
+      bundleChecksum: '',
+      outputBytes: 0,
+      bundleSource: null,
+      findings: findings,
+    };
+  }
+
+  private packageRoot(moduleName: string): string {
+    if (moduleName.startsWith('@')) {
+      return moduleName.split('/').slice(0, 2).join('/');
+    }
+
+    return moduleName.split('/')[0];
+  }
+
+  private checksum(value: string): string {
+    return createHash('sha256').update(value, 'utf8').digest('hex');
+  }
+}

package/src/_modules/artifact-compiler/index.ts

@@ -0,0 +1,9 @@
+export { DyNTS_ArtifactCompiler_ControlService } from './artifact-compiler.control-service';
+export { DyNTS_ArtifactCompileOutcome_Type } from './_enums/artifact-compile-outcome.type-enum';
+export { DyNTS_ArtifactCompileStage_Type } from './_enums/artifact-compile-stage.type-enum';
+export { DyNTS_ArtifactRetryClass_Type } from './_enums/artifact-retry-class.type-enum';
+export {
+  DyNTS_ArtifactCompileFinding_Interface,
+  DyNTS_ArtifactCompileRequest_Interface,
+  DyNTS_ArtifactCompileResult_Interface
+} from './_models/artifact-compile.interface';

package/SKILLS.md

@@ -1,75 +0,0 @@
-# SKILLS.md — `dynamo-nts` tooling
-
-Ez a fájl a projektben **ténylegesen használt** CLI-ket és eszközöket írja le, hogy a coding agent
-(Codex / Claude Code) tudja, **mit mivel** kell futtatni. Kísérő fájlok: `CLAUDE.md` / `AGENTS.md`
-(szabályok + architektúra). Rule: `core-agent-file-sync`.
-
-> A `SKILLS:AUTO:BEGIN` … `SKILLS:AUTO:END` markerek közti rész **GENERÁLT** (forrás:
-> `__agent/scripts/skills-md-generate.ps1`; adat: a projekt `package.json`-jai, config-fájljai,
-> `__agent/scripts/` tartalma) — újrafuttatáskor **felülíródik**.
-> Az azon **kívüli** rész kézi és megőrződik: oda írd a projekt-specifikus jegyzeteket.
-
-<!-- SKILLS:AUTO:BEGIN -->
-## 1. Flotta-szintű CLI-k (mindenhol elérhetők)
-
-| CLI | Csomag | Mire való | Tipikus hívás |
-|---|---|---|---|
-| `dc` / `dyn-cli` | `@futdevpro/cli-dynamo` | Dynamo fejlesztői CLI: projekt-/kód-generálás, pipeline-futtatás, review, konvenció-validálás | `dc im` (interaktív), `dc cdp`, `dc ldp`, `dc rev --json` |
-| `fdp` / `fdp-cli` | `@futdevpro/fdp-cli` | DevOps + Overseer lekérdezés: deploy, runner, build-report, logok, errorok | `fdp build-detail --project <p>`, `fdp errors --range 24h`, `fdp deploy-service --services <n>` |
-| `dye2e` | `@futdevpro/dynamo-e2e` | E2E generátor + Visual-QA review-bundle | `dye2e generate-review-bundle`, `dye2e validate-manifest` |
-| `fam` | `fdp-agent-memory` (MCP `:39265`) | Tudás-keresés / recall / szabály-lekérés — **MINDEN feladat elején** (rule: `fam-use-preferentially`) | MCP `read` a `rules` / `documents` / `codebase` táron |
-| `pnpm` | — | **Az egyetlen** csomagkezelő a flottában (npm-kompatibilis) | `pnpm run prep`, `pnpm test` |
-
-**Alap-szabályok a CLI-kre** (kanonikus: `fdp-documentations/rules/fdp-global/`):
-- `fdp-use-existing-tooling` — a meglévő scriptet/CLI-t használd, ne írj sajátot mellé.
-- `fdp-cli-only` — a DevOps-műveletek az `fdp` CLI-n mennek, nem kézi docker/ssh parancsokon.
-- **Az NPM-scripteket ne bontsd szét** — a `pnpm test` már tartalmazza a build-lépést is.
-
-**Pipeline-ok:**
-- `dc ldp` — Live Dev Pipeline: felhúzza a LOKÁL instance-t és az ellen futtat (`pipeline.config.json`);
-  státusz: `server/logs/live-dev-pipeline/status.json`.
-- `dc cdp` — CI/CD Pipeline: a **deployolt test-szerver** ellen fut (`pipeline.cicd.config.json`).
-  A CI-t az **Overseer** vezérli, nem a GitHub Actions (az csak webhook-trigger).
-
-## 2. Ebben a projektben — MÉRT adatok
-
-> Forrás: a projekt `package.json`-jai, config-fájljai és `__agent/scripts/` tartalma, beolvasva a generáláskor.
-
-### 2.1 gyökér — `@futdevpro/nts-dynamo`
-
-
-| Script | Parancs |
-|---|---|
-| `pnpm run audit:eslintrc` | `dynamo-eslintrc-audit` |
-| `pnpm run build` | `npm run build-base && jasmine && npm publish` |
-| `pnpm run build-base` | `rimraf ./build && npx tsc` |
-| `pnpm run build-tgz` | `npm run build-base && jasmine && npm pack && move ./*.tgz ../tgz-collection/dynamo-nts` |
-| `pnpm run deploy` | `npm run build` |
-| `pnpm run ldp` | `dc ldp` |
-| `pnpm run lint` | `eslint src --ext .ts` |
-| `pnpm run lint:fix` | `eslint src --ext .ts --fix` |
-| `pnpm run prep` | `npm i -g pnpm rimraf nodemon && pnpm i` |
-| `pnpm run start` | `npm run prep && nodemon` |
-| `pnpm run start-clean` | `npm run clean && npm run start` |
-| `pnpm run test` | `npm run build-base && jasmine` |
-| `pnpm run test:coverage` | `npx c8 --reporter=html --reporter=text --reporter=lcov node scripts/run-coverage-tests.js` |
-| `pnpm run validate:imports` | `dynamo-validate-imports` |
-| `pnpm run validate:naming` | `dynamo-validate-naming` |
-
-**További scriptek (csak név):** `build-all` · `build-clean` · `build-n-test` · `build-simple` · `build-tgz-cheap` · `clean` · `clean-deploy` · `fix` · `fix:return-types` · `ldp:clear` · `ldp:status` · `ldp:stop` · `nodemon-run` · `prepare` · `preprep-setup-safechain-linux` · `preprep-setup-safechain-windows` · `start-first` · `test-clean`
-
-**Felismert eszközök a dependency-kből:** Dynamo ESLint konfiguráció (`@futdevpro/dynamo-eslint`) · ESLint (`eslint`) · Jasmine (unit teszt) (`jasmine`) · Socket.IO (`socket.io`) · TypeScript (`tsc`) (`typescript`)
-
-### Konfigurációk és belépési pontok (jelenlévő fájlok)
-
-- `.dynamo` — Dynamo CLI projekt-konfiguráció
-- `.github/workflows` — GitHub Actions (Overseer-migrált projektnél csak webhook-trigger)
-- `.husky` — Git hookok (pre-commit gate)
-- `__documentations` — Projekt-dokumentáció (ARCHITECTURE / DECISIONS / BEDROCK-FRS / CHANGELOG)
-<!-- SKILLS:AUTO:END -->
-
-## 3. Projekt-specifikus jegyzetek (KÉZI — a generátor nem írja felül)
-
-_Ide jön minden, amit mérésből nem lehet kiolvasni: buktatók, kötelező sorrendek, környezeti előfeltételek,
-credential-lelőhely, „ezt sose futtasd" figyelmeztetések. Ha itt üres, az annyit jelent: még nincs feljegyezve —
-NEM azt, hogy nincs ilyen (`core-no-guessing`)._