f-layer 2.0.0__tar.gz

f_layer-2.0.0/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

f_layer-2.0.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,41 @@
+name: Bug report
+description: Report reproducible incorrect F-Layer behavior
+title: ""
+labels: []
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Do not include credentials, tokens, private keys, or private infrastructure identifiers.
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: What went wrong?
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Reproduction
+      description: Provide the smallest safe reproduction that does not expose secrets or unrelated infrastructure.
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: F-Layer version/commit, OS, runtime version, provider type, and other relevant non-secret context.
+    validations:
+      required: true
+  - type: textarea
+    id: evidence
+    attributes:
+      label: Evidence
+      description: Sanitized logs, trace output, failing test, or other deterministic evidence.

f_layer-2.0.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,2 @@
+blank_issues_enabled: false
+contact_links: []

f_layer-2.0.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,31 @@
+name: Feature request
+description: Propose a new F-Layer capability or contract
+title: ""
+labels: []
+body:
+  - type: textarea
+    id: outcome
+    attributes:
+      label: Desired outcome
+      description: What should become possible after this feature exists?
+    validations:
+      required: true
+  - type: textarea
+    id: scope
+    attributes:
+      label: Scope
+      description: Which core/provider/deployment/integration boundary does this affect?
+    validations:
+      required: true
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: Acceptance criteria
+      description: What observable evidence would prove the feature complete?
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Existing approaches, workarounds, or related contracts.

f_layer-2.0.0/.github/pull_request_template.md

@@ -0,0 +1,15 @@
+## Summary
+
+<!-- What changed and why? -->
+
+## Validation
+
+<!-- List the checks or tests actually run and their results. -->
+
+## Security / infrastructure impact
+
+<!-- Note any cloud mutation, credential, generated-artifact, routing, compatibility, or lifecycle implications. Write "None" when not applicable. -->
+
+## Issue
+
+Closes #

f_layer-2.0.0/.github/workflows/close-linked-tasks.yml

@@ -0,0 +1,86 @@
+name: Close linked Tasks after merge
+
+on:
+  pull_request:
+    types:
+      - closed
+    branches:
+      - develop
+      - master
+
+permissions:
+  contents: write
+  issues: write
+  pull-requests: read
+
+jobs:
+  close-linked-tasks:
+    if: github.event.pull_request.merged == true
+    runs-on: ubuntu-latest
+    env:
+      GH_TOKEN: ${{ github.token }}
+      GH_REPO: ${{ github.repository }}
+      PR_NUMBER: ${{ github.event.pull_request.number }}
+      PR_URL: ${{ github.event.pull_request.html_url }}
+      PR_BODY: ${{ github.event.pull_request.body }}
+      HEAD_REF: ${{ github.event.pull_request.head.ref }}
+      BASE_REF: ${{ github.event.pull_request.base.ref }}
+
+    steps:
+      - name: Check out merged base
+        uses: actions/checkout@v5
+        with:
+          ref: ${{ github.event.pull_request.base.ref }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Close explicitly linked Task issues
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          mapfile -t linked_issues < <(python tools/pr_merge_links.py)
+
+          for issue_number in "${linked_issues[@]}"; do
+            issue="$(gh api "repos/$GH_REPO/issues/$issue_number")"
+
+            if [ "$(printf '%s' "$issue" | jq -r 'has("pull_request")')" = "true" ]; then
+              continue
+            fi
+
+            issue_type="$(printf '%s' "$issue" | jq -r '.type.name // ""')"
+            issue_state="$(printf '%s' "$issue" | jq -r '.state')"
+
+            if [ "$issue_type" != "Task" ] || [ "$issue_state" = "closed" ]; then
+              continue
+            fi
+
+            comment="$(jq -nc \
+              --arg body "Implemented by merged PR #$PR_NUMBER ($PR_URL). Automatically marked completed after merge into $BASE_REF." \
+              '{body:$body}')"
+
+            printf '%s' "$comment" | gh api \
+              --method POST \
+              "repos/$GH_REPO/issues/$issue_number/comments" \
+              --input - >/dev/null
+
+            printf '%s' '{"state":"closed","state_reason":"completed"}' | gh api \
+              --method PATCH \
+              "repos/$GH_REPO/issues/$issue_number" \
+              --input - >/dev/null
+          done
+
+      - name: Delete merged same-repository branch
+        if: >-
+          github.event.pull_request.head.repo.full_name == github.repository &&
+          github.event.pull_request.head.ref != 'master' &&
+          github.event.pull_request.head.ref != 'develop' &&
+          github.event.pull_request.head.ref != github.event.pull_request.base.ref
+        shell: bash
+        run: |
+          set -euo pipefail
+          encoded_ref="${HEAD_REF//\//%2F}"
+          gh api --method DELETE "repos/$GH_REPO/git/refs/heads/$encoded_ref" || true

