PGS Field Manual

Status: Public Reference Artifact — v0 · Baseline: PGS v0.5.0

Canonical Repository: bachipeachy/pgs_workspace

Audience: Architects · Compiler Engineers · Runtime Engineers · Governance Engineers · AI Coding Agents

What This Manual Is

This is a high-density architectural restoration artifact. Its purpose is to restore the correct architectural mental model of Protocol-Governed Systems in under 30 minutes — not to teach, not to document implementation, not to walk code.

Intended for: system architects, compiler engineers, runtime engineers, governance engineers, AI coding agents operating under human supervision, security reviewers, technical maintainers.

Not a tutorial. Assumes PGS familiarity. Source code, constitutions, invariants, and protocol artifacts remain authoritative. This manual restores the mental model needed to read them correctly.

AI coding agent operating constraint. PGS contains constraints that general-purpose coding agents violate unintentionally. Without architectural restoration, agents tend to introduce convenience abstractions, collapse governance boundaries, embed domain logic into runtime layers, add fallback behavior, and weaken determinism. The nine constraints below are non-negotiable before any substantial modification:

no fallback logic          no runtime discovery       no dynamic imports
no heuristic resolution    no ambient authority       no runtime topology synthesis
no short-name artifacts    compile-time governance    strict layer separation

Architectural reading rule. When ambiguity exists — governance overrides implementation convenience. This single rule resolves most architectural decisions correctly.

PGS is not: workflow orchestration with governance wrappers · a policy engine · a runtime authorization framework · a service mesh · a BPM engine.

PGS is: compile-time admissible execution construction.

PGS In One Page

Protocol
    ↓
Compiler
    ↓
Snapshot
    ↓
Runtime
    ↓
Trace

Three invariants that follow directly:

The runtime does not decide what may exist. The compiler already decided. The runtime does not interpret behavior. The protocol already declared it. The compiler does not execute. The runtime executes only what the compiler sealed.

The mantra:

Governance defines. Compiler constructs. Snapshot seals. Runtime executes. Trace proves.

The nine execution concerns:

Manual reading map:

                      FIELD MANUAL

                            │
                            ▼

                    PGS IN ONE PAGE
                            │
                            ▼

                   EXECUTIVE DOCTRINE
                            │
                            ▼

                      CORE DOCTRINE
                            │
                            ▼

                 ARCHITECTURAL ONTOLOGY
                            │
                            ▼

                   GOVERNANCE MODEL
                            │
                            ▼

                   AUTHORING MODEL
                            │
                            ▼

           ┌────────────────┼────────────────┐
           ▼                ▼                ▼

       COMPILER          RUNTIME         EXECUTION
        MODEL             MODEL            MODEL

           └────────────────┼────────────────┘
                            ▼

              ARCHITECTURAL PROPERTIES
                            │
                            ▼

                 TRANSPORT GOVERNANCE
                            │
                            ▼

                FEDERATED GOVERNANCE
                            │
                            ▼

                    ANTI-PATTERNS
                            │
                            ▼

                 ARCHITECTURE EVOLUTION
                            │
                            ▼

                        APPENDICES

0. Executive Doctrine

One-line summary: Behavior is a compiled artifact of protocol declarations — not an emergent property of implementation code.

1. Core Doctrine

1.1 Protocol is the Source of Truth

• Behavior identity is carried by protocol artifacts, not code
• Business logic is encoded in protocol artifacts, not in implementation code
• Code may be regenerated, replaced, or machine-authored; governance remains stable
• Behavioral authority persists independently of implementation lifecycle

1.2 Runtime Dumbness (Semantic-Agnostic Execution)

• The runtime enforces graph structure — it does not interpret domain meaning
• Same execution engine runs blockchain, AI governance, and collatz conjecture identically
• No domain logic is permitted in the runtime layer

1.3 Compile-Time Resolution

• Execution graphs are constructed before any runtime begins
• Behavioral admissibility is determined at compile time, not runtime
• If the compiler does not construct the path, the implementation cannot traverse it

1.4 Zero Inference

• No implicit defaults, no heuristics, no filesystem scanning
• All artifact locations must be declared explicitly
• No ../ traversal, no cwd(), no environment sniffing

1.5 Fail Hard

• Missing artifact → hard failure, not silent skip
• Constraint violation → reject, not log-and-continue
• No graceful degradation that masks architectural violations

1.6 Deterministic Execution

• Execution is a pure function: Φ(G, input, actor_context) → (result, trace)
• Replay is structural, not reconstructed

1.7 Governance Before Execution

