wire-mesh-core 1.42.0 → 1.44.0

package/dist/domain/erasure-coding.cjs

@@ -0,0 +1,149 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/domain/erasure-coding.ts
+/**
+* K-of-N erasure coding over GF(2^8) for wire-mesh#36's mailbox-opacity case (the shard half of #34's encrypt-then-shard design): a systematic Reed-Solomon construction where the first `dataShards` shards ARE the padded input split into equal runs, and the remaining shards are parity rows of a Vandermonde-style matrix. Any `dataShards` of `totalShards` reconstruct the input -- the property a single mailbox holder must NOT have (it holds one shard and never the epoch key either).
+*
+* Deliberately hand-written rather than a dependency, the same choice the ECIES construction made: the encode format must be byte-identical across this and the Rust implementation, so both pin the SAME vectors against the documented construction rather than trusting two third-party ports to agree. The math is linear algebra over GF(2^8) with the standard 0x11d polynomial (AES's field), not cryptography.
+*
+* The construction, pinned: pad the input with zero bytes to dataShards * ceil(len / dataShards); any shard index below dataShards is that shard's own equal run; parity shard j (0-based within the parity block) has, at each byte position, the GF dot product of the data runs at that position with the coefficient row (alpha^j, alpha^(j+1), ..., alpha^(j+dataShards-1)) where alpha = 0x02 (the field's generator). Decoding: build the dataShards x dataShards submatrix of the full encode matrix selected by the surviving shards' row indices, invert it over the field, and apply it to the surviving shards' bytes. The encode matrix's first dataShards rows are the identity (systematic), so the all-data-shards case needs no inversion at all.
+*/
+/** The AES field's irreducible polynomial x^8+x^4+x^3+x+1, the conventional GF(2^8) choice. */
+const GF_POLY = 285;
+/** The bit that appears when a GF(2^8) value overflows a byte and needs the polynomial reduction. */
+const GF_OVERFLOW_BIT = 256;
+/** GF(2^8) caps total shards at 255 (a 256th row would repeat, breaking invertibility). */
+const GF_MAX_SHARDS = 255;
+const gfExp = Array.from({ length: 510 }, () => 0);
+const gfLog = Array.from({ length: 256 }, () => 0);
+{
+	let x = 1;
+	for (let power = 0; power < GF_MAX_SHARDS; power += 1) {
+		gfExp[power] = x;
+		gfLog[x] = power;
+		x <<= 1;
+		if (x & GF_OVERFLOW_BIT) x ^= GF_POLY;
+	}
+	for (let power = GF_MAX_SHARDS; power < 510; power += 1) gfExp[power] = gfExp[power - GF_MAX_SHARDS] ?? 0;
+}
+function gfMul(a, b) {
+	if (a === 0 || b === 0) return 0;
+	return gfExp[(gfLog[a] ?? 0) + (gfLog[b] ?? 0)] ?? 0;
+}
+function gfInv(a) {
+	return gfExp[GF_MAX_SHARDS - (gfLog[a] ?? 0)] ?? 1;
+}
+function validateConfig(config) {
+	const { dataShards, totalShards } = config;
+	if (!Number.isInteger(dataShards) || dataShards < 1) throw new Error(`dataShards must be a positive integer, got ${String(dataShards)}`);
+	if (!Number.isInteger(totalShards) || totalShards < dataShards) throw new Error(`totalShards must be an integer at least dataShards (${String(dataShards)}), got ${String(totalShards)}`);
+	if (totalShards > GF_MAX_SHARDS) throw new Error(`the GF(2^8) field supports at most ${String(GF_MAX_SHARDS)} shards, got ${String(totalShards)}`);
+}
+/** Row i of the encode matrix: identity rows for the data shards, alpha-power rows for parity. */
+/**
+* Row i of the encode matrix: identity rows for the data shards, Cauchy rows for parity. Cauchy, not Vandermonde, because only Cauchy guarantees EVERY square submatrix is invertible -- identity-plus-Vandermonde has singular K-subsets (found the hard way: parity-based reconstruction produced wrong bytes on some subsets). With parity row j carrying c_i = 1/(x_j XOR y_i) where x_j = row and y_i = column (all row/column values distinct across the whole matrix, no parity row index equals any data column index, so no denominator is zero), any K surviving rows reduce -- expanding along the identity rows -- to a square Cauchy submatrix, always invertible.
+*/
+function encodeMatrixRow(row, dataShards) {
+	const coefficients = Array.from({ length: dataShards }, () => 0);
+	if (row < dataShards) {
+		coefficients[row] = 1;
+		return coefficients;
+	}
+	for (let column = 0; column < dataShards; column += 1) coefficients[column] = gfInv(row ^ column);
+	return coefficients;
+}
+/** Inverts a square matrix over GF(2^8) by Gauss-Jordan with an identity augmentation. */
+function invertMatrix(matrix) {
+	const size = matrix.length;
+	const work = matrix.map((row, rowIndex) => {
+		const augmented = [...row, ...Array.from({ length: size }, () => 0)];
+		augmented[size + rowIndex] = 1;
+		return augmented;
+	});
+	for (let column = 0; column < size; column += 1) {
+		let pivotRow = -1;
+		for (let candidate = column; candidate < size; candidate += 1) if ((work[candidate]?.[column] ?? 0) !== 0) {
+			pivotRow = candidate;
+			break;
+		}
+		if (pivotRow === -1) throw new Error("matrix is singular over GF(2^8)");
+		if (pivotRow !== column) {
+			const swap = work[column] ?? [];
+			work[column] = work[pivotRow] ?? [];
+			work[pivotRow] = swap;
+		}
+		const pivotRowValues = work[column];
+		if (pivotRowValues === void 0) throw new Error("internal: pivot row vanished");
+		const pivotInverse = gfInv(pivotRowValues[column] ?? 1);
+		for (let c = 0; c < 2 * size; c += 1) pivotRowValues[c] = gfMul(pivotRowValues[c] ?? 0, pivotInverse);
+		for (let other = 0; other < size; other += 1) {
+			if (other === column) continue;
+			const factor = work[other]?.[column] ?? 0;
+			if (factor === 0) continue;
+			const target = work[other];
+			const source = work[column];
+			if (target === void 0 || source === void 0) throw new Error("internal: row vanished mid-inversion");
+			for (let c = 0; c < 2 * size; c += 1) target[c] = (target[c] ?? 0) ^ gfMul(factor, source[c] ?? 0);
+		}
+	}
+	return work.map((row) => row.slice(size));
+}
+async function encodeShards(data, config) {
+	validateConfig(config);
+	const { dataShards, totalShards } = config;
+	const shardLength = Math.ceil(data.length / dataShards);
+	const shards = [];
+	for (let i = 0; i < totalShards; i += 1) shards.push(new Uint8Array(new ArrayBuffer(shardLength)));
+	for (let i = 0; i < dataShards; i += 1) shards[i]?.set(data.subarray(i * shardLength, (i + 1) * shardLength));
+	for (let parityIndex = dataShards; parityIndex < totalShards; parityIndex += 1) {
+		const coefficients = encodeMatrixRow(parityIndex, dataShards);
+		for (let position = 0; position < shardLength; position += 1) {
+			let accumulated = 0;
+			for (let column = 0; column < dataShards; column += 1) accumulated ^= gfMul(coefficients[column] ?? 0, shards[column]?.[position] ?? 0);
+			const parityTarget = shards[parityIndex];
+			if (parityTarget !== void 0) parityTarget[position] = accumulated;
+		}
+	}
+	return Promise.resolve(shards);
+}
+async function decodeShards(presented, config, originalLength) {
+	validateConfig(config);
+	const { dataShards, totalShards } = config;
+	for (const entry of presented) if (entry.index < 0 || entry.index >= totalShards) throw new Error(`shard index ${String(entry.index)} is outside 0..${String(totalShards - 1)}`);
+	if (presented.length < dataShards) throw new Error(`need at least ${String(dataShards)} shards to reconstruct, got ${String(presented.length)}`);
+	const chosen = presented.slice(0, dataShards);
+	const firstChosen = chosen[0];
+	if (firstChosen === void 0) throw new Error("internal: chosen shard set is empty");
+	const shardLength = firstChosen.data.length;
+	const recovered = [];
+	if (chosen.every((entry) => entry.index < dataShards)) for (let dataIndex = 0; dataIndex < dataShards; dataIndex += 1) {
+		const entry = chosen.find((candidate) => candidate.index === dataIndex);
+		if (entry === void 0) throw new Error("internal: data shard missing after the all-present check");
+		recovered.push(entry.data);
+	}
+	else {
+		const inverse = invertMatrix(chosen.map((entry) => encodeMatrixRow(entry.index, dataShards)));
+		for (let dataIndex = 0; dataIndex < dataShards; dataIndex += 1) {
+			const row = new Uint8Array(shardLength);
+			for (let chosenIndex = 0; chosenIndex < dataShards; chosenIndex += 1) {
+				const coefficient = inverse[dataIndex]?.[chosenIndex] ?? 0;
+				if (coefficient === 0) continue;
+				for (let position = 0; position < shardLength; position += 1) row[position] = (row[position] ?? 0) ^ gfMul(coefficient, chosen[chosenIndex]?.data[position] ?? 0);
+			}
+			recovered.push(row);
+		}
+	}
+	const totalLength = dataShards * shardLength;
+	if (originalLength > totalLength) throw new Error(`originalLength ${String(originalLength)} exceeds the shards' capacity ${String(totalLength)} -- wrong manifest for these shards`);
+	const stitched = new Uint8Array(new ArrayBuffer(originalLength));
+	for (let position = 0; position < originalLength; position += 1) {
+		const shardIndex = Math.floor(position / shardLength);
+		const within = position % shardLength;
+		const byte = recovered[shardIndex]?.[within];
+		if (byte === void 0) throw new Error("shard position out of range while stitching");
+		stitched[position] = byte;
+	}
+	return Promise.resolve(stitched);
+}
+//#endregion
+exports.decodeShards = decodeShards;
+exports.encodeShards = encodeShards;

