feat: observe verified metadata before persistence

packages/client/README.mdmodified+28-0

Changes to packages/client/README.md

		@@ -1,3 +1,31 @@
1	1	# tuf-js
2	2
3	3	JavaScript TUF client implementation.
	4	+
	5	+## Verified metadata observation
	6	+
	7	+This source branch adds optional `UpdaterOptions.onVerifiedMetadata(role, bytes)`.
	8	+The updater awaits the observer after metadata verification and before its cache
	9	+write or the next metadata request. Each call receives an owned byte copy. A
	10	+rejection becomes `PersistError` with its exact original cause and aborts the
	11	+refresh. Persistence failures are never interpreted as a missing root or a
	12	+cache miss, including with `forceCache`.
	13	+
	14	+`UpdaterOptions.referenceTime` accepts a finite `Date` and copies its value at
	15	+construction. Omitting it preserves the normal fixed update-start time. This
	16	+option supports recovery replay; it does not establish a trusted clock or
	17	+permit accepting expired metadata at the actual trusted time.
	18	+
	19	+Remote verification failures expose `MetadataVerificationError.role` and retain
	20	+the original failure in `cause`. Download failures and equal-version timestamp
	21	+handling preserve their existing paths. Classify persistence failures before
	22	+examining an observer's nested cause. An observer can reject with any value,
	23	+including another verification error.
	24	+
	25	+Discard an updater after a failed refresh. Observer ordering does not roll back
	26	+its in-memory trust set, make cache writes transactional, or provide a protected
	27	+trust store. Applications must implement those boundaries independently.
	28	+
	29	+These extensions are maintained source changes, not options present in the
	30	+unmodified upstream 6.0.0 package. Release and qualify this source before removing
	31	+an application's legacy distribution patch.