@avee1234/memport 0.1.0

package/src/export.js

@@ -0,0 +1,51 @@
+// memport export — read a memory store into the neutral memport format (#2).
+//
+// A thin, adapter-based pipeline on top of the #1 schema:
+//   1. select an export adapter (default `folder`) from the registry,
+//   2. call its `read` to get raw record objects from the store,
+//   3. run them through `validateMemorySet`,
+//   4. return the array on success, or throw an ExportError on failure.
+//
+// The output is exactly a memory set — a bare JS array `validate`/`import`
+// understand — so `exportMemory` composes directly with import (#3) and
+// conformance (#4). Export does I/O, so unlike the validators it can throw:
+// failures surface as an ExportError carrying the structured #1 errors.
+
+import { validateMemorySet } from './validate.js';
+import { getAdapter } from './adapters/index.js';
+
+/**
+ * Error thrown by the export pipeline. `.code` names the failure so the CLI can
+ * map it to an exit code; `.errors` carries the #1 structured errors on an
+ * invalid set, and `.file` names the offending file for I/O failures.
+ */
+export class ExportError extends Error {
+  constructor(code, message, { errors, file } = {}) {
+    super(message);
+    this.name = 'ExportError';
+    this.code = code;
+    if (errors !== undefined) this.errors = errors;
+    if (file !== undefined) this.file = file;
+  }
+}
+
+/**
+ * Read a memory store into a validated memory set.
+ * @param {string} source - a directory or `.json` file (folder adapter), etc.
+ * @param {{ adapter?: string }} [opts]
+ * @returns {Array<object>} the memory set (passes validateMemorySet)
+ * @throws {ExportError} on unknown adapter, I/O failure, or an invalid set
+ */
+export function exportMemory(source, opts = {}) {
+  const adapter = getAdapter(opts.adapter ?? 'folder');
+  const { records } = adapter.read(source, opts);
+
+  const { valid, errors } = validateMemorySet(records);
+  if (!valid) {
+    throw new ExportError('invalid_set', 'export produced an invalid memory set', {
+      errors,
+    });
+  }
+
+  return records;
+}

package/src/import.js

