@xtrape/capsule-contracts-node 0.1.0-public-review.0

package/dist/index.js

@@ -0,0 +1,179 @@
+// src/index.ts
+import { customAlphabet } from "nanoid";
+import { z } from "zod";
+var AgentStatus = ["PENDING", "ONLINE", "OFFLINE", "DISABLED", "REVOKED"];
+var CapsuleServiceStatus = ["UNKNOWN", "HEALTHY", "UNHEALTHY", "STALE", "OFFLINE"];
+var HealthStatus = ["UP", "DEGRADED", "DOWN", "UNKNOWN"];
+var CommandStatus = ["PENDING", "RUNNING", "SUCCEEDED", "FAILED", "EXPIRED", "CANCELLED"];
+var DangerLevel = ["LOW", "MEDIUM", "HIGH"];
+var AuditActorType = ["USER", "AGENT", "SYSTEM"];
+var AuditResult = ["SUCCESS", "FAILURE"];
+var TokenStatus = ["ACTIVE", "REVOKED", "EXPIRED", "USED"];
+var ErrorCode = {
+  INTERNAL_ERROR: "INTERNAL_ERROR",
+  VALIDATION_FAILED: "VALIDATION_FAILED",
+  UNAUTHORIZED: "UNAUTHORIZED",
+  FORBIDDEN: "FORBIDDEN",
+  NOT_FOUND: "NOT_FOUND",
+  CONFLICT: "CONFLICT",
+  CSRF_INVALID: "CSRF_INVALID",
+  ACTION_REQUIRES_CONFIRMATION: "ACTION_REQUIRES_CONFIRMATION",
+  COMMAND_EXPIRED: "COMMAND_EXPIRED",
+  TOKEN_REVOKED: "TOKEN_REVOKED",
+  TOKEN_EXPIRED: "TOKEN_EXPIRED",
+  AGENT_REVOKED: "AGENT_REVOKED",
+  AGENT_DISABLED: "AGENT_DISABLED"
+};
+var idPrefixes = ["wks_", "usr_", "agt_", "tok_", "svc_", "hlr_", "cfg_", "act_", "cmd_", "crs_", "aud_"];
+var NANO = customAlphabet("0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz_-", 21);
+function newId(prefix) {
+  return `${prefix}${NANO()}`;
+}
+var AnyJson = z.record(z.any());
+var AgentStatusSchema = z.enum(AgentStatus);
+var CapsuleServiceStatusSchema = z.enum(CapsuleServiceStatus);
+var HealthStatusSchema = z.enum(HealthStatus);
+var CommandStatusSchema = z.enum(CommandStatus);
+var DangerLevelSchema = z.enum(DangerLevel).default("LOW");
+var UserSchema = z.object({ id: z.string().startsWith("usr_"), username: z.string(), displayName: z.string().nullable().optional(), createdAt: z.string(), updatedAt: z.string() });
+var UserRole = z.enum(["owner", "operator", "viewer"]);
+var createUserRequestSchema = z.object({ username: z.string().min(1), password: z.string().min(12), displayName: z.string().optional(), role: UserRole.default("viewer") });
+var updateUserRequestSchema = z.object({ displayName: z.string().optional(), role: UserRole.optional(), status: z.enum(["ACTIVE", "DISABLED"]).optional() });
+var resetUserPasswordRequestSchema = z.object({ password: z.string().min(12) });
+var AdminLoginRequestSchema = z.object({ username: z.string().min(1), password: z.string().min(1) });
+var adminLoginRequestSchema = AdminLoginRequestSchema;
+var AdminSessionSchema = z.object({ user: UserSchema, csrfToken: z.string(), expiresAt: z.string() });
+var AgentSchema = z.object({ id: z.string().startsWith("agt_"), code: z.string(), name: z.string().nullable().optional(), mode: z.enum(["embedded", "sidecar", "external"]), runtime: z.string().nullable().optional(), status: AgentStatusSchema, lastHeartbeatAt: z.string().nullable().optional(), createdAt: z.string(), updatedAt: z.string() });
+var RegistrationTokenSchema = z.object({ id: z.string().startsWith("tok_"), name: z.string(), status: z.enum(TokenStatus), expiresAt: z.string().nullable().optional(), usedAt: z.string().nullable().optional(), createdAt: z.string() });
+var CreateRegistrationTokenRequestSchema = z.object({ name: z.string().default("Default registration token").optional(), expiresInSeconds: z.number().int().min(60).optional() });
+var createRegistrationTokenRequestSchema = CreateRegistrationTokenRequestSchema;
+var CreateRegistrationTokenResponseSchema = RegistrationTokenSchema.extend({ rawToken: z.string().startsWith("opstage_reg_") });
+var CapsuleManifestSchema = z.object({ kind: z.literal("CapsuleService"), schemaVersion: z.string().default("1.0").optional(), code: z.string().min(1), name: z.string().min(1), description: z.string().optional(), version: z.string().min(1), runtime: z.enum(["nodejs", "java", "python", "go", "other"]), agentMode: z.enum(["embedded", "sidecar", "external"]), capabilities: z.array(z.string()).optional(), labels: z.record(z.string()).optional() }).passthrough();
+var HealthReportInputSchema = z.object({ status: HealthStatusSchema, message: z.string().optional(), details: AnyJson.optional() });
+var healthReportInputSchema = HealthReportInputSchema;
+var ConfigItemInputSchema = z.object({ key: z.string(), label: z.string().optional(), type: z.string(), source: z.string().optional(), editable: z.boolean().optional(), sensitive: z.boolean().optional(), valuePreview: z.string().optional(), defaultValue: z.string().optional(), secretRef: z.string().optional() });
+var configItemInputSchema = ConfigItemInputSchema;
+var ActionDefinitionInputSchema = z.object({ name: z.string(), label: z.string(), description: z.string().optional(), dangerLevel: z.enum(DangerLevel).default("LOW").optional(), requiresConfirmation: z.boolean().optional(), category: z.string().optional(), order: z.number().int().optional(), inputSchema: AnyJson.optional(), outputSchema: AnyJson.optional(), timeoutSeconds: z.number().int().positive().optional() });
+var actionDefinitionInputSchema = ActionDefinitionInputSchema;
+var ReportedServiceSchema = z.object({ code: z.string().min(1).max(80), name: z.string().min(1).max(200), description: z.string().max(2e3).optional(), version: z.string().max(80).optional(), runtime: z.string().optional(), manifest: AnyJson, health: HealthReportInputSchema.optional(), configs: z.array(ConfigItemInputSchema).optional(), actions: z.array(ActionDefinitionInputSchema).optional() });
+var reportedServiceSchema = ReportedServiceSchema;
+var ServiceReportRequestSchema = z.object({ services: z.array(ReportedServiceSchema).min(1) });
+var serviceReportRequestSchema = ServiceReportRequestSchema;
+var RegisterAgentRequestSchema = z.object({ registrationToken: z.string().startsWith("opstage_reg_"), agent: z.object({ code: z.string(), name: z.string().optional(), mode: z.literal("embedded"), runtime: z.string().optional() }), service: ReportedServiceSchema.optional() });
+var registerAgentRequestSchema = RegisterAgentRequestSchema;
+var RegisterAgentResponseSchema = z.object({ agentId: z.string().startsWith("agt_"), agentToken: z.string().startsWith("opstage_agent_"), heartbeatIntervalSeconds: z.number().int(), commandPollIntervalSeconds: z.number().int() });
+var AgentHeartbeatResponseSchema = z.object({ heartbeatIntervalSeconds: z.number().int(), commandPollIntervalSeconds: z.number().int() });
+var AgentHeartbeatRequestSchema = z.object({ serviceId: z.string().startsWith("svc_").optional(), health: HealthReportInputSchema.optional() });
+var agentHeartbeatRequestSchema = AgentHeartbeatRequestSchema;
+var CapsuleServiceSchema = z.object({ id: z.string().startsWith("svc_"), agentId: z.string().startsWith("agt_").optional(), code: z.string(), name: z.string(), description: z.string().nullable().optional(), version: z.string().nullable().optional(), runtime: z.string().nullable().optional(), status: CapsuleServiceStatusSchema, healthStatus: HealthStatusSchema.optional(), lastReportedAt: z.string().nullable().optional(), lastHealthAt: z.string().nullable().optional(), createdAt: z.string(), updatedAt: z.string() });
+var HealthReportSchema = z.object({ id: z.string().startsWith("hlr_"), serviceId: z.string().startsWith("svc_"), agentId: z.string().startsWith("agt_").optional(), status: HealthStatusSchema, message: z.string().nullable().optional(), details: AnyJson.optional(), reportedAt: z.string() });
+var ConfigItemSchema = z.object({ id: z.string().startsWith("cfg_"), serviceId: z.string().startsWith("svc_"), key: z.string(), label: z.string().nullable().optional(), type: z.string(), source: z.string().nullable().optional(), editable: z.boolean().default(false), sensitive: z.boolean(), valuePreview: z.string().nullable().optional(), defaultValue: z.string().nullable().optional(), secretRef: z.string().nullable().optional() });
+var ActionDefinitionSchema = z.object({ id: z.string().startsWith("act_"), serviceId: z.string().startsWith("svc_"), name: z.string(), label: z.string(), description: z.string().nullable().optional(), dangerLevel: z.enum(DangerLevel), requiresConfirmation: z.boolean(), category: z.string().optional(), order: z.number().int().optional(), inputSchema: AnyJson.optional(), outputSchema: AnyJson.optional(), timeoutSeconds: z.number().int().optional() });
+var CapsuleServiceDetailSchema = CapsuleServiceSchema.extend({ manifest: AnyJson.optional(), health: HealthReportSchema.nullable().optional(), configs: z.array(ConfigItemSchema).optional(), actions: z.array(ActionDefinitionSchema).optional() });
+var CreateActionCommandRequestSchema = z.object({ payload: AnyJson.optional(), confirmation: z.boolean().optional() });
+var createActionCommandRequestSchema = CreateActionCommandRequestSchema;
+var CommandSchema = z.object({ id: z.string().startsWith("cmd_"), agentId: z.string().startsWith("agt_"), serviceId: z.string().startsWith("svc_"), type: z.enum(["ACTION_PREPARE", "ACTION_EXECUTE", "ACTION"]), actionName: z.string(), status: CommandStatusSchema, payload: AnyJson.optional(), createdByUserId: z.string().startsWith("usr_").nullable().optional(), createdAt: z.string(), startedAt: z.string().nullable().optional(), completedAt: z.string().nullable().optional(), expiresAt: z.string().nullable().optional() });
+var ReportCommandResultRequestSchema = z.object({ success: z.boolean(), message: z.string().optional(), data: AnyJson.optional(), error: AnyJson.optional(), startedAt: z.string().optional(), finishedAt: z.string().optional() });
+var reportCommandResultRequestSchema = ReportCommandResultRequestSchema;
+var CommandResultSchema = z.object({ id: z.string().startsWith("crs_"), commandId: z.string().startsWith("cmd_"), success: z.boolean(), message: z.string().nullable().optional(), data: AnyJson.optional(), error: AnyJson.optional(), reportedAt: z.string() });
+var CommandDetailSchema = CommandSchema.extend({ result: CommandResultSchema.nullable().optional() });
+var AuditEventSchema = z.object({ id: z.string().startsWith("aud_"), actorType: z.enum(AuditActorType), actorId: z.string().nullable().optional(), action: z.string(), targetType: z.string().nullable().optional(), targetId: z.string().nullable().optional(), result: z.enum(AuditResult), message: z.string().nullable().optional(), metadata: AnyJson.optional(), createdAt: z.string() });
+var DashboardSummarySchema = z.object({ agentCounts: z.record(z.number().int()), serviceCounts: z.record(z.number().int()), commandCounts: z.record(z.number().int()), recentCommands: z.array(CommandSchema).optional(), recentAuditEvents: z.array(AuditEventSchema).optional() });
+var SystemHealthSchema = z.object({ status: z.enum(["UP", "DEGRADED", "DOWN"]), timestamp: z.string(), version: z.string(), edition: z.literal("ce"), database: z.object({ status: z.enum(["UP", "DEGRADED", "DOWN"]), kind: z.enum(["sqlite", "postgres", "mysql"]).optional(), latencyMs: z.number().int().optional() }), uptimeSeconds: z.number().int().optional() });
+var SystemVersionSchema = z.object({ version: z.string(), edition: z.literal("ce"), commit: z.string().optional(), buildTime: z.string().optional() });
+var ListQueryBase = z.object({ page: z.coerce.number().int().min(1).default(1), pageSize: z.coerce.number().int().min(1).max(100).default(20), sort: z.string().optional() });
+var HttpError = class extends Error {
+  constructor(httpStatus, code, publicMessage, details) {
+    super(publicMessage);
+    this.httpStatus = httpStatus;
+    this.code = code;
+    this.publicMessage = publicMessage;
+    this.details = details;
+  }
+  httpStatus;
+  code;
+  publicMessage;
+  details;
+};
+function parseSort(value, allowed) {
+  if (!value) return [];
+  return value.split(",").filter(Boolean).map((raw) => {
+    const desc = raw.startsWith("-");
+    const field = desc ? raw.slice(1) : raw;
+    if (!allowed.includes(field)) throw new HttpError(422, "VALIDATION_FAILED", `Unknown sort field: ${field}`);
+    return { field, direction: desc ? "desc" : "asc" };
+  });
+}
+function paginate(items, page, pageSize, total) {
+  return { data: items, pagination: { page, pageSize, total } };
+}
+export {
+  ActionDefinitionInputSchema,
+  ActionDefinitionSchema,
+  AdminLoginRequestSchema,
+  AdminSessionSchema,
+  AgentHeartbeatRequestSchema,
+  AgentHeartbeatResponseSchema,
+  AgentSchema,
+  AgentStatus,
+  AgentStatusSchema,
+  AnyJson,
+  AuditActorType,
+  AuditEventSchema,
+  AuditResult,
+  CapsuleManifestSchema,
+  CapsuleServiceDetailSchema,
+  CapsuleServiceSchema,
+  CapsuleServiceStatus,
+  CapsuleServiceStatusSchema,
+  CommandDetailSchema,
+  CommandResultSchema,
+  CommandSchema,
+  CommandStatus,
+  CommandStatusSchema,
+  ConfigItemInputSchema,
+  ConfigItemSchema,
+  CreateActionCommandRequestSchema,
+  CreateRegistrationTokenRequestSchema,
+  CreateRegistrationTokenResponseSchema,
+  DangerLevel,
+  DangerLevelSchema,
+  DashboardSummarySchema,
+  ErrorCode,
+  HealthReportInputSchema,
+  HealthReportSchema,
+  HealthStatus,
+  HealthStatusSchema,
+  HttpError,
+  ListQueryBase,
+  RegisterAgentRequestSchema,
+  RegisterAgentResponseSchema,
+  RegistrationTokenSchema,
+  ReportCommandResultRequestSchema,
+  ReportedServiceSchema,
+  ServiceReportRequestSchema,
+  SystemHealthSchema,
+  SystemVersionSchema,
+  TokenStatus,
+  UserRole,
+  UserSchema,
+  actionDefinitionInputSchema,
+  adminLoginRequestSchema,
+  agentHeartbeatRequestSchema,
+  configItemInputSchema,
+  createActionCommandRequestSchema,
+  createRegistrationTokenRequestSchema,
+  createUserRequestSchema,
+  healthReportInputSchema,
+  idPrefixes,
+  newId,
+  paginate,
+  parseSort,
+  registerAgentRequestSchema,
+  reportCommandResultRequestSchema,
+  reportedServiceSchema,
+  resetUserPasswordRequestSchema,
+  serviceReportRequestSchema,
+  updateUserRequestSchema,
+  z
+};

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@xtrape/capsule-contracts-node",
+  "version": "0.1.0-public-review.0",
+  "description": "TypeScript contracts and Zod schemas for Xtrape Capsule and Opstage wire protocols.",
+  "keywords": [
+    "xtrape",
+    "capsule",
+    "opstage",
+    "contracts",
+    "zod",
+    "agent-sdk"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xtrape-com/xtrape-capsule-contracts-node.git"
+  },
+  "homepage": "https://github.com/xtrape-com/xtrape-capsule-contracts-node#readme",
+  "bugs": {
+    "url": "https://github.com/xtrape-com/xtrape-capsule-contracts-node/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "spec",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "prepack": "pnpm build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "tsc --noEmit"
+  },
+  "dependencies": {
+    "nanoid": "^5.0.9",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.9"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "license": "Apache-2.0"
+}

