@airalogy/aira-core 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,20 @@
+# `@airalogy/aira-core`
+
+Core TypeScript parser and validator for Airalogy `.aira` archives.
+
+It opens `.aira` files in browser-compatible JavaScript, reads `_airalogy_archive/manifest.json`, lists archive members, loads JSON/text payloads, and validates manifest references, Record hashes, Protocol file hashes, and offline blob hashes.
+
+Supported archive kinds are `protocol`, `protocols`, and `records`.
+
+Example archives covering these kinds are available in `examples/aira/`.
+
+```ts
+import { openAiraArchive } from '@airalogy/aira-core'
+
+const archive = await openAiraArchive(file)
+const summary = archive.summary()
+const validation = await archive.validate()
+const manifest = archive.manifest
+```
+
+`.aira` archives are standard ZIP containers. The core package keeps reading independent from the full Airalogy platform, database, or execution engine.

package/dist/index.js

@@ -0,0 +1,291 @@
+const b = "_airalogy_archive/manifest.json", g = "airalogy.archive", A = new TextDecoder("utf-8"), E = new TextEncoder(), R = /^[0-9a-f]{64}$/;
+function m(i, t) {
+  return i.getUint16(t, !0);
+}
+function p(i, t) {
+  return i.getUint32(t, !0);
+}
+function U(i) {
+  return A.decode(i);
+}
+function v(i) {
+  return !i || i.startsWith("/") ? `Archive member '${i}' uses an absolute or empty path.` : i.split("/").some((t) => t === "..") ? `Archive member '${i}' escapes the archive root.` : null;
+}
+function k(i) {
+  const t = Math.max(0, i.length - 65535 - 22);
+  for (let o = i.length - 22; o >= t; o -= 1)
+    if (i[o] === 80 && i[o + 1] === 75 && i[o + 2] === 5 && i[o + 3] === 6)
+      return o;
+  throw new Error("Archive is not a valid zip file: EOCD not found.");
+}
+function D(i) {
+  const t = new DataView(i.buffer, i.byteOffset, i.byteLength), o = k(i), n = m(t, o + 10), s = p(t, o + 16), c = [];
+  let e = s;
+  for (let r = 0; r < n; r += 1) {
+    if (p(t, e) !== 33639248)
+      throw new Error(`Archive central directory is invalid at offset ${e}.`);
+    const a = m(t, e + 10), h = p(t, e + 20), l = p(t, e + 24), f = m(t, e + 28), d = m(t, e + 30), $ = m(t, e + 32), u = p(t, e + 42), w = e + 46, S = U(i.slice(w, w + f));
+    if (p(t, u) !== 67324752)
+      throw new Error(`Archive local header is invalid for '${S}'.`);
+    const B = m(t, u + 26), P = m(t, u + 28), x = u + 30 + B + P;
+    c.push({
+      name: S,
+      compressionMethod: a,
+      compressedSize: h,
+      uncompressedSize: l,
+      localHeaderOffset: u,
+      compressedDataStart: x
+    }), e = w + f + d + $;
+  }
+  return c.filter((r) => !r.name.endsWith("/"));
+}
+async function j(i) {
+  const t = globalThis.DecompressionStream;
+  if (!t)
+    throw new Error("This browser does not support DecompressionStream.");
+  const o = new Blob([i]).stream().pipeThrough(new t("deflate-raw")), n = await new Response(o).arrayBuffer();
+  return new Uint8Array(n);
+}
+async function _(i) {
+  const t = await crypto.subtle.digest("SHA-256", i);
+  return Array.from(new Uint8Array(t)).map((o) => o.toString(16).padStart(2, "0")).join("");
+}
+class y {
+  bytes;
+  entries;
+  manifest;
+  entryMap;
+  constructor(t, o, n) {
+    this.bytes = t, this.entries = o.map(({ compressedDataStart: s, ...c }) => c), this.entryMap = new Map(o.map((s) => [s.name, s])), this.manifest = n;
+  }
+  static async open(t) {
+    const o = t instanceof Uint8Array ? t : t instanceof Blob ? new Uint8Array(await t.arrayBuffer()) : new Uint8Array(t), n = D(o);
+    if (!n.find((r) => r.name === b))
+      throw new Error(`Archive does not contain '${b}'.`);
+    const e = await new y(o, n, {
+      format: g,
+      version: 0,
+      kind: "records"
+    }).readJson(b);
+    if (e.format !== g)
+      throw new Error(`Unsupported archive format '${String(e.format)}'.`);
+    if (e.kind !== "protocol" && e.kind !== "protocols" && e.kind !== "records")
+      throw new Error(`Unsupported archive kind '${String(e.kind)}'.`);
+    return new y(o, n, e);
+  }
+  has(t) {
+    return this.entryMap.has(t);
+  }
+  summary() {
+    const t = Array.isArray(this.manifest.records) ? this.manifest.records.length : 0, o = this.manifest.kind === "protocol" ? 1 : Array.isArray(this.manifest.protocols) ? this.manifest.protocols.length : 0, n = Array.isArray(this.manifest.blobs) ? this.manifest.blobs.length : 0, s = Array.isArray(this.manifest.files) ? this.manifest.files.length : 0;
+    return {
+      format: this.manifest.format,
+      version: this.manifest.version,
+      kind: this.manifest.kind,
+      createdAt: this.manifest.created_at,
+      memberCount: this.entries.length,
+      recordCount: t,
+      protocolCount: o,
+      blobCount: n,
+      fileCount: s
+    };
+  }
+  async readBytes(t) {
+    const o = this.entryMap.get(t);
+    if (!o)
+      throw new Error(`Archive member '${t}' not found.`);
+    const n = this.bytes.slice(
+      o.compressedDataStart,
+      o.compressedDataStart + o.compressedSize
+    );
+    if (o.compressionMethod === 0)
+      return n;
+    if (o.compressionMethod === 8)
+      return j(n);
+    throw new Error(`Archive member '${t}' uses unsupported compression method ${o.compressionMethod}.`);
+  }
+  async readText(t) {
+    return A.decode(await this.readBytes(t));
+  }
+  async readJson(t) {
+    return JSON.parse(await this.readText(t));
+  }
+  async validate() {
+    const t = [], o = new Set(this.entries.map((n) => n.name));
+    for (const n of this.entries) {
+      const s = v(n.name);
+      s && t.push(s);
+    }
+    return o.has(b) || t.push(`Archive is missing '${b}'.`), this.manifest.format !== g && t.push(`Unsupported archive format '${String(this.manifest.format)}'.`), this.manifest.version !== 1 && t.push(`Unsupported archive version '${String(this.manifest.version)}'.`), this.manifest.kind === "protocol" ? await this.validateProtocol(this.manifest.protocol, "", t) : this.manifest.kind === "protocols" ? await this.validateProtocolList(this.manifest.protocols, t, !0) : this.manifest.kind === "records" ? await this.validateRecords(t) : t.push(`Unsupported archive kind '${String(this.manifest.kind)}'.`), { ok: t.length === 0, issues: t };
+  }
+  async validateProtocol(t, o, n) {
+    if (!t || typeof t != "object") {
+      n.push("Protocol manifest entry must be an object.");
+      return;
+    }
+    const s = t.entrypoint || "protocol.aimd", c = `${o}${s}`;
+    this.has(c) || n.push(`Protocol entrypoint '${c}' is missing.`);
+    const e = Array.isArray(t.files) ? t.files : [], r = t.file_hashes && typeof t.file_hashes == "object" ? t.file_hashes : {};
+    for (const a of e) {
+      const h = `${o}${a}`, l = v(h);
+      if (l) {
+        n.push(l);
+        continue;
+      }
+      if (!this.has(h)) {
+        n.push(`Protocol file '${h}' is missing.`);
+        continue;
+      }
+      const f = r[a];
+      if (f) {
+        const d = await _(await this.readBytes(h));
+        d !== f && n.push(`Protocol file '${h}' sha256 mismatch: expected ${f}, got ${d}.`);
+      }
+    }
+  }
+  async validateProtocolList(t, o, n = !1) {
+    const s = /* @__PURE__ */ new Set();
+    if (!Array.isArray(t))
+      return o.push("Protocols manifest field must be a list."), s;
+    n && t.length === 0 && o.push("Protocols manifest field must include at least one protocol.");
+    for (const [c, e] of t.entries()) {
+      if (!e || typeof e != "object") {
+        o.push(`Protocol manifest entry #${c + 1} must be an object.`);
+        continue;
+      }
+      if (!e.archive_root) {
+        o.push(`Protocol manifest entry #${c + 1} is missing archive_root.`);
+        continue;
+      }
+      if (s.has(e.archive_root)) {
+        o.push(`Protocol manifest entry #${c + 1} uses duplicate archive_root '${e.archive_root}'.`);
+        continue;
+      }
+      s.add(e.archive_root), await this.validateProtocol(e, `${e.archive_root.replace(/\/+$/, "")}/`, o);
+    }
+    return s;
+  }
+  async validateRecords(t) {
+    const o = Array.isArray(this.manifest.records) ? this.manifest.records : [], n = await this.validateProtocolList(this.manifest.protocols, t), s = /* @__PURE__ */ new Set();
+    for (const [e, r] of o.entries()) {
+      if (!r || typeof r != "object") {
+        t.push(`Record manifest entry #${e + 1} must be an object.`);
+        continue;
+      }
+      const a = r.path;
+      if (!a) {
+        t.push(`Record manifest entry #${e + 1} is missing a path.`);
+        continue;
+      }
+      const h = v(a);
+      if (h) {
+        t.push(h);
+        continue;
+      }
+      if (!this.has(a)) {
+        t.push(`Record file '${a}' is missing.`);
+        continue;
+      }
+      s.add(a);
+      let l;
+      try {
+        l = await this.readBytes(a), JSON.parse(A.decode(l));
+      } catch {
+        t.push(`Record file '${a}' is not valid UTF-8 JSON.`);
+        continue;
+      }
+      if (r.sha256) {
+        const f = await _(l);
+        f !== r.sha256 && t.push(`Record file '${a}' sha256 mismatch: expected ${r.sha256}, got ${f}.`);
+      }
+      r.embedded_protocol_root && !n.has(r.embedded_protocol_root) && t.push(`Record file '${a}' references missing embedded protocol root '${r.embedded_protocol_root}'.`);
+    }
+    const c = await this.validateBlobs(t);
+    this.validateFileReferences(t, c, s);
+  }
+  async validateBlobs(t) {
+    const o = /* @__PURE__ */ new Set(), n = this.manifest.blobs;
+    if (n === void 0)
+      return o;
+    if (!Array.isArray(n))
+      return t.push("Blobs manifest field must be a list."), o;
+    const s = /* @__PURE__ */ new Set();
+    for (const [c, e] of n.entries()) {
+      if (!e || typeof e != "object") {
+        t.push(`Blob manifest entry #${c + 1} must be an object.`);
+        continue;
+      }
+      const r = e.blob_id, a = e.archive_path, h = e.sha256;
+      if (!r) {
+        t.push(`Blob manifest entry #${c + 1} is missing blob_id.`);
+        continue;
+      }
+      if (o.has(r)) {
+        t.push(`Blob manifest entry #${c + 1} uses duplicate blob_id '${r}'.`);
+        continue;
+      }
+      if (o.add(r), !h || !R.test(h)) {
+        t.push(`Blob '${r}' must include a valid sha256 hash.`);
+        continue;
+      }
+      const l = `sha256:${h}`;
+      if (r !== l && t.push(`Blob '${r}' does not match sha256-derived id '${l}'.`), !a) {
+        t.push(`Blob '${r}' is missing archive_path.`);
+        continue;
+      }
+      const f = v(a);
+      if (f) {
+        t.push(f);
+        continue;
+      }
+      if (a.startsWith("blobs/sha256/") || t.push(`Blob '${r}' archive_path must be under 'blobs/sha256/'.`), s.has(a)) {
+        t.push(`Blob '${r}' uses duplicate archive_path '${a}'.`);
+        continue;
+      }
+      if (s.add(a), !this.has(a)) {
+        t.push(`Blob file '${a}' is missing.`);
+        continue;
+      }
+      const d = await this.readBytes(a), $ = await _(d);
+      $ !== h && t.push(`Blob file '${a}' sha256 mismatch: expected ${h}, got ${$}.`), typeof e.size == "number" && e.size !== d.byteLength ? t.push(`Blob file '${a}' size mismatch: expected ${e.size}, got ${d.byteLength}.`) : e.size !== void 0 && typeof e.size != "number" && t.push(`Blob '${r}' size must be a number when present.`);
+    }
+    return o;
+  }
+  validateFileReferences(t, o, n) {
+    const s = this.manifest.files;
+    if (s !== void 0) {
+      if (!Array.isArray(s)) {
+        t.push("Files manifest field must be a list.");
+        return;
+      }
+      for (const [c, e] of s.entries()) {
+        if (!e || typeof e != "object") {
+          t.push(`File manifest entry #${c + 1} must be an object.`);
+          continue;
+        }
+        !e.file_id && !e.source_uri && !e.blob_id && t.push(`File manifest entry #${c + 1} must include file_id, source_uri, or blob_id.`), e.blob_id && !o.has(e.blob_id) && t.push(`File manifest entry #${c + 1} references missing blob_id '${e.blob_id}'.`), e.record_path && !n.has(e.record_path) && t.push(`File manifest entry #${c + 1} references missing record_path '${e.record_path}'.`), e.field_path !== void 0 && typeof e.field_path != "string" && t.push(`File manifest entry #${c + 1} field_path must be a string.`);
+      }
+    }
+  }
+}
+async function M(i) {
+  return y.open(i);
+}
+async function O(i) {
+  return (await y.open(i)).summary();
+}
+function z(i) {
+  return JSON.stringify(i, null, 2);
+}
+function F(i) {
+  return E.encode(i);
+}
+export {
+  g as AIRA_ARCHIVE_FORMAT,
+  b as AIRA_MANIFEST_PATH,
+  y as AiraArchive,
+  F as encodeUtf8,
+  M as openAiraArchive,
+  z as prettyPrintJson,
+  O as readAiraArchiveSummary
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@airalogy/aira-core",
+  "type": "module",
+  "version": "0.1.0",
+  "description": "Core parser and validator for Airalogy .aira archives",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/airalogy/airalogy.git",
+    "directory": "packages/npm/aira-core"
+  },
+  "bugs": {
+    "url": "https://github.com/airalogy/airalogy/issues"
+  },
+  "homepage": "https://github.com/airalogy/airalogy/tree/main/packages/npm/aira-core#readme",
+  "keywords": [
+    "airalogy",
+    "aira",
+    "archive",
+    "record",
+    "protocol"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "typescript": "5.8.3",
+    "vite": "^7.1.3"
+  },
+  "scripts": {
+    "type-check": "tsc --noEmit",
+    "build:types": "tsc --emitDeclarationOnly --declaration --outDir dist",
+    "build": "vite build && pnpm run build:types",
+    "dev": "vite build --watch",
+    "test": "pnpm run build && node --test ./tests/*.test.mjs"
+  }
+}

