getculpa 1.0.4 → 1.0.6

package/LICENSE

@@ -17,7 +17,9 @@ the Culpa End User Licence Agreement ("EULA") between you and Myaigi AI Labs
   Product:       Culpa
   Governing law: Republic of South Africa
 
-To obtain the current EULA, contact the licensor at the address below.
+The full End User Licence Agreement ships WITH the product: it is shown at
+first launch and is readable any time at /docs/terms-of-use in the app, and
+as client_docs/terms-of-use.md in the source. You do not need to ask for it.
 
 Except as the EULA expressly permits, you may not copy, modify, merge,
 publish, distribute, sublicense, sell, rent, lease, reverse engineer, or

package/assets/culpa-compose.yml

@@ -5,7 +5,7 @@
 # name is used when present, which is how these pins were verified before
 # publication.
 #
-# ── RELEASE STATE: v1.0.4 PUBLISHED AND SIGNED (2026-08-20) ─────────
+# ── RELEASE STATE: v1.0.6 PUBLISHED AND SIGNED (2026-08-26) ─────────
 # The line above is REWRITTEN BY installers/publish.sh at real-publish time —
 # this file has shipped a hand-edited, wrong publication claim twice, so the
 # claim is now mechanical, never prose. While it reads NOT PUBLISHED, the pins
@@ -26,7 +26,7 @@
 #   cosign verify \
 #     --certificate-identity 'info@myaigi.ai' \
 #     --certificate-oidc-issuer 'https://github.com/login/oauth' \
-#     ghcr.io/myaigidev/culpa-server:v1.0.3
+#     ghcr.io/myaigidev/culpa-server:v1.0.6
 # Repeat for culpa-dashboard. Both must report VERIFIED.
 #
 # If a pull fails with an authentication or "denied" error rather than a
@@ -55,7 +55,7 @@ services:
     restart: unless-stopped
 
   server:
-    image: ghcr.io/myaigidev/culpa-server:v1.0.3
+    image: ghcr.io/myaigidev/culpa-server:v1.0.6
     container_name: culpa-server
     environment:
       DATABASE_URL: postgres://culpa:culpa@db:5432/culpa
@@ -123,11 +123,13 @@ services:
     restart: unless-stopped
 
   dashboard:
-    # CF14 (2026-08-12): dashboard-only bump. v0.11.1 is v0.11.0 plus the dark
-    # black-surface palette — no server, migration or API change, so the server
-    # above deliberately stays at v0.11.0 rather than being re-tagged for a
-    # release it has no diff in (D-072: never rebuild a tag that already exists).
-    image: ghcr.io/myaigidev/culpa-dashboard:v1.0.4
+    # Per-component release (D-087). v1.0.5 is a dashboard + relay release: no
+    # server, migration or API change, so culpa-server above deliberately stays
+    # at v1.0.3 rather than being re-tagged for a release it has no diff in
+    # (D-072: never rebuild a tag that already exists). The example this note
+    # used to give was CF14's v0.11.0/v0.11.1 pair, which no longer matches
+    # either pin in this file.
+    image: ghcr.io/myaigidev/culpa-dashboard:v1.0.6
     container_name: culpa-dashboard
     environment:
       CULPA_API_BASE: http://server:4545

package/assets/launch-culpa.ps1