package/spec/.source

@@ -0,0 +1 @@
+xtrape-capsule-docs@local

package/spec/enums/audit-actions.json

@@ -0,0 +1,213 @@
+{
+  "$schema": "./audit-actions.schema.json",
+  "version": "0.1.0",
+  "comment": "Single source of truth for AuditEvent.action values used in CE v0.1. Action names are lowercase, dot-separated, and stable. New action names require a contract update.",
+  "namingRules": [
+    "lowercase, dot-separated",
+    "format: <subject>.<verb>[.<qualifier>]",
+    "subject is the dominant resource (agent, service, command, token, session, system)",
+    "verb is the past-tense or imperative observation (created, requested, completed, failed, revoked, ...)",
+    "qualifier is optional and disambiguates similar actions"
+  ],
+  "actions": [
+    {
+      "name": "session.login.succeeded",
+      "actorType": "USER",
+      "targetType": "User",
+      "summary": "Admin user successfully logged in."
+    },
+    {
+      "name": "session.login.failed",
+      "actorType": "USER",
+      "targetType": "User",
+      "summary": "Login attempt failed."
+    },
+    {
+      "name": "session.logout",
+      "actorType": "USER",
+      "targetType": "User",
+      "summary": "Admin user logged out."
+    },
+    {
+      "name": "session.csrf.refreshed",
+      "actorType": "USER",
+      "targetType": "User",
+      "summary": "Admin requested a new CSRF token."
+    },
+    {
+      "name": "registration_token.created",
+      "actorType": "USER",
+      "targetType": "RegistrationToken",
+      "summary": "Admin created a registration token."
+    },
+    {
+      "name": "registration_token.revoked",
+      "actorType": "USER",
+      "targetType": "RegistrationToken",
+      "summary": "Admin revoked a registration token."
+    },
+    {
+      "name": "registration_token.consumed",
+      "actorType": "AGENT",
+      "targetType": "RegistrationToken",
+      "summary": "An Agent consumed the registration token during register."
+    },
+    {
+      "name": "agent.registered",
+      "actorType": "AGENT",
+      "targetType": "Agent",
+      "summary": "Agent completed registration and received an AgentToken."
+    },
+    {
+      "name": "agent.heartbeat.received",
+      "actorType": "AGENT",
+      "targetType": "Agent",
+      "summary": "Agent heartbeat received (sampled, not every heartbeat).",
+      "sampled": true
+    },
+    {
+      "name": "agent.disabled",
+      "actorType": "USER",
+      "targetType": "Agent",
+      "summary": "Admin disabled an Agent."
+    },
+    {
+      "name": "agent.enabled",
+      "actorType": "USER",
+      "targetType": "Agent",
+      "summary": "Admin re-enabled an Agent."
+    },
+    {
+      "name": "agent.revoked",
+      "actorType": "USER",
+      "targetType": "Agent",
+      "summary": "Admin revoked an Agent token; the Agent must re-register."
+    },
+    {
+      "name": "agent_token.issued",
+      "actorType": "SYSTEM",
+      "targetType": "AgentToken",
+      "summary": "Backend issued an AgentToken in response to a successful registration."
+    },
+    {
+      "name": "agent_token.rejected",
+      "actorType": "AGENT",
+      "targetType": "AgentToken",
+      "summary": "Backend rejected an AgentToken (revoked/expired/invalid)."
+    },
+    {
+      "name": "service.reported",
+      "actorType": "AGENT",
+      "targetType": "CapsuleService",
+      "summary": "Agent reported (or updated) a Capsule Service manifest."
+    },
+    {
+      "name": "service.retired",
+      "actorType": "AGENT",
+      "targetType": "CapsuleService",
+      "summary": "Agent reported the service as retired."
+    },
+    {
+      "name": "service.action.requested",
+      "actorType": "USER",
+      "targetType": "CapsuleService",
+      "summary": "Admin requested an action on a Capsule Service; backend created a Command."
+    },
+    {
+      "name": "command.created",
+      "actorType": "USER",
+      "targetType": "Command",
+      "summary": "Backend persisted a new Command (paired with service.action.requested)."
+    },
+    {
+      "name": "command.dispatched",
+      "actorType": "AGENT",
+      "targetType": "Command",
+      "summary": "Agent polled and received the Command."
+    },
+    {
+      "name": "command.started",
+      "actorType": "AGENT",
+      "targetType": "Command",
+      "summary": "Agent reported startedAt."
+    },
+    {
+      "name": "command.completed",
+      "actorType": "AGENT",
+      "targetType": "Command",
+      "summary": "Agent reported successful CommandResult."
+    },
+    {
+      "name": "command.failed",
+      "actorType": "AGENT",
+      "targetType": "Command",
+      "summary": "Agent reported failure CommandResult."
+    },
+    {
+      "name": "system.agent.offline",
+      "actorType": "SYSTEM",
+      "targetType": "Workspace",
+      "summary": "agent-offline-sweep transitioned an Agent to OFFLINE."
+    },
+    {
+      "name": "system.service.stale",
+      "actorType": "SYSTEM",
+      "targetType": "Workspace",
+      "summary": "service-stale-sweep transitioned a service to STALE."
+    },
+    {
+      "name": "system.command.expired",
+      "actorType": "SYSTEM",
+      "targetType": "Workspace",
+      "summary": "command-ttl-sweep transitioned a Command to EXPIRED."
+    },
+    {
+      "name": "system.bootstrap.completed",
+      "actorType": "SYSTEM",
+      "targetType": "Workspace",
+      "summary": "First-run bootstrap created the default workspace and admin."
+    },
+    {
+      "name": "user.created",
+      "actorType": "USER",
+      "targetType": "User",
+      "summary": "Admin created a new user."
+    },
+    {
+      "name": "user.updated",
+      "actorType": "USER",
+      "targetType": "User",
+      "summary": "Admin updated a user's role or status."
+    },
+    {
+      "name": "user.password.reset",
+      "actorType": "USER",
+      "targetType": "User",
+      "summary": "Admin reset a user's password."
+    },
+    {
+      "name": "command.cancelled",
+      "actorType": "USER",
+      "targetType": "Command",
+      "summary": "Admin cancelled a pending or running Command."
+    },
+    {
+      "name": "maintenance.triggered",
+      "actorType": "USER",
+      "targetType": "Workspace",
+      "summary": "Admin manually triggered a maintenance run."
+    },
+    {
+      "name": "maintenance.run",
+      "actorType": "SYSTEM",
+      "targetType": "Workspace",
+      "summary": "Scheduled maintenance run completed."
+    },
+    {
+      "name": "backup.sqlite.created",
+      "actorType": "USER",
+      "targetType": "Backup",
+      "summary": "Admin created a SQLite backup."
+    }
+  ]
+}