f_layer-2.0.0/.github/workflows/documentation-gates.yml

@@ -0,0 +1,78 @@
+name: Documentation quality gates
+
+on:
+  pull_request:
+    branches: [develop, master]
+  push:
+    branches: [develop, master]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: documentation-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build-documentation:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+          cache: pip
+          cache-dependency-path: docs/requirements-api.txt
+      - name: Install exact documentation and test tools
+        run: |
+          python -m pip install --requirement docs/requirements-api.txt
+          python -m pip install -e '.[dev]'
+      - name: Test documentation failure contracts
+        run: PYTHONPATH=src:. python -m pytest --no-cov tests/unit/test_documentation*.py tests/unit/test_locale*.py
+      - name: Validate authored locale identity and review evidence
+        run: |
+          python -m tools.locale_documentation validate \
+            --output _build/documentation-gates/locales.json
+      - name: Build strict reference from a clean installed wheel
+        run: python -m tools.build_locale_sites --require-complete-translations
+      - name: Upload previewable documentation
+        uses: actions/upload-artifact@v4
+        with:
+          name: flayer-documentation-preview
+          path: _build/api-reference/site
+          if-no-files-found: error
+      - name: Upload documentation evidence
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: flayer-documentation-evidence
+          path: |
+            _build/documentation-gates
+            _build/api-reference/build-evidence.json
+            _build/api-reference/api-locales.json
+            _build/api-reference/repository-coverage.json
+          if-no-files-found: warn
+      - name: Upload official Pages artifact
+        if: github.event_name == 'push' && github.ref == 'refs/heads/master'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: _build/api-reference/site
+
+  deploy-pages:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/master'
+    needs: build-documentation
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy verified master-branch documentation
+        id: deployment
+        uses: actions/deploy-pages@v4

f_layer-2.0.0/.github/workflows/python-quality.yml

@@ -0,0 +1,60 @@
+name: Python quality
+
+on:
+  pull_request:
+    branches:
+      - develop
+      - master
+  push:
+    branches:
+      - develop
+      - master
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    name: Python quality
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Install project and development dependencies
+        run: python -m pip install -e ".[dev]"
+
+      - name: Fetch checksum-pinned Xray for isolated routing tests
+        run: |
+          python - <<'PYTHON'
+          import hashlib
+          import io
+          from pathlib import Path
+          import urllib.request
+          import zipfile
+          from flayer.profiles._vless_guest import ARCHIVES, XRAY_VERSION
+
+          name, digest = ARCHIVES["x86_64"]
+          url = f"https://github.com/XTLS/Xray-core/releases/download/v{XRAY_VERSION}/{name}"
+          with urllib.request.urlopen(url, timeout=120) as response:
+              archive = response.read()
+          if hashlib.sha256(archive).hexdigest() != digest:
+              raise SystemExit("Xray archive checksum mismatch")
+          destination = Path("_build/xray/xray")
+          destination.parent.mkdir(parents=True, exist_ok=True)
+          with zipfile.ZipFile(io.BytesIO(archive)) as bundle:
+              destination.write_bytes(bundle.read("xray"))
+          destination.chmod(0o700)
+          PYTHON
+
+      - name: Run the canonical local and CI validation gate
+        env:
+          FLAYER_XRAY_BINARY: ${{ github.workspace }}/_build/xray/xray
+        run: python tools/validate.py

f_layer-2.0.0/.github/workflows/release-publish.yml

