codex-chatgpt-control 0.5.1-alpha.2 → 0.5.1-alpha.3

package/dist/src/operations/turn-ownership.d.ts

@@ -0,0 +1,202 @@
+/**
+ * The turn ownership classifier deliberately accepts normalized, already
+ * redacted observations.  It must never be handed DOM nodes or prompt text.
+ * Adapters are responsible for producing the bounded digests in these types.
+ */
+export declare const TURN_OWNERSHIP_SCHEMA_VERSION: "chatgpt.browser_control.turn_ownership.v1";
+export type OwnershipDigest = string;
+export type OwnershipIdentityEvidence = {
+    readonly status: "available";
+    /** Stable provider/browser/tab/thread identity, never user content. */
+    readonly value: string;
+} | {
+    readonly status: "unavailable";
+    readonly reason: "not_exposed" | "not_observed" | "redacted";
+};
+export type OwnershipTargetEvidence = {
+    readonly provider: OwnershipIdentityEvidence;
+    readonly browser: OwnershipIdentityEvidence;
+    readonly tab: OwnershipIdentityEvidence;
+    readonly thread: OwnershipIdentityEvidence;
+    readonly conversation: OwnershipIdentityEvidence;
+    readonly canonicalThreadUrl: OwnershipIdentityEvidence;
+    readonly authoritativeTabClaim: OwnershipIdentityEvidence;
+    readonly coordinationScope: "process" | "provider";
+};
+export type OwnershipEvidenceProfile = {
+    readonly stableConversationId: "required" | "unavailable";
+    readonly stableUserTurnId: "required" | "unavailable";
+    readonly stableAssistantTurnId: "required" | "unavailable";
+    readonly stableBranchId: "required" | "unavailable";
+    readonly authoritativeTabClaim: "required" | "unavailable";
+};
+export type OwnershipBinding = {
+    readonly schemaVersion: typeof TURN_OWNERSHIP_SCHEMA_VERSION;
+    readonly operationId: string;
+    readonly targetBindingDigest: OwnershipDigest;
+    readonly target: OwnershipTargetEvidence;
+    readonly evidenceProfile: OwnershipEvidenceProfile;
+    readonly replacementTabRecovery: boolean;
+    readonly actionId: string;
+    readonly actionKind: "send" | "work_steer";
+};
+export type OwnershipTurn = {
+    /** Stable turn ID, when the provider exposes one. Never raw turn text. */
+    readonly stableId?: string;
+    /** HMAC/cryptographic evidence digest for the normalized turn. */
+    readonly evidenceDigest: OwnershipDigest;
+    /** Deterministic structure digest; text is never accepted by this module. */
+    readonly structureDigest: OwnershipDigest;
+    /** Ordered position in the normalized provider snapshot. */
+    readonly ordinal: number;
+    /** Stable parent identity for assistant turns. */
+    readonly parentStableId?: string;
+    /** Stable branch identity for assistant turns. */
+    readonly branchStableId?: string;
+    readonly state?: "generating" | "terminal";
+    readonly artifactEvidenceDigests?: readonly OwnershipDigest[];
+};
+export type OwnershipSnapshotCompleteness = "complete" | "truncated" | "incomplete" | "out_of_order";
+export type OwnershipSnapshot = {
+    readonly schemaVersion: typeof TURN_OWNERSHIP_SCHEMA_VERSION;
+    readonly snapshotDigest: OwnershipDigest;
+    readonly target: OwnershipTargetEvidence;
+    readonly userTurns: readonly OwnershipTurn[];
+    readonly assistantTurns: readonly OwnershipTurn[];
+    readonly completeness: OwnershipSnapshotCompleteness;
+    readonly terminalState: "idle" | "generating" | "terminal" | "unknown";
+    /** Captured by the adapter after Send using the exact before/after delta. */
+    readonly postSendDelta?: OwnershipDeltaEvidence;
+};
+export type OwnershipBaseline = {
+    readonly schemaVersion: typeof TURN_OWNERSHIP_SCHEMA_VERSION;
+    /** Digest of the complete pre-Send normalized snapshot. */
+    readonly snapshotDigest: OwnershipDigest;
+    readonly target: OwnershipTargetEvidence;
+    readonly userTurns: readonly OwnershipTurn[];
+    readonly assistantTurns: readonly OwnershipTurn[];
+    readonly completeness: "complete";
+};
+export type OwnershipDeltaEvidence = {
+    readonly baselineSnapshotDigest: OwnershipDigest;
+    /** Exact new-user evidence digests from the normalized before/after delta. */
+    readonly addedUserEvidenceDigests: readonly OwnershipDigest[];
+    /** Digest over the canonical delta object, generated by the adapter. */
+    readonly deltaDigest: OwnershipDigest;
+};
+export type OwnershipSubmissionWitness = {
+    readonly actionId: string;
+    readonly actionKind: "send" | "work_steer";
+    /** Digest of the complete authenticated pre-Send ownership snapshot. */
+    readonly baselineSnapshotDigest: OwnershipDigest;
+    /** Durable action evidence for the exact post-Send user-turn delta. */
+    readonly postSendDeltaDigest: OwnershipDigest;
+    /** Durable evidence for the operation's submitted user turn. */
+    readonly operationUserEvidenceDigest: OwnershipDigest;
+    /** Optional immediate stable ID returned by the provider. */
+    readonly userTurnStableId?: string;
+};
+export type OwnershipCursorPhase = "owned_user_turn" | "owned_assistant_generating" | "owned_assistant_terminal";
+export type OwnershipCursor = Readonly<{
+    readonly schemaVersion: typeof TURN_OWNERSHIP_SCHEMA_VERSION;
+    readonly operationId: string;
+    readonly targetBindingDigest: OwnershipDigest;
+    readonly phase: OwnershipCursorPhase;
+    readonly userTurnId: string;
+    readonly userTurnEvidenceDigest: OwnershipDigest;
+    readonly assistantTurnId?: string;
+    readonly assistantBranchId?: string;
+    /** Digest of the normalized snapshot from which this cursor was issued. */
+    readonly snapshotDigest: OwnershipDigest;
+    /** Frozen assistant evidence used to detect mutation after terminal capture. */
+    readonly assistantEvidenceDigest?: OwnershipDigest;
+    readonly assistantStructureDigest?: OwnershipDigest;
+}>;
+export type OwnershipResultStatus = "no_operation_turn" | "owned_user_turn" | "owned_assistant_generating" | "owned_assistant_terminal" | "target_mismatch" | "target_evidence_unavailable" | "concurrent_user_turn" | "regeneration_ambiguous" | "ownership_ambiguous";
+export type OwnershipReason = "none" | "target_binding_mismatch" | "target_evidence_unavailable" | "replacement_tab_requires_owned_user" | "incomplete_snapshot" | "out_of_order_snapshot" | "baseline_turn_missing" | "baseline_turn_changed" | "intervening_user_turn" | "multiple_new_user_turns" | "operation_user_evidence_mismatch" | "post_send_delta_missing" | "post_send_delta_mismatch" | "stable_user_turn_id_unavailable" | "stable_assistant_turn_id_unavailable" | "stable_parent_identity_unavailable" | "stable_branch_identity_unavailable" | "assistant_parent_mismatch" | "assistant_state_unknown" | "terminal_state_mismatch" | "regeneration_siblings" | "prior_owned_turn_missing" | "prior_owned_turn_changed" | "prior_cursor_mismatch" | "unexpected_new_assistant_turn" | "baseline_target_mismatch";
+export type OwnershipRecoveryObservation = {
+    readonly status: "not_observed";
+} | {
+    readonly status: "owned_user_turn";
+    readonly userTurnId: string;
+    readonly evidenceDigest: OwnershipDigest;
+} | {
+    readonly status: "owned_assistant_generating";
+    readonly userTurnId: string;
+    readonly assistantTurnId: string;
+    readonly evidenceDigest: OwnershipDigest;
+} | {
+    readonly status: "owned_assistant_terminal";
+    readonly userTurnId: string;
+    readonly assistantTurnId: string;
+    readonly evidenceDigest: OwnershipDigest;
+} | {
+    readonly status: "ambiguous";
+    readonly evidenceDigest?: OwnershipDigest;
+};
+export type OwnershipEvidenceMaterial = Readonly<{
+    readonly schemaVersion: typeof TURN_OWNERSHIP_SCHEMA_VERSION;
+    readonly operationId: string;
+    readonly status: OwnershipResultStatus;
+    readonly reason: OwnershipReason;
+    readonly target: Readonly<{
+        readonly provider: "available" | "unavailable";
+        readonly browser: "available" | "unavailable";
+        readonly tab: "available" | "unavailable";
+        readonly thread: "available" | "unavailable";
+        readonly conversation: "available" | "unavailable";
+        readonly canonicalThreadUrl: "available" | "unavailable";
+        readonly authoritativeTabClaim: "available" | "unavailable";
+        readonly replacedTab: boolean;
+    }>;
+    readonly baselineSnapshotDigest: OwnershipDigest;
+    readonly snapshotDigest: OwnershipDigest;
+    readonly postSendDeltaDigest?: OwnershipDigest;
+    readonly addedUserCount: number;
+    readonly addedAssistantCount: number;
+    readonly terminalState: OwnershipSnapshot["terminalState"];
+    readonly userTurn?: Readonly<{
+        readonly evidenceDigest: OwnershipDigest;
+        readonly structureDigest: OwnershipDigest;
+        readonly ordinal: number;
+        readonly stableIdAvailable: boolean;
+        readonly parentStableIdAvailable: boolean;
+        readonly branchStableIdAvailable: boolean;
+        readonly artifactEvidenceDigests: readonly OwnershipDigest[];
+        readonly state?: OwnershipTurn["state"];
+    }>;
+    readonly assistantTurn?: Readonly<{
+        readonly evidenceDigest: OwnershipDigest;
+        readonly structureDigest: OwnershipDigest;
+        readonly ordinal: number;
+        readonly stableIdAvailable: boolean;
+        readonly parentStableIdAvailable: boolean;
+        readonly branchStableIdAvailable: boolean;
+        readonly artifactEvidenceDigests: readonly OwnershipDigest[];
+        readonly state?: OwnershipTurn["state"];
+    }>;
+}>;
+export type OwnershipClassification = Readonly<{
+    readonly status: OwnershipResultStatus;
+    readonly reason: OwnershipReason;
+    readonly evidence: OwnershipEvidenceMaterial;
+    readonly recoveryObservation: OwnershipRecoveryObservation;
+    readonly cursor?: OwnershipCursor;
+}>;
+export type TurnOwnershipInput = {
+    readonly binding: OwnershipBinding;
+    readonly baseline: OwnershipBaseline;
+    readonly snapshot: OwnershipSnapshot;
+    readonly submissionWitness?: OwnershipSubmissionWitness;
+    readonly prior?: OwnershipCursor;
+};
+/**
+ * Classify one normalized snapshot.  This function has no browser, DOM, or
+ * I/O dependency.  It only permits an owned user turn when the adapter has
+ * supplied the exact post-Send delta digest and operation-specific evidence.
+ */
+export declare function classifyTurnOwnership(input: TurnOwnershipInput): OwnershipClassification;
+/** Return the deterministic, redacted JSON input a caller may HMAC. */
+export declare function ownershipEvidenceJson(material: OwnershipEvidenceMaterial): string;
+/** Validate a cursor before persisting or supplying it to a later snapshot. */
+export declare function validateOwnershipCursor(cursor: OwnershipCursor): void;