Integration

Four API calls.
That is the entire integration.

No schema migrations. No changes to your existing database. Hook ProjectLedger into any decision process and your first sealed record is written in minutes.

01create_evaluation()Open a window

02promote()Record a decision

03close_evaluation()Seal the window

04generate_artifact()Produce the sealed record. Verifiable offline.

Evaluation Lifecycle

Open. Record. Close. Artifact.

Every evaluation follows the same four-step lifecycle. The window opens, decisions are recorded as they happen, the window closes, and the sealed artifact is generated. Once closed, no further entries can be written.

create_evaluation(name)

Open the evaluation window

Creates a named evaluation context and returns an evaluationId. Everything recorded during this window is grouped under this ID. Name it to match your process: a loan batch, a moderation queue, a fraud review cycle.

# Step 1: Open evaluation
result = svc.create_evaluation(
  "Loan Approval - APP123"
)

eval_id = result["data"]["evaluationId"]
# eval_id = "eval_9f2c3a8b"

promote(evaluationId, payload)

Record a decision

Call promote() at the moment a decision is made. Pass the authority mode, the actor, and a summary. The record is written, hashed, and timestamped immediately. Supports an idempotency key to prevent duplicate entries on retry.

# Step 2: Record a decision
svc.promote(eval_id, {
  "type":          "decision",
  "authorityMode": "human_in_the_loop",
  "actor": {
    "type": "human",
    "id":   "UW-5521"
  },
  "summary":       "Approved after review.",
  "decisionState": "accepted",
  "idempotencyKey":"txn-APP123-001"
})

close_evaluation(evaluationId)

Seal the window

Hard-closes the evaluation. Any promote() call after close returns HTTP 409. This is enforced at two layers: Firestore rules and application logic. Once closed, the record is permanent.

# Step 3: Seal the window
svc.close_evaluation(eval_id)

# Any further promote() calls
# returns HTTP 409: rejected.

generate_artifact(evaluationId)

Produce the sealed artifact

Generates Artifact 5, a KMS asymmetric-signed bundle containing every entry recorded during the window, a manifest root hash, and the KMS signature with key version reference. The private signing key is non-exportable and remains inside Google Cloud KMS at all times. Independently verifiable offline with the public key alone. No connection to ProjectLedger infrastructure required. Artifact generation fails in production if signing fails. You will never receive an unsigned artifact silently.

# Step 4: Generate artifact
artifact = svc.generate_artifact(eval_id)

# Returns signed bundle:
# entries, manifestRootHash,
# signature.scheme,
# signature.keyId,
# signature.value

Authority Modes

Every decision has a mode. The mode is part of the record.

authorityMode is a required field on every promote() call. It records the governance structure of the decision, not just what was decided, but who or what had the authority to decide it. This is the field that answers the human oversight question.

human_led

Human Led

A human makes the decision directly. No AI proposal precedes it. The actor type is human. The record proves a person was in the decision seat.

actor.type: human

Examples: manual underwriting approval, policy rate change sign-off, compliance override.

human_in_the_loop

Human in the Loop

An agent proposes. A human reviews and commits. Both actions are captured. The sealed record proves human oversight actually happened, not just that your policy says it should.

actor.type: agent + human

Examples: AI fraud flag reviewed by analyst, AI recommendation approved by advisor, moderation queue with human review.

agent_autonomous

Agent Autonomous

The agent acts on its own. No human in the loop. promote() is called automatically at the moment of decision. Every autonomous decision is on the record, regardless of volume.

actor.type: agent or service

Examples: fraud detection engine, refund rules logic, matchmaking algorithm, automated pricing engine.

Error Codes

The system is fail-closed. Errors surface to the caller.

There is no silent failure mode. If a decision cannot be recorded, the calling system receives an error. Decisions do not proceed without a confirmed write. The 409 on post-close promote() calls is the append-only guarantee in action.

Artifact generation fails in production if KMS signing fails. You will never receive an unsigned artifact silently.

400

Invalid input. Check required fields and authorityMode values.

401

Authentication failure. Check your PROMOTE_API_KEY.

403

Cross-tenant access denied. EvaluationId does not belong to this tenant.

409

Promote after close. The evaluation window is sealed. No further entries accepted.

500

Internal error. Includes signing failures. Artifact generation will not silently return an unsigned record.

Data Handling

Store sensitive data in your system. Reference it here by ID.

ProjectLedger records the governance structure of decisions, not the underlying personal data. Your customer records, transaction details, and personally identifiable information stay in your own infrastructure.

Pass opaque identifiers in the summary or tags fields. The artifact captures who decided, with what authority, at what time, linked to your records by ID without duplicating sensitive data into the ledger.

Correct pattern

summary: "Approved. Ref: APP-123, UW-5521"

The case ID and reviewer ID are opaque references. The underlying application data lives in your system. The ledger captures the governance event, not the personal data attached to it.

Avoid this pattern

summary: "Approved loan for Jane Smith, SSN 123-45-6789, $42,000 at 7.2%"

Do not pass raw PII into the summary field. The artifact is designed to be shareable with auditors and regulators. Keep sensitive data in your own infrastructure where you control access.

Ready to Integrate

Four calls. Minutes to your first sealed record.

A 30-minute discovery call to scope your evaluation. We will walk through the integration against your specific decision process. $15K to $60K, evaluation only.