Skip to content

Data model ​

DutyGraph records a company as typed, versioned records in PostgreSQL. This page explains the main entities in plain English. It describes concepts, not every column.

The core picture ​

mermaid
flowchart TB
    T["Tenant<br/>advisor workspace"] --> CO["Company"]
    T --> ACC["Account"] --> ENG["Engagement"] --> CO
    CO --> P["Person"]
    P -.->|role and team| R["Role / Department<br/>derived"]
    P -->|owns| D["Duty"]
    D -->|groups| TC["Task Card"]
    P -->|"owns / performs"| TC
    TC -->|handoff| TC2["Task Card"]
    WF["Workflow"] -->|orders| TC
    REQ["Ask"] --> RES["Answer"] --> EV["Evidence"]
    EV --> TC
    CL["Research claim"] --> CO
    TC --> PC["Possible constraint"] --> MEA["Measure"] --> OUT["Outcome"]
    TC --> M["Agent manifest"] --> AR["Agent request"]
    AR --> LE["Ledger entry"]
    AR --> IA["Issued agent"] --> AA["Agent activity"]
    GP["Governance packs<br/>rules, catalog, holdings, chain"] --> AR

Company and engagement ​

EntityWhat it is
TenantAn advisor's workspace or firm. Every business row carries its tenant.
AccountA company in the advisor's pipeline, with its contacts and timeline
CompanyThe organization being mapped. A sample company is marked as a sample.
EngagementThe advisor's piece of work with the company. Its status runs from proposed to active, paused, complete or cancelled. An active engagement needs a recorded activation, such as a payment. A separate engagement record holds the scope, dates, systems and success criteria.

People and work ​

EntityWhat it is
PersonName, email, role, team and manager. Reporting lines come only from recorded managers.
Role and DepartmentDerived from people's roles and teams. They are marked Inferred and get readable ids such as DEPT-FINANCE.
DutyA lasting responsibility with one owner. It groups Task Cards.
Task CardOne bounded piece of work: purpose, trigger, inputs, steps marked [H], [A] or [S], outputs, systems, an owner, a performer and a proposed AI mode. See Task Cards.
HandoffA recorded link from one Task Card's output to another's input. It must connect two different Task Cards. A handoff marked as executable, not documentation only, needs an exception owner.
Workflow (flow)An ordered set of Task Cards and handoffs. DutyGraph refuses cycles, duplicate paths and disconnected steps.

Duty ownership, reporting lines and Task Card confirmation are separate facts. One never implies another.

Asks, answers and evidence ​

EntityWhat it is
Ask (request)Questions sent to one person, by email or private link
Answer (response)What the person sent back, kept with the understanding they confirmed
ConfirmationA person's decision on an exact version of a record: correct, needs change, not mine or unsure
EvidenceAn original source: an accepted answer, meeting notes, a reviewed transcript or a research page. It is labelled Known, Inferred, Assumed or Missing. Retracting it keeps its history and marks dependent records stale.
Research claimOne researched fact, such as headcount. It holds a value, a state (known, inferred, disputed or unknown), a confidence and a verification state, such as client confirmed or corrected. Each change is a new claim version.
Field readingA value DutyGraph read from an answer, pointing to the speaker's own words. It waits in Repo › To review until the advisor accepts it.

How these become file states is on Evidence and provenance.

Repo files ​

A Repo file is not stored. The compiler builds it from the records above. See System architecture. Two things are stored for files:

  • Notes: append-only text versions for a file, saved only when the advisor accepts a DutyGraph Agent edit that fits no record field.
  • Stable ids. Every file has an id that never changes. A record-backed file uses a prefix and eight hex characters, in the form TSK-1a2b3c4d. Prefixes include COMPANY, DEPT, ROLE, PER, DUTY, TSK, FLOW, HND, AGT, MET, SYS and FND.

A link between files is an id in double square brackets, such as [[ROOT-AGENTS]]. An id that does not resolve is shown as plain text. Links up, down and across the company are computed from records, never typed. A link is confirmed only when accepted records state it, and proposed otherwise.

Improvement records ​