package/src/index.ts

@@ -0,0 +1,552 @@
+export const AIRA_MANIFEST_PATH = '_airalogy_archive/manifest.json'
+export const AIRA_ARCHIVE_FORMAT = 'airalogy.archive'
+
+export type AiraArchiveKind = 'protocol' | 'protocols' | 'records'
+
+export interface AiraEntry {
+  name: string
+  compressedSize: number
+  uncompressedSize: number
+  compressionMethod: number
+  localHeaderOffset: number
+}
+
+export interface AiraProtocolManifest {
+  protocol_id?: string | null
+  protocol_version?: string | null
+  protocol_name?: string | null
+  entrypoint?: string
+  archive_root?: string
+  files?: string[]
+  file_hashes?: Record<string, string>
+}
+
+export interface AiraRecordManifest {
+  path: string
+  record_id?: string | null
+  record_version?: string | number | null
+  protocol_id?: string | null
+  protocol_version?: string | null
+  sha1?: string | null
+  sha256?: string | null
+  source_path?: string
+  source_index?: number
+  embedded_protocol_root?: string | null
+}
+
+export interface AiraBlobManifest {
+  blob_id: string
+  archive_path: string
+  sha256: string
+  size?: number
+}
+
+export interface AiraFileManifest {
+  file_id?: string | null
+  source_uri?: string | null
+  blob_id?: string | null
+  filename?: string | null
+  mime_type?: string | null
+  size?: number | null
+  record_path?: string | null
+  field_path?: string | null
+}
+
+export interface AiraManifest {
+  format: string
+  version: number
+  kind: AiraArchiveKind
+  created_at?: string
+  protocol?: AiraProtocolManifest
+  records?: AiraRecordManifest[]
+  protocols?: AiraProtocolManifest[]
+  blobs?: AiraBlobManifest[]
+  files?: AiraFileManifest[]
+  [key: string]: unknown
+}
+
+export interface AiraSummary {
+  format: string
+  version: number
+  kind: AiraArchiveKind
+  createdAt?: string
+  memberCount: number
+  recordCount: number
+  protocolCount: number
+  blobCount: number
+  fileCount: number
+}
+
+export interface AiraValidationResult {
+  ok: boolean
+  issues: string[]
+}
+
+type ZipEntryInternal = AiraEntry & {
+  compressedDataStart: number
+}
+
+const textDecoder = new TextDecoder('utf-8')
+const textEncoder = new TextEncoder()
+const sha256Pattern = /^[0-9a-f]{64}$/
+
+function getUint16(view: DataView, offset: number): number {
+  return view.getUint16(offset, true)
+}
+
+function getUint32(view: DataView, offset: number): number {
+  return view.getUint32(offset, true)
+}
+
+function decodeName(bytes: Uint8Array): string {
+  return textDecoder.decode(bytes)
+}
+
+function validateMemberPath(name: string): string | null {
+  if (!name || name.startsWith('/')) {
+    return `Archive member '${name}' uses an absolute or empty path.`
+  }
+  if (name.split('/').some(part => part === '..')) {
+    return `Archive member '${name}' escapes the archive root.`
+  }
+  return null
+}
+
+function findEndOfCentralDirectory(bytes: Uint8Array): number {
+  const minOffset = Math.max(0, bytes.length - 0xffff - 22)
+  for (let offset = bytes.length - 22; offset >= minOffset; offset -= 1) {
+    if (
+      bytes[offset] === 0x50
+      && bytes[offset + 1] === 0x4b
+      && bytes[offset + 2] === 0x05
+      && bytes[offset + 3] === 0x06
+    ) {
+      return offset
+    }
+  }
+  throw new Error('Archive is not a valid zip file: EOCD not found.')
+}
+
+function parseZipEntries(bytes: Uint8Array): ZipEntryInternal[] {
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+  const eocdOffset = findEndOfCentralDirectory(bytes)
+  const entryCount = getUint16(view, eocdOffset + 10)
+  const centralDirectoryOffset = getUint32(view, eocdOffset + 16)
+  const entries: ZipEntryInternal[] = []
+  let offset = centralDirectoryOffset
+
+  for (let index = 0; index < entryCount; index += 1) {
+    if (getUint32(view, offset) !== 0x02014b50) {
+      throw new Error(`Archive central directory is invalid at offset ${offset}.`)
+    }
+    const compressionMethod = getUint16(view, offset + 10)
+    const compressedSize = getUint32(view, offset + 20)
+    const uncompressedSize = getUint32(view, offset + 24)
+    const fileNameLength = getUint16(view, offset + 28)
+    const extraLength = getUint16(view, offset + 30)
+    const commentLength = getUint16(view, offset + 32)
+    const localHeaderOffset = getUint32(view, offset + 42)
+    const fileNameStart = offset + 46
+    const name = decodeName(bytes.slice(fileNameStart, fileNameStart + fileNameLength))
+
+    if (getUint32(view, localHeaderOffset) !== 0x04034b50) {
+      throw new Error(`Archive local header is invalid for '${name}'.`)
+    }
+    const localNameLength = getUint16(view, localHeaderOffset + 26)
+    const localExtraLength = getUint16(view, localHeaderOffset + 28)
+    const compressedDataStart = localHeaderOffset + 30 + localNameLength + localExtraLength
+
+    entries.push({
+      name,
+      compressionMethod,
+      compressedSize,
+      uncompressedSize,
+      localHeaderOffset,
+      compressedDataStart,
+    })
+
+    offset = fileNameStart + fileNameLength + extraLength + commentLength
+  }
+
+  return entries.filter(entry => !entry.name.endsWith('/'))
+}
+
+async function inflateRaw(data: Uint8Array): Promise<Uint8Array> {
+  const DecompressionStreamClass = globalThis.DecompressionStream
+  if (!DecompressionStreamClass) {
+    throw new Error('This browser does not support DecompressionStream.')
+  }
+
+  const stream = new Blob([data]).stream().pipeThrough(new DecompressionStreamClass('deflate-raw'))
+  const buffer = await new Response(stream).arrayBuffer()
+  return new Uint8Array(buffer)
+}
+
+async function sha256Hex(bytes: Uint8Array): Promise<string> {
+  const digest = await crypto.subtle.digest('SHA-256', bytes)
+  return Array.from(new Uint8Array(digest))
+    .map(value => value.toString(16).padStart(2, '0'))
+    .join('')
+}
+
+export class AiraArchive {
+  readonly bytes: Uint8Array
+  readonly entries: AiraEntry[]
+  readonly manifest: AiraManifest
+
+  private readonly entryMap: Map<string, ZipEntryInternal>
+
+  private constructor(bytes: Uint8Array, entries: ZipEntryInternal[], manifest: AiraManifest) {
+    this.bytes = bytes
+    this.entries = entries.map(({ compressedDataStart: _compressedDataStart, ...entry }) => entry)
+    this.entryMap = new Map(entries.map(entry => [entry.name, entry]))
+    this.manifest = manifest
+  }
+
+  static async open(input: ArrayBuffer | Blob | Uint8Array): Promise<AiraArchive> {
+    const bytes = input instanceof Uint8Array
+      ? input
+      : input instanceof Blob
+        ? new Uint8Array(await input.arrayBuffer())
+        : new Uint8Array(input)
+    const entries = parseZipEntries(bytes)
+    const manifestEntry = entries.find(entry => entry.name === AIRA_MANIFEST_PATH)
+    if (!manifestEntry) {
+      throw new Error(`Archive does not contain '${AIRA_MANIFEST_PATH}'.`)
+    }
+    const archive = new AiraArchive(bytes, entries, {
+      format: AIRA_ARCHIVE_FORMAT,
+      version: 0,
+      kind: 'records',
+    })
+    const manifest = await archive.readJson<AiraManifest>(AIRA_MANIFEST_PATH)
+    if (manifest.format !== AIRA_ARCHIVE_FORMAT) {
+      throw new Error(`Unsupported archive format '${String(manifest.format)}'.`)
+    }
+    if (manifest.kind !== 'protocol' && manifest.kind !== 'protocols' && manifest.kind !== 'records') {
+      throw new Error(`Unsupported archive kind '${String(manifest.kind)}'.`)
+    }
+    return new AiraArchive(bytes, entries, manifest)
+  }
+
+  has(path: string): boolean {
+    return this.entryMap.has(path)
+  }
+
+  summary(): AiraSummary {
+    const records = Array.isArray(this.manifest.records) ? this.manifest.records.length : 0
+    const protocols = this.manifest.kind === 'protocol'
+      ? 1
+      : Array.isArray(this.manifest.protocols) ? this.manifest.protocols.length : 0
+    const blobs = Array.isArray(this.manifest.blobs) ? this.manifest.blobs.length : 0
+    const files = Array.isArray(this.manifest.files) ? this.manifest.files.length : 0
+    return {
+      format: this.manifest.format,
+      version: this.manifest.version,
+      kind: this.manifest.kind,
+      createdAt: this.manifest.created_at,
+      memberCount: this.entries.length,
+      recordCount: records,
+      protocolCount: protocols,
+      blobCount: blobs,
+      fileCount: files,
+    }
+  }
+
+  async readBytes(path: string): Promise<Uint8Array> {
+    const entry = this.entryMap.get(path)
+    if (!entry) {
+      throw new Error(`Archive member '${path}' not found.`)
+    }
+    const compressed = this.bytes.slice(
+      entry.compressedDataStart,
+      entry.compressedDataStart + entry.compressedSize,
+    )
+    if (entry.compressionMethod === 0) {
+      return compressed
+    }
+    if (entry.compressionMethod === 8) {
+      return inflateRaw(compressed)
+    }
+    throw new Error(`Archive member '${path}' uses unsupported compression method ${entry.compressionMethod}.`)
+  }
+
+  async readText(path: string): Promise<string> {
+    return textDecoder.decode(await this.readBytes(path))
+  }
+
+  async readJson<T = unknown>(path: string): Promise<T> {
+    return JSON.parse(await this.readText(path)) as T
+  }
+
+  async validate(): Promise<AiraValidationResult> {
+    const issues: string[] = []
+    const entryNames = new Set(this.entries.map(entry => entry.name))
+    for (const entry of this.entries) {
+      const issue = validateMemberPath(entry.name)
+      if (issue) {
+        issues.push(issue)
+      }
+    }
+    if (!entryNames.has(AIRA_MANIFEST_PATH)) {
+      issues.push(`Archive is missing '${AIRA_MANIFEST_PATH}'.`)
+    }
+    if (this.manifest.format !== AIRA_ARCHIVE_FORMAT) {
+      issues.push(`Unsupported archive format '${String(this.manifest.format)}'.`)
+    }
+    if (this.manifest.version !== 1) {
+      issues.push(`Unsupported archive version '${String(this.manifest.version)}'.`)
+    }
+
+    if (this.manifest.kind === 'protocol') {
+      await this.validateProtocol(this.manifest.protocol, '', issues)
+    }
+    else if (this.manifest.kind === 'protocols') {
+      await this.validateProtocolList(this.manifest.protocols, issues, true)
+    }
+    else if (this.manifest.kind === 'records') {
+      await this.validateRecords(issues)
+    }
+    else {
+      issues.push(`Unsupported archive kind '${String(this.manifest.kind)}'.`)
+    }
+
+    return { ok: issues.length === 0, issues }
+  }
+
+  private async validateProtocol(protocol: AiraProtocolManifest | undefined, prefix: string, issues: string[]): Promise<void> {
+    if (!protocol || typeof protocol !== 'object') {
+      issues.push('Protocol manifest entry must be an object.')
+      return
+    }
+    const entrypoint = protocol.entrypoint || 'protocol.aimd'
+    const entrypointPath = `${prefix}${entrypoint}`
+    if (!this.has(entrypointPath)) {
+      issues.push(`Protocol entrypoint '${entrypointPath}' is missing.`)
+    }
+    const files = Array.isArray(protocol.files) ? protocol.files : []
+    const fileHashes = protocol.file_hashes && typeof protocol.file_hashes === 'object'
+      ? protocol.file_hashes
+      : {}
+    for (const file of files) {
+      const path = `${prefix}${file}`
+      const pathIssue = validateMemberPath(path)
+      if (pathIssue) {
+        issues.push(pathIssue)
+        continue
+      }
+      if (!this.has(path)) {
+        issues.push(`Protocol file '${path}' is missing.`)
+        continue
+      }
+      const expectedHash = fileHashes[file]
+      if (expectedHash) {
+        const actualHash = await sha256Hex(await this.readBytes(path))
+        if (actualHash !== expectedHash) {
+          issues.push(`Protocol file '${path}' sha256 mismatch: expected ${expectedHash}, got ${actualHash}.`)
+        }
+      }
+    }
+  }
+
+  private async validateProtocolList(
+    protocols: AiraProtocolManifest[] | undefined,
+    issues: string[],
+    requireNonEmpty = false,
+  ): Promise<Set<string>> {
+    const protocolRoots = new Set<string>()
+    if (!Array.isArray(protocols)) {
+      issues.push('Protocols manifest field must be a list.')
+      return protocolRoots
+    }
+    if (requireNonEmpty && protocols.length === 0) {
+      issues.push('Protocols manifest field must include at least one protocol.')
+    }
+    for (const [index, protocol] of protocols.entries()) {
+      if (!protocol || typeof protocol !== 'object') {
+        issues.push(`Protocol manifest entry #${index + 1} must be an object.`)
+        continue
+      }
+      if (!protocol.archive_root) {
+        issues.push(`Protocol manifest entry #${index + 1} is missing archive_root.`)
+        continue
+      }
+      if (protocolRoots.has(protocol.archive_root)) {
+        issues.push(`Protocol manifest entry #${index + 1} uses duplicate archive_root '${protocol.archive_root}'.`)
+        continue
+      }
+      protocolRoots.add(protocol.archive_root)
+      await this.validateProtocol(protocol, `${protocol.archive_root.replace(/\/+$/, '')}/`, issues)
+    }
+    return protocolRoots
+  }
+
+  private async validateRecords(issues: string[]): Promise<void> {
+    const records = Array.isArray(this.manifest.records) ? this.manifest.records : []
+    const protocolRoots = await this.validateProtocolList(this.manifest.protocols, issues)
+    const recordPaths = new Set<string>()
+
+    for (const [index, record] of records.entries()) {
+      if (!record || typeof record !== 'object') {
+        issues.push(`Record manifest entry #${index + 1} must be an object.`)
+        continue
+      }
+      const path = record.path
+      if (!path) {
+        issues.push(`Record manifest entry #${index + 1} is missing a path.`)
+        continue
+      }
+      const pathIssue = validateMemberPath(path)
+      if (pathIssue) {
+        issues.push(pathIssue)
+        continue
+      }
+      if (!this.has(path)) {
+        issues.push(`Record file '${path}' is missing.`)
+        continue
+      }
+      recordPaths.add(path)
+      let raw: Uint8Array
+      try {
+        raw = await this.readBytes(path)
+        JSON.parse(textDecoder.decode(raw))
+      }
+      catch {
+        issues.push(`Record file '${path}' is not valid UTF-8 JSON.`)
+        continue
+      }
+      if (record.sha256) {
+        const actualHash = await sha256Hex(raw)
+        if (actualHash !== record.sha256) {
+          issues.push(`Record file '${path}' sha256 mismatch: expected ${record.sha256}, got ${actualHash}.`)
+        }
+      }
+      if (record.embedded_protocol_root && !protocolRoots.has(record.embedded_protocol_root)) {
+        issues.push(`Record file '${path}' references missing embedded protocol root '${record.embedded_protocol_root}'.`)
+      }
+    }
+    const blobIds = await this.validateBlobs(issues)
+    this.validateFileReferences(issues, blobIds, recordPaths)
+  }
+
+  private async validateBlobs(issues: string[]): Promise<Set<string>> {
+    const blobIds = new Set<string>()
+    const blobs = this.manifest.blobs
+    if (blobs === undefined) {
+      return blobIds
+    }
+    if (!Array.isArray(blobs)) {
+      issues.push('Blobs manifest field must be a list.')
+      return blobIds
+    }
+
+    const archivePaths = new Set<string>()
+    for (const [index, blob] of blobs.entries()) {
+      if (!blob || typeof blob !== 'object') {
+        issues.push(`Blob manifest entry #${index + 1} must be an object.`)
+        continue
+      }
+      const blobId = blob.blob_id
+      const archivePath = blob.archive_path
+      const expectedHash = blob.sha256
+
+      if (!blobId) {
+        issues.push(`Blob manifest entry #${index + 1} is missing blob_id.`)
+        continue
+      }
+      if (blobIds.has(blobId)) {
+        issues.push(`Blob manifest entry #${index + 1} uses duplicate blob_id '${blobId}'.`)
+        continue
+      }
+      blobIds.add(blobId)
+
+      if (!expectedHash || !sha256Pattern.test(expectedHash)) {
+        issues.push(`Blob '${blobId}' must include a valid sha256 hash.`)
+        continue
+      }
+      const expectedBlobId = `sha256:${expectedHash}`
+      if (blobId !== expectedBlobId) {
+        issues.push(`Blob '${blobId}' does not match sha256-derived id '${expectedBlobId}'.`)
+      }
+      if (!archivePath) {
+        issues.push(`Blob '${blobId}' is missing archive_path.`)
+        continue
+      }
+      const pathIssue = validateMemberPath(archivePath)
+      if (pathIssue) {
+        issues.push(pathIssue)
+        continue
+      }
+      if (!archivePath.startsWith('blobs/sha256/')) {
+        issues.push(`Blob '${blobId}' archive_path must be under 'blobs/sha256/'.`)
+      }
+      if (archivePaths.has(archivePath)) {
+        issues.push(`Blob '${blobId}' uses duplicate archive_path '${archivePath}'.`)
+        continue
+      }
+      archivePaths.add(archivePath)
+      if (!this.has(archivePath)) {
+        issues.push(`Blob file '${archivePath}' is missing.`)
+        continue
+      }
+      const raw = await this.readBytes(archivePath)
+      const actualHash = await sha256Hex(raw)
+      if (actualHash !== expectedHash) {
+        issues.push(`Blob file '${archivePath}' sha256 mismatch: expected ${expectedHash}, got ${actualHash}.`)
+      }
+      if (typeof blob.size === 'number' && blob.size !== raw.byteLength) {
+        issues.push(`Blob file '${archivePath}' size mismatch: expected ${blob.size}, got ${raw.byteLength}.`)
+      }
+      else if (blob.size !== undefined && typeof blob.size !== 'number') {
+        issues.push(`Blob '${blobId}' size must be a number when present.`)
+      }
+    }
+    return blobIds
+  }
+
+  private validateFileReferences(issues: string[], blobIds: Set<string>, recordPaths: Set<string>): void {
+    const files = this.manifest.files
+    if (files === undefined) {
+      return
+    }
+    if (!Array.isArray(files)) {
+      issues.push('Files manifest field must be a list.')
+      return
+    }
+
+    for (const [index, fileRef] of files.entries()) {
+      if (!fileRef || typeof fileRef !== 'object') {
+        issues.push(`File manifest entry #${index + 1} must be an object.`)
+        continue
+      }
+      if (!fileRef.file_id && !fileRef.source_uri && !fileRef.blob_id) {
+        issues.push(`File manifest entry #${index + 1} must include file_id, source_uri, or blob_id.`)
+      }
+      if (fileRef.blob_id && !blobIds.has(fileRef.blob_id)) {
+        issues.push(`File manifest entry #${index + 1} references missing blob_id '${fileRef.blob_id}'.`)
+      }
+      if (fileRef.record_path && !recordPaths.has(fileRef.record_path)) {
+        issues.push(`File manifest entry #${index + 1} references missing record_path '${fileRef.record_path}'.`)
+      }
+      if (fileRef.field_path !== undefined && typeof fileRef.field_path !== 'string') {
+        issues.push(`File manifest entry #${index + 1} field_path must be a string.`)
+      }
+    }
+  }
+}
+
+export async function openAiraArchive(input: ArrayBuffer | Blob | Uint8Array): Promise<AiraArchive> {
+  return AiraArchive.open(input)
+}
+
+export async function readAiraArchiveSummary(input: ArrayBuffer | Blob | Uint8Array): Promise<AiraSummary> {
+  return (await AiraArchive.open(input)).summary()
+}
+
+export function prettyPrintJson(value: unknown): string {
+  return JSON.stringify(value, null, 2)
+}
+
+export function encodeUtf8(value: string): Uint8Array {
+  return textEncoder.encode(value)
+}