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: <ArtifactName>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