fix(service-package): unwrap the mysql2 [rows, fields] tuple in normalizeRows (#11207)

The local flattener had two accepting branches where its docblock claimed
three-dialect coverage. mysql2's `[rows, fields]` tuple is an array, so it
satisfied the bare-array branch and was returned whole: `get()` read index 0 —
the row array, not a row — so `row.manifest` was undefined, `JSON.parse` threw
into the method's own catch, and the caller was told the package was not
installed over a driver that had just returned it. `list()` failed the same way
into `[]`.

Reachable in a supported composition: `OS_DATABASE_URL=mysql://…` dispatches to
a SqlDriver on the mysql2 client as the DEFAULT driver, and both
`ObjectQLEngine.execute()` and `SqlDriver.execute()` return the client's shape
verbatim.

Kept a local copy rather than depending on `@objectstack/metadata-protocol`,
matching the call this file's `isResultSet` already documents. Drift is pinned
instead: `mysql2-tuple.test.ts` asserts all three dialect shapes recover the
same row, that the tuple test cannot misfire on a bare row array, and that an
empty result in any dialect still answers "no rows".


Claude-Session: https://claude.ai/code/session_01APWX2AwT3a4xDcjPCe8bk4

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-sam

.changeset/eighty-donkeys-shave.md

@@ -0,0 +1,23 @@
+---
+"@objectstack/service-package": patch
+---
+
+Unwrap the mysql2 `[rows, fields]` tuple in the package service's row flattener
+
+On a MySQL/MariaDB-backed deployment (`OS_DATABASE_URL=mysql://…`, which builds a
+`SqlDriver` on the `mysql2` client as the default driver), `PackageService.get()` and
+`PackageService.list()` reported **"this package is not installed"** and **"no packages
+are installed"** over a database that had just returned the rows.
+
+`ObjectQLEngine.execute()` and `SqlDriver.execute()` both pass the underlying client's
+result through verbatim, so mysql2's `[rows, fields]` tuple reached the service's local
+`normalizeRows` unflattened. The tuple is an array, so it was returned whole; `get()`
+then read index 0 — the row *array* rather than a row — and `JSON.parse(undefined)` threw
+into the method's own catch, which answers `null`. `list()` failed the same way into `[]`.
+Boot-time package hydration read the same empty answer and silently installed nothing.
+
+The flattener now unwraps the tuple, matching the three-dialect coverage its own docblock
+already claimed and the `metadata-protocol` sibling already implemented. The bare row
+array (better-sqlite3 through knex, Turso) and `{ rows, rowCount }` (pg) shapes are
+unchanged, and an empty result in any of the three still answers "no rows" rather than
+raising the seam refusal.

packages/services/service-package/src/index.ts

@@ -166,20 +166,55 @@ function declaresHttpAnswer(error: unknown): boolean {
 /**
  * Normalize the result of `objectql.execute()` into a row array.
  *
- * Different drivers return different shapes for raw SELECT statements:
- *   - SQL driver (knex/SQLite) and Turso remote transport return rows
- *     directly as an array.
- *   - PostgreSQL (knex/pg) returns `{ rows, rowCount, ... }`.
- *   - Some drivers may return `{ rows: [...] }` wrappers in other contexts.
+ * `ObjectQLEngine.execute()` returns what the driver returned, VERBATIM, and
+ * `SqlDriver.execute()` in turn returns `knex.raw()` verbatim — so the shape
+ * that arrives here is the underlying client's own, and there are THREE:
  *
- * This helper accepts any of those shapes and always returns an array.
+ *   1. **bare row array** — better-sqlite3 through knex, and Turso's remote
+ *      transport (which returns `@libsql/client`'s `result.rows`).
+ *   2. **`{ rows, rowCount, … }`** — PostgreSQL (knex/pg).
+ *   3. **`[rows, fields]` tuple** — mysql2. The first element is itself the
+ *      row array; the second is column metadata.
+ *
+ * ⚠️ [#11062] Shape 3 used to fall through the `Array.isArray` branch
+ * UNFLATTENED, and that was not a shape this file merely failed to support — it
+ * was a shape it MISREAD. The tuple is an array, so it satisfied both the
+ * branch below and {@link isResultSet}; `get()` then read `rows[0]`, which is
+ * the row ARRAY rather than a row, so `row.manifest` was `undefined` and
+ * `JSON.parse(undefined)` threw into `get()`'s own catch — which answers
+ * `null`, i.e. **"this package is not installed"** over a driver that had just
+ * returned the row. `list()` failed the same way into `[]`. The defect is
+ * reachable in a supported composition: `OS_DATABASE_URL=mysql://…` builds a
+ * `SqlDriver` on the `mysql2` client as the DEFAULT driver, which is the one
+ * this service's raw SELECTs land on.
+ *
+ * The tuple test is `Array.isArray(result[0])`, and it cannot misfire on shape
+ * 1: a bare row array holds row OBJECTS. Measured on `@libsql/client` 0.17.4,
+ * `result.rows` is a real array whose elements are plain objects
+ * (`Array.isArray(rows[0]) === false`), and knex/better-sqlite3 likewise maps
+ * rows to objects. Only mysql2 nests an array at index 0.
+ *
+ * ⛔ A LOCAL copy, deliberately — the same call this file's {@link isResultSet}
+ * already makes and for the same reason: `@objectstack/metadata-protocol`
+ * (whose exported `normalizeRows` is the sibling this arm is aligned with) is
+ * not a dependency of this package at all, and it resolves through `exports` to
+ * `dist/`, so value-importing it would make this package's unit pins a verdict
+ * about a build artifact (`check:test-source-alias`). Unifying the copies is
+ * its own decision, not a rider on this fix. What holds them together
+ * meanwhile is a pin: `mysql2-tuple.test.ts` asserts all three shapes recover
+ * the SAME row, so the next divergence is a red test rather than prose someone
+ * has to re-read.
  *
  * ⚠️ [#10965] It returns `[]` for EVERYTHING else too, and that is the whole
  * defect this file's seam guard exists for — see {@link isResultSet}. Flatten
  * with this only AFTER the result has been established as an answer.
  */
 function normalizeRows(result: any): any[] {
-  if (Array.isArray(result)) return result;
+  if (Array.isArray(result)) {
+    // mysql2's `[rows, fields]`: the first element is itself the row array.
+    if (result.length > 0 && Array.isArray(result[0])) return result[0];
+    return result;
+  }
   if (result && Array.isArray(result.rows)) return result.rows;
   return [];
 }

packages/services/service-package/src/mysql2-tuple.test.ts

@@ -0,0 +1,215 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * #11062 — the mysql2 `[rows, fields]` tuple was never unwrapped, so a
+ * POPULATED result answered "not installed".
+ *
+ * ## The shape, and why it reaches this file
+ *
+ * `ObjectQLEngine.execute()` returns what the driver returned verbatim, and
+ * `SqlDriver.execute()` returns `knex.raw()` verbatim — so the raw client's own
+ * per-dialect shape arrives at this service's `normalizeRows` untouched.
+ * `sql-driver.ts` says so in its own words at the one place it flattens a raw
+ * SELECT internally: *"mysql2 returns [rows, fields]"*.
+ *
+ * This is a SUPPORTED composition, not a hypothetical one:
+ * `OS_DATABASE_URL=mysql://…` is dispatched by `standalone-stack.ts` to
+ * `kind === 'mysql'` → a `SqlDriver` on the `mysql2` client, as the DEFAULT
+ * driver — and the default driver is exactly the one `objectql.execute()`
+ * selects for this service's raw SELECTs (its own docblock names
+ * `PackageService` as the caller it exists for). `os serve` loads
+ * `PackageServicePlugin` for the `marketplace` feature over that same engine.
+ *
+ * ## What the defect did
+ *
+ * The tuple is an ARRAY, so it satisfied both the old `Array.isArray(result)`
+ * branch and `isResultSet` — no false 503, and #10965's guard was never at
+ * fault. `normalizeRows` simply returned the 2-element tuple, so:
+ *
+ *   - `get()`  read `rows[0]` — the row ARRAY, not a row. `row.manifest` was
+ *     `undefined`, `JSON.parse(undefined)` threw into `get()`'s catch, and the
+ *     catch answers `null` ⇒ **"this package is not installed"**.
+ *   - `list()` mapped over `[rows, fields]` and threw in the same place, into a
+ *     catch that answers `[]` ⇒ **"no packages are installed"**.
+ *
+ * Both over a driver that had just returned the row. The swallowed throw is the
+ * signature, which is why the populated cases below also assert that NOTHING
+ * was logged to `error` — a fix that returned the right rows while still
+ * throwing and recovering somewhere would pass a rows-only assertion.
+ *
+ * ## What is pinned — all three dialects, one row, one answer
+ *
+ * The parity case is the point: the SAME logical row, spelled three ways,
+ * must produce the SAME answer. A fix that taught the flattener the tuple but
+ * broke the bare array or `{ rows }` would fail here, and so would a "fix" that
+ * special-cased mysql2 into a different result. Shapes 1 and 2 are not
+ * regression ballast — they are half the contract.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  PackageServicePlugin,
+  type PackageService,
+} from './index.js';
+
+const MANIFEST = { id: 'com.acme.crm', name: 'CRM', version: '1.0.0', type: 'application' };
+const METADATA = { author: 'ACME', installedBy: 'os-dev' };
+
+/** One stored row, as every dialect hands back the columns of `sys_packages`. */
+const ROW = {
+  id: 'com.acme.crm',
+  version: '1.0.0',
+  manifest: JSON.stringify(MANIFEST),
+  metadata: JSON.stringify(METADATA),
+  hash: 'd3adb33f',
+  created_at: '2026-08-23T00:00:00.000Z',
+  updated_at: '2026-08-23T00:00:00.000Z',
+};
+
+/** The answer both read doors must produce from that row, in every dialect. */
+const EXPECTED = {
+  id: 'com.acme.crm',
+  version: '1.0.0',
+  manifest: MANIFEST,
+  metadata: METADATA,
+  hash: 'd3adb33f',
+  created_at: '2026-08-23T00:00:00.000Z',
+  updated_at: '2026-08-23T00:00:00.000Z',
+};
+
+/**
+ * mysql2's second tuple element — column metadata, never rows.
+ *
+ * Spelled out rather than left `[]` so the tuple case cannot pass by accident:
+ * with a non-empty second element, returning the whole tuple yields a
+ * 2-element `list()`, which is visibly wrong rather than coincidentally equal.
+ */
+const FIELDS = [
+  { name: 'id', type: 253 },
+  { name: 'version', type: 253 },
+  { name: 'manifest', type: 252 },
+];
+
+interface Booted {
+  svc: PackageService;
+  errorLogs: string[];
+}
+
+/** Boot the real plugin over a seam that returns `result` for every SELECT. */
+async function bootReturning(result: unknown): Promise<Booted> {
+  const errorLogs: string[] = [];
+  const engine: any = {
+    async execute({ sql }: { sql: string; args?: unknown[] }) {
+      // DDL from `ensureTable` answers like a real driver; only SELECTs carry
+      // the dialect shape under test.
+      return /^\s*select/i.test(sql) ? result : undefined;
+    },
+  };
+
+  let registered: PackageService | undefined;
+  const ctx: any = {
+    logger: {
+      debug: () => {},
+      info: () => {},
+      warn: () => {},
+      error: (msg: string) => errorLogs.push(String(msg)),
+    },
+    getService: (n: string) => (n === 'objectql' ? engine : undefined),
+    registerService: (_n: string, s: PackageService) => { registered = s; },
+  };
+
+  const plugin = new PackageServicePlugin();
+  await plugin.init(ctx);
+  await plugin.start(ctx);
+  return { svc: registered!, errorLogs };
+}
+
+// ───────────────────────────────────────────────────────────────────────────
+// 1. The three dialect shapes recover the SAME row
+// ───────────────────────────────────────────────────────────────────────────
+
+describe('#11062 normalizeRows — every supported dialect answers with the row', () => {
+  const dialects: Array<[string, unknown]> = [
+    ['bare row array (better-sqlite3 through knex, Turso remote)', [ROW]],
+    ['`{ rows, rowCount }` (pg)', { rows: [ROW], rowCount: 1 }],
+    ['`[rows, fields]` tuple (mysql2)', [[ROW], FIELDS]],
+  ];
+
+  for (const [label, shape] of dialects) {
+    it(`get() returns the package from ${label}`, async () => {
+      const { svc, errorLogs } = await bootReturning(shape);
+      await expect(svc.get('com.acme.crm', 'latest')).resolves.toEqual(EXPECTED);
+      // The defect's signature was a SWALLOWED throw, not a wrong return.
+      expect(errorLogs).toEqual([]);
+    });
+
+    it(`list() returns exactly one package from ${label}`, async () => {
+      const { svc, errorLogs } = await bootReturning(shape);
+      await expect(svc.list()).resolves.toEqual([EXPECTED]);
+      expect(errorLogs).toEqual([]);
+    });
+  }
+
+  it('all three dialects agree — same row in, same answer out', async () => {
+    const answers = [];
+    for (const [, shape] of dialects) {
+      const { svc } = await bootReturning(shape);
+      answers.push(await svc.list());
+    }
+    expect(answers[0]).toEqual(answers[1]);
+    expect(answers[1]).toEqual(answers[2]);
+  });
+});
+
+// ───────────────────────────────────────────────────────────────────────────
+// 2. The tuple branch must not misfire on the shapes that already worked
+// ───────────────────────────────────────────────────────────────────────────
+
+describe('#11062 the tuple test cannot swallow a bare row array', () => {
+  /**
+   * The unwrap keys on `Array.isArray(result[0])`, so it fires only where a
+   * dialect NESTS an array at index 0. A bare row array holds row OBJECTS —
+   * measured on `@libsql/client` 0.17.4, `result.rows` is a real array whose
+   * elements are plain objects (`Array.isArray(rows[0]) === false`), and knex
+   * over better-sqlite3 likewise maps rows to objects.
+   */
+  it('a multi-row bare array keeps every row', async () => {
+    const second = { ...ROW, id: 'com.acme.hr', version: '2.0.0' };
+    const { svc } = await bootReturning([ROW, second]);
+    const listed = await svc.list();
+    expect(listed).toHaveLength(2);
+    expect(listed.map((p: any) => p.id)).toEqual(['com.acme.crm', 'com.acme.hr']);
+  });
+
+  it('a single-row bare array is not mistaken for a tuple', async () => {
+    const { svc } = await bootReturning([ROW]);
+    await expect(svc.list()).resolves.toEqual([EXPECTED]);
+  });
+});
+
+// ───────────────────────────────────────────────────────────────────────────
+// 3. An EMPTY answer stays an answer — in every dialect, including the tuple
+// ───────────────────────────────────────────────────────────────────────────
+
+describe('#11062 empty results remain "no rows", never a refusal', () => {
+  /**
+   * The half that stops this being a rename (#10965's leg, re-asserted for the
+   * shape this card adds): an empty result set in ANY spelling is still a
+   * result set, so it answers "not installed" / "nothing installed" rather than
+   * raising the seam refusal.
+   */
+  const empties: Array<[string, unknown]> = [
+    ['bare `[]`', []],
+    ['`{ rows: [], rowCount: 0 }` (pg)', { rows: [], rowCount: 0 }],
+    ['`[[], fields]` (mysql2, zero rows)', [[], FIELDS]],
+  ];
+
+  for (const [label, shape] of empties) {
+    it(`${label} answers no-rows without throwing`, async () => {
+      const { svc, errorLogs } = await bootReturning(shape);
+      await expect(svc.get('com.acme.crm', 'latest')).resolves.toBeNull();
+      await expect(svc.list()).resolves.toEqual([]);
+      expect(errorLogs).toEqual([]);
+    });
+  }
+});

