@x12i/memorix-descriptors 1.5.0 → 1.7.0

package/dist/validation/write-descriptor-validation.js

@@ -0,0 +1,120 @@
+import { resolveMemorixCollectionName, } from "../collections/collection-name.js";
+import { DescriptorValidationError } from "./errors.js";
+import { validateMemorixEntityDescriptor } from "./descriptor-validation.js";
+const CONTENT_OBJECT_TYPE = "memorix-content-object";
+export function validateMemorixWriteDescriptorShape(raw) {
+    const descriptor = raw;
+    if (!descriptor.id?.trim()) {
+        throw new DescriptorValidationError("INVALID_WRITE_DESCRIPTOR", "write descriptor id is required");
+    }
+    if (!descriptor.entity?.trim()) {
+        throw new DescriptorValidationError("INVALID_WRITE_DESCRIPTOR", "write descriptor entity is required");
+    }
+    if (!descriptor.target?.contentType?.trim()) {
+        throw new DescriptorValidationError("INVALID_WRITE_DESCRIPTOR", "write descriptor target.contentType is required");
+    }
+    if (!descriptor.operations?.allowed?.length) {
+        throw new DescriptorValidationError("INVALID_WRITE_DESCRIPTOR", "write descriptor operations.allowed must be non-empty");
+    }
+    if (!descriptor.operations.allowed.includes(descriptor.operations.default)) {
+        throw new DescriptorValidationError("INVALID_WRITE_DESCRIPTOR", "write descriptor operations.default must be in operations.allowed");
+    }
+    if (!descriptor.fields || Object.keys(descriptor.fields).length === 0) {
+        throw new DescriptorValidationError("INVALID_WRITE_DESCRIPTOR", "write descriptor must declare at least one field");
+    }
+    for (const [fieldKey, field] of Object.entries(descriptor.fields)) {
+        if (!field.target?.path?.trim()) {
+            throw new DescriptorValidationError("INVALID_WRITE_DESCRIPTOR", `write descriptor field "${fieldKey}" requires target.path`);
+        }
+        if (field.content?.enabled && field.content.objectType !== CONTENT_OBJECT_TYPE) {
+            throw new DescriptorValidationError("INVALID_WRITE_DESCRIPTOR", `write descriptor field "${fieldKey}" content.objectType must be "${CONTENT_OBJECT_TYPE}"`);
+        }
+    }
+    return { ...descriptor, id: descriptor.id.trim(), entity: descriptor.entity.trim() };
+}
+function entityCollections(entity, env) {
+    return Object.keys(entity.contentTypes).map((key) => resolveMemorixCollectionName(entity, key, env));
+}
+export function validateWriteDescriptorAgainstSnapshot(snapshot, descriptor, env = process.env) {
+    const errors = [];
+    const entityRaw = snapshot.entityDescriptors[descriptor.entity];
+    if (!entityRaw) {
+        errors.push({
+            code: "UNKNOWN_OBJECT_TYPE",
+            message: `Write descriptor entity "${descriptor.entity}" not found in object type catalog`,
+            path: "entity",
+        });
+        return errors;
+    }
+    let entity;
+    try {
+        entity = validateMemorixEntityDescriptor(entityRaw);
+    }
+    catch (err) {
+        errors.push({
+            code: "INVALID_OBJECT_TYPE",
+            message: err instanceof Error ? err.message : String(err),
+            path: "entity",
+        });
+        return errors;
+    }
+    const entitySource = {
+        entityName: entity.entityName,
+        collectionPrefix: entity.collectionPrefix,
+        target: entity.target,
+        contentTypes: Object.fromEntries(Object.entries(entity.contentTypes).map(([key, ct]) => [
+            key,
+            { postfix: ct.postfix, collection: ct.collection },
+        ])),
+    };
+    if (!entity.contentTypes[descriptor.target.contentType]) {
+        errors.push({
+            code: "UNKNOWN_CONTENT_TYPE",
+            message: `Write descriptor target.contentType "${descriptor.target.contentType}" is not declared on object type "${descriptor.entity}"`,
+            path: "target.contentType",
+        });
+    }
+    const collections = entityCollections(entitySource, env);
+    const resolvedCollection = entity.contentTypes[descriptor.target.contentType]
+        ? resolveMemorixCollectionName(entitySource, descriptor.target.contentType, env)
+        : undefined;
+    if (descriptor.target.targetCollection) {
+        if (!collections.includes(descriptor.target.targetCollection)) {
+            errors.push({
+                code: "UNKNOWN_TARGET_COLLECTION",
+                message: `targetCollection "${descriptor.target.targetCollection}" is not declared on object type "${descriptor.entity}"`,
+                path: "target.targetCollection",
+            });
+        }
+    }
+    if (descriptor.target.targetCollectionCandidates?.length) {
+        for (const candidate of descriptor.target.targetCollectionCandidates) {
+            if (!collections.includes(candidate)) {
+                errors.push({
+                    code: "UNKNOWN_TARGET_COLLECTION",
+                    message: `targetCollectionCandidates entry "${candidate}" is not declared on object type "${descriptor.entity}"`,
+                    path: "target.targetCollectionCandidates",
+                });
+            }
+        }
+    }
+    if (resolvedCollection &&
+        descriptor.target.targetCollection &&
+        descriptor.target.targetCollection !== resolvedCollection) {
+        errors.push({
+            code: "TARGET_COLLECTION_MISMATCH",
+            message: `targetCollection "${descriptor.target.targetCollection}" does not match resolved collection "${resolvedCollection}" for content type "${descriptor.target.contentType}"`,
+            path: "target.targetCollection",
+        });
+    }
+    return errors;
+}
+export function validateMemorixWriteDescriptor(raw, snapshot, env = process.env) {
+    const descriptor = validateMemorixWriteDescriptorShape(raw);
+    const snapshotErrors = validateWriteDescriptorAgainstSnapshot(snapshot, descriptor, env);
+    if (snapshotErrors.length > 0) {
+        throw new DescriptorValidationError(snapshotErrors[0].code, snapshotErrors.map((e) => e.message).join("; "));
+    }
+    return descriptor;
+}
+//# sourceMappingURL=write-descriptor-validation.js.map

