@pkcprotocol/pkc-js 0.0.88 → 0.0.89

package/dist/bundled/chunks/{src-B2CwDTfy.js → src-Dz9wtvrK.js}

@@ -5,10 +5,10 @@ import { CID } from "multiformats/cid";
 import { fromString } from "uint8arrays/from-string";
 import { concat } from "uint8arrays/concat";
 import { equals } from "uint8arrays/equals";
+import { sha256 } from "multiformats/hashes/sha2";
 import * as raw from "multiformats/codecs/raw";
 import { alloc, allocUnsafe } from "uint8arrays/alloc";
 import { withArrayBuffer } from "uint8arrays/with-array-buffer";
-import { sha256 } from "multiformats/hashes/sha2";
 import { murmur3128 } from "@multiformats/murmur3";
 import { BlackHoleBlockstore } from "blockstore-core/black-hole";
 //#region node_modules/ipfs-unixfs-importer/node_modules/uint8arraylist/dist/src/index.js
@@ -485,7 +485,7 @@ const fixedSize = (options = {}) => {
 	};
 };
 //#endregion
-//#region node_modules/ipfs-unixfs-importer/node_modules/ipfs-unixfs/dist/src/errors.js
+//#region node_modules/ipfs-unixfs/dist/src/errors.js
 var InvalidTypeError = class InvalidTypeError extends Error {
 	static name = "InvalidTypeError";
 	static code = "ERR_INVALID_TYPE";
@@ -496,7 +496,7 @@ var InvalidTypeError = class InvalidTypeError extends Error {
 	}
 };
 //#endregion
-//#region node_modules/ipfs-unixfs-importer/node_modules/uint8-varint/dist/src/index.js
+//#region node_modules/ipfs-unixfs/node_modules/uint8-varint/dist/src/index.js
 const N1 = Math.pow(2, 7);
 const N2 = Math.pow(2, 14);
 const N3 = Math.pow(2, 21);
@@ -579,7 +579,7 @@ function decodeUint8Array(buf, offset) {
 	throw new RangeError("Could not decode varint");
 }
 //#endregion
-//#region node_modules/ipfs-unixfs-importer/node_modules/protons-runtime/dist/src/utils/float.js
+//#region node_modules/ipfs-unixfs/node_modules/protons-runtime/dist/src/utils/float.js
 const f32 = new Float32Array([-0]);
 const f8b = new Uint8Array(f32.buffer);
 /**
@@ -633,7 +633,7 @@ function readDoubleLE(buf, pos) {
 	return f64[0];
 }
 //#endregion
-//#region node_modules/ipfs-unixfs-importer/node_modules/protons-runtime/dist/src/utils/longbits.js
+//#region node_modules/ipfs-unixfs/node_modules/protons-runtime/dist/src/utils/longbits.js
 const MAX_SAFE_NUMBER_INTEGER = BigInt(Number.MAX_SAFE_INTEGER);
 const MIN_SAFE_NUMBER_INTEGER = BigInt(Number.MIN_SAFE_INTEGER);
 /**
@@ -777,7 +777,7 @@ zero.length = function() {
 };
 const TWO_32 = 4294967296n;
 //#endregion
-//#region node_modules/ipfs-unixfs-importer/node_modules/protons-runtime/dist/src/utils/utf8.js
+//#region node_modules/ipfs-unixfs/node_modules/protons-runtime/dist/src/utils/utf8.js
 /**
 * Calculates the UTF8 byte length of a string
 */
@@ -853,7 +853,7 @@ function write(string, buffer, offset) {
 	return offset - start;
 }
 //#endregion
-//#region node_modules/ipfs-unixfs-importer/node_modules/protons-runtime/dist/src/utils/reader.js
+//#region node_modules/ipfs-unixfs/node_modules/protons-runtime/dist/src/utils/reader.js
 /* istanbul ignore next */
 function indexOutOfRange(reader, writeLength) {
 	return RangeError(`index out of range: ${reader.pos} + ${writeLength ?? 1} > ${reader.len}`);
@@ -1153,13 +1153,13 @@ function createReader(buf) {
 	return new Uint8ArrayReader(buf instanceof Uint8Array ? buf : buf.subarray());
 }
 //#endregion
-//#region node_modules/ipfs-unixfs-importer/node_modules/protons-runtime/dist/src/decode.js
+//#region node_modules/ipfs-unixfs/node_modules/protons-runtime/dist/src/decode.js
 function decodeMessage(buf, codec, opts) {
 	const reader = createReader(buf);
 	return codec.decode(reader, void 0, opts);
 }
 //#endregion
-//#region node_modules/ipfs-unixfs-importer/node_modules/protons-runtime/dist/src/utils/pool.js
+//#region node_modules/ipfs-unixfs/node_modules/protons-runtime/dist/src/utils/pool.js
 /**
 * A general purpose buffer pool
 */
@@ -1180,7 +1180,7 @@ function pool(size) {
 	};
 }
 //#endregion
