@foss.global/interfaces 0.13.0 → 1.1.0

package/changelog.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 2026-10-13 - 1.1.0
+
+### Features
+
+- add forge source inventory contracts (data)
+  - `IForgeSourceInventoryReport`: an authenticated, read-only, deterministic measurement of a source forge before its migration, with `complete`, `partial` and `notMeasured` measures as decimal strings, organization and user owner inventories with owner totals, and per-repository Git, LFS, collaboration, release (drafts, asset counts and bytes), access and Actions counts.
+  - Run units (`TForgeSourceInventoryUnit`, `TForgeSourceInventoryUnitResult`, `IForgeSourceInventoryDiscovery`) for resumable measurement, and `TForgeSourceCollisionCheck` for the native name collision check.
+  - A report never carries secret values; secrets and variables are counted, never named.
+
+### Maintenance
+
+- release tooling: `@git.zone/tsbuild` ^6.0.2 (TypeScript 7; the tsconfig needs no change), `@git.zone/tstest` ^7.2.1, `@git.zone/tsrun` ^3.0.3, `@git.zone/tsdoc` ^3.0.2 (its CLI moved to smartconsole; `buildDocs` is unchanged), `@types/node` ^26.6.4 and pnpm 12.10.0 (26.6.5 and pnpm 12.11.x are younger than seven days)
+
+## 2026-09-25 - 1.0.0
+
+### Breaking Changes
+
+- replace the GitManager ref listing contract with a complete paginated ref inventory (gitmanager)
+  - `IGitManagerRefRequest` gains `prefixes`, `cursor`, and `limit`; without prefixes every ref under `refs/` is selected, overlapping prefixes select their de-duplicated union, an empty array is invalid, and a complete ref name as the only prefix is an exact lookup.
+  - `IGitManagerRef` now carries `name`, `objectId`, `objectType`, `peeledObjectId`, `peeledObjectType`, and `symbolicTarget`; `objectId` and `objectType` are null only for a symbolic ref whose target does not resolve. The per-ref `org`, `repo`, `shortName`, `refType`, `updatedAt`, and `subject` fields and `TGitManagerRefType` are removed.
+  - Add `TGitManagerRefInventoryResult`: an `IGitManagerRefInventoryPage` with HEAD, total count, inventory digest, and cursor pagination, or `IGitManagerRefInventoryStale` when the selected refs or HEAD changed between pages.
+
+### Maintenance
+
+- Update release tooling to pnpm 12.4.2, `@git.zone/tsbuild` 5.0.0, `@git.zone/tsrun` 3.0.0, `@git.zone/tstest` 6.2.0, `@git.zone/tsdoc` 2.2.2 and `@types/node` 26.6.1 (tooling)
+  - pnpm 12.5.x and `@types/node` 26.6.2 are inside the seven-day release-age window, so pnpm stays on 12.4.2 and `@types/node` on 26.6.1.
+  - No source migration is needed: no `ts*` folder carries its own `tsconfig.json` (tsbuild 5), no script reads `process.argv` (tsrun 3), and both test files end in `tap.start()` without `TapNodeTools` (tstest 5 and 6).
+
 ## 2026-09-05 - 0.13.0
 
 ### Features

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@foss.global/interfaces',
-    version: '0.13.0',
+    version: '1.1.0',
     description: 'Shared TypeScript interfaces and TypedRequest contracts for the foss.global Git platform ecosystem.'
 };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSx5QkFBeUI7SUFDL0IsT0FBTyxFQUFFLFFBQVE7SUFDakIsV0FBVyxFQUFFLHFHQUFxRztDQUNuSCxDQUFBIn0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSx5QkFBeUI7SUFDL0IsT0FBTyxFQUFFLE9BQU87SUFDaEIsV0FBVyxFQUFFLHFHQUFxRztDQUNuSCxDQUFBIn0=

package/dist_ts/data/forgesourceinventory.d.ts

