@foss.global/interfaces 0.12.0 → 1.0.0

package/changelog.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 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
+
+- add issue observation contract (forgeinventory)
+  - Add IForgeInventoryIssue for provider issue identity, repository-local numbers, metadata, author identity and timestamps.
+  - Document issue inventory semantics and add type-level round-trip contract coverage.
+
 ## 2026-09-04 - 0.12.0
 
 ### Features

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@foss.global/interfaces',
-    version: '0.12.0',
+    version: '1.0.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/forgeinventory.d.ts

@@ -79,6 +79,30 @@ export interface IForgeInventoryRepository {
     /** Git storage bytes only; never an admission estimate for an outgoing push. */
     gitSizeBytes: TForgeInventoryQuantity;
 }
+/** Issue metadata observed from a provider, never a complete historical import payload. */
+export interface IForgeInventoryIssue {
+    /** Provider row identity; an issue's displayed number is a separate locator. */
+    identity: TForgeInventoryIdentity;
+    repository: TForgeInventoryIdentity;
+    location: IForgeInventoryLocation;
+    /** Canonical positive decimal repository-local number (GitLab iid). */
+    number: string;
+    title: string;
+    /** Provider text verbatim, including empty text; null means not exposed. */
+    body: string | null;
+    state: 'open' | 'closed' | null;
+    /** Provider issue classification, such as GitLab issue/incident/task; null if unknown. */
+    providerType: string | null;
+    /** null means unknown or unsupported, never implicit public visibility. */
+    confidential: boolean | null;
+    /** Reported provider author identity; does not establish an imported original author. */
+    author: TForgeInventoryIdentity;
+    /** ISO 8601 provider content times, distinct from inventory observation times. */
+    createdAt: string | null;
+    updatedAt: string | null;
+    /** null means no observed close time; state determines whether the issue is open. */
+    closedAt: string | null;
+}
 export type TForgeInventoryEntityClass = 'namespaces' | 'users' | 'teams' | 'memberships' | 'repositories' | 'gitRefs' | 'gitObjects' | 'protectedRefs' | 'publicSshKeys' | 'deployKeys' | 'issues' | 'issueComments' | 'pullRequests' | 'reviews' | 'reviewComments' | 'labels' | 'milestones' | 'assignees' | 'reactions' | 'releases' | 'releaseAssets' | 'lfsObjects' | 'packages' | 'packageVersions' | 'packageBlobs' | 'webhooks' | 'webhookDeliveries' | 'ciWorkflows' | 'ciRuns' | 'ciArtifacts' | 'wikis' | 'projects';
 /** Availability of an inventory read, never a claim of write/import fidelity. */
 export type TForgeInventoryCapability = {

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foss.global/interfaces",
-  "version": "0.12.0",
+  "version": "1.0.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": "^5.0.0",
+    "@git.zone/tsdoc": "^2.2.2",
+    "@git.zone/tsrun": "^3.0.0",
+    "@git.zone/tstest": "^6.2.0",
+    "@types/node": "^26.6.1"
   },
   "files": [
     "ts/**/*",

package/readme.md

@@ -95,10 +95,68 @@ 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`,
-and `IForgeInventoryRepository` describe operator inventory observations. They
+`IForgeInventoryRepository` and `IForgeInventoryIssue` describe operator inventory observations. They
 are exported from both the package root and `data`. This package supplies types;
 it does not scan a forge or validate network responses.
 
@@ -108,6 +166,15 @@ subgroups and literal hyphens. A source without a stable identifier reports an
 unresolved identity. URLs must be credential-free, and inventory responses need
 operator authorization rather than anonymous public exposure.
 
+Issue observations separate the provider row ID from its repository-local
+`number` (GitLab `iid`) and retain the repository identity. They preserve empty
+body text, unknown metadata, open/closed state, provider issue classification,
+confidentiality, reported author identity and provider content timestamps.
+The reported author does not prove original attribution for previously imported
+issues. Comments, labels, milestones, assignees, attachments and history require
+their own inventory and preservation work; this metadata DTO does not claim
+that those collections or external writes are implemented.
+
 Every canonical entity class has an explicit capability and collection result,
 including classes not inspected or unavailable. Additional provider features
 have their own entries. `enumerated` means the selected collection was exhausted

package/ts/00_commitinfo_data.ts

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

package/ts/data/forgeinventory.ts

@@ -81,6 +81,31 @@ export interface IForgeInventoryRepository {
   gitSizeBytes: TForgeInventoryQuantity;
 }
 
+/** Issue metadata observed from a provider, never a complete historical import payload. */
+export interface IForgeInventoryIssue {
+  /** Provider row identity; an issue's displayed number is a separate locator. */
+  identity: TForgeInventoryIdentity;
+  repository: TForgeInventoryIdentity;
+  location: IForgeInventoryLocation;
+  /** Canonical positive decimal repository-local number (GitLab iid). */
+  number: string;
+  title: string;
+  /** Provider text verbatim, including empty text; null means not exposed. */
+  body: string | null;
+  state: 'open' | 'closed' | null;
+  /** Provider issue classification, such as GitLab issue/incident/task; null if unknown. */
+  providerType: string | null;
+  /** null means unknown or unsupported, never implicit public visibility. */
+  confidential: boolean | null;
+  /** Reported provider author identity; does not establish an imported original author. */
+  author: TForgeInventoryIdentity;
+  /** ISO 8601 provider content times, distinct from inventory observation times. */
+  createdAt: string | null;
+  updatedAt: string | null;
+  /** null means no observed close time; state determines whether the issue is open. */
+  closedAt: string | null;
+}
+
 export type TForgeInventoryEntityClass =
   | 'namespaces'
   | 'users'

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';