-//#region node_modules/ipfs-unixfs-importer/node_modules/protons-runtime/dist/src/utils/writer.js
+//#region node_modules/ipfs-unixfs/node_modules/protons-runtime/dist/src/utils/writer.js
 /**
 * Constructs a new writer operation instance.
 *
@@ -1575,20 +1575,20 @@ function createWriter() {
 	return new Uint8ArrayWriter();
 }
 //#endregion
-//#region node_modules/ipfs-unixfs-importer/node_modules/protons-runtime/dist/src/encode.js
+//#region node_modules/ipfs-unixfs/node_modules/protons-runtime/dist/src/encode.js
 function encodeMessage(message, codec) {
 	const w = createWriter();
 	codec.encode(message, w, { lengthDelimited: false });
 	return w.finish();
 }
 //#endregion
-//#region node_modules/ipfs-unixfs-importer/node_modules/protons-runtime/dist/src/stream.js
+//#region node_modules/ipfs-unixfs/node_modules/protons-runtime/dist/src/stream.js
 function* streamMessage(buf, codec, opts) {
 	const reader = createReader(buf);
 	yield* codec.stream(reader, void 0, "$", opts);
 }
 //#endregion
-//#region node_modules/ipfs-unixfs-importer/node_modules/protons-runtime/dist/src/codec.js
+//#region node_modules/ipfs-unixfs/node_modules/protons-runtime/dist/src/codec.js
 const CODEC_TYPES = {
 	VARINT: 0,
 	BIT64: 1,
@@ -1607,7 +1607,7 @@ function createCodec(name, type, encode, decode, stream) {
 	};
 }
 //#endregion
-//#region node_modules/ipfs-unixfs-importer/node_modules/protons-runtime/dist/src/codecs/enum.js
+//#region node_modules/ipfs-unixfs/node_modules/protons-runtime/dist/src/codecs/enum.js
 function enumeration(v) {
 	function findValue(val) {
 		if (v[val.toString()] == null) throw new Error("Invalid enum value");
@@ -1623,12 +1623,12 @@ function enumeration(v) {
 	});
 }
 //#endregion
-//#region node_modules/ipfs-unixfs-importer/node_modules/protons-runtime/dist/src/codecs/message.js
+//#region node_modules/ipfs-unixfs/node_modules/protons-runtime/dist/src/codecs/message.js
 function message(encode, decode, stream) {
 	return createCodec("message", CODEC_TYPES.LENGTH_DELIMITED, encode, decode, stream);
 }
 //#endregion
-//#region node_modules/ipfs-unixfs-importer/node_modules/protons-runtime/dist/src/index.js
+//#region node_modules/ipfs-unixfs/node_modules/protons-runtime/dist/src/index.js
 /**
 * Thrown when a repeated field has too many elements
 */
@@ -1642,7 +1642,7 @@ var MaxLengthError = class extends Error {
 	name = "MaxLengthError";
 };
 //#endregion
