Writes judgment and execution graphs with the Toulmin argument model. It is the core family through which GEUL describes its own rules in GEUL and revises itself.

GroupCodec
DeclarationCASE-DECLARE (case), PREDICATE-DECLARE (predicate), SPEC-DECLARE (criterion), RULE-DECLARE (claim), COUNTER-DECLARE (rebuttal), EXCEPT-DECLARE (exception) — NODE
RelationATTACKS (attack), SUPERSEDES (exclusion) — LINK, SUPERSEDE-CHAIN (priority chain, layout undecided)
ExecutionRUN, DO, DO-ONCE, UNDO, CHECKING — LINK, ENTRY, TRIGGER — NODE
ResultVERDICT (judgment result: Pass, Review, Fail), EVIDENCE (evidence of a judgment) — layout undecided
  • The source, section, and auxiliary nodes and relations are the direct codes 0x120L~0x134L of the TOULMIN format family (Source and sections, TOULMIN format).
  • A judgment result is kept in a document different from the one being judged. The result document imports and points to the target document. So judging does not change the content hash of the target document.

TOULMIN family Edges (direct codes 0x100L~0x11BL; auxiliary records are in the TOULMIN format family 0x120L~0x134L) write judgment and execution graphs with the Toulmin argument model. Declarations of claims, rebuttals, and exceptions, attack and exclusion relations, execution links, and judgment results are all Edges. One TANGEUL document (the rule language of the toulmin engine) becomes one GEUL document. The file extension is .geul, the same as other documents.

What this document does not fix follows the common rules of Edge and Records and TAG WORD.

Metacognition and self-revision

TOULMIN is a GEUL Codec so that GEUL can be metacognitive about itself. Only if the judgment and execution rules are also described in GEUL can TOULMIN take those rules as its object and revise them itself. So TOULMIN is not an application profile but the core of GEUL operation, and it sits in the Edge direct code space (0x100L~0x11BL).

  • Self-description makes self-improvement possible but bears the risk of circular error. If a rule judges its own revision, a revision that loosens the judgment criteria can also pass (the pass rate rises while the real accuracy falls).
  • The circularity is accepted as a risk but cut by structure.
    • Fixed core: the meaning of judgment (Pass, Review, Fail; attack, exclusion, priority; the three-valued evaluation and U → Review in Judging on the unknown below) is fixed in this specification. It cannot be changed by a TOULMIN document. This is the same place as the rules built into the decoder (layer 0 of Publication addresses and version lists).
    • Version separation: the revision of rule document v(n) is judged by the rules of v(n−1) and by external checks. A rule does not judge itself. A judgment result is kept in a document different from its target (the content hash of the target does not change).
    • Immutable history: revisions accumulate as new versions (PARENT, content hash, signature). Because old versions remain, a circular error can be found afterwards and rolled back. The safety net of self-revision is the GEUL version model (Document).
    • Outside criterion: a set of test cases that the revision path cannot touch is kept separately. The adoption of a revision is confirmed by the result on this set.
  • Falsification test: deliberately plant one wrong rule. If the system fixes it and the outside-criterion score rises, self-improvement works. If only the pass rate rises and the outside-criterion score falls, it is a circular error.

Codes

A TOULMIN record uses one of three layouts. The Codec sets the layout.

LayoutUsePage
NODEgraph nodes such as case, rule, definition, entry pointNODE
LINKrelations between nodes (attack, exclusion, execution, definition)LINK
EXPRcondition expression (predicate)EXPR

The source and section records (SOURCE, TEXT, SECTION, CASE-BEGIN and CASE-END, PROSE) are set by Source and sections.

Direct codes