packages/services/service-package/src/null-seam.test.ts

@@ -39,14 +39,14 @@
  *
  * ## What is deliberately NOT asserted here
  *
- * This service's LOCAL `normalizeRows` implements TWO of the three dialect
- * shapes — a bare row array and `{ rows }`. It does not unwrap the mysql2
- * `[rows, fields]` tuple the way `metadata-protocol`'s copy does (that one
- * tests `Array.isArray(result[0])`). So no populated-tuple result is asserted
- * here: it would be a pin on behaviour this file does not have. What IS pinned
- * is that a tuple-shaped result is still treated as an ANSWER, so the guard
- * cannot misfire on a dialect it does not fully flatten. The gap itself is
- * filed separately rather than fixed as a rider.
+ * The ROWS a dialect yields are not this file's subject — only the
+ * answered/unanswered separation is. When these tests were written the local
+ * `normalizeRows` implemented two of the three dialect shapes and did not
+ * unwrap the mysql2 `[rows, fields]` tuple; that gap was filed rather than
+ * fixed as a rider, and closed in #11062. The populated-tuple assertions live
+ * with the rest of the dialect-shape contract in `mysql2-tuple.test.ts`. What
+ * stays pinned HERE is the part this card owns: a tuple-shaped result is an
+ * ANSWER, so the guard cannot misfire on it.
  */
 
 import { describe, it, expect } from 'vitest';
@@ -267,9 +267,9 @@ describe('#10965 the guard never turns a result set into a refusal', () => {
   });
 
   it('an `[rows, fields]`-shaped result is an ANSWER — the guard does not misfire', async () => {
-    // This local flattener does not UNWRAP the tuple (filed separately), so
-    // nothing is asserted about the rows it yields. What is asserted is the
-    // only thing this card owns: it is not mistaken for a seam that failed to
+    // Nothing is asserted here about the rows the tuple yields — that is
+    // `mysql2-tuple.test.ts`'s contract (#11062). What is asserted is the only
+    // thing this card owns: it is not mistaken for a seam that failed to
     // answer, so no dialect gets a false 503.
     const { svc } = await bootWith(seamReturning([[], []]));
     await expect(svc.list()).resolves.toEqual([]);