docs: regenerate the API reference (#8744)

Lands #8742.

Regenerates `docs/src/api/reference.md` and `docs/api/perry.d.ts` from the
compile-time manifest, clearing the release-blocking api-docs-drift check.

Verified against the source of truth rather than by rebuilding: the
manifest at `crates/perry-api-manifest/src/entries.rs` declares the `ffi`
module, and `entries/part_1.rs` carries exactly the six entries the
generated `.d.ts` now exposes -- `method("ffi", …)` for dlopen,
getRawPointer, toArrayBuffer, toBuffer and toString, plus
`property("ffi", "suffix")`. One-to-one, no extras on either side.

The disappearing `@perryStub stage ≥2 — not yet implemented, throws at
runtime (#6562)` markers are correct: #8704 implemented that surface and
closed #6562, and the remaining #6562 mentions in the manifest are
comments describing the implementation rather than stub annotations.

Coverage moves 2,059 entries / 134 modules -> 2,065 / 135.

A changelog fragment was added; the PR had neither one nor a
skip-changelog label. No version bump.

Co-authored-by: Ralph Küpper <ralph@skelpo.com>

Author: proggeramlug

changelog.d/8742-regenerate-api-reference.md

@@ -0,0 +1 @@
+Regenerated the checked-in API reference and TypeScript declarations from the compile-time manifest, picking up the `ffi` module that #8704 added and dropping the `@perryStub … (#6562)` markers from the entries it implemented. Coverage moves from 2,059 entries across 134 modules to 2,065 across 135. This clears the release-blocking api-docs-drift check.

docs/api/perry.d.ts

@@ -1,6 +1,6 @@
 // Auto-generated from Perry's API manifest (#465). Do not edit by hand.
 // Source: perry-api-manifest::API_MANIFEST
-// Coverage: 2059 entries across 134 modules
+// Coverage: 2065 entries across 135 modules
 
 type PerryI8 = number & { readonly __perryI8?: never };
 type PerryI16 = number & { readonly __perryI16?: never };
@@ -370,26 +370,26 @@ declare module "bun:ffi" {
   /** stdlib */
   export const FFIType: any;
   /** stdlib */
+  export const read: any;
+  /** stdlib */
   export const suffix: any;
-  /** stdlib @perryStub stage 3 — not yet implemented, throws at runtime (#6562) */
+  /** stdlib */
   export function CFunction(...args: any[]): any;
   /** stdlib */
   export function CString(...args: any[]): any;
   /** stdlib */
   export function JSCallback(...args: any[]): any;
   /** stdlib */
   export function dlopen(...args: any[]): any;
-  /** stdlib @perryStub stage ≥2 — not yet implemented, throws at runtime (#6562) */
+  /** stdlib */
   export function linkSymbols(...args: any[]): any;
   /** stdlib */
   export function ptr(...args: any[]): any;
-  /** stdlib @perryStub stage ≥2 — not yet implemented, throws at runtime (#6562) */
-  export function read(...args: any[]): any;
   /** stdlib */
   export function toArrayBuffer(...args: any[]): any;
   /** stdlib */
   export function toBuffer(...args: any[]): any;
-  /** stdlib @perryStub stage ≥2 — not yet implemented, throws at runtime (#6562) */
+  /** stdlib */
   export function viewSource(...args: any[]): any;
 }
 
@@ -1585,6 +1585,21 @@ declare module "fetch" {
   export default function (...args: any[]): any;
 }
 
+declare module "ffi" {
+  /** stdlib */
+  export const suffix: any;
+  /** stdlib */
+  export function dlopen(...args: any[]): any;
+  /** stdlib */
+  export function getRawPointer(...args: any[]): any;
+  /** stdlib */
+  export function toArrayBuffer(...args: any[]): any;
+  /** stdlib */
+  export function toBuffer(...args: any[]): any;
+  /** stdlib */
+  export function toString(...args: any[]): any;
+}
+
 declare module "fs" {
   /** stdlib */
   export class Dir { [key: string]: any; }

docs/src/api/reference.md

@@ -2,7 +2,7 @@
 
 This page is auto-generated from Perry's compile-time API manifest (`perry-api-manifest::API_MANIFEST`). It is the source of truth for what `perry compile` accepts; references to symbols not listed here produce `R005 UnimplementedApi` (issue #463). Stubs (#464) are flagged ⚠ — they link cleanly but no-op at runtime on the chosen target.
 
-Total: 3009 entries across 136 modules.
+Total: 3015 entries across 137 modules.
 
 ## Modules
 
@@ -52,6 +52,7 @@ Total: 3009 entries across 136 modules.
 - [`exponential-backoff`](#exponential-backoff)
 - [`fastify`](#fastify)
 - [`fetch`](#fetch)
+- [`ffi`](#ffi)
 - [`fs`](#fs)
 - [`fs/promises`](#fspromises)
 - [`http`](#http)
@@ -437,20 +438,20 @@ Total: 3009 entries across 136 modules.
 
 ### Methods
 
-- `CFunction` — module ⚠ **stub** — stage 3 — not yet implemented, throws at runtime (#6562)
+- `CFunction` — module
 - `CString` — module
 - `JSCallback` — module
 - `dlopen` — module
-- `linkSymbols` — module ⚠ **stub** — stage ≥2 — not yet implemented, throws at runtime (#6562)
+- `linkSymbols` — module
 - `ptr` — module
-- `read` — module ⚠ **stub** — stage ≥2 — not yet implemented, throws at runtime (#6562)
 - `toArrayBuffer` — module
 - `toBuffer` — module
-- `viewSource` — module ⚠ **stub** — stage ≥2 — not yet implemented, throws at runtime (#6562)
+- `viewSource` — module
 
 ### Properties
 
 - `FFIType`
+- `read`
 - `suffix`
 
 ## `bun:sqlite`
@@ -1426,6 +1427,20 @@ Total: 3009 entries across 136 modules.
 
 - `default` — module
 
+## `ffi`
+
+### Methods
+
+- `dlopen` — module
+- `getRawPointer` — module
+- `toArrayBuffer` — module
+- `toBuffer` — module
+- `toString` — module
+
+### Properties
+
+- `suffix`
+
 ## `fs`
 
 ### Classes