Policy Service Package Design

This document defines architecture boundaries for the policy service package at src/mud_server/services/policy/.

Goals

  1. Keep canonical policy operations DB/artifact-first.

  2. Keep mud_server.services.policy_service as a stable facade for canonical callers.

  3. Remove legacy world-file import/read pathways from runtime and service surfaces.

Canonical Invariants

  1. Canonical policy identity is represented by policy object fields and stored in SQLite.

  2. Activation (policy_activation) and variant status (policy_variant.status) are distinct concerns.

  3. Runtime effective policy resolution is computed from activation mappings, not file paths.

  4. Publish artifacts are deterministic exchange outputs, not runtime authority.

  5. Artifact import is idempotent at policy identity + variant granularity.

Package Modules

types.py

Defines shared typed structures used across policy modules, including: ActivationScope, EffectiveAxisBundle, and EffectiveImagePolicyBundle.

errors.py

Defines canonical policy service exceptions consumed by facade and route layers.

constants.py

Defines canonical constants used by policy validation and import/publish paths.

utils.py

Implements normalization and shared utility helpers used across modules.

hashing.py

Owns deterministic content hashing helpers used by upsert and publish flows.

validation.py

Owns policy content validation and policy-type specific rules.

activation.py

Owns activation writes, activation listing, and effective activation overlays.

runtime_resolution.py

Owns runtime effective resolution for policy variants, prompt templates, axis bundles, and image-policy diagnostic bundles.

publish.py

Owns deterministic publish runs and manifest generation.

artifact_import.py

Owns canonical artifact ingestion into policy tables.

paths.py

Owns policy export root resolution used by artifact bootstrap/import flows.

Facade Contract

src/mud_server/services/policy_service.py provides compatibility wrappers for canonical APIs.

Supported canonical facade exports:

  • list_policies

  • get_policy

  • get_policy_capabilities

  • validate_policy_variant

  • upsert_policy_variant

  • set_policy_activation

  • list_policy_activations

  • resolve_effective_policy_activations

  • get_effective_policy_variant

  • resolve_effective_prompt_template

  • resolve_effective_axis_bundle

  • resolve_effective_image_policy_bundle

  • publish_scope

  • get_publish_run

  • import_published_artifact

  • parse_scope

Compatibility aliases are also preserved for existing callers:

  • config

  • policy_repo

  • PolicyServiceError

Removed legacy exports are intentionally absent.

Legacy Removal Scope

Removed from service/CLI surface:

  1. Legacy world-policy file import entry points.

  2. Legacy path-to-policy mapping helpers.

  3. Legacy runtime fallback assumptions that imply file-path canonicality.

Testing Expectations

  1. Unit coverage for validation, activation overlays, runtime resolution, publish, and artifact import.

  2. Integration coverage for policy API routes and retained CLI commands.

  3. Regression coverage proving DB/runtime behavior does not depend on legacy world policy files.