Lispex 2.0 specification · not released · Tested product not run · Examples not run

<a id="lispex.page.v2.first-rule"></a>

# First rule

Use one rule to select the first item of an input list. Change the input, inspect a failure, and repeat a request.

Canonical: /v2.0/en/docs/tour/first-rule

Document revision: 2.0-draft-1. Content locale: en. Translation: current.

- language: `lispex`
- languageVersion: `2.0`

<a id="lispex.section.v2.first-rule.scope"></a>

## 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.

<a id="lispex.section.v2.first-rule.rule-boundary"></a>

## Rule boundary

Declare first-item under the [entry contract](/v2.0/en/docs/language/procedures#lispex.rule.v2.procedures.entry-declaration). Supply the list as one [Datum](/v2.0/en/docs/language/values#lispex.section.v2.values.datum). This example follows the [single result rule](/v2.0/en/docs/language/procedures#lispex.rule.v2.procedures.entry-result).

The application displays that result. The rule needs no printing procedure.

<a id="lispex.rule.v2.first-rule.one-input-one-result"></a>

### 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.

<a id="lispex.claim.v2.first-rule.one-input-one-result"></a>

Claim: `lispex.claim.v2.first-rule.one-input-one-result` · acceptance · coverage partial · verification not-run

- language: `lispex`
- languageVersion: `2.0`

```json
{
  "predicate": {
    "kind": "rule-entry-call",
    "entry": "first-item",
    "input": "one-nonempty-list-datum"
  },
  "result": {
    "kind": "single-datum-result",
    "selection": "first-list-element",
    "resultCount": 1,
    "guestIO": false
  },
  "pendingCases": [
    "Entry arity and zero or multiple returned values require the Procedures cases."
  ]
}
```

See [Concrete entry declaration and admission](/v2.0/en/docs/language/procedures#lispex.rule.v2.procedures.entry-declaration), [Module grammar and initialization](/v2.0/en/docs/tools/prepare#lispex.rule.v2.prepare.module-forms), [Concrete command forms](/v2.0/en/docs/tools/run#lispex.rule.v2.cli-and-diagnostics.command-forms).

<a id="lispex.section.v2.first-rule.program"></a>

## Rule program

Read source.scm as the rule source for this chapter. Its [module](/v2.0/en/docs/tools/prepare#lispex.rule.v2.prepare.module-forms) 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.

<a id="lispex.example.v2.first-rule.success"></a>

### Return the first item

Mode: illustrative. Stage: semantic-request. Verification: not-run.

- language: `lispex`
- languageVersion: `2.0`

File: `source.scm`

```lispex
(module main
  (import)
  (export first-item)
  (entry first-item)
  (define first-item
    (lambda (items)
      (car items)))
)
```

File: `request.json`

```lispex
{
  "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"
    }
  ]
}
```

Fixture inputs and environment:

```json
{
  "entry": "source.scm",
  "argv": [],
  "stdin": "",
  "cwd": ".",
  "environment": [],
  "wrapper": null,
  "packageRef": null,
  "lockRef": null,
  "generatedBindingRefs": {
    "knowledgeState": "not-applicable",
    "values": []
  }
}
```

#### Expected result

```json
{
  "status": "unspecified",
  "reason": "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.

<a id="lispex.section.v2.first-rule.input-and-result"></a>

## 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](/v2.0/en/docs/profiles/receipt-and-replay#lispex.section.v2.receipt-and-replay.canonical-outcome). Product commands and displayed output belong to [CLI and diagnostics](/v2.0/en/docs/tools/run).

<a id="lispex.section.v2.first-rule.failure"></a>

## 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](/v2.0/en/docs/language/conditions#lispex.rule.v2.conditions.condition-catalog) identifies this failure as `domain.type` in phase `evaluate`. The [diagnostic field rule](/v2.0/en/docs/diagnostics#lispex.rule.v2.cli-and-diagnostics.diagnostics.typed-fields) defines its serialized fields. Human message text does not change the canonical outcome.


<a id="lispex.rule.v2.first-rule.empty-input"></a>

### 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.

<a id="lispex.claim.v2.first-rule.empty-input"></a>

Claim: `lispex.claim.v2.first-rule.empty-input` · rejection · coverage partial · verification not-run

- language: `lispex`
- languageVersion: `2.0`

```json
{
  "predicate": {
    "kind": "rule-entry-call",
    "entry": "first-item",
    "input": "empty-list-datum"
  },
  "result": {
    "kind": "rule-language-failure",
    "condition": "domain.type",
    "resultCount": 0
  },
  "pendingCases": [
    "Other non-pair inputs and competing failures require the Library and Conditions cases."
  ]
}
```

<a id="lispex.example.v2.first-rule.empty-input"></a>

### Inspect the empty-list failure

Mode: illustrative. Stage: semantic-request. Verification: not-run.

- language: `lispex`
- languageVersion: `2.0`

File: `source.scm`

```lispex
(module main
  (import)
  (export first-item)
  (entry first-item)
  (define first-item
    (lambda (items)
      (car items)))
)
```

File: `request.json`

```lispex
{
  "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"
    }
  ]
}
```

Fixture inputs and environment:

```json
{
  "entry": "source.scm",
  "argv": [],
  "stdin": "",
  "cwd": ".",
  "environment": [],
  "wrapper": null,
  "packageRef": null,
  "lockRef": null,
  "generatedBindingRefs": {
    "knowledgeState": "not-applicable",
    "values": []
  }
}
```

#### Expected result

```json
{
  "status": "unspecified",
  "reason": "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.

See [Diagnostic catalog and reports](/v2.0/en/docs/diagnostics#lispex.rule.v2.cli-and-diagnostics.diagnostics.catalog), [Numeric exit mapping](/v2.0/en/docs/tools/run#lispex.rule.v2.cli-and-diagnostics.exit-mapping).

<a id="lispex.section.v2.first-rule.repair"></a>

## 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.

<a id="lispex.rule.v2.first-rule.independent-input"></a>

### 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.

<a id="lispex.claim.v2.first-rule.independent-input"></a>

Claim: `lispex.claim.v2.first-rule.independent-input` · interaction · coverage partial · verification not-run

- language: `lispex`
- languageVersion: `2.0`

```json
{
  "predicate": {
    "kind": "successive-rule-requests",
    "entry": "first-item",
    "source": "same-definition",
    "previousOutcome": "failure"
  },
  "result": {
    "kind": "request-independence",
    "nextResult": "first-element-of-next-input",
    "previousFailureChangesNextOutcome": false
  },
  "pendingCases": [
    "Other interleavings of successful and failed requests require separate product cases."
  ]
}
```

<a id="lispex.example.v2.first-rule.next-input"></a>

### Use a new input after a failure

Mode: illustrative. Stage: semantic-request. Verification: not-run.

- language: `lispex`
- languageVersion: `2.0`

File: `source.scm`

```lispex
(module main
  (import)
  (export first-item)
  (entry first-item)
  (define first-item
    (lambda (items)
      (car items)))
)
```

File: `request.json`

```lispex
{
  "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"
    }
  ]
}
```

Fixture inputs and environment:

```json
{
  "entry": "source.scm",
  "argv": [],
  "stdin": "",
  "cwd": ".",
  "environment": [],
  "wrapper": null,
  "packageRef": null,
  "lockRef": null,
  "generatedBindingRefs": {
    "knowledgeState": "not-applicable",
    "values": []
  }
}
```

#### Expected result

```json
{
  "status": "unspecified",
  "reason": "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.

<a id="lispex.section.v2.first-rule.replay"></a>

## Replay

Use [replay](/v2.0/en/docs/profiles/receipt-and-replay#lispex.section.v2.receipt-and-replay.signatures-and-replay) to repeat first-item. Keep the complete [semantic request](/v2.0/en/docs/language/sandbox-contract#lispex.section.v2.sandbox-contract.semantic-request) and compare [canonical outcomes](/v2.0/en/docs/profiles/receipt-and-replay#lispex.section.v2.receipt-and-replay.canonical-outcome).

Retain [source and artifact identities](/v2.0/en/docs/profiles/receipt-and-replay#lispex.section.v2.receipt-and-replay.identities) and [execution and signature evidence](/v2.0/en/docs/profiles/receipt-and-replay#lispex.section.v2.receipt-and-replay.execution-evidence) using the definitions there.

The same replay procedure applies to the empty-input failure.

<a id="lispex.rule.v2.first-rule.exact-replay"></a>

### Repeat the complete request

Apply the [exact-replay rule](/v2.0/en/docs/profiles/receipt-and-replay#lispex.rule.v2.receipt-and-replay.exact-replay) 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.

<a id="lispex.claim.v2.first-rule.exact-replay"></a>

Claim: `lispex.claim.v2.first-rule.exact-replay` · interaction · coverage partial · verification not-run

- language: `lispex`
- languageVersion: `2.0`

```json
{
  "predicate": {
    "kind": "exact-semantic-request-replay",
    "entry": "first-item",
    "fixed": [
      "canonical-program",
      "canonical-input",
      "language-semantics",
      "standard-library",
      "unicode-semantics",
      "resource-model",
      "finite-limits"
    ]
  },
  "result": {
    "kind": "replay-equality",
    "comparison": "canonical-outcome",
    "sourceIdentity": "separate",
    "engineArtifactIdentity": "separate",
    "executionEvidence": "separate"
  },
  "pendingCases": [
    "Cross-engine and cross-architecture replay requires the corresponding released products."
  ]
}
```

<a id="lispex.example.v2.first-rule.replay-success"></a>

### Replay a successful request

Mode: illustrative. Stage: semantic-request. Verification: not-run.

- language: `lispex`
- languageVersion: `2.0`

File: `source.scm`

```lispex
(module main
  (import)
  (export first-item)
  (entry first-item)
  (define first-item
    (lambda (items)
      (car items)))
)
```

File: `request.json`

```lispex
{
  "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"
    }
  ]
}
```

Fixture inputs and environment:

```json
{
  "entry": "source.scm",
  "argv": [],
  "stdin": "",
  "cwd": ".",
  "environment": [],
  "wrapper": null,
  "packageRef": null,
  "lockRef": null,
  "generatedBindingRefs": {
    "knowledgeState": "not-applicable",
    "values": []
  }
}
```

#### Expected result

```json
{
  "status": "unspecified",
  "reason": "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.

<a id="lispex.example.v2.first-rule.replay-failure"></a>

### Replay a failing request

Mode: illustrative. Stage: semantic-request. Verification: not-run.

- language: `lispex`
- languageVersion: `2.0`

File: `source.scm`

```lispex
(module main
  (import)
  (export first-item)
  (entry first-item)
  (define first-item
    (lambda (items)
      (car items)))
)
```

File: `request.json`

```lispex
{
  "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"
    }
  ]
}
```

Fixture inputs and environment:

```json
{
  "entry": "source.scm",
  "argv": [],
  "stdin": "",
  "cwd": ".",
  "environment": [],
  "wrapper": null,
  "packageRef": null,
  "lockRef": null,
  "generatedBindingRefs": {
    "knowledgeState": "not-applicable",
    "values": []
  }
}
```

#### Expected result

```json
{
  "status": "unspecified",
  "reason": "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](/v2.0/en/docs/profiles/receipt-and-replay#lispex.rule.v2.receipt-and-replay.replay-request), [Identity domains and encoded inputs](/v2.0/en/docs/profiles/receipt-and-replay#lispex.rule.v2.receipt-and-replay.identity-encoding), [Artifact and package formats](/v2.0/en/docs/tools/embedding#lispex.rule.v2.embedding.artifact-format), [Outcome, preparation report, and receipt bytes](/v2.0/en/docs/profiles/receipt-and-replay#lispex.rule.v2.receipt-and-replay.outcome-format), [Resource model numbers](/v2.0/en/docs/language/resources#lispex.pending.v2.resources.model-numbers).

<a id="lispex.section.v2.first-rule.related"></a>

## Related chapters

[Sandbox contract](/v2.0/en/docs/language/sandbox-contract)

[Procedures](/v2.0/en/docs/language/procedures)

[Standard library](/v2.0/en/docs/library)

[Identity, receipt, replay](/v2.0/en/docs/profiles/receipt-and-replay)

[CLI and diagnostics](/v2.0/en/docs/tools/run)

<a id="lispex.pending.v2.resources.model-numbers"></a>

### Pending · Resource model numbers

The 2.0 tariff coefficients, logical allocation units, bit-size accounting, detailed frame accounting, finite defaults, representation limits, and physical memory envelopes remain open. This includes preparation, calls, values, exact arithmetic, equality, text, record conversion, and canonical encoding.

Profile host budget coefficients and defaults remain separate from language preparation and evaluation budgets. Trace capacity, reservation sizes, and host memory requirements retain their separate reporting scope. Each budget retains its own identity and accounting boundary.

Implementation and attack tests must support these choices. [Resource event declarations](/v2.0/en/docs/language/resources#lispex.rule.v2.resources.event-catalog) and [native kernel membership](/v2.0/en/docs/library#lispex.pending.v2.standard-library.kernel-and-cost-model) remain separate contracts.

<a id="lispex.pending.v2.standard-library.kernel-and-cost-model"></a>

### Pending · Native kernel membership

The final native kernel list and count remain open. Implementation and product attack tests must support these choices. [Tariff coefficients, allocation units, finite defaults, and physical envelopes](/v2.0/en/docs/language/resources#lispex.pending.v2.resources.model-numbers) are tracked once with the resource numbers.

## Related

[Sandbox contract](/v2.0/en/docs/language/sandbox-contract)

[Procedures](/v2.0/en/docs/language/procedures)

[Standard library](/v2.0/en/docs/library)

[Identity, receipt, replay](/v2.0/en/docs/profiles/receipt-and-replay)

[CLI and diagnostics](/v2.0/en/docs/tools/run)