engineering-argument-language 3.2.3__tar.gz

engineering_argument_language-3.2.3/.github/workflows/experiment-stage.yml

@@ -0,0 +1,110 @@
+name: EAL experiment stage
+on:
+  workflow_call:
+    inputs:
+      phase:
+        type: string
+        required: true
+      stage_name:
+        type: string
+        required: true
+      operation:
+        type: string
+        default: start
+      plan:
+        type: string
+        default: comparison
+      plan_path:
+        type: string
+        default: ''
+      source_artifact_id:
+        type: string
+        default: ''
+      annotation_labels:
+        type: string
+        default: ''
+      information_config:
+        type: string
+        default: ''
+      workers:
+        type: number
+        default: 0
+    secrets:
+      OPENAI_API_KEY:
+        required: false
+    outputs:
+      artifact_id:
+        description: Cumulative retained data or the frozen preflight plan
+        value: ${{ jobs.stage.outputs.artifact_id }}
+      can_collect:
+        description: True only when another bounded collection job is appropriate
+        value: ${{ jobs.stage.outputs.can_collect }}
+permissions:
+  contents: read
+  actions: read
+jobs:
+  stage:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 120
+    outputs:
+      artifact_id: ${{ steps.retain.outputs.artifact-id }}
+      can_collect: ${{ steps.execute.outputs.can_collect }}
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
+        with:
+          persist-credentials: false
+          ref: ${{ github.sha }}
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1
+        with:
+          python-version: '3.12.14'
+      - name: Install the pinned experiment runtime
+        run: python -m pip install -c experiments/model_transfer/requirements.lock -e .
+      - name: Execute the ordered stage
+        id: execute
+        env:
+          PIPELINE_PHASE: ${{ inputs.phase }}
+          PIPELINE_OPERATION: ${{ inputs.operation }}
+          TRANSFER_PLAN: ${{ inputs.plan }}
+          PLAN_PATH: ${{ inputs.plan_path }}
+          SOURCE_ARTIFACT_ID: ${{ inputs.source_artifact_id }}
+          ANNOTATION_LABELS: ${{ inputs.annotation_labels }}
+          INFORMATION_CONFIG: ${{ inputs.information_config }}
+          EXPERIMENT_WORKERS: ${{ inputs.workers }}
+          OPENAI_API_KEY: ${{ inputs.phase == 'collect' && secrets.OPENAI_API_KEY || '' }}
+          GH_TOKEN: ${{ github.token }}
+        run: python -m scripts.experiment_pipeline "$PIPELINE_PHASE"
+      - name: Retain this cumulative stage even after a failure
+        id: retain
+        if: ${{ always() && steps.execute.outputs.artifact_path != '' }}
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
+        with:
+          name: experiment-${{ inputs.stage_name }}-${{ github.run_id }}-${{ github.run_attempt }}
+          path: ${{ steps.execute.outputs.artifact_path }}
+          include-hidden-files: true
+          if-no-files-found: warn
+          retention-days: 90
+      - name: Retain calibration and scripted rehearsal records
+        if: ${{ always() && inputs.phase == 'prepare' && inputs.operation != 'resume' }}
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
+        with:
+          name: experiment-preflight-${{ github.run_id }}-${{ github.run_attempt }}
+          path: experiments/model_transfer/runs/preflight
+          include-hidden-files: true
+          if-no-files-found: warn
+          retention-days: 90
+      - name: Export only masked answer text for the independent assessor
+        id: masked
+        if: ${{ success() && inputs.phase == 'export' }}
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
+        with:
+          name: experiment-annotations-${{ github.run_id }}-${{ github.run_attempt }}
+          path: experiments/model_transfer/runs/live/annotation-bundle/items.json
+          if-no-files-found: warn
+          retention-days: 90
+      - name: Explain the result and the next required input
+        if: ${{ always() && steps.execute.outputs.artifact_path != '' }}
+        env:
+          PIPELINE_ARTIFACT_PATH: ${{ steps.execute.outputs.artifact_path }}
+          PIPELINE_ARTIFACT_ID: ${{ steps.retain.outputs.artifact-id }}
+          ANNOTATION_ARTIFACT_ID: ${{ steps.masked.outputs.artifact-id }}
+        run: python -m scripts.experiment_pipeline summary

engineering_argument_language-3.2.3/.github/workflows/experiment.yml

