fix(spec): close the ctx.api nameability chain completely — four names, not three

Measured, not reasoned: exporting `IScopedContext` alone is a HALF closure,
because `IScopedContext.object(name)` returns `IScopedObjectRepository` and a
consumer writing `ctx.api.object('deal')` still answered TS2883 on that fourth
name. With all four, a probe covering both `transaction` arguments, `ctx.api`,
`ctx.api.object(...)`, `api.object(...)` and a repository read emits at exit 0
and every inferred type in the emitted declarations resolves through
`@objectstack/spec/data`. The chain terminates there — the repository's members
answer in structural types that name nothing further.

Claude-Session: https://claude.ai/code/session_01AmH9bKvGoLjiY86Q4Z3og2
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

.changeset/18163-export-hook-api-types.md

@@ -2,7 +2,7 @@
 '@objectstack/spec': minor
 ---
 
-`@objectstack/spec/data` now exports the typed hook `ctx.api` face — `HookApi`, `HookObjectApi`, `HookQuery`, `HookCountQuery`, `HookUpdateDoc`, `HookUpdateOptions`, `HookDeleteOptions`, `HookDoc` and `HookDriverPassthroughOptions` — so a metadata app's `*.hook.ts` imports the platform's type instead of hand-declaring one (#18163). The same entry additionally re-exports `EngineTransactionInfo`, `EngineTransactionOptions` and `IScopedContext`, which its public declarations reference structurally: without them a consumer that imports only `@objectstack/spec/data` and emits declarations answers `TS2883: The inferred type ... cannot be named without a reference to ...`. Type-only re-exports of the declarations `@objectstack/spec/contracts` already publishes, not second declarations.
+`@objectstack/spec/data` now exports the typed hook `ctx.api` face — `HookApi`, `HookObjectApi`, `HookQuery`, `HookCountQuery`, `HookUpdateDoc`, `HookUpdateOptions`, `HookDeleteOptions`, `HookDoc` and `HookDriverPassthroughOptions` — so a metadata app's `*.hook.ts` imports the platform's type instead of hand-declaring one (#18163). The same entry additionally re-exports `EngineTransactionInfo`, `EngineTransactionOptions`, `IScopedContext` and `IScopedObjectRepository`, which its public declarations reference structurally: without them a consumer that imports only `@objectstack/spec/data` and emits declarations answers `TS2883: The inferred type ... cannot be named without a reference to ...`. Type-only re-exports of the declarations `@objectstack/spec/contracts` already publishes, not second declarations.
 
 ```ts
 import type { HookApi } from '@objectstack/spec/data';
@@ -19,6 +19,6 @@ The platform already implemented this surface; it just never published a type an
 - **Every option shape is DERIVED, not transcribed.** Each is an `Omit`/`Pick` over the `Engine*Options` schemas that the engine's own per-method legal-key sets are pinned against, so a key added to a schema reaches the published type in the same run it reaches the engine's accepted set. `count` is the one shape without the driver pass-through keys, because the engine forwards no bag on that method and rejects them there — engine behaviour no document states, and exactly what a hand-written copy gets wrong.
 - **What is deliberately absent, each for a stated reason**: `context` (the repository injects it and discards a caller's), the `cursor` / `distinct` / `upsert` tombstones, `sudo()` (the #5945 exclusion stands — `Hook.runAs: 'system'` is the declared way to run elevated), and `aggregate` / `execute` / `create` / `deleteById`.
 
-Additive only: twelve new exported names from `./data` (nine new declarations plus three type-only re-exports), no removal and no signature change, so nothing an existing consumer imports moves.
+Additive only: thirteen new exported names from `./data` (nine new declarations plus four type-only re-exports), no removal and no signature change, so nothing an existing consumer imports moves.
 
 Clause-②: yes (widening)

packages/spec/src/data/hook-api.test.ts

@@ -60,6 +60,7 @@ import type {
   HookQuery,
   HookUpdateOptions,
   IScopedContext as ReExportedScopedContext,
+  IScopedObjectRepository as ReExportedScopedRepository,
 } from './hook-api';
 import type { IScopedContext, IScopedObjectRepository } from '../contracts/scoped-context';
 
@@ -190,15 +191,19 @@ describe('HookApi — the published hook ctx.api face', () => {
     // `@objectstack/spec/data` and emitting declarations answers TS2883 without
     // them, and `check:entry-nameability` cannot see it (it probes the call
     // surface of VALUE exports; `HookApi` is a type).
-    it('the transaction signature\'s two types, and the type ctx.api already carries', () => {
+    it('the transaction signature\'s two types, and the ctx.api pair', () => {
       const infoIsReachable: Assignable<EngineTransactionInfo, EngineTransactionInfo> = true;
       const optsIsReachable: Assignable<EngineTransactionOptions, EngineTransactionOptions> = true;
       // Same declaration, reached through both entries — one declaration, two
       // paths, which is what `check:dual-source-exports` asks about.
       const oneDeclaration: Assignable<ReExportedScopedContext, IScopedContext> = true;
       const andBack: Assignable<IScopedContext, ReExportedScopedContext> = true;
-      expect([infoIsReachable, optsIsReachable, oneDeclaration, andBack]).toEqual([
-        true, true, true, true,
+      // The repository comes with it: `IScopedContext.object(name)` returns it,
+      // so exporting the context without it is a HALF closure — measured as a
+      // surviving TS2883 on `ctx.api.object(...)`.
+      const repoReachable: Assignable<ReExportedScopedRepository, IScopedObjectRepository> = true;
+      expect([infoIsReachable, optsIsReachable, oneDeclaration, andBack, repoReachable]).toEqual([
+        true, true, true, true, true,
       ]);
     });
   });

packages/spec/src/data/hook-api.ts

@@ -328,13 +328,24 @@ export interface HookApi {
  * ```
  *
  * The second position — `transaction`'s `opts` — answers the same way for
- * `EngineTransactionOptions`, and `HookContext.api` has answered it for
- * `IScopedContext` since #5945, which is why that third name is here too: it is
- * the SAME defect in the SAME entry, its remedy is this same one-line form, it
- * lands in this file rather than in any file another card holds, and it adds no
- * gate beyond the three this diff already regenerates. Leaving it would publish
- * a hook seam that still cannot be written from one entry — the exact gap this
- * card was opened to close.
+ * `EngineTransactionOptions`. Those two are the blocking finding.
+ *
+ * The other two names close the SAME defect one frame out, and they come as a
+ * PAIR because that is what the measurement said. `HookContext.api` has leaked
+ * `IScopedContext` since #5945, and exporting that name alone is a HALF
+ * closure: `IScopedContext.object(name)` returns `IScopedObjectRepository`, so
+ * with three names `(ctx) => ctx.api!.object('deal')` still answered TS2883 on
+ * that fourth name. With all four, a probe carrying every position — both
+ * `transaction` arguments, `ctx.api`, `ctx.api.object(…)`, `api.object(…)` and
+ * a repository read — emits at exit 0, and the emitted declarations resolve
+ * every inferred type through `@objectstack/spec/data`. The chain terminates
+ * there: the repository's own members answer in structural types
+ * (`Promise` of `Record` of `string` to `any`, or `null`) that name nothing
+ * further. Taken in one stroke because leaving it publishes a hook seam whose
+ * own `ctx.api` cannot be named from the entry that publishes the seam — the
+ * exact gap this card was opened to close — and because all four are one-line
+ * re-exports in this file, of declarations `@objectstack/spec/contracts`
+ * already publishes, adding no gate beyond the three this diff regenerates.
  *
  * ⛔ `check:entry-nameability` is NOT the instrument that answers this. By its
  * own docblock it probes the CALL surface of VALUE exports that have a call
@@ -344,9 +355,9 @@ export interface HookApi {
  * are a known target outside it. The instrument that answers is a consumer
  * program with `declaration` emit, which is what the excerpt above is.
  *
- * Type-only re-exports: they add three names to this entry and no runtime byte,
+ * Type-only re-exports: they add four names to this entry and no runtime byte,
  * and each is ONE declaration reachable from two entries rather than two
  * declarations sharing a name, which is what `check:dual-source-exports` asks.
  */
 export type { EngineTransactionInfo, EngineTransactionOptions } from '../contracts/objectql-engine';
-export type { IScopedContext } from '../contracts/scoped-context';
+export type { IScopedContext, IScopedObjectRepository } from '../contracts/scoped-context';