spine-framework 0.4.3 → 0.5.0-rc.4

package/.framework/migrations/067_episode_lease_stale_steal.sql

@@ -0,0 +1,93 @@
+-- Migration 067: stale-gated detached-driver steal
+--
+-- 066 let a request-bound driver steal any live 'detached:' lease
+-- unconditionally. That guaranteed a mid-turn displacement on every
+-- guided run (triage kick claims first, the client's episode POST steals
+-- seconds later), fencing a healthy driver and leaving research_state
+-- mid-flight — the residual duplicate-narration class. Steal is a
+-- recovery path for STALLED background work, so it now requires the
+-- holder's heartbeat (updated_at, renewed by heartbeat_episode_lease)
+-- to be older than p_stale_seconds. Healthy detached drivers are
+-- refused 'held' like any other live driver.
+
+-- CIL[BEGIN stable_id="~/.framework/migrations/067_episode_lease_stale_steal.sql:module:migration" type="migration" identity="episode-lease-stale-steal" parent="~/.framework/migrations/067_episode_lease_stale_steal.sql"]
+-- CIL[DOC-MACRO purpose="Gate p_steal_detached on the holder's heartbeat age so request drivers only displace stalled background work"]
+-- CIL[DOC-RESPONSIBILITY responsibility="Redefine acquire_episode_lease with a p_stale_seconds parameter; detach-prefix holders are stealable only when updated_at exceeds the staleness window"]
+-- CIL[DOC-CONTEXT module="episode-concurrency" layer="schema" related_files=".framework/functions/_shared/agent-runner.ts,.framework/functions/ai-agents.ts"]
+-- CIL[DOC-CONTRACT inputs="p_thread_id uuid, p_account_id uuid, p_driver_id text, p_ttl_seconds int default 90, p_steal_detached bool default false, p_stale_seconds int default 30" outputs="jsonb verdict {outcome: claimed|held, lease_token?, holder_driver_id?}" errors="none — fail-open verdict" side_effects="inserts or updates episode_leases"]
+-- CIL[DOC-MICRO logic_summary="Identical to 066 except the steal branch additionally requires v_lease.updated_at to be older than p_stale_seconds; heartbeat renewals keep a healthy detached driver unstealable" notable_decisions="30s default bounds takeover latency well under the 90s TTL while tolerating slow single turns between heartbeats"]
+-- CIL[DOC-CONFIDENCE pass="first" score="0.92" flags="none"]
+-- CIL[DOC-STABILITY stability="stable"]
+-- CIL[DOC-AUDIENCE audience="system-admin"]
+-- CIL[DOC-VECTOR type="context" content="Third lease RPC revision: 063 atomic claim, 066 detached steal, 067 stale-gated steal" status="ready"]
+-- CIL[END stable_id="~/.framework/migrations/067_episode_lease_stale_steal.sql:module:migration"]
+
+DROP FUNCTION IF EXISTS public.acquire_episode_lease(uuid, uuid, text, integer, boolean);
+
+CREATE FUNCTION public.acquire_episode_lease(
+  p_thread_id uuid,
+  p_account_id uuid,
+  p_driver_id text,
+  p_ttl_seconds integer DEFAULT 90,
+  p_steal_detached boolean DEFAULT false,
+  p_stale_seconds integer DEFAULT 30
+)
+RETURNS jsonb
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+DECLARE
+  v_lease        public.episode_leases%ROWTYPE;
+  v_new_token    uuid := gen_random_uuid();
+BEGIN
+  INSERT INTO public.episode_leases (thread_id, account_id, driver_id, lease_token, expires_at)
+  VALUES (
+    p_thread_id,
+    p_account_id,
+    p_driver_id,
+    v_new_token,
+    now() + make_interval(secs => p_ttl_seconds)
+  )
+  ON CONFLICT (thread_id) DO NOTHING;
+
+  IF FOUND THEN
+    RETURN jsonb_build_object('outcome', 'claimed', 'lease_token', v_new_token);
+  END IF;
+
+  SELECT * INTO v_lease
+  FROM public.episode_leases
+  WHERE thread_id = p_thread_id
+  FOR UPDATE;
+
+  -- Held: a different live driver owns the episode. Steal is allowed
+  -- only for a 'detached:'-prefixed holder whose heartbeat has gone
+  -- stale — a healthy background driver is refused like anyone else so
+  -- request claims stop displacing mid-turn work.
+  IF v_lease.driver_id <> p_driver_id
+     AND v_lease.expires_at > now()
+     AND NOT (p_steal_detached
+              AND v_lease.driver_id LIKE 'detached:%'
+              AND v_lease.updated_at < now() - make_interval(secs => p_stale_seconds)) THEN
+    RETURN jsonb_build_object(
+      'outcome', 'held',
+      'holder_driver_id', v_lease.driver_id
+    );
+  END IF;
+
+  UPDATE public.episode_leases SET
+    driver_id   = p_driver_id,
+    lease_token = v_new_token,
+    account_id  = p_account_id,
+    expires_at  = now() + make_interval(secs => p_ttl_seconds),
+    updated_at  = now()
+  WHERE thread_id = p_thread_id;
+
+  RETURN jsonb_build_object('outcome', 'claimed', 'lease_token', v_new_token);
+END;
+$$;
+
+REVOKE ALL ON FUNCTION public.acquire_episode_lease(uuid, uuid, text, integer, boolean, integer) FROM PUBLIC;
+REVOKE ALL ON FUNCTION public.acquire_episode_lease(uuid, uuid, text, integer, boolean, integer) FROM anon;
+REVOKE ALL ON FUNCTION public.acquire_episode_lease(uuid, uuid, text, integer, boolean, integer) FROM authenticated;
+GRANT EXECUTE ON FUNCTION public.acquire_episode_lease(uuid, uuid, text, integer, boolean, integer) TO service_role;

