runtime.example.yaml

# yaml-language-server: $schema=https://id.registrystack.org/schemas/scheduling/runtime/runtime.v1alpha1.schema.json
# A complete Scheduling runtime configuration: the document
# `scheduling serve --runtime-config` reads and `schedulingctl plan`,
# `schedulingctl apply`, and `schedulingctl status` read with --runtime-config.
# Copy it to runtime.yaml, set every absolute path to this deployment's real
# location, and point the secret references at secrets the configured provider
# can resolve. Scheduling reads the authored policy at
# package.root/scheduling.yaml and refuses to start when that file is missing
# or does not pass its checks. Every configured path must be absolute and must
# not pass through a symbolic link.
#
# String values in this file may use ${VAR}, ${VAR:-default}, or ${VAR:?message}
# to take a deployment value from the environment when the runtime starts.
# Substitution never applies to a *Ref field, whose value must be written as a
# literal secret reference, nor under secretProviders, nor to the authored
# scheduling.yaml.
apiVersion: id.registrystack.org/formats/scheduling/runtime/v1alpha1
kind: SchedulingRuntimeConfig
package:
  # The package `schedulingctl package --output` writes: scheduling.yaml and
  # the SHA256SUMS file that lists it. The runtime verifies it at every start,
  # in every listener mode, and refuses a changed, missing, or extra file; no
  # second selector can override the policy it holds.
  root: /srv/registry-scheduling/package
  # Pin the package the runtime must serve: the packageDigest
  # `schedulingctl package` prints, the SHA-256 digest of SHA256SUMS. Any
  # other package is a startup refusal.
  # expectedDigest: sha256:<64 lowercase hex digits>
identity:
  # The name of the one database this deployment owns. `schedulingctl apply`
  # records it in the database's activation ledger, and apply, records apply,
  # and startup refuse a database whose ledger names another. Choose it once
  # per database; it is an operator label, never a secret or a URL.
  databaseId: registry-scheduling-production
listener:
  # Required: the IP address and port the runtime listens on.
  bind: 127.0.0.1:8105
  tlsTermination: development-loopback
  networkExposure: private-address
  # `operator-controlled-upstream` is the production value: the runtime itself
  # stays plaintext and an operator-managed TLS edge terminates transport in
  # front of it. `development-loopback` is direct plaintext, refused on any
  # non-loopback bind. `networkExposure: container-private` additionally
  # permits an unspecified bind for a listener kept on a private container
  # network.
secretProviders:
  file:
    # Every secret:file reference resolves under this root. A secret file must
    # be a regular file owned by the runtime user, with mode 0400 or 0600 and
    # exactly one hard link, carrying non-empty text of at most 64 KiB without
    # NUL bytes; `openssl rand -hex 32` generates the audit key.
    root: /run/secrets/registry-scheduling
  # Declare `environment: {}` to enable secret:env/NAME references. The
  # runtime does not fall back from one provider to another; every configured
  # reference must resolve under a provider declared here.
  # environment: {}
database:
  # The least-privilege service connection and the operator-run migration
  # connection, each a PostgreSQL URL held in the secret provider. The
  # runtime requires TLS on the database connection: it sets sslmode Require
  # and refuses a connection that cannot be verified.
  runtimeUrlRef: secret:file/runtime-database-url
  migrationUrlRef: secret:file/migration-database-url
  # The PEM bundle of the private CA in front of PostgreSQL, when the
  # deployment terminates database TLS with one.
  # trustedRootCertificateRef: secret:file/postgres-ca.pem
  # `testOnlyPlaintext: true` is the one plaintext escape, and only a build
  # carrying the `postgres-test` feature accepts it: a production build
  # refuses the setting at startup instead of opening an unencrypted
  # connection.
  # testOnlyPlaintext: true
authentication:
  oidc:
    issuer: https://identity.example.test/realms/registry
    audience: urn:example:scheduling
    # The claim carrying the accepted OAuth scopes. The default is `scope`,
    # the claim stock ThunderID emits.
    scopeClaim: scope
    # The read scope defaults to `scheduling:read` and the explain scope to
    # `scheduling:explain`; the two must differ. `allowedClients` names the
    # client ids the runtime admits. It is required in every file, development
    # loopback included: an omitted or empty list is refused when the file is
    # read, and `unrestricted` is a startup refusal, because it would admit
    # every client the issuer verifies.
    allowedClients: [scheduling-booking-agent]
    # `assertionIssuers` maps a client id to the assertion authorities it may
    # exchange a subject token from. A deployment that performs no token
    # exchange leaves it empty; once a client is listed, a token it
    # exchanged is accepted only for one of that client's declared
    # authorities.
    # assertionIssuers:
    #   scheduling-booking-agent: [https://issuer.example.test/assertions]
    # Signing keys come from issuer discovery by default. Declare the static
    # alternative instead when the runtime cannot reach the issuer's discovery
    # document, when the deployment is air-gapped, or when a test issuer's
    # keys are pinned by hand. It does no rotation of its own: rolling a key
    # means replacing the referenced document and restarting Scheduling.
    # jwksSource:
    #   type: static
    #   documentRef: secret:file/jwks.json
    # `type: uri` with `uri: https://...` fetches the key set from a fixed
    # address instead of the one discovery names.
# Required: how a task grant is checked before any hold or appointment
# changes. List the task authorities whose fresh grant status Scheduling
# checks for every commitment and replay, or write
# `unchecked-final-fifteen-minutes` to accept only a grant with at most
# fifteen minutes left at request entry, without a revocation check. An
# omitted member and an empty list are refused.
taskGrantStatus: unchecked-final-fifteen-minutes
# taskGrantStatus:
#   - sourceIssuer: https://casework.example.test/task-authority
#     baseUrl: https://casework.example.test
#     tokenEndpoint: https://identity.example.test/realms/registry/protocol/openid-connect/token
#     clientAssertionAudience: https://identity.example.test/realms/registry
#     clientId: scheduling-task-status
#     privateKeyRef: secret:file/scheduling-task-status-private-jwk
#     statusResource: urn:example:casework
audit:
  # One single-writer destination. `file`, the default, appends to the
  # absolute path, rotates at rotateBytes (default 100 MiB), and deletes
  # rotated files after retentionDays (default 90); `stdout` hands each entry to
  # the process supervisor and takes neither path nor the rotation keys.
  destination: file
  path: /var/lib/registry-scheduling/audit.ndjson
  hashKeyRef: secret:file/scheduling-audit-key
destinations: {}
  # Where due reminder intents are delivered as the shared hook envelope,
  # application/json over HTTPS POST (see the README Events section). An
  # absent reminders destination is a supported deployment: the intents stay
  # readable in the outbox and are set aside as local, never pretended
  # delivered.
  # reminders:
  #   url: https://bus.example.test/scheduling-reminders
  #   bearerTokenRef: secret:file/reminder-bearer-token
  # URL observers declared under scheduling.yaml hooks bind here. The policy
  # carries no endpoint or secret, and retained work keeps this exact binding.
  # hooks:
  #   appointment-events:
  #     url: https://integration.example.test/scheduling-events
  #     hmacSha256KeyRef: secret:file/appointment-events-hmac
  #     attemptTimeoutMilliseconds: 5000
  #     maximumAttempts: 8
retention:
  # Receipts, raw claim owners and hook payloads have separate bounded lifetimes.
  # Claim, history and reminder rows stay; audit.retentionDays bounds rotated
  # audit files. Seven days is a placeholder, not a jurisdictional recommendation.
  receiptRetentionDays: 7
  claimOwnerRetentionDays: 7
  hookPayloadRetentionDays: 7