@@ -0,0 +1,336 @@
+import type { TForgeInventoryVisibility } from './forgeinventory.js';
+/**
+ * Authenticated, read-only measurement of a source forge before its one-time
+ * migration. Unlike the caller-visible inventory in `forgeinventory.ts`, it is
+ * read with a site administrator's token and counts per owner and repository.
+ *
+ * A report never contains secret values: no credentials, tokens, private keys,
+ * Actions secret or variable values, webhook secrets, or mirror remote URLs.
+ * Secrets and variables are counted, never named in the report. Reasons are
+ * sanitized diagnostics, never raw response bodies or URLs.
+ */
+/** Source forges the inventory can read. */
+export type TForgeSourceKind = 'gitea';
+/**
+ * Values are canonical nonnegative decimal integers, retaining JSON precision.
+ * `partial` was attempted and did not finish (a resumed run retries it);
+ * `notMeasured` was not attempted, for example because no read exists yet.
+ */
+export type TForgeSourceMeasure = {
+    status: 'complete';
+    value: string;
+} | {
+    status: 'partial';
+    observedValue: string;
+    reason: string;
+} | {
+    status: 'notMeasured';
+    reason: string;
+};
+export interface IForgeSourceIdentity {
+    /** Operator-assigned identity retained when the instance URL changes. */
+    instanceId: string;
+    kind: TForgeSourceKind;
+    /** Origin and path prefix only; never carries credentials. */
+    baseUrl: string;
+    version: string;
+}
+/** The account whose token read the source; an inventory requires a site administrator. */
+export interface IForgeSourceReader {
+    login: string;
+    siteAdmin: boolean;
+}
+export interface IForgeSourceUserCounts {
+    total: TForgeSourceMeasure;
+    active: TForgeSourceMeasure;
+    admins: TForgeSourceMeasure;
+    restricted: TForgeSourceMeasure;
+    prohibitLogin: TForgeSourceMeasure;
+    /** Users authenticated through an external source such as LDAP or OAuth2. */
+    externalAuth: TForgeSourceMeasure;
+    twoFactor: TForgeSourceMeasure;
+}
+export interface IForgeSourceInstanceInventory {
+    users: IForgeSourceUserCounts;
+    organizations: TForgeSourceMeasure;
+    /** System and default webhooks. */
+    systemWebhooks: TForgeSourceMeasure;
+    /** Instance-scoped Actions runners; their registrations are reissued. */
+    runners: TForgeSourceMeasure;
+    /** Repositories on disk that the forge database does not know. */
+    unadoptedRepositories: TForgeSourceMeasure;
+}
+export interface IForgeSourcePackageTypeCounts {
+    /** Provider package type, such as `npm`, `generic` or `container`. */
+    type: string;
+    packages: TForgeSourceMeasure;
+    versions: TForgeSourceMeasure;
+    files: TForgeSourceMeasure;
+    bytes: TForgeSourceMeasure;
+}
+export interface IForgeSourceUserAccount {
+    admin: boolean;
+    active: boolean;
+    restricted: boolean;
+    prohibitLogin: boolean;
+    externalAuth: boolean;
+}
+export interface IForgeSourceOwnerInventoryBase {
+    name: string;
+    /** Provider row id as a decimal string. */
+    id: string;
+    visibility: TForgeInventoryVisibility;
+    repositories: TForgeSourceMeasure;
+    webhooks: TForgeSourceMeasure;
+    actionsVariables: TForgeSourceMeasure;
+    runners: TForgeSourceMeasure;
+    /** Sorted by type. */
+    packages: IForgeSourcePackageTypeCounts[];
+}
+export interface IForgeSourceOrganizationInventory extends IForgeSourceOwnerInventoryBase {
+    kind: 'organization';
+    members: TForgeSourceMeasure;
+    teams: TForgeSourceMeasure;
+    teamMemberships: TForgeSourceMeasure;
+    teamRepositoryGrants: TForgeSourceMeasure;
+    labels: TForgeSourceMeasure;
+    actionsSecrets: TForgeSourceMeasure;
+}
+/** User-scoped Actions secrets have no list read; see `IForgeSourceInventory.limitations`. */
+export interface IForgeSourceUserInventory extends IForgeSourceOwnerInventoryBase {
+    kind: 'user';
+    account: IForgeSourceUserAccount;
+    sshKeys: TForgeSourceMeasure;
+    gpgKeys: TForgeSourceMeasure;
+}
+export type TForgeSourceOwnerInventory = IForgeSourceOrganizationInventory | IForgeSourceUserInventory;
+/** Owner-level settings summed over every owner; repository settings are summed separately. */
+export interface IForgeSourceOwnerTotals {
+    webhooks: TForgeSourceMeasure;
+    actionsSecrets: TForgeSourceMeasure;
+    actionsVariables: TForgeSourceMeasure;
+    runners: TForgeSourceMeasure;
+    members: TForgeSourceMeasure;
+    teams: TForgeSourceMeasure;
+    teamMemberships: TForgeSourceMeasure;
+    teamRepositoryGrants: TForgeSourceMeasure;
+    labels: TForgeSourceMeasure;
+    sshKeys: TForgeSourceMeasure;
+    gpgKeys: TForgeSourceMeasure;
+}
+export interface IForgeSourceGitCounts {
+    /** As reported by the forge, in KiB; not a transfer size. */
+    reportedSizeKiB: TForgeSourceMeasure;
+    branches: TForgeSourceMeasure;
+    tags: TForgeSourceMeasure;
+    /** Hidden refs that preserve pull request heads. */
+    pullRequestRefs: TForgeSourceMeasure;
+    otherRefs: TForgeSourceMeasure;
+}
+export interface IForgeSourceLfsCounts {
+    objects: TForgeSourceMeasure;
+    bytes: TForgeSourceMeasure;
+}
+export interface IForgeSourceCollaborationCounts {
+    issues: TForgeSourceMeasure;
+    pullRequests: TForgeSourceMeasure;
+    /** Conversation comments on issues and pull requests. */
+    comments: TForgeSourceMeasure;
+    reviews: TForgeSourceMeasure;
+    reviewComments: TForgeSourceMeasure;
+    labels: TForgeSourceMeasure;
+    milestones: TForgeSourceMeasure;
+    /** Reactions on issues, pull requests and their comments. */
+    reactions: TForgeSourceMeasure;
+    /** Files attached to issues, pull requests and their comments. */
+    attachments: TForgeSourceMeasure;
+    attachmentBytes: TForgeSourceMeasure;
+}
+export interface IForgeSourceReleaseCounts {
+    /** Includes drafts and prereleases. */
+    releases: TForgeSourceMeasure;
+    drafts: TForgeSourceMeasure;
+    assets: TForgeSourceMeasure;
+    assetBytes: TForgeSourceMeasure;
+}
+export interface IForgeSourceAccessCounts {
+    collaborators: TForgeSourceMeasure;
+    teams: TForgeSourceMeasure;
+    deployKeys: TForgeSourceMeasure;
+    webhooks: TForgeSourceMeasure;
+    branchProtections: TForgeSourceMeasure;
+    tagProtections: TForgeSourceMeasure;
+    /** Push mirror configurations; their remote credentials are reissued. */
+    pushMirrors: TForgeSourceMeasure;
+}
+export interface IForgeSourceActionsCounts {
+    /** Workflow files on the default branch. */
+    workflows: TForgeSourceMeasure;
+    secrets: TForgeSourceMeasure;
+    variables: TForgeSourceMeasure;
+    runners: TForgeSourceMeasure;
+    /** Run history and artifacts are archived, not migrated; counted to size the archive. */
+    runs: TForgeSourceMeasure;
+    artifacts: TForgeSourceMeasure;
+    artifactBytes: TForgeSourceMeasure;
+}
+/** Repository units the forge enables. */
+export interface IForgeSourceRepositoryFeatures {
+    issues: boolean;
+    pullRequests: boolean;
+    wiki: boolean;
+    releases: boolean;
+    packages: boolean;
+    actions: boolean;
+    projects: boolean;
+}
+export interface IForgeSourceRepositoryInventory {
+    owner: string;
+    name: string;
+    id: string;
+    visibility: TForgeInventoryVisibility;
+    fork: boolean;
+    /** `owner/name` of the fork parent, or null. */
+    parent: string | null;
+    mirror: boolean;
+    template: boolean;
+    archived: boolean;
+    empty: boolean;
+    /** Git object format such as `sha1` or `sha256`. */
+    objectFormat: string;
+    defaultBranch: string;
+    features: IForgeSourceRepositoryFeatures;
+    git: IForgeSourceGitCounts;
+    lfs: IForgeSourceLfsCounts;
+    collaboration: IForgeSourceCollaborationCounts;
+    releases: IForgeSourceReleaseCounts;
+    wikiPages: TForgeSourceMeasure;
+    access: IForgeSourceAccessCounts;
+    actions: IForgeSourceActionsCounts;
+}
+export interface IForgeSourceRepositoryTotals {
+    total: TForgeSourceMeasure;
+    private: TForgeSourceMeasure;
+    internal: TForgeSourceMeasure;
+    forks: TForgeSourceMeasure;
+    mirrors: TForgeSourceMeasure;
+    templates: TForgeSourceMeasure;
+    archived: TForgeSourceMeasure;
+    empty: TForgeSourceMeasure;
+    withWiki: TForgeSourceMeasure;
+}
+/**
+ * Sums over every owner and repository; a sum is complete only when every
+ * addend is. Repository-shaped groups sum repositories only.
+ */
+export interface IForgeSourceInventoryTotals {
+    organizations: TForgeSourceMeasure;
+    users: TForgeSourceMeasure;
+    repositories: IForgeSourceRepositoryTotals;
+    git: IForgeSourceGitCounts;
+    lfs: IForgeSourceLfsCounts;
+    collaboration: IForgeSourceCollaborationCounts;
+    releases: IForgeSourceReleaseCounts;
+    wikiPages: TForgeSourceMeasure;
+    access: IForgeSourceAccessCounts;
+    actions: IForgeSourceActionsCounts;
+    owners: IForgeSourceOwnerTotals;
+    /** Sorted by type. */
+    packages: IForgeSourcePackageTypeCounts[];
+}
+export interface IForgeSourceInventoryGenerator {
+    package: string;
+    version: string;
+}
+/**
+ * The deterministic measurement of one source: the same source state yields
+ * the same document. It carries no timestamps; run times belong to the run.
+ * Owners sort by kind then name, repositories by owner then name, and reason
+ * lists by code-unit order.
+ */
+export interface IForgeSourceInventory {
+    generators: IForgeSourceInventoryGenerator[];
+    source: IForgeSourceIdentity;
+    reader: IForgeSourceReader;
+    /** True only when discovery finished and no measure is partial or not measured. */
+    inventoryComplete: boolean;
+    incompleteReasons: string[];
+    /**
+     * Source data that the migration reissues rather than copies and that the
+     * provider exposes to no administrator read, such as user-scoped Actions
+     * secrets on Gitea. Nothing that is migrated may be listed here instead of
+     * being measured.
+     */
+    limitations: string[];
+    instance: IForgeSourceInstanceInventory;
+    owners: TForgeSourceOwnerInventory[];
+    repositories: IForgeSourceRepositoryInventory[];
+    totals: IForgeSourceInventoryTotals;
+}
+/** A source name that already exists natively and would block an import under that name. */
+export interface IForgeSourceCollision {
+    subject: 'owner' | 'repository';
+    /** `owner` or `owner/name` at the source. */
+    source: string;
+    /** The existing native name. */
+    native: string;
+    nativeKind: 'namespace' | 'repository' | 'user';
+    match: 'exact' | 'caseInsensitive';
+}
+export type TForgeSourceCollisionCheck = {
+    status: 'checked';
+    collisions: IForgeSourceCollision[];
+} | {
+    status: 'notChecked';
+    reason: string;
+};
+/**
+ * A report is a complete basis for migration planning only when
+ * `inventoryComplete` is true and the collision check ran. Collisions sort by
+ * subject, then source, then native name.
+ */
+export interface IForgeSourceInventoryReport extends IForgeSourceInventory {
+    collisionCheck: TForgeSourceCollisionCheck;
+}
+/** The complete list of what a run measures, read before any unit. */
+export interface IForgeSourceInventoryDiscovery {
+    source: IForgeSourceIdentity;
+    reader: IForgeSourceReader;
+    owners: Array<{
+        kind: 'organization' | 'user';
+        name: string;
+    }>;
+    repositories: Array<{
+        owner: string;
+        name: string;
+    }>;
+    /** Non-empty when discovery could not finish; such a run can never be complete. */
+    incompleteReasons: string[];
+}
+/** One independently measured and resumable part of a run. */
+export type TForgeSourceInventoryUnit = {
+    kind: 'instance';
+} | {
+    kind: 'owner';
+    ownerKind: 'organization' | 'user';
+    name: string;
+} | {
+    kind: 'repository';
+    owner: string;
+    name: string;
+};
+/** A failed unit, or one holding a partial measure, is measured again when a run resumes. */
+export type TForgeSourceInventoryUnitResult = {
+    kind: 'instance';
+    instance: IForgeSourceInstanceInventory;
+} | {
+    kind: 'owner';
+    owner: TForgeSourceOwnerInventory;
+} | {
+    kind: 'repository';
+    repository: IForgeSourceRepositoryInventory;
+} | {
+    kind: 'failed';
+    unit: TForgeSourceInventoryUnit;
+    reason: string;
+};

