@loaders.gl/tile-converter 5.0.0-alpha.10 → 5.0.0-alpha.12

package/src/v5/node-cli.ts

@@ -0,0 +1,197 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {parseArgs} from 'node:util';
+import {readFeatureSchema} from './node-feature-schema.js';
+import {TileConversionError} from '@loaders.gl/tile-converter/v5/core';
+import {createNodeTilesetConversionSource, NODE_TILESET_LIMITS} from './node-source.js';
+import type {NodeTileConversionOutputFormat} from './node-conversion.js';
+
+/** Text destinations supplied by the process wrapper or a hermetic caller. */
+export interface TileConverterCLIOutput {
+  /** Writes a complete JSON result or help text. */
+  readonly stdout: (text: string) => void;
+  /** Writes a JSON error without contaminating stdout. */
+  readonly stderr: (text: string) => void;
+}
+
+/** Usage for bounded metadata inspection and selected static mesh conversion. */
+const HELP = `Usage: tile-converter-v5 inspect|convert|validate <input path or URL> [options]
+
+  --input-format 3d-tiles|3tz|i3s|slpk  Explicit input format (default: 3d-tiles)
+  --geometric-error N        Required source error in meters for I3S to 3D Tiles
+  --integrated-mesh-policy as-3d-object  Authorize I3S layer-type change
+  --preserve-hierarchy        Retain a complete explicit 3D Tiles tree (3D Tiles/3TZ only)
+  --feature-schema PATH       Local JSON feature class/schema mapping (at most 64 KiB)
+  --resource ID               Selected content placement; repeat for multiple selections
+  --output-format 3d-tiles|3tz|slpk  Target profile (default: 3tz)
+  --output PATH               New destination (required for convert, forbidden for validate)
+  --max-input-bytes N          Lower the 16 MiB input/read budget
+  --max-resources N            Lower the 1,000 content-declaration limit
+  --max-documents N            Lower the 32 metadata-document limit
+  --max-output-bytes N         Lower the 32 MiB output/archive budget
+  --help                      Show this help
+
+Inspect reads metadata only, following declared .json external tilesets.
+Convert/validate require explicit selections; I3S uses declared CRS and shared spatial preparation.
+Validate decodes, converts and packages the selected target profile without writing files.
+Output defaults to a partial flat mesh collection. --preserve-hierarchy requires every declared content.
+Remote archives require HTTP 206 ranges and a stable ETag or Last-Modified validator.
+I3S inspect lists leaf nodes; feature-bearing conversion requires --feature-schema.
+Hierarchy mode supports at most 32 document placements, 256 tiles and 64 total mesh primitive placements, including ordered 1.1 contents arrays.
+`;
+
+/** Runs a bounded v5 operation, returning an exit code after source/output cleanup. */
+export async function runTileConverterCLI(
+  argumentsList: string[],
+  output: TileConverterCLIOutput,
+  signal?: AbortSignal
+): Promise<number> {
+  try {
+    const {values, positionals} = parseArgs({
+      args: argumentsList,
+      allowPositionals: true,
+      options: {
+        help: {type: 'boolean'},
+        'preserve-hierarchy': {type: 'boolean'},
+        'input-format': {type: 'string', default: '3d-tiles'},
+        'max-input-bytes': {type: 'string', default: String(NODE_TILESET_LIMITS.maxInputBytes)},
+        'max-resources': {type: 'string', default: String(NODE_TILESET_LIMITS.maxInputResources)},
+        'max-documents': {type: 'string', default: String(NODE_TILESET_LIMITS.maxTilesetDocuments)},
+        'max-output-bytes': {type: 'string', default: String(32 * 1024 * 1024)},
+        'output-format': {type: 'string', default: '3tz'},
+        output: {type: 'string'},
+        resource: {type: 'string', multiple: true},
+        'feature-schema': {type: 'string'},
+        'geometric-error': {type: 'string'},
+        'integrated-mesh-policy': {type: 'string'}
+      }
+    });
+    if (values.help || !argumentsList.length) {
+      output.stdout(HELP);
+      return 0;
+    }
+    if (
+      positionals.length !== 2 ||
+      !['inspect', 'convert', 'validate'].includes(positionals[0]) ||
+      !['3d-tiles', '3tz', 'i3s', 'slpk'].includes(values['input-format'])
+    )
+      throw new TileConversionError(
+        'CLI_USAGE_ERROR',
+        'Use inspect, convert or validate with one input and --input-format 3d-tiles, 3tz, i3s or slpk'
+      );
+    const format = values['input-format'] as '3d-tiles' | '3tz' | 'i3s' | 'slpk';
+    const operation = positionals[0];
+    const sourceOptions = {
+      input: positionals[1],
+      format,
+      signal,
+      maxInputBytes: parseLimit(values['max-input-bytes']),
+      maxInputResources: parseLimit(values['max-resources']),
+      maxTilesetDocuments: parseLimit(values['max-documents']),
+      inspectNestedTilesets: true
+    };
+    if (operation !== 'inspect') {
+      if (
+        !values.resource?.length ||
+        !['3d-tiles', '3tz', 'slpk'].includes(values['output-format']) ||
+        (operation === 'convert' ? !values.output : values.output !== undefined)
+      )
+        throw new TileConversionError(
+          'CLI_USAGE_ERROR',
+          'Convert/validate require --resource selections and a supported --output-format; only convert requires --output'
+        );
+      if (
+        values['integrated-mesh-policy'] !== undefined &&
+        values['integrated-mesh-policy'] !== 'as-3d-object'
+      )
+        throw new TileConversionError(
+          'CLI_USAGE_ERROR',
+          'Use --integrated-mesh-policy as-3d-object'
+        );
+      const features =
+        values['feature-schema'] === undefined
+          ? undefined
+          : await readFeatureSchema(
+              values['feature-schema'],
+              format === 'i3s' || format === 'slpk',
+              signal
+            );
+      const {convertNodeTileset} = await import('./node-conversion.js');
+      const report = await convertNodeTileset({
+        ...sourceOptions,
+        ...features,
+        resourceIds: values.resource,
+        preserveHierarchy: values['preserve-hierarchy'],
+        outputFormat: values['output-format'] as NodeTileConversionOutputFormat,
+        output: values.output,
+        maxOutputBytes: parseLimit(values['max-output-bytes']),
+        geometricError:
+          values['geometric-error'] === undefined
+            ? undefined
+            : parseGeometricError(values['geometric-error']),
+        integratedMeshPolicy: values['integrated-mesh-policy'] as 'as-3d-object' | undefined
+      });
+      output.stdout(
+        `${JSON.stringify({operation, input: positionals[1], inputFormat: format, outputFormat: values['output-format'], ...(values.output ? {output: values.output} : {}), report}, null, 2)}\n`
+      );
+      return 0;
+    }
+    if (
+      values['feature-schema'] !== undefined ||
+      values['preserve-hierarchy'] !== undefined ||
+      values['geometric-error'] !== undefined ||
+      values['integrated-mesh-policy'] !== undefined ||
+      values.resource ||
+      values.output ||
+      values['output-format'] !== '3tz' ||
+      values['max-output-bytes'] !== String(32 * 1024 * 1024)
+    )
+      throw new TileConversionError(
+        'CLI_USAGE_ERROR',
+        'Inspect does not accept conversion/output options'
+      );
+    const source =
+      format === 'i3s' || format === 'slpk'
+        ? await (await import('./node-i3s-source.js')).createNodeI3SConversionSource({
+            ...sourceOptions,
+            format
+          })
+        : await createNodeTilesetConversionSource({...sourceOptions, format});
+    const inspection = await source.inspect(signal).finally(() => source.close());
+    output.stdout(
+      `${JSON.stringify({operation: 'inspect', input: positionals[1], inputFormat: format, ...inspection}, null, 2)}\n`
+    );
+    return 0;
+  } catch (error) {
+    output.stderr(
+      `${JSON.stringify({
+        code: error instanceof Error && 'code' in error ? error.code : 'CONVERSION_FAILED',
+        message: error instanceof Error ? error.message : String(error),
+        diagnostics: error instanceof TileConversionError ? error.diagnostics : []
+      })}\n`
+    );
+    return 1;
+  }
+}
+
+/** Parses a positive decimal byte/count limit without accepting fractional or infinite values. */
+function parseLimit(value: string): number {
+  if (!/^[1-9]\d*$/.test(value) || !Number.isSafeInteger(Number(value)))
+    throw new TileConversionError(
+      'CLI_USAGE_ERROR',
+      'Limits must be positive safe decimal integers'
+    );
+  return Number(value);
+}
+
+/** Parses an explicit metric source error without inferring I3S screen-size semantics. */
+function parseGeometricError(value: string): number {
+  if (!/^(?:\d+(?:\.\d+)?|\.\d+)(?:[eE][+-]?\d+)?$/.test(value) || !Number.isFinite(Number(value)))
+    throw new TileConversionError(
+      'CLI_USAGE_ERROR',
+      'Geometric error must be a finite nonnegative number in meters'
+    );
+  return Number(value);
+}

