Home /Modules/philosophy/help_desk.h

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