@x12i/memorix-metadata

Declarative metadata contracts, multi-agent effective resolution, and metadata-only abstract unions for Memorix.

This package is the law layer (what agents, types, views, mappings, and pipelines are). It does not install packs into Mongo, read subject records, or serve HTTP.

Install

npm install @x12i/[email protected]

| Audience | Use this package? | |----------|-------------------| | Remote app | Usually no — call memorix-service /api/metadata | | Pack authors / platform engineers | Yes — validate packs, resolve effective metadata in-process | | “Install a pack into an org” | Use @x12i/memorix-metadata-runtime (or HTTP install routes) |

What it covers

Built-in kinds (via METADATA_KIND_IDS / Catalox catalogs):

agents · object-types · abstract-types · abstract-bindings · relationship-definitions · mappings · views · writes · sources · services · pipelines · schedules · kind-declarations

Plus namespaced custom kinds (kindDeclarations + extensions) — store/resolve only; engines do not execute them.

Core API

import {
  validateMetadataPack,
  assertValidMetadataPack,
  resolveEffectiveMetadata,
  resolveMultiAgentMetadata,
  resolveAbstractBindingsFromPack,
  buildEffectiveMetadataTopology,
  normalizeOpxPackBundle,
  METADATA_KIND_IDS,
  isValidCustomKindId,
} from "@x12i/memorix-metadata";

| Function | Role | |----------|------| | validateMetadataPack / assertValidMetadataPack | Structural + cross-ref validation of a pack | | resolveEffectiveMetadata / resolveMultiAgentMetadata | Merge agentIds[] inheritance into effective definitions | | resolveAbstractBindings* | Plan abstract → concrete property paths (virtual only) | | buildEffectiveMetadataTopology | Project concrete OT↔OT / feed / pipeline-derived graph (no new authoring kinds) | | normalizeOpxPackBundle | Normalize opx-pack style JSON into a pack | | fingerprintDefinition | Stable fingerprints for install/diff |

Quick example

import { validateMetadataPack, resolveEffectiveMetadata } from "@x12i/memorix-metadata";

const pack = /* MetadataPack */;
const { ok, issues } = validateMetadataPack(pack);
if (!ok) throw new Error(issues.map((i) => i.message).join("; "));

const effective = resolveEffectiveMetadata({
  packsByAgentId: { opx: pack },
  agentIds: ["opx"],
});
// effective.effective → definitions with provenance; conflicts reported, not silent

Custom-kind example pack: examples/custom-kinds/acme-ui-tabs.pack.json

Boundaries

| Need | Use instead | |------|-------------| | Install / publish into Catalox + effective client | @x12i/memorix-metadata-runtime | | HTTP for operators / remote apps | @x12i/memorix-service /api/metadata | | Subject record I/O | @x12i/memorix-data / /api/data |

Abstracts stay virtual — no abstract collections and no abstract recordId.

Relationships are authored on abstracts; concrete OT↔OT edges come from buildEffectiveMetadataTopology (HTTP: GET /api/metadata/topology). Sources/streams feed object types; services appear on an OT neighborhood only when a pipeline invokes them and a mapping on that pipeline lands on an OT.

Docs

• Practical: documentation/metadata.md · documentation/packages/memorix-metadata.md
• Ebook: Metadata, Agents, Abstracts
• Hub: https://docs.memorix.x12i.com