SDK contracts

Choose the namespace for your task below. Consume means inject a host capability; implement means publish an App contribution; construct means use a value, helper, or adapter directly. A namespace can contain more than one kind.

Use a host capability

use Nexia\Tenancy\Contracts\TenantSettings;

final class ReportClock
{
    public function __construct(private TenantSettings $settings) {}

    public function timezone(): string
    {
        return $this->settings->businessTimezone();
    }
}1234567891011

Resolve ReportClock through Laravel in a restored tenant context. It returns that tenant's business timezone through the host binding. For Resource authorization, start with Resource contracts; for frontend imports, use React components and hooks.

PHP namespace map

Output or return: Interfaces versus implementations

Where the platform owns the behavior, the SDK publishes an interface and the platform binds the implementation. It does ship app-neutral implementations of its own — the Nexia\Laravel\Models adapter, its model concerns, and the frontend primitives and hooks — so "contracts only" is true of platform behavior, not of the whole package. The pattern for platform-owned behavior:

Resolve directly bound host contracts from the container. The optional batch contracts above have no separate binding: inject Nexia\Identity\Contracts\PersonProfileDirectory, Nexia\Identity\Contracts\PersonLoginInvitations or Nexia\Laravel\Identity\Contracts\PartyDirectory, then check that the returned implementation implements its corresponding batch interface. Current Core implementations support all three batch capabilities. Never type-hint a platform class or use its Eloquent model as an App API.

Nexia\Tenancy\Contracts\TenantIdentity, Nexia\Identity\Contracts\Actor and Nexia\Identity\Contracts\Party are identities supplied through context or call results, not services to assume independently injectable. Contributions and App providers are implemented by the App; test-host bindings are configured only in the test environment.

The batch profile and Party directories query only the tenant context already restored by the caller; their keys and emails are not cross-tenant selectors. Batch login-invitation status additionally requires the current Actor and a Legal Entity key, and reports NotAuthorized when that actor may not invite.

PersonPartyProvisioner::ensureForDirectorySubject($displayName, $email) returns the app-neutral Party contract. The host reuses the single unambiguous active person Party for the email, including one already linked to a user; otherwise it creates a person Party. The App receives no host model and must not reimplement email-based identity convergence itself.

RecentAuthentication::isFresh($actor, $withinMinutes) is an additional proof for a protected action. Keep the operation's permission, row, scope, and state checks in place. PdfFontProvider::forLocale() returns a host-owned local PdfFontAsset when an App needs to embed a font in a generated PDF; the App must not reconstruct Core filesystem paths.

PartyDirectory::searchActivePeople($search, $limit, $excludedKeys) returns PersonDirectoryEntry options with an opaque key, public id, display label, and optional contact email.

ResolvedResourceReference keeps public fields separate from protectedValues(). Protected values are accepted only from an exact resolve() or resolveMany() call whose context explicitly sets includeProtectedValues; searches reject them, and snapshots, debug output, and PHP serialization omit them. People uses this boundary to return bank account values for the exact payroll.bank-export purpose without making a People-specific payment contract part of the SDK. The same owner can add a safe effective planned-schedule projection for the workforce.effective-planned-schedule purpose, bounded by asOf and effectiveThrough. Actorless consumers use a public Event and local projection instead of fabricating an actor.

Tenant permission snapshots

TenantPermissionSnapshotAuthorizer evaluates several tenant-scoped permission keys with one app-neutral contract:

Here $user is the authenticated host user already supplied to the request. These two tenant-scoped Core permissions demonstrate the shape; pass the tenant-scoped permissions needed by your UI.

use Nexia\Laravel\Access\Contracts\TenantPermissionSnapshotAuthorizer;

$snapshot = app(TenantPermissionSnapshotAuthorizer::class)->forPermissions($user, [
    'system.apps.read',
    'system.data.export',
]);123456

The result contains every requested string key verbatim. Unknown or retired permissions, permissions from a non-operational App, non-tenant permissions, and subjects that cannot be resolved all evaluate to false; non-string input is ignored. The contract uses the ambient tenant and deliberately accepts no Legal Entity or Operating Unit argument. Use the snapshot to render read-only affordances such as menus or buttons. A write still performs point-in-time authorization in its request path.

AttachmentDirectory::listForTargets() accepts AttachmentTarget values and returns attachment summaries visible to the actor; it does not read bytes. AuthorizedFileReader::read() takes a filePublicId. In the restored tenant and request Legal Entity context, it checks actor authorization, isolation and clean status; absence, refusal, boundary mismatch and an unclean file return null.

AttachmentStore::createGeneratedFile() stores a generated file and attach() links it to a Resource target. exists() checks an attachment public id against the target; fileAttached() checks whether a file public id is already linked. These checks are not uniqueness constraints or domain mutation authorization. The App must authorize its business write and handle duplicates before storing/attaching. downloadHrefIfAuthorized() returns a URL only when the actor may read it.

For import-only uploads, AuthorizedImportFileReader::read(uploadIntentPublicId, resourceKey, legalEntityKey, actor) claims and reads the upload. Use AuthorizedImportFileStore::claim(), find() and withLocalCopy() for metadata reauthorization or temporary-copy processing of larger files. Neither contract is the general Resource attachment directory.

