@x12i/memorix-writer 1.0.0

package/README.md

@@ -0,0 +1,145 @@
+# @x12i/memorix-writer
+
+Descriptor-driven write layer for Memorix. Turns Catalox write descriptors, entity descriptors, validated input, and optional Markdown/text content into Memorix records and external content object pointers.
+
+Shared MongoDB naming rules: [docs/MEMORIX-DATABASE-CONVENTIONS.md](./docs/MEMORIX-DATABASE-CONVENTIONS.md).
+
+## Architecture
+
+- **Catalox** — `memorix-write-descriptors`, `memorix-entity-descriptors`
+- **MongoDB** — built-in `MemorixDataTier` + collection-name CRUD (no separate `@x12i/memorix` package)
+- **@x12i/memorix-descriptors** — shared catalog ids and descriptor validation (aligned with retrieval)
+- **@x12i/helpers** — GCS/S3 content uploads (`contentWriters.gcs` / `contentWriters.s3`)
+- **@x12i/memorix-retrieval** (optional) — `returnMode: "retrievalItem"`
+
+## Quick start
+
+Set `MONGO_URI` and provide a Catalox client. Database names, entity vs event routing, and collection resolution are handled internally.
+
+```bash
+MONGO_URI=mongodb://localhost:27017
+```
+
+```typescript
+import {
+  createMemorixWriterFromEnv,
+  writeMemorixRecord,
+} from "@x12i/memorix-writer";
+
+const writer = await createMemorixWriterFromEnv({
+  catalox: boundCatalox, // must implement getCatalogItem(appId, catalogId, itemId)
+  contentWriters: {
+    gcs: myGcsUploader, // uploadObject({ key, body, contentType })
+  },
+});
+
+const result = await writeMemorixRecord(writer, {
+  writeDescriptorId: "asset-analysis-write",
+  entityId: "10.150.68.31",
+  input: { riskLevel: "HIGH", summary: "..." },
+  content: {
+    fields: {
+      investigationReport: { body: "# Report\n...", format: "markdown" },
+    },
+  },
+});
+
+await writer.close?.();
+```
+
+Lazy connect (same env, no upfront `await`):
+
+```typescript
+import { createMemorixWriter, writeMemorixRecord } from "@x12i/memorix-writer";
+
+const writer = createMemorixWriter({ catalox: boundCatalox });
+// connects to Mongo on first write using MONGO_URI
+```
+
+## Advanced (optional)
+
+Override defaults only when you need to:
+
+| Option | Purpose |
+|--------|---------|
+| `MEMORIX_ENTITIES_DB` / `MEMORIX_EVENTS_DB` | Non-default database names |
+| `MEMORIX_ENTITIES_COLLECTION_*` / `MEMORIX_EVENTS_COLLECTION_*` | Per-type collection overrides |
+| `memorix` | Inject a pre-configured `MemorixDataTier` instead of built-in Mongo connect |
+| `mongo` | Reuse an existing `MongoClient` |
+| `processEnv` | Custom env object (default: `process.env`) |
+
+## Collection resolution
+
+Writes target **`memorix-entities`** or **`memorix-events`** based on the write descriptor (`target.kind`, defaulting from `identity.idField`). Database names follow [Memorix Database Conventions](./docs/MEMORIX-DATABASE-CONVENTIONS.md) (`MEMORIX_ENTITIES_DB`, `MEMORIX_EVENTS_DB`, …).
+
+Collection name resolution order:
+
+1. Explicit override (API/code parameter)
+2. Write descriptor `target.targetCollection`
+3. Entity descriptor content type `collection`
+4. `MEMORIX_ENTITIES_COLLECTION_*` / `MEMORIX_EVENTS_COLLECTION_*` env vars
+5. Write descriptor `target.targetCollectionCandidates`
+6. Content-type slice `{collectionPrefix}-{postfix}` (e.g. `assets-analysis`)
+7. Built-in defaults for known `entityType` values
+8. Heuristic (`<entityType>` or `<entityType>-events`)
+9. Verify the collection exists in the target database (skipped for `dryRun` / `validateOnly`)
+
+For content-type slices, step 6 runs before canonical entity defaults so `assets` + `analysis` still resolves to `assets-analysis` unless overridden explicitly.
+
+## Operations
+
+| Operation | Default | Notes |
+|-----------|---------|--------|
+| `add` | yes | Always inserts a new record |
+| `upsert` | descriptor-gated | Requires `conflict.matchBy` |
+| `patch` | descriptor-gated | Updates writable fields on existing row |
+| `replace` | descriptor-gated | Full replace |
+
+## Catalox seeds
+
+Validate the example write descriptor seed:
+
+```bash
+npm run catalox:seed:write-descriptors:validate
+```
+
+Seed file: [`catalox-seeds/memorix-write-descriptors.manifest.json`](catalox-seeds/memorix-write-descriptors.manifest.json)
+
+## Acceptance criteria
+
+| ID | Status |
+|----|--------|
+| AC-1 | Generic descriptor-driven write |
+| AC-2 | Prefix/postfix collection resolution |
+| AC-3 | Identity: exactly one of `entityId` / `eventId` |
+| AC-4 | Default operation `add` |
+| AC-5 | Upsert only when allowed |
+| AC-6 | Patch only when allowed |
+| AC-7 | Writable field allowlist / unknown fields |
+| AC-8 | Required fields |
+| AC-9 | Content body → object storage + pointer |
+| AC-10 | Existing content pointer |
+| AC-11 | Content maxBytes |
+| AC-12 | No secrets in descriptors |
+| AC-13 | Idempotency |
+| AC-14 | `dryRun` |
+| AC-15 | `validateOnly` |
+| AC-16 | Retrieval delegated when configured |
+
+## Development
+
+```bash
+npm run build
+npm test
+```
+
+Mongo collection I/O is built in (`insertMemorixCollectionDocument`, etc. under `src/mongo/`).
+
+## Publish
+
+```bash
+npm run build
+npm publish --access public
+```
+
+Or from the x12i workspace root: `./scripts/publish-memorix-packages.sh`

