Service and Infrastructure Standard

Purpose and applicability

A service that starts successfully can still leak disk space or have no recovery path. SIS describes its operator-visible identity, health, resources and lifecycle.

Long-running services, local APIs, daemons, scheduled processes, indexers and shared infrastructure, independent of language.

How it works

Declare start, stop, restart and graceful shutdown, dependencies, bind addresses and ports. Define healthy, degraded, offline and unknown health states. Bound logs/cache growth and give the operator a recovery procedure that preserves durable state.

Outputs are the service manifest, health contract, runbook and resource constraint contract. Operators should be able to inspect health/logs and recover without reading source code.

In practice

The health specimen uses “unknown” to avoid implying an observed running service. The runbook excerpt records the canonical example’s resource bounds and a safe inspection/recovery boundary.

{
  "service_id": "example-service",
  "status": "unknown",
  "version": "",
  "dependencies": [],
  "ports": [],
  "warnings": ["No live observation"],
  "errors": [],
  "next_safe_action": "inspect logs and dependencies"
}

Log policy: rotate at 10 MB/file; retain 10 files.
Cache cleanup trigger: 2 GB.
Durable state: metadata records.
Rebuildable state: cache.
Inspect: health/status and logs.
Restart boundary: do not restart during active indexing unless runbook confirms the queue is idle.
Recovery: inspect dependencies and preserve durable records before rebuilding cache.

Adopt one part

Start with a bounded surface or record. Complete the relevant adopter checks before extending the claim.

1. Document one service’s identity, lifecycle, ports and durable versus rebuildable data.
2. Write its health contract and log/cache limits; name dependency failure and port-conflict behavior.
3. Exercise start/stop, degraded health and recovery in the intended environment, then record actual results.

Sources and limits

No API was contacted. Resource limits below are teaching values from the example, not configured limits on this site. A command-shaped lifecycle control can use CTS while the running process remains governed by SIS.

These are reviewed public explanations, not the normative specifications. Suite references are relative to the canonical collection; site/ references identify committed website sources and webserver/ references identify serving configuration. Illustrative examples demonstrate record shape; they do not establish compliance. Suite checks and adopter validation are separate.

• SIS/SIS.manifest.toml
• SIS/Adoption-Guide.md
• SIS/Validation-Checklist.md
• SIS/examples/Example-Local-API-Service.md
• SIS/templates/Health-Check-Contract.md
• SIS/templates/Service-Runbook.md