@@ -42,8 +42,28 @@ function Test-DockerUp {
 
 # The server tag pinned in a compose text; $null when absent (QW-1/2/3 all
 # read the pin through this ONE function so they can never disagree).
+# Full-line YAML comments, removed before ANY pin is parsed. Review finding
+# (2026-08-23): the unanchored parser below matched the cosign-verify EXAMPLE
+# at installers/culpa-compose.yml:29 - a COMMENT - which precedes the real
+# image: pin at line 58 and so won the first-match race. Both read v1.0.3
+# today, but publish.sh rewrites the example and the pin with SEPARATE seds,
+# so a server release whose example sed missed would leave QW-3 comparing a
+# stale version and REFUSING to launch a perfectly good pin.
+function Remove-ComposeComments([string]$ComposeText) {
+    if ([string]::IsNullOrEmpty($ComposeText)) { return "" }
+    return ((($ComposeText -split "`r?`n") | Where-Object { $_ -notmatch '^\s*#' }) -join "`n")
+}
+
+# Anchored on image: as well as comment-stripped - a pin is something docker
+# would actually pull, never prose that happens to name the image.
 function Get-PinnedServerVersion([string]$ComposeText) {
-    if ($ComposeText -match 'culpa-server:([^"\s]+)') { return $Matches[1] }
+    # Comment-stripping is what cures the defect; the image: anchor is preferred
+    # but NOT required, because callers legitimately pass a bare
+    # "culpa-server:vX.Y.Z" fragment. Anchored first, then an unanchored fallback
+    # over the SAME comment-stripped text.
+    $text = Remove-ComposeComments $ComposeText
+    if ($text -match '(?m)^[ 	]*image:\s*\S*?culpa-server:([^"''\s]+)') { return $Matches[1] }
+    if ($text -match 'culpa-server:([^"''\s]+)') { return $Matches[1] }
     return $null
 }
 
@@ -64,6 +84,54 @@ function Compare-CulpaVersions([string]$A, [string]$B) {
     return 0
 }
 
+# ISS-V103-12 - every pinned CULPA image in a compose text, as a hashtable
+# @{ "culpa-server" = "v1.0.3"; "culpa-dashboard" = "v1.0.5" }. Scoped to
+# culpa-* deliberately: the compose also pins postgres, and a postgres bump
+# must never read as a Culpa release.
+function Get-PinnedImageVersions([string]$ComposeText) {
+    $out = @{}
+    if ($null -eq $ComposeText) { return $out }
+    foreach ($m in [regex]::Matches((Remove-ComposeComments $ComposeText), '(?m)^[ 	]*image:\s*\S*?(culpa-[A-Za-z0-9_-]+):([^"''\s]+)')) {
+        $out[$m.Groups[1].Value] = $m.Groups[2].Value
+    }
+    return $out
+}
+
+# ISS-V103-12 - is the SHIPPED compose a release the LIVE one has not had?
+#
+# This used to be Compare-CulpaVersions on the culpa-server pin and nothing
+# else, so any per-component release (D-087) that did not bump culpa-server
+# never re-pinned: new npm files over old containers. Observed on v1.0.4.
+#
+# Rule: at least one pinned Culpa image is NEWER, and none is OLDER.
+#   - an image in shipped but not live counts as NEWER (a release that ADDS a
+#     service must reach the live file, or that service never starts);
+#   - an image in live but not shipped is ignored, not "older";
+#   - unparsable tags still compare 0, so exotic dev tags contribute neither
+#     direction and can never brick a launch.
+#
+# MUST stay behaviourally identical to isComposeUpgrade in
+# packaging/npm-getculpa/lib/preflight.mjs - tests/npm-ps1-repin-parity.test.ts
+# executes both against one shared table of cases.
+function Test-ComposeUpgrade([string]$ShippedText, [string]$LiveText) {
+    $shipped = Get-PinnedImageVersions $ShippedText
+    $live = Get-PinnedImageVersions $LiveText
+    if ($shipped.Count -eq 0 -or $live.Count -eq 0) { return $false }
+
+    $anyNewer = $false
+    foreach ($name in $shipped.Keys) {
+        if (-not $live.ContainsKey($name)) { $anyNewer = $true; continue }
+        $cmp = Compare-CulpaVersions $shipped[$name] $live[$name]
+        if ($cmp -eq -1) {
+            # not silent: an ambiguous file must not look like "nothing to do"
+            Write-Warning "The shipped compose moves $name BACKWARD ($($live[$name]) -> $($shipped[$name])) while moving others forward; refusing to re-pin from an ambiguous file."
+            return $false
+        }
+        if ($cmp -eq 1) { $anyNewer = $true }
+    }
+    return $anyNewer
+}
+
 # QW-1 - ONE canonical compose. The live file ($LivePath) owns the pin; the
 # shipped culpa-compose.yml beside the install ($ShippedPath) is only a
 # SOURCE: when an upgrade drops a NEWER shipped file, the live one is
@@ -73,10 +141,7 @@ function Compare-CulpaVersions([string]$A, [string]$B) {
 function Sync-CanonicalCompose([string]$ShippedPath, [string]$LivePath) {
     if (-not (Test-Path $LivePath)) { return "no-live" }
     if (-not (Test-Path $ShippedPath)) { return "no-shipped" }
-    $shipped = Get-PinnedServerVersion (Get-Content $ShippedPath -Raw)
-    $live = Get-PinnedServerVersion (Get-Content $LivePath -Raw)
-    if ($null -eq $shipped -or $null -eq $live) { return "kept" }
-    if ((Compare-CulpaVersions $shipped $live) -eq 1) {
+    if (Test-ComposeUpgrade (Get-Content $ShippedPath -Raw) (Get-Content $LivePath -Raw)) {
         Copy-Item $ShippedPath $LivePath -Force
         return "synced"
     }

package/lib/preflight.d.mts

@@ -19,6 +19,12 @@ export function checkDockerEngineReachable(spawnSync?: SpawnSyncLike): boolean;
 
 export function parsePinnedServerVersion(composeText: string | null | undefined): string | null;
 export function compareVersions(a: string | null | undefined, b: string | null | undefined): -1 | 0 | 1;
+export function parsePinnedImageVersions(composeText: string | null | undefined): Record<string, string>;
+export function isComposeUpgrade(
+  shippedComposeText: string | null | undefined,
+  liveComposeText: string | null | undefined,
+  onRefusal?: (message: string) => void,
+): boolean;
 
 export type InstallKind = "fresh" | "upgrade" | "same-version" | "repair";
 

package/lib/preflight.mjs

@@ -61,9 +61,38 @@ export function checkDockerEngineReachable(spawnSync = realSpawnSync) {
 }
 
 // Same parsing target as launch-culpa.ps1's Get-PinnedServerVersion.
+// Full-line YAML comments, removed before any pin is parsed. Review finding
+// (2026-08-23): the unanchored parser below matched
+//   #     ghcr.io/myaigidev/culpa-server:v1.0.3
+// inside installers/culpa-compose.yml's cosign-verify EXAMPLE at line 29 —
+// which precedes the real `image:` pin at line 58, so the comment won the
+// first-match race.
+// Both read v1.0.3 today so nothing was visibly wrong, but publish.sh rewrites
+// the example and the pin with SEPARATE seds: a server release whose example
+// sed failed to match would leave QW-3 comparing a stale version against
+// last-boot-version.txt and REFUSING to launch a perfectly good pin.
+function stripComposeComments(composeText) {
+  return String(composeText ?? "")
+    .split(/\r?\n/)
+    .filter((line) => !/^\s*#/.test(line))
+    .join("\n");
+}
+
+// Anchored on `image:` as well as comment-stripped: a pin is something docker
+// would actually pull, never prose that happens to name the image.
 export function parsePinnedServerVersion(composeText) {
-  const m = /culpa-server:([^"\s]+)/.exec(composeText ?? "");
-  return m ? m[1] : null;
+  // Comment-stripping is what actually cures the defect: prose can never be a
+  // pin. The `image:` anchor is preferred but NOT required — callers legitimately
+  // pass a bare "culpa-server:vX.Y.Z" fragment (isIncomingComposeOlder's unit
+  // facts do), and requiring the anchor turned 5 of those 7 tests vacuous while
+  // only 2 went red. Anchored first so a real compose is read from its image
+  // line; unanchored fallback over the SAME comment-stripped text, where the
+  // only thing left to match is real content.
+  const text = stripComposeComments(composeText);
+  const anchored = /^[ \t]*image:\s*\S*?culpa-server:([^"'\s]+)/m.exec(text);
+  if (anchored) return anchored[1];
+  const bare = /culpa-server:([^"'\s]+)/.exec(text);
+  return bare ? bare[1] : null;
 }
 
 // Same fail-open-to-"equal" semantics as launch-culpa.ps1's
@@ -83,6 +112,82 @@ export function compareVersions(a, b) {
   return 0;
 }
 
+// ISS-V103-12. Every pinned CULPA image in a compose text, as
+// { "culpa-server": "v1.0.3", "culpa-dashboard": "v1.0.5" }.
+//
+// Deliberately scoped to `culpa-*`: the compose also pins postgres, and a
+// postgres bump must never be read as a Culpa release. Non-Culpa images are
+// simply absent from the map.
+export function parsePinnedImageVersions(composeText) {
+  const out = {};
+  // `^[ \t]*image:` with /m, not a bare `image:` anywhere. Comment-stripping
+  // alone was not enough: `command: echo "image: .../culpa-dashboard:v9.9.9"`
+  // is not a comment, yet an unanchored match read v9.9.9 as the pin (verified
+  // 2026-08-23, from a CodeRabbit finding). A pin is a YAML key at line start.
+  const rx = /^[ \t]*image:\s*\S*?(culpa-[A-Za-z0-9_-]+):([^"'\s]+)/gm;
+  let m;
+  // comment-stripped for the same reason parsePinnedServerVersion is: a
+  // commented-out or example `image:` line is documentation, not a pin.
+  const text = stripComposeComments(composeText);
+  while ((m = rx.exec(text)) !== null) out[m[1]] = m[2];
+  return out;
+}
+
+// ISS-V103-12. Is the SHIPPED compose a release the live one has not had?
+//
+// This used to be `compareVersions(shippedServerPin, livePin) === 1` — the
+// culpa-server tag and nothing else. A release is PER-COMPONENT (D-087), so
+// any release that did not bump culpa-server left shipped == live and the
+// re-pin never fired: v1.0.4 and v1.0.5 both reached existing installs as new
+// npm FILES over old CONTAINERS, which is worse than not shipping because the
+// two then disagree.
+//
+// The rule now: at least one pinned Culpa image is NEWER, and none is OLDER.
+//   - "at least one newer" generalises the original intent (the shipped file
+//     represents a release that moved something forward) without caring WHICH
+//     component moved;
+//   - "none older" preserves the one-direction rule this function has always
+//     had — an OLDER shipped file never wins. A file moving one image forward
+//     and another back is ambiguous, cannot be produced by publish.sh, and
+//     must not silently win;
+//   - an image in shipped but not live counts as newer: a release that ADDS a
+//     service must reach the live file or that service never starts;
+//   - an image in live but not shipped is ignored, not treated as older;
+//   - unparsable tags still compare as 0, so exotic dev tags contribute
+//     neither direction and can never brick a launch.
+//
+// NB QW-3 (backward-pin refusal) and QW-4 (pre-migration backup) deliberately
+// still key off the culpa-server pin: those are about database migration
+// history, not release delivery, and widening them would change when backups
+// and refusals fire.
+export function isComposeUpgrade(shippedComposeText, liveComposeText, onRefusal = () => {}) {
+  const shipped = parsePinnedImageVersions(shippedComposeText);
+  const live = parsePinnedImageVersions(liveComposeText);
+  if (Object.keys(shipped).length === 0 || Object.keys(live).length === 0) return false;
+
+  let anyNewer = false;
+  for (const [name, shippedTag] of Object.entries(shipped)) {
+    if (!(name in live)) {
+      anyNewer = true;
+      continue;
+    }
+    const cmp = compareVersions(shippedTag, live[name]);
+    // Refusing an ambiguous file must not look like "nothing to do". QW-3
+    // explains itself loudly when it refuses; this branch used to be silent,
+    // leaving an operator asking why an upgrade never landed. The claim that
+    // publish.sh cannot produce such a file is also weaker than it sounds —
+    // this very release had step 5 applied BY HAND.
+    if (cmp === -1) {
+      onRefusal(
+        `getculpa: the shipped compose moves ${name} BACKWARD (${live[name]} -> ${shippedTag}) while moving others forward; refusing to re-pin from an ambiguous file.`,
+      );
+      return false;
+    }
+    if (cmp === 1) anyNewer = true;
+  }
+  return anyNewer;
+}
+
 // Shared by classifyInstall and classifyUpgrade so the two can never read
 // "what version is already here" two different ways.
 function resolveInstalledVersionInfo(appDir) {

package/lib/start.mjs

@@ -40,7 +40,7 @@ import {
   waitForHealth,
   waitForPgReady,
 } from "./docker.mjs";
-import { checkDockerPresent, compareVersions, parsePinnedServerVersion } from "./preflight.mjs";
+import { checkDockerPresent, compareVersions, isComposeUpgrade, parsePinnedServerVersion } from "./preflight.mjs";
 import { askYesNo as realAskYesNo } from "./tty.mjs";
 
 export const STAGES = Object.freeze({
@@ -123,9 +123,12 @@ function isBackwardPin(pinnedVersion, lastBootVersion) {
 async function runVersionGuards({ appDir, liveCompose, spawnSync, env, log, warn, sleepFn }) {
   const shippedPath = path.join(appDir, "culpa-compose.yml");
   if (existsSync(shippedPath)) {
-    const shippedVer = parsePinnedServerVersion(readFileSync(shippedPath, "utf8"));
-    const liveVer = parsePinnedServerVersion(readFileSync(liveCompose, "utf8"));
-    if (shippedVer && liveVer && compareVersions(shippedVer, liveVer) === 1) {
+    // ISS-V103-12: this compared the culpa-server pin and NOTHING else, so a
+    // per-component release (D-087) that did not bump culpa-server never
+    // re-pinned the live compose — the customer got new npm files over old
+    // containers. isComposeUpgrade weighs EVERY pinned Culpa image, and keeps
+    // the one-direction rule (an older shipped file still never wins).
+    if (isComposeUpgrade(readFileSync(shippedPath, "utf8"), readFileSync(liveCompose, "utf8"), warn)) {
       copyFileSync(shippedPath, liveCompose);
       log("==> Upgrade detected: live compose re-pinned from the shipped culpa-compose.yml");
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "getculpa",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Culpa CLI: `npm i -g getculpa` provisions the full Culpa install (Windows-installer parity) and leaves it dormant. `getculpa` wakes the stack.",
   "license": "SEE LICENSE IN LICENSE",
   "bin": {