Search by

maxx / laravel-ai-sdk

Sandeep Maxxmann

Laravel integration for Maxx Universal AI governance APIs

dev-main 2026-10-27 12:00 UTC

This package is not auto-updated.

Last update: 2026-11-17 08:19:43 UTC


README

Standalone Composer package: maxx/laravel-ai-sdk.

For step-by-step host installation, access, billing, troubleshooting and rollback, see the user manual. The Universal AI dashboard footer also provides a bundled browser-readable SDK guide that opens in a new tab.

This is a library, not a web application or standalone server. Do not expose this directory through Apache. A deny-all .htaccess is included for XAMPP; ensure the server honors it or exclude the directory from the document root.

Status: provisional local/test SDK, not an approved production release. Implements the reusable SDK portion of worksheet task UAI-WF-03-A against m1-dummy-v1 / m2-dummy-v1. Production and staging environments are intentionally rejected: only local and testing with explicit opt-in are supported. Frozen C01-C08 contracts and human acceptance are still required.

Requirements and scope

  • PHP 8.2+ with OpenSSL, JSON and mbstring; Laravel 12.
  • Host applications must confirm their actual lockfile/runtime before installation; Laravel 10/11 support is not claimed. Laravel 11 qualification attempted on 27 October 2026 failed Composer resolution because matching framework releases were blocked by security advisories. Advisory blocking was not disabled. The owner selected retaining Laravel 12 support; Laravel 11 hosts require an approved upgrade before integration, not relaxed package constraints.
  • Backend machine identity and registered account/application/deployment, matching approved local/test key configuration and enabled M1/M2 runtimes.
  • The SDK does not implement DIS, replicate users/tenant tables, provision credits automatically, adopt HRMS policies, calculate tax or create legal invoices.
  • HRMS/CRM business call sites remain in their own host repositories. An optional copy of the regional HRMS AI Governance module is bundled for explicit installation.

Install in an existing Laravel application

Command quick reference

Run commands from the Laravel host application, not this SDK checkout. Configure the Composer path/private repository first as described below.

Task Commands in order Result
Add SDK and module composer require maxx/laravel-ai-sdk:"dev-main" then php artisan maxx-ai:install Composer installs the SDK under vendor; Artisan copies the module, registers its provider, publishes missing configuration and records an installation manifest.
Complete host setup composer dump-autoload, php artisan config:clear, php artisan route:clear Refresh host autoloading and clear stale configuration/routes. Review the regional database before separately running the module migration tool below.
Remove module and SDK php artisan maxx-ai:uninstall then composer remove maxx/laravel-ai-sdk Artisan safely removes an unchanged generated module first; Composer then removes the SDK dependency if no other package requires it.

Do not remove the Composer package first: that also removes the Artisan uninstall command. An existing regional module is not an installer-owned module unless it has its original installation manifest. Neither install nor uninstall overwrites or deletes such a module. These commands are implemented in this source tree; use a package revision containing them. They do not imply that this development version has been published or deployed.

This repository is separate from the Python backend. Until a private VCS release is published, add a Composer path repository to the host application's composer.json:

{
  "repositories": [
    {
      "type": "path",
      "url": "../maxx-laravel-ai-sdk",
      "options": {"symlink": false}
    }
  ]
}

Then run from that Laravel application's directory:

composer require maxx/laravel-ai-sdk:"dev-main"
php artisan vendor:publish --tag=maxx-ai-config

Laravel auto-discovers the service provider. No routes, migrations, accounts, funding, workers or HTTP calls run automatically. Pin an approved immutable release in consuming applications when a release exists; dev-main is only a local development installation.

Copy the names from the environment example into your host environment. Set APP_ENV=local or testing; never change a production application to local to bypass the gate. The package is disabled by default.

Install the regional HRMS AiGovernance module

For a compatible regional HRMS host, the optional installation flow is:

composer require maxx/laravel-ai-sdk
    -> vendor/maxx/laravel-ai-sdk/
php artisan maxx-ai:install
    -> Modules/AiGovernance/

The Composer command requires an accessible package repository and a version matching the host's stability settings. There is no tagged/public release claimed here. For the local path repository above, continue using composer require maxx/laravel-ai-sdk:"dev-main".

