diff --git a/docs/cli.md b/docs/cli.md index f29277b..21d7fc7 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -40,7 +40,7 @@ pipeline ID and **--input** are required. | **--debug-dir path** | Override the debug-bundle root. Requires **--debug**. | | **--only lane-a,lane-b** | Run only the selected comma-separated artifact lanes when that selection is valid for the configured pipeline. | | **--llm-profile id** | Highest-precedence configured profile for selected LLM-backed bindings and validators; it replaces binding and [pipeline](config.md#pipelines) defaults. | -| **--session-id id** | Supply a non-empty prompt session identifier to LLM-backed module calls. | +| **--session-id id** | Override the generated prompt session identifier with a non-empty value for LLM-backed module calls. | | **--reasoning-effort value** | Replace the selected PromptKit profile's reasoning effort for every LLM-backed call in this run. The value must be non-empty and the flag may be specified only once. | | **--clear-reasoning-effort** | Clear reasoning effort inherited from the selected PromptKit profile for every LLM-backed call in this run. | | **--reference selector=path** | Add or replace a file reference binding. Repeatable. | @@ -57,6 +57,16 @@ Persistent reasoning settings remain a PromptKit profile concern. **--recompute-step** requires **--resume**; checkpoint requirements and reuse behavior are documented in [Operations](operations.md). +Every run uses one effective prompt session. Without **--session-id**, Notarius +generates a stable `notarius:v1:` identifier from the trimmed resolved input +module key and the input file's exact raw bytes. The same module and bytes +therefore produce the same identifier, regardless of pipeline, references, +profile, retries, or run settings. An explicit non-empty value replaces that +default. Session identifiers are visible to providers; they are non-secret +correlation identifiers, not credential storage. See +[Operations](operations.md#operational-limits) for privacy and workflow +guidance. + ### Reference selectors Use **--reference** only for a reference slot declared by the selected diff --git a/docs/config.md b/docs/config.md index 2aeb274..f1ead4f 100644 --- a/docs/config.md +++ b/docs/config.md @@ -58,7 +58,7 @@ Built-in defaults are: | Field | Default | | --- | --- | -| **concurrency.total_llm** | 1 | +| **concurrency.total_llm** | 16 | | **concurrency.stage_workers.extract** | Effective **total_llm** | | **output.directory** | **./notarius-output** | | **cache.chunk_plans.mode** | **auto** | diff --git a/docs/consumers/subprocess.md b/docs/consumers/subprocess.md index a828639..fe67c5a 100644 --- a/docs/consumers/subprocess.md +++ b/docs/consumers/subprocess.md @@ -27,10 +27,13 @@ notarius run pipeline-id \ ``` Use absolute paths for supplied input, configuration, output-root, and -reference files. When a stable prompt session identifier or references are -needed, pass the supported CLI flags. Supply credentials through Notarius's -documented configuration and environment mechanisms, never as command-line -arguments or generated secret-bearing configuration. +reference files. Notarius generates a stable prompt session for the resolved +input module and exact input bytes. Pass **--session-id** only when intentionally +grouping different invocations under a different session. Supply credentials +through Notarius's documented configuration and environment mechanisms, never +as command-line arguments or generated secret-bearing configuration. In +particular, a session identifier is provider-visible and is not a credential +mechanism. Wait for the process before interpreting standard output. Only an exit status of 0 permits decoding the receipt. On a nonzero exit, retain standard error for diff --git a/docs/integrations/json-output.md b/docs/integrations/json-output.md index 1885f34..70ddd48 100644 --- a/docs/integrations/json-output.md +++ b/docs/integrations/json-output.md @@ -98,6 +98,11 @@ summarize results without embedding lane payload bytes. A chunk-plan summary is provenance for the plan used by this run; cache records, debug artifacts, and other operational state are not published as bundle files. +When present, `metadata.session_id` is the effective non-secret routing +correlation identifier used for the run. It can be visible to providers and is +not a substitute for a cache or checkpoint identity. Its generation and +override behavior are defined by the [CLI reference](../cli.md#run). + Each `llm_profiles` entry identifies effective, non-secret LLM execution provenance: diff --git a/docs/integrations/pkg-promptkit.md b/docs/integrations/pkg-promptkit.md index 00b022a..baa7811 100644 --- a/docs/integrations/pkg-promptkit.md +++ b/docs/integrations/pkg-promptkit.md @@ -48,11 +48,13 @@ adapter boundary. It also retains responsibility for pipeline retries, scheduling, debug persistence, redaction, profile provenance, and conversion from private model responses into durable domain artifacts. -Notarius sends its trimmed run session through PromptKit's direct session +Notarius sends one stable effective session through PromptKit's direct session field, which is authoritative for provider session behavior. It also retains the same value as the `session_id` prompt variable for maintained prompt -compatibility. Session IDs are stable, non-secret correlation identifiers and -may be exposed to providers and provider observability. +compatibility. The generated identifier is 76 ASCII characters, within +PromptKit v0.5.0's 256-code-point session limit. Session IDs are non-secret +correlation identifiers and may be exposed to providers and provider +observability. The CLI contract owns generation and override behavior. Notarius records PromptKit's selected backend ID and effective reasoning setting as optional run-manifest provenance. Endpoint-only profiles have no diff --git a/docs/internal/cli.md b/docs/internal/cli.md index 566a704..b470e15 100644 --- a/docs/internal/cli.md +++ b/docs/internal/cli.md @@ -89,9 +89,11 @@ handoff: profiles; 4. materialize external or generated references and record redacted invocation and resolution provenance when debug capture is enabled; -5. construct registries, the scheduled LLM client, prepared modules, and the - requested cache/checkpoint collaborators; -6. read the source input and invoke the framework runner; and +5. construct registries, the scheduled LLM client, and prepared modules; +6. read the source input once, resolve its effective session from the explicit + override or resolved input module and raw bytes, then construct requested + checkpoint collaborators and invoke the framework runner with that same + value; and 7. write the runner's logical output files only after a successful run, then complete the command report and user-facing result. @@ -102,6 +104,13 @@ final command result. Detailed state lifecycle, resume handling, and physical path confinement are maintained in [Run State Internals](state.md) and [Operations](../operations.md). +The CLI owns the versioned generated-session policy and resolves the sole +effective value before checkpoint construction. It records that value in the +final debug invocation summary when capture is enabled and passes it unchanged +to checkpoint identity and `pipeline.RunInput`. The public flag and stability +contract are defined by the [CLI reference](../cli.md#run); framework and LLM +packages only transport the supplied value. + For `run --json`, the CLI constructs and encodes its private run-result receipt after a successful runner result is available, before it publishes logical output files. It writes the prepared receipt to standard output only after diff --git a/docs/internal/llm.md b/docs/internal/llm.md index a82e656..a3fe5f3 100644 --- a/docs/internal/llm.md +++ b/docs/internal/llm.md @@ -26,9 +26,10 @@ durable schemas. Those responsibilities remain with the module and its `PromptKitClient` validates the request target and prompt identity, maps each named material to a PromptKit inline artifact while preserving its origin URI, -maps the trimmed request session to PromptKit's direct per-run session field, -retains the same value as the `session_id` prompt variable for maintained -prompt compatibility, and forwards profile selection. It then creates one +passes the supplied request session through to PromptKit's direct per-run +session field, retains the same value as the `session_id` prompt variable for +maintained prompt compatibility, and forwards profile selection. It does not +derive or replace session values; the CLI owns that policy. It then creates one frozen prepared execution, captures its caller-owned credential-redacted details for debug material, and executes that exact snapshot through PromptKit's prepared-execution boundary. The direct field diff --git a/docs/internal/pipeline.md b/docs/internal/pipeline.md index cf152eb..0589337 100644 --- a/docs/internal/pipeline.md +++ b/docs/internal/pipeline.md @@ -10,11 +10,11 @@ own durable output shapes. Concrete production extensions are covered by ## Boundary The pipeline framework accepts a resolved composition, registries, shared -dependencies, input bytes, and state/debug collaborators. It returns logical -output files, normalized artifacts, recorded rejections and warnings, manifest -provenance, and checkpoint decisions. The CLI owns process arguments, -configuration discovery, physical roots, and placement of returned output -files. +dependencies, input bytes, a supplied prompt session, and state/debug +collaborators. It returns logical output files, normalized artifacts, recorded +rejections and warnings, manifest provenance, and checkpoint decisions. The +CLI owns process arguments, configuration discovery, session resolution, +physical roots, and placement of returned output files. The framework has one fixed shape: @@ -84,6 +84,10 @@ incompatible producer prevents the consumer step from starting. The runner validates its input, installs no-op state collaborators when none were supplied, and serially performs source parsing and chunk-plan selection. +It transports the supplied session unchanged to prompt-facing operations and +run-manifest metadata; it neither derives a session nor substitutes a parsed +source document identifier. The public session contract is owned by the +[CLI reference](../cli.md#run). An accepted plan is materialized into source-addressed chunks and passes the configured chunk validators before any lane runs. A chunk rejection is a recorded pipeline outcome: lanes do not start, but the output stage can encode diff --git a/docs/operations.md b/docs/operations.md index a25d94a..2f21777 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -266,16 +266,18 @@ transport-wide cap. Notarius does not add another timeout around PromptKit. The pinned upstream boundary and profile-format links are in [PromptKit Integration](integrations/pkg-promptkit.md). -Concurrency has two independent layers. Notarius **total_llm** is the -application-wide provider-call limit shared by all backends, modules, retries, -and validators. PromptKit may impose a narrower admission limit for the -selected backend. The effective active-generation bound is the intersection of -both limits and can therefore be lower than **total_llm**. Built-in OpenRouter -profiles use PromptKit's upstream backend limit; endpoint-only profiles have no -PromptKit backend limit and remain bounded by Notarius. For the configured -local backend, a zero **concurrency_limit** leaves only the Notarius scheduler -as a call limit. A positive value makes the effective active local-generation -bound the smaller of **total_llm** and that local limit. +Concurrency has two independent layers. Notarius **total_llm** defaults to 16 +and is the application-wide provider-call limit shared by all backends, +modules, retries, and validators. PromptKit may impose a narrower admission +limit for the selected backend. The effective active-generation bound is the +intersection of the Notarius limit, any PromptKit backend limit, and work made +available by the pipeline. Built-in OpenRouter profiles use PromptKit's +upstream backend limit; endpoint-only profiles have no PromptKit backend limit +and remain bounded by Notarius. For the configured local backend, a zero +**concurrency_limit** leaves only the Notarius scheduler as a call limit. A +positive value makes the effective active local-generation bound the smaller +of **total_llm** and that local limit, so a local limit of four permits no more +than four active local generations. For a positive local limit, PromptKit owns its default waiting capacity and admission behavior. When a PromptKit backend has admitted all active and queued @@ -289,3 +291,11 @@ under [PromptKit profiles](config.md#promptkit-profiles) and limits and actual provider-call limits are independent. Notarius writes local filesystem state only; remote storage, archival, and retention automation are outside the implemented CLI. + +Every run has an effective prompt session used for provider routing and run +provenance. The generated default is stable for the same input module and raw +input bytes; use [**--session-id**](cli.md#run) only when intentionally grouping +different invocations. Both generated and explicit values can be visible to +providers, manifests, checkpoints, and requested debug bundles. Do not put +credentials or other secrets in an explicit session identifier; command-line +values are not a credential mechanism. diff --git a/docs/roadmap/future.md b/docs/roadmap/future.md index df750cc..fd1c7a2 100644 --- a/docs/roadmap/future.md +++ b/docs/roadmap/future.md @@ -53,71 +53,6 @@ not as committed release dates. spell, combat, interaction, and scene-description lanes after real-world use. Add more complex chunking only in response to demonstrated failures. -## Cross-Cutting LLM Runtime - -### Deterministic Prompt Session Identity - -- Replace the source-document-ID default for prompt sessions with one - predictable, procedurally generated session ID for the complete - source-processing workload. -- Preserve an explicit non-empty `--session-id` as the highest-precedence - override. Otherwise, derive the default only from the effective input module - identity and the exact raw input bytes. -- Use a versioned, bounded representation such as - `notarius:v1:`. The exact encoding - must fit PromptKit's session length contract and must not embed source - content. -- Keep the derived session stable across runs, pipelines, selected lanes, - ordered steps, retries, resume, recomputation, LLM profiles, reasoning - overrides, and output, debug, or cache settings. -- Do not include file-backed references, generated references, reference - contents, or the composition of a reference bundle in session derivation. - References may change between prompt calls within one pipeline without - changing routing affinity. -- Resolve the authoritative session before checkpoint construction and use the - same value for checkpoint runtime identity, every prompt-facing module, - PromptKit's direct session field, the compatibility `session_id` prompt - variable, run-manifest metadata, and debug metadata. -- Keep routing identity separate from cache and checkpoint content identity. - Exact prompt prefixes, reference contents, model settings, and other - generation-affecting inputs must continue to participate in their existing - hashes and checkpoint fingerprints even though they do not change the - session. -- Treat the generated value as a provider-visible, stable pseudonymous - correlation identifier. Do not introduce an installation-specific HMAC or - secret unless a concrete multi-tenant or privacy requirement justifies - sacrificing deterministic identity across installations. - -### Raise The Default Application-Wide LLM Limit - -- Raise the default `concurrency.total_llm` value from 1 to 16 so ordinary - single-backend runs can use PromptKit's expected OpenRouter capacity and - lower-capacity local backends without an unnecessarily narrower Notarius - limit. -- Keep the Notarius application-wide scheduler mandatory and require - `total_llm` to remain a positive integer. Do not make the default unlimited: - endpoint-only profiles, an unrestricted local backend, injected clients, and - aggregate work across several backends may have no narrower PromptKit limit. -- Continue defaulting `concurrency.stage_workers.extract` to the effective - `total_llm`, making its default 16 as part of the same change. Preserve an - explicit lower extract-worker setting when an operator wants less queued or - concurrent extraction work. -- Define effective provider concurrency as the intersection of the Notarius - application-wide limit, the selected PromptKit backend limit when present, - and the work made available by stage execution. A Notarius limit of 16 does - not narrow a backend already limited to 16, while a local backend limited to - 4 remains bounded at 4. -- Treat the default as an application-wide safety ceiling across profiles, - backends, modules, retries, and validators. A run that intentionally needs - the combined capacity of several backends may configure a higher - `total_llm` and an appropriate extract-worker count explicitly. -- Retain the existing configuration and environment override surfaces. Update - canonical configuration, operations, and internal documentation together - when the default changes. -- Reconsider decoupling the extract-worker default from `total_llm` only after - mixed-backend workloads demonstrate a need for a high global emergency - ceiling with a lower default work-production rate. - ## Shared Normalization And Quality Work ### Generic LLM-Assisted Deduplication