Struct EnrichArgs 

pub struct EnrichArgs {

    pub operation: Option<EnrichOperation>,
    pub mode: Option<EnrichMode>,
    pub limit: Option<usize>,
    pub scan_page_size: Option<usize>,
    pub target: ReEmbedTarget,
    pub dry_run: bool,
    pub namespace: Option<String>,
    pub openrouter_model: Option<String>,
    pub openrouter_api_key: Option<String>,
    pub openrouter_base_url: Option<String>,
    pub max_cost_usd: Option<f64>,
    pub resume: bool,
    pub retry_failed: bool,
    pub reset_stale_claims: bool,
    pub stale_claim_secs: u64,
    pub until_empty: bool,
    pub max_runtime: Option<u64>,
    pub max_attempts: u32,
    pub status: bool,
    pub list_dead: bool,
    pub requeue_dead: bool,
    pub list_skipped: bool,
    pub requeue_skipped: bool,
    pub prune_dead_orphans: bool,
    pub prune_dead_entity_orphans: bool,
    pub ignore_backoff: bool,
    pub body_extract_graph_only: bool,
    pub rest_concurrency: u32,
    pub min_output_chars: usize,
    pub max_output_chars: usize,
    pub preserve_check: bool,
    pub prompt_template: Option<PathBuf>,
    pub llm_parallelism: Option<u32>,
    pub json: bool,
    pub db: Option<String>,
    pub wait_job_singleton: Option<u64>,
    pub force_job_singleton: bool,
    pub names: Vec<String>,
    pub names_file: Option<PathBuf>,
    pub preflight_check: bool,
    pub rate_limit_buffer: u64,
    pub max_load_check: bool,
    pub no_max_load_check: bool,
    pub circuit_breaker_threshold: u32,
    pub preserve_threshold: f64,
    pub entity_description_grounding_threshold: Option<f64>,
    pub force_redescribe: bool,
    pub quality_sample: Option<usize>,
    pub entity_names: Vec<String>,
    pub entity_type: Option<String>,
    pub allowed_types: Vec<String>,
    pub on_unknown_type: Option<String>,
    pub memory_names: Vec<String>,
    pub anchor_memory: Option<String>,
    pub entity_description_domain: String,
    pub yield_every_n_items: Option<usize>,
    pub ops_gate: bool,
    pub print_schema: bool,
}

Arguments for the enrich subcommand.

Fields

operation: Option<EnrichOperation>

Enrichment operation to run. Required for write operations; optional for the read-only queue inspectors (--status / --list-dead / --requeue-dead), where it defaults to memory-bindings when omitted (GAP-SG-31).

mode: Option<EnrichMode>

LLM provider to use. Required for write operations; not needed for the read-only queue inspectors (--status / --list-dead / --requeue-dead / --list-skipped / --requeue-skipped), which never call the LLM (GAP-SG-31).

GAP-CLI-DRY-01 (v1.1.8): also optional for --dry-run (preview only).

When omitted on a path that allows it, the resolved provider is openrouter. That default is deliberate: it is a REST call and never spawns a headless CLI (GAP-HEADLESS-DEFAULT).

limit: Option<usize>

Maximum number of items to process in this run. Omit for all.

scan_page_size: Option<usize>

GAP-SG-185 / v1.2.4: keyset page size for the enrich SCAN phase.

SQL row buffers and in-process candidate pages are this wide; production enqueue walks pages without retaining the full eligible key list. The sidecar queue still stores one row per eligible item. Precedence: this flag > XDG enrich.scan_page_size > 512. Accepted range: 1..=4096 (clamped).

target: ReEmbedTarget

v1.1.1 (P2): embedding table backfilled by --operation re-embed. memories (default) preserves the historical behaviour; entities and chunks rebuild entity_embeddings / chunk_embeddings; all covers the three tables in one run. The scan also selects rows whose stored dim diverges from the configured --embedding-dim (P10), so legacy-dimension vectors are regenerated, not only missing ones. Ignored (rejected) for every other operation.

dry_run: bool