package/dist/domain/erasure-coding.d.cts

@@ -0,0 +1,27 @@
+//#region src/domain/erasure-coding.d.ts
+/**
+ * K-of-N erasure coding over GF(2^8) for wire-mesh#36's mailbox-opacity case (the shard half of #34's encrypt-then-shard design): a systematic Reed-Solomon construction where the first `dataShards` shards ARE the padded input split into equal runs, and the remaining shards are parity rows of a Vandermonde-style matrix. Any `dataShards` of `totalShards` reconstruct the input -- the property a single mailbox holder must NOT have (it holds one shard and never the epoch key either).
+ *
+ * Deliberately hand-written rather than a dependency, the same choice the ECIES construction made: the encode format must be byte-identical across this and the Rust implementation, so both pin the SAME vectors against the documented construction rather than trusting two third-party ports to agree. The math is linear algebra over GF(2^8) with the standard 0x11d polynomial (AES's field), not cryptography.
+ *
+ * The construction, pinned: pad the input with zero bytes to dataShards * ceil(len / dataShards); any shard index below dataShards is that shard's own equal run; parity shard j (0-based within the parity block) has, at each byte position, the GF dot product of the data runs at that position with the coefficient row (alpha^j, alpha^(j+1), ..., alpha^(j+dataShards-1)) where alpha = 0x02 (the field's generator). Decoding: build the dataShards x dataShards submatrix of the full encode matrix selected by the surviving shards' row indices, invert it over the field, and apply it to the surviving shards' bytes. The encode matrix's first dataShards rows are the identity (systematic), so the all-data-shards case needs no inversion at all.
+ */
+export interface ShardConfig {
+  dataShards: number;
+  totalShards: number;
+}
+export declare function encodeShards(data: Uint8Array, config: Readonly<ShardConfig>): Promise<Uint8Array<ArrayBuffer>[]>;
+/**
+ * Reconstructs the original bytes from any dataShards of the totalShards
+ * produced by encodeShards. originalLength is the manifest's own fact, not
+ * derivable from the shards (zero-padding is indistinguishable from a
+ * legitimate trailing zero byte), so the caller passes it -- #34's design
+ * puts the length in the shard manifest alongside the device/transfer-id list.
+ */
+/** One surviving shard as presented for reconstruction: its ORIGINAL position among the encode output (the parity equation's row index), never its position in whichever array the caller collected survivors into -- confusing the two silently reconstructs garbage, which is exactly why the index is explicit rather than implied by array order. */
+export interface PresentedShard {
+  index: number;
+  data: Uint8Array;
+}
+export declare function decodeShards(presented: readonly PresentedShard[], config: Readonly<ShardConfig>, originalLength: number): Promise<Uint8Array<ArrayBuffer>>;
+//#endregion

