apple_kit

Apple-native services for Radroots iOS and macOS apps
git clone https://radroots.dev/git/apple_kit.git
Log | Files | Refs | README | LICENSE

AGENTS.md (6806B)

      1 # AGENTS.md — Radroots Apple Kit
      2 
      3 These instructions apply to the complete standalone `radrootslabs/apple_kit`
      4 repository. A more specific `AGENTS.md` may refine them for its subtree.
      5 
      6 ## Repository role and authority
      7 
      8 This repository owns the public Swift package that adapts Apple platform
      9 services for Radroots applications. `RadrootsKit` owns the protocol-first and
     10 live Apple adapters; `RadrootsKitTesting` owns reusable public test doubles and
     11 launch configuration. Application presentation and product policy remain in
     12 host apps, while domain, wire, signing, storage-engine, and relay policy remain
     13 with their public producer packages.
     14 
     15 `Package.swift`, `Package.resolved`, and
     16 `Sources/RadrootsKit/PrivacyInfo.xcprivacy` are machine-readable package and
     17 privacy authority. Swift source and tests are implementation evidence, and the
     18 root `README` is concise public routing material. Keep the package at its
     19 declared Swift tools version and supported iOS/macOS floors unless an approved
     20 breaking change updates source, tests, public routing material, and consumers
     21 together.
     22 
     23 The `swift-secp256k1` dependency must use its canonical public Git source and
     24 one exact immutable revision in both `Package.swift` and `Package.resolved`.
     25 Never replace it with a path dependency, floating branch or tag, private
     26 mirror, implicit sibling checkout, or unrecorded binary artifact.
     27 
     28 Human specifications, decisions, runbooks, migration history, qualification
     29 records, and execution evidence are parent-owned and absent from standalone
     30 clones. They are not package, build, test, or release inputs. Physical or
     31 tracked `docs/**`, `.github/**`, and `.act/**` roots are forbidden, including
     32 symlinks. Public commands must remain forge agnostic and independent of an
     33 enclosing monorepo.
     34 
     35 ## Apple platform and security boundaries
     36 
     37 - Keep secret material in the Security/Keychain boundary with explicit access
     38   policy. Do not downgrade device-local, accessibility, or user-presence
     39   requirements, or silently migrate secrets into `UserDefaults`, files,
     40   telemetry, fixtures, or application models.
     41 - Identity metadata storage is metadata-only, namespaced, bounded, and
     42   synchronized. It must not become private-key custody or canonical domain
     43   storage.
     44 - Local Authentication prompts require an explicit, human-readable reason.
     45   Callback bridges must complete exactly once and remain bounded, cancelable,
     46   race-safe, and correctly classified for user cancellation, permission
     47   denial, temporary failure, and unavailability.
     48 - Permission, location, media, document, background task, background transfer,
     49   notification, and external-action adapters must be explicit host requests.
     50   Do not add hidden polling, unbounded work, ambient authority, or automatic
     51   external mutation.
     52 - Telemetry must apply the canonical redaction policy before rendering, bound
     53   identifiers and payload length, and never expose keys, credentials, tokens,
     54   sensitive locations or media, private event contents, or raw platform error
     55   internals.
     56 - Keep the privacy manifest synchronized with every required-reason API and
     57   collected-data behavior. A framework link or new platform API is incomplete
     58   until privacy impact and tests are reviewed.
     59 
     60 ## API, concurrency, and testing rules
     61 
     62 - Prefer protocol-first interfaces and injected adapters so live platform
     63   behavior has deterministic test substitutes. `RadrootsKitTesting` must not
     64   contain production credentials, hidden global state, or behavior that
     65   weakens production invariants.
     66 - Preserve Swift 6 concurrency correctness. Public values crossing concurrency
     67   boundaries must be genuinely `Sendable`; every `@unchecked Sendable` use
     68   requires a narrow, documented synchronization invariant and race-oriented
     69   tests.
     70 - Keep callbacks single-resolution, release locks before invoking foreign or
     71   async code, and bound data sizes, timeouts, and resource lifetime. Avoid
     72   detached tasks and process-global ownership unless a public contract assigns
     73   them explicitly.
     74 - Public errors must be typed, stable, actionable, and secret-safe. Avoid force
     75   unwraps, `fatalError`, unchecked casts, and production assertions for
     76   recoverable input or platform failures.
     77 - A public API or behavior change requires implementation tests and consuming
     78   host review in the same ordered sequence. Do not add compatibility aliases,
     79   dual paths, or silent fallbacks for prototype behavior removed by the active
     80   clean-slate services-hardening refactor.
     81 
     82 ## Change and verification rules
     83 
     84 Inspect status, package manifests and locks, privacy declarations, affected
     85 protocols/adapters, all relevant tests, and public routing text before editing.
     86 Make one coherent, reviewable target-state change at a time and preserve
     87 unrelated work.
     88 
     89 The standalone package lanes are `tools/verify-boundaries.sh`,
     90 `tools/verify-supply-chain.sh`, `swift build`, and `swift test`; run the
     91 smallest relevant selection while iterating and the complete suite before a
     92 checkpoint. The boundary gate freezes the normalized public symbol inventory
     93 and rejects forbidden repository roots or credential material. The
     94 supply-chain gate proves the exact single remote dependency revision and
     95 repository license authority. Verify `Package.swift` and `Package.resolved`
     96 still agree, inspect privacy-manifest changes, prove no forbidden root exists,
     97 run `git diff --check`, and review final status and diff.
     98 
     99 In an extbuild-enabled checkout, run `cargo extbuild doctor` before the first
    100 mutating build, test, dependency, package, install, or generated-artifact
    101 command and route those commands through `cargo extbuild run -- ...`. Any
    102 future Xcode command must pass the explicit extbuild-owned derived-data,
    103 source-package, and package-cache paths required by the active configuration;
    104 extbuild does not rewrite child arguments. An ordinary standalone clone must
    105 not require parent-only tools or configuration.
    106 
    107 Never claim a lane passed unless it ran successfully. Report unavailable SDK,
    108 platform, signing, network, or dependency prerequisites exactly; do not treat
    109 parent-only workflow proof as a substitute for standalone package validation.
    110 
    111 ## Git and external gates
    112 
    113 Use focused commits in the established `<scope>: <imperative summary>` style.
    114 Do not reset, discard, rewrite, push, tag, sign, publish, deploy, change package
    115 ownership, change signing identities or entitlements, or rotate credentials
    116 without the corresponding explicit authority.
    117 
    118 The change is complete only when it is implemented at the correct Apple or
    119 protocol boundary, relevant standalone validation is green, dependency and
    120 privacy evidence is current, forbidden roots remain absent, and final review
    121 finds no secret exposure, concurrency regression, hidden platform authority,
    122 private dependency, or unreported skipped lane.