@kici-dev/engine 0.0.0 → 0.1.1

package/dist/provider/webhook-normalizer.d.ts

@@ -0,0 +1,163 @@
+/**
+ * WebhookNormalizer interface.
+ *
+ * Translates provider-specific webhook HTTP requests into KiCI's universal
+ * SimulatedEvent format. Each provider implements this to handle its own
+ * header conventions, signature schemes, and payload structures.
+ */
+import type { SimulatedEvent } from '../trigger/types.js';
+import type { ProviderType } from './types.js';
+/**
+ * Discriminated union describing which `ContributorCache` entries a webhook
+ * event invalidates. Returned by `WebhookNormalizer.getAccessCacheInvalidations`.
+ *
+ * Three scopes:
+ * - `repo-user`: a single `{repo, user}` permission changed (e.g. GitHub
+ *   `member` event on a specific collaborator).
+ * - `repo`: every contributor's effective permission on a repo may have
+ *   shifted (e.g. a team was added/removed from the repo).
+ * - `user-in-org`: a user's org membership changed, so any repo under that
+ *   org may now return a different permission for them.
+ */
+export type AccessCacheInvalidation = {
+    kind: 'repo-user';
+    repoFullName: string;
+    username: string;
+} | {
+    kind: 'repo';
+    repoFullName: string;
+} | {
+    kind: 'user-in-org';
+    orgLogin: string;
+    username: string;
+};
+export interface WebhookNormalizer {
+    readonly provider: ProviderType;
+    /**
+     * Extract a routing key from webhook headers/payload.
+     *
+     * The routing key uniquely identifies a webhook source within KiCI.
+     * Format: "{provider}:{provider-specific-id}"
+     *
+     * Examples:
+     * - GitHub: "github:12345" from X-GitHub-Hook-Installation-Target-ID header
+     * - GitLab: "gitlab:67890" from payload.project.id
+     * - Bitbucket: "bitbucket:{uuid}" from payload.repository.uuid
+     */
+    extractRoutingKey(headers: Record<string, string>, payload: unknown): string | null;
+    /**
+     * Extract a unique delivery ID for deduplication.
+     *
+     * Examples:
+     * - GitHub: X-GitHub-Delivery header
+     * - GitLab: X-Gitlab-Event-UUID header
+     * - Bitbucket: X-Request-UUID header
+     */
+    extractDeliveryId(headers: Record<string, string>): string | null;
+    /**
+     * Extract the event type from headers.
+     *
+     * Returns the provider-specific event type string (not yet normalized).
+     *
+     * Examples:
+     * - GitHub: X-GitHub-Event header ("push", "pull_request")
+     * - GitLab: X-Gitlab-Event header ("Push Hook", "Merge Request Hook")
+     * - Bitbucket: X-Event-Key header ("repo:push", "pullrequest:created")
+     */
+    extractEventType(headers: Record<string, string>): string | null;
+    /**
+     * Verify webhook signature or token.
+     *
+     * Each provider has its own verification scheme:
+     * - GitHub: HMAC-SHA256 with X-Hub-Signature-256 header
+     * - GitLab: Plain token comparison with X-Gitlab-Token header
+     * - Bitbucket: HMAC-SHA256 with X-Hub-Signature header
+     *
+     * @param body - Raw request body as string
+     * @param headers - Request headers (lowercase keys)
+     * @param secret - Webhook secret/token configured for this source
+     * @returns true if signature/token is valid
+     */
+    verifySignature(body: string, headers: Record<string, string>, secret: string): boolean;
+    /**
+     * Normalize a provider-specific webhook into a SimulatedEvent.
+     *
+     * Maps provider event types to universal 'pull_request' | 'push' types.
+     * Returns null if the event type is not relevant for trigger matching
+     * (e.g., GitHub "star" events, GitLab "Pipeline Hook" events).
+     *
+     * @param eventType - Provider-specific event type (from extractEventType)
+     * @param action - Event action/sub-type, if applicable (e.g., "opened" for PRs)
+     * @param payload - Raw webhook payload
+     * @returns Normalized SimulatedEvent, or null if not matchable
+     */
+    normalizeEvent(eventType: string, action: string | null, payload: unknown): SimulatedEvent | null;
+    /**
+     * Extract the repository identifier from a webhook payload.
+     *
+     * Returns a string in "owner/repo" format, or null if the payload
+     * does not contain repository information (e.g., generic webhooks).
+     *
+     * Examples:
+     * - GitHub: "octocat/Hello-World" from payload.repository.full_name
+     * - GitLab: "group/project" from payload.project.path_with_namespace
+     * - Generic/internal: may return null if no repo concept
+     */
+    extractRepoIdentifier(payload: unknown): string | null;
+    /**
+     * Extract the commit SHA or ref for lock file fetching from a webhook payload.
+     *
+     * Returns a commit SHA, branch name, or 'HEAD' as a fallback.
+     * Each provider maps event types to the appropriate payload field.
+     *
+     * Examples:
+     * - GitHub push: payload.after
+     * - GitHub pull_request: payload.pull_request.head.sha
+     * - Generic: 'HEAD' (no ref concept)
+     *
+     * @param eventType - Provider-specific event type (from extractEventType)
+     * @param payload - Raw webhook payload
+     */
+    extractRef(eventType: string, payload: unknown): string;
+    /**
+     * Extract provider-specific credentials from a webhook payload.
+     *
+     * Returns an object with provider-specific credential fields needed
+     * for downstream operations (clone tokens, API calls, etc.).
+     *
+     * Examples:
+     * - GitHub: { installationId: 12345 } from payload.installation.id
+     * - Generic: {} (no credentials in payload)
+     */
+    extractCredentials(payload: unknown): Record<string, unknown>;
+    /**
+     * Extract the repository's default branch from the webhook payload.
+     *
+     * Optional. When implemented, the orchestrator uses this hook to decide
+     * whether a push event targets the default branch (required for workflow
+     * registration extraction). When omitted, the orchestrator falls back to
+     * the hardcoded `payload.repository.default_branch` shape.
+     *
+     * Returns null when the field is missing or cannot be resolved.
+     */
+    extractDefaultBranch?(payload: unknown): string | null;
+    /**
+     * Map a webhook event to the `ContributorCache` entries it should drop.
+     *
+     * Optional. When implemented, the orchestrator calls this before
+     * `normalizeEvent` and invalidates every returned entry so the next
+     * permission check hits the provider API instead of relying on stale
+     * cached data. Events that do not imply a permission shift (most events,
+     * including `push` / `pull_request` / etc.) should return `[]`.
+     *
+     * The caller is responsible for pairing the returned entries with the
+     * `provider` field of the matched bundle — this method receives no
+     * provider argument.
+     *
+     * @param eventType Provider-specific event type (from extractEventType).
+     * @param action Event action/sub-type, if applicable.
+     * @param payload Raw webhook payload.
+     */
+    getAccessCacheInvalidations?(eventType: string, action: string | null, payload: unknown): AccessCacheInvalidation[];
+}
+//# sourceMappingURL=webhook-normalizer.d.ts.map

