Reliability Operations Pack

The Reliability Operations Pack (@hellmai/lumenflow-packs-reliability-operations) gives operators one small, provider-neutral vocabulary for asking what is failing. It normalizes service, incident, metrics, logs, traces, alert, and timeline evidence without copying a remote provider’s complete tool catalog into the model loop.

The manifest command surface remains seven read-only tools. Remediation is a separate application workflow with closed actions, exact authority, durable one-shot approval, reconciliation, and recovery; installing the package does not expose a generic write command or grant connector credentials.

Caution

The pack declares a trusted host-adapter boundary. A host must explicitly register trusted-host-adapter:reliability-operations and bind the tool executor before any manifest entry can run. The pack cannot self-register; an unbound entry fails closed with capability_denied.

Install and verify the distribution

The npm package is the independently consumable TypeScript/JavaScript API. The signed OCI artifact is the executable Pack Contract v2 distribution activated in a workspace. Use the same release version for both, and obtain the immutable OCI digest from the signed release evidence rather than trusting a mutable tag.

# Requires a licence grant: a consumer npmrc scoped to
# //<registry-host>/, selected via NPM_CONFIG_USERCONFIG or --userconfig.
# See https://lumenflow.dev/packs/software-delivery/setup/migrating-to-github-packages/.
pnpm add @hellmai/lumenflow-packs-reliability-operations@<release-version>

# Read the exact npm version and registry integrity back independently.
npm view @hellmai/lumenflow-packs-reliability-operations@<release-version> \
  version dist.integrity dist.tarball --json

# Activate the signed pack by immutable digest.
pnpm pack:install --id reliability-operations --source registry \
  --version <release-version> \
  --digest sha256:<published-oci-digest> \
  --registry-url https://registry.lumenflow.dev \
  --expected-publisher-id lumenflow \
  --expected-issuer https://token.actions.githubusercontent.com \
  --expected-identity-pattern '^https://github\.com/hellmai/lumenflow/'

Installation fails closed unless the pack digest, publisher, Sigstore signer, SLSA builder/build type, CycloneDX SBOM subject and media type, SBOM content digest, provenance-to-SBOM binding, compatibility range, and Contract v2 registration all verify before atomic cache promotion. A missing, duplicate, or conflicting referrer is an error; there is no checksum-only, unsigned, git, or tarball fallback.

pnpm lumenflow:upgrade --version <release-version> includes this package when it is already declared directly in the consumer’s package.json. Upgrade does not silently add optional packs. Re-run the npm read-back above and compare the release’s OCI digest before changing a workspace pin.

See Signed OCI pack distribution for the publisher command, SBOM generation, verification order, quarantine, replay and downgrade rules, and cache recovery.

Reliability vocabulary

• Service identifies the workload and environment under investigation.
• Incident captures status, severity, affected services, and lifecycle timestamps.
• Signal query names a service, signal family, normalized expression, and exact time range.
• Source reference binds evidence to a source identity, tenant, and workspace.
• Observation records query provenance, pagination, retrieval time, digest, truncation, error provenance, and untrusted content.
• Evidence link relates an observation to a conclusion without mutating either record.
• Action proposal is deliberately proposal-only; this read-only phase grants no remediation authority.

These schemas contain no Grafana-, protocol-, or cloud-specific fields. Provider details live only behind the connector port.

Small read-only surface

Tool	Result
reliability:get_service	One bounded service lookup.
reliability:get_incident	One incident record.
reliability:query_metrics	Metrics evidence for a time range.
reliability:query_logs	Log evidence for a time range.
reliability:query_traces	Trace evidence for a time range.
reliability:query_alerts	Alert evidence through a fixed list operation.
reliability:get_incident_timeline	Source-linked incident activity.

There is no dispatch, generic remote tool name, or caller-supplied provider payload. Every manifest tool is read-only and asks the trusted host adapter to perform a named pack operation.

Evidence guarantees

Every observation includes:

• source identity plus tenant/workspace binding;
• the normalized query and time range;
• the incoming pagination cursor and retrieval timestamp;
• a SHA-256 content digest;
• explicit truncation and error provenance;
• trust: untrusted-provider-output.

Sensitive token-shaped fields are redacted before content reaches evidence. Instruction-like text remains inert provider data; it never becomes a new tool request, scope, or approval.

See Connector security for the trust boundary and Safe investigations for a complete read example. Review Approval-gated remediation before enabling any write profile.

Connector setup checklist

1. Register trusted-host-adapter:reliability-operations for this exact pack ID; an adapter registered for another pack is rejected.
2. Configure all six context pins: issuer, audience, canonical resource, tenant, workspace, and connector ID.
3. Create seven unique read credential profiles with exactly the scopes in Connector security.
4. If remediation is enabled, create separate action-specific write profiles and a distinct reconciliation read profile. Never reuse a read tool profile for a mutation.
5. Exercise a bounded read fixture first. Keep live smoke read-only and redact credentials, headers, provider output, and tenant identifiers from evidence.

Schema drift, stale connector identity, an extra scope, a reused profile, or a contradictory remote annotation fails before provider invocation. Fix the pin or profile; do not widen authority to make discovery pass.

Recovery and clean removal

Registry installs materialize at <LUMENFLOW_HOME>/pack-cache/reliability-operations@<release-version> only after verification. If the cache is missing or corrupt, rerun the same digest-pinned pack:install; atomic replacement never patches mixed content in place. A same-digest reinstall is idempotent. Downgrades, same-version digest retargets, publisher substitution, replayed superseded digests, and frozen state require an explicit audited trust-transition authorization.

To remove the pack cleanly:

1. stop workloads using the workspace;
2. remove only the reliability-operations pin from workspace.yaml through your reviewed workspace-configuration change;
3. remove only the exact version directory under <LUMENFLOW_HOME>/pack-cache/ after the pin change is committed;
4. restart/reinitialize the runtime and verify the installed extension registry contains no reliability-operations pack ID, tools, policies, state namespaces, event kinds, or imports.

Do not delete the installed-trust-state ledger to force a transition. It is the record that makes later replay, downgrade, retarget, and substitution attempts fail closed. Reinstalling the same accepted digest remains supported after a clean removal.