#Audit and Health

init() and health() expose the readiness evidence that operators need before accepting permission traffic or diagnosing degraded state.

#Purpose and preconditions

This section narrows the public contract for this method family. Read it before wiring the call into an admin page, route guard, or diagnostic tool.

#What Do You Want To Do

#Signatures

The signatures below are the public contract. The code block is kept executable-looking so TypeScript users can compare argument order, option requirements, and raw return wrappers quickly.

pc.init(): Promise<PermissionCoreHealth>
pc.health(): Promise<PermissionCoreHealth>

interface MutationResult<T> {
  committed: true;
  changed: boolean;
  data: T;
  revision: number;
  revisions: RevisionVector;
  operationId: string;
  auditId: string;
  replayed: boolean;
  cache: { status: 'not-needed' | 'completed' | 'bypassed' | 'degraded'; reason?: string };
  warnings: BoundedDetails<ManagementWarning>;
  detailBudget: ResponseDetailBudget;
}

#Method and Field Details

The methods below are the public health and audit surface. They are intentionally small so operators can use them from readiness probes and incident tooling.

#pc.init()

• Purpose: Initialize persistence contracts, indexes, health state, and runtime readiness before serving permission checks.
• Parameters: Pass the documented identifier, filter, action, resource, query, or options object. Optional detail budgets are bounded and should be handled as possibly truncated diagnostics.
• State impact: Read methods are side-effect free. Mutation or execute methods validate scope, revision, preview token, ownership, and capacity before committing state and audit evidence.
• Raw return: the public type shown in the signature section. Read the documented envelope directly; tutorial summary JSON is only a selected display shape.

#pc.health()

• Purpose: Read current readiness plus database, schema, cache, token, and audit health for operators or health checks.
• Parameters: Pass the documented identifier, filter, action, resource, query, or options object. Optional detail budgets are bounded and should be handled as possibly truncated diagnostics.
• State impact: Read methods are side-effect free. Mutation or execute methods validate scope, revision, preview token, ownership, and capacity before committing state and audit evidence.
• Raw return: VersionedResult<T> or SubjectRuntimeResult<T> depending on the context. Read the documented envelope directly; tutorial summary JSON is only a selected display shape.

#Responses and side effects

Side effects are scoped and revisioned. Writes record audit evidence and invalidate affected semantic cache keys; reads preserve bounded detail metadata so callers can tell whether diagnostics were complete.

{
  "status": "degraded",
  "lifecycle": "ready",
  "database": { "status": "up" },
  "cache": {
    "permissionLayer": "enabled",
    "invalidationIncidentActive": true,
    "invalidationFailures": 1,
    "invalidationRiskUntil": 1780000000000
  },
  "audit": {
    "pendingCacheOutcomes": { "value": 1, "cap": 1000, "truncated": false }
  }
}

#Failures and limits

Failures close authorization instead of widening it. Important limits are enforced before state is committed, and stale previews or revisions must be refreshed rather than guessed.

#Example

The example keeps one narrow path per page. It shows the raw method family and a compact response shape, while the full runnable scenarios live in the examples section.

const result = await scoped.roles.create(
  { id: 'operator', label: 'Operator' },
  { actorId: 'admin-7', reason: 'Initial setup', requestId: 'req-42' },
);
businessAudit.info({ operationId: result.operationId, auditId: result.auditId });

{
  "committed": true,
  "operationId": "operation_...",
  "auditId": "audit_...",
  "replayed": false,
  "cache": { "status": "completed" }
}

#Related

Continue with the linked guide or neighboring API page when you need workflow context rather than only signatures.

Continue with Errors.