@kici-dev/orchestrator 0.4.0 → 0.6.0

package/dist/security/trust-directory-store.d.ts

@@ -0,0 +1,233 @@
+/**
+ * Cache of the Platform-owned approval directory.
+ *
+ * The Platform pushes three documents next to the trust policy on
+ * `trust_policy.update`: the org's identity links (an array), each member's CI
+ * trust level (a user-id-keyed map), and the operator-defined teams (an array).
+ * They feed approval authorization: the `/kici approve` comment handler
+ * resolves a commenter to a KiCI user through the identity links and reads that
+ * user's CI trust level, and the approval resolver matches a `{team}` clause
+ * against the team memberships.
+ *
+ * Held only in memory, all three are empty after a restart until the next push
+ * lands, so a `/kici approve` comment in that window cannot be attributed to
+ * anyone and is refused. This store persists them so the directory survives the
+ * restart.
+ *
+ * Wherever a Platform is attached it is the sole writer, exactly as it is for
+ * `TrustPolicyStore`'s platform-sourced rows: a push replaces the cached
+ * directory wholesale. An independent orchestrator has no Platform and so no
+ * upstream authority, which is where `upsertLocalMember` / `removeLocalMember`
+ * come in — the operator registers approvers themselves. The two writers never
+ * overlap, because the admin route refuses the local write on any
+ * Platform-attached orchestrator, so a row still only ever has one writer for
+ * the lifetime of a deployment.
+ *
+ * ## The staleness trade-off
+ *
+ * Persisting the directory trades a fail-closed default for availability, and
+ * the trade runs in both directions.
+ *
+ * The gain: approvals keep working across a restart instead of being refused
+ * until the Platform reconnects.
+ *
+ * The cost: a restart restores whoever the last push named, so a member whose
+ * CI trust the Platform revoked while this orchestrator was down can still
+ * approve until the next push overwrites the cache. The Platform sends that
+ * push immediately after the orchestrator's WebSocket authenticates, so the
+ * window is normally the handshake — but an orchestrator that cannot reach the
+ * Platform at all never gets the push, so during a Platform outage the window
+ * is unbounded.
+ *
+ * The cache is deliberately not bounded by a TTL. An expired directory would
+ * fail closed exactly when the Platform is unreachable, which is when frozen
+ * approvals hurt most, and it would undo the restart-survival this store
+ * exists for. `TrustPolicyStore` caches the policy on the same terms.
+ * `updated_at` is stored, and read today only to order `loadLastPushed` and to
+ * report the cache's age in the boot log line — nothing compares it against a
+ * deadline — so a bound can be added later without a migration.
+ */
+import { Kysely, type Transaction } from 'kysely';
+import { z } from 'zod';
+import { type CiTrustLevel } from '@kici-dev/engine';
+import type { Database } from '../db/types.js';
+/**
+ * The three directory fields of `trust_policy.update`, taken from the wire
+ * schema itself.
+ *
+ * What that pins: these three field *names*. Rename one upstream or drop it and
+ * this schema stops compiling, because the `.shape` lookup no longer resolves.
+ * A change *inside* one of them — an element gaining, losing, or retyping a
+ * field — compiles fine and propagates through `z.infer`, so the persisted
+ * document follows the pushed one automatically rather than by a compile error.
+ *
+ * What it does not pin: the field *set*. A fourth directory field added to
+ * `trustPolicyUpdateSchema` is not picked up here, and `server.ts` hand-builds
+ * the value it passes to `upsertFromPlatform`, so nothing would fail — the new
+ * field would simply go unpersisted. Adding one means extending this object and
+ * that literal together.
+ */
+export declare const trustDirectorySchema: z.ZodObject<{
+    identityLinks: z.ZodArray<z.ZodObject<{
+        userId: z.ZodString;
+        provider: z.ZodString;
+        providerUsername: z.ZodString;
+        providerUserId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>;
+    memberCiTrustLevels: z.ZodRecord<z.ZodString, z.ZodEnum<{
+        admin: "admin";
+        none: "none";
+        read: "read";
+        write: "write";
+    }>>;
+    teamMemberships: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        teamName: z.ZodString;
+        memberUserIds: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type TrustDirectory = z.infer<typeof trustDirectorySchema>;
+/** A directory as stored, with the write timestamp. */
+export interface StoredTrustDirectory extends TrustDirectory {
+    updatedAt: Date;
+}
+/** A stored directory carrying the org id it was written under. */
+export interface KeyedTrustDirectory extends StoredTrustDirectory {
+    orgId: string;
+}
+/**
+ * A directory with nothing in it — what an org with no stored row starts from.
+ *
+ * A factory rather than a shared constant: the merge helpers below pass
+ * `teamMemberships` through by reference, so a single shared instance would
+ * hand every caller the same array and let one of them mutate what the next
+ * one reads as empty.
+ */
+export declare function emptyTrustDirectory(): TrustDirectory;
+/**
+ * One member's approval registration, as an operator supplies it on an
+ * independent orchestrator.
+ *
+ * `providerUserId` is REQUIRED here, unlike the nullish field on a pushed link.
+ * `findIdentityLink` matches on `(provider, providerUserId)` and never falls
+ * back to the mutable username, so a link registered without a numeric id would
+ * be inert — accepted, stored, and silently unable to authorize anyone. The
+ * caller is made to supply one rather than discover that from a refused
+ * approval.
+ */
+export interface DirectoryMemberRegistration {
+    /** KiCI user id the approval is attributed to. */
+    userId: string;
+    /** Provider the link is for, e.g. `github`. */
+    provider: string;
+    /** Provider-side username. Display only — never matched on. */
+    providerUsername: string;
+    /** Immutable provider-side numeric id. The only field a link is matched on. */
+    providerUserId: string;
+    /** CI trust level to record for `userId`. `write` or `admin` may approve. */
+    ciTrust: CiTrustLevel;
+}
+/**
+ * Register one member into a directory, returning a new directory.
+ *
+ * Two existing links are displaced, not one. The obvious key is
+ * `(provider, providerUserId)` — the pair `findIdentityLink` matches on — but
+ * `(provider, userId)` has to go too: re-registering a member whose provider
+ * account changed would otherwise leave their OLD numeric id in the directory,
+ * still resolving to their user id and still carrying their CI trust. Whoever
+ * holds that id at the provider now would inherit the ability to approve.
+ *
+ * `teamMemberships` is passed through untouched — teams are not operator-
+ * writable here, and dropping them would silently break every `{team}` clause.
+ */
+export declare function applyMemberRegistration(current: TrustDirectory, registration: DirectoryMemberRegistration): TrustDirectory;
+/**
+ * Remove one member from a directory, returning a new directory and whether
+ * anything was actually removed.
+ *
+ * The inverse of {@link applyMemberRegistration}: every link the member holds
+ * on every provider goes, together with their CI trust level. Leaving the trust
+ * level behind would be harmless only until the member is re-registered on a
+ * different provider account, at which point the revoked level would silently
+ * come back with them.
+ */
+export declare function removeMemberFromDirectory(current: TrustDirectory, userId: string): {
+    directory: TrustDirectory;
+    removed: boolean;
+};
+export declare class TrustDirectoryStore {
+    private readonly db;
+    constructor(db: Kysely<Database>);
+    /**
+     * Replace the cached directory for `orgId`.
+     *
+     * Needs no lock and no read-merge: a push carries all three lists in full, so
+     * concurrent pushes correctly settle on the last one — the same reasoning as
+     * `TrustPolicyStore.upsertFromPlatform`.
+     */
+    upsertFromPlatform(orgId: string, directory: TrustDirectory): Promise<void>;
+    /**
+     * Register (or re-register) one member in an operator-owned directory.
+     *
+     * Only reachable in independent mode — the admin route refuses on a
+     * Platform-attached orchestrator, because the next push replaces the whole
+     * document and would clobber the write.
+     *
+     * The read-merge-write is serialised per org by a transaction-scoped advisory
+     * lock, for the same reason `TrustPolicyStore.upsertLocal` takes one: the
+     * transaction alone gives nothing under READ COMMITTED, so two concurrent
+     * registrations would both read the pre-existing document and the second
+     * would overwrite the first's member out of its own stale copy.
+     *
+     * `onWrite` receives the same transaction and the merged directory, so an
+     * audit row written there commits or rolls back with the directory itself — a
+     * self-granted `write` level can never land unattributed.
+     *
+     * Returns the merged directory so the caller does not need a second read
+     * (which would be outside the transaction and could observe a later write).
+     */
+    upsertLocalMember(orgId: string, registration: DirectoryMemberRegistration, onWrite?: (trx: Transaction<Database>, merged: TrustDirectory) => Promise<void>): Promise<TrustDirectory>;
+    /**
+     * Remove one member from an operator-owned directory. Same mode restriction,
+     * locking, and audit contract as {@link upsertLocalMember}.
+     *
+     * `removed` is false when the member held no link and no CI trust level, so
+     * the caller can tell "revoked" from "was never registered" — the row is
+     * still rewritten either way, which keeps the operation idempotent. It is
+     * handed to `onWrite` as well as returned, because the audit row is written
+     * before this method returns and cannot read its own result.
+     */
+    removeLocalMember(orgId: string, userId: string, onWrite?: (trx: Transaction<Database>, merged: TrustDirectory, removed: boolean) => Promise<void>): Promise<{
+        directory: TrustDirectory;
+        removed: boolean;
+    }>;
+    /** Read the cached directory for `orgId`, or null when nothing was ever pushed. */
+    load(orgId: string): Promise<StoredTrustDirectory | null>;
+    /**
+     * Read the most recently written cached directory together with the org id it
+     * is keyed by.
+     *
+     * At process start the orchestrator has no org id in hand to call `load()`
+     * with: none is configured, and the DB-derived resolution that exists is
+     * written inline in `server.ts`'s auth path rather than extracted. The row
+     * itself carries one — the org of the last push, which is by construction the
+     * org this directory belongs to — so the boot-time seed is keyed by real data
+     * instead of a hardcoded or invented id. An
+     * orchestrator serves exactly one org, so ordering by `updated_at` is a
+     * tiebreak that in practice never has to break a tie; it keeps the read
+     * deterministic if a row for a second org is ever present.
+     */
+    loadLastPushed(): Promise<KeyedTrustDirectory | null>;
+    /**
+     * The shared read-merge-write both local writers run: take the per-org
+     * advisory lock, read the current document (an absent row reads as
+     * {@link emptyTrustDirectory}), apply `merge`, write it back, then invoke
+     * `onWrite` inside the same transaction.
+     *
+     * The lock MUST precede the read: it is what orders this merge against a
+     * concurrent one, so taking it after the SELECT would order nothing.
+     */
+    private mergeLocally;
+    /** Replace the whole stored document for `orgId`. */
+    private write;
+}
+//# sourceMappingURL=trust-directory-store.d.ts.map

package/dist/security/trust-policy-gate.d.ts

@@ -1,117 +1,152 @@
 /**
- * Org trust-policy gate — turns the Platform-owned policy plus three per-PR
- * signals into exactly one outcome.
+ * Org trust-policy gate — turns the org's fork switch plus the per-PR signals
+ * into exactly one outcome.
  *
  * Pure: no I/O, no DB, no clock. The caller supplies the effective policy (see
- * `resolveEffectivePolicy`) and the signals; enforcement lives in the dispatch
- * gate.
+ * `resolveEffectivePolicy`) and the signals; enforcement lives elsewhere — the
+ * webhook pipeline drops an `ignore`d event before it can create a run, and the
+ * dispatch gate acts on the remaining verdicts.
  *
- * Scope: the caller only invokes this for sources whose provider bundle carries
- * a `ContributorResolver` (GitHub today). Every other source is trusted by
- * construction and never reaches here.
+ * Scope: the pipeline reaches this through `evaluateSecurityPolicy`, which
+ * short-circuits to `pass` for a source whose provider bundle leaves
+ * `hasForkModel` unset — so a source with no fork model never reaches the
+ * switch below by that route. That short-circuit is not a trust claim: a
+ * PR from a fork-less provider resolves NO tier, because the fork signal such a
+ * provider computes reads `false` whenever the payload keys it compares are
+ * absent. Those sources skip the switch because its one condition — "the PR
+ * came from a fork" — cannot be established for them, not because they are
+ * trusted.
  */
 import { z } from 'zod';
+import { ForkPolicy } from '@kici-dev/engine';
 import type { OrchestratorMode, TrustPolicy, TrustTier } from '@kici-dev/engine';
 import { SecurityHoldReason } from '../contexts/held-runs.js';
 import type { StoredTrustPolicy } from './trust-policy-store.js';
 /**
- * Which arm of the gate is actually in force for an org — the vocabulary the
- * admin API reports and `kici-admin trust-policy show` renders.
+ * The enforcement vocabulary the admin API reports and `kici-admin
+ * trust-policy show` renders.
  *
- * `policy` means `resolveEffectivePolicy` produced a policy and all three arms
- * apply; `legacy` means it produced `null`, so only the legacy
- * workflow-modification rule runs and there are no policy values to report.
- * Named here, next to the resolver that decides between them, so the route and
- * the CLI cannot drift apart on a bare string literal.
+ * @deprecated The route reports `policy` unconditionally: `resolveEffectivePolicy`
+ * returns a policy for every input, so there is no state left in which the
+ * values are absent. The field and this enum stay so an older `kici-admin`
+ * binary keeps parsing the response. Removed at v1.0.0.
  */
 export declare const TrustPolicyEnforcement: z.ZodEnum<{
     legacy: "legacy";
     policy: "policy";
 }>;
 export type TrustPolicyEnforcement = z.infer<typeof TrustPolicyEnforcement>;
-/** The per-PR facts the policy is evaluated against. */
+/** The per-PR facts the fork switch is evaluated against. */
 export interface TrustPolicySignals {
-    /** Resolved contributor tier; undefined when trust resolution failed. */
+    /** Resolved contributor tier; undefined when no tier was resolved. */
     tier: TrustTier | undefined;
     /** The PR's head repo differs from its base repo. */
     isForkPR: boolean;
-    /** The PR changes `.kici/` workflow definitions. */
-    hasWorkflowModifications: boolean;
 }
 /**
- * The reasons the ORG TRUST POLICY itself can raise — its three arms.
+ * The reason the ORG TRUST POLICY itself raises.
  *
- * `context_trust` is excluded at the type level rather than merely by
- * convention: that reason belongs to the per-context minimum-trust gate, which
- * holds an individual job under its real name. Narrowing here is what lets
- * `SECURITY_HOLD_JOB_IDS` drop its phantom `context_trust` sentinel — a value
- * that existed only to satisfy a `Record<SecurityHoldReason, ...>` and was never
- * written to a single row.
+ * The fork switch is the policy's only arm, so `fork_pr` is the only reason it
+ * can produce. The `SecurityHoldReason` Zod enum deliberately keeps its other
+ * members: `held_runs` rows written by earlier builds still carry them, and the
+ * per-context minimum-trust gate still writes `context_trust` under its own
+ * name. Narrowing here is a statement about what this gate emits, not about
+ * what the column may hold.
  */
-export type TrustPolicyHoldReason = Exclude<SecurityHoldReason, 'context_trust'>;
+export type TrustPolicyHoldReason = Extract<SecurityHoldReason, 'fork_pr'>;
 export type TrustPolicyOutcome = {
     action: 'pass';
+}
+/**
+ * Drop the event entirely: no run row, no check status, nothing dispatched.
+ * The pipeline enforces this before it fetches a lock file, so an ignored
+ * event leaves no trace a contributor can see.
+ */
+ | {
+    action: 'ignore';
 } | {
     action: 'hold';
     reason: TrustPolicyHoldReason;
     message: string;
     /**
-     * Hours the resulting hold stays approvable, taken from the SAME policy
-     * that produced this verdict. `null` in independent mode, where there is
-     * no upstream policy and therefore no operator-set window.
+     * Seconds the resulting hold stays approvable, taken from the SAME policy
+     * that produced this verdict.
      *
      * Carried on the outcome rather than re-read at the hold site: a second,
      * independent read bypassed `resolveEffectivePolicy`, so it was both a
      * TOCTOU (the policy could change between deciding and sizing) and a
-     * divergence — independent mode got the 72h default where the decision
-     * path deliberately has no policy at all.
+     * divergence between deciding and sizing. `null` means "no window came
+     * with this verdict", and the hold site falls back to
+     * `DEFAULT_APPROVAL_EXPIRY_SECONDS`.
+     *
+     * Seconds, not hours, because this is what the hold site actually needs:
+     * an hours-only window cannot express the sub-hour hold the policy may now
+     * carry, and rounding it here would silently lengthen it.
      */
-    approvalExpiryHours: number | null;
+    approvalExpirySeconds: number | null;
 } | {
     action: 'reject';
     reason: TrustPolicyHoldReason;
     message: string;
 };
 /**
- * The policy a Platform-attached orchestrator applies when it has no stored
- * row. Every arm holds — a hold is recoverable by approval, and these are the
- * documented org defaults, so an org that never changed its policy gets the
- * behavior its dashboard shows.
+ * The reason a verdict carries, or `undefined` for one that carries none.
+ *
+ * Logging and check-status call sites take any outcome, so they need the reason
+ * without narrowing the union themselves — and a call site that reached for
+ * `.reason` on a reasonless verdict would print `undefined` rather than fail.
+ */
+export declare function trustPolicyOutcomeReason(outcome: TrustPolicyOutcome): TrustPolicyHoldReason | undefined;
+/** The fork switch applied when no policy row is stored. */
+export declare const DEFAULT_FORK_POLICY: ForkPolicy;
+/**
+ * The policy applied when no row is stored — in every mode. Ignoring fork
+ * events is the fail-closed posture: nothing foreign dispatches, and the event
+ * is dropped rather than parked in a queue nobody is watching.
  *
  * This is NOT necessarily a brief transient. The Platform sends
  * `trust_policy.update` only when the org has a `trust_policies` row, and that
  * row is created lazily on a dashboard read — so an org that has never opened
  * Settings > CI trust receives no push at all and stays on these values
- * indefinitely. The expiry is therefore the generous documented default rather
- * than a short one: a short window would auto-fail legitimate runs.
+ * indefinitely.
  */
 export declare const FAIL_CLOSED_POLICY: TrustPolicy;
 /**
- * Pick the policy to evaluate. A stored row always wins. Without one, a
- * Platform-attached orchestrator fails closed (a push is imminent); an
- * independent orchestrator has no upstream authority at all, so it gets `null`
- * and the evaluator applies only the legacy rule — which is what keeps this
- * change from silently gating existing independent deployments on upgrade.
+ * The policy applied when the stored row could not be READ — a thrown query, a
+ * dropped connection.
+ *
+ * Distinct from `FAIL_CLOSED_POLICY`, which answers a different question: that
+ * one is what an org with no stored row has chosen by not choosing. A read
+ * failure says nothing about what the org chose, and an org that chose `hold`
+ * or `allow` would have its fork PRs dropped with no trace if the two cases
+ * shared an answer — a transient database blip turning a recoverable,
+ * contributor-visible hold into a silent disappearance.
  *
- * `PLATFORM_CONNECTED_MODES` is the shared definition of "expects a Platform
- * push", so a mode added there is fail-closed here without a second edit.
+ * Holding is fail-closed on the same terms: nothing untrusted dispatches. It is
+ * also recoverable — the contributor sees the security check, and an operator
+ * can approve it — which an ignored event is not.
  */
-export declare function resolveEffectivePolicy(stored: StoredTrustPolicy | null, mode: OrchestratorMode): TrustPolicy | null;
+export declare const READ_FAILURE_POLICY: TrustPolicy;
 /**
- * Evaluate the policy.
- *
- * Arms are evaluated in a fixed order — workflow_modification, fork_pr,
- * unknown_contributor — and then any `reject` beats any `hold`, with the first
- * arm in that order supplying the reason among equals. That makes a PR tripping
- * several arms produce one outcome with a stable reason rather than a verdict
- * that depends on evaluation accident.
+ * Pick the policy to evaluate. A stored row always wins; without one every
+ * orchestrator gets the fail-closed policy above.
  *
- * An unresolved tier (`undefined`) counts as `unknown`, never as a pass: a
- * trust resolution that could not be answered is not evidence of trust.
+ * `mode` no longer selects between two postures — an independent orchestrator
+ * has no upstream authority, which is a reason to be stricter rather than more
+ * permissive — but it stays on the signature so callers that legitimately hold
+ * a mode do not have to change, and so a future per-mode difference has a place
+ * to land.
+ */
+export declare function resolveEffectivePolicy(stored: StoredTrustPolicy | null, _mode: OrchestratorMode): TrustPolicy;
+/**
+ * Evaluate the fork switch.
  *
- * A `null` policy applies only the legacy rule (workflow modifications by a
- * non-trusted contributor hold), reproducing behavior from before the policy was
- * enforced.
+ * Two guards precede it. A `trusted` tier passes: the ref lives in the base
+ * repo, so only a write-or-higher contributor could have put it there. A
+ * non-fork event passes too — the switch names one condition, and an event that
+ * does not meet it has no verdict to receive here. Reduced privilege for a
+ * non-trusted contributor is derived from the tier further down the pipeline,
+ * not from this outcome.
  */
-export declare function evaluateTrustPolicy(policy: TrustPolicy | null, signals: TrustPolicySignals): TrustPolicyOutcome;
+export declare function evaluateTrustPolicy(policy: TrustPolicy, signals: TrustPolicySignals): TrustPolicyOutcome;
 //# sourceMappingURL=trust-policy-gate.d.ts.map

package/dist/security/trust-policy-store.d.ts

@@ -20,6 +20,9 @@ export type TrustPolicySource = z.infer<typeof TrustPolicySource>;
 /**
  * The strictest documented defaults. Used to fill gaps on a local merge; the
  * fail-closed policy an unknown org resolves to lives in `trust-policy-gate.ts`.
+ *
+ * `forkPolicy` reads that module's `DEFAULT_FORK_POLICY` so a partial local
+ * merge and an absent row settle on the same fork switch.
  */
 export declare const DEFAULT_TRUST_POLICY: TrustPolicy;
 /** A policy as stored, with its provenance. */

package/dist/security/trust-resolver.d.ts

@@ -1,108 +1,24 @@
 /**
- * TrustResolver -- combines identity links, RBAC ci_trust, and provider permissions
- * into a trust tier decision.
+ * Ref-based trust: may this git ref reach shared state and real secrets?
  *
- * The TrustResolver is the core decision engine for CI security. It determines
- * whether a contributor is trusted, known, or unknown based on:
- * 1. Identity link lookup (provider username -> KiCI user ID)
- * 2. ci_trust RBAC level for that user in the org
- * 3. Provider API permission (via ContributorResolver + cache)
- */
-import type { ContributorPermission, ContributorResolver } from '@kici-dev/engine';
-import type { TrustTier } from '@kici-dev/engine';
-import type { ContributorCache } from './contributor-cache.js';
-/**
- * Match an identity link strictly by `(provider, providerUserId)`.
- *
- * Returns `null` whenever the numeric id is missing on either side or when no
- * link's id matches the event's id. This is the strict end-state contract:
- * username fallback is gone, mutable-username impersonation cannot grant
- * trust, and a refused match is recorded under
- * `kici_orch_trust_match_refused_no_id_total{reason}` so the rate of refusals
- * stays observable.
+ * Trusted ⇔ the ref lives in the base repo (any same-repo push or PR —
+ * only a write-or-higher contributor can put a ref there). Untrusted ⇔ the
+ * ref comes from a fork. Resolved locally from the webhook payload; no
+ * provider API call, no identity lookup.
  *
- * Pre-conditions for callers: Platform's reconcile job has filled
- * `provider_user_id` for every row in `identity_links` (verified by the
- * `kici_platform_identity_links_missing_provider_user_id` gauge being 0 for
- * ≥4 cycles before this strict policy was deployed). See
- * `.claude/plans/cryptic-jumping-narwhal.md` for the rollout journey.
+ * The stored/wire tier vocabulary keeps 'unknown' as the name for
+ * "untrusted" and 'trusted' for "trusted"; 'known' is legacy vocabulary
+ * that is no longer produced.
  */
-export declare function findIdentityLink(identityLinks: IdentityLink[], provider: string, providerUsername: string, providerUserId: string | undefined): IdentityLink | null;
-/** RBAC permission levels from the Platform permission system. */
-export type PermissionLevel = 'none' | 'read' | 'write' | 'admin';
-/** Identity link mapping a provider identity to a KiCI user. */
-export interface IdentityLink {
-    userId: string;
-    provider: string;
-    providerUsername: string;
-    /**
-     * Immutable IDP-side numeric id (e.g. GitHub's `sender.id`).
-     * Nullable during the backfill window for legacy rows that
-     * predate Platform migration 009. Trust resolver matches on
-     * this field first; once backfill completes the strict policy
-     * refuses trust when this is null.
-     */
-    providerUserId?: string | null;
-}
-/** Parameters for trust tier resolution. */
-interface TrustResolutionParams {
-    /** Sender username from the webhook event. */
-    providerUsername: string;
-    /**
-     * Sender immutable IDP-side numeric id from the webhook event (e.g.
-     * GitHub's `sender.id` coerced to string). Optional during the backfill
-     * window; the strict end-state refuses trust when this is missing.
-     */
-    providerUserId?: string;
-    /** Provider type (e.g. 'github'). */
-    provider: string;
-    /** Repository identifier (e.g. 'owner/repo'). */
-    repoIdentifier: string;
-    /** Whether the PR comes from a fork. */
-    isForkPR: boolean;
-    /** Organization ID this webhook routes to. */
-    orgId: string;
-    /** Cached identity links from Platform push. */
-    identityLinks: IdentityLink[];
-    /** ci_trust permission levels per user ID from Platform push. */
-    orgMemberPermissions: Map<string, PermissionLevel>;
-    /** Provider-specific contributor resolver. */
-    contributorResolver: ContributorResolver;
-    /** Credentials for provider API calls. */
-    credentials: unknown;
-}
-/** Result of trust tier resolution with full audit trail. */
+import type { TrustTier } from '@kici-dev/engine';
+/** Result of ref-based trust resolution, with the reason recorded for audit. */
 export interface TrustResolution {
     tier: TrustTier;
     contributorUsername: string;
-    identityLinked: boolean;
-    userId?: string;
-    providerPermission: ContributorPermission;
-    ciTrustLevel?: PermissionLevel;
     reason: string;
 }
-/**
- * TrustResolver combines identity links, ci_trust RBAC, and provider permissions
- * into a trust tier.
- *
- * Decision matrix:
- * 1. Fork PR -> always unknown
- * 2. No identity link -> provider API fallback (never trusted)
- *    - read+ -> known
- *    - none -> unknown
- * 3. Identity linked -> combine ci_trust + provider permission:
- *    - provider write+ AND ci_trust write+ -> trusted
- *    - provider write+ AND ci_trust none/read -> known
- *    - provider read -> known
- *    - provider none -> unknown
- */
-export declare class TrustResolver {
-    private readonly contributorCache;
-    constructor(contributorCache: ContributorCache);
-    /**
-     * Resolve the trust tier for a contributor.
-     */
-    resolveTrustTier(params: TrustResolutionParams): Promise<TrustResolution>;
-}
-export {};
+export declare function resolveRefTrust(args: {
+    isForkPR: boolean;
+    contributorUsername: string;
+}): TrustResolution;
 //# sourceMappingURL=trust-resolver.d.ts.map

package/dist/server.d.ts

@@ -13,5 +13,15 @@
  * Graceful shutdown in reverse order:
  * Platform client -> agent WS -> heartbeat -> HTTP -> DB
  */
-export {};
+import type { OrchestratorFaultInjection } from './testing/fault-injection.js';
+/**
+ * Boot the Platform-connected orchestrator. Factored out of the module entry so
+ * both this file's production entry (which passes no fault injection) and the
+ * test-only `server-test.ts` entry (which passes an injected fault-injection
+ * policy) run the identical bootstrap through one code path. Exported solely for
+ * that single test-only caller; nothing else imports it.
+ */
+export declare function runServer(opts?: {
+    faultInjection?: OrchestratorFaultInjection;
+}): Promise<void>;
 //# sourceMappingURL=server.d.ts.map