Docs • API Contracts • v0.2

Contract docs của `api.noos.iai.one` cho NOOS liên hành tinh `api.noos.iai.one` contract docs for interplanetary NOOS

Trang này định nghĩa contract vocabulary cho NOOS ở mức habitat-local và interplanetary federation. Đây chưa phải production API hoàn chỉnh, mà là bề mặt ngôn ngữ chung cho docs, UI, Flow runtime và các implementation tương lai sống qua độ trễ phút tới ngày. This page defines the contract vocabulary for NOOS at habitat-local and interplanetary federation scale. It is not yet a complete production API, but a shared language surface for docs, UI, Flow runtime and future implementations that must survive minute-to-day latency.

System Map System Map Governance Governance Evidence Anchors Evidence Anchors OpenAPI YAML OpenAPI YAML

Scope của v0.2 Scope of v0.2

Control-plane first Control-plane first

API này ưu tiên missions, twins, telemetry, delay-tolerant intents, DTN bundles, federation policy và evidence. Nó không cố trở thành raw device shell. This API prioritizes missions, twins, telemetry, delay-tolerant intents, DTN bundles, federation policy and evidence. It does not try to become a raw device shell.

Execution không bypass Flow Execution does not bypass Flow

Các intent cần chạy workflow hoặc approvals sẽ đi qua `flow.iai.one`, không được dùng API để bỏ qua runtime và governance dù đang ở habitat, quỹ đạo hay relay node. Intents that need workflows or approvals will go through `flow.iai.one`; the API cannot be used to bypass runtime and governance whether the caller sits in a habitat, orbit or relay node.

Evidence-native Evidence-native

Mọi hành động quan trọng cần tạo record có thể review sau này. Logs là chưa đủ nếu không có claim, context, custody chain và signatures. Every important action must create a reviewable record later. Logs alone are insufficient without claim, context, custody chains and signatures.

Insight-only interplanetary sync Insight-only interplanetary sync

Liên hành tinh chỉ sync insight, twin delta, command bundle và evidence summary qua DTN store-and-forward. Raw data bulk replication không nằm trong scope v0.2. Interplanetary operation syncs only insight, twin deltas, command bundles and evidence summaries through DTN store-and-forward. Bulk raw data replication is outside v0.2 scope.

Base surface Base surface

Base URL:
https://api.noos.iai.one/v1

Suggested auth headers:
Authorization: Bearer <operator-or-service-token>
X-NOOS-Actor-Type: operator | service | device
X-NOOS-Signature: <optional detached signature for high-trust flows>
X-NOOS-Twin-Id: <required for device-side telemetry ingestion>
X-NOOS-Route-Mode: realtime | dtn_store_forward
X-NOOS-Bundle-Id: <optional DTN bundle id>

Content-Type:
application/json

Machine-readable draft của contract này nằm tại `/docs/api-contracts/openapi.noos.v0.1.yaml` và đã phản ánh vocabulary liên hành tinh v0.2. The machine-readable draft of this contract lives at `/docs/api-contracts/openapi.noos.v0.1.yaml` and now reflects the interplanetary v0.2 vocabulary.

Resource families Resource families

`/missions`

Định nghĩa mission graph: objective, risk class, owners, regions và success criteria. Defines the mission graph: objective, risk class, owners, regions and success criteria.

`/twins`

Quản lý twin registry cho site, robot, node, gateway, zone, habitat, relay node, health twin và energy asset. Manages the twin registry for sites, robots, nodes, gateways, zones, habitats, relay nodes, health twins and energy assets.

`/telemetry/events`

Nhận telemetry chuẩn hóa từ devices, gateways hoặc upstream processors, gồm route mode, bundle references và custody-aware evidence. Ingests normalized telemetry from devices, gateways or upstream processors, including route mode, bundle references and custody-aware evidence.

`/intents`

Tạo command intents có approval state, workflow reference, rollback reference và biến thể delay-tolerant cho DTN. Creates command intents with approval state, workflow reference, rollback reference and a delay-tolerant variant for DTN.

`/policy-envelopes`

Cung cấp hard limits, required human review, allowed modes, BCI veto, disconnect rights và federation rules. Provides hard limits, required human review, allowed modes, BCI veto, disconnect rights and federation rules.

`/evidence-records`

Lưu claim, source, timestamps, confidence, custody chain và relay provenance cho post-action analysis. Stores claim, source, timestamps, confidence, custody chains and relay provenance for post-action analysis.

`/dtn-bundles`

Đóng gói insight, twinDelta, command và evidence theo kiểu store-and-forward với custody tracking. Packages insight, twinDelta, command and evidence in store-and-forward form with custody tracking.

`/federation-policies`

Mô tả sync scope, conflict resolution, approval threshold và dữ liệu nào được federation giữa habitats. Describes sync scope, conflict resolution, approval thresholds and which data may federate between habitats.

`/interplanetary-twins`

Bề mặt đọc/ghi cho habitat twins có latency profile, federation level, autonomy mode và energy profile. Read/write surface for habitat twins with latency profiles, federation levels, autonomy modes and energy profiles.

Endpoint sketches Endpoint sketches

Core reads and writes Core reads and writes