The installer copies the complete module from stubs/AiGovernance, based on maxx-hrms-india/Modules/AiGovernance on 27 October 2026, with an additional HRMS-style JSON API. It includes the web/API controllers, Blade dashboard, routes, models, services, five migrations, and regional migration tool. It registers the provider in bootstrap/providers.php without changing existing provider order and publishes config/maxx-ai.php only if absent. Existing module directories are refused, including repeat installations; there is deliberately no destructive --force option. Installed files are host-owned: subsequent SDK updates do not overwrite them.

This is an HRMS-specific module, not a standalone UI for arbitrary Laravel applications. The host must already provide App\Support\ScopeContext, the regional App\Models\User contract, regional.scope middleware, Spatie permissions, the admin.layouts.base layout, and app.jurisdiction (in, ae, or us). Its existing Modules\\ PSR-4 mapping must point to Modules/; if missing, add it to the host's Composer autoload configuration and run composer dump-autoload before installing. The original regional application registers providers explicitly; the installer follows that same pattern rather than depending on nwidart module discovery or enabling other modules.

After installation:

composer dump-autoload
php artisan config:clear
php artisan route:clear
# Review the target regional database before running:
php Modules\AiGovernance\Tools\install.php

The regional tool validates in -> hrms_in, ae -> hrms_ae, or us -> hrms_us, then applies only this module's migrations. The Artisan installer does not migrate, change .env, create credentials, grant permissions, add sidebar links, wire business-module call sites, configure billing, or contact the AI backend. The module supplies no legal invoice handler; the existing billing integration below remains host-owned. Configure permissions and SDK Connection before using /ai-governance. SDK execution still requires local/testing opt-in; installing the module does not permit production execution.

Safe uninstall before Composer removal

Composer owns vendor/maxx/laravel-ai-sdk, not the generated host module. Remove the module before removing the package:

php artisan maxx-ai:uninstall
# After successful uninstall and review of remaining host integrations:
composer remove maxx/laravel-ai-sdk

For approved non-interactive deployments use php artisan maxx-ai:uninstall --yes. The installer records original file hashes and directories in bootstrap/maxx-ai-installation.json. Keep this manifest with the installed host module; uninstall compares against the original installation, not the current SDK stubs, so SDK upgrades do not invalidate unchanged installed copies.

Uninstall requires confirmation, refuses modified/added/missing files or directories and symbolic links, preserves other modules and provider ordering, clears route/config caches, then removes Modules/AiGovernance, its provider registration and installation manifest. It preserves config/maxx-ai.php, .env, encrypted credentials, permissions, migrations' database history, usage/execution records, billing/invoice evidence and all other database tables. No rollback or data purge is performed.

If files were customized or the manifest is missing (including original regional modules installed outside this command), nothing is automatically removed. Back up/review changes and remove that host-owned module through its deployment process; do not generate a fresh manifest to bypass the check. Customized provider registration must be removed manually before retrying. Do not run composer remove after a refused uninstall until you have resolved the host's provider and SDK dependencies.

Review/remove remaining host business call sites, sidebar links, schedules and direct SDK references before Composer removal, then restart long-lived workers. The SDK cannot safely rewrite unrelated host integration code. Composer removal alone deliberately does not delete a generated module; no Composer plugin or automatic removal script is installed.

AI Governance API

The optional module follows the regional Workspaces API structure: App/Http/Controllers/Api/AiGovernanceApiController.php, Routes/api.php, direct route loading from its module provider, Sanctum authentication, and {"success": true, "data": ...} responses. The original web routes remain unchanged. See the module API reference for request fields, pagination, permissions, and examples.

The host must have Laravel Sanctum 4 installed and configured, its personal-access-token migration applied, and HasApiTokens on its user model. Use the existing HRMS login-issued bearer token; the module does not create login/token endpoints or require new token abilities. This package uses Sanctum as a development dependency for tests, not as a mandatory dependency for SDK-only hosts.

Method Endpoint Purpose
GET /api/ai-governance/overview Filtered tenant/region summary
GET /api/ai-governance/analytics Module and paginated user breakdowns
GET /api/ai-governance/requests Paginated usage/request history
GET /api/ai-governance/sdk-connection Safe connection status/configuration
POST /api/ai-governance/connection-check Check saved or submitted connection
PUT /api/ai-governance/sdk-connection Verify and save all six connection fields
GET /api/ai-governance/executions/{requestId} Owner-scoped status reconciliation; never resubmits work

Use Authorization: Bearer <HRMS-login-token> and Accept: application/json. All routes require active, matching regional tenant scope and existing governance permissions; SDK mutations additionally require administrator/SDK-management authority. API access requires a real Sanctum personal access token, not a browser session. Connection saves reverify the submitted credential immediately instead of using the web screen's session proof. Credentials are encrypted at rest and never returned. These endpoints create no new generation, completion, settlement or billing APIs.

