feat(alpha): packaging — the proven story up front, a non-blocking Action, and an honest attach contract (A4)

.github/workflows/ci.yml

@@ -1984,6 +1984,22 @@ jobs:
             echo "FAIL: a tree with leaks should exit non-zero under --fail-on-finding"; exit 1
           fi
           echo "OK: --fail-on-finding surfaced the leaks as a non-zero exit"
+      - name: A broken stage 1 is a hard error, never the "findings" tier
+        run: |
+          # Exit 1 means "analysed, and there are findings". If a failed
+          # extractor build could also exit 1, then a caller that chooses NOT to
+          # gate on findings — which is now the Action's default — reads a run
+          # that analysed nothing as clean. So stage-1 failures are normalised
+          # into the >=2 tier, and this pins it: --root at a path with no
+          # extractor project makes `dotnet run` fail with 1.
+          set +e
+          scripts/own-check.sh --root "$RUNNER_TEMP/no-such-root" --format github \
+            -- "$RUNNER_TEMP/owen-action-clean" >/dev/null 2>"$RUNNER_TEMP/stage1.err"
+          rc=$?
+          set -e
+          tail -3 "$RUNNER_TEMP/stage1.err" || true
+          [ "$rc" -ge 2 ] || { echo "FAIL: a broken stage 1 must exit >=2 (the tool did not look), got $rc"; exit 1; }
+          echo "OK: stage-1 failure landed in the hard-error tier (exit $rc)"
       - name: SARIF surface is a valid 2.1.0 log (the structure code scanning enforces)
         run: |
           # The contract GitHub's code-scanning ingest enforces, checked locally so
@@ -2011,13 +2027,89 @@ jobs:
           ' "$out" >/dev/null \
             || { echo "FAIL: a result is unlocated or references an undeclared rule"; exit 1; }
           echo "OK: SARIF 2.1.0 — Owen driver, every result rule-backed + located"
+      - name: Fixtures for the action's status contract (clean tree, broken config)
+        run: |
+          # Tier 0: a tree with nothing to report.
+          mkdir -p "$RUNNER_TEMP/owen-action-clean"
+          printf 'public class Clean { public int M() { return 1; } }\n' \
+            > "$RUNNER_TEMP/owen-action-clean/Clean.cs"
+          # Asserted here rather than on the action step: a `uses:` step's
+          # stdout is not capturable, so "annotates nothing" is checked through
+          # the same script the action runs.
+          out=$(scripts/own-check.sh --format github -- "$RUNNER_TEMP/owen-action-clean")
+          [ -z "$(echo "$out" | grep '^::' || true)" ] \
+            || { echo "FAIL: a clean tree must emit no annotations, got:"; echo "$out"; exit 1; }
+          echo "OK: clean tree, zero annotations"
+          # Tier >=2: a config own-check refuses to parse, so it exits 2 before
+          # analysing anything.
+          printf 'this is not = valid toml [[[\n' > "$RUNNER_TEMP/owen-broken.toml"
       - name: The composite action runs end-to-end (non-failing)
         uses: ./
         with:
           path: frontend/roslyn/samples
           format: github
           fail-on-finding: "false"
 
