Skip to content
ContractSpec
Start here

Package manual · platform

·Forms, data views and data exchange

lib.data-exchange-core

SchemaModel-first core primitives for data import/export and mapping

platformlibraryv2.0.4experimentalservernode
@lssm-tech/lib.data-exchange-core
bun add @lssm-tech/lib.data-exchange-core
Package source ↗Manifest ↗

Manifest declarations describe the current workspace; they do not verify registry publication or runtime execution.

Package guide

Website: https://contractspec.io

SchemaModel-first core primitives for data import, export, mapping, preview, and reconciliation planning.

What It Provides

  • Headless CSV, JSON, and XML codecs.
  • Normalized RecordBatch contracts for runtime data interchange.
  • SchemaModel mapping inference, coercion, and validation helpers.
  • Import/export planning and preview diff APIs.
  • Provider-neutral governed projection contracts for cross-product sharing, consent and lawful-basis grants, residency, retention, revocation, and privacy

status.

Delivery contracts add leased pending → processing → retry_scheduled recovery with explicit applied or dead_letter terminals. Rights jobs follow the same bounded-attempt discipline. Operator projections expose application, state, attempt, redacted error, and evidence references only—never pairwise subjects or shared values.

Product recovery dispatches are a narrower contract than the central queue record. They carry only the receiving consumer or processor's pairwise subject, exact grant/projection event or rights operation, product binding, and idempotency identifier. Scheduler leases, attempt counters, payloads, credentials, and source values are rejected. Revocation and rights dispatches name the receiver-specific pairwise subject. They never reuse another relying party's subject or expose the canonical identity.

Installation

npm install @lssm-tech/lib.data-exchange-core

or

bun add @lssm-tech/lib.data-exchange-core

Usage

Import the root entrypoint from @lssm-tech/lib.data-exchange-core, or use subpaths such as ./codecs, ./governed, ./mapping, ./plans, ./preview, ./records, ./schema, and ./types.

SQL sources and targets may include optional portable database metadata (database.resource, fieldMapping, policyRefs, and provenance). The core package remains runtime-agnostic; server adapters and provider integrations decide how to execute PostgreSQL, SQLite, or MySQL work.

Import Templates

Developers can define the recommended import shape once, then let users upload files with different column labels or value formats:

ts
import {
	createImportPlan,
	createRecordBatch,
	defineDataExchangeTemplate,
	previewImport,
} from "@lssm-tech/lib.data-exchange-core";

const template = defineDataExchangeTemplate({
	key: "accounts.import",
	version: "1.0.0",
	columns: [
		{
			key: "id",
			label: "Account ID",
			targetField: "id",
			required: true,
			sourceAliases: ["Account Identifier", "External ID"],
		},
		{
			key: "amount",
			label: "Amount",
			targetField: "amount",
			format: {
				kind: "number",
				decimalSeparator: ",",
				thousandsSeparator: ".",
			},
		},
	],
});

const sourceBatch = createRecordBatch([
	{ "Account Identifier": "acc-1", Amount: "1.234,50" },
]);

const preview = previewImport(
	createImportPlan({
		source: { kind: "memory", batch: sourceBatch, format: "csv" },
		target: { kind: "memory", format: "json" },
		schema: AccountImportSchema,
		sourceBatch,
		template,
	})
);

Template resolution uses exact headers, aliases, normalized labels, and SchemaModel fallback inference. Explicit mappings still override template mappings. defineImportTemplate remains available as a backwards-compatible import-specific alias.

Governed ecosystem projections

@lssm-tech/lib.data-exchange-core/governed defines the portable contract for sharing a minimized projection between LSSM products. A catalog entry declares the source, schema, exact field paths, provenance, classification, and storage region. A separate grant binds one subject and optional tenant to one audience, purpose, lawful basis, field allowlist, expiry, retention horizon, region set, revision, and revocation watermark.

The access request and decision schemas are deliberately payload-free. They reject identity secrets and require denied decisions to disclose no field paths. Revocation events and consumer acknowledgements support deterministic reconciliation, while the privacy projection exposes who receives which fields and why without exposing the shared values.

A source product may publish an immutable sharing offer with an exact grantee, field subset, purpose code, legal-basis reference, EN/FR/ES consent copy, residency, expiry, and retention limit. User issuance accepts only the published offer id and locale; the resulting grant binds the projection schema version and preserves the exact localized consent text, version, and timestamp.

@lssm-tech/lib.data-exchange-core/governed/privacy-commands holds the pure privacy-rights transitions hosts compose: resolvePrivacyRightsProcessor routes export to the catalog source and erasure to the materialized consumer, createPrivacyRevocation derives the next revision/watermark revocation event and its payload-free pending delivery to the grant consumer, and resetFailedRightsJob requeues a failed rights job without stale terminal evidence. Event and delivery ids come from an injected deterministic opaqueId function so the package stays free of node:crypto.

This is not a shared raw database. Products keep their own persistence and local authorization; only a purpose-bound projection crosses the product boundary.

Receiving products persist a governed copy only through GovernedProductMaterialization: an exact pairwise subject, application, grant, projection/schema version, purpose, lawful-basis evidence, field allowlist, receiver region, grant expiry, retention horizon, revocation watermark, receiver key reference, and encrypted envelope. A separate payload-free authorization must match every one of those facts and the encryption algorithm exactly. The schema rejects plaintext, source subjects, canonical identity, credentials, leases, and payload fields. Product recovery and materialization receipts return evidence only; they never return the subject or shared values to the central identity authority.

Exact native rights and revocation subjects

GovernedProcessorSubjectRefSchema accepts 1–200 opaque ASCII bytes: the legacy governed subject alphabet plus native AuthOS Base64 + and =. Rights queue subjectRef, rights dispatch processorSubjectRef, revocation delivery subjectRef, and revocation dispatch consumerSubjectRef preserve those exact bytes. Whitespace (including a final newline), controls, Unicode confusables and percent encoding are rejected. The schema does not trim, normalize, decode, hash or create an alias. Its generated JSON Schema retains the same pattern.

Exact top-level field projection and replay recheck

projectExactTopLevelFields enforces exact top-level Object.hasOwn(record, field) lookup without traversing JSON dot paths or prototype properties, and refuses nested objects or non-plain source records so embedded private blobs can never cross a projection boundary. extractTopLevelGovernedFieldPaths derives top-level fieldPaths from flat Zod object schemas. GovernedProjectionReplayRequestSchema bounds cached-replay current-authority rechecks against a prior allowed decision.

Relationships

THIS PACKAGElib.data-exchange-core50 import paths

Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.

3 declarations

Declared capabilities

Lib Data Exchange Core

SchemaModel-first core primitives for data import/export and mapping

Scripts

  • publish:pkgbun publish --tolerate-republish --ignore-scripts --verbose
  • publish:pkg:canarybun publish:pkg --tag canary
  • buildcontractspec-bun-build build
  • build:bundlecontractspec-bun-build transpile
  • build:typescontractspec-bun-build types
  • devcontractspec-bun-build dev
  • cleanrimraf dist .turbo
  • lintbun lint:fix
  • lint:fixnode ../../../../scripts/biome.cjs check --write --unsafe --only=nursery/useSortedClasses . && node ../../../../scripts/biome.cjs check --write .
  • lint:checknode ../../../../scripts/biome.cjs check .
  • prebuildcontractspec-bun-build prebuild
  • typechecktsgo --noEmit
  • testbun test