Coming soon · Contract draft

Time Reconciliation & Adjustments

Planned

A financial-truth boundary for time actuals, reconciliation findings, adjustment proposals, review, and approval.

Reviewable specification — not callable

Documentation-first contract draft. The proposed additions on this page are not callable or available yet. Paths, payloads, scopes, names, and examples are intentionally concrete so customers can review the intended contract before and during implementation.

Canonical owner

Time actuals, reconciliation, and financial adjustment services

Contract posture

P2 · Documentation first · implementation follows approval

Contract metadata

Draft version

0.2 review draft

Review owner

Work/Finance + Developer Platform

Last reviewed

July 14, 2026

Target wave

Wave 5 · Financial operations

Contract dependencies

• Financial/privacy scope matrix
• Generic Operation resource
• Transactional audit and event contracts

What this unlocks

Explain time variance

Read a stable domain model for time reconciliation & adjustments without depending on GUI routes or database shapes.

Resolve provider findings

Create a reviewable proposal and apply only the bounded commands the canonical owner permits.

Govern financial adjustments

React to durable lifecycle facts and connect external systems with explicit direction and provenance.

Lifecycle and invariants

Time Reconciliation & Adjustments exposes a bounded lifecycle with explicit commands and named authority at every transition.

openinvestigatingproposedapprovedresolvedrejected

From	To	Command	Authority
open	investigating	Start review	Reconciliation and financial adjustment services
investigating	proposed	Draft adjustment	Reconciliation and financial adjustment services
proposed	approved	Approve adjustment	Reconciliation and financial adjustment services
approved	resolved	Apply adjustment	Reconciliation and financial adjustment services

Lifecycle invariants

• Provider records are idempotent and provenance-bearing.
• Agents cannot approve or apply financial adjustments.

Authority boundaries

The interfaces expose canonical capabilities; they do not become a second owner of domain rules or state.

DigitalStack owns

• Reconciliation finding lifecycle
• Provider-to-actual provenance
• Adjustment proposal and approval history

Explicitly not building

• Silent financial adjustment by an agent
• Raw provider records becoming actuals twice
• Time scopes leaking rate or margin

Surface decisions

Deliberate additions, retained boundaries, and removals from the proposed external contract.

add

Finding reads, reconciliation evidence, adjustment drafts, decisions, and apply history

The interface must make financial correction authority visible.

keep

Separate proposal, approval, and application

Explaining a variance is not authority to change financial truth.

remove

Generic finding creation/update and silent adjustment application

Findings are service-generated and adjustments require named approval.

Interface plan

REST API

Planned

Versioned time reconciliation & adjustments resources, commands, idempotency, and operation status.

Reads + explicit commands

GraphQL

Planned

Composable TimeFinding reads with mutations delegated to the same canonical domain service.

Composable reads + bounded delegated mutations

MCP / Agent API

Planned

Bounded read, draft, and human-request tools with evidence and audit attribution.

Read + proposal/confirmed commands only

Webhooks

Planned

Past-tense time finding lifecycle facts with minimal payloads.

Past-tense durable facts only

Connected Apps

Planned

Timely / ERP / accounting plus consumer clients, with declared direction and authority.

Declared direction and field authority required

Cross-interface parity

Each surface delegates to the named canonical owner; a blank surface is an intentional denial of authority, not missing documentation.

Capability	REST	GraphQL	MCP	Webhook	Canonical owner
Primary read	GET /time-reconciliation/findings	timeFinding(id: ID!): TimeFinding	get_time_reconciliation	—	Time actuals, reconciliation, and financial adjustment services
Primary command	POST /time-reconciliation/findings/{id}/resolve	draftTimeFindingChange(input: DraftTimeFindingChangeInput!): TimeFindingChangeProposal!	draft_time_reconciliation_change	time_finding.created	Time actuals, reconciliation, and financial adjustment services

Proposed scopes

Proposed scopes are not grantable yet.

time-reconciliation:readplanned scope

Read governed time reconciliation & adjustments resources.

time-reconciliation:writeplanned scope

Create and edit bounded time reconciliation & adjustments fields.

time-reconciliation:operateplanned scope

Run explicit time reconciliation & adjustments lifecycle commands.

Behavioral contract

Cross-cutting rules every implementation and interface must satisfy.

Canonical delegation

Every interface delegates to Time actuals, reconciliation, and financial adjustment services; no resolver, gateway, worker, or connector reimplements domain rules.

Least-privilege principals

Scopes are evaluated with tenant, role, field-visibility, and principal-type constraints before data is read or changed.

Safe writes

Mutations use explicit confirmation where required, optimistic concurrency, idempotency, and durable actor attribution.

Transactional facts

Webhook facts are emitted from the canonical commit path, versioned, minimal, and safe to redeliver.

Declared provider authority

Every Connected App declares direction, field authority, provenance, and conflict behavior before activation.

REST API

Proposed endpoints

Planned

GET/api/v1/time-reconciliation/findings

List time reconciliation & adjustments

Return an authorized, paginated collection with stable filters and provenance.

time-reconciliation:read

GET/api/v1/time-reconciliation/findings/{id}

Retrieve TimeFinding

Return canonical detail, lifecycle state, permissions, and allowed actions.

time-reconciliation:read