+      # The four tiers of the action's status contract, each pinned. The point
+      # of "annotations, not failures" is that it applies to FINDINGS ONLY;
+      # every other tier must keep behaving exactly as before, or the friendly
+      # default silently turns "the tool could not run" into a green check.
+      #
+      # Deliberately here and not only in action-marketplace-readiness.yml,
+      # which covers the same ground for the consumer fixture: that workflow is
+      # PATH-FILTERED (action.yml, own-check.sh, …), so a change to the Python
+      # core's exit codes — where these tiers actually originate — would never
+      # wake it. This job runs on every push and PR.
+      - name: "Tier 1 — findings, DEFAULT inputs: annotations published, step succeeds"
+        id: default_findings
+        uses: ./
+        with:
+          path: frontend/roslyn/samples
+          format: github
+          # fail-on-finding deliberately NOT set: this is the out-of-the-box
+          # experience of someone who just added Owen to their repository.
+      - name: "Tier 1 — the default really was non-blocking"
+        run: |
+          [ "${{ steps.default_findings.outcome }}" = "success" ] \
+            || { echo "FAIL: a leaky tree must not fail the step by default"; exit 1; }
+          echo "OK: findings did not fail the step under default inputs"
+      - name: "Tier 1 opt-in — fail-on-finding: true turns the same findings into a failure"
+        id: strict_findings
+        continue-on-error: true
+        uses: ./
+        with:
+          path: frontend/roslyn/samples
+          format: github
+          fail-on-finding: "true"
+      - name: "Tier 1 opt-in — the strict mode really did fail"
+        run: |
+          [ "${{ steps.strict_findings.outcome }}" = "failure" ] \
+            || { echo "FAIL: fail-on-finding: true must fail on a leaky tree (outcome=${{ steps.strict_findings.outcome }})"; exit 1; }
+          echo "OK: the same tree, the same annotations, a failing status"
+      - name: "Tier 0 — a clean tree succeeds and annotates nothing"
+        id: clean_tree
+        uses: ./
+        with:
+          path: ${{ runner.temp }}/owen-action-clean
+          format: github
+      - name: "Tier >=2 — an operational failure fails the step even with fail-on-finding: false"
+        id: operational_failure
+        continue-on-error: true
+        uses: ./
+        with:
+          path: frontend/roslyn/samples
+          format: github
+          fail-on-finding: "false"
+          # A malformed own.toml makes own-check exit 2 before it can analyse
+          # anything. That is the tool failing to LOOK, not a defect found in
+          # the caller's code — the friendly default must not absorb it.
+          config: ${{ runner.temp }}/owen-broken.toml
+      - name: "Tier >=2 — the operational failure really did fail"
+        run: |
+          [ "${{ steps.operational_failure.outcome }}" = "failure" ] \
+            || { echo "FAIL: an operational failure (exit >=2) must fail the step regardless of fail-on-finding (outcome=${{ steps.operational_failure.outcome }})"; exit 1; }
+          echo "OK: 'could not look' did not become 'looked and found nothing'"
+
   # Dog-food the code-scanning surface end-to-end (P-013): run the composite action
   # with format: sarif over the sample tree, then upload the log to GitHub code
   # scanning. The repo is public, so code scanning is free — this is the live proof
@@ -2569,6 +2661,45 @@ jobs:
           print(f"ok: nothing durably retains the window — verdict "
                 f"{doc.get('verdict')}, roots seen: {dict(kinds) or 'none'}")
           PY