• Constitutions define what is admissible
• Compiler validates — only conformant behavior enters the snapshot
• Runtime enforces — only snapshot behavior executes

1.8 No Ambient Authority

• Code has no inherent authority derived from its execution context
• All authority originates exclusively from protocol declarations: (AC, IN, WF, CC)
• An operation has exactly the authority declared in its artifacts — no more
• Confused deputy attacks are structurally eliminated, not defended against

1.9 Snapshot Sovereignty

• Runtime executes compiled snapshot state exclusively
• Snapshot is immutable during execution — no live modification
• Runtime behavior cannot diverge from compiled admissibility state
• To change behavior: change protocol source → recompile → rebuild snapshot

1.10 Architectural Compression

• PGS intentionally compresses architecture into a small number of explicit executable concerns
• A smaller ontology with stronger invariants is preferred over a larger ontology with heuristic flexibility
• This reduces governance ambiguity, hidden behavioral surfaces, cognitive reconstruction cost, and AI-agent violation probability
• The closed set of nine execution concerns and five governance surfaces is a feature, not a limitation
• Expanding ontology size without governance necessity is treated as architectural debt

2. Architectural Ontology

2.1 The Nine Execution Concerns

Orthogonal Resolution:

2.2 Governance Constructs

Version immutability: Versions are immutable. There is no “latest.” A change to behavior requires a new version number (_V1, _V2, etc.) — the old version remains valid and unchanged in the snapshot.

2.3 Governance Surfaces

PGS has five orthogonal governance surfaces. Each governs a distinct concern. They evolve independently — adding governance sophistication to one surface does not couple to any other. New governance surfaces may be added as long as the separation-of-concerns principle is not violated by design.

Key invariant: Governance surfaces are orthogonal planes. Topology governs traversal structure only. Authority governs eligibility only. Neither governs the other. Execution is semantically blind to both.

2.4 Artifact Code Prefixes

3. Governance Model

3.1 Constitutions

• Each artifact family governed by a constitution
• Constitution declares invariants that all artifacts of that type must satisfy
• Violation → compiler rejects the artifact; it never enters the snapshot

3.2 Invariants

• Structural laws applied at compile time
• Examples: FQDN identity required, no undeclared outcomes, no missing bindings
• Invariants are not advisory — violations are hard failures

3.3 Assertions

• Specific checks instantiated from invariants
• Registered in handler registry; resolved at compile time
• Static imports only — no dynamic loading of assertion handlers

3.4 Protocol Surface Closure (Vocabulary Closure Invariant)

• Executable Behavior ⊆ Expressible in V (the declared concern vocabulary)
• Behavior not expressible in V cannot pass governance, cannot enter snapshot, cannot execute
• This is a construction-time property, not a runtime guard

3.5 Governance Dividend

Named Property: As governance surface matures, cost-of-change decreases rather than increases.

• Conventional: low initial governance cost → debt accumulates → per-change cost grows unboundedly
• PGS: higher initial governance cost → debt does not accumulate → per-change cost remains stable
• Complexity: O(N + M) vs conventional O(N × M) where N = capabilities, M = workflows
• Attack surface: |CS_| + |AC_| + |RB_| — finite and enumerable

PGS separates implementation authorship from behavioral admissibility. Behavioral admissibility remains compiler-governed regardless of whether implementation is human-authored or machine-authored. AI may generate implementation, transforms, and workflow proposals — but AI does not define admissibility. Governance defines admissibility. Compiler constructs it. Runtime enforces it. Trace proves it.

3.6 Federation Boundaries

The governance registry is organized into federation boundaries — named semantic governance authorities, not filesystem folders.

Current boundary inventory:

FQDN namespace: All governance artifacts use fb.<boundary_lower>::ARTIFACT_CODE format.

fb.constitution::CONSTITUTION_FEDERATION_BOUNDARY_V0
fb.topology::CONSTITUTION_EXECUTION_TOPOLOGY_V0
fb.constitution::STRUCTURE_BUILD_PLATFORM_CONFIG_V0

Sovereignty model: Exactly one sovereign boundary (FB_CONSTITUTION). All others are delegated. A second sovereign boundary is a constitutional violation.

Governance locality doctrine: A governance artifact belongs in pgs_governance (central) if and only if it governs all PGS systems universally. Domain-specific governance law belongs in the domain repository.

Anti-sprawl rule: Federation boundaries must not be created to mirror organizational structure, repository topology, or implementation convenience. A boundary exists only when a distinct semantic governance authority exists.

