ASO Documentation

Appearance

Register

User Upgrade and Operations Guide ​

Last Updated: 2026-03-01
Audience: Product owner, operators, backend/frontend engineers
Purpose: Practical handover for the completed system-upgrade program: what changed, what to configure, how to validate, and how to operate in a stable standard way.

1) What changed in this upgrade ​

This release focused on stability, determinism, and reducing architectural drift.

A. Guardrails now have one owner ​

  • Canonical owner is orchestration (aso.service.ts).
  • Runtime-level fallback ownership was removed from langchainToolTurn.service.ts.
  • GUARDRAIL_OWNER_MODE remains for compatibility, but effective behavior is orchestration-only.
  • Logs now include guardrail_owner, guardrail_source, and guardrail_reason.

Why this matters:

  • Prevents duplicate guardrail execution in one turn.
  • Makes debugging and trace review deterministic.

B. Durable queue path is enforced for background jobs ​

  • Background processing is standardized on BullMQ + Redis when BG_QUEUE_DRIVER=bullmq.
  • Startup now fails fast if durable queue initialization is required but unavailable.
  • File-based background jobs were upgraded to durable payloads (serialized), with strict size checks via BG_FILE_JOB_MAX_BYTES.
  • Unsupported or non-durable file payload paths now fail fast instead of silently falling back.

Why this matters:

  • Prevents data loss and hidden queue behavior.
  • Makes queue reliability explicit and operationally observable.

C. Retriever correctness and scoring improvements ​

  • Keyword retrieval paths no longer incorrectly require embeddings.
  • Keyword-only rows are scored correctly and bounded.
  • Hybrid retrieval behavior is now consistent for vector and keyword branches.

Why this matters:

  • Better recall for historical content without embeddings.
  • More reliable ranking and fewer relevance regressions.

D. Contracts, schema, and prompt/runtime hardening ​

  • Tool input/output validation now runs through canonical schemas (toolSchemas.ts) in the executor path.
  • search_my_memories is included in canonical tool compilation/meta.
  • Prompt budget enforcement is centralized in langchainToolTurn.service.ts:
    • PROMPT_HARD_TOKEN_BUDGET
    • PROMPT_RESERVED_OUTPUT_TOKENS

Why this matters:

  • Fewer runtime drift bugs across tool callers.
  • Better control over token growth and latency.

E. Invariant and regression scaffolding ​

  • Added/updated focused invariants and regressions around guardrails, retriever behavior, tool contracts, and protocol flow consistency.
  • Test fixes made reruns idempotent for protocol-flow integration coverage.

Why this matters:

  • Reduces chance of silent regressions while features evolve.

F. Program closure status ​

  • Architecture upgrade phases are complete (Phase 0 through Phase 4).
  • Closure status is formally CLOSED in SYSTEM-CLOSURE-DONE-DEFINITION.md.
  • Ongoing work is maintenance-mode hardening, not structural migration catch-up.

G. Identity Stabilization Closure (new baseline layer) ​

  • Identity Pack v1 is now wired as a first-class runtime contract in prompt building.
  • Protocol scope now controls identity anchor behavior explicitly:
    • identity:chinatsu_anchor_off for public/tech/neutral
    • identity:chinatsu_anchor_on for private/system
  • Prompt wording and runtime tool list alignment were hardened for web tools.
  • Identity pass/fail regression suite was expanded and is now part of the focused verification path.

Why this matters:

  • Prevents identity drift between protocols.
  • Keeps public-safe behavior while preserving core continuity.
  • Makes prompt behavior easier to audit in LangSmith.

2) What you must configure now ​

Use backend/env.example as source of truth.

Required for durable queue mode:

bash
BG_QUEUE_DRIVER=bullmq
BG_QUEUE_REDIS_URL=redis://127.0.0.1:6379 or REDIS_URL.
BG_JOB_CONCURRENCY=3
BG_JOB_RETRIES=3
BG_JOB_BACKOFF_MS=1500
BG_FILE_JOB_MAX_BYTES=8388608

Recommended stability flags:

bash
GUARDRAIL_OWNER_MODE=orchestration_only
PROMPT_HARD_TOKEN_BUDGET=12000
PROMPT_RESERVED_OUTPUT_TOKENS=3000
TOOL_RESPONSE_CONTRACT_STRICT=true

Notes:

  • GUARDRAIL_OWNER_MODE is compatibility-facing; behavior is still orchestration-only.
  • If BG_QUEUE_DRIVER=bullmq and Redis is unavailable, startup should fail by design.