package/dist/provider/webhook-normalizer.js

@@ -0,0 +1,2 @@
+import "../chunk-gOLHoazu.js";
+export {};

package/dist/registration/registerable-trigger-type.d.ts

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+/**
+ * Trigger types whose owning workflows must be stored in workflow_registrations
+ * so the orchestrator can resolve them from an index lookup instead of
+ * re-fetching a lock file per inbound event.
+ *
+ * Two families live in this list:
+ *
+ *   1. Non-Git-provider triggers (kici_event, schedule, webhook, lifecycle, …)
+ *      — these have no per-repo lock file pipeline to fall back to, so the
+ *      registration index is the authoritative source for matching.
+ *
+ *   2. Git-provider triggers (push, pr, tag, release, …) — these ARE still
+ *      matched via the per-event lock file pipeline on the same-source path
+ *      (e.g. a real GitHub push webhook). Registering them in addition is
+ *      what makes cross-source dispatch work for a generic webhook that
+ *      targets an externally-hosted repo (phase 28.5): the cross-source
+ *      branch looks up `(customer_id, repo_identifier)` and reuses the
+ *      stored `provider_context` (installation id, app id, …) to mint
+ *      credentials for the actual provider bundle that owns the repo.
+ *      Without this, a workflow whose only trigger is `push()` is invisible
+ *      to cross-source dispatch and generic webhooks targeting its repo
+ *      silently no-op.
+ *
+ * Access values: RegisterableTriggerType.enum.kici_event, etc.
+ */
+export declare const RegisterableTriggerType: z.ZodEnum<{
+    status: "status";
+    generic_webhook: "generic_webhook";
+    pr: "pr";
+    push: "push";
+    tag: "tag";
+    comment: "comment";
+    review: "review";
+    review_comment: "review_comment";
+    release: "release";
+    dispatch: "dispatch";
+    create: "create";
+    delete: "delete";
+    workflow_run: "workflow_run";
+    fork: "fork";
+    star: "star";
+    watch: "watch";
+    webhook: "webhook";
+    kici_event: "kici_event";
+    workflow_complete: "workflow_complete";
+    job_complete: "job_complete";
+    schedule: "schedule";
+    lifecycle: "lifecycle";
+}>;
+export type RegisterableTriggerType = z.infer<typeof RegisterableTriggerType>;
+//# sourceMappingURL=registerable-trigger-type.d.ts.map

