@wovin/core 0.3.0 → 0.3.2

package/src/applog/object-values.test.ts

@@ -74,15 +74,12 @@ describe('object/array applog values', () => {
 		expect(index.get(valueKey({ a: 9 }))).toHaveLength(1)
 	})
 
-	it('matchPartStatic matches a literal object value by deep equality', () => {
+	it('matchPartStatic matches a literal object/array value by deep equality', () => {
 		expect(matchPartStatic('vl', { a: 1, b: 2 }, { b: 2, a: 1 })).toBe(true)
 		expect(matchPartStatic('vl', { a: 1 }, { a: 2 })).toBe(false)
-	})
-
-	it('matching a literal array value requires a predicate (a bare array throws)', () => {
-		// bare arrays are reserved/rejected, so an array value is matched via a predicate
-		expect(matchPartStatic('vl', (v: any) => valueEq(v, [1, 2, 3]), [1, 2, 3])).toBe(true)
-		expect(() => matchPartStatic('vl', [1, 2, 3] as any, [1, 2, 3])).toThrow(/anyOf/)
+		// a bare array is a literal value, matched deeply (NOT set-membership)
+		expect(matchPartStatic('vl', [1, 2, 3], [1, 2, 3])).toBe(true)
+		expect(matchPartStatic('vl', [1, 2], [1, 2, 3])).toBe(false)
 	})
 
 	it('anyOf(...) provides set-membership and matches via matchPartStatic', () => {
@@ -96,8 +93,11 @@ describe('object/array applog values', () => {
 		expect(matchPartStatic('vl', isDark, { theme: 'light' })).toBe(false)
 	})
 
-	it('a bare array pattern fails loudly rather than matching ambiguously', () => {
-		expect(() => matchPartStatic('at', ['a', 'b'] as any, 'a')).toThrow(/anyOf/)
+	it('a bare array is a literal value, not set-membership (use anyOf for membership)', () => {
+		// ['a','b'] is the literal value to match, so it does NOT match the string 'a'
+		expect(matchPartStatic('at', ['a', 'b'], 'a')).toBe(false)
+		// membership is explicit via anyOf
+		expect(matchPartStatic('at', anyOf('a', 'b'), 'a')).toBe(true)
 	})
 
 	it('anyOf rejects object/array members (would silently never match)', () => {

package/src/ipfs/car.ts

@@ -69,6 +69,12 @@ export async function decodePubFromBlocks(
 			// New(er) format
 			if (!applogsCID) applogsCID = root.applogs  // Save from first snapshot
 			const applogsBlock = (await getDecodedBlock(blockStore, root.applogs)) as SnapBlockLogsOrChunks
+			if (!applogsBlock) {
+				throw ERROR('[decodePubFromBlocks] applogs block missing from blockStore', {
+					cid: root.applogs.toString(),
+					rootCID: cidStr,
+				})
+			}
 			pubLogsArray = await unchunkApplogsBlock(applogsBlock, blockStore)
 			// Info only from first (most recent) snapshot
 			if (!firstInfo) {

package/src/ipns/ipns-record.ts

@@ -95,6 +95,21 @@ export async function resolveIPNSSequence(
 	return 0n
 }
 
+/** Regex to detect Kubo IPNS sequence conflict in error messages */
+const SEQ_CONFLICT_RE = /existing IPNS record has sequence (\d+) >= new record sequence (\d+)/
+
+/**
+ * Options for {@link publishIPNSRecord}.
+ */
+export interface PublishIPNSRecordOptions {
+	/**
+	 * Max number of times to bump the sequence on "existing >= new" conflict.
+	 * Defaults to 3. Each bump re-signs the record with a higher sequence
+	 * and retries all targets.
+	 */
+	maxSequenceBumps?: number
+}
+
 /**
  * Create a signed IPNS record and publish to all configured targets.
  *
@@ -105,38 +120,101 @@ export async function resolveIPNSSequence(
  *
  * Publish fan-out: only targets with a `publish` method are called.
  * Throws if every publish-capable target fails; partial failures are logged.
+ *
+ * **Sequence-coherence retry:** if a publish target rejects with the Kubo
+ * "existing IPNS record has sequence X >= new record sequence Y" error,
+ * the function parses `X`, bumps the sequence to `max(X + 1n, Y + 1n)`,
+ * re-signs the record, and retries (up to `maxSequenceBumps` times).
+ * This is the "increment and clobber" mechanism that recovers from
+ * sequence drift without requiring server-side `--force` support.
  */
 export async function publishIPNSRecord(
 	privateKey: Uint8Array,
 	cid: CID,
 	targets: IPNSPublishTarget[],
+	options?: PublishIPNSRecordOptions,
 ): Promise<SignedIPNSRecord> {
 	const ipnsName = ipnsNameFromPrivateKey(privateKey)
-	const sequence = await pickNextSequence(ipnsName, targets)
-	const signed = await createSignedIPNSRecord(privateKey, cid, sequence)
+	const maxBumps = options?.maxSequenceBumps ?? 3
 
 	const publishTargets = targets.filter(t => typeof t.publish === 'function')
 	if (publishTargets.length === 0) {
 		throw new Error('No publish-capable targets supplied to publishIPNSRecord')
 	}
 
-	const results = await Promise.allSettled(
-		publishTargets.map(t => t.publish!(ipnsName, signed.recordBytes)),
-	)
-	const failures = results
-		.map((r, i) => ({ r, name: publishTargets[i].name }))
-		.filter(({ r }) => r.status === 'rejected') as { r: PromiseRejectedResult; name: string }[]
-
-	if (failures.length > 0 && failures.length < publishTargets.length) {
-		// Partial failure — log but don't throw
-		for (const { r, name } of failures) {
-			console.warn(`[publishIPNSRecord] target '${name}' failed:`, r.reason)
+	let sequence: bigint | undefined
+	let bumpFloor: bigint | undefined
+
+	for (let attempt = 0; ; attempt++) {
+		// Compute next sequence on first pass or after a conflict bump
+		if (sequence === undefined) {
+			sequence = await pickNextSequence(ipnsName, targets)
 		}
-	} else if (failures.length === publishTargets.length) {
-		throw new Error(`All IPNS publish targets failed: ${failures.map(({ r, name }) => `${name}: ${r.reason}`).join('; ')}`)
-	}
+		if (bumpFloor !== undefined) {
+			// bumpFloor was set on previous attempt from a conflict error
+			if (bumpFloor > sequence) sequence = bumpFloor
+			bumpFloor = undefined
+		}
+
+		const signed = await createSignedIPNSRecord(privateKey, cid, sequence)
 
-	return signed
+		const results = await Promise.allSettled(
+			publishTargets.map(t => t.publish!(ipnsName, signed.recordBytes)),
+		)
+		const failures = results
+			.map((r, i) => ({ r, name: publishTargets[i].name }))
+			.filter(({ r }) => r.status === 'rejected') as { r: PromiseRejectedResult; name: string }[]
+
+		// All succeeded — done
+		if (failures.length === 0) {
+			return signed
+		}
+
+		// Check if any failure is a sequence conflict we can recover from
+		const conflictReasons = failures.filter(({ r }) =>
+			SEQ_CONFLICT_RE.test(typeof r.reason === 'string' ? r.reason : String(r.reason)),
+		)
+
+		if (conflictReasons.length > 0 && attempt < maxBumps) {
+			// Parse the highest existing sequence from each conflict error
+			let bump = sequence
+			for (const { r } of conflictReasons) {
+				const msg = typeof r.reason === 'string' ? r.reason : String(r.reason)
+				const m = msg.match(SEQ_CONFLICT_RE)
+				if (m) {
+					const existing = BigInt(m[1])
+					if (existing >= bump) bump = existing + 1n
+				}
+			}
+			if (bump > sequence) {
+				console.warn(
+					`[publishIPNSRecord] Sequence conflict: server seq ${bump - 1n} >= current ${sequence}, ` +
+					`bumping to ${bump} (attempt ${attempt + 1}/${maxBumps})`,
+				)
+				sequence = bump
+				continue
+			}
+		}
+
+		// Partial failure (some targets succeeded) — log and return the signed record
+		if (failures.length < publishTargets.length) {
+			for (const { r, name } of failures) {
+				console.warn(`[publishIPNSRecord] target '${name}' failed:`, r.reason)
+			}
+			return signed
+		}
+
+		// Every publish-capable target failed and we cannot recover
+		if (conflictReasons.length > 0) {
+			throw new Error(
+				`IPNS sequence conflict not resolved after ${Math.min(attempt + 1, maxBumps)} bumps. ` +
+				`All publish targets failed: ${failures.map(({ r, name }) => `${name}: ${r.reason}`).join('; ')}`,
+			)
+		}
+		throw new Error(
+			`All IPNS publish targets failed: ${failures.map(({ r, name }) => `${name}: ${r.reason}`).join('; ')}`,
+		)
+	}
 }
 
 /**

package/src/ipns/ipns-w3name.ts

@@ -1,6 +1,7 @@
 import type { IPNSPublishTarget } from '@wovin/core/ipns'
 import { Logger } from 'besonders-logger'
 import { base64pad } from 'multiformats/bases/base64'
+import { resolveIPNSSequence, unmarshalIPNSRecord } from './ipns-record.ts'
 import { CID } from 'multiformats/cid'
 import * as W3Name from 'w3name'
 
@@ -77,22 +78,125 @@ async function _publishIPNSImpl(ipnsPrivateKey: Uint8Array, cid: CID): Promise<W
 	return revision // Return for Kubo integration or other uses
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// zt.ax naming service target (primary)
+// ─────────────────────────────────────────────────────────────────────────────
+
 /**
- * Create an IPNSPublishTarget that publishes to W3Name service via HTTP POST.
+ * Resolve the current IPNS sequence from a zt.ax-compatible naming service.
+ *
+ * The naming service API uses the simple W3NameRecord format:
+ *   `GET <baseUrl>/<ipnsName>` → `{ value: "/ipfs/<cid>", seq?: number, validity?: string }`
+ *
+ * Also supports the legacy w3name record format (`{ record: "<base64>", value: "..." }`)
+ * for backward compatibility with hybrid services.
  */
-export function w3nameTarget(serviceUrl = 'https://name.web3.storage'): IPNSPublishTarget {
+export async function resolveZtaxSequence(
+	baseUrl: string,
+	ipnsName: string,
+): Promise<bigint | null> {
+	const url = `${baseUrl.replace(/\/+$/, '')}/${ipnsName}`
+	let response: Response
+	try {
+		response = await fetch(url)
+	} catch (err) {
+		throw new Error(`Network error resolving sequence from ${baseUrl}: ${err}`)
+	}
+
+	if (response.status === 404) return null
+	if (!response.ok) {
+		throw new Error(`HTTP ${response.status} resolving sequence from ${baseUrl}: ${response.statusText}`)
+	}
+
+	const body: Record<string, unknown> = await response.json()
+
+	// Format 1: simple W3NameRecord with seq number
+	if (typeof body.seq === 'number') {
+		return BigInt(body.seq)
+	}
+
+	// Format 2: legacy w3name record with base64-encoded protobuf
+	if (typeof body.record === 'string') {
+		try {
+			const bytes = base64pad.baseDecode(body.record)
+			const entry = unmarshalIPNSRecord(bytes)
+			return entry.sequence
+		} catch {
+			WARN('[resolveZtaxSequence] failed to unmarshal record for', ipnsName)
+			return null
+		}
+	}
+
+	// No sequence info — treat as never published or zero
+	return null
+}
+
+/**
+ * Create an IPNSPublishTarget that publishes to a zt.ax naming service.
+ *
+ * Uses HTTP POST to publish signed IPNS records and HTTP GET to resolve
+ * the current sequence number, following the same wire format as the
+ * standard w3name API but at a configurable base URL.
+ *
+ * The naming service is expected to support:
+ *   - `POST <baseUrl>/<ipnsName>` — publish signed IPNS record (base64-encoded body)
+ *   - `GET  <baseUrl>/<ipnsName>` — resolve current record (`{ value, seq?, record? }`)
+ *
+ * @param baseUrl - Base URL of the naming service (default: https://ipfs.zt.ax)
+ */
+export function ztaxTarget(baseUrl = 'https://ipfs.zt.ax'): IPNSPublishTarget {
+	const cleanBase = baseUrl.replace(/\/+$/, '')
 	return {
-		name: 'w3name',
+		name: 'zt.ax',
 		async publish(ipnsName: string, recordBytes: Uint8Array) {
-			const res = await fetch(`${serviceUrl}/name/${ipnsName}`, {
+			const url = `${cleanBase}/${ipnsName}`
+			DEBUG(`[ztaxTarget] POST ${url}`)
+			const res = await fetch(url, {
 				method: 'POST',
 				body: base64pad.baseEncode(recordBytes),
 			})
-			if (!res.ok) throw new Error(`W3Name HTTP ${res.status}`)
+			if (!res.ok) {
+				let detail = ''
+				try {
+					const body = await res.json() as Record<string, unknown>
+					detail = body.message ? ` — ${body.message}` : ''
+				} catch {
+					detail = res.statusText ? ` — ${res.statusText}` : ''
+				}
+				throw new Error(`zt.ax HTTP ${res.status}${detail}`)
+			}
+		},
+		async resolveSequence(ipnsName: string): Promise<bigint | null> {
+			return resolveZtaxSequence(cleanBase, ipnsName)
 		},
 	}
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// w3name naming service target (deprecated — read‑only backup)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Create an IPNSPublishTarget for the w3name service.
+ *
+ * @deprecated w3name is shut down for publishing. This target is kept as a
+ * read‑only backup for sequence resolution only (no publish method).
+ * Use {@link ztaxTarget} for all publishing.
+ *
+ * @param serviceUrl - Base URL of the w3name-compatible service (default: https://name.web3.storage)
+ */
+export function w3nameTarget(serviceUrl = 'https://name.web3.storage'): IPNSPublishTarget {
+	return {
+		name: 'w3name',
+		// No publish() — w3name is read-only; publishing goes through ztaxTarget
+		async resolveSequence(ipnsName: string): Promise<bigint | null> {
+			return resolveIPNSSequence(serviceUrl, ipnsName)
+		},
+	}
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+
 export async function generateIpnsKey() {
 	return W3Name.create() // Returns W3Name.WritableName type
 }

package/src/ipns/ipns-watcher.ts

@@ -151,8 +151,9 @@ export function watchNameRaw(nameBaseUrl: string, name: string, options: WatchRa
 	}
 
 	ws.onerror = (event) => {
-		WARN('[watchNameRaw] error for', name, event)
-		options.onError?.(event)
+		const errorMsg = event instanceof ErrorEvent ? event.message : 'WebSocket error'
+		WARN('[watchNameRaw] error for', name, ':', errorMsg)
+		options.onError?.(new Error(errorMsg))
 	}
 
 	ws.onclose = (event) => {
@@ -322,7 +323,7 @@ export class IpnsWatcher {
 
 			// Still call the error handler for unexpected errors
 			if (errorMsg !== 'Unexpected EOF') {
-				options.onError?.(event)
+				options.onError?.(new Error(errorMsg))
 			}
 		}