package/dist/domain/erasure-coding.d.mts

@@ -0,0 +1,27 @@
+//#region src/domain/erasure-coding.d.ts
+/**
+ * K-of-N erasure coding over GF(2^8) for wire-mesh#36's mailbox-opacity case (the shard half of #34's encrypt-then-shard design): a systematic Reed-Solomon construction where the first `dataShards` shards ARE the padded input split into equal runs, and the remaining shards are parity rows of a Vandermonde-style matrix. Any `dataShards` of `totalShards` reconstruct the input -- the property a single mailbox holder must NOT have (it holds one shard and never the epoch key either).
+ *
+ * Deliberately hand-written rather than a dependency, the same choice the ECIES construction made: the encode format must be byte-identical across this and the Rust implementation, so both pin the SAME vectors against the documented construction rather than trusting two third-party ports to agree. The math is linear algebra over GF(2^8) with the standard 0x11d polynomial (AES's field), not cryptography.
+ *
+ * The construction, pinned: pad the input with zero bytes to dataShards * ceil(len / dataShards); any shard index below dataShards is that shard's own equal run; parity shard j (0-based within the parity block) has, at each byte position, the GF dot product of the data runs at that position with the coefficient row (alpha^j, alpha^(j+1), ..., alpha^(j+dataShards-1)) where alpha = 0x02 (the field's generator). Decoding: build the dataShards x dataShards submatrix of the full encode matrix selected by the surviving shards' row indices, invert it over the field, and apply it to the surviving shards' bytes. The encode matrix's first dataShards rows are the identity (systematic), so the all-data-shards case needs no inversion at all.
+ */
+export interface ShardConfig {
+  dataShards: number;
+  totalShards: number;
+}
+export declare function encodeShards(data: Uint8Array, config: Readonly<ShardConfig>): Promise<Uint8Array<ArrayBuffer>[]>;
+/**
+ * Reconstructs the original bytes from any dataShards of the totalShards
+ * produced by encodeShards. originalLength is the manifest's own fact, not
+ * derivable from the shards (zero-padding is indistinguishable from a
+ * legitimate trailing zero byte), so the caller passes it -- #34's design
+ * puts the length in the shard manifest alongside the device/transfer-id list.
+ */
+/** One surviving shard as presented for reconstruction: its ORIGINAL position among the encode output (the parity equation's row index), never its position in whichever array the caller collected survivors into -- confusing the two silently reconstructs garbage, which is exactly why the index is explicit rather than implied by array order. */
+export interface PresentedShard {
+  index: number;
+  data: Uint8Array;
+}
+export declare function decodeShards(presented: readonly PresentedShard[], config: Readonly<ShardConfig>, originalLength: number): Promise<Uint8Array<ArrayBuffer>>;
+//#endregion

package/dist/domain/erasure-coding.mjs