package/catalox-seeds/memorix-write-descriptors.manifest.json

@@ -0,0 +1,164 @@
+{
+  "presetVersion": 1,
+  "id": "memorix-write-descriptors",
+  "name": "Memorix write descriptors",
+  "description": "Write descriptors for @x12i/memorix-writer (example: asset analysis write).",
+  "catalogs": [
+    {
+      "catalogId": "memorix-write-descriptors",
+      "name": "Memorix write descriptors",
+      "catalogType": "memorix",
+      "sourceMode": "native",
+      "native": {
+        "itemIdField": "id",
+        "titleField": "title"
+      }
+    }
+  ],
+  "descriptors": [
+    {
+      "catalogId": "memorix-write-descriptors",
+      "descriptorVersion": "1",
+      "mode": "replace",
+      "descriptor": {
+        "catalogId": "memorix-write-descriptors",
+        "label": "Memorix write descriptors",
+        "sourceMode": "native",
+        "status": "active",
+        "capabilities": {
+          "canList": true,
+          "canGet": true,
+          "canCreate": true,
+          "canEdit": true,
+          "canDelete": true,
+          "canImport": true,
+          "canExport": true,
+          "canSync": false,
+          "canValidate": true,
+          "canViewReferences": true
+        },
+        "queryableFields": [
+          {
+            "key": "id",
+            "label": "Id",
+            "type": "string",
+            "indexed": true,
+            "filterable": true,
+            "listVisible": true,
+            "detailVisible": true
+          },
+          {
+            "key": "entity",
+            "label": "Entity",
+            "type": "string",
+            "indexed": true,
+            "filterable": true,
+            "listVisible": true,
+            "detailVisible": true
+          },
+          {
+            "key": "title",
+            "label": "Title",
+            "type": "string",
+            "indexed": true,
+            "filterable": true,
+            "listVisible": true,
+            "detailVisible": true
+          }
+        ],
+        "identity": {
+          "itemIdStrategy": "natural",
+          "itemIdField": "id",
+          "titleField": "title"
+        }
+      }
+    }
+  ],
+  "bindings": [
+    {
+      "appId": "memorix",
+      "catalogId": "memorix-write-descriptors",
+      "access": {
+        "canRead": true,
+        "canWrite": true
+      }
+    }
+  ],
+  "items": [
+    {
+      "catalogId": "memorix-write-descriptors",
+      "data": {
+        "id": "asset-analysis-write",
+        "entity": "assets",
+        "title": "Write Asset Analysis",
+        "target": { "contentType": "analysis" },
+        "identity": {
+          "idField": "entityId",
+          "requireExistingCanonical": true,
+          "createCanonicalIfMissing": false
+        },
+        "operations": {
+          "allowed": ["add"],
+          "default": "add"
+        },
+        "fields": {
+          "riskLevel": {
+            "label": "Risk Level",
+            "inputPath": "riskLevel",
+            "target": { "path": "data.riskLevel" },
+            "required": true,
+            "writable": true,
+            "valueType": "enum",
+            "enumValues": ["LOW", "MEDIUM", "HIGH", "CRITICAL"]
+          },
+          "summary": {
+            "label": "Summary",
+            "inputPath": "summary",
+            "target": { "path": "data.summary" },
+            "writable": true,
+            "valueType": "string"
+          },
+          "investigationReport": {
+            "label": "Investigation Report",
+            "inputPath": "investigationReport",
+            "target": { "path": "data.investigationReport" },
+            "writable": true,
+            "valueType": "content",
+            "content": {
+              "enabled": true,
+              "objectType": "memorix-content-object",
+              "acceptBody": true,
+              "acceptPointer": true,
+              "format": "markdown",
+              "maxBytes": 5242880,
+              "contentKeyTemplate": "{{entity}}/{{contentType}}/{{entityId}}/{{recordId}}/{{field}}.md",
+              "generatePreview": true,
+              "previewMaxChars": 500,
+              "computeMetadata": true,
+              "storage": {
+                "provider": "gcs",
+                "bucket": "memorix-content",
+                "prefix": "assets"
+              }
+            }
+          }
+        },
+        "content": {
+          "allowed": true,
+          "allowedFields": ["investigationReport"],
+          "generatePreview": true,
+          "previewMaxChars": 500,
+          "computeMetadata": true,
+          "maxBytes": 5242880
+        },
+        "validation": {
+          "rejectUnknownFields": true,
+          "requireAtLeastOneWritableField": true
+        },
+        "return": {
+          "defaultMode": "summary"
+        }
+      }
+    }
+  ]
+}

