@foss.global/interfaces 1.1.0 → 2.1.0

package/changelog.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 2026-10-13 - 2.1.0
+
+### Features
+
+- add origin and atomic push contracts for the Gitea import (data)
+  - `IOriginRef` and `TOriginState`: where a native entity came from (`native`, `imported` with the source forge instance and entity id, or `unknown`); an identity only, never a URL, path or authority.
+  - `IGitManagerAtomicPushRequest` with leased `IGitManagerAtomicPushRefUpdate`s and the all-or-nothing `IGitManagerAtomicPushResult` (`ok`, `stale` or `rejected` per ref); https or loopback-http remotes only.
+  - `IGitManagerSetDefaultBranchRequest` points a repository's HEAD at an existing branch.
+
+## 2026-10-13 - 2.0.0
+
+### Features
+
+- add GitManager remote transfer options and the repository size contract (gitmanager)
+  - `IGitManagerRemoteTransferOptions` on `IGitManagerImportMirrorRequest` and the new `IGitManagerRefreshMirrorRequest`: an HTTP Basic `credential` carried outside the URL, command line and Git config, `caCertificates` for a private CA, and a `timeoutMs` up to six hours.
+  - `IGitManagerRepositorySize`: object count, uncompressed object bytes and object database storage bytes.
+
+### Breaking Changes
+
+- measure Git objects and LFS presence in the forge source inventory (data)
+  - `IForgeSourceGitCounts` gains the required measures `objects` and `objectBytes`, and `IForgeSourceLfsCounts` gains `missingObjects`; producers must fill them. LFS `objects` and `bytes` now count only the referenced objects the forge holds.
+
+### Maintenance
+
+- update release tooling: pnpm 12.10.1 (deps)
+
 ## 2026-10-13 - 1.1.0
 
 ### Features

package/dist_ts/00_commitinfo_data.js

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

package/dist_ts/data/forgesourceinventory.d.ts

@@ -118,6 +118,10 @@ export interface IForgeSourceOwnerTotals {
     sshKeys: TForgeSourceMeasure;
     gpgKeys: TForgeSourceMeasure;
 }
