tegwick
8f54a5509e
11 KiB
RunManifestSchema
Prompt run tracking
RunManifestSchema v0.1
Purpose:
- Record a PromptRun end-to-end (TemplateAnalysis → ContextCompilation → PromptProcessing)
- Provide deterministic dependency tracking for incremental recompute (spreadsheet/build-system style)
- Support Generate-macros via nested PromptRuns
- Capture validation/quality outcomes and "impact debt" when recompute is suppressed (cycles/depth)
$schema: "https://markitect.dev/schemas/run-manifest/v0.1" # optional identifier schema_version: "0.1"
----------------------------
Top-level identity & timing
----------------------------
run_id: "uuid-or-content-address" # unique per run (uuid ok; content-addressed optional) run_type: "PromptRun" # reserved for future (e.g., ValidatorRun) created_at: "2026-02-08T19:12:34+01:00" # ISO8601, Europe/Berlin status: "succeeded" # enum: succeeded | failed | partial | skipped
----------------------------
Where this run happened
----------------------------
execution_context: engine: "MarkiTect" engine_version: "0.0.0" # semantic version or git hash workspace_id: "coulomb-social-workspace-id" # optional information_space_id: "space:my-topic" # the primary InformationSpace this run targets resolver_config_id: "resolver:default" # identifies PromptResolver ruleset used
----------------------------
Stage breakdown (conceptual)
----------------------------
stages:
- name: "TemplateAnalysis" started_at: "2026-02-08T19:12:34+01:00" ended_at: "2026-02-08T19:12:35+01:00" status: "succeeded"
- name: "ContextCompilation" started_at: "2026-02-08T19:12:35+01:00" ended_at: "2026-02-08T19:12:38+01:00" status: "succeeded"
- name: "PromptProcessing" started_at: "2026-02-08T19:12:38+01:00" ended_at: "2026-02-08T19:12:44+01:00" status: "succeeded"
----------------------------
Template used (the "formula")
----------------------------
template: prompt_template_name: "IllustratorPrompt" # name referenced by user/UI prompt_template_artifact: # resolved artifact for the template itself artifact_id: "artifact:IllustratorPrompt.md" # stable ID in MarkiTect information_space_id: "space:my-topic" # where it was found (local/default/etc) path: "prompts/IllustratorPrompt.md" # optional content_digest: "sha256:..." # digest of template content version_ref: "git:abc123" # optional, if versioned template_parameters: # runtime overrides (shadow resolver) # only include if used overrides: BrandBook: null # example; explicit override to null is allowed Audience: "IT Experts"
----------------------------
Macro graph extracted by TemplateAnalysis
----------------------------
content_macros:
- name: "Topic" kind: "Required" # enum: Required | Optional | Generate expected_artifact_name: "Topic" # or "TOPIC.md" depending on your naming expected_format: "markdown"
- name: "BrandBook" kind: "Generate" expected_artifact_name: "BrandBook" expected_format: "markdown" generator: selection_rule: "by-name" # enum: by-name | registry | explicit generator_template_name: "BrandBookGenerator" # convention: Generator output_artifacts: - "BrandBook"
----------------------------
PromptResolver decisions (what resolved from where)
----------------------------
resolution: resolution_order: - "local" - "explicit_includes" - "default" - "team" explicit_includes: # InformationSpaces included for this run (optional) - information_space_id: "space:default" alias: "default" - information_space_id: "space:team" alias: "team"
resolved_inputs: - macro: "Topic" kind: "Required" resolved: status: "found" # enum: found | missing_optional | generated | failed artifact_ref: artifact_id: "artifact:Topic.md" information_space_id: "space:my-topic" path: "Topic.md" content_digest: "sha256:..." - macro: "BrandBook" kind: "Generate" resolved: status: "generated" artifact_ref: artifact_id: "artifact:BrandBook.md" information_space_id: "space:my-topic" path: "BrandBook.md" content_digest: "sha256:..." generated_by_run_id: "run:uuid-of-generator-run"
missing: # filled when applicable required: [] # list of unresolved required macros optional: [] # list of unresolved optional macros
----------------------------
ContextCompilation outputs
----------------------------
compilation: compiled_prompt: compiled_prompt_id: "compiled:sha256:..." # optional content-address content_digest: "sha256:..." # digest of the compiled prompt text token_estimate: 4200 # optional assembly_plan: # Optional but useful for debugging: which artifacts got concatenated and how segments: - type: "template" artifact_id: "artifact:IllustratorPrompt.md" - type: "macro_injection" macro: "Topic" artifact_id: "artifact:Topic.md" - type: "macro_injection" macro: "BrandBook" artifact_id: "artifact:BrandBook.md"
input_bundle_hash: # Deterministic hash used for idempotent skipping/caching: # hash(template_digest + ordered dependency digests + resolver_config + model_settings + compilation_options) algorithm: "sha256" value: "sha256:..."
idempotency: cache_decision: "executed" # enum: executed | skipped_cache_hit | skipped_user cache_hit_run_id: null # if skipped_cache_hit, point to prior run
----------------------------
PromptProcessing (LLM execution)
----------------------------
llm: provider: "openai" # or "local" model: "gpt-5.2" # string settings: temperature: 0.4 top_p: 1.0 max_output_tokens: 1200 seed: 12345 # optional: if supported request: # optional: do NOT store raw prompt by default if privacy-sensitive; store hashes + refs instead compiled_prompt_digest: "sha256:..." response: output_digest: "sha256:..." # digest of raw model output finish_reason: "stop" # optional
----------------------------
Produced artifacts (writes to InformationSpace)
----------------------------
outputs: written_artifacts: - artifact_name: "IllustrationBrief" artifact_id: "artifact:IllustrationBrief.md" information_space_id: "space:my-topic" path: "IllustrationBrief.md" content_digest: "sha256:..." format: "markdown" role: "primary_output" # enum: primary_output | intermediate | log side_effects: # optional: e.g. triggered image generation job, created links, etc. - type: "image_request" ref: "image_gen:request_id" status: "queued" # or "completed" if synchronous in your system
----------------------------
Validation / QualityGates
----------------------------
validation: quality_gates: - gate_id: "schema:BrandBook.v0.1" target_artifact_id: "artifact:BrandBook.md" status: "passed" # enum: passed | failed | skipped details: errors: [] warnings: - code: "MISSING_SECTION" message: "Consider adding 'Color Palette' section." - gate_id: "schema:IllustrationBrief.v0.1" target_artifact_id: "artifact:IllustrationBrief.md" status: "passed" details: errors: [] warnings: []
metrics: # soft metrics snapshot used for marginal-gains halting policies - metric_id: "completeness.sections" target_artifact_id: "artifact:BrandBook.md" value: 0.86 scale: "0..1" - metric_id: "consistency.internal" target_artifact_id: "artifact:IllustrationBrief.md" value: 0.92 scale: "0..1"
policy: quality_policy_id: "policy:default-satisficing" halt_decision: "halted_quality_met" # enum: halted_quality_met | continue_refine | halted_budget | unknown iterations: current: 2 max: 5
----------------------------
Dependency recompute support (spreadsheet/build behavior)
----------------------------
dependencies:
Directed edges: output depends on inputs (resolved artifacts).
Used to build the global dependency graph.
edges: - dependent_artifact_id: "artifact:IllustrationBrief.md" depends_on_artifact_id: "artifact:Topic.md" depends_on_digest: "sha256:..." role: "macro:Topic" - dependent_artifact_id: "artifact:IllustrationBrief.md" depends_on_artifact_id: "artifact:BrandBook.md" depends_on_digest: "sha256:..." role: "macro:BrandBook" - dependent_artifact_id: "artifact:BrandBook.md" depends_on_artifact_id: "artifact:Topic.md" depends_on_digest: "sha256:..." role: "generator_input:Topic"
recompute: default_depth: 1 suppressed_recompute: # record when a dependent should be recomputed but was suppressed (cycle/depth) - dependent_artifact_id: "artifact:Topic.md" reason: "cycle_detected" would_trigger_from_artifact_id: "artifact:BrandBook.md"
----------------------------
Impact debt (changes ignored due to depth/cycle, with "gravity of change")
----------------------------
impact_debt: items: - dependent_artifact_id: "artifact:IllustrationBrief.md" upstream_artifact_id: "artifact:BrandBook.md" upstream_previous_digest: "sha256:old..." upstream_current_digest: "sha256:new..." suppression_reason: "depth_limit" gravity: method: "diff_ratio" # enum: diff_ratio | embedding_distance | llm_assessed score: 0.31 # normalized 0..1 label: "medium" # enum: none | low | medium | high recommendation: "recompute" # enum: ignore | recompute | recompute_and_revalidate noted_at: "2026-02-08T19:12:45+01:00"
----------------------------
Nested runs (for Generate macros, validators, fixers)
----------------------------
subruns:
You can inline summaries here, or store subruns as separate manifests and link by id
- run_id: "run:uuid-of-generator-run"
relation: "generated_macro:BrandBook"
status: "succeeded"
produced_artifacts:
- "artifact:BrandBook.md"
----------------------------
Diagnostics
----------------------------
errors:
present if status failed/partial
- code: "MISSING_REQUIRED_MACRO" message: "Required macro 'Topic' could not be resolved." stage: "ContextCompilation" details: macro: "Topic"
warnings:
- code: "OPTIONAL_MISSING" message: "Optional macro 'Examples' was not found; continuing with empty." stage: "ContextCompilation" details: macro: "Examples"
xxx