package/dist/client/create-client.d.ts

@@ -0,0 +1,3 @@
+import type { CreateMemorixWriterOptions, MemorixWriterClient } from "./types.js";
+export declare function createMemorixWriter(options: CreateMemorixWriterOptions): MemorixWriterClient;
+//# sourceMappingURL=create-client.d.ts.map

package/dist/client/create-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-client.d.ts","sourceRoot":"","sources":["../../src/client/create-client.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EACV,0BAA0B,EAC1B,mBAAmB,EAEpB,MAAM,YAAY,CAAC;AAsEpB,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,0BAA0B,GAClC,mBAAmB,CAyBrB"}

package/dist/client/create-client.js

@@ -0,0 +1,81 @@
+import { createMemorixDataTier, } from "../mongo/tier.js";
+import { DEFAULT_CANONICAL_CONTENT_TYPE, DEFAULT_CONTENT_KEY_TEMPLATE, DEFAULT_CONTENT_MAX_BYTES, DEFAULT_DATA_ROOT, DEFAULT_EFFECTIVE_DATE_PATH, DEFAULT_MEMORIX_APP_ID, DEFAULT_MEMORIX_METADATA_PATH, } from "../constants.js";
+import { connectMemorixMongo } from "../mongo/connection.js";
+import { resolveMemorixDbName } from "../mongo/env.js";
+function resolveDefaults(partial) {
+    return {
+        canonicalContentType: partial?.canonicalContentType ?? DEFAULT_CANONICAL_CONTENT_TYPE,
+        dataRoot: partial?.dataRoot ?? DEFAULT_DATA_ROOT,
+        effectiveDatePath: partial?.effectiveDatePath ?? DEFAULT_EFFECTIVE_DATE_PATH,
+        contentMaxBytes: partial?.contentMaxBytes ?? DEFAULT_CONTENT_MAX_BYTES,
+        packageMaxContentBytes: partial?.packageMaxContentBytes,
+        defaultWriteMode: partial?.defaultWriteMode ?? "add",
+        defaultConflictBehavior: partial?.defaultConflictBehavior ?? "fail",
+        defaultReturnMode: partial?.defaultReturnMode ?? "summary",
+        contentKeyTemplate: partial?.contentKeyTemplate ?? DEFAULT_CONTENT_KEY_TEMPLATE,
+        memorixMetadataPath: partial?.memorixMetadataPath ?? DEFAULT_MEMORIX_METADATA_PATH,
+    };
+}
+function createLazyMemorixTierAccess(args) {
+    let tier = args.memorix ?? null;
+    let ownedMongo = !args.memorix && !args.mongo;
+    let mongoClient = args.mongo ?? null;
+    let tierConnect = null;
+    const getMemorixTier = async () => {
+        if (tier?.memorixReady)
+            return tier;
+        if (!tierConnect) {
+            tierConnect = (async () => {
+                if (!mongoClient) {
+                    mongoClient = await connectMemorixMongo(args.processEnv);
+                }
+                const nextTier = createMemorixDataTier({
+                    memorixDb: resolveMemorixDbName("entity", args.processEnv),
+                    processEnv: args.processEnv,
+                    client: mongoClient,
+                });
+                await nextTier.init();
+                tier = nextTier;
+                return nextTier;
+            })();
+        }
+        return tierConnect;
+    };
+    const close = async () => {
+        if (tier) {
+            await tier.close();
+            tier = null;
+            tierConnect = null;
+        }
+        if (ownedMongo && mongoClient) {
+            await mongoClient.close();
+            mongoClient = null;
+        }
+    };
+    return { getMemorixTier, close };
+}
+export function createMemorixWriter(options) {
+    if (!options.catalox) {
+        throw new Error("MemorixWriter: catalox client is required");
+    }
+    const processEnv = options.processEnv ?? process.env;
+    const tierAccess = createLazyMemorixTierAccess({
+        memorix: options.memorix,
+        mongo: options.mongo,
+        processEnv,
+    });
+    return {
+        appId: options.appId ?? DEFAULT_MEMORIX_APP_ID,
+        catalox: options.catalox,
+        memorix: options.memorix,
+        retrieval: options.retrieval,
+        contentWriters: options.contentWriters ?? {},
+        defaults: resolveDefaults(options.defaults),
+        getMemorixTier: async () => {
+            const tier = await tierAccess.getMemorixTier();
+            return tier;
+        },
+        close: tierAccess.close,
+    };
+}
+//# sourceMappingURL=create-client.js.map

