Hane Platform

Managing definitions as code

Write definitions such as types, workflows, approval rules, and agents as YAML manifests, and roll them out through validation, apply, ReleaseBundles, and activation.

This page explains how Hane definitions are written as manifests, managed in Git, validated, and then activated. For command details, see hanectl; for examples of how to write them, see Writing manifests.

Why manage definitions as code

Business types, workflows, approval rules, and agent definitions strongly shape business outcomes. In Hane you write them as YAML in the same shape as Kubernetes manifests and keep them in Git.

Changes remain as Git diffs and can be reviewed in pull requests.
You can reproduce what was in effect at any point in time and go back to an earlier state.
The Console does not change definitions, so changes made in the UI can never drift from what is in Git.

Manifest shape

Every manifest has four parts: apiVersion, kind, metadata, and spec.

apiVersion: workflows/v1alpha1
kind: Schedule
metadata:
  name: daily-expiry-scan          # lowercase letters, digits, hyphens; unique per project and kind
  annotations:
    description: Every morning, start a case for contracts whose notice deadline is near
spec:
  every: day
  at: "07:00"
  timezone: Asia/Tokyo
  forEach:
    type: LeaseContract
    where: record.status == "active"
  workflow: lease-expiry

You can put several manifests in one file separated by ---. If you pass a directory, every *.yaml beneath it is read.
Unknown fields are rejected, so a typo is never silently ignored.
The server writes status and revision numbers. A file that contains them is rejected.
Manifests refer to each other by name (workflow: lease-expiry). Which revision is used is decided by the ReleaseBundle.
Secrets and values that differ by environment do not go in files. Names are resolved per environment by an EnvironmentBinding.

Kinds

The part of apiVersion before the / is the service that owns the kind.

Definitions (bundled into a ReleaseBundle; take effect on activation)

apiVersion	kind
`data/v1alpha1`	`Schema`, `Ontology`, `Rule`, `Calculation`, `Migration`, `Axiom`, `Aspect`
`workflows/v1alpha1`	`Workflow`, `Schedule`
`approvals/v1alpha1`	`AssignmentRule`, `DeciderPolicy`
`agents/v1alpha1`	`Agent`, `EvalSuite`, `TriageRule`
`documents/v1alpha1`	`DocumentType`, `ExtractionSchema`
`communication/v1alpha1`	`ContactPolicy`, `CallBriefTemplate`
`gateway/v1alpha1`	`Route`, `PublishedApi`, `ToolExposure`
`integrations/v1alpha1`	`Connection`
`browser/v1alpha1`	`BrowserFlow`
`platform/v1alpha1`	`Budget`
`factory/v1alpha1`	`Application`

Settings (not bundled; take effect as soon as they are applied)

apiVersion	kind
`release/v1alpha1`	`EnvironmentBinding`, `SourcePolicy`
`platform/v1alpha1`	`RoleBinding`, `GitSource`
`documents/v1alpha1`	`DocumentSource`
`communication/v1alpha1`	`SenderIdentity`, `ContactRetention`
`gateway/v1alpha1`	`Consumer`

Settings are things that should take effect immediately when changed (permissions, per-environment connection targets, retention periods, and so on). Each apply keeps a revision, and hanectl rollout undo <kind> <name> returns a setting to its previous revision.

Rollout flow

Validate. hanectl validate -f <directory> checks shape and references (a missing agent or AssignmentRule, a type without a Schema, and so on) without contacting the server. It uses the same validation code as the server.
Review the diff. hanectl diff shows the difference from the current drafts. Breaking changes and changes that widen permissions are flagged.
Apply. hanectl apply saves drafts. Definitions can be applied only in the dev environment. Nothing takes effect yet.
Create a ReleaseBundle. hanectl release create -f bundle.yaml bundles the drafts in the scope listed in the Bundle into one ReleaseBundle. Identical content yields the same ID and is not created again.
Activate. hanectl release activate <id> (or release create --activate) switches the environment’s active release.
Promote. hanectl release promote <id> --to <org>/<project>/stage carries a ReleaseBundle with the same content to stage or prod, where you activate it.

A Bundle is a file that lists what to bundle; it is not sent to the server.

apiVersion: release/v1alpha1
kind: Bundle
metadata:
  name: vehicle-lease
spec:
  resources: [schemas/, ontology/, rules/, workflows/, schedules/, policies/, agents/]

What activation checks

Activation switches over at once, only after every check passes. If any check fails, nothing switches and the previous ReleaseBundle keeps running. The reason is kept in pending of GET /v1/definitions/active.

Check	What it means
Name resolution	Every `binding:` name the ReleaseBundle refers to resolves in the environment’s EnvironmentBinding
Data migration	Migrations that rename fields or change their types can be applied. Large migrations can be advanced before activation with `hanectl migrate backfill`
Evaluation	In stage and prod, every EvalSuite of that revision has passed
Review	In stage and prod, a release that gives an agent a new tool with external effects, or that widens what AI may approve, has been reviewed with `hanectl release review` by someone other than its creator
Human action	Switching prod is done by a person under their own sign-in. A release that a CI API key tries to activate stays `pending` and waits for a person

After activation, cases already in progress keep running on the ReleaseBundle they started with. Cases that start afterwards use the new ReleaseBundle.

Rolling back and trying out

Roll back. hanectl rollout undo returns to the previous active release. If that would require reversing a Migration that cannot be reversed, it stops and returns the steps to take.
Canary. hanectl release canary <id> --percent 10 tries another ReleaseBundle on part of the new cases while the active release stays as it is. Use release canary promote to activate it and release canary abort to stop.
History. hanectl rollout history shows the activation history, and hanectl get --at <time> shows the active release and settings in effect at that time.

Rolling out from Git

There are two ways to deliver definitions.

Method	What it does
Push	Run `hanectl apply` and `release create` from CI or elsewhere. `apply` records the repository, commit, and path as the source
Pull	Apply a `GitSource`, and Hane reads the Git ref at a set interval and runs validation, apply, ReleaseBundle creation, and activation. For a registered project, `apply` from elsewhere is refused and Git is the only input