package/dist_ts/data/forgesourceinventory.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZm9yZ2Vzb3VyY2VpbnZlbnRvcnkuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL2Zvcmdlc291cmNlaW52ZW50b3J5LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiIifQ==

package/dist_ts/data/gitmanager.d.ts

@@ -1,4 +1,3 @@
-export type TGitManagerRefType = 'branch' | 'tag' | 'other';
 export type TGitManagerObjectType = 'blob' | 'tree' | 'commit' | 'tag' | 'other';
 export type TGitManagerTreeEntryType = 'file' | 'dir' | 'symlink' | 'submodule' | 'other';
 export type TGitManagerDiffFileStatus = 'added' | 'modified' | 'deleted' | 'renamed' | 'copied' | 'typechange' | 'unmerged' | 'unknown';
@@ -18,17 +17,92 @@ export interface IGitManagerInitBareRepositoryRequest extends IGitManagerReposit
 export interface IGitManagerImportMirrorRequest extends IGitManagerRepositorySelector {
     remoteUrl: string;
 }
-export interface IGitManagerRef extends IGitManagerRepositorySelector {
-    name: string;
-    shortName: string;
-    objectId: string;
-    objectType: TGitManagerObjectType;
-    refType: TGitManagerRefType;
-    updatedAt: string;
-    subject: string;
-}
+/**
+ * One page request of a repository's complete ref inventory.
+ *
+ * Without `prefixes`, every ref under `refs/` is listed: branches, tags, and
+ * all other namespaces such as `refs/notes/*`, `refs/pull/*`,
+ * `refs/keep-around/*`, and provider-internal refs. A prefix selects refs on
+ * full path components: `refs/heads/` selects every branch, and a complete
+ * ref name such as `refs/heads/main` selects exactly that ref.
+ */
 export interface IGitManagerRefRequest extends IGitManagerRepositorySelector {
+    /**
+     * `refs/`-rooted prefixes; omit to list every ref. An empty array is
+     * rejected as invalid. Overlapping prefixes select the de-duplicated union,
+     * so each ref appears once.
+     */
+    prefixes?: string[];
+    /** Opaque cursor from the preceding page; omit to start a new inventory. */
+    cursor?: string;
+    /** Maximum refs in this page. The engine owns the default and maximum. */
+    limit?: number;
 }