package/dist/registration/registerable-trigger-type.js

@@ -0,0 +1,56 @@
+import "../chunk-gOLHoazu.js";
+import { z } from "zod";
+//#region src/registration/registerable-trigger-type.ts
+/**
+* Trigger types whose owning workflows must be stored in workflow_registrations
+* so the orchestrator can resolve them from an index lookup instead of
+* re-fetching a lock file per inbound event.
+*
+* Two families live in this list:
+*
+*   1. Non-Git-provider triggers (kici_event, schedule, webhook, lifecycle, …)
+*      — these have no per-repo lock file pipeline to fall back to, so the
+*      registration index is the authoritative source for matching.
+*
+*   2. Git-provider triggers (push, pr, tag, release, …) — these ARE still
+*      matched via the per-event lock file pipeline on the same-source path
+*      (e.g. a real GitHub push webhook). Registering them in addition is
+*      what makes cross-source dispatch work for a generic webhook that
+*      targets an externally-hosted repo (phase 28.5): the cross-source
+*      branch looks up `(customer_id, repo_identifier)` and reuses the
+*      stored `provider_context` (installation id, app id, …) to mint
+*      credentials for the actual provider bundle that owns the repo.
+*      Without this, a workflow whose only trigger is `push()` is invisible
+*      to cross-source dispatch and generic webhooks targeting its repo
+*      silently no-op.
+*
+* Access values: RegisterableTriggerType.enum.kici_event, etc.
+*/
+const RegisterableTriggerType = z.enum([
+	"kici_event",
+	"workflow_complete",
+	"job_complete",
+	"generic_webhook",
+	"schedule",
+	"lifecycle",
+	"webhook",
+	"push",
+	"pr",
+	"tag",
+	"comment",
+	"review",
+	"review_comment",
+	"release",
+	"dispatch",
+	"create",
+	"delete",
+	"status",
+	"workflow_run",
+	"fork",
+	"star",
+	"watch"
+]);
+//#endregion
+export { RegisterableTriggerType };
+
+//# sourceMappingURL=registerable-trigger-type.js.map