package/dist/client/create-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-client.js","sourceRoot":"","sources":["../../src/client/create-client.ts"],"names":[],"mappings":"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"}

package/dist/client/create-from-env.d.ts

@@ -0,0 +1,3 @@
+import type { CreateMemorixWriterFromEnvOptions, MemorixWriterClient } from "./types.js";
+export declare function createMemorixWriterFromEnv(options: CreateMemorixWriterFromEnvOptions): Promise<MemorixWriterClient>;
+//# sourceMappingURL=create-from-env.d.ts.map

package/dist/client/create-from-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-from-env.d.ts","sourceRoot":"","sources":["../../src/client/create-from-env.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,iCAAiC,EACjC,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAEpB,wBAAsB,0BAA0B,CAC9C,OAAO,EAAE,iCAAiC,GACzC,OAAO,CAAC,mBAAmB,CAAC,CAgB9B"}

package/dist/client/create-from-env.js

@@ -0,0 +1,21 @@
+import { createMemorixDataTier } from "../mongo/tier.js";
+import { connectMemorixMongo } from "../mongo/connection.js";
+import { resolveMemorixDbName } from "../mongo/env.js";
+import { createMemorixWriter } from "./create-client.js";
+export async function createMemorixWriterFromEnv(options) {
+    const processEnv = options.processEnv ?? process.env;
+    const mongo = options.mongo ?? (await connectMemorixMongo(processEnv));
+    const tier = createMemorixDataTier({
+        memorixDb: resolveMemorixDbName("entity", processEnv),
+        processEnv,
+        client: mongo,
+    });
+    await tier.init();
+    return createMemorixWriter({
+        ...options,
+        memorix: tier,
+        processEnv,
+        mongo,
+    });
+}
+//# sourceMappingURL=create-from-env.js.map

