Implement @cellix/service-queue-storage for type-safe queue messaging, validation, logging, and OCOM integration

[nnoce14]

Overview

Create a new Cellix framework infrastructure service package, @cellix/service-queue-storage, for reusable Azure Queue Storage access in Cellix applications.

This effort is a follow-on to the blob storage framework work in PR #254 (#254) and should reuse the same general architectural approach, especially where blob storage support is needed for the queue logging mechanism.

A legacy reference implementation was intended to be provided here but the link is currently missing. When available, please add the reference so the implementation can closely mirror its intended behavior while being refined to Cellix standards (design, code quality, and maintainability).

Goals

• Provide generally reusable queue storage operations for backend application code, specifically:
  • sending messages to a named queue
  • reading or inspecting queue contents when needed for operational visibility
• This service is for backend usage only—do NOT confuse with Azure Functions queue triggers (that will be a separate integration effort).

Requirements

1. Framework package

• New package: @cellix/service-queue-storage
• Exposes core queue storage capabilities for Cellix applications.

2. Consumer abstraction

• Like the blob storage service, provide an abstraction layer so downstream application packages (such as OCOM) can downscope the framework service to only the subset they need.
• Enables a downstream package: @ocom/service-queue-storage

3. OCOM integration

• Expose on ApiContextSpec in @ocom/context-spec
• Register the service in @apps/api/
• Add application-specific config under @apps/api/src/service-config/queue-storage

4. Type-safe message validation

• Queue messages must be validated with a JSON schema at the service layer before sending.
• Message contracts should be type-safe and generally applicable across queue use cases.

5. Logging support

• Integrate blob-backed logging of queue message payloads with configurable metadata/tagging, as in the blob storage service.

6. Poison queue support

• Automatic poison queue provisioning when retry attempts exceed a configurable threshold, to handle bad messages gracefully.

7. Environment-aware behavior

• Works identically from app code in both local (Azurite) and deployed/prod (Azure Storage Account) environments.
• For authentication, support managed identity by default—connection strings only for local/Azurite use.

8. Local queue provisioning

• In local development (Azurite only), service startup should auto-create any necessary queues.
• Do not auto-provision queues in production.

9. Implementation Reference

See blob storage service from PR #254 and (pending) legacy reference implementation for design patterns.

---

Out of Scope

• Azure Functions queue triggers – register/message-driven function execution will be handled separately in the Azure Functions integration module for Cellix.

Acceptance Criteria

• @cellix/service-queue-storage provides type-safe queue management
• Type-safe JSON schema validation for outgoing messages
• Managed identity auth preferred, avoid connection string except for local development
• Poison queue provisioning after a configurable failure threshold
• Configurable blob-backed logging for queue message payloads with meta/tag support
• Supports Azurite in local/dev; uses actual storage accounts in production/deployment
• Local startup auto-creates queues needed by the app (Azurite only)
• Extensible abstraction for use by consumer app packages (e.g., @ocom/service-queue-storage)
• Sample OCOM usage: available via @ocom/context-spec, registered in @apps/api/, and configured in @apps/api/src/service-config/queue-storage