Identity and keys

Platform-issued customer credential

With a backend including migration 0006_m2_client_credentials, a platform administrator can register the customer account/application/deployment under Client Access, then issue a scoped credential. Save the secret once in the Laravel server environment:

MAXX_AI_AUTH_MODE=platform
MAXX_AI_ACCESS_TOKEN=<one-time-secret>
MAXX_AI_ACCOUNT_ID=client-a
MAXX_AI_APPLICATION_ID=client-a-hrms
MAXX_AI_DEPLOYMENT_ID=client-a-india

Keep the SDK enabled only in an approved local/testing environment with provisional contracts explicitly allowed. Re-publish/merge the updated SDK config in an existing installation, then run php artisan config:clear after changing environment settings. This auth mode requires a version of this package containing PlatformTokenProvider; older published versions do not support it.

Clients do not need a machine private signing key in this mode. Identity and permissions are resolved by the backend from the stored credential hash, not from client-supplied account IDs. The account/application config remains required for billing-signature verification; configure the trusted backend billing public key ring separately.

Use separate customer accounts, and a credential per deployment or service. Secrets expire in 1-90 days; rotation immediately revokes the old secret and displays a replacement once. Revocation rejects new authentication requests; it does not cancel already-authorized M1 work. Never place secrets in browser code, Git, chat or logs. A lost issuance response must be reconciled by refreshing the credential list and revoking inaccessible credentials before issuing another.

Allowed permissions are actions:execute, completion:report, billing:read, and billing:ack. These credentials cannot issue funding, deliver internal receipts or attest human approval. Accepted completion of a human-review action still needs a separate trusted human identity. Onboarding does not configure actions, policies, pricing, budgets, funding or host invoice handlers. Billing streams are application/invoice-owner scoped, not isolated by regional deployment.

Existing machine JWT mode

MAXX_AI_AUTH_MODE=machine remains the default for compatibility. Configure the machine issuer, subject, account, application, deployment and kid to match the backend registration. MAXX_AI_MACHINE_PRIVATE_KEY_PATH must point to a protected local RSA private-key file (2048 bits minimum) outside the web root. The corresponding public key must be explicitly trusted by the backend. Do not copy or reuse backend billing/receipt private keys as machine keys. There are no bundled keys, passwords or automatic demo-key discovery.

Adjust machine.permissions in the published config to least privilege. Funding and receipt delivery require separate backend-designated subjects and permissions; permission strings alone do not grant authority. Machine tokens expire after 300 seconds (maximum 900).

The built-in signer represents a provisioned service, not an end user. For human review, bind a trusted request-scoped TokenProvider carrying the backend-approved human_actor_ref and permission; never turn an arbitrary browser actor reference into a signed human-review identity. Token issuance, MaxxSATA SSO and user permission decisions remain with the host/identity owners.

Client usage

use Maxx\Ai\Data\ActionContext;
use Maxx\Ai\Data\AuthorizationRequest;
use Maxx\Ai\GovernanceClient;

// Perform the host application's tenant/user permission checks first.
$client = app(GovernanceClient::class);
$request = new AuthorizationRequest(
    new ActionContext('tenant-1', 'actor-1', 'hrms', 'policy', 'interpret'),
    'persisted-request-id', 'dummy-resource', 'dummy-text', 'local', 'dis-service',
);
$authorization = $client->authorize($request);
$actionId = $authorization->string('logical_action_id');
$status = $client->status($actionId);

All result objects expose data and a generated correlationId; string($key) requires an actual string and fails explicitly on malformed responses. Financial values stay decimal strings. The HTTP client sets X-Correlation-ID; backend persistence/echo of that header is not guaranteed.

Client Methods
GovernanceClient scopeKeys, authorize, status, recover, complete, issueEntitlement, statement, deliverReceipt, billingEvents, acknowledge
ExecutionClient execute, status, receipt

Completion takes a typed CompletionRequest, including event ID, outcome, evidence hash, jurisdiction, validator version and optional human/adopted-policy references. The SDK never marks a business result accepted or adopts a policy automatically.

M1 execution uses a typed ExecutionRequest plus the M2-issued authorization token, not a machine bearer token. The caller must be the authorized executor and preserve the exact scoped IDs/token limits from the trusted M2 response. Do not send document content to M2 accounting. DIS delegation is not implemented because C08 is not approved.

