Waypoint™ Canonical Domain Model

1. Purpose

This specification defines the canonical business concepts that Waypoint™ uses across Design, Plan, Execute, Deliver, governance, reporting, and integrations.

The canonical model must remain independent of Jira, GitHub, a specific AI provider, cloud provider, or deployment platform.

External systems are projections or execution providers. Waypoint™ owns lifecycle semantics.

2. Modeling principles

Stable Waypoint™ identities are distinct from external-system IDs.
Core entities are versioned where their approved meaning may change.
Lifecycle artifacts preserve history rather than being overwritten.
N:N relationships are first-class.
Requirements and decisions remain traceable to planned work, execution, evidence, and delivery.
Current state and historical events are both retained.
External references are modeled explicitly.
Reporting must be derivable from the canonical model without requiring Jira-specific interpretation.

3. Aggregate overview

Portfolio
  └── Project
      ├── Project Design Package
      │   ├── Requirement
      │   ├── Decision
      │   ├── Risk / Assumption / Open Question
      │   └── Design Artifact
      │
      ├── Execution Plan
      │   ├── Phase / Release
      │   ├── Epic / Work Package / Work Item
      │   ├── Dependency
      │   ├── Stream
      │   ├── Timebox
      │   └── Capability Requirement
      │
      ├── Execution
      │   ├── Assignment
      │   ├── Reservation
      │   ├── Execution Run
      │   ├── Workspace
      │   ├── Validation
      │   └── Evidence
      │
      ├── Delivery
      │   ├── Delivery Unit
      │   ├── Delivery Run
      │   ├── Release
      │   ├── Target
      │   └── Acceptance
      │
      └── Governance
          ├── Gate
          ├── Approval
          ├── Policy Decision
          ├── Exception
          └── Audit Event

Worker Registry
  ├── Worker
  ├── Agent Profile
  ├── Capability
  ├── Skill
  ├── Tool
  └── Execution Environment

4. Project and portfolio entities

4.1 Portfolio

Optional grouping for projects.

Key attributes:

portfolio_id;
name;
owner;
status;
metadata.

4.2 Project

Root lifecycle aggregate.

Key attributes:

project_id;
name;
description;
project_type;
owner;
lifecycle_state;
priority;
portfolio_id;
created_at;
completed_at;
current_design_version;
current_plan_version.

A Project should not embed external Jira project identity as its primary key.

4.3 Stakeholder

Represents a person, team, role, or organizational participant.

Relationships may identify:

owner;
contributor;
approver;
technical lead;
acceptance owner;
observer.

5. Design entities

5.1 ProjectDesignPackage

Versioned authoritative output of the Design Engine.

Attributes:

design_package_id;
project_id;
version;
status;
readiness_state;
created_at;
approved_at;
supersedes_version.

5.2 Requirement

Stable requirement identity with versionable content.

Attributes:

requirement_id;
project_id;
requirement_type;
title;
description;
rationale;
priority;
status;
source/provenance;
verification_method.

Requirements may relate to multiple work items and evidence records.

5.3 AcceptanceCriterion

May attach to:

requirement;
work item;
delivery unit;
project.

Attributes include criterion, verification method, required evidence type, and status.

5.4 Decision

Records a material design or architecture decision.

Attributes:

decision_id;
context;
decision;
alternatives;
rationale;
consequences;
decision_owner;
status;
version;
supersedes_decision_id.

5.5 Risk

Attributes:

risk_id;
statement;
impact;
likelihood;
mitigation;
owner;
status.

5.6 Assumption

Attributes:

assumption_id;
statement;
validation_method;
owner;
status;
impact_if_false.

5.7 OpenQuestion

Attributes:

question_id;
question;
classification;
owner;
blocking_stage;
resolution;
status.

5.8 Artifact

Generic versioned project artifact.

Examples:

Markdown specification;
architecture diagram;
API specification;
data model;
test plan;
runbook.

Attributes:

