fix(js): validate reply prefix in decodeResult

[ukint-vs]

Summary

• v2 SailsProgram decodeResult and v1 Sails decodeResult now validate the reply's Sails header / (service, method) prefix before SCALE-decoding, matching the existing behavior of decodePayload.
• Previously, passing headerless or mismatched reply bytes silently produced garbage (or a cryptic codec error); now both throw a clear Invalid Sails header for … / Invalid prefix for … result error.
• Documents the long-existing sails-js/types, sails-js/parser, and sails-js/util subpath exports in both READMEs so downstream tooling can import ISailsTypeDef / ISailsPrimitiveDef instead of falling back to any casts.

Why

decodePayload, event decode(), and ctor decodePayload() already validate the method prefix — see _assertMatchingHeader at js/src/sails-idl-v2.ts and the getServiceNamePrefix / getFnNamePrefix checks at js/src/sails.ts. decodeResult was the only public decode entry point that skipped this validation. The asymmetry is easy to miss because internal builders (e.g. QueryBuilderWithHeader) strip the prefix themselves via result.payload.slice(this._prefixByteLength), so decodeResult is only hit by external consumers — which is exactly where a clear error matters most.

This came up while integrating sails-js into a downstream wallet / tooling stack: passing a reply payload that had already been stripped by an intermediate layer to decodeResult returned plausible-looking but wrong values instead of throwing.

Behavior change

Callers who were (deliberately or accidentally) relying on decodeResult accepting prefix-less bytes will now see a thrown error instead of garbage output. Given the prior behavior produced undefined/garbage results rather than anything semantically useful, this should be considered a bug fix rather than a breaking change — but flagging it explicitly for reviewers.

Test plan

• New non-live unit tests in js/test/idl-v2-parser-type-resolver.test.ts covering the v2 error paths (bogus 16-byte prefix without magic bytes → Invalid Sails header; prefix whose entry_id belongs to a different method → Header mismatch).
• New unit test in js/test/encode-decode.test.ts covering the v1 happy path and the mismatched-prefix error path.
• pnpm jest idl-v2-parser-type-resolver — all 11 tests pass
• pnpm jest encode-decode — all 3 tests pass
• pnpm lint — no issues
• npx prettier --check on edited files — clean

Not covered here (deliberately deferred)

• Package version coherence (e.g. js/package.json is still at 0.5.1 despite the js/v1.0.0-beta.1 git tag; sails-js-parser standalone vs the sails-js/parser subpath naming overlap). This is a release-cadence / publishing decision rather than a code fix, and should be handled as part of the 1.0 bump rather than dragged in here.

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request introduces validation for the reply prefix in decodeResult for both Sails (v1) and SailsProgram (v2) to ensure the data matches the expected service and method. It also documents subpath exports (sails-js/types, sails-js/parser, and sails-js/util) in the README files. Review feedback highlights that the changelog's claim regarding consistency with v1's decodePayload is inaccurate, as decodePayload and event.decode in v1 still lack similar validation. Additionally, it is noted that the sails-js/parser subpath documentation is missing from the v1 README.

[ukint-vs]

Addressed all three review comments in c70556a (plus a3fcd7d for the earlier truncated-bytes polish):

Comment	Fix
"decodePayload in v1 does not currently perform this validation — inconsistency that should be addressed"	v1 decodePayload (function + constructor) and event.decode now go through shared _assertMatchingServicePrefix / _assertMatchingCtorPrefix helpers, matching v2's _assertMatchingHeader coverage.
"Changelog's claim regarding consistency with v1's decodePayload is inaccurate"	CHANGELOG rewritten to describe the fix as covering every v1/v2 decode entry point rather than claiming parity with an already-validated decodePayload.
"sails-js/parser subpath missing from v1 README"	Added, with a note clarifying it's the IDL v2 parser; v1 users still import from the standalone sails-js-parser package.

Coverage bumped to 7 tests for v1 (3 existing + 4 new validation tests across decodePayload/decodeResult/event.decode/ctor decodePayload) and 12 for v2. Lint + Prettier clean.

[ukint-vs]

Ran /review with Codex adversarial pass. Codex flagged three things; two applied, one deferred:

Applied (commit 4441368):

1. HIGH: v1 Uint8Array regression. The new _assertMatchingServicePrefix went through getServiceNamePrefix/getFnNamePrefix, which only accept hex strings — but registry.createType accepts Uint8Array too, so callers doing fn.decodeResult(message.payload as any) with bytes worked before and broke after this PR. Fixed by normalizing via u8aToHex up front, matching the existing ctor helper pattern. Added a Uint8Array round-trip test.

2. MEDIUM: error-message log injection surface. The got ${actualService}.${actualFn} text echoed attacker-controlled bytes verbatim — a malformed reply could smuggle ANSI escapes / control chars into log sinks. Added a _safeEchoedName helper that truncates to 64 chars and replaces non-printable ASCII with ?. Test verifies ESC/BEL are stripped.

Deferred:

3. MEDIUM: _assertMatchingHeader doesn't check routeIdx. Pre-existing design — all v2 decode sites share this behavior, not something this PR introduced. Worth a separate issue if cross-route reply confusion is a real risk for multi-mounted services, but out of scope here.

Updated coverage: v1 9/9 tests pass (2 new), v2 12/12 pass. Lint + Prettier clean.

[ukint-vs]

Filed the deferred route_idx follow-up as #1316.