Skip to main content

Appendix K — Amendment of a Model (amendment 0.1)

This appendix specifies the amendment extension to CADL. It adds the key amendment: to sos_body (A.2) and the keys schedule: and measure: to metric_def (A.3). A file that uses it declares it:

extensions:
- amendment: 0.1

The extension declares how a model may change, not how a change is made. It states:

  • which values of the model may be amended, the layer each belongs to, who decides an amendment, and how far one amendment may move the value (K.3);
  • the identity of a version of the model, the version it replaces, when it takes effect, and what happens to contract instances that are running at that time (K.4);
  • targets of a metric that change over time or from one version to the next, how a metric is measured, and references to the records of human decisions on which a version rests (K.5).

No verdict of the core, of Appendix E, or of Appendix F depends on these keys. The reference implementation checks them, lowers them to the IR, and compares two versions of a model with them, from cadl 0.3.32 (K.9).

K.1 Motivation and scope​

The robot town of Course D amends its own rules after every period. Up to cadl 0.3.31 the model could not say which of its values may be amended: the exercise marks them with comments (# @amend:hold_limit), keeps their layer, range, and step in a separate constitution.yaml, keeps the KPI, which changes from period to period, in kpi.md, and keeps the human decisions in decisions.md and gsn.yaml. A comment is lost when a tool rewrites the file, two lines that carry the same value can drift apart, and a reader of one version of the rules cannot tell from it when it took effect or which version governs an order that was already under way.

The extension moves into the model what belongs to it:

In the exerciseIn the model
# @amend:<name> on the lines that hold a valuea parameter with at:, the places that hold its value
layer, min, max, step, unit, safety in constitution.yamlthe same keys on the parameter
who may adopt an amendment of each layer (the council by vote, the human)decided_by:, procedure:, quorum: per layer or per parameter
the version number of v<k>.cadl and the period from which it appliessos.version, amendment.previous, amendment.effective
what an order already under way follows (Exercise 12-3)amendment.transitional
the KPI of kpi.md by period, and how it is measured (five seeds, one period)schedule: and measure: of a metric
the entries of decisions.md and the nodes of gsn.yamlamendment.decisions, named by decision:

What stays outside: the procedure that produces a version (the proposal, the gates, the vote, the request to the human), the text of the KPI and of the decisions, and the values of the constitution that are not values of the model (the invariants and the improvement threshold of the exercise). The extension does not apply a version: a runtime or simulator that runs several versions reads their declarations (K.4), and applies them as K.11 says.

K.2 Concepts​

  • An amendable parameter is a named value of the model, a number or a duration, that an amendment may change. Its locations are the places of the file that hold the value.
  • Its layer says what kind of rule it belongs to: rule (the rules that the constituent systems set among themselves), contract (a promise to parties who do not take part in the amendment, such as customers), or regulation (a limit set from outside the SoS).
  • Its authority is the actor or role whose decision adopts an amendment of it: alone (procedure: single) or by the votes of voters: with a quorum: (procedure: vote).
  • A version of a model is one file. Its identity is sos.version. It takes effect at a period or at an instant, and stays in force until the next version takes effect. It replaces the version that previous: names, or, when it gives no previous:, the version with the latest effective time before its own (K.11). A version without previous: that gives no effective: or effective: { period: 1 } replaces none: it is a first version.
  • A transitional rule says, per contract, what an instance that is running when a version takes effect does: it keeps the version it started under, or it switches to the new version.
  • A decision record is an entry of a record of human decisions, or a node of a GSN assurance case, named by a URI reference.
  • A schedule gives the target of a metric from a period, an instant, or a version on. A measurement method says over which window and how many runs one measurement of the metric is taken.

K.3 Amendable parameters​

Syntax​

(* addition to sos_body (A.2) *)
[ "amendment:" , amendment_block ]

amendment_block = [ "previous:" , scalar ] ,
[ "effective:" , time_point ] ,
[ "transitional:" , transitional_block ] ,
[ "decisions:" , { "-" , decision_def } ] ,
[ "layers:" , { layer , ":" , authority } ] ,
[ "parameters:" , { "-" , param_def } ] ;

layer = "rule" | "contract" | "regulation" ;
authority = "decided_by:" , text ,
[ "procedure:" , ( "single" | "vote" ) ] ,
[ "quorum:" , int_literal ] ,
[ "voters:" , { "-" , actor_ref } ] ;

param_def = "id:" , identifier ,
"layer:" , layer ,
"value:" , quantity ,
[ "min:" , quantity ] ,
[ "max:" , quantity ] ,
[ "step:" , quantity ] ,
[ "max_steps:" , int_literal ] ,
[ "unit:" , text ] ,
[ "safety:" , bool_literal ] ,
"at:" , { "-" , location } ,
[ "decision:" , identifier ] ,
[ "decided_by:" , text ] , [ "procedure:" , ( "single" | "vote" ) ] ,
[ "quorum:" , int_literal ] , [ "voters:" , { "-" , actor_ref } ] ;

quantity = number | duration_lit ;
location = text ; (* see Locations *)

value:, min:, max:, and step: are all numbers or all durations (60s, 2min). decided_by: names an actor of the file by its id (COUNCIL, "ROBOT[*]") or a role (service_operator).

Meaning​

The value of the parameter is value:, and it is the value that the model has at each of its locations. min: and max: bound the values that an amendment may give it, and step: is the grid of those values: a value is allowed when it lies in [min, max] and differs from min: by a whole number of steps. One amendment moves the value by at most max_steps: steps (default 1). unit: names the unit of a number for a reader; a duration has its own unit. safety: true marks a parameter on which a safety condition of the model depends (for example the condition of a regime transition that has a safety_invariant:).

The authority of a parameter is its own decided_by:, procedure:, quorum:, and voters: when it gives any of them, and otherwise the authority of its layer under amendment.layers. With procedure: vote, the actor of decided_by: adopts an amendment when at least quorum: of voters: vote for it; without voters: the voters are outside the model. The layer itself has no further meaning in this version: it groups the parameters and gives them a default authority.

The declaration bounds amendments. It is not a constraint on the system while it runs: a regime binding (A.7.1) or a later version may give the same place another value.

Locations​

A location is a dot-separated path of keys from sos::

  • at a mapping, a segment is a key;
  • in a sequence, a segment selects the item whose id: equals it, for an entry of transitions: the item written FROM->TO, and a segment of digits selects the item at that index, counted from 0;
  • a segment in double quotes is taken as written, dots included, so that a value bound to a regime can be named: regimes.CENTRALIZED.parameters."ROUTING.beta"; the quotes span the whole segment (in YAML, write the location in single quotes);
  • when the first segment is not a key of sos:, C.alpha, C.beta, and C.lambda name the values of the contract C and environment.X the entry X of context.environment, as in the regime bindings of A.7.1.
LocationValue
contracts.ROAD_USE.lifecycle.transitions.release.deadlinethe deadline: of the lifecycle transition release
contracts.ROAD_USE.monitors.blocking_guard.rulethe rule: of a monitor
contracts.DELIVERY_SLA.guarantee.0the first item of guarantee:
contracts.JOB.norms.report.deadlinethe deadline: of a norm (Appendix F)
transitions.DISTRIBUTED->CENTRALIZED.conditionthe condition of a regime transition
regimes.CENTRALIZED.parameters."ROUTING.beta"the value that the regime CENTRALIZED binds to ROUTING.beta (A.7.1)
ROAD_USE.lambda, environment.baysshort forms of contracts.ROAD_USE.incentives.lambda and context.environment.bays

A location holds the parameter when the value written there, read as a literal (A.1), equals value:, or, for an expression, when the expression has a literal equal to value: or uses the name of the parameter as a name (hold_time <= hold_limit). The index of an actor reference (ROBOT[3]) is not a literal of this kind. Every literal equal to value: at a location is an occurrence of the parameter: a location should therefore be as narrow as the file allows (guarantee.0 rather than guarantee when two items hold equal values), and a processor warns when it is not (K-9). Two literals are equal when they denote the same number or the same duration: 120s and 2min are equal, 120s and 120 are not.

K.4 Versions and transitional provisions​

Syntax​

time_point = "period:" , int_literal
| "at:" , text ; (* exactly one *)
transitional_block = [ "default:" , transitional_rule ] ,
[ "contracts:" , { "-" , transitional_entry } ] ;
transitional_entry = "contract:" , identifier ,
"rule:" , transitional_rule ,
[ "in_states:" , { "-" , identifier } ] ;
transitional_rule = "keep" | "switch" ;

Meaning​

sos.version is the identity of the version, previous: names the version it replaces (optional; K.11 says which version a version without it replaces), and effective: says when it takes effect: at the start of the period with the given number (period:, counted from 1; what a period is, is set by the system, in the hands-on one simulated hour), or at an instant (at:, an ISO 8601 date or date-time; a date stands for 00:00 UTC of that day, and a date-time without an offset is read as UTC). A version stays in force until the next one takes effect.

A contract instance that starts at or after the time a version takes effect is an instance of that version. An instance that is running then (it has started and not ended) follows the transitional rule of its contract in the new version: the entry under transitional.contracts for the contract, or transitional.default, which defaults to switch.

RuleLifecycle, monitors, guaranteesNorms (Appendix F)
keepThe instance continues under the version it started under until it ends: its deadlines, monitors, assume: and guarantee: are those of the old version.The norm instances are not amended; their on_amendment: is not applied.
switchThe instance moves to the new version when the version takes effect, or with in_states: at the first observation, at or after that time, at which it is in one of the listed states (an instance that ends before is never moved). From then on it follows the new version; the time already spent in its current state counts against the new deadlines.When the instance moves, F.6 applies at that observation: each active or suspended norm instance follows its on_amendment: (carry_over, discharge, transform:).

switch is the rule that Appendix F, F.6 assumes: F.6 says what an amendment does to the norm instances of a contract instance, and this section says whether and when a contract instance is amended. The two do not overlap. As F.6 requires, the current state of an instance that switches must be a state of the new version; in_states: restricts the switch to states for which this holds. A version that has no transitional: lets every running instance switch when it takes effect, which is the behaviour of a file without the extension under F.6.

keep corresponds to the transitional provision "an order or a wait begun before the change keeps the old deadlines" of Exercise 12-3; switch with in_states: lets, for example, an order switch only while it has not been picked up (in_states: [Assigned]).

K.5 Metrics: schedules, measurement, and decision records​

Syntax​

(* additions to metric_def (A.3) *)
[ "schedule:" , { "-" , schedule_entry } ] ,
[ "measure:" , measure_def ]

schedule_entry = "from:" , ( time_point | "version:" , scalar ) ,
"target:" , scalar ,
[ "decision:" , identifier ] ;
measure_def = [ "window:" , duration_lit ] ,
[ "every:" , duration_lit ] ,
[ "aggregate:" , aggregate ] ,
[ "runs:" , int_literal ] ,
[ "across_runs:" , aggregate ] ,
[ "description:" , text ] ,
[ "decision:" , identifier ] ;
aggregate = "mean" | "median" | "min" | "max" | "sum" | "last" ;

decision_def = "id:" , identifier ,
"ref:" , text , (* a URI reference *)
[ "kind:" , ( "gsn" | "record" ) ] ,
[ "text:" , text ] ;

Meaning​

Schedule. The target of a metric at a time is the target: of the last entry of schedule: whose from: is not after that time, and the metric's own target: before the first entry. The entries of one schedule use one form of from:. With period: or at: they are in increasing order of time. With version:, an entry applies from the time that version of the model takes effect, and the entries are listed in the order in which their versions take effect. A target is written as the target: of a metric (A.3) and is not interpreted further.

Measurement. One measurement of the metric covers a window of length window:. With every:, the formula is evaluated at that interval within the window and the values are combined by aggregate: (default mean); without it, the formula is evaluated once over the window. With runs:, one measurement is taken in that many independent runs (for example simulations with different random seeds) and the values are combined by across_runs: (default mean). The target is compared with the measurement. description: says in words what the measurement means, for a reader.

Decision records. amendment.decisions lists the records of human decisions on which this version rests. ref: is a URI reference (RFC 3986), relative to the file or absolute, for example decisions.md#d1 or gsn.yaml#S2; kind: says whether it names a node of a GSN assurance case (gsn) or an entry of a record of decisions (record), and text: summarises it. A parameter (the decision that set its current value), a schedule entry (the decision that set the target), and a measurement method (the decision that chose it) name a record with decision:. The extension does not read the records.

K.6 Static semantics​

In a file that declares amendment: 0.1, a processor MUST report the following as errors.

  • K-1 amendment: and each of its parts are mappings or sequences as K.3 to K.5 give them, with no keys other than those listed.
  • K-2 A file with amendment: gives sos.version. previous: is a scalar other than sos.version.
  • K-3 A time_point has exactly one of period:, a positive integer, and at:, an ISO 8601 date or date-time.
  • K-4 A transitional rule is keep or switch. A transitional_entry names a contract of the file, at most once. in_states: is given only with switch and names states of the contract's lifecycle: that are not terminal.
  • K-5 A decision_def has an identifier as id:, unique among the decisions, a ref: without white space, and a kind: from the list.
  • K-6 decided_by: names an actor of the file (by the id, with or without an index) or a role of an actor; every item of voters: names an actor. A layer of layers: is one of rule, contract, regulation, and its authority has decided_by:. procedure: vote has a positive quorum:, no larger than the number of voters: when they are all actors without an index; quorum: and voters: are given only with procedure: vote. Every parameter has an authority, its own or that of its layer.
  • K-7 A parameter has an identifier as id:, unique among the parameters, a layer from the list, and a number or a duration as value:; unit: is a string and safety: a boolean.
  • K-8 min:, max:, and step: are of the kind of value:; step: is positive and min: is not greater than max:; value: lies in [min, max] and, when min: and step: are given, differs from min: by a whole number of steps. max_steps: is a positive integer and is given only with step:. A processor SHOULD warn when a parameter located at alpha, beta, or lambda of a contract is not a number or declares min: below 0 or max: above 1, the range of these values (A.12).
  • K-9 at: is a non-empty list of distinct locations; each resolves (K.3), is not inside version: or amendment:, and holds the parameter. A processor SHOULD warn when two parameters have the same value at the same location, or one inside the other: an amendment of one could not be told from one of the other. It SHOULD also warn when a location is a mapping or a sequence, or holds the value more than once: every such literal counts as the parameter.
  • K-10 A decision: names a decision of amendment.decisions.
  • K-11 A schedule: is a non-empty list of entries with one form of from:, in increasing order for period: and at: and with distinct versions for version:; a target: is a string or a number.
  • K-12 window: and every: are positive durations, every: is given only with window: and is not longer; aggregate: and across_runs: are from the list and are given only with every: and runs: respectively; runs: is a positive integer.
  • K-13 A file that uses amendment:, schedule:, or measure: without declaring amendment: 0.1 gets one warning; the keys are not checked and not lowered to the IR.

A processor SHOULD report, as information, a contract whose running instances keep the old version while it has norms: their on_amendment: does not apply (K.4).

K.7 Comparing two versions​

Two versions of a model are compared under the declaration of the old one, since that is the declaration under which the amendment is made. An old version that does not declare amendment: 0.1 declares no parameter, whatever keys it has. A change of the model respects the declared amendability when it is the change of declared parameters at their locations, each within the bounds of its old declaration:

  1. For each parameter of the old version whose value changes, the new value is of the same kind, lies in the old [min, max], lies on the old steps from min:, and differs from the old value by at most max_steps × step.
  2. Replacing in the old version, in one pass, the occurrences of the old value of every changed parameter at each of its locations by its new value gives the new version, apart from version:, amendment:, and the sections that are not rules: name:, description:, metrics:, codegen:, and motivation:. verification: is compared like the rules, since a change of it can weaken what is proved. Values are compared as in K.3: 60s and 1min are equal. The replacement is ambiguous, and the change is not explained, when a location holds the old value more than once (the other occurrences would change with it), or when two changed parameters have the same old value at the same place and give it different new values.
  3. A list whose items have ids keeps the order of the items that both versions have, where the semantics use that order: the norms of a contract (F.5, step 2, processes them in declaration order) and the actors (the file order of Appendix J). A change of order of another such list SHOULD be reported as a warning.
  4. previous: of the new version, when given, is the sos.version of the old one, and the two versions differ. When the old version has no sos.version, previous: cannot be checked, and a processor SHOULD report that as a warning. When both give an effective time of the same form, the new one is later; a period and a time cannot be compared, and a processor SHOULD say so.
  5. For a contract that changes and whose running instances switch, the states in which an instance may switch (in_states:, or every state that is not terminal) are states of the new version (F.6). A removed state is already a change that no parameter explains (item 2); a processor SHOULD add, as a warning, which switching instances it affects, without counting it as a second error.

A change of the declaration itself (a parameter's layer, authority, range, step, or locations, a parameter that is added) is not covered by the declaration, and a processor SHOULD report it. A change of a section that is not a rule SHOULD be reported. For every contract with norms whose running instances switch, whether or not its text changes, a processor SHOULD report what F.6 does to its norms, as cadl norms-diff does: every running instance of it is amended.

K.8 Intermediate Representation (IR) addition​

For a file that declares amendment: 0.1 and uses its keys, the IR gets the top-level key amendment. Durations are in milliseconds (kind: duration, unit: ms), numbers are written as numbers, and each parameter carries its resolved authority.

"amendment": {
"version": "2", "previous": "1", "effective": { "period": 2 },
"transitional": {
"default": "keep",
"contracts": [ { "contract": "ROAD_USE", "rule": "switch", "in_states": [] } ]
},
"decisions": [ { "id": "D1", "ref": "decisions.md#d1", "kind": "record" } ],
"parameters": [
{ "id": "block_k", "layer": "rule", "kind": "number", "unit": null,
"value": 2, "min": 1, "max": 4, "step": 1, "max_steps": 1, "safety": false,
"decided_by": "COUNCIL", "procedure": "vote", "quorum": 2, "voters": [],
"at": ["contracts.ROAD_USE.monitors.blocking_guard.rule"], "decision": "D1" }
],
"metrics": [
{ "id": "on_time_deliveries",
"measure": { "window_ms": 3600000, "runs": 5, "across_runs": "mean",
"decision": "K1" },
"schedule": [ { "from": { "period": 5 },
"target": ">= 0.85 * count(orders)", "decision": "K5" } ] }
]
}

The entries of metrics of the core IR keep id, formula, and target only; the additions are under amendment.metrics. The key is absent for a file without the declaration or without the keys.

K.9 Example and reference implementation status​

The cadl repository has the robot town of Course D with the extension in two versions, examples/amendment_robot_town_v1.cadl and _v2.cadl. Excerpt of version 2:

sos:
name: "RobotTown"
version: "2"
extensions:
- sos-dsl: 0.1
- amendment: 0.1
actors:
# TOWN_STEWARD, "ROBOT[1..N]", COUNCIL as in the hands-on, and the human:
- { id: OPERATOR, role: "service_operator", autonomy: high }
# contracts DELIVERY_SLA and ROAD_USE, transitions, protocols as in the hands-on
metrics:
- id: on_time_deliveries
formula: "count(Delivered)"
target: ">= 0.9 * count(orders)"
measure: { window: 3600s, runs: 5, across_runs: mean, decision: K1 }
schedule:
- { from: { period: 5 }, target: ">= 0.85 * count(orders)", decision: K5 }
amendment:
previous: "1"
effective: { period: 2 }
transitional:
default: keep # an order under way keeps its deadlines
contracts:
- { contract: ROAD_USE, rule: switch }
decisions:
- { id: K1, ref: "decisions.md#k1", kind: record }
- { id: K5, ref: "gsn.yaml#G5", kind: gsn }
- { id: D1, ref: "decisions.md#d1", kind: record }
layers:
rule: { decided_by: COUNCIL, procedure: vote, quorum: 2 }
contract: { decided_by: OPERATOR }
parameters:
- { id: hold_limit, layer: rule, value: 60s, min: 10s, max: 120s, step: 10s,
at: [contracts.ROAD_USE.lifecycle.transitions.release.deadline] }
- { id: block_k, layer: rule, value: 2, min: 1, max: 4, step: 1, decision: D1,
at: [contracts.ROAD_USE.monitors.blocking_guard.rule] }
- { id: to_central, layer: rule, safety: true, decided_by: OPERATOR,
value: 22, min: 10, max: 30, step: 2, unit: orders,
at: ["transitions.DISTRIBUTED->CENTRALIZED.condition"] }
- { id: pickup_deadline, layer: contract, value: 120s, min: 60s, max: 180s,
step: 30s,
at: [contracts.DELIVERY_SLA.lifecycle.transitions.pickup.deadline,
contracts.DELIVERY_SLA.guarantee.0] }
# sanction_lambda, to_distributed, dropoff_deadline likewise

cadl amend-diff compares the two versions (abridged):

$ cadl amend-diff examples/amendment_robot_town_v1.cadl examples/amendment_robot_town_v2.cadl
Amendment from ... (version 1) to ... (version 2) (amendment 0.1, K.7)
takes effect: period 2
decisions: K1 (decisions.md#k1), K5 (gsn.yaml#G5), D1 (decisions.md#d1)

Parameters
hold_limit: 60s → 60s (rule, COUNCIL by vote, quorum 2)
changed block_k: 3 → 2 (rule, COUNCIL by vote, quorum 2)
...
pickup_deadline: 120s → 120s (contract, OPERATOR)

Contract ROAD_USE: changed by block_k (transitional: switch)
info running instances switch to the new version when the new version takes effect

Result: the changes respect the declared amendability

A version that moves block_k from 3 to 1 at once and also makes the overstay of ROAD_USE a Major violation gets two errors: block_k "moves by 2, more than 1 step of 1", and the severity "is changed and no declared parameter explains it". The exit status is then 1.

From cadl 0.3.32 the reference implementation provides:

  • cadl check: the rules K-1 to K-13, including the information of K.6 for a kept contract with norms;
  • cadl sim-ir: the IR addition of K.8;
  • cadl amend-diff OLD NEW (text or --format json): the comparison of K.7. It lists every declared parameter with its old and new value, layer, and authority, every contract that changed with the parameters that changed it and its transitional rule, and the findings. An unexplained change of the rules (including verification: and the order of the actors and of the norms) and an ambiguous replacement are errors; a change of the sections that are not rules, of the order of other lists, and of the declaration is a warning, and so is an old version without the declaration (every change of the rules is then unexplained). A previous: that is not the old version, the same version on both sides, and an effective time that is not later are errors. For every contract with norms that switches, the findings of cadl norms-diff for that contract are included, also when its text is unchanged; for one that keeps, they are not, since F.6 does not apply. Exit status 0 when the changes respect the declared amendability, 1 when they do not or the new version does not pass cadl check, 2 for a missing file or an old version that does not pass cadl check.

From cadl 0.3.34 the reference implementation applies versions while a system runs, as K.11 says:

  • cadl norms-eval FILE --version FILE ... [--period DURATION] [--origin SECONDS] [--epoch]: the versions of the run (the file and the later versions, one sequence by previous:), the time base, and the key version of an observation of the trace, which names the version in force. The result has the key versions, with the version under which the instance started, the version it follows, and every keep, switch, waiting switch, and dropped switch with its time; an amendment by a switch is reported as one by amend is (F.10). Up to cadl 0.3.34 a trace with versions could not have amend, and a run that named a regime or whose initial regime did not have the contract in force could not have versions (both lifted in 0.3.35, K.11). Without --version, a time base, or the key version, the result is that of cadl 0.3.33, also for a file that declares the extension.
  • the norms monitor of the Python target (F.10), for a file that declares the extension with an amendment: block: the models of the other versions, the time base, and the key version of an observation, as cadl norms-eval;
  • cadl metrics-eval FILE --measurements FILE [--version FILE ...] with the same time base: the judgement of measurements of K.11 (met, not met, or not judged with the reason). A measurement gives the start of its window (a time stamp or a period), the value of each run (a list of samples with every:), and the values of the terms of the target. Exit status 1 when a measurement does not meet its target;
  • cadl norms-check --version models a version whose rule for the contract is keep or switch with in_states: as K.11 applies it from cadl 0.3.36 (F.10, F.12); cadl 0.3.34 and 0.3.35 refused such a version;
  • the module version.py of the Python target, and the refusals of the norms monitors of the Rego and Solidity targets and of the Unity C# target that K.11 gives.

The test suite compares cadl norms-eval with versions with cadl norms-eval given an amend line at each observation at which a reference implementation of K.11, written separately in the test, switches the instance, and the monitor with cadl norms-eval, on random traces of the example with two to four versions and random rules (keep, switch, switch with in_states:, and pickup deadlines). Each of four errors injected into the choice of the version in force or of the switch was detected. Up to cadl 0.3.34 cadl agents-run amended only where a trace said amend. Decision records are not opened.

From cadl 0.3.35 the reference implementation provides:

  • versions that give no previous:, placed by their effective times (K.11, "The versions of a run"), and the key version of a trace for a file without an amendment: block (K.11, "The version in force at a step");
  • versions together with regime bindings in cadl norms-eval and the norms monitor of the Python target (K.11, "Versions and regimes");
  • cadl agents-run FILE --trace T --version FILE ... [--period DURATION] [--origin SECONDS] [--epoch], and the same options of cadl mcp-gateway and cadl a2a-gateway: the enforcement point switches to a version at the first line of the trace whose time reaches its effective time. At that line it first expires the holds whose deadline has passed and applies the withdrawals and host events of the line (G.6), as at every line; then the versions take effect, before the contract instances of the line are created (they start under the new version), before the time and values of the line are observed, and before its messages are decided. With --epoch an instant is placed on the time of the trace through its epoch (the instant of t = 0). An amend of the same line is applied after the versions that take effect there. The enforcement point holds one version of the file with its boundary policy, so it refuses a version whose rule for a changed enforced contract is keep or switch with in_states: while an instance of that contract runs; a gateway refuses versions that change the actors or the counts_as: rules that create approval or rejection, which it reads once;
  • the target checks of metrics.py with the versions of the run (K.11, "Generated code"); a version whose effective time the time base cannot place is refused (ValueError), and without a time base the first version is in force unless the check is given the version in force;
  • amend together with versions in cadl norms-eval and the norms monitor, in the order of cadl agents-run (the versions first; an amend cancels a waiting switch), and the key version in a trace of cadl agents-run;
  • the refusals of the Rego and Solidity norms monitors and of Unity C# for a version that gives no previous: and an effective time other than period: 1.

The test suite compares cadl norms-eval with versions and regimes with a reference written in the test (the projection on the clock of the contract, as a trace of a file without regimes with amend lines where the reference switches the instance) on 300 random runs with up to four versions, random rules, and versions that differ in the regime that suspends the contract; each of four errors injected into the combination (the state seen while the contract is not in force, a switch made then, the bindings of the version in force, and the clock) was detected. The monitor is compared with cadl norms-eval on 300 further runs, metrics.py with cadl metrics-eval on 1800 random measurements, and cadl agents-run with versions with cadl agents-run given an amend line at the effective time on 100 random traces. cadl agents-run and cadl norms-eval are compared on the same file and trace with versions and an amend line (in 53 of 120 random traces at the line at which a version takes effect), and the monitor with cadl norms-eval on 80 such traces.

K.10 Backward compatibility​

The extension adds keys only. A file that uses none of them gives the same results as with cadl 0.3.31 for cadl check, cadl sim-ir, and cadl verify. For cadl 0.3.32 this was compared with 0.3.31 on the 78 example and test files of the cadl repository, and the test suite checks that no bundled example without the keys gets the IR addition or a diagnostic of the extension. Keys of the extension in a file that does not declare it get one warning (K-13) and are otherwise ignored, as A.2 asks of keys that are not part of a version of the language. The core metrics entries of the IR are unchanged also for a file that declares the extension.

K.11 Applying versions while a system runs​

K.4 and K.5 declare when a version takes effect, what a running contract instance does then, and which target a metric has at a time. This section fixes how a processor that runs or monitors a system applies these declarations, from cadl 0.3.34. It adds no key. It uses the steps of Appendix A, A.7.1 ("Runs") and the amendment of norm instances of Appendix F, F.6, which it does not change.

The versions of a run​

The versions of a run are files that declare amendment: 0.1 and form one sequence: every version but the first gives effective:, and the version before a version is the one that its previous: names. A version that gives no previous: (from cadl 0.3.35; up to 0.3.34 every version but the first gave it) replaces the version of the run with the latest effective time strictly earlier than its own. A version without previous: is not placed after another one when it gives no effective: or effective: { period: 1 }, or when no version of the run takes effect before it; it is then the first version. For example, in a run whose version 1 gives no effective:, a version 2 with effective: { period: 2 } and no previous: replaces version 1, while one with effective: { period: 1 } would be a second first version and the run would be refused. When two versions take effect at that latest time, or the effective times cannot be ordered (they use both forms of effective: and the run has no time base for one of them), the previous version is ambiguous, and a processor MUST refuse the versions and ask for previous:. Without a time base, effective times of the same form are ordered by their period or instant. A processor MUST refuse a set of versions that does not form one sequence, in which two versions have the same sos.version, or in which a previous: given in a version contradicts the order of the effective times. With a time base every two effective times are compared. Without one (from cadl 0.3.35) effective times of the same form are compared, period numbers with each other and instants with each other, and a period and an instant are not compared, as in 0.3.34.

Time base​

An effective time is a point in the time of the run, the time stamps of its steps; it is not read on the clock of a contract (F.5), since a version is a version of the whole model and the clock measures only the time in which one contract is in force. Since K.4 leaves the length of a period to the system, the run gives its time base:

  • for period: k, the length L of a period and the time T0 at which period 1 starts: period k starts at T0 + (k - 1) × L;
  • for at:, that the time stamps are seconds since 1970-01-01T00:00:00Z, so that the instant is a time stamp (a date stands for 00:00 UTC, and a date-time without an offset is UTC, as in K.4).

With a time base, the effective times of the versions MUST increase strictly along the sequence; a processor refuses the versions otherwise.

The version in force at a step​

At every step exactly one version is in force. It is determined in one of two ways, or in both:

  1. By the effective times. With a time base, the version in force at a step with time stamp t is the last version of the sequence whose effective time is not after t; the first version without effective: is in force from the start. A step before the effective time of the first version has no version in force, and a processor refuses it.
  2. By the host. As a host names the regime (A.7.1), it may name the version in force at a step; the version stays in force until another step names one, and before the first one the first version of the sequence is in force. A named version MUST NOT come before the version in force at the previous step. With a time base as well, the named version MUST be the version that item 1 gives; a processor refuses the step otherwise.

Without a time base and without a named version, the first version of the sequence is in force at every step. A version therefore takes effect at the first step whose time stamp is at or after its effective time, between that step and the one before it, as the bindings of a regime change (A.7.1, item 4). A value or a message observed at a step at exactly the effective time belongs to the new version: F.6 applies the new version at that step before anything else is evaluated.

A file that does not declare versions of a run (it has no amendment: block) has one version. From cadl 0.3.35 a host may still name it: a named version equal to the sos.version of the file is accepted and changes nothing, and a processor MUST refuse any other value, stating that the file declares no versions to switch to. With versions of a run, a named version has the meaning above in every processor, also in cadl agents-run.

Running contract instances​

A contract instance follows one version at each step. It follows the version in force at its first step. When a version V takes effect at a step, every running instance follows the transitional rule of its contract in V (K.4):

Rule of VAt this step
keepThe instance goes on following its version. Nothing of F.6 applies, and its norm instances, deadlines, and windows are not touched.
switchThe instance is amended (F.6) from the version it follows to V, before anything else is evaluated at this step. As K.4 says, the time already spent in its current lifecycle state counts against the deadlines of V, as the time already elapsed counts against the deadline of a norm that carries over (F.6).
switch with in_states:The switch waits. It is made, as above, at the first step from this one on at which the lifecycle state of the instance before the step (the state that the predicates of the step see, F.5) is one of in_states:.

F.6 is applied as it stands, with the version that the instance follows as the old version: an instance that kept version 1 when version 2 took effect and switches when version 3 takes effect is amended from version 1 to version 3, and the on_amendment: of the norms of version 1 applies. At one step, a waiting switch whose state holds before the step is made first, and then the versions that take effect at that step apply; a waiting switch is dropped when a later version takes effect at a step at which it is not made, and the rule of the later version then applies alone. An instance that ends first never switches. When several versions take effect at one step, they take effect in the order of the sequence, and the instance follows the rule of each in turn: two switches at one step are two amendments, applied one after the other before anything else. A switch to a version that does not have the contract, or in which the current lifecycle state does not exist, cannot be applied (F.6), and a processor refuses the step. An instance that keeps its version has the deadlines, monitors, assume: and guarantee: items, and norms of that version until it ends or switches.

A trace that amends a contract with the key amend of F.10 switches its instance at that observation whatever the versions declare. Up to cadl 0.3.34 a processor did not apply both to one run. From 0.3.35 a processor that applies both (cadl norms-eval, the norms monitor of the Python target, cadl agents-run, and the gateways of Appendix G) MUST apply, at one step, the versions that take effect there first and the amend afterwards, as versions take effect before F.6 amends at a step; a later version is then applied, by its transitional rule, to the definition that the amend gave. An amend applied to an instance cancels its waiting switch (switch with in_states:): the instance follows the amended file, and later versions apply to it by their rules. A run that combines versions with regime bindings ("Versions and regimes") cannot have amend; a run with regime bindings alone cannot have it either (F.10). When a processor applies such a key to a file whose transitional rule for the contract is keep or switch with in_states:, it SHOULD warn that the amendment is applied as a switch. The models of new versions that a processor is given for the key amend are not versions of a run; the versions of a run are given to it separately.

Versions and regimes​

From cadl 0.3.35 a run of a file with regimes: (Appendix A, A.7.1) can be given versions; up to 0.3.34 a processor refused a run that named a regime, or whose initial regime did not have the contract in force. A run is then judged as follows.

  1. Order at a step. Between two steps, the regime transition chosen at the end of the earlier step (A.7.1, "Runs", item 3) is taken first; it was chosen with the versions in force during that step. Then the versions take effect, in the order of "Running contract instances" above: a waiting switch with in_states: whose state holds first, then the versions whose effective time is reached.
  2. Contracts in force. Whether a contract is in force at a step is decided by the regime bindings of the version in force at that step, by the name of the contract. The version that an instance follows selects only the definition of the contract; an instance that keeps an older version is in force by the bindings of the version in force.
  3. Regimes of the versions. The run starts in the initial regime of the version in force at its first step. A regime that is current at some step MUST be a regime of every version that the run uses (every version in force at some step), and a run that is in no regime (its first version has no regimes:) MUST NOT use a version that has regimes:. A processor refuses a run that breaks this, naming the regime and the version.
  4. A version that takes effect while the contract is not in force. The contract instance is judged on the projection of the steps and on the clock of the contract (F.5, "Contracts not in force"). A version that takes effect at a step at which the contract is not in force still applies to the instance at that step: keep leaves it on its version, switch replaces its definition, and switch with in_states: waits as above, judged on the lifecycle state that the instance sees, which does not change while the contract is not in force (the state after the last step of the projection). Since the clock of the contract does not advance meanwhile, the amendment (F.6) is applied at the next step of the projection (the next step at which the contract is in force, or the step at which the instance ends), before anything else is evaluated there; the time already elapsed against its deadlines is that of the clock. A processor reports the switch at the time of the step at which the version took effect. An instance starts at the first step of its projection, under the version in force then.

A run that names no regime and whose versions have no regimes: is judged as in cadl 0.3.34. A run of 0.3.34 that named no regime and whose versions had different initial regimes was judged as one of a file without regimes:; from 0.3.35 it is in the initial regime of the version in force at its first step, and it is refused by item 3 when that regime is not a regime of a later version.

Metric schedules and measurements​

One measurement of a metric covers the window [s, s + window) of its measure:, where s is its start, a time stamp of the run; without window: it is taken at the instant s. It is judged as follows.

  1. Declaration. The target, the schedule, and the measurement method are those of the metric in the version in force at s. A version that does not declare the metric does not judge it.
  2. Target. The target at a time is the one K.5 gives. An entry with from: { version: X } applies from the effective time of X in the sequence of versions; an entry whose time cannot be placed (no time base for its form, or a version that is not in the sequence) leaves the measurement not judged. When the target at s differs from the target at some time inside the window, no single target applies, and the measurement is not judged. The target at a time inside the window is that of the version in force then: a version that takes effect inside the window and gives the metric another target, or does not declare it, leaves the measurement not judged, as a schedule entry would, so that a change written as a new version and one written as an entry of schedule: are judged alike.
  3. Value. Without every:, one run gives one value. With every:, one run gives the values of the formula at s, s + every, ..., before s + window, that is ⌈window / every⌉ values, combined by aggregate:. With runs:, the measurement has that many runs, combined by across_runs:; without it, one. median of an even number of values is the mean of the two middle ones. The formula itself is evaluated by the system that runs, not by this appendix.
  4. Comparison. A target that is a comparison operator (<, <=, >, >=, ==, !=) followed by an arithmetic expression of numbers, durations, and terms is compared with the value: the value is the left operand. A duration is in seconds, and so is the value of a metric whose target has a duration. A term that is not a number or a duration (count(orders)) takes the value that the measurement gives for it, by its text. The measurement meets the target when the comparison holds and does not meet it when it does not. A target of another form, a term without a value, and a division by zero leave the measurement not judged, with the reason.

Numbers are exact, as in F.5.

What the tools can state​

  • cadl verify judges one version. Its results hold for every step at which that version is in force and for every instance that follows it; a property of an instance that switches is not a property of either version alone, and cadl verify does not state it.
  • cadl amend-diff states, as before, whether the change from one version to the next respects the declared amendability; it does not depend on when the version takes effect.
  • cadl norms-check with --version lets the environment amend every instance at any one observation, which is switch without in_states: at an effective time it does not know. From cadl 0.3.34 it refused a later version whose rule for the contract is keep or switch with in_states:. From cadl 0.3.36 such a run is modelled as this section applies it: every file declares the extension with an amendment: block, the later versions are given in the order of previous:, and the next version takes effect at any observation (every effective time is possible). Each instance has the version it follows, the version of a waiting in_states: switch, and the class of its lifecycle state, which the environment sets at every observation (states that no rule tells apart form one class). A witness trace names the version in force (version) and the state (state), so that cadl norms-eval with the versions reads it. A model above the limits of commands is refused with the limit (F.12).
  • cadl norms-eval and the norms monitor of the Python target apply this section to a trace (F.10), and cadl metrics-eval judges measurements (K.9). From cadl 0.3.35 cadl agents-run and the gateways of Appendix G switch the enforcement point at the effective times (K.9). From cadl 0.3.36 they also follow regime bindings together with the versions ("Versions and regimes"): at a line the regime it names is current first, then the versions take effect; a version that takes effect while a contract is not in force reaches its instances at their next observation; a regime must be a regime of every version that the run uses (Appendix G, G.13).

Generated code​

A file is one version, and the code generated from it is the code of that version. Code that keeps no contract instance from one step to the next (the contract checks of the Python, Solidity, and Rego targets, and the boundary policies of Appendix G) applies a version at every step at which the host runs it: a host applies this section by running, at each step, the code of the version in force, and for an instance that keeps an older version the code of that version. Code that keeps the state of contract instances must move them when they switch:

  • the norms monitor of the Python target applies this section when it is given the models of the other versions of the run (F.10); the Python target also writes the module version.py, with the identity, the effective time, the transitional rules, the parameter values, and the metric schedules of the version, for the host that decides which version is in force. The target check of a metric with schedule: in metrics.py takes the time and the time base and checks the target in force then; it returns no verdict (not judged) when the time or the time base is missing, and so does any target check whose target cannot be compiled. From cadl 0.3.35, for a file with an amendment: block, every target check also takes the versions of the run (the modules version.py of their packages, in the order of the sequence; version.py has the targets of the metrics as well): it then judges a measurement whose window starts at the given time as "Metric schedules and measurements" above says, placing an entry from: { version: X } at the effective time of X, and returns no verdict when its own version is not in force at that time, an entry cannot be placed, or the target changes inside the window of its measure:. The norms monitor of the Python target also applies "Versions and regimes" above;
  • the norms monitors of the Rego and Solidity targets (D.5) do not apply amendments; a version that may replace another gets no monitor for a contract with norms whose running instances switch (switch, also by default), since the monitor could not take them over. Generated code sees one file, so it treats a version as one that may replace another when it names previous:, or, from cadl 0.3.35, when it gives no previous: and an effective time other than period: 1 ("The versions of a run"). This is a conservative test, not the definition of a first version: such a version may be the first of its run, but the file cannot show it, while a version without previous: and with no effective: or effective: { period: 1 } is always a first version. For a contract whose instances keep their version, the monitor serves the instances that start under this version. From cadl 0.3.36 the Rego monitor generated with the other versions of the run (cadl codegen -t opa FILE --version OTHER ...) contains the contract of every version and applies this section to the versions that the observations name, with the amendment of F.6; so does the Solidity monitor generated with them (-t solidity), to the versions that the orchestrator sets with setVersion, and it also applies "Versions and regimes" above when a version binds regimes (setRegime), as does the Rego monitor (the key regime of an observation). Given the other versions, the generated code takes the sequence of the run as this section builds it, without the conservative test;
  • the Unity C# target keeps lifecycle instances with deadlines; it refuses, without the other versions, a version that may replace another and in which a contract with lifecycle: switches its running instances. From cadl 0.3.36, given the other versions (--version FILE), it writes a class per version and a class that follows the version the host sets (SetVersion); a moved instance keeps its state, the time at which the deadlines of that state were armed, and the last times of its periodic monitors. When a version binds regimes, the class also follows the regime the host sets (CadlRegimes.Set) as "Versions and regimes" above says: the contract is in force by the bindings of the version in force, the instance starts at the first time it is in force, and a version that takes effect while it is not in force is applied when it is in force again, before anything else.