-//#region node_modules/ipfs-unixfs-importer/node_modules/ipfs-unixfs/dist/src/unixfs.js
+//#region node_modules/ipfs-unixfs/dist/src/unixfs.js
 var Data;
 (function(Data) {
 	(function(DataType) {
@@ -1946,7 +1946,7 @@ var Metadata;
 	Metadata.stream = stream;
 })(Metadata || (Metadata = {}));
 //#endregion
-//#region node_modules/ipfs-unixfs-importer/node_modules/ipfs-unixfs/dist/src/index.js
+//#region node_modules/ipfs-unixfs/dist/src/index.js
 /**
 * @packageDocumentation
 *

package/dist/bundled/chunks/{util-BxLdjyTF.js → util-DuJcVQ7Y.js}

@@ -1,4 +1,4 @@
-import { br as PKCError, et as pubsubTopicToDhtKeyCid } from "./schema-By3Sh-uW.js";
+import { br as PKCError, et as pubsubTopicToDhtKeyCid } from "./schema-bDrzx9EZ.js";
 import { ipnsSelector } from "ipns/selector";
 import { equals } from "uint8arrays/equals";
 //#region dist/node/helia/util.js

package/dist/bundled/index.js

@@ -1,2 +1,2 @@
-import { a as getShortCid, i as getShortAddress, n as challenges, o as nativeFunctions, r as createAnchorIpnsRecord, s as setNativeFunctions, t as PKC } from "./chunks/node-BjSTVzbx.js";
+import { a as getShortCid, i as getShortAddress, n as challenges, o as nativeFunctions, r as createAnchorIpnsRecord, s as setNativeFunctions, t as PKC } from "./chunks/node-C9RpmtmM.js";
 export { challenges, createAnchorIpnsRecord, PKC as default, getShortAddress, getShortCid, nativeFunctions, setNativeFunctions };

package/dist/bundled/rpc/src/index.js

@@ -1,7 +1,7 @@
-import { Ct as findStartedCommunity, L as hideClassPrivateProps, Sr as logger_default, br as PKCError, lt as replaceXWithY, rr as t, tr as n } from "../../chunks/schema-By3Sh-uW.js";
-import { _ as parseRpcPublishAnchorRecordParam, c as parseRpcAuthorNameParam, d as parseRpcCommentRepliesPageParam, f as parseRpcCommunityIdentifierParam, g as parseRpcExportCommunityParam, h as parseRpcExportCommunityModLogsParam, l as parseRpcCancelExportParam, m as parseRpcEditCommunityParam, p as parseRpcCommunityPageParam, t as PKC, u as parseRpcCidParam, v as parseRpcPublishChallengeAnswersParam, y as parseRpcUnsubscribeParam } from "../../chunks/node-BjSTVzbx.js";
-import { An as parseSetNewSettingsPKCWsServerSchemaWithPKCErrorIfItFails, Cn as parseDecryptedChallengeAnswerWithPKCErrorIfItFails, J as buildPagesRuntimeFields, ct as pRetry, dn as parseCommunityEditOptionsSchemaWithPKCErrorIfItFails, dt as require_lib, jn as parseVoteChallengeRequestToEncryptSchemaWithPKCErrorIfItFails, lt as pLimit, nn as parseCommentChallengeRequestToEncryptSchemaWithPKCErrorIfItFails, on as parseCommentModerationChallengeRequestToEncryptSchemaWithPKCErrorIfItFails, q as buildPageRuntimeFields, rn as parseCommentEditChallengeRequestToEncryptSchemaWithPKCErrorIfItFails, rr as t$1, rt as extractCrosspostRuntimeFields, un as parseCommunityEditChallengeRequestToEncryptSchemaWithPKCErrorIfItFails, ur as stringify, vn as parseCreateNewLocalCommunityUserOptionsSchemaWithPKCErrorIfItFails, yn as parseCreatePKCWsServerOptionsSchemaWithPKCErrorIfItFails } from "../../chunks/rpc-local-community-Bu6Wp-tO.js";
-import { t as LocalCommunity } from "../../chunks/local-community-6_MVz1cc.js";
+import { Ct as findStartedCommunity, L as hideClassPrivateProps, Sr as logger_default, br as PKCError, lt as replaceXWithY, rr as t, tr as n } from "../../chunks/schema-bDrzx9EZ.js";
+import { _ as parseRpcPublishAnchorRecordParam, c as parseRpcAuthorNameParam, d as parseRpcCommentRepliesPageParam, f as parseRpcCommunityIdentifierParam, g as parseRpcExportCommunityParam, h as parseRpcExportCommunityModLogsParam, l as parseRpcCancelExportParam, m as parseRpcEditCommunityParam, p as parseRpcCommunityPageParam, t as PKC, u as parseRpcCidParam, v as parseRpcPublishChallengeAnswersParam, y as parseRpcUnsubscribeParam } from "../../chunks/node-C9RpmtmM.js";
+import { An as parseSetNewSettingsPKCWsServerSchemaWithPKCErrorIfItFails, Cn as parseDecryptedChallengeAnswerWithPKCErrorIfItFails, J as buildPagesRuntimeFields, ct as pRetry, dn as parseCommunityEditOptionsSchemaWithPKCErrorIfItFails, dt as require_lib, jn as parseVoteChallengeRequestToEncryptSchemaWithPKCErrorIfItFails, lt as pLimit, nn as parseCommentChallengeRequestToEncryptSchemaWithPKCErrorIfItFails, on as parseCommentModerationChallengeRequestToEncryptSchemaWithPKCErrorIfItFails, q as buildPageRuntimeFields, rn as parseCommentEditChallengeRequestToEncryptSchemaWithPKCErrorIfItFails, rr as t$1, rt as extractCrosspostRuntimeFields, un as parseCommunityEditChallengeRequestToEncryptSchemaWithPKCErrorIfItFails, ur as stringify, vn as parseCreateNewLocalCommunityUserOptionsSchemaWithPKCErrorIfItFails, yn as parseCreatePKCWsServerOptionsSchemaWithPKCErrorIfItFails } from "../../chunks/rpc-local-community-Dq00OHRf.js";
+import { t as LocalCommunity } from "../../chunks/local-community-D5fzgPCr.js";
 import { fileURLToPath } from "node:url";
 import path from "path";
 import assert from "assert";

package/dist/node/generated-version.d.ts

@@ -1 +1 @@
-export declare const version = "0.0.88";
+export declare const version = "0.0.89";

package/dist/node/generated-version.js

@@ -1,3 +1,3 @@
 // Auto-generated by config/generate-version.js — do not edit
-export const version = "0.0.88";
+export const version = "0.0.89";
 //# sourceMappingURL=generated-version.js.map

package/dist/node/helia/helia-for-pkc.d.ts

@@ -1,3 +1,5 @@
 import type { ParsedPKCOptions } from "../types.js";
 import { Libp2pJsClient } from "./libp2pjsClient.js";
+export declare function ipnsRouterTag(router: unknown): string;
+export declare function isLocalStoreIpnsRouter(router: unknown): boolean;
 export declare function createLibp2pJsClientOrUseExistingOne(pkcOptions: Required<Pick<ParsedPKCOptions, "httpRoutersOptions">> & Pick<ParsedPKCOptions, "dataPath"> & NonNullable<ParsedPKCOptions["libp2pJsClientsOptions"]>[number]): Promise<Libp2pJsClient>;

package/dist/node/helia/helia-for-pkc.js

@@ -1,4 +1,6 @@
-import { createHelia, libp2pDefaults } from "helia";
+import { createHeliaLight } from "helia";
+import { libp2pDefaults, withLibp2p } from "@helia/libp2p";
+import { withBitswap } from "@helia/bitswap";
 import { ipns } from "@helia/ipns";
 import { unmarshalIPNSRecord, multihashToIPNSRoutingKey } from "ipns";
 import { ipnsValidator } from "ipns/validator";
@@ -6,15 +8,15 @@ import { gossipsub } from "@libp2p/gossipsub";
 import { identify } from "@libp2p/identify";
 import extraLibp2pTransports from "../runtime/node/libp2p-extra-transports.js";
 import { CID } from "multiformats/cid";
+import { sha512 } from "multiformats/hashes/sha2";
 import { peerIdFromString } from "@libp2p/peer-id";
-import { bitswap } from "@helia/block-brokers";
 import { createBlockstoreForLibp2pJsClient } from "../runtime/node/blockstore.js";
 import { LruBlockstore } from "./lru-blockstore.js";
 import { delegatedRoutingV1HttpApiClientContentRouting } from "@helia/delegated-routing-v1-http-api-client";
 import { NotFoundError } from "@libp2p/interface";
 import { unixfs } from "@helia/unixfs";
 import { fetch as libp2pFetch } from "@libp2p/fetch";
-import { pubsub as createIpnsPubusubRouter } from "@helia/ipns/routing";
+import { pubSubIPNSRouting as createIpnsPubusubRouter } from "@helia/ipns";
 import Logger from "../logger.js";
 import { EventEmitter } from "events";
 import { PKCError } from "../pkc-error.js";
@@ -84,6 +86,16 @@ function getDelegatedRoutingFields(routers) {
     }
     return routersObj;
 }
+// @helia/ipns routers identify themselves through a literal toString() tag ("LocalStoreRouting()",
+// "HeliaRouting()", "PubSubRouting()"). Use that, never `constructor.name`: the classes are
+// module-private and bundlers mangle their names, which turned the old class-name filter into a
+// silent no-op in production builds.
+export function ipnsRouterTag(router) {
+    return String(router);
+}
+export function isLocalStoreIpnsRouter(router) {
+    return ipnsRouterTag(router) === "LocalStoreRouting()";
+}
 export async function createLibp2pJsClientOrUseExistingOne(pkcOptions) {
     if (!pkcOptions.httpRoutersOptions?.length)
         throw Error("You need to have pkc.httpRouterOptions to set up helia");
@@ -98,11 +110,16 @@ export async function createLibp2pJsClientOrUseExistingOne(pkcOptions) {
         client.countOfUsesOfInstance++;
         return client;
     }
+    // Both are set from inside the factory so that the catch handler after it can tear down
+    // whatever got started when the wiring throws part-way through: until the client lands in
+    // libp2pJsClients nothing else holds a reference to the node, and a started-but-orphaned
+    // libp2p keeps gossipsub heartbeats, bitswap and open sockets alive past pkc.destroy().
+    let startedHelia;
+    let closeBlockstore = async () => { };
     creatingLibp2pJsClients[pkcOptions.key] = (async () => {
         // A caller supplying their own heliaOptions.blockstore owns block storage entirely, so skip
         // ours rather than opening a directory or IndexedDB database nothing will read.
         let lruBlockstore;
-        let closeBlockstore = async () => { };
         if (!pkcOptions.heliaOptions?.blockstore) {
             const { blockstore: childBlockstore, persistent, defaultMaxBytes, close } = await createBlockstoreForLibp2pJsClient({
                 dataPath: pkcOptions.dataPath,
@@ -165,17 +182,45 @@ export async function createLibp2pJsClientOrUseExistingOne(pkcOptions) {
             // instance ever removes one, so an unbounded store grows for the life of the process.
             // See pkc-js#240 for the measurement behind the cap.
             blockstore: lruBlockstore,
-            blockBrokers: [bitswap()],
-            start: false,
             ...pkcOptions.heliaOptions
         };
-        const helia = await createHelia(mergedHeliaInit);
-        // Helia's default content routers are [Libp2pRouter, HTTPGatewayRouter]. We use our own
-        // gateway-fan-out logic in base-client-manager, so the HTTP gateway router here is
-        // redundant and adds latency. Filter by class name (not index) so a future helia release
-        // that re-orders the array can't silently leave the gateway in or drop libp2p routing.
-        //@ts-expect-error — helia.routing.routers is internal
-        helia.routing.routers = helia.routing.routers.filter((r) => r.constructor.name !== "HTTPGatewayRouter");
+        // helia 7's createHelia() composes withHTTP() in: a public trustless-gateway block broker
+        // plus public delegated HTTP routers and recursive gateways. We use our own gateway
+        // fan-out logic in base-client-manager and only the routers the user configured, so
+        // compose the node without any HTTP components (heliaOptions.http is excluded from the
+        // schema for that reason): bitswap is the only block broker and libp2p the only content
+        // router. withLibp2p applies libp2pDefaults with shallow per-key replace semantics (same
+        // as helia 6's createHelia): every key we set above wins outright (in particular our
+        // narrow `services` map fully replaces the default one), while keys we leave out
+        // (connectionEncrypters, streamMuxers, ...) come from helia's defaults.
+        //
+        // A caller-supplied heliaOptions.blockBrokers REPLACES bitswap, as it did under helia 6
+        // (`init.blockBrokers ?? [bitswap()]`): withBitswap() is additive, so applying it on top of
+        // the caller's list would hand a gateway-only/opt-out config bitswap sessions and dials anyway.
+        //
+        // createHeliaLight registers only sha2-256/identity and dag-pb/raw, where createHelia adds
+        // sha2-512 and the dag-cbor/dag-json/json codecs. pkc records are unixfs (dag-pb/raw) so
+        // the codecs are not needed, but nothing stops a community from publishing a sha2-512 CID
+        // (e.g. `ipfs add --hash sha2-512`) and helia looks the hasher up before the first block
+        // fetch, so keep sha2-512 to match what fetched under helia 6.
+        const { libp2p: mergedLibp2pInit, bitswap: bitswapInit, blockBrokers: callerBlockBrokers, ...heliaLightInit } = mergedHeliaInit;
+        const heliaWithLibp2p = withLibp2p(createHeliaLight({
+            ...heliaLightInit,
+            blockBrokers: callerBlockBrokers,
+            hashers: [sha512, ...(heliaLightInit.hashers ?? [])]
+        }), mergedLibp2pInit ?? {});
+        // The composition is typed as helia's default service map (dht, relay, upnp, ...) while our
+        // `services` above replaces it; HeliaWithLibp2pPubsub is the narrow map we actually run.
+        const helia = (callerBlockBrokers === undefined ? withBitswap(heliaWithLibp2p, bitswapInit) : heliaWithLibp2p);
+        // helia 7 creates libp2p lazily inside start() — the `helia.libp2p` getter throws
+        // NotStartedError until then — so start the node before wiring anything that reads it.
+        // Nothing can race the wiring below: no topic is subscribed and no dial is made until
+        // this factory returns the client.
+        // Assigned before start(): helia 7's start() has no rollback, so if a later mixin throws
+        // (e.g. bitswap's network.start() after withLibp2p already started libp2p) the node is
+        // half-started and must still be stopped by the catch below.
+        startedHelia = helia;
+        await helia.start();
         log("Initialized libp2pjs helia with key", pkcOptions.key, "peer id", helia.libp2p.peerId.toString());
         const pubsubEventHandler = new EventEmitter();
         helia.libp2p.services.pubsub.addEventListener("message", (evt) => {
@@ -185,10 +230,6 @@ export async function createLibp2pJsClientOrUseExistingOne(pkcOptions) {
             pubsubEventHandler.emit(evt.detail.topic, msgFormatted);
         });
         const heliaFs = unixfs(helia);
-        const asHeliaCatCid = (ipfsPathOrCid) => {
-            CID.parse(ipfsPathOrCid.split("/")[0]); // validate the root CID; throws on malformed input
-            return ipfsPathOrCid;
-        };
         // Issue #189: without a session, every block fetched over bitswap fires its own
         // network.findAndConnect — a findProviders query against ALL configured HTTP routers per
         // block, plus stray dials to whatever providers it discovers mid-fetch. cat() therefore
@@ -272,20 +313,51 @@ export async function createLibp2pJsClientOrUseExistingOne(pkcOptions) {
             signal.addEventListener("abort", onAbort, { once: true });
         });
         const ipnsPubsubRouter = createIpnsPubusubRouter(helia);
+        const ipnsNameResolver = ipns(helia, {
+            routers: [ipnsPubsubRouter]
+        });
+        // @helia/ipns constructs routers as [LocalStoreIPNSRouting, HeliaIPNSRouting, ...userRouters]
+        // and hands that SAME array to its resolver/publisher/republisher, so it must be mutated in
+        // place: reassigning `.routers` only changes what pkc's own loops below iterate, while
+        // ipnsNameResolver.resolve() keeps querying (and writing the local cache through) the
+        // original list. We drop LocalStoreIPNSRouting because pkc-js never publishes IPNS via
+        // @helia/ipns (kubo does that), so the local cache is always empty and just adds a wasted
+        // lookup. Keep HeliaIPNSRouting (HTTP delegated routing via helia.routing) and our pubsub
+        // router. Match by the router's toString() tag ("LocalStoreRouting()") rather than by
+        // `constructor.name`: the class is module-private and bundlers mangle its name (in 5chan's
+        // production build it becomes `dMe`), so a class-name match is a silent no-op there. The
+        // tag is a string literal and survives minification. Matching by identity (rather than
+        // by index) also means a future @helia/ipns release that re-orders the array can't make
+        // us drop the wrong router.
+        for (let i = ipnsNameResolver.routers.length - 1; i >= 0; i--) {
+            if (isLocalStoreIpnsRouter(ipnsNameResolver.routers[i]))
+                ipnsNameResolver.routers.splice(i, 1);
+        }
+        // The IPNS facade marks itself started (and runs its hourly republisher) from helia's
+        // 'start' event, which helia 7 dispatches exactly once at the end of start(), i.e. before the
+        // facade existed (its constructor walks helia's components, whose `libp2p` getter throws
+        // until start(), so it cannot be built earlier). helia 6 fell back to
+        // `libp2p.status === 'started'` and so ran the republisher; that fallback is gone in 7.
+        // Nothing in pkc depends on the facade being "started" (resolve() has no started check and
+        // pkc walks `routers` directly), so this only keeps helia-6 lifecycle parity for the
+        // republisher. start() is on the class but not on the exported IPNS interface.
+        ipnsNameResolver.start?.();
+        // The router is Startable but neither helia.start() (blockstore/datastore/routing/brokers
+        // only) nor the IPNS facade (republisher only) starts user-supplied routers. Its start()
+        // registers the libp2p/fetch topology that fills `fetchPeers`, which gates the
+        // subscription-change fast path: fetch the record over /libp2p/fetch from a server that
+        // joins the topic after our get() already ran (ipfs/helia#906) and republish it to the
+        // topic. NOTE: this path is newly enabled here, not restored. Under helia 6 nothing ever
+        // called start() on this router either, so `fetchPeers` stayed empty and the fast path
+        // never fired. It is largely redundant with the direct fetch below (issue #210) but bounded
+        // (one fetch per subscription-change event, into the router's own queue); its republish
+        // goes through raw libp2p pubsub, not pkc's mesh-gated wrapper, so a `could not publish
+        // record` error line is possible when no mesh peer exists. stop() is mirrored in stop() below.
+        await ipnsPubsubRouter.start?.();
         // The router's localStore is where gossipsub-delivered records get cached (handleRecord).
         // It's declared private but is a plain class field at runtime; the direct-fetch path below
         // writes to it to keep the cached-record invariant (issue #210).
         const ipnsPubsubLocalStore = ipnsPubsubRouter.localStore;
-        const ipnsNameResolver = ipns(helia, {
-            routers: [ipnsPubsubRouter]
-        });
-        // @helia/ipns constructs routers as [LocalStoreRouting, HeliaRouting, ...userRouters].
-        // We drop LocalStoreRouting because pkc-js never publishes IPNS via @helia/ipns (kubo
-        // does that), so the local cache is always empty and just adds a wasted lookup. Keep
-        // HeliaRouting (HTTP delegated routing via helia.routing.routers) and our PubSubRouting.
-        // Filter by class name so a future @helia/ipns release that re-orders the array can't
-        // silently drop our pubsub router.
-        ipnsNameResolver.routers = ipnsNameResolver.routers.filter((r) => r?.constructor?.name !== "LocalStoreRouting");
         // Side-channel awaitable warmup: gossipsub's pubsub.subscribe(topic) is sync and returns
         // void, so we can't make it awaitable without breaking @helia/ipns and other internal
         // callers that expect the sync contract. Instead, we expose `warmupForTopic(topic)` and
@@ -427,22 +499,17 @@ export async function createLibp2pJsClientOrUseExistingOne(pkcOptions) {
                         // See docs/protocol/delegated-ipns.md.
                         //
                         // Why call routers directly instead of ipnsNameResolver.resolve():
-                        // - @helia/ipns 9.2.x has no public single-hop / non-recursive resolve API.
-                        //   resolve() always recurses until it reaches an /ipfs/ value, and its single-hop
-                        //   primitive (#findIpnsRecord) is private — so the router layer is the only public
-                        //   way to fetch exactly one record.
-                        // - resolve()'s ResolveProgressEvents type declares ipns:resolve:success (carrying
-                        //   the per-hop IPNSRecord), but those events are never emitted in 9.2.x — only
-                        //   routing-level events fire, none carrying a record value or next-hop name. So an
-                        //   onProgress listener cannot reconstruct the hop chain either. Empirically pinned
-                        //   in test/node/community/helia-ipns-resolve-equivalence.unit.test.ts.
-                        // Upstream main has since reworked resolve() into an async generator that yields each
-                        // hop's IPNSRecord (ipfs/helia#1041) — that would replace this manual walk and even let
-                        // us warm each pubsub topic between yields — but it's unreleased; npm latest 9.2.1 still
-                        // collapses the chain to the terminal CID. So the per-hop walk stays for now.
-                        // TODO: after the @helia/ipns upgrade, re-check this — once the generator resolve() is
-                        // released, replace this router.get + ipnsValidator loop with
-                        // `for await (const { record } of ipnsNameResolver.resolve(...))`.
+                        // @helia/ipns 10 reworked resolve() into an async generator that yields one
+                        // IPNSResolveResult per hop (ipfs/helia#1041), so a single-hop read is now
+                        // technically reachable by taking the first yield. The per-hop walk stays anyway:
+                        // - the direct-fetch fast path above (libp2p/fetch from subscribers + freshly
+                        //   discovered providers, with the issue #210 cache write) has no equivalent
+                        //   inside resolve();
+                        // - per-hop pubsub warmup has to happen BEFORE that hop's record is requested, and
+                        //   resolve() requests the next hop's record internally as soon as it yields;
+                        // - per-router error aggregation below is what the tests and callers report on.
+                        // Equivalence of the resolved value with resolve() is pinned in
+                        // test/node/community/helia-ipns-resolve-equivalence.unit.test.ts.
                         // This does NOT bypass an active cache/TTL: all cache-read + TTL logic lives in the
                         // resolver's #findIpnsRecord and is gated on `nocache !== true`, but pkc always
                         // resolves IPNS with nocache:true (see resolveIpnsToCidP2P in base-client-manager),
@@ -497,7 +564,13 @@ export async function createLibp2pJsClientOrUseExistingOne(pkcOptions) {
                 // see MAX_BITSWAP_SESSION_SEED_PEERS above for the why. UnixFSComponents only
                 // needs a blockstore, and blocks fetched through the session land in the same
                 // underlying blockstore helia uses, so nothing else changes.
-                const rootCid = CID.parse(ipfsPath.split("/")[0]);
+                // ipfsPath is either a bare cid or a `<root-cid>/sub/path`; derive both parts here, once,
+                // so root and sub-path can never disagree. unixfs cat takes the root CID plus the sub-path
+                // via the `path` option. (The multiformats 13/14 split that used to force string-only cat
+                // input is gone: helia 7 and our tree share a single multiformats copy.)
+                const [rootCidString, ...ipfsSubPathSegments] = ipfsPath.split("/");
+                const rootCid = CID.parse(rootCidString);
+                const ipfsSubPath = ipfsSubPathSegments.length > 0 ? ipfsSubPathSegments.join("/") : undefined;
                 const timeoutMs = parseKuboStyleTimeoutMs(options?.timeout); // throws on unparseable timeout at call time
                 // Our own option, not kubo-rpc-client's — strip it so it never reaches unixfs cat.
                 const { bitswapSessionSeedScopeIpnsPubsubTopic, ...unixfsCatOptions } = options ?? {};
@@ -520,7 +593,8 @@ export async function createLibp2pJsClientOrUseExistingOne(pkcOptions) {
                     try {
                         for (let attempt = 0;; attempt++) {
                             const session = helia.blockstore.createSession(rootCid, {
-                                providers: getBitswapSessionSeedPeers(bitswapSessionSeedScopeIpnsPubsubTopic)
+                                // helia 7 sessions take providers as libp2p-key CIDs (or multiaddrs), not PeerIds
+                                providers: getBitswapSessionSeedPeers(bitswapSessionSeedScopeIpnsPubsubTopic).map((peerId) => peerId.toCID())
                             });
                             // Issue #218: the session broker waits on a single elected HAVE peer per
                             // block with no stall timeout, so one slow seeder holding the only HAVE
@@ -542,12 +616,9 @@ export async function createLibp2pJsClientOrUseExistingOne(pkcOptions) {
                             });
                             let yieldedAnyBytes = false;
                             try {
-                                // ipfsPath is either a bare cid or a `<root-cid>/sub/path`. Hand the whole
-                                // thing to cat as one string and never split out a `path` option — see
-                                // asHeliaCatCid above for why the `path` option would re-trip the
-                                // exporter's CID identity check.
-                                const catIterable = unixfs({ blockstore: session }).cat(asHeliaCatCid(ipfsPath), {
+                                const catIterable = unixfs({ blockstore: session }).cat(rootCid, {
                                     ...unixfsCatOptions,
+                                    path: ipfsSubPath,
                                     signal: controller.signal
                                 });
                                 for await (const chunk of catIterable) {
@@ -664,8 +735,8 @@ export async function createLibp2pJsClientOrUseExistingOne(pkcOptions) {
                     // createLibp2pJsClientOrUseExistingOne() can't grab a mid-stopping client.
                     delete libp2pJsClients[pkcOptions.key];
                     // Tear down the IPNS pubsub router's internal subscription state.
-                    // PubSubRouting (from @helia/ipns/routing) implements Startable and tracks its
-                    // own subscriptions list — without stop() those subscriptions leak past helia.
+                    // PubSubIPNSRouting (@helia/ipns) implements Startable and tracks its own
+                    // subscriptions list and fetch topology — without stop() those leak past helia.
                     for (const router of ipnsNameResolver.routers) {
                         const lifecycle = router;
                         if (typeof lifecycle.stop === "function") {
@@ -673,7 +744,7 @@ export async function createLibp2pJsClientOrUseExistingOne(pkcOptions) {
                                 await lifecycle.stop();
                             }
                             catch (e) {
-                                log.error("Error stopping IPNS router", router?.constructor?.name, e);
+                                log.error("Error stopping IPNS router", ipnsRouterTag(router), e);
                             }
                         }
                     }
@@ -735,11 +806,43 @@ export async function createLibp2pJsClientOrUseExistingOne(pkcOptions) {
             key: pkcOptions.key
         };
         const client = new Libp2pJsClient(fullInstanceWithOptions);
-        await helia.start();
         log("Helia/libp2p-js started with key", pkcOptions.key, "and peer id", helia.libp2p.peerId.toString());
         libp2pJsClients[pkcOptions.key] = client;
         return client;
-    })();
+    })().catch(async (creationError) => {
+        // The client never reached libp2pJsClients, so stop() can't be called on it: release
+        // whatever this factory started before rethrowing (mirrors the final-release path in stop()).
+        if (startedHelia) {
+            // The `libp2p` getter throws NotStartedError if start() failed before the libp2p mixin
+            // ran, in which case there is nothing to abort.
+            let connections = [];
+            try {
+                connections = startedHelia.libp2p.getConnections();
+            }
+            catch { }
+            for (const connection of connections) {
+                try {
+                    connection.abort(new Error("pkc-js libp2p instance failed to initialize"));
+                }
+                catch (e) {
+                    log.error("Error aborting libp2p connection during failed initialization", e);
+                }
+            }
+            try {
+                await startedHelia.stop();
+            }
+            catch (e) {
+                log.error("Error stopping helia after failed initialization", e);
+            }
+        }
+        try {
+            await closeBlockstore();
+        }
+        catch (e) {
+            log.error("Error closing blockstore after failed initialization", e);
+        }
+        throw creationError;
+    });
     const createdClientPromise = creatingLibp2pJsClients[pkcOptions.key];
     if (!createdClientPromise)
         throw new Error("Missing creation promise after initialization");