@omnifyjp/omnify 3.20.0 → 3.21.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omnifyjp/omnify",
-  "version": "3.20.0",
+  "version": "3.21.1",
   "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.20.0",
-    "@omnifyjp/omnify-darwin-x64": "3.20.0",
-    "@omnifyjp/omnify-linux-x64": "3.20.0",
-    "@omnifyjp/omnify-linux-arm64": "3.20.0",
-    "@omnifyjp/omnify-win32-x64": "3.20.0"
+    "@omnifyjp/omnify-darwin-arm64": "3.21.1",
+    "@omnifyjp/omnify-darwin-x64": "3.21.1",
+    "@omnifyjp/omnify-linux-x64": "3.21.1",
+    "@omnifyjp/omnify-linux-arm64": "3.21.1",
+    "@omnifyjp/omnify-win32-x64": "3.21.1"
   }
 }

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

@@ -262,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, translationCtx));
+    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) {
@@ -291,14 +291,13 @@ function generateBaseService(name, schema, reader, config) {
     if (lookup) {
         sections.push('');
         sections.push(buildSectionComment('Lookup'));
-        sections.push(buildLookupMethod(modelName, lookupFields, filterableFields, defaultSort, translationCtx));
+        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({
@@ -341,6 +340,254 @@ 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('/**');
@@ -386,13 +633,15 @@ function buildClassDocblock(c) {
         lines.push(` *   Locales:    ${c.locales.join(', ')}`);
         lines.push(` *   Sidecar:    ${toSnakeCase(c.schemaName)}_translations (synced in create/update)`);
         lines.push(' *');
-        lines.push(' *   Input format (preferred — Astrotomic-native flat, see #78):');
+        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(' *   Legacy "translations" wrapper is accepted but deprecated — it emits');
-        lines.push(' *   a E_USER_DEPRECATED notice and will be removed in omnify v3.21.0.');
+        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).');
@@ -461,10 +710,12 @@ 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, tx) {
+function buildListMethod(modelName, searchableFields, filterableFields, sortableFields, hasSoftDelete, eagerLoad, eagerCount, defaultSort, perPage, allowedSortColumns, tx, reader) {
     const lines = [];
-    // PHPDoc with filter shape (#77: documented, @throws, intent)
-    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(`
     /**
      * List ${modelName} records with filters, search, sort and pagination.
@@ -473,7 +724,11 @@ function buildListMethod(modelName, searchableFields, filterableFields, sortable
      * unknown keys are ignored. The sort column is whitelisted against
      * searchable + filterable + standard audit columns (#75.2).
      *
-     * @param  array{${filterShape}}  $filters
+     * @param array{
+${filterShape}
+     * } $filters
+     *
+${listExample}
      */
     public function list(array $filters = []): LengthAwarePaginator
     {
@@ -631,23 +886,62 @@ function buildSortSection(_sortableFields, defaultSort, allowedSortColumns, tx)
         }`;
 }
 // ── 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) {
@@ -666,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);
@@ -691,6 +981,8 @@ 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 `
     /**
      * Create a new ${modelName}.
@@ -700,13 +992,19 @@ function buildCreateMethod(modelName, hasAuditCreatedBy, hasTranslatable, transl
      *   - 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 are extracted from either flat ("name:ja") or
-     *     nested ("translations.ja.name") input and persisted to the sidecar
-     *     translation table after the main row is inserted.` : ''}${eagerLoad.length + eagerCount.length > 0 ? `
+     *   - 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<string, mixed>  $data
+     * @param array{
+${dataShape}
+     * } $data
+     *
+${exampleBlock}
+     *
      * @throws \\Illuminate\\Database\\QueryException on constraint violation
      */
     public function create(array $data): ${modelName}
@@ -717,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) --
@@ -727,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) {
@@ -749,16 +1044,24 @@ 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 `
     /**
      * Update an existing ${modelName}.
      *
      * Same transaction + cascade contract as create():${hasAuditUpdatedBy ? `
      *   - updated_by_id is forced from Auth::id() (#75 item 3).` : ''}${hasTranslatable ? `
-     *   - Translatable fields are re-synced via translateOrNew() so only the
-     *     locales present in $data are touched; other locales remain intact.` : ''}
+     *   - 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}
      *
-     * @param  array<string, mixed>  $data
      * @throws \\Illuminate\\Database\\QueryException on constraint violation
      */
     public function update(${modelName} $model, array $data): ${modelName}
@@ -802,6 +1105,13 @@ function buildRestoreMethod(modelName, eagerLoad, eagerCount) {
     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}
     {
@@ -832,6 +1142,9 @@ function buildForceDeleteMethod(modelName, hasTranslatable) {
      * 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
     {
@@ -881,7 +1194,7 @@ function buildEmptyTrashMethod(hasTranslatable) {
     }`;
 }
 // ── lookup() ────────────────────────────────────────────────────────────────
-function buildLookupMethod(_modelName, lookupFields, filterableFields, defaultSort, tx) {
+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(/^-/, '');
@@ -898,6 +1211,19 @@ function buildLookupMethod(_modelName, lookupFields, filterableFields, defaultSo
         // 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(', ');
@@ -909,8 +1235,12 @@ function buildLookupMethod(_modelName, lookupFields, filterableFields, defaultSo
      * 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<string, mixed>  $filters
+     * @param array{
+${lookupFilterShape}
+     * } $filters
      * @return array<int, array{${returnShape}}>
+     *
+${lookupExample}
      */
     public function lookup(array $filters = []): array
     {
@@ -918,7 +1248,7 @@ function buildLookupMethod(_modelName, lookupFields, filterableFields, defaultSo
             ->select([${selectFields}])
             ->orderBy('${sortCol}', '${sortDir}');
 
-${filterBlock}${limitBlock}
+${filterBlock}${softDeleteBlock}${limitBlock}
 
         return $query->get()->toArray();
     }`;
@@ -959,8 +1289,12 @@ ${filterBlock}${limitBlock}
      * Default row cap is 100 (caller override via ?limit=..., hard ceiling
      * 500 — see #75.8).
      *
-     * @param  array<string, mixed>  $filters
+     * @param array{
+${lookupFilterShape}
+     * } $filters
      * @return array<int, array{${returnShape}}>
+     *
+${lookupExample}
      */
     public function lookup(array $filters = []): array
     {
@@ -984,82 +1318,65 @@ ${filterBlock}${limitBlock}
             })
             ${orderByLine};
 
-${filterBlock}${limitBlock}
+${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(', ');
+// ── 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.
+    //
+    // #78 Step 3 followup (v3.21.1): mirror Astrotomic's own saveTranslations()
+    // FK-assignment step (Translatable::saveTranslations:382-401) — when the
+    // parent row is created via Model::create() inside WithoutModelEvents, the
+    // new translation models are queued before the parent INSERT runs, so the
+    // belongsTo backref never fires. We must explicitly stamp the FK from the
+    // saved parent before calling $translation->save() or MySQL rejects the
+    // row with "Column 'product_id' cannot be null". Same applies to the
+    // connection name for multi-connection projects.
     return `
     /**
-     * Extract translation data from input.
-     *
-     * Preferred format (Astrotomic-native, flat):
-     *     [ "name:ja" => "テスト", "name:en" => "Test" ]
-     *
-     * Legacy format (DEPRECATED — will be removed in a future major release,
-     * see #78):
-     *     [ "translations" => [ "ja" => [ "name" => "テスト" ] ] ]
+     * Persist pending translation rows (seeder-safe).
      *
-     * The flat "attr:locale" form is what Astrotomic's own Translatable::fill()
-     * consumes natively (see Translatable::getAttributeAndLocale()), so sticking
-     * to it keeps request bodies, FormRequest rules and OpenAPI schemas flat.
+     * 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
+     * (mirroring Astrotomic's own saveTranslations()) so both runtime and
+     * seeder paths write to the sidecar table.
      *
-     * @return array<string, array<string, string>>  locale => [attr => value]
+     * @see https://github.com/Astrotomic/laravel-translatable/blob/main/src/Translatable/Translatable.php Translatable::saveTranslations()
      */
-    protected function extractTranslations(array &$data): array
+    protected function flushTranslations(${modelName} $model): void
     {
-        $translatedAttributes = [${fieldsArray}];
-        $locales = [${localesArray}];
-        $translations = [];
-
-        // Legacy wrapper format (#78 — deprecated). Still accepted for backward
-        // compat, but emits a deprecation notice so consumers migrate ahead of
-        // the v3.21.0 removal.
-        if (isset($data['translations']) && is_array($data['translations'])) {
-            @trigger_error(
-                'The "translations" wrapper input format is deprecated (omnify #78). '
-                . 'Use the flat "attr:locale" form (e.g. "name:ja" => "..." ) which '
-                . 'Astrotomic Translatable consumes natively. This path will be '
-                . 'removed in omnify v3.21.0.',
-                E_USER_DEPRECATED
-            );
-            $translations = $data['translations'];
-            unset($data['translations']);
-
-            return $translations;
-        }
-
-        // Preferred: 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]);
+        foreach ($model->translations as $translation) {
+            if (! $translation->exists || $translation->isDirty()) {
+                // Mirror Astrotomic\\Translatable\\Translatable::saveTranslations() —
+                // explicitly stamp the FK and (when set) the connection so the
+                // save works even inside Model::withoutEvents(), where the
+                // belongsTo backref never fires.
+                if (! empty($connectionName = $model->getConnectionName())) {
+                    $translation->setConnection($connectionName);
                 }
+                $translation->setAttribute(
+                    $model->getTranslationRelationKey(),
+                    $model->getKey()
+                );
+                $translation->save();
             }
         }
-
-        return $translations;
-    }`;
-}
-// ── syncTranslations() ─────────────────────────────────────────────────────
-function buildSyncTranslationsMethod(modelName) {
-    return `
-    /**
-     * Sync translations for all provided locales.
-     */
-    protected function syncTranslations(${modelName} $model, array $translations): void
-    {
-        foreach ($translations as $locale => $attrs) {
-            $translation = $model->translateOrNew($locale);
-            $translation->fill($attrs);
-            $translation->save();
-        }
     }`;
 }
 // ============================================================================