GET    /v1/missions
POST   /v1/missions
GET    /v1/missions/{missionId}

GET    /v1/twins
POST   /v1/twins
GET    /v1/twins/{twinId}
PATCH  /v1/twins/{twinId}

GET    /v1/interplanetary-twins
POST   /v1/interplanetary-twins
GET    /v1/interplanetary-twins/{twinId}
PATCH  /v1/interplanetary-twins/{twinId}

POST   /v1/telemetry/events
GET    /v1/telemetry/events/{eventId}

POST   /v1/intents
GET    /v1/intents/{intentId}
POST   /v1/intents/{intentId}/approve
POST   /v1/intents/{intentId}/reject
POST   /v1/intents/{intentId}/rollback

GET    /v1/policy-envelopes/{policyId}
POST   /v1/evidence-records
GET    /v1/evidence-records/{recordId}

POST   /v1/dtn-bundles
GET    /v1/dtn-bundles/{bundleId}

GET    /v1/federation-policies/{policyId}

Envelope examples Envelope examples

{
  "mission": {
    "id": "mission_wildfire_delta",
    "domain": "wildfire",
    "objective": "Observe and escalate anomalous fire signatures",
    "riskClass": "high",
    "owners": ["ops_sg_01"],
    "regions": ["vn_central_highlands"],
    "successCriteria": ["detect_under_5m", "human_review_under_120s"]
  },
  "interplanetaryTwin": {
    "id": "habitat_mars_vallis_01",
    "class": "habitat",
    "habitatId": "mars_vallis_01",
    "solarLocation": {
      "body": "Mars",
      "coords": { "lat": -14.6, "lon": 175.4 }
    },
    "latencyProfile": {
      "avgMs": 720000,
      "maxMs": 1440000,
      "blackoutWindow": "PT6H"
    },
    "federationLevel": "partial",
    "autonomyMode": "federated",
    "energyProfile": {
      "currentkWh": 1820,
      "reserveHours": 96,
      "shedPriority": 2
    }
  }
}

Delay-tolerant intent example Delay-tolerant intent example

{
  "id": "intent_01HV8Y3GAT",
  "actor": {
    "id": "operator_iai_ops_01",
    "type": "operator"
  },
  "targetTwinId": "uav_quangnam_02",
  "workflowRef": "flow://mission-response/drone-survey-v1",
  "requestedAction": {
    "type": "launch_survey",
    "params": {
      "zone": "forest_corridor_17",
      "altitudeM": 90
    }
  },
  "approvalState": "pending_human",
  "bundleId": "bundle_01JX8MARS01",
  "expectedDeliveryWindow": {
    "earliest": "2126-03-23T05:00:00Z",
    "latest": "2126-03-23T05:40:00Z"
  },
  "priorityOnReconnect": "critical",
  "rollbackOnTimeout": true,
  "custodyChain": ["earth_gateway_01", "lagrange_relay_a2"],
  "rollbackRef": "playbook://uav/abort-return-home-v1"
}

Auth modes Auth modes

Operator tokens Operator tokens

Dùng cho review, approval và các write actions từ human-facing surfaces. Phải mang role context và audit principal rõ ràng. Used for review, approval and write actions from human-facing surfaces. They must carry clear role context and an audit principal.

Service principals Service principals

Dùng cho integrations nội bộ giữa NOOS services và Flow. Scope phải bị giới hạn theo resource family. Used for internal integrations between NOOS services and Flow. Scope must stay limited by resource family.

Device identity Device identity

Dùng cho telemetry ingestion và attestation-bound operations. Về sau cần gắn với TPM, secure elements hoặc equivalent roots of trust. Used for telemetry ingestion and attestation-bound operations. Later this should bind to TPMs, secure elements or equivalent roots of trust.

Relay identity Relay identity

Dùng cho DTN bundles, custody updates và solar relay links. Cần PQC signatures, attestation chain và optional QKD session state. Used for DTN bundles, custody updates and solar relay links. Requires PQC signatures, attestation chains and optional QKD session state.

Non-goals của v0.2 Non-goals of v0.2

Không shell trực tiếp vào robot No direct shell into robots

API không cung cấp raw terminal hay unrestricted execution lên robot và gateways. The API does not provide raw terminal access or unrestricted execution on robots and gateways.

Không bypass approvals No approval bypass

Mọi write path nhạy cảm phải tôn trọng policy envelopes và human review khi cần. Every sensitive write path must respect policy envelopes and human review when required.

Không sync raw data bulk xuyên DTN No bulk raw-data sync across DTN

DTN backbone chỉ dành cho insight, twin delta, command bundle và evidence summary. Raw payload replication cần transport riêng. The DTN backbone is only for insight, twin delta, command bundles and evidence summaries. Raw payload replication needs a separate transport.

Không coi docs này là production spec cuối Do not treat this as the final production spec

Đây là contract vocabulary v0.2. Triển khai thật sau này cần thêm version negotiation, pagination, custody error taxonomy, CGR policies và signature formats cụ thể hơn. This is the v0.2 contract vocabulary. Real implementations later need version negotiation, pagination, custody error taxonomy, CGR policies and more explicit signature formats.