Add in-app rule authoring backed by a draft rules table

.gitignore

@@ -307,5 +307,8 @@ Cargo.lock
 
 .claude
 
+# Local docker compose overrides (env vars, port remaps, secrets)
+docker-compose.override.yaml
+
 # docs output
 book/

CHANGELOG.md

@@ -24,6 +24,7 @@ For more information about each release including git tags and artifacts, see [R
 - Per-action health metrics in the executor ([#191](https://github.com/roostorg/osprey/pull/191) by [@cmttt](https://github.com/cmttt))
 - Option to suppress cached errors to reduce metric bloat ([#180](https://github.com/roostorg/osprey/pull/180) by [@lithium-powered](https://github.com/lithium-powered))
 - Experimental asyncio-native worker with metrics and engine/coordinator improvements ([#341](https://github.com/roostorg/osprey/pull/341) by [@cmttt](https://github.com/cmttt))
+- Experimental in-app rule authoring with a `rule_drafts` table and deployment hooks ([#402](https://github.com/roostorg/osprey/pull/402) by [@julietshen](https://github.com/julietshen))
 - ATProto JetStream example plugins and rules ([#236](https://github.com/roostorg/osprey/pull/236) by [@haileyok](https://github.com/haileyok))
 - `osprey-stress` CLI: closed-loop stress harness that produces synthetic events at a configurable rate, observes their `ExecutionResult`s on the output topic, and reports drop rate and p50/p95/p99 latency, exiting non-zero on threshold breach so it can gate CI on pipeline health ([#367](https://github.com/roostorg/osprey/pull/367) by [@julietshen](https://github.com/julietshen), closes [#324](https://github.com/roostorg/osprey/issues/324))
 

docs/user/manage.md

@@ -56,3 +56,28 @@ The list is paginated (50 per page) and can be filtered and sorted:
 - **Sort**: by name, most referenced, or least referenced
 
 Each row shows the rule's name, source file, description, reference count, and line number within the source file.
+
+## Rule Authoring (Experimental feature)
+
+Users can draft SML rules directly in the UI. Drafts are saved to a `rule_drafts` table so the people who operate Osprey can reference, edit, and deploy them without any external code host.
+
+The editor validates every keystroke against the same AST validator the running engine uses, so compile-time errors surface before a draft is saved. The Rule Builder view expresses the common shape (name, conditions, outcomes) as a form and generates SML; the Code Editor view accepts arbitrary SML for anything the builder can't represent.
+
+### The draft rules table
+
+Drafts live in a Postgres table (`rule_drafts`), one row per rule file path. The API (all gated by the `CAN_EDIT_RULE_DRAFTS` ability, granted to `super_user`):
+
+- `POST /rule-drafts` — re-validates the SML server-side, then upserts the draft.
+- `GET /rule-drafts` — lists every draft (the table operators work from).
+- `GET /rule-drafts/<id>` — fetches a single draft.
+- `POST /rule-drafts/<id>/deploy` — re-validates, writes the SML into the rules directory, and marks the draft `deployed`. Pass `wire_into_main: true` to also append a `Require(rule=...)` line to `main.sml` so the rule takes effect (a rule file is inert until something requires it).
+
+### Deploying
+
+Deploy writes the draft's SML into a rules directory that the engine's sources provider already loads (a filesystem hand-off: whatever pipeline syncs that directory activates the rule).
+
+| Var | Default | Notes |
+|---|---|---|
+| `OSPREY_RULES_LOCAL_PATH` | _required for deploy_ | Absolute path to the rules directory the engine loads. Deploy writes SML here; must already exist. If unset, `POST /deploy` returns 503 (drafting and validation still work). |
+
+> **Future direction:** a DB-backed `SourcesProvider` could let the engine load deployed drafts straight from the `rule_drafts` table, removing the filesystem hand-off and making rule management work with zero external infrastructure. This PR keeps the filesystem deploy; the table is already the source of truth for drafts.

osprey_worker/src/osprey/worker/lib/acls/definitions/super_user.json

@@ -40,6 +40,10 @@
     {
       "name": "CAN_VIEW_EVENTS_BY_ACTION",
       "allow_all": true
+    },
+    {
+      "name": "CAN_EDIT_RULE_DRAFTS",
+      "allow_all": true
     }
   ],
   "ability_groups": ["CAN_VIEW_BASIC_USER_DATA"]

osprey_worker/src/osprey/worker/lib/osprey_engine.py

@@ -157,6 +157,14 @@ def _handle_updated_sources(self) -> None:
     def execution_graph(self) -> ExecutionGraph:
         return self._execution_graph
 
+    @property
+    def udf_registry(self) -> UDFRegistry:
+        return self._udf_registry
+
+    @property
+    def validator_registry(self) -> ValidatorRegistry:
+        return self._validator_registry
+
     @property
     def config(self) -> SourcesConfig:
         return self._execution_graph.validated_sources.sources.config

osprey_worker/src/osprey/worker/lib/storage/postgres.py

@@ -56,6 +56,7 @@ def _init(config: Config) -> None:
             bulk_label_task,
             pg_stored_execution,
             queries,
+            rule_drafts,
             temporary_ability_token,
         )
 

osprey_worker/src/osprey/worker/lib/storage/rule_drafts.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from enum import StrEnum
+
+from sqlalchemy import BigInteger, Column, DateTime, Enum, Text
+from sqlalchemy.dialects.postgresql import insert as pg_insert
+
+from .postgres import Model, scoped_session
+
+
+def _now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+class RuleDraftStatus(StrEnum):
+    DRAFT = 'draft'
+    DEPLOYED = 'deployed'
+
+
+class RuleDraft(Model):
+    """A staged SML rule draft.
+
+    Drafts are authored and validated in the UI and live here so the people who
+    operate Osprey can reference, edit, and deploy them without any external code
+    host. Deploying writes the SML into the configured rules directory; the draft
+    row stays as the record of what was deployed.
+
+    One row per rule `path` (upserted on submit), so the table reads as the
+    current set of drafts rather than an append-only history.
+    """
+
+    __tablename__ = 'rule_drafts'
+
+    id: int = Column(BigInteger, primary_key=True, autoincrement=True)
+    path: str = Column(Text, nullable=False, unique=True)
+    rule_name: str = Column(Text, nullable=False)
+    sml_source: str = Column(Text, nullable=False)
+    summary: str = Column(Text, nullable=False, default='')
+    # Osprey has no users table; identity is just an email with ACLs applied, so
+    # this stores the author's email rather than a foreign key.
+    author_email: str = Column(Text, nullable=False)
+    status: RuleDraftStatus = Column(
+        Enum(RuleDraftStatus, native_enum=False, length=32),
+        nullable=False,
+        default=RuleDraftStatus.DRAFT,
+    )
+    created_at: datetime = Column(DateTime(timezone=True), nullable=False, default=_now)
+    updated_at: datetime = Column(DateTime(timezone=True), nullable=False, default=_now, onupdate=_now)
+    deployed_at: datetime | None = Column(DateTime(timezone=True), nullable=True)  # type: ignore[misc]
+
+    def to_json(self) -> dict[str, object]:
+        return {
+            'id': self.id,
+            'path': self.path,
+            'rule_name': self.rule_name,
+            'source': self.sml_source,
+            'summary': self.summary,
+            'author': self.author_email,
+            'status': str(self.status),
+            'created_at': self.created_at.isoformat() if self.created_at else None,
+            'updated_at': self.updated_at.isoformat() if self.updated_at else None,
+            'deployed_at': self.deployed_at.isoformat() if self.deployed_at else None,
+        }
+
+    @classmethod
+    def upsert(cls, *, path: str, rule_name: str, sml_source: str, summary: str, author_email: str) -> 'RuleDraft':
+        """Create the draft for `path`, or update it in place if one already exists.
+
+        Uses a single `INSERT ... ON CONFLICT DO UPDATE` so two concurrent saves of
+        the same path can't both see "no row" and then race the unique constraint.
+        Editing a deployed draft moves it back to `DRAFT` so the table reflects that
+        the in-flight SML no longer matches what was last deployed.
+        """
+        now = _now()
+        mutable = {
+            'rule_name': rule_name,
+            'sml_source': sml_source,
+            'summary': summary,
+            'author_email': author_email,
+            'status': RuleDraftStatus.DRAFT,
+            'updated_at': now,
+        }
+        statement = (
+            pg_insert(cls.__table__)
+            .values(path=path, created_at=now, **mutable)
+            .on_conflict_do_update(index_elements=[cls.path], set_=mutable)
+        )
+        with scoped_session(commit=True) as session:
+            session.execute(statement)
+            session.flush()
+            draft = session.query(cls).filter(cls.path == path).one()
+            session.expunge(draft)
+            return draft
+
+    @classmethod
+    def list_all(cls) -> list['RuleDraft']:
+        with scoped_session() as session:
+            drafts = session.query(cls).order_by(cls.updated_at.desc()).all()
+            session.expunge_all()
+            return drafts
+
+    @classmethod
+    def get_one(cls, draft_id: int) -> 'RuleDraft | None':
+        with scoped_session() as session:
+            draft = session.query(cls).filter(cls.id == draft_id).first()
+            if draft is not None:
+                session.expunge(draft)
+            return draft
+
+    @classmethod
+    def other_with_rule_name(cls, rule_name: str, *, exclude_path: str) -> 'RuleDraft | None':
+        """A draft at a different path that already uses `rule_name`, if one exists.
+
+        Rule names are global identifiers in SML, so two drafts sharing a name would
+        collide once both deploy. Validation only sees deployed rules, not other
+        drafts, so this catches the draft-vs-draft case that validation can't.
+        """
+        with scoped_session() as session:
+            draft = session.query(cls).filter(cls.rule_name == rule_name, cls.path != exclude_path).first()
+            if draft is not None:
+                session.expunge(draft)
+            return draft
+
+    @classmethod
+    def mark_deployed(cls, draft_id: int) -> 'RuleDraft | None':
+        with scoped_session(commit=True) as session:
+            draft = session.query(cls).filter(cls.id == draft_id).first()
+            if draft is None:
+                return None
+            draft.status = RuleDraftStatus.DEPLOYED
+            draft.deployed_at = _now()
+            session.flush()
+            session.expunge(draft)
+            return draft

osprey_worker/src/osprey/worker/ui_api/osprey/app.py

@@ -68,6 +68,7 @@ def create_app() -> Flask:
         events,
         features,
         queries,
+        rule_drafts,
         rules,
         rules_visualizer,
         saved_queries,
@@ -111,6 +112,7 @@ def create_app() -> Flask:
     _register_with_prefix(app, events.blueprint)
     _register_with_prefix(app, features.blueprint)
     _register_with_prefix(app, rules.blueprint)
+    _register_with_prefix(app, rule_drafts.blueprint)
     _register_with_prefix(app, queries.blueprint)
     _register_with_prefix(app, config.blueprint)
     _register_with_prefix(app, docs.blueprint)

osprey_worker/src/osprey/worker/ui_api/osprey/lib/abilities.py

@@ -535,6 +535,7 @@ def _get_query_filter(self) -> dict[str, Any] | None:
 CanViewSavedQueries = register_ability('CAN_VIEW_SAVED_QUERIES')(make_marker_ability())
 CanCreateAndEditSavedQueries = register_ability('CAN_CREATE_AND_EDIT_SAVED_QUERIES')(make_marker_ability())
 CanBulkAction = register_ability('CAN_BULK_ACTION')(make_marker_ability())
+CanEditRuleDrafts = register_ability('CAN_EDIT_RULE_DRAFTS')(make_marker_ability())
 
 
 def require_ability_with_request(request_model: ModelT, ability_class: Type[Ability[ModelT, ItemT]]) -> None: