@map-protocol/map1 0.0.1 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aaron Gerard Davidson
+
+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/dist/constants.d.ts

@@ -0,0 +1,12 @@
+/** Canonical header: "MAP1\0" */
+export declare const CANON_HDR: Buffer;
+/** MCF type tags */
+export declare const TAG_STRING = 1;
+export declare const TAG_BYTES = 2;
+export declare const TAG_LIST = 3;
+export declare const TAG_MAP = 4;
+/** Structural limits */
+export declare const MAX_CANON_BYTES = 1048576;
+export declare const MAX_DEPTH = 32;
+export declare const MAX_MAP_ENTRIES = 65535;
+export declare const MAX_LIST_ENTRIES = 65535;

package/dist/constants.js

@@ -0,0 +1,16 @@
+"use strict";
+// MAP v1.0 constants
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_LIST_ENTRIES = exports.MAX_MAP_ENTRIES = exports.MAX_DEPTH = exports.MAX_CANON_BYTES = exports.TAG_MAP = exports.TAG_LIST = exports.TAG_BYTES = exports.TAG_STRING = exports.CANON_HDR = void 0;
+/** Canonical header: "MAP1\0" */
+exports.CANON_HDR = Buffer.from("MAP1\0", "binary");
+/** MCF type tags */
+exports.TAG_STRING = 0x01;
+exports.TAG_BYTES = 0x02;
+exports.TAG_LIST = 0x03;
+exports.TAG_MAP = 0x04;
+/** Structural limits */
+exports.MAX_CANON_BYTES = 1048576;
+exports.MAX_DEPTH = 32;
+exports.MAX_MAP_ENTRIES = 65535;
+exports.MAX_LIST_ENTRIES = 65535;

package/dist/core.d.ts

@@ -0,0 +1,12 @@
+export declare function sha256Hex(buf: Buffer): string;
+/** Unsigned byte-wise comparison (memcmp semantics). */
+export declare function keyCmp(a: Buffer, b: Buffer): number;
+/** Reject strings containing unpaired surrogates (lone high/low code units). */
+export declare function rejectSurrogatesInString(s: string): void;
+/** Validate a byte buffer as UTF-8 scalar values. Returns the decoded JS string. */
+export declare function validateUtf8ScalarBytes(bytes: Uint8Array): string;
+export declare function mcfEncodeValue(val: unknown, depth: number): Buffer;
+/** Encode a descriptor value to canonical bytes (MAP1 header + MCF body). */
+export declare function canonBytesFromValue(val: unknown): Buffer;
+/** Compute MID from pre-formed canonical bytes. Validates header + MCF structure. */
+export declare function midFromCanonBytes(canon: Buffer): string;

package/dist/core.js