EntityWhat it is
Possible constraintA hypothesis about what limits a flow, with quotes from Repo files. It is never shown as proven.
MeasureA metric with an owner, a formula, a unit, a baseline and a target. A missing baseline needs a reason. Readings are added over time.
Change (intervention)A change to test against a possible constraint, with an owner, a measure, a prediction, stop conditions and a review date. Route's Accept writes one.
OutcomeThe result of a change: supported, falsified or inconclusive, with its evidence. It keeps the original prediction. A falsified result reopens the hypothesis.
Task proposalAn AI mode, owner, performer or hours value that code proposed for a Task Card, waiting for Accept

Agents and governance ​

EntityWhat it is
Agent manifestA versioned, hashed description of one agent for one named person. See Agent builder and manifests.
Agent plan linkA frozen copy of a manifest version and hash, shared with the person by a private link
Agent requestA request to issue an agent, for named Task Cards, with each scope's state (Inherited, Auto-trimmed or Escalated) and the approval chain's decisions. It records Task Card ids, not Task Card versions.
Governance packsSix kinds, each versioned with a content hash: agent rules, separation of duties (SoD) rules, mitigating controls, the System Catalog, holdings and the approval chain. A new load is a new version that supersedes the old one.
Task Card registry entryA governance id (TSK-0001) for an eligible Task Card, with the scopes it is treated as needing: its listed scope lines, else every catalog scope of its systems
HoldingsThe access each person holds, as system/action:object scopes, from an uploaded access export. Matched by email or external id, never by name. Never compiled into the Repo.
Ledger entryOne governance event: a pack sealed, a request decided, an agent issued, suspended or revoked. Each entry holds the hash of the previous one. See Ledger.
Issued agent and credentialThe agent as issued, with its issued scopes, bound to its manifest hash, its issue record and its expiry. The credential is stored only as a hash.
Agent activityOne row per gateway call: agent, tool, scope, allowed or blocked, and the rule for a block

Work, capability and authority ​

Some of the distinctions below are built. The rest are proposed refinements, marked Planned. They would extend the existing Task Card records, governance packs and evaluator, not add a separate authorization database.

ConceptWhat it isStatus
Task definitionWhat the work is: purpose, trigger, steps, systems, rulesBuilt, as the Task Card. Definition and assignment share one record today.
Task assignmentWho owns and who performs the workBuilt as owner and performer fields on the Task Card. A separate assignment record, so one definition can have many assignments, is Planned.
Business capabilityAn action the work requires, named in business terms, for example "place a hold on a supplier invoice", referenced from a Task Card stepPlanned
EntitlementA permission in a system. Today a catalog scope, or an entitlement name in an access export that the catalog maps to scopes.Built as scopes and catalog mappings. Capability-to-entitlement mappings validated by an application owner are Planned.
Agent GrantThe authority issued to one agent under conditions: scopes, controls, end dateBuilt as the issued agent's scopes and credential. A grant traced to validated capabilities is Planned.
VersionsEach mapping and grant records its source, evidence, version, validator, confirmation state and effective periodPartial: records, packs and manifests are versioned and hashed. Requests pinning Task Card versions, and versioned mappings, are Planned.

The Agent Authority Record is a Planned view over these records. It is not new storage.

Versions and content hashes ​

  • Every change to a record is a new version. The application cannot change or delete an earlier version.
  • Each version has a content hash over its canonical JSON plus the tenant, company, record id, kind, title and version.
  • A confirmation binds one version and hash. If the work changes, the person confirms again.
  • A state change is an audit event, not a new version. A hash identifies content, not each later review step.
  • Governance packs, the ledger and agent activity are append-only.

INFO

Status. Built: every entity on this page not marked Planned, versioned records with content hashes, confirmations bound to a version, stable Repo ids and [[ID]] links, append-only Notes, governance packs, the hash-linked ledger and agent activity. Simulated: holdings and identity data in the governance sample come from illustrative files. Planned: role and department records of their own (today they are derived), separate task assignments, business capabilities, validated entitlement mappings, Task Card version pins on requests, and live holdings from identity systems.

Source: gitbook/product/architecture/data-model.md in the DutyGraph repository.

DutyGraph. Pages label each feature Built, In review or Planned.