package/.framework/migrations/068_cron_schedule_timer_rpcs.sql

@@ -0,0 +1,251 @@
+-- Migration 068: bootstrap the RPCs system-cron expects
+--
+-- system-cron calls nine Postgres functions that were documented as
+-- "bootstrapped by framework migrations" but never created — every tick
+-- hard-failed on get_due_schedules with
+--   "Could not find the function public.get_due_schedules(p_now) in the
+--    schema cache"
+-- This migration creates the missing RPCs against the existing
+-- schedules / timers / schedule_executions / pipeline_executions / logs
+-- tables.
+--
+-- Honest limits (the tables are half-designed — schedules has no
+-- config/delegated_scopes columns and there is no cron-expression
+-- evaluator in the DB):
+--   * get_due_schedules returns delegated_scopes=NULL and config='{}'
+--     (the cron handler already tolerates both).
+--   * update_schedule_after_run reschedules only the every-N-minutes
+--     cron form ('*/N * * * *'); anything else gets next_run_at=NULL so
+--     a schedule can never re-fire every tick forever.
+--   * update_timer_after_run reschedules when
+--     config->>'interval_minutes' is a positive number, else NULL.
+
+-- CIL[BEGIN stable_id="~/.framework/migrations/068_cron_schedule_timer_rpcs.sql:module:migration" type="migration" identity="cron-schedule-timer-rpcs" parent="~/.framework/migrations/068_cron_schedule_timer_rpcs.sql"]
+-- CIL[DOC-MACRO purpose="Create the nine Postgres RPCs system-cron invokes for schedules, timers, threshold metrics and log cleanup"]
+-- CIL[DOC-RESPONSIBILITY responsibility="Provide get_due_schedules, validate_schedule_creator, update_schedule_after_run, get_due_timers, update_timer_after_run, get_error_rate, get_latency_percentiles, get_pipeline_stats, cleanup_old_logs"]
+-- CIL[DOC-CONTEXT module="system-cron" layer="schema" related_files=".framework/functions/system-cron.ts"]
+-- CIL[DOC-CONTRACT inputs="timestamptz/uuid/bool/int params per function" outputs="setof rows or scalars matching the shapes system-cron reads" errors="none — SECURITY DEFINER, stable where read-only" side_effects="update_schedule_after_run/update_timer_after_run mutate schedule/timer rows; cleanup_old_logs deletes old logs"]
+-- CIL[DOC-MICRO logic_summary="Simple SELECT/UPDATE/DELETE implementations; cron reschedule limited to '*/N * * * *', timers honor config->>'interval_minutes', everything else next_*=NULL to prevent infinite re-fire" notable_decisions="No speculative cron parser — a NULL next_run_at is a safe one-shot stop until the feature gets a real scheduler model"]
+-- CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+-- CIL[DOC-STABILITY stability="stable"]
+-- CIL[DOC-AUDIENCE audience="system-admin"]
+-- CIL[END stable_id="~/.framework/migrations/068_cron_schedule_timer_rpcs.sql:module:migration"]
+
+-- ── schedules ─────────────────────────────────────────────────────────
+
+CREATE OR REPLACE FUNCTION public.get_due_schedules(p_now timestamptz)
+RETURNS TABLE (
+  schedule_id uuid,
+  action_id uuid,
+  account_id uuid,
+  machine_principal_id uuid,
+  delegated_scopes jsonb,
+  config jsonb
+)
+LANGUAGE sql
+STABLE
+SECURITY DEFINER
+SET search_path = public
+AS $$
+  SELECT
+    s.id,
+    s.action_id,
+    s.account_id,
+    s.machine_principal_id,
+    NULL::jsonb,
+    '{}'::jsonb
+  FROM public.schedules s
+  WHERE s.is_active
+    AND s.next_run_at IS NOT NULL
+    AND s.next_run_at <= p_now
+$$;
+
+CREATE OR REPLACE FUNCTION public.validate_schedule_creator(p_schedule_id uuid)
+RETURNS TABLE (is_valid boolean, error_message text)
+LANGUAGE sql
+STABLE
+SECURITY DEFINER
+SET search_path = public
+AS $$
+  SELECT
+    EXISTS (
+      SELECT 1 FROM public.schedules s
+      WHERE s.id = p_schedule_id AND s.is_active
+    ),
+    CASE
+      WHEN NOT EXISTS (SELECT 1 FROM public.schedules s WHERE s.id = p_schedule_id)
+        THEN 'schedule not found'
+      WHEN NOT EXISTS (SELECT 1 FROM public.schedules s WHERE s.id = p_schedule_id AND s.is_active)
+        THEN 'schedule is not active'
+      ELSE NULL
+    END
+$$;
+
+CREATE OR REPLACE FUNCTION public.update_schedule_after_run(
+  p_schedule_id uuid,
+  p_success boolean,
+  p_error_message text
+)
+RETURNS void
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+DECLARE
+  v_cron text;
+  v_minutes integer;
+BEGIN
+  SELECT cron_expression INTO v_cron FROM public.schedules WHERE id = p_schedule_id;
+
+  -- Only the every-N-minutes form is reschedulable here; a full cron
+  -- evaluator does not exist in the DB. Anything else becomes a
+  -- one-shot (NULL next_run_at) rather than re-firing every tick.
+  v_minutes := NULL;
+  IF v_cron ~ '^\*/(\d+) \* \* \* \*$' THEN
+    v_minutes := substring(v_cron FROM '^\*/(\d+)')::integer;
+  END IF;
+
+  UPDATE public.schedules
+  SET
+    last_run_at = now(),
+    next_run_at = CASE
+      WHEN v_minutes IS NOT NULL THEN now() + make_interval(mins => v_minutes)
+      ELSE NULL
+    END,
+    updated_at = now()
+  WHERE id = p_schedule_id;
+END;
+$$;
+
+-- ── timers ────────────────────────────────────────────────────────────
+
+CREATE OR REPLACE FUNCTION public.get_due_timers(p_now timestamptz)
+RETURNS TABLE (
+  timer_id uuid,
+  pipeline_id uuid,
+  account_id uuid,
+  app_id uuid,
+  name text,
+  execution_count integer,
+  created_by uuid
+)
+LANGUAGE sql
+STABLE
+SECURITY DEFINER
+SET search_path = public
+AS $$
+  SELECT
+    t.id,
+    t.pipeline_id,
+    t.account_id,
+    t.app_id,
+    t.name,
+    COALESCE(t.execution_count, 0),
+    t.created_by
+  FROM public.timers t
+  WHERE t.is_active
+    AND t.pipeline_id IS NOT NULL
+    AND t.next_execution IS NOT NULL
+    AND t.next_execution <= p_now
+$$;
+
+CREATE OR REPLACE FUNCTION public.update_timer_after_run(
+  p_timer_id uuid,
+  p_success boolean,
+  p_error_message text
+)
+RETURNS void
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+DECLARE
+  v_interval numeric;
+BEGIN
+  SELECT CASE
+    WHEN config->>'interval_minutes' ~ '^\d+(\.\d+)?$'
+      THEN (config->>'interval_minutes')::numeric
+    ELSE NULL
+  END INTO v_interval
+  FROM public.timers WHERE id = p_timer_id;
+
+  UPDATE public.timers
+  SET
+    last_execution = now(),
+    execution_count = COALESCE(execution_count, 0) + 1,
+    success_count = COALESCE(success_count, 0) + CASE WHEN p_success THEN 1 ELSE 0 END,
+    failure_count = COALESCE(failure_count, 0) + CASE WHEN p_success THEN 0 ELSE 1 END,
+    next_execution = CASE
+      WHEN v_interval IS NOT NULL AND v_interval > 0
+        THEN now() + make_interval(mins => v_interval::double precision)
+      ELSE NULL
+    END,
+    updated_at = now()
+  WHERE id = p_timer_id;
+END;
+$$;
+
+-- ── threshold metrics ─────────────────────────────────────────────────
+
+CREATE OR REPLACE FUNCTION public.get_error_rate(p_window_minutes integer)
+RETURNS TABLE (error_rate numeric)
+LANGUAGE sql
+STABLE
+SECURITY DEFINER
+SET search_path = public
+AS $$
+  SELECT CASE WHEN count(*) = 0 THEN 0
+    ELSE round(count(*) FILTER (WHERE outcome = 'failure' OR level = 'error')::numeric * 100 / count(*), 2)
+  END
+  FROM public.logs
+  WHERE created_at >= now() - make_interval(mins => p_window_minutes)
+$$;
+
+CREATE OR REPLACE FUNCTION public.get_latency_percentiles(p_window_minutes integer)
+RETURNS TABLE (p50 numeric, p95 numeric, p99 numeric)
+LANGUAGE sql
+STABLE
+SECURITY DEFINER
+SET search_path = public
+AS $$
+  SELECT
+    percentile_cont(0.50) WITHIN GROUP (ORDER BY duration_ms)::numeric,
+    percentile_cont(0.95) WITHIN GROUP (ORDER BY duration_ms)::numeric,
+    percentile_cont(0.99) WITHIN GROUP (ORDER BY duration_ms)::numeric
+  FROM public.logs
+  WHERE created_at >= now() - make_interval(mins => p_window_minutes)
+    AND duration_ms IS NOT NULL
+$$;
+
+CREATE OR REPLACE FUNCTION public.get_pipeline_stats(p_window_minutes integer)
+RETURNS TABLE (total_success bigint, total_failure bigint)
+LANGUAGE sql
+STABLE
+SECURITY DEFINER
+SET search_path = public
+AS $$
+  SELECT
+    count(*) FILTER (WHERE status = 'completed'),
+    count(*) FILTER (WHERE status = 'failed')
+  FROM public.pipeline_executions
+  WHERE created_at >= now() - make_interval(mins => p_window_minutes)
+$$;
+
+-- ── log retention ─────────────────────────────────────────────────────
+
+CREATE OR REPLACE FUNCTION public.cleanup_old_logs(p_retention_days integer DEFAULT 90)
+RETURNS TABLE (deleted_count bigint)
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+BEGIN
+  RETURN QUERY
+  WITH deleted AS (
+    DELETE FROM public.logs
+    WHERE created_at < now() - make_interval(days => p_retention_days)
+    RETURNING 1
+  )
+  SELECT count(*) FROM deleted;
+END;
+$$;

