reflect_start

Category: reflection
Access: write
Audience: advanced (ordinary users do not normally call this directly)

Purpose

Creates a reflection run and executes the extract stage synchronously. Call it to turn an audit preview into reviewable persisted candidates.

Arguments

Optional: abandoned_inbox_days, created_by, instructions, limit_per_category, model, project, stale_days, version.

abandoned_inbox_days.
created_by: actor recorded in reflection_runs.created_by. Note: Actor recorded on the run; defaults user.
instructions: free-form guidance text (max 4096 chars per C14/Dreams). Note: Free-form guidance, at most 4096 characters; longer fails as instructions_too_long.
limit_per_category.
model: optional model id for future LLM-based runs (Phase 2 uses). Note: Optional model id for future runs; recorded only.
project: optional project filter for the audit pass.
stale_days.
version: run schema version for forward-compat (default reflect_v1.0). Note: Run schema version; defaults reflect_v1.0.

Result

Object with run_id, status (completed, or failed on cap exhaustion), candidates_persisted, summary, and on failure error_type.

Boundaries

An explicit project must be granted; unfiltered runs are star-only since their candidates would span all projects. The audit scan constrains to grants.

Lifecycle / side effects

Creates a pending entry, records the filter input, marks it running, reuses the Phase 0.5 audit to persist one candidate per finding (capped at 10000, beyond which the run fails as candidate_limit_exceeded), then marks it completed. All-or-nothing per run.

Errors

Out-of-scope project or non-star global request fails as invalid_argument. Overlong instructions fail as instructions_too_long. Engine failures return normal internal_error payloads with a best-effort failed marking.

Example

{
  "instructions": "Prefer archiving stale drafts"
}

Result shape:

{
  "candidates_persisted": 4,
  "run_id": "<uuid>",
  "status": "completed",
  "summary": {
    "by_category": {
      "stale_overdue_tasks": 4
    },
    "total_candidates": 4
  }
}