CodecNameLayoutTANGEULMeaning
0x100LCASE-DECLARENODEin case ofCase declaration. A judgment graph that holds nodes and relations
0x101LPREDICATE-DECLAREEXPRcondition expression of RulesPredicate declaration. A judgment expression
0x102LSPEC-DECLARENODEDefinitions itemCriterion declaration (Backing). The role bits give the kind of definition
0x103LRULE-DECLARENODEgeneral rule, rule name in RulesClaim declaration (Warrant). It can be attacked
0x104LCOUNTER-DECLARENODEcounter ruleRebuttal declaration. It attacks with a conclusion of its own. The default Level is Fail
0x105LEXCEPT-DECLARENODEexcept ruleException declaration. It attacks without a conclusion of its own. The default Level is Review
0x108LATTACKSLINKdon't X when YAttack relation. The attacker’s verdict gradually reduces the target’s verdict by the attack strength (0 to 1, default 1)
0x109LSUPERSEDESLINKX supersedes YExclusion relation. If the attacker is Active, it deterministically removes the target from the aggregation. A chain (A > B > C) is written one pair at a time
0x10ALSUPERSEDE-CHAIN—Priority chain A > B > C. An abbreviation of pairwise SUPERSEDES. Only the code is assigned; there is no layout yet
0x110LRUNLINKrun c when nExecution composition. If the node is Active, it runs a sub-case (DAG)
0x111LDOLINKdo fn when nAn action performed if the node is Active
0x112LDO-ONCELINKdo fn once when nAn action performed only once even on retry
0x113LUNDOLINKundo fn when nThe compensating action of DO (saga). If a later step fails, it is performed in reverse order
0x114LCHECKINGLINKchecking cA link that only judges, without side effects
0x115LENTRYNODEprovides xExternal entry point. It runs or judges a case
0x116LTRIGGERNODEon, every, untilAn event or periodic entry point with no external call
0x118LVERDICT—The judgment result of a node or record. Result (Pass, Review, Fail), verdict value, Activated, Excluded, Level. Only the code is assigned; there is no layout yet
0x119LEVIDENCE—The evidence of a judgment. Location, expected value, actual value (Fact). Only the code is assigned; there is no layout yet
0x11CL~0x11FLReserved
  • Direct codes not in the table (0x106L, 0x107L, 0x10BL~0x10FL, 0x117L, 0x11AL, 0x11BL) are Reserved.
  • The groups are 0x100L~0x107L declaration, 0x108L~0x10FL relation, 0x110L~0x117L execution, and 0x118L~0x11FL result (0x11CL~0x11FL are Reserved).
  • The verdict of a whole document belongs to Meta VERDICT (0x1E9L), and the verdict of a node or record belongs to TOULMIN VERDICT (Edge 0x118L). The two are separate Codecs with different Kinds.

TOULMIN format

The source, section, and auxiliary nodes and relations are placed in the direct codes 0x120L~0x134L of the Edge TOULMIN format family. There is no Issuer or Codec number slot, and the Payload follows the TAG directly.

TAG WORD          0001 0010 0000 LLLL      Edge, Codec 0x120L (SOURCE). Other codes use the same slot
[Length extension TAG]
Edge Id           LOCAL Reference record
components        layout set by the format
CodecNameLayoutMeaning
0x120LSOURCEID, SPAN width WORD, UTF8 ValueAuthoring source text
0x121LTEXTID, UTF8 ValueName or string
0x122LSECTIONID, section code 1 WORDSection start
0x123LCASE-BEGINID, REF (case)Start of a case scope
0x124LCASE-ENDID, REF (case)End of a case scope
0x125LPROSEID, SPANDescriptive paragraph
0x126LNAMESPACENODEthis document is
0x127LFUNCNODEFunction reference
0x128LFIELDNODEis required
0x129LALIASNODEsee … from
0x12ALGROUPNODEOrdered execution group
0x12BLREQUIRESLINKCase → field
0x12CLMEANSLINKDefinition item → value or type
0x12DLHASLINKDefinition item → field
0x12ELRUNSLINKEntry point → case, run
0x12FLEVALUATESLINKEntry point → case, judge
0x130LTRIGGERSLINKTrigger → case
0x131LUNTILLINKTrigger → case (every … until)
0x132LSAME-ASLINKNode → global identifier
0x133LIMPORTED-FROMLINKAlias → path (TEXT)
0x134LLABELLINKNode → TEXT, name notation

Document

One .geul file is one DOC. No other bytes are placed outside the DOC.