Preview items without calling the LLM (zero tokens consumed).

namespace: Option<String>

Namespace to operate on. Default: global.

openrouter_model: Option<String>

OpenRouter text model to use (REQUIRED with –mode openrouter; no default).

openrouter_api_key: Option<String>

OpenRouter API key. Prefer config add-key --provider openrouter --from-stdin, which stores it at rest under XDG; this flag overrides that store for a single invocation and is visible in the process table.

openrouter_base_url: Option<String>

Timeout per item in seconds when using OpenRouter. Default: 600.

GAP-SG-17: raised from 300 to 600 because dense bodies (close to the ~32K-token context ceiling of the configured model) routinely take longer than five minutes to generate via deepseek-v4-flash:nitro. Raise it further for very large corpora; lower it for short snippets.

Optional OpenRouter base URL override (reserved; defaults to the public API).

max_cost_usd: Option<f64>

Abort when cumulative cost exceeds this USD budget (API key only; ignored for OAuth).

resume: bool

Resume a previously interrupted run (skip already-done items).

retry_failed: bool

Retry only items that failed in a previous run.

reset_stale_claims: bool

v1.1.2 (Bug 4): reset processing rows whose claimed_at is older than --stale-claim-secs (default 1800s = 30 min) back to pending, then exit. Recover rows orphaned by a kill -9 mid-enrich without a full re-scan.

stale_claim_secs: u64

v1.1.2 (Bug 4): age threshold (seconds) for --reset-stale-claims and the run-startup stale sweep. Default 1800 (30 min).

until_empty: bool

GAP-ENRICH-BACKLOG-CONVERGE: loop scan→drain internally until the queue empties of eligible items or –max-runtime elapses; removes the need for an external bash retry loop.

max_runtime: Option<u64>

GAP-ENRICH-BACKLOG-CONVERGE: wall-clock ceiling in seconds for –until-empty. Defaults to 3600 when omitted.

max_attempts: u32

GAP-ENRICH-BACKLOG-CONVERGE: attempts per item before it becomes a dead-letter (status=‘dead’). Range 1..=20. Default 8.

GAP-SG-21: the default was raised from 5 to 8 because GAP-SG-09 now reclassifies malformed / non-JSON LLM output as TRANSIENT (retryable) rather than a permanent HardFailure. A flaky structured-output model (e.g. deepseek-v4-flash:nitro) may emit several bad generations in a row even after JSON repair (GAP-SG-10) recovers most of them; the extra attempts give the backlog room to converge before an item is parked in the dead-letter sink. Permanent faults (ProviderError, NotFound) still dead-letter on the first attempt regardless of this value.

status: bool

GAP-ENRICH-BACKLOG-CONVERGE: read-only mode — report queue and backlog counts without calling the LLM or acquiring the singleton.

Field semantics (v1.1.03 clarification):

• scan_backlog = candidates a fresh scan WOULD select from the database (REAL pending work, same WHERE predicate as the scanners).
• queue_pending = a COMPUTED COUNT over the sidecar queue, NOT a physical queue of rows to process — it stays non-zero even after a clean drain.
• eligible_now == 0 WITH queue_pending > 0 means COOLDOWN (rate-limit backoff), NOT a deadlock: items are parked on next_retry_at.
• eligible_now > 0 stuck against state: "draining" IS a deadlock — stale processing claims hold the state. Run --reset-stale-claims to clear processing claims older than the threshold.

list_dead: bool

GAP-SG-23: list every dead-letter item (status=‘dead’) for the current operation with its error_class, attempt count and last error message. Read-only — no LLM, no singleton. Use it to inspect what --requeue-dead would resurrect before running it.

requeue_dead: bool

GAP-SG-11/14: resurrect dead-letter items — move every status='dead' row back to pending, zeroing attempt, next_retry_at, error and error_class. Distinct from --retry-failed, which only resets the legacy status='failed' rows; dead-letter rows are the terminal sink of the v1.0.96 converge loop and are never re-selected without this flag. No LLM call or singleton is taken — it only rewrites queue statuses.

list_skipped: bool