artifact_id;
artifact_type;
name;
version;
location/reference;
checksum where applicable;
status;
provenance.

6. Planning entities

6.1 ExecutionPlan

Versioned output of Planning.

Attributes:

execution_plan_id;
project_id;
design_package_version;
version;
status;
approval_state;
created_at;
supersedes_version.

6.2 WorkNode

A generic planning hierarchy node.

Attributes:

work_node_id;
project_id;
plan_version;
node_type;
parent_id;
title;
description;
priority;
state.

node_type may include:

phase;
release;
epic;
story;
work_package;
task;
bug.

Only appropriate leaf nodes are executable.

6.3 WorkItem

Executable specialization/logical view of WorkNode.

Attributes may include:

estimate;
estimate_unit;
confidence;
performer_category;
execution_constraints;
acceptance state;
actual effort/duration/cost.

6.4 Dependency

Explicit relationship between work or external prerequisites.

Attributes:

dependency_id;
predecessor;
successor;
dependency_type;
status;
external_reference if applicable.

6.5 Stream

Parallel/coherent work lane.

Attributes:

stream_id;
name;
purpose;
status;
concurrency policy.

Work items and workers may relate N:N to streams over time.

6.6 Timebox

Generic scheduled interval.

May represent:

sprint;
iteration;
wave;
maintenance window.

Attributes:

timebox_id;
type;
start;
end;
capacity assumptions.

6.7 RequirementCoverage

Traceability relation between requirements and planned work.

This relation should support coverage states such as:

implemented;
validated;
deferred;
excluded with approval.

7. Worker entities

7.1 Worker

Canonical performer.

Attributes:

worker_id;
worker_type;
name;
status;
capacity;
concurrency_limit;
cost_model;
policy_profile.

7.2 AgentProfile

Reusable AI-worker definition.

Attributes:

agent_profile_id;
provider/runtime reference;
configuration;
instruction reference;
autonomy level;
timeout;
concurrency;
cost metadata.

7.3 Capability

Normalized capability identifier.

Attributes:

capability_id;
canonical_name;
category;
description;
parent_capability_id;
status.

7.4 WorkerCapability

N:N relationship containing:

worker_id;
capability_id;
proficiency;
verification;
restrictions;
valid_from/to.

7.5 CapabilityRequirement

Links work to required/preferred capabilities.

7.6 Skill

Versioned procedural knowledge.

7.7 Tool

Actionable interface available to a worker.

7.8 ExecutionEnvironment

Runtime environment with network, tool, credential, data, and cleanup constraints.

8. Execution entities

8.1 Assignment

Represents intended or actual worker-to-work association.

Attributes:

assignment_id;
work_item_id;
worker_id;
assignment_type;
status;
assigned_at;
released_at.

8.2 Reservation

Durable lease preventing conflicting execution.

Attributes:

reservation_id;
work_item_id;
worker_id;
execution_run_id;
acquired_at;
expires_at;
renewed_at;
status.

8.3 ExecutionRun

Durable execution attempt.

Attributes:

execution_run_id;
work_item_id;
worker_id;
status;
attempt;
started_at;
ended_at;
heartbeat_at;
idempotency_key;
correlation_id;
failure_classification.

One work item may have multiple runs.

8.4 Workspace

Isolated execution context.

Attributes:

workspace_id;
workspace_type;
provider/reference;
status;
created_at;
cleanup_state.

8.5 ValidationRun

Represents a test/check/review.

Attributes:

validation_run_id;
validation_type;
subject;
status;
result;
executed_by;
started_at;
ended_at.

8.6 Evidence

Proof of completion, validation, approval, or delivery.

Attributes:

evidence_id;
evidence_type;
subject_type/id;
artifact/reference;
checksum;
produced_by;
created_at;
retention policy.

9. Delivery entities

9.1 DeliveryUnit

A coherent deliverable.

Attributes:

delivery_unit_id;
project_id;
name;
type;
status;
target_id;
acceptance_owner;
rollback_classification.