DOC-1WORD/2WORD/4WORD     total length
  SPEC-VERSION            0x0001 (v1, integer with no embedded Value)
  PROFILE                 UTF8 Value "tangeul-<major>.<minor>". Currently "tangeul-1.0"
  [DEFAULT-LANGUAGE]      LANGUAGE-BCP47-CODE Value. Authoring locale ("en", "ko")
BODY
  SOURCE                  authoring source text. First record of the BODY
  statement records …     in document declaration order
END
  • HEAD: SPEC-VERSION, PROFILE, optional DEFAULT-LANGUAGE.
  • The decoder rejects a different SPEC-VERSION or a different PROFILE major. A different minor is still read.
  • The first record of the BODY is SOURCE. Every SPAN is a range within this source text.
  • The order of statement records is the same as the document declaration order. Execution order (do and run firing, undo reverse compensation) relies on this order. In a TOULMIN document, Edge order is meaningful (an exception to the order rule of the Edge layout).
  • Every record in the BODY is an Edge. No standalone Value records are placed. Values are embedded in the Edge Payload.
  • The identity of a case and imports use Meta DOC-ID and IMPORT-DOC (Subject and See of TANGEUL).

Common fields

FieldWidthDescription
IDLOCAL Reference recordThe Edge Id of the record. The first element of the Payload of every record
REFLOCAL Reference recordAn Edge Id pointing to another record of this document. 0 means none
SPANwidth set by SOURCE × 2A range within the authoring source text. Start byte, byte count
  • ID and REF are embedded LOCAL Reference records (0000 0000 0101 LLLL + an ID of the shortest width). The width is set by the Length of that record and is not declared per document.
  • REF 0 (LOCAL 0) means “none”. This is a Codec rule that uses LOCAL 0 as none (LOCAL).
  • Edge Ids are assigned from 1 and are not duplicated within a document. 0 is not used as an Edge Id because it means “none” in REF.
  • Nodes are forward-referenced by other records, so they receive numbers first, in document declaration order. The encoder assigns the other records (SOURCE, TEXT, LINK, FUNC, section records) numbers after the nodes.
  • The decoder only checks that an Edge Id is not 0 and has no duplicate. The assignment order is not used in interpretation.
  • Nodes and relations are pointed to by Edge Id.
  • An embedded Value is the Value record as is, including its TAG WORD. Its length is set by that TAG.

Numbers

  • The verdict value (−1 to 1), Qualifier (0 to 1), and attack strength (0 to 1) are SIGNED-DECIMAL Values. No separate fixed-point format is provided.
  • The encoder strips trailing zeros of the coefficient. 0.8 is C=8, E=−1. The decoder accepts up to 4 decimal places.
  • A confidence gate (for example, at least 75%) is written as a comparison operator 1 WORD and a percent UNSIGNED-DECIMAL Value (E=0) (LINK F_GATE).
  • Attack strength is the F_FORCE field of ATTACKS (LINK). A value out of range is rejected.

Axes of node declaration

  • A node declaration (RULE-, COUNTER-, EXCEPT-DECLARE) has a role (claim, rebuttal, exception), a Qualifier (0 to 1), and a Level (Unset, Fail, Review). The role is held by the Codec and the role of the NODE header, the Qualifier by F_QUAL, and the Level by the level of the header (NODE).
  • Strength (Strict, Defeasible, Defeater) is a separate axis from the role. The placement of strength is not decided yet.
  • Attack strength (Force) is a value of the ATTACKS edge, not of a node (LINK F_FORCE). It is a different axis from strength.

Judging on the unknown

When a judgment graph takes GEUL facts as input, the three concepts of the slot marker (not written, unknown, none) are evaluated differently. The evaluation of the comparison operators of EXPR is as follows.

