@fabrika/provider-contract 0.0.4 → 0.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/provider-contract",
-	"version": "0.0.4",
+	"version": "0.0.5",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -26,6 +26,6 @@
 		"test": "bun test"
 	},
 	"dependencies": {
-		"@fabrika/auth-core": "^0.0.4"
+		"@fabrika/auth-core": "^0.0.5"
 	}
 }

package/src/control.ts

@@ -46,6 +46,21 @@ export interface ProviderRegistrationInput {
 /** Canonical registration returned after provider-owned validation and normalization. */
 export type ProviderRegistration = ProviderRegistrationInput
 
+/** Provider-neutral input for resolving one requested source ref to an immutable Git object id. */
+export interface ProviderSourceResolutionInput {
+	readonly runId: string
+	readonly app: ProviderApp
+	readonly environment: ProviderEnvironment
+	/** An immutable commit already recorded by the trigger, which resolution must verify exactly. */
+	readonly expectedCommitSha?: string
+	readonly signal: AbortSignal
+}
+
+/** The exact source revision a provider resolved before starting deploy work. */
+export interface ProviderSourceResolution {
+	readonly commitSha: string
+}
+
 /** One control-plane deploy invocation. */
 export interface ProviderDeployInput {
 	readonly runId: string
@@ -89,6 +104,8 @@ export interface ProviderRunReference {
 	readonly runId: string
 	readonly externalId: string
 	readonly environment: ProviderEnvironment
+	/** Credential-free provider-owned progress needed to resume the external operation. */
+	readonly providerState?: JsonValue
 }
 
 export type ProviderCancelInput = ProviderRunReference
@@ -96,6 +113,8 @@ export type ProviderCancelInput = ProviderRunReference
 export interface ProviderReconcileInput extends ProviderRunReference {
 	/** See `ProviderDeployInput.returnOrigins`; a provider that finishes a resumed deploy projects the same set. */
 	readonly returnOrigins?: readonly string[]
+	/** Persist a credential-free recovery checkpoint before the next irreversible provider call. */
+	checkpoint(state: JsonValue): Promise<void>
 }
 
 /** The latest state reported while reconciling a platform-owned run. */
@@ -216,6 +235,7 @@ export interface ProviderNamespaceCapabilities {
 export interface ControlProvider {
 	readonly id: string
 	normalizeRegistration(input: ProviderRegistrationInput): ProviderRegistration
+	resolveSource?(input: ProviderSourceResolutionInput): Promise<ProviderSourceResolution>
 	deploy(input: ProviderDeployInput): Promise<ProviderTerminalOutcome>
 	cancel?(input: ProviderCancelInput): Promise<void>
 	reconcile?(input: ProviderReconcileInput): Promise<ProviderReconcileOutcome>

package/src/deploy.ts

@@ -1,4 +1,4 @@
-import type { ProviderEnvelope } from './json'
+import type { JsonValue, ProviderEnvelope } from './json'
 
 /** One provider-owned unit of deploy work. Core treats `kind` as an open string. */
 export interface ProviderJobSpec {
@@ -45,7 +45,10 @@ export interface ProviderDeployResult {
 /** Events whose persistence and presentation belong to the control plane. */
 export interface ProviderRunEvents {
 	log(line: string): void
-	externalId(id: string): Promise<void>
+	/** Atomically persist the external operation id and, when supplied, its credential-free resume state. */
+	externalId(id: string, state?: JsonValue): Promise<void>
+	/** Replace the credential-free resume state while this run remains active. */
+	checkpoint(state: JsonValue): Promise<void>
 }
 
 /** Complete platform-owned runtime state. A null value removes the key from persistent targets. */