@x12i/memorix-associator 1.0.0

package/README.md

@@ -0,0 +1,90 @@
+# @x12i/memorix-associator
+
+Memorix cross-record association materialization — plan, apply, verify, and associated-property metadata.
+
+## Responsibilities
+
+- Build reviewable association plans from declarative rules.
+- Apply idempotent smart merges onto `associated*` snapshot fields.
+- Write technical failure records to `<objectType>-failed` collections.
+- Discover and merge associated snapshot property metadata (`managed`, `discovered`, `both`).
+
+Resolver logic lives in [`@x12i/memorix-resolvers`](../memorix-resolvers/). This package consumes resolver output but does not hard-code resolver types.
+
+## Associated property metadata
+
+### Discovery (FR A)
+
+For `contentType === "snapshots"`, any root-level field whose name starts with `associated` is a valid associated property — including custom names like `associatedRiskScores`.
+
+### Managed metadata (FR B)
+
+Managed descriptor entries describe associated properties intentionally (linked object type, content type, value shape, description).
+
+### Merge contract
+
+`mergeAssociatedPropertyDescriptors()` returns one list with `source: "managed" | "discovered" | "both"`. Managed metadata is authoritative; discovery fills gaps.
+
+### Consumer guidance
+
+```text
+Consumers should prefer Memorix associated-property metadata when available. Until metadata is available, or when reading older/custom records, fall back to the prefix rule: root-level snapshot fields whose names start with "associated".
+
+The well-known names associatedData, associatedInferred, and associatedAnalysis are conventions only.
+```
+
+See `ASSOCIATED_PROPERTY_CONSUMER_GUIDANCE` export.
+
+## API
+
+```typescript
+import { planAssociations, applyAssociations, InMemoryRecordStore } from "@x12i/memorix-associator";
+
+const plan = await planAssociations(request, { store });
+const result = await applyAssociations({ ...request, mode: "apply" }, { store });
+```
+
+## Running associations
+
+**Full guide:** [docs/running-associations.md](docs/running-associations.md)
+
+Quick start:
+
+```bash
+export MONGO_URI="mongodb://…"
+npm run build
+
+# 1. Dry-run — review counts and planFingerprint
+memorix-associator plan \
+  --request examples/minimal-association-request.json \
+  --output temp/plan.json
+
+# 2. Apply — requires the reviewed plan report
+memorix-associator apply \
+  --request examples/minimal-association-request.json \
+  --reviewed-report temp/plan.json
+
+# 3. Verify associated field shapes
+memorix-associator verify --request examples/minimal-association-request.json
+
+# 4. Re-run plan — expect zero associatedItemsWouldAppend when converged
+memorix-associator plan --request examples/minimal-association-request.json
+```
+
+- **Metadata-managed:** use a request whose `rules[].ruleKey` matches `refreshRuleKey` on the entity descriptor's `associatedProperties`.
+- **Ad-hoc:** edit `examples/minimal-association-request.json` (or add your own) with source, target, and join paths.
+- **Re-runs are safe:** apply is append-unique and idempotent; a second plan after apply should show no pending updates.
+
+## CLI reference
+
+```bash
+memorix-associator plan   --request <file.json> [--output <report.json>]
+memorix-associator apply  --request <file.json> --reviewed-report <report.json> [--output <report.json>]
+memorix-associator verify --request <file.json>
+memorix-associator --help
+```
+
+## Related
+
+- [Operational design note](../memorix-schema-api/src/operational/memorix-enrichment-processes.md)
+- [Memorix format — associated buckets](../docs/memorix-format.md)

package/dist/associated-properties/index.d.ts

@@ -0,0 +1,16 @@
+import type { AssociatedPropertyDescriptor, AssociatedPropertyValueShape, DiscoveredAssociatedProperty, ManagedAssociatedProperty } from "../request/schema.js";
+export declare function inferAssociatedValueShape(value: unknown): AssociatedPropertyValueShape;
+export declare function discoverAssociatedPropertiesFromRecord(record: Record<string, unknown>, contentType: string): DiscoveredAssociatedProperty[];
+export declare function discoverAssociatedPropertiesFromRecords(records: Array<Record<string, unknown>>, contentType: string): DiscoveredAssociatedProperty[];
+export declare function mergeAssociatedPropertyDescriptors(input: {
+    managed: ManagedAssociatedProperty[];
+    discovered: DiscoveredAssociatedProperty[];
+}): AssociatedPropertyDescriptor[];
+export declare function suggestManagedMetadataFromRules(rules: Array<{
+    associatedProperty: string;
+    target: {
+        objectType: string;
+        contentType: string;
+    };
+}>): ManagedAssociatedProperty[];
+//# sourceMappingURL=index.d.ts.map