@@ -0,0 +1,147 @@
+//#region src/domain/erasure-coding.ts
+/**
+* K-of-N erasure coding over GF(2^8) for wire-mesh#36's mailbox-opacity case (the shard half of #34's encrypt-then-shard design): a systematic Reed-Solomon construction where the first `dataShards` shards ARE the padded input split into equal runs, and the remaining shards are parity rows of a Vandermonde-style matrix. Any `dataShards` of `totalShards` reconstruct the input -- the property a single mailbox holder must NOT have (it holds one shard and never the epoch key either).
+*
+* Deliberately hand-written rather than a dependency, the same choice the ECIES construction made: the encode format must be byte-identical across this and the Rust implementation, so both pin the SAME vectors against the documented construction rather than trusting two third-party ports to agree. The math is linear algebra over GF(2^8) with the standard 0x11d polynomial (AES's field), not cryptography.
+*
+* The construction, pinned: pad the input with zero bytes to dataShards * ceil(len / dataShards); any shard index below dataShards is that shard's own equal run; parity shard j (0-based within the parity block) has, at each byte position, the GF dot product of the data runs at that position with the coefficient row (alpha^j, alpha^(j+1), ..., alpha^(j+dataShards-1)) where alpha = 0x02 (the field's generator). Decoding: build the dataShards x dataShards submatrix of the full encode matrix selected by the surviving shards' row indices, invert it over the field, and apply it to the surviving shards' bytes. The encode matrix's first dataShards rows are the identity (systematic), so the all-data-shards case needs no inversion at all.
+*/
+/** The AES field's irreducible polynomial x^8+x^4+x^3+x+1, the conventional GF(2^8) choice. */
+const GF_POLY = 285;
+/** The bit that appears when a GF(2^8) value overflows a byte and needs the polynomial reduction. */
+const GF_OVERFLOW_BIT = 256;
+/** GF(2^8) caps total shards at 255 (a 256th row would repeat, breaking invertibility). */
+const GF_MAX_SHARDS = 255;
+const gfExp = Array.from({ length: 510 }, () => 0);
+const gfLog = Array.from({ length: 256 }, () => 0);
+{
+	let x = 1;
+	for (let power = 0; power < GF_MAX_SHARDS; power += 1) {
+		gfExp[power] = x;
+		gfLog[x] = power;
+		x <<= 1;
+		if (x & GF_OVERFLOW_BIT) x ^= GF_POLY;
+	}
+	for (let power = GF_MAX_SHARDS; power < 510; power += 1) gfExp[power] = gfExp[power - GF_MAX_SHARDS] ?? 0;
+}
+function gfMul(a, b) {
+	if (a === 0 || b === 0) return 0;
+	return gfExp[(gfLog[a] ?? 0) + (gfLog[b] ?? 0)] ?? 0;
+}
+function gfInv(a) {
+	return gfExp[GF_MAX_SHARDS - (gfLog[a] ?? 0)] ?? 1;
+}
+function validateConfig(config) {
+	const { dataShards, totalShards } = config;
+	if (!Number.isInteger(dataShards) || dataShards < 1) throw new Error(`dataShards must be a positive integer, got ${String(dataShards)}`);
+	if (!Number.isInteger(totalShards) || totalShards < dataShards) throw new Error(`totalShards must be an integer at least dataShards (${String(dataShards)}), got ${String(totalShards)}`);
+	if (totalShards > GF_MAX_SHARDS) throw new Error(`the GF(2^8) field supports at most ${String(GF_MAX_SHARDS)} shards, got ${String(totalShards)}`);
+}
+/** Row i of the encode matrix: identity rows for the data shards, alpha-power rows for parity. */
+/**
+* Row i of the encode matrix: identity rows for the data shards, Cauchy rows for parity. Cauchy, not Vandermonde, because only Cauchy guarantees EVERY square submatrix is invertible -- identity-plus-Vandermonde has singular K-subsets (found the hard way: parity-based reconstruction produced wrong bytes on some subsets). With parity row j carrying c_i = 1/(x_j XOR y_i) where x_j = row and y_i = column (all row/column values distinct across the whole matrix, no parity row index equals any data column index, so no denominator is zero), any K surviving rows reduce -- expanding along the identity rows -- to a square Cauchy submatrix, always invertible.
+*/
+function encodeMatrixRow(row, dataShards) {
+	const coefficients = Array.from({ length: dataShards }, () => 0);
+	if (row < dataShards) {
+		coefficients[row] = 1;
+		return coefficients;
+	}
+	for (let column = 0; column < dataShards; column += 1) coefficients[column] = gfInv(row ^ column);
+	return coefficients;
+}
+/** Inverts a square matrix over GF(2^8) by Gauss-Jordan with an identity augmentation. */
+function invertMatrix(matrix) {
+	const size = matrix.length;
+	const work = matrix.map((row, rowIndex) => {
+		const augmented = [...row, ...Array.from({ length: size }, () => 0)];
+		augmented[size + rowIndex] = 1;
+		return augmented;
+	});
+	for (let column = 0; column < size; column += 1) {
+		let pivotRow = -1;
+		for (let candidate = column; candidate < size; candidate += 1) if ((work[candidate]?.[column] ?? 0) !== 0) {
+			pivotRow = candidate;
+			break;
+		}
+		if (pivotRow === -1) throw new Error("matrix is singular over GF(2^8)");
+		if (pivotRow !== column) {
+			const swap = work[column] ?? [];
+			work[column] = work[pivotRow] ?? [];
+			work[pivotRow] = swap;
+		}
+		const pivotRowValues = work[column];
+		if (pivotRowValues === void 0) throw new Error("internal: pivot row vanished");
+		const pivotInverse = gfInv(pivotRowValues[column] ?? 1);
+		for (let c = 0; c < 2 * size; c += 1) pivotRowValues[c] = gfMul(pivotRowValues[c] ?? 0, pivotInverse);
+		for (let other = 0; other < size; other += 1) {
+			if (other === column) continue;
+			const factor = work[other]?.[column] ?? 0;
+			if (factor === 0) continue;
+			const target = work[other];
+			const source = work[column];
+			if (target === void 0 || source === void 0) throw new Error("internal: row vanished mid-inversion");
+			for (let c = 0; c < 2 * size; c += 1) target[c] = (target[c] ?? 0) ^ gfMul(factor, source[c] ?? 0);
+		}
+	}
+	return work.map((row) => row.slice(size));
+}
+async function encodeShards(data, config) {
+	validateConfig(config);
+	const { dataShards, totalShards } = config;
+	const shardLength = Math.ceil(data.length / dataShards);
+	const shards = [];
+	for (let i = 0; i < totalShards; i += 1) shards.push(new Uint8Array(new ArrayBuffer(shardLength)));
+	for (let i = 0; i < dataShards; i += 1) shards[i]?.set(data.subarray(i * shardLength, (i + 1) * shardLength));
+	for (let parityIndex = dataShards; parityIndex < totalShards; parityIndex += 1) {
+		const coefficients = encodeMatrixRow(parityIndex, dataShards);
+		for (let position = 0; position < shardLength; position += 1) {
+			let accumulated = 0;
+			for (let column = 0; column < dataShards; column += 1) accumulated ^= gfMul(coefficients[column] ?? 0, shards[column]?.[position] ?? 0);
+			const parityTarget = shards[parityIndex];
+			if (parityTarget !== void 0) parityTarget[position] = accumulated;
+		}
+	}
+	return Promise.resolve(shards);
+}
+async function decodeShards(presented, config, originalLength) {
+	validateConfig(config);
+	const { dataShards, totalShards } = config;
+	for (const entry of presented) if (entry.index < 0 || entry.index >= totalShards) throw new Error(`shard index ${String(entry.index)} is outside 0..${String(totalShards - 1)}`);
+	if (presented.length < dataShards) throw new Error(`need at least ${String(dataShards)} shards to reconstruct, got ${String(presented.length)}`);
+	const chosen = presented.slice(0, dataShards);
+	const firstChosen = chosen[0];
+	if (firstChosen === void 0) throw new Error("internal: chosen shard set is empty");
+	const shardLength = firstChosen.data.length;
+	const recovered = [];
+	if (chosen.every((entry) => entry.index < dataShards)) for (let dataIndex = 0; dataIndex < dataShards; dataIndex += 1) {
+		const entry = chosen.find((candidate) => candidate.index === dataIndex);
+		if (entry === void 0) throw new Error("internal: data shard missing after the all-present check");
+		recovered.push(entry.data);
+	}
+	else {
+		const inverse = invertMatrix(chosen.map((entry) => encodeMatrixRow(entry.index, dataShards)));
+		for (let dataIndex = 0; dataIndex < dataShards; dataIndex += 1) {
+			const row = new Uint8Array(shardLength);
+			for (let chosenIndex = 0; chosenIndex < dataShards; chosenIndex += 1) {
+				const coefficient = inverse[dataIndex]?.[chosenIndex] ?? 0;
+				if (coefficient === 0) continue;
+				for (let position = 0; position < shardLength; position += 1) row[position] = (row[position] ?? 0) ^ gfMul(coefficient, chosen[chosenIndex]?.data[position] ?? 0);
+			}
+			recovered.push(row);
+		}
+	}
+	const totalLength = dataShards * shardLength;
+	if (originalLength > totalLength) throw new Error(`originalLength ${String(originalLength)} exceeds the shards' capacity ${String(totalLength)} -- wrong manifest for these shards`);
+	const stitched = new Uint8Array(new ArrayBuffer(originalLength));
+	for (let position = 0; position < originalLength; position += 1) {
+		const shardIndex = Math.floor(position / shardLength);
+		const within = position % shardLength;
+		const byte = recovered[shardIndex]?.[within];
+		if (byte === void 0) throw new Error("shard position out of range while stitching");
+		stitched[position] = byte;
+	}
+	return Promise.resolve(stitched);
+}
+//#endregion
+export { decodeShards, encodeShards };

