# Panasync / optional ORION integration reference

Clarified 21 October 2026. IDC, Civitas and HLN Group's industry/mission workflows operate within ORION. **HorizonOS is not a dependency, and no HorizonOS development or game-log feed is required.** HorizonOS does not currently handle the contract, bidding or delivery workflows described here. This guide describes ORION's API and possible future adapters; it does not describe installed HorizonOS capabilities or ask Panasync to build them.

Public Apex Atlas and Alerts are separate services. ORION's use of their documented public APIs does not require HorizonOS. Private Apex Dispatch would be a separately agreed future integration. Check the accompanying release record for deployment and validation status.

## What ORION handles

The **Interstellar Diplomatic Corps (IDC)** brokers bids between clients and independently operated mercenary organizations. A provider retains command of its personnel. ORION records the request, private bids, client selection, independent broker award, provider acceptance, actual Civitas escrow, delivery, client acceptance and independent settlement. Disputes retain a recorded decision and return funds through the original accounts.

**Civitas Credit Cooperative (CCC)** is the current name. Old internal `ctb:` identifiers and the stable `/portfolio/ctb` address are retained for compatibility. ORION Convoy remains the freight system; Manifest is an existing game app. Apex StarComm supplies public Atlas references and expiring Alerts; neither proves a live tactical position or completed delivery.

## Optional connections, only if separately agreed

### A. An external service → ORION IDC

An external service may choose to use ORION's organization-scoped API, through an adapter for capabilities it actually offers. No adapter is required for normal ORION operation. The following checklist applies only if such a connection is requested; it does **not** require an Apex-audience token or raw game logs. Do not assume HorizonOS has local contracts, bids, delivery records or Dispatch functions to export.

| Step | Owner | Information/action |
| --- | --- | --- |
| Choose integration organization | Integrating service operator + HLN administrator | Confirm the active Corp organization ID, matching Civitas institution and actual source tenant. Confirm the registry record rather than assuming the display name is a tenant slug. |
| Generate server key | Integrating service operator | Ed25519 private key held only in that service's server secret store; share **public JWK only**, `{kty:'OKP',crv:'Ed25519',x:'...'}`. Never send the private key in chat. |
| Register client | HLN Corporate administrator | IDC Brokerage → Access & integrations → Register a client; record organization, source tenant, public key, minimal scopes and expiry. Return public client UUID. No account, appointment or money movement is created. |
| Delegate rights | Authorized organization member | Sign in with their own UCI identity, choose the client and institution, grant only needed scopes for up to 90 days. Return delegation UUID through the organization's configuration process. Delegation is revocable and must not be shared as a blanket identity for unrelated users. |
| Implement connection | Integrating service operator | Implement only the separately agreed mapping from capabilities that service actually has. Use `client.mjs` and the OpenAPI specification. Keep exact signed bytes, durable business instruction IDs and event cursor. No signing material belongs in a browser bundle. |
| Joint acceptance | Integrating service operator + HLN | Test only the agreed operations with synthetic records, plus replay/conflict, revocation, event resume and denial of financial actions. ORION's wider API catalogue is not a requirement to implement every operation. |

Suggested initial scopes: `contracts.read`, `events.read`, `records.write`. Add `tenders.write`, `bids.write` or `deliveries.write` only for a concrete approved workflow. A read/source-only client needs no payment authority.

Addresses:

- Workspace and registration: `https://hlncorp.space/idc`
- Developer page: `https://hlncorp.space/developers/operations`
- API: `https://hlncorp.space/api/v1/idc`
- OpenAPI: `https://hlncorp.space/api/v1/idc/openapi`
- Signing/action reference: `https://hlncorp.space/developers/idc/README.md`
- Full ORION guide: `https://hlncorp.space/developers/idc/ORION-OS-API-Guide.md`
- Node client: `https://hlncorp.space/developers/idc/client.mjs`

Source observations must use the registration's exact source tenant, actual record UUID, kind, selected state, SHA-256 of the deliberately shared projection, observation time within five minutes and authenticated local UCI subject equal to the delegation holder. The source server must enforce its own OPE/access checks before signing. Do not send exact crew coordinates, medical details, private dispatch threads or an entire stock ledger. Observations remain evidence for review and cannot release escrow.

### B. ORION → private Apex Dispatch, if separately requested

The public docs describe manually registered, player-authorized access. This is not needed for IDC, Civitas, Group's own workflows or the public Atlas/Alerts reads. If a private crew integration is later agreed, confirm the following with its operator; no credentials are requested in this document:

1. The **client registration process and resulting public client ID** for ORION's private crew integration. Tell us whether this is a new UCI client, an allowed audience on an existing registration, or another documented mechanism.
2. The **exact OAuth scopes**, issuer/discovery/JWKS information and authorization/token endpoint requirements that produce an Apex-audience player token. We will use Authorization Code with PKCE S256 and server-side token handling. Existing ORION tokens will not be forwarded as substitutes.
3. The **allowed exact redirect URI(s)** and approved host(s), including the installed ORION path if supported. ORION will supply the final implemented callback for allowlisting after the registration contract is confirmed. No guessed callback is represented as working; the existing Corp UCI callback is not an Apex callback.
4. How a player obtains, inspects and loses the **responder or dispatcher operator grant**, which scope maps to which route, and whether a non-operator receives 403 or another documented result.
5. Refresh-token availability/rotation/revocation, access-token lifetime, session logout behavior and the expected `aud` value (**documented: `https://apexstarcomm.space`**).
6. A safe acceptance arrangement using the Apex operator's supported test tools and an authorized test responder/dispatcher, with no real crew/private medical information in shared logs. Do not assume HorizonOS creates or owns the test record. Do not send test-account credentials in chat.
7. Any documentation changes concerning rate tiers, ETags, request IDs, retention or supported write operations. The current documented API has **one Apex queue**, permits only authorized crew operations and **does not offer third-party beacon creation**. ORION will not simulate missing routes or publish emergency alerts without an approved endpoint and separate authorization.

After these facts are confirmed, ORION can add the private authorization callback/token storage and test the permitted crew flow. That adapter is deliberately not advertised as connected today. No Apex-side change is needed for ORION's existing public Atlas/Alerts reads.

## ORION-native connection

ORION's Convoy, Dispatch and Materials gain an IDC connection action. An administrator configures the server-only `ORION_IDC_CLIENTS` map with a separate `{clientId,privateKey}` for each actual tenant. The member supplies their own IDC delegation. ORION verifies linked UCI identity, tenant, OPE and the current source before attesting it.

Default mapping examples: Corp `hln` → ORION `hln-corp`; Corp `hln-group` → ORION `hln`; SATO → `sato`. These are examples of existing mappings, not authority to create new affiliations. The client registration permits an explicit source tenant.

This native bridge does not need a new SQL file on every organization's database. Its configured client must still be registered centrally and delegated by an authorized member. Key rotation uses a new registered client and deliberate delegation, followed by revocation of the old client; there is no private-key export from ORION to users.

## App Store option

Developers who choose to build an installable ORION app can use [App SDK 1.6.0](https://www.orionos.app/downloads/orion-app-sdk-1.6.0.zip). This is a separate option, not a HorizonOS deliverable. The full guide describes six member-approved actions, Work Suite formats, appearance, draft lifecycle, packaging and review.

An uploaded `.orion-app` requires no public hosting but runs with restricted networking and no server runtime. It is suited to self-contained tools and approved file actions. Any server-to-server IDC client belongs on the integrating service's own backend, not inside an uploaded package. A separately hosted app can use its own backend under its own reviewed privacy policy; it still receives no ORION credentials from the SDK.

## Financial and operational boundaries

- No default funded cargo policy is installed. Treasury proposes immutable terms, a second current Treasury officer approves actual available capital, an independent officer quotes risk, and the client explicitly accepts the premium. Claims need evidence and two current independent reviewers before payout. No automatic parametric payout is implied.
- OCR runs on the member's device; its amount/recipient hints are unverified. Server-computed image similarity flags review, never proof or automatic credit. Raw OCR text is not persisted.
- Published exchange data is read through `https://hlncorp.space/api/omb-financial-feed`; missing data stays null and stale alerts expire. There are no guaranteed bond yields, invented telemetry-derived prices or private account data in that feed.
- Installation preserves existing service mode and disabled monetary automation. It creates no member accounts, staff grants, client delegations, live policies, capital allocations or transactions. IDC organization/unit records and an unassigned broker role definition provide the administrative structure.

## Joint acceptance record

Record deployment/version, client UUID, organization/source tenant, allowed scopes, delegation expiry, test request ID and final result. Keep private keys, bearer tokens, signatures, private contract bodies and personal information out of the shared record.

Accept when: a permitted request succeeds; another actor/organization is denied; revocation takes effect; unchanged retries do not duplicate work; event restart loses no changes; stale source observations are refused; public feeds contain no private data; and a delivery/source report cannot approve or pay itself. Real payments are outside this integration acceptance exercise.

## HLN Group industry preparation

Group can use Materials → Targets and Materials → Industry work to prepare actual Operations planning drafts. A stock-target rule uses available organization stock in the matching unit, subtracting reservations and excluding personal stores. An IDC rule reads current funded INDUSTRY contracts using its owner's UCI-bound contracts.read delegation. Rules are saved paused and deliberately enabled; the protected scheduler checks them every 15 minutes. Existing active missions are not duplicated or overwritten. Loss of the owner's authority pauses preparation; stale/revoked integrations produce a visible rule error.

No HorizonOS change is required for local stock-target or IDC-contract rules. They read ORION's own stock and funded contracts. ORION's source bridge can attach mission references after local classification and OPE checks. A future external adapter would need its own agreed purpose and a confirmed source capability; no such HorizonOS adapter is required here. Mission generation does not consume stock, assign crews, issue orders, announce operations, approve receiving evidence or settle Civitas funds. Those actions stay in their existing apps and approval flows.

All API timestamps remain real UTC. User-facing dates are displayed as real date + 930 years. Do not add 930 years to a signed request's timestamp or source observation.