feat: add workspace operation and operation task contracts

Agent-Logs-Url: https://github.com/SourceOS-Linux/sourceos-syncd/sessions/744c639e-1999-4873-80c6-cbc4b6f037f1

Co-authored-by: mdheller <21163552+mdheller@users.noreply.github.com>

Author: Copilot

docs/contracts.md

@@ -2,7 +2,7 @@
 
 Canonical architecture: `SourceOS-Linux/sourceos-spec/docs/architecture/sourceos-state-integrity-layer.md`
 
-This repository implements the first executable contract for SourceOS State Integrity. The current implementation lane is Python and standard-library-first. It provides State Integrity Report generation, diagnosis, verification, non-destructive repair planning, a filesystem-backed local store prototype, an append-only JSONL event log, registry persistence, and contract models for actors, schemas, objects, policy decisions, conflicts, events, profiles, devices, sync plans, and agent object transactions.
+This repository implements the first executable contract for SourceOS State Integrity. The current implementation lane is Python and standard-library-first. It provides State Integrity Report generation, diagnosis, verification, non-destructive repair planning, a filesystem-backed local store prototype, an append-only JSONL event log, registry persistence, and contract models for actors, schemas, objects, policy decisions, conflicts, events, profiles, devices, sync plans, workspace operations, operation tasks, and agent object transactions.
 
 The next daemon phases should extend this baseline into full event-log, policy, profile, repair, service, and adapter subsystems without breaking the current JSON report contracts.
 
@@ -114,6 +114,8 @@ sourceos.conflict-record/v1alpha1
 sourceos.policy-decision/v1alpha1
 sourceos.integrity-event/v1alpha1
 sourceos.agent-object-transaction/v1alpha1
+sourceos.workspace-operation/v1alpha1
+sourceos.operation-task/v1alpha1
 ```
 
 Use `validate_contract(record)` to validate a JSON object by its `schema` field. Use the specific dataclass `from_dict()` helpers when callers know the expected type.
@@ -139,6 +141,8 @@ conflict.alpha.json
 policy.decision-review.json
 event.object-alpha-created.json
 agent-transaction.alpha.json
+workspace-operation.alpha.json
+operation-task.alpha.json
 ```
 
 The contract test suite loads every fixture, validates it through the model registry, and round-trips each fixture through its dataclass model.
@@ -223,6 +227,18 @@ Agent transaction statuses:
 draft, proposed, approved, applied, rejected, reverted
 ```
 
+Workspace operation types:
+
+```text
+sync.operation.enqueue, sync.operation.replay, sync.operation.reconcile, sync.conflict.detect, sync.conflict.resolve, sync.repair.apply, sync.tombstone.apply, sync.checkpoint.write
+```
+
+Decision card options:
+
+```text
+merge, fork, skip
+```
+
 Device states:
 
 ```text

examples/contracts/conflict.alpha.json

@@ -10,6 +10,15 @@
   "schema_version": "v1",
   "severity": "review_required",
   "merge_policy": "human_review_required",
+  "decision_card": {
+    "card_id": "decision-card:conflict-alpha-001",
+    "options": ["merge", "fork", "skip"],
+    "recommended_option": "merge",
+    "selected_option": "fork",
+    "rationale": "Payload lineage diverged after remote replay; preserve both versions for review.",
+    "selected_by": "actor:local-user",
+    "selected_at": "2026-05-05T00:07:30Z"
+  },
   "user_explanation": "Two scoped actors produced competing updates for the same object fixture.",
   "created_at": "2026-05-05T00:07:00Z"
 }

examples/contracts/operation-task.alpha.json

@@ -0,0 +1,19 @@
+{
+  "schema": "sourceos.operation-task/v1alpha1",
+  "task_id": "operation-task:alpha-0001",
+  "operation_id": "workspace-operation:alpha-001",
+  "operation_type": "sync.operation.replay",
+  "status": "succeeded",
+  "attempt": 1,
+  "idempotency_key": "idem-replay-alpha-0001",
+  "policy_decision_ref": "policy-decision:review-alpha",
+  "evidence_refs": ["evidence:operation-task-0001"],
+  "created_at": "2026-05-05T00:10:01Z",
+  "updated_at": "2026-05-05T00:10:06Z",
+  "started_at": "2026-05-05T00:10:02Z",
+  "completed_at": "2026-05-05T00:10:06Z",
+  "remote_operation_id": "remote-op:9931",
+  "conflict_id": "conflict:alpha-001",
+  "checkpoint_ref": "checkpoint:workspace-default-0001",
+  "replay_safe": true
+}

examples/contracts/workspace-operation.alpha.json

@@ -0,0 +1,32 @@
+{
+  "schema": "sourceos.workspace-operation/v1alpha1",
+  "operation_id": "workspace-operation:alpha-001",
+  "local_operation_id": "local-op:0001",
+  "remote_operation_id": "remote-op:9931",
+  "operation_type": "sync.operation.reconcile",
+  "status": "reconciled",
+  "workspace_id": "workspace:default",
+  "profile_id": "profile:local-dev",
+  "actor_id": "actor:agent-one",
+  "device_id": "device:local",
+  "encryption_profile_ref": "encryption-profile:local-default",
+  "local_log_ref": "journal:evt-00000001",
+  "checkpoint_ref": "checkpoint:workspace-default-0001",
+  "causal_parent_ids": ["local-op:0000"],
+  "conflict_ids": ["conflict:alpha-001"],
+  "provisional_artifact_ids": {
+    "artifact:temp-1": "object:alpha"
+  },
+  "artifact_reconciliation": {
+    "artifact:temp-1": "artifact:final-44"
+  },
+  "policy_decision_ref": "policy-decision:review-alpha",
+  "artifact_admission_ref": "artifact-admission:alpha-allow",
+  "ledger_evidence_refs": ["evidence:operation-0001"],
+  "replay_safe": true,
+  "stale_task": false,
+  "lease_expired": false,
+  "replay_idempotency_key": "idem-replay-alpha-0001",
+  "created_at": "2026-05-05T00:10:00Z",
+  "updated_at": "2026-05-05T00:10:05Z"
+}