Skip to main content

Default Plugin Business Rules

These are the default plugin's own business rules — how the reference implementation handles Things, workspaces, statuses, finalization, input, and output. They're plugin-owned (the core doesn't enforce them), and they're documented here as a model: when you build your plugin, this is the kind of rule set you define for your domain.

Thing and workspace ownership​

  • A Thing (default_plugin_thing) is the stable business object; a workspace is a working branch of it. Their relationship is the default_plugin_workspace join table. Workflow progress and history are workspace-scoped; aggregate concepts (active workspace, final workspace, completion) live at the Thing layer.
  • Do not model workflow progress on the Thing — operational status lives on the workspace.

Active workspace​

  • Each Thing has exactly one active workspace at a time, stored on default_plugin_thing.active_workspace_id, always pointing to a workspace that belongs to that Thing and (while the Thing is live) is not soft-deleted.
  • Normal workspace selectors exclude soft-deleted links (is_deleted = true).
  • In v1 the default plugin doesn't expose per-workspace deletion — deletion is Thing-level only.

Statuses and transitions​

  • Canonical statuses: new → text_generated → input_provided → media_generated → completed. The initial (new) and finalizable (completed) statuses are manifest-driven, not hardcoded.
  • Workflow-driven transitions: the core moves the workspace to the workflow's resulting status after the result handler succeeds. Plugin-driven transitions go through coreWorkspaceService.updateStatus — the only one in the default plugin is submitting input → input_provided. completed is reached only via workflows; there's no manual "mark done."

Completion vs. finalization​

  • A Thing is completed if at least one of its workspaces has reached completed; this drives the dashboard KPI. Multiple workspaces can be completed at once.
  • Finalization is separate: the operator designates one completed workspace as the canonical final version, recorded on final_workspace_id, which puts the Thing into frozen (read-only) mode (only Unfinalize remains). Unfinalizing clears it and exits frozen mode. Finalization never changes any workspace's status.

Sections, creation, and deletion​

  • Sections (default_plugin_section) group Things (at most one section per Thing), with ordering; an empty section can be deleted, a non-empty one cannot.
  • Creating a Thing always produces an initial new workspace and a join row via core services.
  • Deleting a Thing is a soft delete (is_deleted = true) that cascades is_deleted to its workspace links and freezes the Thing; core workspace rows are never deleted, and execution/cost history is preserved.

Input and output​

  • Input (default_plugin_input) is stored append-only per workspace; submitting transitions the workspace to input_provided. (The backend doesn't gate input on status — which statuses show the input form is a frontend concern.)
  • Output (default_plugin_output) stores results per workspace with an output_type (text, media, image, audio, video); persistence happens in the plugin's resultHandler.

Cost reporting​

  • A Thing's production cost is aggregated across all its workspaces and executions (via the join table → workflow_execution → workflow_execution_log.cost_usd), and is unaffected by workspace deletion or archival.

Read these as a worked example of the rule set a plugin author writes for their own domain — the shape and concerns carry over even when the specifics don't.