novaflow-types 0.1.0.dev1__py3-none-any.whl

novaflow/types/__init__.py

@@ -0,0 +1,9 @@
+from .core.action import NodeSchema, OperationType
+from .core.service import ActionServiceMetadata, StateProviderSchema
+
+__all__ = [
+    "NodeSchema",
+    "ActionServiceMetadata",
+    "StateProviderSchema",
+    "OperationType",
+]

novaflow/types/comm/camera_registry.py

@@ -0,0 +1,72 @@
+"""``registry_cameras`` KV wire contract — the single typed source of truth for
+camera-feed advertisements that connectors publish and canopy reads.
+
+A connector (the mobile-integration-SDK ``RegistryPublisher``, the MockMobileBot
+fixture, or — in future — a Nova-native camera service such as the Techman
+eye-in-hand camera) publishes one entry per camera feed into the
+``registry_cameras`` JetStream KV bucket, keyed ``{robot_id}.{feed}``. Canopy
+watches the bucket and renders each feed's ``browser_stream_url`` as an MJPEG
+``<img>`` in the robot panel.
+
+Before this model the shape lived only in canopy's hand-written parser
+(``parseCameraEntry``) — an untyped boundary a producer in a *separate* repo
+could silently drift from. This model generates BOTH the canopy TypeScript type
+(``pydantic2ts`` → ``cameraRegistryTypes.ts``) and the JSON Schema canopy
+validates against on read (ajv → ``camera_registry.schema.json``), mirroring the
+#251 wire-contract symmetry already used for the per-run comm-KV signals.
+
+``robot_id`` and ``feed`` are required — they carry the feed's identity and are
+also encoded in the KV key. Everything else is optional so producers advertise
+only what they have; canopy renders a placeholder for any feed lacking a
+``browser_stream_url``.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class CameraRegistryEntry(BaseModel):
+    """One camera feed advertised in the ``registry_cameras`` KV bucket."""
+
+    # extra="ignore" (the default) keeps the JSON Schema free of
+    # ``additionalProperties: false`` so producers may carry extra keys
+    # (e.g. ``last_seen``) without failing canopy's read-side validation.
+    model_config = ConfigDict(extra="ignore")
+
+    robot_id: str = Field(
+        description="Controller/robot id this feed belongs to; the first "
+        "segment of the KV key ``{robot_id}.{feed}``.",
+    )
+    feed: str = Field(
+        description="Feed name unique within the robot (e.g. ``front_camera`` or "
+        "``eih``); the remainder of the KV key.",
+    )
+    robot_type: str = Field(
+        default="",
+        description="Robot model/type label, for display grouping.",
+    )
+    stream_url: str = Field(
+        default="",
+        description="In-cluster MJPEG endpoint. NOT browser-reachable; kept for "
+        "server-side / e2e consumers.",
+    )
+    browser_stream_url: str | None = Field(
+        default=None,
+        description="Browser-reachable MJPEG URL (through the cell ingress). "
+        "Canopy renders ONLY this; a feed without it shows a placeholder.",
+    )
+    snapshot_url: str | None = Field(
+        default=None,
+        description="Browser-reachable single-frame snapshot URL, if available.",
+    )
+    source: str = Field(
+        default="",
+        description="Publishing connector's source id (the ingress path segment).",
+    )
+    width: int | None = Field(default=None, description="Frame width in pixels.")
+    height: int | None = Field(default=None, description="Frame height in pixels.")
+    rotation: float = Field(
+        default=0,
+        description="Clockwise display rotation in degrees.",
+    )

novaflow/types/comm/cloudevent.py

@@ -0,0 +1,167 @@
+import uuid
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Generic, Optional, TypeVar
+
+from pydantic import BaseModel, Field
+
+T = TypeVar("T")
+
+_example_event_id = uuid.uuid4()
+_example_datetime = datetime.now(timezone.utc)
+
+
+class SpecVersion(str, Enum):
+    """
+    The version of the CloudEvents specification which an event uses.
+    This enables the interpretation of the context.
+
+    Currently, this attribute will only have the 'major' and 'minor' version numbers
+    included in it. This allows for 'patch' changes to the specification to be made
+    without changing this property's value in the serialization.
+    """
+
+    v0_3 = "0.3"
+    v1_0 = "1.0"
+
+
+def date_factory() -> datetime:
+    """
+    Factory function to create a datetime object with the current UTC time.
+    This is used as a default value for the `time` field in CloudEvent.
+    """
+    return datetime.now(timezone.utc)
+
+
+def uuid_factory() -> str:
+    """
+    Factory function to create a UUID string.
+    This is used as a default value for the `id` field in CloudEvent.
+    """
+    return str(uuid.uuid4())
+
+
+class CloudEvent(BaseModel, Generic[T]):
+    data: Optional[T] = Field(
+        title="Event Data",
+        description=(
+            "CloudEvents MAY include domain-specific information about the occurrence."
+            " When present, this information will be encapsulated within data.It is"
+            " encoded into a media format which is specified by the datacontenttype"
+            " attribute (e.g. application/json), and adheres to the dataschema format"
+            " when those respective attributes are present."
+        ),
+        examples=[{"message": "This is an example of event data"}],
+    )
+    source: str = Field(
+        title="Event Source",
+        description=(
+            "Identifies the context in which an event happened. Often this will include"
+            " information such as the type of the event source, the organization"
+            " publishing the event or the process that produced the event. The exact"
+            " syntax and semantics behind the data encoded in the URI is defined by the"
+            " event producer.\n"
+            "\n"
+            "Producers MUST ensure that source + id is unique for"
+            " each distinct event.\n"
+            "\n"
+            "An application MAY assign a unique source to each"
+            " distinct producer, which makes it easy to produce unique IDs since no"
+            " other producer will have the same source. The application MAY use UUIDs,"
+            " URNs, DNS authorities or an application-specific scheme to create unique"
+            " source identifiers.\n"
+            "\n"
+            "A source MAY include more than one producer. In"
+            " that case the producers MUST collaborate to ensure that source + id is"
+            " unique for each distinct event."
+        ),
+        examples=["https://example.com/myapp/instance1"],
+    )
+    id: str = Field(
+        title="Event ID",
+        description=(
+            "Identifies the event. Producers MUST ensure that source + id is unique for"
+            " each distinct event. If a duplicate event is re-sent (e.g. due to a"
+            " network error) it MAY have the same id. Consumers MAY assume that Events"
+            " with identical source and id are duplicates. MUST be unique within the"
+            " scope of the producer"
+        ),
+        examples=[_example_event_id],
+        default_factory=uuid_factory,
+    )
+    type: str = Field(
+        title="Event Type",
+        description=(
+            "This attribute contains a value describing the type of event related to"
+            " the originating occurrence. Often this attribute is used for routing,"
+            " observability, policy enforcement, etc. The format of this is producer"
+            " defined and might include information such as the version of the type"
+        ),
+        examples=["com.github.pull_request.opened"],
+    )
+    specversion: SpecVersion = Field(
+        title="Specification Version",
+        description=(
+            "The version of the CloudEvents specification which the event uses. This"
+            " enables the interpretation of the context.\n"
+            "\n"
+            "Currently, this attribute will only have the 'major'"
+            " and 'minor' version numbers included in it. This allows for 'patch'"
+            " changes to the specification to be made without changing this property's"
+            " value in the serialization."
+        ),
+        examples=[SpecVersion.v1_0],
+        default=SpecVersion.v1_0,
+    )
+    time: Optional[datetime] = Field(
+        title="Occurrence Time",
+        description=(
+            " Timestamp of when the occurrence happened. If the time of the occurrence"
+            " cannot be determined then this attribute MAY be set to some other time"
+            " (such as the current time) by the CloudEvents producer, however all"
+            " producers for the same source MUST be consistent in this respect. In"
+            " other words, either they all use the actual time of the occurrence or"
+            " they all use the same algorithm to determine the value used."
+        ),
+        examples=[_example_datetime],
+        default_factory=date_factory,
+    )
+    subject: Optional[str] = Field(
+        title="Event Subject",
+        description=(
+            "This describes the subject of the event in the context of the event"
+            " producer (identified by source). In publish-subscribe scenarios, a"
+            " subscriber will typically subscribe to events emitted by a source, but"
+            " the source identifier alone might not be sufficient as a qualifier for"
+            " any specific event if the source context has internal"
+            " sub-structure.\n"
+            "\n"
+            "Identifying the subject of the event in context"
+            " metadata (opposed to only in the data payload) is particularly helpful in"
+            " generic subscription filtering scenarios where middleware is unable to"
+            " interpret the data content. In the above example, the subscriber might"
+            " only be interested in blobs with names ending with '.jpg' or '.jpeg' and"
+            " the subject attribute allows for constructing a simple and efficient"
+            " string-suffix filter for that subset of events."
+        ),
+        examples=["123"],
+        default=None,
+    )
+    datacontenttype: Optional[str] = Field(
+        title="Event Data Content Type",
+        description=(
+            "Content type of data value. This attribute enables data to carry any type"
+            " of content, whereby format and encoding might differ from that of the"
+            " chosen event format."
+        ),
+        examples=["application/json", "text/xml"],
+        default=None,
+    )
+    dataschema: Optional[str] = Field(
+        title="Event Data Schema",
+        description=(
+            "Identifies the schema that data adheres to. "
+            "Incompatible changes to the schema SHOULD be reflected by a different URI"
+        ),
+        default=None,
+    )

novaflow/types/comm/execution_state.py

@@ -0,0 +1,22 @@
+"""Minimal, cross-package constant for control-plane's active-execution KV
+entries.
+
+Used by ADR-032's demand-map reconciliation (the IO action service checking
+whether a run it still has demand recorded for is actually still executing).
+The run_id itself is parsed directly from the KV key
+(``runs.active.{run_id}``), not the stored value — control-plane's
+``ExecutionState`` value shape is control-plane-internal
+(``control-plane/app/core/execution_state.py``, e.g. ``cp_instance_id``) and
+deliberately not mirrored here, to avoid drift if its fields change
+independently.
+
+ADR-006 (2026-07 revision) replaced control-plane's single well-known
+``runs.current`` key with one key per active run (``runs.active.{run_id}``)
+so N runs can be tracked concurrently — a reconciliation consumer watches
+every key under this prefix instead of reading one.
+"""
+
+# Must match control-plane/app/core/execution_state.py::RUNS_ACTIVE_PREFIX.
+# Not re-exported from there (control-plane and this package are consumed
+# independently), so keep the two literals in sync by hand if either changes.
+RUNS_ACTIVE_PREFIX = "runs.active."

novaflow/types/comm/heartbeat.py

@@ -0,0 +1,11 @@
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class Heartbeat(BaseModel):
+    """Represents a heartbeat message from a service."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    last_seen: int = Field(
+        ..., description="The last seen timestamp in Unix epoch format"
+    )