package/dist/validation/write-descriptor-validation.js.map

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

package/docs/METADATA-RELEASE-CHECKLIST.md

@@ -0,0 +1,44 @@
+# Memorix metadata release checklist (v2 canonical)
+
+After deploying `@x12i/memorix-descriptors` with v2-only runtime loading:
+
+1. **Inspect baseline**
+   ```bash
+   npx tsx scripts/memorix-metadata/inspect.ts
+   ```
+
+2. **Plan canonical reset** (from `CANONICAL_OBJECT_TYPE_SPECS`)
+   ```bash
+   npx tsx scripts/memorix-metadata/plan.ts
+   npx tsx scripts/memorix-metadata/validate-plan.ts
+   ```
+
+3. **Apply** to Catalox (`memorix-object-type-descriptors`, lists, items)
+   ```bash
+   npx tsx scripts/memorix-metadata/apply.ts
+   ```
+
+4. **Verify** — canonical `memorix-object-type-descriptors` must be populated; legacy catalogs must be absent
+
+See also: [../../docs/MIGRATION-V2-CATALOG.md](../../docs/MIGRATION-V2-CATALOG.md)
+
+Legacy catalog `memorix-entity-descriptors` is **not read** at runtime and must be deleted during migration.
+   ```bash
+   npx tsx scripts/memorix-metadata/verify.ts
+   ```
+
+5. **Seed** (optional programmatic apply)
+   ```bash
+   # Uses createCanonicalSeedReadJson() from default-seed-spec
+   npm run catalox:seed:memorix-retrieval:apply
+   ```
+
+6. **Validate**
+   ```bash
+   npm test
+   npm run test:live   # with MONGO_URI + FIRESTORE_LIVE_TESTS=1
+   ```
+
+7. **Explorer** — reload unified inventory; Catalox-first rows should match declared object types.
+
+Legacy catalog `memorix-entity-descriptors` is **not read** at runtime. Canonical validation fails if legacy catalog items remain.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/memorix-descriptors",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "Manage Memorix entity, list, and item descriptors in Catalox",
   "type": "module",
   "main": "./dist/index.js",