# TIES Newcomer Onboarding, Pseudocode & SOP Eval Guide (`S0 → S4`)

This guide is designed so a newcomer can inspect any catalog entry, compare **Exemplars vs. Non-Exemplars**, run executable **Pseudocode**, and verify **SOP Lambdas ($\lambda_{\text{SOP}}$)** via live `POST https://tiesapi.com/sop/eval` and `/api/ties/sop-nonce-chain/` without guessing.

---

## 1. System Map & Singleton Sandbox Chain (`2026-11-14`)

| Step | Sandbox | Live Route | Responsibility |
|---|---|---|---|
| **S0** | `20261114/T155522Z` | `/` (`/hub/`) | FastAPI hub & Django Central Index |
| **S1** | `20261114/T231500Z` | `/upload` | Browser `getUserMedia` + `MediaRecorder` A/V capture + out-of-band companion DB (`media_untouched=True`) |
| **S2** | `20261114/T231600Z` | `/manuscript/workbench` | Non-LLM APA 7th PDF scan, side-by-side trimming/heading check, `\n\n` sentences & `\n\n\n` paragraphs, Ghostwriter outline, & ML `0.97` competency practice |
| **S3** | `20261114/T231700Z` | `/ops` + bottom bar | Event-sourced `ART_DEPARTMENT_TODO` (98) + `ANALYST_TODO` (19), Calendar `.ics`, Quick SOPs, & Append-Only Syslog with nested `has_soft_delete=1` clarifications & KMMO |
| **S4** | `20261114/T233600Z` | `/catalog`, `/sop/eval` | Catalog `SOP-005..007`, Olog DOT/300-DPI PNG/SVG diagrams, session & activity logs, exemplars/non-exemplars, and live `/sop/eval` |

---

## 2. Executable Pseudocode for Every Newcomer Skill

### `SOP-005`: Browser A/V Capture + Out-of-Band Companion (`lambda_sop_av_companion`)
```python
def lambda_sop_av_companion(media_blob_bytes: bytes, mime_type: str, companion: dict, party_id: str) -> dict:
    # 1. Compute content hash BEFORE storage; media bytes remain strictly immutable
    sha256_digest = sha256_hex(media_blob_bytes)
    s3_key = upload_raw_media_to_s3(media_blob_bytes, mime_type)

    # 2. Store companion fields ONLY out-of-band in how.db tables (never remux/edit media bytes)
    comp = normalize_companion(companion)  # {title, speaker, context, tags[], notes, media_untouched: True}
    concrete_id = insert_concrete(path=s3_key, title=comp["title"], notes=comp["notes"], attachment_hash=sha256_digest)
    insert_metadata(concrete_id=concrete_id, Artist=comp["speaker"], Description=comp["context"], Comment=comp["notes"])
    merged_id = insert_merged_records(source_id=concrete_id, description=comp["notes"])
    ann_id = persist_companion_annotation(source_table="merged_records", source_id=merged_id, companion=comp)

    assert sha256_hex(media_blob_bytes) == sha256_digest
    return {"concrete_id": concrete_id, "annotation_id": ann_id, "media_untouched": True}
```
- **Exemplar:** Capturing a browser WebM stream with companion `{title, speaker, context, tags, notes}`, writing companion to `ANNOTATION` + `metadata` + `concrete.notes` with `media_untouched=True` and raw SHA-256 identical.
- **Non-Exemplar:** Re-encoding audio/video to burn subtitle/metadata overlays into the media bytes, or dropping `source_table='merged_records'` / `concrete_id` linkage.

