carlos / platform Public

schedule: file-level doc comments for spec.go, declaration.go, status.go

cron.go carries the package's canonical doc comment plus a
file-specific paragraph in its own voice; the other three files that
each own one bucket/registry shape had no such orientation. Add one
matching paragraph to each, naming the spec section it implements.

Paul Campbell pushed by paul@keymail.dev 2 months ago 343e159ba16ab796e682901bb833f8145f224d99 parent 1269537

3 files changed, +16 −0

internal/schedule/declaration.go +5 −0
internal/schedule/spec.go +5 −0
internal/schedule/status.go +6 −0

diff --git a/internal/schedule/declaration.go b/internal/schedule/declaration.go

index e4432f2be..f427704ec 100644

--- a/internal/schedule/declaration.go

+++ b/internal/schedule/declaration.go

@@ -1,3 +1,8 @@

+// This file is apps/<acct>/<app>/schedules.json end to end (spec §4.1): the

+// member-facing validation shared with the console door, so a typo costs a

+// round trip nothing; the CAS-guarded read/modify/write cycle with one

+// retry on a conflicting writer; and schedule-run.json (spec §4.2), whose

+// etag movement alone — never its content — is the "fire it now" signal.

package schedule

import (

diff --git a/internal/schedule/spec.go b/internal/schedule/spec.go

index 2627453fa..36bb981ac 100644

--- a/internal/schedule/spec.go

+++ b/internal/schedule/spec.go

@@ -1,3 +1,8 @@

+// This file is the timers.spec column's grammar: parse the three stored

+// shapes ("every <duration>", "cron <5 fields>", "at <unix>"), compute each

+// one's next fire from now (spec §6.1's coalescing — always from now, never

+// from the scheduled time), and render the canonical text back for

+// Converge and Runner to store and for `carlos schedule ls` to show.

package schedule

import (

diff --git a/internal/schedule/status.go b/internal/schedule/status.go

index df933dc3c..2919eceb9 100644

--- a/internal/schedule/status.go

+++ b/internal/schedule/status.go

@@ -1,3 +1,9 @@

+// This file is apps/<acct>/<app>/schedule-status/<host>.json (spec §4.3):

+// the box's best-effort report of what each of its instances will do next

+// and what happened last time, written after every fire and every converge

+// that changed a host's rows. It is what makes `carlos schedule ls` honest

+// for a member with no box access — the declaration alone says what was

+// asked; these objects say what is actually going to happen.

package schedule

import (