@x12i/memorix-metadata 3.0.0 → 3.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +73 -15
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,24 +1,82 @@
|
|
|
1
|
-
#
|
|
1
|
+
# `@x12i/memorix-metadata`
|
|
2
2
|
|
|
3
|
-
Declarative **metadata contracts**, **
|
|
3
|
+
Declarative **metadata contracts**, **multi-agent effective resolution**, and **metadata-only abstract unions** for Memorix.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
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.
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
- Declare **namespaced custom kinds** (`kindDeclarations` + `extensions`) for client-owned descriptor families (store/resolve only)
|
|
9
|
-
- Resolve effective metadata for `agentIds[]`
|
|
10
|
-
- Keep abstracts virtual (no abstract collections)
|
|
7
|
+
## Install
|
|
11
8
|
|
|
12
|
-
|
|
9
|
+
```bash
|
|
10
|
+
npm install @x12i/memorix-metadata@3.0.2
|
|
11
|
+
```
|
|
13
12
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
13
|
+
| Audience | Use this package? |
|
|
14
|
+
|----------|-------------------|
|
|
15
|
+
| Remote app | Usually **no** — call `memorix-service` `/api/metadata` |
|
|
16
|
+
| Pack authors / platform engineers | **Yes** — validate packs, resolve effective metadata in-process |
|
|
17
|
+
| “Install a pack into an org” | Use `@x12i/memorix-metadata-runtime` (or HTTP install routes) |
|
|
17
18
|
|
|
18
|
-
|
|
19
|
+
## What it covers
|
|
19
20
|
|
|
20
|
-
|
|
21
|
+
Built-in kinds (via `METADATA_KIND_IDS` / Catalox catalogs):
|
|
21
22
|
|
|
22
|
-
|
|
23
|
+
`agents` · `object-types` · `abstract-types` · `abstract-bindings` · `relationship-definitions` · `mappings` · `views` · `writes` · `sources` · `services` · `pipelines` · `schedules` · `kind-declarations`
|
|
23
24
|
|
|
24
|
-
**
|
|
25
|
+
Plus **namespaced custom kinds** (`kindDeclarations` + `extensions`) — store/resolve only; engines do not execute them.
|
|
26
|
+
|
|
27
|
+
## Core API
|
|
28
|
+
|
|
29
|
+
```ts
|
|
30
|
+
import {
|
|
31
|
+
validateMetadataPack,
|
|
32
|
+
assertValidMetadataPack,
|
|
33
|
+
resolveEffectiveMetadata,
|
|
34
|
+
resolveMultiAgentMetadata,
|
|
35
|
+
resolveAbstractBindingsFromPack,
|
|
36
|
+
normalizeOpsPackBundle,
|
|
37
|
+
METADATA_KIND_IDS,
|
|
38
|
+
isValidCustomKindId,
|
|
39
|
+
} from "@x12i/memorix-metadata";
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
| Function | Role |
|
|
43
|
+
|----------|------|
|
|
44
|
+
| `validateMetadataPack` / `assertValidMetadataPack` | Structural + cross-ref validation of a pack |
|
|
45
|
+
| `resolveEffectiveMetadata` / `resolveMultiAgentMetadata` | Merge `agentIds[]` inheritance into effective definitions |
|
|
46
|
+
| `resolveAbstractBindings*` | Plan abstract → concrete property paths (virtual only) |
|
|
47
|
+
| `normalizeOpsPackBundle` | Normalize ops-pack style JSON into a pack |
|
|
48
|
+
| `fingerprintDefinition` | Stable fingerprints for install/diff |
|
|
49
|
+
|
|
50
|
+
## Quick example
|
|
51
|
+
|
|
52
|
+
```ts
|
|
53
|
+
import { validateMetadataPack, resolveEffectiveMetadata } from "@x12i/memorix-metadata";
|
|
54
|
+
|
|
55
|
+
const pack = /* MetadataPack */;
|
|
56
|
+
const { ok, issues } = validateMetadataPack(pack);
|
|
57
|
+
if (!ok) throw new Error(issues.map((i) => i.message).join("; "));
|
|
58
|
+
|
|
59
|
+
const effective = resolveEffectiveMetadata({
|
|
60
|
+
packsByAgentId: { ops: pack },
|
|
61
|
+
agentIds: ["ops"],
|
|
62
|
+
});
|
|
63
|
+
// effective.effective → definitions with provenance; conflicts reported, not silent
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Custom-kind example pack: [`examples/custom-kinds/acme-ui-tabs.pack.json`](./examples/custom-kinds/acme-ui-tabs.pack.json)
|
|
67
|
+
|
|
68
|
+
## Boundaries
|
|
69
|
+
|
|
70
|
+
| Need | Use instead |
|
|
71
|
+
|------|-------------|
|
|
72
|
+
| Install / publish into Catalox + effective client | `@x12i/memorix-metadata-runtime` |
|
|
73
|
+
| HTTP for operators / remote apps | `@x12i/memorix-service` `/api/metadata` |
|
|
74
|
+
| Subject record I/O | `@x12i/memorix-data` / `/api/data` |
|
|
75
|
+
|
|
76
|
+
Abstracts stay **virtual** — no abstract collections and no abstract `recordId`.
|
|
77
|
+
|
|
78
|
+
## Docs
|
|
79
|
+
|
|
80
|
+
- Practical: [`documentation/metadata.md`](../documentation/metadata.md) · [`documentation/packages/memorix-metadata.md`](../documentation/packages/memorix-metadata.md)
|
|
81
|
+
- Ebook: [Metadata, Agents, Abstracts](../new-ebooks/05-metadata-agents-abstracts/)
|
|
82
|
+
- Hub: [https://ebooks.memorix.x12i.com](https://ebooks.memorix.x12i.com)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@x12i/memorix-metadata",
|
|
3
|
-
"version": "3.0.
|
|
3
|
+
"version": "3.0.2",
|
|
4
4
|
"description": "Canonical Memorix metadata contracts, effective multi-agent resolution, and metadata-only abstract unions (Phase 3).",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -28,7 +28,7 @@
|
|
|
28
28
|
"node": ">=18.0.0"
|
|
29
29
|
},
|
|
30
30
|
"dependencies": {
|
|
31
|
-
"@x12i/memorix-mapping": "^3.0.
|
|
31
|
+
"@x12i/memorix-mapping": "^3.0.2"
|
|
32
32
|
},
|
|
33
33
|
"devDependencies": {
|
|
34
34
|
"@types/node": "^20.14.0",
|