quest: plan moq-net API audit follow-ups and retire the public-model goal

.github/justfile

@@ -51,7 +51,6 @@ test:
     python3 sh/js/workspace.test.py
     python3 sh/js/audit.test.py
     python3 sh/rs/test-lints.test.py
-    python3 sh/rs/model-markers.test.py
     python3 sh/gh/nightly.test.py
     python3 sh/gh/pages-clean.test.py
     python3 sh/gh/bench-report.test.py

js/net/src/announced.ts

@@ -42,7 +42,6 @@ export interface Announce {
  */
 export type Event = { kind: "start" | "update" | "restart" | "end" } & Announce;
 
-// pending: /quest/m1/public-model/answer.md
 /**
  * Options for an announcement stream.
  *
@@ -89,7 +88,6 @@ function closeState(state: AnnounceState, abort?: Error) {
 	state.synced.set(true);
 }
 
-// pending: /quest/m1/public-model/answer.md
 /**
  * The write side of an announcement stream.
  *
@@ -119,7 +117,6 @@ export class Producer {
 		});
 	}
 
-	// pending: /quest/m1/public-model/answer.md
 	/**
 	 * Marks the initial set as delivered: the stream syncs once the reader has taken
 	 * everything queued so far. A no-op until {@link behind} once marked.
@@ -133,7 +130,6 @@ export class Producer {
 		settle(state);
 	}
 
-	// pending: /quest/m1/public-model/answer.md
 	/**
 	 * Takes sync back until the next {@link synced}, as when another initial set starts.
 	 *

js/net/src/auth_gate.ts

@@ -2,7 +2,6 @@ import type { Dispose, Getter } from "@moq/signals";
 import type { Grant } from "./auth.ts";
 import type * as Path from "./path.ts";
 
-// private: plumbing
 /** Whether our grant still lets us serve one incoming request, built when it is dispatched. @internal */
 export class Gate {
 	#grant?: Getter<Grant | undefined>;

js/net/src/consume.ts

@@ -31,7 +31,6 @@ class Blind implements Selection {
 	readonly validity = new Validity();
 }
 
-// private: plumbing
 /** Consumed broadcasts shared only within the selected serving instance. @internal */
 export class BroadcastCache {
 	#cache = new Map<Path.Valid, Map<Epoch.Valid | object, { consumer: broadcast.Consumer; selection: Selection }>>();

js/net/src/group.ts

@@ -270,7 +270,6 @@ export class Producer {
 		return makeConsumer(this.#state);
 	}
 
-	// pending: /quest/m1/public-model/deferred.md
 	/**
 	 * Create an independent read handle that receives every frame written here.
 	 *

js/net/src/hop.ts

@@ -11,7 +11,6 @@ import * as z from "zod/mini";
 import type { Auth } from "./auth.ts";
 import type * as Epoch from "./epoch.ts";
 
-// pending: /quest/m1/public-model/answer.md
 /**
  * One relay's identity in a broadcast's hop chain, encoded as a 62-bit varint on the wire.
  *
@@ -31,7 +30,6 @@ export const HopSchema = z
 /** A relay's hop id, validated by {@link HopSchema}. */
 export type Hop = z.infer<typeof HopSchema>;
 
-// pending: /quest/m1/public-model/answer.md
 /**
  * The reserved id 0, meaning "no identity".
  *
@@ -42,7 +40,6 @@ export type Hop = z.infer<typeof HopSchema>;
  */
 export const UNKNOWN_HOP: Hop = HopSchema.parse(0n);
 
-// pending: /quest/m1/public-model/answer.md
 /**
  * Maximum length of a hop chain. Must match `MAX_HOPS` in Rust's `model/origin.rs`.
  *
@@ -51,7 +48,6 @@ export const UNKNOWN_HOP: Hop = HopSchema.parse(0n);
  */
 export const MAX_HOPS = 32;
 
-// pending: /quest/m1/public-model/answer.md
 /**
  * Generate a fresh hop with a random non-zero id.
  *
@@ -73,7 +69,6 @@ export function randomHop(): Hop {
 	return HopSchema.parse(raw === 0n ? 1n : raw);
 }
 
-// pending: /quest/m1/public-model/answer.md
 /** The static cost of pulling content through a route; lower wins. */
 export type Cost = bigint;
 
@@ -143,7 +138,6 @@ export function isAnonymous(route: Route): boolean {
 	return route.hops.includes(UNKNOWN_HOP);
 }
 
-// pending: /quest/m1/public-model/answer.md
 /** Whether two routes name the same epoch, hop chain, cost, and auth. */
 export function routesEqual(a: Route | undefined, b: Route | undefined): boolean {
 	if (a === b) return true;

js/net/src/internal.ts

@@ -19,7 +19,6 @@ import type { Timestamp } from "./time.ts";
 import type { Groups, Info, Location, Producer, Request, Subscriber, Subscription } from "./track.ts";
 import type { Advertised, Advertisements } from "./wire.ts";
 
-// private: plumbing
 /** Normalize public group bounds into an inclusive start and exclusive end. */
 export function groupBounds(groups: Groups = {}): { start: number; end?: number } {
 	const bound = (value: Groups["start"] | undefined, start: boolean): number | undefined => {
@@ -36,7 +35,6 @@ export function groupBounds(groups: Groups = {}): { start: number; end?: number
 	return { start: bound(groups.start, true) ?? 0, end: bound(groups.end, false) };
 }
 
-// pending: /quest/m1/public-model/answer.md
 /**
  * The announce-interest prefix a scope needs on a prefix-shaped wire: its literal head.
  * The peer echoes every suffix beneath it, and the caller filters what arrives.
@@ -45,7 +43,6 @@ export function scopeHead(scope: Path.Pattern): Path.Valid {
 	return Path.from(scope.head);
 }
 
-// pending: /quest/m1/public-model/answer.md
 /**
  * Whether a segment of `path` below `prefix` starts with `.`, which hides it from announce
  * discovery unless the request opts in. A path at or above the prefix never hides.
@@ -55,7 +52,6 @@ export function hiddenBelow(prefix: Path.Valid, path: Path.Valid): boolean {
 	return below !== null && Path.parts(below).some((part) => part.startsWith("."));
 }
 
-// pending: /quest/m1/public-model/answer.md
 /**
  * Where each carried route lands under the requested prefix: its suffix beneath the
  * prefix, or the empty suffix for a route above it, where the most specific such route
@@ -86,26 +82,22 @@ export function presented(
 	return out;
 }
 
-// pending: /quest/m1/public-model/answer.md
 /** Whether the announced prefix's subtree overlaps `scope`. */
 export function scopeOverlaps(scope: Path.Pattern, prefix: Path.Valid): boolean {
 	return scope.overlaps(Path.Pattern.subtree(prefix));
 }
 
-// pending: /quest/m1/public-model/answer.md
 /** What `scope` captures from an exact announced prefix, if it pins every wildcard. */
 export function scopeCaptures(scope: Path.Pattern, prefix: Path.Valid): Path.Pattern[] | undefined {
 	return scope.captures(Path.Pattern.literal(prefix));
 }
 
-// private: plumbing
 /** A half-open run of group sequences, `[start, end)`. */
 export interface Run {
 	start: number;
 	end: number;
 }
 
-// private: plumbing
 /** Add `[start, end)` to sorted, disjoint, non-adjacent `runs`, merging every run it touches. */
 export function insertRun(runs: Run[], start: number, end: number): void {
 	if (start >= end) return;
@@ -160,7 +152,6 @@ export function dropAt(drops: readonly DropRun[], sequence: number): Error | und
 	return drops.find((run) => run.start <= sequence && sequence < run.end)?.error;
 }
 
-// private: plumbing
 /** The parts of `[start, end)` that sorted, disjoint `runs` do not cover, in order. */
 export function runGaps(runs: readonly Run[], start: number, end: number): Run[] {
 	const gaps: Run[] = [];
@@ -387,16 +378,13 @@ export interface TrackRequestOptions {
 /** Maximum buffered datagrams per subscriber; mirrors Rust's bounded send buffer. */
 export const MAX_DATAGRAMS = 64;
 
-// pending: /quest/m1/public-model/serve.md
 /** The first group an exclusive track end excludes whole: one past the last group that may exist. */
 export function finalSequence(end: Location): number {
 	return end.group + (end.frame === 0 ? 0 : 1);
 }
 
-// private: plumbing
 /** Hooks assigned in static blocks by the owning class. */
 export const hooks: {
-	// pending: /quest/m1/public-model/deferred.md
 	/**
 	 * Declare the end a wire subscription received: repeating it is a no-op, and a mid-group
 	 * end may refine the group boundary it falls just before. Throws `ProtocolViolation` on
@@ -405,24 +393,20 @@ export const hooks: {
 	 * a higher one. Mirrors the Rust `finish_at` on a `received()` copy; assigned by `track.ts`.
 	 */
 	endTrack: (producer: Producer, end: Location) => void;
-	// pending: /quest/m1/public-model/deferred.md
 	/**
 	 * End a wire subscription's copy cleanly without declaring an end, for a session closed
 	 * locally: a dead route, not finished content, so a resumed reader's replacement route
 	 * continues past it. Mirrors the Rust `close` on a `received()` copy; assigned by `track.ts`.
 	 */
 	releaseTrack: (producer: Producer) => void;
-	// private: capability gap
 	/** The producer's largest reported location and its subsequent changes. */
 	producerLargest: (producer: Producer) => Getter<Location | undefined>;
 
-	// private: passthrough
 	/** Re-evaluate a live-edge join at this subscriber's copy. */
 	joinSubscriber: (subscriber: Subscriber) => void;
 	/** Re-evaluate a live-edge join at a producer. */
 	joinProducer: (producer: Producer) => void;
 
-	// pending: /quest/m1/public-model/deferred.md
 	/**
 	 * Declare the first group a wire subscription's live feed serves (lite SUBSCRIBE_START, or
 	 * IETF SUBSCRIBE_OK's Largest) for the floor its SUBSCRIBE requested: while the demand keeps
@@ -442,24 +426,19 @@ export const hooks: {
 	 * cache window once it closed cleanly, else zero; assigned by `track.ts`.
 	 */
 	linger: (producer: Producer) => Milli;
-	// private: capability gap
 	/** Seed a received track from the publisher's reported edge; assigned by `track.ts`. */
 	reportedLargest: (producer: Producer, largest: Location | undefined) => void;
-	// pending: /quest/m1/public-model/serve.md
 	/** Snapshot the latest group sequence for wire positioning; assigned by `track.ts`. */
 	latestSequence: (subscriber: Subscriber) => number | undefined;
-	// pending: /quest/m1/public-model/serve.md
 	/**
 	 * The source's declared start, raised to the subscriber's cursor floor, or `"pending"` while
 	 * the upstream START that resolves it has yet to arrive; assigned by `track.ts`.
 	 */
 	sourceStart: (subscriber: Subscriber) => number | "pending" | undefined;
-	// pending: /quest/m1/public-model/serve.md
 	/** The newest frame buffered for a subscriber, which wire answers name; assigned by `track.ts`. */
 	bufferedLargest: (subscriber: Subscriber) => Location | undefined;
 	/** Call `fn` with a group's frame count now and on every change; assigned by `group.ts`. */
 	groupProgress: (group: GroupProducer, fn: (total: number) => void) => Dispose;
-	// pending: /quest/m1/public-model/serve.md
 	/**
 	 * Take the next group the subscriber's cursor allows, without waiting; assigned by `track.ts`.
 	 *
@@ -497,7 +476,6 @@ export const hooks: {
 	givenUp: (subscriber: Subscriber, sequence: number) => { error?: Error; changed: Getter<unknown> };
 	/** Whether a group may still land on the live feed of the subscriber's track; see {@link Land}. */
 	mayLand: (subscriber: Subscriber, land: Land) => boolean;
-	// private: capability gap
 	/** A subscriber's largest location now, and whether it can still advance. */
 	peekLargest: (subscriber: Subscriber) => { largest?: Location; ended: boolean };
 	/** Wake once a subscriber's largest location or its end may have changed; fires at most once. */
@@ -508,12 +486,10 @@ export const hooks: {
 		subscription: Subscription | undefined,
 		source: (shell: ResumeShell) => ResumeSource,
 	) => Subscriber;
-	// pending: /quest/m1/public-model/serve.md
 	/** Wake once a subscriber's group cursor may read differently; assigned by `track.ts`. */
 	groupChanged: (subscriber: Subscriber, fn: () => void) => Dispose;
 	/** Apply a FETCH reader budget without inheriting SUBSCRIBE's zero default. */
 	fetchBudget: (subscriber: Subscriber, maxDelay: Milli | undefined) => void;
-	// pending: /quest/m1/public-model/serve.md
 	/**
 	 * Replace a serving cursor. An omitted start keeps the current floor; a provided start
 	 * can lower it. Wire publishers apply SUBSCRIBE_UPDATE here rather than through
@@ -526,13 +502,10 @@ export const hooks: {
 	 */
 	bindGroupTimed: (group: GroupProducer, timed: boolean) => void;
 	/** Admit a datagram in its stored wire form. */
-	// private: passthrough
 	writeDatagram: (producer: Producer, datagram: Datagram, inflated?: number) => void;
 	/** Bind the group to its immutable track codec. */
-	// private: passthrough
 	bindGroupCompression: (group: GroupProducer, compressed: boolean) => void;
 	/** Admit a received stored slice without recompressing it. */
-	// private: passthrough
 	writeGroupFrame: (group: GroupProducer, frame: Frame, inflated?: number) => void;
 	/** Payload footprint including a shared inflated copy, for measurements. */
 	groupCacheBytes: (group: GroupProducer) => number;
@@ -566,10 +539,8 @@ export const hooks: {
 	expireGroup: (group: GroupConsumer, expiry: Expiry) => void;
 	/** Carry a handed-out group across its logical track's route changes. */
 	recoverGroup: (group: GroupConsumer, recover: GroupRecover) => void;
-	// pending: /quest/m1/public-model/serve.md
 	/** Start a group operation unless the handed-out group has expired, and stop it if the group expires mid-flight. */
 	guardGroup: <T>(group: GroupConsumer, operation: () => Promise<T>) => Promise<T>;
-	// pending: /quest/m1/public-model/serve.md
 	/** Read a frame the wire publisher completes (or skips) once written. */
 	readGroupFrame: (group: GroupConsumer, from?: number, compressed?: boolean) => Promise<ReadGroupFrame | undefined>;
 	/** Make an evicted mirror terminal while its track timeline still contains it. */
@@ -792,7 +763,6 @@ export function spreadHash(path: string, hops: readonly bigint[]): bigint {
 	return hash;
 }
 
-// pending: /quest/m1/public-model/answer.md
 /** Covering prefixes, most specific first, including the empty root. */
 export function* coveringPrefixes(path: Path.Valid): Generator<Path.Valid> {
 	for (;;) {

js/net/src/ledger.ts

@@ -10,7 +10,6 @@ import { Instant, Milli, Nano } from "@moq/clock";
  */
 export const GRACE = Milli(1000);
 
-// private: plumbing
 /** The grace for a subscription with `maxDelay`: how long it was willing to wait for a late group anyway, or {@link GRACE} without one. */
 export function grace(maxDelay: Milli): Milli {
 	return maxDelay > 0 ? maxDelay : GRACE;

js/net/src/listing.ts

@@ -386,7 +386,6 @@ export class Tracks {
 	}
 }
 
-// pending: /quest/m1/public-model/answer.md
 /**
  * Answers a broadcast's listings for a handler that knows the tracks it would serve, as a
  * session lists its peer's. A broadcast has at most one.

js/net/src/origin.ts

@@ -241,7 +241,6 @@ class CoveringRoot {
 	}
 }
 
-// pending: /quest/m1/public-model/answer.md
 /**
  * One requested path: the notify node for everything watching it.
  *
@@ -2297,7 +2296,6 @@ export class Dynamic {
 	 *
 	 * @internal
 	 */
-	// pending: /quest/m1/public-model/answer.md
 	updateRoute(
 		route: Route | { epoch?: Route["epoch"]; hops?: Route["hops"]; cost?: Route["cost"]; auth?: Route["auth"] },
 	): void {
@@ -2433,7 +2431,6 @@ export class Request {
 	 * @throws Error when handed a broadcast a session delivered. The request stays open.
 	 * @internal
 	 */
-	// pending: /quest/m1/public-model/answer.md
 	accept(source: broadcast.Producer | broadcast.Consumer): void {
 		if (this.#done) {
 			// A withdrawn request takes no answer. Only the handed-off consumer is ours;

js/net/src/priority.ts

@@ -38,7 +38,6 @@ export interface Rank {
 	position?: number;
 }
 
-// private: plumbing
 /**
  * The transport send order for a group, where HIGHER values are transmitted first.
  *
@@ -61,7 +60,6 @@ function clamp(value: number, min: number, max: number): number {
 	return Math.min(Math.max(Math.trunc(value), min), max);
 }
 
-// private: plumbing
 /**
  * Ranks one subscription's group streams against each other, and re-ranks them whenever the
  * set changes or the subscription is updated.

js/net/src/tail.ts

@@ -8,7 +8,6 @@ export interface TailOptions {
 	grace?: () => Milli;
 }
 
-// private: plumbing
 /**
  * The group streams a subscription has received, so its end can wait for the ones still owed.
  *

js/net/src/track.ts

@@ -132,7 +132,6 @@ export interface Info {
 	 */
 	refresh?: number;
 	/** The original moq-transport publisher's draft, whose timestamps may rewind. @internal */
-	// private: passthrough
 	ietf?: IetfVersion;
 }
 
@@ -160,7 +159,6 @@ function priorityValue(value: number): number {
 	return value;
 }
 
-// private: passthrough
 /** The timescale a moq-lite hop serves a track at: none for an {@link Info.ietf} one. @internal */
 export function liteTimescale(info: Info): Timescale | undefined {
 	return info.ietf === undefined ? (info.timescale ?? undefined) : undefined;
@@ -2265,7 +2263,6 @@ export class Subscriber {
 		return undefined;
 	}
 
-	// pending: /quest/m1/public-model/deferred.md
 	/**
 	 * An independent subscriber to the same track, with its own cursor and its own replay of
 	 * the retained window.