POST/api/v1/time-reconciliation/findings/{id}/resolveconfirmation

resolve TimeFinding

Run one explicit domain command after validation and authorization.

time-reconciliation:operate

POST/api/v1/time-reconciliation/adjustments/draft

Draft an adjustment

Create a proposal without changing approved actuals.

time-reconciliation:write

Execution: Synchronous

GET/api/v1/time-reconciliation/adjustments/{id}

Get adjustment proposal

Return proposal evidence, decision state, and apply result.

time-reconciliation:read

Execution: Synchronous

resolve a TimeFinding

Planned request

curl --request POST \
+  --url https://www.digitalstack360.com/api/v1/time-reconciliation/findings/time_finding_123/resolve \
+  --header "Authorization: Bearer $DSTACK_API_KEY" \
+  --header "Content-Type: application/json" \
+  --header "Idempotency-Key: time-reconciliation-resolve-v2" \
+  --data '{
    "expected_version": 2,
    "reason": "Confirmed through the reviewed integration workflow"
  }'

Planned response

{
  "data": {
    "id": "time_finding_123",
    "status": "resolved",
    "version": 3,
    "operation_id": "op_01k4..."
  }
}

GraphQL

Proposed graph

Planned

Types

TimeFinding

TimeFindingConnection

TimeFindingChangeProposal

Operation

Queries

timeFinding(id: ID!): TimeFinding

timeFindingList(filter: TimeFindingFilter, pagination: PaginationInput): TimeFindingConnection!

Mutations

draftTimeFindingChange(input: DraftTimeFindingChangeInput!): TimeFindingChangeProposal!

Planned GraphQL query

query TimeFindingDetail($id: ID!) {
  timeFinding(id: $id) {
    id
    status
    version
    updatedAt
    allowedActions { id label requiresConfirmation }
    source { kind externalId }
  }
}

MCP / Agent API

Proposed tools

Planned

Get Time Reconciliation & Adjustments

get_time_reconciliation

Planned

Read the authorized time reconciliation & adjustments state, provenance, and allowed actions.

Scope: time-reconciliation:read
Input: Resource id or a bounded filter.
Output: Canonical detail with source provenance and allowed actions.
Write boundary: Read only.

Draft Time Reconciliation & Adjustments change

draft_time_reconciliation_change

Planned

Build a reviewable proposal from explicit user intent and DigitalStack evidence.

Scope: time-reconciliation:write
Input: Target, requested outcome, expected version, and optional evidence references.
Output: A persisted proposal, validation results, and conflicts.
Write boundary: Creates a proposal; it does not mutate canonical state.

Request Time Reconciliation & Adjustments action

request_time_reconciliation_action

Planned

Prepare an authorized human action request without executing the high-risk command.

Scope: time-reconciliation:operate
Input: Proposal id, expected version, named decision maker, and reason.
Output: A pending human-action request and audit reference.
Write boundary: The agent cannot execute the final command.

Planned agent workflow

User: Review the proposed time reconciliation & adjustments change and help me apply it.

1. Call get_time_reconciliation to inspect current state, provenance, and allowed actions.
2. Call draft_time_reconciliation_change to create a proposal without changing canonical state.
3. Show validation results, conflicts, and the exact command to the user.
4. Call request_time_reconciliation_action so an authorized human can decide.

Never infer authority from access to the MCP client.

Webhooks

Proposed event catalog

Planned

Event types

time_finding.createdplanned event

A canonical TimeFinding was created.

payload: time_finding_id, status, created_at

time_finding.updatedplanned event

Governed TimeFinding fields changed.

payload: time_finding_id, changed_fields, version, occurred_at

time_finding.resolvedplanned event

The resolve command completed.

payload: time_finding_id, prior_status, status, occurred_at

Planned event example

{
  "event_id": "evt_01k4...",
  "type": "time_finding.resolved",
  "event_version": 1,
  "occurred_at": "2026-07-16T14:22:04Z",
  "workspace_id": "ws_abc123",
  "resource": {
    "type": "time_finding",
    "id": "time_finding_123"
  },
  "actor": {
    "id": "user_123"
  },
  "payload": {
    "time_finding_id": "time_finding_123",
    "prior_status": "draft",
    "status": "resolved"
  },
  "source": null
}

Connected Apps

Proposed connection roles

Planned

Claude / ChatGPT / IDE clients

Consumer application

Read, explain, and submit bounded time reconciliation & adjustments proposals through MCP.

Authority: Client access never implies domain approval or unrestricted mutation authority.

Timely / ERP / accounting

Synchronization provider

Supply actuals and reconciliation evidence.

Authority: Imports are idempotent; approved DigitalStack financial truth remains singular.

Open contract decisions

Resolve before implementation approval

• Do low-value non-billable corrections need the same approval threshold as financial adjustments?

Proof obligations

Must remain true	Failure indicator
Time actuals, reconciliation, and financial adjustment services remains the singular canonical owner.	An interface or connector persists a second authoritative lifecycle state.
Draft and apply remain separate actions.	An agent or integration silently converts inferred intent into a canonical mutation.
Every write is attributable, versioned, and idempotent.	A retry duplicates work or stale state overwrites a newer human decision.
Connected App direction and field authority are explicit.	Provider data silently becomes canonical or conflicts are resolved without policy.