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 exercise | In the model |
|---|---|
# @amend:<name> on the lines that hold a value | a parameter with at:, the places that hold its value |
layer, min, max, step, unit, safety in constitution.yaml | the 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 applies | sos.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.yaml | amendment.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), orregulation(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 ofvoters:with aquorum:(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 thatprevious:names, or, when it gives noprevious:, the version with the latest effective time before its own (K.11). A version withoutprevious:that gives noeffective:oreffective: { 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 oftransitions:the item writtenFROM->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, andC.lambdaname the values of the contractCandenvironment.Xthe entryXofcontext.environment, as in the regime bindings of A.7.1.
| Location | Value |
|---|---|
contracts.ROAD_USE.lifecycle.transitions.release.deadline | the deadline: of the lifecycle transition release |
contracts.ROAD_USE.monitors.blocking_guard.rule | the rule: of a monitor |
contracts.DELIVERY_SLA.guarantee.0 | the first item of guarantee: |
contracts.JOB.norms.report.deadline | the deadline: of a norm (Appendix F) |
transitions.DISTRIBUTED->CENTRALIZED.condition | the 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.bays | short 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.
| Rule | Lifecycle, monitors, guarantees | Norms (Appendix F) |
|---|---|---|
keep | The 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. |
switch | The 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:givessos.version.previous:is a scalar other thansos.version. - K-3 A
time_pointhas exactly one ofperiod:, a positive integer, andat:, an ISO 8601 date or date-time. - K-4 A transitional rule is
keeporswitch. Atransitional_entrynames a contract of the file, at most once.in_states:is given only withswitchand names states of the contract'slifecycle:that are not terminal. - K-5 A
decision_defhas an identifier asid:, unique among the decisions, aref:without white space, and akind: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 ofvoters:names an actor. A layer oflayers:is one ofrule,contract,regulation, and its authority hasdecided_by:.procedure: votehas a positivequorum:, no larger than the number ofvoters:when they are all actors without an index;quorum:andvoters:are given only withprocedure: 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 asvalue:;unit:is a string andsafety:a boolean. - K-8
min:,max:, andstep:are of the kind ofvalue:;step:is positive andmin:is not greater thanmax:;value:lies in[min, max]and, whenmin:andstep:are given, differs frommin:by a whole number of steps.max_steps:is a positive integer and is given only withstep:. A processor SHOULD warn when a parameter located atalpha,beta, orlambdaof a contract is not a number or declaresmin:below 0 ormax: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 insideversion:oramendment:, 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 ofamendment.decisions. - K-11 A
schedule:is a non-empty list of entries with one form offrom:, in increasing order forperiod:andat:and with distinct versions forversion:; atarget:is a string or a number. - K-12
window:andevery:are positive durations,every:is given only withwindow:and is not longer;aggregate:andacross_runs:are from the list and are given only withevery:andruns:respectively;runs:is a positive integer. - K-13 A file that uses
amendment:,schedule:, ormeasure:without declaringamendment: 0.1gets 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:
- 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 frommin:, and differs from the old value by at mostmax_steps×step. - 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:, andmotivation:.verification:is compared like the rules, since a change of it can weaken what is proved. Values are compared as in K.3:60sand1minare 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. - 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.
previous:of the new version, when given, is thesos.versionof the old one, and the two versions differ. When the old version has nosos.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.- 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 (includingverification: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). Aprevious: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 ofcadl norms-difffor 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 passcadl check, 2 for a missing file or an old version that does not passcadl 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 byprevious:), the time base, and the keyversionof an observation of the trace, which names the version in force. The result has the keyversions, with the version under which the instance started, the version it follows, and everykeep,switch, waiting switch, and dropped switch with its time; an amendment by a switch is reported as one byamendis (F.10). Up tocadl0.3.34 a trace with versions could not haveamend, 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 keyversion, the result is that ofcadl0.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 keyversionof an observation, ascadl 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, ornot judgedwith 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 withevery:), and the values of the terms of the target. Exit status 1 when a measurement does not meet its target;cadl norms-check --versionmodels a version whose rule for the contract iskeeporswitchwithin_states:as K.11 applies it fromcadl0.3.36 (F.10, F.12);cadl0.3.34 and 0.3.35 refused such a version;- the module
version.pyof 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 keyversionof a trace for a file without anamendment:block (K.11, "The version in force at a step"); - versions together with regime bindings in
cadl norms-evaland 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 ofcadl mcp-gatewayandcadl 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--epochan instant is placed on the time of the trace through itsepoch(the instant oft = 0). Anamendof 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 iskeeporswitchwithin_states:while an instance of that contract runs; a gateway refuses versions that change the actors or thecounts_as:rules that createapprovalorrejection, which it reads once;- the target checks of
metrics.pywith 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; amendtogether with versions incadl norms-evaland the norms monitor, in the order ofcadl agents-run(the versions first; anamendcancels a waiting switch), and the keyversionin a trace ofcadl 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 thanperiod: 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 lengthLof a period and the timeT0at which period 1 starts: periodkstarts atT0 + (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:
- By the effective times. With a time base, the version in force
at a step with time stamp
tis the last version of the sequence whose effective time is not aftert; the first version withouteffective: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. - 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 V | At this step |
|---|---|
keep | The instance goes on following its version. Nothing of F.6 applies, and its norm instances, deadlines, and windows are not touched. |
switch | The 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.
- 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
switchwithin_states:whose state holds first, then the versions whose effective time is reached. - 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.
- 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 hasregimes:. A processor refuses a run that breaks this, naming the regime and the version. - 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:
keepleaves it on its version,switchreplaces its definition, andswitchwithin_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.
- 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. - Target. The target at a time is the one K.5 gives. An entry
with
from: { version: X }applies from the effective time ofXin 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 atsdiffers 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 ofschedule:are judged alike. - Value. Without
every:, one run gives one value. Withevery:, one run gives the values of the formula ats,s + every, ..., befores + window, that is ⌈window/every⌉ values, combined byaggregate:. Withruns:, the measurement has that many runs, combined byacross_runs:; without it, one.medianof 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. - 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 verifyjudges 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, andcadl verifydoes not state it.cadl amend-diffstates, 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-checkwith--versionlets the environment amend every instance at any one observation, which isswitchwithoutin_states:at an effective time it does not know. Fromcadl0.3.34 it refused a later version whose rule for the contract iskeeporswitchwithin_states:. Fromcadl0.3.36 such a run is modelled as this section applies it: every file declares the extension with anamendment:block, the later versions are given in the order ofprevious:, 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 waitingin_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 thatcadl norms-evalwith the versions reads it. A model above the limits of commands is refused with the limit (F.12).cadl norms-evaland the norms monitor of the Python target apply this section to a trace (F.10), andcadl metrics-evaljudges measurements (K.9). Fromcadl0.3.35cadl agents-runand the gateways of Appendix G switch the enforcement point at the effective times (K.9). Fromcadl0.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 withschedule:inmetrics.pytakes 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. Fromcadl0.3.35, for a file with anamendment:block, every target check also takes the versions of the run (the modulesversion.pyof their packages, in the order of the sequence;version.pyhas 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 entryfrom: { version: X }at the effective time ofX, 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 itsmeasure:. 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 namesprevious:, or, fromcadl0.3.35, when it gives noprevious:and an effective time other thanperiod: 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 withoutprevious:and with noeffective:oreffective: { 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. Fromcadl0.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 withsetVersion, and it also applies "Versions and regimes" above when a version binds regimes (setRegime), as does the Rego monitor (the keyregimeof 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. Fromcadl0.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.