package/dist/client/create-from-env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-from-env.js","sourceRoot":"","sources":["../../src/client/create-from-env.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAMzD,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC9C,OAA0C;IAE1C,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,OAAO,CAAC,GAAG,CAAC;IACrD,MAAM,KAAK,GACT,OAAO,CAAC,KAAK,IAAI,CAAC,MAAM,mBAAmB,CAAC,UAAU,CAAC,CAAC,CAAC;IAC3D,MAAM,IAAI,GAAG,qBAAqB,CAAC;QACjC,SAAS,EAAE,oBAAoB,CAAC,QAAQ,EAAE,UAAU,CAAC;QACrD,UAAU;QACV,MAAM,EAAE,KAAc;KACvB,CAAC,CAAC;IACH,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;IAClB,OAAO,mBAAmB,CAAC;QACzB,GAAG,OAAO;QACV,OAAO,EAAE,IAAI;QACb,UAAU;QACV,KAAK;KACN,CAAC,CAAC;AACL,CAAC"}

package/dist/client/ensure-tier.d.ts

@@ -0,0 +1,3 @@
+import type { MemorixWriterClient } from "./types.js";
+export declare function getWriterMemorixTier(client: MemorixWriterClient): Promise<import("../mongo/tier.js").MemorixDataTier>;
+//# sourceMappingURL=ensure-tier.d.ts.map

package/dist/client/ensure-tier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensure-tier.d.ts","sourceRoot":"","sources":["../../src/client/ensure-tier.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,mBAAmB,uDAErE"}

package/dist/client/ensure-tier.js

@@ -0,0 +1,4 @@
+export async function getWriterMemorixTier(client) {
+    return client.getMemorixTier();
+}
+//# sourceMappingURL=ensure-tier.js.map

package/dist/client/ensure-tier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensure-tier.js","sourceRoot":"","sources":["../../src/client/ensure-tier.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,MAA2B;IACpE,OAAO,MAAM,CAAC,cAAc,EAAE,CAAC;AACjC,CAAC"}

package/dist/client/types.d.ts

