@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/memorix-metadata@3.0.2| 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 OTOT / 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 silentCustom-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 OTOT 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.