package/src/v5/node-conversion.ts

@@ -0,0 +1,345 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {mkdir, open, rm, link, mkdtemp} from 'node:fs/promises';
+import {dirname, join, resolve} from 'node:path';
+import {convertTileset, TileConversionError} from '@loaders.gl/tile-converter/v5/core';
+import type {
+  BrowserTileConversionFile,
+  BrowserTilesetConversionInspection,
+  TileConversionReport
+} from '@loaders.gl/tile-converter/v5/core';
+import {
+  createSelectedMeshConversionSource,
+  measureMeshBytes,
+  SELECTED_MESH_LIMITS,
+  createMeshConversionCodec,
+  createI3SMeshConversionCodec,
+  createMeshTilesetSink,
+  createMeshHierarchyTilesetSink,
+  createI3SMeshSink,
+  encodeTileConversionArchiveInBatches
+} from '@loaders.gl/tile-converter/v5/adapters';
+import type {
+  I3SMeshSourceFeatureOptions,
+  MeshSourceFeatureOptions
+} from '@loaders.gl/tile-converter/v5/adapters';
+import {createNodeTilesetConversionSource} from './node-source.js';
+import {createNodeI3SConversionSource} from './node-i3s-source.js';
+import type {NodeTilesetConversionSourceOptions} from './node-source.js';
+
+/** Explicit targets for the initial bounded Node mesh profile. */
+export type NodeTileConversionOutputFormat = '3d-tiles' | '3tz' | 'slpk';
+
+/** Selected static mesh conversion with application-owned Node output. */
+export interface NodeTileConversionOptions
+  extends Omit<NodeTilesetConversionSourceOptions, 'format'> {
+  /** Explicit 3D Tiles, I3S layer or indexed archive source. */
+  readonly format?: '3d-tiles' | '3tz' | 'i3s' | 'slpk';
+  /** Explicit I3S attribute mapping, also supplied by the CLI feature-schema file. */
+  readonly i3sFeatures?: I3SMeshSourceFeatureOptions;
+  /** Required metric source error for I3S to 3D Tiles; no screen-size inference. */
+  readonly geometricError?: number;
+  /** Retain a complete explicit 3D Tiles tree, including inspected external documents in 3D Tiles/3TZ output. */
+  readonly preserveHierarchy?: boolean;
+  /** Authorizes IntegratedMesh to 3DObject output with a reported semantic warning. */
+  readonly integratedMeshPolicy?: 'as-3d-object';
+  /** One to 64 inspected content placement identifiers; no automatic all-content conversion. */
+  readonly resourceIds: readonly string[];
+  /** Explicit feature class/schema mapping, also supplied by the CLI feature-schema file. */
+  readonly features?: MeshSourceFeatureOptions;
+  /** Target mesh profile, independent of output filename. */
+  readonly outputFormat: NodeTileConversionOutputFormat;
+  /** New destination path; omitted for profile validation without writing. */
+  readonly output?: string;
+  /** Maximum retained files and, separately, archive bytes; at most 32 MiB. */
+  readonly maxOutputBytes?: number;
+}
+
+/** Runs the qualified browser mesh codecs with confined Node input and optional output. */
+export async function convertNodeTileset(
+  options: NodeTileConversionOptions
+): Promise<TileConversionReport> {
+  const signal = options.signal ?? new AbortController().signal;
+  const maxOutputBytes = options.maxOutputBytes ?? SELECTED_MESH_LIMITS.maxOutputBytes;
+  if (
+    !['3d-tiles', '3tz', 'slpk'].includes(options.outputFormat) ||
+    !Number.isSafeInteger(maxOutputBytes) ||
+    maxOutputBytes < 1 ||
+    maxOutputBytes > SELECTED_MESH_LIMITS.maxOutputBytes
+  )
+    throw new TileConversionError(
+      'INVALID_NODE_CONVERSION_OPTIONS',
+      'Select a supported output profile and a positive output budget at most 32 MiB'
+    );
+  const i3s = options.format === 'i3s' || options.format === 'slpk';
+  if (
+    (options.preserveHierarchy !== undefined && typeof options.preserveHierarchy !== 'boolean') ||
+    (options.preserveHierarchy && (i3s || options.outputFormat === 'slpk'))
+  )
+    throw new TileConversionError(
+      'MESH_HIERARCHY_UNSUPPORTED',
+      'Hierarchy preservation requires 3D Tiles/3TZ input and output'
+    );
+  if (
+    i3s &&
+    ((options.outputFormat !== 'slpk' && options.geometricError === undefined) ||
+      (options.geometricError !== undefined &&
+        (typeof options.geometricError !== 'number' ||
+          !Number.isFinite(options.geometricError) ||
+          options.geometricError < 0)))
+  )
+    throw new TileConversionError(
+      'MESH_GEOMETRIC_ERROR_INVALID',
+      'I3S to 3D Tiles requires an explicit nonnegative geometric error in meters'
+    );
+  if (
+    i3s
+      ? options.features !== undefined
+      : options.i3sFeatures !== undefined ||
+        options.integratedMeshPolicy !== undefined ||
+        options.geometricError !== undefined
+  )
+    throw new TileConversionError(
+      'INVALID_NODE_CONVERSION_OPTIONS',
+      'Feature and layer policies must match the selected input format'
+    );
+  const sourceOptions = {
+    ...options,
+    signal,
+    inspectNestedTilesets: true,
+    maxTilesetDocuments: options.maxTilesetDocuments ?? SELECTED_MESH_LIMITS.maxTilesetDocuments
+  };
+  const rawSource = i3s
+    ? await createNodeI3SConversionSource({
+        ...sourceOptions,
+        format: options.format as 'i3s' | 'slpk'
+      })
+    : await createNodeTilesetConversionSource({
+        ...sourceOptions,
+        format: options.format as '3d-tiles' | '3tz' | undefined
+      });
+  let files: readonly BrowserTileConversionFile[];
+  let report: TileConversionReport;
+  try {
+    const inspection = await rawSource.inspect(signal);
+    await import('@loaders.gl/polyfills');
+    const {getDracoLibraryOptions} = await import('@loaders.gl/draco/bundled');
+    const dracoLibraryOptions = getDracoLibraryOptions({
+      decoderProfile: 'full',
+      useLocalLibraries: true
+    });
+    const selection =
+      'select' in rawSource
+        ? {
+            ...(await rawSource.select(
+              inspection as Awaited<ReturnType<typeof rawSource.inspect>>,
+              options.resourceIds,
+              dracoLibraryOptions,
+              options.i3sFeatures
+            )),
+            geometricError: (options.geometricError ?? 0) + SELECTED_MESH_LIMITS.maxPositionError
+          }
+        : await createSelectedMeshConversionSource(
+            inspection as Awaited<ReturnType<typeof rawSource.inspect>>,
+            {
+              resourceIds: options.resourceIds,
+              preserveHierarchy: options.preserveHierarchy,
+              features: options.features,
+              signal,
+              source: rawSource,
+              fetcher: rawSource.fetcher,
+              dracoLibraryOptions,
+              maxInputBytes: options.maxInputBytes
+            }
+          );
+    const {source, spatialContext, geometricError} = selection;
+    const common = {
+      source,
+      signal,
+      measureInputBytes: measureMeshBytes,
+      maxInputBytes: options.maxInputBytes ?? SELECTED_MESH_LIMITS.maxInputBytes,
+      maxOutputBytes,
+      maxInputResources: SELECTED_MESH_LIMITS.maxMeshResources,
+      maxOutputResources: SELECTED_MESH_LIMITS.maxMeshResources
+    };
+    const codecOptions = {
+      spatialContext,
+      autoOrigin: i3s,
+      integratedMeshPolicy: options.integratedMeshPolicy,
+      dracoLibraryOptions,
+      maxPositionError: SELECTED_MESH_LIMITS.maxPositionError
+    };
+    if (options.outputFormat === 'slpk') {
+      const sink = createI3SMeshSink({
+        maxTotalBytes: maxOutputBytes,
+        maxMeshes: SELECTED_MESH_LIMITS.maxMeshResources,
+        maxResourceBytes: maxOutputBytes
+      });
+      report = await convertTileset({
+        ...common,
+        sink,
+        codec: createI3SMeshConversionCodec({...codecOptions, maxResourceBytes: maxOutputBytes}),
+        measureOutputBytes: resource =>
+          Object.values(resource.files).reduce((total, bytes) => total + bytes.byteLength, 0)
+      });
+      files = sink.getFiles();
+    } else {
+      const sink = options.preserveHierarchy
+        ? createMeshHierarchyTilesetSink({
+            inspection: inspection as BrowserTilesetConversionInspection,
+            resourceIds: options.resourceIds,
+            maxTotalBytes: maxOutputBytes,
+            maxPositionError: SELECTED_MESH_LIMITS.maxPositionError
+          })
+        : createMeshTilesetSink({
+            maxTotalBytes: maxOutputBytes,
+            maxMeshes: SELECTED_MESH_LIMITS.maxMeshResources,
+            geometricError
+          });
+      report = await convertTileset({
+        ...common,
+        sink,
+        codec: createMeshConversionCodec(codecOptions),
+        measureOutputBytes: resource => resource.glb.byteLength
+      });
+      files = sink.getFiles();
+    }
+  } finally {
+    await rawSource.close();
+  }
+  signal.throwIfAborted();
+  // Validate packaging as well as content, including on the write-free validation path.
+  if (options.outputFormat !== '3d-tiles' && !options.output) {
+    for await (const chunk of encodeTileConversionArchiveInBatches(files, {
+      format: options.outputFormat,
+      maxArchiveBytes: maxOutputBytes,
+      signal
+    }))
+      void chunk;
+  }
+  if (options.output)
+    await writeNodeTileConversionOutput(
+      files,
+      options.output,
+      options.outputFormat,
+      maxOutputBytes,
+      signal
+    );
+  return report;
+}
+
+/** Saves fixed relative resource names or an archive; existing destinations are never overwritten. */
+export async function writeNodeTileConversionOutput(
+  files: readonly BrowserTileConversionFile[],
+  output: string,
+  format: NodeTileConversionOutputFormat,
+  maxOutputBytes: number,
+  signal: AbortSignal
+): Promise<void> {
+  signal.throwIfAborted();
+  if (
+    !['3d-tiles', '3tz', 'slpk'].includes(format) ||
+    !Number.isSafeInteger(maxOutputBytes) ||
+    maxOutputBytes < 1
+  )
+    throw new TileConversionError(
+      'INVALID_NODE_OUTPUT',
+      'Output requires a supported format and positive safe byte limit'
+    );
+  let bytes = 0;
+  const names = new Set<string>();
+  for (const file of files) {
+    const name = file.resourceId;
+    if (
+      !name ||
+      name.includes('\\') ||
+      name.includes('\0') ||
+      name.includes(':') ||
+      name.split('/').some(segment => !segment || segment === '.' || segment === '..') ||
+      names.has(name)
+    )
+      throw new TileConversionError(
+        'INVALID_NODE_OUTPUT',
+        'Output names must be unique confined relative resource paths'
+      );
+    names.add(name);
+    if (file.blob.size > maxOutputBytes - bytes)
+      throw new TileConversionError(
+        'OUTPUT_BYTES_LIMIT_EXCEEDED',
+        'Output files exceed the byte budget'
+      );
+    bytes += file.blob.size;
+  }
+  const destination = resolve(output);
+  if (format === '3d-tiles') {
+    // Exclusive directory creation makes every subsequently created child application-owned.
+    await mkdir(destination);
+    try {
+      for (const file of files) {
+        signal.throwIfAborted();
+        const path = join(destination, file.resourceId);
+        await mkdir(dirname(path), {recursive: true});
+        const handle = await open(path, 'wx');
+        try {
+          const reader = file.blob.stream().getReader();
+          try {
+            while (true) {
+              signal.throwIfAborted();
+              const {value, done} = await reader.read();
+              if (done) break;
+              await writeFileBytes(handle, value, signal);
+            }
+          } finally {
+            await reader.cancel();
+            reader.releaseLock();
+          }
+        } finally {
+          await handle.close();
+        }
+      }
+      signal.throwIfAborted();
+    } catch (error) {
+      await rm(destination, {recursive: true, force: true});
+      throw error;
+    }
+  } else {
+    const temporaryDirectory = await mkdtemp(join(dirname(destination), '.tile-converter-'));
+    try {
+      const path = join(temporaryDirectory, 'archive');
+      const handle = await open(path, 'wx');
+      try {
+        for await (const chunk of encodeTileConversionArchiveInBatches(files, {
+          format,
+          maxArchiveBytes: maxOutputBytes,
+          signal
+        }))
+          await writeFileBytes(handle, chunk, signal);
+      } finally {
+        await handle.close();
+      }
+      signal.throwIfAborted();
+      // Same-filesystem hard link publishes a complete archive and fails if the destination exists.
+      await link(path, destination);
+    } finally {
+      await rm(temporaryDirectory, {recursive: true, force: true});
+    }
+  }
+}
+
+/** Completes native typed-array writes, including partial writes and cooperative cancellation. */
+async function writeFileBytes(
+  handle: Awaited<ReturnType<typeof open>>,
+  bytes: Uint8Array,
+  signal: AbortSignal
+): Promise<void> {
+  let offset = 0;
+  while (offset < bytes.byteLength) {
+    signal.throwIfAborted();
+    const result = await handle.write(bytes, offset, bytes.byteLength - offset);
+    if (!result.bytesWritten)
+      throw new TileConversionError('NODE_OUTPUT_WRITE_FAILED', 'Output write made no progress');
+    offset += result.bytesWritten;
+  }
+}