@@ -0,0 +1,165 @@
+import type { MongoClient } from "mongodb";
+import type { MemorixDataTier } from "../mongo/tier.js";
+import type { MemorixContentObject } from "../descriptors/entity-descriptor-types.js";
+import type { MemorixWriteIssue } from "../errors/issues.js";
+export type CataloxLike = {
+    getCatalogItem(appId: string, catalogId: string, itemId: string): Promise<{
+        data: Record<string, unknown>;
+    } | null>;
+};
+export type MemorixObjectWriterLike = {
+    uploadObject(args: {
+        key: string;
+        body: string | Uint8Array;
+        contentType?: string;
+    }): Promise<void>;
+    deleteObject?(args: {
+        key: string;
+    }): Promise<void>;
+};
+export type MemorixContentWriterRegistry = {
+    gcs?: MemorixObjectWriterLike;
+    s3?: MemorixObjectWriterLike;
+};
+export type MemorixRetrievalClient = {
+    fetchMemorixItem(args: {
+        itemDescriptorId: string;
+        entityId?: string;
+        eventId?: string;
+        recordId?: string;
+    }): Promise<Record<string, unknown>>;
+};
+export type MemorixWriterDefaults = {
+    canonicalContentType: string;
+    dataRoot: string;
+    effectiveDatePath: string;
+    contentMaxBytes: number;
+    packageMaxContentBytes?: number;
+    defaultWriteMode: "add" | "upsert" | "patch" | "replace";
+    defaultConflictBehavior: "fail" | "skip" | "append";
+    defaultReturnMode: "summary" | "record" | "retrievalItem";
+    contentKeyTemplate: string;
+    memorixMetadataPath: string;
+};
+export type CreateMemorixWriterOptions = {
+    appId?: string;
+    catalox: CataloxLike;
+    /** Advanced: inject Memorix tier. Omit to connect from `MONGO_URI` on first write. */
+    memorix?: MemorixDataTier;
+    /** Advanced: reuse an existing MongoClient (simple mode lazy/eager connect). */
+    mongo?: MongoClient;
+    processEnv?: NodeJS.ProcessEnv;
+    retrieval?: MemorixRetrievalClient;
+    contentWriters?: MemorixContentWriterRegistry;
+    defaults?: Partial<MemorixWriterDefaults>;
+};
+export type CreateMemorixWriterFromEnvOptions = Omit<CreateMemorixWriterOptions, "memorix">;
+export type MemorixWriterClient = {
+    appId: string;
+    catalox: CataloxLike;
+    /** Resolved tier (available after `getMemorixTier()` or first write). */
+    memorix?: MemorixDataTier;
+    retrieval?: MemorixRetrievalClient;
+    contentWriters: MemorixContentWriterRegistry;
+    defaults: MemorixWriterDefaults;
+    /** Internal: lazy Mongo tier from env (simple mode). */
+    getMemorixTier: () => Promise<MemorixDataTier>;
+    close?: () => Promise<void>;
+};
+export type WriteMemorixRecordRequest = {
+    writeDescriptorId: string;
+    operation?: "add" | "upsert" | "patch" | "replace";
+    entityId?: string;
+    eventId?: string;
+    input: Record<string, unknown>;
+    content?: {
+        fields?: Record<string, {
+            body: string;
+            format?: "markdown" | "text";
+            filename?: string;
+            metadata?: Record<string, unknown>;
+        } | MemorixContentObject>;
+    };
+    source?: {
+        system?: string;
+        connector?: string;
+        runId?: string;
+        jobId?: string;
+        recordId?: string;
+    };
+    actor?: {
+        type: "user" | "service" | "agent" | "system";
+        id?: string;
+        name?: string;
+    };
+    options?: {
+        dryRun?: boolean;
+        validateOnly?: boolean;
+        idempotencyKey?: string;
+        correlationId?: string;
+        returnMode?: "summary" | "record" | "retrievalItem";
+    };
+};
+export type WriteMemorixRecordResponse = {
+    ok: boolean;
+    writeDescriptorId: string;
+    entity: string;
+    contentType: string;
+    collection: string;
+    operation: "add" | "upsert" | "patch" | "replace";
+    action: "inserted" | "updated" | "patched" | "replaced" | "skipped" | "deduplicated" | "validated";
+    entityId?: string;
+    eventId?: string;
+    recordId?: string;
+    idempotencyKey?: string;
+    writtenAt?: string;
+    contentObjects?: Record<string, {
+        contentKey: string;
+        sizeBytes?: number;
+        format?: "markdown" | "text";
+        written: boolean;
+    }>;
+    record?: Record<string, unknown>;
+    retrievalItem?: Record<string, unknown>;
+    issues?: MemorixWriteIssue[];
+};
+export type WriteMemorixRecordsRequest = {
+    writeDescriptorId: string;
+    operation?: "add" | "upsert" | "patch" | "replace";
+    records: Array<{
+        entityId?: string;
+        eventId?: string;
+        input: Record<string, unknown>;
+        content?: WriteMemorixRecordRequest["content"];
+        source?: WriteMemorixRecordRequest["source"];
+        actor?: WriteMemorixRecordRequest["actor"];
+        options?: Pick<NonNullable<WriteMemorixRecordRequest["options"]>, "idempotencyKey" | "correlationId">;
+    }>;
+    options?: {
+        dryRun?: boolean;
+        validateOnly?: boolean;
+        continueOnError?: boolean;
+        returnMode?: "summary" | "record";
+    };
+};
+export type WriteMemorixRecordsResponse = {
+    ok: boolean;
+    writeDescriptorId: string;
+    entity: string;
+    contentType: string;
+    count: {
+        requested: number;
+        inserted: number;
+        updated: number;
+        skipped: number;
+        failed: number;
+    };
+    results: WriteMemorixRecordResponse[];
+    issues?: MemorixWriteIssue[];
+};
+export type ValidateMemorixWriteResponse = {
+    ok: boolean;
+    issues?: MemorixWriteIssue[];
+    plannedRecord?: Record<string, unknown>;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/client/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/client/types.ts"],"names":[],"mappings":"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"}

package/dist/client/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/client/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/client/types.ts"],"names":[],"mappings":""}

package/dist/constants.d.ts

@@ -0,0 +1,13 @@
+export declare const DEFAULT_MEMORIX_APP_ID = "memorix";
+export declare const MEMORIX_WRITE_DESCRIPTORS_CATALOG_ID = "memorix-write-descriptors";
+export declare const MEMORIX_ENTITY_DESCRIPTORS_CATALOG_ID = "memorix-entity-descriptors";
+export declare const DEFAULT_CANONICAL_CONTENT_TYPE = "snapshots";
+export declare const DEFAULT_DATA_ROOT = "data";
+export declare const DEFAULT_EFFECTIVE_DATE_PATH = "modifiedAt";
+export declare const DEFAULT_CONTENT_MAX_BYTES: number;
+export declare const DEFAULT_MEMORIX_METADATA_PATH = "_memorix";
+export declare const DEFAULT_AUDIT_PATH = "_memorix.audit";
+export declare const DEFAULT_IDEMPOTENCY_KEY_PATH = "_memorix.idempotencyKey";
+export declare const DEFAULT_PAYLOAD_HASH_PATH = "_memorix.payloadHash";
+export declare const DEFAULT_CONTENT_KEY_TEMPLATE = "{{entity}}/{{contentType}}/{{id}}/{{recordId}}/{{field}}.md";
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,sBAAsB,YAAY,CAAC;AAEhD,eAAO,MAAM,oCAAoC,8BAA8B,CAAC;AAChF,eAAO,MAAM,qCAAqC,+BAA+B,CAAC;AAElF,eAAO,MAAM,8BAA8B,cAAc,CAAC;AAC1D,eAAO,MAAM,iBAAiB,SAAS,CAAC;AACxC,eAAO,MAAM,2BAA2B,eAAe,CAAC;AACxD,eAAO,MAAM,yBAAyB,QAAkB,CAAC;AACzD,eAAO,MAAM,6BAA6B,aAAa,CAAC;AACxD,eAAO,MAAM,kBAAkB,mBAAmB,CAAC;AACnD,eAAO,MAAM,4BAA4B,4BAA4B,CAAC;AACtE,eAAO,MAAM,yBAAyB,yBAAyB,CAAC;AAEhE,eAAO,MAAM,4BAA4B,gEACsB,CAAC"}