From f5ec6bacd5cfe97d6505f119a2560b9e6df8855d Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 29 Sep 2026 17:17:14 +0000 Subject: [PATCH 1/2] docs(service-datasource): re-anchor the dead tracker citations to the commits that decided them Every comment and docblock site under packages/services/service-datasource/src that cited a tracker number answering 404 now cites the commit in this repository's history that decided what the line describes, and says in its own words what that commit decided (ruling C+D, form C): 75 sites on 74 lines in 23 files, 16 numbers, 17 commits, plus 4 reflow lines. Comments only; every file keeps its line count, and no citation number is added. Claude-Session: https://claude.ai/code/session_01XY5uCwTjZj7884yYtyur4H Co-authored-by: Claude --- ...admin-routes-authz-outage-envelope.test.ts | 6 +-- ...n-routes-tenancy-posture-admission.test.ts | 2 +- .../bound-secret-dsn-branches.test.ts | 4 +- .../connection-engine-like-contract.test.ts | 4 +- .../datasource-admin-service.test.ts | 2 +- .../datasource-config-redaction.test.ts | 2 +- .../datasource-connection-service.test.ts | 2 +- .../__tests__/datasource-pool-support.test.ts | 4 +- .../default-datasource-driver-factory.test.ts | 4 +- .../src/__tests__/driver-catalog.test.ts | 2 +- .../external-datasource-service.test.ts | 14 ++--- .../src/__tests__/mysql-dsn-ssl.test.ts | 10 ++-- .../postgres-dsn-bound-secret.test.ts | 4 +- .../__tests__/prebuilt-driver-factory.test.ts | 2 +- .../service-datasource/src/admin-routes.ts | 4 +- .../src/datasource-connection-service.ts | 12 ++--- .../src/datasource-credential-migration.ts | 4 +- .../src/datasource-pool-support.ts | 2 +- .../src/default-datasource-driver-factory.ts | 52 +++++++++---------- .../service-datasource/src/driver-catalog.ts | 4 +- .../src/external-datasource-service.ts | 10 ++-- .../src/missing-driver-package-error.ts | 4 +- .../src/turso-driver-config.ts | 2 +- 23 files changed, 78 insertions(+), 78 deletions(-) diff --git a/packages/services/service-datasource/src/__tests__/admin-routes-authz-outage-envelope.test.ts b/packages/services/service-datasource/src/__tests__/admin-routes-authz-outage-envelope.test.ts index a85a2a1ca9d..60420b3bad3 100644 --- a/packages/services/service-datasource/src/__tests__/admin-routes-authz-outage-envelope.test.ts +++ b/packages/services/service-datasource/src/__tests__/admin-routes-authz-outage-envelope.test.ts @@ -24,7 +24,7 @@ * turns exactly that into `AuthzStoreUnavailableError`: declared `status: * 503`, declared `code: SERVICE_UNAVAILABLE`. * 3. `requireDatasourceAdmin`'s own `catch` re-raises it rather than - * laundering an outage into a denial — the #13279 ruling, which this card + * laundering an outage into a denial — commit 6a180e42d's ruling, which this card * leaves completely untouched. Only the RENDERING moves. * 4. The throw escapes the handler. Before this card the adapter answered * `500 { code: 'INTERNAL_ERROR', message: 'No response from handler' }` — @@ -50,7 +50,7 @@ * ⭐ The controls answering `401` rather than `200` is the SHARPER reading, and * it is the discriminator this card is actually about: a 401 is a VERDICT the * door reached, while the outage arm reaches no verdict at all — which is - * exactly why #13279 refuses to answer it as a denial. Two different 4xx/5xx + * exactly why commit 6a180e42d refuses to answer it as a denial. Two different 4xx/5xx * answers separated by whether a decision was ever taken. */ @@ -159,7 +159,7 @@ describe('GET /api/v1/datasources — an authz-store outage reaches the caller a const { listDatasources } = await list({ kind: 'throws' }); // The card moves the RENDERING only. If the outage started resolving to a - // verdict, this would be non-zero and #13279 would have been reversed as a + // verdict, this would be non-zero and commit 6a180e42d would have been reversed as a // rider. expect(listDatasources).not.toHaveBeenCalled(); }); diff --git a/packages/services/service-datasource/src/__tests__/admin-routes-tenancy-posture-admission.test.ts b/packages/services/service-datasource/src/__tests__/admin-routes-tenancy-posture-admission.test.ts index 2556ec4ab96..d031de3a5bf 100644 --- a/packages/services/service-datasource/src/__tests__/admin-routes-tenancy-posture-admission.test.ts +++ b/packages/services/service-datasource/src/__tests__/admin-routes-tenancy-posture-admission.test.ts @@ -537,7 +537,7 @@ describe('[#15350] §5b — a `tenancy` service that was REGISTERED and FAILED i // handler"), not the `503 SERVICE_UNAVAILABLE` the brand carries. That is a // PRE-EXISTING relay gap, not one this card opened — `requireDatasourceAdmin` // has re-raised `AuthzStoreUnavailableError` for the identical `ql` - // permission-store outage since #13279, out of route handlers that have no + // permission-store outage since commit 6a180e42d, out of route handlers that have no // `catch`, and the Hono adapter renders any escaped throw as a bare 500. It // is filed separately. Asserting the class rather than the digits keeps this // pin measuring the SECURITY property — the outage is never answered as an diff --git a/packages/services/service-datasource/src/__tests__/bound-secret-dsn-branches.test.ts b/packages/services/service-datasource/src/__tests__/bound-secret-dsn-branches.test.ts index f256c90b6bb..297d0ac890c 100644 --- a/packages/services/service-datasource/src/__tests__/bound-secret-dsn-branches.test.ts +++ b/packages/services/service-datasource/src/__tests__/bound-secret-dsn-branches.test.ts @@ -1,7 +1,7 @@ // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license. /** - * #8696 — a bound `external.credentialsRef` reaches the client on the mysql + * Commit 72050cc47 — a bound `external.credentialsRef` reaches the client on the mysql * arm's DSN branch, not only on its discrete-fields branch. * * ## The defect @@ -69,7 +69,7 @@ * The first failure is the whole defect in one line: the arm answered with the * DSN *string*, which has no key for a credential to live in. * - * ## The mongodb half, added second (#8696's remaining arm) + * ## The mongodb half, added second (commit 90a12fb18, the remaining arm) * * `buildMongoUrl`'s `if (explicit) return explicit;` dropped the bound secret * the same way, and is closed by `buildMongoAuth` — `options.auth` beside an diff --git a/packages/services/service-datasource/src/__tests__/connection-engine-like-contract.test.ts b/packages/services/service-datasource/src/__tests__/connection-engine-like-contract.test.ts index 33854bbc03a..043c9a34a41 100644 --- a/packages/services/service-datasource/src/__tests__/connection-engine-like-contract.test.ts +++ b/packages/services/service-datasource/src/__tests__/connection-engine-like-contract.test.ts @@ -1,7 +1,7 @@ // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license. /** - * [#12010] The seam pin for `ConnectionEngineLike`. + * [commit 77b91bdb4] The seam pin for `ConnectionEngineLike`. * * `ConnectionEngineLike` is the exported view `DatasourceConnectionService` * drives the ObjectQL `'data'` engine through. It used to re-declare seven @@ -55,7 +55,7 @@ describe('ConnectionEngineLike is the contract, not a fork of it (#12010)', () = it('refuses a value that is not a driver, at the call site', () => { const engine = {} as ConnectionEngineLike; // @ts-expect-error - a bare `{ name }` is not an `IDataDriver`. This call - // compiled before #12010, which is precisely the hole: the seam promised + // compiled before commit 77b91bdb4, which is precisely the hole: the seam promised // the engine accepts any value as a driver, and it does not. engine.registerDriver?.({ name: 'com.example.not-a-driver' }); expect(engine).toBeTruthy(); diff --git a/packages/services/service-datasource/src/__tests__/datasource-admin-service.test.ts b/packages/services/service-datasource/src/__tests__/datasource-admin-service.test.ts index 1e7259edcfa..97b7dddf4f8 100644 --- a/packages/services/service-datasource/src/__tests__/datasource-admin-service.test.ts +++ b/packages/services/service-datasource/src/__tests__/datasource-admin-service.test.ts @@ -671,7 +671,7 @@ describe('migrateCredential (#8155)', () => { /** * The contract half the #8153 block was about: the row this migration WRITES - * must be spec-valid. Before PR #8588 a managed row carrying + * must be spec-valid. Before commit 3dede582b a managed row carrying * `external.credentialsRef` failed re-parse, so the migration would have moved * rows from "invalid because it holds cleartext" to "invalid because it holds a * credentialsRef" while reporting success. diff --git a/packages/services/service-datasource/src/__tests__/datasource-config-redaction.test.ts b/packages/services/service-datasource/src/__tests__/datasource-config-redaction.test.ts index 568ba142396..635dada2872 100644 --- a/packages/services/service-datasource/src/__tests__/datasource-config-redaction.test.ts +++ b/packages/services/service-datasource/src/__tests__/datasource-config-redaction.test.ts @@ -404,7 +404,7 @@ describe('GREEN ON MAIN — #8078 is not weakened by anything above', () => { }); describe('#9040 — the passthrough spelling, both halves at the service door', () => { - /** A legacy mongo row written before #9040: the password rides the MongoClient passthrough. */ + /** A legacy mongo row written before commit 24206416a: the password rides the MongoClient passthrough. */ const LEGACY_MONGO: StoredDatasource = { name: 'legacy_mongo', driver: 'mongodb', diff --git a/packages/services/service-datasource/src/__tests__/datasource-connection-service.test.ts b/packages/services/service-datasource/src/__tests__/datasource-connection-service.test.ts index 14d34f5e7df..ba0a17c6666 100644 --- a/packages/services/service-datasource/src/__tests__/datasource-connection-service.test.ts +++ b/packages/services/service-datasource/src/__tests__/datasource-connection-service.test.ts @@ -45,7 +45,7 @@ function fakeEngine() { registerDatasourceDef: (def) => { defs.push(def); }, - // [#12010] The double deliberately stores MINIMAL stand-ins (a bare + // [commit 77b91bdb4] The double deliberately stores MINIMAL stand-ins (a bare // `{ name }` is how these tests simulate an `onEnable`-registered // driver), while the derived seam member answers the contract's // `IDataDriver | undefined`. Narrowing on the way out keeps the double diff --git a/packages/services/service-datasource/src/__tests__/datasource-pool-support.test.ts b/packages/services/service-datasource/src/__tests__/datasource-pool-support.test.ts index f4e84f031a5..5d3aaf41fa8 100644 --- a/packages/services/service-datasource/src/__tests__/datasource-pool-support.test.ts +++ b/packages/services/service-datasource/src/__tests__/datasource-pool-support.test.ts @@ -162,7 +162,7 @@ describe('#5714 — which driver arms read a declared `pool`', () => { // literal as it stood on `origin/main` before this change, because "we only // added an arm" is a claim about bytes. // Byte-for-byte as #5714 wrote it, with ONE word changed: the closing clause - // names the pooled drivers, and #6345 renamed the canonical mongo id to + // names the pooled drivers, and commit e2798fab7 renamed the canonical mongo id to // `mongodb`. Naming the retired canon in an instruction the author is meant to // act on would send them to a spelling the catalog no longer publishes. it('leaves the sqlite arms\' message byte-for-byte as #5714 wrote it', () => { @@ -305,7 +305,7 @@ function fakeEngine() { drivers, registerDriver: (driver: any) => { drivers.set(driver.name, driver); }, registerDatasourceDef: () => {}, - // [#12010] The double deliberately stores MINIMAL stand-ins (a bare + // [commit 77b91bdb4] The double deliberately stores MINIMAL stand-ins (a bare // `{ name }` is how these tests simulate an `onEnable`-registered // driver), while the derived seam member answers the contract's // `IDataDriver | undefined`. Narrowing on the way out keeps the double diff --git a/packages/services/service-datasource/src/__tests__/default-datasource-driver-factory.test.ts b/packages/services/service-datasource/src/__tests__/default-datasource-driver-factory.test.ts index 2bd67b0dfad..184ca635d2e 100644 --- a/packages/services/service-datasource/src/__tests__/default-datasource-driver-factory.test.ts +++ b/packages/services/service-datasource/src/__tests__/default-datasource-driver-factory.test.ts @@ -371,7 +371,7 @@ describe('createDefaultDatasourceDriverFactory — legacy config spellings are n // #7314 — the OPTIONAL libSQL driver is missing, and until now this arm said so // and stopped: `turso driver requested but @objectstack/driver-turso is not // installed (…)`. The HOST loader (`@objectstack/runtime`'s -// `loadTursoDriverFactory`, single owner since #6268) has answered the same +// `loadTursoDriverFactory`, single owner since commit 68f5eccb1) has answered the same // missing package with the install command, the consequence and the reason for // refusing since #5602 — so the SAME fault got two qualities of answer depending // on whether the datasource happened to be the host's `default` (told how to fix @@ -437,7 +437,7 @@ describe('createDefaultDatasourceDriverFactory — the missing libSQL package is }); it('is what the turso arm actually raises when the optional package is absent', async () => { - // ⭐ STAGED absence since #12943 — this case used to reach the arm with NO + // ⭐ STAGED absence since commit 090f2302e — this case used to reach the arm with NO // stub, and that is no longer possible. `@objectstack/driver-turso` is now // an OPTIONAL PEER of `@objectstack/service-datasource` // (`peerDependencies` + `peerDependenciesMeta.optional`): the honest diff --git a/packages/services/service-datasource/src/__tests__/driver-catalog.test.ts b/packages/services/service-datasource/src/__tests__/driver-catalog.test.ts index 576d0b6920a..db7d4acf2a8 100644 --- a/packages/services/service-datasource/src/__tests__/driver-catalog.test.ts +++ b/packages/services/service-datasource/src/__tests__/driver-catalog.test.ts @@ -46,7 +46,7 @@ describe('DRIVER_CATALOG', () => { expect(entry.description, entry.id).toBeTruthy(); expect(entry.icon, entry.id).toBeTruthy(); } - // `mongodb`, not `mongo`, since #6345 renamed the canonical driver id. This + // `mongodb`, not `mongo`, since commit e2798fab7 renamed the canonical driver id. This // list is the PUBLISHED contract Studio writes into `datasource.driver`, so // the assertion is the one that has to move with the rename — stored rows // carrying `mongo` are converged by the ADR-0087 conversion diff --git a/packages/services/service-datasource/src/__tests__/external-datasource-service.test.ts b/packages/services/service-datasource/src/__tests__/external-datasource-service.test.ts index 9d9122ff607..0fde8164a29 100644 --- a/packages/services/service-datasource/src/__tests__/external-datasource-service.test.ts +++ b/packages/services/service-datasource/src/__tests__/external-datasource-service.test.ts @@ -441,7 +441,7 @@ describe('validateAll', () => { }); /** - * [#11166] The card's measured defect, reproduced: an introspector throwing + * [commit 735f5c709] Its card's measured defect, reproduced: an introspector throwing * `connect ECONNREFUSED 10.0.0.5:5432` used to come back as * `kind: 'missing_table'` — indistinguishable from a genuinely dropped * table, and an abort under the boot gate's default `onMismatch: 'fail'`. @@ -490,7 +490,7 @@ describe('validateAll', () => { }); /** - * [#11166] The other half of the distinction: a table genuinely absent from + * [commit 735f5c709] The other half of the distinction: a table genuinely absent from * a schema that WAS read stays `missing_table` — the classification change * must not blur the measured fact into the indeterminate kind. */ @@ -514,7 +514,7 @@ describe('validateAll', () => { }); /** - * [#10537] `validateDatasource` — the same sweep, scoped to one datasource. + * [commit e634ecf6a] `validateDatasource` — the same sweep, scoped to one datasource. * * The card it closes is a COST/SHAPE defect, not a wrong answer: * `POST /datasources/:name/external/validate` used to run `validateAll()` and @@ -585,7 +585,7 @@ describe('validateDatasource', () => { return { svc, introspected }; } - /** What the pre-#10537 route computed: the whole sweep, filtered afterwards. */ + /** What the route computed before commit e634ecf6a: the whole sweep, filtered afterwards. */ async function sweptThenFiltered(datasource: string, opts?: { unreachable?: readonly string[] }) { const { svc, introspected } = makeMulti(opts); const report = await svc.validateAll(); @@ -649,7 +649,7 @@ describe('validateDatasource', () => { // The scoped path still turns a per-object throw into a row rather than // rejecting the whole report — the sweep's `catch`, not a second one. - // [#11166] The row's kind is `unreachable` (the fixture's introspector + // [commit 735f5c709] The row's kind is `unreachable` (the fixture's introspector // threw a connection error), no longer the invented `missing_table`. expect(introspected).toEqual(['wh_b']); expect(report.ok).toBe(false); @@ -673,7 +673,7 @@ describe('validateDatasource', () => { }); /** - * [#10962] Per-sweep introspection memo — the CALL COUNT is the deliverable. + * [commit 29d067646] Per-sweep introspection memo — the CALL COUNT is the deliverable. * * `validateObject` reads the live remote schema on every call, so a sweep over * M federated objects on one datasource used to perform M concurrent @@ -810,7 +810,7 @@ describe('per-sweep introspection memo [#10962]', () => { datasource: M_DATASOURCE, diffs: [ expect.objectContaining({ - // [#11166] A throw out of introspect is `unreachable`, never an + // [commit 735f5c709] A throw out of introspect is `unreachable`, never an // invented `missing_table` — this pin is about the COUNT (one // shared connection attempt), and rides the kind ruling as-is. kind: 'unreachable', diff --git a/packages/services/service-datasource/src/__tests__/mysql-dsn-ssl.test.ts b/packages/services/service-datasource/src/__tests__/mysql-dsn-ssl.test.ts index c501a6106d2..2feeaeb0411 100644 --- a/packages/services/service-datasource/src/__tests__/mysql-dsn-ssl.test.ts +++ b/packages/services/service-datasource/src/__tests__/mysql-dsn-ssl.test.ts @@ -1,7 +1,7 @@ // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license. /** - * #8874 — a declared `ssl` reaches the mysql CLIENT on both branches of the + * Commit d70428ae7 — a declared `ssl` reaches the mysql CLIENT on both branches of the * mysql arm, in the spelling mysql2 can actually read. * * ## The defect, in two halves @@ -37,7 +37,7 @@ * {uri:'mysql://app@db.internal:3306/app', ssl:{}} -> ssl {rejectUnauthorized:true} * ``` * - * The branch #8874 describes as "honouring" the declaration was therefore + * The branch commit d70428ae7's card describes as "honouring" the declaration was therefore * throwing on every connection acquisition for the commonest way of declaring * it. Emitting `ssl: true` onto the DSN branch to close the first half would * have shipped that throw to a second branch, so `mysqlSslOption` translates @@ -50,7 +50,7 @@ * the mysql2 module knex itself resolved (`knex.client.driver`), fed the exact * `connectionSettings` knex will hand it. Nothing asserts on the `connection` * object this factory emitted, and that is deliberate: it is the constraint - * inherited from #8873, where the postgres arm passed the equivalent + * inherited from commit 096106522, where the postgres arm passed the equivalent * config-layer assertion throughout the defect's entire life while the client * threw the value away one layer below. Here it is the sharper of the two * lessons, because the boolean half of this card is invisible at the config @@ -186,7 +186,7 @@ describe('#8874 — mysql: a declared `ssl` reaches the client on the DSN branch }); it('carries TLS and a bound secret together on the DSN branch', async () => { - // The other DSN sub-case. #8696 made this branch return `{ uri, password }` + // The other DSN sub-case. Commit 72050cc47 made this branch return `{ uri, password }` // and deliberately left `ssl` out of it, because carrying TLS only for // datasources that happen to bind a credential would have been a second, // stranger asymmetry. Both channels now ride together. @@ -260,7 +260,7 @@ describe('#8874 — mysql: a declared `ssl` reaches the client on the DSN branch it('leaves a DSN with only a secret bound as the #8696 shape (control)', async () => { // Green before this change and after it. The `ssl` key must not appear on a // connection that declared none — otherwise this card would have widened - // #8696's blast radius rather than added to it. + // commit 72050cc47's blast radius rather than added to it. const conn = await emittedConnection({ name: 'secret-only', config: { url: BARE_USERNAME_DSN }, diff --git a/packages/services/service-datasource/src/__tests__/postgres-dsn-bound-secret.test.ts b/packages/services/service-datasource/src/__tests__/postgres-dsn-bound-secret.test.ts index 939ebd11e0e..ed3f1a30fe5 100644 --- a/packages/services/service-datasource/src/__tests__/postgres-dsn-bound-secret.test.ts +++ b/packages/services/service-datasource/src/__tests__/postgres-dsn-bound-secret.test.ts @@ -1,7 +1,7 @@ // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license. /** - * #8873 — a bound `external.credentialsRef` reaches the SERVER on the postgres + * Commit 096106522 — a bound `external.credentialsRef` reaches the SERVER on the postgres * arm's DSN branch, not merely the knex config. * * ## The defect, and why it survived a passing sibling pin @@ -220,7 +220,7 @@ describe('#8873 — postgres: a bound secret reaches the CLIENT on the DSN branc // password only when the server asks for one — so injecting cannot break a // datasource that connects today, and refusing would silently drop a // credential the operator bound. Making the contradictory pair loud belongs - // at the authoring door (#9041), which this card lands before. + // at the authoring door (commit d491625c1), which landed after this pin. const resolved = await pgResolved({ name: 'anonymous-url', config: { url: 'postgresql://db.internal:5432/app' }, diff --git a/packages/services/service-datasource/src/__tests__/prebuilt-driver-factory.test.ts b/packages/services/service-datasource/src/__tests__/prebuilt-driver-factory.test.ts index 976be478c05..93d87347813 100644 --- a/packages/services/service-datasource/src/__tests__/prebuilt-driver-factory.test.ts +++ b/packages/services/service-datasource/src/__tests__/prebuilt-driver-factory.test.ts @@ -92,7 +92,7 @@ describe('createPrebuiltDriverFactory — through DatasourceConnectionService (t drivers.set(d.name, d); if (isDefault) defaultName = d.name; }, - // [#12010] The double deliberately stores MINIMAL stand-ins (a bare + // [commit 77b91bdb4] The double deliberately stores MINIMAL stand-ins (a bare // `{ name }` is how these tests simulate an `onEnable`-registered // driver), while the derived seam member answers the contract's // `IDataDriver | undefined`. Narrowing on the way out keeps the double diff --git a/packages/services/service-datasource/src/admin-routes.ts b/packages/services/service-datasource/src/admin-routes.ts index c06f05ff1e9..c14e7b565d3 100644 --- a/packages/services/service-datasource/src/admin-routes.ts +++ b/packages/services/service-datasource/src/admin-routes.ts @@ -412,7 +412,7 @@ export function registerDatasourceAdminRoutes( * The throw is raised inside `requireDatasourceAdmin`'s own `try`, so it * takes the relay that block already runs for the identical fault one seam * over: `isAuthzStoreUnavailableError(err)` re-raises it rather than - * laundering an outage into a denial (#13279). Deliberately NOT a new relay. + * laundering an outage into a denial (commit 6a180e42d). Deliberately NOT a new relay. * * ## Why `getServiceAsync`, and why its ABSENCE is quiet * @@ -487,7 +487,7 @@ export function registerDatasourceAdminRoutes( systemPermissions = Array.isArray(authz.systemPermissions) ? authz.systemPermissions : []; } } catch (err) { - // [#13279] "grants that could not be READ are not grants" was the exact + // [commit 6a180e42d] "grants that could not be READ are not grants" was the exact // reasoning the 2026-08-30 ruling reverses: an unreadable store licenses // no verdict at all, so the outage is re-raised instead of being answered // as a denial. Every other fault still fails closed, unchanged. diff --git a/packages/services/service-datasource/src/datasource-connection-service.ts b/packages/services/service-datasource/src/datasource-connection-service.ts index c9590bb83a7..7e50dc8f65e 100644 --- a/packages/services/service-datasource/src/datasource-connection-service.ts +++ b/packages/services/service-datasource/src/datasource-connection-service.ts @@ -92,13 +92,13 @@ export interface DatasourceBoundObject { * #4251 B3 sweep pattern, applied here exactly as `datasource-admin-plugin.ts` * applied it to its own `DataEngineLike` one file over, under #11493's ruling. * - * [#12010] Every member was hand-written here until this change, and the - * inventory that filed that card measured what it cost. Three of them — + * [commit 77b91bdb4] Every member was hand-written here until this change, and the + * inventory that filed its card measured what it cost. Three of them — * `registerDatasourceDef`, `markDatasourceUnavailable`, * `clearDatasourceUnavailable` — were declared by NO contract at all: real * `ObjectQL` methods, called across a package boundary, meeting no compiler on - * the producer side, so drift landed silently in this consumer. #12248 - * adjudicated all three onto {@link IDataEngine} and #12482 followed with + * the producer side, so drift landed silently in this consumer. Commit 8425c17cc + * adopted all three onto {@link IDataEngine} per the ruling, and #12482 followed with * `syncObjectSchema`; deriving is what makes the next drift a build error here * instead of a re-declaration that quietly disagrees. * @@ -606,7 +606,7 @@ export class DatasourceConnectionService { // `default` goes through the engine's default-driver fallback, never // `drivers.get('default')`, and the natural name keeps logs/lookups // byte-for-byte with the pre-#3826 boot. - // [#12010] `DatasourceDriverHandle.driver` is declared `unknown` — the + // [commit 77b91bdb4] `DatasourceDriverHandle.driver` is declared `unknown` — the // factory escape hatch is open to any host-built driver — so a cast is // unavoidable somewhere on this path. It belongs HERE, at the one call // site that constructs the value, not widened into the exported seam @@ -697,7 +697,7 @@ export class DatasourceConnectionService { async disconnect(name: string, opts: { asDefault?: boolean } = {}): Promise { const engine = this.cfg.engine(); const driverName = opts.asDefault ? engine?.getDefaultDriverName?.() : name; - // [#12010] Cast-free: `getDriverByName` now answers the contract's + // [commit 77b91bdb4] Cast-free: `getDriverByName` now answers the contract's // `IDataDriver | undefined` instead of a locally re-declared `unknown`. // The `typeof … === 'function'` guard below stays — a host-built driver in // the registry satisfies the contract only structurally. diff --git a/packages/services/service-datasource/src/datasource-credential-migration.ts b/packages/services/service-datasource/src/datasource-credential-migration.ts index 505a95835db..002f389c5ad 100644 --- a/packages/services/service-datasource/src/datasource-credential-migration.ts +++ b/packages/services/service-datasource/src/datasource-credential-migration.ts @@ -172,14 +172,14 @@ export function planCredentialMigration(record: StoredDatasource): CredentialMig const config = record.config; - // The passthrough spelling (#9040): a stored `options.auth.password` (or a + // The passthrough spelling (commit 24206416a): a stored `options.auth.password` (or a // legacy row's equivalent) is a LIVE login credential — measured, the client // resolves the block into `MongoCredentials` — that this action cannot // re-home mechanically: dropping the nested leaf would leave an `auth` block // with only a username, which the client refuses at construction // (`credentials must be an object with 'username' and 'password' // properties`, measured on mongodb@7.5.0), and the DSN branch injects a - // bound secret only through a URL that already names a user (#8696). Refused + // bound secret only through a URL that already names a user (commit 90a12fb18). Refused // with the per-row remedy, exactly like the URL spellings below. const passthroughKeys = refusedPassthroughSecretPaths(record.driver) .filter((path) => { diff --git a/packages/services/service-datasource/src/datasource-pool-support.ts b/packages/services/service-datasource/src/datasource-pool-support.ts index b56ea3fe90c..7f051ebd7c6 100644 --- a/packages/services/service-datasource/src/datasource-pool-support.ts +++ b/packages/services/service-datasource/src/datasource-pool-support.ts @@ -129,7 +129,7 @@ export type PoolUnsupportedDriverId = (typeof POOL_UNSUPPORTED_DRIVER_IDS)[numbe * every declared key lands. * * `turso` answered `true` until #7243, first via the unknown-id branch and, - * after #6345 made it a builtin, via "not in the rejected set" — both wrong the + * after commit e2798fab7 made it a builtin, via "not in the rejected set" — both wrong the * same way: the arm never reads `spec.pool`. The 2026-08-11 ruling folds it in * whole-arm, so this now answers `false` for every spelling of it. */ diff --git a/packages/services/service-datasource/src/default-datasource-driver-factory.ts b/packages/services/service-datasource/src/default-datasource-driver-factory.ts index 5efad54874d..8c164aa6178 100644 --- a/packages/services/service-datasource/src/default-datasource-driver-factory.ts +++ b/packages/services/service-datasource/src/default-datasource-driver-factory.ts @@ -31,7 +31,7 @@ * Anything else returns `supports() === false`, so the admin service degrades * gracefully (testConnection → `{ ok: false }`, create skips hot pool reg). * - * `turso` joined in #6345, and it HAD to: `supports()` is + * `turso` joined in commit e2798fab7, and it HAD to: `supports()` is * `resolveKind() !== undefined`, so the moment turso became a builtin id this * factory started claiming it. Without an arm the claim would have been answered * by the trailing `memory` fall-through — a libSQL datasource silently built as @@ -99,7 +99,7 @@ export const TURSO_DRIVER_INSTALL_COMMAND = `npm install ${TURSO_DRIVER_PACKAGE} * Until #7314 this arm said only *"turso driver requested but * @objectstack/driver-turso is not installed (…)"* — the fault and nothing * else. The host loader (`@objectstack/runtime`'s `loadTursoDriverFactory`, - * single owner since #6268) has answered the SAME missing package with the + * single owner since commit 68f5eccb1) has answered the SAME missing package with the * install command, the consequence and the reason for refusing since #5602, so * an operator who booted with a libSQL url was told how to fix it while an * admin who added the identical datasource in Setup was not. One missing @@ -224,7 +224,7 @@ function missingDriverPackageMessage( * command an operator runs to install it. * * Optional from THIS package's side, which is the side that matters here: - * `@objectstack/service-datasource` declares it as an OPTIONAL PEER (#12943) — + * `@objectstack/service-datasource` declares it as an OPTIONAL PEER (commit 090f2302e) — * which tells an installing consumer the relationship exists while installing * nothing — alongside the `devDependencies` entry this package's own suites * build real drivers from. So a host that installs this service on its own does @@ -245,7 +245,7 @@ export const SQLITE_WASM_DRIVER_INSTALL_COMMAND = `npm install ${SQLITE_WASM_DRI * The optional package that provides the MongoDB driver, and the exact command * an operator runs to install it. * - * `@objectstack/service-datasource` declares it as an OPTIONAL PEER (#12943) + * `@objectstack/service-datasource` declares it as an OPTIONAL PEER (commit 090f2302e) * beside its `devDependencies` entry, and `@objectstack/runtime` carries it as * an `optionalDependencies` entry — two different optional idioms, and neither * installs it for a consumer of THIS package — so `--omit=optional` and a direct @@ -380,7 +380,7 @@ function resolveSslOption(spec: DatasourceConnectionSpec): unknown { } /** - * {@link resolveSslOption}'s answer in the spelling `mysql2` accepts (#8874). + * {@link resolveSslOption}'s answer in the spelling `mysql2` accepts (commit d70428ae7). * * ## `ssl: true` is not a mysql2 value — it throws * @@ -409,7 +409,7 @@ function resolveSslOption(spec: DatasourceConnectionSpec): unknown { * declarations — `ssl: { enabled: true }` with no certificate material, and the * `config.ssl` shorthand, whose schema (`DriverSslToggleSchema`) is * `z.boolean()` and so has no other authorable value. So the mysql arm's - * DISCRETE-FIELDS branch — the one #8874 describes as honouring the + * DISCRETE-FIELDS branch — the one commit d70428ae7's card describes as honouring the * declaration — has been handing `mysql2` a value that makes every connection * acquisition throw. That is the same declared-≠-enforced defect as the dropped * DSN-branch block, one spelling further along, and it is fixed here rather @@ -436,7 +436,7 @@ function mysqlSslOption(resolved: unknown): unknown { /** * What this factory says when `pg`'s own parser rejects a postgres DSN that - * carries a bound credential (#8873). + * carries a bound credential (commit 096106522). * * Reached only on the secret-bound path, and only for a url `pg` itself cannot * read: {@link postgresDsnFields} runs the client's own parser, so anything it @@ -514,12 +514,12 @@ function buildSqlConnection(spec: DatasourceConnectionSpec, client: 'pg' | 'bett }; // Nothing bound: byte-for-byte the shape this arm has always emitted. The - // blast radius of #8873 is "a secret was bound", so a datasource that binds + // blast radius of commit 096106522 is "a secret was bound", so a datasource that binds // none must not change at all — including keeping the DSN unparsed here, so // a url `pg` rejects still fails where it fails today. if (!spec.secret) return { connectionString: url, ...siblings }; - // A bound secret, on the DSN branch (#8873). + // A bound secret, on the DSN branch (commit 096106522). // // ## Why `connectionString` is gone rather than accompanied // @@ -596,7 +596,7 @@ function buildSqlConnection(spec: DatasourceConnectionSpec, client: 'pg' | 'bett // a password only when the server asks for one — so injecting cannot break // a datasource that connects today, and refusing would drop a credential the // operator bound. Making that contradictory pair loud belongs at the - // authoring door, where both halves are visible at once (#9041). + // authoring door, where both halves are visible at once (commit d491625c1). return { ...siblings, ...postgresDsnFields(url, spec.name), @@ -715,7 +715,7 @@ function buildSqlPool(spec: DatasourceConnectionSpec): Record { * (`url`) selects the connection-string form; otherwise discrete fields, with * the secret as the password (never part of `config`). * - * ## A bound secret reaches the client on the DSN branch too (#8696) + * ## A bound secret reaches the client on the DSN branch too (commit 72050cc47) * * This arm used to be `if (url) return url;` — the DSN string became the whole * knex `connection` and an injected `spec.secret` was dropped on the floor, @@ -733,7 +733,7 @@ function buildSqlPool(spec: DatasourceConnectionSpec): Record { * * `mysql2` merges a `uri` with sibling keys itself, and the EXPLICIT key wins * (`ConnectionConfig`: uri-derived values are only filled in for keys the - * caller supplied no TRUTHY value for — see the falsy-value note under #8874 + * caller supplied no TRUTHY value for — see the falsy-value note under commit d70428ae7 * below, which matters for `ssl` and not for a bound secret). So the DSN keeps * being parsed by the client that * owns its grammar — no URL parsing, no re-encoding, no second dialect of @@ -758,13 +758,13 @@ function buildSqlPool(spec: DatasourceConnectionSpec): Record { * `Object.assign({}, config, parse(config.connectionString))`, i.e. the DSN * overrides the explicit key — so `{connectionString, password}` there resolves * to the DSN's own (absent) password. That was a live defect for as long as this - * comment described it as one; #8873 closed it by dropping `connectionString` + * comment described it as one; commit 096106522 closed it by dropping `connectionString` * entirely on that branch and handing `pg` its own parse of the url with the * credential attached. It was NOT fixed by symmetry with this arm, and the two * clients disagreeing is exactly why each arm's precedence is measured rather * than assumed. * - * ## A declared `ssl` reaches the client on the DSN branch too (#8874) + * ## A declared `ssl` reaches the client on the DSN branch too (commit d70428ae7) * * The gap the paragraph above used to describe as "filed separately". This arm * resolved the TLS option and then returned before anything could use it, so a @@ -821,9 +821,9 @@ function buildMysqlConnection(spec: DatasourceConnectionSpec): unknown { const url = cfg.url as string | undefined; if (url) { // Nothing to carry beside the DSN: the bare-string passthrough this arm has - // always emitted, unchanged. The blast radius of both #8696 and #8874 is - // "something was declared", so a datasource that declared neither a secret - // nor TLS must not move at all. + // always emitted, unchanged. The blast radius of both commit 72050cc47 and + // commit d70428ae7 is "something was declared", so a datasource that declared + // neither a secret nor TLS must not move at all. if (mysqlSsl === undefined && !spec.secret) return url; return { uri: url, @@ -923,7 +923,7 @@ function buildMemoryConfig(spec: DatasourceConnectionSpec): Record; - // #8696 — the bound secret rides into the SAME passthrough on the DSN + // Commit 90a12fb18 — the bound secret rides into the SAME passthrough on the DSN // branch (see `buildMongoAuth`), so it is merged rather than assigned: // the author's `options` keep arriving verbatim, and the injected // `auth` is spread LAST so a resolved `external.credentialsRef` wins @@ -1265,7 +1265,7 @@ export function createDefaultDatasourceDriverFactory( } if (kind === 'turso') { - // libSQL/Turso (#6345). Lazy + caught exactly like `mongodb` and + // libSQL/Turso (commit e2798fab7). Lazy + caught exactly like `mongodb` and // `sqlite-wasm` above: all three ship in optional packages, and a driver // being an optional INSTALL has never meant it lacks a contract. // @@ -1287,7 +1287,7 @@ export function createDefaultDatasourceDriverFactory( // It is now also the SAME CLASS. `MissingDriverPackageError` used to be // declared in `@objectstack/runtime`, which DEPENDS on this package, so // this arm could neither import it (dependency inversion) nor declare - // its own (the identity hazard #6268 closed — `serve.ts` decides boot + // its own (the identity hazard commit 68f5eccb1 closed — `serve.ts` decides boot // fatality with `instanceof`). #7314 moved the one class DOWN to // `missing-driver-package-error.ts` here; runtime re-exports it from its // old home, so both loaders now raise an error that satisfies the same @@ -1323,7 +1323,7 @@ export function createDefaultDatasourceDriverFactory( const url = resolveTursoUrl(spec); if (!url) { // `TursoConfigSchema.url` is required, so the authoring and wizard - // gates already refuse this. A stored row written before #6345 had no + // gates already refuse this. A stored row written before commit e2798fab7 had no // gate at all, and refusing here is the difference between a named // failure and `@libsql/client` opening something unexpected. throw new Error( @@ -1350,7 +1350,7 @@ export function createDefaultDatasourceDriverFactory( return toHandle(new InMemoryDriver(buildMemoryConfig(spec))); } - // Every `BuiltinDriverId` must have an arm above (#6345). Until then this + // Every `BuiltinDriverId` must have an arm above (commit e2798fab7). Until then this // was `memory`'s implicit position: an id the spec table knew and this // switch did not silently became an in-process store that accepted writes // and lost them. `kind` is `never` here, so adding a builtin without an diff --git a/packages/services/service-datasource/src/driver-catalog.ts b/packages/services/service-datasource/src/driver-catalog.ts index 920545a548f..69d1a3247d6 100644 --- a/packages/services/service-datasource/src/driver-catalog.ts +++ b/packages/services/service-datasource/src/driver-catalog.ts @@ -27,7 +27,7 @@ * label/description/icon. `sqlite-wasm` is deliberately absent: it is * constructible and has a config contract, but it exists for CI and * no-native-build environments rather than as something an admin picks here. - * `turso` is absent for the same reason since #6345 gave it a contract: it is a + * `turso` is absent for the same reason since commit e2798fab7 gave it a contract: it is a * full builtin now, but it additionally needs an optional package installed next * to the server, which is not a thing a dropdown can arrange. */ @@ -79,7 +79,7 @@ const CURATED: ReadonlyArray<{ icon: 'database', }, { - // `mongodb` since #6345 — the canonical driver id was renamed to the + // `mongodb` since commit e2798fab7 — the canonical driver id was renamed to the // spelling both boot hosts and `@objectstack/driver-mongodb` already used. // This `id` is what Studio writes into `datasource.driver`, so rows written // before the rename carry `mongo`; the ADR-0087 conversion diff --git a/packages/services/service-datasource/src/external-datasource-service.ts b/packages/services/service-datasource/src/external-datasource-service.ts index 5922f8abfbe..e84a6bcef5b 100644 --- a/packages/services/service-datasource/src/external-datasource-service.ts +++ b/packages/services/service-datasource/src/external-datasource-service.ts @@ -613,7 +613,7 @@ export class ExternalDatasourceService implements IExternalDatasourceService { } /** - * [#10962] The body of {@link validateObject}, with the live-schema read + * [commit 29d067646] The body of {@link validateObject}, with the live-schema read * abstracted behind `readSchema` so one sweep can share a single read per * datasource across all of its objects. `readSchema` is either * `config.introspect` itself (the public single-object path above) or the @@ -716,7 +716,7 @@ export class ExternalDatasourceService implements IExternalDatasourceService { } /** - * [#10962] One live schema read per datasource per SWEEP. + * [commit 29d067646] One live schema read per datasource per SWEEP. * * Returns a reader that memoises `config.introspect` by datasource name for * the lifetime of ONE {@link validateEach} call. The memo is a local of that @@ -751,7 +751,7 @@ export class ExternalDatasourceService implements IExternalDatasourceService { * one object whose definition vanished mid-sweep) must not erase the verdicts * of the objects that did validate. * - * [#10962] All objects in one call share one live schema read per datasource + * [commit 29d067646] All objects in one call share one live schema read per datasource * (see {@link sweepScopedIntrospect}); the memo dies with this call. * * ## Why the row's kind is `unreachable` for EVERY throw — no error sniffing @@ -770,7 +770,7 @@ export class ExternalDatasourceService implements IExternalDatasourceService { * from a successfully read schema in which the table is absent. A throw * means the comparison never ran, and per the repo's read-failure * classification precedent (`READ_FAILURE_DISCRIMINATORS`, - * `packages/types/src/driver-error-classification.ts` (#13279 moved it there + * `packages/types/src/driver-error-classification.ts` (commit 6a180e42d moved it there * from `packages/metadata/src/utils/schema-sync-errors.ts`): a fact verdict must * be POSITIVELY EARNED, never defaulted to), no signature test on the thrown * value can earn a claim about a remote schema nobody read. Deliberately NOT @@ -819,7 +819,7 @@ export class ExternalDatasourceService implements IExternalDatasourceService { } /** - * [#10537] Validate the federated objects bound to ONE datasource. + * [commit e634ecf6a] Validate the federated objects bound to ONE datasource. * * The scoped twin of {@link validateAll}, composed from the same primitives * (`listObjects` → filter → `validateObject`) so a caller that asked about diff --git a/packages/services/service-datasource/src/missing-driver-package-error.ts b/packages/services/service-datasource/src/missing-driver-package-error.ts index 54d69705c1e..89ec12a6445 100644 --- a/packages/services/service-datasource/src/missing-driver-package-error.ts +++ b/packages/services/service-datasource/src/missing-driver-package-error.ts @@ -8,7 +8,7 @@ * ## Why it lives here rather than where it was written * * It was declared in `@objectstack/runtime` - * (`turso-driver-factory.ts`) under #6268, which converged the two HOST-injected + * (`turso-driver-factory.ts`) under commit 68f5eccb1, which converged the two HOST-injected * libSQL loaders (CLI + standalone stack) onto one owner. That convergence was * complete for the hosts and could not reach the third loader: the open-core * `createDefaultDatasourceDriverFactory` in THIS package, which serves every @@ -18,7 +18,7 @@ * `@objectstack/runtime` depends on `@objectstack/service-datasource`, never the * reverse, so the open-core arm could not import the class and raised a plain * `Error` instead. The two legal ways out were "declare a second same-named - * class here" — precisely the identity hazard #6268 closed — or move the one + * class here" — precisely the identity hazard commit 68f5eccb1 closed — or move the one * class DOWN to where both sides can reach it. This is the move. `runtime` * RE-EXPORTS it from its old home, so every existing importer * (`@objectstack/runtime`, `@objectstack/cli`'s `storage-driver.ts`, and diff --git a/packages/services/service-datasource/src/turso-driver-config.ts b/packages/services/service-datasource/src/turso-driver-config.ts index 113d83dcd52..565454defd5 100644 --- a/packages/services/service-datasource/src/turso-driver-config.ts +++ b/packages/services/service-datasource/src/turso-driver-config.ts @@ -11,7 +11,7 @@ * `default`: * * - `@objectstack/runtime`'s `loadTursoDriverFactory` (the HOST-injected - * loader, single owner for the CLI and the standalone stack since #6268) + * loader, single owner for the CLI and the standalone stack since commit 68f5eccb1) * serves the `default` datasource; * - the open-core `createDefaultDatasourceDriverFactory` in this package serves * every other door — a datasource created in Setup, `testConnection`, a From 265dc6861ea8235e3fe5962fd814276c391a6ad2 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 29 Sep 2026 17:29:54 +0000 Subject: [PATCH 2/2] chore(changeset): patch for the service-datasource provenance comments The rewritten docblocks ship in dist (index.d.ts / index.d.cts, and the runtime bundles for the ones tsup keeps), so the released package changes bytes and owes a patch changeset. Claude-Session: https://claude.ai/code/session_01XY5uCwTjZj7884yYtyur4H Co-authored-by: Claude --- .../20596-service-datasource-provenance-anchors.md | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 .changeset/20596-service-datasource-provenance-anchors.md diff --git a/.changeset/20596-service-datasource-provenance-anchors.md b/.changeset/20596-service-datasource-provenance-anchors.md new file mode 100644 index 00000000000..519e47da701 --- /dev/null +++ b/.changeset/20596-service-datasource-provenance-anchors.md @@ -0,0 +1,10 @@ +--- +'@objectstack/service-datasource': patch +--- + +Provenance comments in `service-datasource` were re-anchored + +Comment and docblock lines under `src/` that cited tracker numbers which no +longer resolve on GitHub now cite the commit in this repository's history that +decided the matter, and say in their own words what was decided. Comments +only: no type, schema, export, log or refusal text, or runtime behaviour changes.