9.2 Release

Versioned deliverable grouping where applicable.

9.3 DeliveryTarget

Operational target.

Attributes:

target_id;
target_type;
provider;
environment;
external_reference;
criticality;
policy profile.

9.4 DeliveryRun

Durable attempt to deliver a unit.

Attributes:

delivery_run_id;
delivery_unit_id;
target_id;
status;
started_at;
ended_at;
artifact_manifest;
rollback_reference;
correlation_id.

9.5 Acceptance

Attributes:

acceptance_id;
delivery_unit_id/project_id;
decision;
approver;
criteria summary;
conditions;
timestamp.

10. Governance entities

10.1 Gate

Attributes:

gate_id;
gate_type;
scope;
status;
required_conditions;
required_approver_role.

10.2 Approval

Binds a decision to an exact artifact/action version.

Attributes:

approval_id;
gate_id;
subject_type/id/version;
approver;
decision;
conditions;
timestamp.

10.3 PolicyDecision

Attributes:

policy_decision_id;
policy;
inputs/reference;
outcome;
reason;
timestamp.

10.4 Exception

Structured authorized deviation.

10.5 AuditEvent

Append-oriented record of material activity.

Attributes:

audit_event_id;
project_id;
actor;
actor_type;
event_type;
subject;
action;
outcome;
timestamp;
correlation_id;
metadata.

11. External integration entities

11.1 ExternalReference

Maps a Waypoint™ entity to an external system.

Attributes:

external_reference_id;
entity_type/id;
provider;
external_type;
external_id;
URL/reference;
synchronization state.

Examples:

Jira issue;
GitHub PR;
Azure deployment;
Vercel deployment.

11.2 IntegrationConnection

Represents configured integration/provider connection without exposing credentials.

11.3 SyncState

Tracks reconciliation cursor/state, last successful synchronization, and drift/error state.

12. Reporting projections

Reporting should use dedicated read models/projections derived from canonical state and events.

Potential projections include:

project lifecycle snapshot;
portfolio snapshot;
work hierarchy progress;
requirement coverage;
sprint/timebox progress;
stream progress;
estimate versus actual;
worker utilization;
capability capacity;
execution reliability;
quality;
delivery history;
gate/approval status;
cost;
audit/evidence completeness.

The reporting API should not require clients to reconstruct these metrics from raw transactional tables.

13. Event model

Material domain changes should emit events.

Examples:

ProjectCreated
DesignPackageApproved
ExecutionPlanApproved
WorkBecameExecutable
WorkerAssigned
ExecutionStarted
ExecutionFailed
ValidationPassed
DeliveryReady
DeliveryStarted
DeliveryFailed
DeliverySucceeded
AcceptanceGranted
ProjectCompleted

Events support:

orchestration;
projections;
reporting;
notifications;
audit;
integrations.

14. Versioning

Versioned entities should preserve:

immutable prior approved versions;
current draft;
supersession relationship;
approval binding;
effective timestamps.

Work/execution must be traceable to the exact plan/design versions under which it was authorized.

15. Identity and correlation

Every major entity should have a stable Waypoint™ ID.

Execution and integration operations should also use:

correlation IDs;
run IDs;
idempotency keys;
external references.

These are essential for recovery, reporting, and audit.

16. Data retention

Retention should distinguish:

active operational state;
historical versions;
audit;
evidence;
logs/telemetry;
temporary worker context.

Sensitive or high-volume telemetry may have shorter retention than governance records.

17. Initial implementation boundary

The first implementation does not need every entity fully generalized, but it should avoid schema choices that prevent the model above.

At minimum, the canonical store should support:

Project;
ProjectDesignPackage;
Requirement;
Artifact;
ExecutionPlan;
WorkNode/WorkItem;
Dependency;
Stream;
Worker;
Capability;
Assignment/Reservation;
ExecutionRun;
Evidence;
Gate/Approval;
DeliveryUnit/DeliveryRun;
ExternalReference;
AuditEvent.