Step 1: Validate Request

Validate the incoming request:

1. Verify operation is "emit"
2. Verify event_type is one of the supported types
3. Verify payload is present

If validation fails, return error with details.

Step 2: Generate or Validate Workflow ID

If workflow_id not provided:

WORK_ID="${work_id:-unknown}"
TIMESTAMP=$(date -u +"%Y%m%dT%H%M%SZ")
WORKFLOW_ID="workflow-${WORK_ID}-${TIMESTAMP}"

Store in workflow state for subsequent events in same workflow.

Step 3: Build Event Object

Construct the full event with automatic fields:

{
  "event_type": "{event_type}",
  "workflow_id": "{workflow_id}",
  "timestamp": "{ISO 8601 UTC}",
  "project": "{detected from git or PWD}",
  "environment": "${FRACTARY_ENV:-development}",
  "payload": {payload}
}

Step 4: Detect Project and Environment

# Project detection
PROJECT=$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")

# Environment detection
ENVIRONMENT="${FRACTARY_ENV:-development}"

Step 5: Write Event to Logs

Invoke log-writer skill with:

• log_type: "workflow"
• data: The constructed event object

Or use script directly:

scripts/emit-event.sh \
  --event-type "{event_type}" \
  --workflow-id "{workflow_id}" \
  --payload '{payload_json}'

The log-writer handles:

• Writing to .fractary/logs/workflow/
• S3 push (if configured in logs config)
• Retention policy

S3 Push Architecture:

The emit-event.sh script writes events to local storage only. S3 push is handled separately:

1. Via log-writer skill (recommended): Invoke log-writer instead of direct script call. The log-writer checks config and pushes to S3 if enabled.

2. Via background sync: Configure a background process or hook to sync .fractary/logs/workflow/ to S3 periodically.

3. Via CI/CD: Push logs to S3 as part of workflow completion in CI pipeline.

Configuration for S3 push (in .fractary/plugins/logs/config.json):

{
  "types": {
    "workflow": {
      "cloud_storage": {
        "enabled": true,
        "provider": "s3",
        "bucket": "${ORG}.logs.${PROJECT}"
      }
    }
  }
}

See plugins/logs/types/workflow/standards.md for complete S3 configuration options.

Step 6: Return Result

Return confirmation:

{
  "status": "success",
  "event_type": "{event_type}",
  "workflow_id": "{workflow_id}",
  "timestamp": "{timestamp}",
  "log_path": "{path to written log}"
}