Inputis emptyis not emptyequals / is in / magnitude comparison
value vfalsetrueevaluated with v
NO-VALUE (none)truefalsefalse
UNKNOWN-VALUE (unknown)falsetrueundetermined (U)
ABSENT (not written) / no descriptionU (open world)UU
  • Logic uses Kleene strong three-valued logic. NOT U = U, false AND U = false, true OR U = true. Any other combination with U is U.
  • EXISTS any is true if any element is true. If there is no true and there is a U, it is U; if all are false, it is false.
  • If a predicate is U, the verdict of that node is not Pass or Fail but Review. What is not known is handed to a person (or the next stage).
  • To read ABSENT as empty rather than U, the input side must declare a closed world (injected as the criterion SPEC, for example “the input of this case is complete”). Without the declaration, it is U.
  • This table and the U → Review mapping are the meaning of judgment, so they are a fixed core. They cannot be changed by a TOULMIN document.
  • Example: a rule that “counts only borders still valid today” (P582 is empty) excludes it as false if P582 = UNKNOWN-VALUE, includes it as true if P582 = NO-VALUE, and sends it to Review as U if P582 is absent.

Judgment results

  • A judgment result (VERDICT, EVIDENCE) is kept in a document different from the one being judged. The result document imports the target document with IMPORT-DOC and points to it with EXTERNAL-POINTER-*. So judging does not change the content hash of the target document.
  • The verdict of a whole document is Meta VERDICT; the verdict of a node or record is TOULMIN VERDICT.
  • Rules that choose the version of a revision to apply (transitional provisions, choosing between the law at the time of the act and the new law), as well as interpretive precedents and case law, are also used as judgment rules (Document).

Open problems

  • The layouts of SUPERSEDE-CHAIN (0x10AL), VERDICT (0x118L), and EVIDENCE (0x119L). Whether the current way of writing SUPERSEDES one pair at a time is enough for a chain.
  • The placement of node strength (Strict, Defeasible, Defeater).
  • An ATTACKS that states attack strength 1 and an ATTACKS that does not have the same verdict but different bytes. Whether the verdicts are the same must be compared by interpreted value, not by bytes.
  • The node count, label count, and label index in EXPR are 1 WORD, and the child count is 13 bits. The upper limits are fixed.
  • The PROVENANCE (rule source and premise) layout.
  • Whether to place a backtick name as a statement LABEL or BIND instead of TEXT + LABEL (0x134L).
  • The code value tables for the predicate and mode of Claim and for the VerbCode of FuncRef.
  • Whether a closed-world declaration (reading ABSENT as empty) is made per criterion (SPEC) or per case.
  • The Codec spec document of the TOULMIN Codecs. The conditional fields of NODE and LINK and the SPAN width set by SOURCE make layouts that cannot be declared with FIELD.

Related pages

NODE

NODE is the layout that writes the nodes of a TOULMIN judgment and execution graph. The node kind is set by the Codec, and a 1 WORD header sets the role, Level, Claim form, and conditional fields.

Codec

CodecNameTANGEULNode
0x100LCASE-DECLAREin case ofcase
0x102LSPEC-DECLAREDefinitions item (means, has)criterion (Backing). The role is the kind of definition
0x103LRULE-DECLAREgeneral ruleclaim (Warrant)
0x104LCOUNTER-DECLAREcounter rulerebuttal (Rebuttal)
0x105LEXCEPT-DECLAREexcept ruleexception (Defeater)
0x115LENTRYprovides xexternal entry point
0x116LTRIGGERon, every, untilevent or periodic entry point
0x126LNAMESPACEthis document isdocument namespace
0x127LFUNCfunction referenceoutside function (for example, bank.withdraw)
0x128LFIELDx is required [as Type]required field
0x129LALIASsee a from pathalias of an imported package
0x12ALGROUP1. ordered listordered execution group

0x126L~0x12AL are direct codes of the Edge TOULMIN format family (TOULMIN format).

Layout

ID               LOCAL Reference record (Edge Id)
header 1 WORD    role 2b | Reserved 2b | F_GROUNDS 1b | level 2b | object kind 2b | flags 7b
[F_FUNC]         FuncRef: REF(ALIAS, 0 if none) + VerbCode 1 WORD
[F_QUAL]         SIGNED-DECIMAL Value. Qualifier
[F_CHECK]        REF(case)
[F_CLAIM]        Claim: REF(subject) + predicate 1 WORD + object + mode 1 WORD
[F_VERDICT]      SIGNED-DECIMAL Value. Initial verdict value
[F_WITH]         count (UNSIGNED-INTEGER Value) + REF(TEXT) × count
[F_GROUNDS]      count (UNSIGNED-INTEGER Value) + REF(TEXT) × count
SPAN             width set by SOURCE × 2 (start byte, byte count)