package/spec/enums/id-prefixes.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "./id-prefixes.schema.json",
+  "version": "0.1.0",
+  "comment": "Single source of truth for typed-ID prefixes used by newId(prefix). Each ID is `<prefix>_<base32-or-ulid>`. Prefixes are stable; renaming a prefix is a breaking change.",
+  "format": {
+    "shape": "<prefix>_<random>",
+    "randomScheme": "ulid (Crockford base32, 26 chars) — see 08-decisions/0001 for rationale",
+    "separator": "_",
+    "casing": "lowercase prefix; uppercase ULID body",
+    "example": "agt_01HZX5TQYP2N9VRJ8WTRQVZ8K2"
+  },
+  "prefixes": [
+    { "prefix": "wks", "type": "Workspace",         "comment": "Default workspace ID; CE v0.1 ships exactly one." },
+    { "prefix": "usr", "type": "AdminUser",         "comment": "Local admin user." },
+    { "prefix": "ses", "type": "Session",           "comment": "Admin session record (server-side)." },
+    { "prefix": "agt", "type": "Agent",             "comment": "Agent identity." },
+    { "prefix": "tok", "type": "RegistrationToken", "comment": "Registration token (the row; the raw token value is generated separately via newToken('reg'))." },
+    { "prefix": "atk", "type": "AgentToken",        "comment": "Agent token (the row; raw token via newToken('agt'))." },
+    { "prefix": "svc", "type": "CapsuleService",    "comment": "Capsule Service registered by an Agent." },
+    { "prefix": "act", "type": "ActionDefinition",  "comment": "Action declared on a service manifest." },
+    { "prefix": "cmd", "type": "Command",           "comment": "Command for an Agent to execute." },
+    { "prefix": "res", "type": "CommandResult",     "comment": "Optional separate row for command results; CE v0.1 may inline into Command." },
+    { "prefix": "evt", "type": "AuditEvent",        "comment": "Audit event row." },
+    { "prefix": "hlt", "type": "HealthReport",      "comment": "Health report snapshot (latest persisted per service)." },
+    { "prefix": "cfg", "type": "ConfigItem",        "comment": "Visible config item attached to a service manifest." },
+    { "prefix": "set", "type": "SystemSetting",     "comment": "Bootstrap and runtime setting row." }
+  ],
+  "tokenPrefixes": [
+    { "tokenKind": "RegistrationToken.rawValue", "prefix": "opstage_reg", "comment": "Wire format for raw registration token; backend stores only the SHA-256 hash." },
+    { "tokenKind": "AgentToken.rawValue",        "prefix": "opstage_agt", "comment": "Wire format for raw Agent token; backend stores only the SHA-256 hash." }
+  ]
+}