@@ -0,0 +1,119 @@
+// memport import — write a memport set into a target store (#3).
+//
+// The mirror of export (#2): where export reads a store *out* into the neutral
+// format and validates its *output*, import takes a neutral set and writes it
+// *into* a target, validating its *input* first. Same adapter seam, opposite
+// direction:
+//   1. validate the incoming set with `validateMemorySet` — reject garbage
+//      before touching the target (symmetric to export's output check),
+//   2. select an import adapter (default `folder`) from the registry,
+//   3. `map` the set to what the target can hold, splitting off an
+//      `unsupported` list of `{ id, fields }` (empty for the full-fidelity
+//      folder target — but the reporting path is real, because loudly naming
+//      what a target cannot represent is the whole point of import),
+//   4. read the target's existing records and apply the merge `mode`
+//      (`merge` | `replace` | `fail`) with an adapter-agnostic helper,
+//   5. write the final list back via the adapter,
+//   6. return `{ written, skipped, unsupported }`.
+
+import { validateMemorySet } from './validate.js';
+import { getImportAdapter } from './adapters/index.js';
+
+// The merge modes. `merge` (default) is additive/non-destructive; `replace`
+// discards existing target records; `fail` refuses a non-empty target.
+export const IMPORT_MODES = ['merge', 'replace', 'fail'];
+
+/**
+ * Error thrown by the import pipeline. Mirrors `ExportError`'s shape so the CLI
+ * renders both uniformly: `.code` names the failure for exit-code mapping,
+ * `.errors` carries the #1 structured errors on an invalid input set, and
+ * `.file` names the offending file for I/O failures.
+ */
+export class ImportError extends Error {
+  constructor(code, message, { errors, file } = {}) {
+    super(message);
+    this.name = 'ImportError';
+    this.code = code;
+    if (errors !== undefined) this.errors = errors;
+    if (file !== undefined) this.file = file;
+  }
+}
+
+// Adapter-agnostic merge, keyed by `id`. Returns the final record list plus the
+// written/skipped counts. Order is fixed for determinism.
+//   - replace → the incoming set wins outright.
+//   - merge   → existing kept as-is; incoming records with a *new* id appended
+//               (written), incoming records whose id already exists dropped
+//               (skipped, existing wins — non-destructive). Existing order
+//               first, then new records in incoming order.
+//   - fail    → the caller rejects a non-empty target before calling; on an
+//               empty target this behaves like replace.
+function applyMode(existing, incoming, mode) {
+  if (mode === 'replace' || mode === 'fail') {
+    return { final: incoming, written: incoming.length, skipped: 0 };
+  }
+
+  // mode === 'merge'
+  const existingIds = new Set(existing.map((r) => r.id));
+  const newOnes = [];
+  let skipped = 0;
+  for (const record of incoming) {
+    if (existingIds.has(record.id)) {
+      skipped++;
+    } else {
+      newOnes.push(record);
+    }
+  }
+  return {
+    final: existing.concat(newOnes),
+    written: newOnes.length,
+    skipped,
+  };
+}
+
+/**
+ * Write a memport set into a target store.
+ * @param {Array<object>} set - a memport set (e.g. the output of `exportMemory`)
+ * @param {string} target - the target store (a `.json` / `.memport` file for folder)
+ * @param {{ adapter?: string, mode?: string }} [opts]
+ * @returns {{ written: number, skipped: number, unsupported: Array<{id: string, fields: string[]}> }}
+ * @throws {ImportError} on an invalid set, unknown adapter/mode, a blocked
+ *   `fail` target, or an I/O failure — always *before* any partial write.
+ */
+export function importMemory(set, target, opts = {}) {
+  const { valid, errors } = validateMemorySet(set);
+  if (!valid) {
+    throw new ImportError('invalid_set', 'import received an invalid memory set', {
+      errors,
+    });
+  }
+
+  const adapter = getImportAdapter(opts.adapter ?? 'folder');
+
+  const mode = opts.mode ?? 'merge';
+  if (!IMPORT_MODES.includes(mode)) {
+    throw new ImportError('unknown_mode', `unknown mode: ${mode} (known: ${IMPORT_MODES.join(', ')})`);
+  }
+
+  // Map the set to what the target can hold, splitting off anything the target
+  // cannot represent (empty for the full-fidelity folder target).
+  const { supported, unsupported } = adapter.map(set, opts);
+
+  // Read existing target records (empty for a not-yet-existing target — writing
+  // to a fresh file is the common case, not an error).
+  const existing = adapter.readExisting(target, opts);
+
+  if (mode === 'fail' && existing.length > 0) {
+    throw new ImportError(
+      'target_not_empty',
+      `target already contains ${existing.length} record${existing.length === 1 ? '' : 's'}; refusing to import with --mode fail`,
+      { file: target },
+    );
+  }
+
+  const { final, written, skipped } = applyMode(existing, supported, mode);
+
+  adapter.write(target, final, opts);
+
+  return { written, skipped, unsupported };
+}

package/src/index.js

@@ -0,0 +1,6 @@
+// Public surface for @avee1234/memport.
+export { validateMemoryRecord, validateMemorySet, KINDS } from './validate.js';
+export { exportMemory, ExportError } from './export.js';
+export { importMemory, ImportError, IMPORT_MODES } from './import.js';
+export { scoreConformance, ConformanceError, CONFORMANCE_IDENTITIES } from './conformance.js';
+export { EXPORT_ADAPTERS, IMPORT_ADAPTERS } from './adapters/index.js';

package/src/validate.js