package/dist/domain/shard-manifest.cjs

@@ -0,0 +1,111 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_domain_erasure_coding = require("./erasure-coding.cjs");
+let cbor2 = require("cbor2");
+//#region src/domain/shard-manifest.ts
+/**
+* The shard manifest for wire-mesh#36's mailbox-opacity delivery (the composition half of #34's erasure-coded shard design): a small self-certifying-enough record published as an ordinary opaque core/data entry, naming which device holds which shard and how many are needed to reconstruct. The manifest deliberately carries NO key material and NO shard bytes -- a mailbox reading it learns only the distribution topology, and the encrypt-then- shard ordering means even a full set of shards without the epoch key is ciphertext.
+*
+* The entry encoding is plain canonical CDE CBOR (the same discipline every core/data application entry uses), with structural validation on both encode (self-check before publishing) and decode (a malformed or internally inconsistent manifest fails loudly rather than guiding a reader into reconstructing garbage).
+*/
+/** The content-type a core/data entry carrying a shard manifest declares. */
+const SHARD_MANIFEST_CONTENT_TYPE = "application/x-wire-mesh-shard-manifest";
+function encodeShardManifest(manifest) {
+	validateManifest(manifest);
+	return new Uint8Array((0, cbor2.encode)({
+		"total-shards": manifest["total-shards"],
+		threshold: manifest.threshold,
+		"content-type": manifest["content-type"],
+		"original-length": manifest["original-length"],
+		shards: manifest.shards.map((shard) => ({
+			device: shard.device,
+			"transfer-id": shard["transfer-id"]
+		}))
+	}, cbor2.cdeEncodeOptions));
+}
+function decodeShardManifest(entry) {
+	const decoded = (0, cbor2.decode)(entry, cbor2.cdeDecodeOptions);
+	if (!isStringKeyedRecord(decoded)) throw new Error("shard manifest entry is not a CBOR map");
+	const totalShards = decoded["total-shards"];
+	const threshold = decoded.threshold;
+	const contentType = decoded["content-type"];
+	const originalLength = decoded["original-length"];
+	const shards = decoded.shards;
+	if (typeof totalShards !== "number" || typeof threshold !== "number") throw new Error("shard manifest is missing numeric total-shards/threshold");
+	if (typeof contentType !== "string" || typeof originalLength !== "number") throw new Error("shard manifest is missing content-type/original-length");
+	if (!Array.isArray(shards)) throw new Error("shard manifest is missing its shards array");
+	const manifest = {
+		"total-shards": totalShards,
+		threshold,
+		"content-type": contentType,
+		"original-length": originalLength,
+		shards: shards.map((raw) => {
+			if (!isStringKeyedRecord(raw)) throw new Error("shard manifest entry is malformed");
+			const device = raw.device;
+			const transferId = raw["transfer-id"];
+			if (!(device instanceof Uint8Array) || !(transferId instanceof Uint8Array)) throw new Error("shard manifest location is missing device/transfer-id bytes");
+			return {
+				device: Uint8Array.from(device),
+				"transfer-id": Uint8Array.from(transferId)
+			};
+		})
+	};
+	validateManifest(manifest);
+	return manifest;
+}
+/** The target for shard `index`, checked rather than asserted -- the length precondition above makes absence a caller bug worth a named error, not a silent undefined device. */
+function targetFor(targets, index, shard) {
+	const target = targets[index];
+	if (target === void 0) throw new Error(`no target device for shard ${String(index)} (${String(shard.length)} bytes)`);
+	return target;
+}
+function isStringKeyedRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function validateManifest(manifest) {
+	if (manifest.shards.length !== manifest["total-shards"]) throw new Error(`shard manifest declares ${String(manifest["total-shards"])} shards but lists ${String(manifest.shards.length)}`);
+	if (manifest.threshold < 1 || manifest.threshold > manifest["total-shards"]) throw new Error(`shard manifest threshold ${String(manifest.threshold)} must be between 1 and ${String(manifest["total-shards"])}`);
+}
+/**
+* The sender half of the composition: split `payload` (already encrypted, when the content is secret -- encrypt-then-shard, so a single holder has neither enough pieces nor the key) into shards and build the manifest naming each shard's home. The bulk transfers themselves are the caller's policy (which sessions, when) -- this module owns the bytes and the manifest, the same primitive-vs-policy split data-sync itself draws.
+*/
+async function splitForShardedDelivery(payload, options) {
+	const { config, contentType, targets, nextTransferId } = options;
+	if (targets.length < config.totalShards) throw new Error(`every shard needs a home: ${String(config.totalShards)} shards but only ${String(targets.length)} targets`);
+	const shards = await require_domain_erasure_coding.encodeShards(payload, {
+		dataShards: config.dataShards,
+		totalShards: config.totalShards
+	});
+	const manifest = {
+		"total-shards": config.totalShards,
+		threshold: config.dataShards,
+		"content-type": contentType,
+		"original-length": payload.length,
+		shards: shards.map((shard, index) => ({
+			device: targetFor(targets, index, shard),
+			"transfer-id": nextTransferId(index)
+		}))
+	};
+	validateManifest(manifest);
+	return {
+		manifest,
+		shards,
+		manifestEntry: encodeShardManifest(manifest)
+	};
+}
+/**
+* The reader half: any `threshold` shards plus the manifest reconstruct the payload -- and decrypt it, when a decryptor is given. Fails closed below the threshold (a mailbox holding fewer shards than the manifest names must not be able to read the content; that is the entire opacity property).
+*/
+async function reconstructFromShards(fetched, manifest, options = {}) {
+	const reconstructed = await require_domain_erasure_coding.decodeShards(fetched, {
+		dataShards: manifest.threshold,
+		totalShards: manifest["total-shards"]
+	}, manifest["original-length"]);
+	if (options.decrypt === void 0) return reconstructed;
+	return options.decrypt(reconstructed);
+}
+//#endregion
+exports.SHARD_MANIFEST_CONTENT_TYPE = SHARD_MANIFEST_CONTENT_TYPE;
+exports.decodeShardManifest = decodeShardManifest;
+exports.encodeShardManifest = encodeShardManifest;
+exports.reconstructFromShards = reconstructFromShards;
+exports.splitForShardedDelivery = splitForShardedDelivery;