Authoritative doctrine artifact: fb.constitution::CONSTITUTION_FEDERATION_BOUNDARY_V0

4. Authoring Model — Governed Evolution (Change Management)

One-line summary: Evolution is itself a governed protocol concern — every protocol change travels a staged pipeline from Change Request to Authoring Mandate, leaving a complete evidence chain (the dossier).

Governing boundary: FB_CHANGE_MGMT (delegated, in pgs_governance/registry/). Implementation: pgs_change_mgmt repo — stage templates in change_mgmt/templates/, dossiers in change_mgmt/dossiers/<domain>/<subdomain>/.

The closing of the loop: PGS governs construction (compiler) and execution (runtime). The change pipeline governs change itself. If the Protocol Snapshot does not change, the system is invariant by definition — the pipeline is complete only when a new snapshot is compiled, attested, and valid.

4.1 The Pipeline (one CR = one dossier)

Discovery Saturation (Stage 3 stop condition) — all three simultaneously: no unresolved CRITICAL gaps · no open analyst questions · no dependency expansion in the last pass.

4.2 Purity Ladder

Each stage admits exactly one more vocabulary class. Exception at every rung: artifacts that already exist in the baseline may be cited by exact FQDN as evidence — citing the baseline is observation, not design.

Stages 1–4   business language only (nothing new gets a code)
Stage 5      + provisional capability names (IN/WF/CC vocabulary, unbound)
Stage 6      + placement (WHERE) — still no new codes
Stage 6b     + binding FQDNs, topology, schemas, stores
Stage 7      + build order

4.3 Elicitation Contract + Stage Execution Rules

Every stage template opens with questions for the human, each paired with declared intent (how the answer will be used). Unanswered question = open gap, never license to assume. The human supplies governed knowledge; the agent structures, verifies, and projects it.

Every stage carries execution rules — accumulated failure knowledge folded back from completed CRs:

4.4 Canonical Documentation Set (the change agent’s oracle)

Complete, implementation-free context for any change agent — human or automated:

1. Protocol Snapshot   what the system currently does (runtime-executable)
2. PPS Snapshot        full compiled inventory (pps_snapshot/index.json) — check before authoring
3. Field Manual        this document — operational doctrine
4. Concept Papers      architectural rationale (why)
+ the dossier built so far

Agent context is declared in pgs_change_mgmt/change_mgmt/templates/0_agent_context_template_v0.md — the reading assignment loaded at CR start alongside 1_change_request_template_v0.md; extend awareness by adding rows, not code.

4.5 Governance Dividend in Practice

Each cycle’s manifest carries methodology lessons forward into the stage templates. Templates are the accumulation vehicle: every future CR (and agent) inherits prior failures as enforced rules, not folklore. Seven CRs executed to date (consensus_pos · block · data_model · consensus_propose · mempool · orchestration · chain) — the conceptual model is documented in the change-management concept paper (fifth in the series).

5. Compiler Model

5.1 Pipeline Stages (in order)

5.2 Compiler Constraints (Non-Negotiable)

• No execution during compilation — compiler never runs CT/CS implementations
• Static imports only — no dynamic module loading
• Deterministic output — same source → same snapshot, always
• No cross-artifact inference — each artifact is validated against its own schema + invariants
• Handler registry must be fully populated before compile starts
• Compiler validates and rejects — it never repairs malformed protocol state

5.3 Two Phase Types

Phase Type B is governed by an aggregation STRUCTURE_ artifact with an aggregation_type field. The CLI routes on this field to the appropriate aggregation runner.

Phase Type B invariants — non-negotiable:

• Deterministic, declarative, bounded, structure-declared
• No implicit dependency ordering between structures
• All contributing source dirs declared explicitly in artifact_source_dirs
• Must run after all contributing Phase Type A builds complete

Current Phase Type B families:

5.4 Compiler Evidence Graph

The compiler emits evidence_graph.json per structure during S7. This is the compiler’s governed observability artifact — a semantic causality graph over all S1–S7 trace events, analogous in role to the execution trace for the runtime.

Formal guarantees:

Location: evidence_snapshot/<domain>/evidence_graph.json — written by S7, verified by S8.

Contract freeze: The EvidenceQuery public surface is a protocol surface, not a utility library. Additions require explicit versioning. No compiler-internal fields may be exposed.

5.5 Protocol Inspection (pi)

Compilation answers is this protocol admissible? Inspection answers what does this protocol mean? pi (Protocol Inspection command processor, in pgs_compiler, v0.6.0+) is the read-only query surface over the compiled snapshot set — the relationship-navigation tool that replaces grepping markdown and mentally reconstructing dependency graphs the compiler has already built and verified.

