@markii/bundle 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sadigaxund
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,5 @@
+# @markii/bundle
+
+Bundle (`.mkbundle`) storage and policy handling for [Mark](https://github.com/sadigaxund/markii): manifest parsing/validation, a bundle-relative path-jail, the zip storage form (via `fflate`), a Node-only directory storage form (`./fs` subpath), and a capability-restricted script view. No React, no markdown parsing.
+
+See the [repository](https://github.com/sadigaxund/markii) for the format spec and the reference library as a whole.

package/dist/errors.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Thrown by a `BundleStorage` implementation when a path fails the
+ * path-jail (`normalizeBundlePath`), or — for the directory form (`./fs`)
+ * — when the real filesystem doesn't behave like the jailed logical path
+ * promised: a symlink anywhere along the path (`resolveInsideRoot`'s
+ * lstat-per-component walk), a resolved path that diverges from the
+ * requested one, or an existing file with more than one hard link
+ * (`writeExistingFileNoHardlink`, refusing to write through a path that
+ * aliases some other file — possibly outside the bundle entirely). All of
+ * these are the same class of violation from the caller's perspective:
+ * "this path does not stay inside the bundle."
+ */
+export declare class BundlePathError extends Error {
+    readonly path: string;
+    readonly reason: string;
+    constructor(path: string, reason: string);
+}
+/**
+ * Thrown by `openZipBundle` when the archive contains one or more entries
+ * whose names fail the path-jail (zip-slip candidates: `../`, absolute
+ * paths, backslash paths, drive letters). Deliberately loud — a tampered
+ * bundle is rejected outright, never silently pruned to "the safe entries."
+ */
+export declare class BundleZipError extends Error {
+    readonly entries: readonly string[];
+    constructor(message: string, entries: readonly string[]);
+}
+/**
+ * Thrown by a `ScriptView` (see `./script-view`) when the manifest does not
+ * grant the capability a call requires. Distinct from `BundlePathError`:
+ * this is a permissions failure, not a malformed-path failure, and a future
+ * script runtime should be able to tell the two apart (e.g. to show "needs
+ * permission" vs. "invalid path" to the note author).
+ */
+export declare class ScriptCapabilityError extends Error {
+    constructor(message: string);
+}

package/dist/errors.js

@@ -0,0 +1,49 @@
+/**
+ * Thrown by a `BundleStorage` implementation when a path fails the
+ * path-jail (`normalizeBundlePath`), or — for the directory form (`./fs`)
+ * — when the real filesystem doesn't behave like the jailed logical path
+ * promised: a symlink anywhere along the path (`resolveInsideRoot`'s
+ * lstat-per-component walk), a resolved path that diverges from the
+ * requested one, or an existing file with more than one hard link
+ * (`writeExistingFileNoHardlink`, refusing to write through a path that
+ * aliases some other file — possibly outside the bundle entirely). All of
+ * these are the same class of violation from the caller's perspective:
+ * "this path does not stay inside the bundle."
+ */
+export class BundlePathError extends Error {
+    path;
+    reason;
+    constructor(path, reason) {
+        super(`invalid bundle path ${JSON.stringify(path)}: ${reason}`);
+        this.name = 'BundlePathError';
+        this.path = path;
+        this.reason = reason;
+    }
+}
+/**
+ * Thrown by `openZipBundle` when the archive contains one or more entries
+ * whose names fail the path-jail (zip-slip candidates: `../`, absolute
+ * paths, backslash paths, drive letters). Deliberately loud — a tampered
+ * bundle is rejected outright, never silently pruned to "the safe entries."
+ */
+export class BundleZipError extends Error {
+    entries;
+    constructor(message, entries) {
+        super(message);
+        this.name = 'BundleZipError';
+        this.entries = entries;
+    }
+}
+/**
+ * Thrown by a `ScriptView` (see `./script-view`) when the manifest does not
+ * grant the capability a call requires. Distinct from `BundlePathError`:
+ * this is a permissions failure, not a malformed-path failure, and a future
+ * script runtime should be able to tell the two apart (e.g. to show "needs
+ * permission" vs. "invalid path" to the note author).
+ */
+export class ScriptCapabilityError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ScriptCapabilityError';
+    }
+}