+export interface IGitManagerRef {
+    /** Full ref name, for example `refs/heads/main`. */
+    name: string;
+    /**
+     * Object the ref points at; for a symbolic ref, the object its target
+     * resolves to. Null only for a symbolic ref whose target does not resolve,
+     * such as `refs/remotes/origin/HEAD` pointing at a deleted branch; such refs
+     * are listed, never dropped.
+     */
+    objectId: string | null;
+    /** Type of `objectId`; null exactly when `objectId` is null. */
+    objectType: TGitManagerObjectType | null;
+    /** Fully peeled object for annotated tags, including nested tags; otherwise null. */
+    peeledObjectId: string | null;
+    peeledObjectType: TGitManagerObjectType | null;
+    /** Target ref name when this ref is symbolic; otherwise null. */
+    symbolicTarget: string | null;
+}
+/** Repository HEAD, which is reported separately and never listed in `refs`. */
+export interface IGitManagerRefHead {
+    /** Target ref name when HEAD is symbolic; null when detached. */
+    symbolicTarget: string | null;
+    /** Resolved object; null when HEAD points at an unborn branch. */
+    objectId: string | null;
+}
+export type TGitManagerRefInventoryPagination = {
+    status: 'more';
+    cursor: string;
+} | {
+    status: 'exhausted';
+};
+/**
+ * A coherent page of the selected ref inventory, sorted by ref name in byte
+ * order. Every page carries the digest of the complete selection it was cut
+ * from; a cursor is honoured only while that digest is unchanged, so pages of
+ * one inventory never mix two ref states.
+ *
+ * `inventoryDigest` is the lowercase hex SHA-256 over the UTF-8 bytes of
+ * `HEAD\0<head.symbolicTarget or empty>\0<head.objectId or empty>\n` followed
+ * by `<name>\0<objectId or empty>\0<symbolicTarget or empty>\n` for each
+ * selected ref in ref-name byte order over the complete selection. Peeled
+ * values and object types follow from the object IDs and are not part of the
+ * digest.
+ */
+export interface IGitManagerRefInventoryPage extends IGitManagerRepositorySelector {
+    status: 'page';
+    inventoryDigest: string;
+    /** Number of refs in the complete selection, not in this page. */
+    refCount: number;
+    head: IGitManagerRefHead;
+    refs: IGitManagerRef[];
+    pagination: TGitManagerRefInventoryPagination;
+}
+/**
+ * The selected refs or HEAD changed since the cursor was issued. The caller
+ * restarts the inventory without a cursor; no partial page is returned.
+ */
+export interface IGitManagerRefInventoryStale extends IGitManagerRepositorySelector {
+    status: 'stale';
+    /** Digest bound to the rejected cursor. */
+    expectedInventoryDigest: string;
+    /** Digest of the current selection. */
+    inventoryDigest: string;
+}
+export type TGitManagerRefInventoryResult = IGitManagerRefInventoryPage | IGitManagerRefInventoryStale;
 export type TGitManagerMergeMethod = 'merge' | 'squash' | 'rebase';
 export type TGitManagerMergeStatus = 'merged' | 'already_merged' | 'conflicting' | 'stale';
 export interface IGitManagerMergeRequest extends IGitManagerRepositorySelector {

package/dist_ts/data/index.d.ts

@@ -1,5 +1,6 @@
 export * from './codefeed.js';
 export * from './forgeinventory.js';
+export * from './forgesourceinventory.js';
 export * from './gitmanager.js';
 export * from './public.js';
 export * from './runner.js';

package/dist_ts/data/index.js

@@ -1,6 +1,7 @@
 export * from './codefeed.js';
 export * from './forgeinventory.js';
+export * from './forgesourceinventory.js';
 export * from './gitmanager.js';
 export * from './public.js';
 export * from './runner.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsZUFBZSxDQUFDO0FBQzlCLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyxpQkFBaUIsQ0FBQztBQUNoQyxjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLGFBQWEsQ0FBQyJ9
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsZUFBZSxDQUFDO0FBQzlCLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYywyQkFBMkIsQ0FBQztBQUMxQyxjQUFjLGlCQUFpQixDQUFDO0FBQ2hDLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsYUFBYSxDQUFDIn0=

package/dist_ts/data/runner.d.ts

@@ -1,4 +1,4 @@
-export declare const runnerProtocolVersion: "1";
+export declare const runnerProtocolVersion: '1';
 export type TRunnerProtocolVersion = typeof runnerProtocolVersion;
 export type TOciRuntime = 'docker' | 'podman';
 export type TJobNetwork = 'none' | 'bridge';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foss.global/interfaces",
-  "version": "0.13.0",
+  "version": "1.1.0",
   "private": false,
   "description": "Shared TypeScript interfaces and TypedRequest contracts for the foss.global Git platform ecosystem.",
   "exports": {
@@ -13,11 +13,11 @@
     "@api.global/typedrequest-interfaces": "^7.1.0"
   },
   "devDependencies": {
-    "@git.zone/tsbuild": "^4.4.2",
-    "@git.zone/tsdoc": "^2.1.1",
-    "@git.zone/tsrun": "^2.0.6",
-    "@git.zone/tstest": "^4.0.0",
-    "@types/node": "^26.4.1"
+    "@git.zone/tsbuild": "^6.0.2",
+    "@git.zone/tsdoc": "^3.0.2",
+    "@git.zone/tsrun": "^3.0.3",
+    "@git.zone/tstest": "^7.2.1",
+    "@types/node": "^26.6.4"
   },
   "files": [
     "ts/**/*",

package/readme.md

@@ -95,6 +95,64 @@ The runner lifecycle contracts cover registration, sessions, runner and job hear
 
 Protocol v1 describes OCI execution with Docker or Podman and `tar.gz` source archives. Artifacts, caches, and service containers are explicitly unsupported in the v1 capability shape. Supported job network modes are `none` and `bridge`; the execution service remains responsible for enforcing the advertised capability.
 
+### GitManager ref inventory contracts
+
+`IGitManagerRefRequest`, `IGitManagerRef`, and `TGitManagerRefInventoryResult`
+describe a complete, paginated ref inventory. Without `prefixes`, every ref
+under `refs/` is listed, including notes, pull, keep-around, and
+provider-internal namespaces. HEAD is reported separately in `head`. Annotated
+tags carry their fully peeled object. Symbolic refs carry their target ref
+name; a symbolic ref whose target does not resolve is still listed, with a null
+`objectId` and `objectType`.
+
+```ts
+import type {
+  IGitManagerRef,
+  IGitManagerRefRequest,
+  TGitManagerRefInventoryResult,
+} from '@foss.global/interfaces';
+
+declare function listRefs(
+  request: IGitManagerRefRequest,
+): Promise<TGitManagerRefInventoryResult>;
+
+const collectRefs = async (): Promise<IGitManagerRef[]> => {
+  const refs: IGitManagerRef[] = [];
+  let cursor: string | undefined;
+  while (true) {
+    const result = await listRefs({ org: 'foss.global', repo: 'interfaces', cursor });
+    if (result.status === 'stale') {
+      refs.length = 0;
+      cursor = undefined;
+      continue;
+    }
+    refs.push(...result.refs);
+    if (result.pagination.status === 'exhausted') {
+      return refs;
+    }
+    cursor = result.pagination.cursor;
+  }
+};
+
+// A complete ref name as the only prefix is an exact lookup.
+const main = await listRefs({
+  org: 'foss.global',
+  repo: 'interfaces',
+  prefixes: ['refs/heads/main'],
+});
+```
+
+Prefixes match whole path components, so `refs/heads/ma` does not select
+`refs/heads/main`. Overlapping prefixes select their de-duplicated union, and
+an empty `prefixes` array is rejected as invalid. Pages are sorted by ref name
+in byte order and each carries `inventoryDigest`, the SHA-256 of the complete
+selection defined on `IGitManagerRefInventoryPage`. A cursor is opaque and
+bound to the repository, the prefix set, and that digest. When the selected
+refs or HEAD change between pages, the next call returns `status: 'stale'`
+instead of a page that would mix two states; the caller restarts without a
+cursor. A cursor is a transport continuation, not a durable replication
+checkpoint.
+
 ### Forge inventory contracts
 
 `IForgeInventoryReport`, `IForgeInventoryPage<TItem>`, `IForgeInventoryNamespace`,
@@ -131,9 +189,49 @@ scope consistency, capability/result agreement, cursor binding, diagnostics, and
 authorization. These DTOs do not establish replication authority, historical
 import fidelity, checksummed manifests, or durable recovery checkpoints.
 
+### Forge source inventory contracts
+
+`IForgeSourceInventoryReport` is the authenticated, read-only measurement of a
+source forge before its one-time migration, read with a site administrator's
+token. It counts users, organizations, teams, memberships, keys, packages by
+type, and per repository the Git refs, LFS objects, issues, pull requests,
+comments, reviews, reactions, attachments, releases (drafts included) with
+asset bytes, wiki pages, access settings, webhooks, push mirrors, Actions
+settings, and the Actions runs and artifacts that are archived rather than
+migrated.
+
+Every count is a `TForgeSourceMeasure`: `complete` with a decimal-string value,
+`partial` with the value observed before a retryable failure, or `notMeasured`
+when no read was attempted. `inventoryComplete` is true only when discovery
+finished and no measure is partial or not measured; `incompleteReasons` lists
+why not. `limitations` names source data the provider exposes to no
+administrator read and that is reissued rather than migrated, such as Gitea's
+user-scoped Actions secrets; everything readable is a measure instead.
+Reasons are sanitized text, never raw response bodies or URLs.
+
+Owners are a `TForgeSourceOwnerInventory` union: an organization carries its
+members, teams, team memberships and repository grants, labels and Actions
+secret count; a user carries its account flags and SSH and GPG key counts.
+Both carry repositories, webhooks, Actions variables, runners and packages by
+type. `totals.owners` sums the owner-level counts; the repository-shaped totals
+sum repositories only.
+
+A run first reads `IForgeSourceInventoryDiscovery`, then measures independent
+`TForgeSourceInventoryUnit`s (the instance, each owner and each repository). A
+failed unit, or one holding a partial measure, is measured again on resume.
+`IForgeSourceInventory` is deterministic: it carries no timestamps, owners sort
+by kind and name, repositories by owner and name. The report adds
+`collisionCheck`, the source owner and repository names that already exist
+natively, exactly or case-insensitively, sorted by subject, source and native
+name. A report is a complete planning basis only when `inventoryComplete` is
+true and the collision check ran.
+
+A report never contains secret values, credentials, tokens, private keys,
+Actions secret or variable values, webhook secrets, or mirror remote URLs.
+
 ## Exports
 
-- `data`: public DTOs for users, organizations, repositories, contents, commits, diffs, releases, issues, activity, news, stats, codefeed commit results, GitManager repository/read API results, and runner/CI contracts.
+- `data`: public DTOs for users, organizations, repositories, contents, commits, diffs, releases, issues, activity, news, stats, codefeed commit results, GitManager repository/read API results, forge and forge source inventories, and runner/CI contracts.
 - `requests`: TypedRequest contracts for `codefeed`, `publicOverview`, `publicOrg`, `publicRepo`, `publicFile`, and `publicCommits`.
 - Barrel exports: all public data and request interfaces are also exported from the package root.
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@foss.global/interfaces',
-  version: '0.13.0',
+  version: '1.1.0',
   description: 'Shared TypeScript interfaces and TypedRequest contracts for the foss.global Git platform ecosystem.'
 }

package/ts/data/forgesourceinventory.ts

@@ -0,0 +1,335 @@
+import type { TForgeInventoryVisibility } from './forgeinventory.js';
+
+/**
+ * Authenticated, read-only measurement of a source forge before its one-time
+ * migration. Unlike the caller-visible inventory in `forgeinventory.ts`, it is
+ * read with a site administrator's token and counts per owner and repository.
+ *
+ * A report never contains secret values: no credentials, tokens, private keys,
+ * Actions secret or variable values, webhook secrets, or mirror remote URLs.
+ * Secrets and variables are counted, never named in the report. Reasons are
+ * sanitized diagnostics, never raw response bodies or URLs.
+ */
+
+/** Source forges the inventory can read. */
+export type TForgeSourceKind = 'gitea';
+
+/**
+ * Values are canonical nonnegative decimal integers, retaining JSON precision.
+ * `partial` was attempted and did not finish (a resumed run retries it);
+ * `notMeasured` was not attempted, for example because no read exists yet.
+ */
+export type TForgeSourceMeasure =
+  | { status: 'complete'; value: string }
+  | { status: 'partial'; observedValue: string; reason: string }
+  | { status: 'notMeasured'; reason: string };
+
+export interface IForgeSourceIdentity {
+  /** Operator-assigned identity retained when the instance URL changes. */
+  instanceId: string;
+  kind: TForgeSourceKind;
+  /** Origin and path prefix only; never carries credentials. */
+  baseUrl: string;
+  version: string;
+}
+
+/** The account whose token read the source; an inventory requires a site administrator. */
+export interface IForgeSourceReader {
+  login: string;
+  siteAdmin: boolean;
+}
+
+export interface IForgeSourceUserCounts {
+  total: TForgeSourceMeasure;
+  active: TForgeSourceMeasure;
+  admins: TForgeSourceMeasure;
+  restricted: TForgeSourceMeasure;
+  prohibitLogin: TForgeSourceMeasure;
+  /** Users authenticated through an external source such as LDAP or OAuth2. */
+  externalAuth: TForgeSourceMeasure;
+  twoFactor: TForgeSourceMeasure;
+}
+
+export interface IForgeSourceInstanceInventory {
+  users: IForgeSourceUserCounts;
+  organizations: TForgeSourceMeasure;
+  /** System and default webhooks. */
+  systemWebhooks: TForgeSourceMeasure;
+  /** Instance-scoped Actions runners; their registrations are reissued. */
+  runners: TForgeSourceMeasure;
+  /** Repositories on disk that the forge database does not know. */
+  unadoptedRepositories: TForgeSourceMeasure;
+}
+
+export interface IForgeSourcePackageTypeCounts {
+  /** Provider package type, such as `npm`, `generic` or `container`. */
+  type: string;
+  packages: TForgeSourceMeasure;
+  versions: TForgeSourceMeasure;
+  files: TForgeSourceMeasure;
+  bytes: TForgeSourceMeasure;
+}
+
+export interface IForgeSourceUserAccount {
+  admin: boolean;
+  active: boolean;
+  restricted: boolean;
+  prohibitLogin: boolean;
+  externalAuth: boolean;
+}
+
+export interface IForgeSourceOwnerInventoryBase {
+  name: string;
+  /** Provider row id as a decimal string. */
+  id: string;
+  visibility: TForgeInventoryVisibility;
+  repositories: TForgeSourceMeasure;
+  webhooks: TForgeSourceMeasure;
+  actionsVariables: TForgeSourceMeasure;
+  runners: TForgeSourceMeasure;
+  /** Sorted by type. */
+  packages: IForgeSourcePackageTypeCounts[];
+}
+
+export interface IForgeSourceOrganizationInventory extends IForgeSourceOwnerInventoryBase {
+  kind: 'organization';
+  members: TForgeSourceMeasure;
+  teams: TForgeSourceMeasure;
+  teamMemberships: TForgeSourceMeasure;
+  teamRepositoryGrants: TForgeSourceMeasure;
+  labels: TForgeSourceMeasure;
+  actionsSecrets: TForgeSourceMeasure;
+}
+
+/** User-scoped Actions secrets have no list read; see `IForgeSourceInventory.limitations`. */
+export interface IForgeSourceUserInventory extends IForgeSourceOwnerInventoryBase {
+  kind: 'user';
+  account: IForgeSourceUserAccount;
+  sshKeys: TForgeSourceMeasure;
+  gpgKeys: TForgeSourceMeasure;
+}
+
+export type TForgeSourceOwnerInventory = IForgeSourceOrganizationInventory | IForgeSourceUserInventory;
+
+/** Owner-level settings summed over every owner; repository settings are summed separately. */
+export interface IForgeSourceOwnerTotals {
+  webhooks: TForgeSourceMeasure;
+  actionsSecrets: TForgeSourceMeasure;
+  actionsVariables: TForgeSourceMeasure;
+  runners: TForgeSourceMeasure;
+  members: TForgeSourceMeasure;
+  teams: TForgeSourceMeasure;
+  teamMemberships: TForgeSourceMeasure;
+  teamRepositoryGrants: TForgeSourceMeasure;
+  labels: TForgeSourceMeasure;
+  sshKeys: TForgeSourceMeasure;
+  gpgKeys: TForgeSourceMeasure;
+}
+
+export interface IForgeSourceGitCounts {
+  /** As reported by the forge, in KiB; not a transfer size. */
+  reportedSizeKiB: TForgeSourceMeasure;
+  branches: TForgeSourceMeasure;
+  tags: TForgeSourceMeasure;
+  /** Hidden refs that preserve pull request heads. */
+  pullRequestRefs: TForgeSourceMeasure;
+  otherRefs: TForgeSourceMeasure;
+}
+
+export interface IForgeSourceLfsCounts {
+  objects: TForgeSourceMeasure;
+  bytes: TForgeSourceMeasure;
+}
+
+export interface IForgeSourceCollaborationCounts {
+  issues: TForgeSourceMeasure;
+  pullRequests: TForgeSourceMeasure;
+  /** Conversation comments on issues and pull requests. */
+  comments: TForgeSourceMeasure;
+  reviews: TForgeSourceMeasure;
+  reviewComments: TForgeSourceMeasure;
+  labels: TForgeSourceMeasure;
+  milestones: TForgeSourceMeasure;
+  /** Reactions on issues, pull requests and their comments. */
+  reactions: TForgeSourceMeasure;
+  /** Files attached to issues, pull requests and their comments. */
+  attachments: TForgeSourceMeasure;
+  attachmentBytes: TForgeSourceMeasure;
+}
+
+export interface IForgeSourceReleaseCounts {
+  /** Includes drafts and prereleases. */
+  releases: TForgeSourceMeasure;
+  drafts: TForgeSourceMeasure;
+  assets: TForgeSourceMeasure;
+  assetBytes: TForgeSourceMeasure;
+}
+
+export interface IForgeSourceAccessCounts {
+  collaborators: TForgeSourceMeasure;
+  teams: TForgeSourceMeasure;
+  deployKeys: TForgeSourceMeasure;
+  webhooks: TForgeSourceMeasure;
+  branchProtections: TForgeSourceMeasure;
+  tagProtections: TForgeSourceMeasure;
+  /** Push mirror configurations; their remote credentials are reissued. */
+  pushMirrors: TForgeSourceMeasure;
+}
+
+export interface IForgeSourceActionsCounts {
+  /** Workflow files on the default branch. */
+  workflows: TForgeSourceMeasure;
+  secrets: TForgeSourceMeasure;
+  variables: TForgeSourceMeasure;
+  runners: TForgeSourceMeasure;
+  /** Run history and artifacts are archived, not migrated; counted to size the archive. */
+  runs: TForgeSourceMeasure;
+  artifacts: TForgeSourceMeasure;
+  artifactBytes: TForgeSourceMeasure;
+}
+
+/** Repository units the forge enables. */
+export interface IForgeSourceRepositoryFeatures {
+  issues: boolean;
+  pullRequests: boolean;
+  wiki: boolean;
+  releases: boolean;
+  packages: boolean;
+  actions: boolean;
+  projects: boolean;
+}
+
+export interface IForgeSourceRepositoryInventory {
+  owner: string;
+  name: string;
+  id: string;
+  visibility: TForgeInventoryVisibility;
+  fork: boolean;
+  /** `owner/name` of the fork parent, or null. */
+  parent: string | null;
+  mirror: boolean;
+  template: boolean;
+  archived: boolean;
+  empty: boolean;
+  /** Git object format such as `sha1` or `sha256`. */
+  objectFormat: string;
+  defaultBranch: string;
+  features: IForgeSourceRepositoryFeatures;
+  git: IForgeSourceGitCounts;
+  lfs: IForgeSourceLfsCounts;
+  collaboration: IForgeSourceCollaborationCounts;
+  releases: IForgeSourceReleaseCounts;
+  wikiPages: TForgeSourceMeasure;
+  access: IForgeSourceAccessCounts;
+  actions: IForgeSourceActionsCounts;
+}
+
+export interface IForgeSourceRepositoryTotals {
+  total: TForgeSourceMeasure;
+  private: TForgeSourceMeasure;
+  internal: TForgeSourceMeasure;
+  forks: TForgeSourceMeasure;
+  mirrors: TForgeSourceMeasure;
+  templates: TForgeSourceMeasure;
+  archived: TForgeSourceMeasure;
+  empty: TForgeSourceMeasure;
+  withWiki: TForgeSourceMeasure;
+}
+
+/**
+ * Sums over every owner and repository; a sum is complete only when every
+ * addend is. Repository-shaped groups sum repositories only.
+ */
+export interface IForgeSourceInventoryTotals {
+  organizations: TForgeSourceMeasure;
+  users: TForgeSourceMeasure;
+  repositories: IForgeSourceRepositoryTotals;
+  git: IForgeSourceGitCounts;
+  lfs: IForgeSourceLfsCounts;
+  collaboration: IForgeSourceCollaborationCounts;
+  releases: IForgeSourceReleaseCounts;
+  wikiPages: TForgeSourceMeasure;
+  access: IForgeSourceAccessCounts;
+  actions: IForgeSourceActionsCounts;
+  owners: IForgeSourceOwnerTotals;
+  /** Sorted by type. */
+  packages: IForgeSourcePackageTypeCounts[];
+}
+
+export interface IForgeSourceInventoryGenerator {
+  package: string;
+  version: string;
+}
+
+/**
+ * The deterministic measurement of one source: the same source state yields
+ * the same document. It carries no timestamps; run times belong to the run.
+ * Owners sort by kind then name, repositories by owner then name, and reason
+ * lists by code-unit order.
+ */
+export interface IForgeSourceInventory {
+  generators: IForgeSourceInventoryGenerator[];
+  source: IForgeSourceIdentity;
+  reader: IForgeSourceReader;
+  /** True only when discovery finished and no measure is partial or not measured. */
+  inventoryComplete: boolean;
+  incompleteReasons: string[];
+  /**
+   * Source data that the migration reissues rather than copies and that the
+   * provider exposes to no administrator read, such as user-scoped Actions
+   * secrets on Gitea. Nothing that is migrated may be listed here instead of
+   * being measured.
+   */
+  limitations: string[];
+  instance: IForgeSourceInstanceInventory;
+  owners: TForgeSourceOwnerInventory[];
+  repositories: IForgeSourceRepositoryInventory[];
+  totals: IForgeSourceInventoryTotals;
+}
+
+/** A source name that already exists natively and would block an import under that name. */
+export interface IForgeSourceCollision {
+  subject: 'owner' | 'repository';
+  /** `owner` or `owner/name` at the source. */
+  source: string;
+  /** The existing native name. */
+  native: string;
+  nativeKind: 'namespace' | 'repository' | 'user';
+  match: 'exact' | 'caseInsensitive';
+}
+
+export type TForgeSourceCollisionCheck =
+  | { status: 'checked'; collisions: IForgeSourceCollision[] }
+  | { status: 'notChecked'; reason: string };
+
+/**
+ * A report is a complete basis for migration planning only when
+ * `inventoryComplete` is true and the collision check ran. Collisions sort by
+ * subject, then source, then native name.
+ */
+export interface IForgeSourceInventoryReport extends IForgeSourceInventory {
+  collisionCheck: TForgeSourceCollisionCheck;
+}
+
+/** The complete list of what a run measures, read before any unit. */
+export interface IForgeSourceInventoryDiscovery {
+  source: IForgeSourceIdentity;
+  reader: IForgeSourceReader;
+  owners: Array<{ kind: 'organization' | 'user'; name: string }>;
+  repositories: Array<{ owner: string; name: string }>;
+  /** Non-empty when discovery could not finish; such a run can never be complete. */
+  incompleteReasons: string[];
+}
+
+/** One independently measured and resumable part of a run. */
+export type TForgeSourceInventoryUnit =
+  | { kind: 'instance' }
+  | { kind: 'owner'; ownerKind: 'organization' | 'user'; name: string }
+  | { kind: 'repository'; owner: string; name: string };
+
+/** A failed unit, or one holding a partial measure, is measured again when a run resumes. */
+export type TForgeSourceInventoryUnitResult =
+  | { kind: 'instance'; instance: IForgeSourceInstanceInventory }
+  | { kind: 'owner'; owner: TForgeSourceOwnerInventory }
+  | { kind: 'repository'; repository: IForgeSourceRepositoryInventory }
+  | { kind: 'failed'; unit: TForgeSourceInventoryUnit; reason: string };

package/ts/data/gitmanager.ts

@@ -1,5 +1,3 @@
-export type TGitManagerRefType = 'branch' | 'tag' | 'other';
-
 export type TGitManagerObjectType = 'blob' | 'tree' | 'commit' | 'tag' | 'other';
 
 export type TGitManagerTreeEntryType = 'file' | 'dir' | 'symlink' | 'submodule' | 'other';
@@ -35,17 +33,95 @@ export interface IGitManagerImportMirrorRequest extends IGitManagerRepositorySel
   remoteUrl: string;
 }
 