@@ -0,0 +1,210 @@
+"use strict";
+// MAP v1.0 core: MCF binary format encode/decode, key comparison, UTF-8 validation
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sha256Hex = sha256Hex;
+exports.keyCmp = keyCmp;
+exports.rejectSurrogatesInString = rejectSurrogatesInString;
+exports.validateUtf8ScalarBytes = validateUtf8ScalarBytes;
+exports.mcfEncodeValue = mcfEncodeValue;
+exports.canonBytesFromValue = canonBytesFromValue;
+exports.midFromCanonBytes = midFromCanonBytes;
+const crypto_1 = require("crypto");
+const constants_1 = require("./constants");
+const errors_1 = require("./errors");
+// ────────── helpers ──────────
+function sha256Hex(buf) {
+    return (0, crypto_1.createHash)("sha256").update(buf).digest("hex");
+}
+/** Unsigned byte-wise comparison (memcmp semantics). */
+function keyCmp(a, b) {
+    const m = Math.min(a.length, b.length);
+    for (let i = 0; i < m; i++) {
+        if (a[i] !== b[i])
+            return a[i] < b[i] ? -1 : 1;
+    }
+    if (a.length === b.length)
+        return 0;
+    return a.length < b.length ? -1 : 1;
+}
+/** Reject strings containing unpaired surrogates (lone high/low code units). */
+function rejectSurrogatesInString(s) {
+    for (let i = 0; i < s.length; i++) {
+        const cu = s.charCodeAt(i);
+        if (cu >= 0xd800 && cu <= 0xdbff) {
+            if (i + 1 >= s.length)
+                throw new errors_1.MapError(errors_1.ERR_UTF8, "unpaired surrogate");
+            const cu2 = s.charCodeAt(i + 1);
+            if (!(cu2 >= 0xdc00 && cu2 <= 0xdfff))
+                throw new errors_1.MapError(errors_1.ERR_UTF8, "unpaired surrogate");
+            i++; // consume well-formed pair (astral scalar)
+            continue;
+        }
+        if (cu >= 0xdc00 && cu <= 0xdfff)
+            throw new errors_1.MapError(errors_1.ERR_UTF8, "unpaired surrogate");
+    }
+}
+/** Validate a byte buffer as UTF-8 scalar values. Returns the decoded JS string. */
+function validateUtf8ScalarBytes(bytes) {
+    let s;
+    try {
+        const dec = new TextDecoder("utf-8", { fatal: true });
+        s = dec.decode(bytes);
+    }
+    catch {
+        throw new errors_1.MapError(errors_1.ERR_UTF8, "invalid utf8");
+    }
+    rejectSurrogatesInString(s);
+    return s;
+}
+function u32be(n) {
+    const b = Buffer.alloc(4);
+    b.writeUInt32BE(n >>> 0, 0);
+    return b;
+}
+function readU32BE(buf, off) {
+    if (off + 4 > buf.length)
+        throw new errors_1.MapError(errors_1.ERR_CANON_MCF, "truncated u32");
+    return [buf.readUInt32BE(off), off + 4];
+}
+function mcfDecodeOne(buf, off, depth) {
+    if (off >= buf.length)
+        throw new errors_1.MapError(errors_1.ERR_CANON_MCF, "truncated tag");
+    const tag = buf[off];
+    off += 1;
+    if (tag === constants_1.TAG_STRING) {
+        let n;
+        [n, off] = readU32BE(buf, off);
+        if (off + n > buf.length)
+            throw new errors_1.MapError(errors_1.ERR_CANON_MCF, "truncated string");
+        const sb = buf.subarray(off, off + n);
+        off += n;
+        const s = validateUtf8ScalarBytes(sb);
+        return [s, off, Buffer.from(sb)];
+    }
+    if (tag === constants_1.TAG_BYTES) {
+        let n;
+        [n, off] = readU32BE(buf, off);
+        if (off + n > buf.length)
+            throw new errors_1.MapError(errors_1.ERR_CANON_MCF, "truncated bytes");
+        const b = buf.subarray(off, off + n);
+        off += n;
+        return [Buffer.from(b), off, null];
+    }
+    if (tag === constants_1.TAG_LIST) {
+        if (depth + 1 > constants_1.MAX_DEPTH)
+            throw new errors_1.MapError(errors_1.ERR_LIMIT_DEPTH, "depth");
+        let count;
+        [count, off] = readU32BE(buf, off);
+        if (count > constants_1.MAX_LIST_ENTRIES)
+            throw new errors_1.MapError(errors_1.ERR_LIMIT_SIZE, "list entries");
+        const arr = [];
+        for (let i = 0; i < count; i++) {
+            const res = mcfDecodeOne(buf, off, depth + 1);
+            arr.push(res[0]);
+            off = res[1];
+        }
+        return [arr, off, null];
+    }
+    if (tag === constants_1.TAG_MAP) {
+        if (depth + 1 > constants_1.MAX_DEPTH)
+            throw new errors_1.MapError(errors_1.ERR_LIMIT_DEPTH, "depth");
+        let count;
+        [count, off] = readU32BE(buf, off);
+        if (count > constants_1.MAX_MAP_ENTRIES)
+            throw new errors_1.MapError(errors_1.ERR_LIMIT_SIZE, "map entries");
+        const obj = {};
+        let prevKeyBytes = null;
+        for (let i = 0; i < count; i++) {
+            if (off >= buf.length)
+                throw new errors_1.MapError(errors_1.ERR_CANON_MCF, "truncated map key tag");
+            if (buf[off] !== constants_1.TAG_STRING)
+                throw new errors_1.MapError(errors_1.ERR_SCHEMA, "map key not string");
+            const [k, offK, kBytes] = mcfDecodeOne(buf, off, depth + 1);
+            off = offK;
+            const kb = kBytes;
+            if (prevKeyBytes !== null) {
+                const c = keyCmp(prevKeyBytes, kb);
+                if (c === 0)
+                    throw new errors_1.MapError(errors_1.ERR_DUP_KEY, "dup");
+                if (c > 0)
+                    throw new errors_1.MapError(errors_1.ERR_KEY_ORDER, "order");
+            }
+            prevKeyBytes = kb;
+            const resV = mcfDecodeOne(buf, off, depth + 1);
+            off = resV[1];
+            obj[k] = resV[0];
+        }
+        return [obj, off, null];
+    }
+    throw new errors_1.MapError(errors_1.ERR_CANON_MCF, "unknown tag");
+}
+// ────────── MCF encode ──────────
+function mcfEncodeValue(val, depth) {
+    if (typeof val === "string") {
+        const b = Buffer.from(val, "utf8");
+        validateUtf8ScalarBytes(b);
+        return Buffer.concat([Buffer.from([constants_1.TAG_STRING]), u32be(b.length), b]);
+    }
+    if (Buffer.isBuffer(val)) {
+        return Buffer.concat([Buffer.from([constants_1.TAG_BYTES]), u32be(val.length), val]);
+    }
+    if (Array.isArray(val)) {
+        if (depth + 1 > constants_1.MAX_DEPTH)
+            throw new errors_1.MapError(errors_1.ERR_LIMIT_DEPTH, "depth");
+        if (val.length > constants_1.MAX_LIST_ENTRIES)
+            throw new errors_1.MapError(errors_1.ERR_LIMIT_SIZE, "list entries");
+        const parts = [Buffer.from([constants_1.TAG_LIST]), u32be(val.length)];
+        for (const it of val)
+            parts.push(mcfEncodeValue(it, depth + 1));
+        return Buffer.concat(parts);
+    }
+    if (val && typeof val === "object") {
+        if (depth + 1 > constants_1.MAX_DEPTH)
+            throw new errors_1.MapError(errors_1.ERR_LIMIT_DEPTH, "depth");
+        const keys = Object.keys(val);
+        const sorted = keys.slice().sort((ka, kb) => keyCmp(Buffer.from(ka, "utf8"), Buffer.from(kb, "utf8")));
+        // enforce ordering and uniqueness
+        for (let i = 1; i < sorted.length; i++) {
+            const a = Buffer.from(sorted[i - 1], "utf8");
+            const b = Buffer.from(sorted[i], "utf8");
+            const c = keyCmp(a, b);
+            if (c === 0)
+                throw new errors_1.MapError(errors_1.ERR_DUP_KEY, "dup");
+            if (c > 0)
+                throw new errors_1.MapError(errors_1.ERR_KEY_ORDER, "order");
+        }
+        if (sorted.length > constants_1.MAX_MAP_ENTRIES)
+            throw new errors_1.MapError(errors_1.ERR_LIMIT_SIZE, "map entries");
+        const parts = [Buffer.from([constants_1.TAG_MAP]), u32be(sorted.length)];
+        for (const k of sorted) {
+            const kb = Buffer.from(k, "utf8");
+            parts.push(Buffer.concat([Buffer.from([constants_1.TAG_STRING]), u32be(kb.length), kb]));
+            parts.push(mcfEncodeValue(val[k], depth + 1));
+        }
+        return Buffer.concat(parts);
+    }
+    throw new errors_1.MapError(errors_1.ERR_SCHEMA, "unsupported type");
+}
+// ────────── public core API ──────────
+/** Encode a descriptor value to canonical bytes (MAP1 header + MCF body). */
+function canonBytesFromValue(val) {
+    const body = mcfEncodeValue(val, 0);
+    const canon = Buffer.concat([constants_1.CANON_HDR, body]);
+    if (canon.length > constants_1.MAX_CANON_BYTES)
+        throw new errors_1.MapError(errors_1.ERR_LIMIT_SIZE, "too big");
+    return canon;
+}
+/** Compute MID from pre-formed canonical bytes. Validates header + MCF structure. */
+function midFromCanonBytes(canon) {
+    if (canon.length > constants_1.MAX_CANON_BYTES)
+        throw new errors_1.MapError(errors_1.ERR_LIMIT_SIZE, "canon exceeds");
+    if (canon.subarray(0, constants_1.CANON_HDR.length).compare(constants_1.CANON_HDR) !== 0) {
+        throw new errors_1.MapError(errors_1.ERR_CANON_HDR, "bad header");
+    }
+    let off = constants_1.CANON_HDR.length;
+    const res = mcfDecodeOne(canon, off, 0);
+    off = res[1];
+    if (off !== canon.length)
+        throw new errors_1.MapError(errors_1.ERR_CANON_MCF, "trailing bytes");
+    return "map1:" + sha256Hex(canon);
+}

