@x12i/nexus

Platform-neutral evidence-graph compiler. Protocol x12i-nexus/1.

No Memorix, Fastify, Mongo, or network I/O. analyze returns a draft and a per-item apply plan. It never writes a database.

npm install @x12i/nexus

Node 18+. ESM only ("type": "module").

Full host + worker copy-paste: x12i/nexus README.

Analyze

import {
  analyze,
  analyzeRequest,
  structuredItem,
  contentItem,
} from "@x12i/nexus";

const result = await analyze({
  request: analyzeRequest([
    structuredItem("credorix", "product", {
      name: "Credorix",
      ownerTeamId: "identity-team",
    }),
    contentItem(
      "auth",
      "# Auth\n\nSee [Credorix](nexus://product/credorix).\n\n## Tokens\n",
      { title: "Auth" },
    ),
  ]),
});

result.graphDraft.nodes;
result.graphDraft.propertyClaims;
result.graphDraft.edgeClaims;
result.applyPlan.actions; // replace-contribution | remove-contribution
result.itemResults;       // ok | failed | skipped
result.diagnostics;

Explicit request (no test helpers):

import {
  ANALYZER_VERSION,
  DEFAULT_LIMITS,
  NEXUS_PROTOCOL,
  analyze,
  coreRegistrySnapshot,
} from "@x12i/nexus";

await analyze({
  request: {
    protocol: NEXUS_PROTOCOL,
    scope: { organizationId: "acme", graphId: "default" },
    items: [
      {
        sourceRef: { namespace: "records", id: "credorix" },
        inputKind: "structured",
        objectType: "product",
        data: { name: "Credorix", ownerTeamId: "identity-team" },
      },
    ],
    registry: coreRegistrySnapshot(),
    options: {
      analyzerVersion: ANALYZER_VERSION,
      deterministicOnly: true,
      crossItemInference: true,
      limits: { ...DEFAULT_LIMITS },
    },
  },
});

Input kinds

| inputKind | objectType | Body | |-------------|--------------|------| | structured | product, team, service, person, object, … | data object | | content | document | content string (format: "markdown" \| "text") | | json-schema | schema | JSON Schema in data | | openapi | openapi | OpenAPI 3.x or Swagger 2.0 in data | | endpoint | endpoint | { method, path } in data |

Mapped structured fields (core registry):

{
  name: "Credorix",
  ownerTeamId: "identity-team", // owned_by → team stub
  parentId: "platform",         // parent --parent_of--> this node
  uses: ["entra-id"],           // uses → technology stub
  externalAuthority: "sku",
  externalId: "X-1",            // exact auto-merge key
}

Markdown links: nexus://{type}/{id}. Other schemes need referenceResolvers.

await analyze({
  request: analyzeRequest([contentItem("d", "See [P](nexus://product/p).\n")]),
  // referenceResolvers: [{ scheme: "memorix", resolve(uri) { ... } }],
});

Delete:

analyzeRequest([], {
  deletions: [{ sourceRef: { namespace: "records", id: "credorix" } }],
});

Identity

• Node id: {type}:{namespace}:{id} or {type}:derived:{slug}-{hash12}
• Auto-merge: exact source id or exact externalAuthority + externalId
• Same label across types/namespaces: not merged (review candidate)
• parentId is the parent of the current record (parent_of source → child)

Optional AI

import {
  ANALYZER_VERSION,
  DEFAULT_LIMITS,
  analyze,
  analyzeRequest,
  contentItem,
  createFakeSemanticProvider,
  spanFact,
} from "@x12i/nexus";

const provider = createFakeSemanticProvider((req) => ({
  facts: [
    spanFact(req.chunk.text, "Alpha uses Beta", {
      kind: "relation",
      relation: "uses",
      sourceLabel: "Alpha",
      targetLabel: "Beta",
    }),
  ],
  tokensIn: 10,
  tokensOut: 5,
});

await analyze({
  semanticProvider: provider,
  semanticBudget: { maxInputTokens: 50_000, maxOutputTokens: 16_000, maxChunks: 24 },
  request: {
    ...analyzeRequest([contentItem("p", "Alpha uses Beta in production.")]),
    options: {
      analyzerVersion: ANALYZER_VERSION,
      deterministicOnly: false,
      crossItemInference: false,
      semantic: {
        enabled: true,
        required: false,
        policyId: "default",
        promptVersion: "nexus-semantic-1",
        providerModel: "fake",
        requireReviewForAiFacts: false,
      },
      limits: { ...DEFAULT_LIMITS },
    },
  },
});

Implement NexusSemanticProvider for a real model. Quotes must be exact spans. Missing provider + required: false → deterministic success, semantic.status: "unavailable".

Errors and abort

import { isNexusError } from "@x12i/nexus";

try {
  await analyze({ request, signal });
} catch (err) {
  if (isNexusError(err)) {
    // err.code, err.retryable, err.details
  }
  throw err;
}

NEXUS_VALIDATION, NEXUS_LIMIT_EXCEEDED, NEXUS_REGISTRY_MISSING, NEXUS_ABORTED, NEXUS_SEMANTIC_UNAVAILABLE, NEXUS_SEMANTIC_BUDGET_EXCEEDED.

Unknown objectType fails that item (itemResults[].status === "failed"), not the whole request.

Public exports

analyze, analyzeRequest, structuredItem, contentItem, coreRegistrySnapshot, canonicalize, hashCanonical, NexusError, isNexusError, NEXUS_PROTOCOL, ANALYZER_VERSION, DEFAULT_LIMITS, createFakeSemanticProvider, spanFact, graph algorithms (neighborhood, shortestPath, detectCycles, communities).

Types: NexusAnalyzeRequest, NexusAnalyzeResult, NexusItem, NexusSemanticProvider, AnalyzeInvocation.