package/.framework/migrations/069_log_stats_window.sql

@@ -0,0 +1,54 @@
+CREATE OR REPLACE FUNCTION public.get_log_stats(
+  p_account_id uuid,
+  p_level text DEFAULT NULL::text,
+  p_source text DEFAULT NULL::text,
+  p_source_type text DEFAULT NULL::text,
+  p_source_id text DEFAULT NULL::text,
+  p_person_id text DEFAULT NULL::text,
+  p_query text DEFAULT NULL::text,
+  p_date_from timestamp with time zone DEFAULT NULL::timestamp with time zone,
+  p_date_to timestamp with time zone DEFAULT NULL::timestamp with time zone
+)
+RETURNS TABLE(total bigint, error_count bigint, user_action_count bigint, event_type_count bigint, levels text[], sources text[], source_types text[])
+LANGUAGE plpgsql
+AS $function$
+DECLARE
+  v_from timestamptz := COALESCE(p_date_from, now() - interval '7 days');
+  v_total bigint;
+  v_error_count bigint;
+  v_user_action_count bigint;
+  v_event_type_count bigint;
+  v_levels text[];
+  v_sources text[];
+  v_source_types text[];
+BEGIN
+  SELECT
+    count(*),
+    count(*) FILTER (WHERE level ILIKE '%error%'),
+    count(*) FILTER (WHERE person_id IS NOT NULL),
+    count(DISTINCT level)
+  INTO v_total, v_error_count, v_user_action_count, v_event_type_count
+  FROM public.logs
+  WHERE account_id = p_account_id
+    AND created_at >= v_from
+    AND (p_level IS NULL OR level = p_level)
+    AND (p_source IS NULL OR source = p_source)
+    AND (p_source_type IS NULL OR source_type = p_source_type)
+    AND (p_source_id IS NULL OR source_id = p_source_id::uuid)
+    AND (p_person_id IS NULL OR person_id = p_person_id::uuid)
+    AND (p_query IS NULL OR message ILIKE '%' || p_query || '%')
+    AND (p_date_to IS NULL OR created_at <= p_date_to);
+
+  SELECT
+    coalesce(array_agg(DISTINCT level ORDER BY level) FILTER (WHERE level IS NOT NULL), ARRAY[]::text[]),
+    coalesce(array_agg(DISTINCT source ORDER BY source) FILTER (WHERE source IS NOT NULL), ARRAY[]::text[]),
+    coalesce(array_agg(DISTINCT source_type ORDER BY source_type) FILTER (WHERE source_type IS NOT NULL), ARRAY[]::text[])
+  INTO v_levels, v_sources, v_source_types
+  FROM public.logs
+  WHERE account_id = p_account_id
+    AND created_at >= v_from
+    AND (p_date_to IS NULL OR created_at <= p_date_to);
+
+  RETURN QUERY SELECT v_total, v_error_count, v_user_action_count, v_event_type_count, v_levels, v_sources, v_source_types;
+END;
+$function$;

