pikelet-wasm 0.9.0 → 0.9.1

package/CHANGELOG.md

@@ -8,6 +8,65 @@ Through 0.6.0 these were published as `pancake-wasm` and
 packages are pre-1.0: a minor bump may carry breaking changes, and each entry lists them
 first.
 
+## pikelet-wasm 0.9.1 / pikelet 0.9.1 — 2026-09-30
+
+Fixes to the layered profile shipped in 0.9.0, headlined by a chain that
+lost its abstention verdicts as soon as a layer deleted anything. Both
+packages move to 0.9.1 together, and `pikelet` requires `pikelet-wasm`
+^0.9.1 so that `pikelet mcp` serves chains with the reader fixes.
+
+### Compatibility
+
+- **Layers from `append` and `rebase` now record a parent locator** when
+  the parent is a local file under the output's directory, so the same
+  inputs produce a layer with a different identity than under 0.9.0.
+- **`--remove` and `--supersede` refuse ids they used to truncate**
+  (`1,2,3`, `12abc`, `1.5`, `1e3`); give one id per flag.
+- **A chain-member location ending in `#` plus hex is read as a pin.** A
+  full 64-hex suffix is verified against the member's identity, and a
+  shorter one is refused; it is no longer treated as part of a filename.
+
+### Fixed
+
+- **`pikelet-wasm` now exports `./package.json`.** `require.resolve('pikelet-wasm/package.json')`
+  and JSON imports of it threw `ERR_PACKAGE_PATH_NOT_EXPORTED`, which
+  tooling that reads the installed version relies on.
+- **`pikelet append` parses `--remove` and `--supersede` ids strictly.**
+  `--remove 1,2,3` used to tombstone record 1 alone, and `--remove 12abc`
+  record 12, without an error; each flag now takes exactly one decimal id.
+- **`#<sha256>` pins on chain members are enforced.** Every layered
+  producer's usage line advertised `--parent <file|url>[#identity]`, but
+  nothing parsed the pin: a local path failed as a missing file, and a URL
+  dropped the fragment and built on whatever the server returned. `--parent`,
+  `--head`, `--onto`, `--old-parent` and `--layer` now verify each pinned
+  member's manifest identity before opening anything, and refuse a
+  truncated pin.
+- **`append` and `rebase` record a parent locator by default.** They wrote
+  one only when given `--parent-locator`, so a rebased layer could not be
+  mounted from its head alone and its next rebase needed `--old-parent`.
+  When the parent is a local file under the output's directory, its relative
+  path is now recorded. An explicit `--parent-locator` is validated up front
+  instead of being written as-is and refused by every reader.
+- **A URL chain mounts from its head alone, and locator redirects are
+  confined.** Walking up from a URL head failed at the first hop ("a locator
+  needs the child's own location") because a range source carried no URL,
+  and a parent's URL would then have been read as a file path. The walk now
+  resolves each parent over HTTP. A parent named by a publisher's locator is
+  confined to the child's origin and directory at every redirect hop, as
+  5.1.1 requires; lineage and host-resolver locations are the operator's
+  choice and are not confined. `httpRangeSource` gains `url` and a
+  `redirectGuard` option.
+- **A tombstone-only layer no longer unscores its chain.** A layer that only
+  deletes records carries no vocabulary bloom, and the reader counted that
+  as a layer hiding its vocabulary, marking the whole chain
+  `drift-exceeded`: on the astro pack, deleting 3 of 3,255 records (drift
+  0.0009 against a 0.20 limit) turned every query's verdict to `unscored`.
+  The rule now applies only to layers with records, and LAYERED_PROFILE.md
+  4.5 and 5.5 say so. Tombstone-only layers already written with 0.9.0
+  score again with no rebuild.
+- **`pikelet --help` documents `append`, `compact` and `rebase`**, including
+  `--supersede`, `--allow-drift`, `--max-depth` and pins.
+
 ## pikelet-wasm 0.9.0 / pikelet 0.9.0 — 2026-09-29
 
 Everything merged to `main` since 0.8.0 that the 0.8.1 and 0.8.2 point

package/complete/index.d.ts

@@ -34,6 +34,8 @@ export interface HttpRangeSourceStats {
 
 export interface HttpRangeSource extends CompleteRangeSource {
   stats: HttpRangeSourceStats;
+  /** The URL as given, before any redirect; a layer's parent locator resolves against it. */
+  url: string;
   init(): Promise<void>;
 }
 
@@ -55,6 +57,13 @@ export declare function httpRangeSource(url: string, options?: {
    * disables. CDNs rate-limit the parallel range bursts a query issues.
    */
   maxRetries?: number;
+  /**
+   * Called with each redirect target before it is followed; throw to refuse
+   * the hop. When set, range reads never auto-follow redirects. A chain walk
+   * sets it for a parent named by a layer's locator, confining every hop to
+   * the child's origin and directory (LAYERED_PROFILE.md 5.1.1).
+   */
+  redirectGuard?: (target: string) => void;
 }): HttpRangeSource;
 
 export interface CompleteQueryResult {

package/complete/layer-chain.mjs

@@ -211,8 +211,10 @@ export function calibrationStatus({ drift, producerEnvelope, readerLimit, baseHa
     if (!baseHasFit) {
         return { status: 'none', drift, effectiveLimit, producerEnvelope: envelope, readerLimit };
     }
-    // A layer whose calibration region is `none` while the base carries a fit
-    // degrades the chain to unscored (4.5, 5.5).
+    // A layer WITH RECORDS whose calibration region is `none` while the base
+    // carries a fit degrades the chain to unscored (4.5, 5.5). The caller
+    // leaves tombstone-only layers out of everyLayerShipsBloom: they have no
+    // vocabulary for a bloom to carry.
     const status = (drift <= effectiveLimit && everyLayerShipsBloom) ? 'inherited' : 'drift-exceeded';
     return { status, drift, effectiveLimit, producerEnvelope: envelope, readerLimit };
 }

package/complete/layer-reader.mjs

@@ -26,7 +26,8 @@
 // named by the caller and a published chain could not be mounted from its head.
 
 import { openPikeletFile, readChainMemberShell, readMemberManifest, base64Bytes, LEXICAL_CANDIDATES, LEXICAL_CUTOFF } from './index.mjs';
-import { resolveParentLocation } from './layer-locator.mjs';
+import { resolveParentLocation, assertConfined } from './layer-locator.mjs';
+import { httpRangeSource } from './sources.mjs';
 import { fuseCandidates, FUSION_DEFAULTS } from './fusion.mjs';
 import { parseTombstoneSegment, firstSupersetViolation } from './tombstones.mjs';
 import { validateAgainstParent, chainIngestDeclaration, validateIngestAgainstChain, LAYER_PROFILE, MAX_DEPTH } from './layer-manifest.mjs';
@@ -83,10 +84,15 @@ async function walkToBase(head, options) {
         }
         if (!peek.isLayer) return chain;          // reached the base
         if (!peek.parent) throw new Error('a layer manifest carries no layer.parent (3.2)');
+        // A child is a URL whether it arrived as a range source or, one hop
+        // up, as the URL string a locator resolved to. Classifying every
+        // string as a file path sent that second hop to fileSource.
+        const childLocation = typeof cursor === 'string' ? cursor : (cursor.url ?? cursor.location ?? null);
+        const childIsFile = typeof cursor === 'string' && !isHttpUrl(cursor);
         const located = await resolveParentLocation(peek.parent, {
             lineage,
-            childLocation: typeof cursor === 'string' ? cursor : (cursor.url ?? cursor.location ?? null),
-            kind: typeof cursor === 'string' ? 'file' : 'url',
+            childLocation,
+            kind: childIsFile ? 'file' : 'url',
             resolveParents: options.resolveParents !== false,
             hostResolver: options.hostResolver || null,
             // A file-path locator needs realpath/dirname/join to confine
@@ -95,15 +101,27 @@ async function walkToBase(head, options) {
             // runtime-agnostic, so the Node implementation is supplied here
             // and only when a file path is actually being resolved -- a
             // browser or Worker mount is URL-only and never loads node:fs.
-            fsops: options.fsops || (typeof cursor === 'string' ? await nodeFsops() : null),
+            fsops: options.fsops || (childIsFile ? await nodeFsops() : null),
         });
         expectIdentity = peek.parent.identity;
         cursor = located.location;
+        if (typeof cursor === 'string' && isHttpUrl(cursor)) {
+            // A publisher's locator is confined to the child's origin and
+            // directory, and so is every redirect on the way to it (5.1.1).
+            // A lineage listing or host resolver is the operator's choice and
+            // may name any origin, so its redirects are not confined.
+            const confineTo = located.via === 'locator' ? childLocation : null;
+            cursor = httpRangeSource(cursor, {
+                ...(confineTo ? { redirectGuard: (target) => assertConfined(target, confineTo) } : {}),
+            });
+            await cursor.init();
+        }
         chain.unshift(cursor);
     }
     throw new Error(`walking to the base exceeded the depth limit ${maxDepth} (2.7): a layer.parent cycle or an over-deep chain`);
 }
 
+const isHttpUrl = (loc) => /^https?:\/\//i.test(loc);
 const describeLocation = (loc) => (typeof loc === 'string' ? loc : (loc?.url ?? loc?.location ?? '<source>'));
 
 // Lazily imported so a URL-only mount in a runtime without node:fs never
@@ -224,8 +242,13 @@ export async function openPikeletChain(members, options = {}) {
             if (inherited.bloomBytes && !baseBloomGeometry) {
                 throw new Error(`layer at depth ${rel.depth} ships a vocabulary bloom but the base carries none whose geometry it could match (4.5)`);
             }
+            // A missing bloom degrades the chain because it hides a layer's
+            // vocabulary from known_frac (4.5). A tombstone-only layer has no
+            // records and so no vocabulary to hide: its `none` region is the
+            // empty bloom, not a gap. Counting it took a chain that deleted 3
+            // of 3,255 records to drift-exceeded, unscoring every query.
             if (inherited.bloomBytes) layerBlooms.push(inherited.bloomBytes);
-            else everyLayerShipsBloom = false;
+            else if (!rel.tombstoneOnly) everyLayerShipsBloom = false;
 
             if (!rel.tombstoneOnly && tier.segments.has('lexical') !== baseHasLexical) {
                 throw new Error(baseHasLexical

package/complete/sources.mjs

@@ -22,6 +22,13 @@ export function httpRangeSource(url, options = {}) {
         : (options.cacheKeyParam === null || options.cacheKeyParam === false) ? null
             : String(options.cacheKeyParam);
     let full = null;
+    // A parent reached through a publisher-supplied locator is confined to the
+    // child's origin and directory, and 5.1.1 applies that rule to EVERY
+    // redirect hop before it is followed. The guard throws to refuse a hop.
+    // With a guard set, reads never auto-follow: only the HEAD walk below,
+    // which checks each hop, may move the target.
+    const redirectGuard = typeof options.redirectGuard === 'function' ? options.redirectGuard : null;
+    const readInit = (headers) => (redirectGuard ? { headers, redirect: 'error' } : { headers });
 
     // Redirect memoization. A host that answers with a redirect (GitHub
     // release assets: github.com 302s every hit to a signed CDN URL) would
@@ -46,7 +53,13 @@ export function httpRangeSource(url, options = {}) {
                     const probe = await fetch(target, { method: 'HEAD', redirect: 'manual' });
                     const location = probe.headers.get('location');
                     if (probe.status >= 300 && probe.status < 400 && location) {
-                        target = new URL(location, target).href;
+                        const next = new URL(location, target).href;
+                        if (redirectGuard) {
+                            try { redirectGuard(next); } catch (err) {
+                                throw Object.assign(new Error(`refused redirect to ${next}: ${err.message}`), { redirectRefused: true });
+                            }
+                        }
+                        target = next;
                         viaRedirect = true;
                         stats.redirects += 1;
                         continue;
@@ -64,7 +77,13 @@ export function httpRangeSource(url, options = {}) {
                     }
                     break;
                 }
-            } catch {
+            } catch (err) {
+                // A refused hop is a verdict, not a probe failure: falling back
+                // to the original URL would retry the same redirect.
+                if (redirectGuard && err?.redirectRefused) {
+                    resolving = null;
+                    throw err;
+                }
                 // HEAD unsupported or blocked: fall back to auto-follow.
                 target = url;
                 viaRedirect = false;
@@ -78,6 +97,9 @@ export function httpRangeSource(url, options = {}) {
 
     return {
         stats,
+        // The location as given, before any redirect: what a child's parent
+        // locator resolves against (5.1.1).
+        url,
         size: undefined,
         preferredParallelism: options.preferredParallelism ?? 32,
         preferredGapBytes: options.preferredGapBytes ?? 16 * 1024,
@@ -108,18 +130,18 @@ export function httpRangeSource(url, options = {}) {
             const targetFor = ({ target, viaRedirect }) => (cacheKeyParam && !viaRedirect
                 ? `${target}${target.includes('?') ? '&' : '?'}${cacheKeyParam}=${offset}-${end}`
                 : target);
-            let response = await fetch(targetFor(pinned), { headers });
+            let response = await fetch(targetFor(pinned), readInit(headers));
             if ((response.status === 401 || response.status === 403) && pinned.viaRedirect) {
                 // The pinned signed URL expired; resolve a fresh one once
                 // and retry. Concurrent reads share the re-resolution.
                 if (resolvedTarget === pinned) resolvedTarget = null;
                 stats.retries += 1;
-                response = await fetch(targetFor(await resolveTarget()), { headers });
+                response = await fetch(targetFor(await resolveTarget()), readInit(headers));
             }
             for (let attempt = 0; RETRYABLE.has(response.status) && attempt < maxRetries; attempt++) {
                 stats.retries += 1;
                 await new Promise((resolve) => setTimeout(resolve, retryDelayMs(attempt, response)));
-                response = await fetch(targetFor(resolvedTarget || pinned), { headers });
+                response = await fetch(targetFor(resolvedTarget || pinned), readInit(headers));
             }
 
             if (response.status === 206) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pikelet-wasm",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "Vector search engine and .pikelet artifact readers/builders, in WebAssembly. Compile a corpus into one self-contained, hash-verified search file, or use the underlying HNSW engine directly. Runs in Node.js, browsers, and Cloudflare Workers with no native dependencies.",
   "main": "src/pikelet.js",
   "types": "src/pikelet.d.ts",
@@ -101,7 +101,8 @@
     "./complete/layer-compact.mjs": {
       "default": "./complete/layer-compact.mjs"
     },
-    "./engine.wasm": "./dist/engine.wasm"
+    "./engine.wasm": "./dist/engine.wasm",
+    "./package.json": "./package.json"
   },
   "files": [
     "src",