-export interface IGitManagerRef extends IGitManagerRepositorySelector {
+/**
+ * One page request of a repository's complete ref inventory.
+ *
+ * Without `prefixes`, every ref under `refs/` is listed: branches, tags, and
+ * all other namespaces such as `refs/notes/*`, `refs/pull/*`,
+ * `refs/keep-around/*`, and provider-internal refs. A prefix selects refs on
+ * full path components: `refs/heads/` selects every branch, and a complete
+ * ref name such as `refs/heads/main` selects exactly that ref.
+ */
+export interface IGitManagerRefRequest extends IGitManagerRepositorySelector {
+  /**
+   * `refs/`-rooted prefixes; omit to list every ref. An empty array is
+   * rejected as invalid. Overlapping prefixes select the de-duplicated union,
+   * so each ref appears once.
+   */
+  prefixes?: string[];
+  /** Opaque cursor from the preceding page; omit to start a new inventory. */
+  cursor?: string;
+  /** Maximum refs in this page. The engine owns the default and maximum. */
+  limit?: number;
+}
+
+export interface IGitManagerRef {
+  /** Full ref name, for example `refs/heads/main`. */
   name: string;
-  shortName: string;
-  objectId: string;
-  objectType: TGitManagerObjectType;
-  refType: TGitManagerRefType;
-  updatedAt: string;
-  subject: string;
+  /**
+   * Object the ref points at; for a symbolic ref, the object its target
+   * resolves to. Null only for a symbolic ref whose target does not resolve,
+   * such as `refs/remotes/origin/HEAD` pointing at a deleted branch; such refs
+   * are listed, never dropped.
+   */
+  objectId: string | null;
+  /** Type of `objectId`; null exactly when `objectId` is null. */
+  objectType: TGitManagerObjectType | null;
+  /** Fully peeled object for annotated tags, including nested tags; otherwise null. */
+  peeledObjectId: string | null;
+  peeledObjectType: TGitManagerObjectType | null;
+  /** Target ref name when this ref is symbolic; otherwise null. */
+  symbolicTarget: string | null;
+}
+
+/** Repository HEAD, which is reported separately and never listed in `refs`. */
+export interface IGitManagerRefHead {
+  /** Target ref name when HEAD is symbolic; null when detached. */
+  symbolicTarget: string | null;
+  /** Resolved object; null when HEAD points at an unborn branch. */
+  objectId: string | null;
+}
+
+export type TGitManagerRefInventoryPagination =
+  | { status: 'more'; cursor: string }
+  | { status: 'exhausted' };
+
+/**
+ * A coherent page of the selected ref inventory, sorted by ref name in byte
+ * order. Every page carries the digest of the complete selection it was cut
+ * from; a cursor is honoured only while that digest is unchanged, so pages of
+ * one inventory never mix two ref states.
+ *
+ * `inventoryDigest` is the lowercase hex SHA-256 over the UTF-8 bytes of
+ * `HEAD\0<head.symbolicTarget or empty>\0<head.objectId or empty>\n` followed
+ * by `<name>\0<objectId or empty>\0<symbolicTarget or empty>\n` for each
+ * selected ref in ref-name byte order over the complete selection. Peeled
+ * values and object types follow from the object IDs and are not part of the
+ * digest.
+ */
+export interface IGitManagerRefInventoryPage extends IGitManagerRepositorySelector {
+  status: 'page';
+  inventoryDigest: string;
+  /** Number of refs in the complete selection, not in this page. */
+  refCount: number;
+  head: IGitManagerRefHead;
+  refs: IGitManagerRef[];
+  pagination: TGitManagerRefInventoryPagination;
+}
+
+/**
+ * The selected refs or HEAD changed since the cursor was issued. The caller
+ * restarts the inventory without a cursor; no partial page is returned.
+ */
+export interface IGitManagerRefInventoryStale extends IGitManagerRepositorySelector {
+  status: 'stale';
+  /** Digest bound to the rejected cursor. */
+  expectedInventoryDigest: string;
+  /** Digest of the current selection. */
+  inventoryDigest: string;
 }
 
-export interface IGitManagerRefRequest extends IGitManagerRepositorySelector {}
+export type TGitManagerRefInventoryResult = IGitManagerRefInventoryPage | IGitManagerRefInventoryStale;
 
 export type TGitManagerMergeMethod = 'merge' | 'squash' | 'rebase';
 

package/ts/data/index.ts

@@ -1,5 +1,6 @@
 export * from './codefeed.js';
 export * from './forgeinventory.js';
+export * from './forgesourceinventory.js';
 export * from './gitmanager.js';
 export * from './public.js';
 export * from './runner.js';