Governing principle (V0): pi answers questions. The compiler performs changes. The runtime performs execution. No mutation verb exists in the taxonomy, the CLI, or the library — including caches. Because inspection answers come from the same verified projections the runtime consumes, a pi result carries snapshot authority and is admissible as dossier evidence (Stage 3 impact analysis cites pi topology impact --json directly).

One core, three surfaces: the inspection library (pgs_compiler.inspection: loader → resolver → traversal) is the core; the terminal CLI/shell and the --json output (stable schema, for agents and CI) are its projections. All three return the same answer by construction.

Query sources (all compiler-materialized): protocol_snapshot/artifact_index/ (index.json — FQDN → domain/structure/kind/paths/addresses; stores.json — entity-store ownership join), per-scope evidence.json (the artifact-level semantic graph: NODE_NEXT, WF_CONTAINS_NODE, CC_BINDS_CT/CS, WF_BINDS_RB, RB_MAPS, GOVERNED_BY edges), vocabulary_snapshot/, pps_snapshot/index.json, protocol_snapshot/behavior_logic/<WF>/*.graph.json, and conformance_results.json. Both index projections enter the workspace only via pgs_compiler.cli build — never hand-placed.

Command taxonomy: pi <object> <verb> [target] over objects artifact, wf|cc|ct|cs|rb|in|ev|ac, topology, behavior_logic, store, vocab, pps, snapshot, trace, plus top-level validate (CI gate: --strict exits non-zero unless VALID with zero violations) and stats. Bare pi opens the interactive shell. Full command set: doc/pgs_cli_cheatsheet.txt.

6. Runtime Model

6.1 Runtime Constraints (Non-Negotiable)

• Snapshot-only: runtime reads protocol_snapshot/ exclusively; never touches protocol source
• No discovery: artifact locations come from the snapshot manifest, not filesystem scanning
• No inference: missing binding → hard failure; no fallback implementations
• No domain logic: runtime is semantically blind to what it executes
• Deterministic traversal: graph edges are followed exactly as declared

6.2 Runtime Bindings

• RB_ maps protocol capability declarations to concrete implementations
• Both CT_ and CS_ resolved via the same binding mechanism
• RB_ resolves implementation location only — behavioral authority originates exclusively from protocol declarations

6.3 Trace Lifecycle

execution start → trace file created at traces/<domain>/<subdomain>/<TRACE_ID>/<TRACE_ID>.jsonl
each CC node   → structured event appended
execution end  → trace sealed; .md summary + .png visualization written

Trace files are OUTPUT only. Never use as input to compiler, runtime, or other components. Trace IDs are deterministic — same inputs produce the same trace ID. Exit codes: 0 for completed execution (including NACK/VIOLATION), 1 for infrastructure failures.

6.4 CS Substrate Inventory

All CS_ artifacts live in the capability_side_effects domain (owned by pgs_capabilities). The side-effect surface is finite and enumerable — this is the entire mutation/IO vocabulary:

7. Execution Model

7.1 Governed Execution Topology

PGS execution is governed declarative graph traversal, not workflow orchestration. The execution topology is a compile-time governed graph — fully declared before runtime begins, immutable during execution.

TI → IN (admission check)
   → WF (governed topology traversal)
     → CC_1 → CT/CS → outcome (SUCCESS | VIOLATION | ALREADY_EXISTS | ...)
     → CC_2 (inputs resolved via JSONPath: $.results.<CC_CODE>.<field>)
     → ...
   → TE (boundary projection)

• Topology is a DAG — no cycles, deterministic termination
• All step sequences declared at compile time — runtime is a traversal engine, not an orchestrator
• Outcomes declared in WF_ route traversal — no runtime branching logic
• Runtime receives a fully closed topology graph; it does not discover, repair, or extend it

Workflow composition rules:

• WF nodes are IN, CC, and EXIT/EXIT_SUCCESS only — a workflow NEVER appears as a node inside another workflow
• Sub-workflow invocation is a gateway CC (CC_INVOKE_* bound to CS_WORKFLOW_GATEWAY_V0); iteration and parallelism use CS_WORKFLOW_LOOP_V0 / CS_CONCURRENT_WORKFLOWS_V0
• EV_ records facts; it never triggers execution — there is no event subscription in the runtime; workflow chaining is always a declared gateway step
• A store is written only by CCs of its owning subdomain — cross-subdomain reads/calls are permitted and declared; cross-subdomain writes are forbidden without exception

7.2 CT Purity Invariant

• Effect(CT) = ∅ — transforms have zero side effects
• CT may call other CTs; may never call CS
• CT correctness is the implementation’s responsibility; PGS constrains invocation, not logic

7.3 CS Side Effect Boundary

• CS is the only authorized channel for external state mutation
• MutationSurface = { s : s ∈ CS_ }
• No implicit write path exists anywhere else in the system

7.4 Trace as Evidence

• Every node execution emits a structured trace event: artifact identity, inputs, outputs, outcome
• Trace is append-only, immutable once written
• “If an action does not appear in the trace, it is architecturally prohibited”
• Replay is deterministic: same trace → same proof

7.5 Ownership Boundaries

7.6 System Boundary Model

External System
      ↓
   TI_  (admission boundary — input normalization only)
      ↓
Execution Graph G  (all admissible execution semantics live here)
      ↓
   TE_  (projection boundary — output rendering only)
      ↓
External System

TI_ and TE_ are orthogonal boundary concerns — they do not participate in workflow authority or execution orchestration.

7.7 Execution Topology Governance

Doctrine: Execution topology governs traversal structure only.

Canonical surface governance: Every step’s result_surface must exactly match the canonical_surface declared by the governing SURFACE_CONTRACT. Workflow authors MAY route surfaces. Workflow authors MAY NOT define capability semantics.

Topology invariant families (compile-time enforced):

• Step identity uniqueness · Capability reference uniqueness · Input reference closure
• Routing completeness · Contract closure · Authority orthogonality
• Transport orthogonality · Surface canonicality

8. Architectural Properties

The PGS architecture produces eleven named properties. These are not design goals — they are structural outcomes that follow directly from the Governance → Compiler → Runtime separation. Each is derived in full in the technical paper trilogy.

The compiler governs possibility. The runtime governs realization. The separation between them is where Protocol-Governed Systems become governable.

9. Transport Governance

9.1 TI / TE Doctrine

• TI (Transport Ingress): Normalizes and validates all external input → canonical internal representation. No business logic.
• TE (Transport Egress): Renders internal results for external systems. Boundary projection only. Does not participate in execution semantics.
• Closed-loop invariant: all behavior follows TI → G → TE

9.2 Transport Orthogonality

• Transport substrate (CLI, HTTP, queue, agent) is orthogonal to execution semantics
• Changing from CLI to HTTP does not change the execution graph
• No routing logic in TI/TE — routing lives in WF_ declarations

9.3 Transport Does Not Route

• Transport artifacts normalize and project data only
• Transport may not perform execution routing, orchestration, or behavioral selection
• All routing lives in WF_ DAG outcome edges — never in TI/TE middleware

9.4 Snapshot-Driven Route Loading

• Routes loaded from snapshot; no hardcoded route tables
• Route = (domain, workflow) pair declared in snapshot
• No middleware intelligence — middleware is transport plumbing only

9.5 Transport Federation Doctrine

Transport governance requires Phase Type B federated aggregation to synthesize: route indices · admission maps · projection schemas · transport boundary manifests.

Transport aggregation may synthesize: routes · projections · admission maps

Transport aggregation may NEVER: mutate execution semantics · alter workflows · inject orchestration · infer routing behavior dynamically

Transport is not federated execution; it is federated boundary governance.

10. Federated Governance

Architectural transition: PGS has evolved from protocol-governed execution to federated governance compilation — a substantially more powerful architecture class.

10.1 Definition

A Federated Governance Domain is a cross-structure governance concern that:

• cannot be semantically closed within a single domain structure
• requires contribution from multiple domain builds
• is compiled via Phase Type B aggregation
• produces a governed artifact consumed by execution, transport, or runtime

10.2 Canonical Domain Families

10.3 Invariants for All Federated Domains

Macro-invariant: Federated governance domains may synthesize governance products but may not synthesize execution semantics.

Every federated governance domain must:

• be declared via an aggregation STRUCTURE_ artifact with an explicit aggregation_type
• declare all contributing source dirs explicitly (artifact_source_dirs)
• produce deterministic output given the same inputs
• run after all contributing Phase Type A builds complete
• introduce no execution node types, runtime graph primitives, or middleware chains
• preserve orthogonality with the execution layer

10.4 Boundary Orthogonality

Federated governance products may never: mutate execution semantics · alter declared workflow behavior · inject orchestration logic · infer behavioral routing dynamically · become smart runtime components.

Authority governs whether execution may exist. Transport governs where boundaries are. Neither touches how the execution graph runs.

10.5 Architectural Significance

11. Anti-Patterns

12. Architecture Evolution

Understanding why the architecture looks as it does prevents re-introducing solved problems.

Architectural Invariants

Hard constraints. Violation = operational failure or architectural corruption.

Appendix A: Operational Reference

Bootstrap

cd pgs_workspace
cd scripts && ./bootstrap_pgs.sh               # default: editable installs from ~/pgs/
cd scripts && ./bootstrap_pgs.sh --env remote  # published PyPI packages
source .venv/bin/activate
pgs_runtime --help

Run Demo End-to-End

source .venv/bin/activate
cd scripts && ./demo_sample_workflow.sh

Run Workflow (CLI)

pgs_runtime run \
  --wf <domain>::<WF_CODE> \
  --payload <path-to-payload.json> \
  --data-root /absolute/path/to/pgs_workspace/data \
  --workspace /absolute/path/to/pgs_workspace

Env var alternatives:

export PGS_DATA_ROOT=/absolute/path/to/pgs_workspace/data
export PGS_WORKSPACE=/path/to/pgs_workspace

Examine a Trace

pgs_runtime examine ./traces/<domain>/<subdomain>/<TRACE_ID>/<TRACE_ID>.jsonl

Build (Compiler)

# Phase A — per-structure (run in order)
python -m pgs_compiler.cli compile --structure STRUCTURE_BUILD_PLATFORM_CONFIG_V0
python -m pgs_compiler.cli compile --structure STRUCTURE_BUILD_BLOCKCHAIN_CONFIG_V0
python -m pgs_compiler.cli compile --structure STRUCTURE_BUILD_AI_GOVERNANCE_CONFIG_V0

# Cross-structure aggregation happens in `build` (artifact_index/ emission) —
# the former Phase B vocabulary-aggregate compile step is retired; per-domain
# vocabulary is materialized in Phase A (S7).

# Full build — compile + sync + conformance + attestation + snapshot validation
python -m pgs_compiler.cli build --workspace /abs/path/to/pgs_workspace

# Inspect compiled evidence (without recompiling)
python -m pgs_compiler.cli inspect --structure STRUCTURE_BUILD_BLOCKCHAIN_CONFIG_V0 \
  --artifact blockchain::WF_REGISTER_ACTOR_UNVERIFIED_V0
python -m pgs_compiler.cli inspect --structure STRUCTURE_BUILD_BLOCKCHAIN_CONFIG_V0 \
  --family CONSTRUCTION

Protocol Inspection (pi)

export PGS_WORKSPACE=/abs/path/to/pgs_workspace   # or pass --workspace per command

# Daily drivers
pi artifact refs blockchain::CC_GENERATE_TX_ID_V0       # who references this artifact
pi topology impact <fqdn> --json                        # transitive consumer closure (dossier evidence)
pi behavior_logic show blockchain::WF_MINT_V0           # execution tree from *.graph.json
pi artifact source blockchain::WF_MINT_V0               # authoring Markdown from PPS snapshot
pi snapshot validate                                    # conformance state of the snapshot
pi validate --strict                                    # CI gate: exit 1 unless VALID + zero violations

# Interactive shell (tab completion; bare codes resolve within declared scope)
pi
#   pi> use blockchain
#   pi:blockchain> artifact refs CC_GENERATE_TX_ID_V0
#   pi:blockchain> exit

Full taxonomy (artifact, kind objects, topology, behavior_logic, store, vocab, pps, snapshot, trace): doc/pgs_cli_cheatsheet.txt. Doctrine: §5.5.

Clean State Rebuild

pgs_compiler/scripts/clean_pycache.sh
pgs_compiler/scripts/clean_outputs_dir.sh
pgs_compiler/scripts/clean_compiled_artifacts.sh

python -m pgs_compiler.cli compile --structure STRUCTURE_BUILD_PLATFORM_CONFIG_V0
python -m pgs_compiler.cli compile --structure STRUCTURE_BUILD_BLOCKCHAIN_CONFIG_V0
python -m pgs_compiler.cli compile --structure STRUCTURE_BUILD_AI_GOVERNANCE_CONFIG_V0
python -m pgs_compiler.cli build --workspace /abs/path/to/pgs_workspace

Unit Tests

python pgs_runtime/testbed/run_runtime_tests.py -v

HTTP Server

scripts/start_http_server.sh

See pgs_cli_cheatsheet.txt for port overrides and manual invocation options.

Appendix B: Artifact Reference

Snapshot Structure

protocol_snapshot/
  artifacts/
    workflows/                       ← WF_ JSON
    capability_contracts/            ← CC_ JSON
    capability_transforms/           ← CT_ JSON
    capability_side_effects/         ← CS_ JSON
    runtime_bindings/                ← RB_ JSON
    intents/                         ← IN_ JSON
    events/                          ← EV_ JSON
    actors/                          ← AC_ JSON
    layers/ invariants/ assertions/  ← governance (compiled from all 14 FB_* boundaries)
  visualization/<WF_NAME>/
    <WF_NAME>.graph.json             ← machine-readable DAG
    <WF_NAME>.projection.png         ← visual graph

evidence_snapshot/                   ← compiler observability (written by S7, verified by S8)
  <domain>/
    evidence_graph.json              ← semantic causality graph; events + edges + families + hash

Both protocol_snapshot/ and evidence_snapshot/ are READ-ONLY post-build. Never edit by hand. To change: modify protocol source and recompile.

Trace Structure

traces/<domain>/<subdomain>/<TRACE_ID>/
  <TRACE_ID>.jsonl    ← append-only structured event log (input to pgs_runtime examine)
  <TRACE_ID>.md       ← human-readable summary
  <TRACE_ID>.png      ← execution path visualization

FQDN Format

<domain>::<ARTIFACT_CODE>_V<version>

Examples:
  blockchain::WF_REGISTER_ACTOR_UNVERIFIED_V0
  ai_governance::WF_GOVERN_AGENT_ACTION_V0
  blockchain::CC_GENERATE_ACTOR_ID_V0
  capability_transforms::CT_PURE_GENERATE_ID_V0

Note: CT_ artifacts live in the capability_transforms domain.
      CS_ artifacts live in the capability_side_effects domain.

Governance artifacts use fb.* namespace:
  fb.constitution::CONSTITUTION_FEDERATION_BOUNDARY_V0
  fb.topology::CONSTITUTION_EXECUTION_TOPOLOGY_V0
  fb.constitution::STRUCTURE_BUILD_PLATFORM_CONFIG_V0

Filesystem separator: :: in code → __ (double-underscore) in filenames:

blockchain__WF_REGISTER_ACTOR_UNVERIFIED_V0.json

Short-code calls to load_bootstrap_artifact() without fb.*:: namespace raise a hard ValueError — no fallback.

Execution Outcome Vocabulary

Intent outcomes (IN_ gate):

ACK     Admission accepted — graph traversal proceeds
NACK    Admission rejected — execution halted before graph entry

CC node outcomes:

SUCCESS          Normal forward completion
ALREADY_EXISTS   Idempotency guard triggered (registry)
VIOLATION        Constraint violated (governance, invariant)
DENIED           Authorization failed
BACKEND_ERROR    Infrastructure or implementation error at CS/CT boundary

Data State Layout

data/<domain>/<subdomain>/...        ← one subtree per FB-aligned subdomain
  blockchain/
    identity/        registry/actors.json · events/identity_events.jsonl
    wallet/          state/wallets.json · events/wallet_events.jsonl
    transaction/     state/transactions.json · events/transaction_events.jsonl
    mempool/         state/mempool.json · registry/mempool_index.json
    block/           blocks/blocks.json · events/block_events.jsonl
    consensus_pos/   registry/validators.json · rounds/rounds.jsonl · events/*.jsonl
    orchestration/   state/slot_clock.json · events/simulation_summary.jsonl
  ai_governance/
    ai_licensing/    license_facts.json (read-only seed) · license_registry.json · audit_log.jsonl
    agent_governance/  governance_actions.json · governance_audit.jsonl

Storage topology is declared in STRUCTURE artifacts (entity_stores) and resolved via RB_ — never hardcode paths. Registry stores are deduplicated; events/ journals are append-only and never truncated; seeds in seeds/ are source of truth, copied to data/ by bootstrap.

Appendix C: Workflow Inventory

All available workflows: ls protocol_snapshot/artifacts/workflows/

In flight (chain CR, at design approval): WF_INITIALIZE_CHAIN_V0 (genesis bootstrap) · WF_COMMIT_BLOCK_V0 (canonical block commitment).

Payload files: <repo>/testbed/<subdomain>/test_payloads/

pgs_runtime run --wf <domain>::<WF_CODE> \
  --payload <domain_repo>/testbed/<subdomain>/test_payloads/<payload>.json \
  --data-root /absolute/path/to/pgs_workspace/data \
  --workspace /absolute/path/to/pgs_workspace

Appendix D: Debugging Guide

Common Failure Signatures

Compile vs Runtime Failures

Trace Debugging

pgs_runtime examine ./traces/<domain>/<subdomain>/<TRACE_ID>/<TRACE_ID>.jsonl
# Each event: artifact_id, inputs, outputs, outcome, timestamp
# .md file: human-readable summary
# .png file: visual execution path

Snapshot Mismatch

If runtime behavior diverges from expected: recompile and sync. Never patch protocol_snapshot/ manually — it will be overwritten by next build.

Appendix E: Refactor Patterns

Add a New Artifact Family

1. Define schema in pgs_governance
2. Write constitution with invariants
3. Implement assertion handlers (static imports only)
4. Register handlers in handler registry
5. Add STRUCTURE_ config entry to include new family
6. Recompile

Add a New CT (Capability Transform)

1. Implement deterministic function in pgs_capabilities (no side effects)
2. Declare CT_<NAME>_V0 artifact in the relevant domain repo
3. Add RB_ binding entry mapping declaration to implementation
4. Reference CT in CC_ capability contract within a workflow
5. Recompile and sync snapshot

Add a New CS (Capability Side Effect)

1. Implement storage/IO operation in pgs_capabilities
2. Declare CS_<NAME>_V0 artifact in the relevant domain repo (defines semantics, not implementation)
3. Add RB_ binding entry
4. Reference CS in CC_ within a workflow
5. Recompile and sync snapshot

Add a New Domain

1. Create new repo (e.g., pgs_<domain>)
2. Author protocol artifacts: WF_, CC_, IN_, EV_ for the domain
3. Add STRUCTURE_BUILD_<DOMAIN>_CONFIG_V0 in pgs_compiler
4. Add the domain layer entry in STRUCTURE_DISCOVERY_V0 — set registry_module to the sub-module path (e.g., pgs_<domain>.registry), not the top-level package. The compiler’s LayerResolver uses module_root.parent to locate the repo root; pointing to the top-level package resolves the wrong parent directory and produces zero compiled artifacts.
5. Wire reusable CT/CS from pgs_capabilities via RB_
6. Implement any domain-specific CT/CS (rarely needed if library is mature)
7. Compile and sync
8. Add domain to workspace bootstrap and HTTP server config

Add a TI Route (HTTP Endpoint)

1. Declare TI_ artifact in protocol
2. Add static UI payload directory under domain testbed
3. Reference TI in HTTP server --domain flag
4. Snapshot-driven route registration happens automatically

Extend STRUCTURE Governance

1. Modify STRUCTURE_BUILD_*_CONFIG_V0 artifact in pgs_compiler
2. Add new artifact directories or scope inclusions
3. Recompile — no runtime changes required

Appendix F: Coding Directives

Appendix G: Repo Map and Quick Reference

Repository Map

Dependency direction: pgs_workspace → domains → capabilities → runtime ← compiler ← governance Change-management direction: pgs_change_mgmt → pgs_compiler (validation) + pgs_workspace (PPS snapshot, read-only)

Artifact Prefix Quick Reference

WF_  Workflow             CC_  Capability Contract
CT_  Transform            CS_  Side Effect
IN_  Intent               RB_  Runtime Binding
EV_  Event                AC_  Actor Context
TI_  Transport Ingress    TE_  Transport Egress
STRUCTURE_  Build Config

High-Value Grep Patterns

# List all workflow artifacts
ls protocol_snapshot/artifacts/workflows/

# Find binding for a specific CT
grep -r "CT_<NAME>" protocol_snapshot/artifacts/runtime_bindings/

# Find which CC uses a given CS
grep -r "CS_<NAME>" protocol_snapshot/artifacts/capability_contracts/

# Find trace events for a specific CC
grep '"artifact_id": "blockchain::CC_<NAME>"' \
  traces/<domain>/<subdomain>/<TRACE_ID>/<TRACE_ID>.jsonl

# Check snapshot validity marker
grep "status" protocol_snapshot/artifacts/workflows/*.json | head -5

Manual Evolution Rule

New content must improve architectural cognition density.

If information is already obvious from source code or protocol artifacts, it does not belong here. If a section does not improve architectural decision quality or cognitive restoration speed, it does not belong here.

PGS prioritizes architectural stability over feature velocity. When architectural tradeoffs occur, preference is given to: explicitness over convenience · governance over heuristics · determinism over flexibility · compile-time enforcement over runtime repair.

End of PGS Field Manual v0 — Doctrine-first. Operations in appendices.