package/dist/domain/shard-manifest.d.cts

@@ -0,0 +1,52 @@
+import { D as DeviceId } from "../protocol-gbXtNeOc.cjs";
+import { PresentedShard, ShardConfig } from "./erasure-coding.cjs";
+//#region src/domain/shard-manifest.d.ts
+/** The content-type a core/data entry carrying a shard manifest declares. */
+export declare const SHARD_MANIFEST_CONTENT_TYPE = "application/x-wire-mesh-shard-manifest";
+/** Where one shard lives: the device holding it, and the bulk transfer that delivered it. */
+export interface ShardLocation {
+  device: DeviceId;
+  "transfer-id": Uint8Array;
+}
+/** The manifest itself: N shards, any `threshold` of which reconstruct `original-length` bytes. */
+export interface ShardManifest {
+  "total-shards": number;
+  threshold: number;
+  /** The reconstructed content's own content-type (already suffixed if encrypted). */
+  "content-type": string;
+  /** The byte length the K shards reconstruct to -- the fact the shards cannot carry themselves (zero-padding is indistinguishable from a trailing zero byte). */
+  "original-length": number;
+  shards: ShardLocation[];
+}
+export declare function encodeShardManifest(manifest: Readonly<ShardManifest>): Uint8Array<ArrayBuffer>;
+export declare function decodeShardManifest(entry: Uint8Array): ShardManifest;
+/** How a split names each transfer: the caller owns transfer-id allocation, same convention mintCapabilityToken applies to token-ids. */
+export type NextTransferId = (shardIndex: number) => Uint8Array;
+export interface SplitForShardedDeliveryOptions {
+  config: Readonly<ShardConfig>;
+  /** The content's own content-type -- already +aes256gcm-suffixed when the payload is encrypted (the usual case: encrypt first, then shard). */
+  contentType: string;
+  /** One target device per shard, in shard order; every shard needs a home. */
+  targets: readonly DeviceId[];
+  nextTransferId: NextTransferId;
+}
+export interface ShardedDelivery {
+  manifest: ShardManifest;
+  /** Shard i goes to targets[i] under transfer-id nextTransferId(i); the manifest records both. */
+  shards: Uint8Array[];
+  /** The manifest itself, encoded as a publishable core/data entry. */
+  manifestEntry: Uint8Array<ArrayBuffer>;
+}
+/**
+ * The sender half of the composition: split `payload` (already encrypted, when the content is secret -- encrypt-then-shard, so a single holder has neither enough pieces nor the key) into shards and build the manifest naming each shard's home. The bulk transfers themselves are the caller's policy (which sessions, when) -- this module owns the bytes and the manifest, the same primitive-vs-policy split data-sync itself draws.
+ */
+export declare function splitForShardedDelivery(payload: Uint8Array, options: Readonly<SplitForShardedDeliveryOptions>): Promise<ShardedDelivery>;
+export interface ReconstructOptions {
+  /** The decryption step, when the reconstructed bytes are ciphertext (the usual case). Applied AFTER reconstruction, never before -- decrypt-then-shard would expose plaintext to every shard holder. */
+  decrypt?: (ciphertext: Uint8Array) => Promise<Uint8Array>;
+}
+/**
+ * The reader half: any `threshold` shards plus the manifest reconstruct the payload -- and decrypt it, when a decryptor is given. Fails closed below the threshold (a mailbox holding fewer shards than the manifest names must not be able to read the content; that is the entire opacity property).
+ */
+export declare function reconstructFromShards(fetched: readonly PresentedShard[], manifest: Readonly<ShardManifest>, options?: Readonly<ReconstructOptions>): Promise<Uint8Array>;
+//#endregion