+/**
+ * Ref and object counts read at the Git level, from a mirror clone of every
+ * ref the forge advertises, except `reportedSizeKiB`.
+ */
 export interface IForgeSourceGitCounts {
     /** As reported by the forge, in KiB; not a transfer size. */
     reportedSizeKiB: TForgeSourceMeasure;
@@ -126,10 +130,22 @@ export interface IForgeSourceGitCounts {
     /** Hidden refs that preserve pull request heads. */
     pullRequestRefs: TForgeSourceMeasure;
     otherRefs: TForgeSourceMeasure;
+    /** Distinct Git objects reachable from those refs. */
+    objects: TForgeSourceMeasure;
+    /** Sum of the uncompressed sizes of those objects; independent of how the forge packs them. */
+    objectBytes: TForgeSourceMeasure;
 }
+/**
+ * LFS objects that pointers in any reachable revision reference, by distinct
+ * object ID, checked for presence through the forge's LFS batch API.
+ */
 export interface IForgeSourceLfsCounts {
+    /** Referenced objects the forge holds. */
     objects: TForgeSourceMeasure;
+    /** Sizes of the objects the forge holds. */
     bytes: TForgeSourceMeasure;
+    /** Referenced objects the forge does not hold; they cannot be migrated. */
+    missingObjects: TForgeSourceMeasure;
 }
 export interface IForgeSourceCollaborationCounts {
     issues: TForgeSourceMeasure;

package/dist_ts/data/gitmanager.d.ts

@@ -14,9 +14,127 @@ export interface IGitManagerRepositoryInfo extends IGitManagerRepositorySelector
 export interface IGitManagerInitBareRepositoryRequest extends IGitManagerRepositorySelector {
     defaultBranch?: string;
 }
-export interface IGitManagerImportMirrorRequest extends IGitManagerRepositorySelector {
+/**
+ * Points a repository's HEAD at an existing branch, which clones then check
+ * out by default.
+ */
+export interface IGitManagerSetDefaultBranchRequest extends IGitManagerRepositorySelector {
+    /** Branch name without `refs/heads/`, as in `IGitManagerRepositoryInfo.defaultBranch`; the branch must exist. */
+    defaultBranch: string;
+}
+/**
+ * HTTP Basic credentials for a remote Git transfer, such as a forge user name
+ * with an access token as the password. Neither part may contain control
+ * characters, and the user name may not contain `:`.
+ */
+export interface IGitManagerRemoteBasicCredential {
+    kind: 'basic';
+    username: string;
+    password: string;
+}
+export type TGitManagerRemoteCredential = IGitManagerRemoteBasicCredential;
+/**
+ * Options for one transfer from a remote repository.
+ *
+ * A credential reaches Git only through the Git process environment, as an
+ * `Authorization` header. It never appears in the remote URL, on a command
+ * line, in the repository's Git config, or in an error. A credential requires
+ * an `https` remote URL without user information, and Git does not follow
+ * HTTP redirects while it carries one.
+ */
+export interface IGitManagerRemoteTransferOptions {
+    credential?: TGitManagerRemoteCredential;
+    /**
+     * PEM certificates that Git uses as its CA bundle for this transfer, in
+     * place of the default bundle file, for a remote behind a private CA.
+     */
+    caCertificates?: string[];
+    /** Wall-clock limit for the transfer in milliseconds; defaults to 120000, at most 21600000 (six hours). */
+    timeoutMs?: number;
+}
+/**
+ * Clones every ref of a remote into a new mirror repository. The stored
+ * `remote.origin.url` is `remoteUrl`, so it must never carry credentials;
+ * pass them as `credential`.
+ */
+export interface IGitManagerImportMirrorRequest extends IGitManagerRepositorySelector, IGitManagerRemoteTransferOptions {
     remoteUrl: string;
 }
+/** Fetches every ref of an imported mirror's remote again, pruning refs the remote no longer has. */
+export interface IGitManagerRefreshMirrorRequest extends IGitManagerRepositorySelector, IGitManagerRemoteTransferOptions {
+}
+/**
+ * One ref change of an atomic push, guarded by a lease: the remote applies it
+ * only while its ref still points at `expectedOldObjectId`. Both object IDs
+ * are full hexadecimal object IDs; at least one of them is non-null.
+ */
+export interface IGitManagerAtomicPushRefUpdate {
+    /** Full ref name on the remote, for example `refs/heads/main`. */
+    ref: string;
+    /** Object the remote ref must point at now; null creates the ref, which must not exist. */
+    expectedOldObjectId: string | null;
+    /** Object to set the remote ref to, present in the managed repository; null deletes the ref. */
+    newObjectId: string | null;
+}
+/**
+ * Pushes ref updates from a managed repository to a remote as one atomic
+ * transaction: the remote applies every update or none. The remote must
+ * advertise the `atomic` receive-pack capability; without it the push fails
+ * before any ref is sent and never falls back to ref-by-ref updates.
+ *
+ * `remoteUrl` is used for this push only and is never stored in the
+ * repository. It must be `https`, or `http` to a loopback host
+ * (`127.0.0.0/8`, `::1` or `localhost`); `ssh`, `git`, `file` and scp-like
+ * URLs are refused. Transfer options behave as for `importMirror`, except
+ * that a push credential is also accepted for `http` to a loopback host, which
+ * never leaves the machine; the URL must not carry user information.
+ */
+export interface IGitManagerAtomicPushRequest extends IGitManagerRepositorySelector, IGitManagerRemoteTransferOptions {
+    remoteUrl: string;
+    /** Updates of distinct refs; at least one. */
+    updates: IGitManagerAtomicPushRefUpdate[];
+}
+/**
+ * Outcome of one ref as the remote reported it. `stale` means the lease
+ * failed: the remote ref did not point at the expected object. `rejected`
+ * covers every other refusal, such as a hook or ref protection, and also the
+ * refs the remote refused only because another ref of the same atomic push
+ * failed.
+ */
+export type TGitManagerAtomicPushRefStatus = 'ok' | 'rejected' | 'stale';
+export interface IGitManagerAtomicPushRefResult {
+    ref: string;
+    status: TGitManagerAtomicPushRefStatus;
+    /** Reason text the remote reported for the ref, when it gave one; credentials are redacted. */
+    message?: string;
+}
+/**
+ * Result of an atomic push. `applied` means every ref is `ok`; `rejected`
+ * means no ref changed on the remote, and `refs` says why.
+ */
+export interface IGitManagerAtomicPushResult extends IGitManagerRepositorySelector {
+    status: 'applied' | 'rejected';
+    /** One result per requested update, in request order. */
+    refs: IGitManagerAtomicPushRefResult[];
+}
+/**
+ * The object database of one repository when it was measured. Objects of
+ * alternate object stores are not counted.
+ */
+export interface IGitManagerRepositorySize extends IGitManagerRepositorySelector {
+    /** Distinct commits, trees, blobs and annotated tags, reachable or not. */
+    objectCount: number;
+    /**
+     * Sum of the uncompressed sizes of those objects. It does not depend on
+     * how the objects are packed, so equal object sets give equal values.
+     */
+    objectBytes: number;
+    /**
+     * Bytes of every file in the object database: loose objects, packs, their
+     * indexes and other pack metadata. It depends on packing.
+     */
+    storageBytes: number;
+}
 /**
  * One page request of a repository's complete ref inventory.
  *

package/dist_ts/data/index.d.ts

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

package/dist_ts/data/index.js

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

package/dist_ts/data/origin.d.ts

@@ -0,0 +1,35 @@
+/** Kinds of source entity an import records its origin for. */
+export type TOriginEntityKind = 'repository';
+/**
+ * Identity of the source entity a native entity was imported from.
+ *
+ * It names the source by stable identifiers only. It carries no URLs, paths,
+ * configuration or run IDs, digests, or authority: it neither locates the
+ * source nor grants access to it.
+ */
+export interface IOriginRef {
+    /** Operator-minted instanceId of the forge connection the entity was imported from. */
+    instanceId: string;
+    entityKind: TOriginEntityKind;
+    /** Source row ID as an opaque string; for a Gitea repository, its decimal repository ID. */
+    entityId: string;
+    /**
+     * Source ID of the parent when entity IDs are parent-scoped; otherwise null.
+     * Null for repositories, because Gitea repository IDs are unique within an
+     * instance. Later entity kinds define their parent.
+     */
+    parentId: string | null;
+}
+/**
+ * Where a native entity came from: created natively, imported from a
+ * recorded source, or not known, for example for an entity that predates
+ * origin tracking. `unknown` must never be read as `native`.
+ */
+export type TOriginState = {
+    kind: 'native';
+} | {
+    kind: 'imported';
+    origin: IOriginRef;
+} | {
+    kind: 'unknown';
+};

package/dist_ts/data/origin.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foss.global/interfaces",
-  "version": "1.1.0",
+  "version": "2.1.0",
   "private": false,
   "description": "Shared TypeScript interfaces and TypedRequest contracts for the foss.global Git platform ecosystem.",
   "exports": {

package/readme.md

@@ -153,6 +153,54 @@ 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.
 
+### GitManager remote transfer and size contracts
+
+`IGitManagerImportMirrorRequest` and `IGitManagerRefreshMirrorRequest` take
+`IGitManagerRemoteTransferOptions`: an optional `credential`
+(`TGitManagerRemoteCredential`, HTTP Basic), optional `caCertificates` (PEM,
+used as Git's CA bundle for that transfer) and an optional `timeoutMs`
+(default 120000, at most 21600000). A credential reaches Git only through the
+Git process environment as an `Authorization` header, so it never appears in
+the remote URL, on a command line, in the repository's Git config, or in an
+error. It requires an `https` remote without user information, and Git does
+not follow redirects while it carries one. A refresh reuses the mirror's stored
+remote URL.
+
+`IGitManagerRepositorySize` measures a repository's object database:
+`objectCount` distinct objects, `objectBytes` (their uncompressed sizes, which
+do not depend on packing) and `storageBytes` (every file of the object
+database, which does).
+
+### GitManager atomic push and default branch contracts
+
+`IGitManagerAtomicPushRequest` pushes `IGitManagerAtomicPushRefUpdate`s from a
+managed repository to `remoteUrl` as one transaction: the remote applies every
+update or none, and a remote that does not advertise the `atomic` capability is
+refused rather than pushed to ref by ref. Every update is leased:
+`expectedOldObjectId` is the object the remote ref must point at now (null to
+create a ref that must not exist), and `newObjectId` is the object to set (null
+to delete). The URL is used for that push only; it must be `https`, or `http` to
+a loopback host. The transfer options are those of `importMirror`, except that
+a push credential is also accepted for loopback `http`.
+
+`IGitManagerAtomicPushResult` is `applied` when every ref is `ok` and
+`rejected` when no ref changed. Each `IGitManagerAtomicPushRefResult` is `ok`,
+`stale` (the lease failed) or `rejected` (a hook, ref protection, or another
+ref of the same push failed), with the remote's reason as `message`.
+
+`IGitManagerSetDefaultBranchRequest` points a repository's HEAD at an existing
+branch, named as in `IGitManagerRepositoryInfo.defaultBranch`.
+
+### Origin contracts
+
+`TOriginState` records where a native entity came from: `native`, `imported`
+with an `IOriginRef`, or `unknown`, which never means native. An `IOriginRef`
+names the source by the operator-minted forge connection `instanceId`, the
+`entityKind` (`repository`), the source `entityId` (a Gitea repository's
+decimal ID) and `parentId` (null for repositories, whose Gitea IDs are unique
+per instance). It carries no URLs, paths, configuration or run IDs, digests, or
+authority.
+
 ### Forge inventory contracts
 
 `IForgeInventoryReport`, `IForgeInventoryPage<TItem>`, `IForgeInventoryNamespace`,
@@ -194,7 +242,7 @@ import fidelity, checksummed manifests, or durable recovery checkpoints.
 `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,
+type, and per repository the Git refs and objects, 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
@@ -209,6 +257,13 @@ 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.
 
+Git counts other than the forge-reported size, and LFS counts, are read at the
+Git level from a mirror clone of every advertised ref: refs by namespace,
+distinct objects and their uncompressed bytes, and the LFS objects that
+pointers in any reachable revision reference. LFS objects are checked through
+the forge's LFS batch API and split into held objects with their bytes and
+`missingObjects`, which cannot be migrated.
+
 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.
@@ -231,7 +286,7 @@ 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, forge and forge source inventories, 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/push API results, origin references, 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: '1.1.0',
+  version: '2.1.0',
   description: 'Shared TypeScript interfaces and TypedRequest contracts for the foss.global Git platform ecosystem.'
 }

package/ts/data/forgesourceinventory.ts

@@ -126,6 +126,10 @@ export interface IForgeSourceOwnerTotals {
   gpgKeys: TForgeSourceMeasure;
 }
 
+/**
+ * Ref and object counts read at the Git level, from a mirror clone of every
+ * ref the forge advertises, except `reportedSizeKiB`.
+ */
 export interface IForgeSourceGitCounts {
   /** As reported by the forge, in KiB; not a transfer size. */
   reportedSizeKiB: TForgeSourceMeasure;
@@ -134,11 +138,23 @@ export interface IForgeSourceGitCounts {
   /** Hidden refs that preserve pull request heads. */
   pullRequestRefs: TForgeSourceMeasure;
   otherRefs: TForgeSourceMeasure;
+  /** Distinct Git objects reachable from those refs. */
+  objects: TForgeSourceMeasure;
+  /** Sum of the uncompressed sizes of those objects; independent of how the forge packs them. */
+  objectBytes: TForgeSourceMeasure;
 }
 
+/**
+ * LFS objects that pointers in any reachable revision reference, by distinct
+ * object ID, checked for presence through the forge's LFS batch API.
+ */
 export interface IForgeSourceLfsCounts {
+  /** Referenced objects the forge holds. */
   objects: TForgeSourceMeasure;
+  /** Sizes of the objects the forge holds. */
   bytes: TForgeSourceMeasure;
+  /** Referenced objects the forge does not hold; they cannot be migrated. */
+  missingObjects: TForgeSourceMeasure;
 }
 
 export interface IForgeSourceCollaborationCounts {

package/ts/data/gitmanager.ts

@@ -29,10 +29,138 @@ export interface IGitManagerInitBareRepositoryRequest extends IGitManagerReposit
   defaultBranch?: string;
 }
 
-export interface IGitManagerImportMirrorRequest extends IGitManagerRepositorySelector {
+/**
+ * Points a repository's HEAD at an existing branch, which clones then check
+ * out by default.
+ */
+export interface IGitManagerSetDefaultBranchRequest extends IGitManagerRepositorySelector {
+  /** Branch name without `refs/heads/`, as in `IGitManagerRepositoryInfo.defaultBranch`; the branch must exist. */
+  defaultBranch: string;
+}
+
+/**
+ * HTTP Basic credentials for a remote Git transfer, such as a forge user name
+ * with an access token as the password. Neither part may contain control
+ * characters, and the user name may not contain `:`.
+ */
+export interface IGitManagerRemoteBasicCredential {
+  kind: 'basic';
+  username: string;
+  password: string;
+}
+
+export type TGitManagerRemoteCredential = IGitManagerRemoteBasicCredential;
+
+/**
+ * Options for one transfer from a remote repository.
+ *
+ * A credential reaches Git only through the Git process environment, as an
+ * `Authorization` header. It never appears in the remote URL, on a command
+ * line, in the repository's Git config, or in an error. A credential requires
+ * an `https` remote URL without user information, and Git does not follow
+ * HTTP redirects while it carries one.
+ */
+export interface IGitManagerRemoteTransferOptions {
+  credential?: TGitManagerRemoteCredential;
+  /**
+   * PEM certificates that Git uses as its CA bundle for this transfer, in
+   * place of the default bundle file, for a remote behind a private CA.
+   */
+  caCertificates?: string[];
+  /** Wall-clock limit for the transfer in milliseconds; defaults to 120000, at most 21600000 (six hours). */
+  timeoutMs?: number;
+}
+
+/**
+ * Clones every ref of a remote into a new mirror repository. The stored
+ * `remote.origin.url` is `remoteUrl`, so it must never carry credentials;
+ * pass them as `credential`.
+ */
+export interface IGitManagerImportMirrorRequest extends IGitManagerRepositorySelector, IGitManagerRemoteTransferOptions {
   remoteUrl: string;
 }
 
+/** Fetches every ref of an imported mirror's remote again, pruning refs the remote no longer has. */
+export interface IGitManagerRefreshMirrorRequest extends IGitManagerRepositorySelector, IGitManagerRemoteTransferOptions {}
+
+/**
+ * One ref change of an atomic push, guarded by a lease: the remote applies it
+ * only while its ref still points at `expectedOldObjectId`. Both object IDs
+ * are full hexadecimal object IDs; at least one of them is non-null.
+ */
+export interface IGitManagerAtomicPushRefUpdate {
+  /** Full ref name on the remote, for example `refs/heads/main`. */
+  ref: string;
+  /** Object the remote ref must point at now; null creates the ref, which must not exist. */
+  expectedOldObjectId: string | null;
+  /** Object to set the remote ref to, present in the managed repository; null deletes the ref. */
+  newObjectId: string | null;
+}
+
+/**
+ * Pushes ref updates from a managed repository to a remote as one atomic
+ * transaction: the remote applies every update or none. The remote must
+ * advertise the `atomic` receive-pack capability; without it the push fails
+ * before any ref is sent and never falls back to ref-by-ref updates.
+ *
+ * `remoteUrl` is used for this push only and is never stored in the
+ * repository. It must be `https`, or `http` to a loopback host
+ * (`127.0.0.0/8`, `::1` or `localhost`); `ssh`, `git`, `file` and scp-like
+ * URLs are refused. Transfer options behave as for `importMirror`, except
+ * that a push credential is also accepted for `http` to a loopback host, which
+ * never leaves the machine; the URL must not carry user information.
+ */
+export interface IGitManagerAtomicPushRequest extends IGitManagerRepositorySelector, IGitManagerRemoteTransferOptions {
+  remoteUrl: string;
+  /** Updates of distinct refs; at least one. */
+  updates: IGitManagerAtomicPushRefUpdate[];
+}
+
+/**
+ * Outcome of one ref as the remote reported it. `stale` means the lease
+ * failed: the remote ref did not point at the expected object. `rejected`
+ * covers every other refusal, such as a hook or ref protection, and also the
+ * refs the remote refused only because another ref of the same atomic push
+ * failed.
+ */
+export type TGitManagerAtomicPushRefStatus = 'ok' | 'rejected' | 'stale';
+
+export interface IGitManagerAtomicPushRefResult {
+  ref: string;
+  status: TGitManagerAtomicPushRefStatus;
+  /** Reason text the remote reported for the ref, when it gave one; credentials are redacted. */
+  message?: string;
+}
+
+/**
+ * Result of an atomic push. `applied` means every ref is `ok`; `rejected`
+ * means no ref changed on the remote, and `refs` says why.
+ */
+export interface IGitManagerAtomicPushResult extends IGitManagerRepositorySelector {
+  status: 'applied' | 'rejected';
+  /** One result per requested update, in request order. */
+  refs: IGitManagerAtomicPushRefResult[];
+}
+
+/**
+ * The object database of one repository when it was measured. Objects of
+ * alternate object stores are not counted.
+ */
+export interface IGitManagerRepositorySize extends IGitManagerRepositorySelector {
+  /** Distinct commits, trees, blobs and annotated tags, reachable or not. */
+  objectCount: number;
+  /**
+   * Sum of the uncompressed sizes of those objects. It does not depend on
+   * how the objects are packed, so equal object sets give equal values.
+   */
+  objectBytes: number;
+  /**
+   * Bytes of every file in the object database: loose objects, packs, their
+   * indexes and other pack metadata. It depends on packing.
+   */
+  storageBytes: number;
+}
+
 /**
  * One page request of a repository's complete ref inventory.
  *

package/ts/data/index.ts

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

package/ts/data/origin.ts

@@ -0,0 +1,33 @@
+/** Kinds of source entity an import records its origin for. */
+export type TOriginEntityKind = 'repository';
+
+/**
+ * Identity of the source entity a native entity was imported from.
+ *
+ * It names the source by stable identifiers only. It carries no URLs, paths,
+ * configuration or run IDs, digests, or authority: it neither locates the
+ * source nor grants access to it.
+ */
+export interface IOriginRef {
+  /** Operator-minted instanceId of the forge connection the entity was imported from. */
+  instanceId: string;
+  entityKind: TOriginEntityKind;
+  /** Source row ID as an opaque string; for a Gitea repository, its decimal repository ID. */
+  entityId: string;
+  /**
+   * Source ID of the parent when entity IDs are parent-scoped; otherwise null.
+   * Null for repositories, because Gitea repository IDs are unique within an
+   * instance. Later entity kinds define their parent.
+   */
+  parentId: string | null;
+}
+
+/**
+ * Where a native entity came from: created natively, imported from a
+ * recorded source, or not known, for example for an entity that predates
+ * origin tracking. `unknown` must never be read as `native`.
+ */
+export type TOriginState =
+  | { kind: 'native' }
+  | { kind: 'imported'; origin: IOriginRef }
+  | { kind: 'unknown' };