wrkmark-observer

Open-source behavioral observation engine for Wrkmark

---

What this is

This is the complete, open-source observation engine that powers Wrkmark — a platform that helps professionals prove their authentic skills in the AI age.

Every line of code that touches user behavior lives in this repo. Nothing hidden. Nothing elsewhere. Fully auditable by anyone.

What it observes

See WHAT_WE_SEE.md for the complete, human-readable list.

Short version: typing rhythm patterns, session timing, pause events, undo frequency, and whether AI tools were open during a session.

Never: content of any file, actual keystrokes, URLs, passwords, personal app activity, microphone, camera, or screenshots.

How privacy is enforced

1. Allowlist validation — only 8 approved signal types can pass through
2. Content stripping — all string values are stripped; only numbers survive
3. On-device processing — raw signals never leave your machine
4. Tamper-evident audit log — every observation creates a hash-chained record
5. Open source — you are reading the enforcement code right now

Quick Start

import { createObserver } from '@wrkmark/observer'

// Wire everything up in one call
const { sessionManager, collector } = createObserver('./wrkmark.db')

// Start observing a VS Code session
sessionManager.startSession('VS Code')
collector.start(sessionManager)

// Your IPC bridge calls these as VS Code fires events:
// collector.onKeystroke(Date.now())
// collector.onUndo(Date.now())
// collector.onFileSwitch(Date.now())

// When the session ends
const completed = sessionManager.endSession()
console.log(`Session: ${completed.duration_ms / 60000} minutes`)

Individual Imports

import {
  createDatabase,
  AuditLog,
  SignalAnonymizer,
  SignalExtractor,
  SessionManager,
  VSCodeCollector,
  WrkmarkObserverError
} from '@wrkmark/observer'

Run the tests yourself

git clone https://github.com/wrkmark/wrkmark-observer
cd wrkmark-observer
pnpm install
pnpm test

Every privacy constraint has a corresponding test. If the tests pass, the constraints are enforced.

Architecture

RawSignal ↓ SignalAnonymizer.validate() ← rejects anything not on approved list ↓ SignalAnonymizer.anonymize() ← strips all string content, keeps numbers only ↓ AuditLog.record() ← tamper-evident hash chain entry ↓ SQLite (local, encrypted) ← never transmitted raw ↓ FeatureVector (aggregated) ← only this reaches Wrkmark servers

Contributing

Read AGENTS.md before contributing anything. All PRs require passing tests + privacy CI check. Privacy-critical files require founder review (see CODEOWNERS).

License

MIT — use this code however you like.