package/dist/errors.d.ts

@@ -0,0 +1,13 @@
+export declare const ERR_CANON_HDR = "ERR_CANON_HDR";
+export declare const ERR_CANON_MCF = "ERR_CANON_MCF";
+export declare const ERR_SCHEMA = "ERR_SCHEMA";
+export declare const ERR_TYPE = "ERR_TYPE";
+export declare const ERR_UTF8 = "ERR_UTF8";
+export declare const ERR_DUP_KEY = "ERR_DUP_KEY";
+export declare const ERR_KEY_ORDER = "ERR_KEY_ORDER";
+export declare const ERR_LIMIT_DEPTH = "ERR_LIMIT_DEPTH";
+export declare const ERR_LIMIT_SIZE = "ERR_LIMIT_SIZE";
+export declare class MapError extends Error {
+    readonly code: string;
+    constructor(code: string, msg?: string);
+}

package/dist/errors.js

@@ -0,0 +1,21 @@
+"use strict";
+// MAP v1.0 error codes and MapError class
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MapError = exports.ERR_LIMIT_SIZE = exports.ERR_LIMIT_DEPTH = exports.ERR_KEY_ORDER = exports.ERR_DUP_KEY = exports.ERR_UTF8 = exports.ERR_TYPE = exports.ERR_SCHEMA = exports.ERR_CANON_MCF = exports.ERR_CANON_HDR = void 0;
+exports.ERR_CANON_HDR = "ERR_CANON_HDR";
+exports.ERR_CANON_MCF = "ERR_CANON_MCF";
+exports.ERR_SCHEMA = "ERR_SCHEMA";
+exports.ERR_TYPE = "ERR_TYPE";
+exports.ERR_UTF8 = "ERR_UTF8";
+exports.ERR_DUP_KEY = "ERR_DUP_KEY";
+exports.ERR_KEY_ORDER = "ERR_KEY_ORDER";
+exports.ERR_LIMIT_DEPTH = "ERR_LIMIT_DEPTH";
+exports.ERR_LIMIT_SIZE = "ERR_LIMIT_SIZE";
+class MapError extends Error {
+    constructor(code, msg) {
+        super(msg || code);
+        this.code = code;
+        this.name = "MapError";
+    }
+}
+exports.MapError = MapError;

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export { MapError } from "./errors";
+export { ERR_CANON_HDR, ERR_CANON_MCF, ERR_SCHEMA, ERR_TYPE, ERR_UTF8, ERR_DUP_KEY, ERR_KEY_ORDER, ERR_LIMIT_DEPTH, ERR_LIMIT_SIZE, } from "./errors";
+export { midFromCanonBytes } from "./core";
+/** Compute the FULL MID from a JS descriptor (plain object/string/array/boolean tree). */
+export declare function midFull(descriptor: Record<string, unknown>): string;
+/** Compute the BIND MID from a JS descriptor + pointer list. */
+export declare function midBind(descriptor: Record<string, unknown>, pointers: string[]): string;
+/** Compute FULL canonical bytes from a JS descriptor. */
+export declare function canonicalBytesFull(descriptor: Record<string, unknown>): Buffer;
+/** Compute BIND canonical bytes from a JS descriptor + pointer list. */
+export declare function canonicalBytesBind(descriptor: Record<string, unknown>, pointers: string[]): Buffer;
+/** Compute FULL MID from raw JSON bytes. Detects duplicate keys after escape resolution. */
+export declare function midFullJson(raw: Buffer): string;
+/** Compute BIND MID from raw JSON bytes + pointer list. */
+export declare function midBindJson(raw: Buffer, pointers: string[]): string;

