Open-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATT&CK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.
Python agentic-aiai-securityalert-triageblue-teamcybersecuritydetection-engineeringincident-responselanggraphllm-agentsmcpmitre-attackmodel-context-protocolpurple-teamsecurity-operationsself-hostedsiemsoarsocthreat-detectionthreat-intelligence
feat(release): a two-directional release-policy gate, a stable channel and an upgrade test with data (Phases 12.3, 12.4) (#936)
Beenu Arora46ac5a8f83a8
diff --git a/.github/workflows/governance.yml b/.github/workflows/governance.ymlindex 10108a356..bfc4c759d 100644--- a/.github/workflows/governance.yml+++ b/.github/workflows/governance.yml@@ -24,6 +24,10 @@ on:- "TRADEMARK.md"- "scripts/check_slos.py"- "scripts/check_governance.py"+ - "scripts/check_release_policy.py"+ - "CHANGELOG.md"+ - "VERSION"+ - "apps/docs/docs/operations/release-policy.md"- ".github/workflows/governance.yml"pull_request:paths:@@ -38,6 +42,10 @@ on:- "TRADEMARK.md"- "scripts/check_slos.py"- "scripts/check_governance.py"+ - "scripts/check_release_policy.py"+ - "CHANGELOG.md"+ - "VERSION"+ - "apps/docs/docs/operations/release-policy.md"- ".github/workflows/governance.yml"workflow_dispatch:@@ -60,3 +68,10 @@ jobs:run: python3 scripts/check_slos.py --print- name: Governance completeness gaterun: python3 scripts/check_governance.py++ # Two directions, and the self-test runs first because a gate nobody has+ # proven can fail is indistinguishable from one that cannot.+ - name: Self-test the release-policy gate+ run: python3 scripts/check_release_policy.py --self-test+ - name: A major declares what it breaks, and nothing else declares a break+ run: python3 scripts/check_release_policy.pydiff --git a/.github/workflows/publish-cli.yml b/.github/workflows/publish-cli.ymlindex cb3172d55..9784d090c 100644--- a/.github/workflows/publish-cli.yml+++ b/.github/workflows/publish-cli.yml@@ -70,15 +70,35 @@ jobs:name: aisoc-npm-tarballpath: packages/aisoc-lite/*.tgz- - name: Publish to npm with provenance+ # Trusted publishing (OIDC) needs npm 11.5.1 or newer; Node 22 ships+ # npm 10, which falls back to token auth and then fails with ENEEDAUTH.+ - name: Upgrade npm for trusted publishing+ if: vars.AISOC_NPM_TRUSTED_PUBLISHING == 'true'+ run: |+ set -euo pipefail+ npm install -g npm@latest+ npm --version++ # npm validates a trusted publisher against the *workflow filename*, so+ # this file is registered separately from release.yml on npmjs.com even+ # though both publish the same package. The names are in+ # docs/operations/publishing.md; changing either filename breaks+ # publishing with ENEEDAUTH and nothing else.+ - name: Publish to npmif: ${{ github.event_name == 'push' && startsWith(github.ref, 'refs/tags/cli-v') }}working-directory: packages/aisoc-liteenv:NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}+ TRUSTED: ${{ vars.AISOC_NPM_TRUSTED_PUBLISHING }}run: |set -euo pipefail+ if [ "${TRUSTED:-}" = "true" ]; then+ # Provenance is generated automatically on the OIDC path.+ npm publish --access public+ exit 0+ fiif [ -z "${NODE_AUTH_TOKEN:-}" ]; then- echo "::notice::NPM_TOKEN not configured — skipping publish (tarball uploaded as an artifact). Configure the secret to enable automated publish."+ echo "::notice::Neither trusted publishing nor NPM_TOKEN is configured, so the tarball was uploaded as an artifact and nothing was published. See docs/operations/publishing.md."exit 0finpm publish --provenance --access publicdiff --git a/.github/workflows/release.yml b/.github/workflows/release.ymlindex bbb3efcf8..f3002a33b 100644--- a/.github/workflows/release.yml+++ b/.github/workflows/release.yml@@ -23,6 +23,11 @@ on:description: 'Existing release tag whose images should be (re)published, e.g. v11.0.0'required: truetype: string+ promote_stable:+ description: 'Move the `stable` tag onto this release. A major does not move it automatically, because a major means an operator must act.'+ required: false+ default: false+ type: booleanpermissions:contents: write@@ -40,6 +45,18 @@ jobs:with:fetch-depth: 0+ # Before anything publishes. A release whose version and notes disagree+ # is far cheaper to stop than to withdraw: images carry the tag,+ # registries refuse a re-upload of a package version, and the release+ # note is the first thing an operator reads. Both directions are+ # checked: a major with no BREAKING section, and a BREAKING section on+ # something that is not a major.+ - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0+ with:+ python-version: '3.11'+ - name: The tag and its changelog section agree about breakage+ run: python3 scripts/check_release_policy.py --tag "${GITHUB_REF_NAME}"+- name: Extract version from tagid: versionrun: echo "VERSION=${GITHUB_REF_NAME}" >> $GITHUB_OUTPUT@@ -506,19 +523,49 @@ jobs:# — which is the defect this whole workflow was being changed to fix,# inflicted by the tool built to fix it. The first republish of v11.0.0# did exactly that to eight images before this was caught.+ #+ # `stable` is the third tag, and it is not a synonym for `latest`.+ # `latest` moves on every release, majors included. A deployment that+ # pulls by tag would therefore be dragged across a breaking change by a+ # tag whose name promises the opposite, with no operator decision in+ # between, and the release policy says a major means an operator must+ # act. So `stable` moves on a minor or a patch automatically and stops+ # at a major until someone dispatches the workflow with+ # `promote_stable: true`. See apps/docs/docs/operations/release-policy.md.+ #+ # tests/test_release_channel_tags.py runs this exact block under bash+ # with each combination, because a tag-selection rule expressed only in+ # a workflow is a rule nothing checks.- id: image-tagsenv:VERSION: ${{ inputs.tag || github.ref_name }}REPUBLISH: ${{ github.event_name == 'workflow_dispatch' }}+ PROMOTE_STABLE: ${{ inputs.promote_stable }}+ IMAGE: ${{ matrix.image }}+ IS_DEMO: ${{ matrix.demo }}run: |+ set -euo pipefail+ # A major is `vX.0.0`. Anything else in the line is a minor or a+ # patch and carries no operator action by policy.+ IS_MAJOR=false+ case "${VERSION#v}" in+ *.0.0) IS_MAJOR=true ;;+ esac{echo 'tags<<EOF'- if [ "${{ matrix.demo }}" = "true" ]; then- echo "${{ matrix.image }}:${VERSION}-demo"- [ "$REPUBLISH" = "true" ] || echo "${{ matrix.image }}:demo"+ if [ "$IS_DEMO" = "true" ]; then+ echo "${IMAGE}:${VERSION}-demo"+ [ "$REPUBLISH" = "true" ] || echo "${IMAGE}:demo"else- echo "${{ matrix.image }}:${VERSION}"- [ "$REPUBLISH" = "true" ] || echo "${{ matrix.image }}:latest"+ echo "${IMAGE}:${VERSION}"+ [ "$REPUBLISH" = "true" ] || echo "${IMAGE}:latest"+ # Automatic on a non-major push; deliberate on a dispatch. The+ # dispatch arm is the only way `stable` ever reaches a major,+ # and it is separate from the republish arm above so repairing+ # an old tag cannot drag `stable` backwards with it.+ if { [ "$REPUBLISH" != "true" ] && [ "$IS_MAJOR" != "true" ]; } || [ "$PROMOTE_STABLE" = "true" ]; then+ echo "${IMAGE}:stable"+ fifiecho 'EOF'} >> "$GITHUB_OUTPUT"@@ -664,19 +711,43 @@ jobs:echo "already=false" >> "$GITHUB_OUTPUT"fi- - name: Publish to npm- if: steps.exists.outputs.already == 'false' && env.NPM_TOKEN != ''+ # Trusted publishing (OIDC) needs npm 11.5.1 or newer. Node 22 ships+ # npm 10, which silently falls back to token authentication and then+ # fails with ENEEDAUTH when there is no token, so the upgrade is what+ # makes the token-free path reachable at all rather than a nicety.+ - name: Upgrade npm for trusted publishing+ if: vars.AISOC_NPM_TRUSTED_PUBLISHING == 'true'+ run: |+ set -euo pipefail+ npm install -g npm@latest+ npm --version++ # Token-free. npm exchanges the workflow's OIDC token for a short-lived+ # publish credential, which cannot be exfiltrated from a log or left+ # unrotated in repository settings. Provenance is generated+ # automatically on this path, so `--provenance` is not passed.+ - name: Publish to npm (trusted publishing)+ if: steps.exists.outputs.already == 'false' && vars.AISOC_NPM_TRUSTED_PUBLISHING == 'true'+ run: npm publish "${{ steps.pack.outputs.tarball }}" --access public++ # The fallback, for as long as it is needed. npm configures a trusted+ # publisher on a package's settings page, so a package that has never+ # been published has no settings page and no way to register one: the+ # very first upload of each package needs a token, and every upload+ # after it does not.+ - name: Publish to npm (token)+ if: steps.exists.outputs.already == 'false' && vars.AISOC_NPM_TRUSTED_PUBLISHING != 'true' && env.NPM_TOKEN != ''env:NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}run: npm publish "${{ steps.pack.outputs.tarball }}" --access public --provenance- name: Explain a skipped publish- if: steps.exists.outputs.already == 'true' || env.NPM_TOKEN == ''+ if: steps.exists.outputs.already == 'true' || (vars.AISOC_NPM_TRUSTED_PUBLISHING != 'true' && env.NPM_TOKEN == '')run: |if [ "${{ steps.exists.outputs.already }}" = "true" ]; then- echo "::notice title=npm::${{ matrix.pkg }}@${{ steps.pack.outputs.version }} is already published — nothing to do."+ echo "::notice title=npm::${{ matrix.pkg }}@${{ steps.pack.outputs.version }} is already published, nothing to do."else- echo "::warning title=npm::NPM_TOKEN is not configured, so ${{ matrix.pkg }} was built and packed but not uploaded. See docs/operations/publishing.md."+ echo "::warning title=npm::Neither trusted publishing nor NPM_TOKEN is configured, so ${{ matrix.pkg }} was built and packed but not uploaded. See docs/operations/publishing.md."fi# ── Publish the PyPI packages ──────────────────────────────────────────────@@ -736,6 +807,88 @@ jobs:run: |echo "::warning title=PyPI::Trusted publishing is not enabled, so ${{ matrix.pkg }} was built and validated but not uploaded. Set the AISOC_PYPI_TRUSTED_PUBLISHING repository variable to 'true' once the pending publishers exist — see docs/operations/publishing.md."+ # ── Publish the Helm chart ────────────────────────────────────────────────+ #+ # `apps/docs/docs/deployment/kubernetes.md` told operators to run+ # `helm show chart oci://ghcr.io/beenuar/aisoc` to find out what a default+ # install resolves to, and no chart has ever been pushed there: the command+ # answers `not found`. A published command is a claim, and this is the job+ # that makes it true rather than the sentence that deletes it.+ #+ # Package and lint run unconditionally so the job fails the moment the chart+ # stops being publishable, rather than only discovering it on a tag. Only+ # the push is conditional, and only on the event: GITHUB_TOKEN already has+ # `packages: write`, so unlike npm and PyPI there is no missing credential+ # here.+ chart-publish:+ name: Helm - publish the chart+ runs-on: ubuntu-latest+ needs: release+ if: always() && (github.event_name == 'push' || needs.release.result == 'success')+ timeout-minutes: 15+ permissions:+ contents: read+ packages: write+ steps:+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7+ - uses: azure/setup-helm@b9e51907a09c216f16ebe8536097933489208112 # v4.3.0+ with:+ version: v3.18.5++ - name: Fetch dependencies, lint and package+ id: package+ run: |+ set -euo pipefail+ helm repo add bitnami https://charts.bitnami.com/bitnami+ helm repo update+ helm dependency build infra/helm/aisoc+ helm lint infra/helm/aisoc+ # The chart's own version, not the release tag. They move+ # independently: appVersion names the images, version names the+ # chart, and pinning one to the other would force a chart release+ # for a change that did not touch it.+ version=$(helm show chart infra/helm/aisoc | awk '/^version:/ {print $2}')+ test -n "$version"+ helm package infra/helm/aisoc --destination "$RUNNER_TEMP"+ echo "version=$version" >> "$GITHUB_OUTPUT"+ echo "package=$RUNNER_TEMP/aisoc-$version.tgz" >> "$GITHUB_OUTPUT"++ # The chart's appVersion is what every unpinned image tag in values.yaml+ # falls back to. A chart published naming a version no image carries is+ # an install that goes straight to ImagePullBackOff, which is what+ # appVersion 5.2.0 would have done for months.+ - name: The appVersion names images that exist+ run: |+ set -euo pipefail+ python -m pip install --quiet pyyaml+ python3 scripts/check_published_images.py --require-network --list++ - name: Log in to GHCR+ if: github.event_name == 'push'+ uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4+ with:+ registry: ghcr.io+ username: ${{ github.actor }}+ password: ${{ secrets.GITHUB_TOKEN }}++ - name: Push to the OCI registry+ if: github.event_name == 'push'+ run: |+ set -euo pipefail+ helm push "${{ steps.package.outputs.package }}" oci://ghcr.io/beenuar/charts+ echo "::notice title=Helm::Published oci://ghcr.io/beenuar/charts/aisoc:${{ steps.package.outputs.version }}"++ - name: Prove it resolves+ if: github.event_name == 'push'+ run: |+ set -euo pipefail+ helm show chart "oci://ghcr.io/beenuar/charts/aisoc" --version "${{ steps.package.outputs.version }}"++ - name: Explain a packaged-but-unpushed chart+ if: github.event_name != 'push'+ run: |+ echo "::notice title=Helm::Chart ${{ steps.package.outputs.version }} was packaged and linted but not pushed; this run was not a tag push."+# ── Prove the release actually published every image ────────────────────## v11.0.0 is why this exists: twelve images carried the tag, the console diddiff --git a/.github/workflows/upgrade-test.yml b/.github/workflows/upgrade-test.ymlnew file mode 100644index 000000000..aedbc2347--- /dev/null+++ b/.github/workflows/upgrade-test.yml@@ -0,0 +1,222 @@+name: Upgrade test++# Upgrade the previous minor to this tree, with data already in the database.+#+# A fresh install applies every migration to an empty schema, which is the one+# case that cannot go wrong. The defects that reach operators are the other+# ones: an `ALTER TABLE ... ADD COLUMN ... NOT NULL` with no default against a+# populated table, a unique index added over rows that already violate it, a+# backfill that assumes a column it is about to create, a type change that+# succeeds on zero rows and fails on a million. None of those is visible+# without data present.+#+# How it works, and why it uses the published image+# -------------------------------------------------+# The migration runner lives in `services/api` and needs that service's+# dependencies. Rather than reconstruct them, this runs the *published*+# previous-minor image twice:+#+# 1. with its own `/app/migrations`, producing the schema an operator on the+# previous release actually has;+# 2. with this tree's `services/api/migrations` bind-mounted over+# `/app/migrations`, which is the upgrade.+#+# The same runner applies both legs, so what is being tested is the migration+# chain rather than a re-implementation of how it is applied. The limit is+# stated rather than hidden: a migration that needs a *newer runner* than the+# previous release shipped is not covered here, and would show up as a failure+# in the second leg rather than as a silent pass.++on:+ pull_request:+ paths:+ - 'services/api/migrations/**'+ - 'services/api/app/scripts/run_migrations.py'+ - 'services/*/alembic/**'+ - '.github/workflows/upgrade-test.yml'+ - 'scripts/upgrade_fixture.sql'+ push:+ branches: [main]+ paths:+ - 'services/api/migrations/**'+ - 'services/api/app/scripts/run_migrations.py'+ - 'services/*/alembic/**'+ - '.github/workflows/upgrade-test.yml'+ - 'scripts/upgrade_fixture.sql'+ workflow_dispatch:++concurrency:+ group: ${{ github.workflow }}-${{ github.ref }}+ cancel-in-progress: true++permissions:+ contents: read++jobs:+ upgrade:+ name: Previous minor to this tree, with data present+ runs-on: ubuntu-latest+ timeout-minutes: 25++ services:+ postgres:+ image: postgres:16-alpine+ env:+ POSTGRES_USER: aisoc+ POSTGRES_PASSWORD: aisoc_dev_secret+ POSTGRES_DB: aisoc+ ports:+ - 5432:5432+ options: >-+ --health-cmd "pg_isready -U aisoc -d aisoc"+ --health-interval 5s+ --health-timeout 5s+ --health-retries 20++ steps:+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7+ - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0+ with:+ python-version: '3.11'++ - name: Which release are we upgrading from?+ id: from+ run: |+ set -euo pipefail+ previous="$(python3 scripts/check_release_policy.py --previous-minor)"+ echo "Upgrading from v${previous} to the migration chain in this tree."+ echo "version=v${previous}" >> "$GITHUB_OUTPUT"++ - name: Install a psql client+ run: sudo apt-get update -qq && sudo apt-get install -y -qq postgresql-client++ # `check_runtime_db_role.py --dsn` connects with asyncpg. Without it the+ # check refuses rather than reporting a pass it did not earn, which is+ # the right behaviour and is how this was found — so install it here+ # rather than letting the job discover it three minutes in.+ - name: Install the driver the role check connects with+ run: python3 -m pip install --quiet "asyncpg>=0.29,<0.31"++ # Leg one: the schema an operator on the previous release has.+ - name: Apply the previous release's migration chain+ env:+ IMAGE: ghcr.io/beenuar/aisoc-core-api:${{ steps.from.outputs.version }}+ run: |+ set -euo pipefail+ # aisoc-db-role: owner - the migration chain is DDL and the runtime role holds no DDL grant.+ MIGRATION_DSN='postgresql+asyncpg://aisoc:[email protected]:5432/aisoc'+ docker run --rm --network host \+ -e DATABASE_MIGRATION_URL="$MIGRATION_DSN" \+ -e DATABASE_URL='postgresql+asyncpg://aisoc_app:[email protected]:5432/aisoc' \+ -e AISOC_APP_DB_PASSWORD='aisoc_app_dev_secret' \+ "$IMAGE" python -m app.scripts.run_migrations+ echo "Applied at the previous release:"+ psql "postgresql://aisoc_app:[email protected]:5432/aisoc" -tAc \+ "select count(*) from aisoc_schema_migrations"++ # The whole point. An empty database cannot exercise a backfill, a NOT+ # NULL addition, or a unique index over existing rows.+ - name: Seed data that the upgrade has to survive+ run: |+ set -euo pipefail+ psql -v ON_ERROR_STOP=1 "postgresql://aisoc_app:[email protected]:5432/aisoc" \+ -f scripts/upgrade_fixture.sql++ - name: Record what is there before the upgrade+ run: |+ set -euo pipefail+ psql -v ON_ERROR_STOP=1 -tA "postgresql://aisoc_app:[email protected]:5432/aisoc" \+ -c "\copy (select 'alerts', count(*) from alerts union all select 'cases', count(*) from cases union all select 'tenants', count(*) from tenants union all select 'users', count(*) from users order by 1) to '/tmp/before.tsv'"+ cat /tmp/before.tsv++ # Leg two: this tree's chain, applied by the release's own runner.+ - name: Apply this tree's migration chain over the populated schema+ env:+ IMAGE: ghcr.io/beenuar/aisoc-core-api:${{ steps.from.outputs.version }}+ run: |+ set -euo pipefail+ # aisoc-db-role: owner - the migration chain is DDL and the runtime role holds no DDL grant.+ MIGRATION_DSN='postgresql+asyncpg://aisoc:[email protected]:5432/aisoc'+ docker run --rm --network host \+ -v "${GITHUB_WORKSPACE}/services/api/migrations:/app/migrations:ro" \+ -e DATABASE_MIGRATION_URL="$MIGRATION_DSN" \+ -e DATABASE_URL='postgresql+asyncpg://aisoc_app:[email protected]:5432/aisoc' \+ -e AISOC_APP_DB_PASSWORD='aisoc_app_dev_secret' \+ "$IMAGE" python -m app.scripts.run_migrations++ - name: Every migration in this tree is recorded as applied+ run: |+ set -euo pipefail+ python3 - <<'PY'+ import pathlib, subprocess, sys++ dsn = "postgresql://aisoc_app:[email protected]:5432/aisoc"+ applied = set(subprocess.run(+ ["psql", "-tA", dsn, "-c", "select name from aisoc_schema_migrations"],+ capture_output=True, text=True, check=True,+ ).stdout.split())+ on_disk = {p.name for p in pathlib.Path("services/api/migrations").glob("*.sql")}+ if not on_disk:+ sys.exit("no migrations found on disk; this check would pass over an absence")+ missing = sorted(on_disk - applied)+ if missing:+ sys.exit(f"{len(missing)} migration(s) in this tree were not applied by the upgrade: {missing}")+ print(f"OK: all {len(on_disk)} migrations applied, {len(applied)} rows in aisoc_schema_migrations.")+ PY++ # The row counts that were there before must still be there, and the+ # rows themselves must still be readable. A migration that drops and+ # recreates a table passes a count check on an empty database and+ # destroys a customer's alert history on a real one.+ - name: The data survived+ run: |+ set -euo pipefail+ psql -v ON_ERROR_STOP=1 -tA "postgresql://aisoc_app:[email protected]:5432/aisoc" \+ -c "\copy (select 'alerts', count(*) from alerts union all select 'cases', count(*) from cases union all select 'tenants', count(*) from tenants union all select 'users', count(*) from users order by 1) to '/tmp/after.tsv'"+ echo "before:"; cat /tmp/before.tsv+ echo "after:"; cat /tmp/after.tsv+ diff /tmp/before.tsv /tmp/after.tsv || {+ echo "::error::row counts changed across the upgrade"+ exit 1+ }+ # Named rows, not just counts: a table recreated with the same+ # number of fabricated rows would pass the diff above.+ psql -v ON_ERROR_STOP=1 -tA "postgresql://aisoc_app:[email protected]:5432/aisoc" -c \+ "select title from alerts where id = '11111111-1111-1111-1111-111111111111'" | grep -q 'pre-upgrade alert'+ psql -v ON_ERROR_STOP=1 -tA "postgresql://aisoc_app:[email protected]:5432/aisoc" -c \+ "select title from cases where id = '22222222-2222-2222-2222-222222222222'" | grep -q 'pre-upgrade case'+ echo "OK: the rows that were there before the upgrade are still there, by id."++ # The runtime role is what every service connects as, and a migration+ # that creates a table without granting it is a table the application+ # cannot read. That failure surfaces as a 500 after deploy, not here,+ # unless it is checked here.+ - name: The runtime role can still read what it owns nothing of+ run: |+ set -euo pipefail+ python3 scripts/check_runtime_db_role.py \+ --dsn "postgresql://aisoc_app:[email protected]:5432/aisoc"+ psql -v ON_ERROR_STOP=1 -tA \+ "postgresql://aisoc_app:[email protected]:5432/aisoc" \+ -c "select count(*) from alerts"++ - name: Re-applying the chain is a no-op+ env:+ IMAGE: ghcr.io/beenuar/aisoc-core-api:${{ steps.from.outputs.version }}+ run: |+ set -euo pipefail+ before=$(psql -tA "postgresql://aisoc_app:[email protected]:5432/aisoc" -c "select count(*) from aisoc_schema_migrations")+ # aisoc-db-role: owner - the migration chain is DDL and the runtime role holds no DDL grant.+ MIGRATION_DSN='postgresql+asyncpg://aisoc:[email protected]:5432/aisoc'+ docker run --rm --network host \+ -v "${GITHUB_WORKSPACE}/services/api/migrations:/app/migrations:ro" \+ -e DATABASE_MIGRATION_URL="$MIGRATION_DSN" \+ -e DATABASE_URL='postgresql+asyncpg://aisoc_app:[email protected]:5432/aisoc' \+ -e AISOC_APP_DB_PASSWORD='aisoc_app_dev_secret' \+ "$IMAGE" python -m app.scripts.run_migrations+ after=$(psql -tA "postgresql://aisoc_app:[email protected]:5432/aisoc" -c "select count(*) from aisoc_schema_migrations")+ test "$before" = "$after" || {+ echo "::error::a second run applied $((after - before)) more migration(s); the chain is not idempotent"+ exit 1+ }+ echo "OK: a second run applied nothing."diff --git a/CHANGELOG.md b/CHANGELOG.mdindex a0856926c..7d612d22b 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -77,6 +77,83 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0parses its own source and asserts it imports neither the hunt engine nor theloader, so it cannot score even if someone later wanted it to.+- **A release policy, enforced in both directions, and a `stable` channel that+ does not cross a major on its own** (gap-closure Phase 12.3).++ **The gap.** Nothing stated what a version number meant, which tags moved on+ their own, how long a release kept getting security fixes, or how much+ warning a removal carried. `apps/docs/docs/operations/release-policy.md` now+ says all four: a major only when an operator must act, `stable` alongside+ `latest`, security fixes on the current minor and the previous one for 90+ days after it is superseded, and a deprecation that warns at the point of+ use one minor ahead of removal.++ **The gate is two-directional**, because the one-directional gate is this+ repository's most common failure. A major bump requires a `### BREAKING`+ section, **and** a `### BREAKING` section requires a major bump. The second+ arm matters at least as much: semantic versioning is the only signal most+ automated upgrade tooling reads, and a minor is the version people let a bot+ merge unattended, so a break announced on a minor arrives through an+ unreviewed dependency update. `scripts/check_release_policy.py` proves each+ arm by injecting that exact violation, and proves they are independent by+ checking that breaking one leaves the other silent. It runs on every pull+ request through `governance.yml` and again with `--tag` in `release.yml`+ before any artefact is published. Eight majors below the 10.0.0 policy floor+ carry no breaking section; they are printed as exempt on every run rather+ than skipped quietly, because published history is not rewritten.++ **`stable` is not a synonym for `latest`.** `latest` moves on every release,+ majors included, so a deployment that pulls by tag is dragged across a+ breaking change by a tag whose name promises the opposite. `stable` advances+ on a minor or a patch and stops at a major until a maintainer dispatches the+ release workflow with `promote_stable: true`. The rule lives in a shell+ block that runs a handful of times a year, so+ `tests/test_release_channel_tags.py` lifts that block out of the workflow+ and executes it under bash for each combination rather than describing it a+ second time.++- **An upgrade test that carries data across the migration chain** (gap-closure+ Phase 12.3). A fresh install applies every migration to an empty schema,+ which is the one case that cannot go wrong. `.github/workflows/upgrade-test.yml`+ runs on every pull request touching a migration: the previous minor's+ **published image** applies its own chain, `scripts/upgrade_fixture.sql`+ seeds a tenant, a user, one alert per severity tier and a case, and then+ this tree's chain is applied over the populated schema by that same runner.+ It asserts every migration on disk is recorded as applied, that the+ pre-upgrade rows are still readable **by id** rather than only by count+ (a table dropped and repopulated passes a count check), that the DML-only+ runtime role can still read them, and that a second run applies nothing.+ Exercised locally across 81 migrations from v11.1.0 to this tree.++- **The Helm chart is published where the documentation says it is**+ (gap-closure Phase 12.3). `apps/docs/docs/deployment/kubernetes.md` told+ operators to run `helm show chart oci://ghcr.io/beenuar/aisoc`, and no chart+ has ever been pushed there: the command answers `not found`. A published+ command is a claim like any other. `release.yml` gained a `chart-publish`+ job that packages and lints on every run so the chart cannot quietly stop+ being publishable, re-checks that `appVersion` names images that exist,+ pushes to `oci://ghcr.io/beenuar/charts` on a tag, and then resolves the+ pushed chart rather than trusting the push step's exit code.++### Changed++- **npm publishing is prepared for trusted publishing (OIDC), token-free**+ (gap-closure Phase 12.4). PyPI already used it. npm's equivalent is+ configured on a package's settings page, and a package that has never been+ published has no settings page, so unlike PyPI there is no pending-publisher+ path: the first upload of each package needs a token and every upload after+ it does not. `release.yml` and `publish-cli.yml` now take the OIDC path when+ the `AISOC_NPM_TRUSTED_PUBLISHING` repository variable is `true`, fall back+ to `NPM_TOKEN`, and explain honestly when neither is configured. Three+ things make that path work and each fails with a bare `ENEEDAUTH` if missed:+ trusted publishing needs npm 11.5.1 or later and Node 22 ships npm 10, so+ the workflow upgrades npm on that path; npm matches the **workflow+ filename** exactly, so `aisoc` needs a second publisher registered for+ `publish-cli.yml`; and provenance is generated automatically on the OIDC+ path, so `--provenance` must not be passed. The one-time registry steps are+ recorded as maintainer-only in `GAP_CLOSURE_PROGRESS.md` and in+ `docs/operations/publishing.md`. **No package has been uploaded and none of+ the eight is published.**### Fixeddiff --git a/GAP_CLOSURE_PROGRESS.md b/GAP_CLOSURE_PROGRESS.mdindex 824e107ad..e879dee36 100644--- a/GAP_CLOSURE_PROGRESS.md+++ b/GAP_CLOSURE_PROGRESS.md@@ -473,8 +473,8 @@ suites' job, and anything at all against a live vendor MCP server.- [x] **12.1 Load harness** measuring sustained throughput and latency percentiles against compose and kind, published with hardware and date. `services/demo-producer --load` pushes one attributable event shape (run id, sequence number and send time in the title, a distinct host per event so the `{tenant}:{entity}:{tactic}` correlation key does not collapse the run), and `scripts/perf/load_harness.py` reads the `alerts` table and times each event to the row it became, correcting for the measured offset between the two clocks rather than assuming they agree. Measured on an Apple M5 Max, 8 CPUs and 15.6 GiB to the container runtime, on 2026-09-27: Compose drained **176.9 alerts/s** at saturation and ran **p50 976 / p95 1,091 / p99 1,156 ms** paced; a three-node kind deployment drained **214.0 alerts/s** and ran **p50 982 / p95 1,317 / p99 1,437 ms** paced. Zero loss, zero duplicates and a zero dead-letter rate in all four runs. Published at `apps/docs/docs/operations/performance.md`, raw JSON under `docs/perf/results/`, both labelled **not a service-level objective**. Two things worth keeping: the producer used to count `len(batch)` as sent the moment `Do()` returned, so a stack refusing every batch reported full throughput, and per-pod CPU and memory on kind read **"not measured"** rather than zero because `kubectl top` needs metrics-server and kind ships none.- [x] **12.2 Reference HA deployment** with a chaos test asserting no loss and no duplicates. `values-ha.yaml` runs three KRaft brokers at replication factor 3 with `min.insync.replicas=2`, multi-replica ingest, fusion, agents and API, and PDBs that will not take a second broker down voluntarily; PostgreSQL and ClickHouse stay external with managed options documented. `scripts/chaos/fusion_restart.py` destroys a replica with `--grace-period=0 --force` mid-stream and asserts **against PostgreSQL** that every accepted event produced exactly one row; on kind on 2026-09-27, 6,000 events with a replica killed 24.3 s in gave 6,000 rows, 0 missing, 0 duplicated. Running the chart found four defects rendering could not: `KAFKA_BOOTSTRAP_SERVERS` set on the UEBA deployment alone so ingest and fusion defaulted to `localhost:9092`, the first batch after an install lost to topic auto-creation, readiness probes on `/health` (always 200) instead of `/readyz` (which reports the subscription), and `ueba.enabled` with no reader. **Only kind was exercised**: no managed Kubernetes, no bare metal, no PVCs, no ingress controller, no NetworkPolicy-enforcing CNI, no managed datastores and nothing longer than a few minutes; `docs/audit/REPOSITORY_REALITY.md` states each of those as UNVERIFIED beside the claim.-- [ ] **12.3 Release policy**, including the gate that a major bump requires a BREAKING section and a BREAKING section requires a major bump.-- [ ] **12.4 Package publishing**: token-free trusted publishing prepared in `release.yml` and `publish-cli.yml`. The one-time registry steps are maintainer-only and recorded below.+- [x] **12.3 Release policy**, including the gate that a major bump requires a BREAKING section and a BREAKING section requires a major bump. `apps/docs/docs/operations/release-policy.md` states all four rules the plan names: a major only when an operator must act, a `stable` image tag and an OCI chart channel, security fixes on the current minor and the previous one for 90 days after it is superseded, and a deprecation that warns at the point of use one minor ahead of removal. `scripts/check_release_policy.py` enforces **both** arms and proves each by injecting that violation, and proves they are independent by asserting that breaking one leaves the other silent; it runs per pull request through `governance.yml` and again with `--tag` in `release.yml` before any artefact publishes. Eight pre-floor majors carry no BREAKING section and are **printed as exempt every run** rather than skipped. `stable` advances on a minor or a patch and stops at a major until `promote_stable: true` is dispatched, and `tests/test_release_channel_tags.py` executes the workflow's own tag block under bash rather than re-describing it. The upgrade test applies the **previous minor's published image** twice, once with its own chain and once with this tree's `migrations/` bind-mounted over it, with a tenant, a user, one alert per severity tier and a case already present; it asserts the rows survive **by id**, that the DML-only runtime role can still read them, and that a second run applies nothing. Exercised locally across 81 migrations from v11.1.0. The `chart-publish` job closes a dead claim: `kubernetes.md` told operators to run `helm show chart oci://ghcr.io/beenuar/aisoc`, which answers `not found`.+- [x] **12.4 Package publishing**: token-free trusted publishing prepared in `release.yml` and `publish-cli.yml`. The one-time registry steps are maintainer-only and recorded below. PyPI already had OIDC; npm now takes the OIDC path when `AISOC_NPM_TRUSTED_PUBLISHING` is `true`, falls back to `NPM_TOKEN`, and says plainly when neither is configured. **Nothing is published and no upload has been attempted.** Three constraints are load-bearing and each fails with a bare `ENEEDAUTH`: npm needs 11.5.1 or later while Node 22 ships npm 10, so the OIDC path upgrades npm first; npm validates the **workflow filename** exactly, so `aisoc` needs a second trusted publisher registered for `publish-cli.yml`; and provenance is automatic on the OIDC path, so `--provenance` must not be passed. Unlike PyPI, npm has **no pending-publisher concept** (a trusted publisher is configured on a package's settings page and an unpublished package has none), so the first upload of each npm package needs a token and every upload after it does not.## Phase 13: Enterprise identity and MSSP plumbing@@ -497,10 +497,49 @@ as a number that was not measured.measured" and never `0`. This is the same blocker that keeps hardening Phase 4deliberately unchecked.- [!] **Registry accounts and trusted-publisher setup for npm and PyPI.**- Request: create the npm organization and the PyPI trusted publisher, then- confirm so `release.yml` and `publish-cli.yml` can arm their upload steps.- The build, pack and check steps already run unconditionally, so only the- upload is gated.+ The workflows are ready and nothing is published. The build, pack and check+ steps run unconditionally, so only the upload is gated. These are the exact+ steps, in order; `docs/operations/publishing.md` carries the same list with+ the reasoning.++ **PyPI (token-free from the very first upload).** PyPI supports *pending*+ publishers, so the trust can be registered before the project exists.+ 1. At <https://pypi.org/manage/account/publishing/>, add a pending publisher+ for each of `aisoc-sandbox`, `aisoc-cli`, `aisoc-sdk`,+ `aisoc-plugin-sdk` and `aisoc-detections`, with Owner `beenuar`,+ Repository name `AiSOC`, Workflow name `release.yml`, and Environment+ name left blank.+ 2. Set the repository **variable** (not a secret)+ `AISOC_PYPI_TRUSTED_PUBLISHING` to `true`.+ 3. Push a `v*.*.*` tag. There is no token to store or rotate.++ **npm (one token, once, then token-free forever).** npm configures a trusted+ publisher on a package's *settings page*, and a package that has never been+ published has no settings page, so the first upload cannot be token-free.+ 1. Create the npm account that will own the packages and the `@aisoc`+ organisation, so the scoped packages have a home.+ 2. Create a **granular access token** scoped to `aisoc`, `@aisoc/mcp` and+ `@aisoc/sdk`, read/write, with the shortest expiry that covers one+ release. Add it as the `NPM_TOKEN` repository secret.+ 3. Push a `v*.*.*` tag. That first publish claims the `aisoc` name, which is+ still unregistered.+ 4. For each of the three packages, on npmjs.com open **Settings → Trusted+ publisher → GitHub Actions** and enter Organization or user `beenuar`,+ Repository `AiSOC`, Workflow filename `release.yml` (the filename only,+ with the extension, not a path), Environment name blank.+ 5. For `aisoc` only, add a **second** trusted publisher with the workflow+ filename `publish-cli.yml`, because the CLI also releases on its own+ `cli-v*` tag and npm validates the workflow filename rather than the+ repository alone.+ 6. Set the repository **variable** `AISOC_NPM_TRUSTED_PUBLISHING` to `true`,+ **delete the `NPM_TOKEN` secret**, and on each package set **Publishing+ access → Require two-factor authentication and disallow tokens**.++ Two things that will waste an afternoon if missed, because both fail with a+ bare `ENEEDAUTH` and nothing more specific: npm does not validate a trusted+ publisher configuration when you save it, so a typo in the workflow filename+ only surfaces at the next release; and renaming `release.yml` or+ `publish-cli.yml` breaks publishing and nothing else.- [!] **Third-party penetration test, SOC 2 and ISO 27001** for the hostedoffering (see ADR-0002), and ISO 42001 if hosted AI is sold. Request: engagethe assessors. This is a procurement action, not an engineering task.diff --git a/ROADMAP.md b/ROADMAP.mdindex d9cc89c12..11d70ddcc 100644--- a/ROADMAP.md+++ b/ROADMAP.md@@ -44,7 +44,7 @@ A proof-first, security-first program to make every README claim gate-backed, cl- **Phase D (breadth):** D1 eight connectors (QRadar/Exabeam/Securonix/Devo/Netskope/Windows-Sysmon/Zeek-Suricata/syslog-CEF) · D2 AI/LLM-usage audit connector + `llm-*` detections + hot/cold lake tiering · D3 live-vendor mock-server smoke.- **Phase E (prove it):** E1 CI-gated benchmark scoreboard tied to a deterministic live-agent MITRE-accuracy run.-The claim-to-gate matrix stands at **230 rows — 222 GATED / 8 PARTIAL / 0 NO GATE** — **every product claim is backed by a failing test** and the ratchet (`MAX_NO_GATE=0`) forbids any regression. The 8 remaining PARTIAL rows are honest, named deferrals; none was relabelled without building the gate it names. Count the table rows with `python3 scripts/check_claim_gate_matrix.py` rather than trusting a figure quoted in prose — this line has gone stale before. The six lettered deferrals are scoped in [`docs/audit/DEFERRED_SUBPHASES.md`](docs/audit/DEFERRED_SUBPHASES.md).+The claim-to-gate matrix stands at **234 rows — 226 GATED / 8 PARTIAL / 0 NO GATE** — **every product claim is backed by a failing test** and the ratchet (`MAX_NO_GATE=0`) forbids any regression. The 8 remaining PARTIAL rows are honest, named deferrals; none was relabelled without building the gate it names. Count the table rows with `python3 scripts/check_claim_gate_matrix.py` rather than trusting a figure quoted in prose — this line has gone stale before. The six lettered deferrals are scoped in [`docs/audit/DEFERRED_SUBPHASES.md`](docs/audit/DEFERRED_SUBPHASES.md).## v4.0 — Shippeddiff --git a/apps/docs/docs/compliance/evidence-pack.md b/apps/docs/docs/compliance/evidence-pack.mdindex 5db936c95..1a265804b 100644--- a/apps/docs/docs/compliance/evidence-pack.md+++ b/apps/docs/docs/compliance/evidence-pack.md@@ -33,7 +33,7 @@ and says so.| Prompt-injection resistance | Three adversarial corpora: 32 payloads scanned in isolation and 71 incident pairs whose payloads are placed in attacker-controllable fields, both against a clean twin with a recall floor and a false-positive ceiling, plus 34 held-out pairs authored after the guard was frozen and carrying no floor at all, on which the guard measures 7.1% | `services/agents/tests/adversarial/` || Claim-to-gate traceability | Every product claim mapped to the CI job that fails when it stops being true | `docs/audit/CLAIM_TO_GATE_MATRIX.md` |-The last row is the one worth reading first. It is the honest index: 222 rows+The last row is the one worth reading first. It is the honest index: 226 rows`GATED`, 8 `PARTIAL` with the specific gap named, and a ratchet that refusesto let a row sit at `NO GATE`.diff --git a/apps/docs/docs/deployment/kubernetes.md b/apps/docs/docs/deployment/kubernetes.mdindex 3e814e5a6..ffa0c0f02 100644--- a/apps/docs/docs/deployment/kubernetes.md+++ b/apps/docs/docs/deployment/kubernetes.md@@ -54,8 +54,20 @@ ghcr.io/beenuar/aisoc-web:v11.2.0```The tags above are an example pinned to a release. The current one is whatever-the chart's `appVersion` says — a default install needs no tag at all, and-`helm show chart oci://ghcr.io/beenuar/aisoc` reports what it resolves to.+the chart's `appVersion` says, and a default install needs no tag at all.++The chart itself is published to an OCI registry from v11.3.0 onward:++```bash+helm show chart oci://ghcr.io/beenuar/charts/aisoc+```++This page previously named `oci://ghcr.io/beenuar/aisoc`, where no chart has+ever been pushed: the command answered `not found`. A published command is a+claim like any other, so `release.yml` now packages, lints and pushes the+chart on every tag, and re-checks that its `appVersion` names images that+exist. Until the first release carrying that job, install from a checkout as+shown below.`scripts/check_published_images.py` resolves every one of these against GHCRdaily, so a name or tag that stops existing fails a build rather than adiff --git a/apps/docs/docs/operations/release-policy.md b/apps/docs/docs/operations/release-policy.mdnew file mode 100644index 000000000..3d3e38460--- /dev/null+++ b/apps/docs/docs/operations/release-policy.md@@ -0,0 +1,182 @@+---+id: release-policy+title: Release policy+sidebar_label: Release policy+---++# Release policy++AiSOC ships often. This page is the contract that makes that safe to live+with: what a version number means, which tags move on their own, how long a+release keeps getting security fixes, and how much warning you get before+something you depend on goes away.++It is enforced, not merely stated. `scripts/check_release_policy.py` runs on+every pull request and again at the moment a tag is pushed, and a release whose+version and notes disagree does not publish.++## A major version means an operator must act++The version number answers one question: **do I have to do something before+upgrading?**++| Change | Version |+|---|---|+| You must change configuration, run a command, or accept behaviour you cannot opt out of | **major** |+| New capability, new endpoint, new connector, anything additive | **minor** |+| A fix that changes nothing you were relying on | **patch** |++That is a narrower rule than "big release". A major is a bill for your time,+so a release that costs you nothing does not get one however large it is.++Concretely, these are majors: a removed or renamed API field, a removed+endpoint, a configuration key that no longer works, a default that flips in a+way you cannot turn back, a migration you must run out of band, a minimum+version of PostgreSQL or Kubernetes going up.++These are not: a new endpoint, a new optional setting, a new connector, a+default that changes only for deployments that never set it, a performance+change, or anything behind a feature flag that ships off.++### Both directions are enforced++A major bump requires a `### BREAKING` section in that version's changelog+entry, **and** a `### BREAKING` section requires a major bump.++The second half matters at least as much as the first. Semantic versioning is+the only signal most automated upgrade tooling reads, and a minor is the+version people let a bot merge unattended. A break announced in a note that+nobody opens, on a version everything treats as safe, arrives through an+unreviewed dependency update.++A major with no breaking notes is the mirror image: a version number that+tells an operator to read upgrade instructions that do not exist, so they+upgrade assuming the major was cosmetic.++The rule applies from **10.0.0** onward, which is the first major that carried+a breaking section. Eight earlier majors do not, and the gate prints them as+exempt on every run rather than quietly skipping them. Published history is+not rewritten.++```bash+python3 scripts/check_release_policy.py # the whole changelog+python3 scripts/check_release_policy.py --tag v12.0.0+```++## Tags and channels++### Container images++Every release publishes `ghcr.io/beenuar/aisoc-<service>:vX.Y.Z`, and moves+two channel tags.++| Tag | Moves | Use it when |+|---|---|---|+| `vX.Y.Z` | Never | Always, in production. Pin it. |+| `latest` | Every release, majors included | You want the newest thing and will read the notes |+| `stable` | Minors and patches automatically; a **major only when promoted deliberately** | You pull by tag and do not want to be moved across a break without deciding to |+| `demo` / `vX.Y.Z-demo` | Demo console only | Never in a real deployment. Demo mode is baked in at build time |++`stable` exists because `latest` cannot be both "newest" and "safe to pull+unattended". A major stops `stable` where it is until a maintainer dispatches+the release workflow with `promote_stable: true`. The rule is executed by+`tests/test_release_channel_tags.py`, which lifts the tag-selection block out+of `release.yml` and runs it under each combination rather than describing it+a second time.++Neither channel tag is ever applied by a repair run. Re-publishing the images+for an older tag moves nothing, because handing a self-hoster older content on+the tag they pull by default is the defect this arrangement exists to prevent.++### The Helm chart++The chart is published to an OCI registry on every release:++```bash+helm show chart oci://ghcr.io/beenuar/charts/aisoc+helm install aisoc oci://ghcr.io/beenuar/charts/aisoc --version <chart-version> -n aisoc --create-namespace+```++The chart's `version` and its `appVersion` move independently. `appVersion`+names the images an unpinned install pulls; `version` is the chart's own. A+chart change that does not touch the services does not force a service+release, and the reverse.++The release job packages and lints the chart on every run and pushes only on a+tag, so the chart cannot quietly stop being publishable between releases. It+also re-checks that `appVersion` names images that exist, because a chart+whose default tag resolves to nothing installs straight into+`ImagePullBackOff`.++## Security fixes: what gets one, and for how long++Security fixes land on the **current minor** and are backported to the+**previous minor** for **90 days** after it is superseded. Older lines get+nothing.++In practice that is a rolling window of two minors. Given the release cadence,+staying inside it means upgrading a minor within about a quarter.++Two things this is not. It is not a paid support commitment, and nothing here+creates one: AiSOC is MIT-licensed software maintained by its community, and+the same MIT warranty disclaimer applies to this page as to the code. And it+is not a statement about compliance certification of any kind.++Report a vulnerability through GitHub's private vulnerability reporting on the+repository, not as a public issue. `SECURITY.md` has the detail.++## Deprecation: one minor of warning, minimum++Nothing is removed without a release in which it still works and says it is+going.++1. **Minor N** ships the deprecation. The old thing keeps working. It warns at+ the point of use: a response header, a log line at `warning`, a console+ notice, or a `DeprecationWarning`, whichever a user of that surface would+ actually see. The changelog entry names the replacement.+2. **Minor N+1** at the earliest, or any later release, removes it. Removal is+ a `### BREAKING` entry and therefore a major, by the rule above.++So the minimum notice is one minor and the removal always costs a major. A+deprecation that a user cannot discover by running the software does not count+as warning them: "it was in the changelog" is not a deprecation path.++Security is the one exception. A control that has to be removed or tightened+because leaving it is unsafe ships immediately, with the reason stated.++## What a release actually publishes++A release is the set of artefacts it published, not the set of jobs that went+green. That distinction is load-bearing here: a release once reported success+having built thirty-two images and published none of them, because a skipped+upstream job propagates the whole way down a `needs` chain.++So `release.yml` ends by asking the registry rather than itself+(`scripts/check_published_images.py --require-fresh --require-network`), and+the release is not considered done until every reference in `docker-compose.yml`,+the chart and the tracked documentation resolves to an image that exists and+carries the version its tag names.++| Artefact | Published |+|---|---|+| 16 service images, `linux/amd64` + `linux/arm64` | Every release |+| Cosign signatures and SBOM attestations | Every release |+| Helm chart, to `oci://ghcr.io/beenuar/charts/aisoc` | Every release |+| Source tarball and SPDX SBOM on the GitHub Release | Every release |+| npm and PyPI packages | Built and validated every release; **uploaded only once the registries are configured**. See [`docs/operations/publishing.md`](https://github.com/beenuar/AiSOC/blob/main/docs/operations/publishing.md) |++## Upgrading++Every pull request that touches a migration runs+`.github/workflows/upgrade-test.yml`: the previous minor's published image+applies its own migration chain, data is seeded, and then the chain from the+pull request is applied over the populated schema. It asserts the rows that+were there are still there by id, that the runtime role can still read them,+and that re-applying the chain is a no-op.++A fresh install applies every migration to an empty schema, which is the one+case that cannot go wrong. The failures that reach operators need data to be+present, so the test carries some.++Operational steps for an upgrade are in [Upgrades](./upgrades.md); the+Kubernetes specifics are in [Kubernetes](../deployment/kubernetes.md).diff --git a/apps/docs/sidebars.ts b/apps/docs/sidebars.tsindex ee4c1346a..14eec574c 100644--- a/apps/docs/sidebars.ts+++ b/apps/docs/sidebars.ts@@ -202,6 +202,7 @@ const sidebars: SidebarsConfig = {"operations/theming","operations/ha-deployment","operations/performance",+ "operations/release-policy","operations/upgrades","operations/notifications","operations/action-approvals",diff --git a/docs/audit/CLAIM_TO_GATE_MATRIX.md b/docs/audit/CLAIM_TO_GATE_MATRIX.mdindex ae1a7a884..4f11c66c4 100644--- a/docs/audit/CLAIM_TO_GATE_MATRIX.md+++ b/docs/audit/CLAIM_TO_GATE_MATRIX.md@@ -238,6 +238,10 @@ Statuses: `GATED` (a CI job fails when the claim stops being true) · `PARTIAL`| A tenant with no vulnerability data is told exposure could not be checked, not that they are unaffected | `apps/docs/docs/concepts/retro-hunts.md` (KEV exposure) | `ci.yml :: api tests` (`test_kev_exposure.py` — `checked` and `exposed_asset_count` are separate fields and `exposed` requires both, so a caller reading the dataclass cannot render an unscanned tenant as clean; the wording is asserted against the module constant rather than a copy written in the test) | GATED | The case-task body additionally states the count is a floor rather than a total, because assets with no scan coverage cannot appear in it. Not gated: whether an analyst reads that sentence || Auto-triage sees the last few analyst decisions on an alert of this shape, with the reason each analyst gave | `plans/aisoc_gap_closure_plan.plan.md` (6.3) | `ci.yml :: agents tests` (`test_triage_dispositions_and_identity.py` — reads the append-only feedback table rather than the per-signature override row, which holds only the latest decision; a rule-tagged decision is asserted to order ahead of one matched on a shared entity) | GATED | Deliberately below the corroboration threshold organisation memory enforces, so a disagreement recorded once is visible here and not there. Not gated: whether the decisions shown are the most relevant ones || Analyst dispositions are point-in-time during a replay, so a replayed decision cannot see a later one | `plans/aisoc_gap_closure_plan.plan.md` (6.3, replay freeze) | `isolation-live.yml` (`test_recent_dispositions_cutoff_live.py` — the cutoff is proven against a live store rather than a stub, because an ORM-level filter that a stub satisfies is the half that has already been wrong once) | GATED | Same seam as the knowledge-base freeze. Not gated: dispositions written by a system outside this store |+| A major version means an operator must act, enforced in both directions | `apps/docs/docs/operations/release-policy.md` (A major version means an operator must act) | `governance.yml :: governance` (`check_release_policy.py`: a major bump whose changelog section carries no `### BREAKING` heading fails, **and** a `### BREAKING` heading on anything that is not a major bump fails. Both arms are proven by injecting that exact violation into a fixture changelog, and each is proven not to fire on the other's violation, so neither is passing by accident. Eight majors below the 10.0.0 policy floor are exempt and are printed on every run rather than skipped quietly) + `release.yml :: release` (`--tag`, run before any artefact is published, because a release whose version and notes disagree is far cheaper to stop than to withdraw) | GATED | The gate reads the changelog, not the diff. It cannot tell that a change *is* breaking when nobody wrote it down; what it removes is the case where somebody did write it down and the version did not follow |+| `stable` does not cross a major on its own | `apps/docs/docs/operations/release-policy.md` (Tags and channels) | `ci.yml :: python-test` (root) `test_release_channel_tags.py` lifts the tag-selection block out of `release.yml` and runs it under bash for each combination rather than re-implementing it: a minor and a patch move `stable`, every `vX.0.0` does not, a dispatch with `promote_stable` does, a republish moves neither channel, and the demo bundle carries no channel tag at all. The `promote_stable` input is asserted to be declared, so the only path by which `stable` can reach a major is reachable | GATED | It asserts which tags are computed, not that the registry ends up holding them. The latter is `docker-verify`'s job, which asks the registry rather than the workflow |+| The Helm chart is published where the documentation says it is | `apps/docs/docs/deployment/kubernetes.md`; `apps/docs/docs/operations/release-policy.md` (The Helm chart) | `release.yml :: chart-publish` (packages and lints on every run so the chart cannot quietly stop being publishable, re-checks that `appVersion` names images that exist via `check_published_images.py --require-network`, pushes on a tag, and then resolves the pushed chart with `helm show chart` rather than trusting the push step's exit code) | GATED | The page told operators to run `helm show chart oci://ghcr.io/beenuar/aisoc`, where no chart has ever been pushed. The job makes the corrected reference true from the next release; until that release the page says so rather than implying it already resolves |+| A migration is exercised against a populated database before it ships | `apps/docs/docs/operations/release-policy.md` (Upgrading) | `upgrade-test.yml :: upgrade`, on every pull request touching `services/api/migrations/**`, `run_migrations.py` or any service's `alembic/`: the previous minor's **published image** applies its own chain, `scripts/upgrade_fixture.sql` seeds a tenant, a user, one alert per severity tier and a case, and then this tree's chain is applied over the populated schema by that same runner. It asserts every migration on disk is recorded as applied, that the pre-upgrade rows are still readable **by id** rather than only by count, that the DML-only runtime role can still read them, and that a second run applies nothing | GATED | The previous release's runner applies both legs, so a migration needing a *newer* runner than the previous release shipped is not covered; it would fail the second leg rather than pass silently. The fixture is four tables deep, not the whole schema |## Summary@@ -245,7 +249,7 @@ Statuses: `GATED` (a CI job fails when the claim stops being true) · `PARTIAL`## Summary-- GATED: 222+- GATED: 226- PARTIAL: 8- NO GATE: 0 (**every claim is backed by a failing test.** The last NO GATE — the weekly benchmark scoreboard running live against `main` — closed in Phase E1: `scripts/check_scoreboard.py` ties the published scoreboard to a deterministic per-PR live-agent MITRE-accuracy run, while the funded weekly `wet-eval.yml` appends the LLM-tier rows. The remaining PARTIAL rows are honest, named deferrals — each states the specific gap and what closes it — not unproven claims.)diff --git a/docs/operations/publishing.md b/docs/operations/publishing.mdindex d2ea33b5b..43fb89db5 100644--- a/docs/operations/publishing.md+++ b/docs/operations/publishing.md@@ -47,22 +47,56 @@ that one is actively maintained.## One-time setup: npm+npm's trusted publishing is configured **on a package's settings page**, and a+package that has never been published has no settings page. So unlike PyPI,+which supports pending publishers, npm cannot be made token-free before the+first upload. The sequence is therefore: one token, one release, then the+token is deleted and never used again.++**Step 1: the first publish, with a token.**+1. Create (or sign in to) the npm account that will own the packages, andcreate the `@aisoc` organisation so the scoped packages have a home.2. Generate a **granular access token** scoped to just these three packages,- with read/write permission and a sensible expiry.+ with read/write permission and the shortest expiry that covers the release.3. Add it as the `NPM_TOKEN` repository secret.4. Tag a release. The first publish claims `aisoc`.-After the first release, switch to trusted publishing and delete the token:-on npmjs.com, open each package's settings, add a trusted publisher pointing-at `beenuar/AiSOC` and the `release.yml` workflow, then remove the `NPM_TOKEN`-secret. The publish step already requests an OIDC token (`id-token: write`),-so nothing in the workflow needs to change.+**Step 2: move to trusted publishing, and delete the token.**++For each of `aisoc`, `@aisoc/mcp` and `@aisoc/sdk`, on npmjs.com open+**Settings → Trusted publisher → GitHub Actions** and enter:++- Organization or user: `beenuar`+- Repository: `AiSOC`+- Workflow filename: `release.yml` (the **filename only**, with the+ extension, not a path)+- Environment name: leave blank-Every upload is published with `--provenance`, which requires the-`repository` field in each `package.json` to point at this repo. If you add a-fourth npm package, set that field or the publish will fail.+For `aisoc` add a **second** trusted publisher with the workflow filename+`publish-cli.yml`, because the CLI also releases on its own `cli-v*` tag and+npm validates the workflow filename rather than the repository alone. A+package may carry up to ten.++Then set the repository **variable** (not a secret)+`AISOC_NPM_TRUSTED_PUBLISHING` to `true`, delete the `NPM_TOKEN` secret, and+on each package set **Publishing access → Require two-factor authentication+and disallow tokens**.++Three things that will bite, all of which fail with `ENEEDAUTH` and nothing+more specific:++- Trusted publishing needs **npm 11.5.1 or later**. Node 22 ships npm 10, so+ the workflow runs `npm install -g npm@latest` on the OIDC path. That step is+ the reason the path works at all, not a tidiness measure.+- The workflow **filename** is matched exactly and is case-sensitive.+ Renaming `release.yml` or `publish-cli.yml` breaks publishing and nothing+ else, and npm does not validate the configuration when you save it.+- Each `package.json`'s `repository.url` must match this repository exactly.+ All three already do; a fourth package must set it too.++On the OIDC path npm generates provenance automatically, so `--provenance` is+not passed and must not be.## One-time setup: PyPIdiff --git a/scripts/check_release_policy.py b/scripts/check_release_policy.pynew file mode 100644index 000000000..816230aab--- /dev/null+++ b/scripts/check_release_policy.py@@ -0,0 +1,384 @@+#!/usr/bin/env python3+"""A major version requires a BREAKING section, and a BREAKING section requires a major version.++Two directions, deliberately+----------------------------+The failure mode this repository keeps finding is the one-directional gate: it+compares A against B and never B against A, so drift in the direction things+actually change slips through while the gate prints OK. A release-policy check+is unusually prone to it, because the obvious half is only the obvious half.++*A major bump with no BREAKING section* publishes a version number that tells+an operator to read the upgrade notes, and then has none. They upgrade+assuming the major was cosmetic.++*A BREAKING section with no major bump* is worse. Semantic versioning is the+only signal most automated upgrade tooling reads, and a minor is the version+people let a bot merge. The note exists, nobody is looking at it, and the+break arrives through an unattended dependency update.++Both are enforced here, and the self-test proves each arm fires by injecting+that exact violation rather than by asserting the gate has never complained.++The floor, stated rather than hidden+------------------------------------+The policy did not exist before ``10.0.0``, and six earlier majors carry no+BREAKING section. Rewriting them would be revisionism, and exempting them+silently would make the gate look like it had scanned a clean corpus. So the+first arm applies from ``POLICY_FLOOR`` onward and the pre-floor majors are+counted and named in the output every run.++The second arm applies to the whole file. No section below the floor carries a+BREAKING heading, so there is nothing to grandfather and no reason to weaken+it.++Usage::++ python3 scripts/check_release_policy.py # the whole changelog+ python3 scripts/check_release_policy.py --tag v12.0.0 # one tag, at release time+ python3 scripts/check_release_policy.py --previous-minor # print it and exit+ python3 scripts/check_release_policy.py --self-test+"""++from __future__ import annotations++import argparse+import re+import sys+from dataclasses import dataclass+from pathlib import Path++sys.path.insert(0, str(Path(__file__).resolve().parent))++from gate_toolkit import repo_root, self_test_main # noqa: E402++CHANGELOG = Path("CHANGELOG.md")+VERSION_FILE = Path("VERSION")+POLICY = Path("apps/docs/docs/operations/release-policy.md")++#: The release from which "a major bump carries a BREAKING section" is+#: enforced. 10.0.0 is the first major that carried one. Raising this would+#: weaken the gate; lowering it would require rewriting published history.+POLICY_FLOOR = (10, 0, 0)++_SECTION_RE = re.compile(r"^## \[(\d+)\.(\d+)\.(\d+)\]", re.M)+_UNRELEASED_RE = re.compile(r"^## \[Unreleased\]", re.M)+#: `### BREAKING`, and the `### BREAKING CHANGES` spelling, and nothing that+#: merely mentions the word in prose.+_BREAKING_HEADING_RE = re.compile(r"^#{2,4}\s+BREAKING\b", re.M | re.I)+++@dataclass(frozen=True)+class Section:+ major: int+ minor: int+ patch: int+ body: str++ @property+ def version(self) -> str:+ return f"{self.major}.{self.minor}.{self.patch}"++ @property+ def tuple(self) -> tuple[int, int, int]:+ return (self.major, self.minor, self.patch)++ @property+ def declares_breaking(self) -> bool:+ return bool(_BREAKING_HEADING_RE.search(self.body))+++def parse_sections(text: str) -> list[Section]:+ """Released sections, newest first, as the file orders them.++ Non-semver headings such as ``## [7.0.x]`` are not releases and are+ skipped; they carry no version to compare.+ """+ matches = list(_SECTION_RE.finditer(text))+ sections: list[Section] = []+ for i, match in enumerate(matches):+ end = matches[i + 1].start() if i + 1 < len(matches) else len(text)+ sections.append(+ Section(+ major=int(match.group(1)),+ minor=int(match.group(2)),+ patch=int(match.group(3)),+ body=text[match.end() : end],+ )+ )+ return sections+++def unreleased_body(text: str) -> str:+ match = _UNRELEASED_RE.search(text)+ if not match:+ return ""+ following = _SECTION_RE.search(text, match.end())+ return text[match.end() : following.start() if following else len(text)]+++def findings(text: str, *, floor: tuple[int, int, int] = POLICY_FLOOR) -> tuple[list[str], list[str]]:+ """Returns (findings, notes). Notes are things a reader must see even on a pass."""+ sections = parse_sections(text)+ if not sections:+ return (["CHANGELOG.md declares no released version, so there is no release policy to check"], [])++ problems: list[str] = []+ notes: list[str] = []++ # Newest first in the file, so the predecessor of sections[i] is+ # sections[i + 1]. The oldest release has no predecessor and cannot be a+ # bump of anything.+ exempt_majors: list[str] = []+ for i, section in enumerate(sections):+ previous = sections[i + 1] if i + 1 < len(sections) else None+ if previous is None:+ # The oldest section in the file. Whether it was a major bump is+ # unanswerable: there is nothing it bumped from. Judging it either+ # way would be inventing a predecessor.+ continue+ is_major_bump = section.major > previous.major++ if is_major_bump and not section.declares_breaking:+ if section.tuple < floor:+ exempt_majors.append(section.version)+ else:+ problems.append(+ f"{section.version} is a major bump over {previous.version} and its changelog section "+ "has no `### BREAKING` heading. A major tells an operator to read upgrade notes that "+ "do not exist"+ )++ # The second arm, over the whole file: no grandfathering, because+ # nothing below the floor violates it.+ if section.declares_breaking and not is_major_bump:+ problems.append(+ f"{section.version} carries a `### BREAKING` heading but is not a major bump over "+ f"{previous.version}. Semantic versioning is the only signal automated upgrade tooling reads, "+ "and a minor is the version people let a bot merge unattended"+ )++ if exempt_majors:+ notes.append(+ f"{len(exempt_majors)} major release(s) below the {'.'.join(map(str, floor))} policy floor carry no "+ f"BREAKING section and are exempt: {', '.join(sorted(exempt_majors))}. The policy did not exist "+ "when they shipped and published history is not rewritten"+ )++ if _BREAKING_HEADING_RE.search(unreleased_body(text)):+ notes.append(+ "[Unreleased] carries a `### BREAKING` heading, so the next release must be a major. "+ "`--tag` enforces that at the moment the tag is pushed"+ )++ return problems, notes+++def check_tag(text: str, tag: str, *, floor: tuple[int, int, int] = POLICY_FLOOR) -> list[str]:+ """The release-time question: is *this* tag consistent with its own notes?++ Run before anything publishes. A release whose version and notes disagree+ is cheaper to stop than to withdraw: images carry the tag, registries+ refuse a re-upload, and the note is what an operator reads first.+ """+ normalized = tag.lstrip("v")+ parts = normalized.split(".")+ if len(parts) != 3 or not all(p.isdigit() for p in parts):+ return [f"tag {tag!r} is not a three-part semantic version"]+ wanted = tuple(int(p) for p in parts)++ sections = parse_sections(text)+ match = next((s for s in sections if s.tuple == wanted), None)+ if match is None:+ return [f"CHANGELOG.md has no `## [{normalized}]` section, so this tag would publish notes for nothing"]++ index = sections.index(match)+ previous = sections[index + 1] if index + 1 < len(sections) else None+ if previous is None:+ return []++ problems: list[str] = []+ is_major_bump = match.major > previous.major+ if is_major_bump and not match.declares_breaking and match.tuple >= floor:+ problems.append(+ f"{normalized} is a major bump over {previous.version} with no `### BREAKING` section. "+ "Add one saying what an operator must do, or cut a minor instead"+ )+ if match.declares_breaking and not is_major_bump:+ problems.append(+ f"{normalized} carries a `### BREAKING` section but only bumps "+ f"{'minor' if match.minor > previous.minor else 'patch'} over {previous.version}. "+ "Cut a major instead, or move the note if it is not a break"+ )+ return problems+++def previous_minor(text: str, current: str) -> str | None:+ """The release an upgrade test should start from.++ The highest released version strictly below ``current`` that is not a+ patch of it: the previous *line*, which is what an operator upgrading is+ actually coming from.+ """+ parts = current.lstrip("v").split(".")+ if len(parts) != 3 or not all(p.isdigit() for p in parts):+ return None+ cur = tuple(int(p) for p in parts)+ candidates = [s for s in parse_sections(text) if s.tuple < cur and (s.major, s.minor) != (cur[0], cur[1])]+ return max(candidates, key=lambda s: s.tuple).version if candidates else None+++def main(argv: list[str] | None = None) -> int:+ parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)+ parser.add_argument("--check", action="store_true", help="accepted for symmetry; this gate always renders a verdict")+ parser.add_argument("--tag", help="check one tag at release time, e.g. v12.0.0")+ parser.add_argument("--previous-minor", action="store_true", help="print the release an upgrade test should start from")+ args = parser.parse_args(argv)++ root = repo_root()+ changelog = root / CHANGELOG+ if not changelog.is_file():+ print("check_release_policy: no CHANGELOG.md in this tree, so there is no release history to judge", file=sys.stderr)+ return 2+ text = changelog.read_text(encoding="utf-8")++ if args.previous_minor:+ version_file = root / VERSION_FILE+ if not version_file.is_file():+ print("check_release_policy: no VERSION file", file=sys.stderr)+ return 2+ answer = previous_minor(text, version_file.read_text(encoding="utf-8").strip())+ if answer is None:+ print("check_release_policy: no earlier release line to upgrade from", file=sys.stderr)+ return 2+ print(answer)+ return 0++ if args.tag:+ problems = check_tag(text, args.tag)+ for problem in problems:+ print(f" FAIL {problem}")+ if problems:+ return 1+ print(f"OK: {args.tag} and its changelog section agree about whether this release breaks anything.")+ return 0++ problems, notes = findings(text)+ released = len(parse_sections(text))++ # A VERSION that disagrees with the newest section means the tag the+ # release workflow extracts notes for is not the version the tree claims.+ version_file = root / VERSION_FILE+ if version_file.is_file():+ declared = version_file.read_text(encoding="utf-8").strip()+ newest = parse_sections(text)[0].version if released else ""+ if declared and newest and declared != newest:+ notes.append(+ f"VERSION reads {declared} and the newest released section is {newest}. That is the normal state "+ "between a release and the next cut; it is a finding only if a tag is pushed in that state, "+ "which `--tag` catches"+ )++ for note in notes:+ print(f" NOTE {note}")+ if problems:+ print(f"\ncheck_release_policy: {len(problems)} finding(s) across {released} released version(s)\n")+ for problem in problems:+ print(f" FAIL {problem}")+ return 1+ if not (root / POLICY).is_file():+ print(f" FAIL {POLICY} does not exist, so the rule this gate enforces is written nowhere a reader can find it")+ return 1+ print(+ f"\nOK: {released} released version(s). Every major at or above {'.'.join(map(str, POLICY_FLOOR))} "+ "declares what it breaks, and no non-major declares a break."+ )+ return 0+++def _self_test() -> int:+ """Both arms, each proven by injecting the violation it exists to catch."""+ clean = (+ "# Changelog\n\n"+ "## [Unreleased]\n\n### Added\n- a thing\n\n"+ "## [3.0.0] — 2026-01-03\n\n### BREAKING\n- the config file moved\n\n"+ "## [2.1.0] 2026-01-02\n\n### Added\n- a thing\n\n"+ "## [2.0.0] 2026-01-01\n\n### BREAKING\n- the port changed\n\n"+ )+ floor = (2, 0, 0)++ major_without_note = clean.replace(+ "## [3.0.0] — 2026-01-03\n\n### BREAKING\n- the config file moved", "## [3.0.0] — 2026-01-03\n\n### Added\n- the config file moved"+ )+ breaking_on_a_minor = clean.replace(+ "## [2.1.0] 2026-01-02\n\n### Added\n- a thing", "## [2.1.0] 2026-01-02\n\n### BREAKING\n- the port changed"+ )++ checks = [+ ("a changelog obeying both directions passes", not findings(clean, floor=floor)[0]),+ (+ "ARM ONE: a major bump whose section has no BREAKING heading fails",+ any("no `### BREAKING` heading" in f for f in findings(major_without_note, floor=floor)[0]),+ ),+ (+ "ARM TWO: a BREAKING heading on a minor fails",+ any("is not a major bump" in f for f in findings(breaking_on_a_minor, floor=floor)[0]),+ ),+ (+ "the two arms are independent: breaking the first leaves the second silent",+ len(findings(major_without_note, floor=floor)[0]) == 1,+ ),+ (+ "and breaking the second leaves the first silent",+ len(findings(breaking_on_a_minor, floor=floor)[0]) == 1,+ ),+ (+ "a pre-floor major with no BREAKING section is exempt, and the exemption is printed rather than hidden",+ (lambda r: not r[0] and any("policy floor" in n for n in r[1]))(findings(major_without_note, floor=(4, 0, 0))),+ ),+ (+ "at release time, tagging the major-without-a-note is refused",+ bool(check_tag(major_without_note, "v3.0.0", floor=floor)),+ ),+ (+ "at release time, tagging the minor-carrying-a-break is refused",+ bool(check_tag(breaking_on_a_minor, "v2.1.0", floor=floor)),+ ),+ ("at release time, a consistent tag is accepted", not check_tag(clean, "v3.0.0", floor=floor)),+ (+ "a tag with no changelog section is refused rather than passing over an absence",+ bool(check_tag(clean, "v9.9.9", floor=floor)),+ ),+ (+ "prose merely containing the word BREAKING is not a heading",+ not findings(+ clean.replace("- a thing\n\n## [2.0.0]", "- a thing, and nothing here is BREAKING\n\n## [2.0.0]"),+ floor=floor,+ )[0],+ ),+ (+ "the previous release line is the previous minor, not the previous patch",+ previous_minor(clean.replace("## [2.1.0]", "## [3.0.1]\n\n### Fixed\n- x\n\n## [2.1.0]"), "3.0.0") == "2.1.0",+ ),+ (+ "[Unreleased] carrying a break is reported as an obligation on the next release",+ any(+ "next release must be a major" in n+ for n in findings(clean.replace("## [Unreleased]\n\n### Added", "## [Unreleased]\n\n### BREAKING"), floor=floor)[1]+ ),+ ),+ ]++ ok = True+ for description, passed in checks:+ ok &= passed+ print(f" {'PASS' if passed else 'FAIL'} {description}")+ print()+ print("check_release_policy.py: self-test " + ("OK" if ok else "FAILED"))+ return 0 if ok else 1+++if __name__ == "__main__":+ if "--self-test" in sys.argv[1:]:+ sys.exit(_self_test() or self_test_main("check_release_policy.py", ["--check"]))+ sys.exit(main())diff --git a/scripts/upgrade_fixture.sql b/scripts/upgrade_fixture.sqlnew file mode 100644index 000000000..c044e66aa--- /dev/null+++ b/scripts/upgrade_fixture.sql@@ -0,0 +1,65 @@+-- Data the upgrade test carries across a migration chain.+--+-- A fresh install applies every migration to an empty schema, which is the one+-- case that cannot go wrong. The defects that reach operators need rows to be+-- there: an `ADD COLUMN ... NOT NULL` with no default, a unique index created+-- over rows that already violate it, a backfill reading a column it is about+-- to create, a type change that succeeds on zero rows.+--+-- Ids are fixed literals rather than generated, because the assertion after+-- the upgrade reads specific rows back by id. A count alone would pass over a+-- table that was dropped and repopulated with the same number of fabricated+-- rows, which is precisely the migration a real deployment cannot survive.+--+-- Written against the owner role (`aisoc`), which is also what applies the+-- migration chain. Every row carries `is_synthetic = true` where the column+-- exists, so a fixture can never be mistaken for a tenant's real state.++BEGIN;++INSERT INTO tenants (id, name, slug)+VALUES ('00000000-0000-0000-0000-0000000000aa', 'Upgrade Fixture Tenant', 'upgrade-fixture')+ON CONFLICT (id) DO NOTHING;++INSERT INTO users (id, tenant_id, email, username, hashed_password)+VALUES (+ '33333333-3333-3333-3333-333333333333',+ '00000000-0000-0000-0000-0000000000aa',+ '[email protected]', -- RFC 2606, unregistrable+ 'upgrade-fixture',+ -- Not a usable credential: a deliberately invalid bcrypt-shaped string,+ -- so nothing can sign in as this row even if a fixture escaped into a+ -- real database.+ '$2b$12$invalid.fixture.hash.not.a.real.credential.000000000000'+)+ON CONFLICT (id) DO NOTHING;++-- One alert per severity, so a migration that rewrites the severity ladder or+-- adds a constraint to it meets every value rather than one.+INSERT INTO alerts (id, tenant_id, title, description, severity, status, is_synthetic)+VALUES+ ('11111111-1111-1111-1111-111111111111', '00000000-0000-0000-0000-0000000000aa',+ 'pre-upgrade alert (critical)', 'Seeded before the migration chain ran.', 'critical', 'new', true),+ ('11111111-1111-1111-1111-111111111112', '00000000-0000-0000-0000-0000000000aa',+ 'pre-upgrade alert (high)', 'Seeded before the migration chain ran.', 'high', 'investigating', true),+ ('11111111-1111-1111-1111-111111111113', '00000000-0000-0000-0000-0000000000aa',+ 'pre-upgrade alert (medium)', 'Seeded before the migration chain ran.', 'medium', 'new', true),+ ('11111111-1111-1111-1111-111111111114', '00000000-0000-0000-0000-0000000000aa',+ 'pre-upgrade alert (low)', 'Seeded before the migration chain ran.', 'low', 'closed', true),+ ('11111111-1111-1111-1111-111111111115', '00000000-0000-0000-0000-0000000000aa',+ 'pre-upgrade alert (info)', 'Seeded before the migration chain ran.', 'info', 'closed', true)+ON CONFLICT (id) DO NOTHING;++INSERT INTO cases (id, tenant_id, case_number, title, description)+VALUES (+ '22222222-2222-2222-2222-222222222222',+ '00000000-0000-0000-0000-0000000000aa',+ 'CASE-UPGRADE-0001',+ 'pre-upgrade case',+ 'Seeded before the migration chain ran, so a case-table migration meets a populated table.'+)+ON CONFLICT (id) DO NOTHING;++COMMIT;++\echo 'upgrade fixture: seeded 1 tenant, 1 user, 5 alerts, 1 case'diff --git a/tests/test_first_run_gate.py b/tests/test_first_run_gate.pyindex d6463eb24..3ed8f6b58 100644--- a/tests/test_first_run_gate.py+++ b/tests/test_first_run_gate.py@@ -313,12 +313,45 @@ def test_publish_images_keeps_demo_off_the_moving_tags() -> None:def test_release_publishes_the_demo_under_its_own_tag() -> None:- text = RELEASE_WORKFLOW.read_text()- assert "-demo" in text, "release.yml has no demo-suffixed tag for the demo build"- assert 'matrix.demo }}" = "true"' in text, (- "release.yml does not branch its tag list on `matrix.demo`, so `vX.Y.Z` and `latest` could carry the demo bundle again"+ """The demo bundle must never ride on `vX.Y.Z` or `latest`.++ Asserted as a property of the step rather than as a literal string. The+ earlier version required the spelling ``matrix.demo }}" = "true"``, which+ made a safety *improvement* look like a regression: binding the matrix+ value through ``env:`` keeps a workflow expression out of the shell, and+ the protection is identical. What matters is that the moving tags are+ emitted only on the branch where this is not the demo build.+ """+ workflow = yaml.safe_load(RELEASE_WORKFLOW.read_text())+ steps = [s for job in workflow["jobs"].values() for s in job.get("steps", []) if isinstance(s, dict)]+ step = next((s for s in steps if s.get("id") == "image-tags"), None)+ assert step is not None, "release.yml has no `image-tags` step, so there is no tag list to check"++ script = step["run"]+ # The demo flag reaches the script either inline or through an env binding;+ # resolve the indirection rather than requiring one of the two spellings.+ names = [name for name, value in (step.get("env") or {}).items() if "matrix.demo" in str(value)]+ branches_on_demo = any(name in script for name in names) or "matrix.demo" in script+ assert branches_on_demo, (+ "release.yml does not branch its tag list on the demo flag, so `vX.Y.Z` and `latest` could carry the demo bundle again")+ assert "-demo" in script, "release.yml has no demo-suffixed tag for the demo build"++ # Split on the shell keyword, which is a line of its own — not on the+ # substring. The script's second line reads "Anything else in the line is+ # a minor", so a substring partition cut at that comment and left a demo+ # arm of two lines that could never contain `latest`. The check passed+ # while a demo build tagged `latest` sat below it.+ lines = script.splitlines()+ keyword = [i for i, line in enumerate(lines) if line.strip() == "else"]+ assert len(keyword) == 1, f"expected exactly one `else` keyword in the tag script, found {len(keyword)}"+ demo_arm = "\n".join(lines[: keyword[0]])+ other_arm = "\n".join(lines[keyword[0] :])++ assert "latest" not in demo_arm, f"release.yml can tag the demo build `latest`:\n{demo_arm}"+ assert "latest" in other_arm, "release.yml never tags a non-demo build `latest`, so this check proves nothing"+def test_each_compose_file_pulls_the_image_built_for_it() -> None:root = ROOT_COMPOSE.read_text()diff --git a/tests/test_release_channel_tags.py b/tests/test_release_channel_tags.pynew file mode 100644index 000000000..39689e505--- /dev/null+++ b/tests/test_release_channel_tags.py@@ -0,0 +1,120 @@+"""The `stable` channel is a rule, so it is executed rather than read.++`latest` moves on every release, majors included. A deployment that pulls by+tag is therefore dragged across a breaking change by a tag whose name promises+the opposite, with no operator decision in between. `stable` exists to be the+tag that does not do that: it advances on a minor or a patch and stops at a+major until someone promotes it deliberately.++That rule lives in a shell block inside `.github/workflows/release.yml`, which+runs only on a tag push. A rule that executes a handful of times a year, in an+environment nobody can step through, is a rule that rots. So this test lifts+that exact block out of the workflow and runs it under bash with each+combination of inputs. It does not re-implement the logic: a copy would agree+with itself while the workflow drifted.+"""++from __future__ import annotations++import os+import subprocess+import tempfile+from pathlib import Path++import pytest+import yaml++ROOT = Path(__file__).resolve().parents[1]+WORKFLOW = ROOT / ".github" / "workflows" / "release.yml"+IMAGE = "ghcr.io/beenuar/aisoc-core-api"+++def _tag_script() -> str:+ workflow = yaml.safe_load(WORKFLOW.read_text(encoding="utf-8"))+ steps = workflow["jobs"]["docker-manifest"]["steps"]+ step = next((s for s in steps if s.get("id") == "image-tags"), None)+ assert step is not None, "release.yml no longer has an `image-tags` step to check"+ return step["run"]+++def run_tags(*, version: str, republish: bool = False, promote_stable: bool = False, demo: bool = False) -> list[str]:+ """Execute the workflow's own tag block and return the tags it emitted."""+ script = _tag_script()+ with tempfile.TemporaryDirectory() as tmp:+ output = Path(tmp) / "gh-output"+ output.touch()+ env = {+ **os.environ,+ "VERSION": version,+ "REPUBLISH": "true" if republish else "false",+ "PROMOTE_STABLE": "true" if promote_stable else "false",+ "IMAGE": IMAGE,+ "IS_DEMO": "true" if demo else "false",+ "GITHUB_OUTPUT": str(output),+ }+ done = subprocess.run(["bash", "-c", script], env=env, capture_output=True, text=True)+ assert done.returncode == 0, f"the workflow's tag block failed: {done.stderr}"+ body = output.read_text(encoding="utf-8")+ lines = body.splitlines()+ assert lines and lines[0] == "tags<<EOF", f"unexpected step output: {body!r}"+ return [line for line in lines[1:] if line and line != "EOF"]+++def test_a_minor_release_moves_both_latest_and_stable() -> None:+ assert run_tags(version="v11.3.0") == [+ f"{IMAGE}:v11.3.0",+ f"{IMAGE}:latest",+ f"{IMAGE}:stable",+ ]+++def test_a_patch_release_moves_both() -> None:+ assert f"{IMAGE}:stable" in run_tags(version="v11.2.1")+++def test_a_major_release_moves_latest_but_not_stable() -> None:+ tags = run_tags(version="v12.0.0")+ assert f"{IMAGE}:latest" in tags+ assert f"{IMAGE}:stable" not in tags, (+ "a major moved `stable` on its own, so a tag-pulling deployment would cross a breaking change with no operator decision"+ )+++def test_a_major_reaches_stable_only_when_promoted_deliberately() -> None:+ assert f"{IMAGE}:stable" in run_tags(version="v12.0.0", republish=True, promote_stable=True)+++def test_repairing_an_old_tag_moves_neither_channel() -> None:+ tags = run_tags(version="v11.0.0", republish=True)+ assert tags == [f"{IMAGE}:v11.0.0"], (+ "a republish moved a channel tag, which is how a repair hands self-hosters older content than main on the tag they pull by default"+ )+++def test_the_demo_bundle_never_carries_a_channel_tag() -> None:+ tags = run_tags(version="v11.3.0", demo=True)+ assert tags == [f"{IMAGE}:v11.3.0-demo", f"{IMAGE}:demo"]+ assert not any(t.endswith(":latest") or t.endswith(":stable") for t in tags), (+ "the demo console shipped on a channel tag; a self-hoster would get a console announcing daily demo resets over their real alerts"+ )++[email protected]("version", ["v1.0.0", "v10.0.0", "v100.0.0"])+def test_every_x_0_0_is_recognised_as_a_major(version: str) -> None:+ assert f"{IMAGE}:stable" not in run_tags(version=version)++[email protected]("version", ["v1.0.1", "v10.1.0", "v11.2.10"])+def test_nothing_else_is(version: str) -> None:+ assert f"{IMAGE}:stable" in run_tags(version=version)+++def test_the_promote_stable_input_is_declared_so_the_dispatch_arm_is_reachable() -> None:+ workflow = yaml.safe_load(WORKFLOW.read_text(encoding="utf-8"))+ # PyYAML parses a bare `on:` key as the boolean True.+ triggers = workflow.get("on", workflow.get(True))+ inputs = triggers["workflow_dispatch"]["inputs"]+ assert "promote_stable" in inputs, (+ "the block reads PROMOTE_STABLE but the workflow declares no such input, so the only path "+ "by which `stable` can reach a major is unreachable"+ )