ENGINE_CONTRACT.md

Engine Contract (v1)

Summary

The engine guarantees: validation against the canonical DSL, deterministic generation (when configured), and auditable artifact emission for self-host runs.

Entry points

Function	Location	Notes
run_self_host(spec_file, schema_path)	src/shieldcraft/main.py	Primary path. Used by learning trial + fuzz suite. Bypasses sync gate.
Engine.run_self_host(spec)	src/shieldcraft/engine.py	Class-method path. Blocked by sync gate unless SHIELDCRAFT_SELFBUILD_ALLOW_DIRTY=1.

Responsibilities

• Validate input specs against spec/schemas/se_dsl_v1.schema.json before building ASTs.
• Emit deterministic artifacts (checklist_draft.json, manifest.json) when determinism is configured in the spec.
• Respect opt-in enforcement flags (e.g., TAC via SHIELDCRAFT_ENFORCE_TEST_ATTACHMENT).

Failure semantics

• Determinism violations are CI-blocking unless explicitly allowlisted in governance contracts.
• Validation failures surface as schema_error with a clear error payload.
• Sync gate failures surface as RuntimeError: sync_not_performed.

Observability and audit

• The engine writes determinism snapshots and emits readiness state for external monitoring.
• Forensic bundles are produced for self-build mismatches.
• All artifact paths are documented in docs/SE_STATE.md.