@carbonenginejs/runtime-resource 0.20.0 → 0.22.0

package/dist/formats/wem/core/resolve.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"resolve.js","sources":["../../../../../src/formats/wem/core/resolve.js"],"sourcesContent":["// Content-verified codec resolution for wem media (resolveType seam; see docs/concepts/format-type-resolution.md).\r\n// The fmt tag is the declaration; each candidate codec gets ONE bounded\r\n// structural check against the actual container facts - no audio is decoded:\r\n//\r\n// - wwise-vorbis: the Wwise Vorbis sidecar must exist (vorb chunk or inline\r\n//   fmt-0x42 layout) with a positive sample count and data payload;\r\n// - wwise-ptadpcm: the frame layout must satisfy the decoder's own guard\r\n//   (blockAlign = frameSize * channels, frameSize >= 6) with block-aligned\r\n//   data;\r\n// - pcm / pcm-extensible: 16-bit with self-consistent blockAlign/byteRate\r\n//   and sample-aligned data.\r\n//\r\n// The declared codec is validated FIRST; when its check fails (a mislabeled\r\n// tag), the other candidates are tried in order. A 2026-07-19 census of all\r\n// 8,987 embedded wems in EVE build 3435006 found no mislabeled tags, so\r\n// mismatch is the exceptional path - but the check is what makes that a\r\n// verified fact per file rather than a corpus-wide assumption.\r\nimport { inspectWithValues } from \"./helpers.js\";\r\n\r\nconst CANDIDATES = [ \"wwise-vorbis\", \"wwise-ptadpcm\", \"pcm\" ];\r\n\r\nfunction validateVorbis(metadata)\r\n{\r\n    if (metadata.codec === \"wwise-vorbis\")\r\n    {\r\n        return metadata.vorbis !== null && metadata.sampleCount > 0 && metadata.dataBytes > 0;\r\n    }\r\n    // Mislabeled tag: inspect() only fills `vorbis` when the tag says so, but\r\n    // the chunk walk always records a standalone vorb sidecar chunk.\r\n    return (metadata.chunks ?? []).some(chunk => chunk.id === \"vorb\") && metadata.dataBytes > 0;\r\n}\r\n\r\nfunction validatePtadpcm(metadata)\r\n{\r\n    const channels = metadata.channels;\r\n    const frameSize = channels > 0 ? Math.floor(metadata.blockAlign / channels) : 0;\r\n    return channels >= 1\r\n        && frameSize >= 6\r\n        && metadata.blockAlign === frameSize * channels\r\n        && metadata.dataBytes >= metadata.blockAlign\r\n        && metadata.dataBytes % metadata.blockAlign === 0;\r\n}\r\n\r\nfunction validatePcm(metadata)\r\n{\r\n    return metadata.bitsPerSample === 16\r\n        && metadata.channels >= 1\r\n        && metadata.blockAlign === metadata.channels * 2\r\n        && metadata.byteRate === metadata.sampleRate * metadata.blockAlign\r\n        && metadata.dataBytes > 0\r\n        && metadata.dataBytes % metadata.blockAlign === 0;\r\n}\r\n\r\nfunction validate(candidate, metadata)\r\n{\r\n    if (candidate === \"wwise-vorbis\") return validateVorbis(metadata);\r\n    if (candidate === \"wwise-ptadpcm\") return validatePtadpcm(metadata);\r\n    return validatePcm(metadata);\r\n}\r\n\r\nfunction candidateFor(codec)\r\n{\r\n    if (codec === \"pcm-extensible\") return \"pcm\";\r\n    return CANDIDATES.includes(codec) ? codec : null;\r\n}\r\n\r\nfunction emitFor(candidate)\r\n{\r\n    if (candidate === \"wwise-vorbis\") return \"ogg\";\r\n    if (candidate === \"wwise-ptadpcm\" || candidate === \"pcm\") return \"pcm\";\r\n    return \"raw\";\r\n}\r\n\r\n/**\r\n * Resolve a wem's actual decode route from content, not just its fmt tag.\r\n *\r\n * @param {*} input Wem bytes.\r\n * @param {object} values Normalized read values.\r\n * @returns {object} Probe-shaped report: verified variant flags, `preferred`\r\n *   route, and declared/resolved/mismatch evidence in `metadata`.\r\n */\r\nexport function resolveTypeWithValues(input, values)\r\n{\r\n    const metadata = inspectWithValues(input, values);\r\n    const declared = metadata.codec || null;\r\n    let resolved = null;\r\n    const declaredCandidate = candidateFor(declared);\r\n    if (declaredCandidate && validate(declaredCandidate, metadata))\r\n    {\r\n        resolved = declaredCandidate;\r\n    }\r\n    else\r\n    {\r\n        for (const candidate of CANDIDATES)\r\n        {\r\n            if (candidate === declaredCandidate) continue;\r\n            if (validate(candidate, metadata))\r\n            {\r\n                resolved = candidate;\r\n                break;\r\n            }\r\n        }\r\n    }\r\n\r\n    const preferred = emitFor(resolved);\r\n    const mismatch = resolved !== null && declaredCandidate !== resolved;\r\n    return {\r\n        format: \"wem\",\r\n        source: values.source || \"buffer\",\r\n        supported: metadata.codec ? \"partial\" : \"none\",\r\n        confidence: resolved ? 1 : 0,\r\n        verified: true,\r\n        preferred,\r\n        reason: resolved\r\n            ? (mismatch\r\n                ? `Declared codec ${declared} failed content validation; ${resolved} validated instead.`\r\n                : `Declared codec validated by content.`)\r\n            : `No decodable codec validated against the content (declared ${declared ?? \"none\"}).`,\r\n        metadata: { ...metadata, declared, resolved, mismatch },\r\n        variants: [\r\n            {\r\n                kind: \"raw\",\r\n                payloadType: \"raw\",\r\n                codec: declared || \"unknown\",\r\n                mimeType: \"application/octet-stream\",\r\n                supported: true,\r\n                containerOnly: true,\r\n                isDecoded: false,\r\n                pcmDecodeSupported: false\r\n            },\r\n            {\r\n                kind: \"ogg\",\r\n                payloadType: \"raw\",\r\n                codec: \"vorbis\",\r\n                mimeType: \"audio/ogg\",\r\n                supported: resolved === \"wwise-vorbis\",\r\n                containerOnly: true,\r\n                isDecoded: false\r\n            },\r\n            {\r\n                kind: \"pcm\",\r\n                payloadType: \"pcm\",\r\n                codec: \"float32\",\r\n                supported: resolved === \"wwise-ptadpcm\" || resolved === \"pcm\",\r\n                isDecoded: true,\r\n                pcmDecodeSupported: resolved === \"wwise-ptadpcm\" || resolved === \"pcm\"\r\n            }\r\n        ]\r\n    };\r\n}\r\n"],"names":["CANDIDATES","validateVorbis","metadata","codec","vorbis","sampleCount","dataBytes","chunks","some","chunk","id","validatePtadpcm","channels","frameSize","Math","floor","blockAlign","validatePcm","bitsPerSample","byteRate","sampleRate","validate","candidate","candidateFor","includes","emitFor","resolveTypeWithValues","input","values","inspectWithValues","declared","resolved","declaredCandidate","preferred","mismatch","format","source","supported","confidence","verified","reason","variants","kind","payloadType","mimeType","containerOnly","isDecoded","pcmDecodeSupported"],"mappings":"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"}