Party relationship and Resource Summary lookups likewise return no projection when the actor-visible provider cannot answer; callers do not receive a host model or a reason that widens disclosure.

There is no kernel Nexia\Models namespace or host-model facade. Use the focused Identity, Organization, Party, or Installed Apps contract; production Apps never query or receive a host Eloquent model. Nexia\Testing\Contracts\HostTestStore is test-only.

Mutation identity and publication

MutationMatcher is an app-neutral recheck condition. It names either Resource Catalog keys with lifecycle operations (Created, Updated, Deleted, Restored) or semantic action keys with only Succeeded. It cannot mix the two subject types. Keys and operations inside one matcher use OR semantics; optional resourceIds narrow a Resource matcher. Resource keys, action keys, and Resource IDs are each limited to 160 UTF-8 bytes across the SDK, host header, Gateway, and Shell boundaries.

The host automatically observes committed Eloquent lifecycle events for every model bound through ResourceCatalogContribution. Ordinary generated Resource controllers therefore add no save/delete instrumentation. Inject MutationPublisher only when the write bypasses model events, such as a bulk query update, or when a successful semantic action has no Resource Catalog root:

use Nexia\Mutation\Contracts\MutationPublisher;
use Nexia\Mutation\MutationOperation;

$mutations = app(MutationPublisher::class);
$mutations->resourceChanged(
    'workshop.note',
    MutationOperation::Updated,
    $publicId,
);

$mutations->actionSucceeded('workshop.note.archived');1234567891011

Call the publisher only after the business write succeeds. The host derives tenant, actor, initiator, request, surface, and correlation context from its trusted runtime; App code supplies none of them. Publication occurs after the current transaction commits, or immediately when no transaction is active.

This signal is a same-browser wake-up hint, not a durable domain event, audit record, cache invalidation, or completion result. A consumer always re-reads authoritative state. Use Nexia\Events when another App or runtime must react reliably.

Cross-App access

App-to-App imports and package dependencies are forbidden. There is no exception. Three supported alternatives:

A ResourceRef names another App's record without importing its model. Core resolves it, applies the actor's authority, and returns only what they may see. The canonical browser selector also requires the consuming Resource and field, then enforces its declared targets, purpose, permissions, and owner availability before dispatch.

For a manually built Dashboard that reads across two Resources, Core composes the existing Resource contracts instead of asking either App to import the other. The SDK publishes only the app-neutral CompositionSpec wire DTO and matching PHP/TypeScript validators. The spec names semantic Resource keys, source aliases, a server-issued relationship key, fields, bounded filters, dimensions, measures, and result shape. It has no table, model, SQL, arbitrary expression, planner, or executor surface. Core resolves the keys against the live actor-filtered catalog and repeats authorization when it plans and runs the query. This is a manual human Dashboard capability, not an App or Agent authoring interface.

When a surface is missing

Check the installed package and host version before adding an API. A source checkout is only needed when you are changing that package. Keep App-specific behavior local and use Resource contracts or published events for cross-App integration. Request a platform capability when the existing public APIs cannot express the task; consume it once both SDK and host support it.

Do not import Core classes, another App, or edit vendor/. To add an available SDK checkout to an existing local setup, use task apps:add PACKAGES=app-sdk.

Capabilities without an App-side contract today

Neither class is an SDK API. Consider Site Configuration as a separate SDK candidate only after an actual App needs to contribute declarative items to the shared settings screen. For an App-owned settings screen, follow Add a settings page. First evaluate installation needs against tenant migrations and Required installation content, optional Copyable templates, and Contribute Setup tasks for operator readiness.

Existing package imports of host-only surfaces, when any remain, appear as explicit exceptions in .nexia/coupling-baseline.json. A clean App has no file; the ratchet permits only recorded file-and-symbol pairs and rejects new ones.

Errors

Use in your App

Use the installed SDK namespace and the host binding together. For a first Resource, follow Create a Resource; the generated files show the model, authorization, and contribution APIs in context.

Related

• HTTP middleware — App route stacks, every registered alias, parameters, ordering, and refusal codes
• React components and hooks — the frontend symbols an App reaches for most; use dist/index.d.ts for pure contracts and dist/host.d.ts for host-bound APIs
• App SDK — why the boundary is shaped this way
• Contribution contracts — every contribution interface and its method
• Fix boundary violations — fixing a rejected import

Use FileDeliveryAttempts::callback(attemptId, producer) around the actual byte producer after prepare(). It records server start and terminal outcomes; a constructed response does not establish delivery. FileLifecycleRecorder accepts bounded identity/context metadata only and does not grant authorization. Inventory observations and retention-pending facts do not claim historical downloads or deleted bytes.

AuthorizedImportFileStore::receiveLocal() routes existing multipart input through verified host intake. discardUnbound() is for a newly claimed input that your App has not bound to a business record (for example, a rejected duplicate upload); do not pass accepted evidence. Custom implementations must provide both methods and delivery callbacks when adopting this SDK change.