@wildshard/shard-format 0.4.5 → 0.4.7

package/src/format/product-stream-rows.ts

@@ -1,3 +1,4 @@
+// oxlint-disable import/max-dependencies -- the old validator's steps, each from its defining module
 // `validateShardfileProduct`'s inventory steps, replayed over what one
 // streaming pass kept (API-CLOUDFLARE AC6a): each listed file's hash and
 // size, the blobs' facts, server files, KTX2 device costs, the cook and its
@@ -7,6 +8,7 @@
 
 import { cookMountPath, readCookData } from './cook-data.ts'
 import { requireCookPreparation } from './cook-preparation.ts'
+import { issueError, withIssueCode } from './issue-codes.ts'
 import { validatePlatformFile } from './platformFileFamilies.ts'
 import { mountSharesBlob } from './product-reads.ts'
 import { inspectFacts, ktx2Text } from './product-stream-facts.ts'
@@ -45,13 +47,19 @@ function readListed(
   replay.listed.add(entry.path)
   const member = replay.members.get(entry.path)
   if (member === undefined) {
-    throw new Error(`missing file: ${entry.path}`)
+    throw issueError('file-mismatch', `missing file: ${entry.path}`)
   }
   if (member.size > entry.bytes) {
-    throw new Error(`larger than its declared size: ${entry.path}`)
+    throw issueError(
+      'file-mismatch',
+      `larger than its declared size: ${entry.path}`,
+    )
   }
   if (member.size !== entry.bytes || member.sha !== entry.hash) {
-    throw new Error(`Output hash or size mismatch: ${entry.path}`)
+    throw issueError(
+      'file-mismatch',
+      `Output hash or size mismatch: ${entry.path}`,
+    )
   }
   return member
 }
@@ -63,7 +71,7 @@ function listedBytes(
 ): Uint8Array {
   const { bytes } = readListed(replay, entry)
   if (bytes === undefined) {
-    throw new Error(`stream: ${entry.path} was not kept`)
+    throw issueError('stream-miss', `stream: ${entry.path} was not kept`)
   }
   return bytes
 }
