Skip to Content
HephaesCurrent State

Current State

Snapshot

As of 2026-03-28, hephaes now owns the full local conversion authoring workflow as a standalone package and CLI.

That means the package can:

  • register and index source assets
  • inspect a source asset
  • create and revise draft conversion specs
  • preview draft revisions
  • confirm drafts
  • save confirmed drafts as reusable configs
  • run conversions from those saved configs
  • persist draft, config, run, job, and output history in the workspace

What Is Implemented Today

Package Layers

The current package is split into three useful layers:

  • hephaes.conversion: stateless inspect, draft, preview, and spec helpers
  • hephaes.workspace.Workspace: durable workflow orchestration and state transitions
  • hephaes CLI: thin adapters over Workspace, including both scriptable commands and the interactive wizard

Durable Workflow Support

Workspace now includes package-owned methods for:

  • inspect_asset(...)
  • create_conversion_draft(...)
  • update_conversion_draft(...)
  • preview_conversion_draft(...)
  • confirm_conversion_draft(...)
  • discard_conversion_draft(...)
  • save_conversion_config_from_draft(...)
  • run_conversion(...)

Drafts are first-class durable records with:

  • draft heads
  • immutable draft revisions
  • current revision tracking
  • confirmed revision tracking
  • saved-config linkage
  • preserved history after discard or promotion

CLI Coverage

The published CLI now includes:

  • hephaes init
  • hephaes add
  • hephaes index
  • hephaes ls assets
  • hephaes inspect
  • hephaes drafts ...
  • hephaes drafts wizard ...
  • hephaes configs ...
  • hephaes convert
  • hephaes jobs ...
  • hephaes runs ...
  • hephaes outputs ...

The authoring workflow is available through either:

  • the interactive wizard for humans
  • the scriptable drafts subcommands for automation and tests

Workflow Status By Step

Source Asset Selection

Status: implemented

Assets can be registered, indexed, listed, and resolved by id or path inside the workspace. The workspace stores the canonical source file path directly and does not copy raw logs into .hephaes.

Inspect

Status: implemented

The package supports both:

  • standalone inspection through hephaes inspect
  • package-owned inspection through Workspace.inspect_asset(...)

Draft Creation

Status: implemented

Draft creation now runs as a package-owned flow that inspects the asset, builds the initial spec, creates the draft head, and persists the first immutable revision.

Draft Revision

Status: implemented

Drafts can accumulate immutable revisions, with the draft head tracking the current revision separately from the confirmed revision.

Preview

Status: implemented

Preview requests and preview results are persisted on draft revisions, and confirmation requires a successful preview of the target revision.

Confirm

Status: implemented

Draft confirmation is now a durable workflow state, not just a frontend or backend convention.

Save Config

Status: implemented

Confirmed drafts can be promoted into reusable saved configs through Workspace.save_conversion_config_from_draft(...) or hephaes drafts save-config ....

Convert

Status: implemented

Conversions can run from either a saved config or an explicit spec document, and the workspace records durable jobs, runs, and output artifacts.

Current Strengths

  • the package can be used independently of the backend for the complete authoring workflow
  • the CLI supports both a human-friendly wizard and automation-friendly commands
  • workflow rules now live in package code instead of adapter code
  • the package remains reusable by a later backend because the CLI is built on top of Workspace, not the other way around

Current Rough Edges

  • hephaes inspect still calls the stateless inspection helper directly instead of routing through Workspace.inspect_asset(...)
  • the wizard supports revision updates through drafts update --spec-document ..., not an inline editor
  • saved-config lineage is currently surfaced through config metadata rather than dedicated top-level config fields
  • direct configs save still exists for importing spec documents, even though draft-first authoring is now the recommended path

None of those gaps block the package-owned authoring workflow, but they are still worth tracking as polish work.

Validation And Quality

The package test suite lives under hephaes/tests.

Current coverage includes:

  • workspace schema and migration behavior
  • draft persistence and lifecycle state transitions
  • saved-config promotion and lineage behavior
  • CLI command coverage for drafts ...
  • interactive wizard behavior
  • conversion execution from promoted configs
Last updated on
How To UseOverview