package/dist/index.js

@@ -0,0 +1,74 @@
+"use strict";
+// MAP v1.0 — Node/TypeScript package public API
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.midFromCanonBytes = exports.ERR_LIMIT_SIZE = exports.ERR_LIMIT_DEPTH = exports.ERR_KEY_ORDER = exports.ERR_DUP_KEY = exports.ERR_UTF8 = exports.ERR_TYPE = exports.ERR_SCHEMA = exports.ERR_CANON_MCF = exports.ERR_CANON_HDR = exports.MapError = void 0;
+exports.midFull = midFull;
+exports.midBind = midBind;
+exports.canonicalBytesFull = canonicalBytesFull;
+exports.canonicalBytesBind = canonicalBytesBind;
+exports.midFullJson = midFullJson;
+exports.midBindJson = midBindJson;
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "MapError", { enumerable: true, get: function () { return errors_1.MapError; } });
+var errors_2 = require("./errors");
+Object.defineProperty(exports, "ERR_CANON_HDR", { enumerable: true, get: function () { return errors_2.ERR_CANON_HDR; } });
+Object.defineProperty(exports, "ERR_CANON_MCF", { enumerable: true, get: function () { return errors_2.ERR_CANON_MCF; } });
+Object.defineProperty(exports, "ERR_SCHEMA", { enumerable: true, get: function () { return errors_2.ERR_SCHEMA; } });
+Object.defineProperty(exports, "ERR_TYPE", { enumerable: true, get: function () { return errors_2.ERR_TYPE; } });
+Object.defineProperty(exports, "ERR_UTF8", { enumerable: true, get: function () { return errors_2.ERR_UTF8; } });
+Object.defineProperty(exports, "ERR_DUP_KEY", { enumerable: true, get: function () { return errors_2.ERR_DUP_KEY; } });
+Object.defineProperty(exports, "ERR_KEY_ORDER", { enumerable: true, get: function () { return errors_2.ERR_KEY_ORDER; } });
+Object.defineProperty(exports, "ERR_LIMIT_DEPTH", { enumerable: true, get: function () { return errors_2.ERR_LIMIT_DEPTH; } });
+Object.defineProperty(exports, "ERR_LIMIT_SIZE", { enumerable: true, get: function () { return errors_2.ERR_LIMIT_SIZE; } });
+const core_1 = require("./core");
+const json_adapter_1 = require("./json-adapter");
+const projection_1 = require("./projection");
+const errors_3 = require("./errors");
+const errors_4 = require("./errors");
+var core_2 = require("./core");
+Object.defineProperty(exports, "midFromCanonBytes", { enumerable: true, get: function () { return core_2.midFromCanonBytes; } });
+// ────────── Descriptor-based API (JS objects) ──────────
+/** Compute the FULL MID from a JS descriptor (plain object/string/array/boolean tree). */
+function midFull(descriptor) {
+    const canon = (0, core_1.canonBytesFromValue)(descriptor);
+    return "map1:" + (0, core_1.sha256Hex)(canon);
+}
+/** Compute the BIND MID from a JS descriptor + pointer list. */
+function midBind(descriptor, pointers) {
+    const proj = (0, projection_1.bindProject)(descriptor, pointers);
+    const canon = (0, core_1.canonBytesFromValue)(proj);
+    return "map1:" + (0, core_1.sha256Hex)(canon);
+}
+/** Compute FULL canonical bytes from a JS descriptor. */
+function canonicalBytesFull(descriptor) {
+    return (0, core_1.canonBytesFromValue)(descriptor);
+}
+/** Compute BIND canonical bytes from a JS descriptor + pointer list. */
+function canonicalBytesBind(descriptor, pointers) {
+    const proj = (0, projection_1.bindProject)(descriptor, pointers);
+    return (0, core_1.canonBytesFromValue)(proj);
+}
+// ────────── JSON-STRICT API (raw bytes) ──────────
+/** Compute FULL MID from raw JSON bytes. Detects duplicate keys after escape resolution. */
+function midFullJson(raw) {
+    const parsed = (0, json_adapter_1.parseJsonStrictWithDups)(raw);
+    const val = (0, json_adapter_1.jsonToCanonValue)(parsed.v);
+    const canon = (0, core_1.canonBytesFromValue)(val);
+    if (parsed.dupFound)
+        throw new errors_3.MapError(errors_4.ERR_DUP_KEY, "dup key");
+    if (parsed.surrogateFound)
+        throw new errors_3.MapError(errors_4.ERR_UTF8, "surrogate escape");
+    return "map1:" + (0, core_1.sha256Hex)(canon);
+}
+/** Compute BIND MID from raw JSON bytes + pointer list. */
+function midBindJson(raw, pointers) {
+    const parsed = (0, json_adapter_1.parseJsonStrictWithDups)(raw);
+    const val = (0, json_adapter_1.jsonToCanonValue)(parsed.v);
+    const proj = (0, projection_1.bindProject)(val, pointers);
+    const canon = (0, core_1.canonBytesFromValue)(proj);
+    if (parsed.dupFound)
+        throw new errors_3.MapError(errors_4.ERR_DUP_KEY, "dup key");
+    if (parsed.surrogateFound)
+        throw new errors_3.MapError(errors_4.ERR_UTF8, "surrogate escape");
+    return "map1:" + (0, core_1.sha256Hex)(canon);
+}

