Files
scriptorium/docs/operations.md

7.0 KiB

Operations Guide

This runbook covers deployment, normal operation, capacity, sensitive data, and recovery. Exact CLI syntax/statuses, configuration, and HTTP wire behavior remain in their canonical references. See the CLI migration guide for changed jobs and the framework upgrade guide 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. Each checkout declares its namespace and explicit fragment imports; arbitrary YAML is not a framework source. The maintained discovery example 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 for a provider-free example, and the CLI contract 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.

HTTP's optional 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; 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 and the CLI/HTTP 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.