Files
scriptorium/docs/operations.md

121 lines
7.0 KiB
Markdown
Raw Normal View History

# Operations Guide
This runbook covers deployment, normal operation, capacity, sensitive data, and
recovery. Exact [CLI syntax/statuses](cli.md), [configuration](config.md), and
[HTTP wire behavior](api.md) remain in their canonical references.
See the [CLI migration guide](consumers/upgrading-cli.md) for changed jobs and
the [framework upgrade guide](consumers/upgrading-promptkit.md) for definitions.
## Deploy Sources And Process
Provide readable application configuration, its selected framework entry file,
and explicitly imported definitions/resources. Set cwd deliberately: application
path values are cwd-relative, while framework imports and message resources keep
their native source contexts. ConfigKit confines source imports/overlays to the
selected main's canonical root; Scriptorium does not widen it.
Engine construction validates selected effective definitions and captures message
resources/template syntax, including definitions not used by a particular request.
Schema/artifact reads, credential resolution, and model work retain their native
preparation/runtime lifecycles. A server constructs one engine at startup and
does not hot-reload changed files; restart to capture updates. Separate CLI
invocations load afresh rather than sharing an immutable snapshot.
For independent collections, install checkouts beneath the layout selected by
the [discovery entry](../examples/discovery/framework.yml). Each checkout declares
its namespace and explicit fragment imports; arbitrary YAML is not a framework
source. The maintained [discovery example](../examples/config.discovery.yml)
supports both entry-file spellings and multiple definitions. New checkouts or
updates become visible to later invocations or a restarted server.
Supply only needed credential environment variables through a supervisor or
secret-management mechanism. Confirm presence without printing their values.
Raw keys do not belong in arguments or checked-in configuration.
## Normal Operator Workflow
1. Validate application configuration through the native application scope.
This does not acquire framework sources or prove provider readiness.
2. Inspect framework configuration/resources and discover requirements for the
selected prompt/profile/namespaces. Discovery can precede generated input
artifacts; completeness does not establish satisfied bindings.
3. Once artifacts exist, validate the concrete request or inspect prepared
content. These are provider-free preparation checks with native prerequisites.
4. Invoke a smoke test only when its provider effects are intended. Findings
can be unsupported or unsuccessful while the command itself succeeds.
Smoke tests are not an automatic startup or release prerequisite.
5. Generate with the same selections and bindings, then inspect the finalized
status and any returned validation result before accepting the output.
Use the [maintained preview script](../examples/render-markdown-summary.sh)
for a provider-free example, and the [CLI contract](cli.md) for commands.
A complete discovery report can still list required inputs that are not bound;
a partial report can still be useful. Consumers own their policy for incomplete
findings and changed resources between invocations.
## Sensitive Data And Retention
Artifacts, prompt messages, prepared content, native run reports, metadata,
diagnostics, and redirected streams are caller-owned potentially sensitive data.
The separate CLI report contains the full returned result, not metadata alone.
Control access, retention, encryption, backup, and deletion accordingly.
Framework effective/explanation views apply native classified-field redaction,
including history, but do not detect arbitrary secrets. Other content-bearing
reports are not automatically made safe for publication.
Keep main output and report destinations separate. Delivery is nontransactional:
one destination or partial bytes can remain after failure. An existing report
can remain on a resultless error; check status and report identity, not just file
existence. A shell can truncate a redirected destination before the child starts.
Omit quiet if main stdout must be captured; the separate report effect remains
independent. Exact delivery behavior belongs to [CLI results](cli.md#results-and-separate-reports).
HTTP's optional [execution report](api.md#execution-report) remains a distinct
terminal-observation projection. Protect its identifiers and any response data.
It increases encoded response size and remains subject to the configured limit.
## HTTP Deployment And Shutdown
The service has no built-in authentication/authorization. Deploy on a trusted
network or behind appropriate authenticated proxy/gateway controls. Use a narrow,
dedicated artifact root with controlled ownership and permissions when accepting
file inputs; this is lexical containment, not a symlink sandbox.
Use a supervisor for cwd, environment, restart policy, and stream capture.
Startup information uses native Info reporting, not stdout banners.
Interrupt/SIGTERM cancels the invocation and closes the listener and active
connections. Canceled shutdown is nonzero operational termination. There is no
graceful-drain deadline or promise that context-ignoring work has finished;
supervisors own forced termination when necessary.
## Capacity, Limits, And Recovery
One server engine shares backend admission/queue state across concurrent requests.
That state is transient operational coordination, not a durable workflow or
queue of resumable runs. HTTP capacity exhaustion retains its
[API outcome](api.md); callers decide whether another model call is safe.
Plan for input/output sizes, schema complexity, provider latency, retries, and
repair costs. Native transient attempts and repair generations can add calls and
waiting; engine defaults and per-request overrides belong to
[configuration](config.md) and the [CLI](cli.md)/[HTTP](api.md) contracts.
Whole-operation budgets are distinct from per-attempt generation timeouts.
They remain cooperative and do not include configuration/setup or delivery.
Before increasing HTTP byte limits, measure representative requests/artifacts/
responses, confirm memory/network/provider capacity, retain authentication and
upstream request controls, and test a representative workload. Do not widen the
artifact root just to make an arbitrary host path accessible.
For failures, capture diagnostics without publishing sensitive data. Verify
selected configuration, resource identity, readable inputs, profile/credentials,
and schema deployment. Use native prepared preview to isolate pre-generation
problems. A completed content-validation failure is distinct from an operational
failure to validate; consumers choose whether failed content is usable.
Correct the cause, then issue a new request only when another provider call and
its cost are acceptable.
There is no durable run store, archive, checkpoint, or resume mechanism.
Cleanup concerns caller-owned files/logs only. Rotate/delete them under the
deployment's normal retention policy; recovery starts from a new request.