@kici-dev/orchestrator 0.14.2 → 0.16.0

package/dist/db/deferred-indexes.d.ts

@@ -16,15 +16,10 @@
  * a failed build retries on the next boot.
  *
  * A repository check enforces that new indexes on those tables land here
- * rather than in a migration.
+ * rather than in a migration. The build itself is `deferred-index-build.ts`;
+ * this module holds only the list, so a CLI can read it without loading the
+ * orchestrator's metrics.
  */
-import type pg from 'pg';
-import { type Logger } from '@kici-dev/shared';
-/**
- * Distinct from the migrator's `543210001`: an index build must not block, or
- * be blocked by, a peer applying migrations.
- */
-export declare const DEFERRED_INDEX_LOCK_KEY = 543210002;
 export interface DeferredIndex {
     /** Index name, matching the one the SQL creates. */
     name: string;
@@ -40,33 +35,4 @@ export interface DeferredIndex {
  * prefixed by an organization or routing key.
  */
 export declare const DEFERRED_INDEXES: ReadonlyArray<DeferredIndex>;
-/**
- * Drop a leftover invalid index before rebuilding it.
- *
- * An interrupted `CREATE INDEX CONCURRENTLY` leaves the index in place marked
- * invalid: it is not used by the planner, and `IF NOT EXISTS` sees it and
- * skips. Without this, the very first failed build would make the retry a
- * permanent no-op — the opposite of the "retries on the next boot" contract.
- */
-export declare function dropIfInvalid(client: Pick<pg.Client, 'query'>, name: string, logger: Logger): Promise<void>;
-export interface BuildDeferredIndexesResult {
-    built: string[];
-    failed: string[];
-}
-/**
- * Build every deferred index on one dedicated connection.
- *
- * The connection is taken straight from `pg` rather than from the serving
- * pool: `CREATE INDEX CONCURRENTLY` must run outside a transaction and must
- * not inherit a statement timeout, and a concurrent build on a large table
- * would otherwise hold a serving connection for its whole duration.
- *
- * The advisory lock is `pg_try_advisory_lock`, not the blocking form: when a
- * peer is already building, this instance has nothing to wait for.
- */
-export declare function buildDeferredIndexes(databaseUrl: string, opts?: {
-    logger?: Logger;
-    indexes?: ReadonlyArray<DeferredIndex>;
-    pg?: typeof import('pg');
-}): Promise<BuildDeferredIndexesResult>;
 //# sourceMappingURL=deferred-indexes.d.ts.map

package/dist/db/migrations/100_held_runs_hold_type_vocabulary.d.ts

@@ -8,11 +8,9 @@ import { type Kysely } from 'kysely';
  * unknown-type badge — and two semantically identical wait holds render
  * differently depending on which gate produced them.
  *
- * Writers emit the gate vocabulary; this backfills the history. The read path
- * also normalizes (`normalizePersistedHoldType`) and the wait-hold release
- * sweep matches both spellings, so a row written by an un-upgraded
- * orchestrator behaves correctly whether or not this has run — the two sides
- * deploy independently.
+ * Writers emit the gate vocabulary; this backfills the history. Migration 158
+ * re-applies the same rewrite, after which the readers match the gate
+ * vocabulary only.
  *
  * Idempotent: a second run matches no rows.
  */

package/dist/db/migrations/157_host_roster_identity_source.d.ts

@@ -0,0 +1,21 @@
+import { type Kysely } from 'kysely';
+/**
+ * Add `host_roster.identity_source text NOT NULL DEFAULT 'operator'`, limited
+ * to `agent`, `operator` and `platform`.
+ *
+ * It records who last set a host's identity (labels, hostname, properties):
+ * the host's own agent registration, a local `kici-admin host declare`, or a
+ * Platform-relayed dashboard declare. A `platform` row is an unconfirmed
+ * placeholder that fan-out, inventory and the unreachable alarm skip.
+ *
+ * Backfill: a row whose `platform` column is set has registered at least once
+ * (only an agent registration writes `platform`), so it becomes `agent`. Every
+ * other row stays `operator`: a dashboard-created row from before this column
+ * cannot be told apart from a `kici-admin` declare, and treating it as
+ * `platform` would drop every declared, never-connected host out of fan-out.
+ *
+ * Idempotent: a re-run on a database that already has the column is a no-op.
+ */
+export declare function up(db: Kysely<unknown>): Promise<void>;
+export declare function down(db: Kysely<unknown>): Promise<void>;
+//# sourceMappingURL=157_host_roster_identity_source.d.ts.map

package/dist/db/migrations/158_normalize_legacy_values.d.ts

@@ -0,0 +1,4 @@
+import { type Kysely } from 'kysely';
+export declare function up(db: Kysely<unknown>): Promise<void>;
+export declare function down(): Promise<void>;
+//# sourceMappingURL=158_normalize_legacy_values.d.ts.map

package/dist/db/repos/org-ids-repo.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The org ids this orchestrator holds data for, and which data names each one.
+ *
+ * The org-scoped kici-admin commands (`secret`, `context`, `variable`,
+ * `remote-source`, `org-settings`, `trust-policy`, `registration`) take an org
+ * id. This module answers "which org ids exist here" from the configuration and
+ * anchor tables, for both `GET /api/v1/admin/org-ids` and
+ * `kici-admin org list --database-url`, so the two transports cannot disagree.
+ */
+import { type Kysely } from 'kysely';
+import { z } from 'zod';
+import type { Database } from '../types.js';
+/**
+ * Where an org id was found. `platform` is the live Platform connection, which
+ * only the admin API can see; every other value names a table.
+ */
+export declare const OrgIdSource: z.ZodEnum<{
+    context: "context";
+    "generic-source": "generic-source";
+    "org-settings": "org-settings";
+    platform: "platform";
+    registration: "registration";
+    "remote-source": "remote-source";
+    secret: "secret";
+    source: "source";
+    "trust-policy": "trust-policy";
+}>;
+export type OrgIdSource = z.infer<typeof OrgIdSource>;
+/**
+ * The orchestrator's Platform attachment: `attached` once the Platform named
+ * the org on `auth.success`, `pending` while a Platform client has not
+ * authenticated yet, `none` when no Platform client runs (independent mode).
+ */
+export declare const PlatformAttachment: z.ZodEnum<{
+    attached: "attached";
+    none: "none";
+    pending: "pending";
+}>;
+export type PlatformAttachment = z.infer<typeof PlatformAttachment>;
+/** One org id and the data that names it. */
+export interface HeldOrg {
+    orgId: string;
+    sources: OrgIdSource[];
+}
+/**
+ * Body of `GET /api/v1/admin/org-ids`. The two Platform fields are absent when the
+ * listing was read from the database directly: only the running orchestrator
+ * knows its connection.
+ */
+export interface OrgListResponse {
+    platformAttachment?: PlatformAttachment;
+    attachedOrgId?: string | null;
+    orgs: HeldOrg[];
+}
+/** The admin API path of the listing. */
+export declare const ORG_LIST_PATH = "/api/v1/admin/org-ids";
+interface OrgIdTable {
+    table: keyof Database;
+    column: 'org_id' | 'customer_id';
+    source: Exclude<OrgIdSource, 'platform'>;
+    /** Skip soft-deleted rows (`deleted_at IS NULL`). */
+    liveOnly?: boolean;
+}
+/** The configuration and anchor tables an org-scoped command reads by org id. */
+export declare const ORG_ID_TABLES: readonly OrgIdTable[];
+/**
+ * Every other table with an `org_id` or `customer_id` column, and why the
+ * listing does not read it. A schema test fails when a migration adds an
+ * org-keyed table that is in neither this map nor {@link ORG_ID_TABLES}.
+ */
+export declare const ORG_ID_TABLES_NOT_LISTED: Readonly<Record<string, string>>;
+/** Group `(org id, source)` rows per org: org ids in byte order, sources in enum order. */
+export declare function groupOrgIdRows(rows: ReadonlyArray<{
+    org_id: string;
+    source: OrgIdSource;
+}>): HeldOrg[];
+/** Add the Platform-attached org to a listing, with the `platform` source. */
+export declare function withPlatformOrg(orgs: readonly HeldOrg[], attachedOrgId: string | null): HeldOrg[];
+/** The attachment the admin API reports, from the Platform client's org id reader. */
+export declare function readPlatformAttachment(getPlatformOrgId: (() => string | undefined) | undefined): {
+    platformAttachment: PlatformAttachment;
+    attachedOrgId: string | null;
+};
+/** Every org id the listed tables hold, in one round trip. */
+export declare function listHeldOrgIds(db: Kysely<Database>): Promise<HeldOrg[]>;
+export {};
+//# sourceMappingURL=org-ids-repo.d.ts.map

package/dist/db/schema-snapshot.generated.d.ts

@@ -0,0 +1,3 @@
+import type { SchemaFingerprint } from '@kici-dev/shared';
+export declare const SCHEMA_SNAPSHOT: SchemaFingerprint;
+//# sourceMappingURL=schema-snapshot.generated.d.ts.map

package/dist/db/types.d.ts

@@ -13,6 +13,17 @@ export declare enum JobKind {
     Gate = "gate",
     Proxy = "proxy"
 }
+/**
+ * Who last set a roster host's identity (labels, hostname, properties).
+ * `platform` marks an unconfirmed placeholder created from the dashboard: it
+ * is never a fan-out, inventory, agent-pin or unreachable-alarm target until
+ * its agent registers (`agent`) or an operator declares it (`operator`).
+ */
+export declare enum HostIdentitySource {
+    agent = "agent",
+    operator = "operator",
+    platform = "platform"
+}
 /**
  * PostgreSQL-only database types.
  * Column names use snake_case matching the actual database column names.
@@ -187,8 +198,9 @@ export type ClusterMeta = Selectable<ClusterMetaTable>;
 export type NewClusterMeta = Insertable<ClusterMetaTable>;
 /**
  * Join tokens table
- * Stores hashed join tokens for zero-knowledge cluster bootstrap.
- * Tokens are one-time use (consumed_at set after validation).
+ * Stores hashed join tokens. `kici-admin join` and peer token mode find a row by
+ * its hash; a token is consumed on first use and re-usable by the instance that
+ * consumed it until it expires.
  */
 export interface JoinTokenTable {
     /** UUID primary key */
@@ -1200,8 +1212,7 @@ export interface HeldRunsTable {
     /**
      * Hold type — an engine `HoldType` member ('reviewer' | 'timer' |
      * 'concurrency' | 'security'). Stays `string` so a row written by a
-     * different orchestrator version is never rejected; read it through
-     * `normalizePersistedHoldType`.
+     * different orchestrator version is never rejected.
      */
     hold_type: string;
     /** Hold status: 'pending' | 'approved' | 'rejected' | 'expired' | 'released' */
@@ -1232,7 +1243,8 @@ export interface HeldRunsTable {
     trigger_source: Generated<string>;
     /**
      * Normalized `ApprovalRequirement` (clauses + expiresAt + reason) the hold
-     * must satisfy. Null for legacy rows that predate the approval model.
+     * must satisfy. Null for a hold with no requirement: security, wait and queue
+     * holds, which `security-hold-check.ts` tells apart on this column.
      */
     approval_requirement: ColumnType<ApprovalRequirement | null, ApprovalRequirement | string | null | undefined, ApprovalRequirement | string | null>;
     /**
@@ -2070,25 +2082,8 @@ export interface OrgTrustPolicyTable {
     customer_id: string;
     /** How to treat a pull request opened from a fork: ignore | hold | allow */
     fork_policy: string;
-    /**
-     * The coarse, hours-granularity view of the security-hold window.
-     *
-     * Retained and always written, because it is the only window an older peer or
-     * CLI can read. This build derives it from `approval_expiry_seconds` on every
-     * write (rounded up, never below 1), so the two columns cannot disagree.
-     */
-    approval_expiry_hours: number;
-    /**
-     * How long a security hold stays approvable before it expires, in seconds —
-     * the authoritative window, and the only granularity that can express a
-     * sub-hour hold.
-     *
-     * Nullable: NULL means no seconds value was ever written (a row predating the
-     * column, or one written by an older build), and every reader falls back to
-     * `approval_expiry_hours * 3600`. Same convention as
-     * `contexts.hold_expiry_seconds`.
-     */
-    approval_expiry_seconds: ColumnType<number | null, number | null | undefined, number | null>;
+    /** How long a security hold stays approvable before it expires, in seconds. */
+    approval_expiry_seconds: number;
     /** Which side last wrote this row: platform | local */
     source: string;
     /** When this policy was last written */
@@ -2839,6 +2834,8 @@ export interface HostRosterTable {
      * presigned URL). NULL / false ⇒ the conservative `ssh-push` fallback.
      */
     s3_reachable: ColumnType<boolean | null, boolean | null | undefined, boolean | null>;
+    /** Who last set the host's identity. See {@link HostIdentitySource}. */
+    identity_source: ColumnType<HostIdentitySource, HostIdentitySource | undefined, HostIdentitySource>;
     created_at: Generated<Date>;
     updated_at: ColumnType<Date, Date | string | undefined, Date | string>;
 }

package/dist/fault-injection-types.d.ts

@@ -9,7 +9,6 @@
  * TS2307s. Only the declaration lives here — its one dependency is a type from
  * `@kici-dev/engine`, so nothing test-only is pulled along with it.
  */
-import type { OrchCapabilities } from '@kici-dev/engine';
 /**
  * The set of synthetic faults a test-only entrypoint can inject into the
  * orchestrator. Every field is optional: an absent field means "no fault at
@@ -44,10 +43,5 @@ export interface OrchestratorFaultInjection {
      * the first coordinator slow enough that the Platform relay fails over.
      */
     beforeRerun?: () => Promise<void>;
-    /**
-     * Transform the advertised capability manifest — used to reproduce an older
-     * / sourceless orchestrator that predates a given dashboard capability.
-     */
-    capabilitiesTransform?: (c: OrchCapabilities) => OrchCapabilities;
 }
 //# sourceMappingURL=fault-injection-types.d.ts.map

package/dist/git/dispatch-git-auth.d.ts

@@ -2,21 +2,15 @@ import type { ProviderGitAuth } from '@kici-dev/engine';
 import type { ProviderBundle, ProviderRegistry } from '../provider-registry.js';
 /** Auth the dispatch message carries; every field is optional on the wire. */
 export interface DispatchCloneAuth {
-    /** Bare source-repository token, kept for agents that read only `token`. */
-    token?: string;
     sourceAuth?: ProviderGitAuth;
     workflowAuth?: ProviderGitAuth;
 }
 /**
- * Mint structured auth (and a bare token when it is basic auth) for one
- * repository through one bundle. Providers that implement `issueGitAuth()`
- * return the auth kind directly; otherwise a clone token is wrapped in a
- * basic-auth envelope.
+ * Mint structured auth for one repository through one bundle. Providers that
+ * implement `issueGitAuth()` return the auth kind directly; otherwise a clone
+ * token is wrapped in a basic-auth envelope.
  */
-export declare function mintRepoGitAuth(bundle: ProviderBundle, repoIdentifier: string, providerContext: unknown): Promise<{
-    token: string | null;
-    structuredAuth: ProviderGitAuth | null;
-}>;
+export declare function mintRepoGitAuth(bundle: ProviderBundle, repoIdentifier: string, providerContext: unknown): Promise<ProviderGitAuth | null>;
 /** The job fields the auth resolution reads. */
 export interface DispatchAuthJob {
     id: string;
@@ -35,8 +29,8 @@ export declare function gitHostOf(url: string): string | undefined;
  * it may.
  *
  * The agent falls back across the two clones: it clones the source repository
- * with `sourceAuth ?? workflowAuth ?? token` and the workflow repository with
- * `workflowAuth ?? sourceAuth ?? token`. When only one repository's credential is
+ * with `sourceAuth ?? workflowAuth` and the workflow repository with
+ * `workflowAuth ?? sourceAuth`. When only one repository's credential is
  * present, the other clone sends it to that repository's host. On the same host
  * that is a credential the host issued; on another host it hands one provider's
  * credential to another, so the job is refused instead. A job with no source URL

package/dist/github-app-name-refresher/github-app-name-refresher.d.ts

@@ -10,11 +10,17 @@
  * the Platform `webhook_sources` row and the dashboard Sources tab pick up the
  * new name/slug without any extra plumbing here.
  *
+ * The same pass checks each App against the events and permissions KiCI needs
+ * (`GITHUB_APP_REQUIREMENTS`) and the permissions each installation has
+ * accepted, and logs one warning per App with gaps. A gap never blocks the name
+ * and slug sync.
+ *
  * Lifecycle mirrors `StaleRunDetector`: `start()` runs an immediate refresh
  * (so a rename made while the orchestrator was down propagates on next boot)
  * then a `setInterval`; `stop()` clears it. Per-source errors are logged and
  * never abort the loop.
  */
+import { type GithubAppIdentity, type GithubAppInstallationGrant, type GithubAppRequirementGaps } from '../providers/github/manifest.js';
 /** A source row as returned by listSources() — the slice this module needs. */
 export type SourceIdentityRow = {
     routing_key: string;
@@ -39,12 +45,14 @@ export interface RefreshableSourceStore {
 export type FetchGithubAppIdentity = (creds: {
     appId: string;
     privateKey: string;
-}) => Promise<{
-    name: string;
-    slug: string;
-}>;
-/** Outcome of a single source refresh. */
-export interface RefreshResult {
+}) => Promise<GithubAppIdentity>;
+/** List a GitHub App's installations. Matches `listGithubAppInstallations`. */
+export type FetchGithubAppInstallations = (creds: {
+    appId: string;
+    privateKey: string;
+}) => Promise<GithubAppInstallationGrant[]>;
+/** Outcome of a single source refresh: the name and slug sync plus the requirement gaps. */
+export interface RefreshResult extends GithubAppRequirementGaps {
     routingKey: string;
     changed: boolean;
     oldName: string;
@@ -54,27 +62,31 @@ export interface RefreshResult {
 }
 /**
  * Refresh one already-resolved GitHub source's identity from GitHub and persist
- * it when the name or slug drifted. The caller supplies the row it already holds,
- * so this never lists the sources table. Throws for a non-GitHub row or missing
- * credentials.
+ * it when the name or slug drifted, then compare the App and its installations
+ * with the required events and permissions. The caller supplies the row it
+ * already holds, so this never lists the sources table. Throws for a non-GitHub
+ * row or missing credentials. A failed installations listing throws after the
+ * name and slug sync has been written, so the sync never waits on the gap check.
  */
-export declare function refreshResolvedGithubSource(sourceStore: Pick<RefreshableSourceStore, 'getSourceWithSecrets' | 'updateSource'>, row: SourceIdentityRow, fetchIdentity: FetchGithubAppIdentity): Promise<RefreshResult>;
+export declare function refreshResolvedGithubSource(sourceStore: Pick<RefreshableSourceStore, 'getSourceWithSecrets' | 'updateSource'>, row: SourceIdentityRow, fetchIdentity: FetchGithubAppIdentity, fetchInstallations: FetchGithubAppInstallations): Promise<RefreshResult>;
 /**
  * Re-fetch one GitHub source's identity from GitHub and persist it when the
- * name or slug drifted. Resolves the row by routing key (one sources read) then
- * delegates. Shared by `kici-admin source refresh`. Throws for a missing or
+ * name or slug drifted, and report requirement gaps. Resolves the row by routing
+ * key (one sources read) then delegates. Shared by `kici-admin source refresh`. Throws for a missing or
  * non-GitHub routing key.
  */
-export declare function refreshGithubSourceIdentity(sourceStore: RefreshableSourceStore, routingKey: string, fetchIdentity: FetchGithubAppIdentity): Promise<RefreshResult>;
+export declare function refreshGithubSourceIdentity(sourceStore: RefreshableSourceStore, routingKey: string, fetchIdentity: FetchGithubAppIdentity, fetchInstallations: FetchGithubAppInstallations): Promise<RefreshResult>;
 export interface GithubAppNameRefresherDeps {
     sourceStore: RefreshableSourceStore;
     fetchIdentity: FetchGithubAppIdentity;
+    fetchInstallations: FetchGithubAppInstallations;
     /** Refresh cadence in ms. Default cluster value: 24h (`config.githubAppNameRefreshIntervalMs`). */
     scanIntervalMs: number;
 }
 export declare class GithubAppNameRefresher {
     private readonly sourceStore;
     private readonly fetchIdentity;
+    private readonly fetchInstallations;
     private readonly scanIntervalMs;
     private interval;
     constructor(deps: GithubAppNameRefresherDeps);

package/dist/helpers/json.d.ts

@@ -0,0 +1,3 @@
+/** Parse JSON, returning null for empty, nullish or invalid input. */
+export declare function safeJsonParse(value: string | null | undefined): unknown;
+//# sourceMappingURL=json.d.ts.map

package/dist/index.d.ts

@@ -5,7 +5,7 @@ export { SourceCache } from './cache/source-cache.js';
 export { DepCache } from './cache/dep-cache.js';
 export { UserCache, DEFAULT_USER_CACHE_QUOTA_BYTES, DEFAULT_USER_CACHE_TTL_MS, type UserCacheRef, type UserCacheRestoreResult, type UserCacheBeginSaveResult, } from './cache/user-cache.js';
 export { PeerCredentialStore, createPeerCredentialStoreFromUrl, type PeerCredential, type CredentialFileData, } from './cluster/peer-credentials.js';
-export { PeerAuthCoordinator, type AuthDecision, type RejectionAction, } from './cluster/peer-auth-coordinator.js';
+export { PeerAuthCoordinator, RejectionAction, type AuthDecision, } from './cluster/peer-auth-coordinator.js';
 export { JoinTokenManager, createJoinTokenManagerFromUrl } from './cluster/join-token.js';
 export { HeldRunStore, createHeldRunStoreFromUrl, SecurityHoldReason, } from './contexts/held-runs.js';
 export { TrustPolicyStore, createTrustPolicyStoreFromUrl, TrustPolicySource, DEFAULT_TRUST_POLICY, type StoredTrustPolicy, } from './security/trust-policy-store.js';