package/.framework/migrations/070_app_type_schema_rpcs.sql

@@ -0,0 +1,166 @@
+-- Migration 070: bootstrap the RPCs the types/apps handlers expect
+--
+-- types.ts getSchema (?action=schema) and apps.ts getSchema /
+-- checkAvailability / updateVersion (?action=schema|available|version)
+-- call four Postgres functions that existed in the pre-consolidation v2
+-- schema (v2-core/migrations/010_apps.sql, 004_types.sql +
+-- 049_schema_driven_permissions.sql) but were never ported into
+-- .framework/migrations — each action fails at runtime on a stock
+-- install with "Could not find the function public.<name>(...) in the
+-- schema cache". This migration recreates them against the public
+-- schema.
+--
+-- Semantics are ported from the recovered v2 definitions:
+--   * get_type_schema returns the matching active type's design_schema
+--     ('{}' when none). An app_id argument prefers that app's row and
+--     falls back to the global (app_id IS NULL) type — the documented
+--     "app-specific fallback to system" behavior.
+--   * get_app_schema returns a jsonb projection of the active app row
+--     ('{}' when none), extended with the required_roles / route_prefix /
+--     renderer columns added since v2.
+--   * is_app_available returns true when an active app with the slug is
+--     available to the account under the same ownership rule
+--     get_account_apps uses (is_system OR owner_account_id IS NULL OR
+--     owner_account_id = account_id).
+--   * update_app_version bumps apps.version + updated_at and returns
+--     void — the handler only checks for an error.
+--
+-- All four run as SECURITY INVOKER (the v2 default): callers go through
+-- ctx.db, so human callers keep RLS scoping (types are world-readable via
+-- types_read; apps via apps_access) and machine principals bypass RLS as
+-- service_role. GRANTs match the sibling RPC convention in
+-- 004_core_rpc_and_broker.sql.
+
+-- CIL[BEGIN stable_id="~/.framework/migrations/070_app_type_schema_rpcs.sql:module:migration" type="migration" identity="app-type-schema-rpcs" parent="~/.framework/migrations/070_app_type_schema_rpcs.sql"]
+-- CIL[DOC-MACRO purpose="Create the four Postgres RPCs the types and apps Netlify handlers invoke: get_type_schema, get_app_schema, is_app_available, update_app_version"]
+-- CIL[DOC-RESPONSIBILITY responsibility="Provide schema lookup, app-schema projection, account-scoped app availability, and app version bump functions missing since the v2-to-public consolidation"]
+-- CIL[DOC-CONTEXT module="functions" layer="schema" related_files=".framework/functions/types.ts,.framework/functions/apps.ts,.framework/migrations/013_get_account_apps_role_filter.sql"]
+-- CIL[DOC-CONTRACT inputs="text/uuid params matching the .rpc named args in types.ts and apps.ts" outputs="jsonb scalars, boolean, void matching the shapes the handlers read" errors="none — SECURITY INVOKER relies on caller RLS" side_effects="update_app_version mutates public.apps version and updated_at"]
+-- CIL[DOC-MICRO logic_summary="Ports the recovered v2-core function bodies to the public schema; get_type_schema reads design_schema with app-specific fallback to the global type; is_app_available reuses the get_account_apps ownership rule including NULL-owner apps" notable_decisions="SECURITY INVOKER rather than DEFINER so human callers keep RLS scoping and no caller-supplied privilege claims are trusted"]
+-- CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+-- CIL[DOC-STABILITY stability="stable"]
+-- CIL[DOC-AUDIENCE audience="framework_developers"]
+-- CIL[END stable_id="~/.framework/migrations/070_app_type_schema_rpcs.sql:module:migration"]
+
+-- ── types ─────────────────────────────────────────────────────────────
+
+CREATE OR REPLACE FUNCTION public.get_type_schema(
+  kind   text,
+  slug   text,
+  app_id uuid DEFAULT NULL
+)
+RETURNS jsonb
+LANGUAGE plpgsql
+STABLE
+AS $$
+DECLARE
+  type_schema jsonb;
+BEGIN
+  SELECT t.design_schema INTO type_schema
+  FROM public.types t
+  WHERE t.kind = get_type_schema.kind
+    AND t.slug = get_type_schema.slug
+    AND t.is_active = true
+    AND (t.app_id = get_type_schema.app_id OR t.app_id IS NULL)
+  ORDER BY t.app_id NULLS LAST -- prefer app-specific types over global
+  LIMIT 1;
+
+  RETURN COALESCE(type_schema, '{}'::jsonb);
+END;
+$$;
+
+GRANT EXECUTE ON FUNCTION public.get_type_schema(text, text, uuid) TO authenticated;
+GRANT EXECUTE ON FUNCTION public.get_type_schema(text, text, uuid) TO service_role;
+
+COMMENT ON FUNCTION public.get_type_schema(text, text, uuid) IS 'Get type design_schema by kind+slug, app-specific with fallback to global';
+
+-- ── apps ──────────────────────────────────────────────────────────────
+
+CREATE OR REPLACE FUNCTION public.get_app_schema(app_slug text)
+RETURNS jsonb
+LANGUAGE plpgsql
+STABLE
+AS $$
+DECLARE
+  app_schema jsonb;
+BEGIN
+  SELECT jsonb_build_object(
+    'id', a.id,
+    'slug', a.slug,
+    'name', a.name,
+    'description', a.description,
+    'icon', a.icon,
+    'color', a.color,
+    'version', a.version,
+    'app_type', a.app_type,
+    'source', a.source,
+    'config', a.config,
+    'nav_items', a.nav_items,
+    'min_role', a.min_role,
+    'required_roles', a.required_roles,
+    'integration_deps', a.integration_deps,
+    'metadata', a.metadata,
+    'route_prefix', a.route_prefix,
+    'renderer', a.renderer
+  ) INTO app_schema
+  FROM public.apps a
+  WHERE a.slug = get_app_schema.app_slug
+    AND a.is_active = true;
+
+  RETURN COALESCE(app_schema, '{}'::jsonb);
+END;
+$$;
+
+GRANT EXECUTE ON FUNCTION public.get_app_schema(text) TO authenticated;
+GRANT EXECUTE ON FUNCTION public.get_app_schema(text) TO service_role;
+
+COMMENT ON FUNCTION public.get_app_schema(text) IS 'Get full app schema by slug';
+
+CREATE OR REPLACE FUNCTION public.is_app_available(
+  app_slug   text,
+  account_id uuid
+)
+RETURNS boolean
+LANGUAGE plpgsql
+STABLE
+AS $$
+BEGIN
+  RETURN EXISTS (
+    SELECT 1
+    FROM public.apps a
+    WHERE a.slug = is_app_available.app_slug
+      AND a.is_active = true
+      AND (
+        a.is_system = true
+        OR a.owner_account_id IS NULL
+        OR a.owner_account_id = is_app_available.account_id
+      )
+  );
+END;
+$$;
+
+GRANT EXECUTE ON FUNCTION public.is_app_available(text, uuid) TO authenticated;
+GRANT EXECUTE ON FUNCTION public.is_app_available(text, uuid) TO service_role;
+
+COMMENT ON FUNCTION public.is_app_available(text, uuid) IS 'Check if app is available to account';
+
+CREATE OR REPLACE FUNCTION public.update_app_version(
+  app_id      uuid,
+  new_version text
+)
+RETURNS void
+LANGUAGE plpgsql
+AS $$
+BEGIN
+  UPDATE public.apps
+  SET
+    version = update_app_version.new_version,
+    updated_at = now()
+  WHERE id = update_app_version.app_id;
+END;
+$$;
+
+GRANT EXECUTE ON FUNCTION public.update_app_version(uuid, text) TO authenticated;
+GRANT EXECUTE ON FUNCTION public.update_app_version(uuid, text) TO service_role;
+
+COMMENT ON FUNCTION public.update_app_version(uuid, text) IS 'Update app version';