GAP-SG-96 / G-PR-4: list every status='skipped' row for the operation (preservation_failed / veto sink). Read-only — no LLM, no singleton.

requeue_skipped: bool

GAP-SG-96 / G-PR-3/4: resurrect skipped items — move every status='skipped' row back to pending, zeroing attempt/backoff so a lower grounding threshold or corpus fix can re-process them without SQL.

prune_dead_orphans: bool

GAP-SG-66: prune ORPHAN dead-letter rows — remove every status='dead' memory row whose item_key (the memory name) no longer exists in the main DB for this namespace. These are terminal “not found” failures that --requeue-dead can never recover (re-processing re-fails the same way), so they inflate queue_dead forever. Read-only on the main DB; deletes only confirmed-orphan rows from the queue sidecar. Entity-keyed dead rows are left untouched. No LLM, no singleton — like --list-dead.

prune_dead_entity_orphans: bool

v1.1.2: prune dead ENTITY orphan rows — remove every status='dead' item_type='entity' row from the queue sidecar. Distinct from --prune-dead-orphans (memory-keyed, consults the main DB): entity dead rows are terminal artifacts of re-extraction and have no recovery path, so no main-DB check is needed. Required because the v1.1.1 re-embed bug left 14680 entity-keyed dead-letter rows that the memory-scoped pruner cannot reach. No LLM, no singleton — like --list-dead.

ignore_backoff: bool

GAP-SG-16: ignore the per-item backoff cooldown (next_retry_at) when selecting candidates, so items waiting on exponential backoff are processed immediately. Use to drain a backlog whose cooldown windows are long but the provider has recovered. Without it, --status reports such items under waiting and they are skipped until their next_retry_at.

body_extract_graph_only: bool

GAP-SG-28: read-only body-extract — extract entities/relationships into the graph WITHOUT rewriting (or truncating) the memory body. The default body-extract restructures the stored body in place; with this flag the body is left untouched and only graph bindings are persisted (additive, via the same upsert path as memory-bindings). Ignored for every other operation.

rest_concurrency: u32

GAP-ENRICH-BACKLOG-CONVERGE: REST concurrency for --mode openrouter (clamp 1..=16). This is the ONLY flag that controls drain fan-out in OpenRouter mode; --llm-parallelism is inert there.

min_output_chars: usize

Minimum output character count for body-enrich. Default: 500.

max_output_chars: usize

Maximum output character count for body-enrich. Default: 2000.

preserve_check: bool

Accepted as a no-op: no line reads this field.

The name promises an LLM judge that verifies the enriched body preserves every fact of the original, and that judge was never wired. A sweep for preserve_check across src/ returns the declaration and one struct literal that SETS it — no reader. It is doubly inert, because default_value_t = true on a bool also means the flag cannot change its own value.

Kept accepted rather than removed so an existing invocation does not start failing with exit 2, and declared here rather than described, because a doc comment promising an effect no line produces is how this class survives review (GAP-SG-302).

prompt_template: Option<PathBuf>

Path to a custom prompt template file for body-enrich.

llm_parallelism: Option<u32>

ALWAYS INERT; accepted only so existing scripts keep parsing.

Use --rest-concurrency to size the drain fan-out. Passing this emits a warning and changes nothing.

json: bool

Emit NDJSON output. Always true; flag accepted for compatibility.

db: Option<String>

Database path override.

wait_job_singleton: Option<u64>

G30: poll for the job singleton every second for up to N seconds when another invocation holds the lock. Default: 0 (fail fast).

force_job_singleton: bool

G30: force acquisition of the singleton lock by removing a stale lock file from a previously crashed invocation. Use only when you are certain no other enrich/ingest is running.

names: Vec<String>

Select a subset of names to enrich instead of the full candidate set. Comma-separated, e.g. --names a,b,c. Semantics depend on the operation (GAP-CLI-NAMES-01): entity-keyed ops (entity-descriptions, entity-connect, …) treat values as entity names; memory-keyed ops (memory-bindings, body-enrich, …) treat values as memory names. Prefer --entity-names / --memory-names for an explicit namespace. Empty when omitted (processes all candidates).

