@airalogy/aira-core 0.1.0 → 0.2.0

package/README.md

@@ -2,12 +2,14 @@
 
 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.
+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 payload structure, 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/`.
 
+The public manifest schema is available at `schemas/aira/manifest.v1.schema.json`; the public Record schema is available at `schemas/aira/record.v1.schema.json`.
+
 ```ts
 import { openAiraArchive } from '@airalogy/aira-core'
 

package/dist/index.d.ts

@@ -0,0 +1,117 @@
+export declare const AIRA_MANIFEST_PATH = "_airalogy_archive/manifest.json";
+export declare const AIRA_ARCHIVE_FORMAT = "airalogy.archive";
+export declare const AIRALOGY_RECORD_FORMAT = "airalogy.record";
+export declare const AIRALOGY_RECORD_SCHEMA_VERSION = 1;
+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 AiralogyRecordPayload {
+    format?: string;
+    schema_version?: number;
+    airalogy_record_id?: string | null;
+    record_id?: string | null;
+    record_version?: number | null;
+    metadata?: Record<string, unknown> | null;
+    data?: {
+        var?: Record<string, unknown>;
+        step?: Record<string, unknown>;
+        check?: Record<string, unknown>;
+        quiz?: Record<string, unknown>;
+        [key: string]: unknown;
+    };
+    files?: Array<Record<string, unknown>>;
+    [key: string]: unknown;
+}
+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[];
+}
+export declare class AiraArchive {
+    readonly bytes: Uint8Array;
+    readonly entries: AiraEntry[];
+    readonly manifest: AiraManifest;
+    private readonly entryMap;
+    private constructor();
+    static open(input: ArrayBuffer | Blob | Uint8Array): Promise<AiraArchive>;
+    has(path: string): boolean;
+    summary(): AiraSummary;
+    readBytes(path: string): Promise<Uint8Array>;
+    readText(path: string): Promise<string>;
+    readJson<T = unknown>(path: string): Promise<T>;
+    validate(): Promise<AiraValidationResult>;
+    private validateProtocol;
+    private validateProtocolList;
+    private validateRecords;
+    private validateBlobs;
+    private validateFileReferences;
+}
+export declare function openAiraArchive(input: ArrayBuffer | Blob | Uint8Array): Promise<AiraArchive>;
+export declare function readAiraArchiveSummary(input: ArrayBuffer | Blob | Uint8Array): Promise<AiraSummary>;
+export declare function prettyPrintJson(value: unknown): string;
+export declare function encodeUtf8(value: string): Uint8Array;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@airalogy/aira-core",
   "type": "module",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Core parser and validator for Airalogy .aira archives",
   "license": "Apache-2.0",
   "repository": {

package/src/index.ts

@@ -1,5 +1,7 @@
 export const AIRA_MANIFEST_PATH = '_airalogy_archive/manifest.json'
 export const AIRA_ARCHIVE_FORMAT = 'airalogy.archive'
+export const AIRALOGY_RECORD_FORMAT = 'airalogy.record'
+export const AIRALOGY_RECORD_SCHEMA_VERSION = 1
 
 export type AiraArchiveKind = 'protocol' | 'protocols' | 'records'
 
@@ -34,6 +36,24 @@ export interface AiraRecordManifest {
   embedded_protocol_root?: string | null
 }
 
+export interface AiralogyRecordPayload {
+  format?: string
+  schema_version?: number
+  airalogy_record_id?: string | null
+  record_id?: string | null
+  record_version?: number | null
+  metadata?: Record<string, unknown> | null
+  data?: {
+    var?: Record<string, unknown>
+    step?: Record<string, unknown>
+    check?: Record<string, unknown>
+    quiz?: Record<string, unknown>
+    [key: string]: unknown
+  }
+  files?: Array<Record<string, unknown>>
+  [key: string]: unknown
+}
+
 export interface AiraBlobManifest {
   blob_id: string
   archive_path: string
@@ -112,6 +132,88 @@ function validateMemberPath(name: string): string | null {
   return null
 }
 
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+}
+
+function validateRecordPayload(record: unknown, label: string): string[] {
+  const issues: string[] = []
+  if (!isPlainObject(record)) {
+    return [`${label} must be a JSON object.`]
+  }
+
+  if (record.format !== undefined && record.format !== AIRALOGY_RECORD_FORMAT) {
+    issues.push(`${label} format must be '${AIRALOGY_RECORD_FORMAT}' when present.`)
+  }
+  if (
+    record.schema_version !== undefined
+    && record.schema_version !== AIRALOGY_RECORD_SCHEMA_VERSION
+  ) {
+    issues.push(`${label} schema_version must be ${AIRALOGY_RECORD_SCHEMA_VERSION} when present.`)
+  }
+  if (
+    record.record_id !== undefined
+    && record.record_id !== null
+    && (typeof record.record_id !== 'string' || record.record_id.length === 0)
+  ) {
+    issues.push(`${label} record_id must be a non-empty string when present.`)
+  }
+  if (
+    record.airalogy_record_id !== undefined
+    && record.airalogy_record_id !== null
+    && (typeof record.airalogy_record_id !== 'string' || record.airalogy_record_id.length === 0)
+  ) {
+    issues.push(`${label} airalogy_record_id must be a non-empty string when present.`)
+  }
+  const recordVersion = record.record_version
+  if (
+    recordVersion !== undefined
+    && recordVersion !== null
+    && (typeof recordVersion !== 'number' || !Number.isInteger(recordVersion) || recordVersion < 1)
+  ) {
+    issues.push(`${label} record_version must be a positive integer when present.`)
+  }
+  if (
+    record.metadata !== undefined
+    && record.metadata !== null
+    && !isPlainObject(record.metadata)
+  ) {
+    issues.push(`${label} metadata must be an object when present.`)
+  }
+
+  if (!isPlainObject(record.data)) {
+    issues.push(`${label} data must be an object.`)
+    return issues
+  }
+  if (!isPlainObject(record.data.var)) {
+    issues.push(`${label} data.var must be an object.`)
+  }
+  for (const section of ['step', 'check', 'quiz']) {
+    const value = record.data[section]
+    if (value !== undefined && value !== null && !isPlainObject(value)) {
+      issues.push(`${label} data.${section} must be an object when present.`)
+    }
+  }
+
+  if (record.files !== undefined) {
+    if (!Array.isArray(record.files)) {
+      issues.push(`${label} files must be a list when present.`)
+    }
+    else {
+      for (const [index, fileRef] of record.files.entries()) {
+        if (!isPlainObject(fileRef)) {
+          issues.push(`${label} files[${index + 1}] must be an object.`)
+          continue
+        }
+        if (!['file_id', 'source_uri', 'blob_id'].some(key => typeof fileRef[key] === 'string' && fileRef[key])) {
+          issues.push(`${label} files[${index + 1}] must include file_id, source_uri, or blob_id.`)
+        }
+      }
+    }
+  }
+  return issues
+}
+
 function findEndOfCentralDirectory(bytes: Uint8Array): number {
   const minOffset = Math.max(0, bytes.length - 0xffff - 22)
   for (let offset = bytes.length - 22; offset >= minOffset; offset -= 1) {
@@ -407,14 +509,16 @@ export class AiraArchive {
       }
       recordPaths.add(path)
       let raw: Uint8Array
+      let parsedRecord: unknown
       try {
         raw = await this.readBytes(path)
-        JSON.parse(textDecoder.decode(raw))
+        parsedRecord = JSON.parse(textDecoder.decode(raw))
       }
       catch {
         issues.push(`Record file '${path}' is not valid UTF-8 JSON.`)
         continue
       }
+      issues.push(...validateRecordPayload(parsedRecord, `Record file '${path}'`))
       if (record.sha256) {
         const actualHash = await sha256Hex(raw)
         if (actualHash !== record.sha256) {