Smart Bin Rule Contract

Smart Bin Rule Contract

Smart Bins are computed collections. Manual membership is preserved separately and is unioned with rule matches.

Version 1

{
  "version": 1,
  "conditions": [
    { "type": "content_type", "operator": "is", "value": "link" },
    { "type": "source", "operator": "contains", "value": "Safari" }
  ],
  "match": "any"
}

match is any or all. Each condition uses is for a case-insensitive exact match or contains for a case-insensitive partial match. Rules contain 1–32 conditions, and each trimmed value is limited to 2,048 characters.

Current condition types are:

Type	Value contract
clip_type	Structural text, image, or file value.
content_type	Stable Content Type ID assigned to the clip's current original or extracted searchable text.
file_format	Format ID produced by current byte-verified File Format inspection.
source	Captured source application name.
visual_label	Visual concept emitted by a current hash-bound Extractor result.

Stable IDs are stored rather than localized labels. GUI pickers present localized built-in Content Type names and user-authored custom names without changing the saved ID.

The corresponding Functionality setting controls each condition type. Disabling Clip Types, Content Types, File Formats, or Sources makes conditions on that axis inactive without deleting the rule. Re-enabling the feature restores matching; rescanning can backfill derived Content Types and File Formats.

Legacy origin_kind, contains, file_extension, and file_path conditions remain readable for existing libraries and portable imports, but new authoring surfaces use the five collection axes above.

Public boundaries

The GUI, Tauri commands, CLI, and History and Organization import validate rules through the shared Rust contract. Invalid versions, targets, operators, match modes, empty values, unknown fields, and excessive bounds are rejected instead of being saved as silently empty Smart Bins.

The CLI accepts this object through --smart-rule-json; --json output retains the canonical JSON string in smart_rule. Full Backup preserves the underlying SQLite record exactly.