package/dist/json-adapter.d.ts

@@ -0,0 +1,14 @@
+interface NumMarker {
+    __num__: string;
+}
+type JsonValue = string | boolean | null | NumMarker | JsonValue[] | {
+    [k: string]: JsonValue;
+};
+interface ParseResult {
+    v: JsonValue;
+    dupFound: boolean;
+    surrogateFound: boolean;
+}
+declare function parseJsonStrictWithDups(raw: Buffer): ParseResult;
+export declare function jsonToCanonValue(x: JsonValue): unknown;
+export { parseJsonStrictWithDups, ParseResult, JsonValue };

package/dist/json-adapter.js

@@ -0,0 +1,224 @@
+"use strict";
+// MAP v1.0 JSON-STRICT adapter
+// Hand-rolled RFC 8259 parser with duplicate-key detection after escape resolution.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jsonToCanonValue = jsonToCanonValue;
+exports.parseJsonStrictWithDups = parseJsonStrictWithDups;
+const errors_1 = require("./errors");
+const constants_1 = require("./constants");
+const core_1 = require("./core");
+// ────────── helpers ──────────
+function isWS(ch) {
+    return ch === 0x20 || ch === 0x09 || ch === 0x0a || ch === 0x0d;
+}
+function rejectBomStrict(raw) {
+    let i = 0;
+    while (i < raw.length && isWS(raw[i]))
+        i++;
+    if (i + 3 <= raw.length && raw[i] === 0xef && raw[i + 1] === 0xbb && raw[i + 2] === 0xbf) {
+        throw new errors_1.MapError(errors_1.ERR_SCHEMA, "BOM");
+    }
+}
+function utf8DecodeStrict(raw) {
+    try {
+        const dec = new TextDecoder("utf-8", { fatal: true });
+        return dec.decode(raw);
+    }
+    catch {
+        throw new errors_1.MapError(errors_1.ERR_UTF8, "json utf8");
+    }
+}
+// ────────── parser ──────────
+function parseJsonStrictWithDups(raw) {
+    if (raw.length > constants_1.MAX_CANON_BYTES)
+        throw new errors_1.MapError(errors_1.ERR_LIMIT_SIZE, "input too big");
+    rejectBomStrict(raw);
+    const text = utf8DecodeStrict(raw);
+    let i = 0;
+    let dupFound = false;
+    let surrogateFound = false;
+    function skipWS() {
+        while (i < text.length && /\s/.test(text[i]))
+            i++;
+    }
+    function expect(ch) {
+        skipWS();
+        if (text[i] !== ch)
+            throw new errors_1.MapError(errors_1.ERR_CANON_MCF, "json parse");
+        i++;
+    }
+    function parseString() {
+        if (text[i] !== '"')
+            throw new errors_1.MapError(errors_1.ERR_CANON_MCF, "json parse");
+        i++;
+        let out = "";
+        let closed = false;
+        while (i < text.length) {
+            const ch = text[i++];
+            if (ch.charCodeAt(0) < 0x20)
+                throw new errors_1.MapError(errors_1.ERR_CANON_MCF, "json parse");
+            if (ch === '"') {
+                closed = true;
+                break;
+            }
+            if (ch === "\\") {
+                if (i >= text.length)
+                    throw new errors_1.MapError(errors_1.ERR_CANON_MCF, "json parse");
+                const esc = text[i++];
+                if (esc === '"' || esc === "\\" || esc === "/")
+                    out += esc;
+                else if (esc === "b")
+                    out += "\b";
+                else if (esc === "f")
+                    out += "\f";
+                else if (esc === "n")
+                    out += "\n";
+                else if (esc === "r")
+                    out += "\r";
+                else if (esc === "t")
+                    out += "\t";
+                else if (esc === "u") {
+                    const hex = text.slice(i, i + 4);
+                    if (!/^[0-9a-fA-F]{4}$/.test(hex))
+                        throw new errors_1.MapError(errors_1.ERR_CANON_MCF, "json parse");
+                    const code = parseInt(hex, 16);
+                    i += 4;
+                    if (code >= 0xd800 && code <= 0xdfff) {
+                        surrogateFound = true; // flag, do not append
+                    }
+                    else {
+                        out += String.fromCodePoint(code);
+                    }
+                }
+                else {
+                    throw new errors_1.MapError(errors_1.ERR_CANON_MCF, "json parse");
+                }
+            }
+            else {
+                out += ch;
+            }
+        }
+        if (!closed)
+            throw new errors_1.MapError(errors_1.ERR_CANON_MCF, "json parse");
+        (0, core_1.rejectSurrogatesInString)(out);
+        return out;
+    }
+    function parseValue() {
+        skipWS();
+        if (i >= text.length)
+            throw new errors_1.MapError(errors_1.ERR_CANON_MCF, "json parse");
+        const c = text[i];
+        if (c === "{")
+            return parseObject();
+        if (c === "[")
+            return parseArray();
+        if (c === '"')
+            return parseString();
+        if (c === "t" && text.startsWith("true", i)) {
+            i += 4;
+            return true;
+        }
+        if (c === "f" && text.startsWith("false", i)) {
+            i += 5;
+            return false;
+        }
+        if (c === "n" && text.startsWith("null", i)) {
+            i += 4;
+            return null;
+        }
+        if (c === "-" || (c >= "0" && c <= "9")) {
+            const m = text.slice(i).match(/^-?(0|[1-9]\d*)(\.\d+)?([eE][+-]?\d+)?/);
+            if (!m)
+                throw new errors_1.MapError(errors_1.ERR_CANON_MCF, "json parse");
+            i += m[0].length;
+            return { __num__: m[0] };
+        }
+        throw new errors_1.MapError(errors_1.ERR_CANON_MCF, "json parse");
+    }
+    function parseObject() {
+        const obj = {};
+        const seen = new Set();
+        i++; // skip {
+        skipWS();
+        if (text[i] === "}") {
+            i++;
+            return obj;
+        }
+        while (true) {
+            skipWS();
+            const key = parseString();
+            (0, core_1.rejectSurrogatesInString)(key);
+            if (seen.has(key)) {
+                dupFound = true;
+                skipWS();
+                expect(":");
+                parseValue();
+                skipWS();
+                if (text[i] === "}") {
+                    i++;
+                    break;
+                }
+                expect(",");
+                continue;
+            }
+            seen.add(key);
+            skipWS();
+            expect(":");
+            const val = parseValue();
+            obj[key] = val;
+            skipWS();
+            if (text[i] === "}") {
+                i++;
+                break;
+            }
+            expect(",");
+        }
+        return obj;
+    }
+    function parseArray() {
+        const arr = [];
+        i++; // skip [
+        skipWS();
+        if (text[i] === "]") {
+            i++;
+            return arr;
+        }
+        while (true) {
+            const v = parseValue();
+            arr.push(v);
+            skipWS();
+            if (text[i] === "]") {
+                i++;
+                break;
+            }
+            expect(",");
+        }
+        return arr;
+    }
+    const v = parseValue();
+    skipWS();
+    if (i !== text.length)
+        throw new errors_1.MapError(errors_1.ERR_CANON_MCF, "trailing json");
+    return { v, dupFound, surrogateFound };
+}
+// ────────── JSON-to-canon value conversion ──────────
+function jsonToCanonValue(x) {
+    if (x && typeof x === "object" && "__num__" in x)
+        throw new errors_1.MapError(errors_1.ERR_TYPE, "number");
+    if (x === null)
+        throw new errors_1.MapError(errors_1.ERR_TYPE, "null");
+    if (typeof x === "boolean")
+        return x ? "true" : "false";
+    if (typeof x === "string")
+        return x;
+    if (Array.isArray(x))
+        return x.map(jsonToCanonValue);
+    if (typeof x === "object") {
+        const out = {};
+        for (const k of Object.keys(x)) {
+            out[k] = jsonToCanonValue(x[k]);
+        }
+        return out;
+    }
+    throw new errors_1.MapError(errors_1.ERR_TYPE, "unknown");
+}

