# Service and Infrastructure Standard

Structures local services, APIs, health checks, logs, and recovery procedures.

Catalog: active · v0.1.0 · reviewed 2026-09-23

Source maturity: candidate · Explanation reviewed 2026-10-01

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

[Public page](https://aptlantis.net/city-hall/sis)

<a id="purpose-and-applicability"></a>

## 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.

<a id="how-it-works"></a>

## 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.

<a id="in-practice"></a>

## 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.

### Health contract specimen

illustrative · teaching example, not a verification result

Illustrative contract with explicit unknown state.

Source: `SIS/templates/Health-Check-Contract.md`

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

[Inspect Health contract specimen](/city-hall/standards/sis/example-1.json)

### Runbook excerpt

illustrative · teaching example, not a verification result

Sanitized example resource policy with an editorial recovery note; no private storage paths are published.

Source: `SIS/examples/Example-Local-API-Service.md`

```text
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.
```

[Inspect Runbook excerpt](/city-hall/standards/sis/example-2.txt)

<a id="adopt-one-part"></a>

## 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.

<a id="sources-and-limits"></a>

## 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`

[Reviewed manifest facts](/city-hall/components/sis.md)

## Related responsibilities

- [Command Tool Standard](/city-hall/cts): Defines lifecycle-command streams and exit codes.
- [Workspace Governance Standard](/city-hall/wgs): Registers service placement and lifecycle.
- [Library Development Standard](/city-hall/lds): Governs any library API consumed inside the service.