@foss.global/interfaces 0.3.0 → 0.4.0

package/changelog.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 2026-07-20 - 0.4.0
+
+### Features
+
+- add runner protocol and CI control-plane contracts (ci)
+  - Define protocol versioning, runner registration, sessions, heartbeats, job leasing, fencing, logs, completion, abandonment, and recovery DTOs.
+  - Define CI job enqueue, status, log page, cancellation, and runner drain DTOs.
+  - Describe OCI runner capabilities including the initial archive, artifact, cache, service-container, and network support boundaries.
+
+### Maintenance
+
+- update the repository package manager and development tooling patch versions (tooling)
+
 ## 2026-06-23 - 0.3.0
 
 ### Features

package/dist_ts/00_commitinfo_data.js

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

@@ -1,3 +1,4 @@
 export * from './codefeed.js';
 export * from './gitmanager.js';
 export * from './public.js';
+export * from './runner.js';

package/dist_ts/data/index.js

@@ -1,4 +1,5 @@
 export * from './codefeed.js';
 export * from './gitmanager.js';
 export * from './public.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsZUFBZSxDQUFDO0FBQzlCLGNBQWMsaUJBQWlCLENBQUM7QUFDaEMsY0FBYyxhQUFhLENBQUMifQ==
+export * from './runner.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsZUFBZSxDQUFDO0FBQzlCLGNBQWMsaUJBQWlCLENBQUM7QUFDaEMsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxhQUFhLENBQUMifQ==

package/dist_ts/data/runner.d.ts

