Kron Documentation

Start here for installation and day-to-day usage, then use the specification set for formal contracts.

Getting Started

• SETUP
  • Prerequisites
  • Clone the Repository
  • Verify the Toolchain
  • Run Quality Gates
  • Build the MVP CLI
  • Current MVP Scope
• USAGE
  • 1. Create a Configuration File
  • 2. Validate Configuration
  • 3. Explain One Period Decision
  • 4. List Upcoming Decisions
  • 5. Troubleshooting
  • Related References
• RELEASE.md
  • Target
  • Freeze Checklist
  • Tagging
  • CI Release Outputs
  • Verification

Specifications

• HELLOKRON.md
  • What Kron is
  • Primary goals
  • Non-goals
  • Architecture
  • Resource model
  • Scheduling semantics
  • Execution semantics
  • Status and explainability
  • Observability
  • Security and operational model
  • Compatibility and integration
  • Failure behavior
  • Versioning and stability
  • User-facing contract
• SPEC.md
  • Scope
  • Terminology
  • Time Model
  • Inputs
  • Outputs
  • Periods
  • Window Semantics
  • Distribution Semantics
  • Seed Semantics
  • Constraint Semantics
  • Decision Computation
  • Handling and Outcomes
  • Execution Trigger Semantics
  • Deadline Semantics
  • Concurrency Semantics
  • Idempotency Semantics
  • State Machine
  • Spec Change Semantics
  • Clock Change Semantics
  • Observability Contract
  • Invariants
  • Compatibility
• CORE-SPEC.md
  • Scope
  • Design Constraints
  • Versioning
  • Core Concepts
  • Primary Interfaces
  • Determinism Requirements
  • PeriodID
  • Window Computation
  • Seed Derivation
  • Seed Hash
  • PRNG Requirements
  • Distribution Specification
  • Distribution Contract
  • Constraint Specification
  • Candidate Selection Algorithm
  • Constraint Evaluation Rules
  • Error Handling
  • Timezone Handling
  • Precision Rules
  • Unschedulable Semantics
  • Stability Guarantees
  • Performance Requirements
  • Prohibited Behaviors
  • Conformance
• SYNTAX.md
  • Scope
  • Grammar overview
  • Cron expression
  • Timezone modifier
  • Window modifier
  • Distribution modifier
  • Seed modifier
  • Policy modifier
  • Constraints modifiers
  • Validation rules
  • Examples (MVP executable with explain/next)
  • Lint-only Examples (planned runtime distributions)
• KRONTAB File Format Specification
  • Scope
  • File Location
  • Encoding
  • Comments
  • Empty Lines
  • Job Entry Structure
  • Schedule and Modifiers
  • Fields
  • Required Fields
  • Optional Fields
  • Multi-Line Entries
  • Quoting Rules
  • Duplicate Fields
  • Job Identity
  • Validation Rules
  • Security Rules
  • Examples
  • Compatibility Guarantees
  • Non-Goals
• EXECUTION.md
  • Scope
  • Process Model Overview
  • krond Lifecycle
  • Scheduler Loop
  • Job Identity
  • Fork and Exec Model
  • Execution Environment
  • Concurrency Handling
  • Timeout Handling
  • State Persistence
  • Missed Period Handling
  • Output Handling
  • Signal Handling
  • Locking Model
  • Isolation and Security
  • Resource Limits
  • Crash Recovery
  • Determinism Guarantee
  • Performance Model
  • Failure Guarantees
  • Summary
• STATE.md
  • Scope
  • Goals
  • Storage Location
  • State File Schema
  • Field Definitions
  • State Transitions
  • Write Semantics
  • Idempotency Rules
  • Crash Recovery
  • Period Advancement Rules
  • Deadline Interaction
  • Unschedulable Period
  • Concurrency Interaction
  • State Corruption Handling
  • Migration Rules
  • File Permissions
  • Locking
  • Invariants
  • Non-Goals