package/dist/domain/shard-manifest.d.mts

@@ -0,0 +1,52 @@
+import { D as DeviceId } from "../protocol-gbXtNeOc.mjs";
+import { PresentedShard, ShardConfig } from "./erasure-coding.mjs";
+//#region src/domain/shard-manifest.d.ts
+/** The content-type a core/data entry carrying a shard manifest declares. */
+export declare const SHARD_MANIFEST_CONTENT_TYPE = "application/x-wire-mesh-shard-manifest";
+/** Where one shard lives: the device holding it, and the bulk transfer that delivered it. */
+export interface ShardLocation {
+  device: DeviceId;
+  "transfer-id": Uint8Array;
+}
+/** The manifest itself: N shards, any `threshold` of which reconstruct `original-length` bytes. */
+export interface ShardManifest {
+  "total-shards": number;
+  threshold: number;
+  /** The reconstructed content's own content-type (already suffixed if encrypted). */
+  "content-type": string;
+  /** The byte length the K shards reconstruct to -- the fact the shards cannot carry themselves (zero-padding is indistinguishable from a trailing zero byte). */
+  "original-length": number;
+  shards: ShardLocation[];
+}
+export declare function encodeShardManifest(manifest: Readonly<ShardManifest>): Uint8Array<ArrayBuffer>;
+export declare function decodeShardManifest(entry: Uint8Array): ShardManifest;
+/** How a split names each transfer: the caller owns transfer-id allocation, same convention mintCapabilityToken applies to token-ids. */
+export type NextTransferId = (shardIndex: number) => Uint8Array;
+export interface SplitForShardedDeliveryOptions {
+  config: Readonly<ShardConfig>;
+  /** The content's own content-type -- already +aes256gcm-suffixed when the payload is encrypted (the usual case: encrypt first, then shard). */
+  contentType: string;
+  /** One target device per shard, in shard order; every shard needs a home. */
+  targets: readonly DeviceId[];
+  nextTransferId: NextTransferId;
+}
+export interface ShardedDelivery {
+  manifest: ShardManifest;
+  /** Shard i goes to targets[i] under transfer-id nextTransferId(i); the manifest records both. */
+  shards: Uint8Array[];
+  /** The manifest itself, encoded as a publishable core/data entry. */
+  manifestEntry: Uint8Array<ArrayBuffer>;
+}
+/**
+ * The sender half of the composition: split `payload` (already encrypted, when the content is secret -- encrypt-then-shard, so a single holder has neither enough pieces nor the key) into shards and build the manifest naming each shard's home. The bulk transfers themselves are the caller's policy (which sessions, when) -- this module owns the bytes and the manifest, the same primitive-vs-policy split data-sync itself draws.
+ */
+export declare function splitForShardedDelivery(payload: Uint8Array, options: Readonly<SplitForShardedDeliveryOptions>): Promise<ShardedDelivery>;
+export interface ReconstructOptions {
+  /** The decryption step, when the reconstructed bytes are ciphertext (the usual case). Applied AFTER reconstruction, never before -- decrypt-then-shard would expose plaintext to every shard holder. */
+  decrypt?: (ciphertext: Uint8Array) => Promise<Uint8Array>;
+}
+/**
+ * The reader half: any `threshold` shards plus the manifest reconstruct the payload -- and decrypt it, when a decryptor is given. Fails closed below the threshold (a mailbox holding fewer shards than the manifest names must not be able to read the content; that is the entire opacity property).
+ */
+export declare function reconstructFromShards(fetched: readonly PresentedShard[], manifest: Readonly<ShardManifest>, options?: Readonly<ReconstructOptions>): Promise<Uint8Array>;
+//#endregion

package/dist/domain/shard-manifest.mjs