package/dist/associated-properties/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/associated-properties/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,4BAA4B,EAC5B,4BAA4B,EAC5B,4BAA4B,EAC5B,yBAAyB,EAC1B,MAAM,sBAAsB,CAAC;AAG9B,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,4BAA4B,CAKtF;AAED,wBAAgB,sCAAsC,CACpD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,WAAW,EAAE,MAAM,GAClB,4BAA4B,EAAE,CA+BhC;AAED,wBAAgB,uCAAuC,CACrD,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACvC,WAAW,EAAE,MAAM,GAClB,4BAA4B,EAAE,CAgBhC;AAED,wBAAgB,kCAAkC,CAAC,KAAK,EAAE;IACxD,OAAO,EAAE,yBAAyB,EAAE,CAAC;IACrC,UAAU,EAAE,4BAA4B,EAAE,CAAC;CAC5C,GAAG,4BAA4B,EAAE,CA0CjC;AAED,wBAAgB,+BAA+B,CAC7C,KAAK,EAAE,KAAK,CAAC;IAAE,kBAAkB,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC,GAChG,yBAAyB,EAAE,CAiB7B"}

package/dist/associated-properties/index.js

@@ -0,0 +1,118 @@
+import { isAssociatedPropertyName } from "@x12i/memorix-resolvers";
+import { isPlainObject } from "../planning/fingerprint.js";
+export function inferAssociatedValueShape(value) {
+    if (!Array.isArray(value))
+        return "unknown";
+    if (value.length === 0)
+        return "array<unknown>";
+    if (value.every((item) => isPlainObject(item)))
+        return "array<object>";
+    return "array<unknown>";
+}
+export function discoverAssociatedPropertiesFromRecord(record, contentType) {
+    if (contentType !== "snapshots")
+        return [];
+    const discovered = new Map();
+    for (const [name, value] of Object.entries(record)) {
+        if (!isAssociatedPropertyName(name))
+            continue;
+        if (value === undefined)
+            continue;
+        const existing = discovered.get(name);
+        const shape = inferAssociatedValueShape(value);
+        if (existing) {
+            existing.observedCount += 1;
+            if (existing.valueShape === "unknown" && shape !== "unknown") {
+                existing.valueShape = shape;
+            }
+            continue;
+        }
+        discovered.set(name, {
+            name,
+            contentType: "snapshots",
+            kind: "associated",
+            valueShape: shape,
+            managed: false,
+            observedPath: name,
+            observedCount: 1,
+        });
+    }
+    return [...discovered.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+export function discoverAssociatedPropertiesFromRecords(records, contentType) {
+    const merged = new Map();
+    for (const record of records) {
+        for (const entry of discoverAssociatedPropertiesFromRecord(record, contentType)) {
+            const existing = merged.get(entry.name);
+            if (!existing) {
+                merged.set(entry.name, { ...entry });
+                continue;
+            }
+            existing.observedCount += entry.observedCount;
+            if (existing.valueShape === "unknown" && entry.valueShape !== "unknown") {
+                existing.valueShape = entry.valueShape;
+            }
+        }
+    }
+    return [...merged.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+export function mergeAssociatedPropertyDescriptors(input) {
+    const byName = new Map();
+    for (const entry of input.managed) {
+        byName.set(entry.name, {
+            name: entry.name,
+            contentType: entry.contentType,
+            kind: entry.kind,
+            valueShape: entry.valueShape,
+            linkedObjectType: entry.linkedObjectType,
+            linkedContentType: entry.linkedContentType,
+            description: entry.description,
+            managed: true,
+            source: "managed",
+        });
+    }
+    for (const entry of input.discovered) {
+        const existing = byName.get(entry.name);
+        if (!existing) {
+            byName.set(entry.name, {
+                name: entry.name,
+                contentType: entry.contentType,
+                kind: entry.kind,
+                valueShape: entry.valueShape,
+                managed: false,
+                source: "discovered",
+                observedPath: entry.observedPath,
+                observedCount: entry.observedCount,
+            });
+            continue;
+        }
+        existing.source = "both";
+        existing.observedPath = entry.observedPath;
+        existing.observedCount = (existing.observedCount ?? 0) + entry.observedCount;
+        if (!existing.valueShape && entry.valueShape) {
+            existing.valueShape = entry.valueShape;
+        }
+    }
+    return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+export function suggestManagedMetadataFromRules(rules) {
+    const suggestions = new Map();
+    for (const rule of rules) {
+        if (!isAssociatedPropertyName(rule.associatedProperty))
+            continue;
+        if (suggestions.has(rule.associatedProperty))
+            continue;
+        suggestions.set(rule.associatedProperty, {
+            name: rule.associatedProperty,
+            contentType: "snapshots",
+            kind: "associated",
+            valueShape: "array<object>",
+            linkedObjectType: rule.target.objectType,
+            linkedContentType: rule.target.contentType,
+            description: `Associated ${rule.target.objectType} ${rule.target.contentType} payloads`,
+            managed: true,
+        });
+    }
+    return [...suggestions.values()];
+}
+//# sourceMappingURL=index.js.map

package/dist/associated-properties/index.js.map

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

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

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

package/dist/cli.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import path from "node:path";
+import { MongoClient } from "mongodb";
+import { applyAssociations, planAssociations, verifyAssociations } from "./engine.js";
+import { createMongoRecordStore } from "./store/mongo.js";
+function parseArgs(argv) {
+    const args = argv.slice(2);
+    const has = (flag) => args.includes(flag);
+    const valueAfter = (flag) => {
+        const idx = args.indexOf(flag);
+        return idx >= 0 ? args[idx + 1] : undefined;
+    };
+    return {
+        plan: has("plan") || (!has("apply") && !has("verify")),
+        apply: has("apply"),
+        verify: has("verify"),
+        help: has("--help") || has("-h"),
+        requestPath: valueAfter("--request"),
+        reviewedReport: valueAfter("--reviewed-report"),
+        output: valueAfter("--output"),
+    };
+}
+function printHelp() {
+    console.log(`Usage:
+  memorix-associator plan   --request <file.json> [--output <report.json>]
+  memorix-associator apply  --request <file.json> --reviewed-report <report.json> [--output <report.json>]
+  memorix-associator verify --request <file.json>
+
+See docs/running-associations.md for the full plan → review → apply → re-run workflow.`);
+}
+async function loadRequest(requestPath) {
+    const raw = await readFile(requestPath, "utf8");
+    return JSON.parse(raw);
+}
+async function main() {
+    const args = parseArgs(process.argv);
+    if (args.help || !args.requestPath) {
+        printHelp();
+        process.exit(args.help ? 0 : 1);
+    }
+    const request = await loadRequest(path.resolve(args.requestPath));
+    const mongoUri = process.env[request.connection.mongoUriEnv ?? "MONGO_URI"];
+    if (!mongoUri) {
+        throw new Error(`Mongo URI env var not set: ${request.connection.mongoUriEnv ?? "MONGO_URI"}`);
+    }
+    const client = new MongoClient(mongoUri);
+    await client.connect();
+    const store = createMongoRecordStore(client);
+    try {
+        if (args.verify) {
+            const verification = await verifyAssociations(request, { store });
+            console.log(JSON.stringify(verification, null, 2));
+            return;
+        }
+        if (args.apply) {
+            const applyRequest = {
+                ...request,
+                mode: "apply",
+                safety: {
+                    ...request.safety,
+                    reviewedReportPath: args.reviewedReport ?? request.safety.reviewedReportPath,
+                },
+            };
+            const result = await applyAssociations(applyRequest, { store });
+            const outputPath = args.output ?? path.join(process.cwd(), "temp", `associator-apply-${Date.now()}.json`);
+            await mkdir(path.dirname(outputPath), { recursive: true });
+            await writeFile(outputPath, JSON.stringify(result.report, null, 2));
+            console.log(`Applied association plan. Report: ${outputPath}`);
+            return;
+        }
+        const planRequest = { ...request, mode: "dry-run" };
+        const result = await planAssociations(planRequest, { store });
+        const outputPath = args.output ?? path.join(process.cwd(), "temp", `associator-plan-${Date.now()}.json`);
+        await mkdir(path.dirname(outputPath), { recursive: true });
+        await writeFile(outputPath, JSON.stringify(result.report, null, 2));
+        console.log(`Plan fingerprint: ${result.planFingerprint}`);
+        console.log(`Report: ${outputPath}`);
+    }
+    finally {
+        await client.close();
+    }
+}
+main().catch((error) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

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

package/dist/engine.d.ts

@@ -0,0 +1,12 @@
+import { type ResolverRegistry } from "@x12i/memorix-resolvers";
+import type { AssociationApplyResult, AssociationPlanResult, AssociationReport, MemorixAssociationRequest, VerificationReport } from "./request/schema.js";
+import type { RecordStore } from "./store/types.js";
+export type AssociatorOptions = {
+    store: RecordStore;
+    registry?: ResolverRegistry;
+};
+export declare function planAssociations(request: MemorixAssociationRequest, options: AssociatorOptions): Promise<AssociationPlanResult>;
+export declare function applyAssociations(request: MemorixAssociationRequest, options: AssociatorOptions): Promise<AssociationApplyResult>;
+export declare function verifyAssociations(request: MemorixAssociationRequest, options: AssociatorOptions): Promise<VerificationReport>;
+export type { AssociationReport, AssociationPlanResult, AssociationApplyResult };
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,KAAK,EACV,sBAAsB,EACtB,qBAAqB,EACrB,iBAAiB,EACjB,yBAAyB,EACzB,kBAAkB,EAGnB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAGpD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,KAAK,EAAE,WAAW,CAAC;IACnB,QAAQ,CAAC,EAAE,gBAAgB,CAAC;CAC7B,CAAC;AAQF,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,yBAAyB,EAClC,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,qBAAqB,CAAC,CAuBhC;AAED,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,yBAAyB,EAClC,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,sBAAsB,CAAC,CA2GjC;AAED,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,yBAAyB,EAClC,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,kBAAkB,CAAC,CAY7B;AAED,YAAY,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,CAAC"}

package/dist/engine.js

@@ -0,0 +1,115 @@
+import { readFile } from "node:fs/promises";
+import { builtinResolvers, createResolverRegistry, } from "@x12i/memorix-resolvers";
+import { buildAssociationPlan } from "./planning/build-plan.js";
+import { validateAssociationRequest } from "./request/validate.js";
+import { verifyAssociatedShapes } from "./verification/associated-shape.js";
+async function loadReviewedFingerprint(path) {
+    const raw = await readFile(path, "utf8");
+    const parsed = JSON.parse(raw);
+    return parsed.planFingerprint;
+}
+export async function planAssociations(request, options) {
+    validateAssociationRequest(request);
+    const registry = options.registry ?? createResolverRegistry(builtinResolvers);
+    const plan = await buildAssociationPlan(request, {
+        store: options.store,
+        registry,
+        apply: false,
+    });
+    if (request.safety.verifyAfterPlan) {
+        const records = [];
+        for await (const record of options.store.scanRecords(request.source.db, request.source.collection, request.source.filter, request.safety.limit)) {
+            records.push(record);
+        }
+        plan.report.verification = verifyAssociatedShapes(records);
+    }
+    return plan;
+}
+export async function applyAssociations(request, options) {
+    validateAssociationRequest({ ...request, mode: "apply" });
+    if (request.safety.requireReviewedReportForApply) {
+        const expected = request.safety.expectedPlanFingerprint ??
+            (request.safety.reviewedReportPath
+                ? await loadReviewedFingerprint(request.safety.reviewedReportPath)
+                : undefined);
+        if (!expected) {
+            throw new Error("Reviewed plan fingerprint is required for apply");
+        }
+    }
+    const registry = options.registry ?? createResolverRegistry(builtinResolvers);
+    const plan = await buildAssociationPlan(request, {
+        store: options.store,
+        registry,
+        apply: true,
+    });
+    if (request.safety.requireReviewedReportForApply) {
+        const expected = request.safety.expectedPlanFingerprint ??
+            (request.safety.reviewedReportPath
+                ? await loadReviewedFingerprint(request.safety.reviewedReportPath)
+                : undefined);
+        if (expected && expected !== plan.planFingerprint) {
+            throw new Error(`Plan fingerprint mismatch: expected ${expected}, got ${plan.planFingerprint}`);
+        }
+    }
+    const backupManifest = [];
+    if (request.safety.backupBeforeApply && options.store.backupCollection) {
+        backupManifest.push(await options.store.backupCollection(request.source.db, request.source.collection));
+    }
+    const grouped = new Map();
+    for (const update of plan.updates) {
+        const key = `${update.db}/${update.collection}`;
+        const bucket = grouped.get(key) ?? [];
+        bucket.push(update);
+        grouped.set(key, bucket);
+    }
+    for (const [key, updates] of grouped.entries()) {
+        const [db, collection] = key.split("/");
+        const result = await options.store.bulkWrite(db, collection, updates.map((entry) => entry.operation));
+        if (plan.report.sourceCollections[0]) {
+            plan.report.sourceCollections[0].writeErrors += result.errors;
+            plan.report.sourceCollections[0].sourceRecordsUpdated +=
+                updates.length - result.errors;
+        }
+    }
+    if (request.failurePolicy.writeFailures && plan.failures.length > 0) {
+        const failureGroups = new Map();
+        for (const failure of plan.failures) {
+            const key = `${failure.db}/${failure.collection}`;
+            const bucket = failureGroups.get(key) ?? [];
+            bucket.push(failure);
+            failureGroups.set(key, bucket);
+        }
+        for (const [key, failureEntries] of failureGroups.entries()) {
+            const [db, collection] = key.split("/");
+            await options.store.bulkWrite(db, collection, failureEntries.map((entry) => ({
+                updateOne: {
+                    filter: entry.filter,
+                    update: { $set: entry.record },
+                    upsert: true,
+                },
+            })));
+            if (plan.report.sourceCollections[0]) {
+                plan.report.sourceCollections[0].failureRecordsWritten += failureEntries.length;
+            }
+        }
+    }
+    plan.report.mode = "apply";
+    plan.report.backupManifest = backupManifest.length > 0 ? backupManifest : undefined;
+    if (request.safety.verifyAfterApply) {
+        const records = [];
+        for await (const record of options.store.scanRecords(request.source.db, request.source.collection, request.source.filter, request.safety.limit)) {
+            records.push(record);
+        }
+        plan.report.verification = verifyAssociatedShapes(records);
+    }
+    return { report: plan.report, applied: true };
+}
+export async function verifyAssociations(request, options) {
+    validateAssociationRequest(request);
+    const records = [];
+    for await (const record of options.store.scanRecords(request.source.db, request.source.collection, request.source.filter, request.safety.limit)) {
+        records.push(record);
+    }
+    return verifyAssociatedShapes(records);
+}
+//# sourceMappingURL=engine.js.map

package/dist/engine.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { planAssociations, applyAssociations, verifyAssociations, type AssociatorOptions, } from "./engine.js";
+export type { MemorixAssociationRequest, AssociationRule, AssociationReport, AssociationPlanResult, AssociationApplyResult, AssociationFailureRecord, VerificationReport, AssociatedPropertyDescriptor, AssociatedPropertySource, ManagedAssociatedProperty, DiscoveredAssociatedProperty, NormalizationStep, ResolverStepRef, } from "./request/schema.js";
+export { validateAssociationRequest, AssociationRequestValidationError } from "./request/validate.js";
+export { buildPlanFingerprint } from "./planning/fingerprint.js";
+export { buildAssociationPlan } from "./planning/build-plan.js";
+export { discoverAssociatedPropertiesFromRecord, discoverAssociatedPropertiesFromRecords, mergeAssociatedPropertyDescriptors, suggestManagedMetadataFromRules, inferAssociatedValueShape, } from "./associated-properties/index.js";
+export { normalizeAssociatedValue, mergeAssociatedAppendUnique, buildUpdateOperation, } from "./writing/smart-merge.js";
+export { verifyAssociatedShapes, verifyAssociatedShapeOnRecord } from "./verification/associated-shape.js";
+export { InMemoryRecordStore, type RecordStore, type BulkWriteOperation } from "./store/types.js";
+export { createMongoRecordStore } from "./store/mongo.js";
+export declare const ASSOCIATED_PROPERTY_CONSUMER_GUIDANCE = "Consumers should prefer Memorix associated-property metadata when available. In the next Memorix release, associated snapshot properties are expected to be exposed through descriptors/metadata. Until that metadata is available, or when reading older/custom records, consumers should fall back to the prefix rule: root-level snapshot fields whose names start with \"associated\".\n\nThe well-known names associatedData, associatedInferred, and associatedAnalysis are conventions only. The complete set comes from Memorix metadata plus the associated* fallback rule.";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,EAClB,KAAK,iBAAiB,GACvB,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,yBAAyB,EACzB,eAAe,EACf,iBAAiB,EACjB,qBAAqB,EACrB,sBAAsB,EACtB,wBAAwB,EACxB,kBAAkB,EAClB,4BAA4B,EAC5B,wBAAwB,EACxB,yBAAyB,EACzB,4BAA4B,EAC5B,iBAAiB,EACjB,eAAe,GAChB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,0BAA0B,EAAE,iCAAiC,EAAE,MAAM,uBAAuB,CAAC;AACtG,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAEhE,OAAO,EACL,sCAAsC,EACtC,uCAAuC,EACvC,kCAAkC,EAClC,+BAA+B,EAC/B,yBAAyB,GAC1B,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EACL,wBAAwB,EACxB,2BAA2B,EAC3B,oBAAoB,GACrB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,sBAAsB,EAAE,6BAA6B,EAAE,MAAM,oCAAoC,CAAC;AAE3G,OAAO,EAAE,mBAAmB,EAAE,KAAK,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAClG,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAE1D,eAAO,MAAM,qCAAqC,yjBAEqI,CAAC"}

package/dist/index.js

@@ -0,0 +1,13 @@
+export { planAssociations, applyAssociations, verifyAssociations, } from "./engine.js";
+export { validateAssociationRequest, AssociationRequestValidationError } from "./request/validate.js";
+export { buildPlanFingerprint } from "./planning/fingerprint.js";
+export { buildAssociationPlan } from "./planning/build-plan.js";
+export { discoverAssociatedPropertiesFromRecord, discoverAssociatedPropertiesFromRecords, mergeAssociatedPropertyDescriptors, suggestManagedMetadataFromRules, inferAssociatedValueShape, } from "./associated-properties/index.js";
+export { normalizeAssociatedValue, mergeAssociatedAppendUnique, buildUpdateOperation, } from "./writing/smart-merge.js";
+export { verifyAssociatedShapes, verifyAssociatedShapeOnRecord } from "./verification/associated-shape.js";
+export { InMemoryRecordStore } from "./store/types.js";
+export { createMongoRecordStore } from "./store/mongo.js";
+export const ASSOCIATED_PROPERTY_CONSUMER_GUIDANCE = `Consumers should prefer Memorix associated-property metadata when available. In the next Memorix release, associated snapshot properties are expected to be exposed through descriptors/metadata. Until that metadata is available, or when reading older/custom records, consumers should fall back to the prefix rule: root-level snapshot fields whose names start with "associated".
+
+The well-known names associatedData, associatedInferred, and associatedAnalysis are conventions only. The complete set comes from Memorix metadata plus the associated* fallback rule.`;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,GAEnB,MAAM,aAAa,CAAC;AAkBrB,OAAO,EAAE,0BAA0B,EAAE,iCAAiC,EAAE,MAAM,uBAAuB,CAAC;AACtG,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAEhE,OAAO,EACL,sCAAsC,EACtC,uCAAuC,EACvC,kCAAkC,EAClC,+BAA+B,EAC/B,yBAAyB,GAC1B,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EACL,wBAAwB,EACxB,2BAA2B,EAC3B,oBAAoB,GACrB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,sBAAsB,EAAE,6BAA6B,EAAE,MAAM,oCAAoC,CAAC;AAE3G,OAAO,EAAE,mBAAmB,EAA6C,MAAM,kBAAkB,CAAC;AAClG,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAE1D,MAAM,CAAC,MAAM,qCAAqC,GAAG;;uLAEkI,CAAC"}

package/dist/planning/build-plan.d.ts

@@ -0,0 +1,10 @@
+import { type ResolverRegistry } from "@x12i/memorix-resolvers";
+import type { AssociationPlanResult, MemorixAssociationRequest } from "../request/schema.js";
+import type { RecordStore } from "../store/types.js";
+export type BuildPlanOptions = {
+    store: RecordStore;
+    registry?: ResolverRegistry;
+    apply?: boolean;
+};
+export declare function buildAssociationPlan(request: MemorixAssociationRequest, options: BuildPlanOptions): Promise<AssociationPlanResult>;
+//# sourceMappingURL=build-plan.d.ts.map

package/dist/planning/build-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-plan.d.ts","sourceRoot":"","sources":["../../src/planning/build-plan.ts"],"names":[],"mappings":"AAAA,OAAO,EASL,KAAK,gBAAgB,EACtB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,KAAK,EAEV,qBAAqB,EAGrB,yBAAyB,EAI1B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAsJrD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,EAAE,WAAW,CAAC;IACnB,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,yBAAyB,EAClC,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,qBAAqB,CAAC,CAgOhC"}