From abecb349e4932235d0d9fe45a2ad1e3d19ee55f6 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Wed, 18 Nov 2026 19:04:45 +0000 Subject: [PATCH] Record agreement on native prompt assembly and deferred schema decisions --- .../promptkit-architecture-discussion.md | 55 +++++++++++-------- 1 file changed, 32 insertions(+), 23 deletions(-) diff --git a/docs/roadmap/promptkit-architecture-discussion.md b/docs/roadmap/promptkit-architecture-discussion.md index 08e559e5..14b486b4 100644 --- a/docs/roadmap/promptkit-architecture-discussion.md +++ b/docs/roadmap/promptkit-architecture-discussion.md @@ -5,8 +5,9 @@ Working notepad for reviewing the ownership boundaries in the [PromptKit v0.23.2 adoption roadmap](promptkit.md). Work through the topics below in order, recording questions, evidence, decisions, and follow-up work. -Item 1 records the selected architectural direction; its detailed design and -the remaining topics are still under discussion. +Items 1 and 2 record selected architectural directions. Detailed design, +read-only filesystem and schema decisions, and the remaining topics are still +under discussion. The Audita comparison is a seventh topic and may inform earlier decisions. The goal is to make Notarius fully PromptKit-native and adopt modern PromptKit @@ -76,29 +77,29 @@ the change lands. Do not treat the remaining topics as decided by this direction ## 2. Prompt Assets And Schema Assembly -**Proposed design:** Keep the embedded content tree and load its prompt and +**Discussion / decision:** Direction agreed: use native PromptKit declarations +as the sole prompt assembly mechanism and remove the duplicate application +assembly plumbing. Resolution of the custom read-only filesystem and schemas +is explicitly deferred; the next topic may clarify those choices. + +**Selected direction:** Keep the embedded content tree and load its prompt and profile definitions as native PromptKit configuration in the application collection. Use native filesystem contexts and imports to reference shared -content directly. Supply the embedded filesystem as the schema root, with -distinct schema paths selected by native output contracts. Application -composition assembles the embedded and operator sources once; modules select -prompt IDs, supply domain inputs, and interpret typed results. +content directly. Application composition assembles the embedded and operator +sources once; modules select prompt IDs, supply domain inputs, and interpret +typed results. The spell extractor illustrates the current duplication: its prompt YAML declares ordered messages and a schema, while a separate Go asset manifest lists files, mounts shared fragments, registers filesystems, and hashes them. -The proposed design makes native declarations the sole prompt assembly source. +The selected direction makes native declarations the sole prompt assembly source. Candidates for removal: -- `AssetRegistry` and per-module prompt, schema, and fallback-profile - registration plumbing. +- Prompt and fallback-profile registration plumbing in `AssetRegistry` and + individual modules; schema responsibilities remain under review. - `ModulePromptFS`, `PromptAssetManifest`, shared-name lookup tables, synthetic - `sharedassets` mounts, and the custom read-only filesystem if no uses remain. -- Private response-schema wrappers whose only jobs are reading JSON, duplicating - schema metadata, and computing a digest. PromptKit owns loading and compiling - the selected model-response schema; Go response types and application checks - remain with their consumers. + `sharedassets` mounts. - Manual prompt-file enumeration for fingerprints, replaced by captured native prompt identities subject to the broader identity design in item 5. @@ -113,7 +114,16 @@ not establish schema equality. Existing schema metadata in manifests and checkpoint inputs must be deliberately replaced or retired; its presence does not require preserving the complete wrapper system. -Questions: +Deferred decisions: + +- Whether the custom read-only filesystem can be removed after reviewing its + remaining responsibilities. +- Schema assembly, root/path selection, wrapper removal, and schema metadata. + Supplying the embedded filesystem as a native schema root remains a candidate, + not a selected design. +- How schema identity contributes to manifests and checkpoint reuse. + +Implementation questions: - Can native sources represent the existing shared fragments and module assets? - Which registry, remounting, and hashing helpers could disappear? @@ -121,13 +131,12 @@ Questions: - How do we preserve message ordering and cache controls while simplifying assembly? -**Discussion / decision:** Pending. - -**Follow-up:** Confirm native source contexts for shared fragments, schema -root/path selection, and operator replacements. Resolve metadata and reuse -identity with items 5–6. Verify the resulting definitions through native -preparation and fake-provider execution; filesystem remounting tests can retire -with the removed implementation. This is a proposal, not an implemented change. +**Follow-up:** Continue with item 3, then revisit the deferred filesystem and +schema decisions with any new clarity. Confirm native source contexts for shared +fragments and operator replacements. Resolve metadata and reuse identity with +items 5–6. Verify the resulting definitions through native preparation and +fake-provider execution; filesystem remounting tests can retire with the removed +implementation. The agreed direction has not yet been implemented. ## 3. Retry And Semantic Correction Ownership