@x12i/memorix-abstracts

Map-1 abstract envelopes, mapping runtime, object-catalog join, integrity report, and acquisition handoff/admission for Memorix.

npm install @x12i/memorix-abstracts@^0.2.1

Public surface

| Module | Role | | --- | --- | | abstract/* | Envelope types, mapper, mapping runtime, workerMap | | objectCatalog | Companion join → memorix-object-catalog/1 | | integrityReport | Scoring → memorix-connector-integrity-report/1 | | acquisition/* | Handoff, records, stage admission | | rawEnvelope | Raw-first ingest envelope | | normalize | Canonicalize transforms (N1-style) | | attribution | IP / asset join primitives | | findings | Finding + instrument ledger types |

Map-1 / acquisition handoff contract

1. Connectors map vendor payloads into AbstractEnvelopes via field maps + mapOperationPayload / workerMap.
2. Acquisition packages admitted records through stageAdmission + handoff (content-hash, provenance, abstract type).
3. MGC continues to stamp semanticProfileId / route ids only — field maps remain companion JSON consumed by this runtime.
4. Product-specific recipes and vendor-local helpers stay in the consuming host, not this package.

Abstraction companion (memorix-connector-abstraction/1)

Author a companion JSON next to the connector definition. Protocol must be memorix-connector-abstraction/1 (isAbstractionCompanionProtocol / assertAbstractionCompanion).

| Field | Role | | --- | --- | | abstractCoverage | Declared abstract property lists per Map-1 type | | operations[] | Per-op propertyMappings (required allowed), unsupportedReason, identity/abstract types | | semanticProfiles[] | Profile-keyed maps (lookup/KV/search/cim-branch). When semanticProfileId is passed to mapOperationPayload, profile wins — no silent fallback to the operation map |

Operations vs semanticProfiles: MGC stamps semanticProfileId / acquisitionRouteId on provenance only. Field maps stay in this companion. Use operations for 1:1 op maps; use semanticProfiles when one acquisition op fans out by product profile.

Object catalog join (memorix-object-catalog/1)

import {
  buildDefinitionObjectCatalog,
  defaultRawCollectionName,
} from "@x12i/memorix-abstracts";

const catalog = buildDefinitionObjectCatalog(definition, companion, {
  observed,   // optional: objectType or collection → field names (opaque; no Mongo)
  extensions, // optional: host-specific rows, never inferred
});

Inputs

• Duck-typed definition: definitionId, streams[] (streamId, objectType, op refs), operations[] (operationId, sideEffect, requiredness, product metadata), optional objectTypes.
• Abstraction companion (or the join uses companion maps only if the def has no streams/ops).

Outputs (kind: "memorix-object-catalog/1")

• objects[]: objectType, Explorer collection (default {objectType}-raw), streamIds / operationIds, abstractTypes, propertyMappings, declaredAbstractProperties, unsupportedReason, product-metadata passthrough, matching semanticProfiles.
• systemCollections: generic kinds only — abstract-envelopes, connector-integrity-runs.
• extensions: caller-supplied only.

Host HTTP convention (not implemented here): GET /api/object-catalog, GET /api/object-catalog/:connector.

Integrity report (memorix-connector-integrity-report/1)

import {
  buildIntegrityReport,
  createIntegrityRun,
  inferIntegrityRunMode,
} from "@x12i/memorix-abstracts";

const report = buildIntegrityReport({
  definition,
  abstraction, // companion or catalog join result
  store,       // optional: collection → { count, domainFields, sampleDocs }
  live,        // optional: opId → { returnedCount, matchedCount, truncated, status }
});

This does not replace streamComplete / admitFeatures. Persistence is an Explorer write of the ledger document, not a memorix-service RPC.

Pin derivation (no fourth JSON)

| Pin | Source | | --- | --- | | write | operation.sideEffect !== "read" (missing sideEffect treated as read) | | DATA-only | companion unsupportedReason and/or empty abstractTypes | | optional vs must | requiredness: "optional" \| "must" (default must) | | collection name | {objectType}-raw via defaultRawCollectionName | | vendor total / truncation | live matchedCount / truncated (def totalCountPath is passthrough until the host fills live) |

Scoring

| Status | When | | --- | --- | | unsupported | DATA-only / no abstract map | | skipped | write op, or optional miss / skip-allowed | | missing | must read, no store/live evidence | | partial | truncated (matchedCount > returnedCount or flag) or store count < vendor total or required mapped sources missing on observed docs | | complete | must/optional read acquired; not truncated; required sources present when docs exist | | failed | must read live fail / envelope broken |

Report-level coreComplete is true when every must object is complete, unsupported (DATA-only), or skipped (writes). Optional misses do not fail the report.

Host HTTP convention (not implemented here)

• GET /api/integrity — all loaded definitions
• GET /api/integrity/:connector — one report

Same pattern as GET /api/object-catalog.

Ledger (memorix.connector-integrity-run.v1)

Explorer collection connector-integrity-runs (generic system kind).

{
  schema: "memorix.connector-integrity-run.v1",
  definitionId: string,
  generatedAt: string,        // ISO
  mode: "contract" | "store" | "live",
  report: MemorixConnectorIntegrityReport,
  workspaceId?: string
}

createIntegrityRun({ report, mode, workspaceId? }) builds that document. inferIntegrityRunMode({ store, live }) picks live / store / contract.

Non-goals

• Product-specific recipes or vendor-local helpers inside this package
• Changing Magit/MGC semantic-profile stamping
• Host HTTP servers or Explorer writers
• Inferring host-specific catalog collections as default system rows