package/.framework/migrations/071_timer_interval_keys.sql

@@ -0,0 +1,96 @@
+-- Migration 071: F-056 — make timers created via the API/admin UI fire.
+--
+-- Two halves of the fix:
+--   1. timers.ts now writes next_execution server-side on
+--      create/update/activate (068's get_due_timers gates on
+--      next_execution IS NOT NULL and nothing else ever set it).
+--   2. This file: update_timer_after_run previously rescheduled only
+--      from config->>'interval_minutes', but TimerDetailPage seeded
+--      config.interval_seconds — UI-created timers would fire once (if
+--      armed) and never reschedule. The RPC now accepts both keys with
+--      the same precedence the TS handler uses: interval_minutes
+--      (minutes) first, then interval_seconds (seconds / 60).
+--      Existing rows keep working under either key.
+--
+-- A backfill at the bottom arms existing active timers that have a
+-- computable interval but next_execution IS NULL — rows created before
+-- the API could write the column could never fire.
+
+-- CIL[BEGIN stable_id="~/.framework/migrations/071_timer_interval_keys.sql:module:migration" type="migration" identity="timer-interval-keys" parent="~/.framework/migrations/071_timer_interval_keys.sql"]
+-- CIL[DOC-MACRO purpose="Teach update_timer_after_run the interval_seconds config key and backfill next_execution for dormant armed-by-interval timers"]
+-- CIL[DOC-RESPONSIBILITY responsibility="Replace update_timer_after_run with a dual-key interval resolver; arm existing active timers whose next_execution is NULL"]
+-- CIL[DOC-CONTEXT module="system-cron" layer="schema" related_files=".framework/functions/system-cron.ts, .framework/functions/timers.ts, .framework/migrations/068_cron_schedule_timer_rpcs.sql"]
+-- CIL[DOC-CONTRACT inputs="p_timer_id uuid, p_success boolean, p_error_message text" outputs="void" errors="none — SECURITY DEFINER" side_effects="mutates timers bookkeeping columns; backfill sets next_execution on dormant interval timers"]
+-- CIL[DOC-MICRO logic_summary="Interval precedence: config->>'interval_minutes' (minutes) then config->>'interval_seconds' (seconds/60); non-positive or absent => next_execution NULL one-shot stop. Backfill UPDATE arms is_active + next_execution IS NULL + positive-interval rows to now()+interval" notable_decisions="Both keys kept forever so rows seeded with the old UI default (interval_seconds) and the canonical key (interval_minutes) both reschedule; 'once'/cron timers still dead-end to NULL since no cron evaluator exists in the DB"]
+-- CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+-- CIL[DOC-STABILITY stability="stable"]
+-- CIL[DOC-AUDIENCE audience="system-admin"]
+-- CIL[END stable_id="~/.framework/migrations/071_timer_interval_keys.sql:module:migration"]
+
+CREATE OR REPLACE FUNCTION public.update_timer_after_run(
+  p_timer_id uuid,
+  p_success boolean,
+  p_error_message text
+)
+RETURNS void
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+DECLARE
+  v_config jsonb;
+  v_interval numeric; -- resolved interval in MINUTES
+BEGIN
+  SELECT config INTO v_config FROM public.timers WHERE id = p_timer_id;
+
+  -- interval_minutes (canonical) wins; interval_seconds is the legacy UI
+  -- default and is converted seconds -> minutes.
+  v_interval := CASE
+    WHEN v_config->>'interval_minutes' ~ '^\d+(\.\d+)?$'
+      THEN (v_config->>'interval_minutes')::numeric
+    WHEN v_config->>'interval_seconds' ~ '^\d+(\.\d+)?$'
+      THEN (v_config->>'interval_seconds')::numeric / 60
+    ELSE NULL
+  END;
+
+  UPDATE public.timers
+  SET
+    last_execution = now(),
+    execution_count = COALESCE(execution_count, 0) + 1,
+    success_count = COALESCE(success_count, 0) + CASE WHEN p_success THEN 1 ELSE 0 END,
+    failure_count = COALESCE(failure_count, 0) + CASE WHEN p_success THEN 0 ELSE 1 END,
+    next_execution = CASE
+      WHEN v_interval IS NOT NULL AND v_interval > 0
+        THEN now() + (v_interval * interval '1 minute')
+      ELSE NULL
+    END,
+    updated_at = now()
+  WHERE id = p_timer_id;
+END;
+$$;
+
+-- Arm timers that are active and have a resolvable interval but were
+-- created while next_execution was unwritable (pre-F-056 API). One-shot
+-- and unparseable configs stay NULL — a NULL next_execution is a safe
+-- never-fire state, matching update_timer_after_run's stop semantics.
+UPDATE public.timers t
+SET
+  next_execution = now() + (v.mins * interval '1 minute'),
+  updated_at = now()
+FROM (
+  SELECT
+    id,
+    CASE
+      WHEN config->>'interval_minutes' ~ '^\d+(\.\d+)?$'
+        THEN (config->>'interval_minutes')::numeric
+      WHEN config->>'interval_seconds' ~ '^\d+(\.\d+)?$'
+        THEN (config->>'interval_seconds')::numeric / 60
+      ELSE NULL
+    END AS mins
+  FROM public.timers
+) v
+WHERE t.id = v.id
+  AND t.is_active
+  AND t.next_execution IS NULL
+  AND v.mins IS NOT NULL
+  AND v.mins > 0;