GAP-SG-18: also a cooldown remedy — when --status shows items under waiting (parked on next_retry_at backoff), pass the exact names here to re-enqueue and process just that subset on the next run instead of waiting for every cooldown to elapse. REQUIRED for --operation augment-bindings, which refuses to re-scan the whole namespace.

names_file: Option<PathBuf>

G37: read the subset of memory names from a file (one per line). Lines starting with # and empty lines are ignored. Combined with --names (union) when both are set.

preflight_check: bool

G35: probe the LLM provider with a 1-turn ping before processing the batch. Aborts with a clear error if the rate-limit window is closed (avoids burning N turns only to fail on item 1).

rate_limit_buffer: u64

G35: number of seconds before the OAuth rate-limit reset at which the preflight probe should refuse to start. Default 300 (5 min).

max_load_check: bool

G28-D: refuse to start when the 1-minute load average exceeds 2 × ncpus (or XDG system.max_load_per_ncpu if set). Set to false to skip the check on contended runners.

The key is system. and not enrich.: this help named a key that the registry never declared, so the documented config set answered exit 1 with a did-you-mean pointing at the real one.

“Set to false” above was unreachable until v1.2.8: default_value_t = true on a bool gives ArgAction::SetTrue over a default that is already true, so this flag alone cannot turn the check off. --no-max-load-check is what does, following the --auto-describe pair in ingest (GAP-SG-302).

no_max_load_check: bool

Skip the load-average refusal on a contended runner.

circuit_breaker_threshold: u32

G28-D: when the system is saturated, abort the job after this many consecutive HardFailure outcomes. Default 5.

preserve_threshold: f64

G29 Step 4: minimum trigram-Jaccard similarity between the original body and the LLM-rewritten body for the rewrite to be accepted. Scores below the threshold are rejected and emitted as EnrichItemResult::PreservationFailed. Default 0.7 (per the G29 gap specification). Ignored when --operation is not body-enrich.

entity_description_grounding_threshold: Option<f64>

GAP-CLI-ED-03: minimum grounding coverage of an entity description against linked memory bodies. Uses trigram coverage (|A∩B|/|A|), not symmetric Jaccard, because descriptions are short. Only applies to entity-descriptions.

Precedence: this flag, then XDG enrich.entity_description.grounding_threshold, then the compiled DEFAULT_ENRICH_GROUNDING_THRESHOLD. Read through the accessor of the same name, never as a bare field.

The constant is deliberately NOT an intra-doc link here: this field is pub while the constant is pub(crate), and [lints.rustdoc] denies private_intra_doc_links since GAP-SG-211.

Zero is a LITERAL zero — it accepts every candidate. It used to mean “use the compiled default”, and that sentinel was the defect: a default_value_t here meant clap always supplied a value, so the branch reading the compiled constant only ran when an operator typed 0 explicitly. Raising the constant therefore changed nothing in production, and the XDG key had no reader at all.

force_redescribe: bool

GAP-CLI-ED-06 / CAPA-B: re-scan entities whose description is empty OR matches high-precision low-quality compound markers (e.g. “is a software component”, “is a configuration file” — not bare domain phrases). Once per invocation, reopens matching skipped/done queue rows for those scan keys to pending (does not reopen dead; use --requeue-dead). Default false (write-once for non-empty descriptions).

quality_sample: Option<usize>

Wave 2 / GAP-CLI-OBS-04: sample N entities with descriptions and report quality_pct / scan_backlog_low_grounding_est on --status. scan_backlog_low_grounding_est is a sample-based estimate only — it is not a drain backlog and is not processed by --force-redescribe. Precedence: this flag > XDG enrich.entity_description.quality_sample

default 50. Set 0 to disable sampling.

entity_names: Vec<String>

GAP-CLI-NAMES-02: explicit entity name filter (entity-descriptions, entity-connect, …). Alias of --names for entity-keyed ops.

entity_type: Option<String>

Restrict an entity-keyed operation to entities carrying this type label.