package/dist/fs.d.ts

@@ -0,0 +1,25 @@
+import type { BundleStorage } from './storage.js';
+import { type OpenZipBundleOptions } from './zip.js';
+/**
+ * Opens the directory form of a bundle: reads/writes go straight to disk
+ * under `rootDir`, with every operation re-verified against symlink escape
+ * (see `resolveInsideRoot`) and, on write, against hard-link aliasing (see
+ * `writeExistingFileNoHardlink`). `rootDir` must already exist.
+ */
+export declare function openDirBundle(rootDir: string): BundleStorage;
+/**
+ * Scaffolds a brand-new bundle directory: `dir/note.mk.md` with `smdText` as
+ * its content, plus a default `dir/manifest.json` (no permissions granted,
+ * no packs declared). Creates `dir` if it doesn't already exist.
+ */
+export declare function promoteToBundle(smdText: string, dir: string, specVersion?: string): Promise<void>;
+/** Zips up an existing bundle directory. Reuses `openDirBundle` + `exportZipBundle` from `./zip`. */
+export declare function dirToZip(rootDir: string): Promise<Uint8Array>;
+/**
+ * Extracts a zip bundle into `destDir` (created if missing). Inherits
+ * `openZipBundle`'s zip-slip/collision/decompression-bomb/CRC rejection —
+ * a tampered or malformed zip throws `BundleZipError` before anything is
+ * written to disk. `options` is forwarded to `openZipBundle` (see there for
+ * the decompression-size-budget knobs).
+ */
+export declare function zipToDir(bytes: Uint8Array, destDir: string, options?: OpenZipBundleOptions): Promise<void>;

package/dist/fs.js