@@ -76,7 +84,11 @@ function replayFiles(
   // oxlint-disable-next-line typescript/prefer-readonly-parameter-types -- format's row type, only read
   scripts: ScriptAdmissionRows,
 ): Map<string, KeptMember> {
-  const contracts = decisionModuleContracts(scripts, index.files)
+  const contracts = withIssueCode(
+    'script-admission',
+    (): ReturnType<typeof decisionModuleContracts> =>
+      decisionModuleContracts(scripts, index.files),
+  )
   const assets = new Map<string, KeptMember>()
   for (const entry of index.files) {
     const member = readListed(replay, {
@@ -84,13 +96,15 @@ function replayFiles(
       hash: entry.hash,
       bytes: entry.compressed,
     })
-    inspectFacts(
-      entry,
-      member,
-      entry.kind === 'wasm'
-        ? (contracts.get(entry.hash) ?? { abi: 0 })
-        : undefined,
-    )
+    withIssueCode('blob-invalid', (): void => {
+      inspectFacts(
+        entry,
+        member,
+        entry.kind === 'wasm'
+          ? (contracts.get(entry.hash) ?? { abi: 0 })
+          : undefined,
+      )
+    })
     assets.set(
       `${entry.commons === true ? 'commons:' : ''}${entry.hash}`,
       member,
@@ -111,34 +125,41 @@ function replayServerAndKtx2(
 ): void {
   for (const entry of index.admission.server ?? []) {
     const bytes = listedBytes(replay, entry)
-    if (entry.kind === 'json') {
-      if (
-        validatePlatformFile(
-          entry.name,
-          entry.schema,
-          readCanonicalJson(bytes),
-        ) === undefined
-      ) {
-        throw new Error(`Unregistered named JSON: ${entry.name}`)
+    withIssueCode('server-file-invalid', (): void => {
+      if (entry.kind === 'json') {
+        if (
+          validatePlatformFile(
+            entry.name,
+            entry.schema,
+            readCanonicalJson(bytes),
+          ) === undefined
+        ) {
+          throw new Error(`Unregistered named JSON: ${entry.name}`)
+        }
+      } else if (outputBlobKind('binary', bytes) !== entry.kind) {
+        throw new Error('Output blob bytes differ from their declared kind')
       }
-    } else if (outputBlobKind('binary', bytes) !== entry.kind) {
-      throw new Error('Output blob bytes differ from their declared kind')
-    }
+    })
   }
   for (const [hash, cost] of Object.entries(index.ktx2Costs ?? {})) {
-    const actual = ktx2Text(assets.get(hash))
+    const actual = withIssueCode('ktx2-costs', (): string | undefined =>
+      ktx2Text(assets.get(hash)),
+    )
     if (
       actual === undefined ||
       new TextDecoder().decode(validationSourceBytes(cost)) !== actual
     ) {
-      throw new Error('KTX2 device costs differ from verified bytes')
+      throw issueError(
+        'ktx2-costs',
+        'KTX2 device costs differ from verified bytes',
+      )
     }
   }
 }
 
-/** C0 (J137): the cook file, and each mount's hash and size. */
+/** The cook steps `replayCook` tags. */
 // oxlint-disable-next-line typescript/prefer-readonly-parameter-types -- valibot's output type, only read
-function replayCook(replay: Readonly<Replay>, index: OutputIndex): void {
+function cookSteps(replay: Readonly<Replay>, index: OutputIndex): void {
   const cook =
     index.cook === undefined
       ? undefined
@@ -154,15 +175,26 @@ function replayCook(replay: Readonly<Replay>, index: OutputIndex): void {
   }
 }
 
+/** C0 (J137): the cook file, and each mount's hash and size. */
+// oxlint-disable-next-line typescript/prefer-readonly-parameter-types -- valibot's output type, only read
+function replayCook(replay: Readonly<Replay>, index: OutputIndex): void {
+  withIssueCode('cook-invalid', (): void => {
+    cookSteps(replay, index)
+  })
+}
+
 /** No copied runtime files (the Worker has no import checker) and no file the index does not list. */
 // oxlint-disable-next-line typescript/prefer-readonly-parameter-types -- valibot's output type, only read
 function replayInventory(replay: Readonly<Replay>, index: OutputIndex): void {
   if ((index.runtime?.files ?? []).length > NONE) {
-    throw new Error('Copied runtime files need a runtime import checker')
+    throw issueError(
+      'runtime-files',
+      'Copied runtime files need a runtime import checker',
+    )
   }
   for (const path of replay.members.keys()) {
     if (!replay.listed.has(path)) {
-      throw new Error(`Unlisted output file: ${path}`)
+      throw issueError('unlisted-file', `Unlisted output file: ${path}`)
     }
   }
 }
@@ -191,7 +223,7 @@ function replayPacksToInventory(
     }
     const refusal = packs.get(pack.path)
     if (refusal !== undefined) {
-      throw new Error(refusal)
+      throw issueError('pack-invalid', refusal)
     }
   }
   replayCook(replay, index)

package/src/format/product-stream-tar.ts

@@ -2,6 +2,7 @@
 // tarball's chunks with the same refusals, in bounded memory. Each regular
 // file is hashed as it streams; the caller says which files it wants whole.
 
+import { archiveError, withIssueCodeAsync } from './issue-codes.ts'
 import { BLOCK, padded } from './tar-fields.ts'
 import { MAX_ENTRIES, claimFile, claimFolder, newClaims } from './tar-paths.ts'
 import { readTarHeader } from './tar.ts'
@@ -95,7 +96,7 @@ async function assertEnd(reader: ChunkReader): Promise<number> {
     zero &&= isZero(piece)
   }
   if (rest < END_BLOCKS * BLOCK || !zero) {
-    throw new Error('tar: bad end-of-archive blocks')
+    throw archiveError('tar: bad end-of-archive blocks')
   }
   return rest
 }
@@ -127,10 +128,10 @@ async function readMember(
     ? new Uint8Array(entry.size)
     : undefined
   if ((await copyMember(reader, entry.size, { hasher, bytes })) < entry.size) {
-    throw new Error(`tar: truncated entry ${entry.path}`)
+    throw archiveError(`tar: truncated entry ${entry.path}`)
   }
   if (!isZero(await reader.read(padded(entry.size) - entry.size))) {
-    throw new Error(`tar: non-zero padding after ${entry.path}`)
+    throw archiveError(`tar: non-zero padding after ${entry.path}`)
   }
   return { size: entry.size, sha: hasher.digest(), bytes }
 }
@@ -144,7 +145,7 @@ async function walkEntry(
   const entry = readTarHeader(block)
   if (entry.type === DIRECTORY_TYPE) {
     if (entry.size !== START) {
-      throw new Error(`tar: directory with a size ${entry.path}`)
+      throw archiveError(`tar: directory with a size ${entry.path}`)
     }
     if (entry.path !== '') {
       claimFolder(walk.claims, entry.path)
@@ -160,13 +161,13 @@ async function walkEntry(
 async function nextBlock(reader: ChunkReader): Promise<Uint8Array> {
   const block = await reader.read(BLOCK)
   if (block.length < BLOCK) {
-    throw new Error('tar: truncated (no end-of-archive blocks)')
+    throw archiveError('tar: truncated (no end-of-archive blocks)')
   }
   return block
 }
 
-/** Walk a tarball once, refusing what `indexTar` refuses; resolves with its byte length. */
-async function walkTar(
+/** `walkTar`, before its refusals (a bad decode among them) take `archive-invalid`. */
+async function walkMembers(
   tar: AsyncIterable<Uint8Array>,
   ports: WalkPorts,
 ): Promise<number> {
@@ -181,12 +182,23 @@ async function walkTar(
       return offset + (await assertEnd(reader))
     }
     if (entries === MAX_ENTRIES) {
-      throw new Error(`tar: too many entries, over ${String(MAX_ENTRIES)}`)
+      throw archiveError(`tar: too many entries, over ${String(MAX_ENTRIES)}`)
     }
     // oxlint-disable-next-line eslint/no-await-in-loop -- a tarball's entries come in order
     offset += await walkEntry(reader, block, walk)
   }
 }
 
+/** Walk a tarball once, refusing what `indexTar` refuses; resolves with its byte length. */
+async function walkTar(
+  tar: AsyncIterable<Uint8Array>,
+  ports: WalkPorts,
+): Promise<number> {
+  return await withIssueCodeAsync(
+    'archive-invalid',
+    async (): Promise<number> => await walkMembers(tar, ports),
+  )
+}
+
 export type { StreamHasher, StreamMember, WalkPorts }
 export { walkTar }

package/src/format/product-stream.ts

@@ -17,6 +17,7 @@
 
 import { SHARDFILE_ADMISSION_LIMITS as limits } from './admissionLimits.ts'
 import { assertSectionSides } from './feature-sides.ts'
+import { issueError, withIssueCode } from './issue-codes.ts'
 import { parseOutputIndex, validateOutputSection } from './outputIndex.ts'
 import {
   admitAssets,
@@ -143,7 +144,10 @@ function collect(ports: StreamValidationPorts): Readonly<{
       (keep && now + size > STREAM_KEPT_CAP) ||
       (!keep && size > STREAM_BLOB_CAP)
     ) {
-      throw new Error(`stream: member over the streaming cap: ${path}`)
+      throw issueError(
+        'stream-cap',
+        `stream: member over the streaming cap: ${path}`,
+      )
     }
     return keep || path.startsWith('blobs/')
   }
@@ -214,22 +218,30 @@ function readSections(
   replay: Readonly<Replay>,
   // oxlint-disable-next-line typescript/prefer-readonly-parameter-types -- valibot's output type, only read
   index: OutputIndex,
-): { sections: Map<string, unknown>; warnings: string[] } {
+): Pick<StreamedProduct, 'sections' | 'warnings' | 'scripts'> {
   const payloads = new Map<string, unknown>()
   for (const entry of index.sections) {
-    const value = readCanonicalJson(listedBytes(replay, entry))
-    assertSectionSides(entry.name, value)
-    validateOutputSection(entry.name, value)
-    payloads.set(entry.name, value)
+    withIssueCode('section-invalid', (): void => {
+      const value = readCanonicalJson(listedBytes(replay, entry))
+      assertSectionSides(entry.name, value)
+      validateOutputSection(entry.name, value)
+      payloads.set(entry.name, value)
+    })
   }
-  const warnings = assertScriptSides(payloads, index, {
+  const sides = {
     paths: (): Iterable<string> => replay.members.keys(),
     read: (path: string): Uint8Array | undefined =>
       replay.members.get(path)?.bytes,
     verify: (bytes: Readonly<Uint8Array>, expected: string): boolean =>
       replay.hash(bytes) === expected,
-  })
-  return { sections: payloads, warnings }
+  }
+  const warnings = withIssueCode('script-side', (): string[] =>
+    assertScriptSides(payloads, index, sides),
+  )
+  const scripts = withIssueCode('script-admission', (): ScriptAdmissionRows =>
+    scriptAdmissionRows(payloads),
+  )
+  return { sections: payloads, warnings, scripts }
 }
 
 /** Stream-validate a stored shardfile object (see the file comment): `open` gives a fresh stream of it on each call.
@@ -246,9 +258,10 @@ async function validateShardfileStream(
     listed: new Set(['validation.json']),
     hash: ports.hash,
   }
-  const index = readIndex(replay)
-  const { sections, warnings } = readSections(replay, index)
-  const scripts = scriptAdmissionRows(sections)
+  const index = withIssueCode('index-invalid', (): OutputIndex =>
+    readIndex(replay),
+  )
+  const { sections, warnings, scripts } = readSections(replay, index)
   replayBeforePacks(replay, index, scripts)
   const before = admitBeforeAssets(index, sections, scripts)
   const later = await assetPasses({

package/src/format/product.ts

@@ -18,10 +18,15 @@ import { SCRIPT_LIMITS } from './scriptLimits.ts';
 import { runtimeAccountedBytes } from "./runtimeCost.ts";
 import { MemoryAdmission } from './memoryAdmission.ts';
 import { nearPlaceholderRoots } from './nearPlaceholder.ts';
+import type { IssueCodeOf } from './issue-codes.ts';
+
 
 /** Actual costs derived from a bounded parser, never trusted from the author declaration. */
 import { isNavigationData, navigationCost } from './navigationBytes.ts';
 
+/** A performance issue's code and its metric words. */
+type Named = readonly [code: IssueCodeOf<'performance'>, metric: string];
+
 /** Admitted decoded CPU bytes, GPU bytes, triangle count and draw count charged to the asset budget. */
 export interface AssetCost { decoded: number; gpu: number; triangles: number; draws: number }
 const MAX_BYTES = 25_000_000;
@@ -176,7 +181,10 @@ export interface PerformanceObservations {
   fuel: { p95: number; max: number; samples: number };
 }
 /** A report issue distinguishes tradeable memory targets from enforceable complete totals and execution budgets. */
-export interface PerformanceIssue { metric: string; actual: number; limit: number; severity: 'warning' | 'refusal' }
+export interface PerformanceIssue {
+  /** SHARD-AUTHORING SA41: the stable code (issue-codes.ts, docs/VALIDATION-CODES.md); `metric` keeps its words. */
+  code: IssueCodeOf<'performance'>; metric: string; actual: number; limit: number; severity: 'warning' | 'refusal';
+}
 /** Build-time estimates retain units, their scope, and the measured execution samples they use. */
 export interface PerformanceReport {
   slug: string; policy: 'refuse' | 'warn'; pass: boolean;
@@ -219,20 +227,20 @@ const near = (tile: Shardfile['tiles'][number], x: number, z: number): boolean =
 /** Cheap target grading before asset reads; format integrity and total-memory admission remain separate. */
 export function performanceTargetIssues(source: Shardfile, policy: 'refuse' | 'warn' = 'refuse'): PerformanceIssue[] {
   const issues: PerformanceIssue[] = [];
-  const check = (metric: string, actual: number, limit: number, provisional = false): void => {
-    if (actual > limit) issues.push({ metric, actual, limit, severity: provisional || policy === 'warn' ? 'warning' : 'refusal' });
+  const check = ([code, metric]: Named, actual: number, limit: number, provisional = false): void => {
+    if (actual > limit) issues.push({ code, metric, actual, limit, severity: provisional || policy === 'warn' ? 'warning' : 'refusal' });
   };
   const libraryAllowance = source.budgets.library.downloadAllowance ?? C.library.compressed;
-  check('library download budget bytes', source.budgets.library.compressed, libraryAllowance);
-  check('critical download budget bytes', source.budgets.sim.compressed, C.sim.compressed);
-  check('library download bytes', totals(source, reportCardClosure(source, source.library)).bytes, libraryAllowance);
-  check('critical download bytes', totals(source, reportCardClosure(source, source.critical)).bytes, C.sim.compressed);
+  check(['perf-library-download-budget', 'library download budget bytes'], source.budgets.library.compressed, libraryAllowance);
+  check(['perf-critical-download-budget', 'critical download budget bytes'], source.budgets.sim.compressed, C.sim.compressed);
+  check(['perf-library-download', 'library download bytes'], totals(source, reportCardClosure(source, source.library)).bytes, libraryAllowance);
+  check(['perf-critical-download', 'critical download bytes'], totals(source, reportCardClosure(source, source.critical)).bytes, C.sim.compressed);
   for (const tile of source.tiles) {
     const cap = tile.lod === 0 ? C.l0 : C.l1, id = `tile ${tile.lod}/${tile.x}/${tile.z}`;
-    check(`${id} download bytes`, tile.compressed, cap.compressed, true); check(`${id} draws`, tile.draws, cap.draws, true); check(`${id} triangles`, tile.triangles, cap.triangles, true);
+    check(['perf-tile-download', `${id} download bytes`], tile.compressed, cap.compressed, true); check(['perf-tile-draws', `${id} draws`], tile.draws, cap.draws, true); check(['perf-tile-triangles', `${id} triangles`], tile.triangles, cap.triangles, true);
   }
   if (source.far !== null) {
-    check('far download bytes', source.far.compressed, C.far.compressed); check('far draws', source.far.draws, C.far.draws); check('far triangles', source.far.triangles, C.far.triangles);
+    check(['perf-far-download', 'far download bytes'], source.far.compressed, C.far.compressed); check(['perf-far-draws', 'far draws'], source.far.draws, C.far.draws); check(['perf-far-triangles', 'far triangles'], source.far.triangles, C.far.triangles);
   }
   return issues;
 }
@@ -293,18 +301,18 @@ export function performanceReport(source: Shardfile, observations: PerformanceOb
   const commons = native.resident + Object.values(source.requires.commonsCosts).reduce((sum, row) => sum + row.decoded + row.gpu, 0);
   const worst = worstContentCost(source, commons), spawn = source.spawn;
   const memory = { near: nearbyContentCost(source, spawn.x, spawn.z, commons), worst, playingLimit: C.playing, loadingLimit: C.loading };
-  const issues: PerformanceIssue[] = memoryTargetWarnings(source).map(row => ({ metric: `${row.category} resident target (tradeable)`, actual: row.bytes, limit: row.target, severity: 'warning' }));
+  const issues: PerformanceIssue[] = memoryTargetWarnings(source).map(row => ({ code: 'perf-memory-target', metric: `${row.category} resident target (tradeable)`, actual: row.bytes, limit: row.target, severity: 'warning' }));
   issues.push(...performanceTargetIssues(source, policy));
-  const check = (metric: string, actual: number, limit: number): void => {
-    if (!Number.isFinite(actual) || actual < 0 || actual > limit) issues.push({ metric, actual, limit, severity: policy === 'warn' ? 'warning' : 'refusal' });
+  const check = ([code, metric]: Named, actual: number, limit: number): void => {
+    if (!Number.isFinite(actual) || actual < 0 || actual > limit) issues.push({ code, metric, actual, limit, severity: policy === 'warn' ? 'warning' : 'refusal' });
   };
-  if (native.unmeasuredViewAndDownload) check('native view/download measurement required', 1, 0);
-  if (source.runtime !== null && source.runtime.cost === undefined) check('native resident measurement required', 1, 0);
+  if (native.unmeasuredViewAndDownload) check(['perf-native-view-unmeasured', 'native view/download measurement required'], 1, 0);
+  if (source.runtime !== null && source.runtime.cost === undefined) check(['perf-native-resident-unmeasured', 'native resident measurement required'], 1, 0);
   // G433: while src/format/memoryGates.json is report-only the totals print as warnings and never refuse a build.
-  const total = (metric: string, actual: number, limit: number): void => {
-    if (MEMORY_GATES.reportOnly && actual > limit) issues.push({ metric: `${metric} (report-only, G433)`, actual, limit, severity: 'warning' }); else check(metric, actual, limit);
+  const total = ([code, metric]: Named, actual: number, limit: number): void => {
+    if (MEMORY_GATES.reportOnly && actual > limit) issues.push({ code, metric: `${metric} (report-only, G433)`, actual, limit, severity: 'warning' }); else check([code, metric], actual, limit);
   };
-  total('worst playing total bytes', worst.playing, C.playing); total('worst loading total bytes', worst.loading, C.loading);
+  total(['perf-playing-memory', 'worst playing total bytes'], worst.playing, C.playing); total(['perf-loading-memory', 'worst loading total bytes'], worst.loading, C.loading);
   const library = reportCardClosure(source, source.library), critical = reportCardClosure(source, source.critical);
   const tileRoots = source.tiles.flatMap(tile => tile.files), farRoots = source.far?.files ?? [], nearRoots = nearPlaceholderRoots(source.near);
   const playable = reportCardClosure(source, [...source.critical, ...source.library, ...farRoots, ...source.tiles.filter(tile => tile.lod === 1 || near(tile, spawn.x, spawn.z)).flatMap(tile => tile.files)]);
@@ -324,11 +332,11 @@ export function performanceReport(source: Shardfile, observations: PerformanceOb
   const graphs: PerformanceReport['graphs'] = [];
   const scriptLimit = Math.min(source.serverBudget.tickMicros, 1_000_000 / 60 / 4);
   for (const [group, data] of ([['scripts', observations.scripts], ['fuel', observations.fuel]] as const)) for (const [metric, value] of Object.entries(data)) {
-    if (!Number.isFinite(value) || value < 0) check(`invalid measured ${group}.${metric}`, value, 0);
+    if (!Number.isFinite(value) || value < 0) check(['perf-script-sample-invalid', `invalid measured ${group}.${metric}`], value, 0);
   }
-  check('script CPU p95 us/tick', observations.scripts.p95Micros, scriptLimit);
-  check('script fuel/tick', observations.fuel.max, SCRIPT_LIMITS.fuelPerTick);
-  if (observations.scripts.samples < 60 || observations.fuel.samples < 60) check('missing execution samples', 60, Math.min(observations.scripts.samples, observations.fuel.samples));
+  check(['perf-script-cpu', 'script CPU p95 us/tick'], observations.scripts.p95Micros, scriptLimit);
+  check(['perf-script-fuel', 'script fuel/tick'], observations.fuel.max, SCRIPT_LIMITS.fuelPerTick);
+  if (observations.scripts.samples < 60 || observations.fuel.samples < 60) check(['perf-script-samples-missing', 'missing execution samples'], 60, Math.min(observations.scripts.samples, observations.fuel.samples));
   // An explicit cold-network estimate, not a measured phone loading claim. The guide names both assumptions.
   const bytesPerSecond = 1_000_000, setupSeconds = 1;
   return { slug: source.identity.slug, policy, pass: !issues.some(issue => issue.severity === 'refusal'), native, memory, views, graphs, scripts: observations, download,

package/src/format/productValidation.ts

@@ -19,6 +19,7 @@ import { assertSectionSides } from './feature-sides.ts';
 import { assertScriptSides } from './script-sides.ts';
 import { productRecordings } from './product-audio.ts';
 import type { RecordingMeasure } from './audio-measure.ts';
+import { issueError, withIssueCode as coded } from './issue-codes.ts';
 
 /**
  * P1-F3 format validation of a built shardfile product (format 2: `shard.json`, sections, blobs, packs): the schema,
@@ -108,23 +109,23 @@ export function outputBlobExtension(kind: OutputFile['kind'], bytes: Uint8Array)
 export function assertProductTargets(source: Shardfile, policy: 'warn' | 'refuse'): void {
   const issues = performanceTargetIssues(source, policy).filter(issue => issue.severity === 'refusal');
   if (issues.length === 0) return;
-  throw new Error(issues.map(issue => `REFUSAL: ${issue.metric}: ${issue.actual} > ${issue.limit}`).join('\n'));
+  throw issueError('performance-targets', issues.map(issue => `REFUSAL: ${issue.metric}: ${issue.actual} > ${issue.limit}`).join('\n'));
 }
 
 /** Admit a whole shardfile's declared costs and its actual immutable bytes through the defining contracts. */
 export function admitShardfileProduct(input: unknown, assets: ReadonlyMap<string, Uint8Array>, hash: (bytes: Uint8Array) => string,
   policy: 'warn' | 'refuse' = 'refuse', scripts: ScriptAdmissionRows = []): Shardfile {
-  const source = parseShardfile(input);
-  preflightDeclaredCosts(source, offlineMemoryAdmission(policy));
-  assertProductTargets(source, policy);
-  return validateShardfileAssets(source, assets, hash, offlineMemoryAdmission(policy), undefined, scripts);
+  const source = coded('shard-schema', (): Shardfile => parseShardfile(input));
+  coded('declared-costs', (): void => { preflightDeclaredCosts(source, offlineMemoryAdmission(policy)); });
+  coded('performance-targets', (): void => { assertProductTargets(source, policy); });
+  return coded('asset-admission', (): Shardfile => validateShardfileAssets(source, assets, hash, offlineMemoryAdmission(policy), undefined, scripts));
 }
 
 /** Refuse world target rows that name items or quests the shardfile does not declare. */
 export function checkWorldTargets(source: Shardfile, input: unknown): void {
   if (input === undefined) return;
-  const errors = worldTargetRules(parseWorldTargets(input), source);
-  if (errors.length > 0) throw new Error(errors.join('; '));
+  const errors = coded('world-targets', (): string[] => worldTargetRules(parseWorldTargets(input), source));
+  if (errors.length > 0) throw issueError('world-targets', errors.join('; '));
 }
 
 function inspectBlob(file: OutputFile, bytes: Uint8Array, ports: ProductValidationPorts, script?: ScriptContract): void {
@@ -148,58 +149,88 @@ function inspectBlob(file: OutputFile, bytes: Uint8Array, ports: ProductValidati
   if ((['decoded', 'gpu', 'triangles', 'draws'] as const).some(key => cost[key] > file[key])) throw new Error('Output blob understates parsed costs');
 }
 
+type ReadListed = (entry: Readonly<{ path: string; hash: string; bytes: number }>) => Uint8Array;
+
+/** Each section: listed, canonical, a declared side, its schema (`section-invalid`). */
+// oxlint-disable-next-line typescript/prefer-readonly-parameter-types -- valibot's output type, only read
+function readSections(index: OutputIndex, read: ReadListed): Map<string, unknown> {
+  const payloads = new Map<string, unknown>();
+  for (const entry of index.sections) {
+    coded('section-invalid', (): void => { const value = readCanonicalJson(read(entry)); assertSectionSides(entry.name, value); validateOutputSection(entry.name, value); payloads.set(entry.name, value); });
+  }
+  return payloads;
+}
+
+/** J91: server files pass the same hash, size and schema checks; they stay out of the client's admitted assets. Then the
+ *  declared KTX2 device costs against the verified bytes. */
+// oxlint-disable-next-line typescript/prefer-readonly-parameter-types -- valibot's output type and the admitted bytes, only read
+function checkServerAndKtx2(index: OutputIndex, read: ReadListed, assets: ReadonlyMap<string, Uint8Array>): void {
+  for (const entry of index.admission.server ?? []) {
+    const bytes = read(entry);
+    coded('server-file-invalid', (): void => {
+      if (entry.kind === 'json') {
+        if (validatePlatformFile(entry.name, entry.schema, readCanonicalJson(bytes)) === undefined) throw new Error(`Unregistered named JSON: ${entry.name}`);
+      } else if (outputBlobKind('binary', bytes) !== entry.kind) throw new Error('Output blob bytes differ from their declared kind');
+    });
+  }
+  coded('ktx2-costs', (): void => {
+    for (const [hash, cost] of Object.entries(index.ktx2Costs ?? {})) {
+      const bytes = assets.get(hash);
+      if (bytes === undefined || decoder().decode(validationSourceBytes(cost)) !== decoder().decode(validationSourceBytes(ktx2DeviceCosts(bytes)))) throw new Error('KTX2 device costs differ from verified bytes');
+    }
+  });
+}
+
+/** C0 (J137): the cook file; a mount passes the same hash and size checks as any listed file (`cook-invalid`). */
+// oxlint-disable-next-line typescript/prefer-readonly-parameter-types -- valibot's output type, only read
+function readCook(index: OutputIndex, read: ReadListed, hash: (bytes: Uint8Array) => string): ReturnType<typeof readCookData> | undefined {
+  return coded('cook-invalid', (): ReturnType<typeof readCookData> | undefined => {
+    const cook = index.cook === undefined ? undefined : readCookData(readCanonicalJson(read(index.cook)));
+    requireCookPreparation(index, cook, hash);
+    for (const mount of cook?.mounts ?? []) {
+      if (!mountSharesBlob(mount, index.files)) {
+        if (mount.path !== cookMountPath(mount.url)) { throw new Error(`Mount path differs from its URL: ${mount.url}`); }
+        read(mount);
+      }
+    }
+    return cook;
+  });
+}
+
 /** Validate a built product folder with format alone: the index and section schemas, the exact inventory (no unlisted,
  *  missing or changed file), every hash and size, byte kinds against declared kinds and costs, KTX2 device costs, pack
  *  members, registered named JSON, budgets and admission, world targets and the declared source hash. A `client/plan`
  *  kind with no declared side (SERVER-PARITY SS2, `feature-sides.ts`) is refused by name before its section schema runs, and
- *  a script run on the wrong side (SS7, `script-sides.ts`) once the sections are read. */
+ *  a script run on the wrong side (SS7, `script-sides.ts`) once the sections are read. A refusal carries the `code` of the
+ *  check that refused (SA41, `issue-codes.ts`). */
 export function validateShardfileProduct(files: ProductFiles, ports: ProductValidationPorts): ValidatedProduct {
   const verify = ports.verify ?? ((bytes: Uint8Array, expected: string): boolean => ports.hash(bytes) === expected);
-  const index = parseOutputIndex(readCanonicalJson(files.read('shard.json', limits.sourceBytes)));
-  const listed = new Set(['shard.json', 'validation.json']), payloads = new Map<string, unknown>(), { assets, keep } = assetStore(files.read, ports.readThrough === true);
-  const read = (entry: { path: string; hash: string; bytes: number }): Uint8Array => {
+  const index = coded('index-invalid', (): OutputIndex => parseOutputIndex(readCanonicalJson(files.read('shard.json', limits.sourceBytes))));
+  const listed = new Set(['shard.json', 'validation.json']), { assets, keep } = assetStore(files.read, ports.readThrough === true);
+  const read: ReadListed = (entry): Uint8Array => coded('file-mismatch', (): Uint8Array => {
     listed.add(entry.path);
     const bytes = files.read(entry.path, entry.bytes);
     if (bytes.length !== entry.bytes || !verify(bytes, entry.hash, true)) throw new Error(`Output hash or size mismatch: ${entry.path}`);
     return bytes;
-  };
-  for (const entry of index.sections) { const value = readCanonicalJson(read(entry)); assertSectionSides(entry.name, value); validateOutputSection(entry.name, value); payloads.set(entry.name, value); } const warnings = assertScriptSides(payloads, index, { ...files, verify });
-  const scripts = scriptAdmissionRows(payloads), contracts = decisionModuleContracts(scripts, index.files);
+  });
+  const payloads = readSections(index, read), warnings = coded('script-side', (): string[] => assertScriptSides(payloads, index, { ...files, verify }));
+  const scripts = coded('script-admission', (): ScriptAdmissionRows => scriptAdmissionRows(payloads));
+  const contracts = coded('script-admission', (): ReturnType<typeof decisionModuleContracts> => decisionModuleContracts(scripts, index.files));
   for (const entry of index.files) {
     const bytes = read({ path: entry.path, hash: entry.hash, bytes: entry.compressed });
-    inspectBlob(entry, bytes, ports, entry.kind === 'wasm' ? contracts.get(entry.hash) ?? { abi: 0 } : undefined);
+    coded('blob-invalid', (): void => { inspectBlob(entry, bytes, ports, entry.kind === 'wasm' ? contracts.get(entry.hash) ?? { abi: 0 } : undefined); });
     keep(entry, bytes, index.requires.commons.includes(entry.hash));
   }
-  // J91: server files pass the same hash, size and schema checks; they stay out of the client's admitted assets
-  for (const entry of index.admission.server ?? []) {
-    const bytes = read(entry);
-    if (entry.kind === 'json') {
-      if (validatePlatformFile(entry.name, entry.schema, readCanonicalJson(bytes)) === undefined) throw new Error(`Unregistered named JSON: ${entry.name}`);
-    } else if (outputBlobKind('binary', bytes) !== entry.kind) throw new Error('Output blob bytes differ from their declared kind');
-  }
-  for (const [hash, cost] of Object.entries(index.ktx2Costs ?? {})) {
-    const bytes = assets.get(hash);
-    if (bytes === undefined || decoder().decode(validationSourceBytes(cost)) !== decoder().decode(validationSourceBytes(ktx2DeviceCosts(bytes)))) throw new Error('KTX2 device costs differ from verified bytes');
-  }
-  checkPacks(index, new Set(files.paths()), { readFile: files.read, readListed: read, verify, hash: ports.hash });
-  // C0 (J137): a mount passes the same hash and size checks as any listed file; nothing else may sit under `mounts/`.
-  const cook = index.cook === undefined ? undefined : readCookData(readCanonicalJson(read(index.cook)));
-  requireCookPreparation(index, cook, ports.hash);
-  if (cook !== undefined) {
-    for (const mount of cook.mounts) {
-      if (!mountSharesBlob(mount, index.files)) {
-        if (mount.path !== cookMountPath(mount.url)) { throw new Error(`Mount path differs from its URL: ${mount.url}`); }
-        read(mount);
-      }
-    }
-  }
+  checkServerAndKtx2(index, read, assets);
+  coded('pack-invalid', (): void => { checkPacks(index, new Set(files.paths()), { readFile: files.read, readListed: read, verify, hash: ports.hash }); });
+  const cook = readCook(index, read, ports.hash);
   for (const entry of index.runtime?.files ?? []) {
-    if (ports.runtimeImports === undefined) throw new Error('Copied runtime files need a runtime import checker');
-    ports.runtimeImports(entry.path, decoder().decode(read(entry)));
+    if (ports.runtimeImports === undefined) throw issueError('runtime-files', 'Copied runtime files need a runtime import checker');
+    coded('runtime-files', (): void => { ports.runtimeImports?.(entry.path, decoder().decode(read(entry))); });
   }
-  for (const path of files.paths()) if (!listed.has(path)) throw new Error(`Unlisted output file: ${path}`);
-  const shard = admitShardfileProduct(assembleOutputShardfile(index, payloads), assets, ports.hash, 'warn', scripts);
+  for (const path of files.paths()) if (!listed.has(path)) throw issueError('unlisted-file', `Unlisted output file: ${path}`);
+  const shard = admitShardfileProduct(coded('shard-schema', (): unknown => assembleOutputShardfile(index, payloads)), assets, ports.hash, 'warn', scripts);
   checkWorldTargets(shard, payloads.get('world/targets'));
-  if (ports.hash(validationSourceBytes(shard)) !== index.build.sourceHash) throw new Error('Output sections differ from the declared source hash');
+  if (ports.hash(validationSourceBytes(shard)) !== index.build.sourceHash) throw issueError('source-hash', 'Output sections differ from the declared source hash');
   return { index, shard, assets, sections: payloads, scripts, warnings, audio: productRecordings({ cook, read: files.read, shard, assets }) };
 }

package/src/format/tar-paths.ts

@@ -2,6 +2,7 @@
 // a hostile path never reaches a disk, on any host a shard is unpacked on.
 
 import { SHARDFILE_ADMISSION_LIMITS } from './admissionLimits.ts'
+import { archiveError } from './issue-codes.ts'
 
 // `tar -C product .` adds directories, and a shard adds `shard.json` and
 // `validation.json`, to the files its index may list.
@@ -57,7 +58,7 @@ function folded(path: string): string {
 }
 
 function clash(path: string): Error {
-  return new Error(`tar: both a file and a folder: ${path}`)
+  return archiveError(`tar: both a file and a folder: ${path}`)
 }
 
 function claimParents(
@@ -81,7 +82,7 @@ function claimParents(
 function claimFile(claims: Readonly<TarClaims>, path: string): void {
   const key = folded(path)
   if (claims.files.has(key)) {
-    throw new Error(`tar: duplicate entry ${path}`)
+    throw archiveError(`tar: duplicate entry ${path}`)
   }
   if (claims.folders.has(key)) {
     throw clash(path)