Failure and retry behavior

  • No automatic retries, including reads, authorization, provider work and acknowledgments.
  • TransportException carries outcomeUnknown and correlation ID. A POST timeout may already have committed work. ApiException exposes HTTP status, safe error code, correlation ID and outcomeUnknown for server errors on POST.
  • ProtocolException marks malformed/oversized responses and whether a mutation's outcome needs reconciliation. A successful HTTP status alone does not prove a valid operation result.
  • Persist request IDs and payloads before sending. Never reuse an idempotency key for changed inputs. Conflicts are surfaced; the backend is the idempotency authority.
  • After an uncertain provider outcome, use known action/execution status and reconciliation; never create a new attempt automatically. If the initial response is lost before its ID is known, use the backend's documented idempotency/reconciliation procedure; the SDK does not invent an unavailable lookup-by-key endpoint.
  • Redirects are refused; TLS verification stays on. HTTP is allowed only for loopback.
  • The SDK does not log payloads, bearer tokens, private keys or raw backend errors. Do not log full responses, fake request histories or signed tokens in host applications. Guzzle transport exceptions are deliberately not chained because they retain sensitive request material.

Durable billing integration

Publish and explicitly apply the optional application-owned inbox migration:

php artisan vendor:publish --tag=maxx-ai-migrations
php artisan migrate

Inspect migrations and select the intended database before running. If billing.connection is not the default connection, migrate the same named connection explicitly using the host's migration procedure. No central wallet/ledger or business tenant tables are created. Inbox downgrade refuses to delete evidence.

In config/maxx-ai.php, set billing.public_key_paths to a map of trusted kid values to local public RSA PEM files. The issuer defaults to maxx-m2; audience/invoice owner must equal machine.application_id, and account must equal machine.account_id. Retain old public keys while their immutable billing events remain replayable. Tokens cannot supply their own keys.

Bind your application's implementation of Maxx\Ai\Billing\InvoiceHandler:

$this->app->bind(
    \Maxx\Ai\Billing\InvoiceHandler::class,
    \App\Billing\MaxxInvoiceHandler::class,
);

handle(BillingEvent $event): string must:

  1. Resolve the verified account/action/tenant mapping to the correct local invoice customer.
  2. Create a local invoice line for charge_finalized, or a linked credit/debit adjustment for charge_adjustment; preserve amounts as exact decimal strings.
  3. Use the same database connection/transaction as the inbox and add a unique event linkage.
  4. Return a stable invoice reference matching [A-Za-z0-9_.:-]{1,255}.
  5. Never make provider/payment/network calls inside the transaction. For external invoicing, implement a host-owned durable outbox and reconciliation workflow instead.

No default invoice handler exists: an SDK cannot safely guess your tax, approval or invoice rules. Do not call billing processing inside an existing database transaction.

Processing locks a unique inbox event, rejects changed payload hashes, commits the host invoice reference, then acknowledges remotely. If acknowledgment fails, the local record remains and replay retries acknowledgment without running the invoice handler again. This is an atomic same-database guarantee, not a claim of exactly-once external network side effects.

Pull worker

php artisan maxx-ai:billing-pull --limit=100 --max-pages=10

Schedule it using your application's scheduler and withoutOverlapping(). Each invocation starts from the oldest unacknowledged events, validates signed payloads and advances bounded opaque cursors. Failures propagate; the command never skips a failed invoice or writes a permanent cursor that could strand it.

Optional webhook

The SDK deliberately registers no route. Register this controller in your host's API routes, outside browser session authentication/CSRF middleware and with appropriate ingress rate limits:

Route::post('/integrations/maxx/billing', \Maxx\Ai\Laravel\BillingWebhookController::class);

Both signed_event and delivery are mandatory. The controller verifies the event plus the short-lived delivery envelope, pinned key, scope, expiry, event ID and exact backend payload hash before touching the inbox. Duplicate deliveries use the same durable event deduplication as polling. Configure the HTTPS destination with the backend owner. Add a reverse-proxy request-size limit. Keep APP_DEBUG=false on exposed receivers and prevent request-body capture in access/APM logs.

Tests and fakes

composer install
composer lint
composer test
composer audit
php examples\fake-portals.php

For this Windows XAMPP installation, if PHP is not on PATH or ZIP is disabled:

$env:PATH = "D:\XAMPP\php;" + $env:PATH
$env:OPENSSL_CONF = "D:\XAMPP\apache\conf\openssl.cnf"
php -d extension=zip C:\composer\composer.phar install

