@x12i/memorix-relationships
Trusted relationship engine: compile definitions, discover, materialize, verify, and rebuild four-field links.
This is the only production path that writes relationship links. Remote clients use HTTP; ad-hoc /links mutation is rejected (405).
Install
npm install @x12i/memorix-relationships@3.0.2
| Audience | Use this package? |
|---|---|
| Remote app | No — /api/relationships |
| Platform / pipelines | Yes |
Core API
import { createRelationshipEngine } from "@x12i/memorix-relationships";
const engine = createRelationshipEngine({ /* store, metadata resolver, data reader */ });
// Dry-run candidates
await engine.discoverAndMaterialize(scope, definitionId, { dryRun: true });
// Persist links
await engine.discoverAndMaterialize(scope, definitionId, { dryRun: false });
await engine.verify(scope, definitionId);
await engine.rebuild(scope, definitionId);
Lifecycle:
relationship definition (metadata)
→ discover (candidates, service-held)
→ materialize (four-field links in store)
→ verify / rebuild
Hard rules
- Links are exactly four fields (
relationshipId,relationshipDefinitionId,fromRecordId,toRecordId). - Never copy related payloads into the source record (
associated*as storage is forbidden). - Neighbor content is read at expand time, not embedded.
Declaring a link
Put the definition in the agent pack. A source-field rule reads an id from one content body and matches it to an existing target recordId.
{
"id": "commitment-contract",
"name": "Commitment to contract",
"meaning": "The commitment was extracted from this contract",
"directionality": "directed",
"from": { "abstractType": "Commitments", "path": "contract" },
"to": { "abstractType": "Contracts", "path": "commitments" },
"discoveryRules": [
{
"id": "by-contract",
"kind": "source-field",
"sourceEndpoint": "from",
"contentType": "extracted",
"sourcePath": "contractId"
}
]
}
contentTypeis the content document that stores the id.sourcePathis inside that document'sdata(contractId, notextracted.data.contractId). OmitcontentTypeonly when the id lives onraworsnapshots.- An array at
sourcePathbecomes one link per id. The path has no[]suffix. - Two possible target types: one abstract whose members are both object types, or two definitions.
- A link that depends on a status: write the id only in the matching state. Clear the field to drop the link. There is no value predicate on the rule.
sourceEndpoint: "from"reads the id on the source record.
writeContent does not create or remove links. After a write or a clear:
POST /api/relationships/rebuild
{ "definitionId": "commitment-contract", "confirm": true }
Then GET /api/relationships/query?recordId=…&definitionId=commitment-contract.
Discover only adds links. Rebuild adds missing links and removes a link when the scanned source no longer points at that target. A link whose source was not read is left in place. If the result includes DISCOVER_BOUND_EXCEEDED, pass a higher maxRecordsPerObjectType and rebuild again. The default cap is 500 records per object type.
Related
| Need | Package |
|---|---|
| Persistence adapter | @x12i/memorix-relationship-store |
| Compose / expand reads | @x12i/memorix-data |
| Pipeline steps | relationship-discover / relationship-write in @x12i/memorix-pipeline |
Docs
npm test