npm.io
3.2.0 • Published 1 month ago

@x12i/memorix-relationships

Licence
exellix-license
Version
3.2.0
Deps
5
Size
177 kB
Vulns
0
Weekly
0

@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.

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"
    }
  ]
}
  • contentType is the content document that stores the id. sourcePath is inside that document's data (contractId, not extracted.data.contractId). Omit contentType only when the id lives on raw or snapshots.
  • An array at sourcePath becomes 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.

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