+      - name: "attach denied by kernel policy is an honest exit 2, never a clean verdict (A4)"
+        if: runner.os == 'Linux'
+        run: |
+          # The operational contract, asserted rather than described: with Yama
+          # at its default scope, attaching to a NON-DESCENDANT process is
+          # refused by the kernel. The witness must say so, name the policy, and
+          # exit 2 — the tier that means "I did not look", distinct from 0
+          # (looked, nothing retained) and 1 (looked, retention found). This is
+          # the failure the first CI round of this arc actually hit.
+          #
+          # Runs BEFORE the demo step relaxes the scope; the app is a sibling of
+          # the witness (both children of this shell), which is exactly the
+          # shape Yama scope 1 forbids.
+          sudo sysctl -w kernel.yama.ptrace_scope=1
+          dotnet build "$GITHUB_WORKSPACE/examples/flagship/console/bad" -c Release -v quiet
+          APP="$GITHUB_WORKSPACE/examples/flagship/console/bad/bin/Release/net8.0/BadDocumentApp.dll"
+          WITNESS="$GITHUB_WORKSPACE/audit/runtime/RetentionPath/bin/Release/net8.0/RetentionPath.dll"
+          STOP="$RUNNER_TEMP/denied-stop"; LOG="$RUNNER_TEMP/denied-app.log"
+          rm -f "$STOP"
+          OWEN_FLAGSHIP_HOLD=1 OWEN_FLAGSHIP_STOP="$STOP" OWEN_FLAGSHIP_HOLD_SECONDS=120 \
+            dotnet "$APP" > "$LOG" 2>&1 &
+          for _ in $(seq 1 60); do grep -q "holding (pid" "$LOG" 2>/dev/null && break; sleep 1; done
+          grep -q "holding (pid" "$LOG" || { cat "$LOG"; echo "FAIL: sample never held"; exit 1; }
+          PID=$(sed -n 's/.*holding (pid \([0-9]*\)).*/\1/p' "$LOG" | head -1)
+          set +e
+          out=$(dotnet "$WITNESS" roots --pid "$PID" --type Owen.Flagship.DocumentView \
+            --out "$RUNNER_TEMP/denied.json" 2>&1)
+          rc=$?
+          set -e
+          touch "$STOP"
+          echo "$out"
+          [ "$rc" -eq 2 ] || { echo "FAIL: a denied attach must exit 2, got $rc"; exit 1; }
+          echo "$out" | grep -q "ptrace_scope" \
+            || { echo "FAIL: the diagnostic must name the policy that refused"; exit 1; }
+          echo "$out" | grep -q "NOT a verdict" \
+            || { echo "FAIL: the diagnostic must say it did not look"; exit 1; }
+          [ ! -s "$RUNNER_TEMP/denied.json" ] \
+            || { echo "FAIL: a refused attach must not write a verdict artifact"; exit 1; }
+          echo "OK: denied attach -> exit 2, policy named, no artifact written"
       - name: "flagship demo orchestrator end-to-end: bad DEMONSTRATED, ok VERIFIED (A3/A4)"
         if: runner.os == 'Linux'
         run: |

README.md

@@ -2,23 +2,82 @@
 
 # Own.NET
 
-> Own.NET finds lifetime/resource bugs that C# cannot express: WPF/event
-> leaks, missing `Dispose`, DI lifetime mismatch, and pooled-buffer misuse.
+> **Owen finds .NET lifetime bugs and confirms them at runtime — showing the
+> reference path that keeps the object alive.**
 
 *Find leaks before the profiler.* GC collects unreachable objects; Own finds
 objects that should have become unreachable. `event +=` is acquire, `-=` is
-release.
+release. It also finds missing `Dispose`, DI lifetime mismatch, and
+pooled-buffer misuse — the same ownership question in different skins.
+
+## Both halves, on one sample
+
+**The defect, at the line that causes it.** A window subscribes to a
+process-lifetime settings hub; the unsubscribe exists, but the close path
+never reaches it:
+
+```console
+$ owen check examples/flagship/wpf/bad --fail-on-finding
+DocumentWindow.xaml.cs:28: warning: [OWN001] event '_settings.PropertyChanged'
+  is subscribed (handler 'OnSettingsChanged') but never unsubscribed; its
+  source is an injected dependency whose lifetime is unknown, so it may
+  outlive and keep 'DocumentWindow' alive (possible leak)
+```
+
+**The same object at runtime, and what is actually holding it.** A separate
+step — you run it when you want proof, not on every build:
+
+```text
+verdict: RETAINED — DocumentWindow: 200 on the heap, 200 durably retained
+
+AppSettings
+  → PropertyChanged
+  → _invocationList
+  → handler
+  → DocumentWindow
+
+100% of them hang off ONE reference.
+```
+
+Both halves are held to a contract on every CI run, on Linux and Windows:
+
+```text
+bad → RETAINED / exit 1
+ok  → ABSENT or OBSERVED_ONLY / exit 0 / zero durable roots
+```
+
+The sample is real and runnable: [`examples/flagship/`](examples/flagship/)
+(console and WPF, each a `bad`/`ok` pair whose only difference is where the
+`-=` lives). What the runtime witness will and will not claim — and why
+"reachable" is not "leaked" — is
+[`docs/how-owen-proves-retention.md`](docs/how-owen-proves-retention.md).
 
 ## Run it in CI — 6 lines
 
 ```yaml
 - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
 - uses: PhysShell/Own.NET@main  # pre-release: no tagged release yet — pin a commit SHA for reproducibility
   with:
+    path: .
     format: github          # inline PR annotations; use "sarif" for the Security tab
-    fail-on-finding: "true"
 ```
 