package/spec/enums/status-enums.json

@@ -0,0 +1,128 @@
+{
+  "$schema": "./status-enums.schema.json",
+  "version": "0.1.0",
+  "comment": "Single source of truth for all status enumerations used in the CE v0.1 wire format. Each binding repo (xtrape-capsule-contracts-node, etc.) generates language-native enum types from this file.",
+  "enums": {
+    "AgentStatus": {
+      "description": "Lifecycle state of an Agent. PENDING = registered but no heartbeat yet; ONLINE = heartbeating; OFFLINE = missed offline threshold; DISABLED = paused by admin; REVOKED = token revoked.",
+      "values": [
+        { "value": "PENDING",  "meaning": "Agent registered but has not yet reported a heartbeat." },
+        { "value": "ONLINE",   "meaning": "Agent has reported a heartbeat within OPSTAGE_AGENT_OFFLINE_THRESHOLD_SECONDS." },
+        { "value": "OFFLINE",  "meaning": "Agent has not reported within the offline threshold; sweepers transitioned PENDING/ONLINE → OFFLINE." },
+        { "value": "DISABLED", "meaning": "Admin paused the Agent; the Agent token is rejected with AGENT_DISABLED." },
+        { "value": "REVOKED",  "meaning": "Admin revoked the Agent token; the Agent must re-register; token is rejected with AGENT_REVOKED." }
+      ],
+      "transitions": [
+        { "from": "PENDING",  "to": ["ONLINE", "OFFLINE", "DISABLED", "REVOKED"] },
+        { "from": "ONLINE",   "to": ["OFFLINE", "DISABLED", "REVOKED"] },
+        { "from": "OFFLINE",  "to": ["ONLINE", "DISABLED", "REVOKED"] },
+        { "from": "DISABLED", "to": ["ONLINE", "REVOKED"] },
+        { "from": "REVOKED",  "to": [] }
+      ]
+    },
+    "CapsuleServiceStatus": {
+      "description": "Effective lifecycle state of a Capsule Service. Persisted by the backend as derived from agent.status, lastReportedAt, and admin actions.",
+      "values": [
+        { "value": "PENDING",  "meaning": "Service was reported by an Agent but has not yet sent a health report." },
+        { "value": "UP",       "meaning": "Service has reported a healthy status within freshness threshold." },
+        { "value": "DEGRADED", "meaning": "Service reports healthStatus=DEGRADED OR last health is stale but Agent online." },
+        { "value": "DOWN",     "meaning": "Service reports healthStatus=DOWN." },
+        { "value": "STALE",    "meaning": "Last service report is older than OPSTAGE_HEALTH_STALE_THRESHOLD_SECONDS." },
+        { "value": "OFFLINE",  "meaning": "Owning Agent is OFFLINE/DISABLED/REVOKED — derived effective state." },
+        { "value": "RETIRED",  "meaning": "Service was explicitly retired by Agent (no longer reported)." }
+      ],
+      "derivationOrder": [
+        "If agent.status in (DISABLED, REVOKED) → OFFLINE",
+        "If agent.status == OFFLINE → OFFLINE",
+        "If service was retired → RETIRED",
+        "If lastReportedAt older than healthStaleThreshold → STALE",
+        "Else use last reported HealthStatus mapping (UP/DEGRADED/DOWN)"
+      ]
+    },
+    "HealthStatus": {
+      "description": "Status reported by a service via Agent health endpoint. Distinct from CapsuleServiceStatus (which is the effective derived state).",
+      "values": [
+        { "value": "UP",       "meaning": "Service is healthy." },
+        { "value": "DEGRADED", "meaning": "Service is reachable but reports a degraded condition (e.g., slow dependency)." },
+        { "value": "DOWN",     "meaning": "Service self-reports unhealthy." },
+        { "value": "UNKNOWN",  "meaning": "Service has no health probe yet (initial state)." }
+      ]
+    },
+    "CommandStatus": {
+      "description": "Lifecycle state of a Command. Strict transitions enforced by backend.",
+      "values": [
+        { "value": "PENDING",   "meaning": "Command created; not yet polled by Agent." },
+        { "value": "DISPATCHED","meaning": "Command was returned to the Agent in a poll response." },
+        { "value": "RUNNING",   "meaning": "Agent reported startedAt." },
+        { "value": "SUCCEEDED", "meaning": "Terminal: Agent reported successful CommandResult." },
+        { "value": "FAILED",    "meaning": "Terminal: Agent reported failure CommandResult." },
+        { "value": "EXPIRED",   "meaning": "Terminal: Command past expiresAt before completion." },
+        { "value": "CANCELED",  "meaning": "Terminal: admin canceled the Command (reserved for EE; CE v0.1 may not expose UI but enum is reserved)." }
+      ],
+      "terminal": ["SUCCEEDED", "FAILED", "EXPIRED", "CANCELED"],
+      "transitions": [
+        { "from": "PENDING",    "to": ["DISPATCHED", "EXPIRED", "CANCELED"] },
+        { "from": "DISPATCHED", "to": ["RUNNING", "EXPIRED", "CANCELED"] },
+        { "from": "RUNNING",    "to": ["SUCCEEDED", "FAILED", "EXPIRED", "CANCELED"] },
+        { "from": "SUCCEEDED",  "to": [] },
+        { "from": "FAILED",     "to": [] },
+        { "from": "EXPIRED",    "to": [] },
+        { "from": "CANCELED",   "to": [] }
+      ]
+    },
+    "TokenStatus": {
+      "description": "Lifecycle state of a RegistrationToken or AgentToken.",
+      "values": [
+        { "value": "ACTIVE",  "meaning": "Token is valid and usable." },
+        { "value": "USED",    "meaning": "Registration token has been consumed (one-shot)." },
+        { "value": "REVOKED", "meaning": "Admin revoked the token." },
+        { "value": "EXPIRED", "meaning": "Token past expiresAt." }
+      ]
+    },
+    "AuditResult": {
+      "description": "Result of an audited operation.",
+      "values": [
+        { "value": "SUCCESS", "meaning": "Operation succeeded." },
+        { "value": "FAILURE", "meaning": "Operation failed; metadata.errorCode SHOULD be populated." },
+        { "value": "DENIED",  "meaning": "Operation was rejected by authorization policy." }
+      ]
+    },
+    "ActorType": {
+      "description": "Type of actor that initiated an audited operation.",
+      "values": [
+        { "value": "USER",   "meaning": "An admin user (browser session)." },
+        { "value": "AGENT",  "meaning": "An Agent (bearer token)." },
+        { "value": "SYSTEM", "meaning": "A background process (sweeper, bootstrap)." }
+      ]
+    },
+    "TargetType": {
+      "description": "Type of resource targeted by an audited operation.",
+      "values": [
+        { "value": "AGENT" },
+        { "value": "CAPSULE_SERVICE" },
+        { "value": "COMMAND" },
+        { "value": "REGISTRATION_TOKEN" },
+        { "value": "AGENT_TOKEN" },
+        { "value": "ADMIN_USER" },
+        { "value": "WORKSPACE" },
+        { "value": "SYSTEM_SETTING" }
+      ]
+    },
+    "DangerLevel": {
+      "description": "Self-declared danger level of an ActionDefinition. UI uses this to choose confirmation UX.",
+      "values": [
+        { "value": "LOW",    "meaning": "Idempotent and safe (e.g. echo, runHealthCheck)." },
+        { "value": "MEDIUM", "meaning": "May change service state but reversible." },
+        { "value": "HIGH",   "meaning": "Destructive or hard to reverse; UI MUST require explicit confirmation." }
+      ]
+    },
+    "AgentMode": {
+      "description": "Deployment mode of an Agent.",
+      "values": [
+        { "value": "embedded", "meaning": "Agent runs in-process inside a Capsule Service (CE v0.1 baseline)." },
+        { "value": "sidecar",  "meaning": "Agent runs as a separate process beside services. Reserved for EE.", "reservedFor": "EE" },
+        { "value": "external", "meaning": "Agent runs as a separate fleet manager. Reserved for EE/Cloud.", "reservedFor": "EE" }
+      ]
+    }
+  }
+}