VI.17
First rule
Use one rule to select the first item of an input list. Change the input, inspect a failure, and repeat a request.
Scope
The examples state the Lispex 2.0 outcome. Native, npm, and WASM product plans are not run.
Every example keeps the same first-item definition. The request.json file shows the entry, input, and finite limits in documentation notation. The CLI and interchange chapters specify the concrete product forms.
Rule boundary
Declare first-item under the entry contract. Supply the list as one Datum. This example follows the single result rule.
The application displays that result. The rule needs no printing procedure.
17.1 Pass one input and receive one result
The root module declares first-item as its entry. The request supplies one list datum. For a nonempty list, first-item returns its first element as one result datum.
Why
An explicit input makes the rule reusable. Returning one datum gives the calling application one decision value to handle.
See Concrete entry declaration and admission, Module grammar and initialization, Concrete command forms.
Rule program
Read source.scm as the rule source for this chapter. Its module exports first-item and declares it as the entry. The parameter items receives the input datum. The body calls car with that value.
Every fixture contains this same module. The request selects main as its root module.
Return the first item
lispex.example.v2.first-rule.success · rev. 2
(module main
(import)
(export first-item)
(entry first-item)
(define first-item
(lambda (items)
(car items)))
)
Request and files
{
"notation": "documentation-request",
"source": "source.scm",
"semantics": {
"language": "Lispex 2.0",
"standardLibrary": "one fixed library identity",
"unicode": "one fixed Unicode semantics version",
"resourceModel": "one fixed finite resource model"
},
"limits": {
"prepare": "finite values sufficient to prepare this source",
"evaluate": "finite values sufficient for the stated finite calculation"
},
"requests": [
{
"input": {
"kind": "list",
"items": [
{
"kind": "integer",
"value": "3"
},
{
"kind": "integer",
"value": "5"
},
{
"kind": "integer",
"value": "8"
}
]
}
}
],
"rootModule": "main",
"moduleSources": [
{
"name": "main",
"source": "source.scm"
}
]
}
3Outcome details
{
"kind": "value",
"valueCount": 1,
"datum": {
"kind": "integer",
"value": "3"
}
}Specification outcome. Product runs are pending the 2.0 adapter.
Product invocation
Expected result
Input list 3, 5, 8 produces the exact integer 3 as one result datum. Product invocation awaits its 2.0 adapter.
The list contains three elements, but the request supplies one datum. The product plan checks the result 3 and the single result count.
Input and result
The input list has the elements 3, 5, and 8. The complete list is the one input Datum. The result is the exact integer 3.
The expected result describes a canonical outcome. Product commands and displayed output belong to CLI and diagnostics.
Failure
Replace the input with the empty list. Keep the rule source unchanged. The call to car fails because it requires a pair.
The condition catalog identifies this failure as domain.type in phase evaluate. The diagnostic field rule defines its serialized fields. Human message text does not change the canonical outcome.
17.2 Report an empty input as a failure
Passing the empty list to first-item produces a domain failure from car. The failed request returns no result datum.
Why
A failure keeps invalid input visible. It prevents the calling application from treating a missing list element as a decision.
Inspect the empty-list failure
lispex.example.v2.first-rule.empty-input · rev. 2
(module main
(import)
(export first-item)
(entry first-item)
(define first-item
(lambda (items)
(car items)))
)
Request and files
{
"notation": "documentation-request",
"source": "source.scm",
"semantics": {
"language": "Lispex 2.0",
"standardLibrary": "one fixed library identity",
"unicode": "one fixed Unicode semantics version",
"resourceModel": "one fixed finite resource model"
},
"limits": {
"prepare": "finite values sufficient to prepare this source",
"evaluate": "finite values sufficient for the stated finite calculation"
},
"requests": [
{
"input": {
"kind": "list",
"items": []
}
}
],
"rootModule": "main",
"moduleSources": [
{
"name": "main",
"source": "source.scm"
}
]
}
domain.typeOutcome details
{
"kind": "language-failure",
"valueCount": 0,
"condition": {
"phase": "evaluate",
"code": "domain.type",
"data": {
"operation": "car",
"argument": "0",
"path": [],
"expected": "pair",
"actual": "empty-list"
}
}
}Specification outcome. Product runs are pending the 2.0 adapter.
Product invocation
Expected result
The empty list produces a car domain failure and no result datum. Product invocation awaits its 2.0 adapter.
The entry still receives one datum. That datum is the empty list. The product plan checks the car domain failure and absence of a result.
Repair
After the failure, submit the list with elements 7 and 9 as a new request. The result is 7. Submit the original list again and the result is 3.
The product plan uses the same prepared rule for all three requests. Each evaluation uses its own input.
17.3 Use the input of each new request
Each request evaluates first-item with its own input datum. A failed request leaves later requests free to evaluate their supplied inputs.
Why
A caller can correct or replace an input without repairing hidden session state. The result then follows from the new request.
Use a new input after a failure
lispex.example.v2.first-rule.next-input · rev. 2
(module main
(import)
(export first-item)
(entry first-item)
(define first-item
(lambda (items)
(car items)))
)
Request and files
{
"notation": "documentation-request",
"source": "source.scm",
"semantics": {
"language": "Lispex 2.0",
"standardLibrary": "one fixed library identity",
"unicode": "one fixed Unicode semantics version",
"resourceModel": "one fixed finite resource model"
},
"limits": {
"prepare": "finite values sufficient to prepare this source",
"evaluate": "finite values sufficient for the stated finite calculation"
},
"requests": [
{
"input": {
"kind": "list",
"items": []
}
},
{
"input": {
"kind": "list",
"items": [
{
"kind": "integer",
"value": "7"
},
{
"kind": "integer",
"value": "9"
}
]
}
},
{
"input": {
"kind": "list",
"items": [
{
"kind": "integer",
"value": "3"
},
{
"kind": "integer",
"value": "5"
},
{
"kind": "integer",
"value": "8"
}
]
}
}
],
"execution": "Evaluate three separate requests using the same prepared rule.",
"rootModule": "main",
"moduleSources": [
{
"name": "main",
"source": "source.scm"
}
]
}
domain.typeOutcome details
{
"kind": "language-failure",
"valueCount": 0,
"condition": {
"phase": "evaluate",
"code": "domain.type",
"data": {
"operation": "car",
"argument": "0",
"path": [],
"expected": "pair",
"actual": "empty-list"
}
}
}7Outcome details
{
"kind": "value",
"valueCount": 1,
"datum": {
"kind": "integer",
"value": "7"
}
}3Outcome details
{
"kind": "value",
"valueCount": 1,
"datum": {
"kind": "integer",
"value": "3"
}
}Specification outcome. Product runs are pending the 2.0 adapter.
Product invocation
Expected result
The empty input fails. The next input list 7, 9 returns 7. Restoring input list 3, 5, 8 returns 3. Product invocation awaits its 2.0 adapter.
Keep the source unchanged. Submit each input as a new request. The product plan checks that a failure does not replace or contaminate later inputs.
Replay
Use replay to repeat first-item. Keep the complete semantic request and compare canonical outcomes.
Retain source and artifact identities and execution and signature evidence using the definitions there.
The same replay procedure applies to the empty-input failure.
17.4 Repeat the complete request
Apply the exact-replay rule to first-item. Repeating the success request returns the same Datum. Repeating the empty-input request produces the same domain failure.
Why
A recorded decision can be checked only when the program, input, semantics, and limits stay fixed. Separating the outcome from execution evidence makes that comparison precise.
Replay a successful request
lispex.example.v2.first-rule.replay-success · rev. 2
(module main
(import)
(export first-item)
(entry first-item)
(define first-item
(lambda (items)
(car items)))
)
Request and files
{
"notation": "documentation-request",
"source": "source.scm",
"semantics": {
"language": "Lispex 2.0",
"standardLibrary": "one fixed library identity",
"unicode": "one fixed Unicode semantics version",
"resourceModel": "one fixed finite resource model"
},
"limits": {
"prepare": "finite values sufficient to prepare this source",
"evaluate": "finite values sufficient for the stated finite calculation"
},
"requests": [
{
"input": {
"kind": "list",
"items": [
{
"kind": "integer",
"value": "3"
},
{
"kind": "integer",
"value": "5"
},
{
"kind": "integer",
"value": "8"
}
]
}
},
{
"input": {
"kind": "list",
"items": [
{
"kind": "integer",
"value": "3"
},
{
"kind": "integer",
"value": "5"
},
{
"kind": "integer",
"value": "8"
}
]
}
}
],
"comparison": "Repeat the complete semantic request with the same canonical program, input, semantics, resource model, and limits.",
"rootModule": "main",
"moduleSources": [
{
"name": "main",
"source": "source.scm"
}
]
}
3Outcome details
{
"kind": "value",
"valueCount": 1,
"datum": {
"kind": "integer",
"value": "3"
}
}3Outcome details
{
"kind": "value",
"valueCount": 1,
"datum": {
"kind": "integer",
"value": "3"
}
}Specification outcome. Product runs are pending the 2.0 adapter.
Semantic details
{
"comparison": {
"canonicalOutcomeEqual": true
}
}Product invocation
Expected result
Both executions return the exact integer 3. Their canonical outcomes are equal. Product invocation awaits its 2.0 adapter.
Retain the complete request and the first outcome. The product plan repeats that request and compares the canonical outcomes.
Replay a failing request
lispex.example.v2.first-rule.replay-failure · rev. 2
(module main
(import)
(export first-item)
(entry first-item)
(define first-item
(lambda (items)
(car items)))
)
Request and files
{
"notation": "documentation-request",
"source": "source.scm",
"semantics": {
"language": "Lispex 2.0",
"standardLibrary": "one fixed library identity",
"unicode": "one fixed Unicode semantics version",
"resourceModel": "one fixed finite resource model"
},
"limits": {
"prepare": "finite values sufficient to prepare this source",
"evaluate": "finite values sufficient for the stated finite calculation"
},
"requests": [
{
"input": {
"kind": "list",
"items": []
}
},
{
"input": {
"kind": "list",
"items": []
}
}
],
"comparison": "Repeat the same failing semantic request and compare its canonical outcomes.",
"rootModule": "main",
"moduleSources": [
{
"name": "main",
"source": "source.scm"
}
]
}
domain.typeOutcome details
{
"kind": "language-failure",
"valueCount": 0,
"condition": {
"phase": "evaluate",
"code": "domain.type",
"data": {
"operation": "car",
"argument": "0",
"path": [],
"expected": "pair",
"actual": "empty-list"
}
}
}domain.typeOutcome details
{
"kind": "language-failure",
"valueCount": 0,
"condition": {
"phase": "evaluate",
"code": "domain.type",
"data": {
"operation": "car",
"argument": "0",
"path": [],
"expected": "pair",
"actual": "empty-list"
}
}
}Specification outcome. Product runs are pending the 2.0 adapter.
Semantic details
{
"comparison": {
"canonicalOutcomeEqual": true
}
}Product invocation
Expected result
Both executions produce the same car domain failure. Neither returns a datum, and their canonical outcomes are equal. Product invocation awaits its 2.0 adapter.
Retain the empty-input request as well. The product plan checks that the same failure repeats. The diagnostic catalog determines its concrete code and representation.
See Replay inputs and comparison reports, Identity domains and encoded inputs, Artifact and package formats, Outcome, preparation report, and receipt bytes, Resource model numbers.