@melite/models-mask 0.1.4-alpha → 0.2.0-alpha

package/README.md

@@ -0,0 +1,43 @@
+---
+description: The mask studio's selection lane as a model family — SAM3/RT-DETR detection, the SAM2 arm, and paint exports, bound by the mask card.
+kind: package-library
+---
+
+# mask
+
+mask registers the model family `mask-select` (label "Mask", genre `image`): the mask studio's selection lane declared as one action — SAM3 CLIP/RT-DETR detection, the SAM2 impact-pack arm, and paint exports — which the mask card binds through the DECL's declared-action interlock. The id is `mask-select`, deliberately not the package name: a family id must not shadow its card.
+
+## Weights
+
+The three weights are the action's own constants (`MASK_WEIGHTS`, the LANE_FILES pattern): `sam3.1_multiplex_fp16.safetensors` (the SAM3 multiplex checkpoint), `rt_detr_v4-x-hgnet_fp32.safetensors` (the RT-DETR detector), and `sam2.1_hiera_large.pt` (the SAM2 arm). No variant swaps them and no row names them; the mask card's provisions declare the downloads, and a card spec pins the agreement between lane constants and provision rows.
+
+## The select action
+
+The family carries one variant (`select`, route `mask-select`, no cells) and one action, `select`. The action declares no params of its own — the card's schema walk owns the knobs (detect hints, the drawn box manifest, paint exports, mask composition), and the build reads the walked shape beneath flat params. Output: one MASK handle. A composed lane also saves intermediates under the run directory: the primary mask, a union composite when a global paint export is stated, and detection-box overlays when box export is requested. `parseMaskLaneFacts` returns the three constants closed — an empty loader name is unrepresentable by construction.
+
+## Model Experience
+
+### Request context and condition
+
+A run needs the image (an upload or an upstream `$spell` tensor) and the card's selection choices; the family contributes the weights and the node tree, the card the vocabulary.
+
+#### What the model sees
+
+One image, the drawn detect hint, and any paint-export paths; the three weights wire into the lane's loaders by constant.
+
+#### Token effect
+
+Zero-direct: the action composes an engine graph, not a token stream.
+
+#### KV Cache effect
+
+Independent: each run is self-contained.
+
+## Known Limitations and Deferred Work
+
+- **Id divergence** — family id `mask-select` versus package name `mask`; deliberate, but a standing search trap across the estate.
+- **No declared params** — tuning vocabulary lives on the card schema; this package cannot state it, and the action trusts the walked shape.
+- **Weights pinned in code** — a weight-file rename must land in the lane constants and the card spec together, or boarding refuses.
+- **Live behavior unobserved** — not verified against the running model.
+
+Exports: the plugin root, `./package.json`.

package/lib/actions.js

