From 2ccbee3758ec3f2c6bc87bec44be8dcdf4be98a4 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Mon, 2 Nov 2026 12:57:20 +0000 Subject: [PATCH] Document identified resource formats and interpretation --- docs/formats.md | 102 +++++++++++++++++---------------- docs/internal/observation.md | 3 +- docs/internal/runner.md | 3 +- docs/internal/sources.md | 26 +++++---- docs/roadmap/implementation.md | 7 +++ 5 files changed, 75 insertions(+), 66 deletions(-) diff --git a/docs/formats.md b/docs/formats.md index 4324143..d63fa1f 100644 --- a/docs/formats.md +++ b/docs/formats.md @@ -6,31 +6,28 @@ This is the canonical reference for Promptkit's backend, profile, prompt, and schema definitions. The [Go consumer guide](consumers/pkg-promptkit.md) shows how to select sources and use an engine; the [OpenAI-compatible integration contract](integrations/openai-compatible-chat.md) -owns outbound wire behavior. [ConfigKit](https://gitea.maximumdirect.net/eric/ConfigKit) +owns outbound wire behavior. [ConfigKit](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.0.0/docs/config.md) owns the generic YAML grammar, imports, layering, inheritance, and diagnostics. This reference describes what Promptkit does with the final effective values. -A configuration document may contain keyed top-level `backends`, `profiles`, -and `prompts` mappings, plus a `collections` mapping of namespaced resource -groups. Resource keys are literal IDs, not filename-derived identities. Each -prompt ID maps directly to one definition; an optional `version` string is -descriptive metadata, not a selection key. Keys and references must be nonblank -and remain exact: Promptkit does not trim or re-key them. Old embedded `id` and -`base_profile` fields are invalid. Unknown fields are errors. Promptkit installs -no provider or profile catalog; callers select the definitions they need. +A configuration document may contain top-level `backends`, `profiles`, and +`prompts` lists, plus a `collections` mapping of namespaced resource groups. +Each resource has an explicit literal `id`, not a filename-derived identity. +IDs and references must be nonblank and remain exact: Promptkit does not trim or +re-key them. Unknown fields are errors. Promptkit installs no provider or +profile catalog; callers select the definitions they need. ```yaml backends: - local: + - id: local endpoint: http://localhost:8000/v1 concurrency_limit: 2 profiles: - local-summary: + - id: local-summary backend: local model: example-model prompts: - meeting.summary: - version: "1.0.0" + - id: meeting.summary default_profile: local-summary messages: - role: user @@ -42,17 +39,17 @@ collections: support: release_version: "1.4.0" backends: - offline: + - id: offline endpoint: https://example.invalid/v1 profiles: - base: + - id: base backend: support/offline model: offline-model - fast: - extends: base + - id: fast + extends: {id: base} timeout_seconds: 30 prompts: - answer: + - id: answer default_profile: support/fast messages: - role: user @@ -66,31 +63,33 @@ collections: An input may omit a source header. When present, the source-root `version` is reserved for ConfigKit's specification header and accepts only the exact string -`"1"` or strict decimal integer `1`; null and other values are invalid. This -header is distinct from a prompt's nested `version` label and a collection's -`release_version`. ConfigKit checks and consumes accepted headers on non-main +`"2"` or strict decimal integer `2`; null and other values are invalid. This +header is distinct from a collection's `release_version` and ConfigKit's own +software version. ConfigKit checks and consumes accepted headers on non-main inputs; a declaration on the main input remains visible in explicit configuration inspection. Headerless inputs still undergo ordinary final-value validation. ConfigKit owns generic import and source-history behavior. +For a standalone prompt item, a root `version` is only a source header, not +prompt metadata. -The root resource mappings contain unqualified IDs. Each `collections` entry +The root resource lists contain unqualified IDs. Each `collections` entry has a namespace key and may contain `release_version` plus the same three -resource mappings. Collection resource keys are local keys; their runtime IDs +resource lists. Collection resource IDs are local keys; their runtime IDs are `/`. Root and collection keys may be the same. A namespace and local key must be nonblank and slash-free, and references must name their intended exact ID; mounting a source does not rewrite references. For example, the `support/fast` profile above stores `support/offline` as its -backend ID. In `collections.support.profiles.fast`, ConfigKit `extends: base` -refers to a sibling profile in that same mapping. It is not a qualified or -cross-collection reference. +backend ID. `extends: {id: base}` refers to a sibling in the same resource +list. It is not a qualified or cross-collection reference. -`release_version` and prompt `version` are optional opaque labels. Absent or -null means no label; an explicitly empty string is retained as a declared -label. Neither label selects a resource or changes execution. Runtime lookups +`release_version` is an optional opaque collection label. Absent or null means +no label; an explicitly empty string is retained. It does not select a resource +or change execution. Runtime lookups use the captured effective resource indexes. `InspectConfiguration` is an -explicit operator view of effective settings and provenance; source history is -not a second runtime resolver, and the retained effective shape is not flattened -or rewritten into those indexes. +explicit operator view of composed settings and provenance. Normalization and +defaults appear in Promptkit's interpreted execution views, not as changes to +that composed tree. Source history is not a second runtime resolver, and the +retained effective shape is not flattened or rewritten into those indexes. For examples of explicitly selecting native collection inputs and inspecting inventories, see the [consumer guide](consumers/pkg-promptkit.md) and its @@ -116,12 +115,11 @@ see the consumer guide's [resource and collection listing](consumers/pkg-promptk ## Prompt Definitions -The `prompts` mapping selects a literal prompt ID whose value is the definition: +The `prompts` list contains definitions selected by their literal IDs: ```yaml prompts: - meeting.summary: - version: "1.0.0" + - id: meeting.summary default_profile: local-summary description: Summarize a synthetic meeting note. session_id: '{{.session}}' @@ -237,7 +235,8 @@ It may contain `default_profile`, `reachability`, and `authentication`: ```yaml backends: - openrouter: + - id: openrouter + endpoint: https://openrouter.ai/api/v1 smoke_tests: default_profile: application-profile reachability: @@ -266,21 +265,22 @@ These values are configuration only: engine construction does not contact a backend. These fields are resolved through the ordinary ConfigKit source layers before -Promptkit validates the final effective values. A higher-priority mapping can -override individual nested fields; an explicit null can clear the whole -`smoke_tests` block or one of its nested objects. An endpoint set to null uses +Promptkit validates the final effective values. Sibling inheritance can overlay +individual nested fields; a later same-ID resource replaces the whole record. +An explicit null can clear the whole `smoke_tests` block or one of its nested +objects. An endpoint set to null uses its documented fallback, while an explicit blank endpoint is invalid. The metadata does not change ordinary generation credential requirements or provider settings. ## Profile Definitions -Profiles are keyed by literal ID and may inherit a named parent with +Profiles have literal IDs and may inherit a sibling parent with `extends`: ```yaml profiles: - local-summary: + - id: local-summary backend: local model: example-model temperature: 0.2 @@ -288,8 +288,8 @@ profiles: timeout_seconds: 90 extra_params: provider_option: enabled - local-summary-fast: - extends: local-summary + - id: local-summary-fast + extends: {id: local-summary} timeout_seconds: 30 reasoning_effort: low ``` @@ -343,25 +343,27 @@ nothing. Imports are disabled by these helpers unless the caller enables them on an input. Single files can use ConfigKit inputs directly. Root backends, profiles, and prompts, as well as collection declarations and -their resource mappings, follow these same source rules. `CollectionInput` +their resource lists, follow these same source rules. `CollectionInput` mounts one explicitly selected source at a collection destination and enables ConfigKit imports for that input; it does not discover or select sources. -A later profile or backend can change individual fields of a lower definition. +A later same-ID record replaces the lower definition in full. Use a distinct +inherited sibling when a variant should retain its parent's fields. A request `ProfileID` takes precedence over a prompt `default_profile`; if neither is selected, preparation fails. Exact profile inspection selects one explicit ID and does not consult a prompt default. -### Profile Inheritance +### Resource Inheritance -ConfigKit resolves `extends` on effective profile definitions. One profile -may inherit a sibling profile by local key in the same root or collection -mapping; collection inheritance cannot cross namespaces. Presence, explicit +ConfigKit resolves `extends: {id: parent}` for backends, profiles, and prompts. +Each child inherits a surviving sibling in the same root or collection list; +collection inheritance cannot cross namespaces. Parents are ordinary validated +resources, and profiles may remain partial until request completion. Presence, explicit null, and recursively merged maps determine the final fields. Other resource references are exact IDs and use their qualified form when they select a collection resource. There is no Promptkit-specific depth limit or second base-chain resolver. Missing references and cycles fail at construction. For generic inheritance and layer mechanics, consult -[ConfigKit](https://gitea.maximumdirect.net/eric/ConfigKit). +[ConfigKit](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.0.0/docs/config.md). ## Schemas diff --git a/docs/internal/observation.md b/docs/internal/observation.md index 5b218cb..072d197 100644 --- a/docs/internal/observation.md +++ b/docs/internal/observation.md @@ -25,8 +25,7 @@ other content. Events are values with no mutable containers. Callback panics propagate to the caller. Resolved prompt and profile IDs are the exact runtime identities selected for the invocation, including namespace qualification when supplied by an engine -view. A prompt's optional version label is descriptive metadata, not a -selection key. +view. Per-operation callbacks are ordered and synchronous; different operations may invoke the same callback concurrently. The recorder marks each measured phase's end before delivery, so callback work does not inflate provider duration. diff --git a/docs/internal/runner.md b/docs/internal/runner.md index 1245540..0e12629 100644 --- a/docs/internal/runner.md +++ b/docs/internal/runner.md @@ -36,8 +36,7 @@ The internal engine applies each namespace view to slashless caller selections before they reach the runner. The runner therefore selects captured prompts and profiles by the resulting exact runtime IDs. Already-qualified selections pass through, while configured defaults and stored references are used as authored -and are not requalified. Prompt version labels are returned as optional -descriptive metadata; they are not prompt selectors. +and are not requalified. Ordinary preparation selects the full prompt definition and construction-time hash. It retains its early request-ID check before direct-session diff --git a/docs/internal/sources.md b/docs/internal/sources.md index 74afaeb..6992670 100644 --- a/docs/internal/sources.md +++ b/docs/internal/sources.md @@ -12,8 +12,8 @@ source semantics. Internal packages are not consumer APIs. `internal/configuration` is the single adapter from ConfigKit's final effective configuration to execution-owned definitions. It performs one -layered load, captures effective presence (including explicit null), records -normalization and defaults through resolution, and validates all effective +layered load, captures effective presence (including explicit null), builds +detached normalized interpretations during validation, and validates all effective root and collection backend, profile, and prompt values. Replaced lower-layer domain values are not separately validated. It indexes root resources under their unqualified IDs and collection resources under their full @@ -27,22 +27,22 @@ do not depend on ConfigKit. ConfigKit owns source headers, imports, composition, and source evidence. Promptkit does not preparse contributions: it validates the final effective values once, captures the indexed identities and their original resource -contexts, and retains ConfigKit's result for explicit operator inspection. +contexts, and retains ConfigKit's composed result for explicit operator inspection. Accepted non-main source headers are consumed during composition; the main -source declaration remains available in that inspection view. Prompt and -collection release labels are descriptive metadata, not selection inputs. The +source declaration remains available in that inspection view. Collection +release labels are descriptive metadata, not selection inputs. The [format reference](../formats.md#source-headers-collections-and-resource-ids) owns the exact source-header and collection contracts. The `ConfigurationInspection.Diff` facade method compares two retained results through a private wrapper and a narrow `internal/configuration.Diff` bridge. The wrapper keeps `Result[document]` inside the adapter; the bridge delegates -once to ConfigKit v0.8.0 and returns its public difference records. Comparison +once to ConfigKit v1.0.0 and returns its public difference records. Comparison uses only frozen effective values and does not reopen sources, resolve runtime credentials, or enter the execution path. ConfigKit applies sensitivity from both results; reports may still contain ordinary application data. See the [consumer comparison guide](../consumers/pkg-promptkit.md#inspect-the-captured-configuration) -and ConfigKit's [v0.8.0 comparison contract](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.8.0/docs/config.md#effective-configuration-diffs). +and ConfigKit's [v1.0.0 comparison contract](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.0.0/docs/config.md#effective-configuration-diffs). After resource materialization and effective-profile snapshot construction, the adapter captures lexically ordered identity inventories for backends, profiles, @@ -85,10 +85,12 @@ returning and retains no source capability for public inspection. Prompt materialization shares a lazy metadata snapshot across root and collection resources during construction, avoiding a full metadata copy per collection. -Role and cache-control normalization is applied to execution-owned message -copies. ConfigKit v0.8.0 retains effective input message metadata and its -resource origins; recording a sequence-wide normalization in the retained -configuration would replace origins of unchanged content-file fields. +Normalization and defaults are applied to execution-owned interpretations, +including message roles and cache controls. ConfigKit retains the composed +values and origins, rather than synthetic Promptkit normalization events. List +indexes identify fields for presence, validation, sensitivity, and resource +context; full IDs select captured runtime indexes. Recording a sequence-wide +normalization would replace origins of unchanged content-file fields. The runner selects full definitions from this index for preparation and uses captured prompt metadata for `InspectPrompt` and `InspectRequirements`; the @@ -142,7 +144,7 @@ change rendering behavior. ## Profiles ConfigKit resolves profile inheritance before the handoff. Within a collection, -`extends` names a sibling local key; it is not a cross-collection reference. +`extends: {id: parent}` names a sibling local ID; it is not a cross-collection reference. The configuration adapter validates final effective resource references and field values, then builds target snapshots with backend defaults and presence/suppression state. A profile can diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 3c05dcc..084781b 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -833,6 +833,13 @@ documents whose descriptions changed. Validation: compare every current format example with the actual implemented schema and owning tests. Exact Go declarations remain the API contract owner. +Completion: the format reference now describes identified lists, header 2, +sibling inheritance, whole-record replacement, and collection labels. Internal +source, runner, and observation documentation now describe captured interpreted +values and unchanged ConfigKit provenance without prompt labels. Examples were +reviewed against the schema and passing loader/example tests; `git diff --check` +passed. + ## Stage 21: Document One Coherent Consumer Migration Scope: `docs/consumers/configuration-migration.md`, the Go consumer guide, README,