Engineering Events

An engineering event is one immutable record of something that happened: a deployment shipped, a system broke, a problem was solved, a decision was reversed. Events are the only thing Pulse stores as truth. Timelines, knowledge, Build Cred and the engineering graph are all derived from them.

Every event carries the same core: who, what, when, where, and — where a machine can confirm it — a proof. Once written, an event is never edited and never deleted. If it turns out to be wrong, you record a new event that supersedes it, and both remain on the timeline. The log only grows.

There are four event kinds, and they are fixed. This is not a taxonomy you extend with custom types; it is a deliberately small vocabulary, chosen because these four cover the entire arc of real engineering work and because a small vocabulary is what makes timelines comparable across projects, teams and years.

Events exist so that engineering history survives the people who made it. A team that turns over completely in two years still has a complete, ordered, verifiable account of how its systems came to be — not a wiki someone maintained for a while, but a log written as a side effect of doing the work.

We chose an append-only event log over an editable document store for one reason: a record you can rewrite is not evidence. If the incident write-up can be softened after a bad quarter, or a deployment can be quietly deleted from a timeline, then nothing on the timeline can be trusted — including the parts nobody touched.

The trade-off is real and we accept it. You cannot fix a typo in an event title. You cannot delete an embarrassing BLOCK. What you can do is record a PIVOT explaining that the earlier approach was wrong, and the timeline shows both — which is a more honest account of engineering than a clean one would be. The append-only constraint is not a limitation we plan to relax; it is the property that makes everything else worth anything.

• Kind — one of PUSH, BLOCK, UNLOCK, PIVOT.
• Actor — the developer the event is attributed to.
• Project — the execution container it belongs to. Optionally an organization and a primary technology.
• occurred_at and recorded_at — when it happened, and when Pulse learned about it. These are separate on purpose: a deployment that is synced an hour late is still ordered by when it deployed.
• Visibility — public, organization, private, or masked.
• Verification — the proof, its method, and its trust level. Absent until the engine attests it.
• Links — typed edges to other events. An UNLOCK links to the BLOCK it resolved.

Events are not a flat list. An UNLOCK that resolves a BLOCK carries a link to it, and that single edge is what produces the incident arc on a timeline, the resolution time on a project, and — once resolved — the knowledge artifact. Links are how a sequence of records becomes a story.

1. The event is captured — automatically from a linked source, or authored by you in the CLI or the Engineering Workspace.
2. It is appended to the log with both timestamps. Nothing is overwritten.
3. The verification engine looks for a source that can confirm it, mints a proof, and assigns a trust level from L0 to L4.
4. Projections are rebuilt: the event appears on the project timeline, the developer's profile, the feed, and search.
5. If it is verified, it contributes weighted points to Build Cred — the weight scales with the trust level, not with the event count.

  1. CAPTURE          2. APPEND              3. VERIFY             4. PROJECT

  From a source          Written once            Checked against       Timeline
  (PUSH)                 Never edited            the strongest         Profile
       or                Never deleted           available source      Feed · Search
  From you                    │                        │               Build Cred
  (BLOCK/UNLOCK/PIVOT)        │                        │                    ▲
       │                      ▼                        ▼                    │
       └──────────▶  occurred_at  ·  recorded_at ─▶ proof + level ──────────┘
                     when it        when Pulse      L0 unverified
                     happened       learned of it   L4 independently attested

  A wrong event is not corrected in place. You append a new event that supersedes it,
  and both stay on the timeline — which is what makes the timeline worth reading.

The incident arc is the workflow worth learning, because it is where Pulse earns its keep. It runs BLOCK → work → UNLOCK → knowledge.

1. Production degrades. You record a BLOCK describing the symptom and the impact — while you are still in it, not afterwards.
2. The BLOCK opens a room. Others join, contribute findings, and every step stays attached to the record.
3. You find the cause and ship the fix. The fix itself lands as a PUSH, automatically.
4. You record an UNLOCK linked to the BLOCK, stating what actually resolved it and pointing at the evidence.
5. The resolved pair is distilled into a knowledge artifact — the problem, the solution, and the lessons.

atlas-gateway starts dropping requests during a deploy. Here is the complete arc as @aria recorded it.

# The system is failing and we are on it
pulse event block \
  --title "Connection-pool exhaustion under deploy stampede" \
  --project atlas-gateway \
  --technology postgres \
  --description "Rolling deploys open a new pool per replica before the old replicas drain. Postgres hits max_connections and the gateway 503s for ~90s per deploy."

# ... investigation, fix, and a deployment that captures itself as a PUSH ...

# The BLOCK is cleared, and this is what did it
pulse event unlock \
  --resolves evt_atlas_pool_block \
  --title "Resolved connection-pool exhaustion with a shared pooler and drain gate" \
  --description "Moved replicas behind PgBouncer in transaction mode and gated new-replica readiness on old-replica drain. Deploy-time connection count is now flat."

{
  "id": "evt_atlas_pool_unlock",
  "kind": "UNLOCK",
  "title": "Resolved connection-pool exhaustion with a shared pooler and drain gate",
  "actor": "@aria",
  "project": "atlas-gateway",
  "organization": "northwind",
  "occurred_at": "2026-07-04T02:10:00Z",
  "recorded_at": "2026-07-04T02:14:31Z",
  "visibility": "public",
  "links": [{ "type": "resolves", "event": "evt_atlas_pool_block" }],
  "verification": {
    "status": "verified",
    "level": "L3",
    "method": "ci_pipeline",
    "proofId": "proof_2a77b410"
  }
}

• Write the BLOCK during the incident. The detail you have at 03:00 is the detail that makes the record useful, and it is gone by morning.
• Always link the UNLOCK to its BLOCK with --resolves. An unlinked resolution produces no arc, no resolution time, and no knowledge artifact.
• Describe the system, not your feelings about it. 'Postgres hit max_connections during rolling deploys' is a record. 'Deploys are painful' is not.
• Record PIVOTs even when the reversal is embarrassing. A reversed decision with reasoning is one of the most valuable events on a timeline — it stops the next engineer from re-making it.
• Set visibility deliberately. Masked is the right choice for work that must be provable but cannot be disclosed.

• Trying to record a PUSH by hand. It is not possible. If deployments are missing, the repository link or the deploy step is the thing to fix.
• Batching a week of BLOCKs on Friday. The timestamps will be honest about it, and the content will be thin.
• Using BLOCK as a to-do item. A BLOCK is an obstruction to engineering that is actively happening, not a task you intend to start.
• Recording an UNLOCK when nothing was actually resolved, to close the loop. It stays on the record permanently, and the BLOCK it claims to resolve is right above it.
• Assuming an event can be deleted later. It cannot. Write it as if it is permanent, because it is.

• occurred_at is what orders a timeline; recorded_at is what proves when Pulse learned of it. A CLI sync from an offline machine backdates correctly without letting anyone rewrite history.
• An event with no verification is still a valid event. It is simply attested at a lower trust level and weighted accordingly.
• Visibility does not affect ordering, verification or Build Cred. A masked event occupies its true place on the timeline.
• KNOWLEDGE, PROJECT and ORGANIZATION are also authored in the Engineering Workspace, but they create containers and artifacts rather than points on the four-verb timeline.