help_desk.h
philosophy/module/helper/help_desk.h · 139 line(s) · c
#ifndef SLEELA_PHILOSOPHY_HELP_DESK_H
#define SLEELA_PHILOSOPHY_HELP_DESK_H
/*
* Help / reach-out desk.
*
* A directory of contacts a user can reach out to -- Management and co-series
* authors, telegenically-aware authors, mayors, city spokespersons -- each
* with an email, phone, and a remote IP + port. A user submits a Question or
* Query; the desk lists the matching respondents and reports, per respondent,
* whether they are alive and whether they are known of Science.
*
* DATA BOUNDARY: this library ships NO real personal contact data. The bundled
* directory is synthetic placeholder data using reserved, non-routable ranges:
* - emails at example.com / example.org (RFC 2606),
* - phone numbers in the 555-01xx fictitious block,
* - IPs in 192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24 (RFC 5737).
* Load real, AUTHORIZED contact data later via sl_help_desk_add_contact or a
* caller-supplied loader. The library performs no network I/O: it does not
* email, call, or connect to any IP; it only stores and lists records.
*
* Sizing: built to hold ~500 contacts for a company of ~1000. Capacity and the
* synthetic generator size are parameters. Query matching is linear (O(n)) in
* the number of contacts, so cost scales linearly with directory size.
*/
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
#define SL_HELP_NAME_CAP 96u
#define SL_HELP_EMAIL_CAP 128u
#define SL_HELP_PHONE_CAP 32u
#define SL_HELP_IP_CAP 46u /* fits IPv4 and IPv6 text forms */
#define SL_HELP_ORG_CAP 96u
#define SL_HELP_TAGS_CAP 256u /* space-separated topic tags */
#define SL_HELP_DEFAULT_CAPACITY 512u /* >= 500 contacts */
#define SL_HELP_DEFAULT_COMPANY_SIZE 1000u
typedef enum sl_help_status {
SL_HELP_OK = 0,
SL_HELP_INVALID_ARGUMENT,
SL_HELP_FULL,
SL_HELP_DUPLICATE_ID,
SL_HELP_NOT_FOUND
} sl_help_status;
/* Roles the user can reach out to. */
typedef enum sl_help_role {
SL_ROLE_MANAGEMENT = 0,
SL_ROLE_CO_SERIES_AUTHOR,
SL_ROLE_TELEGENIC_AUTHOR, /* telegenically-aware author */
SL_ROLE_MAYOR,
SL_ROLE_CITY_SPOKESPERSON,
SL_ROLE_COUNT
} sl_help_role;
/* How a respondent may be reached (bitmask). */
typedef enum sl_help_channel {
SL_CHANNEL_EMAIL = 1u << 0,
SL_CHANNEL_PHONE = 1u << 1,
SL_CHANNEL_REMOTE = 1u << 2 /* remote IP + port */
} sl_help_channel;
typedef struct sl_contact {
uint64_t id;
char name[SL_HELP_NAME_CAP];
char organization[SL_HELP_ORG_CAP];
char email[SL_HELP_EMAIL_CAP];
char phone[SL_HELP_PHONE_CAP];
char remote_ip[SL_HELP_IP_CAP];
uint16_t remote_port;
char topic_tags[SL_HELP_TAGS_CAP]; /* lowercase, space-separated */
sl_help_role role;
uint32_t channels; /* OR of sl_help_channel */
bool alive; /* respondent is alive */
bool known_of_science; /* respondent is known of Science */
} sl_contact;
typedef struct sl_help_desk sl_help_desk;
/* One row of a query response. */
typedef struct sl_respondent {
const sl_contact *contact;
unsigned match_score; /* number of query terms matched */
} sl_respondent;
/* ---- Lifecycle --------------------------------------------------------- */
sl_help_desk *sl_help_desk_create(size_t capacity, size_t company_size);
void sl_help_desk_destroy(sl_help_desk *desk);
size_t sl_help_desk_count(const sl_help_desk *desk);
size_t sl_help_desk_capacity(const sl_help_desk *desk);
size_t sl_help_desk_company_size(const sl_help_desk *desk);
/* ---- Directory population --------------------------------------------- *
* Add a fully-specified contact (this is the seam for loading real,
* authorized data later). Validates the record and rejects duplicate ids. */
sl_help_status sl_help_desk_add_contact(sl_help_desk *desk, const sl_contact *c);
/* Helper to initialize a contact struct with validated, bounded fields. */
sl_help_status sl_contact_init(
sl_contact *out, uint64_t id, sl_help_role role, const char *name,
const char *organization, const char *email, const char *phone,
const char *remote_ip, uint16_t remote_port, const char *topic_tags,
bool alive, bool known_of_science);
/* Fill the desk with synthetic placeholder contacts (RFC-safe example data)
* up to `count` (clamped to remaining capacity). Deterministic from `seed`.
* Returns how many were added. For real use, replace with loaded data. */
size_t sl_help_desk_seed_placeholders(sl_help_desk *desk, size_t count, uint64_t seed);
/* ---- Query ------------------------------------------------------------- *
* Match a user Question/Query against contacts (name, organization, role and
* topic tags, case-insensitive term matching). Writes up to max_out ranked
* respondents (highest match first) and returns the number written; the total
* number of matches is reported via *total if non-NULL. Linear scan O(n). */
size_t sl_help_desk_query(
const sl_help_desk *desk, const char *question,
sl_respondent *out, size_t max_out, size_t *total);
/* Optional role filter for a query (SL_ROLE_COUNT means "any role"). */
size_t sl_help_desk_query_role(
const sl_help_desk *desk, const char *question, sl_help_role role,
sl_respondent *out, size_t max_out, size_t *total);
/* ---- Stringization ----------------------------------------------------- */
const char *sl_help_role_string(sl_help_role);
const char *sl_help_status_string(sl_help_status);
/* "alive" / "deceased" and "known of Science" / "not known of Science". */
const char *sl_help_alive_string(bool alive);
const char *sl_help_science_string(bool known_of_science);
#ifdef __cplusplus
}
#endif
#endif