dzql 0.5.4 → 0.5.6

package/bin/cli.js

@@ -346,6 +346,13 @@ $$;
       writeFileSync(checksumsFile, JSON.stringify(checksums, null, 2), 'utf-8');
 
       console.log(`   ✓ checksums.json`);
+
+      // Write drop-semantics.json (drag-and-drop manifest for canvas UI)
+      if (result.dropSemantics) {
+        const semanticsFile = resolve(options.output, 'drop-semantics.json');
+        writeFileSync(semanticsFile, JSON.stringify(result.dropSemantics, null, 2), 'utf-8');
+        console.log(`   ✓ drop-semantics.json`);
+      }
     }
 
     console.log(`\n✅ Compilation complete!\n`);

package/docs/guides/drop-semantics.md

@@ -0,0 +1,554 @@
+# Drop Semantics
+
+Compile-time manifest describing valid drag-and-drop interactions for canvas UIs.
+
+## Overview
+
+When you compile entity definitions, DZQL generates a `drop-semantics.json` file that describes all valid drag-and-drop relationships between entities. This allows canvas UIs to:
+
+- Know which entities can be dropped onto which targets
+- Display appropriate visual feedback (containment, frames, edges, badges)
+- Execute the correct database operation for each drop
+- Provide unlink/remove functionality
+
+**Key benefit:** The canvas never interprets SQL - it reads a static manifest and knows exactly what connections are valid.
+
+## Quick Start
+
+```bash
+dzql compile entities/domain.sql -o compiled/
+# Outputs:
+#   compiled/entities.sql
+#   compiled/drop-semantics.json   ← Canvas consumes this
+#   compiled/checksums.json
+```
+
+## Output Format
+
+```json
+{
+  "entities": {
+    "tasks": {
+      "droppable_on": {
+        "task_groups": [{
+          "relation": "group_id",
+          "type": "fk",
+          "action": "move",
+          "visual": "containment",
+          "label": "Move to group",
+          "operation": {
+            "method": "save",
+            "entity": "tasks",
+            "params": { "id": "@source.id", "group_id": "@target.id" }
+          },
+          "removable": true,
+          "remove_operation": {
+            "method": "save",
+            "entity": "tasks",
+            "params": { "id": "@source.id", "group_id": null }
+          }
+        }],
+        "users": [{
+          "relation": "assigned_to_user_id",
+          "type": "fk",
+          "action": "move",
+          "visual": "badge",
+          "label": "Move to user",
+          "primary_direction": "accepts",
+          "operation": { ... }
+        }]
+      },
+      "accepts": {
+        "users": [{
+          "relation": "assigned_to_user_id",
+          "type": "fk",
+          "action": "assign",
+          "visual": "badge",
+          "label": "Assign user",
+          "operation": {
+            "method": "save",
+            "entity": "tasks",
+            "params": { "id": "@target.id", "assigned_to_user_id": "@source.id" }
+          },
+          "removable": true,
+          "remove_operation": {
+            "method": "save",
+            "entity": "tasks",
+            "params": { "id": "@target.id", "assigned_to_user_id": null }
+          }
+        }]
+      }
+    }
+  }
+}
+```
+
+### Primary Direction Hint
+
+Some relationships have a natural gesture direction. For example, you typically drop a *user* onto a *task* to assign them, not the other way around. When `primary_direction: "accepts"` is present, the canvas should prioritize the `accepts` entry for UI affordances (drop zones, visual hints).
+
+```json
+{
+  "relation": "assigned_to_user_id",
+  "primary_direction": "accepts"
+}
+```
+
+The compiler infers this from naming patterns like `assigned_to_*`, `created_by_*`, `author`, `owner`, etc.
+
+## Terminology
+
+- **source** - The entity being dragged
+- **target** - The entity being dropped onto
+- **droppable_on** - What THIS entity can be dropped onto
+- **accepts** - What can be dropped onto THIS entity
+
+## Derivation Rules
+
+The compiler derives drop semantics from your schema relationships:
+
+### 1. Foreign Key Relationships
+
+```sql
+-- tasks.group_id REFERENCES task_groups
+```
+
+Generates:
+
+| Perspective | Entry | Meaning |
+|-------------|-------|---------|
+| `tasks.droppable_on.task_groups` | action: "move" | Drag task onto group → update task.group_id |
+| `tasks.accepts.task_groups` | action: "assign" | Drag group onto task → update task.group_id |
+
+### 2. Many-to-Many (Junction Tables)
+
+```sql
+-- post_tags(post_id, tag_id)
+```
+
+Generates:
+
+| Perspective | Entry | Meaning |
+|-------------|-------|---------|
+| `posts.droppable_on.tags` | action: "link" | Drag post onto tag → insert junction |
+| `posts.accepts.tags` | action: "link" | Drag tag onto post → insert junction |
+
+### 3. Self-Referential FK
+
+```sql
+-- categories.parent_id REFERENCES categories
+```
+
+Generates:
+
+| Perspective | Entry | Meaning |
+|-------------|-------|---------|
+| `categories.droppable_on.categories` | action: "reparent" | Drag category onto another → set parent |
+
+### 4. Self-Referential Junction (Dependencies)
+
+```sql
+-- task_dependencies(task_id, depends_on_task_id)
+```
+
+Generates:
+
+| Perspective | Entry | Meaning |
+|-------------|-------|---------|
+| `tasks.droppable_on.tasks` | action: "link", visual: "edge" | Drag task onto task → create dependency edge |
+
+## Visual Types
+
+The `visual` field tells the canvas how to render each relationship:
+
+| Visual | Meaning | When Used |
+|--------|---------|-----------|
+| `containment` | Node moves inside container | Tree structures (folders, groups) |
+| `frame` | Visual bounding box around members | Sets, collections |
+| `edge` | Arrow drawn between nodes | Dependencies, relationships |
+| `badge` | Tag/chip displayed on node | Assignments, references |
+
+### Automatic Visual Inference
+
+The compiler infers visual type using these rules (in order):
+
+1. **Self-referential junction** → `edge`
+2. **Self-referential FK** → `containment`
+3. **Target has self-referential FK** (is a tree) → `containment`
+4. **Name ends with `_groups`, `_folders`, `_categories`** → `containment`
+5. **Name ends with `_sets`, `_collections`, `_lists`** → `frame`
+6. **Default** → `badge`
+
+### Edge Direction
+
+For `edge` visuals (self-referential junctions), the output includes direction:
+
+```json
+{
+  "visual": "edge",
+  "direction": "source_to_target",
+  "self_referential": true
+}
+```
+
+The canvas can use this to draw arrows in the correct direction.
+
+## Remove Operations
+
+Every relationship includes remove semantics:
+
+### FK Relationships
+
+```json
+{
+  "removable": true,
+  "remove_operation": {
+    "method": "save",
+    "entity": "tasks",
+    "params": { "id": "@source.id", "group_id": null }
+  }
+}
+```
+
+Setting the FK to `null` unlinks the relationship.
+
+### Junction Relationships
+
+```json
+{
+  "removable": true,
+  "remove_operation": {
+    "method": "delete",
+    "entity": "post_tags",
+    "params": { "post_id": "@source.id", "tag_id": "@target.id" }
+  }
+}
+```
+
+Deleting the junction record removes the link.
+
+## Composite Primary Keys
+
+Entities with composite primary keys include all key fields in params:
+
+```json
+{
+  "operation": {
+    "method": "save",
+    "entity": "org_items",
+    "params": {
+      "org_id": "@source.org_id",
+      "item_code": "@source.item_code",
+      "category_id": "@target.id"
+    }
+  }
+}
+```
+
+## Canvas Integration
+
+### Checking Valid Drops
+
+```javascript
+function canDrop(sourceEntity, sourceId, targetEntity, targetId) {
+  const semantics = dropSemantics.entities[sourceEntity];
+  if (!semantics) return false;
+  
+  return semantics.droppable_on[targetEntity]?.length > 0;
+}
+```
+
+### Executing Drop
+
+```javascript
+async function executeDrop(ws, sourceEntity, sourceData, targetEntity, targetData, relationIndex = 0) {
+  const action = dropSemantics.entities[sourceEntity].droppable_on[targetEntity][relationIndex];
+  
+  const params = resolveParams(action.operation.params, sourceData, targetData);
+  
+  if (action.operation.method === 'save') {
+    await ws.api.save[action.operation.entity](params);
+  } else if (action.operation.method === 'delete') {
+    await ws.api.delete[action.operation.entity](params);
+  }
+}
+
+function resolveParams(template, sourceData, targetData) {
+  const params = {};
+  for (const [key, value] of Object.entries(template)) {
+    if (typeof value === 'string' && value.startsWith('@source.')) {
+      params[key] = sourceData[value.replace('@source.', '')];
+    } else if (typeof value === 'string' && value.startsWith('@target.')) {
+      params[key] = targetData[value.replace('@target.', '')];
+    } else {
+      params[key] = value;
+    }
+  }
+  return params;
+}
+```
+
+### Getting Visual Hint
+
+```javascript
+function getDropVisual(sourceEntity, targetEntity) {
+  const action = dropSemantics.entities[sourceEntity]?.droppable_on[targetEntity]?.[0];
+  return action?.visual || null;
+}
+```
+
+### Multiple Relations Picker
+
+When multiple relations exist between the same entities (e.g., task→task could be "depends on" or "blocks"), show a picker:
+
+```javascript
+function getDropOptions(sourceEntity, targetEntity) {
+  const actions = dropSemantics.entities[sourceEntity]?.droppable_on[targetEntity] || [];
+  return actions.map((action, index) => ({
+    index,
+    label: action.label,
+    visual: action.visual,
+    relation: action.relation
+  }));
+}
+
+// In Vue component
+<template>
+  <div v-if="dropOptions.length > 1" class="relation-picker">
+    <button 
+      v-for="option in dropOptions" 
+      :key="option.index"
+      @click="executeDrop(option.index)"
+    >
+      {{ option.label }}
+    </button>
+  </div>
+</template>
+```
+
+## Example: Complete Task Management
+
+### Schema
+
+```sql
+-- Groups with hierarchy
+CREATE TABLE task_groups (
+  id SERIAL PRIMARY KEY,
+  name TEXT NOT NULL,
+  parent_id INT REFERENCES task_groups(id)
+);
+
+-- Tasks
+CREATE TABLE tasks (
+  id SERIAL PRIMARY KEY,
+  title TEXT NOT NULL,
+  group_id INT REFERENCES task_groups(id),
+  assigned_to_user_id INT REFERENCES users(id)
+);
+
+-- Task sets (for batch operations)
+CREATE TABLE task_sets (
+  id SERIAL PRIMARY KEY,
+  name TEXT NOT NULL
+);
+
+CREATE TABLE task_set_members (
+  task_id INT REFERENCES tasks(id) ON DELETE CASCADE,
+  set_id INT REFERENCES task_sets(id) ON DELETE CASCADE,
+  PRIMARY KEY (task_id, set_id)
+);
+
+-- Task dependencies
+CREATE TABLE task_dependencies (
+  task_id INT REFERENCES tasks(id) ON DELETE CASCADE,
+  depends_on_task_id INT REFERENCES tasks(id) ON DELETE CASCADE,
+  PRIMARY KEY (task_id, depends_on_task_id)
+);
+
+-- Entity registrations
+SELECT dzql.register_entity('task_groups', 'name', ARRAY['name'],
+  jsonb_build_object('parent', 'task_groups'),
+  false, '{}', '{}',
+  jsonb_build_object('view', ARRAY[]::text[], 'create', ARRAY[]::text[], 
+                     'update', ARRAY[]::text[], 'delete', ARRAY[]::text[])
+);
+
+SELECT dzql.register_entity('tasks', 'title', ARRAY['title'],
+  jsonb_build_object('group', 'task_groups', 'assigned_to_user', 'users'),
+  false, '{}', '{}',
+  jsonb_build_object('view', ARRAY[]::text[], 'create', ARRAY[]::text[], 
+                     'update', ARRAY[]::text[], 'delete', ARRAY[]::text[]),
+  jsonb_build_object(
+    'many_to_many', jsonb_build_object(
+      'sets', jsonb_build_object(
+        'junction_table', 'task_set_members',
+        'local_key', 'task_id',
+        'foreign_key', 'set_id',
+        'target_entity', 'task_sets',
+        'id_field', 'set_ids'
+      ),
+      'dependencies', jsonb_build_object(
+        'junction_table', 'task_dependencies',
+        'local_key', 'task_id',
+        'foreign_key', 'depends_on_task_id',
+        'target_entity', 'tasks',
+        'id_field', 'dependency_ids'
+      )
+    )
+  )
+);
+```
+
+### Generated Drop Semantics
+
+```json
+{
+  "entities": {
+    "task_groups": {
+      "droppable_on": {
+        "task_groups": [{
+          "relation": "parent_id",
+          "type": "fk",
+          "action": "reparent",
+          "visual": "containment",
+          "label": "Set parent",
+          "operation": { ... },
+          "removable": true,
+          "remove_operation": { ... }
+        }]
+      },
+      "accepts": {
+        "tasks": [{ ... }]
+      }
+    },
+    "tasks": {
+      "droppable_on": {
+        "task_groups": [{
+          "relation": "group_id",
+          "type": "fk",
+          "action": "move",
+          "visual": "containment",
+          "label": "Move to group",
+          "operation": { ... }
+        }],
+        "users": [{
+          "relation": "assigned_to_user_id",
+          "type": "fk",
+          "action": "move",
+          "visual": "badge",
+          "label": "Move to assigned to user",
+          "operation": { ... }
+        }],
+        "task_sets": [{
+          "relation": "task_set_members",
+          "type": "junction",
+          "action": "link",
+          "visual": "frame",
+          "label": "Add task set member",
+          "operation": { ... }
+        }],
+        "tasks": [{
+          "relation": "task_dependencies",
+          "type": "junction",
+          "action": "link",
+          "visual": "edge",
+          "direction": "source_to_target",
+          "label": "Add task dependency",
+          "operation": { ... },
+          "self_referential": true
+        }]
+      },
+      "accepts": {
+        "users": [{
+          "relation": "assigned_to_user_id",
+          "type": "fk",
+          "action": "assign",
+          "visual": "badge",
+          "label": "Assign assigned to user",
+          "operation": { ... }
+        }],
+        "task_sets": [{ ... }],
+        "tasks": [{
+          "visual": "edge",
+          "direction": "target_to_source"
+        }]
+      }
+    }
+  }
+}
+```
+
+### Canvas Interpretation
+
+| Drop | Visual | Result |
+|------|--------|--------|
+| Task → Group | containment | Task node moves inside group container |
+| Task → Task | edge | Arrow drawn from source to target |
+| User → Task | badge | User chip appears on task node |
+| Task → Set | frame | Task included in set's visual boundary |
+| Group → Group | containment | Group nests inside another group |
+
+## Relationship Types Summary
+
+| Schema Pattern | Type | Action | Default Visual |
+|----------------|------|--------|----------------|
+| `A.fk_id REFERENCES B` | `fk` | `move` | `badge` or `containment`* |
+| `A.fk_id REFERENCES A` | `fk` | `reparent` | `containment` |
+| Junction(A, B) | `junction` | `link` | `badge` or `frame`* |
+| Junction(A, A) | `junction` | `link` | `edge` |
+
+*Visual depends on target entity name and structure
+
+## Canvas Position Storage
+
+The drop-semantics manifest covers relationships but not node positions. For canvas x/y coordinates, consider:
+
+### Option A: JSON Column on Entity
+
+Simple approach for single-user or shared layouts:
+
+```sql
+ALTER TABLE tasks ADD COLUMN canvas JSONB DEFAULT '{}';
+
+-- Store position
+UPDATE tasks SET canvas = jsonb_build_object('x', 100, 'y', 200) WHERE id = 1;
+
+-- Or include in entity definition for automatic handling
+```
+
+### Option B: Separate Positions Table
+
+For multi-user layouts or per-project views:
+
+```sql
+CREATE TABLE canvas_positions (
+  entity TEXT NOT NULL,
+  record_id INT NOT NULL,
+  user_id INT REFERENCES users(id),
+  project_id INT,  -- Optional: per-project layouts
+  x FLOAT NOT NULL,
+  y FLOAT NOT NULL,
+  updated_at TIMESTAMPTZ DEFAULT NOW(),
+  PRIMARY KEY (entity, record_id, COALESCE(user_id, 0), COALESCE(project_id, 0))
+);
+
+CREATE INDEX idx_canvas_positions_lookup 
+  ON canvas_positions(entity, user_id, project_id);
+```
+
+### Option C: Client-Side Storage
+
+For personal layouts that don't need server persistence:
+
+```javascript
+// localStorage per user
+const positions = JSON.parse(localStorage.getItem('canvas_positions') || '{}');
+positions[`${entity}:${id}`] = { x, y };
+localStorage.setItem('canvas_positions', JSON.stringify(positions));
+```
+
+## See Also
+
+- [Many-to-Many](./many-to-many.md) - Junction table configuration
+- [Compiler Guide](../compiler/README.md) - Full compilation workflow
+- [Custom Functions](./custom-functions.md) - Extending with business logic

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dzql",
-  "version": "0.5.4",
+  "version": "0.5.6",
   "description": "PostgreSQL-powered framework with zero boilerplate CRUD operations and real-time WebSocket synchronization",
   "type": "module",
   "main": "src/server/index.js",