@@ -0,0 +1,170 @@
+// Portable memory-record schema + validators (v0.1).
+//
+// Hand-written, zero-dependency. Both validators are pure and never throw:
+// bad input is reported as a structured error, not an exception, so adapters
+// can collect and report all problems instead of catching.
+//
+// Error shape:
+//   record-level: { code, path, message }
+//   set-level:    { index, code, path, message }   // adds the record's index
+// Return value is always { valid, errors } with valid === (errors.length === 0).
+
+export const KINDS = ['fact', 'preference', 'event', 'entity'];
+
+// --- helper predicates -------------------------------------------------------
+
+function isPlainObject(v) {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+function isNonEmptyString(v) {
+  return typeof v === 'string' && v.length > 0;
+}
+
+// Date.parse is lenient (some engines accept "yesterday" or partial forms), so
+// we pair it with a shape guard requiring an ISO-8601-ish string: a date, an
+// optional time, and an optional Z or ±HH:MM offset.
+const ISO_8601 =
+  /^\d{4}-\d{2}-\d{2}([T ]\d{2}:\d{2}(:\d{2})?(\.\d+)?(Z|[+-]\d{2}:\d{2})?)?$/;
+
+function isIsoTimestamp(v) {
+  return typeof v === 'string' && ISO_8601.test(v) && !Number.isNaN(Date.parse(v));
+}
+
+function isStringArray(v) {
+  return Array.isArray(v) && v.every((x) => typeof x === 'string');
+}
+
+function isNumberArray(v) {
+  return Array.isArray(v) && v.every((x) => typeof x === 'number' && !Number.isNaN(x));
+}
+
+// --- record validator --------------------------------------------------------
+
+/**
+ * Validate a single memory record.
+ * @param {unknown} obj
+ * @returns {{ valid: boolean, errors: Array<{code: string, path: string, message: string}> }}
+ */
+export function validateMemoryRecord(obj) {
+  const errors = [];
+  const err = (code, path, message) => errors.push({ code, path, message });
+
+  if (!isPlainObject(obj)) {
+    err('not_an_object', '', 'record must be a plain JSON object');
+    return { valid: false, errors };
+  }
+
+  // Required: id, content, kind, created.
+  if (!('id' in obj)) {
+    err('missing_field', 'id', 'id is required');
+  } else if (!isNonEmptyString(obj.id)) {
+    err('empty_string', 'id', 'id must be a non-empty string');
+  }
+
+  if (!('content' in obj)) {
+    err('missing_field', 'content', 'content is required');
+  } else if (!isNonEmptyString(obj.content)) {
+    err('empty_string', 'content', 'content must be a non-empty string');
+  }
+
+  if (!('kind' in obj)) {
+    err('missing_field', 'kind', 'kind is required');
+  } else if (!KINDS.includes(obj.kind)) {
+    err('invalid_enum', 'kind', `kind must be one of ${KINDS.join(' | ')}`);
+  }
+
+  if (!('created' in obj)) {
+    err('missing_field', 'created', 'created is required');
+  } else if (!isIsoTimestamp(obj.created)) {
+    err('invalid_iso8601', 'created', 'created must be an ISO 8601 timestamp');
+  }
+
+  // Optional fields — only checked when present.
+  if ('salience' in obj) {
+    if (typeof obj.salience !== 'number' || Number.isNaN(obj.salience)) {
+      err('wrong_type', 'salience', 'salience must be a number');
+    } else if (obj.salience < 0 || obj.salience > 1) {
+      err('out_of_range', 'salience', 'salience must be in [0, 1]');
+    }
+  }
+
+  if ('source' in obj && !isNonEmptyString(obj.source)) {
+    err('empty_string', 'source', 'source must be a non-empty string');
+  }
+
+  if ('links' in obj && !isStringArray(obj.links)) {
+    err('wrong_type', 'links', 'links must be an array of strings');
+  }
+
+  if ('embedding' in obj && !isNumberArray(obj.embedding)) {
+    err('wrong_type', 'embedding', 'embedding must be an array of numbers');
+  }
+
+  // Unknown/extra fields are allowed and preserved — not an error.
+
+  return { valid: errors.length === 0, errors };
+}
+
+// --- set validator -----------------------------------------------------------
+
+/**
+ * Validate a memory set (array of records). Runs the record validator per
+ * element (prefixing each error with its index), then two cross-record checks:
+ * unique ids and referential integrity of links.
+ * @param {unknown} arr
+ * @returns {{ valid: boolean, errors: Array<{index?: number, code: string, path: string, message: string}> }}
+ */
+export function validateMemorySet(arr) {
+  const errors = [];
+
+  if (!Array.isArray(arr)) {
+    errors.push({
+      code: 'not_an_array',
+      path: '',
+      message: 'memory set must be a JSON array of records',
+    });
+    return { valid: false, errors };
+  }
+
+  // Per-record validation, tagged with the record's index.
+  arr.forEach((record, index) => {
+    const { errors: recErrors } = validateMemoryRecord(record);
+    for (const e of recErrors) errors.push({ index, ...e });
+  });
+
+  // Collect the set's ids for the cross-record checks.
+  const seen = new Set();
+  const ids = new Set();
+  arr.forEach((record, index) => {
+    if (!isPlainObject(record) || !isNonEmptyString(record.id)) return;
+    if (seen.has(record.id)) {
+      errors.push({
+        index,
+        code: 'duplicate_id',
+        path: 'id',
+        message: `duplicate id: ${record.id}`,
+      });
+    } else {
+      seen.add(record.id);
+    }
+    ids.add(record.id);
+  });
+
+  // Dangling links — a link that points to an id absent from the set.
+  arr.forEach((record, index) => {
+    if (!isPlainObject(record) || !isStringArray(record.links)) return;
+    record.links.forEach((linkId) => {
+      if (!ids.has(linkId)) {
+        errors.push({
+          index,
+          code: 'dangling_link',
+          path: 'links',
+          message: `link points to unknown id: ${linkId}`,
+        });
+      }
+    });
+  });
+
+  return { valid: errors.length === 0, errors };
+}