Documentation
Traceability

When a premise leaves force

A Decision can rest on another Decision. When that premise leaves force, how far does Smeldr follow the chain? It depends on what you ask for. Smeldr has three answers, and each has a stated limit:

  • The flag goes one step, by rule.
  • The count goes all the way, up to 1,000 items in each direction, and says "at least" when it stops.
  • The trace goes ring by ring, up to 10 hops, and says exactly where it was cut.

The examples on this page use five ratified Decisions. D2 and D5 rest on D1, D3 rests on D2, and D4 addresses D1:

D3 --grounded_in--> D2 --grounded_in--> D1 <--grounded_in-- D5
                                         ^
                    D4 ---addresses------'

Then D1 is superseded.

The flag: one step

When a Decision leaves force, every Decision in force that rests on it directly gets a premise-flagged condition: one per pair of Decision and premise. Rests on directly means a live grounded_in relation from the one to the other.

In the example, D2 and D5 are flagged. D3 is not. D2 is still in force, so nothing D3 rests on has left force. The flag stops after one step because that is the rule, not to save work. Whoever confirms that D2 still holds, or replaces it, decides what happens to D3; if D2 leaves force, D3 is flagged then.

D4 is not flagged either. addresses says a Decision is about another: it declines it, follows it up or clarifies it. It does not rest on it. An Amendment's amends relation does not raise the flag.

The condition is a Signal addressed to whoever may ratify the Decision. Its message names the Decision and never the premise, so a reader who may not read the premise does not learn about it there:

D2 rests on a Decision that is not in force

The condition resolves by itself when the rule stops holding: the premise is in force again, the relation ends, or the flagged Decision leaves force itself. Or someone who holds ratify over the Decision's place confirms that it still holds, with a reason, using the MCP tool confirm_premise:

{"decision": "D2", "premise": "D1", "reason": "Still holds: checked against D6."}

Instead of the decision and the premise, you can name the condition ("condition": the Signal's address or ID). That form works even when you may not read the premise. A confirmation keeps the pair closed until the premise's state changes again: if D1 later moves from superseded to archived, D2 is flagged again.

The count: everything, up to 1,000

The MCP tool get_rest_counts counts what rests on an item and what the item rests on, transitively, each item once:

{"type": "Decision", "id": "D1"}
{"rests_on_this": {"open": 0, "closed": 4}, "this_rests_on": {"open": 0, "closed": 0}}

The count follows more relations than the flag: grounded_in, addresses and amends. So D1 has four items resting on it: D2, D5, D3 through D2, and D4. Open means the item's state waits for someone to act, such as a proposed Decision; a ratified Decision counts as closed.

The count applies your read rules. An item you may not read is neither counted nor walked through, so a count never reveals a hidden item. It can be lower than what someone with wider rights sees.

Each direction stops at 1,000 items, nearest first. A walk that stops there sets "at_least": true, and the true count is at least the number shown.

For lists, list_rest_counts reads counts that a sweep stored, up to 200 items per call. The sweep runs with ENABLE_STRUCTURAL_SWEEP, on STRUCTURAL_SWEEP_SCHEDULE (hourly by default). Each result carries counted_at, the time of the sweep. Without it, no sweep has counted the item yet and the numbers are zero. A stored count is summed over the places you may read, so it may be lower than the live count, never higher.

The trace: ring by ring

The MCP tool get_reachability shows which items are reached, not just how many. It walks outward from an item one ring per hop. To follow the premise chain of D1, ask for grounded_in relations coming in, three hops deep:

{"type_name": "Decision", "id": "D1", "kind": "grounded_in", "direction": "incoming", "depth": 3}

The result has D2 and D5 in ring 1, D3 in ring 2 and nothing in ring 3: "ring_sizes": [2, 1, 0]. An empty ring means there is nothing at that distance.

  • depth is 1 to 10, and 1 when you leave it out.
  • direction is incoming, outgoing or both (the default).
  • Without kind, the walk follows every relation kind, so it also reaches places and Signals.

The walk returns at most max_items items: 500 by default, 2,000 at most. When the cap stops it, the result says where, with the exact number of items left out:

"cut": {"depth": 1, "dropped": 2}

The ring at that depth is partial. Deeper rings were not walked, and are left out of the result rather than shown as empty. The returned items come in pages of 100 (limit, at most 500).

So how deep does it go?

The flag stops after one step, by rule. The count and the trace go further, and each says where it stopped when it did not reach the end.

To see this before you replace a Decision, read See what rests on a Decision before you replace it. For relations in general, see Content relations.