package/dist/scaler/resource-types.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Resource request and limit types for jobs and scalers.
+ *
+ * Single source of truth — re-exported from the engine barrel and consumed by:
+ * - SDK (`Job` / `JobOptions` `resources` field)
+ * - compiler (compile-time validation + lockfile emission)
+ * - orchestrator (scaler accounting + backend enforcement)
+ * - dashboard (read-only display)
+ *
+ * Shape is K8s-style requests/limits split:
+ * - `requests` drive the scheduler's cap math (per-scaler / per-orch / per-machine).
+ * - `limits` drive kernel-side enforcement (Docker memory + nanoCpus, FC memSizeMib + vcpuCount,
+ *   optional bare-metal systemd-run scope).
+ *
+ * Mirroring rule (applied at the orchestrator's resolve step):
+ * - request-only ⇒ limit = request
+ * - limit-only ⇒ request = limit
+ * - neither ⇒ scaler default
+ * - nothing anywhere ⇒ 0/0 (job counts toward agent-count cap only)
+ */
+import { z } from 'zod';
+/**
+ * A single resource specification (cpus + memory).
+ *
+ * - `cpus`: fractional cores (e.g., 1.5 means 1.5 cores).
+ * - `memory`: container-style suffix (e.g., "2g", "512m", "1024k").
+ *   No K8s "Mi/Gi" units — one parser, one format across the codebase.
+ */
+export interface ResourceSpec {
+    /** CPU in fractional cores. */
+    cpus?: number;
+    /** Memory limit, e.g. "2g", "512m", "1024k". */
+    memory?: string;
+}
+/**
+ * Per-job resource request (declared in workflow source, threaded through to scaler).
+ *
+ * `requests` drive scheduling math (cap aggregation).
+ * `limits` drive kernel-side enforcement of the spawned agent.
+ */
+export interface ResourceRequest {
+    /** Requests drive the scheduler's cap math (per-scaler / per-orch / per-machine). */
+    requests?: ResourceSpec;
+    /** Limits drive kernel enforcement (Docker memory + nanoCpus, FC memSizeMib + vcpuCount, optional bare-metal systemd-run scope). */
+    limits?: ResourceSpec;
+}
+/**
+ * Zod schema for a single resource spec (cpus + memory).
+ */
+export declare const resourceSpecSchema: z.ZodObject<{
+    cpus: z.ZodOptional<z.ZodNumber>;
+    memory: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * Zod schema for the nested request/limit form.
+ */
+export declare const resourceRequestNestedSchema: z.ZodObject<{
+    requests: z.ZodOptional<z.ZodObject<{
+        cpus: z.ZodOptional<z.ZodNumber>;
+        memory: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    limits: z.ZodOptional<z.ZodObject<{
+        cpus: z.ZodOptional<z.ZodNumber>;
+        memory: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/**
+ * Parse a memory string with unit suffix to bytes.
+ *
+ * Supported formats:
+ * - "512m" or "512M" -> 536870912 (512 * 1024^2)
+ * - "2g" or "2G" -> 2147483648 (2 * 1024^3)
+ * - "1024k" or "1024K" -> 1048576 (1024 * 1024)
+ *
+ * @throws Error if the format is invalid
+ */
+export declare function parseMemoryString(memory: string): number;
+/**
+ * Validate a `ResourceRequest` literal (e.g., from compile-time SDK input).
+ *
+ * Checks:
+ * - `memory` strings parse via `parseMemoryString`.
+ * - `cpus` are positive numbers ≤ 256 (max practical scaler).
+ * - When both `requests` and `limits` are set on the same dimension,
+ *   `requests <= limits` (a request that exceeds its own limit is nonsensical).
+ *
+ * Throws on the first violation with a descriptive error.
+ */
+export declare function validateResourceRequest(req: ResourceRequest): void;
+//# sourceMappingURL=resource-types.d.ts.map

package/dist/scaler/resource-types.js

@@ -0,0 +1,99 @@
+import "../chunk-gOLHoazu.js";
+import { z } from "zod";
+//#region src/scaler/resource-types.ts
+/**
+* Resource request and limit types for jobs and scalers.
+*
+* Single source of truth — re-exported from the engine barrel and consumed by:
+* - SDK (`Job` / `JobOptions` `resources` field)
+* - compiler (compile-time validation + lockfile emission)
+* - orchestrator (scaler accounting + backend enforcement)
+* - dashboard (read-only display)
+*
+* Shape is K8s-style requests/limits split:
+* - `requests` drive the scheduler's cap math (per-scaler / per-orch / per-machine).
+* - `limits` drive kernel-side enforcement (Docker memory + nanoCpus, FC memSizeMib + vcpuCount,
+*   optional bare-metal systemd-run scope).
+*
+* Mirroring rule (applied at the orchestrator's resolve step):
+* - request-only ⇒ limit = request
+* - limit-only ⇒ request = limit
+* - neither ⇒ scaler default
+* - nothing anywhere ⇒ 0/0 (job counts toward agent-count cap only)
+*/
+/**
+* Zod schema for a single resource spec (cpus + memory).
+*/
+const resourceSpecSchema = z.object({
+	cpus: z.number().positive().max(256).optional(),
+	memory: z.string().optional()
+}).strict();
+/**
+* Zod schema for the nested request/limit form.
+*/
+const resourceRequestNestedSchema = z.object({
+	requests: resourceSpecSchema.optional(),
+	limits: resourceSpecSchema.optional()
+}).strict();
+/**
+* Memory string units supported across the codebase.
+*
+* Mirrors `parseMemoryString` in `packages/orchestrator/src/scaler/config.ts` —
+* keep both in sync. Hoisted here so the compiler (browser-safe) can validate
+* memory strings at compile time without depending on the orchestrator package.
+*/
+const MEMORY_FORMAT_RE = /^(\d+(?:\.\d+)?)\s*([kmgKMG])$/;
+/**
+* Parse a memory string with unit suffix to bytes.
+*
+* Supported formats:
+* - "512m" or "512M" -> 536870912 (512 * 1024^2)
+* - "2g" or "2G" -> 2147483648 (2 * 1024^3)
+* - "1024k" or "1024K" -> 1048576 (1024 * 1024)
+*
+* @throws Error if the format is invalid
+*/
+function parseMemoryString(memory) {
+	const match = memory.match(MEMORY_FORMAT_RE);
+	if (!match) throw new Error(`Invalid memory format: "${memory}". Expected format like "512m", "2g", or "1024k".`);
+	const value = parseFloat(match[1]);
+	const unit = match[2].toLowerCase();
+	switch (unit) {
+		case "k": return Math.floor(value * 1024);
+		case "m": return Math.floor(value * 1024 * 1024);
+		case "g": return Math.floor(value * 1024 * 1024 * 1024);
+		default: throw new Error(`Unknown memory unit: "${unit}"`);
+	}
+}
+/**
+* Validate a `ResourceRequest` literal (e.g., from compile-time SDK input).
+*
+* Checks:
+* - `memory` strings parse via `parseMemoryString`.
+* - `cpus` are positive numbers ≤ 256 (max practical scaler).
+* - When both `requests` and `limits` are set on the same dimension,
+*   `requests <= limits` (a request that exceeds its own limit is nonsensical).
+*
+* Throws on the first violation with a descriptive error.
+*/
+function validateResourceRequest(req) {
+	resourceRequestNestedSchema.parse(req);
+	for (const side of ["requests", "limits"]) {
+		const spec = req[side];
+		if (!spec) continue;
+		if (spec.memory !== void 0) parseMemoryString(spec.memory);
+		if (spec.cpus !== void 0 && spec.cpus <= 0) throw new Error(`resources.${side}.cpus must be > 0 (got ${spec.cpus})`);
+	}
+	const requests = req.requests;
+	const limits = req.limits;
+	if (requests && limits) {
+		if (requests.cpus !== void 0 && limits.cpus !== void 0 && requests.cpus > limits.cpus) throw new Error(`resources.requests.cpus (${requests.cpus}) must not exceed resources.limits.cpus (${limits.cpus})`);
+		if (requests.memory !== void 0 && limits.memory !== void 0) {
+			if (parseMemoryString(requests.memory) > parseMemoryString(limits.memory)) throw new Error(`resources.requests.memory (${requests.memory}) must not exceed resources.limits.memory (${limits.memory})`);
+		}
+	}
+}
+//#endregion
+export { parseMemoryString, resourceRequestNestedSchema, resourceSpecSchema, validateResourceRequest };
+
+//# sourceMappingURL=resource-types.js.map

package/dist/scaler/scaler-backend-type.d.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+/**
+ * Scaler backend type identifiers.
+ *
+ * Enumerates the agent provisioning backends supported by the orchestrator's
+ * auto-scaler module. Each backend implements the ScalerBackend interface.
+ * Access values: ScalerBackendType.enum.container, ScalerBackendType.enum.firecracker, etc.
+ */
+export declare const ScalerBackendType: z.ZodEnum<{
+    container: "container";
+    "bare-metal": "bare-metal";
+    firecracker: "firecracker";
+    kubernetes: "kubernetes";
+}>;
+export type ScalerBackendType = z.infer<typeof ScalerBackendType>;
+//# sourceMappingURL=scaler-backend-type.d.ts.map

package/dist/scaler/scaler-backend-type.js

@@ -0,0 +1,20 @@
+import "../chunk-gOLHoazu.js";
+import { z } from "zod";
+//#region src/scaler/scaler-backend-type.ts
+/**
+* Scaler backend type identifiers.
+*
+* Enumerates the agent provisioning backends supported by the orchestrator's
+* auto-scaler module. Each backend implements the ScalerBackend interface.
+* Access values: ScalerBackendType.enum.container, ScalerBackendType.enum.firecracker, etc.
+*/
+const ScalerBackendType = z.enum([
+	"container",
+	"bare-metal",
+	"firecracker",
+	"kubernetes"
+]);
+//#endregion
+export { ScalerBackendType };
+
+//# sourceMappingURL=scaler-backend-type.js.map

package/dist/secrets/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Secrets management module.
+ *
+ * Re-exports scope-based secret store types and audit entry.
+ */
+export type { SecretStore, AuditEntry, BackendType, BackendHealthStatus, BackendDescriptor, AddBackendParams, BackendManager, BackendSyncManager, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/secrets/index.js

@@ -0,0 +1,2 @@
+import "../chunk-gOLHoazu.js";
+export {};

package/dist/secrets/types.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Secrets management interfaces for KiCI.
+ *
+ * Defines the pluggable backend contract (SecretStore) and audit logging
+ * (AuditEntry) for the scoped secrets system.
+ *
+ * These interfaces are backend-agnostic -- implementations live in
+ * orchestrator (PG backend) or can be swapped for Vault, etc.
+ */
+/**
+ * Scope-based secret store interface.
+ * Provides access to secrets organized by (orgId, scope, key).
+ */
+export interface SecretStore {
+    /** Get all secrets for a scope as decrypted key-value pairs. */
+    getSecrets(orgId: string, scope: string): Promise<Record<string, string>>;
+    /** Set (create or update) a secret in a scope. */
+    setSecret(orgId: string, scope: string, key: string, value: string): Promise<void>;
+    /** Delete a secret from a scope. */
+    deleteSecret(orgId: string, scope: string, key: string): Promise<void>;
+    /** List all secret key names in a scope (no values returned). */
+    listKeys(orgId: string, scope: string): Promise<string[]>;
+    /** List all distinct scopes for an org. */
+    listScopes(orgId: string): Promise<string[]>;
+    /** Create an empty scope (implementation may use a sentinel row or metadata table). */
+    createScope?(orgId: string, scope: string): Promise<void>;
+    /** Rename a scope -- update all secret rows from oldScope to newScope. */
+    renameScope?(orgId: string, oldScope: string, newScope: string): Promise<void>;
+    /** Delete a scope and all its secrets. */
+    deleteScope?(orgId: string, scope: string): Promise<void>;
+    /** Get all secrets for an org (for resolver). Returns encrypted values. */
+    getAllSecrets(orgId: string): Promise<Array<{
+        scope: string;
+        key: string;
+        encryptedValue: string;
+        keyVersion: number;
+    }>>;
+}
+/** Supported secret backend types. */
+export type BackendType = 'pg' | 'vault';
+/** Health status of a secret backend. */
+export type BackendHealthStatus = 'healthy' | 'degraded' | 'unreachable' | 'unknown';
+/**
+ * Metadata descriptor for a registered secret backend.
+ * Does NOT include credentials — safe to expose via API.
+ */
+export interface BackendDescriptor {
+    id: string;
+    name: string;
+    backendType: BackendType;
+    /** Comma-separated globs for scope filtering. Default '**'. */
+    scopeFilter: string;
+    /** Sync interval in milliseconds. Default 300000 (5 min). */
+    syncIntervalMs: number;
+    enabled: boolean;
+    healthStatus: BackendHealthStatus;
+    scopeCount: number;
+    lastSyncAt: Date | null;
+    lastSyncError: string | null;
+    lastHealthCheckAt: Date | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/** Parameters for registering a new secret backend. */
+export interface AddBackendParams {
+    name: string;
+    backendType: BackendType;
+    config: Record<string, unknown>;
+    scopeFilter?: string;
+    syncIntervalMs?: number;
+}
+/**
+ * Backend lifecycle manager interface.
+ * Provides CRUD, health checks, and connection testing for secret backends.
+ */
+export interface BackendManager {
+    /** Check backend connectivity. Returns health status. */
+    checkHealth(name: string): Promise<BackendHealthStatus>;
+    /** Trigger scope discovery sync for a backend (or all if name omitted). */
+    syncScopes(name?: string): Promise<void>;
+    /** List all registered backends (no credentials). */
+    listBackends(): Promise<BackendDescriptor[]>;
+    /** Get a single backend by name. */
+    getBackend(name: string): Promise<BackendDescriptor | null>;
+    /** Register a new backend. Returns the descriptor. */
+    addBackend(params: AddBackendParams): Promise<BackendDescriptor>;
+    /** Remove a backend by name. Returns true if removed. */
+    removeBackend(name: string): Promise<boolean>;
+    /** Test connectivity without persisting. */
+    testConnection(params: AddBackendParams): Promise<{
+        ok: boolean;
+        error?: string;
+        latencyMs: number;
+    }>;
+}
+/**
+ * Periodic scope sync manager for secret backends.
+ */
+export interface BackendSyncManager {
+    syncBackend(name: string): Promise<{
+        scopeCount: number;
+        error?: string;
+    }>;
+    syncAllBackends(): Promise<Array<{
+        name: string;
+        scopeCount: number;
+        error?: string;
+    }>>;
+    startPeriodicSync(): void;
+    stopPeriodicSync(): void;
+}
+/**
+ * Audit log entry for secrets operations.
+ * Used for tracking access patterns and security events.
+ */
+export interface AuditEntry {
+    /** The action performed (e.g., 'getSecrets', 'setSecret', 'resolve'). */
+    action: string;
+    /** The scope or context name involved. */
+    contextName: string;
+    /** Routing key scope. */
+    routingKey: string | null;
+    /** Secret keys involved (null for scope-level ops). */
+    secretKeys: string[] | null;
+    /** Whether the operation was allowed or denied. */
+    outcome: 'allowed' | 'denied';
+    /** CI run ID if applicable. */
+    runId: string | null;
+    /** Job ID if applicable. */
+    jobId: string | null;
+    /** User ID if applicable. */
+    userId: string | null;
+    /** User role if applicable. */
+    role: string | null;
+    /** Additional metadata. */
+    metadata: Record<string, unknown> | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/secrets/types.js

@@ -0,0 +1,2 @@
+import "../chunk-gOLHoazu.js";
+export {};

package/dist/state-machine/index.d.ts

@@ -0,0 +1,2 @@
+export { transition, isTerminal } from './machine.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/state-machine/index.js

@@ -0,0 +1,3 @@
+import "../chunk-gOLHoazu.js";
+import { isTerminal, transition } from "./machine.js";
+export { isTerminal, transition };