From a8f77a3ba9d4acc1f3ed11ebfc7e93f0072568c1 Mon Sep 17 00:00:00 2001
From: Yevhenii Basarab <yevhenii@flamingo.cx>
Date: Fri, 2 Oct 2026 20:48:06 +0200
Subject: [PATCH 1/4] feat(codegen): CU-17tkuw5tebe publish release-bound
 osquery schemas

---
 .github/workflows/release.yml        |  85 +++++++++++-
 .github/workflows/test.yml           |  41 +++++-
 tools/codegen/CMakeLists.txt         |   2 +
 tools/codegen/RELEASE_SCHEMA.md      |  56 ++++++++
 tools/codegen/release_schema.py      | 188 +++++++++++++++++++++++++++
 tools/codegen/test_release_schema.py | 167 ++++++++++++++++++++++++
 6 files changed, 537 insertions(+), 2 deletions(-)
 create mode 100644 tools/codegen/RELEASE_SCHEMA.md
 create mode 100644 tools/codegen/release_schema.py
 create mode 100644 tools/codegen/test_release_schema.py

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index b3cecf92c03..ddd3ca10070 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -33,6 +33,16 @@ env:
 # =============================================================================
 
 jobs:
+  schema_test:
+    name: Test Release Schema Exporter
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: python -B -m unittest discover -s tools/codegen -p test_release_schema.py -v
+
   # cmake needs 3 semver components and no leading "v"
   version:
     name: "Resolve Version"
@@ -79,11 +89,13 @@ jobs:
             os: macos-15-intel
             os_arch: x86-64
             cmake_arch: x86_64
+            schema_arch: amd64
             artifact_name: osquery-macos-x64
           - name: "macOS ARM64"
             os: macos-15 # pinned: Xcode 26 on macos-latest fails to compile boost mpl
             os_arch: arm64
             cmake_arch: arm64
+            schema_arch: arm64
             artifact_name: osquery-macos-arm64
 
     steps:
@@ -164,6 +176,27 @@ jobs:
           
           echo "Build completed successfully"
 
+      - name: Export and verify release schema
+        env:
+          RELEASE_TAG: ${{ inputs.version || 'latest' }}
+          OSQUERY_VERSION: ${{ needs.version.outputs.version }}
+          SOURCE_COMMIT: ${{ github.sha }}
+        run: |
+          python3 tools/codegen/release_schema.py variant \
+            --native-specs build/specs/native_specs.txt \
+            --foreign-specs build/specs/foreign_specs.txt \
+            --platform darwin --architecture '${{ matrix.schema_arch }}' \
+            --release-tag "$RELEASE_TAG" --osquery-version "$OSQUERY_VERSION" \
+            --source-commit "$SOURCE_COMMIT" --binary build/osquery/osqueryd \
+            --output schema/osquery-schema.json
+
+      - name: Upload schema variant
+        uses: actions/upload-artifact@v4
+        with:
+          name: schema-darwin-${{ matrix.schema_arch }}
+          path: schema/osquery-schema.json
+          if-no-files-found: error
+
       - name: ccache statistics
         if: always()
         run: ccache --show-stats
@@ -266,6 +299,10 @@ jobs:
 
       - name: Setup MSBuild
         uses: microsoft/setup-msbuild@v2
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
       
       - name: Setup Visual Studio Build Tools
         uses: ilammy/msvc-dev-cmd@v1
@@ -283,6 +320,28 @@ jobs:
           cd build
           cmake --build . --config RelWithDebInfo -j10
 
+      - name: Export and verify release schema
+        shell: bash
+        env:
+          RELEASE_TAG: ${{ inputs.version || 'latest' }}
+          OSQUERY_VERSION: ${{ needs.version.outputs.version }}
+          SOURCE_COMMIT: ${{ github.sha }}
+        run: |
+          python tools/codegen/release_schema.py variant \
+            --native-specs build/specs/native_specs.txt \
+            --foreign-specs build/specs/foreign_specs.txt \
+            --platform windows --architecture amd64 \
+            --release-tag "$RELEASE_TAG" --osquery-version "$OSQUERY_VERSION" \
+            --source-commit "$SOURCE_COMMIT" --binary build/osquery/RelWithDebInfo/osqueryd.exe \
+            --output schema/osquery-schema.json
+
+      - name: Upload schema variant
+        uses: actions/upload-artifact@v4
+        with:
+          name: schema-windows-amd64
+          path: schema/osquery-schema.json
+          if-no-files-found: error
+
       - name: Sign Windows package
         uses: ./.github/steps/sign-windows-package
         with:
@@ -307,7 +366,7 @@ jobs:
 
   release:
     name: "Create Release"
-    needs: [build_macos, create_universal_macos, build_windows]
+    needs: [schema_test, build_macos, create_universal_macos, build_windows]
     runs-on: ubuntu-latest
     if: |
       github.event_name == 'push' ||
@@ -324,6 +383,18 @@ jobs:
         with:
           path: release-artifacts
 
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Aggregate matching build schemas
+        run: |
+          python tools/codegen/release_schema.py aggregate \
+            --variants release-artifacts/schema-darwin-amd64/osquery-schema.json \
+              release-artifacts/schema-darwin-arm64/osquery-schema.json \
+              release-artifacts/schema-windows-amd64/osquery-schema.json \
+            --output final-artifacts/osquery-schema.json
+
       - name: Prepare release artifacts
         run: |
           set -e
@@ -350,12 +421,20 @@ jobs:
 
           ls -lh final-artifacts/clients/
 
