Root Cause and Fix for Product→Model Generating type="Unknown" (2026-07-09)

Symptom

When the frontend uses useCapabilityCreate to create a Product dialog, the Model relationship is parsed as related_item_type='Unknown',

resulting in illegal AML and multiple 404 errors.

Root Cause Chain (Located and Fixed)

1. In the local server/data/rule_engine.db, the Product→Model row in sciot_relationships has

empty related_item_type and relationship_item_type (a data defect originating from the source JSON).

1. The relTypes map in frontend src/composables/useCapabilityCreate.js line 528, when related_item_type is empty

Fallback to 'Unknown', resulting in rel.related_item_type='Unknown'.

1. Type A/B determination: isTypeB = relationship_type === related_item_type → 'Model'===''=false → proceed with Type A.

Generate.

1. DB persistence pitfall: When server.js starts, if sciot_item_types is empty, it will perform a full re-sync from generated/full-aml-extract.json.

and when the old server process exits, the sqlite-compat exit handler writes the in-memory state (298 types) back to the file,

Override manual fixes. Directly modifying the db file will be overwritten upon server restart/exit.

Fix

• Phase A (Data): sync-rels.mjs directly connects using sqlite-compat (bypassing the db-adapter proxy layer to avoid modification loss due to un-triggered save() debounce/proxy split during rapid exit).

It pulls 600 relationships from the real SCSAI for authoritative backfilling:

• Backfill related_item_type for 314 rows (from 431 empty to 117 empty).
• Insert 311 missing ItemTypes (total types increased from 298 to 609), including Model (is_relationship=1).
• Correct 6 is_relationship flags.
• Switch to db.close() for persistence (export+writeFileSync) and verify independent process reads as 609/117/Model exists.
• Key: After fixing, ensure all server processes are closed before restarting; otherwise, old processes may overwrite changes upon exit.
• Phase B (Frontend Fallback): In useCapabilityCreate.js L528, add a fallback r.name (for Type B relationships, e.g., relationship names like Model, which are ItemType names) to prevent any remaining empty related_item_type from generating Unknown.

ItemType name), avoiding any residual empty related_item_type from generating Unknown.

Verification (real SCSAI)

• After restarting the server, HTTP GET /api/sciot/type-template/Product returns Model→related_item_type=Model;

GET /api/sciot/type-template/Model returns is_relationship=1.

• POST /api/unified/create creates a Product (including Model relationship) and persists it to SCSAI (id=E64D1373472747269E2493B0DA9512B6).

The response body contains type="Unknown": false.

Residual issue:

• Line 117: related_item_type remains empty: local name format does not match the relationship name in SCSAI (mostly z_* subsystem/document hierarchy).

Core 6 business types (Project/Product/Part/Vendor/Customer/ECN) are fully covered.

Tools:

• Retain sync-rels.mjs (can be re-run for fixes); verify-capability-line.mjs (capability line verification).
• All probe/sr diagnostic scripts from this session have been cleaned up.

End-to-end real SCSAI verification (supplemented 2026-07-10).

• Batch check core/common ItemTypes via /api/sciot/type-template: core 6 types (Project/Product/Part/Vendor/Customer/ECN).

Relationships are generally parsed correctly; remaining empty related_item_type is concentrated in self-referencing/symmetric relationships (e.g., Project Part→Part, Sales Order Part→Part).

Their relationship names inherently contain the target type; frontend fallback to r.name already covers this, no Unknown is generated.

• WBS/BOM/Requirement/Specification/Workflow/Made From/BOM Structure returns HTTP 404: These ItemTypes are not local

sciot_item_types (present in SCSAI but not synced locally in meta), is a meta missing issue, not an Unknown problem; WBS Element/Activity2 is normal in the database.

• Key real verification: Using the real frontend contract related_items:[{properties:{name}}] to call POST /api/unified/create to create a Product (including Model relationship),

then directly query the real SCSAI back:

• Creation success=true, response body contains type="Unknown": false
• SCSAI query returns Product(12A695CF64514C4ABF107D79CFACCCA9) containing a node with type="Model"
• Model object is actually created and linked (name=Validation Model_1783613355657)

→ The entire chain (data backfilling + frontend fallback + backend handleCreate type B relationship processing) works completely on the real SCSAI.

• Note: Early tests mistakenly used properties in the request body (instead of related_items:[...]), causing relationships not to be saved to the database and misjudging a server bug for missing relationships;

After switching to the correct contract, relationships are fully saved, proving it is not a server bug.