@@ -72,6 +72,15 @@ export const select = {
         const detectionDilation = p.detection_dilation ?? 10;
         const cropFactor = p.crop_factor ?? 3.0;
         const dropSize = p.drop_size ?? 10;
+        // THE DETECTOR THRESHOLD FOLD (audit 015 C5 — one fold for every
+        // detector seat): the effective detector threshold derives ONCE —
+        // per-entry tune → lane-flat param → the pack's 0.5 default. The
+        // SAM2 impact detectors AND the RT-DETR proposal seat read THIS
+        // derivation (the seats reference it, never re-stamp the fold):
+        // a second spelling let one graph carry two effective thresholds
+        // — SAM2 folded 0.5 while an unstated RT-DETR seat rode the raw
+        // cast to undefined (tests/threshold-fold-parity.spec.ts).
+        const detectorThreshold = (tune) => tune?.detection_threshold ?? p.detection_threshold ?? 0.5;
         const exportBoxes = p.export_boxes;
         const viaRtdetr = p.primary_via_rtdetr;
         // the lazy loader trio (see the header note — created on first use)
@@ -197,7 +206,7 @@ export const select = {
             const segs = g.node(detector.detectorNode, {
                 [detector.detectorInput]: provider,
                 image: img(),
-                threshold: (tune?.detection_threshold ?? p.detection_threshold ?? 0.5),
+                threshold: detectorThreshold(tune),
                 dilation: tune?.detection_dilation ?? detectionDilation,
                 crop_factor: tune?.crop_factor ?? cropFactor,
                 drop_size: tune?.drop_size ?? dropSize,
@@ -249,7 +258,7 @@ export const select = {
             rtdetrBoxes = g.node('RTDETR_detect', {
                 model: rtdetrLoader(),
                 image: img(),
-                threshold: p.detection_threshold,
+                threshold: detectorThreshold(), // the SAME fold as the SAM2 detectors (audit 015 C5)
                 class_name: 'person',
                 max_detections: cap,
             }).out(0);

package/lib/index.d.ts

@@ -1,6 +1,26 @@
 import type { Plugin } from "@deepseek-ai/cordis";
-import type { ModelDecl } from "@melite/comfyui-cordis/model-contract";
+import type { ModelDecl } from '@melite/comfyui-card-kit/model-contract';
+import type { ProvisionRow } from '@melite/comfyui-card-kit/model-contract';
+
+
+
+
+
+
+
+
+
+export declare const PROVISIONS: ProvisionRow[];
+
+
+
+
+
+
+
+export declare const DETECTOR_PROVISIONS: ProvisionRow[];
 export declare const DECL: ModelDecl;
 export declare const family: Plugin;
 export { select, parseMaskLaneFacts, MASK_WEIGHTS, type MaskLaneFacts, type MaskLaneParams } from "./actions.js";
+export { family as default };
 //# sourceMappingURL=index.d.ts.map

package/lib/index.js

@@ -1,4 +1,50 @@
-import { select } from "./actions.js";
+import { IMPACT_DETECTOR_PROVISIONS } from "@melite/comfyui-card-kit";
+import { select, MASK_WEIGHTS } from "./actions.js";
+
+
+
+
+
+
+
+
+
+export const PROVISIONS = [
+    {
+        
+        // existed since stroke ~40 but the weight was NEVER fetched —
+        // the engine silently dropped the whole mask arm). The official
+        // ComfyUI conversion.
+        name: "sam3.1_multiplex_fp16.safetensors",
+        url: "https://huggingface.co/Comfy-Org/sam3.1/resolve/main/checkpoints/sam3.1_multiplex_fp16.safetensors",
+        folder: "checkpoints",
+        sha256: "9ba99c92703c2e8b4f47de2d34a539bb8e18923049e238b780d70dbe6368eb03",
+        size_bytes: 1745546848,
+    },
+    {
+        name: "rt_detr_v4-x-hgnet_fp32.safetensors",
+        url: "https://huggingface.co/Comfy-Org/SDPose/resolve/main/diffusion_models/rt_detr_v4-x-hgnet_fp32.safetensors",
+        folder: "diffusion_models",
+        sha256: "1ba4a7794c2f8b176327c887ba38fbe0f977049cbef149960288aa923d0239f3",
+        size_bytes: 247790660,
+    },
+    {
+        name: "sam2.1_hiera_large.pt",
+        url: "https://huggingface.co/facebook/sam2.1-hiera-large/resolve/main/sam2.1_hiera_large.pt",
+        folder: "sams",
+        sha256: "2647878d5dfa5098f2f8649825738a9345572bae2d4350a2468587ece47dd318",
+        size_bytes: 898083611,
+    },
+    ...IMPACT_DETECTOR_PROVISIONS,
+];
+
+
+
+
+
+
+
+export const DETECTOR_PROVISIONS = [...IMPACT_DETECTOR_PROVISIONS];
 // THE TOOL FAMILY (the F1 shape): a selection tool, not a generative
 // model — `unoffered: true` registers the atom (the actions admission
 // gate runs at boot; the card's declaredAction binding resolves
@@ -10,25 +56,49 @@ import { select } from "./actions.js";
 // shadows the card arm — discovery.spec's mask envelope wall catches
 // exactly that), and the bench plane keeps the self-naming strip for
 // era rows. The three weights are the family's constants (actions.ts
-// MASK_WEIGHTS — the LANE_FILES pattern), so the row carries no
-// lane_inputs. ONE variant, ONE address, no cells: the family's id
-// is its own route — an address with no download, because the
-// weights ride the card's provisions, not a variant cell.
+// MASK_WEIGHTS rides the loaders), and the DECL seats them as
+// lane_inputs (the run-gate probe + anchor - the seat row below
+// provisions). ONE variant, ONE address, no cells: the family's id
+// is its own route — and its six weights DOWNLOAD through the family
+// provisions above, like every other model (no separate
+// card-provision behavior).
 export const DECL = {
     "id": "mask-select",
     "label": "Mask",
     "description": "The mask studio's selection lane — SAM3 CLIP/RT-DETR detection, the SAM2 impact-pack arm, and paint exports, as one declared action the mask card binds.",
     "genre": "image",
     "unoffered": true,
+    "provisions": PROVISIONS,
+    
+    // h3's crime shape closed for mask). The three weights stay the
+    // build's constants (MASK_WEIGHTS rides the loaders - a row value
+    // never reaches one, lane-laws pins that), but the DECL seats
+    // them as lane_inputs so the run gate PROBES presence at press
+    // and each miss's refusal anchors to its provisions URL (the
+    // anchor-at-the-door law). sam2 rides model_path + a declared
+    // sams home (the anny precedent - the stock folder map has no
+    // key for the sams pack, and EngineFacts' closed vocabulary
+    // forbids inventing one).
+    "lane_inputs": {
+        "checkpoint": MASK_WEIGHTS.checkpoint,
+        "unet": MASK_WEIGHTS.unet,
+        "model_path": MASK_WEIGHTS.sam2,
+    },
+    "lane_homes": { "model_path": "sams" },
     "variants": [
         {
             "id": "select",
             "label": "Select",
-            "group": "Variant",
+            "group": "",
             "route": "mask-select",
             "cells": [],
         },
     ],
+    
+    // axes — the anny shape. The undeclared 'Variant' literal the
+    
+    // solo category the canon gives the one-row family.
+    "variant_groups": [],
     // THE FAMILY DOOR (the atom vocabulary, stroke 0): the select
     // action's facts parse runs over the family row and every variant
     // merge AT REGISTRATION — here it closes over the family's own
@@ -44,6 +114,13 @@ export const family = {
 };
 // The family's offered actions (the atom vocabulary): the select
 // segment the mask card binds. The card imports this beside the DECL
-// — the family's whole offer, one face.
+// — the family's whole offer, one face. PROVISIONS rides too: the
+// card serves the family's rows to its arm-weight gate (the
+// provisions-identity pin, image/mask card.spec).
 export { select, parseMaskLaneFacts, MASK_WEIGHTS } from "./actions.js";
+// The Loader-row face: DSH loads plugin rows by bare specifier and
+// unwraps `exports.default ?? exports` (vendor/cordis_plugins/loader
+// unwrapExports) — the default export IS the row-loadable plugin. The
+// named `family` stays the library face (engine loadFamilies).
+export { family as default };
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@melite/models-mask",
-  "version": "0.1.4-alpha",
-  "license": "SSPL-1.0",
+  "version": "0.2.0-alpha",
+  "license": "AGPL-3.0-or-later",
   "type": "module",
   "exports": {
     ".": {
@@ -11,13 +11,12 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@melite/comfyui-cordis": "0.1.4-alpha",
-    "@melite/comfyui-card-kit": "0.1.4-alpha"
+    "@melite/comfyui-card-kit": "0.2.0-alpha"
   },
   "devDependencies": {
     "@types/node": "^22.20.0",
     "typescript": "^5.9.3",
-    "@deepseek-ai/cordis": "^4.0.4"
+    "@deepseek-ai/cordis": "^4.0.5"
   },
   "files": [
     "lib/index.js",
@@ -25,7 +24,7 @@
     "lib/**/*.d.ts"
   ],
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.4"
+    "@deepseek-ai/cordis": "^4.0.5"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",