package/docs/concepts/format-type-resolution.md

@@ -1,79 +0,0 @@
-# Format type resolution
-
-Status: Evolving
-Scope: `CjsFormat.resolveType`, `CjsResourceProbe`, and the formats that override them
-Audience: Anyone adding a format, choosing a decode route, or debugging a mislabeled container
-Summary: Separates what a container claims about itself from what a reader has evidence it can decode, and states how a verified resolution may and may not change a route.
-
-## Claims versus evidence
-
-A container's header is a claim. `inspect()` and `isSupported()` report that
-claim: they read the declaration and answer whether this format recognizes it.
-That is the right answer almost always, and it is cheap.
-
-`resolveType()` answers a different question — what the reader has *evidence*
-it can actually decode. It performs one bounded asynchronous content check: a
-magic number, a first frame or block, a setup header. It never decodes the
-payload.
-
-The distinction matters because a mislabeled container is indistinguishable
-from a correct one until something looks at the content. Routing on the
-declaration alone turns that into a decode failure much later, somewhere that
-has forgotten what the file claimed to be.
-
-## The contract
-
-`resolveType()` returns a `CjsResourceProbe`. The probe carries a persisted
-`verified` boolean, and its `metadata` carries the evidence: what was
-declared, what resolved, and whether those disagreed. `preferred` names the
-resolved decode route.
-
-Three rules govern what a probe may do:
-
-- **A caller-forced emit always wins.** Resolution informs a default; it never
-  overrides an explicit request.
-- **An unverified result never changes a route.** The base implementation
-  delegates to `isSupported()` and sets `verified` to false, so a format
-  without an override costs nothing and cannot silently redirect anything.
-- **Opting in is per format.** Overriding is a decision made by a format that
-  has a cheap, meaningful content check — not a requirement on all of them.
-
-That third rule is why this is a seam rather than a pipeline stage. The
-zero-extra-work path is the default, and it stays free.
-
-## What a check may look like: wem
-
-`CjsWemFormat` overrides it, and its shape is the model. The `fmt` tag is the
-declaration. Each candidate codec gets one bounded **structural** check
-against container facts — a Wwise Vorbis sidecar present with a positive
-sample count; a PTADPCM frame layout satisfying the decoder's own guard with
-block-aligned data; PCM with self-consistent block alignment and byte rate.
-No audio is decoded in any of them.
-
-The declared codec is validated first. Only when its check fails are the other
-candidates tried, in order. The resolved codec maps to an emit — Wwise Vorbis
-to `ogg`, PTADPCM and PCM to `pcm`, anything unresolved to `raw`.
-
-A census of all 8,987 embedded wems in one EVE build found no mislabeled tag.
-That is the point rather than a reason to drop the check: it converts a
-corpus-wide assumption into a fact verified per file, and the cost of holding
-that guarantee is one structural read.
-
-## Current limits
-
-Resolution is available to callers but is **not yet wired into the resource
-read path**. `CjsResMan` still selects a format by extension using the
-synchronous `isSupported()` tie-break, so a mislabeled file routed through
-ordinary resource acquisition is not corrected today. Consumers that need the
-verified answer call `resolveType()` themselves.
-
-Wem exposes `raw`, `ogg`, and `pcm` as distinct outputs, so a caller still
-chooses a decoder. A single resolve-then-route output that hides the codec
-choice is [planned](../roadmap.md), not present.
-
-## Related documentation
-
-- [Resource lifecycle](resource-lifecycle.md) — how a resource is acquired,
-  prepared, and published.
-- [Wwise formats](../formats/wwise.md) — the wem container these checks read.
-- [Roadmap](../roadmap.md) — the unbuilt read-path integration.