scheduledcompartment

Scheduled Compartment

cloud-path-app-scheduled-compartment is a device-agnostic reference Application plugin for CloudPath. It manages a set of compartments against a daily schedule: when a schedule window starts it emits a reminder, observes contact opened/closed events for each compartment, records a completed or missed outcome per window, and keeps everything idempotent.

The application does not depend on any Driver ID, port or vendor field. It is expressed purely in terms of standard Capability requirements and stable entity_id bindings, so the same application can be deployed against any set of entities that expose those capabilities.

Only the following domain terms are used: schedule, window, compartment, opened, completed, missed and reminder. No industry-specific semantics are hard-coded.

Dependencies

• Go 1.26.3 or newer (the checkout's go.mod declares go 1.26.3).

• Only the public CloudPath SDK and protocol schema. The code imports these packages from github.com/DeliciousBuding/cloud-path and nothing else from the Core repository:

  Import path	Purpose
  sdk/go/cloudpath/v1/application	Application Protocol v1 types and RPC
  sdk/go/cloudpath/v1/status	Status codes
  sdk/go/pluginmain	Host-injected launch identity and handshake
  sdk/go/rpc	RPC server
  sdk/go/transport	Host-provided transport

  There are no imports from internal/ of the Core repository. Re-check the boundary from this directory with:

  grep -R "cloud-path/internal" --include="*.go" .
  # expected: no output
  

• The manifest requests no hardware, network, filesystem or secret permissions.

Required Capabilities

The same declarations live in requirements.yaml (human review) and plugin.yaml (machine manifest). Describe returns the equivalent ApplicationDescriptor, so the runtime and the manifest cannot drift; the manifest_test.go suite enforces that all three copies stay identical.

Instance Configuration

The instance config is a bounded JSON object. It is validated on ConfigureInstance; a missing field, a duplicate compartment, an unknown window compartment or an invalid time is rejected with a non-OK status.

{
  "timezone": "Asia/Shanghai",
  "compartments": [
    {"id": "c1", "name": "Compartment 1"},
    {"id": "c2", "name": "Compartment 2"},
    {"id": "c3", "name": "Compartment 3"}
  ],
  "schedule": [
    {"id": "w-morning", "compartment": "c1", "start": "08:00", "end": "08:30"}
  ]
}

Field rules:

• timezone: required, a valid IANA name (for example Asia/Shanghai).
• compartments: required, at least one, each with a unique non-empty id.
• schedule: required, at least one window. Each window has a unique non-empty id, a compartment that references a configured compartment, and start / end in 24-hour HH:MM. end must be strictly after start.

ScheduleTick events carry the concrete runtime window (with RFC3339 start / end timestamps). The app validates that the referenced compartment exists in the instance config before starting the window.

Binding

An application instance is bound to Capabilities rather than to a device or Driver. ValidateBinding enforces the declared cardinalities and rejects any requirement id that this application does not declare (which structurally rules out Driver coupling).

Bindings persist stable entity_id values. Reconnects, Edge restarts and Driver restarts must not change a binding. A valid binding is stored so that the reminder is routed to the bound alarm entity and contact events are mapped back to their compartment.

Behavior

The runtime is a process-based ApplicationService (Application Protocol v1):

1. Window start — on a ScheduleTick, the app opens a window, emits a UpsertDomainRecord (window, state=opened), a RequestCommand to the bound alarm entity, and a ScheduleTask so Core can later trigger the window-check job.
2. Completion — on a contact opened/closed event for the compartment while its window is open, the app marks the window completed and cancels the window-check task.
3. Missed — the window-check job scans open windows against the clock and records a window record with state=missed, cancels the task and emits a notification.
4. Idempotency — duplicate events (same sequence or same window id) and repeated jobs (same IdempotencyKey) do not emit duplicate effects.

Effects are limited to the Core-approved closed set: UpsertDomainRecord, DeleteDomainRecord, RequestCommand, ScheduleTask, CancelScheduledTask and SendNotification. The app never produces arbitrary SQL, shell commands, file/network effects or global credential requests.

The HandleRequest subroute is read-only and returns a bounded JSON summary of the instance config and window state.

Build

From a standalone checkout of this repository:

# Application library, tests and entrypoint command
go build ./...
go vet ./...

# Build just the entrypoint binary
go build -o cloud-path-app-scheduled-compartment ./cmd/cloud-path-app-scheduled-compartment

The entrypoint binary is cloud-path-app-scheduled-compartment, matching the entrypoint field in plugin.yaml.

Inside the CloudPath monorepo the same code lives under examples/scheduled-compartment; prefix the package patterns with that directory, for example go build ./examples/scheduled-compartment/....

Test

go test ./... -count=1
go test ./... -count=20   # idempotency / flake soak

The suite covers the descriptor requirements, config/binding validation, the window reminder effect, contact-driven completion, missed-window recording, duplicate-event idempotency, rejection of driver coupling, invalid config, graceful shutdown, and manifest identity / requirements drift.

Inside the monorepo, the repository-level gates additionally cover the whole tree:

go vet ./...
python scripts/fmtcheck.py
# Full binary → Host E2E (monorepo-only harness)
go test ./testing/plugin-harness -run TestScheduledCompartmentBinaryHostE2E -count=1

Run as an Application Plugin

cmd/cloud-path-app-scheduled-compartment is an install-style, process-based Application plugin. It is launched by the CloudPath Plugin Host, never with manual flags: the Host injects the launch identity and a loopback endpoint through CLOUDPATH_* environment variables (the contract is defined by the public pluginmain package), the process prints the single CP1 handshake line, dials back and serves Application Protocol v1 over that authenticated transport. Started outside a Host it exits immediately with a missing environment error.

To attach it to a Host:

1. Build the entrypoint binary (see Build).

2. Publish plugin.yaml and the entrypoint binary as a release asset together with its published sha256 digest.

3. Install and enable the instance:

   cloudpath plugin install <repository-url-or-id> --digest sha256:<hex> --yes
   cloudpath plugin enable io.github.deliciousbuding.cloud-path-app-scheduled-compartment
   

4. Start the Host, which supervises the plugin process and serves the protocol:

   cloudpath plugin host
   

The runtime then delivers the instance configuration through ConfigureInstance and entity bindings through ValidateBinding (see Instance Configuration and Binding).

Disable and remove

cloudpath plugin disable io.github.deliciousbuding.cloud-path-app-scheduled-compartment
cloudpath plugin remove  io.github.deliciousbuding.cloud-path-app-scheduled-compartment

remove keeps the instance data; add --purge to delete it as well.

Repository Layout

Status

Implemented as a runnable reference application. It is a process-based plugin that depends only on the public CloudPath SDK and schema.