@@ -0,0 +1,114 @@
+name: EAL experiment
+run-name: EAL experiment — ${{ inputs.operation }} — ${{ inputs.plan }}
+on:
+  workflow_dispatch:
+    inputs:
+      operation:
+        description: 'start runs the pilot; finish imports labels and processes results; evaluate starts a separately budgeted evaluation'
+        type: choice
+        options: [start, resume, finish, evaluate, rehearse]
+        default: start
+      plan:
+        description: 'Pilot question (used only for start/rehearse); bundled plans have a USD 2 ceiling'
+        type: choice
+        options: [comparison, diagnostics, cadence, cadence-diagnostics, custom]
+        default: comparison
+      source_artifact_id:
+        description: 'Latest full artefact ID for resume/finish; planning artefact for evaluate; otherwise blank'
+        type: string
+        default: ''
+      annotation_labels:
+        description: 'For finish: repository path to completed labels JSON with declared human/AI assessor provenance'
+        type: string
+        default: ''
+      plan_path:
+        description: 'For a custom start/rehearse only: repository path to pilot plan'
+        type: string
+        default: ''
+      information_config:
+        description: 'For finish: optional repository path to a matching allocation configuration'
+        type: string
+        default: ''
+      workers:
+        description: '0 uses the plan (default 4); 1–8 overrides a new pilot; resume/evaluation preserve their allocation'
+        type: number
+        default: 0
+permissions:
+  contents: read
+  actions: read
+concurrency:
+  group: eal-experiment-${{ inputs.source_artifact_id || github.run_id }}
+  cancel-in-progress: false
+jobs:
+  verify:
+    uses: ./.github/workflows/verify.yml
+  prepare:
+    needs: verify
+    if: ${{ inputs.operation != 'finish' }}
+    uses: ./.github/workflows/experiment-stage.yml
+    with:
+      phase: prepare
+      stage_name: prepared
+      operation: ${{ inputs.operation }}
+      plan: ${{ inputs.plan }}
+      plan_path: ${{ inputs.plan_path }}
+      source_artifact_id: ${{ inputs.source_artifact_id }}
+      workers: ${{ inputs.workers }}
+  collect-1:
+    needs: prepare
+    if: ${{ needs.prepare.outputs.can_collect == 'true' }}
+    uses: ./.github/workflows/experiment-stage.yml
+    with:
+      phase: collect
+      stage_name: segment-1
+      source_artifact_id: ${{ needs.prepare.outputs.artifact_id }}
+    secrets:
+      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+  collect-2:
+    needs: collect-1
+    if: ${{ needs.collect-1.outputs.can_collect == 'true' }}
+    uses: ./.github/workflows/experiment-stage.yml
+    with:
+      phase: collect
+      stage_name: segment-2
+      source_artifact_id: ${{ needs.collect-1.outputs.artifact_id }}
+    secrets:
+      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+  collect-3:
+    needs: collect-2
+    if: ${{ needs.collect-2.outputs.can_collect == 'true' }}
+    uses: ./.github/workflows/experiment-stage.yml
+    with:
+      phase: collect
+      stage_name: segment-3
+      source_artifact_id: ${{ needs.collect-2.outputs.artifact_id }}
+    secrets:
+      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+  collect-4:
+    needs: collect-3
+    if: ${{ needs.collect-3.outputs.can_collect == 'true' }}
+    uses: ./.github/workflows/experiment-stage.yml
+    with:
+      phase: collect
+      stage_name: segment-4
+      source_artifact_id: ${{ needs.collect-3.outputs.artifact_id }}
+    secrets:
+      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+  export:
+    needs: [prepare, collect-1, collect-2, collect-3, collect-4]
+    if: ${{ !cancelled() && needs.prepare.result == 'success' && inputs.operation != 'rehearse' }}
+    uses: ./.github/workflows/experiment-stage.yml
+    with:
+      phase: export
+      stage_name: export
+      source_artifact_id: ${{ needs.collect-4.outputs.artifact_id || needs.collect-3.outputs.artifact_id || needs.collect-2.outputs.artifact_id || needs.collect-1.outputs.artifact_id || needs.prepare.outputs.artifact_id }}
+  finish:
+    needs: verify
+    if: ${{ inputs.operation == 'finish' }}
+    uses: ./.github/workflows/experiment-stage.yml
+    with:
+      phase: finish
+      stage_name: finish
+      source_artifact_id: ${{ inputs.source_artifact_id }}
+      annotation_labels: ${{ inputs.annotation_labels }}
+      information_config: ${{ inputs.information_config }}