@@ -0,0 +1,189 @@
+export declare const runnerProtocolVersion: "1";
+export type TRunnerProtocolVersion = typeof runnerProtocolVersion;
+export type TOciRuntime = 'docker' | 'podman';
+export type TJobNetwork = 'none' | 'bridge';
+export type TLogStream = 'stdout' | 'stderr' | 'runner';
+export type TJobCompletionStatus = 'succeeded' | 'failed' | 'canceled' | 'timed_out' | 'system_error';
+export type TCiJobState = 'queued' | 'running' | TJobCompletionStatus;
+export interface IRunnerCredential {
+    runnerId: string;
+    runnerToken: string;
+    runnerTokenExpiresAt: string;
+}
+export interface IRunnerCapabilities {
+    executor: 'oci';
+    runtime: TOciRuntime;
+    networks: TJobNetwork[];
+    sourceArchives: ['tar.gz'];
+    artifacts: false;
+    caches: false;
+    serviceContainers: false;
+}
+export interface IRegisterRunnerRequest {
+    registrationRequestId: string;
+    protocolVersion: string;
+    runnerVersion: string;
+    name: string;
+    labels: string[];
+    capabilities: IRunnerCapabilities;
+}
+export interface IRegisterRunnerResponse extends IRunnerCredential {
+    protocolVersion: string;
+    serverTime: string;
+}
+export interface IStartSessionRequest {
+    sessionRequestId: string;
+    runnerId: string;
+    protocolVersion: string;
+    runnerVersion: string;
+    capabilities: IRunnerCapabilities;
+}
+export interface IStartSessionResponse {
+    sessionId: string;
+    protocolVersion: string;
+    serverTime: string;
+    credential?: IRunnerCredential;
+}
+export interface IRunnerHeartbeatRequest {
+    runnerId: string;
+    sessionId: string;
+}
+export interface IRunnerHeartbeatResponse {
+    serverTime: string;
+    drainRequested: boolean;
+    credential?: IRunnerCredential;
+}
+export interface IJobResources {
+    memoryBytes?: number;
+    cpus?: number;
+    pids?: number;
+}
+export interface IJobSourceArchive {
+    format: 'tar.gz';
+    url: string;
+    sha256: string;
+}
+export interface IJobSpec {
+    image: string;
+    command: string[];
+    environment?: Record<string, string>;
+    secrets?: Record<string, string>;
+    network?: TJobNetwork;
+    timeoutMs?: number;
+    resources?: IJobResources;
+    source?: IJobSourceArchive;
+}
+export interface IJobLease {
+    jobId: string;
+    attemptId: string;
+    leaseId: string;
+    fencingToken: string;
+    leaseExpiresAt: string;
+    job: IJobSpec;
+}
+export interface IClaimJobRequest {
+    claimRequestId: string;
+    runnerId: string;
+    sessionId: string;
+    labels: string[];
+}
+export interface IClaimJobResponse {
+    serverTime: string;
+    retryAfterMs?: number;
+    lease: IJobLease | null;
+}
+export interface IJobMutationIdentity {
+    runnerId: string;
+    sessionId: string;
+    jobId: string;
+    attemptId: string;
+    leaseId: string;
+    fencingToken: string;
+}
+export interface IJobHeartbeatResponse {
+    serverTime: string;
+    leaseExpiresAt: string;
+    cancelRequested: boolean;
+}
+export interface ILogChunk extends IJobMutationIdentity {
+    sequence: number;
+    stream: TLogStream;
+    data: string;
+    timestamp: string;
+}
+export interface ILogAcknowledgement {
+    serverTime: string;
+    nextSequence: number;
+}
+export interface ICompleteJobRequest extends IJobMutationIdentity {
+    status: TJobCompletionStatus;
+    exitCode: number | null;
+    startedAt: string;
+    completedAt: string;
+    error?: string;
+}
+export interface ICompleteJobResponse {
+    serverTime: string;
+    accepted: boolean;
+}
+export interface IAbandonJobRequest extends IJobMutationIdentity {
+    reason: 'runner_shutdown' | 'runner_error';
+}
+export interface IRecoverAttemptRequest extends IJobMutationIdentity {
+    currentSessionId: string;
+    reason: 'runner_restarted';
+}
+export interface ICiEnqueueJobRequest {
+    idempotencyKey: string;
+    tenantId: string;
+    repositoryId: string;
+    requiredLabels: string[];
+    job: IJobSpec;
+}
+export interface ICiEnqueueJobResponse {
+    jobId: string;
+    state: TCiJobState;
+    createdAt: string;
+    duplicate: boolean;
+}
+export interface ICiJobSummary {
+    jobId: string;
+    tenantId: string;
+    repositoryId: string;
+    state: TCiJobState;
+    image: string;
+    requiredLabels: string[];
+    attemptNumber: number;
+    cancelRequested: boolean;
+    createdAt: string;
+    updatedAt: string;
+    startedAt?: string;
+    completedAt?: string;
+    completionStatus?: TJobCompletionStatus;
+    exitCode?: number | null;
+    error?: string;
+}
+export interface ICiLogEntry {
+    sequence: number;
+    stream: TLogStream;
+    data: string;
+    timestamp: string;
+}
+export interface ICiLogPage {
+    jobId: string;
+    attemptId: string;
+    entries: ICiLogEntry[];
+    nextSequence: number | null;
+}
+export interface ICiCancelJobResponse {
+    jobId: string;
+    state: TCiJobState;
+    cancelRequested: boolean;
+}
+export interface ICiSetRunnerDrainRequest {
+    drainRequested: boolean;
+}
+export interface ICiSetRunnerDrainResponse {
+    runnerId: string;
+    drainRequested: boolean;
+}

package/dist_ts/data/runner.js