+Findings arrive as PR annotations and **the step stays green** — adding Owen
+to a repository does not turn its CI red on day one. When you are ready to
+gate on it:
+
+```yaml
+  with:
+    path: .
+    fail-on-finding: true
+```
+
+Both modes analyse identically and publish identical annotations/SARIF; only
+the step's final status differs. And `fail-on-finding` governs *findings*
+only — if Owen cannot complete the analysis (crash, unreadable input, no SARIF
+written) the step fails in either mode. A friendly default must never turn
+"could not look" into "looked and found nothing".
+
 Once a release ships, prefer a pinned tag (`@v0.1.0`) or the moving major tag
 (`@v0`) over `@main` — see
 [`docs/notes/action-marketplace-readiness.md`](docs/notes/action-marketplace-readiness.md)

README.ru.md

@@ -2,24 +2,84 @@
 
 # Own.NET
 
-> Own.NET находит баги времени жизни/ресурсов, которые C# не может выразить:
-> WPF/event-лики, забытый `Dispose`, рассинхрон DI lifetime и неправильное
-> использование pooled-буферов.
+> **Owen находит ошибки времени жизни в .NET и подтверждает их во время
+> выполнения — показывая ссылочный путь, который держит объект живым.**
 
 *Находи лики до профайлера.* GC собирает недостижимые объекты; Own находит
 объекты, которые должны были стать недостижимыми. `event +=` — это acquire,
-`-=` — это release.
+`-=` — это release. Он также находит забытый `Dispose`, рассинхрон DI
+lifetime и неправильное использование pooled-буферов — тот же вопрос о
+владении в разных обличьях.
+
+## Обе половины, на одном образце
+
+**Дефект — на строке, которая его порождает.** Окно подписывается на хаб
+настроек, живущий всё время процесса; отписка существует, но путь закрытия до
+неё не доходит:
+
+```console
+$ owen check examples/flagship/wpf/bad --fail-on-finding
+DocumentWindow.xaml.cs:28: warning: [OWN001] event '_settings.PropertyChanged'
+  is subscribed (handler 'OnSettingsChanged') but never unsubscribed; its
+  source is an injected dependency whose lifetime is unknown, so it may
+  outlive and keep 'DocumentWindow' alive (possible leak)
+```
+
+**Тот же объект во время выполнения — и то, что его действительно держит.**
+Отдельный шаг: он запускается, когда нужно доказательство, а не на каждой
+сборке:
+
+```text
+verdict: RETAINED — DocumentWindow: 200 on the heap, 200 durably retained
+
+AppSettings
+  → PropertyChanged
+  → _invocationList
+  → handler
+  → DocumentWindow
+
+100% из них висят на ОДНОЙ ссылке.
+```
+
+Обе половины держатся контракта на каждом прогоне CI, под Linux и Windows:
+
+```text
+bad → RETAINED / exit 1
+ok  → ABSENT or OBSERVED_ONLY / exit 0 / zero durable roots
+```
+
+Образец настоящий и запускаемый: [`examples/flagship/`](examples/flagship/)
+(консоль и WPF, каждый — пара `bad`/`ok`, отличающаяся только тем, где живёт
+`-=`). Что свидетель времени выполнения утверждает, а что — нет, и почему
+«достижим» не значит «утёк»:
+[`docs/how-owen-proves-retention.md`](docs/how-owen-proves-retention.md).
 
 ## Запустить в CI — 6 строк
 
 ```yaml
 - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
 - uses: PhysShell/Own.NET@main  # пре-релиз: тегов ещё нет — для воспроизводимости пиньте commit SHA
   with:
+    path: .
     format: github          # инлайн-аннотации в PR; "sarif" — для вкладки Security
-    fail-on-finding: "true"
 ```
 
