#Errors

PermissionCoreError is the structured failure surface. Callers should branch on code and details.kind, not on localized message text.

#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.

class PermissionCoreError extends Error {
  readonly code: PermissionCoreErrorCode;
  readonly details?: PermissionCoreErrorDetails;
  readonly retryable: boolean;
  readonly committed?: boolean;
  readonly operationId?: string;
}

#Error Object Details

Every error carries a stable public code and a discriminated details object. Logs and HTTP mappers should keep these structured fields.

Details discriminators include validation, limit-exceeded, data-value-unsupported, close-timeout, revision-conflict, read-conflict, preview-stale, cursor-stale, preview-required, menu-management-preview-conflict, capacity-risk-ack-required, persisted-state-invalid, unexpected-post-image-field, schema-version-mismatch, schema-contract-mismatch, database-failure, audit-lookup, and reconcile-superseded.

#PermissionCoreError

• Purpose: Handle permission-core failures with stable error codes, HTTP mapping, and machine-readable details.
• 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.

#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.

{
  "code": "PERMISSION_DENIED",
  "message": "The subject is not allowed to invoke this route.",
  "retryable": false,
  "requestId": "req-42"
}

#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.

MENU_MANAGEMENT_PREVIEW_CONFLICT means an incremental menu auto-commit needs explicit administrator preview confirmation. Treat it like other preview/revision conflicts: refresh, show the impact, then execute with the returned expected/previewToken.

#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.

import { PermissionCoreError } from 'permission-core';

try {
  await subject.assert('delete', 'db:orders');
} catch (error) {
  if (error instanceof PermissionCoreError && error.code === 'PERMISSION_DENIED') {
    return { status: 403, code: error.code };
  }
  throw error;
}

{ "status": 403, "code": "PERMISSION_DENIED" }

#Related

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

Continue with Resource Schemes.