@wildshard/shard-format 0.0.1 → 0.4.5

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

@@ -0,0 +1,493 @@
+// oxlint-disable eslint/max-lines, eslint/max-statements, typescript/prefer-readonly-parameter-types -- the old validator's steps in its order, over reads that share state; the state is only read but for the held maps
+// `validateShardfileAssets`' byte checks and `checkPacks` over a second read
+// of the stored object (API-CLOUDFLARE AC6a2). The first read (product-
+// stream.ts) found the index; this one runs `admitFileBytes` on each listed
+// file as it streams past, in tarball order, and keeps each refusal as its
+// message until `validateShardfileAssets` would have thrown it (its files'
+// order). It holds only the files a later check reads by hash: those the
+// shard names outside its inventory lists (props, terrain, navigation,
+// collision, entryways, near, skins, sketches, recordings, commons). JSON and
+// Wasm stay from the first read. A later check that asks for any other file
+// is refused, never answered from a guess (StreamMissError): the corpus and pin
+// tests prove no check does. Packs the reads' groups need come with them
+// (product-stream-packs.ts).
+
+import { admitFileBytes } from './assetAdmission.ts'
+import { StreamMissError } from './product-stream-miss.ts'
+import { packGroups, packPass } from './product-stream-packs.ts'
+import { walkTar } from './product-stream-tar.ts'
+
+import type { AssetAdmission } from './assetAdmission.ts'
+import type { OutputIndex } from './outputIndex.ts'
+import type { PackPass, PackVerdicts } from './product-stream-packs.ts'
+import type { KeptMember } from './product-stream-rows.ts'
+import type { StreamHasher, StreamMember } from './product-stream-tar.ts'
+
+/** A stored object to read again: each call opens a fresh stream from its start. */
+type StoredSource = () =>
+  | AsyncIterable<Uint8Array>
+  | Promise<AsyncIterable<Uint8Array>>
+
+interface AssetPassPorts {
+  readonly hash: (bytes: Readonly<Uint8Array>) => string
+  readonly hasher: () => StreamHasher
+  readonly decode?: (
+    stored: AsyncIterable<Uint8Array>,
+  ) => AsyncIterable<Uint8Array>
+}
+
+/** What the later reads found. */
+interface AssetPasses {
+  /** By `shard.files` row: the refusal `admitFileBytes` gave, if any. */
+  readonly fileErrors: readonly (string | undefined)[]
+  /** By pack path: the refusal `checkPacks` would give for it, if any. */
+  readonly packs: PackVerdicts
+  /** The admitted bytes by asset key for the checks after the files. */
+  readonly assets: ReadonlyMap<string, Uint8Array>
+  /** The most member bytes any later read held, the first read's kept files included. */
+  readonly heldBytes: number
+  /** The reads taken after the first. */
+  readonly reads: number
+}
+
+const NONE = 0
+const NEXT = 1
+/** The most bytes the reads keep for the checks after the files: the first read's kept files and the placed assets. */
+const PLACED_HOLD_CAP = 48_000_000
+const HASH = /^(?:commons:)?[0-9a-f]{64}$/u
+/** Keys under the placed roots whose hashes list files no later check reads by hash: the inventory lists, and prop
+ *  library models, textures and materials (`admitFileBytes` reads those while their own GLB streams). */
+const SKIPPED_KEYS: ReadonlySet<string> = new Set([
+  'files',
+  'library',
+  'critical',
+  'dependencies',
+  'materials',
+  'models',
+  'splat',
+  'textures',
+])
+
+/** Each asset key's tarball path: `replayFiles`' map, the last listed row of a key winning. */
+function assetPaths(
+  // oxlint-disable-next-line typescript/prefer-readonly-parameter-types -- valibot's output type, only read
+  index: OutputIndex,
+): Map<string, string> {
+  const paths = new Map<string, string>()
+  for (const entry of index.files) {
+    paths.set(
+      `${entry.commons === true ? 'commons:' : ''}${entry.hash}`,
+      entry.path,
+    )
+    if (index.requires.commons.includes(entry.hash)) {
+      paths.set(`commons:${entry.hash}`, entry.path)
+    }
+  }
+  return paths
+}
+
+/** The parts of a shard whose hashes the checks after the files read: recordings, skin looks, sketches, navigation,
+ *  native ground, terrain, collision, props, near content, entryways and the commons. */
+function placedRoots(shard: Readonly<AssetAdmission['shard']>): unknown[] {
+  return [
+    shard.audio.recordings,
+    shard.rows.looks,
+    shard.rows.compendiums,
+    shard.navigation,
+    shard.nativeGround,
+    shard.terrain,
+    shard.meshCollision,
+    shard.props,
+    shard.near,
+    shard.entryways,
+    shard.requires.commons.map((hash: string): string => `commons:${hash}`),
+  ]
+}
+
+/** A string's asset keys, bare or as a pinned commons. */
+function hashKeys(value: string, paths: ReadonlyMap<string, string>): string[] {
+  if (!HASH.test(value)) {
+    return []
+  }
+  return [value, `commons:${value}`].filter((key: string): boolean =>
+    paths.has(key),
+  )
+}
+
+/** Every asset key named under `value`, skipping `SKIPPED_KEYS`. */
+function namedKeys(
+  value: unknown,
+  paths: ReadonlyMap<string, string>,
+): string[] {
+  if (typeof value === 'string') {
+    return hashKeys(value, paths)
+  }
+  if (Array.isArray(value)) {
+    return value.flatMap((item: unknown): string[] => namedKeys(item, paths))
+  }
+  if (typeof value !== 'object' || value === null) {
+    return []
+  }
+  return Object.entries(value).flatMap(
+    ([key, item]: readonly [string, unknown]): string[] =>
+      SKIPPED_KEYS.has(key) ? [] : namedKeys(item, paths),
+  )
+}
+
+/** The placed keys, and the listed dependencies of the JSON among them (a skin file names its GLB; Codex review). */
+function placedKeys(
+  shard: Readonly<AssetAdmission['shard']>,
+  paths: ReadonlyMap<string, string>,
+): Set<string> {
+  const rows = new Map(
+    shard.files.map(
+      (
+        row: Readonly<AssetAdmission['shard']['files'][number]>,
+      ): readonly [
+        string,
+        Readonly<AssetAdmission['shard']['files'][number]>,
+      ] => [row.hash, row] as const,
+    ),
+  )
+  const keys = new Set(namedKeys(placedRoots(shard), paths))
+  for (const key of keys) {
+    const row = rows.get(key)
+    if (row?.kind === 'json') {
+      for (const dependency of row.dependencies) {
+        for (const found of hashKeys(dependency, paths)) {
+          keys.add(found)
+        }
+      }
+    }
+  }
+  return keys
+}
+
+/** Where the stream holds a file's bytes for the checks. */
+interface AssetSources {
+  readonly paths: ReadonlyMap<string, string>
+  readonly members: ReadonlyMap<string, KeptMember>
+  readonly held: ReadonlyMap<string, Readonly<Uint8Array>>
+  readonly current: () => Current | undefined
+}
+
+/** The file streaming past now. */
+interface Current {
+  readonly path: string
+  readonly bytes: Readonly<Uint8Array>
+}
+
+/** The admitted bytes as `validateShardfileAssets` reads them: by key, from what the reads held. */
+class StreamAssets extends Map<string, Uint8Array> {
+  private readonly sources: AssetSources
+
+  public constructor(sources: AssetSources) {
+    super()
+    this.sources = sources
+    // `for…of` must refuse too; an own property keeps the emitted declaration plain (no computed member).
+    Object.defineProperty(this, Symbol.iterator, {
+      value: (): never => {
+        throw this.walked()
+      },
+    })
+  }
+
+  public override get size(): number {
+    return this.sources.paths.size
+  }
+
+  public override get(key: string): Uint8Array | undefined {
+    const path = this.sources.paths.get(key)
+    if (path === undefined) {
+      return undefined
+    }
+    const now = this.sources.current()
+    const bytes =
+      this.sources.members.get(path)?.bytes ??
+      this.sources.held.get(path) ??
+      (now?.path === path ? now.bytes : undefined)
+    if (bytes === undefined) {
+      throw new StreamMissError(
+        `stream: an asset check read ${key}, which the stream did not hold`,
+      )
+    }
+    return bytes
+  }
+
+  public override has(key: string): boolean {
+    return this.sources.paths.has(key)
+  }
+
+  public override keys(): MapIterator<string> {
+    return this.sources.paths.keys()
+  }
+
+  public override values(): MapIterator<Uint8Array> {
+    throw this.walked()
+  }
+
+  public override entries(): MapIterator<[string, Uint8Array]> {
+    throw this.walked()
+  }
+
+  public override forEach(): void {
+    throw this.walked()
+  }
+
+  private walked(): StreamMissError {
+    return new StreamMissError(
+      `stream: an asset check walked all ${String(this.sources.paths.size)} assets`,
+    )
+  }
+}
+
+function message(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+/** What the later reads start from: the opener, the ports, the first read and the index. */
+interface AssetPassInput {
+  readonly open: StoredSource
+  readonly ports: AssetPassPorts
+  readonly members: ReadonlyMap<string, KeptMember>
+  readonly keptBytes: number
+  readonly index: OutputIndex
+  readonly admission: AssetAdmission | undefined
+}
+
+/** What the later reads need, worked out from the first read and the index. */
+interface AssetPlan {
+  readonly open: StoredSource
+  readonly ports: AssetPassPorts
+  readonly members: ReadonlyMap<string, KeptMember>
+  readonly keptBytes: number
+  readonly index: OutputIndex
+  readonly admission: AssetAdmission | undefined
+  readonly assets: StreamAssets
+  readonly held: Map<string, Readonly<Uint8Array>>
+  readonly setCurrent: (current: Current | undefined) => void
+  readonly fileErrors: (string | undefined)[]
+  readonly rowsByPath: ReadonlyMap<string, readonly number[]>
+  readonly keep: ReadonlySet<string>
+}
+
+/** One later read's state. */
+interface ReadState {
+  readonly plan: AssetPlan
+  readonly packs: PackPass
+  readonly withAssets: boolean
+  seen: number
+  peak: number
+}
+
+/** `admitFileBytes` on each listed row whose bytes stream past; a refusal kept as its message. */
+function admitStreamed(
+  plan: AssetPlan,
+  path: string,
+  bytes: Readonly<Uint8Array>,
+): void {
+  const { admission } = plan
+  if (admission === undefined) {
+    return
+  }
+  plan.setCurrent({ path, bytes })
+  for (const at of plan.rowsByPath.get(path) ?? []) {
+    const row = admission.shard.files[at]
+    try {
+      if (row !== undefined) {
+        admitFileBytes(admission, row, bytes, plan.assets, plan.ports.hash)
+      }
+    } catch (error) {
+      if (error instanceof StreamMissError) {
+        throw error
+      }
+      plan.fileErrors[at] = message(error)
+    }
+  }
+  plan.setCurrent(undefined)
+  if (plan.keep.has(path)) {
+    plan.held.set(path, bytes)
+  }
+}
+
+/** The bytes held for the placed checks so far. */
+function heldTotal(held: ReadonlyMap<string, Readonly<Uint8Array>>): number {
+  let total = NONE
+  for (const bytes of held.values()) {
+    total += bytes.length
+  }
+  return total
+}
+
+/** One member of a later read: the same bytes as the first read, then its checks. */
+function streamedMember(
+  state: ReadState,
+  path: string,
+  found: Readonly<{ sha: string; bytes: Uint8Array | undefined }>,
+): void {
+  state.seen += NEXT
+  if (state.plan.members.get(path)?.sha !== found.sha) {
+    throw new Error('stream: the stored object changed between reads')
+  }
+  const { bytes } = found
+  if (bytes !== undefined) {
+    state.peak = Math.max(
+      state.peak,
+      state.plan.keptBytes +
+        heldTotal(state.plan.held) +
+        state.packs.held() +
+        bytes.length,
+    )
+    if (state.withAssets) {
+      admitStreamed(state.plan, path, bytes)
+    }
+    state.packs.member(path, bytes)
+  }
+}
+
+/** One later read of the stored object. */
+async function oneRead(
+  plan: AssetPlan,
+  packs: PackPass,
+  withAssets: boolean,
+): Promise<Readonly<{ peak: number; verdicts: PackVerdicts }>> {
+  const state: ReadState = { plan, packs, withAssets, seen: NONE, peak: NONE }
+  const wants = new Set([
+    ...packs.wants,
+    ...(withAssets ? [...plan.rowsByPath.keys(), ...plan.keep] : []),
+  ])
+  const source = await plan.open()
+  const { decode } = plan.ports
+  await walkTar(decode === undefined ? source : decode(source), {
+    hasher: plan.ports.hasher,
+    wants: (path: string): boolean => wants.has(path),
+    member: (path: string, found: Readonly<StreamMember>): void => {
+      streamedMember(state, path, found)
+    },
+  })
+  if (state.seen !== plan.members.size) {
+    throw new Error('stream: the stored object changed between reads')
+  }
+  return { peak: state.peak, verdicts: packs.finish() }
+}
+
+/** The listed rows by tarball path; a row with no file is refused now, as `admitFileBytes` refuses it. */
+function rowsAtPaths(
+  admission: AssetAdmission | undefined,
+  paths: ReadonlyMap<string, string>,
+  fileErrors: (string | undefined)[],
+): Map<string, number[]> {
+  const rowsByPath = new Map<string, number[]>()
+  for (const [at, row] of (admission?.shard.files ?? []).entries()) {
+    const path = paths.get(row.hash)
+    if (path === undefined) {
+      fileErrors[at] = 'file hash or wire size mismatch'
+    } else {
+      rowsByPath.set(path, [...(rowsByPath.get(path) ?? []), at])
+    }
+  }
+  return rowsByPath
+}
+
+/** The placed files to hold (those the first read did not keep), refusing a set over `PLACED_HOLD_CAP`. */
+function placedPaths(
+  first: Readonly<{
+    members: ReadonlyMap<string, KeptMember>
+    keptBytes: number
+  }>,
+  admission: AssetAdmission | undefined,
+  paths: ReadonlyMap<string, string>,
+): Set<string> {
+  const keep = new Set<string>()
+  let bytes = first.keptBytes
+  for (const key of admission === undefined
+    ? []
+    : placedKeys(admission.shard, paths)) {
+    const path = paths.get(key) ?? ''
+    const member = first.members.get(path)
+    if (member !== undefined && member.bytes === undefined && !keep.has(path)) {
+      keep.add(path)
+      bytes += member.size
+    }
+  }
+  if (bytes > PLACED_HOLD_CAP) {
+    throw new Error('stream: the placed assets are over the streaming cap')
+  }
+  return keep
+}
+
+/** The plan for the later reads. */
+function assetPlan(base: AssetPassInput): AssetPlan {
+  const paths = assetPaths(base.index)
+  const held = new Map<string, Readonly<Uint8Array>>()
+  let current: Current | undefined = undefined
+  const fileErrors = (base.admission?.shard.files ?? []).map(
+    (): undefined => undefined,
+  ) as (string | undefined)[]
+  return {
+    ...base,
+    assets: new StreamAssets({
+      paths,
+      members: base.members,
+      held,
+      current: (): Current | undefined => current,
+    }),
+    held,
+    setCurrent: (now: Current | undefined): void => {
+      current = now
+    },
+    fileErrors,
+    rowsByPath: rowsAtPaths(base.admission, paths, fileErrors),
+    keep: placedPaths(base, base.admission, paths),
+  }
+}
+
+/** 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> {
+  const plan = assetPlan(base)
+  const order = [...plan.members.keys()]
+  const sizes = new Map(
+    order.map((path: string): [string, number] => [
+      path,
+      plan.members.get(path)?.size ?? NONE,
+    ]),
+  )
+  const present = new Set(order)
+  const carried = (plan.index.packs ?? []).filter(
+    (pack: Readonly<{ path: string }>): boolean => present.has(pack.path),
+  )
+  const groups = packGroups(plan.index, present, order, sizes)
+  const needed =
+    plan.admission === undefined && carried.length === NONE ? NONE : NEXT
+  const verdicts: PackVerdicts = new Map()
+  let heldBytes = plan.keptBytes
+  const reads = Math.max(groups.length, needed)
+  for (let read = NONE; read < reads; read += NEXT) {
+    const packs = packPass(
+      plan.index,
+      { carried: read === NONE ? carried : [], group: groups[read] ?? [] },
+      plan.ports,
+    )
+    // oxlint-disable-next-line eslint/no-await-in-loop -- one read at a time is the memory bound
+    const found = await oneRead(
+      plan,
+      packs,
+      read === NONE && plan.admission !== undefined,
+    )
+    heldBytes = Math.max(heldBytes, found.peak)
+    for (const [path, verdict] of found.verdicts) {
+      verdicts.set(path, verdict)
+    }
+  }
+  return {
+    fileErrors: plan.fileErrors,
+    packs: verdicts,
+    assets: plan.assets,
+    heldBytes,
+    reads,
+  }
+}
+
+export type { AssetPassInput, AssetPasses, StoredSource }
+export { assetPasses }

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

@@ -0,0 +1,208 @@
+// What `inspectBlob` reads from a blob's bytes, taken while the blob streams
+// (API-CLOUDFLARE AC6a). A tarball is sorted (J60), so its blobs pass before
+// `shard.json` names their declared kinds and costs: the stream keeps these
+// facts, drops the bytes, and replays `inspectBlob` once the index is read.
+// A parser's refusal is kept as its message only: a live Error can hold its
+// blob through the stack it captured (Codex review, AC6a).
+
+import { parseNamedJson } from './json.ts'
+import { ktx2DeviceCosts } from './ktx2Cost.ts'
+import { validatePlatformFile } from './platformFileFamilies.ts'
+import { assetCost } from './product.ts'
+import { outputBlobExtension, outputBlobKind } from './productValidation.ts'
+import {
+  registeredJsonContract,
+  validateRegisteredJson,
+} from './registeredJson.ts'
+import { validationSourceBytes } from './validationReceipt.ts'
+
+import type { OutputFile } from './outputIndex.ts'
+import type { AssetCost } from './product.ts'
+import type { ScriptContract } from './scriptContract.ts'
+
+/** A computed value, or the message of the refusal computing it threw: thrown later, in the old validator's order. */
+type Outcome<Value> =
+  | Readonly<{ ok: true; value: Value }>
+  | Readonly<{ ok: false; message: string }>
+
+/** The facts of one blob, for the kind its path's extension names. */
+interface BlobFacts {
+  readonly kind: OutputFile['kind']
+  readonly sniffed: Outcome<OutputFile['kind']>
+  readonly extension: Outcome<string>
+  /** Absent for Wasm, whose cost needs its script contract; its bytes are kept instead. */
+  readonly cost: Outcome<Readonly<AssetCost>> | undefined
+  /** Canonical `ktx2DeviceCosts` text, for KTX2. */
+  readonly ktx2: Outcome<string> | undefined
+}
+
+/** A blob's or kept file's bytes and facts, as the replay sees them. */
+interface FactsMember {
+  readonly bytes: Readonly<Uint8Array> | undefined
+  readonly facts: BlobFacts | undefined
+}
+
+const KINDS: ReadonlyMap<string, OutputFile['kind']> = new Map([
+  ['glb', 'glb'],
+  ['ktx2', 'ktx2'],
+  ['wav', 'audio'],
+  ['ogg', 'audio'],
+  ['m4a', 'audio'],
+  ['mp3', 'audio'],
+  ['json', 'json'],
+  ['wasm', 'wasm'],
+  ['webp', 'image'],
+  ['jpg', 'image'],
+  ['png', 'image'],
+  ['bin', 'bin'],
+  ['wtt', 'tile'],
+])
+const NEXT = 1
+const COSTS = ['decoded', 'gpu', 'triangles', 'draws'] as const
+
+function outcome<Value>(run: () => Value): Outcome<Value> {
+  try {
+    return { ok: true, value: run() }
+  } catch (error) {
+    return {
+      ok: false,
+      message: error instanceof Error ? error.message : String(error),
+    }
+  }
+}
+
+function settled<Value>(result: Outcome<Value>): Value {
+  if (result.ok) {
+    return result.value
+  }
+  throw new Error(result.message)
+}
+
+function legacyKind(kind: OutputFile['kind']): string {
+  return kind === 'bin' || kind === 'tile' ? 'binary' : kind
+}
+
+function ktx2Facts(bytes: Readonly<Uint8Array>): Outcome<string> {
+  return outcome((): string =>
+    new TextDecoder().decode(validationSourceBytes(ktx2DeviceCosts(bytes))),
+  )
+}
+
+/** The facts of a blob's bytes, or nothing for a path that names no blob kind. */
+function blobFacts(
+  path: string,
+  bytes: Readonly<Uint8Array>,
+): BlobFacts | undefined {
+  const kind = KINDS.get(path.slice(path.lastIndexOf('.') + NEXT))
+  if (kind === undefined) {
+    return undefined
+  }
+  const legacy = legacyKind(kind)
+  return {
+    kind,
+    sniffed: outcome((): OutputFile['kind'] => outputBlobKind(legacy, bytes)),
+    extension: outcome((): string => outputBlobExtension(kind, bytes)),
+    cost:
+      kind === 'wasm'
+        ? undefined
+        : outcome((): AssetCost => assetCost(legacy, bytes)),
+    ktx2: kind === 'ktx2' ? ktx2Facts(bytes) : undefined,
+  }
+}
+
+function kindError(): Error {
+  return new Error('Output blob bytes differ from their declared kind')
+}
+
+function keptBytes(member: FactsMember): Readonly<Uint8Array> {
+  if (member.bytes === undefined) {
+    throw kindError()
+  }
+  return member.bytes
+}
+
+/** `inspectBlob`'s registered-JSON checks, for a host with no JSON Schema checker (the Worker). */
+// oxlint-disable-next-line typescript/prefer-readonly-parameter-types -- valibot's output type, only read
+function inspectRegistered(file: OutputFile, member: FactsMember): void {
+  const contract =
+    file.name === undefined ? undefined : registeredJsonContract(file.name)
+  if (
+    contract !== undefined &&
+    (file.kind !== 'json' || file.jsonSchema === undefined)
+  ) {
+    throw new Error('Registered JSON requires its defining schema')
+  }
+  if (file.jsonSchema === undefined) {
+    return
+  }
+  if (contract === undefined || file.name === undefined) {
+    throw new Error(
+      'Unregistered named JSON with a schema needs a JSON Schema checker',
+    )
+  }
+  if (file.jsonSchema['$comment'] !== contract.source) {
+    throw new Error(
+      'Registered JSON requires its exact defining format contract',
+    )
+  }
+  validateRegisteredJson(file.name, parseNamedJson(keptBytes(member)))
+}
+
+/** `inspectBlob`'s platform-file check of named JSON. */
+// oxlint-disable-next-line typescript/prefer-readonly-parameter-types -- valibot's output type, only read
+function inspectPlatformJson(file: OutputFile, member: FactsMember): void {
+  if (file.kind !== 'json' || file.name === undefined) {
+    return
+  }
+  const source = file.jsonSchema?.['$comment']
+  const schema = typeof source === 'string' ? source : undefined
+  if (
+    validatePlatformFile(
+      file.name,
+      schema,
+      parseNamedJson(keptBytes(member)),
+    ) === undefined
+  ) {
+    throw new Error(`Unregistered named JSON: ${file.name}`)
+  }
+}
+
+/** `inspectBlob` again, from the facts: the same checks in the same order. A declared kind other than the one the
+ *  path names fails the kind or extension check, as it does in `inspectBlob` (its message may differ). */
+function inspectFacts(
+  // oxlint-disable-next-line typescript/prefer-readonly-parameter-types -- valibot's output type, only read
+  file: OutputFile,
+  member: FactsMember,
+  script: Readonly<ScriptContract> | undefined,
+): void {
+  inspectRegistered(file, member)
+  inspectPlatformJson(file, member)
+  const { facts } = member
+  if (facts?.kind !== file.kind) {
+    throw kindError()
+  }
+  if (
+    settled(facts.sniffed) !== file.kind ||
+    !file.path.endsWith(`.${settled(facts.extension)}`)
+  ) {
+    throw kindError()
+  }
+  const cost =
+    facts.cost === undefined
+      ? assetCost('wasm', keptBytes(member), script)
+      : settled(facts.cost)
+  if (
+    COSTS.some((key: (typeof COSTS)[number]): boolean => cost[key] > file[key])
+  ) {
+    throw new Error('Output blob understates parsed costs')
+  }
+}
+
+/** A KTX2 blob's device-cost text, for `ktx2Costs`. */
+function ktx2Text(member: FactsMember | undefined): string | undefined {
+  const facts = member?.facts?.ktx2
+  return facts === undefined ? undefined : settled(facts)
+}
+
+export type { BlobFacts, FactsMember }
+export { blobFacts, inspectFacts, ktx2Text }