+      - name: Hash release artifacts
+        run: |
+          cd final-artifacts
+          sha256sum osquery-schema.json clients/* > SHA256SUMS
+
       - name: Generate release header
         run: |
           cat > RELEASE_HEADER.md <<EOF
           ## OSQuery Clients
           - **macOS** (Universal): \`osquery-macos-universal.tar.gz\`
           - **Windows** (amd64): \`osquery-windows-amd64.zip\`
+          - **Versioned table schema**: \`osquery-schema.json\`
+          - **Schema SHA-256**: \`osquery-schema.json.sha256\`
+          - **Checksums**: \`SHA256SUMS\`
           EOF
 
       - name: Delete existing latest release
@@ -373,5 +452,9 @@ jobs:
           prerelease: ${{ github.event_name == 'push' }}
           token: ${{ secrets.GITHUB_TOKEN }}
           body_path: RELEASE_HEADER.md
+          fail_on_unmatched_files: true
           files: |
             final-artifacts/clients/*
+            final-artifacts/osquery-schema.json
+            final-artifacts/osquery-schema.json.sha256
+            final-artifacts/SHA256SUMS
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 98c462a6e92..fad24641178 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -32,6 +32,16 @@ env:
 # =============================================================================
 
 jobs:
+  schema_test:
+    name: Test Release Schema Exporter
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: python -B -m unittest discover -s tools/codegen -p test_release_schema.py -v
+
   build_macos:
     name: "Build C Client for (${{ matrix.os }} ${{ matrix.os_arch }})"
     runs-on: ${{ matrix.os }}
@@ -47,11 +57,13 @@ jobs:
             os: macos-15-intel
             os_arch: x86-64
             cmake_arch: x86_64
+            schema_arch: amd64
             artifact_name: osquery-macos-x64
           - name: "macOS ARM64"
             os: macos-15 # pinned: Xcode 26 on macos-latest fails to compile boost mpl
             os_arch: arm64
             cmake_arch: arm64
+            schema_arch: arm64
             artifact_name: osquery-macos-arm64
     steps:
       - name: Checkout
@@ -131,6 +143,17 @@ jobs:
           
           echo "Build completed successfully"
 
+      - name: Verify built table schema
+        env:
+          SOURCE_COMMIT: ${{ github.sha }}
+        run: |
+          python3 tools/codegen/release_schema.py variant \
+            --native-specs build/specs/native_specs.txt \
+            --foreign-specs build/specs/foreign_specs.txt \
+            --platform darwin --architecture '${{ matrix.schema_arch }}' \
+            --release-tag pr-test --osquery-version 5.9.1 --source-commit "$SOURCE_COMMIT" \
+            --binary build/osquery/osqueryd --output schema/osquery-schema.json
+
       - name: ccache statistics
         if: always()
         run: ccache --show-stats
@@ -158,6 +181,10 @@ jobs:
 
       - name: Setup MSBuild
         uses: microsoft/setup-msbuild@v2
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
       
       - name: Setup Visual Studio Build Tools
         uses: ilammy/msvc-dev-cmd@v1
@@ -175,9 +202,21 @@ jobs:
           cd build
           cmake --build . --config RelWithDebInfo -j10
 
+      - name: Verify built table schema
+        shell: bash
+        env:
+          SOURCE_COMMIT: ${{ github.sha }}
+        run: |
+          python tools/codegen/release_schema.py variant \
+            --native-specs build/specs/native_specs.txt \
+            --foreign-specs build/specs/foreign_specs.txt \
+            --platform windows --architecture amd64 \
+            --release-tag pr-test --osquery-version 5.9.1 --source-commit "$SOURCE_COMMIT" \
+            --binary build/osquery/RelWithDebInfo/osqueryd.exe --output schema/osquery-schema.json
+
   all-checks:
     name: "All Checks"
-    needs: [build_macos, build_windows]
+    needs: [schema_test, build_macos, build_windows]
     runs-on: ubuntu-latest
     if: always()
     steps:
diff --git a/tools/codegen/CMakeLists.txt b/tools/codegen/CMakeLists.txt
index 8733808e33e..f6766b59de4 100644
--- a/tools/codegen/CMakeLists.txt
+++ b/tools/codegen/CMakeLists.txt
@@ -118,6 +118,8 @@ function(generateTables category)
     list(APPEND table_spec_list "${CMAKE_SOURCE_DIR}/specs/${relative_table_spec}")
   endforeach()
 
+  file(WRITE "${CMAKE_CURRENT_BINARY_DIR}/${category}_specs.txt" "${table_spec_list}")
+
   # Iterate through each table spec file
   set(output_folder "${CMAKE_CURRENT_BINARY_DIR}/${category}")
 
diff --git a/tools/codegen/RELEASE_SCHEMA.md b/tools/codegen/RELEASE_SCHEMA.md
new file mode 100644
index 00000000000..976fadf7eb8
--- /dev/null
+++ b/tools/codegen/RELEASE_SCHEMA.md
@@ -0,0 +1,56 @@
+# Released osquery schema
+
+The osquery release publishes `osquery-schema.json` and
+`osquery-schema.json.sha256` alongside the macOS universal and Windows binaries.
+The JSON is generated from the same checkout and CMake-selected specs as each
+binary. Publication requires all three build variants and matching provenance.
+
+## Contract (formatVersion 1)
+
+- `releaseTag`: exact GitHub release tag, including a leading `v` when supplied.
+- `osqueryVersion`: resolved CMake engine version (the fork release version).
+- `sourceCommit`: full 40-character checkout commit SHA.
+- `variants`: Darwin amd64, Darwin arm64, Windows amd64; each has `platform`,
+  `architecture` and `tables`.
+- Table: `name`, `aliases` (string array), `description`, `notes`, `url` (strings),
+  `examples` (string array), `availability`, `attributes` (spec attribute object),
+  `foreignKeys` (`{column, table}` array), `columns`.
+- Column: `name`, `aliases` (string array), SQL `type` (lowercase), `description`,
+  `notes`, `platforms` (string array), `options` (spec options object such as
+  `required`, `hidden`, `index`, `optimized`, `additional`, `collate`).
+
+`availability` is `native`, `foreign` or `disabled`. Foreign tables are registered
+empty-result placeholders. They do not establish native platform support.
+Platform-specific columns retain their platform list; an empty list means no
+column-level restriction within that variant. Hidden columns can be selected
+explicitly and are not automatically invalid SQL. Runtime event configuration,
+permissions and extensions remain separate from compiled schema availability.
+
+The checksum is SHA-256 of the exact complete JSON asset bytes, before decoding
+or reserialization. The sidecar uses `HASH  osquery-schema.json\n`, with a lowercase
+64-character hexadecimal hash. There is no embedded checksum or canonical JSON
+requirement. `SHA256SUMS` additionally covers the schema and binary archives.
+
+## Build and release checks
+
+CMake writes `build/specs/native_specs.txt` and `foreign_specs.txt` using its actual
+selected source lists. `release_schema.py variant` reads those manifests, applies
+the target platform to the upstream spec parser, and verifies version, table,
+column and alias registration using the just-built executable in shell mode.
+Metadata queries do not execute the table's data collection query.
+
+`release_schema.py aggregate` requires exactly the three supported variants with
+the same format, release tag, engine version and source commit. Release and PR CI
+run the exporter tests; each platform build verifies its own schema.
+
+The existing mutable `latest` prerelease retains its exact source and engine
+provenance. It does not prove a device has that build. Consumers must distinguish
+catalog provenance from verified installed platform, architecture and version.
+Older releases without an artifact remain unconfirmed rather than falling back
+to another version's schema.
+
+Run the local exporter tests with:
+
+```sh
+python3 -B -m unittest discover -s tools/codegen -p test_release_schema.py -v
+```
diff --git a/tools/codegen/release_schema.py b/tools/codegen/release_schema.py
new file mode 100644
index 00000000000..f519661be30
--- /dev/null
+++ b/tools/codegen/release_schema.py
@@ -0,0 +1,188 @@
+#!/usr/bin/env python3
+"""Publish the table specs selected for each released osquery binary."""
+
+import argparse
+import hashlib
+import json
+from pathlib import Path
+import re
+import subprocess
+import sys
+import tempfile
+
+import gentable
+
+
+REQUIRED_VARIANTS = {("darwin", "amd64"), ("darwin", "arm64"), ("windows", "amd64")}
+PROVENANCE_FIELDS = ("formatVersion", "releaseTag", "osqueryVersion", "sourceCommit")
+
+
+def selected_specs(manifest, source_root):
+    paths = [Path(value).resolve() for value in manifest.read_text(encoding="utf-8").strip().split(";") if value]
+    specs_root = (source_root / "specs").resolve()
+    for path in paths:
+        if specs_root not in path.parents or path.suffix != ".table" or not path.is_file():
+            raise ValueError("Invalid selected spec: {}".format(path))
+    if len(set(paths)) != len(paths):
+        raise ValueError("Duplicate specs in {}".format(manifest))
+    return paths
+
+
+def platform_names(platforms):
+    return sorted({"windows" if name in gentable.WINDOWS else name for name in platforms})
+
+
+def table_metadata(path, platform, availability, source_root, source_commit):
+    gentable.PLATFORM = "win32" if platform == "windows" else platform
+    gentable.table.__init__()
+    namespace = dict(vars(gentable))
+    exec(compile(path.read_text(encoding="utf-8"), str(path), "exec"), namespace)
+    table = gentable.table
+    if not table.table_name or not table.columns() or not table.function:
+        raise ValueError("Incomplete table spec: {}".format(path))
+    if gentable.is_denylisted(table.table_name, path=str(path)):
+        availability = "disabled"
+    return {
+        "name": table.table_name,
+        "aliases": table.aliases,
+        "description": table.description,
+        "notes": table.notes,
+        "examples": table.examples,
+        "attributes": table.attributes,
+        "availability": availability,
+        "url": "https://github.com/flamingo-stack/osquery/blob/{}/{}".format(
+            source_commit, path.relative_to(source_root).as_posix()),
+        "columns": [{
+            "name": column.name,
+            "aliases": column.aliases,
+            "type": column.type.affinity.replace("_TYPE", "").lower(),
+            "description": column.description,
+            "notes": column.notes,
+            "platforms": platform_names(column.platforms),
+            "options": column.options,
+        } for column in table.columns()],
+        "foreignKeys": [{"column": key.column, "table": key.table} for key in table.foreign_keys()],
+    }
+
+
+def export_variant(source_root, native_manifest, foreign_manifest, platform, architecture,
+                   release_tag, osquery_version, source_commit):
+    source_root = Path(source_root).resolve()
+    if (platform, architecture) not in REQUIRED_VARIANTS:
+        raise ValueError("Unsupported release platform/architecture")
+    if not re.fullmatch(r"[0-9a-f]{40}", source_commit):
+        raise ValueError("sourceCommit must be the full source commit SHA")
+    if not release_tag or not re.fullmatch(r"\d+\.\d+\.\d+", osquery_version):
+        raise ValueError("Missing release tag or invalid osquery version")
+    native = selected_specs(Path(native_manifest), source_root)
+    foreign = selected_specs(Path(foreign_manifest), source_root)
+    if not native or set(native) & set(foreign):
+        raise ValueError("Native selection is empty or overlaps foreign selection")
+    tables = sorted(
+        [table_metadata(path, platform, availability, source_root, source_commit)
+         for paths, availability in ((native, "native"), (foreign, "foreign")) for path in paths],
+        key=lambda table: table["name"],
+    )
+    if len({table["name"] for table in tables}) != len(tables):
+        raise ValueError("Duplicate selected table names")
+    variants = [{"platform": platform, "architecture": architecture, "tables": tables}]
+    return {"formatVersion": 1, "releaseTag": release_tag, "osqueryVersion": osquery_version,
+            "sourceCommit": source_commit, "variants": variants}
+
+
+def aggregate(parts):
+    if not parts:
+        raise ValueError("No schema variants")
+    provenance = {field: parts[0][field] for field in PROVENANCE_FIELDS}
+    variants = []
+    for part in parts:
+        if any(part.get(field) != value for field, value in provenance.items()):
+            raise ValueError("Schema variants have different source/version provenance")
+        variants.extend(part["variants"])
+    keys = [(variant["platform"], variant["architecture"]) for variant in variants]
+    if set(keys) != REQUIRED_VARIANTS or len(keys) != len(REQUIRED_VARIANTS):
+        raise ValueError("Release needs exactly darwin/amd64, darwin/arm64 and windows/amd64")
+    variants.sort(key=lambda variant: (variant["platform"], variant["architecture"]))
+    return dict(provenance, variants=variants)
+
+
+def write_artifact(artifact, output):
+    raw = (json.dumps(artifact, ensure_ascii=False, indent=2) + "\n").encode("utf-8")
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_bytes(raw)
+    checksum = hashlib.sha256(raw).hexdigest() + "  " + output.name + "\n"
+    output.with_name(output.name + ".sha256").write_text(checksum, encoding="ascii")
+
+
+def verify_binary(artifact, binary):
+    """Check version and SQL column/alias registration without reading table data."""
+    with tempfile.TemporaryDirectory(prefix="osquery-schema-") as scratch:
+        config = Path(scratch) / "config.json"
+        config.write_text("{}", encoding="utf-8")
+        def query(sql):
+            result = subprocess.run(
+                [str(Path(binary).resolve()), "-S", "--json", "--disable_extensions",
+                 "--disable_events", "--disable_logging", "--config_plugin=filesystem",
+                 "--config_path=" + str(config), "--database_path=" + str(Path(scratch) / "db"), sql],
+                capture_output=True, text=True, check=True, timeout=30,
+            )
+            return json.loads(result.stdout)
+
+        rows = query("select version from osquery_info;")
+        if len(rows) != 1 or rows[0]["version"] != artifact["osqueryVersion"]:
+            raise ValueError("Built binary version differs from schema version")
+        for table in artifact["variants"][0]["tables"]:
+            if table["availability"] != "native":
+                continue
+            expected = {column["name"] for column in table["columns"]}
+            for name in [table["name"]] + table["aliases"]:
+                escaped = name.replace("'", "''")
+                columns = query("select name from pragma_table_xinfo('{}');".format(escaped))
+                names = {column["name"] for column in columns}
+                if not expected <= names:
+                    raise ValueError("Built table {} missing columns {}".format(name, sorted(expected - names)))
+            for column in table["columns"]:
+                for alias in column["aliases"]:
+                    if not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", alias):
+                        raise ValueError("Unexpected SQL column alias: {}".format(alias))
+                    quoted_table = table["name"].replace('"', '""')
+                    query('select [{}] from "{}" limit 0;'.format(alias, quoted_table))
+
+
+def main():
+    parser = argparse.ArgumentParser(__doc__)
+    commands = parser.add_subparsers(dest="command", required=True)
+    variant = commands.add_parser("variant")
+    variant.add_argument("--source-root", type=Path, default=Path(__file__).resolve().parents[2])
+    variant.add_argument("--native-specs", type=Path, required=True)
+    variant.add_argument("--foreign-specs", type=Path, required=True)
+    variant.add_argument("--platform", choices=("darwin", "windows"), required=True)
+    variant.add_argument("--architecture", choices=("amd64", "arm64"), required=True)
+    variant.add_argument("--release-tag", required=True)
+    variant.add_argument("--osquery-version", required=True)
+    variant.add_argument("--source-commit", required=True)
+    variant.add_argument("--binary", type=Path)
+    variant.add_argument("--output", type=Path, required=True)
+    merge = commands.add_parser("aggregate")
+    merge.add_argument("--variants", type=Path, nargs="+", required=True)
+    merge.add_argument("--output", type=Path, required=True)
+    args = parser.parse_args()
+    if args.command == "variant":
+        artifact = export_variant(args.source_root, args.native_specs, args.foreign_specs,
+                                  args.platform, args.architecture, args.release_tag,
+                                  args.osquery_version, args.source_commit)
+        if args.binary:
+            verify_binary(artifact, args.binary)
+    else:
+        artifact = aggregate([json.loads(path.read_text(encoding="utf-8")) for path in args.variants])
+    write_artifact(artifact, args.output)
+    print("Exported {} variant(s), {} tables: {}".format(
+        len(artifact["variants"]), sum(len(v["tables"]) for v in artifact["variants"]), args.output))
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except (ValueError, OSError, subprocess.SubprocessError) as error:
+        print("Schema export failed: {}".format(error), file=sys.stderr)
+        sys.exit(1)
diff --git a/tools/codegen/test_release_schema.py b/tools/codegen/test_release_schema.py
new file mode 100644
index 00000000000..d44a562faea
--- /dev/null
+++ b/tools/codegen/test_release_schema.py
@@ -0,0 +1,167 @@
+#!/usr/bin/env python3
+"""Release schemas must describe the selected build, including valid SQL aliases."""
+
+import importlib.util
+import hashlib
+import json
+from pathlib import Path
+import tempfile
+from types import SimpleNamespace
+import unittest
+from unittest.mock import patch
+import subprocess
+
+
+MODULE_PATH = Path(__file__).with_name("release_schema.py")
+SPEC = '''table_name("sample", aliases=["sample_alias"])
+description("A sample table.")
+schema([
+    Column("path", TEXT, "Path", aliases=["location"], required=True, optimized=True),
+    ForeignKey(column="path", table="file"),
+])
+extended_schema(WINDOWS, [Column("windows_only", INTEGER, "Windows value")])
+notes("Needs permission.")
+examples(["select location from sample_alias where path = '/tmp'"])
+attributes(cacheable=True)
+implementation("sample@genSample")
+'''
+
+
+class ReleaseSchemaTest(unittest.TestCase):
+    def setUp(self):
+        self.assertTrue(MODULE_PATH.exists(), "release schema exporter is missing")
+        spec = importlib.util.spec_from_file_location("release_schema", MODULE_PATH)
+        self.exporter = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(self.exporter)
+        self.temp = tempfile.TemporaryDirectory()
+        self.addCleanup(self.temp.cleanup)
+        self.root = Path(self.temp.name)
+        (self.root / "specs").mkdir()
+        self.sample = self.root / "specs/sample.table"
+        self.sample.write_text(SPEC)
+        self.native = self.root / "native.txt"
+        self.foreign = self.root / "foreign.txt"
+        self.native.write_text(str(self.sample))
+        self.foreign.write_text("")
+
+    def variant(self, platform="darwin", architecture="arm64"):
+        return self.exporter.export_variant(
+            self.root, self.native, self.foreign, platform, architecture,
+            "0.0.8", "0.0.8", "a" * 40,
+        )
+
+    def test_preserves_aliases_constraints_examples_and_foreign_keys(self):
+        table = self.variant()["variants"][0]["tables"][0]
+        self.assertEqual(table["aliases"], ["sample_alias"])
+        self.assertEqual(table["columns"][0]["aliases"], ["location"])
+        self.assertEqual(table["columns"][0]["options"], {"required": True, "optimized": True})
+        self.assertEqual(table["foreignKeys"], [{"column": "path", "table": "file"}])
+        self.assertEqual(table["notes"], "Needs permission.")
+        self.assertEqual(table["examples"], ["select location from sample_alias where path = '/tmp'"])
+        self.assertEqual(table["availability"], "native")
+
+    def test_platform_columns_do_not_depend_on_exporter_host(self):
+        darwin = self.variant()["variants"][0]["tables"][0]["columns"][1]
+        windows = self.variant("windows", "amd64")["variants"][0]["tables"][0]["columns"][1]
+        self.assertEqual(darwin["platforms"], ["windows"])
+        self.assertTrue(darwin["options"]["hidden"])
+        self.assertNotIn("hidden", windows["options"])
+
+    def test_only_cmake_selected_specs_are_exported_and_foreign_is_marked(self):
+        (self.root / "specs/unselected.table").write_text(SPEC.replace("sample", "unselected"))
+        other = self.root / "specs/other.table"
+        other.write_text(SPEC.replace("sample", "other"))
+        self.foreign.write_text(str(other))
+        tables = self.variant()["variants"][0]["tables"]
+        self.assertEqual([(t["name"], t["availability"]) for t in tables],
+                         [("other", "foreign"), ("sample", "native")])
+
+    def test_rejects_specs_outside_source_and_empty_native_selection(self):
+        self.native.write_text(str(self.root / "outside.table"))
+        with self.assertRaises(ValueError):
+            self.variant()
+        self.native.write_text("")
+        with self.assertRaises(ValueError):
+            self.variant()
+
+    def test_rejects_duplicate_native_foreign_spec(self):
+        self.foreign.write_text(str(self.sample))
+        with self.assertRaises(ValueError):
+            self.variant()
+
+    def test_aggregation_requires_three_variants_with_matching_provenance(self):
+        parts = [self.variant("darwin", "amd64"), self.variant(), self.variant("windows", "amd64")]
+        artifact = self.exporter.aggregate(parts)
+        self.assertEqual([(v["platform"], v["architecture"]) for v in artifact["variants"]],
+                         [("darwin", "amd64"), ("darwin", "arm64"), ("windows", "amd64")])
+        self.assertEqual(artifact["sourceCommit"], "a" * 40)
+        with self.assertRaises(ValueError):
+            self.exporter.aggregate(parts[:2])
+        parts[2]["sourceCommit"] = "b" * 40
+        with self.assertRaises(ValueError):
+            self.exporter.aggregate(parts)
+
+    def test_rejects_duplicate_variant(self):
+        parts = [self.variant("darwin", "amd64"), self.variant(), self.variant("windows", "amd64")]
+        with self.assertRaises(ValueError):
+            self.exporter.aggregate(parts + [parts[0]])
+
+    def test_sidecar_hashes_exact_utf8_bytes_without_reserializing(self):
+        first = self.variant()
+        first["variants"][0]["tables"][0]["notes"] = "Permissions — needed"
+        output = self.root / "osquery-schema.json"
+        self.assertTrue(hasattr(self.exporter, "write_artifact"), "raw checksum writer is missing")
+        self.exporter.write_artifact(first, output)
+        raw = output.read_bytes()
+        checksum = output.with_name("osquery-schema.json.sha256").read_text()
+        self.assertEqual(checksum, hashlib.sha256(raw).hexdigest() + "  osquery-schema.json\n")
+        self.assertNotIn("schemaSha256", first)
+        self.assertEqual(json.loads(raw)["variants"][0]["tables"][0]["notes"], "Permissions — needed")
+        self.assertEqual(json.loads(json.dumps(first))["formatVersion"], 1)
+
+    def binary_query(self, version="0.0.8", columns=("path", "windows_only"), missing_alias=False):
+        def run(command, **kwargs):
+            sql = command[-1]
+            if sql == "select version from osquery_info;":
+                rows = [{"version": version}]
+            elif sql.startswith("select name from pragma_table_xinfo("):
+                rows = [{"name": name} for name in columns]
+            elif sql == 'select [location] from "sample" limit 0;':
+                if missing_alias:
+                    raise subprocess.CalledProcessError(1, command, stderr="no such column: location")
+                rows = []
+            else:
+                raise AssertionError("Unexpected binary SQL: {}".format(sql))
+            return SimpleNamespace(stdout=json.dumps(rows))
+        return run
+
+    def test_binary_verification_rejects_wrong_engine_version(self):
+        with patch.object(self.exporter.subprocess, "run", side_effect=self.binary_query(version="0.0.7")):
+            with self.assertRaisesRegex(ValueError, "version differs"):
+                self.exporter.verify_binary(self.variant(), self.root / "osqueryd")
+
+    def test_binary_verification_rejects_missing_table_or_column(self):
+        for columns in ((), ("path",)):
+            with self.subTest(columns=columns):
+                with patch.object(self.exporter.subprocess, "run", side_effect=self.binary_query(columns=columns)):
+                    with self.assertRaisesRegex(ValueError, "missing columns"):
+                        self.exporter.verify_binary(self.variant(), self.root / "osqueryd")
+
+    def test_binary_verification_rejects_missing_column_alias_using_identifier_sql(self):
+        with patch.object(self.exporter.subprocess, "run", side_effect=self.binary_query(missing_alias=True)):
+            with self.assertRaises(subprocess.CalledProcessError):
+                self.exporter.verify_binary(self.variant(), self.root / "osqueryd")
+
+    def test_binary_verification_does_not_treat_foreign_tables_as_supported(self):
+        artifact = self.variant()
+        artifact["variants"][0]["tables"][0]["availability"] = "foreign"
+        with patch.object(self.exporter.subprocess, "run", side_effect=self.binary_query(columns=())):
+            self.exporter.verify_binary(artifact, self.root / "osqueryd")
+
+    def test_binary_verification_accepts_registered_table_and_column_aliases(self):
+        with patch.object(self.exporter.subprocess, "run", side_effect=self.binary_query()):
+            self.exporter.verify_binary(self.variant(), self.root / "osqueryd")
+
+
+if __name__ == "__main__":
+    unittest.main()

From 43005e349cd3e19239dc6dcf1a70e606f8728b7f Mon Sep 17 00:00:00 2001
From: Yevhenii Basarab <yevhenii@flamingo.cx>
Date: Fri, 2 Oct 2026 21:14:39 +0200
Subject: [PATCH 2/4] fix(codegen): verify only visible columns in table
 aliases

---
 tools/codegen/release_schema.py      |  5 ++++-
 tools/codegen/test_release_schema.py | 21 +++++++++++++++++++--
 2 files changed, 23 insertions(+), 3 deletions(-)

diff --git a/tools/codegen/release_schema.py b/tools/codegen/release_schema.py
index f519661be30..d5f2f40d4eb 100644
--- a/tools/codegen/release_schema.py
+++ b/tools/codegen/release_schema.py
@@ -134,8 +134,11 @@ def query(sql):
         for table in artifact["variants"][0]["tables"]:
             if table["availability"] != "native":
                 continue
-            expected = {column["name"] for column in table["columns"]}
+            all_columns = {column["name"] for column in table["columns"]}
+            visible_columns = {column["name"] for column in table["columns"]
+                               if not column["options"].get("hidden", False)}
             for name in [table["name"]] + table["aliases"]:
+                expected = all_columns if name == table["name"] else visible_columns
                 escaped = name.replace("'", "''")
                 columns = query("select name from pragma_table_xinfo('{}');".format(escaped))
                 names = {column["name"] for column in columns}
diff --git a/tools/codegen/test_release_schema.py b/tools/codegen/test_release_schema.py
index d44a562faea..8a524ed75c8 100644
--- a/tools/codegen/test_release_schema.py
+++ b/tools/codegen/test_release_schema.py
@@ -119,13 +119,17 @@ def test_sidecar_hashes_exact_utf8_bytes_without_reserializing(self):
         self.assertEqual(json.loads(raw)["variants"][0]["tables"][0]["notes"], "Permissions — needed")
         self.assertEqual(json.loads(json.dumps(first))["formatVersion"], 1)
 
-    def binary_query(self, version="0.0.8", columns=("path", "windows_only"), missing_alias=False):
+    def binary_query(self, version="0.0.8", columns=("path", "windows_only"), missing_alias=False,
+                     table_alias_columns=None):
         def run(command, **kwargs):
             sql = command[-1]
             if sql == "select version from osquery_info;":
                 rows = [{"version": version}]
-            elif sql.startswith("select name from pragma_table_xinfo("):
+            elif sql == "select name from pragma_table_xinfo('sample');":
                 rows = [{"name": name} for name in columns]
+            elif sql == "select name from pragma_table_xinfo('sample_alias');":
+                rows = [{"name": name} for name in
+                        (columns if table_alias_columns is None else table_alias_columns)]
             elif sql == 'select [location] from "sample" limit 0;':
                 if missing_alias:
                     raise subprocess.CalledProcessError(1, command, stderr="no such column: location")
@@ -162,6 +166,19 @@ def test_binary_verification_accepts_registered_table_and_column_aliases(self):
         with patch.object(self.exporter.subprocess, "run", side_effect=self.binary_query()):
             self.exporter.verify_binary(self.variant(), self.root / "osqueryd")
 
+    def test_binary_verification_accepts_table_alias_without_hidden_columns(self):
+        with patch.object(self.exporter.subprocess, "run",
+                          side_effect=self.binary_query(table_alias_columns=("path",))):
+            self.exporter.verify_binary(self.variant(), self.root / "osqueryd")
+
+    def test_binary_verification_rejects_table_alias_missing_visible_columns(self):
+        for platform, columns in (("darwin", ()), ("windows", ("path",))):
+            with self.subTest(platform=platform):
+                with patch.object(self.exporter.subprocess, "run",
+                                  side_effect=self.binary_query(table_alias_columns=columns)):
+                    with self.assertRaisesRegex(ValueError, "sample_alias missing columns"):
+                        self.exporter.verify_binary(self.variant(platform, "amd64"), self.root / "osqueryd")
+
 
 if __name__ == "__main__":
     unittest.main()

From 97ee4ac44b700887c2025e4fb0ed1d500872d508 Mon Sep 17 00:00:00 2001
From: Yevhenii Basarab <yevhenii@flamingo.cx>
Date: Mon, 5 Oct 2026 19:55:58 +0200
Subject: [PATCH 3/4] docs: explain osquery schema export and CI validation
 steps

---
 .github/workflows/release.yml   | 15 +++++++++++++++
 .github/workflows/test.yml      |  8 ++++++++
 tools/codegen/release_schema.py | 32 ++++++++++++++++++++++++++++++++
 3 files changed, 55 insertions(+)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index ddd3ca10070..c65c663df36 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -33,6 +33,7 @@ env:
 # =============================================================================
 
 jobs:
+  # Test exporter behavior. Release publication depends on this job succeeding.
   schema_test:
     name: Test Release Schema Exporter
     runs-on: ubuntu-latest
@@ -176,6 +177,10 @@ jobs:
           
           echo "Build completed successfully"
 
+      # Step 1: export this architecture's CMake-selected .table descriptions.
+      # Step 2: run the just-built binary to check version, native columns and aliases.
+      # JSON is written only after verification passes; errors fail the release build.
+      # This checks schema registration, not JOINs, column types or actual device data.
       - name: Export and verify release schema
         env:
           RELEASE_TAG: ${{ inputs.version || 'latest' }}
@@ -190,6 +195,7 @@ jobs:
             --source-commit "$SOURCE_COMMIT" --binary build/osquery/osqueryd \
             --output schema/osquery-schema.json
 
+      # Keep each architecture's verified JSON for the final release aggregation.
       - name: Upload schema variant
         uses: actions/upload-artifact@v4
         with:
@@ -320,6 +326,8 @@ jobs:
           cd build
           cmake --build . --config RelWithDebInfo -j10
 
+      # Repeat steps 1 and 2 against the Windows executable and its selected tables.
+      # This runs before signing; it does not revalidate the final signed package.
       - name: Export and verify release schema
         shell: bash
         env:
@@ -335,6 +343,7 @@ jobs:
             --source-commit "$SOURCE_COMMIT" --binary build/osquery/RelWithDebInfo/osqueryd.exe \
             --output schema/osquery-schema.json
 
+      # Keep the Windows JSON alongside the two verified Mac build catalogs.
       - name: Upload schema variant
         uses: actions/upload-artifact@v4
         with:
@@ -364,6 +373,7 @@ jobs:
           compression-level: 9
 
 
+  # Do not publish until exporter tests, all builds and Mac packaging succeed.
   release:
     name: "Create Release"
     needs: [schema_test, build_macos, create_universal_macos, build_windows]
@@ -387,6 +397,8 @@ jobs:
         with:
           python-version: '3.12'
 
+      # Step 3: combine exactly Mac Intel, Mac ARM and Windows x64 catalogs.
+      # Reject missing/duplicate builds or mismatched source commits and versions.
       - name: Aggregate matching build schemas
         run: |
           python tools/codegen/release_schema.py aggregate \
@@ -421,6 +433,7 @@ jobs:
 
           ls -lh final-artifacts/clients/
 
+      # Write downloadable checksums for the exact JSON and client archive bytes.
       - name: Hash release artifacts
         run: |
           cd final-artifacts
@@ -443,6 +456,8 @@ jobs:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: gh release delete latest --yes --cleanup-tag || true
 
+      # Step 4: publish JSON as a separate asset beside binaries in the same release.
+      # Consumers download osquery-schema.json; they do not extract it from a binary.
       - name: Create Release
         uses: softprops/action-gh-release@v2
         with:
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index fad24641178..c5bce1a5a8c 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -32,6 +32,8 @@ env:
 # =============================================================================
 
 jobs:
+  # Check the JSON exporter with small .table fixtures and simulated binary replies.
+  # The build jobs below separately verify the real catalog against real binaries.
   schema_test:
     name: Test Release Schema Exporter
     runs-on: ubuntu-latest
@@ -143,6 +145,9 @@ jobs:
           
           echo "Build completed successfully"
 
+      # Read the .table files selected by CMake, then run the newly built executable
+      # to check the engine version and advertised native table/column names and aliases.
+      # Export or verification errors fail this build; this step does not fetch table data.
       - name: Verify built table schema
         env:
           SOURCE_COMMIT: ${{ github.sha }}
@@ -202,6 +207,8 @@ jobs:
           cd build
           cmake --build . --config RelWithDebInfo -j10
 
+      # Perform the same catalog-versus-binary check on Windows, not on a Mac binary.
+      # --binary makes verification mandatory here; JSON is written only after it passes.
       - name: Verify built table schema
         shell: bash
         env:
@@ -214,6 +221,7 @@ jobs:
             --release-tag pr-test --osquery-version 5.9.1 --source-commit "$SOURCE_COMMIT" \
             --binary build/osquery/RelWithDebInfo/osqueryd.exe --output schema/osquery-schema.json
 
+  # Report failure if exporter tests or any platform build/schema check failed.
   all-checks:
     name: "All Checks"
     needs: [schema_test, build_macos, build_windows]
diff --git a/tools/codegen/release_schema.py b/tools/codegen/release_schema.py
index d5f2f40d4eb..9a0eb9397d6 100644
--- a/tools/codegen/release_schema.py
+++ b/tools/codegen/release_schema.py
@@ -13,11 +13,15 @@
 import gentable
 
 
+# Each release contains a catalog for these three binary builds.
 REQUIRED_VARIANTS = {("darwin", "amd64"), ("darwin", "arm64"), ("windows", "amd64")}
+# Build catalogs can be combined only when they describe the same source and release.
 PROVENANCE_FIELDS = ("formatVersion", "releaseTag", "osqueryVersion", "sourceCommit")
 
 
 def selected_specs(manifest, source_root):
+    # CMake lists the .table files selected for this build. Do not scan every spec:
+    # doing so could include tables that were not selected for this binary.
     paths = [Path(value).resolve() for value in manifest.read_text(encoding="utf-8").strip().split(";") if value]
     specs_root = (source_root / "specs").resolve()
     for path in paths:
@@ -29,19 +33,25 @@ def selected_specs(manifest, source_root):
 
 
 def platform_names(platforms):
+    # Use the public platform name in JSON instead of Python's Windows identifiers.
     return sorted({"windows" if name in gentable.WINDOWS else name for name in platforms})
 
 
 def table_metadata(path, platform, availability, source_root, source_commit):
+    # Read each trusted repository .table file with osquery's existing generator.
+    # Use the target OS, not the OS running this script, and reset the previous table.
     gentable.PLATFORM = "win32" if platform == "windows" else platform
     gentable.table.__init__()
     namespace = dict(vars(gentable))
     exec(compile(path.read_text(encoding="utf-8"), str(path), "exec"), namespace)
     table = gentable.table
+    # Fail on an incomplete table; never publish a partial catalog by skipping it.
     if not table.table_name or not table.columns() or not table.function:
         raise ValueError("Incomplete table spec: {}".format(path))
     if gentable.is_denylisted(table.table_name, path=str(path)):
         availability = "disabled"
+    # Copy every column returned by the generator, including hidden columns.
+    # Descriptions, aliases and constraints help the AI construct a suitable query.
     return {
         "name": table.table_name,
         "aliases": table.aliases,
@@ -74,10 +84,13 @@ def export_variant(source_root, native_manifest, foreign_manifest, platform, arc
         raise ValueError("sourceCommit must be the full source commit SHA")
     if not release_tag or not re.fullmatch(r"\d+\.\d+\.\d+", osquery_version):
         raise ValueError("Missing release tag or invalid osquery version")
+    # Native tables have implementations for this build. Foreign tables describe
+    # other platforms; disabled tables are excluded by osquery's denylist.
     native = selected_specs(Path(native_manifest), source_root)
     foreign = selected_specs(Path(foreign_manifest), source_root)
     if not native or set(native) & set(foreign):
         raise ValueError("Native selection is empty or overlaps foreign selection")
+    # Process every selected file. A read, parse or conversion error stops export.
     tables = sorted(
         [table_metadata(path, platform, availability, source_root, source_commit)
          for paths, availability in ((native, "native"), (foreign, "foreign")) for path in paths],
@@ -91,6 +104,7 @@ def export_variant(source_root, native_manifest, foreign_manifest, platform, arc
 
 
 def aggregate(parts):
+    # Combine the three build catalogs without mixing releases or source commits.
     if not parts:
         raise ValueError("No schema variants")
     provenance = {field: parts[0][field] for field in PROVENANCE_FIELDS}
@@ -100,6 +114,7 @@ def aggregate(parts):
             raise ValueError("Schema variants have different source/version provenance")
         variants.extend(part["variants"])
     keys = [(variant["platform"], variant["architecture"]) for variant in variants]
+    # A release must contain each required OS/architecture exactly once.
     if set(keys) != REQUIRED_VARIANTS or len(keys) != len(REQUIRED_VARIANTS):
         raise ValueError("Release needs exactly darwin/amd64, darwin/arm64 and windows/amd64")
     variants.sort(key=lambda variant: (variant["platform"], variant["architecture"]))
@@ -107,6 +122,8 @@ def aggregate(parts):
 
 
 def write_artifact(artifact, output):
+    # Publish JSON as a separate release file, not as content inside the binary.
+    # Hash the exact bytes written to disk for the accompanying checksum file.
     raw = (json.dumps(artifact, ensure_ascii=False, indent=2) + "\n").encode("utf-8")
     output.parent.mkdir(parents=True, exist_ok=True)
     output.write_bytes(raw)
@@ -116,6 +133,8 @@ def write_artifact(artifact, output):
 
 def verify_binary(artifact, binary):
     """Check version and SQL column/alias registration without reading table data."""
+    # Run the newly built osquery executable with a temporary database/config.
+    # Disable extensions and events so they do not change the inspected schema.
     with tempfile.TemporaryDirectory(prefix="osquery-schema-") as scratch:
         config = Path(scratch) / "config.json"
         config.write_text("{}", encoding="utf-8")
@@ -128,20 +147,25 @@ def query(sql):
             )
             return json.loads(result.stdout)
 
+        # Ask the executable for its version, rather than trusting a file name.
         rows = query("select version from osquery_info;")
         if len(rows) != 1 or rows[0]["version"] != artifact["osqueryVersion"]:
             raise ValueError("Built binary version differs from schema version")
         for table in artifact["variants"][0]["tables"]:
+            # Foreign and disabled tables are not supported native implementations.
             if table["availability"] != "native":
                 continue
             all_columns = {column["name"] for column in table["columns"]}
             visible_columns = {column["name"] for column in table["columns"]
                                if not column["options"].get("hidden", False)}
             for name in [table["name"]] + table["aliases"]:
+                # Canonical tables expose hidden columns; table aliases omit them.
                 expected = all_columns if name == table["name"] else visible_columns
                 escaped = name.replace("'", "''")
                 columns = query("select name from pragma_table_xinfo('{}');".format(escaped))
                 names = {column["name"] for column in columns}
+                # Every advertised column must exist in the executable. This is
+                # one-way: omitted tables/columns and column types are not checked.
                 if not expected <= names:
                     raise ValueError("Built table {} missing columns {}".format(name, sorted(expected - names)))
             for column in table["columns"]:
@@ -149,6 +173,8 @@ def query(sql):
                     if not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", alias):
                         raise ValueError("Unexpected SQL column alias: {}".format(alias))
                     quoted_table = table["name"].replace('"', '""')
+                    # LIMIT 0 checks that SQL accepts the alias without fetching rows.
+                    # This does not test JOINs, device permissions or actual table data.
                     query('select [{}] from "{}" limit 0;'.format(alias, quoted_table))
 
 
@@ -171,13 +197,18 @@ def main():
     merge.add_argument("--output", type=Path, required=True)
     args = parser.parse_args()
     if args.command == "variant":
+        # Step 1: turn this build's selected .table files into an in-memory catalog.
         artifact = export_variant(args.source_root, args.native_specs, args.foreign_specs,
                                   args.platform, args.architecture, args.release_tag,
                                   args.osquery_version, args.source_commit)
         if args.binary:
+            # Step 2: CI supplies --binary to verify the catalog against real osquery.
+            # Any verification failure prevents this command from writing the JSON.
             verify_binary(artifact, args.binary)
     else:
+        # Step 3: the release job merges the three already verified build catalogs.
         artifact = aggregate([json.loads(path.read_text(encoding="utf-8")) for path in args.variants])
+    # Step 4: write the individual or combined catalog and its checksum file.
     write_artifact(artifact, args.output)
     print("Exported {} variant(s), {} tables: {}".format(
         len(artifact["variants"]), sum(len(v["tables"]) for v in artifact["variants"]), args.output))
@@ -187,5 +218,6 @@ def main():
     try:
         main()
     except (ValueError, OSError, subprocess.SubprocessError) as error:
+        # Exit non-zero so CI stops instead of publishing an unverified release.
         print("Schema export failed: {}".format(error), file=sys.stderr)
         sys.exit(1)

From 337491326c1bac4c134c63a504814ebb7d343ea1 Mon Sep 17 00:00:00 2001
From: Yevhenii Basarab <yevhenii@flamingo.cx>
Date: Tue, 6 Oct 2026 12:08:38 +0200
Subject: [PATCH 4/4] docs: simplify schema export and CI comments

---
 .github/workflows/release.yml   | 20 +++++-------------
 .github/workflows/test.yml      | 11 +++-------
 tools/codegen/release_schema.py | 37 ++++++---------------------------
 3 files changed, 14 insertions(+), 54 deletions(-)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index c65c663df36..b72f97cf4e0 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -33,7 +33,6 @@ env:
 # =============================================================================
 
 jobs:
-  # Test exporter behavior. Release publication depends on this job succeeding.
   schema_test:
     name: Test Release Schema Exporter
     runs-on: ubuntu-latest
@@ -177,10 +176,8 @@ jobs:
           
           echo "Build completed successfully"
 
-      # Step 1: export this architecture's CMake-selected .table descriptions.
-      # Step 2: run the just-built binary to check version, native columns and aliases.
-      # JSON is written only after verification passes; errors fail the release build.
-      # This checks schema registration, not JOINs, column types or actual device data.
+      # Export CMake-selected .table files to JSON; SELECTs check version, columns and aliases in the built binary.
+      # Verification must pass before JSON is written; it does not test JOINs or device data.
       - name: Export and verify release schema
         env:
           RELEASE_TAG: ${{ inputs.version || 'latest' }}
@@ -195,7 +192,6 @@ jobs:
             --source-commit "$SOURCE_COMMIT" --binary build/osquery/osqueryd \
             --output schema/osquery-schema.json
 
-      # Keep each architecture's verified JSON for the final release aggregation.
       - name: Upload schema variant
         uses: actions/upload-artifact@v4
         with:
@@ -326,8 +322,7 @@ jobs:
           cd build
           cmake --build . --config RelWithDebInfo -j10
 
-      # Repeat steps 1 and 2 against the Windows executable and its selected tables.
-      # This runs before signing; it does not revalidate the final signed package.
+      # Export and verify the Windows schema against the built executable, before signing.
       - name: Export and verify release schema
         shell: bash
         env:
@@ -343,7 +338,6 @@ jobs:
             --source-commit "$SOURCE_COMMIT" --binary build/osquery/RelWithDebInfo/osqueryd.exe \
             --output schema/osquery-schema.json
 
-      # Keep the Windows JSON alongside the two verified Mac build catalogs.
       - name: Upload schema variant
         uses: actions/upload-artifact@v4
         with:
@@ -373,7 +367,6 @@ jobs:
           compression-level: 9
 
 
-  # Do not publish until exporter tests, all builds and Mac packaging succeed.
   release:
     name: "Create Release"
     needs: [schema_test, build_macos, create_universal_macos, build_windows]
@@ -397,8 +390,7 @@ jobs:
         with:
           python-version: '3.12'
 
-      # Step 3: combine exactly Mac Intel, Mac ARM and Windows x64 catalogs.
-      # Reject missing/duplicate builds or mismatched source commits and versions.
+      # Merge the three build catalogs only when their release, source and version match.
       - name: Aggregate matching build schemas
         run: |
           python tools/codegen/release_schema.py aggregate \
@@ -433,7 +425,6 @@ jobs:
 
           ls -lh final-artifacts/clients/
 
-      # Write downloadable checksums for the exact JSON and client archive bytes.
       - name: Hash release artifacts
         run: |
           cd final-artifacts
@@ -456,8 +447,7 @@ jobs:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: gh release delete latest --yes --cleanup-tag || true
 
-      # Step 4: publish JSON as a separate asset beside binaries in the same release.
-      # Consumers download osquery-schema.json; they do not extract it from a binary.
+      # Publish JSON as a separate release asset beside the binaries.
       - name: Create Release
         uses: softprops/action-gh-release@v2
         with:
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index c5bce1a5a8c..5ea6ed638ba 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -32,8 +32,7 @@ env:
 # =============================================================================
 
 jobs:
-  # Check the JSON exporter with small .table fixtures and simulated binary replies.
-  # The build jobs below separately verify the real catalog against real binaries.
+  # Unit-test the exporter with .table fixtures and simulated binary replies.
   schema_test:
     name: Test Release Schema Exporter
     runs-on: ubuntu-latest
@@ -145,9 +144,7 @@ jobs:
           
           echo "Build completed successfully"
 
-      # Read the .table files selected by CMake, then run the newly built executable
-      # to check the engine version and advertised native table/column names and aliases.
-      # Export or verification errors fail this build; this step does not fetch table data.
+      # Export CMake-selected .table files; SELECTs check version, columns and aliases in the built binary.
       - name: Verify built table schema
         env:
           SOURCE_COMMIT: ${{ github.sha }}
@@ -207,8 +204,7 @@ jobs:
           cd build
           cmake --build . --config RelWithDebInfo -j10
 
-      # Perform the same catalog-versus-binary check on Windows, not on a Mac binary.
-      # --binary makes verification mandatory here; JSON is written only after it passes.
+      # Verify the exported Windows schema against the built executable.
       - name: Verify built table schema
         shell: bash
         env:
@@ -221,7 +217,6 @@ jobs:
             --release-tag pr-test --osquery-version 5.9.1 --source-commit "$SOURCE_COMMIT" \
             --binary build/osquery/RelWithDebInfo/osqueryd.exe --output schema/osquery-schema.json
 
-  # Report failure if exporter tests or any platform build/schema check failed.
   all-checks:
     name: "All Checks"
     needs: [schema_test, build_macos, build_windows]
diff --git a/tools/codegen/release_schema.py b/tools/codegen/release_schema.py
index 9a0eb9397d6..704041945b7 100644
--- a/tools/codegen/release_schema.py
+++ b/tools/codegen/release_schema.py
@@ -13,15 +13,12 @@
 import gentable
 
 
-# Each release contains a catalog for these three binary builds.
 REQUIRED_VARIANTS = {("darwin", "amd64"), ("darwin", "arm64"), ("windows", "amd64")}
-# Build catalogs can be combined only when they describe the same source and release.
 PROVENANCE_FIELDS = ("formatVersion", "releaseTag", "osqueryVersion", "sourceCommit")
 
 
 def selected_specs(manifest, source_root):
-    # CMake lists the .table files selected for this build. Do not scan every spec:
-    # doing so could include tables that were not selected for this binary.
+    # Use CMake's selected files, not every .table file in the repository.
     paths = [Path(value).resolve() for value in manifest.read_text(encoding="utf-8").strip().split(";") if value]
     specs_root = (source_root / "specs").resolve()
     for path in paths:
@@ -33,25 +30,20 @@ def selected_specs(manifest, source_root):
 
 
 def platform_names(platforms):
-    # Use the public platform name in JSON instead of Python's Windows identifiers.
     return sorted({"windows" if name in gentable.WINDOWS else name for name in platforms})
 
 
 def table_metadata(path, platform, availability, source_root, source_commit):
-    # Read each trusted repository .table file with osquery's existing generator.
-    # Use the target OS, not the OS running this script, and reset the previous table.
+    # Reuse osquery's generator for the target OS, resetting its state for each table.
     gentable.PLATFORM = "win32" if platform == "windows" else platform
     gentable.table.__init__()
     namespace = dict(vars(gentable))
     exec(compile(path.read_text(encoding="utf-8"), str(path), "exec"), namespace)
     table = gentable.table
-    # Fail on an incomplete table; never publish a partial catalog by skipping it.
     if not table.table_name or not table.columns() or not table.function:
         raise ValueError("Incomplete table spec: {}".format(path))
     if gentable.is_denylisted(table.table_name, path=str(path)):
         availability = "disabled"
-    # Copy every column returned by the generator, including hidden columns.
-    # Descriptions, aliases and constraints help the AI construct a suitable query.
     return {
         "name": table.table_name,
         "aliases": table.aliases,
@@ -84,13 +76,11 @@ def export_variant(source_root, native_manifest, foreign_manifest, platform, arc
         raise ValueError("sourceCommit must be the full source commit SHA")
     if not release_tag or not re.fullmatch(r"\d+\.\d+\.\d+", osquery_version):
         raise ValueError("Missing release tag or invalid osquery version")
-    # Native tables have implementations for this build. Foreign tables describe
-    # other platforms; disabled tables are excluded by osquery's denylist.
+    # Foreign tables describe other platforms; only native tables are verified below.
     native = selected_specs(Path(native_manifest), source_root)
     foreign = selected_specs(Path(foreign_manifest), source_root)
     if not native or set(native) & set(foreign):
         raise ValueError("Native selection is empty or overlaps foreign selection")
-    # Process every selected file. A read, parse or conversion error stops export.
     tables = sorted(
         [table_metadata(path, platform, availability, source_root, source_commit)
          for paths, availability in ((native, "native"), (foreign, "foreign")) for path in paths],
@@ -104,7 +94,6 @@ def export_variant(source_root, native_manifest, foreign_manifest, platform, arc
 
 
 def aggregate(parts):
-    # Combine the three build catalogs without mixing releases or source commits.
     if not parts:
         raise ValueError("No schema variants")
     provenance = {field: parts[0][field] for field in PROVENANCE_FIELDS}
@@ -114,7 +103,6 @@ def aggregate(parts):
             raise ValueError("Schema variants have different source/version provenance")
         variants.extend(part["variants"])
     keys = [(variant["platform"], variant["architecture"]) for variant in variants]
-    # A release must contain each required OS/architecture exactly once.
     if set(keys) != REQUIRED_VARIANTS or len(keys) != len(REQUIRED_VARIANTS):
         raise ValueError("Release needs exactly darwin/amd64, darwin/arm64 and windows/amd64")
     variants.sort(key=lambda variant: (variant["platform"], variant["architecture"]))
@@ -122,8 +110,6 @@ def aggregate(parts):
 
 
 def write_artifact(artifact, output):
-    # Publish JSON as a separate release file, not as content inside the binary.
-    # Hash the exact bytes written to disk for the accompanying checksum file.
     raw = (json.dumps(artifact, ensure_ascii=False, indent=2) + "\n").encode("utf-8")
     output.parent.mkdir(parents=True, exist_ok=True)
     output.write_bytes(raw)
@@ -133,8 +119,7 @@ def write_artifact(artifact, output):
 
 def verify_binary(artifact, binary):
     """Check version and SQL column/alias registration without reading table data."""
-    # Run the newly built osquery executable with a temporary database/config.
-    # Disable extensions and events so they do not change the inspected schema.
+    # Isolate the schema check from installed extensions and existing osquery state.
     with tempfile.TemporaryDirectory(prefix="osquery-schema-") as scratch:
         config = Path(scratch) / "config.json"
         config.write_text("{}", encoding="utf-8")
@@ -147,12 +132,10 @@ def query(sql):
             )
             return json.loads(result.stdout)
 
-        # Ask the executable for its version, rather than trusting a file name.
         rows = query("select version from osquery_info;")
         if len(rows) != 1 or rows[0]["version"] != artifact["osqueryVersion"]:
             raise ValueError("Built binary version differs from schema version")
         for table in artifact["variants"][0]["tables"]:
-            # Foreign and disabled tables are not supported native implementations.
             if table["availability"] != "native":
                 continue
             all_columns = {column["name"] for column in table["columns"]}
@@ -164,8 +147,7 @@ def query(sql):
                 escaped = name.replace("'", "''")
                 columns = query("select name from pragma_table_xinfo('{}');".format(escaped))
                 names = {column["name"] for column in columns}
-                # Every advertised column must exist in the executable. This is
-                # one-way: omitted tables/columns and column types are not checked.
+                # This checks advertised columns, not omitted columns or column types.
                 if not expected <= names:
                     raise ValueError("Built table {} missing columns {}".format(name, sorted(expected - names)))
             for column in table["columns"]:
@@ -173,8 +155,7 @@ def query(sql):
                     if not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", alias):
                         raise ValueError("Unexpected SQL column alias: {}".format(alias))
                     quoted_table = table["name"].replace('"', '""')
-                    # LIMIT 0 checks that SQL accepts the alias without fetching rows.
-                    # This does not test JOINs, device permissions or actual table data.
+                    # LIMIT 0 checks alias syntax without fetching device data.
                     query('select [{}] from "{}" limit 0;'.format(alias, quoted_table))
 
 
@@ -197,18 +178,13 @@ def main():
     merge.add_argument("--output", type=Path, required=True)
     args = parser.parse_args()
     if args.command == "variant":
-        # Step 1: turn this build's selected .table files into an in-memory catalog.
         artifact = export_variant(args.source_root, args.native_specs, args.foreign_specs,
                                   args.platform, args.architecture, args.release_tag,
                                   args.osquery_version, args.source_commit)
         if args.binary:
-            # Step 2: CI supplies --binary to verify the catalog against real osquery.
-            # Any verification failure prevents this command from writing the JSON.
             verify_binary(artifact, args.binary)
     else:
-        # Step 3: the release job merges the three already verified build catalogs.
         artifact = aggregate([json.loads(path.read_text(encoding="utf-8")) for path in args.variants])
-    # Step 4: write the individual or combined catalog and its checksum file.
     write_artifact(artifact, args.output)
     print("Exported {} variant(s), {} tables: {}".format(
         len(artifact["variants"]), sum(len(v["tables"]) for v in artifact["variants"]), args.output))
@@ -218,6 +194,5 @@ def main():
     try:
         main()
     except (ValueError, OSError, subprocess.SubprocessError) as error:
-        # Exit non-zero so CI stops instead of publishing an unverified release.
         print("Schema export failed: {}".format(error), file=sys.stderr)
         sys.exit(1)