@@ -0,0 +1,2 @@
+export const runnerProtocolVersion = '1';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicnVubmVyLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vdHMvZGF0YS9ydW5uZXIudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsTUFBTSxDQUFDLE1BQU0scUJBQXFCLEdBQUcsR0FBWSxDQUFDIn0=

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foss.global/interfaces",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "private": false,
   "description": "Shared TypeScript interfaces and TypedRequest contracts for the foss.global Git platform ecosystem.",
   "exports": {
@@ -15,9 +15,9 @@
   "devDependencies": {
     "@git.zone/tsbuild": "^4.4.2",
     "@git.zone/tsdoc": "^2.1.1",
-    "@git.zone/tsrun": "^2.0.4",
+    "@git.zone/tsrun": "^2.0.5",
     "@git.zone/tstest": "^3.6.6",
-    "@types/node": "^26.0.0"
+    "@types/node": "^26.1.1"
   },
   "files": [
     "ts/**/*",

package/readme.md

@@ -47,9 +47,57 @@ const repo: data.IPublicRepo = {
 type PublicOverviewRequest = requests.IReq_PublicOverview;
 ```
 
+### Runner and CI contracts
+
+Runner protocol v1 is exposed through `runnerProtocolVersion`. The package root and the `data` namespace both export the complete runner and CI DTO set:
+
+```ts
+import {
+  runnerProtocolVersion,
+  type IClaimJobResponse,
+  type ICiEnqueueJobRequest,
+  type IRegisterRunnerRequest,
+} from '@foss.global/interfaces';
+
+const registration: IRegisterRunnerRequest = {
+  registrationRequestId: 'registration-1',
+  protocolVersion: runnerProtocolVersion,
+  runnerVersion: '0.1.0',
+  name: 'linux-amd64-1',
+  labels: ['linux', 'amd64'],
+  capabilities: {
+    executor: 'oci',
+    runtime: 'docker',
+    networks: ['none', 'bridge'],
+    sourceArchives: ['tar.gz'],
+    artifacts: false,
+    caches: false,
+    serviceContainers: false,
+  },
+};
+
+const enqueue: ICiEnqueueJobRequest = {
+  idempotencyKey: 'build-main-1',
+  tenantId: 'foss.global',
+  repositoryId: 'foss.global/interfaces',
+  requiredLabels: ['linux', 'amd64'],
+  job: {
+    image: 'node:24',
+    command: ['pnpm', 'test'],
+    network: 'none',
+  },
+};
+
+type ClaimedJob = IClaimJobResponse;
+```
+
+The runner lifecycle contracts cover registration, sessions, runner and job heartbeats, claim/lease identity, fencing tokens, ordered log chunks, completion, abandonment, and recovery. The CI control-plane contracts cover job enqueue and summaries, log pages, cancellation, and runner drain state.
+
+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.
+
 ## Exports
 
-- `data`: public DTOs for users, organizations, repositories, contents, commits, diffs, releases, issues, activity, news, stats, codefeed commit results, and GitManager repository/read API results.
+- `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.
 - `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.3.0',
+  version: '0.4.0',
   description: 'Shared TypeScript interfaces and TypedRequest contracts for the foss.global Git platform ecosystem.'
 }

package/ts/data/index.ts

@@ -1,3 +1,4 @@
 export * from './codefeed.js';
 export * from './gitmanager.js';
 export * from './public.js';
+export * from './runner.js';

package/ts/data/runner.ts

@@ -0,0 +1,225 @@
+export const runnerProtocolVersion = '1' as const;
+
+export type TRunnerProtocolVersion = typeof runnerProtocolVersion;
+export type TOciRuntime = 'docker' | 'podman';
+export type TJobNetwork = 'none' | 'bridge';
+export type TLogStream = 'stdout' | 'stderr' | 'runner';
+export type TJobCompletionStatus =
+  | 'succeeded'
+  | 'failed'
+  | 'canceled'
+  | 'timed_out'
+  | 'system_error';
+export type TCiJobState = 'queued' | 'running' | TJobCompletionStatus;
+
+export interface IRunnerCredential {
+  runnerId: string;
+  runnerToken: string;
+  runnerTokenExpiresAt: string;
+}
+
+export interface IRunnerCapabilities {
+  executor: 'oci';
+  runtime: TOciRuntime;
+  networks: TJobNetwork[];
+  sourceArchives: ['tar.gz'];
+  artifacts: false;
+  caches: false;
+  serviceContainers: false;
+}
+
+export interface IRegisterRunnerRequest {
+  registrationRequestId: string;
+  protocolVersion: string;
+  runnerVersion: string;
+  name: string;
+  labels: string[];
+  capabilities: IRunnerCapabilities;
+}
+
+export interface IRegisterRunnerResponse extends IRunnerCredential {
+  protocolVersion: string;
+  serverTime: string;
+}
+
+export interface IStartSessionRequest {
+  sessionRequestId: string;
+  runnerId: string;
+  protocolVersion: string;
+  runnerVersion: string;
+  capabilities: IRunnerCapabilities;
+}
+
+export interface IStartSessionResponse {
+  sessionId: string;
+  protocolVersion: string;
+  serverTime: string;
+  credential?: IRunnerCredential;
+}
+
+export interface IRunnerHeartbeatRequest {
+  runnerId: string;
+  sessionId: string;
+}
+
+export interface IRunnerHeartbeatResponse {
+  serverTime: string;
+  drainRequested: boolean;
+  credential?: IRunnerCredential;
+}
+
+export interface IJobResources {
+  memoryBytes?: number;
+  cpus?: number;
+  pids?: number;
+}
+
+export interface IJobSourceArchive {
+  format: 'tar.gz';
+  url: string;
+  sha256: string;
+}
+
+export interface IJobSpec {
+  image: string;
+  command: string[];
+  environment?: Record<string, string>;
+  secrets?: Record<string, string>;
+  network?: TJobNetwork;
+  timeoutMs?: number;
+  resources?: IJobResources;
+  source?: IJobSourceArchive;
+}
+
+export interface IJobLease {
+  jobId: string;
+  attemptId: string;
+  leaseId: string;
+  fencingToken: string;
+  leaseExpiresAt: string;
+  job: IJobSpec;
+}
+
+export interface IClaimJobRequest {
+  claimRequestId: string;
+  runnerId: string;
+  sessionId: string;
+  labels: string[];
+}
+
+export interface IClaimJobResponse {
+  serverTime: string;
+  retryAfterMs?: number;
+  lease: IJobLease | null;
+}
+
+export interface IJobMutationIdentity {
+  runnerId: string;
+  sessionId: string;
+  jobId: string;
+  attemptId: string;
+  leaseId: string;
+  fencingToken: string;
+}
+
+export interface IJobHeartbeatResponse {
+  serverTime: string;
+  leaseExpiresAt: string;
+  cancelRequested: boolean;
+}
+
+export interface ILogChunk extends IJobMutationIdentity {
+  sequence: number;
+  stream: TLogStream;
+  data: string;
+  timestamp: string;
+}
+
+export interface ILogAcknowledgement {
+  serverTime: string;
+  nextSequence: number;
+}
+
+export interface ICompleteJobRequest extends IJobMutationIdentity {
+  status: TJobCompletionStatus;
+  exitCode: number | null;
+  startedAt: string;
+  completedAt: string;
+  error?: string;
+}
+
+export interface ICompleteJobResponse {
+  serverTime: string;
+  accepted: boolean;
+}
+
+export interface IAbandonJobRequest extends IJobMutationIdentity {
+  reason: 'runner_shutdown' | 'runner_error';
+}
+
+export interface IRecoverAttemptRequest extends IJobMutationIdentity {
+  currentSessionId: string;
+  reason: 'runner_restarted';
+}
+
+export interface ICiEnqueueJobRequest {
+  idempotencyKey: string;
+  tenantId: string;
+  repositoryId: string;
+  requiredLabels: string[];
+  job: IJobSpec;
+}
+
+export interface ICiEnqueueJobResponse {
+  jobId: string;
+  state: TCiJobState;
+  createdAt: string;
+  duplicate: boolean;
+}
+
+export interface ICiJobSummary {
+  jobId: string;
+  tenantId: string;
+  repositoryId: string;
+  state: TCiJobState;
+  image: string;
+  requiredLabels: string[];
+  attemptNumber: number;
+  cancelRequested: boolean;
+  createdAt: string;
+  updatedAt: string;
+  startedAt?: string;
+  completedAt?: string;
+  completionStatus?: TJobCompletionStatus;
+  exitCode?: number | null;
+  error?: string;
+}
+
+export interface ICiLogEntry {
+  sequence: number;
+  stream: TLogStream;
+  data: string;
+  timestamp: string;
+}
+
+export interface ICiLogPage {
+  jobId: string;
+  attemptId: string;
+  entries: ICiLogEntry[];
+  nextSequence: number | null;
+}
+
+export interface ICiCancelJobResponse {
+  jobId: string;
+  state: TCiJobState;
+  cancelRequested: boolean;
+}
+
+export interface ICiSetRunnerDrainRequest {
+  drainRequested: boolean;
+}
+
+export interface ICiSetRunnerDrainResponse {
+  runnerId: string;
+  drainRequested: boolean;
+}