3) Runbook: start, validate, and monitor ​

Startup checklist ​

  1. Ensure Redis is running and reachable from backend.
  2. Confirm .env values match current env.validation.ts.
  3. Run DB migrations (including identity/protocol scope migration).
  4. Start backend and verify queue-health logs at startup.

Commands:

bash
cd backend
npm run migrate
npm run dev

Use focused suites instead of full-suite runs when legacy tests are known unstable:

bash
npm run test:invariants
npm run test:langchain:regressions
npm run test -- tests/integration/time-tools.jest.test.ts tests/integration/tools-remaining.jest.test.ts tests/integration/protocol-flows.jest.test.ts
npm run env:check-drift

Runtime checks in logs ​

Look for:

  • Guardrail metadata (guardrail_owner, guardrail_source, guardrail_reason)
  • Queue startup/health success
  • Tool execution start/done without contract warnings in strict mode
  • No silent fallback messages for durable-only file job paths
  • Use GET /api/admin/observability for an aggregated snapshot (queue/tool-denials/latency/embeddings).

4) What users/operators need to understand ​

Behavior changes users may notice ​

  • Some unsupported file workflows now fail fast with explicit error messages instead of delayed/silent fallback behavior.
  • Guardrail decisions should appear more consistent across similar prompts.
  • Prompt truncation may occur earlier under budget constraints to preserve output headroom.
  • Protocol-specific identity expression is now more deterministic:
    • public/tech/neutral avoid unnecessary relationship anchor mentions
    • private/system can reference relationship anchors naturally when contextually relevant

Behavior changes engineers should expect ​

  • Queue availability is now a startup dependency in durable mode.
  • Tool contract mismatches are surfaced earlier.
  • Deterministic ownership boundaries are favored over dual-path compatibility.
  • Prompt identity/module toggles now emit debug telemetry for easier routing/prompt diagnosis.

5) Standard process from now on ​

Use this as the default implementation policy for future upgrades.

  1. One owner per behavior
    No duplicate control logic across orchestration/runtime layers.

  2. One canonical contract
    Tool schemas and policy checks live in one place and are reused.

  3. Fail fast over silent fallback
    Especially for queueing, file payloads, and contract violations.

  4. Small phased PRs with invariants
    Each PR must include focused tests proving non-regression.

  5. Docs updated in same PR
    Update roadmap/ADR/runbook when behavior or ownership changes.

  6. Targeted regression sets for safety
    Maintain a stable, curated “critical path” test set for day-to-day validation.

6) What to keep doing next (maintenance roadmap) ​

Short-term maintenance actions:

  • Keep expanding invariant coverage around critical paths:
    • queue durability and failure modes
    • tool contract strictness
    • prompt budget clipping behavior
  • Continue reducing legacy-path drift in planned cleanup batches.
  • Keep GET /api/admin/observability and OBSERVABILITY-RUNBOOK.md aligned with runtime behavior.

Medium-term maintenance:

  • Tighten deploy gates to require focused regression + invariants on every high-risk PR.
  • Keep env.example, validation schema, and setup docs in lockstep.

Long-term:

  • Preserve deterministic boundaries as the top design rule:
    • one owner
    • one contract
    • one failure policy

7) Quick troubleshooting ​

Backend fails at startup in durable mode ​

  • Check BG_QUEUE_DRIVER and BG_QUEUE_REDIS_URL.
  • Verify Redis is reachable and credentials/network are correct.
  • Confirm queue init logs appear before traffic starts.

File-based tools now error quickly ​

  • This is expected in strict durable-only behavior for unsupported payloads or oversize files.
  • Check BG_FILE_JOB_MAX_BYTES and file serialization path constraints.

Tool outputs rejected ​

  • In strict contract mode, validate handler output against canonical schema in toolSchemas.ts.

Guardrail behavior seems duplicated ​

  • Confirm current branch uses orchestration-only execution and no old runtime fallback code is active.

8) Related docs ​

  • SYSTEM-AUDIT-AND-ROADMAP.md
  • SYSTEM-INVARIANTS-AND-SMOKE-TESTS.md
  • OBSERVABILITY-RUNBOOK.md
  • SYSTEM-CLOSURE-DONE-DEFINITION.md
  • ADRS-ONE-RUNTIME-GUARDRAIL-RETRIEVAL.md
  • LEGACY-TOOL-GATEWAY-DEPRECATION.md
  • IDENTITY-STABILIZATION-CLOSURE.md

ASO Universal Consciousness System Documentation

Copyright © 2025 ASO Universal Consciousness System