novaflow/types/comm/kv_keys.py

@@ -0,0 +1,185 @@
+"""Single source of truth for every per-run KV key + bucket name
+in the MotionRoutine V2 programming-session pipeline.
+
+The same class of drift this module guards against — wire-string
+divergence between writer and reader as the codebase evolves — is
+exactly what ``subjects.py`` already handles for NATS subjects.
+This file is the KV-side twin.
+
+Before this module existed, ``novaflow_programming_sessions`` was
+spelled as a literal in 8+ places (run.py, motion_routine.py,
+useNats.ts, programmingNats.ts, settings.py, multiple e2e tests).
+A typo in one site or a future rename to a per-cell bucket name
+would silently desync; the symptom would be "canopy shows stale
+state and the action runs anyway", which is exactly the failure
+mode KV-as-source-of-truth is supposed to prevent.
+
+Python helpers below produce the canonical strings; the TypeScript
+twin at ``canopy/src/types/generated/programmingKvKeys.ts`` is
+GENERATED from this module by ``generate_comm_registries.py`` (#251),
+so it can no longer drift by hand.  Sibling test files still assert
+the exact strings on both sides as a contract pin.
+"""
+
+from __future__ import annotations
+
+
+PROGRAMMING_SESSIONS_BUCKET = "novaflow_programming_sessions"
+"""Name of the JetStream KV bucket that holds the **small, durable / low-churn**
+per-run programming-session keys — ``terminal`` and ``speed`` (until the latter
+moves to the operator-control channel, issue #248).  See ADR 022 + spec §14.1
+for the ownership map.
+
+The **high-churn** keys (``cursor``/``scrub_state``/``progress``) were split
+out into :data:`PROGRAMMING_LIVE_BUCKET`.  The **large** ``cached_plan`` keys
+(per-segment full trajectories, ~hundreds of KB each, + the cross-run
+``routine.{hash}.*`` reuse cache) were split out into
+:data:`PROGRAMMING_PLANS_BUCKET` — they accumulated to this bucket's
+``max_bytes`` cap and, because nats-py KV streams use ``discard=new``, the
+full bucket then *rejected* the tiny but critical ``terminal`` write
+(``10077 'maximum bytes exceeded'``), stranding the operator UI in "Running".
+Keeping this bucket terminal/speed-only means it stays small and never fills."""
+
+
+PROGRAMMING_PLANS_BUCKET = "novaflow_programming_plans"
+"""Name of the JetStream KV bucket that holds the **large, evictable** pre-plan
+cache written by the MotionRoutine executor during planning:
+
+  * ``{run_id}.cached_plan`` — per-run summary (metadata only)
+  * ``{run_id}.cached_plan.{seg_idx}`` — per-run full per-segment trajectory
+  * ``routine.{hash}.cached_plan[.{seg_idx}]`` — the cross-run reuse cache
+    keyed by routine hash (spec §7.5), so an unchanged routine skips PRE-PLAN.
+
+Split out of :data:`PROGRAMMING_SESSIONS_BUCKET` so this churning, large-payload
+cache can never starve the critical ``terminal`` write — the whole point of the
+split.  Uses the KV default ``discard=new`` (this module's rule: KV never uses
+``discard=old``, which evicts by *write* age — a hot cross-run reuse key is
+written once but read forever, so ``discard=old`` would drop it while hot).  At
+the cap, a *new* plan write is skipped (best-effort → that run re-plans) while
+the existing — including the hot reuse — cache survives to its TTL; the 24h TTL
+then frees space.  ``terminal`` lives in its own bucket and is never affected
+either way."""
+
+
+PROGRAMMING_LIVE_BUCKET = "novaflow_programming_live"
+"""Name of the JetStream KV bucket that holds the **high-churn, ephemeral,
+in-run-only** display state — ``cursor`` (re-written ~5 Hz after coalescing),
+``scrub_state``, and per-item ``progress.*``.
+
+Split out from :data:`PROGRAMMING_SESSIONS_BUCKET` to fix the issue #186 OOM:
+a constantly-overwritten key spawns a superseded revision per write, and those
+revisions can only be reclaimed once the stream's ``first_seq`` advances past
+them.  A lingering low-sequence durable key (``terminal``, kept 24h for the
+post-run banner; ``cached_plan``, kept for Run-again reuse) **pins**
+``first_seq``, so the cursor's superseded revisions accumulate as interior
+tombstones until the durable key expires — the proven OOM mechanism.  With the
+churn isolated in its own bucket (no durable key to pin it) the revisions
+self-reclaim per run; the bucket also runs the ephemeral storage profile
+(memory/R1/cap + short TTL backstop, ADR-017 split rule).
+
+Canopy watches **both** buckets (``{run}.>`` on each); writers target the
+bucket each key belongs to."""
+
+
+def cursor_key(run_id: str) -> str:
+    """``{run_id}.cursor`` — per-frame float cursor + item index."""
+    return f"{run_id}.cursor"
+
+
+def scrub_state_key(run_id: str) -> str:
+    """``{run_id}.scrub_state`` — canopy reads this on reconnect to
+    re-derive the scrubber's current phase (running / paused / etc.)."""
+    return f"{run_id}.scrub_state"
+
+
+def terminal_key(run_id: str) -> str:
+    """``{run_id}.terminal`` — "the run is done" signal canopy reads
+    to transition out of running state.  Carries
+    ``{"status": ..., "message": ..., "data": ...}`` JSON."""
+    return f"{run_id}.terminal"
+
+
+def speed_key(run_id: str) -> str:
+    """``{run_id}.speed`` — canopy's slider writes here; the action
+    watches and emits ``PlaybackSpeedRequest`` mid-flight."""
+    return f"{run_id}.speed"
+
+
+def progress_item_key(run_id: str, item_index: int) -> str:
+    """``{run_id}.progress.{item_index}`` — per-item lifecycle
+    ("running" / "done" / "failed").  Wait/IO items use this; motion
+    segments emit through the same path."""
+    return f"{run_id}.progress.{item_index}"
+
+
+def progress_key_prefix(run_id: str) -> str:
+    """``{run_id}.progress.`` — prefix used for KV-purge scans
+    (e.g. step-back rollbacks).  Matches all ``progress_item_key``
+    values for this run."""
+    return f"{run_id}.progress."
+
+
+def cached_plan_summary_key(run_id: str) -> str:
+    """``{run_id}.cached_plan`` — light-payload summary (no
+    ``joint_trajectory``) canopy can read in one shot for display.
+    Per-segment full payloads live at
+    ``cached_plan_segment_key(run_id, idx)``."""
+    return f"{run_id}.cached_plan"
+
+
+def cached_plan_segment_key(run_id: str, segment_idx: int) -> str:
+    """``{run_id}.cached_plan.{segment_idx}`` — full
+    ``JointTrajectory`` payload for one segment.  PR-23 Run-again
+    reuse + the action's PRE-PLAN write target the same key."""
+    return f"{run_id}.cached_plan.{segment_idx}"
+
+
+def cross_run_cached_plan_summary_key(routine_hash: str) -> str:
+    """``routine.{routine_hash}.cached_plan`` — cross-run reuse
+    summary, keyed on the hash of ``MotionRoutineInput`` (spec
+    §7.5).  Same shape as ``cached_plan_summary_key`` but lives
+    under a different prefix so per-run purges don't touch it."""
+    return f"routine.{routine_hash}.cached_plan"
+
+
+def cross_run_cached_plan_segment_key(
+    routine_hash: str, segment_idx: int,
+) -> str:
+    """``routine.{routine_hash}.cached_plan.{segment_idx}`` — per-
+    segment full payload for cross-run reuse.  PR-23."""
+    return f"routine.{routine_hash}.cached_plan.{segment_idx}"
+
+
+# ---------------------------------------------------------------------------
+# Per-run suffixes whose lifetime is bounded by the run, grouped by which
+# bucket they live in.  Used by ``control-plane/app/core/programming_kv.py``
+# to purge each bucket on TERMINUS, uniformly across tree-mode + programming-
+# mode runs.  Since the #186 split, the high-churn display keys live in
+# ``PROGRAMMING_LIVE_BUCKET`` and the rest in ``PROGRAMMING_SESSIONS_BUCKET``,
+# so the purge must target each suffix in its OWN bucket.
+# ---------------------------------------------------------------------------
+
+LIVE_BUCKET_PURGE_SUFFIXES: tuple[str, ...] = (
+    "cursor",
+    "scrub_state",
+    # NOTE: per-item ``progress.*`` keys also live in the LIVE bucket but are
+    # variable-cardinality — the purge discovers them by prefix scan
+    # (``progress_key_prefix``), not from this fixed-suffix tuple.
+)
+"""Fixed-suffix keys purged from :data:`PROGRAMMING_LIVE_BUCKET`."""
+
+SESSIONS_BUCKET_PURGE_SUFFIXES: tuple[str, ...] = (
+    "speed",
+)
+"""Fixed-suffix keys purged from :data:`PROGRAMMING_SESSIONS_BUCKET`.
+
+NOTE: ``terminal`` is NOT purged — canopy displays it post-run and the
+operator dismisses it.  ``cached_plan`` is exempt for Run-again reuse
+(spec §14.3 step 3; bucket-level ``max_age`` provides the TTL).  Both
+exemptions are load-bearing — don't add them here."""
+
+PER_RUN_PURGE_SUFFIXES: tuple[str, ...] = (
+    *LIVE_BUCKET_PURGE_SUFFIXES,
+    *SESSIONS_BUCKET_PURGE_SUFFIXES,
+)
+"""Back-compat union of every fixed purge suffix across both buckets."""