Header WORD

BitsFieldValue
15–14role0 general, 1 counter, 2 except
13–12Reserved0
11F_GROUNDSa grounds list is present
10–9level0 Unset, 1 Fail, 2 Review (3 Reserved)
8–7object kindThe form of the Claim object. 0 REF, 1 UNSIGNED-INTEGER Value, 2 SPAN
6–0flagstable below
BitflagMeaning
b0F_FUNCa FuncRef field is present
b1F_QUALa Qualifier field is present
b2F_CHECKa field for the case that checking targets is present
b3F_CLAIMa Claim field is present
b4F_VERDICTan initial verdict value field is present
b5F_STRIKEa declaration crossed out with strikethrough. It has no fields
b6F_WITHa criteria list field is present
  • Conditional fields are placed in flag order (F_FUNC, F_QUAL, F_CHECK, F_CLAIM, F_VERDICT, F_WITH, F_GROUNDS). A field whose flag is off takes no space.
  • If a flag is on but the field is missing, the record is rejected. The position after reading the fields in order must match the end of the record exactly after the SPAN.

Fields

FieldDescription
FuncRefThe function slot. REF is the ALIAS record from which the function was imported, and is 0 for a function of this document. VerbCode is a 1 WORD code and is not assigned yet (0x0000 is allowed). The source notation of the function is written separately as TEXT + LABEL
QualifierThe confidence of the node (0 to 1)
caseF_CHECK: the case that this node only judges (checking c)
ClaimThe proposition the node holds. Subject REF, predicate 1 WORD, object, mode 1 WORD. The form of the object is set by the object kind of the header
verdict valueThe initial verdict value (−1 to 1)
F_WITHThe criteria at declaration time (with). A list of TEXT record REFs
F_GROUNDSNames of external facts resolved at evaluation time (grounds). A list of TEXT record REFs
SPANThe range of the source text where this declaration appears
  • The notation of verdict values and Qualifier follows the numeric rules of TOULMIN.
  • The count of a list is an embedded UNSIGNED-INTEGER Value record.
  • The default form of a descriptive Claim has subject and predicate 0 and the object as a SPAN (object kind 2). It is fixed to the source notation.

Interpretation and validity

  • For RULE-, COUNTER-, and EXCEPT-DECLARE, the role must equal the Codec (0 general, 1 counter, 2 except). For SPEC-DECLARE it is the kind of definition. For any other Codec it is 0.
  • If level is 0 (Unset), the engine default is used: Fail for COUNTER-DECLARE, Review for EXCEPT-DECLARE.
  • A host-function rule of TANGEUL tangl:rule (is a rule that uses) is written as a RULE-DECLARE NODE outside a case. The function is F_FUNC, the criterion is F_WITH, and the grounds are F_GROUNDS. Only a condition expression rule has a PREDICATE-DECLARE before it.
  • Reserved bits (13–12) must be 0. If a Reserved bit is on, or the role does not match the Codec, the record is rejected.

Related pages

LINK is the layout that writes the relations between nodes in a TOULMIN graph. The Codec sets the kind of relation.

Codec

CodecNameTANGEULsrc → dst
0x108LATTACKSdon't X when Yrule → rule. Gradually reduces the verdict by the attack strength
0x109LSUPERSEDESX supersedes Yrule → rule. If Active, removes the target from the aggregation
0x110LRUNrun c when nrule → case
0x111LDOdo fn when nrule → FuncRef
0x112LDO-ONCEdo fn once when nrule → FuncRef
0x113LUNDOundo fn when nrule → FuncRef
0x114LCHECKINGchecking crule → case. A judgment without side effects
0x12BLREQUIRESf is requiredcase → field
0x12CLMEANSDefinitions meansdefinition item → value or type
0x12DLHASDefinitions hasdefinition item → field
0x12ELRUNSentry point run centry point → case (run)
0x12FLEVALUATESentry point check centry point → case (judge)
0x130LTRIGGERStrigger run ctrigger → case
0x131LUNTILevery … until ctrigger → case
0x132LSAME-ASnode → global identifier
0x133LIMPORTED-FROMsee a from pathalias → path (TEXT)
0x134LLABELbacktick namenode → TEXT. Name notation

