@omnifyjp/omnify 3.19.4 → 3.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omnifyjp/omnify",
-  "version": "3.19.4",
+  "version": "3.21.0",
   "description": "Schema-driven code generation for Laravel, TypeScript, and SQL",
   "license": "MIT",
   "repository": {
@@ -36,10 +36,10 @@
     "zod": "^3.24.0"
   },
   "optionalDependencies": {
-    "@omnifyjp/omnify-darwin-arm64": "3.19.4",
-    "@omnifyjp/omnify-darwin-x64": "3.19.4",
-    "@omnifyjp/omnify-linux-x64": "3.19.4",
-    "@omnifyjp/omnify-linux-arm64": "3.19.4",
-    "@omnifyjp/omnify-win32-x64": "3.19.4"
+    "@omnifyjp/omnify-darwin-arm64": "3.21.0",
+    "@omnifyjp/omnify-darwin-x64": "3.21.0",
+    "@omnifyjp/omnify-linux-x64": "3.21.0",
+    "@omnifyjp/omnify-linux-arm64": "3.21.0",
+    "@omnifyjp/omnify-win32-x64": "3.21.0"
   }
 }

package/ts-dist/php/service-generator.js

@@ -218,9 +218,16 @@ function generateBaseService(name, schema, reader, config) {
     const hasAuditUpdatedBy = schemaAudit?.updatedBy ?? globalAudit?.updatedBy ?? false;
     const hasAuditDeletedBy = schemaAudit?.deletedBy ?? globalAudit?.deletedBy ?? false;
     const hasAnyAudit = hasAuditCreatedBy || hasAuditUpdatedBy || hasAuditDeletedBy;
-    // Translatable fields
+    // Translatable fields + sidecar table info (#76: lookup/sort need join rewrite)
     const translatableFields = reader.getTranslatableFields(name);
     const hasTranslatable = translatableFields.length > 0;
+    const modelSnake = toSnakeCase(name);
+    const translationCtx = {
+        mainTable: reader.getTableName(name),
+        translationTable: `${modelSnake}_translations`,
+        fkColumn: `${modelSnake}_id`,
+        translatableFields,
+    };
     // Eager load / count (#75.1: rejoin YAML-split `rel:col,col` tokens)
     const eagerLoad = reconstructRelationTokens(svc.eagerLoad ?? []);
     const eagerCount = svc.eagerCount ?? [];
@@ -255,17 +262,17 @@ function generateBaseService(name, schema, reader, config) {
     // Allowed sort columns whitelist (#75.2: prevent SQL injection via sort filter)
     const allowedSortColumns = buildAllowedSortColumns(searchableFields, filterableFields, sortableFields, defaultSort, hasSoftDelete);
     // list() method
-    sections.push(buildListMethod(modelName, searchableFields, filterableFields, sortableFields, hasSoftDelete, eagerLoad, eagerCount, defaultSort, perPage, allowedSortColumns));
+    sections.push(buildListMethod(modelName, searchableFields, filterableFields, sortableFields, hasSoftDelete, eagerLoad, eagerCount, defaultSort, perPage, allowedSortColumns, translationCtx, reader));
     // findById() method
-    sections.push(buildFindByIdMethod(modelName, eagerLoad, eagerCount));
+    sections.push(buildFindByIdMethod(modelName, eagerLoad, eagerCount, hasSoftDelete));
     // ── Create section ────────────────────────────────────────────────────────
     sections.push('');
     sections.push(buildSectionComment('Create'));
-    sections.push(buildCreateMethod(modelName, hasAuditCreatedBy, hasTranslatable, translatableFields, eagerLoad, eagerCount, defaults));
+    sections.push(buildCreateMethod(modelName, name, schema, reader, hasAuditCreatedBy, hasTranslatable, translatableFields, eagerLoad, eagerCount, defaults, locales));
     // ── Update section ────────────────────────────────────────────────────────
     sections.push('');
     sections.push(buildSectionComment('Update'));
-    sections.push(buildUpdateMethod(modelName, hasAuditUpdatedBy, hasTranslatable, eagerLoad, eagerCount));
+    sections.push(buildUpdateMethod(modelName, name, schema, reader, hasAuditUpdatedBy, hasTranslatable, eagerLoad, eagerCount, translatableFields, locales));
     // ── Delete & Restore section ──────────────────────────────────────────────
     sections.push('');
     if (hasSoftDelete) {
@@ -284,29 +291,40 @@ function generateBaseService(name, schema, reader, config) {
     if (lookup) {
         sections.push('');
         sections.push(buildSectionComment('Lookup'));
-        sections.push(buildLookupMethod(modelName, lookupFields, filterableFields, defaultSort));
+        sections.push(buildLookupMethod(modelName, lookupFields, filterableFields, defaultSort, translationCtx, reader, hasSoftDelete));
     }
     // ── Translatable helpers ──────────────────────────────────────────────────
     if (hasTranslatable) {
         sections.push('');
         sections.push(buildSectionComment('Translatable Helpers'));
-        sections.push(buildExtractTranslationsMethod(translatableFields, locales));
-        sections.push(buildSyncTranslationsMethod(modelName));
+        sections.push(buildFlushTranslationsMethod(modelName));
     }
     // ── Assemble file ─────────────────────────────────────────────────────────
+    const classDoc = buildClassDocblock({
+        modelName,
+        schemaName: name,
+        modelFqcn: `${modelNs}\\${modelName}`,
+        searchableFields,
+        filterableFields,
+        allowedSortColumns,
+        defaultSort,
+        perPage,
+        eagerLoad,
+        eagerCount,
+        translatableFields,
+        hasSoftDelete,
+        hasAnyAudit,
+        lookup,
+        lookupFields,
+        locales,
+    });
     const content = `<?php
 
 namespace ${baseNs};
 
-/**
- * DO NOT EDIT - This file is auto-generated by Omnify.
- * Any changes will be overwritten on next generation.
- *
- * @generated by omnify
- */
-
 ${imports.join('\n')}
 
+${classDoc}
 class ${modelName}ServiceBase
 {
 ${sections.join('\n')}
@@ -322,6 +340,331 @@ function buildSectionComment(title) {
     //  ${title}
     // =========================================================================`;
 }
+// ============================================================================
+// #77 follow-up: strict @param array-shape + @example block derivation
+// ============================================================================
+/**
+ * Map a schema PropertyDefinition to a PHPStan/Psalm array-shape value type.
+ * EnumRef is resolved to a literal union by the reader before we get here.
+ */
+function mapPropertyToPhpType(prop, reader) {
+    // Inline enum values: ['draft', 'published'] → 'draft'|'published'
+    if (prop.enum) {
+        if (typeof prop.enum === 'string') {
+            // Reference to a schema enum — resolve values
+            const enumSchema = reader.getSchema(prop.enum);
+            const values = enumSchema?.values ?? [];
+            if (values.length > 0) {
+                return values.map(v => `'${v.value}'`).join('|');
+            }
+        }
+        else if (Array.isArray(prop.enum) && prop.enum.length > 0) {
+            return prop.enum.map(v => `'${v}'`).join('|');
+        }
+        return 'string';
+    }
+    switch (prop.type) {
+        case 'Boolean': return 'bool';
+        case 'Int':
+        case 'BigInt':
+        case 'TinyInt':
+        case 'Integer': return 'int';
+        case 'Float':
+        case 'Decimal': return 'float';
+        case 'Json': return 'array<string, mixed>';
+        case 'File': return '\\Illuminate\\Http\\UploadedFile|string';
+        case 'Text':
+        case 'LongText':
+        case 'MediumText':
+        case 'String':
+        case 'Date':
+        case 'DateTime':
+        case 'Timestamp':
+        case 'Time':
+        case 'Uuid':
+        case 'Email':
+        case 'Url':
+        case 'Password':
+        case 'Slug': return 'string';
+        default: return 'string';
+    }
+}
+/**
+ * Placeholder value for an @example block, derived from the property's type
+ * and name so consumers can copy-paste and tweak. Not intended to be valid
+ * production data — just type-realistic.
+ */
+function samplePhpValueForProperty(prop, colName, reader) {
+    // Enum — prefer the first declared value
+    if (prop.enum) {
+        if (typeof prop.enum === 'string') {
+            const enumSchema = reader.getSchema(prop.enum);
+            const first = enumSchema?.values?.[0]?.value;
+            if (first)
+                return `'${first}'`;
+        }
+        else if (Array.isArray(prop.enum) && prop.enum.length > 0) {
+            return `'${prop.enum[0]}'`;
+        }
+    }
+    switch (prop.type) {
+        case 'Boolean': return 'false';
+        case 'Int':
+        case 'BigInt':
+        case 'TinyInt':
+        case 'Integer': return colName.endsWith('_order') ? '0' : '1';
+        case 'Float':
+        case 'Decimal': return '0.0';
+        case 'Json': return '[]';
+        case 'Uuid': return "'01h000000000000000000000000'";
+        case 'Email': return "'user@example.com'";
+        case 'Url': return "'https://example.com'";
+        case 'Date': return "'2026-01-01'";
+        case 'DateTime':
+        case 'Timestamp': return "'2026-01-01 00:00:00'";
+        case 'Time': return "'12:00:00'";
+        case 'File': return '$uploadedFile';
+        default:
+            // Use the column name itself as a hint for string-like fields
+            if (colName === 'slug')
+                return "'example-slug'";
+            if (colName === 'password')
+                return "'hunter2'";
+            if (colName.endsWith('_id'))
+                return "'01h000000000000000000000000'";
+            return `'example-${colName}'`;
+    }
+}
+/** Property inclusion filter for @param shapes on write methods. */
+function isWriteMethodDataField(propName, prop) {
+    // Skip auto-managed / system columns
+    if (propName === 'id' || propName === 'created_at' || propName === 'updated_at' || propName === 'deleted_at') {
+        return false;
+    }
+    if (propName === 'created_by_id' || propName === 'updated_by_id' || propName === 'deleted_by_id') {
+        return false;
+    }
+    // Skip Associations — they represent relations, not insertable columns
+    if (prop.type === 'Association')
+        return false;
+    // Skip files — they flow through a separate upload path
+    if (prop.type === 'File')
+        return false;
+    return true;
+}
+/**
+ * Build the `@param array{...} $data` shape for create()/update().
+ * Enumerates every schema property that is insertable, with typed values.
+ * Translatable fields expand into bare + `attr:locale` variants so the
+ * consumer gets autocomplete on every valid key Astrotomic::fill() accepts.
+ * The deprecated `translations` wrapper is still listed (with a comment)
+ * so readers see both paths until v3.21.0 drops the wrapper entirely.
+ */
+function buildWriteDataShape(schema, reader, translatableFields, locales) {
+    const properties = schema.properties ?? {};
+    const order = schema.propertyOrder ?? Object.keys(properties);
+    const lines = [];
+    const translatableSet = new Set(translatableFields);
+    for (const propName of order) {
+        const prop = properties[propName];
+        if (!prop || !isWriteMethodDataField(propName, prop))
+            continue;
+        const colName = toSnakeCase(propName);
+        const phpType = mapPropertyToPhpType(prop, reader);
+        // Emit the bare column (Astrotomic falls back to it for the default locale)
+        lines.push(`     *     ${colName}?: ${phpType},`);
+        // For translatable fields, also emit 'attr:locale' variants per configured locale
+        if (translatableSet.has(colName) || translatableSet.has(propName)) {
+            for (const loc of locales) {
+                lines.push(`     *     '${colName}:${loc}'?: ${phpType},`);
+            }
+        }
+    }
+    // #78 Step 3: legacy 'translations' wrapper is removed — only flat
+    // 'attr:locale' keys are accepted.
+    return lines.join('\n');
+}
+/**
+ * Build the `@param array{...} $filters` shape for list()/lookup(). Enumerates
+ * every filterable column with its typed value (enum union where applicable),
+ * plus the standard control keys (search, sort, pagination, trash toggles).
+ */
+function buildListFilterShape(filterableFields, allowedSortColumns, hasSoftDelete, reader) {
+    const lines = [];
+    for (const f of filterableFields) {
+        const phpType = mapPropertyToPhpType(f.prop, reader);
+        lines.push(`     *     ${f.colName}?: ${phpType},`);
+    }
+    lines.push(`     *     search?: string,`);
+    const sortUnion = allowedSortColumns.length > 0
+        ? allowedSortColumns.flatMap(c => [`'${c}'`, `'-${c}'`]).join('|')
+        : 'string';
+    lines.push(`     *     sort?: ${sortUnion},`);
+    lines.push(`     *     per_page?: int,`);
+    if (hasSoftDelete) {
+        lines.push(`     *     with_trashed?: bool,`);
+        lines.push(`     *     only_trashed?: bool,`);
+    }
+    return lines.join('\n');
+}
+function buildLookupFilterShape(filterableFields, reader, hasSoftDelete) {
+    const lines = [];
+    for (const f of filterableFields) {
+        const phpType = mapPropertyToPhpType(f.prop, reader);
+        lines.push(`     *     ${f.colName}?: ${phpType},`);
+    }
+    lines.push(`     *     limit?: int,`);
+    if (hasSoftDelete) {
+        // #79: lookup() now mirrors list()'s soft-delete filter contract so
+        // trashed-row admin flows can resolve options through the same method.
+        lines.push(`     *     with_trashed?: bool,`);
+        lines.push(`     *     only_trashed?: bool,`);
+    }
+    return lines.join('\n');
+}
+/**
+ * @example block body for create()/update(): one flat-format example plus a
+ * translatable-locale variant when the schema has translatable fields.
+ */
+/** Format a key+value pair with the arrow aligned across rows. */
+function formatPhpArrayRow(key, value, arrowColumn) {
+    const padding = ' '.repeat(Math.max(1, arrowColumn - key.length));
+    return `     *       ${key}${padding}=> ${value},`;
+}
+function buildWriteExampleBlock(methodName, modelName, schema, reader, translatableFields, locales) {
+    const properties = schema.properties ?? {};
+    const order = schema.propertyOrder ?? Object.keys(properties);
+    const translatableSet = new Set(translatableFields);
+    // Pass 1: collect (key, value) tuples so we can align the arrow across rows.
+    const rows = [];
+    for (const propName of order) {
+        const prop = properties[propName];
+        if (!prop || !isWriteMethodDataField(propName, prop))
+            continue;
+        const colName = toSnakeCase(propName);
+        if (translatableSet.has(colName) || translatableSet.has(propName)) {
+            for (const loc of locales) {
+                rows.push({ key: `'${colName}:${loc}'`, value: `'example-${colName}-${loc}'` });
+            }
+            continue;
+        }
+        rows.push({ key: `'${colName}'`, value: samplePhpValueForProperty(prop, colName, reader) });
+    }
+    const arrowColumn = Math.max(0, ...rows.map(r => r.key.length)) + 1;
+    const keyLines = rows.map(r => formatPhpArrayRow(r.key, r.value, arrowColumn));
+    const invocation = methodName === 'create'
+        ? `$service->create([`
+        : `$service->update($existing${modelName}, [`;
+    return `     * @example ${methodName === 'create' ? `Create a ${modelName} with per-locale translations (flat form)` : `Update a ${modelName} (same shape as create)`}
+     *   ${invocation}
+${keyLines.join('\n')}
+     *   ]);`;
+}
+function buildListExampleBlock(modelName, filterableFields, defaultSort, reader) {
+    const rows = [];
+    for (const f of filterableFields) {
+        rows.push({ key: `'${f.colName}'`, value: samplePhpValueForProperty(f.prop, f.colName, reader) });
+    }
+    rows.push({ key: "'search'", value: "'pho'" });
+    rows.push({ key: "'sort'", value: `'${defaultSort}'` });
+    rows.push({ key: "'per_page'", value: '25' });
+    const arrowColumn = Math.max(0, ...rows.map(r => r.key.length)) + 1;
+    const keyLines = rows.map(r => formatPhpArrayRow(r.key, r.value, arrowColumn));
+    return `     * @example List ${modelName}s with every supported filter key
+     *   $paginator = $service->list([
+${keyLines.join('\n')}
+     *   ]);`;
+}
+function buildLookupExampleBlock(modelName, filterableFields, reader) {
+    const rows = [];
+    for (const f of filterableFields) {
+        rows.push({ key: `'${f.colName}'`, value: samplePhpValueForProperty(f.prop, f.colName, reader) });
+    }
+    rows.push({ key: "'limit'", value: '50' });
+    const arrowColumn = Math.max(0, ...rows.map(r => r.key.length)) + 1;
+    const keyLines = rows.map(r => formatPhpArrayRow(r.key, r.value, arrowColumn));
+    return `     * @example Fetch ${modelName} options for a type-ahead / dropdown
+     *   $rows = $service->lookup([
+${keyLines.join('\n')}
+     *   ]);`;
+}
+function buildClassDocblock(c) {
+    const lines = [];
+    lines.push('/**');
+    lines.push(` * ${c.modelName}ServiceBase — auto-generated service layer for the ${c.schemaName} schema.`);
+    lines.push(' *');
+    lines.push(` * Model:     ${c.modelFqcn}`);
+    lines.push(' * Extends:   (none) — consumers extend this via the sibling non-Base file,');
+    lines.push(' *            which is never overwritten.');
+    lines.push(' *');
+    lines.push(' * === list() filter contract ===');
+    if (c.searchableFields.length > 0) {
+        const searchCols = c.searchableFields
+            .map(f => f.translatable ? `${f.colName} (translated)` : f.colName)
+            .join(', ');
+        lines.push(` *   search        (LIKE)  — against: ${searchCols}`);
+    }
+    for (const f of c.filterableFields) {
+        const phpType = resolvePhpFilterType(f.type);
+        const note = f.translatable ? ' (translatable)' : '';
+        lines.push(` *   ${f.colName.padEnd(13)} (${phpType})${note} — from options.service.filterable`);
+    }
+    lines.push(` *   sort          (col)   — whitelisted: ${c.allowedSortColumns.join(', ')}.`);
+    lines.push(` *                          Default: ${c.defaultSort}. Prefix '-' for DESC.`);
+    if (c.hasSoftDelete) {
+        lines.push(' *   only_trashed  (bool)  — wins over with_trashed when both set.');
+        lines.push(' *   with_trashed  (bool)');
+    }
+    lines.push(` *   per_page      (int)   — default ${c.perPage}.`);
+    lines.push(' *');
+    if (c.eagerLoad.length > 0 || c.eagerCount.length > 0) {
+        lines.push(' * === Relations ===');
+        if (c.eagerLoad.length > 0) {
+            lines.push(` *   Eager loads:   ${c.eagerLoad.join(', ')}`);
+        }
+        if (c.eagerCount.length > 0) {
+            lines.push(` *   Eager counts:  ${c.eagerCount.join(', ')}`);
+        }
+        lines.push(' *');
+    }
+    if (c.translatableFields.length > 0) {
+        lines.push(' * === Translatable ===');
+        lines.push(` *   Fields:     ${c.translatableFields.join(', ')}`);
+        lines.push(` *   Locales:    ${c.locales.join(', ')}`);
+        lines.push(` *   Sidecar:    ${toSnakeCase(c.schemaName)}_translations (synced in create/update)`);
+        lines.push(' *');
+        lines.push(' *   Input format (Astrotomic-native flat — #78 Step 3):');
+        const sampleField = c.translatableFields[0] ?? 'name';
+        const sampleLocale = c.locales[0] ?? 'ja';
+        lines.push(` *     [ "${sampleField}:${sampleLocale}" => "...", "${sampleField}:${c.locales[1] ?? 'en'}" => "..." ]`);
+        lines.push(' *');
+        lines.push(' *   The old "translations" wrapper format was removed in v3.21.0 (#78).');
+        lines.push(' *   Astrotomic Translatable::fill() routes these keys natively; this base');
+        lines.push(' *   class just calls flushTranslations() after save() to persist sidecar');
+        lines.push(' *   rows under seeder paths that suppress model events.');
+        lines.push(' *');
+        lines.push(' *   Lookup/sort on translatable columns rewrites to a LEFT JOIN on the');
+        lines.push(' *   sidecar for the request locale + fallback (see #76).');
+        lines.push(' *');
+    }
+    if (c.hasSoftDelete) {
+        lines.push(' * Soft delete: enabled (delete → trash, forceDelete → hard delete, restore → untrash).');
+    }
+    if (c.hasAnyAudit) {
+        lines.push(' * Audit:       created_by/updated_by/deleted_by forced from Auth::id() (client');
+        lines.push(' *              values are discarded — see #75 item 3).');
+    }
+    if (c.lookup) {
+        lines.push(` * Lookup:      returns ${c.lookupFields.join(', ')} (default limit 100, hard cap 500 — #75.8).`);
+    }
+    lines.push(' *');
+    lines.push(' * DO NOT EDIT - This file is auto-generated by Omnify.');
+    lines.push(' * Any changes will be overwritten on next generation.');
+    lines.push(' *');
+    lines.push(' * @generated by omnify');
+    lines.push(' */');
+    return lines.join('\n');
+}
 function buildEagerLoadChain(eagerLoad, eagerCount) {
     const parts = [];
     if (eagerLoad.length > 0) {
@@ -367,13 +710,25 @@ function buildAllowedSortColumns(searchableFields, filterableFields, sortableFie
         set.add(defaultCol);
     return Array.from(set).sort();
 }
-function buildListMethod(modelName, searchableFields, filterableFields, sortableFields, hasSoftDelete, eagerLoad, eagerCount, defaultSort, perPage, allowedSortColumns) {
+function buildListMethod(modelName, searchableFields, filterableFields, sortableFields, hasSoftDelete, eagerLoad, eagerCount, defaultSort, perPage, allowedSortColumns, tx, reader) {
     const lines = [];
-    // PHPDoc with filter shape
-    const filterShape = buildFilterDocShape(filterableFields, hasSoftDelete);
+    // #77 follow-up: strict multi-line array-shape enumerating every filter
+    // key explicitly (no catch-all). Sort union includes -prefixed DESC variants.
+    const filterShape = buildListFilterShape(filterableFields, allowedSortColumns, hasSoftDelete, reader);
+    const listExample = buildListExampleBlock(modelName, filterableFields, defaultSort, reader);
     lines.push(`
     /**
-     * @param  array{${filterShape}}  $filters
+     * List ${modelName} records with filters, search, sort and pagination.
+     *
+     * Filter keys are whitelisted from the schema's options.service config;
+     * unknown keys are ignored. The sort column is whitelisted against
+     * searchable + filterable + standard audit columns (#75.2).
+     *
+     * @param array{
+${filterShape}
+     * } $filters
+     *
+${listExample}
      */
     public function list(array $filters = []): LengthAwarePaginator
     {
@@ -413,7 +768,7 @@ function buildListMethod(modelName, searchableFields, filterableFields, sortable
     }
     // Sort
     lines.push('');
-    lines.push(buildSortSection(sortableFields, defaultSort, allowedSortColumns));
+    lines.push(buildSortSection(sortableFields, defaultSort, allowedSortColumns, tx));
     // Paginate
     lines.push(`
         return $query->paginate($filters['per_page'] ?? ${perPage});
@@ -473,11 +828,14 @@ ${clauses.join('\n')}
             });
         });`;
 }
-function buildSortSection(_sortableFields, defaultSort, allowedSortColumns) {
+function buildSortSection(_sortableFields, defaultSort, allowedSortColumns, tx) {
     const defaultCol = defaultSort.replace(/^-/, '');
     const allowedList = allowedSortColumns.map(c => `'${c}'`).join(', ');
-    // #75.2: whitelist sort column to prevent SQL injection / arbitrary column access
-    return `        // -- Sort (#75.2: whitelist guards against SQL injection) --
+    const hasTranslatableSortable = tx.translatableFields.length > 0 &&
+        allowedSortColumns.some(c => tx.translatableFields.includes(c));
+    if (!hasTranslatableSortable) {
+        // Fast path: nothing translatable in the allowlist, plain orderBy works.
+        return `        // -- Sort (#75.2: whitelist guards against SQL injection) --
         $sort = $filters['sort'] ?? '${defaultSort}';
         $direction = str_starts_with($sort, '-') ? 'desc' : 'asc';
         $column = ltrim($sort, '-');
@@ -486,19 +844,104 @@ function buildSortSection(_sortableFields, defaultSort, allowedSortColumns) {
             $column = '${defaultCol}';
         }
         $query->orderBy($column, $direction);`;
+    }
+    // #76: one or more whitelisted columns live in the translation sidecar.
+    // Runtime-branch on $column: translatable → leftJoin + orderByRaw with
+    // COALESCE(locale, fallback); non-translatable → plain orderBy.
+    const translatablePhpList = tx.translatableFields
+        .filter(f => allowedSortColumns.includes(f))
+        .map(f => `'${f}'`)
+        .join(', ');
+    const mainTable = tx.mainTable;
+    const trTable = tx.translationTable;
+    const fk = tx.fkColumn;
+    return `        // -- Sort (#75.2 whitelist + #76 translatable join rewrite) --
+        $sort = $filters['sort'] ?? '${defaultSort}';
+        $direction = str_starts_with($sort, '-') ? 'desc' : 'asc';
+        $column = ltrim($sort, '-');
+        $allowedSortColumns = [${allowedList}];
+        if (! in_array($column, $allowedSortColumns, true)) {
+            $column = '${defaultCol}';
+        }
+        $translatableSortColumns = [${translatablePhpList}];
+        if (in_array($column, $translatableSortColumns, true)) {
+            // #76: sort column lives in '${trTable}'. LEFT JOIN once on the
+            // request locale and once on the fallback locale, then COALESCE
+            // so missing translations don't push rows to the top/bottom.
+            $locale = app()->getLocale();
+            $fallback = config('translatable.fallback_locale', 'en');
+            $query
+                ->leftJoin('${trTable} as tr_sort', function ($j) use ($locale) {
+                    $j->on('tr_sort.${fk}', '=', '${mainTable}.id')
+                      ->where('tr_sort.locale', $locale);
+                })
+                ->leftJoin('${trTable} as tr_sort_fb', function ($j) use ($fallback) {
+                    $j->on('tr_sort_fb.${fk}', '=', '${mainTable}.id')
+                      ->where('tr_sort_fb.locale', $fallback);
+                })
+                ->select('${mainTable}.*')
+                ->orderByRaw("COALESCE(tr_sort.\`{$column}\`, tr_sort_fb.\`{$column}\`) " . strtoupper($direction));
+        } else {
+            $query->orderBy($column, $direction);
+        }`;
 }
 // ── findById() ──────────────────────────────────────────────────────────────
-function buildFindByIdMethod(modelName, eagerLoad, eagerCount) {
+function buildFindByIdMethod(modelName, eagerLoad, eagerCount, hasSoftDelete) {
     const eagerChain = buildEagerLoadChain(eagerLoad, eagerCount);
     const chain = eagerChain ? `\n${eagerChain}\n            ` : '';
-    return `
+    if (!hasSoftDelete) {
+        return `
+    /**
+     * Load a single ${modelName} by primary key with the configured eager
+     * loads applied. Throws ModelNotFoundException (→ HTTP 404) on miss.
+     *
+     * @throws \\Illuminate\\Database\\Eloquent\\ModelNotFoundException
+     *
+     * @example Fetch a single ${modelName} by id
+     *   $model = $service->findById('01h000000000000000000000000');
+     */
     public function findById(string $id): ${modelName}
     {
         return $this->model::query()${chain}->findOrFail($id);
     }`;
+    }
+    // #79: soft-deletable schemas accept an opt-in `$withTrashed` flag so admin
+    // restore / audit workflows can resolve a trashed row through the base
+    // instead of bypassing it with Product::withTrashed()->findOrFail($id).
+    const queryAssignment = eagerChain
+        ? `        $query = $this->model::query()\n${eagerChain};`
+        : `        $query = $this->model::query();`;
+    return `
+    /**
+     * Load a single ${modelName} by primary key with the configured eager
+     * loads applied. Throws ModelNotFoundException (→ HTTP 404) on miss.
+     *
+     * Pass \`\\$withTrashed = true\` to include soft-deleted rows — required
+     * for admin "view trashed item" / restore flows that need to resolve a
+     * row to hand to restore() or forceDelete() without bypassing this base
+     * class (#79).
+     *
+     * @throws \\Illuminate\\Database\\Eloquent\\ModelNotFoundException
+     *
+     * @example Fetch an active ${modelName}
+     *   $model = $service->findById('01h000000000000000000000000');
+     *
+     * @example Resolve a trashed ${modelName} for restore() / forceDelete()
+     *   $trashed = $service->findById('01h000000000000000000000000', withTrashed: true);
+     *   $service->restore($trashed);
+     */
+    public function findById(string $id, bool $withTrashed = false): ${modelName}
+    {
+${queryAssignment}
+        if ($withTrashed) {
+            $query->withTrashed();
+        }
+
+        return $query->findOrFail($id);
+    }`;
 }
 // ── create() ────────────────────────────────────────────────────────────────
-function buildCreateMethod(modelName, hasAuditCreatedBy, hasTranslatable, translatableFields, eagerLoad, eagerCount, defaults) {
+function buildCreateMethod(modelName, schemaName, schema, reader, hasAuditCreatedBy, hasTranslatable, translatableFields, eagerLoad, eagerCount, defaults, locales) {
     const bodyLines = [];
     // Audit (#75.3: always overwrite — never trust client-supplied audit columns)
     if (hasAuditCreatedBy) {
@@ -517,19 +960,15 @@ function buildCreateMethod(modelName, hasAuditCreatedBy, hasTranslatable, transl
         }
         bodyLines.push('');
     }
-    // Translatable
-    if (hasTranslatable) {
-        bodyLines.push(`            // -- Translatable: extract locale-keyed data --
-            $translations = $this->extractTranslations($data);
-`);
-    }
+    // #78 Step 3: compose on Astrotomic's native fill() so 'attr:locale'
+    // keys route through Translatable::fill() directly. flushTranslations()
+    // below persists any dirty translation rows even when the `saved` event
+    // hook is suppressed (seeders under WithoutModelEvents).
     bodyLines.push(`            $model = $this->model::create($data);`);
     if (hasTranslatable) {
         bodyLines.push(`
-            // -- Translatable: sync translations for all locales --
-            if (! empty($translations)) {
-                $this->syncTranslations($model, $translations);
-            }`);
+            // -- Translatable: persist sidecar rows (#78 Step 3) --
+            $this->flushTranslations($model);`);
     }
     // Return with eager load
     const loadChain = buildLoadChain(eagerLoad, eagerCount);
@@ -542,9 +981,31 @@ function buildCreateMethod(modelName, hasAuditCreatedBy, hasTranslatable, transl
         bodyLines.push(`
             return $model;`);
     }
+    const dataShape = buildWriteDataShape(schema, reader, translatableFields, locales);
+    const exampleBlock = buildWriteExampleBlock('create', modelName, schema, reader, translatableFields, locales);
     return `
     /**
-     * @param  array<string, mixed>  $data
+     * Create a new ${modelName}.
+     *
+     * Runs inside a DB transaction so partial failures roll back cleanly.
+     * Behaviour derived from the schema:${hasAuditCreatedBy ? `
+     *   - created_by_id is forced from Auth::id(); any client-supplied value
+     *     is discarded before the insert (#75 item 3 — prevents audit forgery).` : ''}${defaults.length > 0 ? `
+     *   - Schema defaults are applied for fields not present in $data.` : ''}${hasTranslatable ? `
+     *   - Translatable fields use Astrotomic's native 'attr:locale' routing
+     *     (#78 Step 3 — legacy 'translations' wrapper removed in v3.21.0).
+     *     flushTranslations() persists sidecar rows even under seeders that
+     *     run with WithoutModelEvents.` : ''}${eagerLoad.length + eagerCount.length > 0 ? `
+     *   - Eager relations are loaded onto the returned model so the caller
+     *     can render it directly.` : ''}
+     *
+     * @param array{
+${dataShape}
+     * } $data
+     *
+${exampleBlock}
+     *
+     * @throws \\Illuminate\\Database\\QueryException on constraint violation
      */
     public function create(array $data): ${modelName}
     {
@@ -554,7 +1015,7 @@ ${bodyLines.join('\n')}
     }`;
 }
 // ── update() ────────────────────────────────────────────────────────────────
-function buildUpdateMethod(modelName, hasAuditUpdatedBy, hasTranslatable, eagerLoad, eagerCount) {
+function buildUpdateMethod(modelName, schemaName, schema, reader, hasAuditUpdatedBy, hasTranslatable, eagerLoad, eagerCount, translatableFields, locales) {
     const bodyLines = [];
     if (hasAuditUpdatedBy) {
         bodyLines.push(`            // -- Audit: force updated_by from Auth (#75.3) --
@@ -564,17 +1025,14 @@ function buildUpdateMethod(modelName, hasAuditUpdatedBy, hasTranslatable, eagerL
             }
 `);
     }
-    if (hasTranslatable) {
-        bodyLines.push(`            // -- Translatable: extract and sync --
-            $translations = $this->extractTranslations($data);
-`);
-    }
+    // #78 Step 3: Astrotomic's fill() (called by ->update()) natively routes
+    // 'attr:locale' keys. flushTranslations() below persists sidecar rows so
+    // seeder-style WithoutModelEvents paths still write translation tables.
     bodyLines.push(`            $model->update($data);`);
     if (hasTranslatable) {
         bodyLines.push(`
-            if (! empty($translations)) {
-                $this->syncTranslations($model, $translations);
-            }`);
+            // -- Translatable: persist sidecar rows (#78 Step 3) --
+            $this->flushTranslations($model);`);
     }
     const loadChain = buildLoadChain(eagerLoad, eagerCount);
     if (loadChain) {
@@ -586,9 +1044,25 @@ function buildUpdateMethod(modelName, hasAuditUpdatedBy, hasTranslatable, eagerL
         bodyLines.push(`
             return $model;`);
     }
+    const dataShape = buildWriteDataShape(schema, reader, translatableFields, locales);
+    const exampleBlock = buildWriteExampleBlock('update', modelName, schema, reader, translatableFields, locales);
     return `
     /**
-     * @param  array<string, mixed>  $data
+     * Update an existing ${modelName}.
+     *
+     * Same transaction + cascade contract as create():${hasAuditUpdatedBy ? `
+     *   - updated_by_id is forced from Auth::id() (#75 item 3).` : ''}${hasTranslatable ? `
+     *   - Astrotomic's fill() routes 'attr:locale' keys through translateOrNew,
+     *     so only the locales present in $data are touched. flushTranslations()
+     *     then persists sidecar rows (seeder-safe — see #78 Step 3).` : ''}
+     *
+     * @param array{
+${dataShape}
+     * } $data
+     *
+${exampleBlock}
+     *
+     * @throws \\Illuminate\\Database\\QueryException on constraint violation
      */
     public function update(${modelName} $model, array $data): ${modelName}
     {
@@ -609,6 +1083,12 @@ function buildDeleteMethod(modelName, hasSoftDelete, hasAuditDeletedBy) {
     }
     bodyLines.push(`            return $model->delete();`);
     return `
+    /**
+     * ${hasSoftDelete ? 'Soft-delete' : 'Delete'} a ${modelName}${hasSoftDelete ? ' (moves to trash, restorable via restore())' : ''}.${hasAuditDeletedBy && hasSoftDelete ? `
+     *
+     * deleted_by_id is stamped from Auth::id() inside the same transaction
+     * so audit trails stay consistent even if the delete fails.` : ''}
+     */
     public function delete(${modelName} $model): bool
     {
         return DB::transaction(function () use ($model) {
@@ -623,6 +1103,16 @@ function buildRestoreMethod(modelName, eagerLoad, eagerCount) {
         ? `            $model->restore();\n\n            return $model\n                ${loadChain};`
         : `            $model->restore();\n\n            return $model;`;
     return `
+    /**
+     * Restore a soft-deleted ${modelName} and return it with eager loads applied.
+     *
+     * Operates on a pre-resolved model. To resolve a trashed id first,
+     * call \`findById(\\$id, withTrashed: true)\` — see #79.
+     *
+     * @example Restore a trashed ${modelName} by id
+     *   $trashed  = $service->findById('01h000000000000000000000000', withTrashed: true);
+     *   $restored = $service->restore($trashed);
+     */
     public function restore(${modelName} $model): ${modelName}
     {
         return DB::transaction(function () use ($model) {
@@ -634,6 +1124,9 @@ ${returnLine}
 function buildForceDeleteMethod(modelName, hasTranslatable) {
     if (!hasTranslatable) {
         return `
+    /**
+     * Hard-delete a ${modelName} (bypasses soft-delete, removes the row).
+     */
     public function forceDelete(${modelName} $model): bool
     {
         return DB::transaction(fn () => $model->forceDelete());
@@ -642,6 +1135,17 @@ function buildForceDeleteMethod(modelName, hasTranslatable) {
     // #75.7: explicitly drop translations inside the same transaction so the
     // service contract does not rely on the FK's ON DELETE behaviour.
     return `
+    /**
+     * Hard-delete a ${modelName} and its translation rows.
+     *
+     * We explicitly delete translations inside the transaction instead of
+     * relying on the FK's ON DELETE behaviour — the migration may or may
+     * not emit CASCADE, and we don't want forceDelete()'s correctness to
+     * depend on schema quirks (#75.7).
+     *
+     * Operates on a pre-resolved model. To resolve a trashed id first,
+     * call \`findById(\\$id, withTrashed: true)\` — see #79.
+     */
     public function forceDelete(${modelName} $model): bool
     {
         return DB::transaction(function () use ($model) {
@@ -656,6 +1160,9 @@ function buildForceDeleteMethod(modelName, hasTranslatable) {
 function buildEmptyTrashMethod(hasTranslatable) {
     if (!hasTranslatable) {
         return `
+    /**
+     * Permanently delete every trashed row. Returns rows-affected count.
+     */
     public function emptyTrash(): int
     {
         return $this->model::onlyTrashed()->forceDelete();
@@ -665,10 +1172,16 @@ function buildEmptyTrashMethod(hasTranslatable) {
     // so translations would be orphaned. Chunk through trashed rows and
     // delegate to forceDelete() which cascades explicitly.
     return `
+    /**
+     * Permanently delete every trashed row, cascading translations.
+     *
+     * Iterates via chunkById(100) and delegates to forceDelete() so the
+     * translation cascade in forceDelete() runs per row. A query-builder
+     * DELETE would be faster but would skip that cascade and orphan
+     * translation rows — see #75 followup comment.
+     */
     public function emptyTrash(): int
     {
-        // #75 followup: delegate to per-model forceDelete so the translation
-        // cascade in forceDelete() runs. A query-builder DELETE would skip it.
         $count = 0;
         $this->model::onlyTrashed()->chunkById(100, function ($batch) use (&$count) {
             foreach ($batch as $model) {
@@ -681,20 +1194,53 @@ function buildEmptyTrashMethod(hasTranslatable) {
     }`;
 }
 // ── lookup() ────────────────────────────────────────────────────────────────
-function buildLookupMethod(_modelName, lookupFields, filterableFields, defaultSort) {
-    const selectFields = lookupFields.map(f => `'${toSnakeCase(f)}'`).join(', ');
-    const returnShape = lookupFields.map(f => `${toSnakeCase(f)}: mixed`).join(', ');
-    // Sort by first non-id field or default
+function buildLookupMethod(modelName, lookupFields, filterableFields, defaultSort, tx, reader, hasSoftDelete) {
+    const snakeLookup = lookupFields.map(f => toSnakeCase(f));
+    const returnShape = snakeLookup.map(f => `${f}: mixed`).join(', ');
     const sortCol = defaultSort.replace(/^-/, '');
     const sortDir = defaultSort.startsWith('-') ? 'desc' : 'asc';
+    const translatableSet = new Set(tx.translatableFields);
+    const hasTranslatableLookup = snakeLookup.some(f => translatableSet.has(f)) ||
+        (translatableSet.has(sortCol) && tx.translationTable.length > 0);
     // Apply filterable columns — reuse buildFilterLine so Boolean handling
-    // matches list() (#75.4: `?? null` collapses `false` so lookup() silently
-    // dropped `is_hidden=false`; list() uses isset() which is correct).
+    // matches list() (#75.4).
     const filterLines = filterableFields.map(f => buildFilterLine(f));
-    return `
+    const filterBlock = filterLines.length > 0 ? filterLines.join('\n') + '\n\n' : '';
+    // #75.8: cap results (shared by both branches)
+    const limitBlock = `        // #75.8: cap results so type-ahead / dropdown endpoints never load the
+        // entire table. Caller can override via ?limit=... up to a hard ceiling.
+        $limit = min((int) ($filters['limit'] ?? 100), 500);
+        $query->limit($limit);`;
+    const lookupFilterShape = buildLookupFilterShape(filterableFields, reader, hasSoftDelete);
+    const lookupExample = buildLookupExampleBlock(modelName, filterableFields, reader);
+    // #79: soft-delete filter block for lookup() mirrors the list() logic.
+    const softDeleteBlock = hasSoftDelete
+        ? `
+        // -- SoftDelete filters (#79: mirrors list()) --
+        if (! empty($filters['only_trashed'])) {
+            $query->onlyTrashed();
+        } elseif (! empty($filters['with_trashed'])) {
+            $query->withTrashed();
+        }
+`
+        : '';
+    if (!hasTranslatableLookup) {
+        // Fast path — no translatable columns involved.
+        const selectFields = snakeLookup.map(f => `'${f}'`).join(', ');
+        return `
     /**
-     * @param  array<string, mixed>  $filters
+     * Lightweight list-projection for dropdowns, type-aheads and autocomplete.
+     *
+     * Returns a flat array of {${returnShape}} rows (never a paginator). Honours
+     * every key that list() honours for filterable columns. Default row cap
+     * is 100 (caller override via ?limit=..., hard ceiling 500 — see #75.8).
+     *
+     * @param array{
+${lookupFilterShape}
+     * } $filters
      * @return array<int, array{${returnShape}}>
+     *
+${lookupExample}
      */
     public function lookup(array $filters = []): array
     {
@@ -702,69 +1248,113 @@ function buildLookupMethod(_modelName, lookupFields, filterableFields, defaultSo
             ->select([${selectFields}])
             ->orderBy('${sortCol}', '${sortDir}');
 
-${filterLines.length > 0 ? filterLines.join('\n') + '\n' : ''}
-        // #75.8: cap results so type-ahead / dropdown endpoints never load the
-        // entire table. Caller can override via ?limit=... up to a hard ceiling.
-        $limit = min((int) ($filters['limit'] ?? 100), 500);
-        $query->limit($limit);
+${filterBlock}${softDeleteBlock}${limitBlock}
 
         return $query->get()->toArray();
     }`;
-}
-// ── extractTranslations() ───────────────────────────────────────────────────
-function buildExtractTranslationsMethod(translatableFields, locales) {
-    const fieldsArray = translatableFields.map(f => `'${f}'`).join(', ');
-    const localesArray = locales.map(l => `'${l}'`).join(', ');
+    }
+    // #76: translatable branch — leftJoin the sidecar keyed by
+    // request locale + fallback locale, COALESCE the translated columns so
+    // missing translations fall back gracefully.
+    const translatedCols = snakeLookup.filter(f => translatableSet.has(f));
+    const plainCols = snakeLookup.filter(f => !translatableSet.has(f));
+    const mainTable = tx.mainTable;
+    const trTable = tx.translationTable;
+    const fk = tx.fkColumn;
+    const selectParts = [];
+    selectParts.push(`'${mainTable}.id'`);
+    for (const col of plainCols) {
+        if (col !== 'id')
+            selectParts.push(`'${mainTable}.${col}'`);
+    }
+    // COALESCE for translatable columns
+    for (const col of translatedCols) {
+        selectParts.push(`DB::raw('COALESCE(tr_current.\`${col}\`, tr_fallback.\`${col}\`) AS \`${col}\`')`);
+    }
+    const selectList = selectParts.join(',\n                ');
+    const sortIsTranslatable = translatableSet.has(sortCol);
+    const orderByLine = sortIsTranslatable
+        ? `->orderByRaw("COALESCE(tr_current.\`${sortCol}\`, tr_fallback.\`${sortCol}\`) ${sortDir.toUpperCase()}")`
+        : `->orderBy('${mainTable}.${sortCol}', '${sortDir}')`;
     return `
     /**
-     * Extract translation data from input.
+     * Lightweight list-projection for dropdowns, type-aheads and autocomplete.
+     *
+     * Returns a flat array of {${returnShape}} rows (never a paginator). One or
+     * more of the returned columns is translatable, so this method LEFT JOINs
+     * the sidecar ${trTable} on both the request locale and the fallback
+     * locale, then COALESCEs the translated column so missing translations
+     * degrade gracefully instead of surfacing as NULL (#76).
+     *
+     * Default row cap is 100 (caller override via ?limit=..., hard ceiling
+     * 500 — see #75.8).
      *
-     * Supports two formats:
-     *   1. Flat:   { "name:ja": "テスト", "name:en": "Test" }
-     *   2. Nested: { "translations": { "ja": { "name": "テスト" }, "en": { "name": "Test" } } }
+     * @param array{
+${lookupFilterShape}
+     * } $filters
+     * @return array<int, array{${returnShape}}>
      *
-     * @return array<string, array<string, string>>  locale => [attr => value]
+${lookupExample}
      */
-    protected function extractTranslations(array &$data): array
+    public function lookup(array $filters = []): array
     {
-        $translatedAttributes = [${fieldsArray}];
-        $locales = [${localesArray}];
-        $translations = [];
-
-        // Format 2: nested "translations" key
-        if (isset($data['translations']) && is_array($data['translations'])) {
-            $translations = $data['translations'];
-            unset($data['translations']);
+        // #76: translatable columns live in '${trTable}'. Join once on the
+        // request locale and once on the configured fallback so missing
+        // translations degrade gracefully instead of returning NULL.
+        $locale = app()->getLocale();
+        $fallback = config('translatable.fallback_locale', 'en');
 
-            return $translations;
-        }
+        $query = $this->model::query()
+            ->select([
+                ${selectList},
+            ])
+            ->leftJoin('${trTable} as tr_current', function ($j) use ($locale) {
+                $j->on('tr_current.${fk}', '=', '${mainTable}.id')
+                  ->where('tr_current.locale', $locale);
+            })
+            ->leftJoin('${trTable} as tr_fallback', function ($j) use ($fallback) {
+                $j->on('tr_fallback.${fk}', '=', '${mainTable}.id')
+                  ->where('tr_fallback.locale', $fallback);
+            })
+            ${orderByLine};
 
-        // Format 1: flat "attr:locale" keys
-        foreach ($translatedAttributes as $attr) {
-            foreach ($locales as $locale) {
-                $key = "{$attr}:{$locale}";
-                if (isset($data[$key])) {
-                    $translations[$locale][$attr] = $data[$key];
-                    unset($data[$key]);
-                }
-            }
-        }
+${filterBlock}${softDeleteBlock}${limitBlock}
 
-        return $translations;
+        return $query->get()->toArray();
     }`;
 }
-// ── syncTranslations() ─────────────────────────────────────────────────────
-function buildSyncTranslationsMethod(modelName) {
+// ── flushTranslations() ────────────────────────────────────────────────────
+function buildFlushTranslationsMethod(modelName) {
+    // #78 Step 3: replaces the old extractTranslations + syncTranslations pair.
+    // Astrotomic's Translatable::fill() natively routes 'attr:locale' keys into
+    // translateOrNew($locale)->fill($attrs) so by the time we reach this helper
+    // the dirty translation models are already attached to $model->translations.
+    // Astrotomic's own `saved` event hook normally persists them, but under
+    // DatabaseSeeder::WithoutModelEvents or any code that calls
+    // Model::withoutEvents(...) that hook doesn't fire. Walking the collection
+    // and calling save() on dirty rows makes the persistence path explicit and
+    // seeder-safe.
     return `
     /**
-     * Sync translations for all provided locales.
+     * Persist pending translation rows (seeder-safe).
+     *
+     * Astrotomic's Translatable::fill() (invoked by ${modelName}::create()
+     * and ${modelName}::update()) natively routes 'attr:locale' keys into
+     * translateOrNew(\\$locale)->fill(\\$attrs), leaving the dirty translation
+     * models queued on \\$model->translations. Astrotomic's own \`saved\` event
+     * hook flushes them at runtime — but that hook is suppressed under
+     * DatabaseSeeder::WithoutModelEvents or any call to Model::withoutEvents.
+     * This helper walks the collection and saves dirty/new rows explicitly so
+     * both runtime and seeder paths write to the sidecar table.
+     *
+     * @see https://github.com/Astrotomic/laravel-translatable/blob/main/src/Translatable/Translatable.php Translatable::fill()
      */
-    protected function syncTranslations(${modelName} $model, array $translations): void
+    protected function flushTranslations(${modelName} $model): void
     {
-        foreach ($translations as $locale => $attrs) {
-            $translation = $model->translateOrNew($locale);
-            $translation->fill($attrs);
-            $translation->save();
+        foreach ($model->translations as $translation) {
+            if (! $translation->exists || $translation->isDirty()) {
+                $translation->save();
+            }
         }
     }`;
 }