v1.2.8: entity-type-validate scanned the whole namespace at random, with no way to aim it. That is the operation which can propose a better label for the entities the closed vocabulary collapsed into concept, and without a filter the only way to reach them was to pay for every entity in the graph. --entity-type concept aims it at exactly the bucket that needs revisiting.

Free text, matched literally against the stored label, because the vocabulary is open since V017 and a closed value set here would refuse the very labels this flag exists to look for.

allowed_types: Vec<String>

GAP-SG-283: entity type labels this project accepts, comma separated.

remember --strict-entity-types and link --strict-relations already let a project declare its vocabulary on the hand-written write channels. enrich declared nothing, and it is the channel that writes type labels in VOLUME: entity-type-validate persists whatever the model returns.

Precedence: this flag > XDG enrich.entity_type.allowed_types > the canonical vocabulary compiled into the binary. An empty declaration falls through to the next layer rather than refusing every label.

Labels are shape-normalised on the way in, so Issue-Tracker and issue_tracker declare the same member. What to do with a label outside the set is --on-unknown-type.

on_unknown_type: Option<String>

GAP-SG-283: policy for a validated entity type outside --allowed-types.

keep (the default) stores the label as written, which is byte-for-byte the v1.2.8 behaviour — an existing caller passing no flag is unaffected. fallback stores the nearest accepted label and preserves the raw one in the entity description, so the rewrite has a declared inverse. strict refuses the item with exit 1, mirroring remember --strict-entity-types.

Precedence: this flag > XDG enrich.entity_type.on_unknown_type > keep. Applies to --operation entity-type-validate; every other operation ignores it.

Parsed against the same list the policy module parses, so the flag and the reader cannot accept different sets.

memory_names: Vec<String>

GAP-CLI-NAMES-02: explicit memory name filter (memory-bindings, body-enrich, …). Alias of --names for memory-keyed ops.

anchor_memory: Option<String>

GAP-CLI-EC-03: limit entity-connect pair scan to the subgraph of entities linked to this memory name.

entity_description_domain: String

GAP-CLI-ED-05: optional domain label for entity-descriptions (auto = no hint, none = force neutral, or free-form e.g. fiscal). Precedence: this flag > XDG enrich.entity_description.domain > auto.

yield_every_n_items: Option<usize>

GAP-CLI-PRIO-05: cooperative yield every N processed items so hot-set entity-descriptions can preempt long entity-connect drains. 0 disables. XDG key: enrich.yield_every_n_items (default 10).

ops_gate: bool

GAP-CLI-OBS-02 / PRIO-04: run gate ops in order memory-bindings → entity-descriptions (before entity-connect).

print_schema: bool

Emit the JSON Schema for enrich --status stdout and exit 0 without opening the database or calling the LLM (agent-native R-AN-01).

Trait Implementations

impl Args for EnrichArgs

fn group_id() -> Option<Id>

Report the ArgGroup::id for this set of arguments

fn augment_args<'b>(__clap_app: Command) -> Command

Append to Command so it can instantiate Self via FromArgMatches::from_arg_matches_mut

fn augment_args_for_update<'b>(__clap_app: Command) -> Command

Append to Command so it can instantiate self via FromArgMatches::update_from_arg_matches_mut

impl Clone for EnrichArgs

fn clone(&self) -> EnrichArgs

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl FromArgMatches for EnrichArgs

fn from_arg_matches(__clap_arg_matches: &ArgMatches) -> Result<Self, Error>

Instantiate Self from ArgMatches, parsing the arguments as needed.

fn from_arg_matches_mut( __clap_arg_matches: &mut ArgMatches, ) -> Result<Self, Error>

Instantiate Self from ArgMatches, parsing the arguments as needed.

fn update_from_arg_matches( &mut self, __clap_arg_matches: &ArgMatches, ) -> Result<(), Error>

Assign values from ArgMatches to self.

fn update_from_arg_matches_mut( &mut self, __clap_arg_matches: &mut ArgMatches, ) -> Result<(), Error>

Assign values from ArgMatches to self.