FakeTransport queues deterministic responses/exceptions, records calls for assertions and never falls through to the network. The HRMS/CRM example uses the same package for both portals.

The suite covers serialized requests against exported backend JSON schemas, JWT identity, signature/algorithm/key rotation, exact decimals, timeout/no-retry behavior, changed billing payloads, duplicate invoicing, transaction rollback, acknowledgment outage/replay, polling and webhook boundaries, including two concurrent PHP processes invoicing the same event once. Laravel integration tests use isolated SQLite, not a host application's data. The separate live qualification below also tests PostgreSQL concurrent polling/webhook processing. MySQL and actual host-application integrations still need their own evidence.

The CI workflow tests the locked baseline and Laravel 12 latest/lowest dependency resolution on PHP 8.2/8.3/8.4. Every job runs the full suite, including invoice concurrency, and uploads JUnit evidence; resolution jobs also retain their lockfile. A configured workflow is not evidence that remote CI has run.

The contract-parity job checks this SDK candidate against an immutable backend revision. Repository variables MAXX_UAI_BACKEND_REPOSITORY and MAXX_UAI_BACKEND_SHA select the producer; defaults are SandipKumar123/maxx-universal-ai-platform at 09da738a138b1a05be7e33abe75e5f97c83a1396. Update both when changing the approved producer. For a private cross-repository checkout, configure a read-only CROSS_REPO_READ_TOKEN secret with access to the producer; the default workflow token normally cannot read another private repository. No personal token belongs in source.

Check upstream snapshots without modifying them:

php tools\sync-contracts.php "C:\xampp\htdocs\maxx-universal-ai-platform" --check

The check fails on missing/changed schemas or invalid provenance. Only LF/CRLF differences are accepted; JSON/schema changes require explicit review. Matching snapshots demonstrate parity, not automatic backward compatibility or approval of an incompatible contract.

Refresh exported schema snapshots only after reviewing the backend changes:

php tools\sync-contracts.php "D:\XAMPP\htdocs\maxx-universal-ai-platform"
composer test

The provenance manifest records each upstream schema path, original source SHA-256 and the SHA-256 of its LF-normalized SDK snapshot. Snapshots are provisional, not C01-C08 approval.

Local verification

On 27 October 2026, the working-tree candidate on PHP 8.5.12 with locked Laravel 12.70.0 passed 87 tests, 176 assertions, including read-only upstream parity checks, changed/missing schema rejection, and LF/CRLF handling. This is separate from historical PHP 8.2 results and does not establish the configured remote PHP matrix, a tagged release, or production acceptance.

Separate temporary package copies also passed all 87 tests / 176 assertions with Laravel 12.70.1 (latest resolution) and 12.69.0 (secure lowest resolution). The lowest resolution emitted two PHP 8.5 deprecations from Testbench's bundled database configuration; the locked/latest runs were clean. No vendor files or advisory policies were changed to suppress these notices. Composer strict validation, PHP lint, locked dependency audit, and the eight-schema upstream parity check passed. Both workflow files passed actionlint.

Real backend and PostgreSQL qualification

An opt-in backend test, tests/integration/test_laravel_sdk_live.py, drives this SDK fixture over real loopback HTTP, not a mocked HTTP client. It uses the actual FastAPI M1/M2 routers, ephemeral RSA identities, the dummy provider, real PostgreSQL accounting, and the SDK's actual published inbox migration in a separate PostgreSQL host schema.

Verified on 19 October 2026 using PostgreSQL 17.11, PHP 8.2.12, Laravel 12.70.0 and an isolated Python 3.13.16 runtime:

  • Authorization and execution replay retain the original IDs; changed authorization payloads fail.
  • Cross-account access, missing human-adoption evidence and jurisdiction mismatches fail.
  • Accepted/rejected completions and duplicate receipt settlement retain durable accounting evidence.
  • Rejected work emits a zero charge without discarding consumed provider expense.
  • Real Python decimal strings such as 0E-12 are normalized exactly, without floats.
  • Unknown provider outcomes keep their hold and deny recovery; no new provider attempt is created.
  • Signed billing pages and opaque cursors work with the actual backend.
  • A real remote acknowledgment followed by a deliberately lost response replays without reinvoicing.
  • Two PHP processes race polling versus a Python-signed webhook for one PostgreSQL inbox event: one local invoice effect is committed. Invalid delivery signatures are rejected.
  • Conflicting acknowledgment references fail; acknowledged events disappear from billing pull.
  • The test server stops and generated schemas, credentials, keys and signed temporary evidence are removed after the run. Existing demo/customer records are not altered.

