xmemory-contracts

Stable contract tier for xmemory MongoDB naming, document envelopes, join keys, and required indexes.

What this package exports

• Environment contract (ResolvedXmemoryEnv, resolveXmemoryEnv)
• Collection contracts: names, JSON Schemas, TS types, and index specs
• Optional record fragments (e.g. MITRE ATT&CK) and scoped triage graph constants (THING_TYPE_SCOPED_TRIAGE_ARTIFACT, EDGE_TYPE_ENTITY_TO_SCOPED_TRIAGE_ARTIFACT)
• Join keys (canonical join fields)
• Schema version strings and compatibility expectations
• Runtime validation helpers (AJV)

Environment contract

Required input

• MONGO_URI (or MONGO_CONNECTION_STRING)

Logical DB defaults

• metaDb: xmemory-meta
• opDb: xmemory-op

Overrides (canonical)

• MONGO_XMEMORY_META_DB → overrides metaDb
• MONGO_XMEMORY_OPERATIONAL_DB (or legacy MONGO_XMEMORY_DB) → overrides opDb
• TARGET_NAMESPACE → namespace filter used by writers/readers

Install

npm i @x12i/xmemory-contracts

Usage

import {
  resolveXmemoryEnv,
  Collections,
  Schemas,
  Indexes,
  Joins,
  SchemaVersions,
  validateDoc
} from "@x12i/xmemory-contracts";

const env = resolveXmemoryEnv(process.env);
// env.metaDb, env.opDb, env.namespace, env.collections...

// Validate before writing (dev/CI)
validateDoc(Schemas.meta.scoping_maps, doc);

Collections (logical)

Meta DB

• scoping_maps: one doc per scoping question (required items + plan + diagnostics)
• xmemory_things: canonical “things corpus” (domain + schema things)

Op DB

• x-snapshots: full-fidelity snapshots of source records
• scoped_views: materialized scoping output for (aboutThingId × scopingMapId)
• x-scoped-data: data-level answers per (snapshot × scoping map)

Indexes

Index specs are exported as data (Indexes) so writers/readers can apply/verify them consistently.

Join keys (canonical)

Joins encodes the stable join fields:

• meta.scoping_maps.id → op.scoped_views.scopingMapId
• meta.scoping_maps.id → op.x-scoped-data._meta.scopingMapId
• meta.xmemory_things._id → op.scoped_views.aboutThingId (stored as hex string)
• op.x-snapshots._snapshot.sourceId → op.x-scoped-data._meta.sourceId

x-scoped-data answer entries (answer.*)

Each answer value is an object with required value and fieldPath. Optional fields:

• linked: When omitted or false, value comes from the primary entity’s row (_meta.entityType, _meta.entityId). When true, value was resolved from another entity’s scoped row (linked read; see @x12i/xmemory-scoper FR-XMS-1).
• linkedEntityType, linkedEntityId: When linked is true, SHOULD be set to identify the source entity for the linked read.

Migration (additive): Consumers that assumed only { value, fieldPath } remain valid; new keys are optional.

x-scoped-data optional PRE / synthesis fields

Optional top-level fields on the same document (distinct from scope.contextualKnowledge in scoped_views, which is scoper graph context):

• synthesizedContext: Structured output from a cheap-model / PRE-style step, persisted for reuse.
• synthesizedInput: Optional materialized question or template bundle for the main step.
• synthesisFreshness: How to decide reuse vs re-run PRE — required inner producedAt (ISO8601), optional boundSnapshotId (stale when it does not match the row’s active snapshot), optional pipelineVersion (opaque; stale when the running pipeline differs).

This is not a substitute for web-derived or live-fetched fields elsewhere on domain records; it only describes what was stored on the scoped-data row at triage time.

MITRE ATT&CK fragment (optional on records)

Types MitreAttackFragment and schema helper MitreAttackSchemaFragment document an optional mitreAttack shape for vulnerability-style payloads, for example:

{
  "mitreAttack": {
    "tactics": [{ "id": "TA0001", "name": "Initial Access" }],
    "techniques": [{ "id": "T1190", "name": "Exploit Public-Facing Application" }]
  }
}

Stability: For interchange, id (and matching name) SHOULD use official MITRE ATT&CK stable identifiers and display names. Internal aliases are allowed if documented by the producer but MUST NOT reuse official MITRE IDs with different meanings.

There is no Zod in this package; mirror the exported TypeScript types in consumers if you need runtime parsing.

Scoped triage artifact vocabulary

Canonical strings (also exported as constants) for the persisted scoped triage artifact graph:

• Thing type: xmemory.scoper.scoped_triage_artifact — THING_TYPE_SCOPED_TRIAGE_ARTIFACT
• Edge from scoped entity Thing to artifact Thing: xmemory.scoper.entity_scoped_triage — EDGE_TYPE_ENTITY_TO_SCOPED_TRIAGE_ARTIFACT

No earlier informal names existed in this repository; adopt these in scoper, writers, and UIs for one shared vocabulary.

Versioning contract

Canonical version strings are exported as SchemaVersions:

• xmemory.scoper.scopingmap.v1
• xmemory.scoper.scopeplan.v1
• xmemory.scoper.scopedview.v1
• xmemory.scoper.scopedaboutcache.v1

Compatibility rules (v1):

• Additive changes allowed (new optional fields)
• Changing/removing required fields is breaking → requires v2
• Readers must ignore unknown fields

Publishing (public npm)

This package is published to the public npm registry as @x12i/xmemory-contracts:

• publishConfig.registry → https://registry.npmjs.org/
• publishConfig.access → public (required once per scoped package on npm)
• prepublishOnly runs lint, typecheck, test, and build

Authenticate with npm login (or a CI NPM_TOKEN with automation access). Do not commit registry auth tokens.

npm publish