engineering_argument_language-3.2.3/.github/workflows/publish.yml

@@ -0,0 +1,191 @@
+name: EAL package release
+
+on:
+  workflow_dispatch:
+    inputs:
+      release_tag:
+        description: 'Existing release tag; dispatch this workflow on the same tag'
+        type: string
+        required: true
+        default: v3.2.3
+      destination:
+        description: 'Verify artefacts, or publish the verified artefacts to the selected index'
+        type: choice
+        options: [verify, testpypi, pypi]
+        default: verify
+
+permissions:
+  contents: read
+
+concurrency:
+  group: package-${{ inputs.release_tag }}-${{ inputs.destination }}
+  cancel-in-progress: false
+
+jobs:
+  resolve:
+    name: Validate release tag and version
+    runs-on: ubuntu-24.04
+    timeout-minutes: 5
+    outputs:
+      commit: ${{ steps.release.outputs.commit }}
+      version: ${{ steps.release.outputs.version }}
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          ref: ${{ github.sha }}
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: '3.12'
+      - name: Resolve the matching tag to an immutable commit on main
+        id: release
+        env:
+          RELEASE_TAG: ${{ inputs.release_tag }}
+          DISPATCH_REF: ${{ github.ref }}
+          DISPATCH_SHA: ${{ github.sha }}
+        run: >-
+          python scripts/check_release_tag.py "$RELEASE_TAG"
+          --dispatch-ref "$DISPATCH_REF" --dispatch-sha "$DISPATCH_SHA"
+          --github-output "$GITHUB_OUTPUT"
+
+  full-check:
+    name: Verify parser, tests and maintained example
+    needs: resolve
+    runs-on: ubuntu-24.04
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          ref: ${{ needs.resolve.outputs.commit }}
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: '3.12.14'
+      - name: Install constrained package and test dependencies
+        run: python -m pip install -c experiments/model_transfer/requirements.lock '.[dev,release]'
+      - name: Check parser, scientific contracts, tests and maintained example
+        run: make check PYTHON=python
+
+  build:
+    name: Build one wheel and source distribution
+    needs: resolve
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    outputs:
+      artifact-id: ${{ steps.distributions.outputs.artifact-id }}
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          ref: ${{ needs.resolve.outputs.commit }}
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: '3.12'
+      - name: Install package and release tools
+        run: python -m pip install -c experiments/model_transfer/requirements.lock '.[release]'
+      - name: Build and check distribution metadata
+        run: |
+          make build PYTHON=python
+          python -m twine check --strict dist/*.whl dist/*.tar.gz
+          sha256sum dist/*.whl dist/*.tar.gz > SHA256SUMS
+      - name: Retain immutable distributions and their checksums
+        id: distributions
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: python-distributions-${{ github.run_id }}-${{ github.run_attempt }}
+          path: |
+            dist/*.whl
+            dist/*.tar.gz
+            SHA256SUMS
+          if-no-files-found: error
+          retention-days: 14
+
+  installed-package:
+    name: Installed package (${{ matrix.os }}, Python ${{ matrix.python }})
+    needs: [resolve, build]
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - {os: ubuntu-24.04, python: '3.11'}
+          - {os: ubuntu-24.04, python: '3.12'}
+          - {os: ubuntu-24.04, python: '3.13'}
+          - {os: ubuntu-24.04, python: '3.14'}
+          - {os: macos-14, python: '3.12'}
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          ref: ${{ needs.resolve.outputs.commit }}
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Retrieve the exact built distributions from this run
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          artifact-ids: ${{ needs.build.outputs.artifact-id }}
+          merge-multiple: true
+          path: release-artifacts
+      - name: Check distribution bytes
+        working-directory: release-artifacts
+        run: shasum -a 256 --check SHA256SUMS
+      - name: Install each distribution outside the checkout and exercise the public interfaces
+        env:
+          RELEASE_VERSION: ${{ needs.resolve.outputs.version }}
+        run: >-
+          python scripts/check_distribution.py release-artifacts/dist
+          --expected-version "$RELEASE_VERSION"
+
+  publish-testpypi:
+    name: Publish verified distributions to TestPyPI
+    if: ${{ inputs.destination == 'testpypi' }}
+    needs: [resolve, full-check, build, installed-package]
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/engineering-argument-language
+    permissions:
+      id-token: write
+    steps:
+      - name: Retrieve the exact verified distributions from this run
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          artifact-ids: ${{ needs.build.outputs.artifact-id }}
+          merge-multiple: true
+      - name: Check distribution bytes before publication
+        run: sha256sum --check --strict SHA256SUMS
+      - name: Publish through the TestPyPI Trusted Publisher
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          packages-dir: dist/
+          attestations: true
+
+  publish-pypi:
+    name: Publish verified distributions to PyPI
+    if: ${{ inputs.destination == 'pypi' }}
+    needs: [resolve, full-check, build, installed-package]
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    environment:
+      name: pypi.org
+      url: https://pypi.org/p/engineering-argument-language
+    permissions:
+      id-token: write
+    steps:
+      - name: Retrieve the exact verified distributions from this run
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          artifact-ids: ${{ needs.build.outputs.artifact-id }}
+          merge-multiple: true
+      - name: Check distribution bytes before publication
+        run: sha256sum --check --strict SHA256SUMS
+      - name: Publish through the PyPI Trusted Publisher
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          packages-dir: dist/
+          attestations: true

engineering_argument_language-3.2.3/.github/workflows/test.yml

@@ -0,0 +1,94 @@
+name: EAL tests
+on:
+  workflow_dispatch:
+    inputs:
+      model_transfer:
+        description: 'Run an experiment stage after tests (only collect calls the API)'
+        type: boolean
+        default: false
+      model_transfer_plan:
+        description: 'Principal, reasoning or evidence-cadence pilot; each has a USD 2 ceiling'
+        type: choice
+        options:
+          - comparison
+          - diagnostics
+          - cadence
+          - cadence-diagnostics
+          - custom
+        default: comparison
+      experiment_action:
+        description: 'Stage: collect/resume, free rehearsal/calibration, or offline processing'
+        type: choice
+        options: [collect, calibrate, rehearse, export-annotations, import-annotations, analyse, plan]
+        default: collect
+      plan_path:
+        description: 'Custom plan: repository path, or path within source artefact; ignored on resume'
+        type: string
+        default: ''
+      source_artifact_id:
+        description: 'Numeric artefact ID from this repository for resume or offline stages'
+        type: string
+        default: ''
+      resume_run:
+        description: 'Continue the frozen retained run; keep its cumulative budget and worker count'
+        type: boolean
+        default: false
+      segment_seconds:
+        description: 'Collection allowance for this job, 1–6000 seconds; remaining time saves artefacts'
+        type: number
+        default: 6000
+      annotation_labels:
+        description: 'Repository path to completed labels for import-annotations'
+        type: string
+        default: ''
+      information_config:
+        description: 'Optional repository path to prospective allocation configuration'
+        type: string
+        default: ''
+      workers:
+        description: '0 uses the plan (default 4); 1–8 overrides pilot workers; ignored for resume'
+        type: number
+        default: 0
+permissions:
+  contents: read
+  actions: read
+jobs:
+  test:
+    uses: ./.github/workflows/verify.yml
+  model-transfer:
+    if: ${{ inputs.model_transfer }}
+    needs: test
+    runs-on: ubuntu-24.04
+    timeout-minutes: 120
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1
+        with:
+          python-version: '3.12.14'
+      - name: Install package
+        run: python -m pip install -c experiments/model_transfer/requirements.lock -e .
+      - name: Run the selected experiment stage
+        env:
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          TRANSFER_PLAN: ${{ inputs.model_transfer_plan }}
+          EXPERIMENT_ACTION: ${{ inputs.experiment_action }}
+          PLAN_PATH: ${{ inputs.plan_path }}
+          SOURCE_ARTIFACT_ID: ${{ inputs.source_artifact_id }}
+          RESUME_RUN: ${{ inputs.resume_run }}
+          SEGMENT_SECONDS: ${{ inputs.segment_seconds }}
+          ANNOTATION_LABELS: ${{ inputs.annotation_labels }}
+          INFORMATION_CONFIG: ${{ inputs.information_config }}
+          EXPERIMENT_WORKERS: ${{ inputs.workers }}
+          GH_TOKEN: ${{ github.token }}
+        run: python -m experiments.model_transfer.workflow
+      - name: Retain every attempt and the report
+        if: ${{ always() }}
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
+        with:
+          name: model-transfer-${{ github.run_id }}-${{ github.run_attempt }}
+          path: experiments/model_transfer/runs/live
+          include-hidden-files: true
+          if-no-files-found: warn
+          retention-days: 90

engineering_argument_language-3.2.3/.github/workflows/verify.yml

@@ -0,0 +1,23 @@
+name: EAL verification
+on:
+  workflow_call:
+permissions:
+  contents: read
+jobs:
+  verify:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+          ref: ${{ github.sha }}
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: '3.12.14'
+      - name: Install package and test dependencies
+        run: python -m pip install -c experiments/model_transfer/requirements.lock -e '.[dev]'
+      - name: Check parser, scientific contracts, tests and maintained example
+        run: make check
+      - name: Build distribution
+        run: make build

engineering_argument_language-3.2.3/AGENTS.md

@@ -0,0 +1,13 @@
+# Project instructions
+
+EAL/3 is the only supported language. Backwards compatibility is never a requirement for this project. Choose the clearest coherent design for the current language; remove obsolete syntax, version-dependent semantics, aliases and compatibility adapters rather than preserving them. Do not add migration machinery solely to support an earlier EAL version.
+
+Apply each change across affected current documentation, discovery schemas and the single API load-test example. Document the present contract and implementation; keep revision history in Git rather than explanatory pages. Keep the maintained example self-contained and clearly distinguish synthetic data from measurements. Focus validation on discovering registered EAL files, reusing compatible observations across sessions and models, and reaching the right scoped output with fewer repeated calls. A source-language version, package version and observation schema version identify different contracts; declare changes to each affected contract explicitly.
+
+Use the repository's `skills/engineer-argumentation-languages/SKILL.md` and its expert language design reference for changes to syntax, abstractions, method contracts or reasoning semantics. Separate primary-source recommendations, EAL design decisions, implemented behaviour and measured results.
+
+Keep one versioned reasoning-method selector: `method "name/version"`. A tool declaration names an interface version; its operational characteristics belong to the trusted host binding and the recorded acquisition, not an EAL `mode` clause. Built-in and installed reasoning methods follow the same typed contracts and binding checks.
+
+Reusable argument patterns use typed parameters with closed lexical scope. Expansion must preserve evidence, claim and assumption identity and the qualifications of an ordinary argument. Retain source locations in diagnostics and canonical parse–format–parse meaning.
+
+Do not infer model capability, comprehension gains or cost savings from a working interpreter alone. Measurements require actual trials and retained outcomes, including failures. Keep GitHub workflows manually triggered.

engineering_argument_language-3.2.3/CONTRACT.md

@@ -0,0 +1,89 @@
+# EAL/3 integration contract
+
+EAL/3 is the supported source language. The Python distribution is `engineering-argument-language` version `3.2.3`, imported as `eal`, and its source notation uses newline-terminated fields and typed flows. The source language, persisted `EAL/observation-record/1`, typed `EAL/typed-input/1`, compact `EAL/assessment-packet/2` and registered `EAL/registered-assessment/1` results are separate contracts. See [language syntax](docs/language.md), [reasoning modes](docs/reasoning-modes.md) and the [argument service](docs/argument-service.md).
+
+Source fields use newlines, contexts resolve metadata defaults, and typed support flows lower to the existing argument model. Package, source notation and stored observation versions remain separate. Strictness, ranks and contraries retain their opt-in ASPIC+ compilation effects.
+
+## Distribution and supported Python imports
+
+The distribution installs the `eal` Python package and the `eal`, `eal-mcp` and `eal-host` console commands. The supported application imports are the documented interfaces in `eal.knowledge`, `eal.runtime`, `eal.parser`, `eal.semantics`, `eal.formatter`, `eal.evaluator`, `eal.methods` and `eal.limits`; [packaging and releases](docs/packaging.md#python-integration) gives their exact import paths. Private helpers, generated-parser internals and database tables are implementation details. A package version identifies the distributed implementation; the source and record schema identifiers identify their own contracts. Integrators pin a reviewed package version and check the current contract when upgrading. The project develops the current EAL/3 contract without a promise of backwards compatibility.
+
+Python 3.11 or later is required. Command collectors and bounded custom-method workers require POSIX process and resource facilities. The release workflow is configured to install both the wheel and source distribution outside the checkout and exercise the public imports, console commands and MCP on Linux and macOS. The [Unlicense](LICENSE) covers original EARL software; third-party terms and the scope of repository materials are described in [licence scope](docs/packaging.md#licence-scope).
+
+
+## Authored source and observations
+
+`parse(source: str) -> Program` parses exact EAL/3 UTF-8 text; `validate(program, *, registry=None)` returns structured diagnostics for references, types and method contracts. `format_source(source)` returns canonical source. `Program.source_digest` hashes exact source bytes, even when two programs have the same meaning.
+
+An EAL a `tool NAME` block containing `version "VERSION"` declares an interface. An `evidence NAME` selects that tool, evidence `kind`, `environment`, `max_age` in seconds, optional JSON `input` and one or more `require "VALUE.FIELD" OP SCALAR` predicates. A `reasoning NAME` selects exactly one installed versioned method, rationale, optional evidence `backing` and optional output predicates. Claims, arguments, premises, assumptions, objections, patterns and optional formal directives state the argument graph. The host never treats prose as a mechanically proven warrant.
+
+An observation is not an EAL declaration. The configured tool returns JSON with `value` and optional `observed_at`, `context`, `request` and `details`; a file import must provide the latter acquisition fields and original time. The host persists the observation under `EAL/observation-record/1` with evidence ID, kind, environment, tool/version, input and request identity, context, source digest, original time, result digest, binding identity and a durable run ID. The original time is never advanced by reuse. A command receives one JSON object with `evidence_id`, `environment`, `tool`, `tool_version`, `input` and `context` on stdin and returns one JSON object on stdout. EAL source cannot select a command, file path, credential or Python method implementation.
+
+`evidence.max_age` checks observation freshness at assessment time. `assumption.valid_from` and `valid_until` define a half-open interval during which that assumption may apply; its `validate` clause names an evidence declaration. These are independent clocks: recollecting evidence cannot extend an expired assumption. An absent, stale, invalid or failed observation cannot establish a negative result. A complete negative measurement may support an explicitly authored negative route.
+
+## Operator tool bindings and method contracts
+
+A sibling TOML registry binds a declared name/version to `command` (`argv`) or `json_file` (`path`). Command settings include timeout, output bound, optional explicit `env`, `inherit_env`, pinned files and `parallel_safe`. Commands run with host permissions; `parallel_safe = true` asserts independent read-only calls, which the bounded scheduler may overlap while serial calls remain barriers. A configured command may authenticate or query an external system. The application controls executable code and credentials through the registry and host environment.
+
+The selected binding has a keyed identity. Command records also carry a keyed digest of the effective process environment, including selected inherited variables and explicit overrides. A default command inherits the full host environment; `inherit_env = ["PATH", "KUBECONFIG"]` narrows it to selected names. A changed tool binding, pinned dependency or effective environment makes prior output ineligible for automatic reuse. The store-local private binding key accompanies a moved database. Current binding checks are performed when reasoning over stored collections.
+
+The default method registry contains `structured/1`, `deductive/1`, `inductive/1`, `abductive/1`, `causal/1`, `counterfactual/1`, `analogical/1` and `temporal/1`. Each method has a typed input kind, resource bound, computation and output interpretation. Computational methods use exactly one suitable designated observation from direct evidence, reasoning backing and assumption validation; an argument premise remains a separate claim dependency. `MethodContract` and `MethodRegistry.with_method` install additional immutable host methods; `--methods package.module:function` loads a trusted factory. A source selects a method ID, never code. The optional `eal.aspic:aspic_registry` installs a bounded formal ASPIC+ method, and `compile_eal_aspic` derives a separate formal snapshot from checked EAL routes.
+
+## Persistent developer knowledge
+
+`EALKnowledgeBase(workspace, registry_path=None, database_path=None, *, method_registry=None)` composes `ReasoningService`, `WorkspaceKnowledgeCatalogue` and `RegisteredAssessmentHost`. The default SQLite path is `.eal/runs.sqlite3` under the workspace. `register(path, *, entry_id=None, context=None, claims=None, label=None)` stores a validated workspace `.eal` file under a stable developer ID (the relative path by default), default context and selected claim IDs. A valid file edit creates an immutable source/method revision; an invalid edit fails without replacing a historical revision. `register_tree`, `sources`, `find`, `history` and catalogue `revisions` support bounded discovery and prior-run lookup. Search results are advisory metadata; assessment takes an exact entry ID and selected claim.
+
+`EALKnowledgeBase.assess(entry_id, claim, *, context=None, now=None, reuse="compatible")` plans the complete authored support and objection closure. For each evidence ID it selects a successful stored observation only if its request, tool binding, execution environment, context, kind and original age remain compatible. It collects missing or expired evidence, stores a new source-bound collection, evaluates the declared methods at the supplied timezone-aware time or current UTC, and returns status, identities, reused/collected counts, a bounded packet and full-explanation reference. Compatible prior observations may come from different sessions and source revisions. `reuse="fresh"` is an explicit operator request to reacquire every selected evidence ID. A prior claim status is never silently substituted for the current assessment.
+
+`ModelContextAdapter(knowledge).prepare(question, entry_id, claim, *, context=None, now=None, reuse="compatible")` returns `EAL/model-context/2` with the checked assessment and two prompt messages: bounded host context and the developer's question. The application chooses the entry and claim; free-form model text does not choose tools. It retains the host status separately from any generated prose. Model-facing MCP registered assessment uses the entry's stored context and exact claim selection, without a caller context override.
+
+## Lower-level Python, CLI and MCP
+
+`ReasoningService.plan(source, claim)` returns ordered evidence IDs, method-registry and source identities, calls and graph dependencies. `collect_claim(source, context, claim)` executes that closure. `collect(source, context, evidence_ids=None)` collects an explicit subset or all declarations. `reason(source, context, collection_id=None, now=None)` evaluates a matching stored collection; `packet(assessment_id, claim=None)` returns a bounded `EAL/assessment-packet/2`; `explain(assessment_id, claim=None)` retrieves the persisted assessment. `validate`, `format`, `describe` and optional `compile_aspic` share the same contracts. Pure `evaluate(program, records, *, now, context, registry=None, binding_digests=None)` performs no implicit acquisition or clock selection.
+
+The CLI exposes `register`, `register-tree`, `sources`, `find`, `assess-known`, `history`, `model-context`, `validate`, `format`, `plan`, `collect`, `reason`, `packet`, `explain`, `grounded`, `compile-aspic` and `export-aspic`. The generic MCP server exposes the corresponding source-level operations. Starting `eal-mcp` with one or more `--known-entry ENTRY_ID` options instead exposes only `eal_sources`, `eal_find_claims` and `eal_assess_known` for those registered entries; it does not expose raw explanation or source-level collection on that endpoint. `eal-host --known-entry ENTRY_ID` accepts a single strict JSON text request through the same MCP server for a model without native tools.
+
+FastMCP `4.0.10` supplies stdio and Streamable HTTP transports through MCP Python SDK `2.2.0`. A shared operation contract defines names and permitted fields; the operation catalogue binds typed handlers and exposure selection. FastMCP derives their schemas, which the strict JSON host discovers and checks before invocation. Both transports reject extra fields and invalid JSON types before handler invocation and expose equivalent application results. Protocol negotiation and HTTP authentication belong to the transport adapter; EAL assessment semantics remain in the SDK-independent service. The supported protocol paths include the `2025-11-25` handshake and `2026-07-28` discovery profiles.
+
+`eal-mcp --config FILE` loads validated `[service]`, `[server]` and `[server.http]` TOML settings. Precedence is CLI > `EAL_MCP_*` environment > TOML > defaults. File-supplied paths are relative to the configuration file's directory; CLI/environment paths are relative to the working directory. `--transport stdio|http` selects one transport per process. `--exposure operator|registered` must agree with the configured entry selection; absent an explicit exposure, a non-empty selection chooses registered exposure. Transport selection does not alter tool exposure. `--max-in-flight` defaults to one admitted tool call per process.
+
+The HTTP runner always enables strict Host/Origin protection before MCP handling. Accepted hosts include FastMCP's loopback defaults, the configured host, the actual bound address and `allowed_hosts` additions. Supplied origins must match the request's origin, qualify as loopback on a loopback request, or appear in `allowed_origins`. Untrusted Host and Origin headers receive HTTP 421 and 403 respectively. `[server.http].allowed_hosts` and `.allowed_origins` contain up to 128 unique literal entries each; repeated `--allowed-host` / `--allowed-origin` options and JSON-array `EAL_MCP_ALLOWED_HOSTS` / `EAL_MCP_ALLOWED_ORIGINS` variables follow normal precedence. Wildcards are rejected.
+
+Non-loopback HTTP binds and additional non-loopback trusted hosts/origins require `--token-env NAME` or `[server.http].token_env`, including public proxies forwarding to loopback. Startup reads the token from that environment variable; settings and source contain only its name. The bearer credential grants access to the endpoint's fixed operator workspace or registered-entry allowlist. The service implements one host trust domain per endpoint. HTTP clients use `eal-host --url URL [--token-env NAME]`; this connects to an already running service and treats the credential as an opaque bearer value. The host's default route launches a stdio subprocess, and its flat JSON `compile_aspic` operation uses the same checked contract as `eal_compile_aspic`. Credential sanitisation preserves JSON field names and public host metadata, while redacting application string values and diagnostics, including values in JSON-bearing content text. See [MCP and tools](docs/mcp-and-tools.md) for settings and examples.
+
+Collections bind exact source bytes and context. The evaluator reports `supported`, `contested`, `unsupported` or `out_of_scope` for claims; it also returns named argument, evidence, assumption, objection and reasoning results. Objections and support dependencies are solved under the finite authored argument model. An `unsupported` result does not assert the opposite claim. Typed propositions check formal correspondence and result predicates within the installed method's limits; human review remains responsible for whether an authored claim and its measurement answer the intended engineering question.
+
+## Bounds and persistence
+
+Source/graph/construction/search budgets are operator-owned `ExecutionLimits`. CLI, MCP and JSON launchers accept `--limits FILE`; source cannot raise them. `[limits]` TOML values are positive integers. Discovery advertises the selected budgets. Compile/export captures them in the checked snapshot, and exporting under a smaller current host budget is rejected. An exhausted calculation is incomplete and supplies no accepted or rejected conclusion. See [scoped composition](docs/eal3-composition.md).
+
+Collection preflight bounds context JSON to 16 KiB, a host-configurable evidence count (default 128) and each request to 1 MiB. The sum of configured tool output allowances is at most 128 MiB, individual command outputs at most 16 MiB, and the final collection JSON at most 32 MiB. Packet output defaults to a 16 KiB bound with explicit omission counts; it excludes raw observation values, command streams and arbitrary extension outputs. SQLite stores immutable observations, collections and assessments under private files. Stored records remain historical results; a new assessment checks current source, method, binding and observation freshness. See [MCP and tools](docs/mcp-and-tools.md) for exact adapter envelopes and failure handling.
+
+A workspace acquisition lease coordinates MCP collection and registered-assessment reuse checks across threads and server processes on a local filesystem. It prevents overlapping acquisitions through the participating MCP services; eligible `parallel_safe` collectors may still overlap within one admitted acquisition. A POSIX command supervisor inherits the lock descriptor and retains it until its collector process group has stopped and been reaped, including after a host deadline or abrupt server termination. Normal collector completion also cleans up residual group members. Configured commands must keep descendants in the owned process group; remotely started work requires separate ownership and cancellation. Command execution requires POSIX and the host's permissions.
+
+Processes launched with stdio and HTTP can share that workspace and database. A private sibling store lock serialises binding-key, WAL, schema and observation-index initialisation during concurrent startup. SQLite connections close after commit or rollback. This coordination contract covers a single local filesystem; distributed replicas and network filesystems require a different coordinator. Admission limits and acquisition leases constrain execution; throughput and model-cost improvements require measurements.
+
+## Investigation contracts
+
+Protocol 5.0.0 uses primary plan/report `/4`, diagnostic plan/report `/2`, and
+information-design configuration/result `/2`. These experiment contracts do not
+change EAL/3 semantics. The default population contains six evaluation cases;
+eight threshold cases serve calibration only. A frozen
+`EAL/evaluation-task-manifest/1` records independently supplied task provenance,
+reference-checked answer keys and explicit evidence revisions. Revisions enter
+assessment context so incompatible snapshots cannot be reused.
+
+Correctness inference uses independent paired trajectories and prospectively
+selected empirical Bernstein bounds. Unknown outcomes retain their planned
+units and completion envelopes. Simultaneous estimation and the one-sided
+intersection-union adoption decision are separate outputs. Resource inference
+is approximate; allocation requires declared nuisance scenarios and fresh-seed
+Monte Carlo calibration. Scripted runs cannot produce an empirical evaluation
+allocation.
+
+Matched-fact diagnostics independently vary withheld, EAL-derived and conventional
+conclusions. Failed manipulation checks retain observations and costs but block
+component attribution. The optional `EAL/adoption-cost-ledger/1` binds measured
+activity to a run and plan digest; missing rates or coverage remain unknown.
+See [methodology](docs/eal3-experiment-methodology.md) and
+[verification](experiments/model_transfer/verification.md).