tegwick
6af04024d5
6.9 KiB
FunctionalRequirementSpecification
PromptDependencyResolution for MarkiTect
Functional Requirements Specification (FRS)
MarkiTect Extension: PromptDependencyResolution Infrastructure
1. System Definition
The system shall provide infrastructure within MarkiTect to support structured execution of PromptTemplates using deterministic PromptDependencyResolution across InformationSpaces.
The system shall enable:
- Resolution of ContentMacros (Required, Optional, Generate)
- Deterministic context compilation
- Controlled PromptRun execution
- Nested Generator runs
- Idempotent execution via InputBundleHash
- Dependency graph construction
- Incremental recomputation with depth control
- RunManifest persistence and inspection
- QualityGate validation and impact tracking
2. Functional Scope
The system shall operate within a MarkiTect workspace and extend existing InformationSpace capabilities to support executable knowledge artifacts.
The system shall not prescribe:
- LLM provider implementation
- UI layout specifics
- Storage backend architecture
- Internal algorithm selection
3. Functional Requirements
FR-1: InformationSpace Addressability
FR-1.1 The system shall allow content artifacts within an InformationSpace to be uniquely addressable by name and persistent identifier.
FR-1.2 The system shall compute and store a content digest for each artifact upon modification.
FR-1.3 The system shall allow referencing artifacts across multiple InformationSpaces.
FR-2: PromptTemplate Definition
FR-2.1 The system shall allow defining a PromptTemplate as a content artifact containing ContentMacros.
FR-2.2 The system shall detect and extract ContentMacros during TemplateAnalysis.
FR-2.3 The system shall support the following ContentMacro kinds:
- Required
- Optional
- Generate
FR-3: PromptResolver Behavior
FR-3.1 The system shall resolve ContentMacros in a deterministic resolution order:
- Local InformationSpace
- Explicitly included InformationSpaces
- Default InformationSpace
- Team/Shared InformationSpace (if configured)
FR-3.2 The system shall mark unresolved Required macros as failure conditions.
FR-3.3 The system shall allow Optional macros to resolve to empty without failure.
FR-3.4 The system shall, for Generate macros:
- Identify a corresponding Generator PromptTemplate
- Initiate a nested PromptRun
- Persist generated artifact(s)
- Resume original resolution
FR-3.5 The system shall enforce a configurable maximum generation depth.
FR-4: PromptRun Lifecycle
FR-4.1 The system shall support PromptRun execution stages:
- TemplateAnalysis
- ContextCompilation
- PromptProcessing
FR-4.2 The system shall produce a CompiledPrompt during ContextCompilation.
FR-4.3 The system shall calculate an InputBundleHash consisting of:
- Template digest
- Ordered dependency digests
- Resolver configuration identifier
- Model settings
- Compilation options
FR-4.4 The system shall skip execution if a prior successful PromptRun with identical InputBundleHash exists, unless explicitly overridden.
FR-5: RunManifest Persistence
FR-5.1 The system shall persist a RunManifest for each PromptRun.
FR-5.2 The RunManifest shall include:
- Template metadata
- Resolved inputs and their digests
- CompiledPrompt digest
- Model configuration
- Output artifacts and digests
- Dependency edges
- Validation results
- Impact debt records (if applicable)
FR-5.3 The system shall link nested Generator runs to parent PromptRuns.
FR-6: Dependency Graph Construction
FR-6.1 The system shall record directed dependency edges between produced artifacts and their input artifacts.
FR-6.2 The system shall construct a dependency graph across InformationSpaces.
FR-6.3 The system shall detect circular dependencies.
FR-7: Incremental Recompute
FR-7.1 When an artifact is modified, the system shall identify dependent artifacts via the dependency graph.
FR-7.2 By default, the system shall recompute direct dependents only (depth = 1).
FR-7.3 If recomputation would create a circular dependency or exceed depth limits, the system shall suppress further recompute.
FR-7.4 The system shall record suppressed recomputations in the RunManifest.
FR-8: Change Impact Assessment
FR-8.1 The system shall calculate a change magnitude metric when an upstream artifact changes.
FR-8.2 The system shall support configurable methods for change magnitude calculation:
- Structural diff ratio
- Content diff ratio
- Embedding distance (optional)
- LLM-assessed impact (optional)
FR-8.3 The system shall record impact assessments as ImpactDebt entries in the RunManifest when recomputation is suppressed.
FR-9: QualityGate Validation
FR-9.1 The system shall support schema validation against generated artifacts.
FR-9.2 The system shall allow multiple QualityGates per artifact.
FR-9.3 The system shall record pass/fail results and validation diagnostics in the RunManifest.
FR-9.4 The system shall support halting policies based on QualityGate results.
FR-10: Halting and Refinement Policy
FR-10.1 The system shall support configurable QualityPolicies.
FR-10.2 The system shall evaluate halting decisions based on:
- QualityGate results
- Marginal improvement metrics
- Iteration limits
- Resource budgets (e.g., number of runs)
FR-10.3 The system shall record halting decisions in the RunManifest.
FR-11: Traceability and Auditability
FR-11.1 The system shall enable traceability from any artifact to:
- Producing PromptTemplate
- Input artifacts
- Generator runs
- Quality validation results
FR-11.2 The system shall enable recomputation based on changes in any dependency.
4. Out of Scope
The following are explicitly excluded from this FRS:
- User interface design and layout
- Internal storage architecture
- LLM provider selection
- Model training or fine-tuning
- Visualization tooling
- Economic or incentive mechanisms
5. Acceptance Criteria
The system shall be considered compliant when:
- A PromptTemplate referencing Required, Optional, and Generate macros can be executed.
- Missing Generate dependencies are automatically generated and persisted.
- Re-running an unchanged PromptRun with identical InputBundleHash results in a skipped execution.
- Changing an upstream artifact triggers recomputation of direct dependents.
- Circular recomputation is suppressed and logged.
- RunManifest contains complete provenance and dependency information.
- Schema validation failures are correctly recorded and influence halting policy.
6. Architectural Positioning
This infrastructure operates:
- Above artifact storage
- Below UI interaction layers
- Orthogonal to LLM provider implementation
- As an execution engine inside MarkiTect
It provides the functional backbone required for executable InformationSpaces within Coulomb Social.
xxx