Read ward policy before changing it

Prerequisite: linking and permissions. Conduit.policy reports the current ward policy. The policy controls contract direction and how per-spell restrictions are applied.

The five modes are default, whitelist_all, block_all, inbound_only, and outbound_only. Use their names or enum members; an enum's integer .value is not its string name.

Diagnose the refusal boundary

The saved policy lesson checks three conditions: the frame must be dynamic, the conduit must be normal, and restrictive policy changes can be refused while contracts exist. A policy change does not silently tear down existing relationships.

Read the current relationships, end the contracts deliberately if that is the intended application operation, then apply the policy. Use the existing severing guide for the relationship's lifecycle.

The workflow in code

These are the core steps from the saved example. Use its complete linked script for all class definitions and setup.

def main() -> None:
    # Pass the mode NAME. That is the whole API - every setter in melder
    # that takes an enum is typed Union[Enum, str] and normalizes for you.
    print("the five modes:", list(MODES))
    assert {policy.name for policy in md.Policies} == set(MODES)

    # AND HERE IS WHY THE STRING IS THE RIGHT HABIT, not just the shorter
    # one. Policies is built on auto(), so `.value` is an INT - reach for
    # it to build the argument and you pass 3 instead of "block_all". The
    # name is the string form. Use the literal and the trap disappears.
    assert isinstance(md.Policies.block_all.value, int)
    assert md.Policies.block_all.name == "block_all"
    print("Policies.block_all.value is", md.Policies.block_all.value,
          "- an int, not the mode name. pass \"block_all\" instead.")

    # ------------------------------------------------------------------
    # REFUSAL 1 - DYNAMIC MODE ONLY
    # ------------------------------------------------------------------
    # Each world binds its OWN class. A spell_id is the SHA256 of the
    # class's code and neither the frame nor the binding_name is in it,
    # so the same class bound in two frames is one spell_id and the
    # second registration is refused process-wide. Frames isolate
    # instances, not identity - see advanced 02.
    automatic_book = md.Spellbook(aetheric_frame="ward-automatic")
    automatic_book.bind(spell=Payload, existence="unique",
                        binding_name="automatic")
    automatic_root = automatic_book.conjure(name="automatic-root")
    try:
        automatic_root.set_new_policy("block_all")
        raise AssertionError("expected RuntimeError on an automatic frame")
    except RuntimeError as error:
        print()
        print("automatic frame refused set_new_policy:", error)

    # ------------------------------------------------------------------
    # A DYNAMIC WORLD - now the door opens
    # ------------------------------------------------------------------
    book = md.Spellbook(aetheric_frame="ward-dynamic")
    book.bind(spell=DynamicPayload, existence="unique", binding_name="dynamic")
    book.configure_aether_frame(system_state="dynamic", disposal=None,
                                disposal_method_names=None)
    root = book.conjure(name="ward-root")
    print()
    print("dynamic frame conjured")

    # Plain strings, like every other enum-shaped argument in melder. The
    # ward normalizes through EnumHelpers.convert_enum_and_check, so the
    # mode NAME is all you ever need to pass.
    root.set_new_policy("outbound_only")
    print("policy -> outbound_only")

    root.set_new_policy("inbound_only")
    print("policy -> inbound_only")

    root.set_new_policy("default")
    print("policy -> default")

    # ------------------------------------------------------------------
    # REFUSAL 2 - NORMAL CONDUITS ONLY
    # ------------------------------------------------------------------
    lesser = root.create_lesser_conduit()
    try:
        lesser.set_new_policy("block_all")
        raise AssertionError("expected RuntimeError on a lesser conduit")
    except RuntimeError as error:
        print()
        print("lesser conduit refused a policy:", error)

    # ------------------------------------------------------------------
    # REFUSAL 3 - NO RETROACTIVE LOCKDOWN
    # ------------------------------------------------------------------
    # With no contracts yet, the restrictive modes are allowed.
    root.set_new_policy("block_all")
    print()
    print("block_all accepted while the ward has no contracts")
    root.set_new_policy("default")

    # Form a contract, and the restrictive modes stop being available -
    # melder refuses rather than severing behind your back.
    peer_book = md.Spellbook(aetheric_frame="ward-dynamic")
    peer = peer_book.conjure(name="ward-peer")
    linked = root.link(peer)
    print("linked to a peer:", linked)

    for restrictive in ("block_all", "whitelist_all"):
        try:
            root.set_new_policy(restrictive)
            raise AssertionError(
                f"expected RuntimeError setting {restrictive} with contracts"
            )
        except RuntimeError as error:
            print(f"{restrictive:14s} refused while contracts exist")

    # The permissive/directional modes are still fine - only the two that
    # would invalidate existing grants are gated.
    root.set_new_policy("outbound_only")
    print("outbound_only still accepted - it does not invalidate grants")

    print()
    print("policy governs direction AND whether per-spell checks apply")
    print("a change that cannot be honestly applied is refused, not partial")

Runnable examples

Ward policies — Advanced 16

All advanced examples · Level contents · Full contents

Canonical page source