@wildshard/shard-format 0.4.5 → 0.4.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wildshard/shard-format",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "description": "The raw shardfile format: the spec, the validator and a validate CLI. The public, versioned contract every other repo builds on.",
   "license": "UNLICENSED",
   "repository": {
@@ -19,6 +19,7 @@
     "src/format/*.ts",
     "!src/format/*.test.ts",
     "src/format/memoryGates.json",
+    "src/tools/runtime-hosts.json",
     "packages/wire/src/net-command.ts",
     "src/cli/*.ts",
     "src/cli/*.mjs",
@@ -115,6 +116,7 @@
     "./eliteScripts": "./src/format/eliteScripts.ts",
     "./encounterRows": "./src/format/encounterRows.ts",
     "./encounters": "./src/format/encounters.ts",
+    "./engineMusic": "./src/format/engine-music.ts",
     "./entryClearance": "./src/format/entryClearance.ts",
     "./entryCoverage": "./src/format/entryCoverage.ts",
     "./entryGeometry": "./src/format/entryGeometry.ts",
@@ -161,6 +163,7 @@
     "./immutable": "./src/format/immutable.ts",
     "./inputDeclarations": "./src/format/inputDeclarations.ts",
     "./islandLibrary": "./src/format/islandLibrary.ts",
+    "./issue-codes": "./src/format/issue-codes.ts",
     "./items": "./src/format/items.ts",
     "./json": "./src/format/json.ts",
     "./keyedSky": "./src/format/keyedSky.ts",
@@ -182,6 +185,7 @@
     "./materials": "./src/format/materials.ts",
     "./memoryAdmission": "./src/format/memoryAdmission.ts",
     "./memoryGates.json": "./src/format/memoryGates.json",
+    "./runtime-hosts.json": "./src/tools/runtime-hosts.json",
     "./meshCollision": "./src/format/meshCollision.ts",
     "./meshCollisionAssets": "./src/format/meshCollisionAssets.ts",
     "./meshCollisionBytes": "./src/format/meshCollisionBytes.ts",

package/src/format/audio-rules.ts

@@ -1,5 +1,8 @@
+import { issueError } from './issue-codes.ts'
+
 import type { RecordingMeasure, RecordingRole } from './audio-measure.ts'
 import type { AudioWaiver } from './audio-waiver.ts'
+import type { IssueCodeOf } from './issue-codes.ts'
 
 // AUDIO AU5 (meta docs/plans/AUDIO-PLAN.md, J299): shardfile owns the audio
 // rules, and sharddev's `pack` and api-server's admission run this one check.
@@ -16,6 +19,8 @@ import type { AudioWaiver } from './audio-waiver.ts'
 type AudioLevel = 'green' | 'amber' | 'red'
 
 interface AudioFinding {
+  /** SHARD-AUTHORING SA41: the stable code (issue-codes.ts, docs/VALIDATION-CODES.md); `message` keeps its words. */
+  readonly code: IssueCodeOf<'audio'>
   readonly level: 'amber' | 'red'
   readonly rule: 'budget' | 'bitrate' | 'duration' | 'format' | 'waiver'
   readonly message: string
@@ -86,11 +91,16 @@ function formatProblem(
   const rate = String(row.sampleRate)
   if (row.codec === 'wav') {
     const message = `${row.url} is PCM WAV at ${rate} Hz; ship AAC-LC 48 kHz`
-    return { level: 'amber', rule: 'format', message }
+    return { code: 'audio-wav', level: 'amber', rule: 'format', message }
   }
   if (row.sampleRate !== AUDIO_RULES.sampleRate) {
     const message = `${row.url} is ${rate} Hz AAC; ship 48 kHz`
-    return { level: 'amber', rule: 'format', message }
+    return {
+      code: 'audio-sample-rate',
+      level: 'amber',
+      rule: 'format',
+      message,
+    }
   }
   return undefined
 }
@@ -99,11 +109,13 @@ function formatFinding(row: Readonly<RecordingMeasure>): AudioFinding[] {
   if (row.codec === 'unreadable') {
     const why = row.reason ?? 'unknown'
     const message = `${row.url} is not AAC-LC 48 kHz mono or stereo (${why})`
-    return [{ level: 'red', rule: 'format', message }]
+    return [{ code: 'audio-unreadable', level: 'red', rule: 'format', message }]
   }
   if (row.codec === 'aac' && row.reason !== undefined) {
     const message = `${row.url} is AAC outside the strict playback index (${row.reason})`
-    return [{ level: 'amber', rule: 'format', message }]
+    return [
+      { code: 'audio-strict-index', level: 'amber', rule: 'format', message },
+    ]
   }
   const problem = formatProblem(row)
   return problem === undefined ? [] : [problem]
@@ -114,7 +126,7 @@ function durationFinding(row: Readonly<RecordingMeasure>): AudioFinding[] {
     return []
   }
   const message = `${row.url} runs ${row.seconds.toFixed(ONE_DECIMAL)} s, over ${String(AUDIO_RULES.maxSeconds)} s`
-  return [{ level: 'red', rule: 'duration', message }]
+  return [{ code: 'audio-duration', level: 'red', rule: 'duration', message }]
 }
 
 function bitrateFinding(row: Readonly<RecordingMeasure>): AudioFinding[] {
@@ -124,7 +136,7 @@ function bitrateFinding(row: Readonly<RecordingMeasure>): AudioFinding[] {
   }
   const layout = row.channels === MONO ? 'mono' : 'stereo'
   const message = `${row.url} is ${row.kbps.toFixed(ONE_DECIMAL)} kbps ${layout} ${row.role}, over ${String(target)} kbps (+10%)`
-  return [{ level: 'amber', rule: 'bitrate', message }]
+  return [{ code: 'audio-bitrate', level: 'amber', rule: 'bitrate', message }]
 }
 
 function fileFindings(row: Readonly<RecordingMeasure>): AudioFinding[] {
@@ -156,17 +168,26 @@ function redBudget(input: Readonly<BudgetInput>): AudioFinding[] {
   const over = `${input.slug} holds ${mb(input.bytes)} of its own audio, over the ${mb(AUDIO_RULES.budgetRedBytes)} red line`
   const { waiver } = input
   if (waiver === undefined) {
-    return [{ level: 'red', rule: 'budget', message: over }]
+    return [
+      { code: 'audio-budget-red', level: 'red', rule: 'budget', message: over },
+    ]
   }
   const gap = waiverGap(waiver, input)
   if (gap === undefined) {
     const message = `${over}; waived until ${waiver.until} (${waiver.reason})`
-    return [{ level: 'amber', rule: 'budget', message }]
+    return [
+      { code: 'audio-budget-waived', level: 'amber', rule: 'budget', message },
+    ]
   }
   const named = `waiver for ${waiver.shard} until ${waiver.until} ${gap}`
   return [
-    { level: 'amber', rule: 'waiver', message: named },
-    { level: 'red', rule: 'budget', message: over },
+    {
+      code: 'audio-waiver-invalid',
+      level: 'amber',
+      rule: 'waiver',
+      message: named,
+    },
+    { code: 'audio-budget-red', level: 'red', rule: 'budget', message: over },
   ]
 }
 
@@ -178,7 +199,9 @@ function budgetFindings(input: Readonly<BudgetInput>): AudioFinding[] {
     return redBudget(input)
   }
   const message = `${input.slug} holds ${mb(input.bytes)} of its own audio, over the ${mb(AUDIO_RULES.budgetAmberBytes)} line`
-  return [{ level: 'amber', rule: 'budget', message }]
+  return [
+    { code: 'audio-budget-amber', level: 'amber', rule: 'budget', message },
+  ]
 }
 
 function levelOf(findings: readonly AudioFinding[]): AudioLevel {
@@ -255,7 +278,8 @@ function assertAudioAdmission(report: Readonly<AudioReport>): void {
     .filter((row: Readonly<AudioFinding>): boolean => row.level === 'red')
     .map((row: Readonly<AudioFinding>): string => row.message)
   if (red.length > NONE) {
-    throw new Error(
+    throw issueError(
+      'audio-refused',
       `Audio rules (AU5) refuse ${report.slug}: ${red.join('; ')}`,
     )
   }

package/src/format/contentBounds.ts

@@ -5,9 +5,10 @@ import memoryGates from './memoryGates.json' with { type: 'json' };
 export const CHUNK_SIZE = 500;        // metres, square
 /** Half a cell width in metres. */
 export const CHUNK_HALF: number = CHUNK_SIZE / 2;
-/** Signed placement radius of the finite platform catalogue (SF88); residency budgets stay independent. */
-export const GRID_RADIUS = 2;
-/** Number of placements, including open plots, in the finite square platform. */
+/** Signed placement radius of the finite platform catalogue (SF88): 7×7 since J314, J305's 5×5 at its centre and the
+ * outer ring void until a shard is placed there; residency budgets stay independent. */
+export const GRID_RADIUS = 3;
+/** Most placements, including open plots, the finite square platform holds; a grid may leave cells empty. */
 export const GRID_CELL_COUNT: number = (2 * GRID_RADIUS + 1) ** 2;
 /** Legal midpoint entry opening in metres. */
 export const ENTRY_WIDTH = 8;

package/src/format/grid-catalogue.ts

@@ -223,15 +223,16 @@ const gridShape = strictObject({
   emptyNeighbour,
 })
 
-/** Placement data, independent of package content and solo coordinates. */
+/** Placement data, independent of package content and solo coordinates. Since J314 a
+ * cell may stay empty: the void a new shard's first upload is placed into. */
 const GridCatalogueSchema: GenericSchema<GridCatalogueInput, GridCatalogue> =
   pipe(
     gridShape,
     check(
       // oxlint-disable-next-line typescript/prefer-readonly-parameter-types -- valibot's check takes the schema's own type
       (grid: InferOutput<typeof gridShape>): boolean =>
-        uniquePlaces(grid.cells) && grid.cells.length === GRID_CELL_COUNT,
-      'unique stable instance identities and complete signed cell layout',
+        uniquePlaces(grid.cells),
+      'unique stable instance identities and cells',
     ),
   )
 

package/src/format/issue-codes.ts

@@ -0,0 +1,262 @@
+// SHARD-AUTHORING SA41 (SA21's follow-up, J317 Q19): every issue shard-format reports carries a stable `code`, so a
+// consumer (sharddev's refusal table, api-server) matches the code instead of the message's words. This is the one
+// table; docs/VALIDATION-CODES.md is generated from it (`node src/tools/validation-codes.ts write`) and a test fails when
+// the page drifts. A code is stable: rename one only with a release note, since consumers match it. Messages are not
+// part of the contract and keep their words.
+//
+// Where the code is:
+// - a validator refusal (`validateShardfileProduct`, `validateShardfileStream`, `readTar`): `error.code` on the thrown
+//   Error, its message unchanged. The validators tag by the check that refused; a more specific code set nearer the
+//   throw wins. A code that is not the table's (Node's `ENOENT` from a host's file port,
+//   `ERR_ENCODING_INVALID_ENCODED_DATA` from bad UTF-8) is replaced: such codes differ by host, and the message keeps
+//   its words.
+// - a performance report issue: `PerformanceIssue.code`.
+// - an audio finding: `AudioFinding.code`; `assertAudioAdmission`'s refusal: `error.code`.
+
+// Validate: both validators, the same code for the same refusal.
+const VALIDATE_CODES = {
+  'archive-invalid':
+    'The tarball is not strict ustar (a bad header, path, padding or end, a truncated entry, too many entries), or the stored object does not decode.',
+  'index-invalid':
+    '`shard.json` is missing, too large, not canonical JSON, or fails the index schema.',
+  'file-mismatch':
+    'A listed file is missing, unreadable (a symlink, not a regular file), larger than declared, or its hash or size differs.',
+  'section-invalid':
+    'A section is not canonical JSON, fails its section schema, or is a `client/plan` kind with no declared side.',
+  'script-side':
+    'A script runs on a side its declaration does not allow (SERVER-PARITY SS7).',
+  'script-admission':
+    'The script admission rows the sections declare are invalid.',
+  'blob-invalid':
+    "A blob's bytes contradict its listing: kind or extension, registered named JSON and its schema, or costs understated.",
+  'server-file-invalid':
+    'A server file (J91) is unregistered named JSON or its bytes differ from its declared kind.',
+  'ktx2-costs':
+    'The declared KTX2 device costs differ from the verified bytes.',
+  'pack-invalid':
+    "A pack is missing a member, or a member or the pack's hash differs.",
+  'cook-invalid':
+    'The cook file, its preparation, or a mount (path or bytes) is invalid (C0, J137).',
+  'runtime-files':
+    'Copied runtime files are present without a runtime import checker, or fail it.',
+  'unlisted-file': 'A file in the product is not listed in `shard.json`.',
+  'shard-schema':
+    'The shardfile assembled from the sections fails the shardfile schema.',
+  'declared-costs':
+    'The declared costs fail preflight: a budget or memory admission over its limit.',
+  'performance-targets':
+    'A declared performance target over its limit refuses (the `REFUSAL:` lines).',
+  'asset-admission':
+    "An asset's bytes fail admission: parse, hash or wire size, costs, bounds or script contract.",
+  'world-targets':
+    '`world/targets` names an item or quest the shardfile does not declare.',
+  'source-hash': 'The sections differ from the declared `build.sourceHash`.',
+} as const
+
+// Stream: the streaming validator's own refusals, beside the validate codes it shares.
+const STREAM_CODES = {
+  'stream-cap':
+    'A member, pack or the placed assets are over the streaming cap.',
+  'stream-miss': 'A check asked for bytes the stream did not hold (AC6a2).',
+  'stream-changed': 'The stored object changed between its reads.',
+} as const
+
+// Performance: `PerformanceIssue.code`.
+const PERFORMANCE_CODES = {
+  'perf-memory-target':
+    'A resident memory target (tradeable) is over; always a warning.',
+  'perf-library-download-budget':
+    'The declared library download budget is over the allowance.',
+  'perf-critical-download-budget':
+    'The declared critical (sim) download budget is over its limit.',
+  'perf-library-download':
+    "The library closure's download bytes are over the allowance.",
+  'perf-critical-download':
+    "The critical closure's download bytes are over the limit.",
+  'perf-tile-download':
+    "A tile's download bytes are over its LOD cap (provisional: a warning).",
+  'perf-tile-draws':
+    "A tile's draws are over its LOD cap (provisional: a warning).",
+  'perf-tile-triangles':
+    "A tile's triangles are over its LOD cap (provisional: a warning).",
+  'perf-far-download': "The far view's download bytes are over the limit.",
+  'perf-far-draws': "The far view's draws are over the limit.",
+  'perf-far-triangles': "The far view's triangles are over the limit.",
+  'perf-native-view-unmeasured':
+    'Native view and download measurement is required and missing.',
+  'perf-native-resident-unmeasured':
+    'The native runtime declares no measured resident cost.',
+  'perf-playing-memory':
+    'The worst playing total bytes are over the limit (report-only under G433: a warning).',
+  'perf-loading-memory':
+    'The worst loading total bytes are over the limit (report-only under G433: a warning).',
+  'perf-script-sample-invalid':
+    'A measured script or fuel figure is not a finite, non-negative number.',
+  'perf-script-cpu': 'Script CPU p95 per tick is over the limit.',
+  'perf-script-fuel': 'Script fuel per tick is over the limit.',
+  'perf-script-samples-missing': 'Fewer than 60 measured script or fuel ticks.',
+} as const
+
+// Audio (AUDIO AU5): `AudioFinding.code`, and the admission refusal.
+const AUDIO_CODES = {
+  'audio-unreadable':
+    'A recording is not readable as AAC-LC 48 kHz mono or stereo (red).',
+  'audio-strict-index':
+    'A recording is AAC outside the strict playback index (amber).',
+  'audio-wav': 'A recording is PCM WAV; ship AAC-LC 48 kHz (amber).',
+  'audio-sample-rate':
+    'A recording is AAC at a sample rate other than 48 kHz (amber).',
+  'audio-duration': 'A recording runs over the maximum seconds (red).',
+  'audio-bitrate':
+    "A recording's bitrate is over its role and channel cap plus slack (amber).",
+  'audio-budget-amber':
+    "The shard's own audio bytes are over the amber line (amber).",
+  'audio-budget-red':
+    "The shard's own audio bytes are over the red line, with no waiver that holds (red).",
+  'audio-budget-waived': 'Over the red line, but a dated waiver holds (amber).',
+  'audio-waiver-invalid':
+    'The waiver names another shard, has expired, or covers fewer bytes (amber; the red budget finding follows).',
+  'audio-refused':
+    '`assertAudioAdmission` refuses a report with a red finding.',
+} as const
+
+/** Which report a code appears in. */
+type IssueFamily = 'validate' | 'stream' | 'performance' | 'audio'
+
+/** Every family's codes and what each means, in table order. */
+const ISSUE_FAMILIES: {
+  readonly validate: typeof VALIDATE_CODES
+  readonly stream: typeof STREAM_CODES
+  readonly performance: typeof PERFORMANCE_CODES
+  readonly audio: typeof AUDIO_CODES
+} = {
+  validate: VALIDATE_CODES,
+  stream: STREAM_CODES,
+  performance: PERFORMANCE_CODES,
+  audio: AUDIO_CODES,
+}
+
+/** The codes of one family. */
+type IssueCodeOf<Family extends IssueFamily> = Family extends IssueFamily
+  ? keyof (typeof ISSUE_FAMILIES)[Family]
+  : never
+/** A stable issue code. */
+type IssueCode = IssueCodeOf<IssueFamily>
+
+/** One row of the table. */
+interface IssueCodeRow {
+  readonly code: IssueCode
+  readonly family: IssueFamily
+  readonly meaning: string
+}
+
+/** A key of a family's own table, as the code it is. */
+// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- only ever given the keys of ISSUE_FAMILIES' tables
+const asCode = (code: string): IssueCode => code as IssueCode
+
+const FAMILY_ORDER: readonly IssueFamily[] = [
+  'validate',
+  'stream',
+  'performance',
+  'audio',
+]
+const ROWS: readonly IssueCodeRow[] = FAMILY_ORDER.flatMap(
+  (family: IssueFamily): IssueCodeRow[] => {
+    const table: Readonly<Record<string, string>> = ISSUE_FAMILIES[family]
+    return Object.entries(table).map(
+      ([code, meaning]: readonly [string, string]): IssueCodeRow => ({
+        code: asCode(code),
+        family,
+        meaning,
+      }),
+    )
+  },
+)
+const KNOWN: ReadonlySet<string> = new Set(
+  ROWS.map((row: IssueCodeRow): string => row.code),
+)
+
+/** Every code, in table order. */
+function issueCodeRows(): readonly IssueCodeRow[] {
+  return ROWS
+}
+
+/** Whether a string is one of the table's codes. */
+function isIssueCode(value: unknown): value is IssueCode {
+  return typeof value === 'string' && KNOWN.has(value)
+}
+
+/** The issue code an error carries, if it is one of the table's. */
+function issueCodeOf(error: unknown): IssueCode | undefined {
+  const code: unknown =
+    typeof error === 'object' && error !== null && 'code' in error
+      ? error.code
+      : undefined
+  return isIssueCode(code) ? code : undefined
+}
+
+/** Give `error` this code unless it already carries one of the table's (a nearer tag); returns it. An own property, so a
+ *  read-only `code` getter (a DOMException's) is shadowed rather than thrown on; an error that refuses even that (frozen)
+ *  is returned untouched, never replaced. */
+function tagIssue(error: unknown, code: IssueCode): unknown {
+  if (error instanceof Error && issueCodeOf(error) === undefined) {
+    try {
+      Object.defineProperty(error, 'code', {
+        value: code,
+        writable: true,
+        enumerable: true,
+        configurable: true,
+      })
+    } catch {
+      // A frozen error keeps its own shape; the refusal still surfaces with its words.
+    }
+  }
+  return error
+}
+
+/** A new Error with this message and code. */
+function issueError(
+  code: IssueCode,
+  message: string,
+): Error & { readonly code: IssueCode } {
+  return Object.assign(new Error(message), { code })
+}
+
+/** A tarball framing refusal (`tar: ...`): `archive-invalid`. */
+function archiveError(message: string): Error & { readonly code: IssueCode } {
+  return issueError('archive-invalid', message)
+}
+
+/** Run one check; a refusal it throws carries `code` unless it already has one of the table's. */
+function withIssueCode<Result>(code: IssueCode, run: () => Result): Result {
+  try {
+    return run()
+  } catch (error) {
+    throw tagIssue(error, code)
+  }
+}
+
+/** `withIssueCode` for an async check. */
+async function withIssueCodeAsync<Result>(
+  code: IssueCode,
+  run: () => Promise<Result>,
+): Promise<Result> {
+  try {
+    return await run()
+  } catch (error) {
+    throw tagIssue(error, code)
+  }
+}
+
+export type { IssueCode, IssueCodeOf, IssueCodeRow, IssueFamily }
+export {
+  ISSUE_FAMILIES,
+  archiveError,
+  isIssueCode,
+  issueCodeOf,
+  issueCodeRows,
+  issueError,
+  tagIssue,
+  withIssueCode,
+  withIssueCodeAsync,
+}

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

@@ -8,6 +8,7 @@ import {
   assetAdmission,
   preflightDeclaredCosts,
 } from './assetAdmission.ts'
+import { issueError, withIssueCode } from './issue-codes.ts'
 import { assembleOutputShardfile } from './outputIndex.ts'
 import { offlineMemoryAdmission } from './product.ts'
 import { assertProductTargets, checkWorldTargets } from './productValidation.ts'
@@ -26,9 +27,15 @@ function admitHead(
   index: OutputIndex,
   payloads: ReadonlyMap<string, unknown>,
 ): Shardfile {
-  const shard = parseShardfile(assembleOutputShardfile(index, payloads))
-  preflightDeclaredCosts(shard, offlineMemoryAdmission('warn'))
-  assertProductTargets(shard, 'warn')
+  const shard = withIssueCode('shard-schema', (): Shardfile =>
+    parseShardfile(assembleOutputShardfile(index, payloads)),
+  )
+  withIssueCode('declared-costs', (): void => {
+    preflightDeclaredCosts(shard, offlineMemoryAdmission('warn'))
+  })
+  withIssueCode('performance-targets', (): void => {
+    assertProductTargets(shard, 'warn')
+  })
   return shard
 }
 
@@ -44,7 +51,9 @@ function admitBeforeAssets(
   try {
     const head = admitHead(index, payloads)
     return {
-      admission: assetAdmission(head, offlineMemoryAdmission('warn'), scripts),
+      admission: withIssueCode('asset-admission', (): AssetAdmission =>
+        assetAdmission(head, offlineMemoryAdmission('warn'), scripts),
+      ),
       refusal: undefined,
     }
   } catch (error) {
@@ -63,18 +72,20 @@ function admitAssets(
   if (admission === undefined) {
     throw before.refusal
   }
-  admitCommonsBytes(admission, later.assets, hash)
-  const refused = later.fileErrors.find(
-    (error: string | undefined): boolean => error !== undefined,
-  )
-  if (refused !== undefined) {
-    throw new Error(refused)
-  }
-  return admitAfterFiles(
-    admission,
-    later.assets,
-    offlineMemoryAdmission('warn'),
-  )
+  return withIssueCode('asset-admission', (): Shardfile => {
+    admitCommonsBytes(admission, later.assets, hash)
+    const refused = later.fileErrors.find(
+      (error: string | undefined): boolean => error !== undefined,
+    )
+    if (refused !== undefined) {
+      throw new Error(refused)
+    }
+    return admitAfterFiles(
+      admission,
+      later.assets,
+      offlineMemoryAdmission('warn'),
+    )
+  })
 }
 
 /** `validateShardfileProduct`'s steps after the assets: the world targets and the source hash. */
@@ -93,7 +104,10 @@ function admitTail(
     product.hash(validationSourceBytes(shard)) !==
     product.index.build.sourceHash
   ) {
-    throw new Error('Output sections differ from the declared source hash')
+    throw issueError(
+      'source-hash',
+      'Output sections differ from the declared source hash',
+    )
   }
 }
 

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

@@ -13,6 +13,7 @@
 // (product-stream-packs.ts).
 
 import { admitFileBytes } from './assetAdmission.ts'
+import { issueError, withIssueCodeAsync } from './issue-codes.ts'
 import { StreamMissError } from './product-stream-miss.ts'
 import { packGroups, packPass } from './product-stream-packs.ts'
 import { walkTar } from './product-stream-tar.ts'
@@ -327,7 +328,10 @@ function streamedMember(
 ): void {
   state.seen += NEXT
   if (state.plan.members.get(path)?.sha !== found.sha) {
-    throw new Error('stream: the stored object changed between reads')
+    throw issueError(
+      'stream-changed',
+      'stream: the stored object changed between reads',
+    )
   }
   const { bytes } = found
   if (bytes !== undefined) {
@@ -366,7 +370,10 @@ async function oneRead(
     },
   })
   if (state.seen !== plan.members.size) {
-    throw new Error('stream: the stored object changed between reads')
+    throw issueError(
+      'stream-changed',
+      'stream: the stored object changed between reads',
+    )
   }
   return { peak: state.peak, verdicts: packs.finish() }
 }
@@ -411,7 +418,10 @@ function placedPaths(
     }
   }
   if (bytes > PLACED_HOLD_CAP) {
-    throw new Error('stream: the placed assets are over the streaming cap')
+    throw issueError(
+      'stream-cap',
+      'stream: the placed assets are over the streaming cap',
+    )
   }
   return keep
 }
@@ -442,9 +452,8 @@ function assetPlan(base: AssetPassInput): AssetPlan {
   }
 }
 
-/** The later reads: the asset checks and carried packs with the first group of left-out packs, then one read per
- *  further group. Without an admission (the shard failed before its bytes), only the packs. */
-async function assetPasses(base: AssetPassInput): Promise<AssetPasses> {
+/** `assetPasses`, before its refusals take `pack-invalid`. */
+async function passes(base: AssetPassInput): Promise<AssetPasses> {
   const plan = assetPlan(base)
   const order = [...plan.members.keys()]
   const sizes = new Map(
@@ -489,5 +498,14 @@ async function assetPasses(base: AssetPassInput): Promise<AssetPasses> {
   }
 }
 
+/** The later reads: the asset checks and carried packs with the first group of left-out packs, then one read per
+ *  further group. Without an admission (the shard failed before its bytes), only the packs. */
+async function assetPasses(base: AssetPassInput): Promise<AssetPasses> {
+  return await withIssueCodeAsync(
+    'pack-invalid',
+    async (): Promise<AssetPasses> => await passes(base),
+  )
+}
+
 export type { AssetPassInput, AssetPasses, StoredSource }
 export { assetPasses }

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

@@ -3,6 +3,9 @@
 // check, and the corpus and pin tests prove no check does.
 
 class StreamMissError extends Error {
+  /** SHARD-AUTHORING SA41: the issue code (issue-codes.ts). */
+  public readonly code = 'stream-miss'
+
   public constructor(message: string) {
     super(message)
     this.name = 'StreamMissError'

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

@@ -8,6 +8,8 @@
 // The packs are split into groups whose held bytes stay under a cap, and
 // each group takes its own read of the stored object.
 
+import { issueError } from './issue-codes.ts'
+
 import type { OutputIndex } from './outputIndex.ts'
 import type { StreamHasher } from './product-stream-tar.ts'
 
@@ -132,7 +134,10 @@ function packGroups(
         group.length === NEXT &&
         heldPeak([entryPaths(pack, paths)], order, sizes) > PACK_HOLD_CAP
       ) {
-        throw new Error(`stream: a pack over the streaming cap: ${pack.path}`)
+        throw issueError(
+          'stream-cap',
+          `stream: a pack over the streaming cap: ${pack.path}`,
+        )
       }
     }
   }