Lenses and watches

A captured lens is a view the owner opens, produced by one of the realm’s handlers. A watch re-reads a lens on a schedule and tells the owner about new items. Declare them together with watching, so a watch can only name a lens declared beside it. watching takes both blocks, capturedLenses and watches:

import { defineRealm, watching } from "@embabel/realm-types";

export default defineRealm({
  // ...
  ...watching({
    capturedLenses: {
      open: { name: "Open incidents", handler: "oncall.open", description: "Every unresolved incident." },
    },
    watches: {
      "new-incident": {
        lens: "open",
        schedule: "0 */5 * * * *",
        criteria: "MATCH (i:Incident) WHERE i.status <> 'resolved' RETURN i",
        judge: "Say yes only for an incident that affects a component the owner's services use",
      },
    },
  }),
});

Lenses. Use capturedLenses; the conventional lenses field is refused on a captured realm. The key is the lens id ([a-z][a-z0-9-]{0,63}), name is at most 128 characters and description at most 512. Synth refuses a lens whose handler the realm does not declare. result is "json" (the default, data only) or "content", where the handler returns focus, data, presentation and complete, and the owner’s cypher_query approval is needed too. See captured handler binding.

Watches. At most 16. The key is [a-z][a-z0-9-]{0,63}, and lens names a lens the realm declares. The schedule is six-field cron, at most 64 characters, written with digits, *, -, , and /, plus ? in the two day fields; month and weekday names, L, W, # and macros are refused. When both day fields are restricted, a day must match both. Synth walks the expression in UTC from 30 December 2023 to 2 January 2026 and refuses one that fires less than five minutes apart or never fires. criteria is one line of at most 2048 bytes, and judge, when present, is not empty and at most 1024 bytes. A watch has no field for where results go: the host alone decides how the owner hears about them.

For a watch, the lens handler returns a top-level items array. The first run takes a baseline and tells the owner nothing. A run may carry at most 32 items, 8 of them new, and deliver at most 4 to the owner; a run past any of these is refused whole, and the host does not trim it. A run’s outcome is BASELINED, DELIVERED, NOTHING_NEW, REFUSED or FAILED. What a watch has seen survives an approved upgrade; a changed capture takes a fresh baseline. The owner approves each watch on its own, and approving a watch approves nothing else.