@@ -0,0 +1,111 @@
+name: Publish an owner-approved PyPI release
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Existing annotated vX.Y.Z tag owning the current master commit'
+        required: true
+        type: string
+      milestone:
+        description: 'Native release-X.Y milestone number; must be closed with no open items'
+        required: true
+        type: string
+      confirm_publication:
+        description: 'Publish the validated distributions to production PyPI'
+        required: true
+        default: false
+        type: boolean
+
+permissions:
+  contents: read
+  issues: read
+
+concurrency:
+  group: flayer-pypi-publication
+  cancel-in-progress: false
+
+jobs:
+  validate-release:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - name: Check out the selected workflow revision and local tag history
+        uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Set up Python
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: '3.11'
+      - name: Install the pinned development and build tools
+        run: python -m pip install -e '.[dev]'
+      - name: Require completed milestone acceptance before validation or publication
+        env:
+          GH_TOKEN: ${{ github.token }}
+          FLAYER_RELEASE_MILESTONE: ${{ inputs.milestone }}
+        run: python tools/release_validation.py --check-milestone "$FLAYER_RELEASE_MILESTONE"
+      - name: Run the canonical full validation gate
+        run: python tools/validate.py
+      - name: Recheck milestone acceptance, owner consent, tag ownership and artifacts
+        env:
+          GH_TOKEN: ${{ github.token }}
+          FLAYER_RELEASE_MILESTONE: ${{ inputs.milestone }}
+          FLAYER_RELEASE_TAG: ${{ inputs.tag }}
+          FLAYER_CONFIRM_PUBLICATION: ${{ inputs.confirm_publication }}
+          FLAYER_RELEASE_OWNER: ${{ vars.FLAYER_RELEASE_OWNER }}
+          FLAYER_PYPI_ENABLED: ${{ vars.FLAYER_PYPI_ENABLED }}
+        run: python tools/release_validation.py --publication --tag "$FLAYER_RELEASE_TAG"
+      - name: Resolve VPN dependency wheels for an isolated installation
+        run: |
+          wheels=(_build/release/dist/*.whl)
+          test "${#wheels[@]}" -eq 1
+          python -m pip download --only-binary=:all: \
+            --dest "$RUNNER_TEMP/flayer-vpn-wheels" "${wheels[0]}[vpn]"
+      - name: Test the exact artifacts approved for publication
+        env:
+          FLAYER_DISTRIBUTION_DIRECTORY: _build/release/dist
+          FLAYER_DISTRIBUTION_WHEELHOUSE: ${{ runner.temp }}/flayer-vpn-wheels
+        run: |
+          export SOURCE_DATE_EPOCH="$(git show -s --format=%ct HEAD)"
+          python -m pytest tests/integration/test*distribution.py --no-cov
+      - name: Upload the validated distributions for this exact run
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: flayer-approved-pypi-distributions
+          path: _build/release/dist
+          if-no-files-found: error
+      - name: Upload release build evidence
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: flayer-approved-pypi-evidence
+          path: _build/release/build-evidence.json
+          if-no-files-found: error
+
+  publish-pypi:
+    needs: validate-release
+    if: >-
+      github.repository == 'Fuzzy-Technologies/F-Layer' &&
+      github.ref == 'refs/heads/master' &&
+      vars.FLAYER_PYPI_ENABLED == 'true' &&
+      vars.FLAYER_RELEASE_OWNER != '' &&
+      github.actor == vars.FLAYER_RELEASE_OWNER &&
+      inputs.confirm_publication == true
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      id-token: write
+    steps:
+      - name: Retrieve the validated artifacts from this workflow run
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: flayer-approved-pypi-distributions
+          path: dist
+      - name: Publish with the configured PyPI Trusted Publisher
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          packages-dir: dist
+          repository-url: https://upload.pypi.org/legacy/
+          skip-existing: false
+          attestations: true

f_layer-2.0.0/.github/workflows/release-validation.yml

@@ -0,0 +1,72 @@
+name: Release artifact validation
+
+on:
+  pull_request:
+    branches: [develop, master]
+  push:
+    branches: [develop, master]
+    tags: ['v*']
+
+permissions:
+  contents: read
+
+jobs:
+  validate-artifacts:
+    name: Release artifact validation
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Check out the exact reviewed revision and local tag history
+        uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Set up Python
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: '3.11'
+      - name: Restore the remote annotated tag after checkout
+        if: startsWith(github.ref, 'refs/tags/')
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: git fetch --force origin "refs/tags/$RELEASE_TAG:refs/tags/$RELEASE_TAG"
+      - name: Install the pinned development and build tools
+        run: python -m pip install -e '.[dev]'
+      - name: Validate the complete release candidate on tag pushes
+        if: startsWith(github.ref, 'refs/tags/')
+        run: python tools/validate.py
+      - name: Build and audit reproducible wheel and source distributions
+        env:
+          RELEASE_REF_TYPE: ${{ github.ref_type }}
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: |
+          if [ "$RELEASE_REF_TYPE" = "tag" ]; then
+            python tools/release_validation.py --tag "$RELEASE_TAG"
+          else
+            python tools/release_validation.py
+          fi
+      - name: Resolve VPN dependency wheels for an isolated installation
+        run: |
+          wheels=(_build/release/dist/*.whl)
+          test "${#wheels[@]}" -eq 1
+          python -m pip download --only-binary=:all: \
+            --dest "$RUNNER_TEMP/flayer-vpn-wheels" "${wheels[0]}[vpn]"
+      - name: Test the audited wheel as an installed application
+        env:
+          FLAYER_DISTRIBUTION_DIRECTORY: _build/release/dist
+          FLAYER_DISTRIBUTION_WHEELHOUSE: ${{ runner.temp }}/flayer-vpn-wheels
+        run: |
+          export SOURCE_DATE_EPOCH="$(git show -s --format=%ct HEAD)"
+          python -m pytest tests/integration/test*distribution.py --no-cov
+      - name: Upload audited distribution preview
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: flayer-release-preview
+          path: _build/release/dist
+          if-no-files-found: error
+      - name: Upload reproducibility and ownership evidence
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: flayer-release-evidence
+          path: _build/release/build-evidence.json
+          if-no-files-found: error

f_layer-2.0.0/.gitignore

@@ -0,0 +1,42 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.egg-info/
+.eggs/
+build/
+dist/
+_build/
+
+# Environments and secrets
+.venv/
+venv/
+.env
+.env.*
+!.env.example
+
+# Test and analysis output
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage/
+htmlcov/
+
+# IDE and OS
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db
+
+# Runtime/local state
+*.log
+*.sqlite
+*.sqlite3
+.local/
+state/
+artifacts/
+
+# Generated documentation output
+_build/

f_layer-2.0.0/AGENTS.md

@@ -0,0 +1,67 @@
+# AGENTS.md
+
+## Purpose
+
+This file is the mandatory entry point for AI agents, Codex sessions, IDE assistants, automation, and other software agents working in F-Layer.
+
+Before changing code or documentation, read and follow [DEVELOPMENT_PROTOCOL.md](DEVELOPMENT_PROTOCOL.md). It is the canonical repository development contract.
+
+## Repository boundary
+
+- Work only inside this repository unless the owner explicitly authorizes another repository or external system for the current task.
+- Do not inspect or modify parent directories, sibling repositories, user home data, mounted shares, or unrelated local storage.
+- Do not infer permission to access infrastructure merely because credentials or tooling are available.
+- Read only the files required for the task; prefer targeted search and narrow excerpts over unrestricted context dumps.
+
+## Infrastructure safety
+
+F-Layer manages infrastructure. Tests and development must not mutate real cloud resources unless the owner explicitly authorizes that exact operation.
+
+By default:
+
+- provider tests use mocks, fakes, fixtures, or repository-defined isolated resources;
+- destructive create/update/delete operations against real accounts are prohibited;
+- credentials and secrets are never model context and are never committed;
+- cleanup, rollback, idempotency, and failure behavior are first-class contracts.
+
+## Language
+
+- Source code, comments, docstrings, commit messages, ADRs, canonical documentation, schemas, CLI commands, and repository metadata are English-only.
+- Localization assets may contain their target language.
+- User-facing discussion may follow the user's language.
+
+## Mandatory development rules
+
+- Follow `DEVELOPMENT_PROTOCOL.md`.
+- Architecture-impacting changes require an ADR or explicit design decision.
+- Prefer deterministic tools and tests when they can answer the question.
+- Keep changes small, reviewable, and scoped to one objective.
+- Do not mix behavior changes with unrelated formatting or cleanup.
+- Never claim completion without applicable tests and evidence.
+- Never add private infrastructure identifiers, local paths, credentials, tokens, or secrets to tracked files.
+
+## Git workflow
+
+- `master` is the stable/released branch.
+- `develop` is the integration branch.
+- Normal work uses `feature/*`, `fix/*`, `release/*`, or `hotfix/*` branches.
+- Do not push normal implementation work directly to `master` or `develop`.
+- Automated agents may prepare branches, commits, and pull requests when authorized, but must not merge their own PRs unless the owner explicitly requests that merge.
+- Do not force-push protected branches or rewrite published history.
+
+## Protected policy files
+
+`AGENTS.md` and `DEVELOPMENT_PROTOCOL.md` are owner-controlled policy files. Agents may read and cite them, but must not modify, replace, delete, or weaken them without explicit owner authorization.
+
+## Completion
+
+Before reporting completion:
+
+1. inspect the exact diff;
+2. run targeted tests;
+3. run the canonical full gate when available;
+4. verify no secret, private identifier, or unrelated file entered the change;
+5. update documentation when required;
+6. report actual evidence, failures, and remaining uncertainty.
+
+If a required check cannot be run, report it as not run. Never convert an unexecuted check into PASS.