Layout

ID               LOCAL Reference record (Edge Id)
src              REF
dst              REF. FuncRef for DO, DO-ONCE, and UNDO
flags 1 WORD     b0 F_ONCE, b1 F_GATE, b2 F_STRIKE, b3 F_ORDERED, b4 F_FORCE
[F_GATE]         operator 1 WORD (top 2 bits) + UNSIGNED-DECIMAL Value (percent)
[F_FORCE]        SIGNED-DECIMAL Value. Attack strength (0 to 1). ATTACKS only
SPAN             width set by SOURCE × 2
flagMeaning
b0 F_ONCEperformed only once (the once of UNDO)
b1 F_GATEa confidence gate field is present
b2 F_STRIKEa relation crossed out with strikethrough
b3 F_ORDEREDbelongs to a 1. ordered list
b4 F_FORCEan attack strength field is present. ATTACKS only
Gate operatorMeaning
0at least
1above
2less than
3at most
  • Conditional fields are placed in flag order (F_GATE, F_FORCE). A field whose flag is off takes no space.

Attack strength

Attack strength (F_FORCE) is used only by ATTACKS. The verdict formula, notation, and example are on that page.

Interpretation and validity

  • REF is the Edge Id of a record in this document (common fields of TOULMIN).
  • The form of dst is set by the Codec. DO, DO-ONCE, and UNDO use a FuncRef (REF(ALIAS, 0 if none) + VerbCode 1 WORD, NODE); LABEL and IMPORTED-FROM use the REF of a TEXT record; the rest use the REF of a node.
  • do … once is represented by the DO-ONCE Codec. F_ONCE is not used in the flags of DO-ONCE (it is rejected if turned on). The once of UNDO is written as F_ONCE.
  • The gate operator is the top 2 bits of the operator WORD, and the remaining 14 bits are 0. The percent is an UNSIGNED-DECIMAL Value with E=0, from 0 to 100.
  • Bits b5 to b15 of flags are Reserved and must be 0. Otherwise the record is rejected.
  • F_FORCE is used only by ATTACKS. If it is on in any other Codec (SUPERSEDES, execution and judgment links, TOULMIN format relations), the record is rejected.
  • If the attack strength is not a SIGNED-DECIMAL Value, is outside 0 to 1, or cannot be represented exactly in 4 decimal places, the record is rejected.
  • A SUPERSEDES chain A > B > C writes one SUPERSEDES per pair.

Related pages

Source and sections

Records that write the source text and the sections of a TOULMIN document. All are direct codes 0x120L~0x125L of the Edge TOULMIN format family (TOULMIN format). There is no Issuer or Codec number slot, and the Payload follows the TAG.

Formats

CodecNameLayout
0x120LSOURCEID, SPAN width WORD, UTF8 Value
0x121LTEXTID, UTF8 Value
0x122LSECTIONID, section code 1 WORD
0x123LCASE-BEGINID, REF (case)
0x124LCASE-ENDID, REF (case)
0x125LPROSEID, SPAN
  • ID is the Edge Id, and REF is the Edge Id of a record in this document (common fields of TOULMIN).
  • A UTF8 Value is a UTF8-TEXT Value record. It holds the bytes as is.

Pages by format

Each format has its own page for the layout, the section code table, and the interpretation.

  • SOURCE: authoring source text. The first record of the BODY, and it sets the SPAN width
  • TEXT: name or string
  • SECTION: section start and section code
  • CASE-BEGIN, CASE-END: case scope
  • PROSE: descriptive paragraph

Related pages