reference_surface.hum

module examples.reference_surface

app reference_surface {
  why:
    show every current Milestone 0 top-level form in one checked file

  starts with:
    start_reference

  task start_reference -> Unit {
    why:
      keep the reference app structurally executable without external effects

    does:
      return
  }
}

type WorkItem {
  id: Text
  title: Text
  done: Bool
}

type WorkError {
  code: Text
}

store work_items: list WorkItem {
  why:
    keep the user's work items available between tasks
}

task remember_work_item(title: Text) -> Result WorkItem, WorkError {
  why:
    let a user capture work without losing the reason it matters
    # comments inside sections are preserved as section facts

  targets:
    triple: wasm32-wasi-preview1
    requires: os.clock
    requires: os.filesystem
    denies: os.network

  uses:
    clock

  changes:
    work_items

  needs:
    title is not empty

  ensures:
    new work item is saved
    new work item is not done

  protects:
    user work history

  trusts:
    local profile storage

  fails when:
    title is empty

  watch for:
    title may contain only spaces

  cost:
    time: O(1)
    space: O(1)
    check: warn

  allocates:
    one work item

  avoids:
    saving empty work items

  tradeoffs:
    local persistence is enough for the reference surface

  optimizes:
    clear review facts over clever implementation

  tests:
    remember_work_item rejects empty title

  does:
    if title is empty {
      fail WorkError.empty_title
    }

    let item = WorkItem {
      id: clock.now_text
      title: title
      done: false
    }

    save item in work_items
    return item
}

test remember_work_item rejects empty title regression {
  why:
    prove the reference entry records its visible failure mode

  uses:
    remember_work_item

  needs:
    empty title input is available

  regression:
    empty titles used to be saved as blank work items

  covers:
    remember_work_item needs title is not empty
    remember_work_item watch for title may contain only spaces
    remember_work_item tests remember_work_item rejects empty title

  avoids:
    depending on real storage or network behavior

  cost:
    time: O(1)
    space: O(1)
    check: warn

  does:
    expect remember_work_item("") fails with WorkError.empty_title
}

test remember_work_item saves valid title unit {
  why:
    prove the reference entry records its success promises

  uses:
    remember_work_item

  needs:
    non-empty title input is available

  covers:
    remember_work_item ensures new work item is saved
    remember_work_item ensures new work item is not done

  avoids:
    depending on real storage or network behavior

  cost:
    time: O(1)
    space: O(1)
    check: warn

  does:
    expect remember_work_item("ship Hum docs") returns WorkItem
}

test remember_work_item records security evidence unit {
  why:
    prove the reference entry records security and trust evidence links

  uses:
    remember_work_item

  covers:
    remember_work_item protects user work history
    remember_work_item trusts local profile storage

  avoids:
    depending on real storage or network behavior

  cost:
    time: O(1)
    space: O(1)
    check: warn

  does:
    expect evidence links are present in graph output
}