package/dist/projection.d.ts

@@ -0,0 +1 @@
+export declare function bindProject(descriptor: Record<string, unknown>, pointers: string[]): Record<string, unknown>;

package/dist/projection.js

@@ -0,0 +1,141 @@
+"use strict";
+// MAP v1.0 BIND projection (RFC 6901 JSON Pointers)
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bindProject = bindProject;
+const errors_1 = require("./errors");
+// ────────── JSON Pointer parsing (RFC 6901) ──────────
+function parseJsonPointer(ptr) {
+    if (ptr === "")
+        return [];
+    if (!ptr.startsWith("/"))
+        throw new errors_1.MapError(errors_1.ERR_SCHEMA, "pointer must start with /");
+    const parts = ptr.split("/").slice(1);
+    return parts.map(t => {
+        let out = "";
+        for (let i = 0; i < t.length; i++) {
+            const ch = t[i];
+            if (ch !== "~") {
+                out += ch;
+                continue;
+            }
+            if (i + 1 >= t.length)
+                throw new errors_1.MapError(errors_1.ERR_SCHEMA, "invalid ~ escape in pointer");
+            const nxt = t[i + 1];
+            if (nxt === "0")
+                out += "~";
+            else if (nxt === "1")
+                out += "/";
+            else
+                throw new errors_1.MapError(errors_1.ERR_SCHEMA, "invalid ~ escape in pointer");
+            i++;
+        }
+        return out;
+    });
+}
+// ────────── BIND projection ──────────
+function bindProject(descriptor, pointers) {
+    // Root must be MAP (object, not array)
+    if (!descriptor ||
+        typeof descriptor !== "object" ||
+        Array.isArray(descriptor)) {
+        throw new errors_1.MapError(errors_1.ERR_SCHEMA, "descriptor");
+    }
+    // Duplicate pointers → fail-closed
+    const seen = new Set();
+    for (const p of pointers) {
+        if (seen.has(p))
+            throw new errors_1.MapError(errors_1.ERR_SCHEMA, "duplicate pointers");
+        seen.add(p);
+    }
+    // Parse all pointers (fail-closed on parse error)
+    const parsed = pointers.map(p => ({ ptr: p, toks: parseJsonPointer(p) }));
+    // Determine matches
+    let anyMatch = false;
+    let anyUnmatched = false;
+    const matchedToks = [];
+    for (const { ptr, toks } of parsed) {
+        if (ptr === "") {
+            anyMatch = true;
+            continue;
+        } // empty pointer always matches MAP root
+        let cur = descriptor;
+        let ok = true;
+        for (const tok of toks) {
+            if (Array.isArray(cur))
+                throw new errors_1.MapError(errors_1.ERR_SCHEMA, "list traversal");
+            if (!cur || typeof cur !== "object") {
+                ok = false;
+                break;
+            }
+            if (!(tok in cur)) {
+                ok = false;
+                break;
+            }
+            cur = cur[tok];
+        }
+        if (ok) {
+            anyMatch = true;
+            matchedToks.push(toks);
+        }
+        else {
+            anyUnmatched = true;
+        }
+    }
+    // Unmatched pointers (fail-closed, with one exception)
+    if (!anyMatch)
+        return {};
+    if (anyUnmatched)
+        throw new errors_1.MapError(errors_1.ERR_SCHEMA, "unmatched pointer");
+    // Empty pointer "" => FULL-equivalent over MAP root
+    if (parsed.some(p => p.ptr === ""))
+        return descriptor;
+    // Overlapping pointers subsumption: discard those strictly within another
+    function isSubsumed(toks) {
+        for (const other of matchedToks) {
+            if (other.length < toks.length) {
+                let same = true;
+                for (let i = 0; i < other.length; i++) {
+                    if (toks[i] !== other[i]) {
+                        same = false;
+                        break;
+                    }
+                }
+                if (same)
+                    return true;
+            }
+        }
+        return false;
+    }
+    const effective = matchedToks.filter(t => !isSubsumed(t));
+    // Build projection
+    const projected = {};
+    for (const toks of effective) {
+        let cur = descriptor;
+        const path = [];
+        for (const tok of toks) {
+            if (Array.isArray(cur))
+                throw new errors_1.MapError(errors_1.ERR_SCHEMA, "list traversal");
+            if (!cur || typeof cur !== "object")
+                throw new errors_1.MapError(errors_1.ERR_SCHEMA, "cannot traverse");
+            if (!(tok in cur))
+                throw new errors_1.MapError(errors_1.ERR_SCHEMA, "cannot traverse");
+            path.push(tok);
+            cur = cur[tok];
+        }
+        let outCur = projected;
+        for (let idx = 0; idx < path.length; idx++) {
+            const tok = path[idx];
+            if (idx === path.length - 1) {
+                outCur[tok] = cur;
+            }
+            else {
+                if (!(tok in outCur))
+                    outCur[tok] = {};
+                if (Array.isArray(outCur[tok]))
+                    throw new errors_1.MapError(errors_1.ERR_SCHEMA, "bind conflict");
+                outCur = outCur[tok];
+            }
+        }
+    }
+    return projected;
+}