package/src/compiler/codegen/drop-semantics-codegen.js

@@ -0,0 +1,553 @@
+/**
+ * Drop Semantics Code Generator
+ * Generates a JSON manifest describing valid drag-and-drop interactions for a canvas UI
+ *
+ * Terminology clarification:
+ * - "source" = the entity being dragged
+ * - "target" = the entity being dropped onto
+ *
+ * Derivation rules:
+ * 1. FK on entity A pointing to entity B (e.g., tasks.group_id REFERENCES task_groups):
+ *    - A.droppable_on.B: drag A onto B → update A.group_id = B.id
+ *    - A.accepts.B: drag B onto A → update A.group_id = B.id (same operation, different drag direction)
+ *
+ * 2. Junction table (M2M):
+ *    - Both entities are droppable_on each other via junction insert
+ *    - Both entities accept each other
+ *
+ * 3. Self-referential FK:
+ *    - Entity is droppable on itself
+ *
+ * Visual semantics:
+ * - "containment": node moves inside container (tree structures, folders)
+ * - "frame": visual bounding box around members (sets, collections)
+ * - "edge": arrow drawn between nodes (dependencies, relationships)
+ * - "badge": tag/chip displayed on node (assignments, references)
+ */
+
+export class DropSemanticsCodegen {
+  /**
+   * @param {Object} entities - Map of tableName -> entityConfig
+   */
+  constructor(entities) {
+    this.entities = entities;
+  }
+
+  /**
+   * Generate the complete drop semantics manifest
+   * @returns {Object} Drop semantics JSON structure
+   */
+  generate() {
+    // Initialize result structure for all entities
+    const semantics = {};
+    for (const tableName of Object.keys(this.entities)) {
+      semantics[tableName] = {
+        droppable_on: {},
+        accepts: {}
+      };
+    }
+
+    // Process all FK relationships (adds to source's droppable_on and accepts)
+    for (const [tableName, config] of Object.entries(this.entities)) {
+      this._processFKRelationships(tableName, config, semantics);
+    }
+
+    // Process all M2M relationships (adds to source's droppable_on and accepts)
+    for (const [tableName, config] of Object.entries(this.entities)) {
+      this._processM2MRelationships(tableName, config, semantics);
+    }
+
+    // Second pass: populate target's accepts from source's droppable_on
+    // This ensures that if posts.droppable_on.tags exists, tags.accepts.posts also exists
+    this._populateTargetAccepts(semantics);
+
+    // Filter out entities with no semantics
+    const result = { entities: {} };
+    for (const [tableName, sem] of Object.entries(semantics)) {
+      if (Object.keys(sem.droppable_on).length > 0 || Object.keys(sem.accepts).length > 0) {
+        result.entities[tableName] = sem;
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Populate target's accepts from source's droppable_on
+   * If A.droppable_on.B exists, then B.accepts.A should also exist
+   * @private
+   */
+  _populateTargetAccepts(semantics) {
+    for (const [sourceTable, sem] of Object.entries(semantics)) {
+      for (const [targetTable, actions] of Object.entries(sem.droppable_on)) {
+        // Skip if target doesn't exist in our entities
+        if (!semantics[targetTable]) continue;
+
+        // For each droppable_on action, create a corresponding accepts entry
+        for (const action of actions) {
+          if (!semantics[targetTable].accepts[sourceTable]) {
+            semantics[targetTable].accepts[sourceTable] = [];
+          }
+
+          // Check if this exact relation already exists (avoid duplicates)
+          const exists = semantics[targetTable].accepts[sourceTable].some(
+            a => a.relation === action.relation && a.type === action.type
+          );
+
+          if (!exists) {
+            // Create the inverse action - swap source and target in params
+            const inverseAction = this._createInverseAction(action, sourceTable, targetTable);
+            semantics[targetTable].accepts[sourceTable].push(inverseAction);
+          }
+        }
+      }
+    }
+  }
+
+  /**
+   * Create an inverse action for accepts (swap source/target perspective)
+   * @private
+   */
+  _createInverseAction(action, sourceTable, targetTable) {
+    // For the inverse, @source becomes what was @target and vice versa
+    const swapRefs = (params) => {
+      const swapped = {};
+      for (const [key, value] of Object.entries(params)) {
+        if (typeof value === 'string') {
+          swapped[key] = value
+            .replace('@source.', '@__tmp__.')
+            .replace('@target.', '@source.')
+            .replace('@__tmp__.', '@target.');
+        } else {
+          swapped[key] = value;
+        }
+      }
+      return swapped;
+    };
+
+    // For inverse (accepts), visual is typically badge unless it's an edge
+    let inverseVisual = 'badge';
+    if (action.visual === 'edge') {
+      inverseVisual = 'edge';  // Edges are bidirectional visually
+    }
+
+    const result = {
+      ...action,
+      action: action.type === 'fk' ? 'assign' : action.action,
+      visual: inverseVisual,
+      label: action.type === 'fk'
+        ? this._generateLabel(action.relation, 'assign')
+        : action.label,
+      operation: {
+        ...action.operation,
+        params: swapRefs(action.operation.params)
+      },
+      remove_operation: action.remove_operation ? {
+        ...action.remove_operation,
+        params: swapRefs(action.remove_operation.params)
+      } : undefined
+    };
+
+    // For edge visual, swap direction
+    if (action.direction === 'source_to_target') {
+      result.direction = 'target_to_source';
+    }
+
+    return result;
+  }
+
+  /**
+   * Process FK relationships for an entity
+   * @private
+   */
+  _processFKRelationships(tableName, config, semantics) {
+    const fkIncludes = config.fkIncludes || {};
+    const primaryKey = config.primaryKey || ['id'];
+
+    for (const [alias, targetTable] of Object.entries(fkIncludes)) {
+      // Skip reverse FKs (child arrays) - indicated when alias === targetTable
+      if (alias === targetTable) {
+        continue;
+      }
+
+      const fkColumn = alias.endsWith('_id') ? alias : `${alias}_id`;
+      const isSelfReferential = targetTable === tableName;
+
+      // 1. Source (tableName) can be dropped onto target
+      // e.g., tasks.droppable_on.task_groups - drag task onto group
+      if (!semantics[tableName].droppable_on[targetTable]) {
+        semantics[tableName].droppable_on[targetTable] = [];
+      }
+
+      const action = isSelfReferential ? this._getSelfReferentialAction(fkColumn) : 'move';
+      const visual = this._inferVisual('fk', targetTable, isSelfReferential);
+
+      // Determine if this is primarily an "accepts" relationship (assign pattern)
+      // e.g., tasks.assigned_to_user_id - natural gesture is to drop user onto task
+      const isAssignPattern = this._isAssignPattern(alias);
+
+      semantics[tableName].droppable_on[targetTable].push({
+        relation: fkColumn,
+        type: 'fk',
+        action: action,
+        visual: visual,
+        label: this._generateLabel(fkColumn, action),
+        ...(isAssignPattern && { primary_direction: 'accepts' }),
+        operation: {
+          method: 'save',
+          entity: tableName,
+          params: this._buildPKParams(primaryKey, '@source', { [fkColumn]: '@target.id' })
+        },
+        removable: true,
+        remove_operation: {
+          method: 'save',
+          entity: tableName,
+          params: this._buildPKParams(primaryKey, '@source', { [fkColumn]: null })
+        }
+      });
+
+      // 2. Source (tableName) accepts target being dropped on it
+      // e.g., tasks.accepts.users - drag user onto task to assign
+      // This only makes sense for non-self-referential FKs
+      if (!isSelfReferential && this.entities[targetTable]) {
+        if (!semantics[tableName].accepts[targetTable]) {
+          semantics[tableName].accepts[targetTable] = [];
+        }
+
+        // For accepts, visual is always badge (something is being attached to this entity)
+        semantics[tableName].accepts[targetTable].push({
+          relation: fkColumn,
+          type: 'fk',
+          action: 'assign',
+          visual: 'badge',
+          label: this._generateLabel(alias, 'assign'),
+          operation: {
+            method: 'save',
+            entity: tableName,  // Update the entity with the FK
+            params: this._buildPKParams(primaryKey, '@target', { [fkColumn]: '@source.id' })
+          },
+          removable: true,
+          remove_operation: {
+            method: 'save',
+            entity: tableName,
+            params: this._buildPKParams(primaryKey, '@target', { [fkColumn]: null })
+          }
+        });
+      }
+    }
+  }
+
+  /**
+   * Process M2M relationships for an entity
+   * @private
+   */
+  _processM2MRelationships(tableName, config, semantics) {
+    const manyToMany = config.manyToMany || {};
+
+    for (const [relationKey, m2mConfig] of Object.entries(manyToMany)) {
+      const { junction_table, local_key, foreign_key, target_entity } = m2mConfig;
+
+      if (!junction_table || !local_key || !foreign_key || !target_entity) {
+        continue;
+      }
+
+      const isSelfReferential = target_entity === tableName;
+      const visual = this._inferVisual('junction', target_entity, isSelfReferential);
+
+      // 1. Source (tableName) can be dropped onto target
+      if (!semantics[tableName].droppable_on[target_entity]) {
+        semantics[tableName].droppable_on[target_entity] = [];
+      }
+
+      const baseEntry = {
+        relation: junction_table,
+        type: 'junction',
+        action: 'link',
+        visual: visual,
+        label: this._generateLabel(junction_table, 'link'),
+        operation: {
+          method: 'save',
+          entity: junction_table,
+          params: {
+            [local_key]: '@source.id',
+            [foreign_key]: '@target.id'
+          }
+        },
+        removable: true,
+        remove_operation: {
+          method: 'delete',
+          entity: junction_table,
+          params: {
+            [local_key]: '@source.id',
+            [foreign_key]: '@target.id'
+          }
+        },
+        ...(isSelfReferential && { self_referential: true })
+      };
+
+      // For edge visual (self-referential), add direction hint
+      if (visual === 'edge') {
+        baseEntry.direction = 'source_to_target';
+      }
+
+      semantics[tableName].droppable_on[target_entity].push(baseEntry);
+
+      // 2. Source (tableName) accepts target being dropped on it
+      // For M2M, the operation is symmetric but params swap
+      if (!isSelfReferential && this.entities[target_entity]) {
+        if (!semantics[tableName].accepts[target_entity]) {
+          semantics[tableName].accepts[target_entity] = [];
+        }
+
+        // For accepts on M2M, use frame if target is a set, otherwise badge
+        const acceptVisual = this._matchesSetPattern(target_entity) ? 'frame' : 'badge';
+
+        semantics[tableName].accepts[target_entity].push({
+          relation: junction_table,
+          type: 'junction',
+          action: 'link',
+          visual: acceptVisual,
+          label: this._generateLabel(junction_table, 'link'),
+          operation: {
+            method: 'save',
+            entity: junction_table,
+            params: {
+              [local_key]: '@target.id',   // target is the entity with the M2M config
+              [foreign_key]: '@source.id'  // source is what's being dropped
+            }
+          },
+          removable: true,
+          remove_operation: {
+            method: 'delete',
+            entity: junction_table,
+            params: {
+              [local_key]: '@target.id',
+              [foreign_key]: '@source.id'
+            }
+          }
+        });
+      }
+    }
+  }
+
+  /**
+   * Build params object with primary key fields
+   * @private
+   */
+  _buildPKParams(primaryKey, refPrefix, additionalParams) {
+    const params = {};
+
+    for (const pkField of primaryKey) {
+      params[pkField] = `${refPrefix}.${pkField}`;
+    }
+
+    Object.assign(params, additionalParams);
+    return params;
+  }
+
+  /**
+   * Infer the visual representation type for a relationship
+   * @private
+   * @param {string} type - 'fk' or 'junction'
+   * @param {string} targetTable - The target entity name
+   * @param {boolean} isSelfReferential - Whether this is a self-referential relation
+   * @returns {string} Visual type: 'containment', 'frame', 'edge', or 'badge'
+   */
+  _inferVisual(type, targetTable, isSelfReferential) {
+    // Rule 1: Self-referential junction → edge (arrows between same entity type)
+    if (type === 'junction' && isSelfReferential) {
+      return 'edge';
+    }
+
+    // Rule 2: Self-referential FK → containment (tree/hierarchy)
+    if (type === 'fk' && isSelfReferential) {
+      return 'containment';
+    }
+
+    // Rule 3: Target entity has self-referential FK → it's a tree/container
+    if (this._isTreeEntity(targetTable)) {
+      return 'containment';
+    }
+
+    // Rule 4: Naming convention fallback
+    if (this._matchesContainerPattern(targetTable)) {
+      return 'containment';
+    }
+
+    if (this._matchesSetPattern(targetTable)) {
+      return 'frame';
+    }
+
+    // Default: badge (tag/chip on node)
+    return 'badge';
+  }
+
+  /**
+   * Check if an entity has a self-referential FK (making it a tree structure)
+   * @private
+   */
+  _isTreeEntity(tableName) {
+    const config = this.entities[tableName];
+    if (!config) return false;
+
+    const fkIncludes = config.fkIncludes || {};
+    for (const [alias, target] of Object.entries(fkIncludes)) {
+      if (target === tableName) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Check if entity name matches container patterns
+   * @private
+   */
+  _matchesContainerPattern(tableName) {
+    const patterns = ['_groups', '_folders', '_categories', '_containers', '_parents'];
+    return patterns.some(p => tableName.endsWith(p));
+  }
+
+  /**
+   * Check if entity name matches set/collection patterns
+   * @private
+   */
+  _matchesSetPattern(tableName) {
+    const patterns = ['_sets', '_collections', '_lists', '_pools', '_batches'];
+    return patterns.some(p => tableName.endsWith(p));
+  }
+
+  /**
+   * Determine action type for self-referential FK
+   * @private
+   */
+  _getSelfReferentialAction(fkColumn) {
+    if (fkColumn.includes('parent')) {
+      return 'reparent';
+    }
+    if (fkColumn.includes('depends') || fkColumn.includes('dependency')) {
+      return 'link';
+    }
+    return 'nest';
+  }
+
+  /**
+   * Check if an FK alias represents an "assign" pattern
+   * where the natural gesture is to drop the target onto the source
+   * e.g., "assigned_to_user" - you drop user onto task, not task onto user
+   * @private
+   */
+  _isAssignPattern(alias) {
+    const assignPatterns = [
+      /^assigned_to_/,
+      /^created_by_/,
+      /^updated_by_/,
+      /^owned_by_/,
+      /^approved_by_/,
+      /^reviewed_by_/,
+      /^managed_by_/,
+      /^author$/,
+      /^owner$/,
+      /^assignee$/,
+      /^reviewer$/,
+      /^approver$/
+    ];
+
+    return assignPatterns.some(pattern => pattern.test(alias));
+  }
+
+  /**
+   * Generate human-readable label from relation name
+   * @private
+   */
+  _generateLabel(relationName, action) {
+    // Remove common suffixes and extract the core noun
+    let name = relationName
+      .replace(/_id$/, '')
+      .replace(/^fk_/, '');
+
+    // Strip preposition patterns to get the core entity name
+    // "assigned_to_user" → "user"
+    // "depends_on_task" → "task" (but keep "depends on" for special handling)
+    // "created_by_user" → "user"
+    // "owner_org" → "org"
+    const prepositionPatterns = [
+      /^assigned_to_/,
+      /^created_by_/,
+      /^updated_by_/,
+      /^owned_by_/,
+      /^belongs_to_/,
+      /^managed_by_/,
+      /^approved_by_/,
+      /^reviewed_by_/
+    ];
+
+    let strippedName = name;
+    for (const pattern of prepositionPatterns) {
+      if (pattern.test(name)) {
+        strippedName = name.replace(pattern, '');
+        break;
+      }
+    }
+
+    // Convert snake_case to Title Case
+    const words = strippedName.split('_').map(word =>
+      word.charAt(0).toUpperCase() + word.slice(1).toLowerCase()
+    );
+
+    // Map action to verb
+    const verbs = {
+      'move': 'Move to',
+      'assign': 'Assign',
+      'link': 'Add',
+      'nest': 'Set as child of',
+      'reparent': 'Set parent'
+    };
+
+    const verb = verbs[action] || '';
+
+    // Special handling for junction tables (link action)
+    if (action === 'link') {
+      const singularName = this._singularize(words.join(' '));
+      return `Add ${singularName.toLowerCase()}`;
+    }
+
+    return `${verb} ${words.join(' ').toLowerCase()}`.trim();
+  }
+
+  /**
+   * Simple singularization
+   * @private
+   */
+  _singularize(word) {
+    if (word.endsWith('ies')) {
+      return word.slice(0, -3) + 'y';
+    }
+    if (word.endsWith('es') && !word.endsWith('ses')) {
+      return word.slice(0, -2);
+    }
+    if (word.endsWith('s') && !word.endsWith('ss')) {
+      return word.slice(0, -1);
+    }
+    return word;
+  }
+}
+
+/**
+ * Generate drop semantics from parsed entities
+ * @param {Array|Object} entities - Array of entity configs or map of tableName -> config
+ * @returns {Object} Drop semantics manifest
+ */
+export function generateDropSemantics(entities) {
+  // Convert array to map if needed
+  let entityMap = entities;
+  if (Array.isArray(entities)) {
+    entityMap = {};
+    for (const entity of entities) {
+      entityMap[entity.tableName] = entity;
+    }
+  }
+
+  const gen = new DropSemanticsCodegen(entityMap);
+  return gen.generate();
+}

package/src/compiler/codegen/permission-codegen.js

@@ -171,55 +171,62 @@ $$ LANGUAGE plpgsql STABLE SECURITY DEFINER;`;
 
   /**
    * Generate traversal check: @org_id->acts_for[org_id=$]{active}.user_id
+   * Supports multi-hop paths like: @product_id->products.organisation_id->acts_for[organisation_id=$].user_id
    * @private
    */
   _generateTraversalCheck(ast) {
     const steps = ast.steps;
 
-    // Extract components from the path
-    let sourceField = null;
-    let targetTable = null;
-    let targetField = null;
-    let filters = [];
-    let temporal = false;
-
-    for (const step of steps) {
-      if (step.type === 'field_ref') {
-        if (!sourceField) {
-          // First field reference is the source
-          sourceField = step.field;
-        } else {
-          // Last field reference is the target
-          targetField = step.field;
-        }
-      } else if (step.type === 'table_ref') {
-        targetTable = step.table;
+    // First step should be the source field reference
+    if (steps.length === 0 || steps[0].type !== 'field_ref') {
+      return 'false';
+    }
 
-        // Collect filter conditions
-        if (step.filter) {
-          filters = step.filter;
-        }
+    const sourceField = steps[0].field;
 
-        // Check for temporal marker
-        if (step.temporal) {
-          temporal = true;
-        }
+    // Collect all table_ref steps (these are the hops)
+    const tableSteps = steps.filter(s => s.type === 'table_ref');
 
-        // Get target field if specified in table ref
-        if (step.targetField) {
-          targetField = step.targetField;
-        }
+    if (tableSteps.length === 0) {
+      return 'false';
+    }
+
+    // Build the value expression that resolves through intermediate tables
+    // Start with the record's source field
+    let valueExpr = `(p_record->>'${sourceField}')::int`;
+
+    // Process intermediate hops (all but the last table_ref)
+    // Each intermediate hop needs a subquery to resolve to the next field
+    for (let i = 0; i < tableSteps.length - 1; i++) {
+      const hop = tableSteps[i];
+      const table = hop.table;
+      const targetField = hop.targetField;
+
+      if (!targetField) {
+        // If no target field specified, assume 'id' for the lookup
+        // This shouldn't normally happen in well-formed paths
+        continue;
       }
+
+      // Build subquery: (SELECT targetField FROM table WHERE id = previousValue)
+      valueExpr = `(SELECT ${targetField} FROM ${table} WHERE id = ${valueExpr})`;
     }
 
-    // Build WHERE conditions
+    // The last table_ref is where we do the EXISTS check
+    const finalStep = tableSteps[tableSteps.length - 1];
+    const targetTable = finalStep.table;
+    const targetField = finalStep.targetField;
+    const filters = finalStep.filter || [];
+    const temporal = finalStep.temporal || false;
+
+    // Build WHERE conditions for the final EXISTS query
     const conditions = [];
 
     // Add filter conditions
     for (const filter of filters) {
       if (filter.operator === '=' && filter.value.type === 'param') {
-        // field=$ means match the record's field value
-        conditions.push(`${targetTable}.${filter.field} = (p_record->>'${sourceField}')::int`);
+        // field=$ means match the resolved value from the path
+        conditions.push(`${targetTable}.${filter.field} = ${valueExpr}`);
       } else if (filter.operator === '=') {
         const value = this._formatValue(filter.value);
         conditions.push(`${targetTable}.${filter.field} = ${value}`);
@@ -228,9 +235,6 @@ $$ LANGUAGE plpgsql STABLE SECURITY DEFINER;`;
 
     // Add temporal condition
     if (temporal) {
-      // Add temporal filtering for {active} marker
-      // Assumes standard field names: valid_from and valid_to
-      // This matches the interpreter's behavior in resolve_path_segment (002_functions.sql:316)
       conditions.push(`${targetTable}.valid_from <= NOW()`);
       conditions.push(`(${targetTable}.valid_to > NOW() OR ${targetTable}.valid_to IS NULL)`);
     }

package/src/compiler/compiler.js

@@ -11,6 +11,7 @@ import { generateNotificationFunction } from './codegen/notification-codegen.js'
 import { generateGraphRuleFunctions } from './codegen/graph-rules-codegen.js';
 import { generateSubscribable } from './codegen/subscribable-codegen.js';
 import { generateAuthFunctions } from './codegen/auth-codegen.js';
+import { generateDropSemantics } from './codegen/drop-semantics-codegen.js';
 import crypto from 'crypto';
 
 export class DZQLCompiler {
@@ -190,7 +191,7 @@ export class DZQLCompiler {
   /**
    * Compile from SQL file
    * @param {string} sqlContent - SQL file content
-   * @returns {Object} Compilation results
+   * @returns {Object} Compilation results with dropSemantics
    */
   compileFromSQL(sqlContent) {
     // Use parseEntitiesFromSQL to properly extract custom functions
@@ -200,11 +201,20 @@ export class DZQLCompiler {
       return {
         results: [],
         errors: [],
-        summary: { total: 0, successful: 0, failed: 0 }
+        summary: { total: 0, successful: 0, failed: 0 },
+        dropSemantics: { entities: {} }
       };
     }
 
-    return this.compileAll(entities);
+    const compilationResult = this.compileAll(entities);
+
+    // Generate drop semantics from all parsed entities
+    const dropSemantics = generateDropSemantics(entities);
+
+    return {
+      ...compilationResult,
+      dropSemantics
+    };
   }
 
   /**