+Находки приходят аннотациями в PR, а шаг **остаётся зелёным** — добавление
+Owen в репозиторий не красит чужой CI в первый же день. Когда готовы на нём
+гейтить:
+
+```yaml
+  with:
+    path: .
+    fail-on-finding: true
+```
+
+Оба режима анализируют одинаково и публикуют одинаковые аннотации/SARIF;
+отличается только итоговый статус шага. И `fail-on-finding` управляет только
+*находками*: если Owen не смог довести анализ до конца (краш, нечитаемый вход,
+SARIF не записан), шаг падает в любом режиме. Дружелюбный дефолт не имеет
+права превращать «не смог посмотреть» в «посмотрел и ничего не нашёл».
+
 После первого релиза предпочитайте закреплённый тег (`@v0.1.0`) или
 подвижный major-тег (`@v0`) вместо `@main` — политика версионирования в
 [`docs/notes/action-marketplace-readiness.md`](docs/notes/action-marketplace-readiness.md).

action.yml

@@ -33,9 +33,15 @@ inputs:
     required: false
     default: "error"
   fail-on-finding:
-    description: "Fail the step when any leak is found."
+    description: >-
+      Whether a FINDING fails the step. Default false: findings are published
+      as annotations/SARIF and the step succeeds, so adding Owen to a repository
+      cannot turn its CI red on day one. Set true once you are ready to gate on
+      it. This input governs findings ONLY — an operational failure (the
+      analyser crashed, the input could not be read, no SARIF could be written)
+      always fails the step, in either mode.
     required: false
-    default: "true"
+    default: "false"
   python-version:
     description: "Python version for the Owen core."
     required: false
@@ -130,8 +136,25 @@ runs:
           fi
           exit 0
         fi
-        args=(--root "${{ github.action_path }}" --format "$OWN_FORMAT" --severity "$OWN_SEVERITY" "${config_args[@]}")
-        if [ "$OWN_FAIL_ON_FINDING" = "true" ]; then
-          args+=(--fail-on-finding)
+        # Always ask own-check for its TRUE tier (0 clean / 1 findings / >=2
+        # operational failure) and decide the step's status here. Run WITHOUT
+        # --fail-on-finding and the script folds findings into 0, making tier 1
+        # indistinguishable from tier 0 — and tier 1 is the only one this
+        # action is allowed to negotiate about.
+        set +e
+        "$check" --root "${{ github.action_path }}" --format "$OWN_FORMAT" \
+          --severity "$OWN_SEVERITY" "${config_args[@]}" --fail-on-finding -- "$OWN_PATH"
+        rc=$?
+        set -e
+        if [ "$rc" -ge 2 ]; then
+          # NOT a finding: the analyser crashed, the input could not be read, or
+          # the contract drifted. "Annotations instead of failure" is a policy
+          # about defects found in your code, never about the tool failing to
+          # look — that must not reach anyone as a green check.
+          echo "::error::Owen could not complete the analysis (exit $rc). This is an operational failure, not a finding — fail-on-finding does not apply to it. The diagnostic is above."
+          exit "$rc"
+        fi
+        if [ "$rc" -eq 1 ] && [ "$OWN_FAIL_ON_FINDING" = "true" ]; then
+          exit 1
         fi
-        "$check" "${args[@]}" -- "$OWN_PATH"
+        exit 0