### `SOP-006`: APA 7th PDF Validation, `\n\n` / `\n\n\n` Format & ML Competency (`lambda_sop_pdf_workbench_competency`)
```python
def lambda_sop_pdf_workbench_competency(source_pdf_or_txt, trainee_validated_md: str, competency_article: str = "Elo_2008") -> dict:
    # 1. Multi-pass non-LLM scan (mandatory LLM step formally skipped)
    scan = scan_pdf_structure(source_pdf_or_txt, run_ocr=True)
    # Inspect scan["trimmed_lines"], scan["figures"], scan["tables"], scan["draft_markdown"]

    # 2. Human confirms headings (# H1, ## H2, 0.1 Citation, 0.2 Abstract, ## References) side-by-side
    formatted = format_sentence_paragraph_text(
        validated_markdown=trainee_validated_md,
        references=scan["references"],
        figures=scan["figures"],
        tables=scan["tables"],
    )
    # Invariant: "\n\n" between sentences; "\n\n\n" between paragraphs/sections; Ghostwriter nodes start collapsed=True

    # 3. Score against Gold Ground Truth & Adopted ML Pipeline (gemma-4-31b + v2 prompt, holdout F1 = 0.97)
    score = evaluate_competency_submission(article_name=competency_article, submitted_markdown=trainee_validated_md)
    return {"formatted": formatted, "competency_score": score}
```
- **Exemplar:** Validating headings (`0.1 Citation`, `0.2 Abstract`, `# 1. Introduction`, `## References`), trimming running page numbers/JSTOR headers, separating sentences by `\n\n` and paragraphs by `\n\n\n`, and scoring `Elo_2008` / `Paletz_2009` vs `0.97` ML benchmark.
- **Non-Exemplar:** Requiring an LLM call before showing text to the human, merging paragraphs with single newlines `\n`, breaking sentences inside `et al.` / `Dr.` / `Fig.`, or omitting APA references.

### `SOP-007`: Event-Sourced TODO, Calendar Bridge & Append-Only Nested Soft-Delete Syslog (`lambda_sop_ops_syslog_route`)
```python
def lambda_sop_ops_syslog_route(db, body: str, entry_kind: str = "log", clarify_target_id: int | None = None, route_to_todo: bool = False):
    if clarify_target_id is not None:
        # Never UPDATE body or SQL DELETE; append clarifying entry & nest soft-deleted parent underneath
        clar = clarify_syslog_entry(db, target_id=clarify_target_id, new_body=body, entry_kind="clarification")
        entry_id = clar["id"]
    else:
        # Supports 'log', 'kmmo' (auto-populates 4-slot kmmo_k), or 'question'
        entry_id = append_syslog_entry(db, body=body, entry_kind=entry_kind)["id"]

    if route_to_todo:
        # Writes to OPS_TODO_ITEM + OPS_TODO_SNAPSHOT + OPS_TODO_EVENT (zero broken pipe)
        return route_syslog_to_todo(db, entry_id=entry_id, track="operational", priority=2, scheduled_date="2026-11-14")
    return get_syslog_entry(db, entry_id)
```
- **Exemplar:** Inserting an `OPS_SYSLOG_ENTRY`, clarifying it via `clarify_syslog_entry()` so the superseded row keeps `has_soft_delete = 1` nested under the new entry (`parent_entry_id = clar.id`), and projecting TODO mutations across `OPS_TODO_ITEM` / `OPS_TODO_SNAPSHOT` / `OPS_TODO_EVENT`.
- **Non-Exemplar:** Executing `DELETE FROM OPS_SYSLOG_ENTRY`, overwriting `body` in place on edit, or executing `INSERT INTO ART_DEPARTMENT_TODO (description, ...)` on the thin event-sourced parent table.

---

## 3. How a Newcomer Evaluates a Lambda SOP Against Live `/sop/eval`

1. Fetch challenge & registered SOP exemplars: `GET https://tiesapi.com/sop/eval?session_id=newcomer-1`
2. Inspect any Catalog `SOP_ENTRY` (e.g. `sop-av-capture-companion`, `sop-pdf-apa-workbench-competency`, `sop-ops-event-todo-syslog-kmmo`, `sop-level1-holder-institution`) via `GET https://tiesapi.com/api/ties/catalog-content/?entry_slug=sop-pdf-apa-workbench-competency` to read its `exemplars_json` & `non_exemplars_json`.
3. Submit step-by-step evaluation:
   ```json
   POST https://tiesapi.com/sop/eval
   {
     "session_id": "newcomer-1",
     "step_index": 0,
     "unblind_nonce": "<step_0_unblind>",
     "prev_nonce": "<head_anchor_nonce>",
     "sop_slug": "sop-pdf-apa-workbench-competency",
     "tie_relation": "validiTIES",
     "olog_stratum": "U_SEM",
     "check_mode": "exemplar",
     "candidate_label": "Validated Elo_2008 headings with \\n\\n sentences and \\n\\n\\n paragraphs"
   }
   ```
   Sending `check_mode: "non_exemplar"` or submitting a known non-exemplar pattern intentionally fails evaluation (`HTTP 422 CATALOG_NON_EXEMPLAR_REJECTED` / `OLOG_STRATUM_MISMATCH`) with the catalog reference explanation.