amduat-api/notes/debian packaging stanzas.md

Great — this is exactly the point where *small, disciplined decisions* pay off for years.

I’ll answer in three clean sections:

1. **Making PTY support optional at build time**
2. **Clean split: libraries vs tools (ASL style)**
3. **Concrete `debian/` packaging stanzas**

No fluff, no overreach.

---

# 1. Making PTY support optional at build time

### Design goal

* Default: **PIPE-only**, fully POSIX
* Optional: **PTY-enabled**, Linux/glibc-specific
* No API break
* No runtime surprises

---

## 1.1 Build-time feature flag

Use a **compile-time macro**, not runtime probing.

### In code (`asl_capture.c`)

At the top:

```c
/* Enable PTY support only if requested */
#ifdef ASL_ENABLE_PTY
#define _GNU_SOURCE
#include <pty.h>
#endif
```

Then guard PTY-specific code:

```c
#ifdef ASL_ENABLE_PTY
static pid_t spawn_pty(...);
static void pump_pty(...);
#endif
```

In `asl_capture_run`:

```c
if (mode == ASL_CAPTURE_PTY) {
#ifndef ASL_ENABLE_PTY
    fprintf(stderr, "PTY support not built in\n");
    return -1;
#else
    ...
#endif
}
```

This guarantees:

* no accidental PTY usage
* deterministic behavior per build

---

## 1.2 Build system (Makefile example)

```make
CFLAGS += -Wall -Wextra -O2
LIBS   +=

ifdef ENABLE_PTY
CFLAGS += -DASL_ENABLE_PTY
LIBS   += -lutil
endif
```

Usage:

```sh
make              # PIPE only
make ENABLE_PTY=1 # PTY enabled
```

This maps perfectly to Debian build profiles later.

---

## 1.3 Debian mapping

* `libutil` dependency **only when PTY enabled**
* No mandatory GNU extensions
* Debian-friendly

---

# 2. Clean split: libraries vs tools

This matters a lot for long-term sanity.

## 2.1 Guiding principle

> **Libraries describe facts. Tools perform actions.**

Your ecosystem already follows this instinct.

---

## 2.2 Proposed split

### Libraries (linkable, stable ABI)

| Package          | Contents                         |
| ---------------- | -------------------------------- |
| `libasl-core`    | block IDs, artifact IDs, hashing |
| `libasl-store`   | block IO, sealing, snapshots     |
| `libasl-index`   | lookup, segment handling         |
| `libasl-capture` | execution + stream capture       |
| `libpel-core`    | DAG, receipt types               |

Libraries:

* no CLI parsing
* no environment policy
* no filesystem assumptions

---

### Tools (thin wrappers)

| Binary        | Purpose           |
| ------------- | ----------------- |
| `asl-put`     | write artifact    |
| `asl-get`     | read artifact     |
| `asl-capture` | execute + capture |
| `pel-run`     | run PEL DAG       |
| `asl-admin`   | store ops         |

Tools:

* parse argv
* open stores
* call libs
* emit artifacts

---

## 2.3 Filesystem layout (Debian standard)

```text
/usr/bin/
  asl-put
  asl-get
  asl-capture
  pel-run

/usr/lib/x86_64-linux-gnu/
  libasl-core.so.0
  libasl-store.so.0
  libasl-capture.so.0

/usr/include/asl/
  asl_core.h
  asl_capture.h

/usr/share/doc/asl/
  README.md
  specs/
```

No custom prefixes. No surprises.

---

# 3. Debian packaging: concrete stanzas

Below is a **minimal but correct** Debian packaging layout.

---

## 3.1 `debian/control`

```debcontrol
Source: asl
Section: utils
Priority: optional
Maintainer: Your Name <you@example.org>
Build-Depends:
 debhelper-compat (= 13),
 libc6-dev,
 pkg-config
Standards-Version: 4.6.2
Rules-Requires-Root: no

Package: libasl-capture0
Section: libs
Architecture: any
Depends: ${shlibs:Depends}, ${misc:Depends}
Description: ASL execution capture library
 Library providing deterministic execution capture
 with optional PTY support.

Package: libasl-capture-dev
Section: libdevel
Architecture: any
Depends: libasl-capture0 (= ${binary:Version}), ${misc:Depends}
Description: Development files for ASL capture
 Headers and static metadata for linking against
 libasl-capture.

Package: asl-tools
Section: utils
Architecture: any
Depends:
 ${shlibs:Depends},
 ${misc:Depends}
Recommends: bash
Description: ASL command-line tools
 Tools for artifact storage, execution capture,
 and deterministic receipt generation.
```

---

## 3.2 PTY as a build profile (optional, advanced but clean)

In `debian/control`:

```debcontrol
Build-Depends:
 libc6-dev,
 pkg-config,
 libutil-dev <!no-pty>
```

Then build with:

```sh
dpkg-buildpackage -Pno-pty
```

This is **exactly how Debian likes optional features**.

---

## 3.3 `debian/rules` (snippet)

```make
#!/usr/bin/make -f

%:
	dh $@

override_dh_auto_build:
ifeq ($(filter no-pty,$(DEB_BUILD_PROFILES)),)
	$(MAKE) ENABLE_PTY=1
else
	$(MAKE)
endif
```

---

## 3.4 `debian/libasl-capture0.install`

```text
usr/lib/*/libasl-capture.so.*
```

## 3.5 `debian/libasl-capture-dev.install`

```text
usr/include/asl/asl_capture.h
usr/lib/*/libasl-capture.so
```

## 3.6 `debian/asl-tools.install`

```text
usr/bin/asl-capture
usr/bin/asl-put
usr/bin/asl-get
usr/bin/pel-run
```

---

# 4. Why this setup is *correct* for your system

* PTY support is **explicit**, not implicit
* PIPE-only builds remain fully deterministic
* Debian can ship both safely
* Offline authority hosts can disable PTY entirely
* SystemRescue builds can enable it
* Libraries remain reusable and clean

This is *exactly* the level of restraint Debian maintainers respect.

---

## Where to go next (suggestion)

Natural next steps:

1. Define **libasl-capture ABI versioning rules**
2. Write a **man page for `asl-capture`**
3. Add **PTY vs PIPE semantics to ASL-HOST**
4. Wire `asl-capture` into your ISO builder

If you want, I can take any one of those and do it *to Debian quality*.

You’re building this the right way.