feat(go): add SDK with release-downloaded native bindings

.github/workflows/go-sdk-test.yml

@@ -0,0 +1,67 @@
+name: Go SDK test
+
+permissions:
+  contents: read
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'sdks/go/**'
+      - '.github/workflows/go-sdk-test.yml'
+  pull_request:
+    paths:
+      - 'sdks/go/**'
+      - '.github/workflows/go-sdk-test.yml'
+
+jobs:
+  unit-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.22.2'
+
+      - name: Run SDK unit tests without native bindings
+        working-directory: sdks/go/sdk
+        env:
+          CGO_ENABLED: '0'
+        run: go test ./...
+
+      - name: Verify SDK standalone module mode
+        working-directory: sdks/go/sdk
+        env:
+          CGO_ENABLED: '0'
+          GOWORK: 'off'
+        run: go test ./...
+
+      - name: Run native installer tests
+        working-directory: sdks/go/tools/install
+        run: go test ./...
+
+  bindings-smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.22.2'
+
+      - name: Install linux-amd64 native library
+        working-directory: sdks/go
+        run: go run ./tools/install --release c-sdk-v0.9.0
+
+      - name: Verify bindings compile with CGO
+        working-directory: sdks/go/bindings
+        env:
+          CGO_ENABLED: '1'
+        run: go build -v .
+
+      - name: Verify SDK compiles with CGO
+        working-directory: sdks/go/sdk
+        env:
+          CGO_ENABLED: '1'
+        run: go build -v .

.github/workflows/publish-go-sdk.yml