@@ -0,0 +1,249 @@
+// Node-only: exported solely via the "./fs" subpath (see package.json),
+// mirroring @markii/core's "./corpus" split — a browser bundler resolving
+// this package's main entry never has to reason about `node:fs`.
+import { lstat, mkdir, open, readFile, readdir, realpath, stat, writeFile, } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { BundlePathError } from './errors.js';
+import { createDefaultManifest, CURRENT_SPEC_VERSION } from './manifest.js';
+import { normalizeOrThrow } from './storage.js';
+import { exportZipBundle, openZipBundle, } from './zip.js';
+function isErrnoException(err) {
+    return err instanceof Error && 'code' in err;
+}
+function isEnoent(err) {
+    return isErrnoException(err) && err.code === 'ENOENT';
+}
+/**
+ * `ENOTDIR` shows up when an *earlier* path component turns out to be a
+ * plain file instead of a directory (e.g. writing `cache/data.json/sub`
+ * when `cache/data.json` already exists as a file) — treated the same as
+ * "doesn't exist yet" by the lstat walk below, deferring the actual clear
+ * error to the subsequent `mkdir`/`writeFile`/`open` call.
+ */
+function isEnoentLike(err) {
+    return (isErrnoException(err) && (err.code === 'ENOENT' || err.code === 'ENOTDIR'));
+}
+/**
+ * Resolves `rootAbs/relPath` (both already-safe: `relPath` has passed
+ * `normalizeOrThrow`) against the real filesystem, refusing to follow any
+ * symlink anywhere along the way — this is the storage-layer half of
+ * closing ESCAPE 1/2/3 from the independent security review: the path-jail
+ * in `./paths` only reasons about the *logical* path string, but the actual
+ * filesystem write/read *follows symlinks*, so a symlink planted anywhere
+ * inside the bundle (even one that resolves to somewhere still nominally
+ * "inside the bundle root", like `cache/pwn -> ../manifest.json`) can
+ * silently retarget an otherwise-innocuous-looking write.
+ *
+ * Two layers, in order:
+ *
+ * 1. **Primary defense — lstat every path component.** Walk `relPath`
+ *    segment by segment from `rootAbs`, `lstat`-ing each one (never
+ *    `stat`, which would itself follow a symlink). The moment any
+ *    *existing* component is a symlink — file or directory, leaf or
+ *    ancestor, whether or not it resolves inside or outside the root — the
+ *    whole operation is rejected. This alone defeats ESCAPE 1 (`cache/pwn`
+ *    symlinked to `../manifest.json`) and its directory variant
+ *    (`cache/up` symlinked to `..`, then `cache/up/manifest.json` or even
+ *    `cache/up/not-yet-created.txt`): the symlinked component is caught
+ *    before we ever ask whether its target exists.
+ * 2. **Defense in depth — resolved-path re-check.** Once the walk finds
+ *    the nearest existing ancestor (the leaf itself may not exist yet,
+ *    e.g. a fresh write), that ancestor is symlink-free by construction
+ *    (step 1 proved it), so its `realpath` is expected to equal its literal
+ *    path exactly. We compute that anyway and assert it — effectively
+ *    "re-run the write policy on the resolved path": since resolved path
+ *    and logical path are now provably identical, whatever policy check a
+ *    caller (e.g. `ScriptView.write`, gated on `isWriteAllowed`) already
+ *    ran against the logical path remains valid for what actually gets
+ *    touched on disk. A mismatch here (mount points, case-insensitive
+ *    filesystems, or a bug in step 1) is rejected rather than trusted.
+ *
+ * TOCTOU note: there is an unavoidable gap between this check and the
+ * `open`/`readFile`/`writeFile` call that follows it (and a second, smaller
+ * gap inside `write` between opening the file and hard-link-checking it —
+ * see there). Closing that gap completely would require doing everything
+ * through `O_NOFOLLOW`-opened file descriptors end-to-end, which Node's
+ * high-level `fs/promises` API does not expose uniformly across platforms.
+ * The threat model here is a *hostile script running inside this process*
+ * (§10) manipulating the bundle's own files between our checks — not a
+ * concurrent, privileged local-filesystem attacker racing the filesystem
+ * from *outside* the process, which is out of scope (same assumption the
+ * rest of this package makes: a bundle's own directory isn't being
+ * concurrently rewritten by an unrelated actor while we operate on it).
+ *
+ * Returns the plain (non-realpath) `rootAbs`-joined path for the caller to
+ * actually operate on, plus whether a filesystem entry currently exists at
+ * that path (so `write` can decide between "fresh file" and "must check
+ * hard-link count before touching an existing one").
+ */
+async function resolveInsideRoot(rootAbs, relPath) {
+    const rootReal = await realpath(rootAbs);
+    const segments = relPath.split('/');
+    let current = rootAbs;
+    let consumed = 0;
+    for (; consumed < segments.length; consumed++) {
+        const segment = segments[consumed];
+        const next = join(current, segment);
+        let st;
+        try {
+            st = await lstat(next);
+        }
+        catch (err) {
+            if (isEnoentLike(err))
+                break;
+            throw err;
+        }
+        if (st.isSymbolicLink()) {
+            throw new BundlePathError(relPath, `path component ${JSON.stringify(segments.slice(0, consumed + 1).join('/'))} is a symlink — symlinks inside a bundle are never followed`);
+        }
+        current = next;
+    }
+    const exists = consumed === segments.length;
+    // Defense-in-depth resolved-path re-check (see doc comment above).
+    const existingReal = current === rootAbs ? rootReal : await realpath(current);
+    const rel = relative(rootReal, existingReal);
+    if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+        throw new BundlePathError(relPath, 'resolved path escapes the bundle root');
+    }
+    const relNormalized = rel.length === 0 ? '' : rel.split(sep).join('/');
+    const expectedPrefix = segments.slice(0, consumed).join('/');
+    if (relNormalized !== expectedPrefix) {
+        throw new BundlePathError(relPath, 'resolved path does not match the requested bundle-relative path (possible symlink or mount-point redirection)');
+    }
+    return { target: join(rootAbs, relPath), exists };
+}
+/**
+ * Writes `data` to an already symlink-checked `target` that is known to
+ * exist, refusing to write through a hard link (ESCAPE 3: `st_nlink > 1`
+ * means some other path — possibly outside the bundle entirely, e.g.
+ * `ln b.mkbundle/../victim.txt b.mkbundle/cache/hard` — refers to the exact same
+ * inode, so writing here would also silently modify that other path).
+ *
+ * Opens the file first *without* truncating (`'r+'`), `fstat`s the open
+ * file descriptor (not a separate `stat(path)` call — checking the fd
+ * avoids a second TOCTOU window between "check nlink" and "open the file
+ * we checked"), and only truncates + writes once the link count is
+ * confirmed to be exactly 1.
+ */
+async function writeExistingFileNoHardlink(target, relPath, data) {
+    const handle = await open(target, 'r+');
+    try {
+        const st = await handle.stat();
+        if (st.nlink > 1) {
+            throw new BundlePathError(relPath, `refusing to write through a hard-linked file (${st.nlink} links) — writing would also modify the other link target(s)`);
+        }
+        await handle.truncate(0);
+        if (data.length > 0) {
+            await handle.write(data, 0, data.length, 0);
+        }
+    }
+    finally {
+        await handle.close();
+    }
+}
+/**
+ * Opens the directory form of a bundle: reads/writes go straight to disk
+ * under `rootDir`, with every operation re-verified against symlink escape
+ * (see `resolveInsideRoot`) and, on write, against hard-link aliasing (see
+ * `writeExistingFileNoHardlink`). `rootDir` must already exist.
+ */
+export function openDirBundle(rootDir) {
+    const rootAbs = resolve(rootDir);
+    return {
+        async read(path) {
+            const relPath = normalizeOrThrow(path);
+            const { target } = await resolveInsideRoot(rootAbs, relPath);
+            try {
+                const buf = await readFile(target);
+                // `readFile` resolves a Node `Buffer` (a `Uint8Array` subclass).
+                // Re-view it as a plain `Uint8Array` so callers get the type this
+                // interface promises, not an implementation detail that happens to
+                // compare unequal to a literal `Uint8Array` under deep-equality.
+                return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+            }
+            catch (err) {
+                if (isEnoent(err))
+                    return undefined;
+                throw err;
+            }
+        },
+        async write(path, data) {
+            const relPath = normalizeOrThrow(path);
+            const { target, exists } = await resolveInsideRoot(rootAbs, relPath);
+            if (exists) {
+                await writeExistingFileNoHardlink(target, relPath, data);
+                return;
+            }
+            await mkdir(dirname(target), { recursive: true });
+            await writeFile(target, data);
+        },
+        async list() {
+            const results = [];
+            const walk = async (dirAbs, prefix) => {
+                const entries = await readdir(dirAbs, { withFileTypes: true });
+                for (const entry of entries) {
+                    // Never follow symlinked entries during enumeration: a symlink
+                    // planted inside the bundle dir could otherwise leak the
+                    // directory structure (or contents) of wherever it points.
+                    if (entry.isSymbolicLink())
+                        continue;
+                    const entryRelPath = prefix ? `${prefix}/${entry.name}` : entry.name;
+                    if (entry.isDirectory()) {
+                        await walk(join(dirAbs, entry.name), entryRelPath);
+                    }
+                    else if (entry.isFile()) {
+                        results.push(entryRelPath);
+                    }
+                }
+            };
+            await walk(rootAbs, '');
+            return results.sort();
+        },
+        async exists(path) {
+            const relPath = normalizeOrThrow(path);
+            const { target } = await resolveInsideRoot(rootAbs, relPath);
+            try {
+                const info = await stat(target);
+                return info.isFile();
+            }
+            catch (err) {
+                if (isEnoent(err))
+                    return false;
+                throw err;
+            }
+        },
+    };
+}
+/**
+ * Scaffolds a brand-new bundle directory: `dir/note.mk.md` with `smdText` as
+ * its content, plus a default `dir/manifest.json` (no permissions granted,
+ * no packs declared). Creates `dir` if it doesn't already exist.
+ */
+export async function promoteToBundle(smdText, dir, specVersion = CURRENT_SPEC_VERSION) {
+    const dirAbs = resolve(dir);
+    await mkdir(dirAbs, { recursive: true });
+    await writeFile(join(dirAbs, 'note.mk.md'), smdText, 'utf8');
+    const manifest = createDefaultManifest(specVersion);
+    await writeFile(join(dirAbs, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+}
+/** Zips up an existing bundle directory. Reuses `openDirBundle` + `exportZipBundle` from `./zip`. */
+export async function dirToZip(rootDir) {
+    return exportZipBundle(openDirBundle(rootDir));
+}
+/**
+ * Extracts a zip bundle into `destDir` (created if missing). Inherits
+ * `openZipBundle`'s zip-slip/collision/decompression-bomb/CRC rejection —
+ * a tampered or malformed zip throws `BundleZipError` before anything is
+ * written to disk. `options` is forwarded to `openZipBundle` (see there for
+ * the decompression-size-budget knobs).
+ */
+export async function zipToDir(bytes, destDir, options) {
+    const src = openZipBundle(bytes, options); // throws BundleZipError on unsafe/oversized/corrupt entries
+    await mkdir(resolve(destDir), { recursive: true });
+    const dest = openDirBundle(destDir);
+    for (const path of await src.list()) {
+        const data = await src.read(path);
+        if (data !== undefined)
+            await dest.write(path, data);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export type { BundleManifest, BundlePermissions, ManifestParseResult, } from './manifest.js';
+export { CURRENT_SPEC_VERSION, createDefaultManifest, parseManifest, } from './manifest.js';
+export type { BundleFsGrant, BundleWritePolicy, NormalizePathResult, } from './paths.js';
+export { isWriteAllowed, normalizeBundlePath } from './paths.js';
+export type { BundleStorage } from './storage.js';
+export { normalizeOrThrow } from './storage.js';
+export { BundlePathError, BundleZipError, ScriptCapabilityError, } from './errors.js';
+export type { OpenZipBundleOptions } from './zip.js';
+export { DEFAULT_MAX_ZIP_ENTRY_BYTES, DEFAULT_MAX_ZIP_TOTAL_BYTES, exportZipBundle, openZipBundle, } from './zip.js';
+export type { ScriptView } from './script-view.js';
+export { createScriptView, grantAllDeclaredPermissions, } from './script-view.js';

package/dist/index.js

@@ -0,0 +1,12 @@
+// This is @markii/bundle's browser-safe entry point: manifest handling, the
+// path-jail, the zip storage form (fflate has no Node dependency), and the
+// script capability view. The directory storage form touches `node:fs` and
+// lives at the `@markii/bundle/fs` subpath instead (mirroring @markii/core's
+// `./corpus` split), so a browser bundler consuming this package's main
+// entry never has to reason about Node builtins reachable from it.
+export { CURRENT_SPEC_VERSION, createDefaultManifest, parseManifest, } from './manifest.js';
+export { isWriteAllowed, normalizeBundlePath } from './paths.js';
+export { normalizeOrThrow } from './storage.js';
+export { BundlePathError, BundleZipError, ScriptCapabilityError, } from './errors.js';
+export { DEFAULT_MAX_ZIP_ENTRY_BYTES, DEFAULT_MAX_ZIP_TOTAL_BYTES, exportZipBundle, openZipBundle, } from './zip.js';
+export { createScriptView, grantAllDeclaredPermissions, } from './script-view.js';

package/dist/manifest.d.ts

@@ -0,0 +1,56 @@
+import type { BundleFsGrant } from './paths.js';
+/**
+ * `manifest.json`'s contract (spec §9–§11). `mark` is the only required
+ * field. The index signature keeps unrecognized top-level keys typed as
+ * `unknown` rather than dropped — `parseManifest` preserves them verbatim
+ * (see the "forward compatibility" note there) so a manifest written by a
+ * newer spec version round-trips through an older implementation intact.
+ */
+export interface BundleManifest {
+    /** Spec semver this bundle was authored against, e.g. `"0.1.0"`. */
+    mark: string;
+    permissions?: BundlePermissions;
+    uses?: string[];
+    [key: string]: unknown;
+}
+export interface BundlePermissions {
+    net?: {
+        /** Bare hostnames (no scheme/port/path/wildcard) allowed for GET. */
+        get?: string[];
+        /** Bare hostnames allowed for POST. */
+        post?: string[];
+    };
+    /** Bundle-filesystem grants; see `isWriteAllowed` in `./paths`. */
+    bundle?: BundleFsGrant[];
+}
+export type ManifestParseResult = {
+    ok: true;
+    manifest: BundleManifest;
+    warnings: string[];
+} | {
+    ok: false;
+    errors: string[];
+};
+/** The current spec version this package's default manifests declare. */
+export declare const CURRENT_SPEC_VERSION = "0.1.0";
+/**
+ * Hand-rolled `manifest.json` validation (no schema library — see CLAUDE.md
+ * dependency policy). Never throws: malformed JSON, a non-object root, or
+ * any other malformed input all come back as `{ ok: false, errors }`.
+ *
+ * Unknown top-level keys are forward-compatible: they produce warnings, not
+ * errors, and are preserved on the returned `manifest` object untouched, so
+ * a manifest field introduced by a future spec version doesn't break an
+ * older implementation and isn't silently discarded if that manifest is
+ * later re-serialized.
+ *
+ * Judgment call: this forward-compatibility guarantee is *top-level only*,
+ * matching the task contract literally. An unrecognized key nested inside
+ * `permissions` (e.g. a future `permissions.fs`) is currently dropped
+ * rather than preserved, since `permissions` itself is a known, normalized
+ * key. Extending preservation to arbitrary nesting depth would be a
+ * reasonable follow-up but wasn't asked for here.
+ */
+export declare function parseManifest(json: string): ManifestParseResult;
+/** A minimal, valid manifest for a freshly promoted bundle: no permissions granted, no packs declared. */
+export declare function createDefaultManifest(specVersion?: string): BundleManifest;

package/dist/manifest.js

@@ -0,0 +1,146 @@
+/** The current spec version this package's default manifests declare. */
+export const CURRENT_SPEC_VERSION = '0.1.0';
+const KNOWN_TOP_LEVEL_KEYS = new Set(['mark', 'permissions', 'uses']);
+const KNOWN_FS_GRANTS = new Set(['read', 'write:cache/']);
+// Simplified but structurally correct semver: MAJOR.MINOR.PATCH with
+// optional prerelease/build metadata. Good enough for a "shape" check —
+// this package does not need to compare or range-match versions.
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+// Bare hostname only: letters/digits/hyphens in dot-separated labels, no
+// scheme (`https://`), no port (`:8080`), no path (`/x`), no wildcard (`*`).
+const HOSTNAME_RE = /^(?!-)[A-Za-z0-9-]{1,63}(?<!-)(?:\.(?!-)[A-Za-z0-9-]{1,63}(?<!-))*$/;
+function isStringArray(value) {
+    return (Array.isArray(value) && value.every((item) => typeof item === 'string'));
+}
+function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * Hand-rolled `manifest.json` validation (no schema library — see CLAUDE.md
+ * dependency policy). Never throws: malformed JSON, a non-object root, or
+ * any other malformed input all come back as `{ ok: false, errors }`.
+ *
+ * Unknown top-level keys are forward-compatible: they produce warnings, not
+ * errors, and are preserved on the returned `manifest` object untouched, so
+ * a manifest field introduced by a future spec version doesn't break an
+ * older implementation and isn't silently discarded if that manifest is
+ * later re-serialized.
+ *
+ * Judgment call: this forward-compatibility guarantee is *top-level only*,
+ * matching the task contract literally. An unrecognized key nested inside
+ * `permissions` (e.g. a future `permissions.fs`) is currently dropped
+ * rather than preserved, since `permissions` itself is a known, normalized
+ * key. Extending preservation to arbitrary nesting depth would be a
+ * reasonable follow-up but wasn't asked for here.
+ */
+export function parseManifest(json) {
+    let raw;
+    try {
+        raw = JSON.parse(json);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            errors: [
+                `malformed JSON: ${err instanceof Error ? err.message : String(err)}`,
+            ],
+        };
+    }
+    if (!isPlainObject(raw)) {
+        return { ok: false, errors: ['manifest must be a JSON object'] };
+    }
+    const obj = raw;
+    const errors = [];
+    const warnings = [];
+    // --- mark (required) ---
+    const markRaw = obj.mark;
+    if (typeof markRaw !== 'string') {
+        errors.push('"mark" is required and must be a string');
+    }
+    else if (!SEMVER_RE.test(markRaw)) {
+        errors.push(`"mark" must be a semver string (got ${JSON.stringify(markRaw)})`);
+    }
+    // --- permissions (optional) ---
+    let permissions;
+    if (obj.permissions !== undefined) {
+        if (!isPlainObject(obj.permissions)) {
+            errors.push('"permissions" must be an object');
+        }
+        else {
+            const permsObj = obj.permissions;
+            const perms = {};
+            if (permsObj.net !== undefined) {
+                if (!isPlainObject(permsObj.net)) {
+                    errors.push('"permissions.net" must be an object');
+                }
+                else {
+                    const netObj = permsObj.net;
+                    const net = {};
+                    for (const method of ['get', 'post']) {
+                        const hosts = netObj[method];
+                        if (hosts === undefined)
+                            continue;
+                        if (!isStringArray(hosts)) {
+                            errors.push(`"permissions.net.${method}" must be an array of strings`);
+                            continue;
+                        }
+                        const badHosts = hosts.filter((host) => !HOSTNAME_RE.test(host));
+                        if (badHosts.length > 0) {
+                            errors.push(`"permissions.net.${method}" must list bare hostnames only ` +
+                                `(no scheme, port, path, or wildcard) — invalid: ${badHosts.join(', ')}`);
+                        }
+                        else {
+                            net[method] = hosts;
+                        }
+                    }
+                    perms.net = net;
+                }
+            }
+            if (permsObj.bundle !== undefined) {
+                if (!isStringArray(permsObj.bundle)) {
+                    errors.push('"permissions.bundle" must be an array of strings');
+                }
+                else {
+                    const badGrants = permsObj.bundle.filter((grant) => !KNOWN_FS_GRANTS.has(grant));
+                    if (badGrants.length > 0) {
+                        errors.push(`"permissions.bundle" contains invalid grant(s): ${badGrants.join(', ')} ` +
+                            `(expected "read" or "write:cache/")`);
+                    }
+                    else {
+                        perms.bundle = permsObj.bundle;
+                    }
+                }
+            }
+            permissions = perms;
+        }
+    }
+    // --- uses (optional) ---
+    let uses;
+    if (obj.uses !== undefined) {
+        if (!isStringArray(obj.uses)) {
+            errors.push('"uses" must be an array of strings');
+        }
+        else {
+            uses = obj.uses;
+        }
+    }
+    // --- unknown top-level keys: forward-compat warning, not an error ---
+    for (const key of Object.keys(obj)) {
+        if (!KNOWN_TOP_LEVEL_KEYS.has(key)) {
+            warnings.push(`unknown manifest key "${key}" (ignored by this implementation)`);
+        }
+    }
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    const manifest = { ...obj, mark: markRaw };
+    if (permissions !== undefined)
+        manifest.permissions = permissions;
+    if (uses !== undefined)
+        manifest.uses = uses;
+    return { ok: true, manifest, warnings };
+}
+/** A minimal, valid manifest for a freshly promoted bundle: no permissions granted, no packs declared. */
+export function createDefaultManifest(specVersion = CURRENT_SPEC_VERSION) {
+    return { mark: specVersion };
+}