package/package.json

@@ -1,13 +1,34 @@
-{
-  "name": "@map-protocol/map1",
-  "version": "0.0.1",
-  "description": "MAP v1: deterministic identity for structured data. Full release coming soon.",
-  "main": "index.js",
-  "license": "MIT",
-  "homepage": "https://github.com/map-protocol/map1",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/map-protocol/map1.git"
-  },
-  "keywords": ["map1", "canonical", "deterministic", "identity"]
-}
+{
+  "name": "@map-protocol/map1",
+  "version": "1.0.0",
+  "description": "MAP v1: deterministic identifiers for structured descriptors",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "node --test tests/*.test.js",
+    "test:conformance": "node --test tests/conformance.test.js",
+    "test:api": "node --test tests/api.test.js"
+  },
+  "keywords": [
+    "map1",
+    "canonical",
+    "deterministic",
+    "hash",
+    "identity",
+    "mcf",
+    "conformance"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/map-protocol/map1",
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {},
+  "dependencies": {}
+}

package/README.md

@@ -1,7 +0,0 @@
-# map1
-
-MAP v1: deterministic identity for structured data.
-
-**This is a name reservation. The full package has not been published yet.**
-
-See: https://github.com/map-protocol/map1

package/index.js

@@ -1,24 +0,0 @@
-throw new Error("map1 v1.0 has not been published yet. See https://github.com/map-protocol/map1");
-```
-
-And a file called `README.md` with:
-```
-# map1
-
-MAP v1: deterministic identity for structured data.
-
-**This is a name reservation. The full package has not been published yet.**
-
-See: https://github.com/map-protocol/map1
-```
-
-Then back in PowerShell:
-```
-npm login
-```
-
-It'll open your browser to sign in to npmjs.com. If you don't have an npm account yet, go to https://www.npmjs.com/signup first and create one.
-
-After login succeeds:
-```
-npm publish