@@ -0,0 +1,72 @@
+name: Publish Go SDK
+
+permissions:
+  contents: write
+
+on:
+  workflow_dispatch:
+    inputs:
+      c_sdk_version:
+        description: 'C SDK GitHub release tag'
+        required: true
+        default: 'c-sdk-v0.9.0'
+      go_version:
+        description: 'Go module version to publish'
+        required: true
+        default: 'v0.1.2'
+
+concurrency:
+  group: go-sdk-release-${{ github.event.inputs.go_version }}
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    env:
+      C_SDK_VERSION: ${{ github.event.inputs.c_sdk_version }}
+      GO_VERSION: ${{ github.event.inputs.go_version }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.22.2'
+
+      - name: Configure Git author
+        run: |
+          git config user.name 'github-actions[bot]'
+          git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
+
+      - name: Update bindings native version metadata
+        shell: bash
+        run: |
+          if [[ ! "${C_SDK_VERSION}" =~ ^c-sdk-v[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]]; then
+            echo "c_sdk_version must be a c-sdk-vMAJOR.MINOR.PATCH tag" >&2
+            exit 1
+          fi
+          if [[ ! "${GO_VERSION}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]]; then
+            echo "go_version must be a vMAJOR.MINOR.PATCH tag" >&2
+            exit 1
+          fi
+          NATIVE_VERSION="${C_SDK_VERSION#c-sdk-v}"
+          cat > sdks/go/bindings/version.go <<EOF
+          package mosscore
+
+          // NativeLibVersion is the Moss C SDK version downloaded at build time.
+          const NativeLibVersion = "${NATIVE_VERSION}"
+
+          // NativeLibReleaseTag is the GitHub release tag used to fetch native artifacts.
+          const NativeLibReleaseTag = "${C_SDK_VERSION}"
+          EOF
+
+      - name: Verify selected C SDK release
+        working-directory: sdks/go
+        run: go run ./tools/install --all --release "$C_SDK_VERSION"
+
+      - name: Verify native Go SDK build
+        run: |
+          (cd sdks/go/bindings && CGO_ENABLED=1 go build .)
+          (cd sdks/go/sdk && CGO_ENABLED=1 go build .)
+
+      - name: Publish source-only module tags
+        run: ./sdks/go/scripts/publish-sdk-module-tags.sh "$GO_VERSION"

examples/go/README.md

@@ -16,13 +16,20 @@ export MOSS_PROJECT_ID=...
 export MOSS_PROJECT_KEY=...
 ```
 
-Runtime operations require the `libmoss` C SDK and the `libmoss` build tag:
+Install the native library for your platform:
 
 ```bash
-export CGO_CFLAGS="-I<libmoss-sdk-root>/include"
-export CGO_LDFLAGS="-L<libmoss-sdk-root>/lib"
-export LD_LIBRARY_PATH="<libmoss-sdk-root>/lib"
+# Monorepo dev:
+../../sdks/go/scripts/link_dev_lib.sh c-sdk-v0.9.0
 
-go run -tags libmoss ./basic
-go run -tags libmoss ./custom-embeddings
+# Or after go get:
+go run github.com/usemoss/moss/sdks/go/tools/install@latest --vendor
+```
+
+Then run an example:
+
+```bash
+cd examples/go
+go run ./basic
+go run ./custom-embeddings
 ```

sdks/go/README.md

@@ -1,20 +1,48 @@
 # Moss Go SDK
 
-The Go work now has the same two-layer direction as the other Moss SDKs:
+The Go SDK follows the same two-layer design as the other Moss SDKs:
 
 - `sdks/go/sdk/` contains the public Go SDK
 - `sdks/go/bindings/` wraps the native `libmoss` runtime via CGO
 
-Current status:
+## Install
 
-- bindings-backed manage operations for mutations and metadata reads
-- local `LoadIndex` / `UnloadIndex` / `GetIndexInfo` / local `Query` via `libmoss`
-- examples under `examples/go/` and unit tests
-- env-gated integration test scaffold
+```bash
+go get github.com/usemoss/moss/sdks/go/sdk
+go run github.com/usemoss/moss/sdks/go/tools/install@latest --vendor
+```
 
-Important note:
+The install tool downloads the static `libmoss` library for your platform from
+[Moss C SDK GitHub Releases](https://github.com/usemoss/moss/releases). You need
+CGO and a C compiler, but not a manual C SDK download or `LD_LIBRARY_PATH`.
+For external projects, the explicit `--vendor` option lets the installer vendor
+the bindings before placing the library next to them, so the normal `go build`
+command finds it.
 
-- all runtime operations require the `libmoss` C SDK plus `-tags libmoss`
+Native bindings currently support Linux (`amd64`, `arm64`) and Apple Silicon
+macOS (`arm64`). Other platforms, including Windows, use the
+bindings-unavailable stub until a compatible native release is available.
 
-The public SDK module lives under [`sdks/go/sdk/`](./sdk/), and the native
-bindings module lives under [`sdks/go/bindings/`](./bindings/).
+From a checkout of the bindings package, you can instead use:
+
+```bash
+go generate github.com/usemoss/moss/sdks/go/bindings
+```
+
+## Local development
+
+```bash
+./sdks/go/scripts/link_dev_lib.sh c-sdk-v0.9.0
+cd sdks/go/sdk
+CGO_ENABLED=1 go test ./...
+```
+
+Unit tests run without native libraries when `CGO_ENABLED=0`.
+
+## Publishing
+
+See [`bindings/README.md`](./bindings/README.md) and
+[`.github/workflows/publish-go-sdk.yml`](../../.github/workflows/publish-go-sdk.yml).
+
+The public SDK module lives under [`sdk/`](./sdk/), and the native bindings module
+lives under [`bindings/`](./bindings/).

sdks/go/bindings/README.md

@@ -9,33 +9,94 @@ It mirrors the role of the other language bindings packages in this repository:
 - local query execution
 - cloud-backed manage operations exposed through the native client
 
-## Status
+## Installation (consumers)
 
-The real bindings implementation is compiled only with the `libmoss` build tag.
-Without that tag, this package builds a stub that returns a clear
-`ErrBindingsUnavailable` error.
+```bash
+go get github.com/usemoss/moss/sdks/go/sdk
+go run github.com/usemoss/moss/sdks/go/tools/install@latest --vendor
+```
+
+The install tool downloads a prebuilt static library for your platform from
+[C SDK GitHub Releases](https://github.com/usemoss/moss/releases). No manual C
+SDK download, `LD_LIBRARY_PATH`, or `-tags libmoss` is required. The explicit
+`--vendor` option permits the installer to run `go mod vendor` and install the
+library beside the vendored bindings; subsequent `go build` commands use that
+copy automatically. If your project already vendors Moss, omit `--vendor` to
+avoid rewriting its `vendor/` tree.
+
+When run from a Go workspace, `--vendor` uses `go work vendor` and installs the
+library in the workspace-level `vendor/` directory.
 
-## Local build workflow
+Run the installer after your application imports the Moss SDK, so `go mod
+vendor` includes the bindings package.
 
-Download the matching `libmoss` C SDK release archive for your platform from:
+Requirements:
 
-- <https://github.com/usemoss/moss/releases/tag/c-sdk-v0.9.0>
+- `CGO_ENABLED=1` (default on Linux and macOS)
+- A C compiler (`gcc` on Linux, Xcode CLI tools on macOS)
+- One of the supported native targets: Linux (`amd64`, `arm64`) or Apple Silicon
+  macOS (`arm64`)
 
-For Linux `x86_64`, extract the archive somewhere local so you have:
+Windows currently uses the bindings-unavailable stub. Native Windows support
+will require a MinGW-compatible C SDK release artifact.
 
-```text
-<sdk-root>/
-├── include/libmoss.h
-└── lib/libmoss.so
+## Layout
+
+```
+bindings/
+  include/libmoss.h          # committed C header
+  libmoss.go                 # CGO wrapper (requires CGO)
+  prebuilt_<os>_<arch>.go    # per-platform CGO linker flags
+  generate.go                # //go:generate install hook for checkouts
+  lib/
+    linux-amd64/             # libmoss.a (gitignored, downloaded at build time)
+    linux-arm64/
+    darwin-arm64/
 ```
 
-Then build with:
+Native `.a` / `.lib` files are gitignored. The
+[`tools/install`](../tools/install) command fetches them from GitHub Releases and
+verifies SHA256 checksums.
+
+## Local development
+
+Install the native library for your current machine:
+
+```bash
+./sdks/go/scripts/link_dev_lib.sh c-sdk-v0.9.0
+```
+
+Or fetch all supported platforms:
 
 ```bash
-export CGO_CFLAGS="-I<sdk-root>/include"
-export CGO_LDFLAGS="-L<sdk-root>/lib"
-export LD_LIBRARY_PATH="<sdk-root>/lib"
-go test -tags libmoss ./...
+./sdks/go/scripts/fetch-static-libs.sh c-sdk-v0.9.0
 ```
 
-The Go SDK module can then be built with the same flags and tag.
+Or use `go generate` from a checkout of this directory:
+
+```bash
+cd sdks/go/bindings
+go generate .
+```
+
+Then build with CGO enabled:
+
+```bash
+CGO_ENABLED=1 go build .
+```
+
+## Publishing
+
+Maintainers run the **Publish Go SDK** GitHub Actions workflow. It creates
+source-only module tags (no binaries in git):
+
+- `sdks/go/sdk/v0.1.2`
+- `sdks/go/bindings/v0.1.2`
+
+Consumers download native libraries during the explicit `tools/install` step.
+
+## Build without CGO
+
+When `CGO_ENABLED=0`, this package builds a stub that returns
+`ErrBindingsUnavailable`. The public SDK can still run unit tests and cloud query
+fallback tests without native libraries.

sdks/go/bindings/errors.go

@@ -2,5 +2,5 @@ package mosscore
 
 import "errors"
 
-var ErrBindingsUnavailable = errors.New("mosscore: libmoss bindings are unavailable; build with -tags libmoss and configure the libmoss C SDK")
+var ErrBindingsUnavailable = errors.New("mosscore: libmoss bindings are unavailable; build with CGO_ENABLED=1 and install the platform native library (see sdks/go/bindings/README.md)")
 var ErrClientClosed = errors.New("mosscore: client is closed")

sdks/go/bindings/generate.go

@@ -0,0 +1,3 @@
+package mosscore
+
+//go:generate go run ../tools/install