• ERROR-MODEL.md
  • Scope
  • Design Principles
  • Error Categories
  • ConfigurationError
  • ValidationError
  • SchedulingError
  • ConstraintError
  • Unschedulable Condition
  • ExecutionError
  • PersistenceError
  • SystemError
  • IncompatibleStateError
  • Deadline Interaction
  • Concurrency Conflicts
  • Clock Anomalies
  • Partial Failure Handling
  • Retry Rules
  • Error Logging Contract
  • Fatal Conditions
  • Non-Fatal Conditions
  • Invariants Under Error
  • Adapter-Specific Notes
  • Summary
• LOGS.md
  • Scope
  • Log Principles
  • Log Format
  • Levels
  • Components
  • Core Events
  • Seed Transparency
  • Distribution Transparency
  • Human Explanation Mode
  • Ordering Guarantees
  • Stability Guarantees
  • Log Compatibility Modes
• SECURITY.md
  • Scope
  • Threat Model
  • Trust Boundaries
  • Principle of Least Privilege
  • Configuration Security
  • Command Execution Security
  • Privilege Dropping
  • Environment Isolation
  • State File Security
  • Symlink and Path Safety
  • PID Validation
  • Denial of Service Mitigation
  • Resource Limits
  • Timezone and Locale Safety
  • Supply Chain Security
  • Logging Safety
  • Kubernetes-Specific Security
  • Upgrade and Migration Security
  • Auditability
  • Cryptographic Requirements
  • Non-Goals
  • Security Invariants
• COMPAT.md
  • Scope
  • Cron Drop-in Profile (Next Stage)
  • Cron Expression Compatibility
  • Day-of-Month and Day-of-Week Semantics
  • Timezone Semantics
  • DST Handling
  • anacron Comparison
  • systemd Timers Comparison
  • Kubernetes CronJob Comparison
  • Behavior Differences from Cron
  • Backward Compatibility Rules
  • Forward Compatibility
  • Migration from Cron
  • Migration from systemd Timers
  • Migration from Kubernetes CronJob
  • Precision Differences
  • Reproducibility Guarantee
  • Unsupported Cron Features
  • Interoperability Expectations
  • Compatibility Invariants
  • Summary
• CRON-DROPIN.md
  • Purpose
  • Coverage Objective
  • Compatibility Tiers
  • Planned Compatibility Matrix
  • Non-Goals for This Stage
  • Acceptance Criteria
  • Execution Plan
• TEST-VECTORS.md
  • Canonical algorithms for vectors
  • Machine-readable vectors
  • Notation
  • Core decision vectors
  • Adapter outcome vectors
• CRD-SPEC.md
  • Scope
  • API Group
  • Resource Structure
  • Spec
  • schedule
  • timezone
  • window
  • distribution
  • seed
  • constraints
  • policy
  • jobTemplate
  • Status
  • lastOutcome
  • next* Fields
  • Conditions
  • Defaulting Rules
  • Immutability Rules
  • Reconciliation Semantics
  • Idempotency Rules
  • Suspension
  • Deadline Handling
  • Deletion Semantics
  • Upgrade Rules
  • Validation Guarantees
  • Compatibility Guarantees
  • Naming of Jobs
  • Invariants
  • Non-Goals
• CLI-SPEC.md
  • Scope
• krontab
  • Configuration Location
  • Command: krontab lint
  • Command: krontab explain
  • Command: krontab next
  • Command: krontab add
  • Command: krontab remove
• krond
  • Command: krond start
  • Command: krond reload
  • Command: krond status
  • Command: krond stop
• kronctl (Kubernetes helper)
  • Command: kronctl explain
  • Command: kronctl next
  • Command: kronctl validate
• Output Formats
• Exit Codes
• Determinism Requirements
• Logging Interaction
• Backward Compatibility
• Security Rules
• Non-Goals
• Kron manifesto (project principles)
  • What we believe
  • The promise
• Product shape (what Kron is) — superseded by SPEC.md and HELLOKRON.md
  • CRD sketch: KronJob (name flexible)
• Roadmap — superseded by top-level ROADMAP.md
  • Phase 0 — “It builds, it runs” (Week 1–2 worth of effort)
  • Phase 1 — Determinism + operational safety (MVP)
  • Phase 2 — Distribution and Constraint Capabilities
  • Phase 3 — Enterprise Adoption Requirements
  • Phase 4 — Long-Term Maintainership and Governance
• Repository layout suggestion — superseded by STRUCTURE.md