sonamu 0.8.12 → 0.8.13

package/dist/testing/parallel-db-manager.js

@@ -25,8 +25,11 @@ import { createKnexInstance } from "../database/knex.js";
             const workerDbNames = Array.from({
                 length: this.maxWorkers
             }, (_, i)=>`${this.templateDb}_${i + 1}`);
-            // 1. 기존 연결 종료 (병렬)
-            await Promise.all(workerDbNames.map((dbName)=>adminDb.raw(`
+            // 1. 기존 연결 종료 (병렬) worker DB + template DB (PG 18에서 FILE_COPY 시 template에 exclusive access 필요)
+            await Promise.all([
+                ...workerDbNames,
+                this.templateDb
+            ].map((dbName)=>adminDb.raw(`
             SELECT pg_terminate_backend(pg_stat_activity.pid)
             FROM pg_stat_activity
             WHERE pg_stat_activity.datname = ?
@@ -82,4 +85,4 @@ import { createKnexInstance } from "../database/knex.js";
     }
 }
 
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy90ZXN0aW5nL3BhcmFsbGVsLWRiLW1hbmFnZXIudHMiXSwic291cmNlc0NvbnRlbnQiOlsiaW1wb3J0IHR5cGUgeyBLbmV4IH0gZnJvbSBcImtuZXhcIjtcbmltcG9ydCB7IGNyZWF0ZUtuZXhJbnN0YW5jZSB9IGZyb20gXCIuLi9kYXRhYmFzZS9rbmV4XCI7XG5cbi8qKlxuICog67OR66CsIO2FjOyKpO2KuOulvCDsnITtlZwgV29ya2Vy67OEIERCIOq0gOumrCDtgbTrnpjsiqTsnoXri4jri6QuXG4gKlxuICogVml0ZXN07J2YIGdsb2JhbFNldHVwL2dsb2JhbFRlYXJkb3du7JeQ7IScIOyCrOyaqe2VmOyXrFxuICog7YWc7ZSM66a/IERC7JeQ7IScIHdvcmtlciDsiJjrp4ztgbwg7YWM7Iqk7Yq4IERC66W8IOuzteygnC/sgq3soJztlanri4jri6QuXG4gKi9cbmV4cG9ydCBjbGFzcyBQYXJhbGxlbERCTWFuYWdlciB7XG4gIGNvbnN0cnVjdG9yKFxuICAgIHByaXZhdGUgcmVhZG9ubHkgbWF4V29ya2VyczogbnVtYmVyLFxuICAgIHByaXZhdGUgcmVhZG9ubHkgZGJDb25maWc6IEtuZXguQ29uZmlnLFxuICAgIHByaXZhdGUgcmVhZG9ubHkgdGVtcGxhdGVEYjogc3RyaW5nLFxuICApIHt9XG4gIC8qKlxuICAgKiBXb3JrZXLrs4Qg7YWM7Iqk7Yq4IERC66W8IO2FnO2UjOumv+yXkOyEnCDrs7XsoJztlZjsl6wg7IOd7ISx7ZWp64uI64ukLlxuICAgKiBnbG9iYWxTZXR1cOyXkOyEnCDtmLjstpzrkKnri4jri6QuXG4gICAqL1xuICBhc3luYyBjcmVhdGVXb3JrZXJEYXRhYmFzZXMoKTogUHJvbWlzZTx2b2lkPiB7XG4gICAgLy8gcG9zdGdyZXMgRELsl5Ag7Jew6rKw7ZWY7JesIENSRUFURSBEQVRBQkFTRSDsi6TtlolcbiAgICBjb25zdCBhZG1pbkRiID0gY3JlYXRlS25leEluc3RhbmNlKHtcbiAgICAgIC4uLnRoaXMuZGJDb25maWcsXG4gICAgfSk7XG5cbiAgICB0cnkge1xuICAgICAgY29uc3Qgd29ya2VyRGJOYW1lcyA9IEFycmF5LmZyb20oXG4gICAgICAgIHsgbGVuZ3RoOiB0aGlzLm1heFdvcmtlcnMgfSxcbiAgICAgICAgKF8sIGkpID0+IGAke3RoaXMudGVtcGxhdGVEYn1fJHtpICsgMX1gLFxuICAgICAgKTtcblxuICAgICAgLy8gMS4g6riw7KG0IOyXsOqysCDsooXro4wgKOuzkeugrClcbiAgICAgIGF3YWl0IFByb21pc2UuYWxsKFxuICAgICAgICB3b3JrZXJEYk5hbWVzLm1hcCgoZGJOYW1lKSA9PlxuICAgICAgICAgIGFkbWluRGIucmF3KFxuICAgICAgICAgICAgYFxuICAgICAgICAgICAgU0VMRUNUIHBnX3Rlcm1pbmF0ZV9iYWNrZW5kKHBnX3N0YXRfYWN0aXZpdHkucGlkKVxuICAgICAgICAgICAgRlJPTSBwZ19zdGF0X2FjdGl2aXR5XG4gICAgICAgICAgICBXSEVSRSBwZ19zdGF0X2FjdGl2aXR5LmRhdG5hbWUgPSA/XG4gICAgICAgICAgICBBTkQgcGlkIDw+IHBnX2JhY2tlbmRfcGlkKClcbiAgICAgICAgICBgLFxuICAgICAgICAgICAgW2RiTmFtZV0sXG4gICAgICAgICAgKSxcbiAgICAgICAgKSxcbiAgICAgICk7XG5cbiAgICAgIC8vIDIuIOq4sOyhtCBEQiDsgq3soJwgKOuzkeugrClcbiAgICAgIGF3YWl0IFByb21pc2UuYWxsKFxuICAgICAgICB3b3JrZXJEYk5hbWVzLm1hcCgoZGJOYW1lKSA9PiBhZG1pbkRiLnJhdyhgRFJPUCBEQVRBQkFTRSBJRiBFWElTVFMgXCIke2RiTmFtZX1cImApKSxcbiAgICAgICk7XG5cbiAgICAgIC8vIDMuIO2FnO2UjOumv+yXkOyEnCDrs7XsoJwgKOuzkeugrClcbiAgICAgIGF3YWl0IFByb21pc2UuYWxsKFxuICAgICAgICB3b3JrZXJEYk5hbWVzLm1hcCgoZGJOYW1lKSA9PlxuICAgICAgICAgIGFkbWluRGIucmF3KFxuICAgICAgICAgICAgYENSRUFURSBEQVRBQkFTRSBcIiR7ZGJOYW1lfVwiIFRFTVBMQVRFIFwiJHt0aGlzLnRlbXBsYXRlRGJ9XCIgU1RSQVRFR1kgRklMRV9DT1BZYCxcbiAgICAgICAgICApLFxuICAgICAgICApLFxuICAgICAgKTtcbiAgICB9IGZpbmFsbHkge1xuICAgICAgYXdhaXQgYWRtaW5EYi5kZXN0cm95KCk7XG4gICAgfVxuICB9XG5cbiAgLyoqXG4gICAqIOyDneyEse2VnCBXb3JrZXIgRELrk6TsnYQg7IKt7KCc7ZWp64uI64ukLlxuICAgKiBnbG9iYWxUZWFyZG93buyXkOyEnCDtmLjstpzrkKnri4jri6QuXG4gICAqL1xuICBhc3luYyBkcm9wV29ya2VyRGF0YWJhc2VzKCk6IFByb21pc2U8dm9pZD4ge1xuICAgIGNvbnN0IGFkbWluRGIgPSBjcmVhdGVLbmV4SW5zdGFuY2Uoe1xuICAgICAgLi4udGhpcy5kYkNvbmZpZyxcbiAgICB9KTtcblxuICAgIHRyeSB7XG4gICAgICBjb25zdCB3b3JrZXJEYk5hbWVzID0gQXJyYXkuZnJvbShcbiAgICAgICAgeyBsZW5ndGg6IHRoaXMubWF4V29ya2VycyB9LFxuICAgICAgICAoXywgaSkgPT4gYCR7dGhpcy50ZW1wbGF0ZURifV8ke2kgKyAxfWAsXG4gICAgICApO1xuXG4gICAgICAvLyDsl7DqsrAg7KKF66OMICjrs5HroKwpXG4gICAgICBhd2FpdCBQcm9taXNlLmFsbChcbiAgICAgICAgd29ya2VyRGJOYW1lcy5tYXAoKGRiTmFtZSkgPT5cbiAgICAgICAgICBhZG1pbkRiLnJhdyhcbiAgICAgICAgICAgIGBcbiAgICAgICAgICAgIFNFTEVDVCBwZ190ZXJtaW5hdGVfYmFja2VuZChwZ19zdGF0X2FjdGl2aXR5LnBpZClcbiAgICAgICAgICAgIEZST00gcGdfc3RhdF9hY3Rpdml0eVxuICAgICAgICAgICAgV0hFUkUgcGdfc3RhdF9hY3Rpdml0eS5kYXRuYW1lID0gP1xuICAgICAgICAgICAgQU5EIHBpZCA8PiBwZ19iYWNrZW5kX3BpZCgpXG4gICAgICAgICAgYCxcbiAgICAgICAgICAgIFtkYk5hbWVdLFxuICAgICAgICAgICksXG4gICAgICAgICksXG4gICAgICApO1xuXG4gICAgICAvLyBEQiDsgq3soJwgKOuzkeugrClcbiAgICAgIGF3YWl0IFByb21pc2UuYWxsKFxuICAgICAgICB3b3JrZXJEYk5hbWVzLm1hcCgoZGJOYW1lKSA9PiBhZG1pbkRiLnJhdyhgRFJPUCBEQVRBQkFTRSBJRiBFWElTVFMgXCIke2RiTmFtZX1cImApKSxcbiAgICAgICk7XG4gICAgfSBmaW5hbGx5IHtcbiAgICAgIGF3YWl0IGFkbWluRGIuZGVzdHJveSgpO1xuICAgIH1cbiAgfVxuXG4gIC8qKlxuICAgKiDtmITsnqwgV29ya2Vy7J2YIElE66W8IOuwmO2ZmO2VqeuLiOuLpC5cbiAgICogVml0ZXN064qUIFZJVEVTVF9QT09MX0lEIO2ZmOqyveuzgOyImOuhnCB3b3JrZXLrpbwg7Iud67OE7ZWp64uI64ukLlxuICAgKi9cbiAgZ2V0V29ya2VySWQoKTogbnVtYmVyIHtcbiAgICAvLyBWSVRFU1RfUE9PTF9JROuKlCAx67aA7YSwIOyLnOyekVxuICAgIHJldHVybiBwYXJzZUludChwcm9jZXNzLmVudi5WSVRFU1RfUE9PTF9JRCA/PyBcIjFcIiwgMTApO1xuICB9XG5cbiAgLyoqXG4gICAqIOuzkeugrCDthYzsiqTtirgg66qo65Oc7J247KeAIO2ZleyduO2VqeuLiOuLpC5cbiAgICovXG4gIGlzUGFyYWxsZWxNb2RlKCk6IGJvb2xlYW4ge1xuICAgIHJldHVybiBwcm9jZXNzLmVudi5TT05BTVVfV09SS0VSX0RCID09PSBcInRydWVcIjtcbiAgfVxufVxuIl0sIm5hbWVzIjpbImNyZWF0ZUtuZXhJbnN0YW5jZSIsIlBhcmFsbGVsREJNYW5hZ2VyIiwibWF4V29ya2VycyIsImRiQ29uZmlnIiwidGVtcGxhdGVEYiIsImNyZWF0ZVdvcmtlckRhdGFiYXNlcyIsImFkbWluRGIiLCJ3b3JrZXJEYk5hbWVzIiwiQXJyYXkiLCJmcm9tIiwibGVuZ3RoIiwiXyIsImkiLCJQcm9taXNlIiwiYWxsIiwibWFwIiwiZGJOYW1lIiwicmF3IiwiZGVzdHJveSIsImRyb3BXb3JrZXJEYXRhYmFzZXMiLCJnZXRXb3JrZXJJZCIsInBhcnNlSW50IiwicHJvY2VzcyIsImVudiIsIlZJVEVTVF9QT09MX0lEIiwiaXNQYXJhbGxlbE1vZGUiLCJTT05BTVVfV09SS0VSX0RCIl0sIm1hcHBpbmdzIjoiQUFDQSxTQUFTQSxrQkFBa0IsUUFBUSxzQkFBbUI7QUFFdEQ7Ozs7O0NBS0MsR0FDRCxPQUFPLE1BQU1DOzs7O0lBQ1gsWUFDRSxBQUFpQkMsVUFBa0IsRUFDbkMsQUFBaUJDLFFBQXFCLEVBQ3RDLEFBQWlCQyxVQUFrQixDQUNuQzthQUhpQkYsYUFBQUE7YUFDQUMsV0FBQUE7YUFDQUMsYUFBQUE7SUFDaEI7SUFDSDs7O0dBR0MsR0FDRCxNQUFNQyx3QkFBdUM7UUFDM0MsdUNBQXVDO1FBQ3ZDLE1BQU1DLFVBQVVOLG1CQUFtQjtZQUNqQyxHQUFHLElBQUksQ0FBQ0csUUFBUTtRQUNsQjtRQUVBLElBQUk7WUFDRixNQUFNSSxnQkFBZ0JDLE1BQU1DLElBQUksQ0FDOUI7Z0JBQUVDLFFBQVEsSUFBSSxDQUFDUixVQUFVO1lBQUMsR0FDMUIsQ0FBQ1MsR0FBR0MsSUFBTSxHQUFHLElBQUksQ0FBQ1IsVUFBVSxDQUFDLENBQUMsRUFBRVEsSUFBSSxHQUFHO1lBR3pDLG1CQUFtQjtZQUNuQixNQUFNQyxRQUFRQyxHQUFHLENBQ2ZQLGNBQWNRLEdBQUcsQ0FBQyxDQUFDQyxTQUNqQlYsUUFBUVcsR0FBRyxDQUNULENBQUM7Ozs7O1VBS0gsQ0FBQyxFQUNDO29CQUFDRDtpQkFBTztZQUtkLG1CQUFtQjtZQUNuQixNQUFNSCxRQUFRQyxHQUFHLENBQ2ZQLGNBQWNRLEdBQUcsQ0FBQyxDQUFDQyxTQUFXVixRQUFRVyxHQUFHLENBQUMsQ0FBQyx5QkFBeUIsRUFBRUQsT0FBTyxDQUFDLENBQUM7WUFHakYsbUJBQW1CO1lBQ25CLE1BQU1ILFFBQVFDLEdBQUcsQ0FDZlAsY0FBY1EsR0FBRyxDQUFDLENBQUNDLFNBQ2pCVixRQUFRVyxHQUFHLENBQ1QsQ0FBQyxpQkFBaUIsRUFBRUQsT0FBTyxZQUFZLEVBQUUsSUFBSSxDQUFDWixVQUFVLENBQUMsb0JBQW9CLENBQUM7UUFJdEYsU0FBVTtZQUNSLE1BQU1FLFFBQVFZLE9BQU87UUFDdkI7SUFDRjtJQUVBOzs7R0FHQyxHQUNELE1BQU1DLHNCQUFxQztRQUN6QyxNQUFNYixVQUFVTixtQkFBbUI7WUFDakMsR0FBRyxJQUFJLENBQUNHLFFBQVE7UUFDbEI7UUFFQSxJQUFJO1lBQ0YsTUFBTUksZ0JBQWdCQyxNQUFNQyxJQUFJLENBQzlCO2dCQUFFQyxRQUFRLElBQUksQ0FBQ1IsVUFBVTtZQUFDLEdBQzFCLENBQUNTLEdBQUdDLElBQU0sR0FBRyxJQUFJLENBQUNSLFVBQVUsQ0FBQyxDQUFDLEVBQUVRLElBQUksR0FBRztZQUd6QyxhQUFhO1lBQ2IsTUFBTUMsUUFBUUMsR0FBRyxDQUNmUCxjQUFjUSxHQUFHLENBQUMsQ0FBQ0MsU0FDakJWLFFBQVFXLEdBQUcsQ0FDVCxDQUFDOzs7OztVQUtILENBQUMsRUFDQztvQkFBQ0Q7aUJBQU87WUFLZCxhQUFhO1lBQ2IsTUFBTUgsUUFBUUMsR0FBRyxDQUNmUCxjQUFjUSxHQUFHLENBQUMsQ0FBQ0MsU0FBV1YsUUFBUVcsR0FBRyxDQUFDLENBQUMseUJBQXlCLEVBQUVELE9BQU8sQ0FBQyxDQUFDO1FBRW5GLFNBQVU7WUFDUixNQUFNVixRQUFRWSxPQUFPO1FBQ3ZCO0lBQ0Y7SUFFQTs7O0dBR0MsR0FDREUsY0FBc0I7UUFDcEIseUJBQXlCO1FBQ3pCLE9BQU9DLFNBQVNDLFFBQVFDLEdBQUcsQ0FBQ0MsY0FBYyxJQUFJLEtBQUs7SUFDckQ7SUFFQTs7R0FFQyxHQUNEQyxpQkFBMEI7UUFDeEIsT0FBT0gsUUFBUUMsR0FBRyxDQUFDRyxnQkFBZ0IsS0FBSztJQUMxQztBQUNGIn0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy90ZXN0aW5nL3BhcmFsbGVsLWRiLW1hbmFnZXIudHMiXSwic291cmNlc0NvbnRlbnQiOlsiaW1wb3J0IHR5cGUgeyBLbmV4IH0gZnJvbSBcImtuZXhcIjtcbmltcG9ydCB7IGNyZWF0ZUtuZXhJbnN0YW5jZSB9IGZyb20gXCIuLi9kYXRhYmFzZS9rbmV4XCI7XG5cbi8qKlxuICog67OR66CsIO2FjOyKpO2KuOulvCDsnITtlZwgV29ya2Vy67OEIERCIOq0gOumrCDtgbTrnpjsiqTsnoXri4jri6QuXG4gKlxuICogVml0ZXN07J2YIGdsb2JhbFNldHVwL2dsb2JhbFRlYXJkb3du7JeQ7IScIOyCrOyaqe2VmOyXrFxuICog7YWc7ZSM66a/IERC7JeQ7IScIHdvcmtlciDsiJjrp4ztgbwg7YWM7Iqk7Yq4IERC66W8IOuzteygnC/sgq3soJztlanri4jri6QuXG4gKi9cbmV4cG9ydCBjbGFzcyBQYXJhbGxlbERCTWFuYWdlciB7XG4gIGNvbnN0cnVjdG9yKFxuICAgIHByaXZhdGUgcmVhZG9ubHkgbWF4V29ya2VyczogbnVtYmVyLFxuICAgIHByaXZhdGUgcmVhZG9ubHkgZGJDb25maWc6IEtuZXguQ29uZmlnLFxuICAgIHByaXZhdGUgcmVhZG9ubHkgdGVtcGxhdGVEYjogc3RyaW5nLFxuICApIHt9XG4gIC8qKlxuICAgKiBXb3JrZXLrs4Qg7YWM7Iqk7Yq4IERC66W8IO2FnO2UjOumv+yXkOyEnCDrs7XsoJztlZjsl6wg7IOd7ISx7ZWp64uI64ukLlxuICAgKiBnbG9iYWxTZXR1cOyXkOyEnCDtmLjstpzrkKnri4jri6QuXG4gICAqL1xuICBhc3luYyBjcmVhdGVXb3JrZXJEYXRhYmFzZXMoKTogUHJvbWlzZTx2b2lkPiB7XG4gICAgLy8gcG9zdGdyZXMgRELsl5Ag7Jew6rKw7ZWY7JesIENSRUFURSBEQVRBQkFTRSDsi6TtlolcbiAgICBjb25zdCBhZG1pbkRiID0gY3JlYXRlS25leEluc3RhbmNlKHtcbiAgICAgIC4uLnRoaXMuZGJDb25maWcsXG4gICAgfSk7XG5cbiAgICB0cnkge1xuICAgICAgY29uc3Qgd29ya2VyRGJOYW1lcyA9IEFycmF5LmZyb20oXG4gICAgICAgIHsgbGVuZ3RoOiB0aGlzLm1heFdvcmtlcnMgfSxcbiAgICAgICAgKF8sIGkpID0+IGAke3RoaXMudGVtcGxhdGVEYn1fJHtpICsgMX1gLFxuICAgICAgKTtcblxuICAgICAgLy8gMS4g6riw7KG0IOyXsOqysCDsooXro4wgKOuzkeugrCkgd29ya2VyIERCICsgdGVtcGxhdGUgREIgKFBHIDE47JeQ7IScIEZJTEVfQ09QWSDsi5wgdGVtcGxhdGXsl5AgZXhjbHVzaXZlIGFjY2VzcyDtlYTsmpQpXG4gICAgICBhd2FpdCBQcm9taXNlLmFsbChcbiAgICAgICAgWy4uLndvcmtlckRiTmFtZXMsIHRoaXMudGVtcGxhdGVEYl0ubWFwKChkYk5hbWUpID0+XG4gICAgICAgICAgYWRtaW5EYi5yYXcoXG4gICAgICAgICAgICBgXG4gICAgICAgICAgICBTRUxFQ1QgcGdfdGVybWluYXRlX2JhY2tlbmQocGdfc3RhdF9hY3Rpdml0eS5waWQpXG4gICAgICAgICAgICBGUk9NIHBnX3N0YXRfYWN0aXZpdHlcbiAgICAgICAgICAgIFdIRVJFIHBnX3N0YXRfYWN0aXZpdHkuZGF0bmFtZSA9ID9cbiAgICAgICAgICAgIEFORCBwaWQgPD4gcGdfYmFja2VuZF9waWQoKVxuICAgICAgICAgIGAsXG4gICAgICAgICAgICBbZGJOYW1lXSxcbiAgICAgICAgICApLFxuICAgICAgICApLFxuICAgICAgKTtcblxuICAgICAgLy8gMi4g6riw7KG0IERCIOyCreygnCAo67OR66CsKVxuICAgICAgYXdhaXQgUHJvbWlzZS5hbGwoXG4gICAgICAgIHdvcmtlckRiTmFtZXMubWFwKChkYk5hbWUpID0+IGFkbWluRGIucmF3KGBEUk9QIERBVEFCQVNFIElGIEVYSVNUUyBcIiR7ZGJOYW1lfVwiYCkpLFxuICAgICAgKTtcblxuICAgICAgLy8gMy4g7YWc7ZSM66a/7JeQ7IScIOuzteygnCAo67OR66CsKVxuICAgICAgYXdhaXQgUHJvbWlzZS5hbGwoXG4gICAgICAgIHdvcmtlckRiTmFtZXMubWFwKChkYk5hbWUpID0+XG4gICAgICAgICAgYWRtaW5EYi5yYXcoXG4gICAgICAgICAgICBgQ1JFQVRFIERBVEFCQVNFIFwiJHtkYk5hbWV9XCIgVEVNUExBVEUgXCIke3RoaXMudGVtcGxhdGVEYn1cIiBTVFJBVEVHWSBGSUxFX0NPUFlgLFxuICAgICAgICAgICksXG4gICAgICAgICksXG4gICAgICApO1xuICAgIH0gZmluYWxseSB7XG4gICAgICBhd2FpdCBhZG1pbkRiLmRlc3Ryb3koKTtcbiAgICB9XG4gIH1cblxuICAvKipcbiAgICog7IOd7ISx7ZWcIFdvcmtlciBEQuuTpOydhCDsgq3soJztlanri4jri6QuXG4gICAqIGdsb2JhbFRlYXJkb3du7JeQ7IScIO2YuOy2nOuQqeuLiOuLpC5cbiAgICovXG4gIGFzeW5jIGRyb3BXb3JrZXJEYXRhYmFzZXMoKTogUHJvbWlzZTx2b2lkPiB7XG4gICAgY29uc3QgYWRtaW5EYiA9IGNyZWF0ZUtuZXhJbnN0YW5jZSh7XG4gICAgICAuLi50aGlzLmRiQ29uZmlnLFxuICAgIH0pO1xuXG4gICAgdHJ5IHtcbiAgICAgIGNvbnN0IHdvcmtlckRiTmFtZXMgPSBBcnJheS5mcm9tKFxuICAgICAgICB7IGxlbmd0aDogdGhpcy5tYXhXb3JrZXJzIH0sXG4gICAgICAgIChfLCBpKSA9PiBgJHt0aGlzLnRlbXBsYXRlRGJ9XyR7aSArIDF9YCxcbiAgICAgICk7XG5cbiAgICAgIC8vIOyXsOqysCDsooXro4wgKOuzkeugrClcbiAgICAgIGF3YWl0IFByb21pc2UuYWxsKFxuICAgICAgICB3b3JrZXJEYk5hbWVzLm1hcCgoZGJOYW1lKSA9PlxuICAgICAgICAgIGFkbWluRGIucmF3KFxuICAgICAgICAgICAgYFxuICAgICAgICAgICAgU0VMRUNUIHBnX3Rlcm1pbmF0ZV9iYWNrZW5kKHBnX3N0YXRfYWN0aXZpdHkucGlkKVxuICAgICAgICAgICAgRlJPTSBwZ19zdGF0X2FjdGl2aXR5XG4gICAgICAgICAgICBXSEVSRSBwZ19zdGF0X2FjdGl2aXR5LmRhdG5hbWUgPSA/XG4gICAgICAgICAgICBBTkQgcGlkIDw+IHBnX2JhY2tlbmRfcGlkKClcbiAgICAgICAgICBgLFxuICAgICAgICAgICAgW2RiTmFtZV0sXG4gICAgICAgICAgKSxcbiAgICAgICAgKSxcbiAgICAgICk7XG5cbiAgICAgIC8vIERCIOyCreygnCAo67OR66CsKVxuICAgICAgYXdhaXQgUHJvbWlzZS5hbGwoXG4gICAgICAgIHdvcmtlckRiTmFtZXMubWFwKChkYk5hbWUpID0+IGFkbWluRGIucmF3KGBEUk9QIERBVEFCQVNFIElGIEVYSVNUUyBcIiR7ZGJOYW1lfVwiYCkpLFxuICAgICAgKTtcbiAgICB9IGZpbmFsbHkge1xuICAgICAgYXdhaXQgYWRtaW5EYi5kZXN0cm95KCk7XG4gICAgfVxuICB9XG5cbiAgLyoqXG4gICAqIO2YhOyerCBXb3JrZXLsnZggSUTrpbwg67CY7ZmY7ZWp64uI64ukLlxuICAgKiBWaXRlc3TripQgVklURVNUX1BPT0xfSUQg7ZmY6rK967OA7IiY66GcIHdvcmtlcuulvCDsi53rs4Ttlanri4jri6QuXG4gICAqL1xuICBnZXRXb3JrZXJJZCgpOiBudW1iZXIge1xuICAgIC8vIFZJVEVTVF9QT09MX0lE64qUIDHrtoDthLAg7Iuc7J6RXG4gICAgcmV0dXJuIHBhcnNlSW50KHByb2Nlc3MuZW52LlZJVEVTVF9QT09MX0lEID8/IFwiMVwiLCAxMCk7XG4gIH1cblxuICAvKipcbiAgICog67OR66CsIO2FjOyKpO2KuCDrqqjrk5zsnbjsp4Ag7ZmV7J247ZWp64uI64ukLlxuICAgKi9cbiAgaXNQYXJhbGxlbE1vZGUoKTogYm9vbGVhbiB7XG4gICAgcmV0dXJuIHByb2Nlc3MuZW52LlNPTkFNVV9XT1JLRVJfREIgPT09IFwidHJ1ZVwiO1xuICB9XG59XG4iXSwibmFtZXMiOlsiY3JlYXRlS25leEluc3RhbmNlIiwiUGFyYWxsZWxEQk1hbmFnZXIiLCJtYXhXb3JrZXJzIiwiZGJDb25maWciLCJ0ZW1wbGF0ZURiIiwiY3JlYXRlV29ya2VyRGF0YWJhc2VzIiwiYWRtaW5EYiIsIndvcmtlckRiTmFtZXMiLCJBcnJheSIsImZyb20iLCJsZW5ndGgiLCJfIiwiaSIsIlByb21pc2UiLCJhbGwiLCJtYXAiLCJkYk5hbWUiLCJyYXciLCJkZXN0cm95IiwiZHJvcFdvcmtlckRhdGFiYXNlcyIsImdldFdvcmtlcklkIiwicGFyc2VJbnQiLCJwcm9jZXNzIiwiZW52IiwiVklURVNUX1BPT0xfSUQiLCJpc1BhcmFsbGVsTW9kZSIsIlNPTkFNVV9XT1JLRVJfREIiXSwibWFwcGluZ3MiOiJBQUNBLFNBQVNBLGtCQUFrQixRQUFRLHNCQUFtQjtBQUV0RDs7Ozs7Q0FLQyxHQUNELE9BQU8sTUFBTUM7Ozs7SUFDWCxZQUNFLEFBQWlCQyxVQUFrQixFQUNuQyxBQUFpQkMsUUFBcUIsRUFDdEMsQUFBaUJDLFVBQWtCLENBQ25DO2FBSGlCRixhQUFBQTthQUNBQyxXQUFBQTthQUNBQyxhQUFBQTtJQUNoQjtJQUNIOzs7R0FHQyxHQUNELE1BQU1DLHdCQUF1QztRQUMzQyx1Q0FBdUM7UUFDdkMsTUFBTUMsVUFBVU4sbUJBQW1CO1lBQ2pDLEdBQUcsSUFBSSxDQUFDRyxRQUFRO1FBQ2xCO1FBRUEsSUFBSTtZQUNGLE1BQU1JLGdCQUFnQkMsTUFBTUMsSUFBSSxDQUM5QjtnQkFBRUMsUUFBUSxJQUFJLENBQUNSLFVBQVU7WUFBQyxHQUMxQixDQUFDUyxHQUFHQyxJQUFNLEdBQUcsSUFBSSxDQUFDUixVQUFVLENBQUMsQ0FBQyxFQUFFUSxJQUFJLEdBQUc7WUFHekMsK0ZBQStGO1lBQy9GLE1BQU1DLFFBQVFDLEdBQUcsQ0FDZjttQkFBSVA7Z0JBQWUsSUFBSSxDQUFDSCxVQUFVO2FBQUMsQ0FBQ1csR0FBRyxDQUFDLENBQUNDLFNBQ3ZDVixRQUFRVyxHQUFHLENBQ1QsQ0FBQzs7Ozs7VUFLSCxDQUFDLEVBQ0M7b0JBQUNEO2lCQUFPO1lBS2QsbUJBQW1CO1lBQ25CLE1BQU1ILFFBQVFDLEdBQUcsQ0FDZlAsY0FBY1EsR0FBRyxDQUFDLENBQUNDLFNBQVdWLFFBQVFXLEdBQUcsQ0FBQyxDQUFDLHlCQUF5QixFQUFFRCxPQUFPLENBQUMsQ0FBQztZQUdqRixtQkFBbUI7WUFDbkIsTUFBTUgsUUFBUUMsR0FBRyxDQUNmUCxjQUFjUSxHQUFHLENBQUMsQ0FBQ0MsU0FDakJWLFFBQVFXLEdBQUcsQ0FDVCxDQUFDLGlCQUFpQixFQUFFRCxPQUFPLFlBQVksRUFBRSxJQUFJLENBQUNaLFVBQVUsQ0FBQyxvQkFBb0IsQ0FBQztRQUl0RixTQUFVO1lBQ1IsTUFBTUUsUUFBUVksT0FBTztRQUN2QjtJQUNGO0lBRUE7OztHQUdDLEdBQ0QsTUFBTUMsc0JBQXFDO1FBQ3pDLE1BQU1iLFVBQVVOLG1CQUFtQjtZQUNqQyxHQUFHLElBQUksQ0FBQ0csUUFBUTtRQUNsQjtRQUVBLElBQUk7WUFDRixNQUFNSSxnQkFBZ0JDLE1BQU1DLElBQUksQ0FDOUI7Z0JBQUVDLFFBQVEsSUFBSSxDQUFDUixVQUFVO1lBQUMsR0FDMUIsQ0FBQ1MsR0FBR0MsSUFBTSxHQUFHLElBQUksQ0FBQ1IsVUFBVSxDQUFDLENBQUMsRUFBRVEsSUFBSSxHQUFHO1lBR3pDLGFBQWE7WUFDYixNQUFNQyxRQUFRQyxHQUFHLENBQ2ZQLGNBQWNRLEdBQUcsQ0FBQyxDQUFDQyxTQUNqQlYsUUFBUVcsR0FBRyxDQUNULENBQUM7Ozs7O1VBS0gsQ0FBQyxFQUNDO29CQUFDRDtpQkFBTztZQUtkLGFBQWE7WUFDYixNQUFNSCxRQUFRQyxHQUFHLENBQ2ZQLGNBQWNRLEdBQUcsQ0FBQyxDQUFDQyxTQUFXVixRQUFRVyxHQUFHLENBQUMsQ0FBQyx5QkFBeUIsRUFBRUQsT0FBTyxDQUFDLENBQUM7UUFFbkYsU0FBVTtZQUNSLE1BQU1WLFFBQVFZLE9BQU87UUFDdkI7SUFDRjtJQUVBOzs7R0FHQyxHQUNERSxjQUFzQjtRQUNwQix5QkFBeUI7UUFDekIsT0FBT0MsU0FBU0MsUUFBUUMsR0FBRyxDQUFDQyxjQUFjLElBQUksS0FBSztJQUNyRDtJQUVBOztHQUVDLEdBQ0RDLGlCQUEwQjtRQUN4QixPQUFPSCxRQUFRQyxHQUFHLENBQUNHLGdCQUFnQixLQUFLO0lBQzFDO0FBQ0YifQ==

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sonamu",
-  "version": "0.8.12",
+  "version": "0.8.13",
   "description": "Sonamu — TypeScript Fullstack API Framework",
   "keywords": [
     "typescript",
@@ -76,8 +76,8 @@
     "@aws-sdk/client-s3": "^3.958.0",
     "@aws-sdk/lib-storage": "^3.971.0",
     "@aws-sdk/s3-request-presigner": "^3.958.0",
-    "@better-auth/passkey": "^1.4.18",
-    "@better-auth/sso": "^1.4.18",
+    "@better-auth/passkey": "~1.4.18",
+    "@better-auth/sso": "~1.4.18",
     "@biomejs/js-api": "^4.0.0",
     "@biomejs/wasm-nodejs": "^2.3.7",
     "@faker-js/faker": "^9.2.0",
@@ -96,7 +96,7 @@
     "@swc/core": "^1.13.5",
     "bcrypt": "^6.0.0",
     "bentocache": "^1.5.0",
-    "better-auth": "^1.4.18",
+    "better-auth": "~1.4.18",
     "chalk": "^4.1.2",
     "chokidar": "^4.0.3",
     "date-fns-tz": "^3.2.0",
@@ -120,9 +120,9 @@
     "vite": "7.3.0",
     "vitest": "^4.0.10",
     "@sonamu-kit/hmr-hook": "^0.4.1",
+    "@sonamu-kit/hmr-runner": "^0.1.1",
     "@sonamu-kit/ts-loader": "^2.1.3",
-    "@sonamu-kit/tasks": "^0.2.0",
-    "@sonamu-kit/hmr-runner": "^0.1.1"
+    "@sonamu-kit/tasks": "^0.2.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.3.13",
@@ -143,12 +143,12 @@
     "@ai-sdk/openai": "^3.0.0",
     "@ai-sdk/provider": "^3.0.0",
     "@ai-sdk/provider-utils": "^4.0.0",
-    "@better-auth/passkey": "^1.4.18",
-    "@better-auth/sso": "^1.4.18",
+    "@better-auth/passkey": "~1.4.18",
+    "@better-auth/sso": "~1.4.18",
     "@swc/cli": "^0.7.8",
     "@swc/core": "^1.13.5",
     "ai": "^6.0.1",
-    "better-auth": "^1.4.18",
+    "better-auth": "~1.4.18",
     "fastify": "^4",
     "ioredis": "^5.8.2",
     "knex": "^3.1.0",

package/src/skills/sonamu/SKILL.md

@@ -27,6 +27,7 @@ Sonamu 프레임워크로 프로젝트를 개발하기 위한 Claude Code skill
 
 ```
 PHASE 0: 프로젝트 생성 및 초기 설정  (프로젝트 생성 → requirements.md/business-logic.md 작성 → auth generate → Users 시퀀스 설정)
+PHASE 0.5: Contract 및 Spec 작성   (main.contract.json → 도메인별 contract → spec → 사용자 검토 완료)
 PHASE 1: 엔티티 설계                (사용자와 함께 설계 확인)
 PHASE 2: 엔티티 생성 및 마이그레이션  (entity.json + migration + cone + scaffolding)
 PHASE 3: 테스트 및 API 구현          (batch별 테스트 → API 구현 반복)
@@ -43,7 +44,8 @@ PHASE 5: Frontend 개발              (batch별 진행, 사용자 확인)
 | 사용자 지시 | 시작 PHASE | 전제 조건 확인 |
 |------------|------------|----------------|
 | "새 프로젝트 만들어줘" | PHASE 0 | — |
-| "엔티티 추가해줘" / "엔티티 생성해줘" | PHASE 1 | 프로젝트 존재, dev 서버 실행 중, skills/project/ 문서 읽기 |
+| "contract 작성해줘" / "spec 작성해줘" | PHASE 0.5 | requirements.md, business-logic.md 존재 |
+| "엔티티 추가해줘" / "엔티티 생성해줘" | PHASE 1 | 프로젝트 존재, dev 서버 실행 중, skills/project/ 문서 읽기, contract/spec 완료 |
 | "테스트 작성해줘" / "API 구현해줘" | PHASE 3 | entity.json 존재, migration 완료, scaffolding 완료 |
 | "fixture 생성해줘" | PHASE 4 | 테스트 통과, cone.note 존재 확인 |
 | "프론트엔드 개발해줘" | PHASE 5 | API 구현 완료 |
@@ -221,6 +223,7 @@ confirmed → cancelled (환자/의사 취소, 24시간 전까지만)
 | Skill | 파일 | 용도 |
 |-------|------|------|
 | **전체 워크플로우** | `workflow.md` | **엔티티 설계 → Frontend 개발 7단계 가이드** |
+| **CDD (Contract-Driven Dev)** | `cdd.md` | **main.contract.json, 도메인 contract, spec 작성 절차** |
 | 프로젝트 생성 | `create-sonamu.md` | create-sonamu CLI 옵션 |
 | 프로젝트 초기화 | `project-init.md` | 프로젝트 생성 여부 확인, 대화 흐름 |
 | 프로젝트 설정 | `config.md` | .env, sonamu.config.ts 설정 |
@@ -257,6 +260,7 @@ confirmed → cancelled (환자/의사 취소, 24시간 전까지만)
 | 작업 | 참고 Skill |
 |------|-----------|
 | **처음부터 전체 시스템 개발** | **workflow.md (7단계 마스터 가이드)** |
+| **Contract/Spec 작성** | **cdd.md** |
 | 프로젝트 생성 | create-sonamu, project-init |
 | 프로젝트 설정 | config |
 | Sonamu 로컬 개발 설정 | config |

package/src/skills/sonamu/api.md

@@ -94,6 +94,32 @@ async me(): Promise<User | null> {
 
 ## 파일 업로드 (@upload)
 
+> **CRITICAL: `@upload`는 `@api` 없이 단독으로 사용한다.**
+> `@upload`를 붙이면 POST 엔드포인트와 `axios-multipart`/`tanstack-mutation-multipart` 클라이언트가 **자동 생성**된다.
+> `@api`를 함께 붙이면 `checkSingleDecorator` 충돌로 **빌드 에러**가 발생한다.
+
+```typescript
+// ✅ CORRECT
+@upload({ limits: { files: 10 }, guards: ["user"] })
+async upload(...): Promise<number[]> { }
+
+// ❌ WRONG — 빌드 에러 발생
+@api({ httpMethod: "POST", clients: ["axios-multipart"] })
+@upload({ limits: { files: 10 } })
+async upload(...): Promise<number[]> { }
+```
+
+**`@upload` 지원 옵션** (`httpMethod`, `clients`는 지원하지 않음 — 자동 설정됨)
+
+| 옵션 | 설명 |
+|------|------|
+| `guards` | 인증/권한 가드 |
+| `limits` | 파일 개수/크기 제한 (`{ files: N }`) |
+| `consume` | `"buffer"` (기본) 또는 `"stream"` |
+| `description` | API 문서 설명 |
+| `destination` | 스트림 모드 전용: 스토리지 드라이버 키 |
+| `keyGenerator` | 스트림 모드 전용: 저장 경로 생성 함수 |
+
 ### 버퍼 모드 (기본)
 
 ```typescript

package/src/skills/sonamu/auth.md

@@ -35,7 +35,7 @@ pnpm sonamu auth generate
 
 ## 필드 매핑 (자동 적용)
 
-**소스코드:** `modules/sonamu/src/auth/better-auth-entities.ts` (SONAMU_FIELD_MAPPINGS)
+**소스코드:** `modules/sonamu/src/auth/better-auth-entities.ts` (BASE_FIELD_MAPPINGS)
 
 | better-auth | Sonamu |
 |-------------|--------|

package/src/skills/sonamu/cdd.md

@@ -0,0 +1,441 @@
+---
+name: sonamu-cdd
+description: Contract-Driven Development(CDD) 가이드. main.contract.json, 도메인별 contract, spec 작성 절차, CDD CLI, 개발 프로세스. Entity 설계 전에 반드시 완료해야 함. Use when writing contracts or specs before entity design.
+---
+
+# Contract-Driven Development (CDD)
+
+This project follows Contract-Driven Development (CDD). All development work must follow the rules below.
+
+## Core Principles
+
+- The `.contract.json` files under the `contract/` directory are the Single Source of Truth (SSoT) for this project.
+- All development follows a **Waterfall process**. Move to the next stage only after the current stage is completed.
+- Authority flows in this order: **Contract -> Spec -> Code**.
+  - Code must always follow Spec.
+  - Spec must always follow Contract.
+- **1 Contract Feature = 1 Spec File**. Each feature in Contract's `Features/Capabilities` maps to exactly one Spec file. Shared infrastructure across features may be separated into `shared/*.spec.json`.
+- Even if a better structure appears during implementation, do not change code first. Update Spec first, then update code.
+- Contract is human-managed. AI must not modify Contract files without user request. When the user explicitly asks to update Contract, AI may edit directly. Otherwise, AI should only propose changes.
+- Code-document consistency is verified by AI automated validation (1st pass) and review checklist (2nd pass for feature mapping/coverage).
+
+## Project Structure
+
+```text
+packages/api/contract/
+|- main.contract.json          # project root contract
+|- {domain}/
+|  |- main.contract.json       # domain representative contract
+|  |- {sub-contract}.contract.json
+|  |- {feature-key}.spec.json  # 1 feature = 1 spec file
+|- shared/
+|  |- {shared-infra}.spec.json # cross-feature shared infrastructure
+\- ...
+```
+
+Example:
+
+```text
+packages/api/contract/
+|- main.contract.json
+|- auth/
+|  |- main.contract.json
+|  |- login.spec.json           # login feature spec (1:1)
+|  |- session.spec.json         # session feature spec (1:1)
+|  \- password-reset.spec.json  # password-reset feature spec (1:1)
+|- payment/
+|  |- main.contract.json
+|  |- checkout.spec.json        # checkout feature spec (1:1)
+|  \- refund.spec.json          # refund feature spec (1:1)
+\- shared/
+   \- auth-session.spec.json    # shared session infrastructure
+```
+
+- Contract: `*.contract.json` - folder-based tree structure, with `main.contract.json` as the folder representative.
+- Spec: `*.spec.json` - one file per feature, placed in the same folder as related Contract files. The filename is the feature key (`login.spec.json` -> feature key `login`).
+
+---
+
+## Document Model
+
+### Contract (`.contract.json`)
+
+A business-logic document that non-developers can read. AI must treat this file as **read-only**. If an update is needed, AI should only propose the change to the user.
+
+```json
+{
+  "lastModified": "YYYY-MM-DD",
+  "content": ["## Overview", "", "Markdown lines as string array", ...]
+}
+```
+
+`content` is a `string[]` where each element is one line of Markdown.
+
+`content` fixed sections:
+
+`Overview -> Domain Glossary -> Features/Capabilities -> User Roles/Actors -> Business Rules/Constraints -> Edge Cases`
+
+### Spec (`.spec.json`)
+
+A feature-level technical document derived from Contract. Each file represents exactly one feature. AI can create and update Spec files. Deletion requires user approval.
+
+```json
+{
+  "schemaVersion": 1,
+  "summary": "Login processing and session issuance",
+  "description": [
+    "Validates user credentials and issues JWT-based sessions.",
+    "Includes password retry limit and account lockout policy."
+  ],
+  "acceptanceCriteria": [
+    "Valid email/password login returns a JWT token",
+    "5 wrong password attempts locks account for 30 minutes",
+    "Expired session request returns 401 response"
+  ],
+  "lastModified": "YYYY-MM-DD",
+  "status": "draft | in-progress | done",
+  "sources": ["packages/api/src/application/auth/login.ts", "packages/api/src/application/auth/login.test.ts"],
+  "contracts": ["./main.contract.json"],
+  "dependsOnSpecs": ["./session.spec.json"],
+  "modules": {
+    "LoginService": "Handles login processing",
+    "SessionManager": "Manages sessions"
+  },
+  "interfaces": {
+    "LoginService.authenticate()": "Performs authentication",
+    "LoginService.validate()": "Validates input"
+  },
+  "dataFlow": [
+    "1. Client -> LoginService.validate(): validate email/password input",
+    "2. LoginService.validate() -> LoginService.authenticate(): pass validated credentials",
+    "3. LoginService.authenticate() -> Database: query user record and compare password hash",
+    "4. LoginService.authenticate() -> SessionManager: request session creation on auth success",
+    "5. SessionManager -> Client: return Access Token + Refresh Token"
+  ],
+  "errorHandling": {
+    "InvalidCredentialsError": "Wrong password",
+    "AccountLockedError": "Account locked after 5 retries"
+  },
+  "constraints": ["Session timeout: 30 min", "Login retry limit: 5 attempts"]
+}
+```
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `schemaVersion` | `number` | Y | Schema version |
+| `summary` | `string` | Y | One-line feature summary |
+| `description` | `string[]` | Y | Detailed feature description |
+| `acceptanceCriteria` | `string[]` | Y | Completion criteria (verifiable conditions) |
+| `lastModified` | `string` | Y | Last modified date (YYYY-MM-DD) |
+| `status` | `string` | Y | `"draft"` / `"in-progress"` / `"done"` |
+| `sources` | `string[]` | Y | Implementation/test files (relative to project root) |
+| `contracts` | `string[]` | Y | Referenced Contract files (relative to Spec file) |
+| `dependsOnSpecs` | `string[]` | N | Dependent Spec files (relative to Spec file) |
+| `modules` | `Record<string, string>` | Y | Module structure (key: module name, value: role) |
+| `interfaces` | `Record<string, string>` | Y | Functions/APIs (key: function name, value: description) |
+| `dataFlow` | `string[]` | Y | Inter-module data flow |
+| `errorHandling` | `Record<string, string>` | Y | Error handling (key: error name, value: trigger condition) |
+| `constraints` | `string[]` | Y | Technical constraints |
+
+**Empty section notation**: `string[]` -> `[]`, `Record<string, string>` -> `{}`
+
+**Spec is higher authority than code.** Code must always follow the confirmed Spec. If Spec and code conflict, code is wrong.
+
+### Contract-Spec linking
+
+Contract is not extended as a structural source of feature keys. **Spec references Contract unidirectionally.**
+
+1. **Spec filename = feature key**: `login.spec.json` -> `login`
+2. **`contracts` field** points to referenced Contract files
+3. **`summary`/`description`** describes which Contract feature this Spec implements (human-readable)
+4. Duplicate feature keys within the same Contract boundary are not allowed
+5. Renaming a Spec file = changing the feature key
+
+### `status` field
+
+| Value | Meaning | Transition condition |
+|---|---|---|
+| `draft` | Spec is being written, not confirmed yet | Initial state |
+| `in-progress` | Spec confirmed, implementation in progress | After all Spec sections are confirmed |
+| `done` | Implementation complete, consistency validation passed, all `acceptanceCriteria` met | After code passes consistency check against Spec |
+
+**Regression**: When `sources`, `contracts`, `dependsOnSpecs`, or `acceptanceCriteria` change on a `done` Spec, `status` reverts to `in-progress`.
+
+### `acceptanceCriteria` field
+
+Conditions that must be met for this Spec's implementation to be considered "done". AI uses these as a checklist during consistency validation.
+
+**Authoring rules**:
+- Each item must be a verifiable, specific condition. Vague expressions like "should work well" are not allowed.
+- Include conditions derived from Contract's business rules and Edge Cases.
+- Conditions derived from `constraints` and `errorHandling` may also be included.
+- Recommended format: "When X, then Y" (input-result).
+
+**Validation usage**: When transitioning `status` to `"done"`, AI verifies all items are satisfied in code. If any item is unmet, `"done"` transition is blocked.
+
+### Spec detail level
+
+- Include: module structure, file/class responsibilities, function/API names with short descriptions, inter-module data flow.
+- Exclude: internal implementation logic, algorithm details, variable names, code snippets.
+
+### Reference rules
+
+- `contracts` field: relative path from the Spec file (e.g. `"./payment.contract.json"`).
+- `sources` field: relative path from the project root (e.g. `"packages/api/src/application/auth/login.ts"`).
+- `dependsOnSpecs` field: relative path from the Spec file (e.g. `"../shared/auth-session.spec.json"`).
+
+### `lastModified` update rule
+
+Whenever any Spec field changes, update `lastModified` to today's date.
+
+### Change history tracking
+
+Spec files do not store history internally. Git handles it.
+
+```bash
+git log -- packages/api/contract/auth/login.spec.json
+git log --follow -- packages/api/contract/auth/login.spec.json  # track renames
+```
+
+---
+
+## Development Process
+
+All processes follow Waterfall. Each stage starts only after the previous stage is complete. If you need to change a previous stage artifact, go back, update the document first, then re-run downstream stages.
+
+### 1. New feature development
+
+```text
+Contract review -> Spec authoring/fix -> Code implementation -> Test authoring/execution -> Consistency validation
+```
+
+**Step 1: Contract review**
+- Read related `.contract.json` files and identify business requirements for the target feature.
+- Confirm the feature is defined under Contract `Features/Capabilities`.
+- If not defined, propose a Contract update to the user. Continue only after Contract is updated.
+
+**Step 2: Spec authoring/fix**
+- Create `{feature-key}.spec.json` in the same folder as related Contract files.
+- Set `status` to `"draft"`.
+- Fill `contracts` with relative paths to base Contract files.
+- Fill `summary` and `description` to clearly state which Contract feature this Spec implements.
+- Fill all structured fields (`modules`, `interfaces`, `dataFlow`, `errorHandling`, `constraints`).
+- Define `acceptanceCriteria` with verifiable completion conditions.
+- Add planned implementation file paths to `sources`.
+- **All fields must be confirmed in this step.** After confirmation, set `status` to `"in-progress"` and continue.
+
+**Step 3: Code implementation**
+- Implement exactly following the confirmed module structure and interfaces defined in Spec.
+- If a better structure appears during implementation, do not change code first. Go back to Step 2, update Spec first, then implement against the updated Spec.
+- If new files are added or plans change, update `sources` in Spec first.
+
+**Step 4: Test authoring and execution**
+- Write tests for implemented code.
+- Add test file paths to `sources`.
+- Run tests and confirm they pass.
+
+**Step 5: Consistency validation**
+- Validate that implemented code follows the confirmed Spec exactly.
+- Check whether `modules`, `interfaces`, and `dataFlow` match Spec.
+- Verify all `acceptanceCriteria` items are satisfied in code.
+- **If mismatch exists, fix code.** Spec should not be changed to match code.
+- After all validations pass, set `status` to `"done"` and update `lastModified` to today.
+
+### 2. Existing code changes
+
+```text
+Impact analysis -> Contract/Spec review -> Spec update/fix -> Code update -> Test execution -> Consistency validation
+```
+
+**Step 1: Impact analysis**
+- Find all Spec files whose `sources` include the target files.
+- Check `contracts` and `dependsOnSpecs` in those Specs to identify chained impact scope.
+
+**Step 2: Contract/Spec review**
+- Read related Specs to understand current module structure and interfaces.
+- Read Contract as well to ensure the change does not violate business rules.
+- If the change conflicts with Contract business rules, notify the user and continue only after Contract update.
+
+**Step 3: Spec update/fix**
+- Determine whether the change affects Spec scope.
+  - Interface changes, module add/remove, data flow changes -> Spec update is required.
+  - Internal-only changes (refactoring, performance tuning) -> Spec update may be unnecessary, but verify `modules` is still accurate.
+- If Spec update is required, update and confirm Spec first.
+- If files are added/removed, update `sources`.
+- Update `acceptanceCriteria` if completion conditions have changed.
+- Set `status` to `"in-progress"`.
+- **Continue only after Spec is confirmed.**
+
+**Step 4: Code update**
+- Update code within confirmed Spec scope.
+- If a better structure appears, do not change code first. Go back to Step 3 and update Spec first.
+
+**Step 5: Test execution**
+- Confirm existing tests pass.
+- Add/update tests according to the change.
+
+**Step 6: Consistency validation**
+- Validate that updated code follows confirmed Spec exactly.
+- Verify all `acceptanceCriteria` items are satisfied.
+- **If mismatch exists, fix code.**
+- After all validations pass, set `status` to `"done"` and update `lastModified` to today.
+
+### 3. Bug fixes
+
+```text
+Bug analysis -> Related Spec/Contract review -> Spec update/fix (if needed) -> Code fix -> Tests -> Consistency validation
+```
+
+**Step 1: Bug analysis**
+- Identify root cause and related source files.
+
+**Step 2: Related Spec/Contract review**
+- Find Spec files whose `sources` include affected files.
+- Classify root cause:
+  - Business rule violation -> verify Spec and code against Contract.
+  - Implementation bug -> check Spec `errorHandling` and Contract `Edge Cases`.
+  - Spec defect -> Spec failed to represent Contract correctly.
+
+**Step 3: Spec update/fix (if needed)**
+- If the bug is a missing technical case in Spec `errorHandling` or `constraints`, update those fields first.
+- If the bug is a missing business case in Contract `Edge Cases`, propose Contract update to user. After Contract update, update Spec.
+- Add missing conditions to `acceptanceCriteria` if applicable.
+- Set `status` to `"in-progress"`.
+- **Continue only after Spec is confirmed.**
+
+**Step 4: Code fix**
+- Fix code according to confirmed Spec.
+
+**Step 5: Tests**
+- Add a reproducing test case for the bug.
+- Confirm tests pass after the fix.
+- Confirm existing tests are not broken.
+
+**Step 6: Consistency validation**
+- Validate that fixed code follows confirmed Spec exactly.
+- Verify all `acceptanceCriteria` items are satisfied.
+- **If mismatch exists, fix code.**
+- After all validations pass, set `status` to `"done"` and update `lastModified` to today.
+
+---
+
+## Contract/Spec Authoring Guide
+
+### Contract authoring principles
+
+- Use language that non-developers can understand.
+- Do not include code, technical jargon, or implementation details.
+- Define project-specific terms in `Domain Glossary`.
+- Each item in `Features/Capabilities` must include clear business rules.
+- `Business Rules/Constraints` should contain only global rules that cross individual features.
+- `Edge Cases` should define business-level boundary conditions and decisions.
+
+### Spec authoring principles
+
+- `summary` must state the feature in one line. `description` provides detailed explanation.
+- `summary`/`description` must make it clear which Contract feature this Spec implements.
+- `modules` and `interfaces` use `Record<string, string>` format (key: name, value: description).
+- In `interfaces`, include only function/API names and short descriptions (no signatures or implementation logic).
+- `dataFlow` and `constraints` use `string[]` format.
+- `errorHandling` uses `Record<string, string>` format (key: error name, value: trigger condition).
+- `acceptanceCriteria` must contain verifiable, specific conditions.
+- `sources` must list all related implementation and test files.
+- `contracts` must list relative paths to base Contract files.
+- Empty sections: `[]` for `string[]` fields, `{}` for `Record<string, string>` fields.
+
+---
+
+## CDD CLI (`@sonamu-kit/cdd`)
+
+The `cdd` CLI tool automates CDD workflow tasks. Run via `pnpm cdd <command>`.
+
+### Commands
+
+| Command | Description |
+|---|---|
+| `cdd init [dir]` | Initialize a CDD project (creates `contract/`, `main.contract.json`, `cdd.md`) |
+| `cdd tree` | Display Contract/Spec tree grouped by domain with status colors |
+| `cdd status` | Show project dashboard (Contract/Spec counts, status breakdown) |
+| `cdd status <file>` | Spec/Contract status with relationship info (contracts, deps, dependents) |
+| `cdd validate` | Verify schema/path/reference integrity (file existence, path resolution, required fields) |
+| `cdd impact <file>` | Analyze source file change impact (direct Specs, chain Contracts, indirect Specs) |
+| `cdd check` | Verify Code-Spec-Contract consistency + `acceptanceCriteria` fulfillment |
+| `cdd spec create <n>` | Create a Spec template. Requires `--domain <n>` or `--contract <path>` |
+| `cdd spec set-status <spec> <status>` | Change Spec status |
+| `cdd spec list` | List Specs. Filters: `--status`, `--domain`, `--contract` |
+| `cdd spec get <spec>` | Show full Spec or a specific field (`--field`) |
+| `cdd spec set <spec>` | Update a Spec field (`--field`, `--value`, `--json`) |
+| `cdd spec add <spec>` | Add an item to an array/map field (`--field`, `--value`, `--key`) |
+| `cdd spec remove <spec>` | Remove an item from an array/map field (`--field`, `--index`/`--value`/`--key`) |
+| `cdd spec blame <feature>` | Contributor analysis per Spec (ownership, score, AI role summary) |
+| `cdd spec log <feature>` | Change timeline grouped by time period and author |
+| `cdd spec explain <feature>` | AI-powered diff analysis: what changed, why, and impact level |
+| `cdd source blame <file>` | Contributor analysis per source file |
+| `cdd source log <file>` | Source file change timeline grouped by time period and author |
+| `cdd source explain <file>` | AI-powered source file diff analysis |
+
+### Common Options
+
+- `--cwd <dir>` : Set working directory (default: current directory)
+- `--raw` / `--json` : Force raw JSON output (auto-enabled in pipe/CI environments)
+- `-h, --help` : Show help
+
+### Git + AI Options (blame, log, explain)
+
+- `--since=<date>` : Start date filter (ISO 8601, e.g. `2025-01-01`)
+- `--until=<date>` : End date filter (ISO 8601, default: HEAD)
+- `--group-by=day|week|month` : Grouping interval for `spec log` / `source log` (default: `day`)
+- `--commit=<hash>` : Analyze a single commit for `spec explain` / `source explain`
+
+AI uses `claude --model haiku` via local CLI.
+
+### Usage Examples
+
+```bash
+# List in-progress specs
+pnpm cdd spec list --status in-progress
+
+# Show full spec
+pnpm cdd spec get signin
+
+# Update a field
+pnpm cdd spec set signin --field summary --value "Updated summary"
+
+# Add a constraint
+pnpm cdd spec add signin --field constraints --value "New constraint"
+
+# Contributor analysis for a spec
+pnpm cdd spec blame signin
+
+# Weekly changelog for a spec
+pnpm cdd spec log signin --group-by=week
+
+# Explain changes in a date range
+pnpm cdd spec explain signin --since=2025-03-01
+
+# JSON output for scripting
+pnpm cdd spec list --raw | jq '.[].status'
+```
+
+---
+
+## Edge Cases
+
+| Situation | Handling |
+|---|---|
+| Feature rename | `git mv` to rename Spec file |
+| Feature split | Keep/delete existing file + create new files, in the same commit |
+| Feature merge | Consolidate into one file, delete the rest, in the same commit |
+| Feature removal | Confirm removal from Contract, delete Spec file with user approval |
+
+---
+
+## Prohibitions
+
+- AI must not modify Contract files without user request.
+- AI must not delete Spec files without user approval.
+- Do not write code without checking Contract and Spec first.
+- Do not include implementation internals, algorithm details, or code snippets in Spec.
+- **Do not start implementation (Entity design) before Spec is confirmed.**
+- **If Spec and code conflict, do not change Spec to match code. Always fix code to match Spec.**
+- **If a better approach appears during implementation, do not change code first. Update Spec first.**

package/src/skills/sonamu/entity-relations.md

@@ -460,56 +460,47 @@ parentId를 설정하면 자식 엔티티의 **BaseSchema에서 FK 컬럼이 제
 
 ## FK 참조 규칙 (FieldExpr)
 
-BelongsToOne 관계를 정의하면 `{name}_id` 컨럼이 자동 생성되지만, **Entity 정의 내에서는 `{name}.id` 형태로 참조**해야 합니다.
+BelongsToOne 관계를 정의하면 `{name}_id` 컬럼이 자동 생성됩니다. **subsets에서는 `{name}.id` 형태(FieldExpr)로 참조**하고, **indexes에서는 실제 DB 컬럼명(`{name}_id`)을 사용**합니다.
 
 ### 적용 대상
 
-| 위치 | 잘못된 예 | 올바른 예 |
-|------|----------|----------|
-| subsets | `"user_id"` | `"user.id"` |
-| indexes | `"user_id"` | `"user.id"` |
-| unique | `["user_id", "date"]` | `["user.id", "date"]` |
-| search | `"user_id"` | `"user.id"` |
+| 위치 | 사용 형식 | 예시 |
+|------|----------|------|
+| subsets | FieldExpr (`relation.field`) | `"user.id"` |
+| indexes | 실제 DB 컬럼명 | `"user_id"` |
+| unique | 실제 DB 컬럼명 | `["user_id", "date"]` |
+| search | FieldExpr (`relation.field`) | `"user.id"` |
 
 ### 예시
 
 ```json
-// WRONG - "user_id"를 직접 사용하면 에러 발생
 {
   "id": "ApiLog",
   "props": [
     { "type": "relation", "name": "user", "with": "User", "relationType": "BelongsToOne" }
   ],
   "subsets": {
-    "A": ["id", "user_id", "api_path"]  // WRONG: user_id
+    "A": ["id", "user.id", "api_path"]  // FieldExpr 사용
   },
   "indexes": [
-    ["user_id"]  // WRONG: user_id
-  ]
-}
-
-// CORRECT - "user.id" 형태로 참조
-{
-  "id": "ApiLog",
-  "props": [
-    { "type": "relation", "name": "user", "with": "User", "relationType": "BelongsToOne" }
-  ],
-  "subsets": {
-    "A": ["id", "user.id", "api_path"]  // CORRECT: user.id
-  },
-  "indexes": [
-    ["user.id"]  // CORRECT: user.id
+    {
+      "type": "index",
+      "name": "api_logs_user_id_index",
+      "columns": [{ "name": "user_id" }]
+    }
   ]
 }
 ```
 
-### 에러 메시지
+### subsets에서의 에러 메시지
 
 ```
 Error: ApiLog -- 잘못된 FieldExpr 'user_id' (사용 가능한 props: id, created_at, ..., user)
 ```
 
-이 에러가 보이면 `user_id` → `user.id`로 변경하세요.
+subsets에서 이 에러가 보이면 `user_id` → `user.id`로 변경하세요. indexes에서는 `user_id`가 올바른 형식입니다.
+
+> **참고:** indexes와 subsets의 참조 방식 차이에 대한 상세 설명은 `entity-basic.md`의 "IMPORTANT: indexes에서 FK 컬럼명은 실제 DB 컬럼명을 사용한다" 섹션을 참고하세요.
 
 ---
 

package/src/skills/sonamu/frontend.md

@@ -589,44 +589,51 @@ function ProfileForm() {
 
 **IMPORTANT**: SonamuProvider에 uploader 함수 필수 설정 (아래 참조)
 
-## MultiSelect
+## Select (다중 선택 모드)
 
-다중 선택 컴포넌트 (검색, 그룹, 애니메이션 지원)
+`Select` 컴포넌트에 `multiple: true`를 설정하면 다중 선택 모드로 동작합니다.
 
 ```typescript
-import { MultiSelect } from "@sonamu-kit/react-components/components";
-import type { MultiSelectOption } from "@sonamu-kit/react-components/components";
+import { Select } from "@sonamu-kit/react-components/components";
 
 function TagForm() {
   const { register } = useTypeForm(PostSaveParams, {
     tag_ids: [],  // number[]
   });
 
-  const options: MultiSelectOption[] = [
-    { label: "JavaScript", value: "1" },
-    { label: "TypeScript", value: "2" },
-    { label: "React", value: "3" },
-    { label: "Vue", value: "4" },
+  const items = [
+    { value: 1, label: "JavaScript" },
+    { value: 2, label: "TypeScript" },
+    { value: 3, label: "React" },
+    { value: 4, label: "Vue" },
   ];
 
   return (
-    <MultiSelect
+    <Select
       {...register("tag_ids")}
-      options={options}
+      items={items}
+      multiple
       placeholder="태그 선택"
-      emptyIndicator={<span>태그가 없습니다</span>}
     />
   );
 }
 ```
 
-**주요 Props:**
+**다중 선택 전용 Props:**
 
-- `options`: `MultiSelectOption[]`
-- `groups`: 옵션 그룹화
+- `multiple`: `true` (다중 선택 활성화)
 - `maxCount`: 표시할 최대 배지 개수
-- `badgeAnimation`: `"bounce" | "pulse" | "wiggle" | "fade" | "slide"`
+- `hideSelectAll`: 전체 선택 버튼 숨기기
+- `searchable`: 검색 입력 활성화
+
+**공통 Props:**
+
+- `items`: `SelectItemDef[]` (값만 또는 `{ value, label, disabled }` 형태)
+- `placeholder`: 선택 전 표시 텍스트
+- `clearable`: X 버튼으로 전체 해제
 - `disabled`: 비활성화
+- `renderItem`: 커스텀 렌더링 함수
+- `async`: `true` 설정 시 `onSearch` 콜백으로 비동기 검색 지원
 
 ## EnumSelect
 

package/src/skills/sonamu/model.md

@@ -672,6 +672,7 @@ if (params.search === "id") {
 - [ ] debug 옵션 불필요하게 명시하지 않음
 - [ ] orderBy 모든 케이스 exhaustive 처리
 - [ ] ManyToMany relation이 있으면 _ids 배열 SaveParams에 추가
+- [ ] `@upload` 메서드에 `@api`가 붙어 있지 않은가? (`@upload`는 단독 사용, 함께 쓰면 빌드 에러)
 - [ ] SearchField enum과 findMany 구현이 일치하는가?
 - [ ] 승인 워크플로우 엔티티에 status/type 필터가 ListParams와 findMany 양쪽에 모두 있는가?
 

package/src/skills/sonamu/workflow.md

@@ -85,11 +85,57 @@ description: Sonamu 전체 개발 워크플로우. 프로젝트 생성부터 Fro
 
 ---
 
+## PHASE 0.5: Contract 및 Spec 작성
+
+**참조 스킬:** cdd.md
+
+**CRITICAL: 이 PHASE가 완료되기 전에 엔티티 설계(PHASE 1)를 시작하지 않는다.**
+
+### 7. main.contract.json 작성
+
+20. `packages/api/contract/main.contract.json` 생성
+    - `requirements.md`, `business-logic.md` 기반으로 작성
+    - 전체 프로젝트 Overview, 하위 도메인 목록, Domain Glossary, User Roles, Business Rules, Edge Cases 포함
+    - `content`는 Markdown 한 줄씩 `string[]`로 작성
+21. 사용자에게 보고 후 승인 대기
+
+### 8. 도메인별 contract 작성
+
+22. `business-logic.md`에서 도메인을 식별하고 도메인 목록을 사용자에게 확인받기
+23. 도메인별로 `packages/api/contract/{domain}/main.contract.json` 작성
+    - 도메인 폴더명은 영문 소문자 (예: `auth`, `organization`, `research`)
+    - 각 도메인 contract 작성 후 사용자 확인받기 (도메인별로 하나씩)
+    - Features/Capabilities 섹션을 상세하게 작성한다 (이후 spec의 1:1 기반이 됨)
+
+### 9. Spec 작성
+
+**CRITICAL: 1 Feature = 1 Spec 파일. 도메인 contract의 Features/Capabilities에 정의된 기능 하나당 spec 파일 하나.**
+
+24. 각 도메인의 Features/Capabilities를 기반으로 spec 파일 목록 작성 후 사용자 확인
+25. 도메인별로 spec 파일 작성
+    - spec 파일은 해당 도메인 폴더에 위치
+    - 파일명은 feature key (예: `signin.spec.json`)
+    - `status: "draft"`로 시작
+26. 전체 spec 작성 완료 후 사용자에게 검토 요청
+    - 사용자 검토 및 수정 반영
+    - 모든 spec 검토 완료 후에만 다음 PHASE로 진행
+
+**완료 기준:**
+
+- [ ] `packages/api/contract/main.contract.json` 작성 및 사용자 승인
+- [ ] 모든 도메인 contract 작성 및 사용자 승인
+- [ ] 모든 domain spec 파일 작성 완료
+- [ ] 사용자 spec 검토 완료
+
+---
+
 ## PHASE 1: 엔티티 설계
 
 **참조 스킬:** entity-basic.md, entity-relations.md
 
-### 7. 엔티티 설계
+**전제 조건:** PHASE 0.5 완료 (모든 spec 사용자 검토 완료)
+
+### 10. 엔티티 설계
 
 20. 사용자 요구사항에 맞는 엔티티 설계
     - 설계하면서 사용자에게 비즈니스 로직에 맞는지 **지속적으로 디테일하게** 확인받을 것

package/src/testing/parallel-db-manager.ts

@@ -29,9 +29,9 @@ export class ParallelDBManager {
         (_, i) => `${this.templateDb}_${i + 1}`,
       );
 
-      // 1. 기존 연결 종료 (병렬)
+      // 1. 기존 연결 종료 (병렬) worker DB + template DB (PG 18에서 FILE_COPY 시 template에 exclusive access 필요)
       await Promise.all(
-        workerDbNames.map((dbName) =>
+        [...workerDbNames, this.templateDb].map((dbName) =>
           adminDb.raw(
             `
             SELECT pg_terminate_backend(pg_stat_activity.pid)