@@ -0,0 +1,106 @@
+import { decodeShards, encodeShards } from "./erasure-coding.mjs";
+import { cdeDecodeOptions, cdeEncodeOptions, decode, encode } from "cbor2";
+//#region src/domain/shard-manifest.ts
+/**
+* The shard manifest for wire-mesh#36's mailbox-opacity delivery (the composition half of #34's erasure-coded shard design): a small self-certifying-enough record published as an ordinary opaque core/data entry, naming which device holds which shard and how many are needed to reconstruct. The manifest deliberately carries NO key material and NO shard bytes -- a mailbox reading it learns only the distribution topology, and the encrypt-then- shard ordering means even a full set of shards without the epoch key is ciphertext.
+*
+* The entry encoding is plain canonical CDE CBOR (the same discipline every core/data application entry uses), with structural validation on both encode (self-check before publishing) and decode (a malformed or internally inconsistent manifest fails loudly rather than guiding a reader into reconstructing garbage).
+*/
+/** The content-type a core/data entry carrying a shard manifest declares. */
+const SHARD_MANIFEST_CONTENT_TYPE = "application/x-wire-mesh-shard-manifest";
+function encodeShardManifest(manifest) {
+	validateManifest(manifest);
+	return new Uint8Array(encode({
+		"total-shards": manifest["total-shards"],
+		threshold: manifest.threshold,
+		"content-type": manifest["content-type"],
+		"original-length": manifest["original-length"],
+		shards: manifest.shards.map((shard) => ({
+			device: shard.device,
+			"transfer-id": shard["transfer-id"]
+		}))
+	}, cdeEncodeOptions));
+}
+function decodeShardManifest(entry) {
+	const decoded = decode(entry, cdeDecodeOptions);
+	if (!isStringKeyedRecord(decoded)) throw new Error("shard manifest entry is not a CBOR map");
+	const totalShards = decoded["total-shards"];
+	const threshold = decoded.threshold;
+	const contentType = decoded["content-type"];
+	const originalLength = decoded["original-length"];
+	const shards = decoded.shards;
+	if (typeof totalShards !== "number" || typeof threshold !== "number") throw new Error("shard manifest is missing numeric total-shards/threshold");
+	if (typeof contentType !== "string" || typeof originalLength !== "number") throw new Error("shard manifest is missing content-type/original-length");
+	if (!Array.isArray(shards)) throw new Error("shard manifest is missing its shards array");
+	const manifest = {
+		"total-shards": totalShards,
+		threshold,
+		"content-type": contentType,
+		"original-length": originalLength,
+		shards: shards.map((raw) => {
+			if (!isStringKeyedRecord(raw)) throw new Error("shard manifest entry is malformed");
+			const device = raw.device;
+			const transferId = raw["transfer-id"];
+			if (!(device instanceof Uint8Array) || !(transferId instanceof Uint8Array)) throw new Error("shard manifest location is missing device/transfer-id bytes");
+			return {
+				device: Uint8Array.from(device),
+				"transfer-id": Uint8Array.from(transferId)
+			};
+		})
+	};
+	validateManifest(manifest);
+	return manifest;
+}
+/** The target for shard `index`, checked rather than asserted -- the length precondition above makes absence a caller bug worth a named error, not a silent undefined device. */
+function targetFor(targets, index, shard) {
+	const target = targets[index];
+	if (target === void 0) throw new Error(`no target device for shard ${String(index)} (${String(shard.length)} bytes)`);
+	return target;
+}
+function isStringKeyedRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function validateManifest(manifest) {
+	if (manifest.shards.length !== manifest["total-shards"]) throw new Error(`shard manifest declares ${String(manifest["total-shards"])} shards but lists ${String(manifest.shards.length)}`);
+	if (manifest.threshold < 1 || manifest.threshold > manifest["total-shards"]) throw new Error(`shard manifest threshold ${String(manifest.threshold)} must be between 1 and ${String(manifest["total-shards"])}`);
+}
+/**
+* The sender half of the composition: split `payload` (already encrypted, when the content is secret -- encrypt-then-shard, so a single holder has neither enough pieces nor the key) into shards and build the manifest naming each shard's home. The bulk transfers themselves are the caller's policy (which sessions, when) -- this module owns the bytes and the manifest, the same primitive-vs-policy split data-sync itself draws.
+*/
+async function splitForShardedDelivery(payload, options) {
+	const { config, contentType, targets, nextTransferId } = options;
+	if (targets.length < config.totalShards) throw new Error(`every shard needs a home: ${String(config.totalShards)} shards but only ${String(targets.length)} targets`);
+	const shards = await encodeShards(payload, {
+		dataShards: config.dataShards,
+		totalShards: config.totalShards
+	});
+	const manifest = {
+		"total-shards": config.totalShards,
+		threshold: config.dataShards,
+		"content-type": contentType,
+		"original-length": payload.length,
+		shards: shards.map((shard, index) => ({
+			device: targetFor(targets, index, shard),
+			"transfer-id": nextTransferId(index)
+		}))
+	};
+	validateManifest(manifest);
+	return {
+		manifest,
+		shards,
+		manifestEntry: encodeShardManifest(manifest)
+	};
+}
+/**
+* The reader half: any `threshold` shards plus the manifest reconstruct the payload -- and decrypt it, when a decryptor is given. Fails closed below the threshold (a mailbox holding fewer shards than the manifest names must not be able to read the content; that is the entire opacity property).
+*/
+async function reconstructFromShards(fetched, manifest, options = {}) {
+	const reconstructed = await decodeShards(fetched, {
+		dataShards: manifest.threshold,
+		totalShards: manifest["total-shards"]
+	}, manifest["original-length"]);
+	if (options.decrypt === void 0) return reconstructed;
+	return options.decrypt(reconstructed);
+}
+//#endregion
+export { SHARD_MANIFEST_CONTENT_TYPE, decodeShardManifest, encodeShardManifest, reconstructFromShards, splitForShardedDelivery };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wire-mesh-core",
-  "version": "1.42.0",
+  "version": "1.44.0",
   "type": "module",
   "packageManager": "pnpm@12.4.1+sha512.2e81e399d73fe8390dab25e06aa788ab7a5908248d2f5a370f82b481147a6a7a367bf8048f9a6fdb6460f21a66f0542dedb8b94ca2c8723596741920b1656d4c",
   "repository": {
@@ -110,6 +110,10 @@
       "import": "./dist/domain/device-id.mjs",
       "require": "./dist/domain/device-id.cjs"
     },
+    "./domain/erasure-coding": {
+      "import": "./dist/domain/erasure-coding.mjs",
+      "require": "./dist/domain/erasure-coding.cjs"
+    },
     "./domain/grant-candidates": {
       "import": "./dist/domain/grant-candidates.mjs",
       "require": "./dist/domain/grant-candidates.cjs"
@@ -158,6 +162,10 @@
       "import": "./dist/domain/room-token-verification.mjs",
       "require": "./dist/domain/room-token-verification.cjs"
     },
+    "./domain/shard-manifest": {
+      "import": "./dist/domain/shard-manifest.mjs",
+      "require": "./dist/domain/shard-manifest.cjs"
+    },
     "./domain/tokens": {
       "import": "./dist/domain/tokens.mjs",
       "require": "./dist/domain/tokens.cjs"