Run from the backend directory with a working project Python environment:

$env:MAXX_UAI_RUN_DB_TESTS = "true"
$env:MAXX_UAI_RUN_SDK_TESTS = "true"
$env:MAXX_UAI_SDK_PATH = "D:\XAMPP\htdocs\maxx-laravel-ai-sdk"
$env:MAXX_UAI_SDK_PHP = "D:\XAMPP\php\php.exe"
$env:MAXX_UAI_SDK_PHP_PGSQL_EXTENSION = "true"
.\.venv\Scripts\python.exe -m pytest tests\integration\test_laravel_sdk_live.py -q -p no:cacheprovider

PHP needs pdo_pgsql; the extension flag enables it only for the test child processes. Omit the flag if already enabled. The backend's existing isolated-database fixture uses MAXX_UAI_TEST_DATABASE_URL when supplied, otherwise the configured local database; the database role needs permission to create temporary schemas. No deployment migrations are applied. The SDK repository is required only when this test is explicitly enabled.

The platform's Pinned Laravel SDK qualification workflow runs this test with PostgreSQL 16 and PHP 8.2, alongside parity, lint, dependency audit and the standalone suite. After committing both candidates, dispatch it at the intended platform revision with sdk_repository and the full 40-character sdk_sha. It records the actual platform/SDK SHAs and rejects a skipped live test. Private SDK checkout requires the platform's read-only CROSS_REPO_READ_TOKEN. It does not deploy services, use live AI, or qualify HRMS/CRM legal invoicing.

This verifies a freshly started isolated instance of the real backend, not your existing running demo server or a live AI provider. The test invoice handler creates synthetic invoice evidence: it is not an HRMS/CRM tax/invoicing implementation. Local PostgreSQL concurrency success does not qualify another database/version, a production deployment, crash recovery, or operational load.

On 27 October 2026 the changed working-tree SDK candidate passed this real HTTP/PHP test against the local platform candidate using PHP 8.5.12 and PostgreSQL 18.6: 1 passed, zero skipped. Validation created and removed a separate randomly named database; the configured application database was not migrated or used for test records. This is local evidence, not a remote CI run or release acceptance.

The existing project .venv was found unusable during this run: C:\Python313 was missing its standard library. Verification used an isolated managed Python 3.13 runtime with the unchanged backend lockfile, rather than repairing shared Python or overwriting the project environment.

Remaining integration checklist

Area Current evidence / remaining requirement
Real SDK-to-backend integration Passed locally against the real isolated FastAPI server and PostgreSQL, with the dummy provider.
HRMS/CRM installation India, USA and UAE HRMS adapters and locked SDK references are present; runtime qualification, upgrades and end-to-end host acceptance remain deployment-specific. CRM acceptance is separate.
Host invoice handler Synthetic PostgreSQL handler verified; actual customer/tax/invoice mapping remains application-owned.
Approved production contracts and SSO Still requires owner-approved contracts, real identity integration and acceptance.
Database concurrency Local PostgreSQL 17.11 polling/webhook race passed; target deployment, failure/load and any MySQL qualification remain.
GitHub publication / release Local Git remote is configured; publication of this candidate, passing remote workflows and an approved immutable release tag remain required.

Release gates and rollback

Before an approved release: freeze contracts/identity and error semantics, audit actual HRMS/CRM PHP/Laravel baselines, run live machine/receiver tests and production-database concurrency tests, review tax/invoice and human-approval integration, rehearse outages/rollback, record baseline/release SHAs and reviewer acceptance, then publish/tag an immutable version. Do not remove the production gate merely to make a deployment start.

Roll back the compatible package version while retaining the inbox and host invoice evidence. Never delete rows to bypass a billing conflict. A configured Git remote or local passing tests do not establish public publication, a release tag, host deployment or production acceptance.

HRMS integration documentation (27 October 2026)

The India, USA and UAE applications already reference this package and use HrmsAiClient for governed local/test generation. See the host integration and operator manual for the six-field regional connection workflow, locked/source version distinction, request recovery and host-owned invoice handling. These inspected HRMS applications require Laravel 12 in their manifests; this does not qualify every deployed host or add Laravel 10/11 support. The selected source SDK suite passed 65 tests / 111 assertions; host end-to-end and production acceptance are separate.