package/src/v5/node-feature-schema.ts

@@ -0,0 +1,155 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {constants} from 'node:fs';
+import {open} from 'node:fs/promises';
+import {TileConversionError} from '@loaders.gl/tile-converter/v5/core';
+import type {NodeTileConversionOptions} from './node-conversion.js';
+
+/** Maximum bytes retained for a local declarative feature mapping. */
+const MAXIMUM_SCHEMA_BYTES = 64 * 1024;
+/** Scalar storage types shared by the qualified mesh feature readers and writers. */
+const FIELD_TYPES = [
+  'int8',
+  'uint8',
+  'int16',
+  'uint16',
+  'int32',
+  'uint32',
+  'int64',
+  'uint64',
+  'float32',
+  'float64',
+  'utf8'
+];
+
+/** Reads a bounded local JSON mapping; source/destination adapters validate data semantics. */
+export async function readFeatureSchema(
+  path: string,
+  i3s: boolean,
+  signal?: AbortSignal
+): Promise<Pick<NodeTileConversionOptions, 'features' | 'i3sFeatures'>> {
+  signal?.throwIfAborted();
+  // Avoid blocking on special files before the regular-file check.
+  const file = await open(path, constants.O_RDONLY | constants.O_NONBLOCK);
+  let mapping: unknown;
+  try {
+    if (!(await file.stat()).isFile()) rejectSchema('Feature schema must be a regular local file');
+    const bytes = new Uint8Array(MAXIMUM_SCHEMA_BYTES + 1);
+    let length = 0;
+    while (length < bytes.length) {
+      signal?.throwIfAborted();
+      const {bytesRead} = await file.read(bytes, length, bytes.length - length, null);
+      if (!bytesRead) break;
+      length += bytesRead;
+    }
+    signal?.throwIfAborted();
+    if (length > MAXIMUM_SCHEMA_BYTES) rejectSchema('Feature schema exceeds 64 KiB');
+    try {
+      mapping = JSON.parse(
+        new TextDecoder('utf-8', {fatal: true}).decode(bytes.subarray(0, length))
+      );
+    } catch {
+      rejectSchema('Feature schema must contain valid UTF-8 JSON');
+    }
+  } finally {
+    await file.close();
+  }
+  const options = requireRecord(mapping);
+  rejectUnknownKeys(options, [
+    'schema',
+    'metadataClass',
+    'sourceFeatureIdProperty',
+    'featureIdField',
+    'batchSize',
+    'integer64Encoding',
+    ...(i3s ? ['objectIdProperty', 'maxAttributeBytes'] : [])
+  ]);
+  requireName(options.metadataClass);
+  for (const key of ['sourceFeatureIdProperty', 'featureIdField']) {
+    if (options[key] !== undefined) requireName(options[key]);
+  }
+  if (
+    options.batchSize !== undefined &&
+    (!Number.isSafeInteger(options.batchSize) ||
+      Number(options.batchSize) < 1 ||
+      Number(options.batchSize) > 65536)
+  )
+    rejectSchema('batchSize must be an integer from 1 to 65536');
+  if (options.integer64Encoding !== undefined && options.integer64Encoding !== 'decimal-string')
+    rejectSchema('integer64Encoding must be decimal-string when supplied');
+  const schema = requireRecord(options.schema);
+  rejectUnknownKeys(schema, ['fields', 'metadata']);
+  validateMetadata(schema.metadata);
+  if (!Array.isArray(schema.fields) || !schema.fields.length || schema.fields.length > 256)
+    rejectSchema('schema.fields must declare between 1 and 256 fields');
+  const names = new Set<string>();
+  for (const value of schema.fields) {
+    const field = requireRecord(value);
+    rejectUnknownKeys(field, ['name', 'type', 'nullable', 'metadata']);
+    requireName(field.name);
+    if (names.has(field.name as string)) rejectSchema('Feature fields must have unique names');
+    names.add(field.name as string);
+    if (
+      typeof field.type !== 'string' ||
+      !FIELD_TYPES.includes(field.type) ||
+      (field.nullable !== undefined && typeof field.nullable !== 'boolean')
+    )
+      rejectSchema('Fields require a scalar numeric/utf8 type and an optional boolean nullable');
+    validateMetadata(field.metadata);
+  }
+  const identifier = schema.fields.find(
+    value => value.name === (options.featureIdField ?? 'feature_id')
+  );
+  if (
+    !identifier ||
+    identifier.nullable === true ||
+    !['utf8', ...FIELD_TYPES.filter(type => /^(u?int)/.test(type))].includes(identifier.type)
+  )
+    rejectSchema('Declare a nonnullable string or integer feature ID field');
+  if (i3s) {
+    requireName(options.objectIdProperty);
+    if (
+      !Number.isSafeInteger(options.maxAttributeBytes) ||
+      Number(options.maxAttributeBytes) < 1 ||
+      Number(options.maxAttributeBytes) > 16 * 1024 * 1024
+    )
+      rejectSchema('maxAttributeBytes must be a positive integer at most 16 MiB');
+    return {
+      i3sFeatures: options as unknown as NonNullable<NodeTileConversionOptions['i3sFeatures']>
+    };
+  }
+  return {features: options as unknown as NonNullable<NodeTileConversionOptions['features']>};
+}
+
+/** Rejects unknown configuration keys rather than silently ignoring misspelled controls. */
+function rejectUnknownKeys(record: Record<string, unknown>, allowed: readonly string[]): void {
+  if (Object.keys(record).some(key => !allowed.includes(key)))
+    rejectSchema('Unknown feature-schema option');
+}
+
+/** Requires a JSON object before accessing its fields. */
+function requireRecord(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value))
+    rejectSchema('Feature mappings require JSON objects');
+  return value as Record<string, unknown>;
+}
+
+/** Requires a nonempty class, property or column name. */
+function requireName(value: unknown): void {
+  if (typeof value !== 'string' || !value.trim())
+    rejectSchema('Feature names must be nonempty strings');
+}
+
+/** Retains only string-valued schema/field metadata. */
+function validateMetadata(value: unknown): void {
+  if (value === undefined) return;
+  if (Object.values(requireRecord(value)).some(entry => typeof entry !== 'string'))
+    rejectSchema('Schema metadata values must be strings');
+}
+
+/** Reports configuration failures before source conversion or output publication. */
+function rejectSchema(message: string): never {
+  throw new TileConversionError('CLI_FEATURE_SCHEMA_INVALID', message);
+}